org.cumulus4j.store.crypto.keymanager.messagebroker
Interface MessageBroker

All Known Implementing Classes:

AbstractMessageBroker, LocalKeyStoreMessageBroker, MessageBrokerInMemory, MessageBrokerPMF

public interface MessageBroker

Broker transmitting messages between application-server and key-manager.

As documented in Deployment scenarios, TCP connections are always established from the key-manager (i.e. client or key-server) to the application server. Since this means that the key-exchange-request-response-cycle works opposite the HTTP-request-response-cycle, we need this MessageBroker.

Within every JVM, there is one single active MessageBroker. This instance must make sure that messages can be exchanged from every cluster-node to every key-manager; i.e. if the key-manager connects to a different cluster-node than the primary connection (established by the application logic), the Requests must be proxied over the right cluster-node to the key-manager. The Response must of course be routed appropriately back to the correct cluster-node:

Important: You should not directly implement this interface but instead subclass AbstractMessageBroker!

Author:

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

Field Summary

static String	SYSTEM_PROPERTY_POLL_REQUEST_TIMEOUT System property to control the timeout (in milliseconds) for the pollRequest(String) method.
static String	SYSTEM_PROPERTY_QUERY_TIMEOUT System property to control the timeout (in milliseconds) for the query(Class, Request) method.

Method Summary

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.

Field Detail

SYSTEM_PROPERTY_QUERY_TIMEOUT

static final String SYSTEM_PROPERTY_QUERY_TIMEOUT

System property to control the timeout (in milliseconds) for the query(Class, Request) method.

The query(...) method will throw a TimeoutException, if no Response to a given Request arrived within this timeout.

If the system property is not present or not a valid number, it is up to the MessageBroker implementation, what default value should be used. See AbstractMessageBroker.getQueryTimeout() for the default implemented there.

See Also:

Constant Field Values

SYSTEM_PROPERTY_POLL_REQUEST_TIMEOUT

static final String SYSTEM_PROPERTY_POLL_REQUEST_TIMEOUT

System property to control the timeout (in milliseconds) for the pollRequest(String) method.

The pollRequest(...) method returns null, if no Request popped up in the to-do-queue within the timeout.

If the system property is not present or not a valid number, it is up to the MessageBroker implementation, what default value should be used. See AbstractMessageBroker.getPollRequestTimeout() for the default implemented there.

See Also:

Constant Field Values

Method Detail

query

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

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 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.

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

Request pollRequest(String cryptoSessionIDPrefix)

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 getPollRequestTimeout() for this purpose.

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

void pushResponse(Response response)

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.

Parameters:

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

getPollRequestTimeout

long getPollRequestTimeout()

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

This method takes the system property 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.

Returns:

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

getQueryTimeout

long getQueryTimeout()

Get the query timeout in milliseconds.

This method takes the system property 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.

Returns:

the query timeout in milliseconds.