API Docs
In this section you'll look at how the docs present the information you need to use class methods and variables.
In either the big right hand frame, or the frame containing the class list for java.lang, click the 'String' class name.
You should see the big right hand frame change to display information on the String class. We'll go through what's shown in this frame, starting at the top.
The topmost part of the frame is a navigation bar...
This lets you navigate back to the package and API overviews.
Following this we have a brief summary of the class...
This shows us the package it's in (java.lang), the fact that it's a class, and it's called 'String', and its place in the java inheritance structure. You can see that String, like all Java classes, extends the class 'java.lang.Object', which is a simple class with a few methods in it that everything needs (have a look at it if you like by clicking its name, but remember to come back to String).
In addition, there is information on the interfaces String implements - 'CharSequence', 'Comparable' and 'Serializable'. Remember that interfaces define methods that classes must make for themselves. Implimenting 'Comparable' for example, forces String to provide methods for comparing itself with other Strings. The > and < angle brackets around the word 'String' after 'Comparable' were a new Java feature in Java 5. They mean that Comparable can be set up to work with any kind of Object - in this case Strings. We'll give you some information about this later in the course - for now, don't worry about them.
We then get a more detailed description of the class, and usually some information on how it's used.
Often this area contains mini tutorials or examples you can run.
At the end of this information is a 'Since:' date and links to related materials.
The 'Since:' date indicates when the class was introduced. In the case of String, this was in JDK1.0. The 'See Also' information often links related abstract classes, interfaces, or, as in this case, useful classes that work with the class you're looking at.
Following this we have the overviews of the documentation. These are one sentence descriptions of the 'fields' (instance variables, but usually just constants/final static variables), constructors, and methods, with links to more detailed information lower in the page.
These short descriptions tell you what variables the methods expect to get passed, and what they pass out. They also tell you if the constructors or other methods have been 'deprecated'. Deprecated methods are methods that shouldn't be used anymore, but have been kept in the API for backwards compatibility, mainly with programs written with JDK1.0.
So, for example, you can see that there are lots of 'getBytes' methods. Remember that because of Java's polymorphism, the one that's used will depend on what is passed into the method as arguments.
One of the 'getBytes' methods (the one above) takes in two ints, a byte array and then an int, and returns 'void'. The names given to the variables passed in aren't significant and can be changed in your code - they're just there to give some idea of what the variables correspond to (in this case 'src' probably refers to the source, and 'dst' to the destination). You can see that this getBytes method has been deprecated, and there is advice on what to do instead.
Finally at the bottom of the overviews are links to the methods inherited from the relevant superclass, and any superclasses that they in turn inherit.
As java.lang.Object isn't a subclass of anything, there's only one set of information here for String. Clicking on them takes you to the relevant part of the java.lang.Object docs.
Finally, below everything, is the detailed documentation you get to by clicking the links in the overviews.
Nine times out of ten the overviews will give you all the information you need, but sometimes the detailed information and the examples they contain are extremely useful.
Once you're happy you understand what the docs are saying, go on to the final part of this tutorial.