Clone wiki

BibSonomy / documentation / api / Java API Examples

This page shows some Java examples on how to use the BibSonomy REST-API. You can easily repeat them by adding the JAR of the rest-client module (and its dependencies) to your Java build path. If you are using Maven, you can use our Maven repository where we publish the rest-client with every release. Simply add our repository to your POM:

<repositories>
    <repository>
      <id>bibsonomy-repo</id>
      <name>Releases von BibSonomy-Modulen</name>
      <url>http://dev.bibsonomy.org/maven2/</url>
    </repository>
  [...]
</repositories>

and the following dependency:

<dependencies>
    <dependency>
        <groupId>org.bibsonomy</groupId>
        <artifactId>bibsonomy-rest-client</artifactId>
        <version>3.5.0</version>
    </dependency>
    [...]
</dependencies>

Replace 3.5.0 with the latest version you can find in our repository.

Note for PUMA users: You can use the BibSonomy modules as well, but please set the endpoint url to your PUMA instance.

Initialization

First, you need to get your API key from the settings page of BibSonomy and use it to acquire an instance of the LogicInterface:

final RestLogicFactory rlf = new RestLogicFactory();
final LogicInterface logic = rlf.getLogicAccess("YourUserName", "YourAPIKey");

The LogicInterface is the entry point to the API and provides the methods to query it. Unfortunately, still not all methods are implemented but the most important ones are.

If you want to use the JAVA Client for a PUMA instance, you have to provide the URL of your PUMA installation in the constructor of the RestLogicFactory:

final RestLogicFactory rlf = new RestLogicFactory(ADDRESS_OF_YOUR_INSTALLATION/api);

Query for Posts and Tags

There are separate methods to get posts and tags:

Posts

List<Post<Bookmark>> bookmarks = logic.getPosts(Bookmark.class, GroupingEntity.USER, "jaeschke", null, null, null, null, null, Order.ADDED, null, null, 0, 100);

returns the first 100 bookmarks of the user "jaeschke". To get the publications or the next bookmarks you have to change the parameters.

List<Post<BibTex>> publications = logic.getPosts(BibTex.class, GroupingEntity.ALL, null, null, null, null, "Attribute Exploration on the Web", null, null, null, null, 0, 100);

returns the first 100 publications that match the query "Attribute Exploration on the Web".

Tags

List<Tag> tags = logic.getTags(Resource.class, GroupingEntity.USER, "jaeschke", null, null, null, null, 0, 1000, null, null);

returns the first 1000 tags of the user "jaeschke". Again, you can use the parameters to restrict the query, e.g., to get only the tags from the user's bookmarks.

Get all informations of a single post

If you only want to get all informations of a single post you can use the getPostDetails method. You must specify the username and intrahash of the post you want to retrieve. The intrahash is a 32 chars long hash; if the hash is 33 long remove the leading 2. (It is only the identifier that the specified hash is an intrahash and not an interhash).

// @see http://www.bibsonomy.org/bibtex/25854a71547051543dd3d3d5e2e2f2b67/dbenz
final Post<BibTex> post = (Post<BibTex>) logic.getPostDetails("5854a71547051543dd3d3d5e2e2f2b67", "dbenz");

returns the publication of the user dbenz with the intrahash 5854a71547051543dd3d3d5e2e2f2b67 with its tags, …

[rest-api]: REST API

Create a new Post

If you want to create a new post with the Java Client, just setup your post and use the createPosts method. Each post must have a user, a group, a resource (bookmark or publication) and at least on tag set. The method takes a list of posts, but you can also create a single post with this method as shown below:

final Post<Bookmark> post = new Post<Bookmark>();
post.setGroups(Collections.singleton(GroupUtils.getPublicGroup()));
post.addTag("bitbucket");
post.addTag("mercurial");
post.addTag("hg");
post.addTag("git");
post.addTag("hosting");
post.setUser(new User("YourUserName"));

final Bookmark bookmark = new Bookmark();
bookmark.setUrl("http://www.bitbucket.org");
bookmark.setTitle("Free source code hosting for Git and Mercurial by Bitbucket");

post.setResource(bookmark);

logic.createPosts(Collections.<Post<? extends Resource>>singletonList(post));

or a publication:

final Post<Bookmark> post = new Post<Bookmark>();
post.setGroups(Collections.singleton(GroupUtils.getPublicGroup()));
post.addTag("bitbucket");
post.addTag("mercurial");
post.addTag("hg");
post.addTag("git");
post.addTag("hosting");
post.setUser(new User("YourUserName"));

final BibTex publication = new BibTex();

publication.setTitle("Your Title");
publication.setAuthor(PersonNameUtils.discoverPersonNamesIgnoreExceptions("Doe, John"));
publication.setYear("2007");
publication.setBibtexKey(BibTexUtils.generateBibtexKey(publication));
publication.setEntrytype("article");

logic.createPosts(Collections.<Post<? extends Resource>>singletonList(post));

Update an existing Post

You can also update your own posts using the Java Client. First get the post to update and than modify it with the updatePosts method. The method takes the posts you want to update and an postUpdateOperation (Currently the Java Client only supports UPDATE_ALL). As the createPosts method you can also use the method to only update one single post.

e. g. adding a tag (newtag) to an existing post can be achieved with the following code:

final Post<? extends Resource> post = // get the post
post.addTag("newtag");
logic.updatePosts(Collections.<Post<? extends Resource>>singletonList(post), PostUpdateOperation.UPDATE_ALL);

Add a document to a post

To attach a new document to a publication call the createDocument method as follows:

File theFile = new File("ABSOLUTE_PATH"); // ensure that the file can be read
final Document document = new Document();
document.setFile(theFile);
document.setFileName("FILE_NAME");
document.setUserName("USER_NAME_OF_THE_OWNER_OF_THE_DOCUMENT");
logic.createDocument(document, "RESOURCE_HASH");

Renaming a document of a post

If you want to rename a document of a post, use the updateDocument method as follows:

final Document document = new Document();
document.setFileName("OLDFILE_NAME.EXTENSION");
document.setUserName("USER_NAME_OF_THE_OWNER_OF_THE_DOCUMENT");
/* you can also get the document from the publication, but check that file name and user name are set */
logic.updateDocument(document, "RESOURCE_HASH", "NEW_FILENAME");

Delete a document of a post

You can delete a document using the deleteDocument method of the logic:

final Document document = new Document();
document.setFileName("FILE_NAME.EXTENSION");
document.setUserName("USER_NAME_OF_THE_OWNER_OF_THE_DOCUMENT");
/* you can also get the document from the publication, but check that file name and user name are set */
logic.deleteDocument(document, "RESOURCE_HASH");

Updated