Add toString methods to API interface implementations

[dbwiddis]

I'm marking this issue for first-timers-only. That means that I will only accept a PR for this one from someone who's never contributed to open source before. This one is easy (but don't make that statement make you feel bad if you have a hard time with it, there's more to contributing to open source than changing lines of code, especially if it's your first time). I'll hold your hand through this if you need me to. :-)

We'd like to add toString() methods to all of the API classes, with the implementation in the associated Abstract class for interfaces. This has been done for AbstractOperatingSystem, AbstractDisplay, AbstractOSVersionInfoEx, AbstractSoundCard, AbstractUsbDevice, AbstractCentralProcessor, and the class OSProcess

Similar implementations should be made for:

• ComputerSystem
• Baseboard
• Firmware
• GlobalMemory
• VirtualMemory
• HWDiskStore
• HWPartition
• NetworkIF
• PowerSource
• Sensors
• OSFileStore
• NetworkParams

Feel free to do one, or multiple implementations! Comment below which one(s) you are doing to avoid stepping on someone else's toes.

Here are the steps to get a PR merged here.

• Read the CONTRIBUTING file for reference. I'll walk you through anything you don't understand.
• Fork the project to your own GitHub account, make a local clone, and create a branch for your submission.
• Look at how this class's information is displayed in the SystemInfoTest class. This is a suggested starting point for the toString() implementation.
• For interfaces, create a toString() method in the Abstract class implementing the interface. See the above links for examples.
• For classes, create the toString() method in the class.
• Alter the code in the SystemInfoTest class to call the toString() method you just created.
• Commit your changes, push to to your GitHub fork, and create a Pull Request
• Respond to the usually minor comments on code review
• Celebrate! 🎉

[phillips0616]

I will work on the implementations for ComputerSystem and Baseboard.

[rohitkukreja1508]

I will work on FirmWare,GlobalMemory and VirtualMemory implementations

[agithyogendra]

I will work on HWDiskStore and HWPartition

[colinbobolin]

Hello, @dbwiddis I'd like to contribute and work on the PowerSource implementation. Thanks for marking this as first-timers-only!

[dbwiddis]

My pleasure, @colinbobolin. After all, contributing here was my first commit and now look at me. :)

This is actually a perfect Issue for that. Lots of small, accessible tasks that I don't have to do, and we all help each other!

[dbwiddis]

General feedback since I've made the same comments on every PR so far...

Please keep the toString() to without any leading or trailing whitespace/newlines. Newlines in the middle of the string are ok in limited cases.

In contrast, please keep "formatting logic" in the SystemInfoTest class. By this I mean indentation, newlines for iterations, etc.

[BilalAM]

Hey @dbwiddis , might I recommend that instead of manually creating toString() strings , why don't we just use the Apache commons toStringBuilder class ? It is designed specifically for this purpose . It will be consistent throughout .

http://commons.apache.org/proper/commons-lang/javadocs/api-3.9/org/apache/commons/lang3/builder/ToStringBuilder.html

Just a simple return toStringBuilder(this).append(field1).append(field2) and etc will return a nicely formatted toString()

[dbwiddis]

Thanks for the recommendation @BilalAM . I do understand the value of consistent toStrings and the code you've linked to seems like a good "default" given no overrides.

I'll note, however, that this "manually creating output" has always been there in the SystemInfoTest class as a "quick summary of values" and we're mostly just refactoring it in this case. Standard toStrings that just replicate the exact values from the getters aren't as useful, in my opinion.

The javadoc for toString says it's:

a concise but informative representation that is easy for a person to read.

I think between the two options below, the second one is more concise and easier to read:

• availableMemory=15032385536, totalMemory=34359738368
• Available: 14 GiB/32 GiB

OSHI's focus is on providing the specific values (including values in the millions and billions, or double-precision floating points) like the full memory values above, and allowing the user to format appropriately for their needs. The toStrings are mostly just for a nice visual output, rounding, trimming and formating with metric/binary, etc.. and are mostly a "nice to have" that may not need a standard format.

"Device Tree" based structures like USB devices connected by hubs, or hard drive/partition arrangements, simply don't display well on a default/standard toString.

Finally, I'm always hesitant to add dependencies, and really don't think we need one just for toStrings.

[TurkishDelightt]

I see multiple people have already commented before me, but are there any implementations yet to be done? I would love to have a go. Thanks!

[SandipanMajhi]

I want to work on Sensors. I have never done these things before. It's a first for me and I might really need a helping hand.

[johnaearley]

@dbwiddis Hello, I would like to work on NetworkIF and NetworkParams if still available.

[dbwiddis]

Looks like @johnaearley has clamed the two remaining Network tasks and @BooSandy1994 has Sensors. @GandalfTheJava can you please take the OSFileStore? Look at HWDiskStore as a sample!

[TurkishDelightt]

@dbwiddis I will get started on OSFileStore immediately! Thank you

[SandipanMajhi]

Hi @dbwiddis , now it is showing that you shared the repo with me. I surfed around and found the Sensor.java file in the repo. Is that the file I have to make changes to? I mean what's the process?

I found that this Sensor.java is an interface.

I kind of realise that I have to fork the project and make necessary changes.

[dbwiddis]

Hi, @BooSandy1994. Here's a step by step.

1. On the top right of this page is a "Fork" button. Click it. This will give you a copy of OSHI on your own github account.
2. Make a local clone of your own repository. Not sure what OS you have, but you will need to install git there, and then use the command git clone https:/BooSandy1994/oshi.git
3. Create a branch to do your work on. git checkout -b sensors-tostring
4. Start coding! Since Sensors is an interface, you need to put the toString method in the implementation. To avoid repeating it in every OS's Sensors class you want to put it in the AbstractSensors class. So put a toString() method right here. You'll add the /** {@inheritDoc} */ javadoc, and an @Override annotation, then the method. See the completed PRs above in this thread for examples.
5. Find the output currently in the SystemInfoTest class. It's at line 248-250. Leave the "Sensors: " portion in this class, and just append sensors.toString() to it.
6. Take the remaining three lines and merge them into a single String in the toString. I'd suggest creating a String Temperature=55°C, Fan Speeds=[1234, 1235], Voltage=3.4V which you can probably do with a single String.format(). If you want to keep the 3 lines separate as they are, just create a StringBuilder and append the existing output (but replace the newline %n with a comma+space.)
7. Commit your changes and push them to your own branch.
8. On your github account, find the branch (which should say it is "ahead of master by 1 commit") and create a pull request.
9. Find the pull request number and edit the changelog to add yourself in the list. Then commit and push again.

[SandipanMajhi]

Omg thank you very much ... I am on it.

[SandipanMajhi]

@dbwiddis I just added the toString method in the Abstract Sensor class. Do I need to delete the remaining 3 lines after tha Oshi.add("Sensors:" + sensors.toString()). I have merged the cpu temp, fan speed and cpu voltage in the toString method only.

[dbwiddis]

Yes, delete those lines.

[SandipanMajhi]

Also when I read the CONTRIBUTING section written at the start of this thread..... it is mentioned something like to run mvn test.
When I run it in git bash it says mvn command not found.
Also how to know if the changes I made are working or not.

[dbwiddis]

You would have to install maven on your machine OR you can use the mvnw maven wrapper batch file or command. See the "Readme" on the project homepage for how to run it!

You can run the SystemInfoTest in your IDE to see if the output looks normal.

[SandipanMajhi]

Finally I was able push the changes with the chnagelogs and the code.

[dbwiddis]

Great job, @BooSandy1994 ! I'll just make a few formatting tweaks and merge it!

[rsersh]

Hi @dbwiddis , I have scanned the thread and I think your topics have all been covered but in case I missed something I would love the opportunity to help. If not, there's always next time. TY for posting.

[dbwiddis]

Hi, @rsersh , you are correct that all the topics have been claimed on this issue, but if you'd like to contribute there are many other things that can be done. Let me know if you'd like to pitch in elsewhere!

[rsersh]

Thank you, @dbwiddis. Yes, I would very much like to provide some assist where needed.

[dbwiddis]

@rsersh Check out #954

[praveenkumarsh]

Hi @dbwiddis it is my first time for looking for open source projects, and I really want to do this.
If there any opensource issues in java related please guide me what and how to do.
So, I will be able to contribute.

[dbwiddis]

Hi, @Praveen101997 ! Glad to know you want to help. I'm not sure there's anything right now that's not being worked on, but if you "watch" the project (click the link near the top of this page) you can see new issues when they pop up.

[praveenkumarsh]

Thanx for your reply
I will make sure to help in the coming time

[shivangi14]

Hi @dbwiddis ! It's my first time for Open Source contribution. I have read the whole thread and got that all the topics here have been claimed. If there are any such more open issues, please guide. Your comments on this issue have motivated me a lot to search for more to start with. Thank you. :)

[dbwiddis]

@johnaearley how's it going on the toStrings for the network info? If you don't have time to do them, there are a few other first-timers who would love to take a shot at it.

[dbwiddis]

@Praveen101997 and @shivangi14 check out #963 if either of you wants to try it.

[fdmcneill2019]

@dbwiddis Are there any tasks/implementations left to do? I would like to try to handle at least one.

[dbwiddis]

The two Network classes haven't been done... @johnaearley signed up for them but hasn't followed up. Can you pick one and if he pops up he can still do the other?

[fdmcneill2019]

@dbwiddis Yes. I'll try to do NetworkIf.

[fdmcneill2019]

Is there a particular way the string should be formatted for the NetworkIF class?

[dbwiddis]

Just grab the same formatting that is in the SystemInfoTest class, except don't indent the first line by a space (but indent the following lines as they are). So like this:

Name: en5 (en5)
   MAC Address: ac:de:48:00:11:22 
   MTU: 1500, Speed: 100 Mbps 
   IPv4: [] 
   IPv6: [fe80:0:0:0:aede:48ff:fe00:1122] 
   Traffic: received 226306 packets/27.5 MiB (0 err); transmitted 224029 packets/75.5 MiB (12010 err)

[shivangi14]

Hi @dbwiddis , is NetworkParams being worked on? I would like to try it.

[dbwiddis]

Go ahead and grab it, @shivangi14.

[shivangi14]

Thanks @dbwiddis . I am on it.

[fdmcneill2019]

I'm pretty much done with the toString method. I'm just having problem testing it with JUnit (first time). I keep getting a NullPointerException for it.

[dbwiddis]

Let me know if I can help debug. :) It's less important to individually test the toStrings as they are all exercised in SystemInfoTest.

[fdmcneill2019]

@dbwiddis I successfully ran tests and it looks like everything is correct. The only question I have now is whether or not I need to add the /** {@inheritdoc} */ javadoc tag as well?

[fdmcneill2019]

@dbwiddis Thanks for the offer but I didn't get to see your reply before it was already too late lol.

[dbwiddis]

No, the inheritdoc is optional, added by a maven tool, and I’m actually removing them as I edit other code.

[fdmcneill2019]

In the SystemInfoTest class, should I remove everything from the printNetworkInterfaces method?

[dbwiddis]

Not everything... you need to call the toString with the header in front of it.

[fdmcneill2019]

This is what I have in the printNetworkInterfaces method:
StringBuilder sb = new StringBuilder(); if (networkIFs.length == 0) { sb.append("Unknown"); } for (NetworkIF net : networkIFs) { sb.append("\n").append(net.toString()); } oshi.add(sb.toString());

[dbwiddis]

That looks good to me visually here... more importantly, do you like the output when you run SystemInfoTest?

[fdmcneill2019]

Yeah. It looks identical to what you showed me earlier.

[dbwiddis]

Closing this issue as there's now a PR for the last submission. For those who want to contribute further, feel free to watch the project and check the Issues list for "Good first issue" tags.