org.shredzone.flattr4j.connector
Interface Connection

All Known Implementing Classes:

FlattrConnection

public interface Connection

Builds and executes a single call against the Flattr API.

Since:

2.0

Author:

Richard "Shred" Körber

Method Summary

Connection	call(String call) Call to be placed against the URL.
Connection	data(FlattrObject data) Data to be transported to the call.
Connection	form(String name, String value) Form parameter to be sent.
Connection	key(ConsumerKey key) Consumer key to be used.
Connection	parameter(String name, String value) A parameter to be used for a placeholder in the call string.
Connection	query(String name, String value) Query parameter to be used in the URL.
Connection	rateLimit(RateLimit limit) RateLimit object to keep updated.
Collection<FlattrObject>	result() Invokes the call and returns a Collection of FlattrObject as response.
FlattrObject	singleResult() Invokes the call and returns a single FlattrObject as response.
Connection	token(AccessToken token) Access token to be used for calls that require authentication.
Connection	url(String url) Base URL to connect to.

Method Detail

url

Connection url(String url)

Base URL to connect to. This must be an absolute URL.

Parameters:

url - URL to connect to.

Returns:

this

token

Connection token(AccessToken token)

Access token to be used for calls that require authentication. If no AccessToken is set, the call will be placed anonymously.

Parameters:

token - AccessToken to be used

Returns:

this

key

Connection key(ConsumerKey key)

Consumer key to be used. Usually, this is only necessary in the OAuth2 authentication process.

Parameters:

key - ConsumerKey to be used

Returns:

this

call

Connection call(String call)

Call to be placed against the URL. The call string may contain placeholders that are prepended by a colon (e.g. "users/:username/things").

If no call is set, the url(String) is invoked unchanged.

Parameters:

call - Signature of the call to be invoked

Returns:

this

parameter

Connection parameter(String name,
                     String value)

A parameter to be used for a placeholder in the call string. If the call string does not contain a matching placeholder, it will be silently ignored.

Parameters:

name - Parameter name, without colon prepended

value - Value to be used.

Returns:

this

query

Connection query(String name,
                 String value)

Query parameter to be used in the URL.

Parameters:

name - Parameter name

value - Parameter value

Returns:

this

data

Connection data(FlattrObject data)

Data to be transported to the call. Requires RequestType.POST or RequestType.PATCH, otherwise an exception will be thrown.

Parameters:

data - Data to be sent

Returns:

this

form

Connection form(String name,
                String value)

Form parameter to be sent. Requires RequestType.POST, otherwise an exception will be thrown. Do not mix with data(FlattrObject).

Parameters:

name - Parameter name

value - Parameter value

Returns:

this

rateLimit

Connection rateLimit(RateLimit limit)

RateLimit object to keep updated.

Parameters:

limit - RateLimit object

Returns:

this

singleResult

FlattrObject singleResult()
                          throws FlattrException

Invokes the call and returns a single FlattrObject as response.

Returns:

result FlattrObject, never null

Throws:

FlattrException - if the call could not be invoked or the web service returned an error

MarshalException - if more or less than a single FlattrObject were returned

result

Collection<FlattrObject> result()
                                throws FlattrException

Invokes the call and returns a Collection of FlattrObject as response.

Returns:

result collection of FlattrObject, may be empty but never null

Throws:

FlattrException - if the call could not be invoked or the web service returned an error