org.cumulus4j.store.crypto.keymanager.messagebroker
Class AbstractMessageBroker

java.lang.Object
  org.cumulus4j.store.crypto.keymanager.messagebroker.AbstractMessageBroker

All Implemented Interfaces:

MessageBroker

Direct Known Subclasses:

MessageBrokerInMemory, MessageBrokerPMF

public abstract class AbstractMessageBroker
extends Object
implements MessageBroker

Abstract super-class to be subclassed by MessageBroker implementations. It is urgently recommended that MessageBroker implementations do not directly implement the MessageBroker interface, but instead subclass this abstract class.

Author:

Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de

Field Summary

Fields inherited from interface org.cumulus4j.store.crypto.keymanager.messagebroker.MessageBroker

SYSTEM_PROPERTY_POLL_REQUEST_TIMEOUT, SYSTEM_PROPERTY_QUERY_TIMEOUT

Constructor Summary

AbstractMessageBroker()

Method Summary

protected abstract Request	_pollRequest(String cryptoSessionIDPrefix) Delegate of the pollRequest(String) method.
protected abstract void	_pushResponse(Response response) Delegate of the pushResponse(Response) method.
protected abstract Response	_query(Class<? extends Response> responseClass, Request request) Delegate of the query(Class, Request) method.
long	getPollRequestTimeout() Get the pollRequest(....) timeout in milliseconds.
long	getQueryTimeout() Get the query timeout in milliseconds.
Request	pollRequest(String cryptoSessionIDPrefix) Poll the next Request that is waiting to be processed.
void	pushResponse(Response response) Push a Response in order to reply a previous request.
<R extends Response> R	query(Class<R> responseClass, Request request) Send request to the key-manager (embedded in client or separate in key-server) and return its response.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractMessageBroker

public AbstractMessageBroker()

Method Detail

getQueryTimeout

public long getQueryTimeout()

Description copied from interface: MessageBroker

Get the query timeout in milliseconds.

This method takes the system property MessageBroker.SYSTEM_PROPERTY_QUERY_TIMEOUT into account. If the system property is not present or not a valid number, the default value 300000 (5 minutes) is returned.

Specified by:

getQueryTimeout in interface MessageBroker

Returns:

the query timeout in milliseconds.

getPollRequestTimeout

public long getPollRequestTimeout()

Description copied from interface: MessageBroker

Get the pollRequest(....) timeout in milliseconds.

This method takes the system property MessageBroker.SYSTEM_PROPERTY_POLL_REQUEST_TIMEOUT into account. If the system property is not present or not a valid number, the default value 60000 (1 minute) is returned.

Usually, a value of about 1 minute is recommended in most situations. However, when using certain runtimes, it must be much shorter (e.g. the Google App Engine allows requests not to take longer than 30 sec, thus 20 sec are an appropriate time to stay safe).

Additionally, since the remote key-manager must wait at maximum this time, its HTTP-client's timeout must be longer than this timeout.

Specified by:

getPollRequestTimeout in interface MessageBroker

Returns:

the pollRequest(....) timeout in milliseconds.

query

public final <R extends Response> R query(Class<R> responseClass,
                                          Request request)
                               throws TimeoutException,
                                      ErrorResponseException

Description copied from interface: MessageBroker

Send request to the key-manager (embedded in client or separate in key-server) and return its response.

This method is used for example by a CryptoSession to request keys via a GetKeyRequest. As soon as this method entered with the request, it is expected that the MessageBroker.pollRequest(String) returns this request to the appropriate key-manager. The query(...) method blocks then until the key-manager handled the request and sent a GetKeyResponse back. As soon as the response was pushed into the MessageBroker, query(...) should return it.

If the expected Response does not arrive within the query-timeout (configurable via system property "cumulus4j.MessageBroker.queryTimeout"), this method should throw a TimeoutException.

Specified by:

query in interface MessageBroker

Parameters:

responseClass - the type of the expected response; can be null, if you expect to receive null (i.e. you pass a "void" request).

request - the request to be sent to the key-manager.

Returns:

the response from the key-manager. Will be null, if the key-manager replied with a NullResponse.

Throws:

TimeoutException - if the request was not replied within the query-timeout.

ErrorResponseException - if the key-manager (either running embedded on the remote client or in a separate key-server) sent an ErrorResponse.

_query

protected abstract Response _query(Class<? extends Response> responseClass,
                                   Request request)
                            throws TimeoutException,
                                   ErrorResponseException

Delegate of the query(Class, Request) method. Subclasses should implement this method instead of query(...).

Parameters:

responseClass - the type of the expected response; can be null, if you expect to receive null (i.e. you pass a "void" request).

request - the request to be sent to the key-manager.

Returns:

the response from the key-manager. Will be null, if the key-manager replied with a NullResponse.

Throws:

TimeoutException - if the request was not replied within the query-timeout.

ErrorResponseException - if the key-manager (either running embedded on the remote client or in a separate key-server) sent an ErrorResponse.

pollRequest

public final Request pollRequest(String cryptoSessionIDPrefix)

Description copied from interface: MessageBroker

Poll the next Request that is waiting to be processed.

This method is - indirectly via a REST web-service - called by the key-manager periodically in order to receive requests. If there is a request waiting, this method should immediately return it. If there is no request in the queue, this method should wait for an incoming request for a short time. If there is still no request available after a short blocking time, this method should return null (before the remote client would timeout).

Usually, blocking about 1 minute is recommended in most situations. However, when using certain runtimes, it must be much shorter (e.g. the Google App Engine allows requests not to take longer than 30 sec, thus 20 sec are an appropriate time to stay safe).

Additionally, since the remote key-manager must wait at maximum this time, its HTTP-client's timeout must be longer than this timeout.

It should be possible to configure this timeout via the system property "cumulus4j.MessageBroker.pollRequestTimeout". Implementors should use MessageBroker.getPollRequestTimeout() for this purpose.

Specified by:

pollRequest in interface MessageBroker

Parameters:

cryptoSessionIDPrefix - usually, every key-manager uses the same prefix for all crypto-sessions. Thus, this prefix is used to efficiently route requests to the right key-manager.

Returns:

the next request waiting for processing and fitting to the given cryptoSessionIDPrefix or null, if no such request pops up in the to-do-queue within the timeout.

_pollRequest

protected abstract Request _pollRequest(String cryptoSessionIDPrefix)

Delegate of the pollRequest(String) method. Subclasses should implement this method instead of pollRequest(...).

Parameters:

cryptoSessionIDPrefix - usually, every key-manager uses the same prefix for all crypto-sessions. Thus, this prefix is used to efficiently route requests to the right key-manager.

Returns:

the next request waiting for processing and fitting to the given cryptoSessionIDPrefix or null, if no such request pops up in the to-do-queue within the timeout.

pushResponse

public final void pushResponse(Response response)

Description copied from interface: MessageBroker

Push a Response in order to reply a previous request.

This method is - indirectly via a REST web-service - called by the key-manager after it successfully handled a Request.

Specified by:

pushResponse in interface MessageBroker

Parameters:

response - the response answering a previous Request enqueued by MessageBroker.query(Class, Request).

_pushResponse

protected abstract void _pushResponse(Response response)

Delegate of the pushResponse(Response) method. Subclasses should implement this method instead of pushResponse(...).

Parameters:

response - the response answering a previous Request enqueued by query(Class, Request).