Java client library

The Java library encapsulates each accessing method provided by the webservice (see methods) with a corresponding class. The client library can be downloaded from here. We also provide its JavaDoc.

The client library consists of multiple jars which must be added to your Java project's classpath. Those jars are:

  • BibSonomy webservice: The webservice client itself consists of five jars:
    • bibsonomy-rest-client.jar (client library classes)
    • bibsonomy-rest-common.jar (REST API core classes)
    • bibsonomy-bibtex-parser.jar (BibTeX parsing module)
    • bibsonomy-model.jar (bibsonomy data model classes)
    • bibsonomy-common.jar (shared library of bibsonomy).
  • Apache HTTP-Client: The HTTP client libraries by the apache software foundation are used for the HTTP communication, log4j is used for logging:
    • commons-httpclient-3.0.jar which uses
    • commons-codec-1.2.jar and
    • commons-logging-1.1.jar
    • log4j-1.2.14.jar.
  • Java Architecture for XML Binding (JAXB): The client uses JAXB to (de)serialize the XML exchange documents:
    • jaxb-api-2.0.jar
    • jsr173_api-1.0.jar
    • activation-1.1.jar

Using the client library

Using the client library is rather simple. At first one has to instantiate an object of type Bibsonomy and set the user's credentials on it. This object can be reused during program run. As already discussed, there exist classes encapsulating each provided webservice method. These classes are derived from AbstractQuery and request in their constructor parameters (usually model data objects, see the package org.bibsonomy.model) - please refer to the JavaDoc of the corresponding constructor.

After instantiating an appropriate AbstractQuery just execute it by invoking the executeQuery method of the Bibsonomy object with the query object as parameter. If your query object fetches a list of objects, for example a list of posts, you can also use the overloaded executeQuery method and register a callback object (use the ProgressCallback interface). The return values of your query are available via the getResult and getHttpStatusCode methods of the AbstractQuery.

Here is a simple example class that demonstrates how to use the client library (see the JavaDoc for further reference):

import java.util.List;
import org.bibsonomy.model.BibTex;
import org.bibsonomy.model.Post;
import org.bibsonomy.rest.client.Bibsonomy;
import org.bibsonomy.rest.client.exception.ErrorPerformingRequestException;
import org.bibsonomy.rest.client.queries.get.GetPostsQuery;

public class apitest {

        public static void main(String[] args) {
                
                // BasicConfigurator.configure();
                
                // create webservice client object with credentials, set API URL
                Bibsonomy bib = new Bibsonomy("username", "api-key");
                bib.setApiURL("http://www.bibsonomy.org/api");

                // instantiate query object
                GetPostsQuery gpq = new GetPostsQuery();

                // some queries can be parametrized
                // -> in this example we want to fetch only bibtex entries
                gpq.setResourceType(BibTex.class);

                try {
                        // perform query
                        bib.executeQuery(gpq);

                        // on success, read results
                        if (gpq.getHttpStatusCode() == 200) {
                                List<Post<?>> posts = gpq.getResult();

                                for (Post post : posts) {
                                        /*
                                         * now do something with your posts :)
                                         * e.g. print the bibtex keys
                                         */                                     
                                        BibTex bibEntry = (BibTex) post.getResource();
                                        System.out.println(bibEntry.getBibtexKey());
                                }
                        }
                } catch (ErrorPerformingRequestException e) {
                        /*
                         * happens on network failure for example
                         */
                }
        }
}

A whole example application for managing bookmarks and publications, demonstrating the webservice client library, is available for download.

Class diagram

Here you can find a diagram that shows the classes of the BibSonomy data model and the connections between them.

Class diagram