With the current implementation of TumblrJ working properly for straight reads of different types, I figured I’d show a quick demo of the api usage (without Spring – I’ll post something about that later).

The api revolves around a single class called TumblrService. The class pretty much acts like a facade hiding the implementation details. The TumblrService needs a couple things to work properly:

  1. A TumblrJProperties instance
  2. An implementation of the ITumblrReader interface. The api includes the only one possible at this point which is an HTTP specific implementation.

Configuration

The TumblrJProperties class automatically initializes itself by looking for a file called tumblrj-config.properties in the classpath. You can override the name by using the 1 arg constructor. For now, the file needs to be found in the classpath.

The file contains basic information about paths, url’s, … The contents should look something exactly like:

base.url=http://{0}.tumblr.com
path.read=/api/read
path.authenticate=/api/authenticate
path.delete=/api/delete

Since most of these properties are pretty much standard, I’ll implement a defaults mechanism so that they aren’t mandatory.

Connection options

The other object needed to use the TumblrService and TumblrHttpReader classes is a TumblrConnectionOptions instance. At a very minimum, you’ll need to enter the name of your tumblr log (usualy, the first part in your tumblr.com url). If you want to access private posts, you’ll want to put in your email and password.

And for those who want fine grained control over the connection options, the object can also accept a org.apache.commons.httpclient.params.HttpClientParams instance which will be used on every http call.

Full Example

TumblrConnectionOptions connectionOptions = new TumblrConnectionOptions();
connectionOptions.setName("lama");

TumblrHttpReader reader = new TumblrHttpReader();

TumblrJProperties properties = new TumblrJProperties();
reader.setProperties(properties);
reader.setTumblrConnectionOptions(connectionOptions);

TumblrService service = new TumblrService();
service.setReader(reader);
TumblrReadOptions readOptions = new TumblrReadOptions();
readOptions.setStart(1);
readOptions.setNum(1);

TumbleLog log = service.read(readOptions);

Explanation

Lines 1 through 11 were pretty much explaines. Lines 12, 13 and 14 are interesting in that they let you configure the read options by letting you filter the data. The available options include:

  • Wether or not to include private posts
  • The start and number of posts to return (for paging and limiting results)
  • The id of the post
  • The type of post

Check out the TumblrReadOptions class for details.

Line 13 is the line where the read is executed and a TumbleLog object returned. That object will include a List of TumblePost objects as well as a gamut of other information concerning the returned results. As mentionned before, the test package contains a lot of usefull unit tests showing off how to use the different read options.