 |
JAIN SLEE Diameter Sh Resource Adaptor Type
Introduction
This page describes a proposed Diameter Sh resource adaptor type donated to the java.net open source community by Open Cloud to initiate the process of standardising JAIN SLEE resource adaptor types.
Note that the scope of this page (and this section of the wiki) is limited to resource adaptor types, and should not be used to describe or discuss resource adaptor implementations.
The proposed RA type contains an exhaustive mapping of the Diameter messages and grouped AVPs defined by the 3GPP Sh technical specification (TS 29.329 V7.1.0). Every Diameter message and grouped AVP is represented by a Java interface with a bean-style access methods for each AVP contained therein. It is done this way for the convenience of the service developer with the intention that the resulting applications are easy to understand and maintain, and applications can send and receive any AVP combination permitted by the specification
Extensibility is currently provided for by exposing the underlying Diameter base API which has a mechanism to register custom AVP codes and add 'extension' AVPs to any message (or grouped AVPs that allow it).
API
SBB Resource Adaptor Interfaces
ShClientProvider
The ShClientProvider is used by a Diameter Sh Client (e.g., an AS) in an IMS network to create and send requests to a Diameter Sh Server (e.g., an HSS). It declares a method to retrieve a factory for messages and AVPs, a method to create an activity used to send and receive messages and methods to send the following messages as synchronous requests (ie, the call will block until an answer is received):
- User-Data-Request
- Profile-Update-Request
- Subscribe-Notifications-Request
ShServerProvider
The ShServerProvider can be used by a SLEE service to provide HSS functions on an IMS network. It declares a method to retrieve a factory for messages and AVPs, a method to create an activity used to send and receive messages and a method to send the following message as a synchronous request:
- Push-Notification-Request
Activities
ShClientActivity
Activity used by a Diameter Sh client to send request messages and receive answer messages.
The following messages can be sent as asynchronous requests using methods on this activity:
- User-Data-Request
- Profile-Update-Request
- Subscribe-Notifications-Request
The following messages are fired as events on this activity:
- User-Data-Answer
- Profile-Update-Answer
- Subscribe-Notifications-Answer
These are stateless requests (the Diameter server does not maintain any state associated with these requests) so the activity ends when the answer event is fired.
ShClientNotificationActivity
Activity for a Diameter Sh client to receive Push-Notification-Request messages and send Push-Notification-Answer messages.
The Push-Notification-Request is an initial event that will cause this activity to be created, and the activity will end when the answer is sent.
It is proposed that a future version of the RA type will allow for this activity to be created when the Subscription request is sent, and will end only when the subscription request is cancelled by sending a Subscribe-Notification-Request message with the Subs-Req-Type set to UNSUBSCRIBE, or when the subscription expires.
ShServerActivity
Activity for a Diameter Sh Server to send and receive messages.
The following request messages are fired as events on this activity:
- User-Data-Request
- Profile-Update-Request
- Subscribe-Notifications-Request
The following messages can be sent using methods on this activity:
- User-Data-Answer
- Profile-Update-Answer
- Subscribe-Notifications-Answer
These are stateless requests so the activity ends when the answer is sent.
ShServerNotificationActivity
Activity for a Diameter Sh server to send Push-Notification-Request messages and receive Push-Notification-Answer messages.
The activity must be created using the method on the ShProvider and will end when the answer is received.
The following answer message is fired as an event on this activity:
The following messages can be sent using methods on this activity:
- Push-Notification-Request
Message and AVP Factories
The RA Type defines interfaces for all messages and grouped AVPs with bean-style access methods. Concrete implementations of these interfaces must be created by a factory provided by the RA implementation.
MessageFactory
This factory declares methods for creating instances of grouped AVP classes and is a superclass of the server- and client-specific message factories.
ShClientMessageFactory
This factory declares methods for creating instances of messages sent by the client:
- User-Data-Request
- Profile-Update-Request
- Subscribe-Notifications-Request
- Push-Notification-Answer
ShServerMessageFactory
This factory declares methods for creating instances of messages sent by the server:
- User-Data-Answer
- Profile-Update-Answer
- Subscribe-Notifications-Answer
- Push-Notification-Request
Messages and Grouped AVPs
There is a Java interface for each Diameter Sh message and grouped AVP. The RA Type API also defines an interface that has factory methods for all messages and grouped AVPs. The RA implementation must provide a class that implements this factory interface to create concrete instances of the messages and grouped AVPs.
Design Overview
The API is a mapping from the BNF message/AVP formats in the specification to Java types. Values for enumerated types are also comprehensively mapped and implemented using the Java typesafe enumeration pattern.
Sh is a stateless protocol -- the Diameter server does not maintain sessions. So from the client perspective, a request to a server will trigger only one answer message at which point that interaction is over (and the activity can end). From a server perspective a new activity is created for an incoming request and it ends when the answer is sent.
When a client subscribes to notifications, this will trigger request messages in the direction from server to client. A new activity will be created for these messages and the request fired as an initial event. When the client sends a PNA this activity ends.
Design Decisions & Rationale
Decision: Separate Server and Client RA Types (and Server and Client Event Jars)
Rationale: There is no overlap in messages sent/received. Both RA Types could be deployed together. (Implementation is out of scope of this discussion.)
Decision: The Resource Adaptor Interface has methods to create activities, the activities have methods to send messages.
Rationale: Activity creation is not coupled with the I/O for sending messages. The activity is created first, so the SBB knows if that invocation returns normally the activity was created and the activity context can be attached to.
Decision: Values of AVPs in messages and grouped AVPs are accessed by bean-style get and set methods.
Rationale: This makes the resulting applications easy to understand and maintain, and applications can send and receive any AVP combination permitted by the specification.
API Limitations and Discussion Points
- Extensibility is an implementation concern.
- The API currently exposes the User-Data AVP XML document in raw form. The API should have a mechanism to create and inspect the XML document.
- How to identify multiple applications in a single Diameter node? (Protocol not designed for this, Session-Id used to route answer messages, but Push-Notification-Requests don't have a correlation ID. For now we have to assume 1 app per host/stack.)
- We should support a long-lived activity for notifications, one possibility being as follows:
- The ShClientProvider allows creation of a ShNotificationActivity (distinct from ShClientActivity)
- ShNotificationActivity used to send the Subscribe-Notifications-Request
- Subscribe-Notification-Answer event fired on this activity
- Push-Notification-Reqests for this particular subscription also fired on this activity for the duration of the subscription
RA Type Versions
The descriptors in the source bundle for this RA Type will have a version number of 0.8. It is proposed that version numbers between 0.8 and 1.0 be used to mark milestones when adding the new behaviour for the ShNotificationActivity discussed above, adding a User-Data API and incorporating any other changes agreed to by the community.
Examples
Creating and sending a UDR
// Create and attach to the Sh activity
ShClientActivity shClientActivity = shClientProvider.createShClientActivity();
ActivityContextInterface shACI = shACIFactory.getActivityContextInterface(shClientActivity);
shACI.attach(getSbbLocalObject());
// Create and send the UDR
ShClientMessageFactory clientMessageFactory = shClientProvider.getClientMessageFactory();
UserIdentity userIdentity = clientMessageFactory.createUserIdentity();
userIdentity.setPublicIdentity(address);
UserDataRequest userDataRequest = clientMessageFactory.createUserDataRequest(userIdentity, DataReference.IMS_PUBLIC_IDENTITY);
userDataRequest.setDestinationHost(new DiameterIdentity("sh-server"));
userDataRequest.setDestinationRealm(new DiameterIdentity("opencloud"));
shClientActivity.sendUserDataRequest(userDataRequest);
Receiving a UDA
public void onUserDataAnswer(UserDataAnswer uda, ActivityContextInterface aci) {
if(uda.getResultCode() == DiameterResultCode.DIAMETER_SUCCESS) {
UserData userData = uda.getUserData();
// process user data
}
}
References
-- Main.perrinm - 25 Aug 2006
|