| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.0 Part Number E21362-01 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.0 Part Number E21362-01 |
|
|
View PDF |
This chapter describes the Parlay X 2.1 Presence/SIP communication service in detail.
The Parlay X 2.1 Presence/SIP communication service exposes both the watcher aspect and the presentity aspect of the Parlay X 2.1 Presence set of application interfaces.
The communication service connects to a SIP-IMS network using Oracle Converged Application Server. Converged Application Server is collocated with Services Gatekeeper in the network tier.
For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.
Presence information is a collection of data on an end user's status, such as current activity, environment, available communication means, and contact addressees. Using the presence functionality, an application can function as a client in two modes: as a watcher or as a presentity. A watcher is a client that is interested in consuming presence information. A presentity is a client that allows its presence information to be delivered to watchers.
An application acting as a watcher can:
Subscribe to obtain presence data.
Each subscription requires authorization by the presentity. The authorization is returned asynchronously via the notification interface.
Choose to acquire presence information when a subscription has been established using:
Direct synchronous polling. This is only effective for a single presentity. Groups are not supported.
Specific notifications. These can be used for a single presentity. The watcher sets a notification trigger based on certain user presence attribute changes.
Possible attribute types include:
Activity (User's status: Available, Busy, At Lunch, and so on.)
Place (User's current location: Home, In a Public Place, and so on.)
Privacy (Degree of privacy the user has: Surrounded by Others, Alone and Can Talk Openly, and so on.)
Sphere (User's personal status: In his Work Capacity; In his Personal Capacity)
Communication means (Type of communication client preferred: Phone, Email, SMS, and so on.)
Other (name-value pair for arbitrary information)
Non-attribute notification parameters can include:
Maximum frequency of notifications
Duration of time during which notifications should occur
Maximum number of notifications
Whether status should be checked immediately after notification setup
End notifications. In this case, the subscription to the presentity is retained, but the specific notification is ended.
Receive information that:
The initial conditions of the notification setup have been met (count or duration) and this specific setup has been ended.
The subscription itself has ended.
An application acting as a presentity can:
Publish present information.
Get a list of new watchers who have asked to subscribe to the client's presence information.
Approve new watchers and update the subscriptions of current watchers.
Get a list of currently subscribed watchers.
Block the subscription of a currently subscribed watcher.
The presentity functionality requires a presence server in the underlying network. To approve new watchers and update the subscriptions of current watchers, there must also be a data manipulation server (DMS) in the underlying network. The block functionality is supported in two modes, one using a DMS and one not.
For information about the SOAP-based interface for the Parlay X 2.1 Presence communication service, the discussion of Parlay X 2.1 Interfaces in Application Developer's Guide.
For information about the RESTful Presence interface, see the discussion of Presence in RESTful Application Developer's Guide.
The RESTful Service Call Notification interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs and reading CDRs, and so on, they are the same.
The Parlay X 2.1 Presence/SIP communication service generates Event Data Records (EDRs), Charging Data Records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 5-1 lists IDs of the EDRs created by the Presence/SIP communication service. This list does not include EDRs created when exceptions are thrown.
Table 5-1 Event Types Generated by Parlay X 2.1 Presence/SIP
| EDR ID | Method Called |
|---|---|
|
2000 |
notifyReceived |
|
2001 |
makeNotifySubscriptionCallback (includes Endpoint, string) |
|
2002 |
makeSubscriptionEndedCallback (includes Endpoint, string) |
|
2003 |
makeStatusChangedCallback (includes Endpoint, string) |
|
2004 |
makeStatusEndCallback (includes Endpoint, string) |
|
2005 |
subscribePresence (processes from application) |
|
2006 |
getUserPresence |
|
2007 |
startPresenceNotification |
|
2008 |
endPresenceNotification |
|
2009 |
publish |
|
2010 |
blockSubscription |
|
2011 |
getMyWatchers |
|
2012 |
getOpenSubscriptions |
|
2013 |
updateSubscriptionAuthorization |
|
2015 |
onRequest (Watcher Info Notify) |
Presence/SIP-specific CDRs are generated under the following conditions:
After the result of a poll for presence is successfully returned to the application.
After a notification for presence information is successfully sent to the application.
A Presence CDR contains an additional_info field for a notification call. This field contains the endpoint.
Table 5-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
This section lists the parameters that can be tunneled.
This value is used to cancel a subscription to a user presence. The parameter is configured in the SIP plug-in.
If set, this value replaces the default SubscribeExpiryValue configured in the Presence MBean.
Can be set using parameter tunneling.
String
<xparams> <param key="expireskey" value="1210"/> </xparams>
This section describes the properties and workflow for the Parlay X 2.1 Presence/SIP plug-in instance. It also describes the caches used by the plug-in instance.
Parlay X 2.1 Presence/SIP uses two parts for SIP connectivity: a part that executes as a network protocol plug-in instance in the Services Gatekeeper container and a part that executes as a SIP application in the SIP Server container.
This plug-in service does not support multiple instantiation using the Plug-in Manager. There is a one to one mapping between plug-in service and plug-in instance. The plug-in instance is created when the plug-in service is started.
In Parlay X 2.1 Presence, the SIP URI of the user (the presentity in Presence Supplier cases, the watcher in Presence Consumer cases) is not passed as an argument. Instead, Services Gatekeeper maps the user URI to the application instance ID of the user application. The URI mapping is configured as a part of the service provider and application provisioning workflow and is then stored in the URI cache.
For requests that originate from an application, the URI is fetched from this cache before being put into the from header in the SIP requests. For application-terminating requests, the to header URI passed in the SIP NOTIFY requests is used to look up the account user name and application instance ID.
In the case of the Presence Supplier interface, the application can override the default mapping by including a tunneled parameter in the header of its request.
Every subscription, pending or not, is stored in the subscriptions cache during the subscription's lifetime. It is added when an application invokes the subscribePresence operation on the application-facing interface. It is removed when the subscription is terminated.
All registered notifications are cached. The entries are created when an application invokes startPresenceNotification on the application-facing interface. They are removed when endPresenceNotification is called, the end criteria are reached, or the subscription is ended.
Table 5-3 lists the technical specifications for the communication service.
Table 5-3 Properties for Parlay X 2.1 Presence/SIP
| Property | Description |
|---|---|
|
Managed object in Administration Console |
domain_name > OCSG > server_name > Communication Services > Plugin_px21_presence_sip |
|
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=Plugin_px21_presence_sip Type=com.bea.wlcp.wlng.plugin.presence.sip.management.PresenceMBean |
|
Network protocol plug-in service ID |
Plugin_px21_presence_sip |
|
Network protocol plug-in instance ID |
Plugin_px21_presence_sip |
|
Supported Address Scheme |
sip |
|
Application-facing interfaces |
com.bea.wlcp.wlng.px21.plugin.PresenceConsumerPlugin com.bea.wlcp.wlng.px21.plugin.PresenceSupplierPlugin com.bea.wlcp.wlng.px21.callback.PresenceNotificationCallback |
|
Service type |
Presence |
|
Exposes to the service communication layer a Java representation of: |
Parlay X 2.1 Part 14: Presence |
|
Interfaces with the network nodes using: |
SIP: Session Initiation Protocol, RFC 3261. |
|
Deployment artifact: NT EAR wlng_nt_presence_px21.ear |
Plugin_px21_presence_sip.jar, px21_presence_service.jar, and px21_presence_sip.jar |
|
Deployment artifact: AT EAR: Normal wlng_at_presence_px21.ear |
px21_presence.war, px21_presence_callback.jar, and rest_presence.war |
|
Deployment artifact: AT EAR: SOAP Only wlng_at_presence_px21_soap.ear |
px21_presence.war and px21_presence_callback.jar |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Select the MBean described in "Properties for Parlay X 2.1 Presence/SIP".
Configure the attributes of the network protocol plug-in instance:
Configure connection information to the SIP server:
Set up the routing rules to the plug-in instance. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Presence/SIP"section.
If required, create and load a node SLA. For details see “Defining Global Node and Service Provider Group Node SLAs” and “Managing SLAs” in the Accounts and SLAs Guide.
Provision the service provider accounts and application accounts. For information, see Accounts and SLAs Guide.
For every application, use "Operation: setApplicationInstanceSIPURI" to define a mapping between a SIP URI and application instance ID.
Use "Operation: getApplicationInstanceSIPURI" to display the mapping.
If an application is deleted, use "Operation: removeApplicationInstanceFromCache" remove the data for the application.
This section describes the attributes and operations for configuration and maintenance:
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the default notification count value. This value is used if none is provided in the startPresenceNotification requests from the application.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the value of the default notification duration. This value is used if none is provided in the startPresenceNotification request from the application.
Example values:
86400 seconds is 1 day
604800 seconds is 1 week
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the value of the timer used for checking on and cleaning up old notifications.
Each time the timer expires, it initiates a check for old notifications. If an old notification is found during the check, it is removed internally and a statusEnd callback is made to the application.
Scope: Cluster
Unit: Not applicable
Format: String formatted as a SIP URI
Specifies the address to which the subscribe messages are sent. It can be the IP address of the Presence server or another IMS node that proxies the request.
Scope: Cluster
Unit: Not applicable
Format: String formatted as a SIP URI
Specifies the XCAP root URI of the XDM server.
Scope: Cluster
Unit: Not applicable
Format: String formatted as a partial path
Specifies the last-part of the XCAP Document selector for Presence rules. This part is after the XCAP User Identifier(XUI). Generally the selector URI should be the string of the following type: [XCAP_ROOT]/[AUID]/users/[XUI]/[document_name]
Example:
/presrules
Scope: Cluster
Unit: Not applicable
Format: String formatted as a path
The pre-part of the XCAP Document selector for presence rules. This part is before the XCAP User Identifier(XUI). Generally the selector URI should be the string of the following type: [XCAP_ROOT]/[AUID]/users/[XUI]/[document_name]
Example:
/services/pres-rules/users/
Scope: Cluster
Unit: Not applicable
Format: Class name as string
The class name of XDM Server provider. This is a pluggable function to allow third party vendors of XDMS to customize their own XCAP client. This class must implement the "com.bea.wlcp.wlng.plugin.presence.sip.south.xcap.XCAPClient" interface.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the value of the timer used for checking on and cleaning up old subscriptions.
Each time the timer expires, it initiates a check for old subscriptions. If an old subscription is found during the check, it is removed and a callback made to the application.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the maximum lifetime of a subscription.
This value might not be accepted by the Presence Server. The Presence server may override this expiry value and give the suggested value to be used in the first NOTIFY sent to the plug-in instance. In that case, the lifetime for the presence subscription will be according to the value received from the Presence Server.
Scope: Cluster
Clears one or all caches used by this plug-in instance.
Note:
Use this method with care.Signature:
clearCache(cacheToClear: String)
Scope: Cluster
Displays the application instance ID associated with a SIP URI. The application instance identifies an application.
Signature:
getApplicationInstance(Uri: String)
Scope: Cluster
Displays the SIP URI associated with an application instance. The application instance is used by an application.
Signature:
getApplicationInstanceSIPURI(ApplicationInstanceID: String)
Scope: Cluster
Displays the cache where notification information is stored. Used for troubleshooting.
Note:
Use with caution: lists data from all entries in the notification cache.Signature:
listNotificationsCache()
Scope: Cluster
Displays the cache where subscription information is stored. Used for troubleshooting.
Note:
Use with caution: lists data from all entries in the subscriptions cache.Signature:
listSubscriptionsCache()
Scope: Cluster
Displays the cache where URI mappings information is stored. Used for troubleshooting.
Note:
Use with caution: lists data from all entries in the URI mappings cache.Signature:
listURImappingCache()
Scope: Cluster
Removes entries that are associated with an application instance from the URI mappings cache. If an application instance has been removed, the associated entries in the cache must be removed, too.
Signature:
removeApplicationInstanceFromCache(ApplicationInstance: String)
Scope: Cluster
Removes a notification. The application will not be notified that the notification has been removed.
Signature:
removeNotification(ApplicationInstanceID: String, Presentity: String)
Scope: Cluster
Removes a subscription and notifications. The application will not be notified that the subscription has been removed.
Signature:
removeSubscription(ApplicationInstanceID: String, Presentity: String)
Scope: Cluster
Associates a SIP URI with an application instance. See "URI Cache".
Signature:
setApplicationInstanceSIPURI(applicationInstanceID: String, URI: String)
Scope: Cluster
Updates the xml rule in XDMS to status: confirm.
Forces a blocked subscription to be pending or confirmed.
Signature:
updateSubscriptionToBeconfirmed(presentity: String, watcher: String)
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
