Knicker Version 2 and Examples

Version 2 of Knicker, the Java library for the Wordnik API, is now available. This version supports version 4 of the Wordnik API.

In addition to supporting version 4 of the Wordnik API, this version of Knicker follows the organization of the API more closely. Previously, all the methods were in one class, Knicker.java. Knicker.java still exists, but it is now abstract and contains only constants used by other classes. The methods that access the Wordnik API are now in classes named after the section of the API they access. So account API methods are now in AccountApi, word API methods are in WordApi, and so on. This makes the source a little more manageable, and allows a more modular approach to testing and development.

This version also includes JUnit tests for all the Wordnik API methods. During the development of version 2, these tests helped find several bugs in the API, which the Wordnik team quickly fixed.

One of the coolest features of the new Wordnik API is the ability to retrieve audio pronunciation data for words. Retrieval of the audio data is fully supported in Knicker version 2. Playback of the data is left up to you.

In addition to a new version of the library, I have also started a Knicker Examples project. There is currently one example that shows how to retrieve and display text definitions, and retrieve and play the audio definition for the word. The project contains all necessary libraries, so you can grab it and go. I will probably be adding additional examples as I have time, and contributions are welcome.

As always, please let me know when you find bugs. You can contact me via email, leave a comment here, or post to the Wordnik developers mailing list, which I am subscribed to.

Happy coding!

Introducing Jinx

Jinx is a Java library that provides access to the Flickr API. It is pure Java, with no external dependencies.

The package structure is straightforward. Each Flickr API section (activity, auth, blogs, etc) has a corresponding class in the net.jeremybrooks.jinx.api package. The API classes are named ActivityApi, AuthApi, BlogsApi, etc. Each API class is implemented as a singleton. You can obtain an instance of an API class with a call to getInstance():

1
BlogsApi bApi = BlogsApi.getInstance();

Each Flickr method has a corresponding method in the API class. So if you want to call the Flickr flickr.blogs.getList method, you will call the getList() method on BlogsApi:

1
BlogsApi.getInstance().getList();

The API methods that return data will generally return instances of the Data Transfer Objects located in the net.jeremybrooks.jinx.dto package. The DTO’s are very simple classes, containing getter and setter methods and no other logic. All DTO’s implement java.io.Serializable.

Flickr returns a status message along with data for every API call. Jinx will check that status message for you. If Flickr reports an error, an instance of net.jeremybrooks.jinx.JinxException will be thrown. The Flickr error code and error message can be retrieved by calling getErrorCode and getErrorMessage.

This project is currently being used in SuprSetr. Currently, the following Flickr API sections are implemented:

  • Activity
  • Auth
  • Blogs
  • Collections
  • Commons
  • Photos
  • Photosets

Other sections of the Flickr API will be implemented over time. If you want to use Jinx now, you can get the source code from github and build it with ant. If you just want the binary jar file, you can download it at the Jinx home page. Javadocs are located here.

The test directory contains sample code showing how to use Jinx to access the Flickr API. Here is the TestAuthorization class, showing how to authorize an application to use Flickr:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import java.io.File;
import net.jeremybrooks.jinx.Jinx;
import net.jeremybrooks.jinx.JinxConstants;
import net.jeremybrooks.jinx.api.AuthApi;
import net.jeremybrooks.jinx.dto.Frob;
import net.jeremybrooks.jinx.dto.Token;

/**
 * This test class demonstrates how to perform authorization for your application.
 *
 * Your application must have its own key and secret. These can be obtained here:
 * http://www.flickr.com/services/apps/create/apply/?
 *
 *
 * @author jeremyb
 */

public class TestAuthorizaion {

    /*
     * Get a key for your app here:
     * http://www.flickr.com/services/apps/create/apply/?
     */

    private static final String KEY = "";
    private static final String SECRET = "";

    public static void main(String[] args) {

    File tokenFile = new File("/tmp/myToken");
    Token token = null;

    try {
        // Attempt to initialize with an existing token
        if (tokenFile.exists()) {
        token = new Token();
        token.load(tokenFile);
        Jinx.getInstance().init(KEY, SECRET, token);

        } else {

        // No token exists, so initialize with our key and secret,
        // then prompt user to authorize our application
        Jinx.getInstance().init(KEY, SECRET);
        Frob frob = AuthApi.getInstance().getFrob(JinxConstants.PERMS_READ);

        // Send user to the login URL
        // In a real application, you would probably do this in a GUI
        // of some sort
        System.out.println("Please go to this URL and allow access: " + frob.getLoginUrl());
        System.out.println("After you have authorized this application, press a key.");

        // Wait for user to press a key
        System.in.read();

        // Complete authorization by getting the token and telling
        // Jinx about it
        token = AuthApi.getInstance().getToken(frob);
        Jinx.getInstance().setToken(token);

        System.out.println("Authorization successful.");

        // The token can be stored for future use, and is valid until
        // the user revokes access
        token.store(new File("/tmp/myToken"));
        }
    } catch (Exception e) {
        System.out.println("Oops, something went wrong!");
        e.printStackTrace();
    }
    }
}

Jinx is released under the Gnu General Public License.