Package com.opencloud.slee.resources.mm7

Provides an interface between the Rhino MM7 Resource Adaptors and SBBs implementing MM7 services within Rhino.

See:
Description

Interface Summary

CancelActivity	Activity representing a MM7 transaction that involves a Cancel Request/Response pair.
CancelRequest	Represents an incoming Cancel Request from the peer VASP.
CancelRequestEvent	Event delivered for an incoming Cancel Request transaction from the peer VASP.
CancelResponse	Marker interface that identifies Cancel Response messages from the peer Relay Server.
CancelResponseEvent	Event delivered when a Cancel Response from the peer Relay Server is received.
DeliverActivity	Activity representing a MM7 transaction that involves a Deliver Request/Response pair.
DeliverRequest	Represents an incoming Deliver Request from the peer RS.
DeliverRequestEvent	Event delivered for an incoming Deliver Request transaction from the peer RS.
DeliverResponse	Represents a Deliver Response message from the peer VASP.
DeliverResponseEvent	Event delivered when a Cancel Response from the peer VASP is received.
DeliveryReportActivity	Activity representing a MM7 transaction that involves a Delivery Report Request/Response pair.
DeliveryReportRequest	Represents an incoming Cancel Request from the peer VASP.
DeliveryReportRequestEvent	Event delivered for an incoming Delivery Report Request transaction from the peer RS.
DeliveryReportResponse	Marker interface identifying Delivery Report Response messages from the peer VASP.
DeliveryReportResponseEvent	Event delivered when a Delivery Report Response from the peer VASP is received.
ErrorResponse	Marker interface for generic error responses.
ExtendedCancelActivity	Activity representing a MM7 transaction that involves a Extended Cancel Request/Response pair.
ExtendedCancelRequest	Represents an incoming Extended Cancel Request from the peer VASP.
ExtendedCancelRequestEvent	Event delivered for an incoming Extended Cancel Request transaction from the peer VASP.
ExtendedCancelResponse	Marker interface that identifies Extended Cancel Response messages from the peer Relay Server.
ExtendedCancelResponseEvent	Event delivered when a Extended Cancel Response from the peer Relay Server is received.
ExtendedReplaceActivity	Activity representing a MM7 transaction that involves a Extended Replace Request/Response pair.
ExtendedReplaceRequest	Represents an incoming Extended Replace Request from the peer VASP.
ExtendedReplaceRequestEvent	Event delivered for an incoming Extended Replace Request transaction from the peer VASP.
ExtendedReplaceResponse	Marker interface identifying Replace Response messages from the peer Relay Server.
ExtendedReplaceResponseEvent	Event delivered when a Extended Replace Response from the peer Relay Server is received.
MM7Activity	Superinterface of all MM7 activity objects.
MM7ActivityContextInterfaceFactory	Provides methods to convert MM7 Activity objects to SLEE ActivityContextInterface objects.
MM7Provider	Superinterface for MM7 provider interfaces.
ReadReplyReportActivity	Activity representing a MM7 transaction that involves a Read Reply Report Request/Response pair.
ReadReplyReportRequest	Represents an incoming Read Reply Report Request from the peer VASP.
ReadReplyReportRequestEvent	Event delivered for an incoming Cancel Request transaction from the peer RS.
ReadReplyReportResponse	Marker interface identifying Read Reply Report Response messages from the peer VASP.
ReadReplyReportResponseEvent	Event delivered when a Read Reply Report Response from the peer VASP is received.
ReplaceActivity	Activity representing a MM7 transaction that involves a Replace Request/Response pair.
ReplaceRequest	Represents an incoming Replace Request from the peer VASP.
ReplaceRequestEvent	Event delivered for an incoming Replace Request transaction from the peer VASP.
ReplaceResponse	Marker interface identifying Replace Response messages from the peer Relay Server.
ReplaceResponseEvent	Event delivered when a Replace Response from the peer Relay Server is received.
Request	Superinterface for all request representations.
RequestEvent	Superinterface for all Request Events.
Response	Superinterface for all MM7 response messages.
ResponseEvent	Superinterface for all events fired in response to a SBB-initiated request.
RSErrorResponse	Marker interface for error responses from a Relay Server.
RSProvider	Provides the SBB interface for a MM7 RA acting as a MMS Relay Server.
RSRequest	Superinterface of all Request interfaces representing requests sent by a MMS Relay Server.
SOAPFault	Representation of a simple SOAP-level fault.
SubmitActivity	Activity representing a MM7 transaction that involves a Submit Request/Response pair.
SubmitRequest	Represents an incoming Submit Request from the peer VASP.
SubmitRequestEvent	Event delivered for an incoming Submit Request transaction from the peer VASP.
SubmitResponse	Represents a Submit Response message from the peer Relay Server.
SubmitResponseEvent	Event delivered when a Cancel Response from the peer Relay Server is received.
VASPErrorResponse	Marker interface for error responses from a VASP.
VASPProvider	Provides the SBB interface for a MM7 RA acting as a MMS VASP.
VASPRequest	Superinterface for all interfaces representing requests sent by a VASP.

Class Summary

CancelRequestParameters	Container for all optional parameters related to a Cancel Request.
DeliverRequestParameters	Container for all optional parameters related to a Deliver Request.
DeliveryReportRequestParameters	Container for all optional parameters related to a Delivery Report Request.
ExtendedReplaceRequestParameters	Container for all optional parameters related to a Replace Request.
MM7Address	Represents MM7 addresses.
MM7Duration	Mapping of the XML Schema "duration" type, as used in MM7.
MM7RelativeOrAbsoluteDate	Mapping of the MM7 relativeOrAbsoluteDateType type, which is a union of dateTime and duration.
MM7StatusCode	Represents a MM7 Status Code.
ReadReplyReportRequestParameters	Container for all optional parameters related to a Read Reply Report Request.
Recipient	Specialization of MM7Address that adds a recipient type.
ReplaceRequestParameters	Container for all optional parameters related to a Replace Request.
SenderID	Representation of the VASP Sender Identification.
SubmitRequestParameters	Container for all optional parameters related to a Submit Request.
UACapabilities	Mapping of the MM7 UACapabilities type, which is used for transferring user agent capabilities from R/S to VASP.
UserAgentInfo	Represents User Agent Info.
UserAgentRelativeOrAbsoluteDate	Mapping of the MM7 previouslySentByDateTime type, which is a union of dateTime and duration with sequence number.

Enum Summary

ContentClass	Represents a MM7 Content Class.
DeliveryReportRequest.MMDeliveryStatus	Enum for Delivery Report mmStatus codes
MM7Address.AddressCoding	Typesafe enum for Address Coding
MMStatusExtension	Enum for MM Status Extension values.
Priority	Enum for MM7 Priority values.
ReadReplyReportRequest.MMReadStatus	Enum for Read Reply Report mmStatus codes
Recipient.Type	Enum of recipient types.
SubmitRequest.ChargedParty	Enum for Submit 'charged party' values.
SubmitRequest.MessageClass	Enum for Submit message classes.

Exception Summary

ValidationException

Exception thrown by all methods that send a MM7 message (request or response) when the message is not a valid MM7 message.

Package com.opencloud.slee.resources.mm7 Description

Provides an interface between the Rhino MM7 Resource Adaptors and SBBs implementing MM7 services within Rhino.

What do I need to know first?

This document assumes familiarity with MMS and the MM7 protocol, and how it is mapped to SOAP and HTTP in general terms. It also assumes familiarity with the JAIN SLEE resource adaptor / service / SBB model.

Resource Adaptor Types

Two MM7 resource adaptors are provided for Rhino. One (the VASP RA) acts as a MMS VASP, communicating with MMS Relay Server peers. The second (the Relay Server RA) acts in the corresponding role as a Relay Server, communicating with VASP peers. The two resource adaptors share classes and interfaces in this package, with the differences appearing as:

• the actual event types injected by the RA into the SLEE
• the type of provider interface available for use by SBBs

In both cases, SBBs receive events corresponding to incoming requests, and may send new requests to a peer and receive response events in return.

Handling Incoming Requests

When a new incoming request is received by the resource adaptor's I/O layer, the contained MM7 message is parsed and validated. Invalid requests (badly formed or invalid for the role the RA is playing) are rejected immediately with an appropriate error code, without SBB intervention. The remaining requests are passed to the SLEE for processing by installed SBBs.

Each request results in the creation of an activity, represented by an appropriate subinterface of MM7Activity depending on the exact request type. A single event that is an appropriate subclass of RequestEvent is fired on that activity for processing by SBBs.

The Resource Adaptor expects at least one SBB to receive the event. If no SBBs receive the event, an error response will be immediately sent to the requesting client and the activity ended.

If at least one SBB receives the event, the resource adaptor expects one of them to eventually generate a response to the request. Responses are sent via type-specific methods on the MM7Activity subinterface the event was fired on for success response, or via MM7Activity.sendErrorResponse() for error responses.

The activity remains active until a response is sent, or the Resource Adaptor's timeout is exceeded without a response being sent. In the case of a timeout, the Resource Adaptor assumes that a SBB has failed or is misconfigured, and will generate a timeout error to the requesting client.

Attempts to send an additional response after a response has been sent, or to send a response after the timeout has gone off, will result in an exception being thrown to the SLEE.

Making Outgoing Requests

The Resource Adaptor provides an implementation of either RSProvider or VASPProvider, depending on role, and makes it available to SBBs through JNDI. SBBs may use this interface to send new outgoing requests to any peer. The address of the peer is specified using a java.net.URL parameter, in the form http://host:port/path. At this time the only supported protocol is HTTP.

Sending a request via the provider interface creates and returns a new activity object corresponding to the type of request sent. In all cases where a new activity is returned (that is, at all times excluding cases where an exception was thrown when sending the request), an appropriate event subclass of ResponseEvent will eventually be fired on the newly created activity. The Resource Adaptor manages connection errors and request timeouts automatically; they are visible to the requesting SBB as appropriate SOAP- or MM7- level error response events.

Each response event carries at least one of a SOAP-level fault and a response object. Four scenarios are possible:

1. Success response. The request was sent to the peer which responded with a success (1xxx) MM7 response. There is no SOAP-level fault and the response object is an appropriate subclass of Response constructed from the body of the response
2. Failure response at the MM7 layer. The request was sent to the peer which responded with a SOAP fault carrying a non-success (anything but 1xxx) MM7 response. The SOAP-level fault reflects the actual fault code and string contained in the SOAP fault. The response object is a subclass of ErrorResponse constructed from the SOAP fault detail body.
3. SOAP fault. The request was sent to the peer which responded with a SOAP fault that did not carry a MM7-level response in its fault detail body. The SOAP-level fault reflects the actual fault code and string contained in the SOAP fault, and there is no response object.
4. Failure response at the HTTP layer: the request could not be sent, or the request timed out, or the connection failed unexpectedly, or the response could not be parsed, or the peer returned an unexpected HTTP status code. The SOAP-level fault contains a synthetic fault code and string that reflects the HTTP error, and there is no response object.

Dispatch of response events on a newly created activity is deferred until after the transaction containing the activity creating has committed. This makes it safe to send a new request, creating a new activity, and then attach a SBB to it to receive the response event. No race condition between event dispatch and SBB attachment occurs.

MM7 Transaction ID Management

MM7 Transaction IDs are managed transparently by the Resource Adaptor. The Transaction ID of an incoming request is automatically propagated to any corresponding response. Outgoing requests have unique transaction IDs automatically generated by the Resource Adaptor, and the transaction ID returned in any response is verified internally.

The Transaction IDs of both incoming and outgoing requests are available for logging purposes via MM7Activity.getTransactionID().

Role-specific differences

VASP

The SBB interface is an implementation of VASPProvider. The peers are Relay Servers. SBBs may send the following request types to their peers:

• Cancel
• Replace
• Submit
• ExtendedCancel
• ExtendedReplace

SBBs may receive the following event types:

• DeliverRequestEvent
• DeliveryReportRequestEvent
• ReadReplyReportRequestEvent
• CancelResponseEvent
• ReplaceResponseEvent
• SubmitResponseEvent
• ExtendedCancelResponseEvent
• ExtendedReplaceResponseEvent

Errors sent via MM7Activity.sendErrorResponse() are VASP Error Responses.

Relay Server

The SBB interface is an implementation of RSProvider. The peers are VASPs. SBBs may send the following request types to their peers:

• Deliver
• Delivery Report
• Read Reply Report

SBBs may receive the following event types:

• CancelRequestEvent
• ReplaceRequestEvent
• SubmitRequestEvent
• ExtendedCancelRequestEvent
• ExtendedReplaceRequestEvent
• DeliverResponseEvent
• DeliveryReportResponseEvent
• ReadReplyReportResponseEvent

Errors sent via MM7Activity.sendErrorResponse() are RS Error Responses.