File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Beginning Java and the fly likes Java API Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Java API " Watch "Java API " New topic
Author

Java API

Donald R. Cossitt
buckaroo
Ranch Hand

Joined: Jan 31, 2003
Posts: 401
In my quest in trying to understand the Java API, I found this quote on a forum here at JavaRanch:

You do need to learn how to find information from the API

I will admit to being a bit thick headed at times but what I find in the API is a lot of 'data' and very little "information". I find I am a bit like a calf at a new gate (AKA deer in the headlights) when going to the API. Is there a secret to extracting how-to's from this plethora of data? Or is spending hours and days sifting through the API for one line of code normal? :roll:


doco
Joel McNary
Bartender

Joined: Aug 20, 2001
Posts: 1821

I have two valuable resources:
My O'Reilly trilogy of Java Nutshell books (Java, JFC, and Enterprise) and "I'm Feeling Lucky" on Google.
In addition to listing all classes and methods in the API, the O'Reilly books provide examples. Unfortunately, the O'Reilly books do not provide javadocs.
If you thye in the full class name in Google and press "I'm feeling Lucky" it will (usually) take you to the on-line java docs for that class.
I've written quite a bit of code this way. Of course, If I need further help, I ask the other ranchers here.


Piscis Babelis est parvus, flavus, et hiridicus, et est probabiliter insolitissima raritas in toto mundo.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Hey doco,
Adding to what Joel said, the writers of the javadoc comments or API documention state outright that the documents are meant for seasoned developers not beginners looking for coding examples. The books Joel mentioned are a great source of code examples and I would add both volumes of Core Java from Sun Press. But the best place for information is right here! Of course I had to pitch the Ranch just a little.


Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius - and a lot of courage - to move in the opposite direction. - Ernst F. Schumacher
Donald R. Cossitt
buckaroo
Ranch Hand

Joined: Jan 31, 2003
Posts: 401

looking for coding examples

Perhaps my choice of words was a bit mis leading in saying "looking for one line of code".
But I will give a for instance; I am currently stuck in SortNames. I have code to access text file and load the ArrayList and a Collection to sort that array by first names. However, the requirement is to sort finally by last names as well. This is where 'starring down' the API gets a bit disconcerting. I am not even sure how to begin the search for the string parsing tools neccessary to sort. Reading the "Comparable" docs is at the least .
I am not necessarily looking for code blocks, just an explantion of how to find necessary methodology then how to apply it.
Can anyone honestly say they entirely understand what this says?

public interface Comparable
This interface imposes a total ordering on the objects of each class that implements it. This ordering is referred to as the class's natural ordering, and the class's compareTo method is referred to as its natural comparison method.
Lists (and arrays) of objects that implement this interface can be sorted automatically by Collections.sort (and Arrays.sort). Objects that implement this interface can be used as keys in a sorted map or elements in a sorted set, without the need to specify a comparator.
A class's natural ordering is said to be consistent with equals if and only if (e1.compareTo((Object)e2)==0) has the same boolean value as e1.equals((Object)e2) for every e1 and e2 of class C.
It is strongly recommended (though not required) that natural orderings be consistent with equals. This is so because sorted sets (and sorted maps) without explicit comparators behave "strangely" when they are used with elements (or keys) whose natural ordering is inconsistent with equals. In particular, such a sorted set (or sorted map) violates the general contract for set (or map), which is defined in terms of the equals operation.
For example, if one adds two keys a and b such that (a.equals((Object)b) && a.compareTo((Object)b) != 0) to a sorted set that does not use an explicit comparator, the second add operation returns false (and the size of the sorted set does not increase) because a and b are equivalent from the sorted set's perspective.
Virtually all Java core classes that implement comparable have natural orderings that are consistent with equals. One exception is java.math.BigDecimal, whose natural ordering equates BigDecimals with equal values and different precisions (such as 4.0 and 4.00).
For the mathematically inclined, the relation that defines the natural ordering on a given class C is:
{(x, y) such that x.compareTo((Object)y) <= 0}.
The quotient for this total order is:
{(x, y) such that x.compareTo((Object)y) == 0}.
It follows immediately from the contract for compareTo that the quotient is an equivalence relation on C, and that the natural ordering is a total order on C. When we say that a class's natural ordering is consistent with equals, we mean that the quotient for the natural ordering is the equivalence relation defined by the class's equals(Object) method:
{(x, y) such that x.equals((Object)y)}.

Sorry for the length.
[ May 02, 2003: Message edited by: Donald R. Cossitt ]
Joel McNary
Bartender

Joined: Aug 20, 2001
Posts: 1821

I can honestly say that I understand it, but I can easily see how it is mightly confusing to someone else. My understanding comes from the fact that I understand C's strcmp function, and this just expands on that feature (making it OO and allowing you to define the mechanism behind how items are compared).
I guess that the best thing to do for understanding how to tackle the API is to sit down and get a little bit of knowledge of the major components of the API. For example, when I first looked at sorting things, I already knew that the java.util.Arrays class had a sort method. Looking up the documentation there pointed me to the Comparable and the Comperator classes. I then read those classes and chose the one that was right for me.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Can anyone honestly say they entirely understand what this says?
Maybe I been doin' this stuff too long, but yep.
Here is a generic sort of way to sort on two criteria. This technique can be expanded to sort on any number of fields:
Donald R. Cossitt
buckaroo
Ranch Hand

Joined: Jan 31, 2003
Posts: 401
Muchas Gracias Joel y Michael; compadres de c�digo.
Now I need to study just what is taking place in the snippet, which is a good thing. This would require someClass Implements Comparable. Way
Thanks
Layne Lund
Ranch Hand

Joined: Dec 06, 2001
Posts: 3061
For me, the API docs are most useful in finding a particular class and/or method that can perform the task I need. I rarely even read the description of the classes. I usually know which class I am looking for, or at least where to start. Then I browse through the methods of the class to find one that will do what I need. If there are other supporting classes, I look at their methods in turn.
Most of my knowledge about each class' usage comes from reading the Core Java books. I highly recommend these to help you learn the concepts of programming Java.
Also, many concepts are independent of the actual language. Sorting, in fact, is very common in any computer language. I find that a firm background in such concepts helps when I need to implement them in a specific language. Sometimes separating these concepts from a certain language is difficult, but when you learn this abstraction, you won't have to rely on Java-specific technology to use them.
HTH
Layne


Java API Documentation
The Java Tutorial
Donald R. Cossitt
buckaroo
Ranch Hand

Joined: Jan 31, 2003
Posts: 401
Ok, two hits in the same post to buy Core Java is good enough for me; I ordered the book. Besides, I'll do just about anything that helps to weed through the API.
Thanks all.
Carl Trusiak
Sheriff

Joined: Jun 13, 2000
Posts: 3340
Sometimes the APIs just aren't enough. Don't be afraid to look for other sources such as Sun'd Tech Tips. There is one on Collections which includes a discussion of Comparable http://developer.java.sun.com/developer/technicalArticles/Collections/Using/ Then there is the Sun Tutorials which, has one on collections http://java.sun.com/docs/books/tutorial/collections/index.html AND of course, there is the good ole' JavaRanch NewsLetter one of which is an article by Thomas Paul on Collections which includes sorting http://www.javaranch.com/newsletter/July2002/newsletterjuly2002.jsp#collections


I Hope This Helps
Carl Trusiak, SCJP2, SCWCD
Kathy Sierra
Cowgirl and Author
Ranch Hand

Joined: Oct 10, 2002
Posts: 1572
Howdy
I could not live without the Java Almanac. I like it much better than Java in a Nutshell. You still have to go to the API when you need the detail about what a method does, or something about how it works, but *most* of the time, just knowing what methods are available and what their signatures are is enough. Plus the almanac has other goodies ("examplets") that are VERY helpful.
Combine that with The Java Cookbook and you're flying. They won't teach you Java from the ground up, but once you get started, they're great resources.
But my FAVORITE thing is the Java class libraries poster. It is the fastest way to find out what classes are in what packages, and get a visual picture of the whole API.
Plus, it looks cool in your cube
get the poster from Amazon
Have fun,
Kathy
O'Reilly page on the new Head First learning series
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Java API