12 Using the Profile Service API

The following chapter describes how to use the Diameter Sh profile service and the Profile Service API, based on the OWLCS Diameter protocol implementation, in your own applications, and contains the following sections:

Section 12.1, "Overview of Profile Service API and Sh Interface Support"
Section 12.2, "Enabling the Sh Interface Provider"
Section 12.3, "Overview of the Profile Service API"
Section 12.4, "Creating a Document Selector Key for Application-Managed Profile Data"
Section 12.5, "Using a Constructed Document Key to Manage Profile Data"
Section 12.6, "Monitoring Profile Data with ProfileListener"

12.1 Overview of Profile Service API and Sh Interface Support

The IMS specification defines the Sh profile service as the method of communication between the Application Server (AS) function and the Home Subscriber Server (HSS), or between multiple IMS Application Servers. The AS uses the Sh profile service in two basic ways:

To query or update a user's data stored on the HSS
To subscribe to and receive notifications when a user's data changes on the HSS

The user data available to an AS may be defined by a service running on the AS (repository data), or it may be a subset of the user's IMS profile data hosted on the HSS. The Sh interface specification, 3GPP TS 29.328, defines the IMS profile data that can be queried and updated through Sh. All user data accessible through the Sh profile service is presented as an XML document with the schema defined in 3GPP TS 29.328.

The IMS Sh profile service is implemented as a provider to the base Diameter protocol support in OWLCS. The provider transparently generates and responds to the Diameter command codes defined in the Sh application specification. A higher-level Profile Service API enables SIP Servlets to manage user profile data as an XML document using XML Document Object Model (DOM). Subscriptions and notifications for changed profile data are managed by implementing a profile listener interface in a SIP Servlet.

Figure 12-1 Profile Service API and Sh Provider Implementation

Description of "Figure 12-1 Profile Service API and Sh Provider Implementation"

OWLCS includes a provider for the Diameter Sh profile service. Providers to support additional interfaces defined in the IMS specification may be provided in future releases. Applications using the profile service API are able to use additional providers as they are made available.

12.2 Enabling the Sh Interface Provider

See "Configuring Diameter Sh Client Nodes and Relay Agents" in Configuring Network Resources for full instructions on setting up Diameter support.

12.3 Overview of the Profile Service API

OWLCS provides a simple profile service API that SIP Servlets can use to query or modify subscriber profile data, or to manage subscriptions for receiving notifications about changed profile data. Using the API, a SIP Servlet explicitly requests user profile documents through the Sh provider application. The provider returns an XML document, and the Servlet can then use standard DOM techniques to read or modify profile data in the local document. Updates to the local document are applied to the HSS after a "put" operation.

12.4 Creating a Document Selector Key for Application-Managed Profile Data

The document selector key identifies the XML document to be retrieved by a Diameter interface, and uses the format protocol://uri/reference_type[/access_key]. Servlets that manage profile data can explicitly obtain an Sh XML document from a Profile Service using a document selector key, and then work with the document using DOM.

The protocol portion of the selector identifies the Diameter interface provider to use for retrieving the document. Sh XML documents require the sh:// protocol designation.

With Sh document selectors, the next element, uri, generally corresponds to the User-Identity or Public-Identity of the user whose profile data is being retrieved. If you are requesting an Sh data reference of type LocationInformation or UserState, the URI value can be the User-Identity or MSISDN for the user.

Table 12-2 summarizes the possible URI values that can be supplied depending on the Sh data reference you are requesting. 3GPP TS 29.328 describes the possible data references and associated reference types in more detail.

Table 12-1 Possible URI Values for Sh Data References

Sh Data Reference Number	Data Reference Type	Possible URI Value in Document Selector
0	RepositoryData	User-Identity or Public-Identity
10	IMSPublicIdentity
11	IMSUserState
12	S-CSCFName
13	InitialFilterCriteria
14	LocationInformation	User-Identity or MSISDN
15	UserState
17	Charging information	User-Identity or Public-Identity
17	MSISDN

The final element of the document selector key, reference_type, specifies the data reference type being requested. For some data reference requests, only the uri and reference_type are required. Other Sh requests use an access key, which requires a third element in the document selector key corresponding to the value of the Attribute-Value Pair (AVP) defined in the document selector key.

Table 12-2 summarizes the required document selector key elements for each type of Sh data reference request.

Table 12-2 Summary of Document Selector Elements for Sh Data Reference Requests

Data Reference Type	Required Document Selector Elements	Example Document Selector
RepositoryData	sh://uri/reference_type/Service-Indication	sh://sip:user@oracle.com/RepositoryData/Call Screening/
IMSPublicIdentity	sh://uri/reference_type/[Identity-Set] where Identity-Set is one of: All-Identities Registered-Identities Implicit-Identities	sh://sip:user@oracle.com/IMSPublicIdentity/Registered-Identities
IMSUserState	sh://uri/reference_type	sh://sip:user@oracle.com/IMSUserState/
S-CSCFName	sh://uri/reference_type	sh://sip:user@oracle.com/S-CSCFName/
InitialFilterCriteria	sh://uri/reference_type/Server-Name	sh://sip:user@oracle.com/InitialFilterCriteria/www.oracle.com/
LocationInformation	sh://uri/reference_type/(CS-Domain \| PS-Domain)	sh://sip:user@oracle.com/LocationInformation/CS-Domain/
UserState	sh://uri/reference_type/(CS-Domain \| PS-Domain)	sh://sip:user@oracle.com/UserState/PS-Domain/
Charging information	sh://uri/reference_type	sh://sip:user@oracle.com/Charging information/
MSISDN	sh://uri/reference_type	sh://sip:user@oracle.com/MSISDN/

12.5 Using a Constructed Document Key to Manage Profile Data

OWLCS provides a helper class, com.bea.wcp.profile.ProfileService, to help you easily retrieve a profile data document. The getDocument() method takes a constructed document key, and returns a read-only org.w3c.dom.Document object. To modify the document, you make and edit a copy, then send the modified document and key as arguments to the putDocument() method.

Note:

If Diameter Sh client node services are not available on the OWLCS instance when getDocument() the profile service throws a "No registered provider for protocol" exception.

OWLCS caches the documents returned from the profile service for the duration of the service method invocation (for example, when a doRequest() method is invoked). If the service method requests the same profile document multiple times, the subsequent requests are served from the cache rather than by re-querying the HSS.

Example 12-1 shows a sample SIP Servlet that obtains and modifies profile data.

Example 12-1 Sample Servlet Using ProfileService to Retrieve and Write User Profile Data

package demo;
import com.bea.wcp.profile.*;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServlet;
import org.w3c.dom.Document;
import java.io.IOException;
public class MyServlet extends SipServlet {
      private ProfileService psvc;
      public void init() {
        psvc = (ProfileService) getServletContext().getAttribute(ProfileService.PROFILE_SERVICE);
      }
      protected void doInvite(SipServletRequest req) throws IOException {
        String docSel = "sh://" + req.getTo() + "/IMSUserState/";
        // Obtain and change a profile document.
        Document doc = psvc.getDocument(docSel); // Document is read only.
        Document docCopy = (Document) doc.cloneNode(true);
        // Modify the copy using DOM.
        psvc.putDocument(docSel, docCopy); // Apply the changes.
      }
}

12.6 Monitoring Profile Data with ProfileListener

The IMS Sh interface enables applications to receive automatic notifications when a subscriber's profile data changes. OWLCS provides an easy-to-use API for managing profile data subscriptions. A SIP Servlet registers to receive notifications by implementing the com.bea.wcp.profile.ProfileListener interface, which consists of a single update method that is automatically invoked when a change occurs to profile to which the Servlet is subscribed. Notifications are not sent if that same Servlet modifies the profile information (for example, if a user modifies their own profile data).

Note:

In a replicated environment, Diameter relay nodes always attempt to push notifications directly to the engine tier server that subscribed for profile updates. If that engine tier server is unavailable, another server in the engine tier cluster is chosen to receive the notification. This model succeeds because session information is stored in the SIP data tier, rather than the engine tier.

12.6.1 Prerequisites for Listener Implementations

In order to receive a call back for subscribed profile data, a SIP Servlet must do the following:

Implement com.bea.wcp.profile.ProfileListener.
Create one or more subscriptions using the subscribe method in the com.bea.wcp.profile.ProfileService helper class.
Register itself as a listener using the listener element in sip.xml.

"Implementing ProfileListener" describes how to implement ProfileListener and use the susbscribe method. In addition to having a valid listener implementation, the Servlet must declare itself as a listener in the sip.xml deployment descriptor file. For example, it must add a listener element declaration similar to:

<listener>
   <lisener-class>com.mycompany.MyLisenerServlet</listener-class>
</listener>

12.6.2 Implementing ProfileListener

Actual subscriptions are managed using the subscribe method of the com.bea.wcp.profile.ProfileService helper class. The subscribe method requires that you supply the current SipApplicationSession and the key for the profile data document you want to monitor. See "Creating a Document Selector Key for Application-Managed Profile Data".

Applications can cancel subscriptions by calling ProfileSubscription.cancel(). Also, pending subscriptions for an application are automatically cancelled if the application session is terminated.

Example 12-2 shows sample code for a Servlet that implements the ProfileListener interface.

Example 12-2 Sample Servlet Implementing ProfileListener Interface

package demo;
    import com.bea.wcp.profile.*;
    import javax.servlet.sip.SipServletRequest;
    import javax.servlet.sip.SipServlet;
    import org.w3c.dom.Document;
    import java.io.IOException;
    public class MyServlet extends SipServlet implements ProfileListener {
      private ProfileService psvc;
      public void init() {
        psvc = (ProfileService) getServletContext().getAttribute(ProfileService.PROFILE_SERVICE);
      }
      protected void doInvite(SipServletRequest req) throws IOException {
        String docSel = "sh://" + req.getTo() + "/IMSUserState/";
        // Subscribe to profile data.
        psvc.subscribe(req.getApplicationSession(), docSel, null);
}
      public void update(ProfileSubscription ps, Document document) {
        System.out.println("IMSUserState updated: " + ps.getDocumentSelector());
      }
    }