|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.thirtyboxes.api.ThirtyBoxes
public class ThirtyBoxes
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()).
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 |
---|
public static final java.lang.String apiBaseURL
Constructor Detail |
---|
public ThirtyBoxes(java.lang.String apiKey)
apiKey
- A valid 30 Boxes API keyMethod Detail |
---|
public void setProxy(java.lang.String proxyHost, int proxyPort)
proxyHost
- The proxy host's machine name or ip addressproxyPort
- The proxy port number through which web traffic should gopublic RESTResult getLastResult()
public boolean testPing() throws MethodCallFailedException
MethodCallFailedException
- if the method call failed.public User userFindByEmail(java.lang.String emailAddress) throws MethodCallFailedException
emailAddress
- The email address of the user to search for
MethodCallFailedException
- if the method call failed.public User userFindById(int id) throws MethodCallFailedException
id
- The 30 Boxes id of the user to search for
MethodCallFailedException
- if the method call failed.public java.lang.String getUserAuthorizeURL(java.lang.String applicationName, java.net.URL applicationLogo, java.net.URL returnURL)
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.
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)
public void userAuthorize(java.lang.String applicationName, java.net.URL applicationLogo, java.net.URL returnURL) throws MethodCallFailedException
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.
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)
MethodCallFailedException
- if a browser could not be launched.public User userGetAllInfo(AuthorizedUserToken userToken) throws MethodCallFailedException
userToken
- The token got from 30 Boxes by using userAuthorize()
MethodCallFailedException
- if the method call failed.public Event[] eventsGet(AuthorizedUserToken userToken, java.util.Calendar startDate, java.util.Calendar endDate) throws MethodCallFailedException
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.
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)
MethodCallFailedException
- if the method call failed.public Event[] eventsSearch(AuthorizedUserToken userToken, java.lang.String query) throws MethodCallFailedException
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.
userToken
- The token got from 30 Boxes by using userAuthorize()query
- The string to search events for.
MethodCallFailedException
- if the method call failed.public Event[] eventsTagSearch(AuthorizedUserToken userToken, java.lang.String tag) throws MethodCallFailedException
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.
userToken
- The token got from 30 Boxes by using userAuthorize()tag
- The tag to search events for.
MethodCallFailedException
- if the method call failed.protected static java.lang.String calendarToDateEntry(java.util.Calendar date)
date
- Calendar object representing the date to convert.
protected static java.util.Calendar dateEntryToCalendar(java.lang.String date) throws java.lang.NumberFormatException
date
- A string in the YYYY-MM-DD HH:MM:SS format used by the API
java.lang.NumberFormatException
- if the date string was invalidprotected RESTResult callMethod(java.lang.String methodName, java.lang.String urlSuffix) throws MethodCallFailedException
methodName
- The API method name as specified by 30 BoxesurlSuffix
- A string containing the optional parameters of the call
MethodCallFailedException
- if the method call failed for any reason
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |