com.thirtyboxes.api
Class ThirtyBoxes

java.lang.Object
  extended by com.thirtyboxes.api.ThirtyBoxes

public class ThirtyBoxes
extends java.lang.Object

Represents a connection to the 30 Boxes API.

All the API methods published by 30 Boxes at this page:
http://30boxes.com/api/
...are included here.

To use this, you will need an API key from here:
http://30boxes.com/api/api.php?method=getKeyForUser

Then create a ThirtyBoxes object with that key, and use!

    ThirtyBoxes myThirtyBoxes = new ThirtyBoxes("this is my api key, really it is!");
    try
    {
       if (tb.testPing())
       {
          System.out.println("API key is valid, 30 Boxes is reachable");
       }
    }
    catch ( MethodCallFailedException mcfe )
    {
        System.out.println("Ping failed! " + mcfe.getReasonString());
    }
 

Note that the apiKey is stored in the object, and does not have to be passed in with each method call, and the method call names have their dot removed, so the api method:

events.TagSearch ( apiKey, authorizedUserToken, tag )

becomes...

myThirtyBoxes.eventsTagSearch(authorizedUserToken,tag);

This implementation uses the Apache Jakarta HttpClient library for HTTP connections, and the BrowserLauncher2 library to pop up a browser in the userAuthorize method, so you will need the following libraries in your path (or later equivalents).

(Note: BrowserLauncher2 is not required if you do not use userAuthorize(), for instance if you have your own way of redirecting a browser to the URL returned by getUserAuthorizeURL()).

Version:
1.0
Author:
keith@kludge.co.uk

Field Summary
static java.lang.String apiBaseURL
           
 
Constructor Summary
ThirtyBoxes(java.lang.String apiKey)
          Default constructor.
 
Method Summary
protected static java.lang.String calendarToDateEntry(java.util.Calendar date)
          Utility function to convert Calendar objects into the 30 Boxes API format for dates.
protected  RESTResult callMethod(java.lang.String methodName, java.lang.String urlSuffix)
          Utility function to call the API (by using the Apache Jakarta HttpClient library)
protected static java.util.Calendar dateEntryToCalendar(java.lang.String date)
          Utility function to convert the 30 Boxes API format for dates into Calendar objects.
 Event[] eventsGet(AuthorizedUserToken userToken, java.util.Calendar startDate, java.util.Calendar endDate)
          The API events.Get method.
 Event[] eventsSearch(AuthorizedUserToken userToken, java.lang.String query)
          The API events.Search method.
 Event[] eventsTagSearch(AuthorizedUserToken userToken, java.lang.String tag)
          The API events.TagSearch method.
 RESTResult getLastResult()
          Gets the result of the last method call.
 java.lang.String getUserAuthorizeURL(java.lang.String applicationName, java.net.URL applicationLogo, java.net.URL returnURL)
          Returns the URL a user needs to visit to authorize an application to access their private info.
 void setProxy(java.lang.String proxyHost, int proxyPort)
          Tells the API object that it will need to connect through a proxy.
 boolean testPing()
          The API test.Ping method.
 void userAuthorize(java.lang.String applicationName, java.net.URL applicationLogo, java.net.URL returnURL)
          The API user.Authorize method.
 User userFindByEmail(java.lang.String emailAddress)
          The API user.FindByEmail method.
 User userFindById(int id)
          The API user.FindById method.
 User userGetAllInfo(AuthorizedUserToken userToken)
          The API user.GetAllInfo method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

apiBaseURL

public static final java.lang.String apiBaseURL
See Also:
Constant Field Values
Constructor Detail

ThirtyBoxes

public ThirtyBoxes(java.lang.String apiKey)
Default constructor.

Parameters:
apiKey - A valid 30 Boxes API key
Method Detail

setProxy

public void setProxy(java.lang.String proxyHost,
                     int proxyPort)
Tells the API object that it will need to connect through a proxy.

Parameters:
proxyHost - The proxy host's machine name or ip address
proxyPort - The proxy port number through which web traffic should go

getLastResult

public RESTResult getLastResult()
Gets the result of the last method call.

Returns:
The result of the last method call, or null if none have been called.

testPing

public boolean testPing()
                 throws MethodCallFailedException
The API test.Ping method.

Returns:
True if 30 Boxes accepted your api Key, false if they didn't.
Throws:
MethodCallFailedException - if the method call failed.

userFindByEmail

public User userFindByEmail(java.lang.String emailAddress)
                     throws MethodCallFailedException
The API user.FindByEmail method.

Parameters:
emailAddress - The email address of the user to search for
Returns:
A User object with Public information, or null if the user wasn't found.
Throws:
MethodCallFailedException - if the method call failed.

userFindById

public User userFindById(int id)
                  throws MethodCallFailedException
The API user.FindById method. This function might be used to get public information on a person in another User's buddy list (part of the Private information you can get on an authorized user).

Parameters:
id - The 30 Boxes id of the user to search for
Returns:
A User object with Public information, or null if the user wasn't found.
Throws:
MethodCallFailedException - if the method call failed.

getUserAuthorizeURL

public java.lang.String getUserAuthorizeURL(java.lang.String applicationName,
                                            java.net.URL applicationLogo,
                                            java.net.URL returnURL)
Returns the URL a user needs to visit to authorize an application to access their private info.

If you have help hyperlinks in your program that the user is directed to click on to authorize your program, they can get the needed URL with this function.

Note that the returnURL parameter will be essentially useless for any desktop programs (since 30 boxes will not be able to connect to a webserver on the program to authorize it), but it might well be useful for JSP programs.

Parameters:
applicationName - The public name of your app (will appear on the auth page)
applicationLogo - A URL for your app's logo (will appear on the auth page), or null.
returnURL - A URL the auth page will send a token to. Usually null (see above)
Returns:
The URL String the user needs to visit to authorize your application.

userAuthorize

public void userAuthorize(java.lang.String applicationName,
                          java.net.URL applicationLogo,
                          java.net.URL returnURL)
                   throws MethodCallFailedException
The API user.Authorize method.

As mentioned in the 30 Boxes API Documentation, this function is a bit different from all the rest. In this implementation, it returns immediately, but pops open the user's default browser pointing to the Authorization page. You should prompt the user (either on the command line or with a text field if your program is a GUI) for the key they will see on that page. The key they copy back can be used to create an AuthorizedUserToken object, which you will need for some of the more advanced functions.

Note that the returnURL parameter will be essentially useless for any desktop programs (since 30 boxes will not be able to connect to a webserver on the program to authorize it), but it might well be useful for JSP programs.

Parameters:
applicationName - The public name of your app (will appear on the auth page)
applicationLogo - A URL for your app's logo (will appear on the auth page), or null.
returnURL - A URL the auth page will send a token to. Usually null (see above)
Throws:
MethodCallFailedException - if a browser could not be launched.

userGetAllInfo

public User userGetAllInfo(AuthorizedUserToken userToken)
                    throws MethodCallFailedException
The API user.GetAllInfo method.

Parameters:
userToken - The token got from 30 Boxes by using userAuthorize()
Returns:
A User object with Private information, or null if the user wasn't found.
Throws:
MethodCallFailedException - if the method call failed.

eventsGet

public Event[] eventsGet(AuthorizedUserToken userToken,
                         java.util.Calendar startDate,
                         java.util.Calendar endDate)
                  throws MethodCallFailedException
The API events.Get method.

Note that if you set startDate to null it defaults to today, and if you set endDate to null it defaults to startDate + 90 days. It can't be more than startDate + 180 days (or - well, it can, but 30 Boxes will ignore that and trim it to start + 180.

The array returned by this function will never by null, it will only be empty, so it is safe to use in iterators without checking for null.

Parameters:
userToken - The token got from 30 Boxes by using userAuthorize()
startDate - The date to start finding events from (or null to get all events)
endDate - The date to finish finding events (or null to get all events)
Returns:
An array of Event objects (or an empty array).
Throws:
MethodCallFailedException - if the method call failed.

eventsSearch

public Event[] eventsSearch(AuthorizedUserToken userToken,
                            java.lang.String query)
                     throws MethodCallFailedException
The API events.Search method.

The array returned by this function will never by null, it will only be empty, so it is safe to use in iterators without checking for null.

Parameters:
userToken - The token got from 30 Boxes by using userAuthorize()
query - The string to search events for.
Returns:
An array of Event objects that match the query (or an empty array).
Throws:
MethodCallFailedException - if the method call failed.

eventsTagSearch

public Event[] eventsTagSearch(AuthorizedUserToken userToken,
                               java.lang.String tag)
                        throws MethodCallFailedException
The API events.TagSearch method.

The array returned by this function will never by null, it will only be empty, so it is safe to use in iterators without checking for null.

Parameters:
userToken - The token got from 30 Boxes by using userAuthorize()
tag - The tag to search events for.
Returns:
An array of Event objects with the supplied tag (or an empty array).
Throws:
MethodCallFailedException - if the method call failed.

calendarToDateEntry

protected static java.lang.String calendarToDateEntry(java.util.Calendar date)
Utility function to convert Calendar objects into the 30 Boxes API format for dates.

Parameters:
date - Calendar object representing the date to convert.
Returns:
A string of that date in the YYYY-MM-DD format used by the API

dateEntryToCalendar

protected static java.util.Calendar dateEntryToCalendar(java.lang.String date)
                                                 throws java.lang.NumberFormatException
Utility function to convert the 30 Boxes API format for dates into Calendar objects. This function will convert either "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format.

Parameters:
date - A string in the YYYY-MM-DD HH:MM:SS format used by the API
Returns:
Calendar object representing the specified date
Throws:
java.lang.NumberFormatException - if the date string was invalid

callMethod

protected RESTResult callMethod(java.lang.String methodName,
                                java.lang.String urlSuffix)
                         throws MethodCallFailedException
Utility function to call the API (by using the Apache Jakarta HttpClient library)

Parameters:
methodName - The API method name as specified by 30 Boxes
urlSuffix - A string containing the optional parameters of the call
Returns:
A RESTResult object containing the parsed XML returned by the API
Throws:
MethodCallFailedException - if the method call failed for any reason