|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 Request
s 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
!
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. |
|
|
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 |
---|
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.
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.
Method Detail |
---|
<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
.
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.
null
, if the key-manager replied with a NullResponse
.
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
.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.
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.
cryptoSessionIDPrefix
or null
, if no such request pops up in the to-do-queue within the timeout.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
.
response
- the response answering a previous Request
enqueued by query(Class, Request)
.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.
pollRequest(....)
timeout in milliseconds.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.
query
timeout in milliseconds.
|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |