How to use a java class based on its API documentation

Question

I am quite new to Java, and need to work on a project requiring using open source software. I am very confusing about understanding those Java API's documentation. As an example, can you show me how to use the related java class, RemoteXmlSimpleSearchEngineBase, based on its Java API.

Please refer to this link http://download.carrot2.org/stable/javadoc/org/carrot2/source/xml/RemoteXmlSimpleSearchEngineBase.html

I am very interested in this derivation process, so that I can use other java classes based on reading its API documentation. Thanks.

Answer 1

Often the JavaDoc doesn't explain the general concept of a library but just the API for that class. It might contain more useful information (like the JDK JavaDocs do), but in general you should try to get a user manual, reference or getting started guide.

From the JavaDoc you can still learn a few things:

1. what interfaces are implemented
2. which directly known subclasses/implementors exist
3. you see that the class is abstract
4. which methods are added/overridden by that class
5. which methods are added
6. pre-/postconditions of the methods and its parameters (sometimes not listed)
7. ...

However, you often don't get the general concept or when a method is called, how to configure a class for various use cases etc. You simply can't put that all into an API documention.

Answer 2

Maybe you should take a look to the project documentation:

http://project.carrot2.org/documentation.html

You have some examples and lot of information.

Answer 3

What I often find useful when trying to get an overview over some API are the class/interface trees, and even more the "Usage" pages - they show which other classes/interfaces use this class/interface in their API. This shows how to get some type of object (by finding return values), or what to do with some object (except from using its methods itself).

Sadly, the latter ones are not generated by default (and also missing in the example in your question).

Answer 4

Very often, the JavaDoc overview page will have some overview of the API and code examples. This is actually the case with Carrot2 JavaDoc:

http://download.carrot2.org/stable/javadoc/overview-summary.html#overview_description