public class Resty
extends java.lang.Object
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.Modifier and Type | Class and Description |
---|---|
static class |
Resty.Option
Base class for Resty options.
|
static class |
Resty.Timeout
Option to set a timeout.
|
Modifier and Type | Field and Description |
---|---|
protected static java.lang.String |
DEFAULT_USER_AGENT |
protected static java.lang.String |
MOZILLA |
protected java.lang.String |
userAgent |
Constructor and Description |
---|
Resty(Resty.Option... someOptions)
Create an instance of Resty with the following list of options.
|
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> |
addStandardHeaders(URLConnection con,
T resource)
Add all standard headers (User-Agent, Accept) to the URLConnection.
|
void |
alwaysSend(java.lang.String aHeader,
java.lang.String aValue)
Deprecated.
|
BinaryResource |
bytes(java.lang.String anUri)
Get the resource specified by the uri and return a binary resource for
it.
|
BinaryResource |
bytes(java.lang.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(java.lang.String mime,
java.io.InputStream stream)
Create chunked data
|
static ChunkedContent |
chunked(java.lang.String mime,
java.io.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(java.lang.String somePlainText)
Create a content object from plain text.
|
protected BinaryResource |
createBinaryResource() |
protected JSONResource |
createJSONResource() |
protected TextResource |
createTextResource() |
static FormData |
data(java.lang.String name,
AbstractContent content)
Create a form data entry for a multipart form with any kind of content
type.
|
static FormData |
data(java.lang.String name,
java.lang.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> |
doGET(URI anUri,
T resource) |
void |
dontSend(java.lang.String aHeader)
Don't send a header that was formely added in the alwaysSend method.
|
protected <T extends AbstractResource> |
doPOSTOrPUT(URI anUri,
AbstractContent requestContent,
T resource) |
protected <T extends AbstractResource> |
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(java.lang.String query)
Create form content as application/x-www-form-urlencoded (i.e.
|
protected java.util.Map<java.lang.String,java.lang.String> |
getAdditionalHeaders() |
Resty |
identifyAsMozilla()
Sets the User-Agent to identify as Mozilla/Firefox.
|
Resty |
identifyAsResty()
Sets the User-Agent to Resty.
|
JSONResource |
json(java.lang.String string)
GET a URI given by string and parse the result as JSON.
|
JSONResource |
json(java.lang.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> |
openConnection(URI anUri,
T resource) |
static JSONPathQuery |
path(java.lang.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(java.lang.String anUri)
Get a plain text resource for the specified URI.
|
TextResource |
text(java.lang.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(java.lang.String aHeader,
java.lang.String aValue)
Tell Resty to send the specified header with each request done on this
instance.
|
protected static java.lang.String MOZILLA
protected static java.lang.String DEFAULT_USER_AGENT
protected java.lang.String userAgent
public Resty(Resty.Option... someOptions)
setOptions(Option...)
to change
options afterwards.public Resty setOptions(Resty.Option... someOptions)
someOptions
- new set of optionspublic Resty identifyAsMozilla()
public Resty identifyAsResty()
public JSONResource json(java.lang.String string) throws java.io.IOException
string
- - the string to use as URIjava.io.IOException
for more docs
public JSONResource json(URI anUri) throws java.io.IOException
anUri
- the URI to requestjava.io.IOException
protected JSONResource createJSONResource()
public JSONResource json(URI anUri, AbstractContent requestContent) throws java.io.IOException
anUri
- the URI to visitrequestContent
- the content to POST to the URIjava.io.IOException
- if uri is wrong or no connection could be made or for 10
zillion other reasonspublic JSONResource json(java.lang.String anUri, AbstractContent content) throws java.io.IOException
java.io.IOException
json(URI, AbstractContent)
public TextResource text(URI anUri) throws java.io.IOException
anUri
- the URI to followjava.io.IOException
- if content type sent is not a plain text, if the connection
could not be made and gazillion other reasonsprotected TextResource createTextResource()
public TextResource text(URI anUri, AbstractContent content) throws java.io.IOException
anUri
- the URI to followjava.io.IOException
- if content type sent is not a plain text, if the connection
could not be made and gazillion other reasonspublic TextResource text(java.lang.String anUri) throws java.io.IOException
anUri
- the URI to followjava.io.IOException
- if content type sent is not a plain text, if the connection
could not be made and gazillion other reasonspublic TextResource text(java.lang.String anUri, AbstractContent content) throws java.io.IOException
anUri
- the URI to followjava.io.IOException
- if content type sent is not a plain text, if the connection
could not be made and gazillion other reasonspublic BinaryResource bytes(java.lang.String anUri) throws java.io.IOException
anUri
- the uri to followjava.io.IOException
public BinaryResource bytes(URI anUri) throws java.io.IOException
anUri
- the uri to followjava.io.IOException
protected BinaryResource createBinaryResource()
public BinaryResource bytes(java.lang.String anUri, AbstractContent someContent) throws java.io.IOException
anUri
- the uri to followjava.io.IOException
public BinaryResource bytes(URI anUri, AbstractContent someContent) throws java.io.IOException
anUri
- the uri to followjava.io.IOException
protected <T extends AbstractResource> T doGET(URI anUri, T resource) throws java.io.IOException
java.io.IOException
protected <T extends AbstractResource> T doPOSTOrPUT(URI anUri, AbstractContent requestContent, T resource) throws java.io.IOException
java.io.IOException
protected <T extends AbstractResource> URLConnection openConnection(URI anUri, T resource) throws java.io.IOException, MalformedURLException
java.io.IOException
MalformedURLException
protected void addAdditionalHeaders(URLConnection con)
protected <T extends AbstractResource> void addStandardHeaders(URLConnection con, T resource)
protected <T extends AbstractResource> T fillResourceFromURL(URLConnection con, T resource) throws java.io.IOException
<T extends AbstractResource>
the resource that
will be created and filled.con
- the URLConnection used to get the dataresource
- the resource class to instantiatejava.io.IOException
public static JSONPathQuery path(java.lang.String string)
Resty r = new Resty();
r.json(someUrl).json(path("path.to.url.in.json"));
string
- public static Content content(JSONObject someJson)
someJson
- the JSON object to usepublic static Content content(JSONArray someJson)
someJson
- the JSON array to usepublic static Content content(java.lang.String somePlainText)
somePlainText
- the plain text to sendpublic static Content content(byte[] bytes)
bytes
- the bytes to sendpublic static FormContent form(java.lang.String query)
query
- the preformatted, properly encoded form datapublic static MultipartContent form(FormData... formData)
public static FormData data(java.lang.String name, java.lang.String plainTextValue)
name
- the name of the control of the formplainTextValue
- the plain text valuepublic static FormData data(java.lang.String name, AbstractContent content)
name
- the name of the control or variable in a formcontent
- the content to sendpublic static ChunkedContent chunked(java.lang.String mime, java.io.InputStream stream)
mime
- mime typestream
- stream to read content frompublic static ChunkedContent chunked(java.lang.String mime, java.io.InputStream stream, int chunkSize)
mime
- the mimestream
- the streamchunkSize
- the chunk size used to configure HttpURLConnection
streaming modepublic static AbstractContent put(Content someContent)
public static AbstractContent delete()
@Deprecated public void alwaysSend(java.lang.String aHeader, java.lang.String aValue)
aHeader
- the header to sendaValue
- the valuepublic void withHeader(java.lang.String aHeader, java.lang.String aValue)
aHeader
- the header to sendaValue
- the valuepublic void dontSend(java.lang.String aHeader)
aHeader
- the header to removeprotected java.util.Map<java.lang.String,java.lang.String> getAdditionalHeaders()