figshare-client-java
Java bindings to Figshare API
This project uses Spring-REST and Spring Social to provide a Java client to the Figshare API.
It is not complete, but supports basic Article operations and File upload.
This library is also now available in MavenCentral if you want to just add it as a dependency:
<dependency>
<groupId>com.researchspace</groupId>
<artifactId>figshare-client-java</artifactId>
<version>0.1.1</version>
</dependency>
or in Gradle:
compile 'com.researchspace:figshare-client-java:0.1.1'
Building
To compile and run unit tests, check out and run the following command. This will install the Gradle build tool if you don't already have it.
./gradlew clean test
To build a jar without integration tests:
./gradlew clean build -x integrationTest
Integration tests
Integration tests make real calls to the Figshare API. To run integration tests, you'll need a previously created Figshare account and a private access token that you can obtain from your Figshare account settings page. Add this as a command-line option, replacing 'XXXXX' with your token:
./gradlew clean integrationTest -DfigshareToken=XXXXX
Alternatively you can add the line:
systemProp.figshareToken=XXXXXXX
to the file gradle.properties in your GRADLE_HOME folder (by default this is USER_HOME/.gradle) and run using command:
./gradlew clean integrationTest
Using the library
The library can be used either with a personal token or by using the OAuth2 mechanism to acquire an access token.
Additionally you can use this library in a Spring application, or independently.
If a personal token is used, this will take precedence over any OAuth2 access token
Use case 1 - personal token:
In a Spring application
Simply supply a personal token as a system property and autowire the Figshare API into your application:
@Autowired
private Figshare figshare;
To set up Figshare bean, if using Java configuration, use the configuration as is from SpringTestConfig. E.g.
@Autowired Environment env;
@Bean
FigshareTemplate FigshareTemplate (){
FigshareTemplate ft = new FigshareTemplate();
ft.setPersonalToken(env.getProperty("figshareToken"));
return ft;
}
In a non-Spring application
You'll have to set up the FigshareTemplate manually:
String token = "myToken";
FigshareTemplate ft = new FigshareTemplate();
ft.setPersonalToken(token);
return ft;
Usage
Here is some code which creates a new article, uploads a file, and returns a link to the article on the Figshare website.
// get a file from somewhere.
File anyFile = new File("Somefile.xls");
// Objects to post are generally created using Builder pattern:
ArticlePostBuilder articleBuilder = ArticlePost.builder();
articleBuilder.title("title")
.description("Some description")
.author(new Author("Fred Bloggs", null))
.author(new Author(null, "[email protected]"));
// you can also iterate over Categories to find the ID matching your category
articleBuilder.category(Category.UNCATEGORIZED.getId().intValue());
// tag required for publishing to work, if needed.
articleBuilder.tags(Arrays.asList(new String []{"from_java"}));
ArticlePost toPost = articleBuilder.build();
// now let's submit it:
Location article = figshare.createArticle(toPost);
PrivateArticleLink privateLink = figshare.createPrivateArticleLink(article.getId());
Location fileId = figshare.uploadFile(article.getId(), anyFile);
String feedbackMsg = String.format("Deposit succeeded - private article link is %s.", privateLink.getWeblink());