Servlets that manage profile data can explicitly obtain an Sh XML document from a factory using a key, and then work with the document using DOM.

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].

The example below summarizes the required document selector elements for each type of Sh data reference request.

Converged Application Server 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.

See "Using the Profile Service API (Diameter Sh Interface)" in Converged Application Server Diameter Application Development Guide for more information.

The IMS Sh interface enables applications to receive automatic notifications when a subscriber's profile data changes. Converged Application Server 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).

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 "Using Document Keys for Application-Managed Profile Data" for more information.

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

Example 2-7 shows sample code for a Servlet that implements the 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());
      }
    }

The ProfileListener interface is handled similar to the TimerService provided by JSR 116 for application timers. Multiple Servlets in an application may implement the ProfileListener interface, but only one Servlet may act as a listener. The SIP deployment descriptor for the application must designate the profile listener class in the set of listeners as shown in Example 2-8.

<listener>
<listener-class>com.foo.MyProfileListener</listener-class>
Declaring a ProfileListener
</listener>
<listener>
  <listener-class>com.foo.MyProfileListener</listener-class>
</listener>

Example 2-7 can be rewritten using an annotated POJO as shown in Example 2-9.

package demo;
// Includes excluded for brevity...
@SipServlet(loadOnStartup = 1);
public class MyServlet implements ProfileListener {
  private ProfileService psvc;
  @Inject SipFactory sipFactory;
  public void init() {
    psvc = (ProfileService) getServletContext().getAttribute(ProfileService.PROFILE_SERVICE);
  }
  @Invite
  protected void handleInvite(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());
  }
}