org.ws4d.java.communication
Interface IncomingMessageListener

All Known Implementing Classes:

DefaultIncomingMessageListener

public interface IncomingMessageListener

Used to register interest for incoming (request) messages of a certain type. When a desired message is received, it is delivered to the matching handle method, e.g. handle(GetMessage, ProtocolData) for a GetMessage.

Method Summary

OperationDescription	getOperation(java.lang.String action) Returns an operation for a given wsa:Action.
void	handle(ByeMessage bye, ProtocolData protocolData) Receives an incoming bye message.
GetResponseMessage	handle(GetMessage get, ProtocolData protocolData) Receives an incoming get message.
GetMetadataResponseMessage	handle(GetMetadataMessage getMetadata, ProtocolData protocolData) Receives an incoming get metadata message.
GetStatusResponseMessage	handle(GetStatusMessage getStatus, ProtocolData protocolData) Receives an incoming get-status message (WS-Eventing).
void	handle(HelloMessage hello, ProtocolData protocolData) Receives an incoming hello message.
InvokeMessage	handle(InvokeMessage invokeRequest, ProtocolData protocolData) Receives an incoming invoke request.
ProbeMatchesMessage	handle(ProbeMessage probe, ProtocolData protocolData) Receives an incoming probe message.
RenewResponseMessage	handle(RenewMessage renew, ProtocolData protocolData) Receives an incoming renew message (WS-Eventing).
ResolveMatchesMessage	handle(ResolveMessage resolve, ProtocolData protocolData) Receives a resolve message.
SubscribeResponseMessage	handle(SubscribeMessage subscribe, ProtocolData protocolData) Receives an incoming subscribe message.
void	handle(SubscriptionEndMessage subscriptionEnd, ProtocolData protocolData) Receives an incoming subscription end message (WS-Eventing).
UnsubscribeResponseMessage	handle(UnsubscribeMessage unsubscribe, ProtocolData protocolData) Receives an incoming unsubscribe message (WS-Eventing).

Method Detail

handle

void handle(HelloMessage hello,
            ProtocolData protocolData)

Receives an incoming hello message.

Parameters:

hello - the message

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Throws:

OldAppSequenceException - in case hello has an older app sequence as expected

handle

void handle(ByeMessage bye,
            ProtocolData protocolData)

Receives an incoming bye message.

Parameters:

bye - the message

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Throws:

OldAppSequenceException - in case bye has an older app sequence as expected

handle

ProbeMatchesMessage handle(ProbeMessage probe,
                           ProtocolData protocolData)
                           throws SOAPException

Receives an incoming probe message. The returned value depends on the content and type (multicast vs. directed) of the probe. For a multicast probe that matches, a corresponding non-empty ProbeMatchesMessage must be returned. Otherwise, if the multicast probe doesn't match, this method must return null. If the received probe is directed, then this method must always return a ProbeMatchesMessage which, in the case of a match, must be not empty.

When the incoming probe message is a directed one and for some reason this method fails (e.g. this implementation doesn't support handling of probe messages, unexpected probe content, etc.), a SOAPException describing the failure reason must be thrown. It will then be forwarded to the original sender of the probe.

Parameters:

probe - the probe message to respond to

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

null or either an empty or a proper probe matches message, depending on the type and content of the received probe message

Throws:

SOAPException - this exception may be raised only if a directed probe was received and its processing caused a failure

handle

ResolveMatchesMessage handle(ResolveMessage resolve,
                             ProtocolData protocolData)

Receives a resolve message. If the incoming resolve matches, a corresponding (non-empty) ResolveMatchesMessage must be returned. Otherwise, this method must return null.

Parameters:

resolve - the resolve message to respond to

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

null in case the incoming resolve doesn't match, otherwise return the corresponding message

handle

GetResponseMessage handle(GetMessage get,
                          ProtocolData protocolData)
                          throws SOAPException

Receives an incoming get message. Must return a valid GetResponseMessage if processing the get request succeeded. Must throw a SOAPException describing the failure otherwise.

Parameters:

get - the incoming get request

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

the response to the incoming get request

Throws:

SOAPException - only if processing the get request failed for some reason (e.g. when the receiving instance is not capable of processing get requests, the request message is malformed, etc.)

handle

GetMetadataResponseMessage handle(GetMetadataMessage getMetadata,
                                  ProtocolData protocolData)
                                  throws SOAPException

Receives an incoming get metadata message. Must return a valid GetMetadataResponseMessage if processing the get metadata request succeeded. Must throw a SOAPException describing the failure otherwise.

Parameters:

getMetadata - the incoming request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

the response to the issued getMetadata request

Throws:

SOAPException - if processing the incoming metadata request fails, e.g. because this instance can not handle get metadata messages or the request includes unexpected content, etc.

handle

SubscribeResponseMessage handle(SubscribeMessage subscribe,
                                ProtocolData protocolData)
                                throws SOAPException

Receives an incoming subscribe message. Returns a suitable SubscribeResponseMessage or throws a SOAPException if processing the incoming request fails for any reason.

Parameters:

subscribe - the incoming subscribe request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

a valid response to the incoming subscribe request

Throws:

SOAPException - if processing the subscribe request fails for any reason, e.g. when this endpoint can not handle subscribe requests, or the request's content is malformed, etc.

handle

GetStatusResponseMessage handle(GetStatusMessage getStatus,
                                ProtocolData protocolData)
                                throws SOAPException

Receives an incoming get-status message (WS-Eventing). Returns a suitable GetStatusResponseMessage or throws a SOAPException if processing the incoming request fails for some reason.

Parameters:

getStatus - the incoming get-status request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

a valid response to the incoming get-status request

Throws:

SOAPException - if processing the get-status request fails for some reason, e.g. when this endpoint cannot handle get-status requests, or the request's content is malformed, etc.

handle

RenewResponseMessage handle(RenewMessage renew,
                            ProtocolData protocolData)
                            throws SOAPException

Receives an incoming renew message (WS-Eventing). Returns a suitable RenewResponseMessage or throws a SOAPException if processing the incoming request fails for any reason.

Parameters:

renew - the incoming renew request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

a valid response to the incoming renew request

Throws:

SOAPException - if processing the renew request fails for some reason, e.g. when this endpoint cannot handle renew requests, or the request's content is malformed, etc.

handle

UnsubscribeResponseMessage handle(UnsubscribeMessage unsubscribe,
                                  ProtocolData protocolData)
                                  throws SOAPException

Receives an incoming unsubscribe message (WS-Eventing). Returns a suitable UnsubscribeResponseMessage or throws a SOAPException if processing the incoming request fails for any reason.

Parameters:

unsubscribe - the incoming unsubscribe request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

a valid response to the incoming unsubscribe request

Throws:

SOAPException - if processing the unsubscribe request fails for some reason, e.g. when this endpoint can not handle unsubscribe requests, or the request's content is malformed, etc.

handle

void handle(SubscriptionEndMessage subscriptionEnd,
            ProtocolData protocolData)

Receives an incoming subscription end message (WS-Eventing).

NOTE: As this type of message is a simple one-way notification, this method neither has a return value, nor is declared to throw a SOAPException in case of a failure. That is, errors occurring during processing of this message must be silently ignored (this includes the case when this IncomingMessageListener instance doesn't process subscription end messages at all).

Parameters:

subscriptionEnd - the incoming subscription end message

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

handle

InvokeMessage handle(InvokeMessage invokeRequest,
                     ProtocolData protocolData)
                     throws SOAPException

Receives an incoming invoke request. The returned value depends on the type of the web service operation the request belongs to (one-way vs. request-response). For a one-way operation, this method must return null, whereas for a request-response operation, the returned InvokeMessage must contain a suitable response to the incoming request.

This method may throw a SOAPException under two distinct circumstances:

• the web service operation to which the incoming request belongs declares one or more faults: in such a case, the thrown SOAPException is expected to correspond to either one of those declared faults
• processing the invoke request fails for any other reason, e.g. malformed content or this IncomingMessageListener instance being unable to handle invoke requests: then, the SOAPException must describe the exact failure reason in a way independent from the actual declaration of the involved web service operation

Parameters:

invokeRequest - the incoming invoke request to process

protocolData - protocol (aka. technology) specific data associated with the incoming message, e.g. source and target addresses or other transport-related information

Returns:

either null for a one-way operation, or a response to the incoming request

Throws:

SOAPException - either because processing the invoke request failed with an user-defined failure reason (i.e. a fault declared by the concerned web service operation) or because of a more generic error such as this instance being unable to process incoming invoke requests, or malformed request content, etc.

getOperation

OperationDescription getOperation(java.lang.String action)

Returns an operation for a given wsa:Action.

Important

The result can be null for an implementation which does not use an operation at all.

Parameters:

action - the wsa:Action which should be used to retrieve the operation.

Returns:

the operation.