Wiki
Clone wikiBibSonomy / 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:
#!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);
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.
Tags
#!java List<Tag> tags = logic.getTags(Resource.class, GroupingEntity.USER, "jaeschke", null, null, null, null, null, null, null, null, 0, 1000);
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).
#!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");
Updated