Wiki

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:

#!xml

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

and the following dependency:

#!xml

<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:

#!java
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:

#!java
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

#!java

PostQuery<Bookmark> query = new PostQueryBuilder()
  .setGrouping(GroupingEntity.USER)
  .setGroupingName("jaeschke")
  .end(100)
  .setSortCriteria(SortUtils.singletonSortCriteria(SortKey.DATE, SortOrder.DESC))
  .setScope(QueryScope.LOCAL)
  .createPostQuery(Bookmark.class);

List<Post<Bookmark>> posts = logic.getPosts(query);

returns the first 100 bookmarks of the user "jaeschke". To get the publications or the next bookmarks you have to change the parameters (e.g., Bookmark.class to BibTex.class to get publications instead of bookmarks and 100 to a lower or higher value to get less or more results).

#!java

PostQuery<BibTex> query = new PostQueryBuilder()
  .search("Attribute Exploration on the Web")
  .setGrouping(GroupingEntity.ALL)
  .end(100)
  .setSortCriteria(SortUtils.singletonSortCriteria(SortKey.DATE, SortOrder.DESC))
  .createPostQuery(BibTex.class);

List<Post<BibTex>> posts = logic.getPosts(query);

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

#!java

PostQuery<BibTex> query = new PostQueryBuilder()
  .setGrouping(GroupingEntity.USER)
  .setGroupingName("jaeschke")
  .end(100)
  .setSortCriteria(SortUtils.singletonSortCriteria(SortKey.TITLE, SortKey.ASC))
  .setScope(QueryScope.SEARCHINDEX)
  .createPostQuery(BibTex.class);

List<Post<BibTex>> posts = logic.getPosts(query);

returns the first 100 publications of the user "jaeschke". The result list will be alphabetically sorted by their titles in ascending order.

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).

#!java
// @see https://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 set up 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:

#!java
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("https://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:

#!java
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:

#!java
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:

#!java
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:

#!java
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:

#!java
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");