org.openestate.is24.restapi

Class AbstractClient

java.lang.Object

org.openestate.is24.restapi.AbstractClient

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

DefaultClient

public abstract class AbstractClient
extends Object
implements Closeable

A basic client for communication with the IS24-Webservice.

This is an abstract class, that implements the basic functions for communication with the IS24-Webservice.

Since:

0.1

Author:

Andreas Rudolph

Field Summary

Fields

Modifier and Type	Field and Description
static String	JSON_CONTENT_TYPE Content type for JSON requests.
static String	LIVE_API URL, that points to the webservice in live environment.
static String	RESPONSE_HEADER_API_CLIENT Name of the custom response header by IS24, that contains the Consumer Key of the client.
static String	RESPONSE_HEADER_CAUSER_ID Name of the custom response header by IS24, that contains the IS24 agent ID.
static String	RESPONSE_HEADER_REQUEST_REFNUM Name of the custom response header by IS24, that contains a unique ID of the request, that refers to this response.
static String	RESPONSE_HEADER_RESOURCE_ID Name of the custom response header by IS24, that contains the ID of the requested resource.
static String	SANDBOX_API URL, that points to the webservice in sandbox environment.
static String	XML_CONTENT_TYPE Content type for XML requests.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractClient(String apiBaseUrl, String consumerToken, String consumerSecret) Create an instance of AbstractClient.

Method Summary

Modifier and Type	Method and Description
void	authorize(Authorization authorization) Initializes client with access credentials.
void	authorize(String accessToken, String accessSecret) Initializes client with access credentials.
Authorization	authorizeAfterVerification(String verificationToken, String verificationSecret, String verificationCode) Initializes client after a successful verification.
Authorization	authorizeAfterVerification(Verification verification, String verificationCode) Initializes client after a successful verification.
protected oauth.signpost.OAuthConsumer	buildOAuthConsumer(String token, String secret) Create an OAuthConsumer object for access credentials.
protected oauth.signpost.OAuthProvider	buildOAuthProvider(String apiBaseUrl) Create an OAuthProvider for the IS24-Webservice.
void	close()
Verification	fetchVerification() Initiate a verification process.
Verification	fetchVerification(String callbackUrl) Initiate a verification process.
String	getApiBaseUrl() Return URL of the configured IS24-Webservice.
oauth.signpost.OAuthConsumer	getAuthConsumer() Return OAuthConsumer of the client for the current authorization.
oauth.signpost.OAuthProvider	getAuthProvider() Return OAuthProvider of the client for the current authorization.
static String	getEncoding() Return encoding for transferred data.
static String	getUrlEncodedValue(String value) Encode a string value for use in an URL according to RFC 3986.
protected abstract Response	sendJsonRequest(URL url, RequestMethod method, String json) Send a JSON string to the IS24-Webservice.
protected abstract Response	sendVideoUploadRequest(URI url, RequestMethod method, String auth, InputStream input, String fileName, long fileSize) Send a video with an authentication value to the IS24-Webservice.
protected abstract Response	sendXmlAttachmentRequest(URL url, RequestMethod method, String xml, InputStream input, String fileName, String mimeType) Send a XML string together with a file to the IS24-Webservice.
protected abstract Response	sendXmlRequest(URL url, RequestMethod method, String xml) Send a XML string to the IS24-Webservice.

Methods inherited from class java.lang.Object

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

Field Detail

LIVE_API

public static final String LIVE_API

URL, that points to the webservice in live environment.

See Also:

Constant Field Values

SANDBOX_API

public static final String SANDBOX_API

URL, that points to the webservice in sandbox environment.

See Also:

Constant Field Values

RESPONSE_HEADER_API_CLIENT

public static final String RESPONSE_HEADER_API_CLIENT

Name of the custom response header by IS24, that contains the Consumer Key of the client.

Since:

0.2.2

See Also:

Constant Field Values

RESPONSE_HEADER_CAUSER_ID

public static final String RESPONSE_HEADER_CAUSER_ID

Name of the custom response header by IS24, that contains the IS24 agent ID.

Since:

0.2.2

See Also:

Constant Field Values

RESPONSE_HEADER_REQUEST_REFNUM

public static final String RESPONSE_HEADER_REQUEST_REFNUM

Name of the custom response header by IS24, that contains a unique ID of the request, that refers to this response.

Since:

0.2.2

See Also:

Constant Field Values

RESPONSE_HEADER_RESOURCE_ID

public static final String RESPONSE_HEADER_RESOURCE_ID

Name of the custom response header by IS24, that contains the ID of the requested resource.

Since:

0.2.2

See Also:

Constant Field Values

XML_CONTENT_TYPE

public static final String XML_CONTENT_TYPE

Content type for XML requests.

Since:

0.3.3

See Also:

Constant Field Values

JSON_CONTENT_TYPE

public static final String JSON_CONTENT_TYPE

Content type for JSON requests.

Since:

0.3.3

See Also:

Constant Field Values

Constructor Detail

AbstractClient

protected AbstractClient(String apiBaseUrl,
                         String consumerToken,
                         String consumerSecret)

Create an instance of AbstractClient.

Parameters:

apiBaseUrl - base URL of the IS24-Webservice (see LIVE_API and SANDBOX_API)

consumerToken - consumer token, that identifies the application at the IS24-Webservice

consumerSecret - consumer secret, that identifies the application at the IS24-Webservice

Method Detail

authorize

public final void authorize(Authorization authorization)
                     throws oauth.signpost.exception.OAuthException

Initializes client with access credentials.

Parameters:

authorization - Authorization object, that contains the credentials for permanent access to the IS24-Webservice

Throws:

oauth.signpost.exception.OAuthException - if initialization of the authorization failed

authorize

public final void authorize(String accessToken,
                            String accessSecret)
                     throws oauth.signpost.exception.OAuthException

Initializes client with access credentials.

Parameters:

accessToken - token for permanent access to the IS24-Webservice

accessSecret - secret for permanent access to the IS24-Webservice

Throws:

oauth.signpost.exception.OAuthException - if initialization of the authorization failed

authorizeAfterVerification

public final Authorization authorizeAfterVerification(Verification verification,
                                                      String verificationCode)
                                               throws oauth.signpost.exception.OAuthException

Initializes client after a successful verification.

Parameters:

verification - Verification object, that contains the credentials for temporary access to the IS24-Webservice during verification

verificationCode - verification code, that was received after the verification was finished

Returns:

Authorization object, that contains the access credentials for future use

Throws:

oauth.signpost.exception.OAuthException - if initialization of the authorization failed

authorizeAfterVerification

public final Authorization authorizeAfterVerification(String verificationToken,
                                                      String verificationSecret,
                                                      String verificationCode)
                                               throws oauth.signpost.exception.OAuthException

Initializes client after a successful verification.

Parameters:

verificationToken - token for temporary access to the IS24-Webservice during verification

verificationSecret - secret for temporary access to the IS24-Webservice during verification

verificationCode - verification code, that was received after the verification was finished

Returns:

Authorization object, that contains the access credentials for future use

Throws:

oauth.signpost.exception.OAuthException - if initialization of the authorization failed

buildOAuthConsumer

protected oauth.signpost.OAuthConsumer buildOAuthConsumer(String token,
                                                          String secret)

Create an OAuthConsumer object for access credentials.

Different implementations of AbstractClient may create different OAuthConsumer objects.

Parameters:

token - access or verification token

secret - access or verification secret

Returns:

an instance of OAuthConsumer for the provided credentials

buildOAuthProvider

protected oauth.signpost.OAuthProvider buildOAuthProvider(String apiBaseUrl)

Create an OAuthProvider for the IS24-Webservice.

Different implementations of AbstractClient may create different OAuthProvider objects.

Parameters:

apiBaseUrl - URL of the IS24-Webservice

Returns:

an instance of OAuthProvider for the provided URL

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

fetchVerification

public final Verification fetchVerification()
                                     throws oauth.signpost.exception.OAuthException

Initiate a verification process.

Returns:

an instance of Verification that contains information about the initiated verification process

Throws:

oauth.signpost.exception.OAuthException - if initiation failed

fetchVerification

public final Verification fetchVerification(String callbackUrl)
                                     throws oauth.signpost.exception.OAuthException

Initiate a verification process.

Parameters:

callbackUrl - the URL, where the user is redirected to, after the verification was finished / cancelled

Returns:

an instance of Verification that contains information about the initiated verification process

Throws:

oauth.signpost.exception.OAuthException - if initiation failed

getApiBaseUrl

public final String getApiBaseUrl()

Return URL of the configured IS24-Webservice.

Returns:

URL of the configured IS24-Webservice

getAuthConsumer

public final oauth.signpost.OAuthConsumer getAuthConsumer()
                                                   throws oauth.signpost.exception.OAuthNotAuthorizedException

Return OAuthConsumer of the client for the current authorization.

Returns:

OAuthConsumer instance of the client

Throws:

oauth.signpost.exception.OAuthNotAuthorizedException - if the client is not authorized

getAuthProvider

public final oauth.signpost.OAuthProvider getAuthProvider()
                                                   throws oauth.signpost.exception.OAuthNotAuthorizedException

Return OAuthProvider of the client for the current authorization.

Returns:

OAuthProvider instance of the client

Throws:

oauth.signpost.exception.OAuthNotAuthorizedException - if the client is not authorized

getEncoding

public static String getEncoding()

Return encoding for transferred data.

This function always returns XmlUtils.DEFAULT_ENCODING.

Returns:

encoding for transferred data

getUrlEncodedValue

public static String getUrlEncodedValue(String value)

Encode a string value for use in an URL according to RFC 3986.

Parameters:

value - the value to encode

Returns:

the encoded value

sendJsonRequest

protected abstract Response sendJsonRequest(URL url,
                                            RequestMethod method,
                                            String json)
                                     throws IOException,
                                            oauth.signpost.exception.OAuthException

Send a JSON string to the IS24-Webservice.

This function must be implemented by specific implementations of AbstractClient.

Parameters:

url - URL of the IS24-Webservice, where the request is sent to

method - HTTP method of the outgoing request

json - JSON string, that is sent to the IS24-Webservice

Returns:

response, that was received from the IS24-Webservice

Throws:

IOException - if communication with IS24-Webservice failed

oauth.signpost.exception.OAuthException - if authorization failed

Since:

0.3.3

sendXmlRequest

protected abstract Response sendXmlRequest(URL url,
                                           RequestMethod method,
                                           String xml)
                                    throws IOException,
                                           oauth.signpost.exception.OAuthException

Send a XML string to the IS24-Webservice.

This function must be implemented by specific implementations of AbstractClient.

Parameters:

url - URL of the IS24-Webservice, where the request is sent to

method - HTTP method of the outgoing request

xml - XML string, that is sent to the IS24-Webservice

Returns:

response, that was received from the IS24-Webservice

Throws:

IOException - if communication with IS24-Webservice failed

oauth.signpost.exception.OAuthException - if authorization failed

sendXmlAttachmentRequest

protected abstract Response sendXmlAttachmentRequest(URL url,
                                                     RequestMethod method,
                                                     String xml,
                                                     InputStream input,
                                                     String fileName,
                                                     String mimeType)
                                              throws IOException,
                                                     oauth.signpost.exception.OAuthException

Send a XML string together with a file to the IS24-Webservice.

This function must be implemented by specific implementations of AbstractClient.

Parameters:

url - URL of the IS24-Webservice, where the request is sent to

method - the HTTP method of the outgoing request

xml - the XML string, that is sent to the IS24-Webservice

input - the file content, that is sent to the IS24-Webservice

fileName - the name of the file, that is sent to the IS24-Webservice

mimeType - the MIME-type of the file, that is sent to the IS24-Webservice

Returns:

the response, that was received from the IS24-Webservice

Throws:

IOException - if communication with IS24-Webservice failed

oauth.signpost.exception.OAuthException - if authorization failed

sendVideoUploadRequest

protected abstract Response sendVideoUploadRequest(URI url,
                                                   RequestMethod method,
                                                   String auth,
                                                   InputStream input,
                                                   String fileName,
                                                   long fileSize)
                                            throws IOException,
                                                   oauth.signpost.exception.OAuthException

Send a video with an authentication value to the IS24-Webservice.

This function must be implemented by specific implementations of AbstractClient.

Parameters:

url - URL of the IS24-Webservice, where the request is sent to

method - HTTP method of the outgoing request

auth - authentication value, that is sent to the IS24-Webservice

input - file content, that is sent to the IS24-Webservice

fileName - name of the file, that is sent to the IS24-Webservice

fileSize - size of the file, that is sent to the IS24-Webservice (in bytes)

Returns:

response, that was received from the IS24-Webservice

Throws:

IOException - if communication with IS24-Webservice failed

oauth.signpost.exception.OAuthException - if authorization failed