ej.rest.web

Class Resty

java.lang.Object

ej.rest.web.Resty

Direct Known Subclasses:

AbstractResource

public class Resty
extends Object

Main class. Use me! Use me! Resty is a small, convenient interface to talk to RESTful services. Basic usage is very simple: Create a Resty instance, use authenticate methode to add credentials (optional), then call one of the content type specific methods, like json(...), xml(...), text(...) or bytes(...). The idea is that the method name will convey the expected content type you can then operate on. Most static methods help you build content objects or queries with a compact syntax. Static methods like put(...) and delete() are used to implement the respective HTTP methods. A neat trick to save you typing is to use

 import static us.monoid.web.Resty.*;
 

GETting an URL (as JSON):

 new Resty().json(url);
 

POSTing to an URL (using multipart/form-data) and expecting JSON back:

 new Resty().json(url, form(data("name", "Don Draper"), data("occupation", "Ad Man")));
 

PUTting content and expecting JSON back:

 
 new Resty().json(url, put(content(someJSON)));
 
 

DELETE a resource via URL expecting JSON back:

 new Resty().json(url, delete());
 

Here is an example on how to use the geonames web service. It retrieves the json object (see json.org for details) and gets the name of a place from the zip code:

 
        Resty r = new Resty();
        Object name = r.json("http://ws.geonames.org/postalCodeLookupJSON?postalcode=66780&country=DE").get("postalcodes[0].placeName");
        assertEquals(name, "Rehlingen-Siersburg");
 
 

The return value is a resource with the data you requested AND a new Resty instance with the same set of options you initialized Resty with. Resty supports complex path queries to navigate into a json object. This is mainly used for extracting URIs to surf along a series of REST resources for web services following the HATEOS paradigm. Resty objects are not re-entrant. You can also specify options when creating a Resty instance. Well, currently there is one option to set the timeout for connections. But you can also create your own options! See Resty.Option for more info.

Author:

beders

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Resty.Option Base class for Resty options.
static class	Resty.Timeout Option to set a timeout.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	DEFAULT_USER_AGENT
protected static String	MOZILLA
protected String	userAgent

Constructor Summary

Constructors

Constructor and Description
Resty(Resty.Option... someOptions) Create an instance of Resty with the following list of options.

Method Summary

Modifier and Type	Method and Description
protected void	addAdditionalHeaders(URLConnection con) Add all headers that have been set with the alwaysSend call.
protected <T extends AbstractResource> void	addStandardHeaders(URLConnection con, T resource) Add all standard headers (User-Agent, Accept) to the URLConnection.
BinaryResource	bytes(String anUri) Get the resource specified by the uri and return a binary resource for it.
BinaryResource	bytes(String anUri, AbstractContent someContent) POST to the URI and get the resource as binary resource.
BinaryResource	bytes(URI anUri) Get the resource specified by the uri and return a binary resource for it.
BinaryResource	bytes(URI anUri, AbstractContent someContent) POST to the URI and get the resource as binary resource.
static ChunkedContent	chunked(String mime, InputStream stream) Create chunked data
static ChunkedContent	chunked(String mime, InputStream stream, int chunkSize) Create chunked data
static Content	content(byte[] bytes) Create a content object from a byte array.
static Content	content(JSONArray someJson) Create a content object from a JSON array.
static Content	content(JSONObject someJson) Create a content object from a JSON object.
static Content	content(String somePlainText) Create a content object from plain text.
protected BinaryResource	createBinaryResource()
protected JSONResource	createJSONResource()
protected TextResource	createTextResource()
static FormData	data(String name, AbstractContent content) Create a form data entry for a multipart form with any kind of content type.
static FormData	data(String name, String plainTextValue) Create a plain/text form data entry for a multipart form.
static AbstractContent	delete() Tell Resty to delete the URL content on the server, resulting in a DELETE.
protected <T extends AbstractResource> T	doGET(URI anUri, T resource)
void	dontSend(String aHeader) Don't send a header that was formely added in the alwaysSend method.
protected <T extends AbstractResource> T	doPOSTOrPUT(URI anUri, AbstractContent requestContent, T resource)
protected <T extends AbstractResource> T	fillResourceFromURL(URLConnection con, T resource) Get the content from the URLConnection, create a Resource representing the content and carry over some metadata like HTTP Result and location header.
static MultipartContent	form(FormData... formData) Create form content to be sent as multipart/form-data.
static FormContent	form(String query) Create form content as application/x-www-form-urlencoded (i.e.
protected Map<String,String>	getAdditionalHeaders()
Resty	identifyAsMozilla() Sets the User-Agent to identify as Mozilla/Firefox.
Resty	identifyAsResty() Sets the User-Agent to Resty.
JSONResource	json(String string) GET a URI given by string and parse the result as JSON.
JSONResource	json(String anUri, AbstractContent content)
JSONResource	json(URI anUri) GET a URI and parse the result as JSON.
JSONResource	json(URI anUri, AbstractContent requestContent) POST to a URI and parse the result as JSON
protected <T extends AbstractResource> URLConnection	openConnection(URI anUri, T resource)
static JSONPathQuery	path(String string) Create a JSONPathQuery to extract data from a JSON object.
static AbstractContent	put(Content someContent) Tell Resty to replace the specified content on the server, resulting in a PUT operation instead of a POST operation.
Resty	setOptions(Resty.Option... someOptions) Set options if you missed your opportunity in the c'tor or if you want to change the options.
TextResource	text(String anUri) Get a plain text resource for the specified URI.
TextResource	text(String anUri, AbstractContent content) Get a plain text resource for the specified URI by POSTing to it.
TextResource	text(URI anUri) Get a plain text resource for the specified URI.
TextResource	text(URI anUri, AbstractContent content) Get a plain text resource for the specified URI by POSTing to it.
void	withHeader(String aHeader, String aValue) Tell Resty to send the specified header with each request done on this instance.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_USER_AGENT

protected static String DEFAULT_USER_AGENT

MOZILLA

protected static String MOZILLA

userAgent

protected String userAgent

Constructor Detail

Resty

public Resty(Resty.Option... someOptions)

Create an instance of Resty with the following list of options. Also, options are carried over to resources created by calls to json/text/binary etc. Use setOptions(Option...) to change options afterwards.

Method Detail

addAdditionalHeaders

protected void addAdditionalHeaders(URLConnection con)

Add all headers that have been set with the alwaysSend call.

addStandardHeaders

protected <T extends AbstractResource> void addStandardHeaders(URLConnection con,
                                                               T resource)

Add all standard headers (User-Agent, Accept) to the URLConnection.

bytes

public BinaryResource bytes(String anUri)
                     throws IOException

Get the resource specified by the uri and return a binary resource for it.

Parameters:

anUri - the uri to follow

Returns:

Throws:

IOException

bytes

public BinaryResource bytes(String anUri,
                            AbstractContent someContent)
                     throws IOException

POST to the URI and get the resource as binary resource.

Parameters:

anUri - the uri to follow

Returns:

Throws:

IOException

bytes

public BinaryResource bytes(URI anUri)
                     throws IOException

Get the resource specified by the uri and return a binary resource for it.

Parameters:

anUri - the uri to follow

Returns:

Throws:

IOException

bytes

public BinaryResource bytes(URI anUri,
                            AbstractContent someContent)
                     throws IOException

POST to the URI and get the resource as binary resource.

Parameters:

anUri - the uri to follow

Returns:

Throws:

IOException

chunked

public static ChunkedContent chunked(String mime,
                                     InputStream stream)

Create chunked data

Parameters:

mime - mime type

stream - stream to read content from

Returns:

chunked

public static ChunkedContent chunked(String mime,
                                     InputStream stream,
                                     int chunkSize)

Create chunked data

Parameters:

mime - the mime

stream - the stream

chunkSize - the chunk size used to configure HttpURLConnection streaming mode

Returns:

the chunked content

content

public static Content content(byte[] bytes)

Create a content object from a byte array. Use this to POST the content to a URL with mime type application/octet-stream.

Parameters:

bytes - the bytes to send

Returns:

the content to send

content

public static Content content(JSONArray someJson)

Create a content object from a JSON array. Use this to POST the content to a URL.

Parameters:

someJson - the JSON array to use

Returns:

the content to send

content

public static Content content(JSONObject someJson)

Create a content object from a JSON object. Use this to POST the content to a URL.

Parameters:

someJson - the JSON object to use

Returns:

the content to send

content

public static Content content(String somePlainText)

Create a content object from plain text. Use this to POST the content to a URL.

Parameters:

somePlainText - the plain text to send

Returns:

the content to send

createBinaryResource

protected BinaryResource createBinaryResource()

createJSONResource

protected JSONResource createJSONResource()

createTextResource

protected TextResource createTextResource()

data

public static FormData data(String name,
                            AbstractContent content)

Create a form data entry for a multipart form with any kind of content type.

Parameters:

name - the name of the control or variable in a form

content - the content to send

Returns:

data

public static FormData data(String name,
                            String plainTextValue)

Create a plain/text form data entry for a multipart form.

Parameters:

name - the name of the control of the form

plainTextValue - the plain text value

Returns:

the FormData part used in a multipart/form-data upload

delete

public static AbstractContent delete()

Tell Resty to delete the URL content on the server, resulting in a DELETE. Example use: r.json(uri,delete());

doGET

protected <T extends AbstractResource> T doGET(URI anUri,
                                               T resource)
                                        throws IOException

Throws:

IOException

dontSend

public void dontSend(String aHeader)

Don't send a header that was formely added in the alwaysSend method.

Parameters:

aHeader - the header to remove

doPOSTOrPUT

protected <T extends AbstractResource> T doPOSTOrPUT(URI anUri,
                                                     AbstractContent requestContent,
                                                     T resource)
                                              throws IOException

Throws:

IOException

fillResourceFromURL

protected <T extends AbstractResource> T fillResourceFromURL(URLConnection con,
                                                             T resource)
                                                      throws IOException

Get the content from the URLConnection, create a Resource representing the content and carry over some metadata like HTTP Result and location header. <T extends AbstractResource> the resource that will be created and filled.

Parameters:

con - the URLConnection used to get the data

resource - the resource class to instantiate

Returns:

the new resource

Throws:

IOException

form

public static MultipartContent form(FormData... formData)

Create form content to be sent as multipart/form-data. Useful if you want to upload files or have tons of form data that looks really ugly in a URL.

form

public static FormContent form(String query)

Create form content as application/x-www-form-urlencoded (i.e. a=b&c=d&...)

Parameters:

query - the preformatted, properly encoded form data

Returns:

a content object to be useable for upload

getAdditionalHeaders

protected Map<String,String> getAdditionalHeaders()

identifyAsMozilla

public Resty identifyAsMozilla()

Sets the User-Agent to identify as Mozilla/Firefox. Otherwise a Resty specific User-Agent is used

identifyAsResty

public Resty identifyAsResty()

Sets the User-Agent to Resty. WHICH IS THE DEFAULT. Sorry for yelling.

json

public JSONResource json(String string)
                  throws IOException

GET a URI given by string and parse the result as JSON.

Parameters:

string - - the string to use as URI

Throws:

IOException

See Also:

for more docs

json

public JSONResource json(String anUri,
                         AbstractContent content)
                  throws IOException

Throws:

IOException

See Also:

json(URI, AbstractContent)

json

public JSONResource json(URI anUri)
                  throws IOException

GET a URI and parse the result as JSON.

Parameters:

anUri - the URI to request

Returns:

the JSONObject, wrapped in a neat JSONResource

Throws:

IOException

json

public JSONResource json(URI anUri,
                         AbstractContent requestContent)
                  throws IOException

POST to a URI and parse the result as JSON

Parameters:

anUri - the URI to visit

requestContent - the content to POST to the URI

Returns:

Throws:

IOException - if uri is wrong or no connection could be made or for 10 zillion other reasons

openConnection

protected <T extends AbstractResource> URLConnection openConnection(URI anUri,
                                                                    T resource)
                                                             throws IOException,
                                                                    MalformedURLException

Throws:

IOException

MalformedURLException

path

public static JSONPathQuery path(String string)

Create a JSONPathQuery to extract data from a JSON object. This is usually used to extract a URI and use it in json|text|xml(JSONPathQuery...) methods of JSONResource. Resty r = new Resty(); r.json(someUrl).json(path("path.to.url.in.json"));

Parameters:

string -

Returns:

put

public static AbstractContent put(Content someContent)

Tell Resty to replace the specified content on the server, resulting in a PUT operation instead of a POST operation. Example use: r.json(uri, put(content("bubu")));

setOptions

public Resty setOptions(Resty.Option... someOptions)

Set options if you missed your opportunity in the c'tor or if you want to change the options.

Parameters:

someOptions - new set of options

Returns:

text

public TextResource text(String anUri)
                  throws IOException

Get a plain text resource for the specified URI.

Parameters:

anUri - the URI to follow

Returns:

a plain text resource, if available

Throws:

IOException - if content type sent is not a plain text, if the connection could not be made and gazillion other reasons

text

public TextResource text(String anUri,
                         AbstractContent content)
                  throws IOException

Get a plain text resource for the specified URI by POSTing to it.

Parameters:

anUri - the URI to follow

Returns:

a plain text resource, if available

Throws:

IOException - if content type sent is not a plain text, if the connection could not be made and gazillion other reasons

text

public TextResource text(URI anUri)
                  throws IOException

Get a plain text resource for the specified URI.

Parameters:

anUri - the URI to follow

Returns:

a plain text resource, if available

Throws:

IOException - if content type sent is not a plain text, if the connection could not be made and gazillion other reasons

text

public TextResource text(URI anUri,
                         AbstractContent content)
                  throws IOException

Get a plain text resource for the specified URI by POSTing to it.

Parameters:

anUri - the URI to follow

Returns:

a plain text resource, if available

Throws:

IOException - if content type sent is not a plain text, if the connection could not be made and gazillion other reasons

withHeader

public void withHeader(String aHeader,
                       String aValue)

Tell Resty to send the specified header with each request done on this instance. These headers will also be sent from any resource object returned by this instance. I.e. chained calls will carry over the headers r.json(url).json(get("some.path.to.a.url")); Multiple headers of the same type are not supported (yet).

Parameters:

aHeader - the header to send

aValue - the value