The following sections describe how to use the profile service API to develop custom profile providers:
WebLogic SIP Server includes a profile service API, com.bea.wcp.profile.API
, that can be used to create profile provider implementations. A profile provider performs the work of accessing XML documents from a data repository using a defined protocol. Deployed SIP Servlets and other applications need not understand the underlying protocol or the data repository in which the document is stored; they simply reference profile data using a custom URL, and WebLogic SIP Server delegates the request processing to the correct profile provider.
The provider performs the necessary protocol operations for manipulating the document. All providers work with documents in XML DOM format, so client code can work with many different types of profile data in a common way.
You can also use the profile service API to create a custom provider for retrieving document schemas using another protocol. For example, a profile provider could be created to retrieve subscription data from an LDAP store or RDBMS.
Note: | The Diameter Sh application also accesses profile data from a Home Subscriber Server using the Sh protocol. Profile. Although applications access this profile data using a simple URL, the Diameter applications are implemented using the Diameter base protocol implementation rather than the profile provider API. |
Each profile provider implemented using the API may enable the following operations against profile data:
Clients that want to use a profile provider obtain a profile service instance via a Servlet context attribute. They then construct an appropriate URL and use that URL with one of the available profile API methods to work with profile data. The contents of the URL, combined with the configuration of profile providers, determines the provider implementation that WebLogic SIP Server to process the client’s requests. Using the Diameter Sh Interface Application provides additional examples about accessing a profile provider from within a SIP Servlet.
The sections that follow describe how to implement the profile service API interfaces in a custom profile provider.
A custom profile providers is implemented as a shared J2EE library (typically a simple JAR file) deployed to the engine tier cluster. The provider JAR file should include, at minimum, a class that implements
com.bea.wcp.profile.ProfileServiceSpi. This interface inherits methods from com.bea.wcp.profile.ProfileService
and defines new methods that are called during provider registration and unregistration.
In addition to the provider implementation, you must implement the
com.bea.wcp.profile.ProfileSubscription interface if your provider supports subscription-based notification of profile data updates. A ProfileSubscription
is returned to the client subscriber when the profile document is modified.
The WebLogic SIP Server JavaDoc describes each method of the profile service API in detail. Also keep in mind the following notes and best practices when implementing the profile service interfaces:
putDocument
, getDocument
, and deleteDocument
methods each have two distinct method signatures. The basic version of a method passes only the document selector on which to operate. The alternate method signature also passes the address of the sender of the request for protocols that require explicit information about the requestor.subscribe
method has multiple method signatures to allow passing the sender’s address, as well as for supporting time-based subscriptions.com.bea.wcp.profile.ProfileServiceSpi
, include a “no-op” method implementation that throws the
OperationNotSupportedException.
com.bea.wcp.profile.ProfileServiceSpi defines provider methods that are called during registration and unregistration. Providers can create connections to data stores or perform any required initializing in the register
method. The register
method also supplies a ProviderBean
instance, which includes any context parameters configured in the provider’s configuration elements in profile.xml
.
Providers should release any backing store connections, and clean up any state that they maintain, in the unregister
method.
Providers must be deployed as a shared J2EE library, because all other deployed applications must be able to access the implementation. Creating Shared J2EE Libraries and Optional Packages in the WebLogic Server 9.2 documentation describes how to assemble J2EE libraries. For most profile providers, you can simply package the implementation classes in a JAR file. Then register the library with WebLogic SIP Server using the instructions in Install a J2EE Library in the WebLogic Server 9.2 documentation.
After installing the provider as a library, you must also identify the provider class as a provider in aprofile.xml
file. Thename
element uniquely identifies a provider configuration, and theclass
element identifies the Java class that implements the profile service API interfaces. One or more context parameters can also be defined for the provider, which are delivered to the implementation class in theregister
method. For example, context parameters might be used to identify backing stores to use for retrieving profile data.
Listing 10-1 shows a sample configuration for a provider that accesses data using XCAP.
<profile-service xmlns=”http://www.bea.com/ns/wlcp/wlss/profile/300”
xmlns:sec=”http://www.bea.com/ns/weblogic/90/security”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema=instance”
xmlns:wls=”http;//www.bea.com/ns/weblogic/90/security/wls”>
<mapping>
<map-by>provider-name</map-by>
</mapping>
<provider>
<name>xcap</name>
<provider-class>com.mycompany.profile.XcapProfileProvider</provider-class>
<param>
<name>server</name>
<value>example.com</name>
</param>
...
</provider>
</profile-service>
When an application makes a request using the profile API, WebLogic SIP Server must find a corresponding provider to process the request. By default, WebLogic SIP Server maps the prefix of the requested URL to a provider name
element defined in profile.xml
. For example, with the basic configuration shown in Listing 10-1, WebLogic SIP Server would map profile API requests beginning with xcap://
to the provider class com.mycompany.profile.XcapProfileProvider.
Alternately, you can define a mapping
entry in profile.xml
that lists the prefixes corresponding to each named provider. Listing 10-2 shows a mapping with two alternate prefixes.
...
<mapping>
<map-by>prefix</map-by>
<provider>
<provider-name>xcap</provider-name>
<doc-prefix>sip</doc-prefix>
<doc-prefix>subscribe</doc-prefix>
</provider>
<by-prefix>
<mapping>
...
If the explicit mapping capabilities of profile.xml
are insufficient, you can create a custom mapping class that implements the com.bea.wcp.profile.ProfileRouter interface, and then identify that class in the map-by-router
element. Listing 10-3 shows an example configuration.
...
<mapping>
<map-by-router>
<class>com.bea.wcp.profile.ExampleRouter</class>
</map-by-router>
</mapping>
...
You can optionally use the Administration Console to create or modify a profile.xml
file. To do so, you must enable the profile provider console extension in the config.xml
file for your domain.
...
<custom-resource>
<name>ProfileService</name>
<target>AdminServer</target>
<descriptor-file-name>custom/profile.xml</descriptor-file-name>
<resource-class>com.bea.wcp.profile.descriptor.resource.ProfileServiceResource</resource-class>
<descriptor-bean-class>com.bea.wcp.profile.descriptor.beans.ProfileServiceBean</descriptor-bean-class>
</custom-resource>
</domain>
The profile provider extension appears under the Sipserver node in the left pane of the console, and enables you to configure new provider classes and mapping behavior.