This chapter provides an introduction to the Oracle WebLogic Communication Services (OWLCS) in the following sections:
Presence may be used to display an end-user's availability and ability to participate in a chat or richer multimedia interaction. Client presence is often represented as a contact management list, which displays user availability as icons. These icons, which not only represent a user's availability, but also a user's location, means of contact, or current activity, enable efficient communications between users.
The Presence application enables a service provider or an enterprise to extend presence service to end users. Major capabilities include:
The term presentity is used here to refer to a Presence Entity (a Presence Entity [presentity] is an entity, such as a person, who is defined by their ability and willingness to communicate). A presentity can publish a Presence Information Data Format (PIDF) document containing presence state to the Presence Server.
The Presence Server supports subscriptions to a presentity's (that is, a user's) status. The Presence Server supports the watcher information event package. This event package allows a presentity to be notified as soon as a watcher has subscribed to his/her presence state. The Presence Server notifies the user when the watcher (subscriber) requests authorization to view the presentity's status. The Presence server also notifies all of the active, authorized watchers of the publication of a new presence document.
A presentity can create filtering rules allowing certain watchers to only see certain parts of the presence states. Whenever a watcher subscribes to a presentity's presence, the Presence Server checks the authorization policy that the presentity has set to see if the watcher has the required authorization.
If no matching rule can be found, the watcher is put in a pending state and a watcher info notification is sent to the presentity. Usually, the presentity's client (User Agent) presents a pop-up box asking whether to accept or reject a new pending watcher. The answer is added to the presentity's authorization policy document in the form of a rule for this watcher. The document is then updated by the client on the XDMS using HTTP. When the document is updated, the Presence Server reads the new policy document and acts on the new rule, changing the subscription state accordingly.
A presentity can leave a hard state note about their presence (such as when going on vacation: 'On vacation - back on the 15th'). Watchers to this presentity's presence state would be able to see this information.
Configuration of the Presence Server is done through the following MBeans:
The following MBeans enables you to configure the XDMS (XML Document Management Server):
Note:
If you change any attributes of the following MBeans, you must restart OWLCS for these changes to take effect.Presence
PresenceEventPackage
PresenceWInfoEventPackage
UAProfileEventPackage
XCapConfigManager
Note:
JGroups channels must only communicate with their intended peers. To ensure that event packages use JGroups correctly, different channels must use different values for the group name, multicast address and multicast port. Seehttp://www.jboss.org/ for more information.Through the Bus MBean you can configure the internal asynchronous bus that the Presence Server is using for its internal job execution. Table 9-1 describes the attributes of the Bus MBean.
Table 9-1 Attributes of the Bus MBean
| Attribute | Value Type | Description |
|---|---|---|
|
ThreadPoolSize |
int |
The number of threads held in the thread pool, which remains constant throughout the lifetime of the application. If no threads are used, then the specified number of threads remain idle. The default value is 15. |
|
HighWatermark |
int |
The number of pending jobs reached before the bus's exhausted threshold level is reached. The default value is 20. |
|
KeepAlive |
long |
The number of seconds to keep an idle thread alive before dropping it. The default value is 60. |
|
LogDuration |
long |
A warning is logged to the system log for events that remain in the queue for a period exceeding the specified duration before they are broadcast to the bus. This warning indicates that server is about to be overloaded, since an old job has been sent to the bus. The default value is 60. |
|
LowWatermark |
int |
Specifies the low threshold level for the number of pending jobs. When this threshold is reached from below, the Bus logs a warning that it is about to be choked. At this point, no more warnings are logged until the high watermark level is reached. The default value is 15. |
The PresenceEventPackage, PresenceWInfoEventPackage, and UA-ProfileEventPackage MBeans enable you to configure the event packages, which define the state information to be reported by a notifier to a watcher (subscriber). These packages form the core of the Presence Server, as most requests flow through them.
A notifier is a User Agent (UA) that generates NOTIFY requests that alert watchers to the state of a resource (the entity about which watchers request state information). Notifiers typically accept SUBSCRIBE requests to create subscriptions. A watcher is another type of UA, one that receives the NOTIFY requests issued by a notifier. Such requests contain information about the state of a resource of interest to the watcher. Watchers typically also generate SUBSCRIBE requests and send them to notifiers to create subscriptions.
The PackageManager MBean sets the configuration that determines which of the three event packages (Presence, Watcher Info and UA-Profile) get loaded, as well as configures the environment in which these event packages are loaded. Table 9-2 describes the attributes of the PackageManger MBean.
Table 9-2 Attributes of the EventPackageManager MBean
| Attribute | Description |
|---|---|
|
JGroupBroadcastEnabled |
If true, a single JGroup channel is created for all the event packages running on this Presence Server instance. Whenever new resources are created in any of the running event packages, a message is broadcast on this JGroup channel. |
|
JGroupXMLConfigPath |
Path to an XML configuration file for JGroups. The path can be absolute or relative to the WebLogic domain directory on which the event package is running. Leave this empty to use the following default values for the jgroups connection: UDP(bind_addr=[ip address of this host];mcast_addr=230.0.0.1;mcast_port=7426;ip_ttl=1) |
|
JGroupChannelName |
The name to use when creating the JGroup channel. Note that to prevent aliasing of different JGroup clusters, each cluster must have a unique channel name in addition to a unique multicast port or address. |
|
CaseSensitiveUserPart |
Setting this attribute to true enables case-sensitive handling of the user part of the SIP URI. If this parameter is set to false, then the user part of the URI is not a case-sensitive match. For example, foo is considered the same as FoO. The domain part of the URI is always case-insensitive. |
|
EventPackageNames |
A comma-separated list of event package names. For example: presence,presence.winfo,ua-profile. Only the event packages listed here will be started by the Presence Server. |
|
WaitingSubsCleanupInterval |
The interval, in seconds, in which the subscription cleanup check runs. The thread sleeps for this period and then awakens to check for any waiting subscriptions with a timestamp older than the MaxWaitingSubsTimeHours parameter. All old subscriptions are then removed from the subscribed resource. |
|
Max WaitingSubsTimeHours |
The maximum time, in hours, that a subscription can be in a waiting state before the server removes it. This parameter is used by the subscription cleanup check thread ( |
The Presence MBean controls how the Presence Server interacts with clients connecting to it. The attributes (described in Table 9-3) include those for setting the composition policy for creating a unified document when a presentity publishes presence documents from two or more clients, as well as setting the blocking, filtering, and presence hard state.
Table 9-3 Attributes of the Presence MBean
| Attribute | Description/Value |
|---|---|
|
CompositionPolicyFilename |
The filename of the composition policy document. Values include |
|
DefaultSubHandling |
The default subscription authorization decision that the server makes when no presence rule is found for an authenticated user. The defined values are:
Unauthenticated users will always be blocked if no rule is found. |
|
DocumentStorageFactory |
The name of the |
|
DocumentStorageRootUrl |
The system identifier for the document storage. In the file storage case, this is the root file URL path where documents are stored. The content of this directory should be deleted when the server is restarted. The default value is file:/tmp/presencestorage/. |
|
DocumentStorageType |
The type of storage to be used for presence documents. Valid values:
The default value is memory. |
|
HttpAssertedIdentityHeader |
The type of asserted identity header used in all HTTP requests from the Presence Server to the XDMS. Set the value of this attribute to one expected by the XDMS. Valid values:
|
|
PidfManipulationAuid |
Also known as hard state, the ID of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocumentName |
The document name for pidf manipulation application usage, for example: hardstate. The default value is hardstate. |
|
PidfManipulationEnabled |
Set to true (the default value) to enable PIDF manipulation. |
|
PidfManipulationXcapUri |
The SIP URI of the XDMS for the pidf manipulation application usage. The default value is: sip:127.0.0.1;transport=TCP;lr. The loose route (lr) parameter must be included in the SIP URI for the server to function properly. |
|
PoliteBlockPendingSubscription |
Set to true if pending subscriptions should be polite-blocked. This feature is used to hide the presentity from the presence watcher with a pending subscription and instead send them fake presence documents. If set to false the subscriptions will remain as pending. |
|
PresRulesAuid |
The ID of the application usage for presrules. The default is pres-rules. |
|
PresRulesDocumentName |
The document name for presrules application usage. The default value is presrules. |
|
PresRulesXcapUri |
The SIP URI of the XDMS for the presence rules application usage. The default value is: sip:127.0.0.1; transport=TCP;lr. The loose route (lr) parameter must be included in the SIP URI for the server to function properly. |
|
PrivacyFilteringEnabled |
Set to true to enable privacy filtering. Set to false to disable filtering. If privacy filtering is disabled, then all subscriptions that are allowed to see a presentity's presence will always see everything that has been published for the presentity. |
|
TransformerFactory |
The name of the |
Table 9-4 shows the attributes of the PresenceEventPackage MBean. The presence event package has two subgroups: publish and subscribe. Each subgroup has a minexpires and a maxexpires parameter. A client may suggest an expiration time for its subscription or its published state but if the suggested time that is lower than the configured minExpires, the server will return a 423 (Interval Too Brief) response.
If a client suggests an expiration time that is higher than the configured max expiration, the server will shorten the suggested time to this configured value. The value chosen by the server is always conveyed in the response to the request.
To keep a publication or subscription alive, the client sends republish or resubscribe to the server within the expiry time. The client must perform this task repeatedly through the lifetime of the publication or subscription.
Table 9-4 Attributes of the PresenceEventPackage
| Attribute | Value/Description |
|---|---|
|
Description |
A description of the PresenceEventPackage. For example: The event package that enables presence. |
|
DocumentFactory |
The |
|
EscMaxDocumentSize |
The maximum size, in bytes, for the contents of a publication. If a client attempts to publish a document that is larger than the specified size, the server sends the 413 response, Request entity too large. The default value is 10000. |
|
ESCMaxExpires |
The maximum time, in seconds, for a publication to expire. The default value is 3600. |
|
ESCMaxPubPerRes |
The maximum number of publications allowed per resource. If the maximum number has been reached for a resource when a new publish is received, the server sends the 503 Response (Service Unavailable). |
|
ESCMinExpires |
The minimum time, in seconds, for a publication to expire. The default is 60. |
|
EventStateCompositor |
The class name of the |
|
Name |
The name of this event package. The default value is Presence. |
|
Notifier |
The name of the |
|
NotifierMaxDocumentSize |
The maximum size for a SUBSCRIBE request. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 3600. |
|
NotifierMaxNoOfSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource, then a new presence subscribe is received and the server sends the 503 Response (Service Unavailable). |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. |
|
ResourceManagerClassName |
The name of the ResourceManager class. The default is |
As described in RFC 3857, a Watcher Information Event Package monitors the resources in another event package to ascertain the state of all of the subscriptions to that resource. This information is then sent to the subscribers of the Watcher Information Event Package. As a result, the watcher learns of changes in the monitored resources subscriptions.
The PresenceWInfoEventPackage MBean (described in Table 9-5) sets the subscription state information for the Watcher Information Event Package.
Table 9-5 Attributes of the WatcherinfoEventPackage
| Attribute | Description/Value |
|---|---|
|
Description |
A description of the PresenceWInfoEventPackage. For example: The event package that enables watcherinfo. |
|
DocumentFactory |
The name of the |
|
Name |
The name of the event package. The default value is presence.winfo. |
|
Notifier |
The |
|
NotifierMaxDocumentSize |
The maximum document size for SUBSCRIBE request. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 3600. |
|
NotifierMaxNoSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource when a new presence subscribe is received, the server will send a 503 Response (Service Unavailable). The default value is 100. |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. |
|
ResourceManagerClassName |
The name of the |
Table 9-6 describes the attributes of the UA-ProfileEventPackage MBean.
Table 9-6 Attributes of the UA-Profile Event Package
| Attributes | Description/Value |
|---|---|
|
Description |
A description of the UA-ProfileEventPackage. The default value is The event package that enables the ua-profile. |
|
Document Factory |
The
|
|
Name |
The name of the event package. The default value is ua-profile. |
|
Notifier |
The name of the |
|
NotifierMaxDocumentSize |
The maximum document size for a SUBSCRIBE request. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 6000. |
|
NotifierMaxNoOfSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource when a new presence subscribe is received, the server will send a 503 Response (Service Unavailable). The default value is 100. |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. The default value is 60. |
|
ResourceManager |
The name of the Resource Manager class. The default value is:
|
The Command Service MBean enables user provisioning of the XDMS.
The XCapConfigManager MBean controls the configuration of the XDMS, the repository of the XML documents containing user presence rules and hard state information. The XCapConfigManager MBean settings can be ignored if the XDMS is external to the Presence Server.
Table 9-7 Attributes of the XCapConfigManager MBean
| Attribute Name | Description/Value |
|---|---|
|
CreateNonExistingUserstore |
Set to true to create a user store if one does not exist when storing a document; otherwise, set to false. If the parameter is set to false and a client tries to store a document for a user that does not exist, then the store fails. If the parameter is set to true, then the user will first be created in the XDMS and then the document will be stored. The default value is true. |
|
MaxContentLength |
The maximum size, in bytes, for an XCAP request. The default is 1MB. You can increase or decrease the size of the document. If you increase the document size, then you must be sure to that there is sufficient disk space to accommodate the XDMS document * the number of users * the number of applications. If you set a smaller per-document size, then this calculation is reduced to the sum of ( The default size for the resource-lists document is also 1 MB. |
|
PersistenceRootUrl |
The storage location for the XDMS documents. The default is jpa:xdms, which means documents will be persisted into an Oracle database through the JDBC connector configured during installation. To change the persistence location to filesystem, use a file url (for example, a value of file: |
|
PidfManipulationAuid |
The ID of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocname |
The document name for pidf manipulation application usage. For example: hardstate. The default value is hardstate. |
|
PresRulesAU |
The name of the pres-rules application usage. The default value is pres-rules. |
|
PresRulesDocName |
The name of the pres-rules document. The default value is presrules. |
|
PublicContentServerRootUrl |
The URL to the public content server root. The URL must be set to the public URL of the content server (that is, the URL of the authentication HTTP proxy server). |
|
PublicXCAPRootUrl |
The URL to the public XDMS root, entered as http://<your.xdms.domain.com>/services/. For example, enter http://127.0.0.1:8001/services. |
|
RequireAssertedIdentity |
Set to true if all HTTP/XDMS requests require an asserted identity header; otherwise, set this parameter to false. Setting this attribute to true requires all XCAP traffic to be authenticated by the Section 9.2.10, "Aggregation Proxy". If this attribute is set to true, then any incoming XCAP request that lacks an asserted identity is denied access. |
The Aggregation Proxy is a server-side entry point for XCAP clients and Web Service calls and will authenticate incoming traffic by providing identify assertion. This component acts as the gatekeeper for the trusted domain that houses the Presence Server and the XDMS.
The attributes of the Aggregation Proxy MBean (Table 9-8) enable you to set the type of identity assertion that is appropriate to the XDMS. In addition, you set the host and port of the Web Server and XDMS that receive the proxied traffic from the Aggregation Proxy.
Table 9-8 Attributes of the Aggregation Proxy
| Attribute | Description |
|---|---|
|
AssertedIdentityType |
Enter the number corresponding to the identity header inserted into proxied HTTP requests that is appropriate to the XDMS:
|
|
ContentHost |
host name of the Content Server where the Aggregation Proxy sends proxied requests. |
|
ContentPort |
The port number of the Content Server where the Aggregation Proxy sends proxied requests. |
|
ContentRoot |
The root URL of the Content Server. |
|
IgnoreUserpartCase |
Set to true if case-sensitive handling of the user name is not required. |
|
Realm |
Realm (for ex: example.com) that is used to create the sip/sips address that's inserted in the P-Asserted-Identity header. |
|
TrustedHosts |
A comma-separated list of IP addresses of trusted hosts. Asserted identity headers are removed from requests with addresses that are not included in this list. |
|
XCAPHost |
The host name of the XDMS to which the Aggregation Proxy proxies requests. |
|
XCAPPort |
The port of the XDMS to which the Aggregation Proxy proxies requests. |
|
XCAPRoot |
The root URL of the XDMS. |
Follow these steps to configure DAR for handling OPTIONS requests:
Open console application in your browser (for example: http://owlcs.example.com:7001/console).
Enter Username and Password to log in.
In the left pane, click Sip Server.
Click the Application Router tab.
Under AR configuration data, depending on whether you want to route the OPTIONS request through proxyregistrar, enter:
OPTIONS: ("proxyregistrar", "DAR:From", "TERMINATING", "", "NO_ROUTE", "0")
OR if you want the request to go through OPTIONSResponder application, enter:
OPTIONS : ("optionsresponder", "DAR:From", "TERMINATING", "", "NO_ROUTE",
"0")
Note:
Options Responder application should have been chosen while extending the domain if you choose the latter DAR configuration.OWLCS enables Web Service clients to access presence services through its support of the Parlay X Presence Web Service as defined in Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14. A Parlay X Web Service enables an HTTP Web Service client to access such presence services as publishing and subscribing to presence information. The Parlay X Presence Web Service does not require developers to be familiar with the SIP protocol to build such a Web-based client; instead, Parlay X enables Web developers to build this client using their knowledge of Web Services.
The Presence Web Services application contains the following MBeans that enable you to configure a Web Services deployment server:
The above MBeans contain attributes for managing presence publication and watcher subscriptions enabled through the OWLCS implementation of Presence Consumer and Presence Supplier interfaces.
The PresenceSupplierWebService MBean (described in Table 9-9) enables you to manage the presence data published to watchers. See Section 9.2.10, "Aggregation Proxy" for more information about aggregation proxy mbean configuration.
Table 9-9 Attributes of the PresenceSupplierWebService MBean
| Attributes | Description |
|---|---|
|
Expires |
The default expiry time, in seconds, for the PUBLISH of a presence status. The value entered for this attribute should be optimized to match that entered for the SessionTimeout attribute. |
|
PIDFManipulationAU |
The name of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocname |
The document name for pidf manipulation application usage. For example: hardstate. If the URI contains a domain name instead of an IP address, then you must configure the DNS Server. The default value is hardstate. Note that this value must match the value you entered when configuring XDMS. |
|
PresRulesAU |
The name of the pres-rules application usage. The default value is pres-rules. |
|
PresRulesDocname |
The name of the pres-rules document. The default value is presrules. |
|
PublicXCAPRootUrl |
The URL to the public XDMS root, entered as http://<your.xdms:domain.com>/services/. For example, enter http://127.0.0.1:8001/services. |
|
SessionTimeout |
The timeout of the HTTP session, in seconds. The value entered for this attribute should be optimized to match the value entered for the Expires attribute. This timeout takes effect for new sessions only. |
|
SIPOutboundProxy |
The IP address of the outbound proxy server where all requests are sent on the first hop. Enter this address in the following format:
You can also enter the default port (5060) in this address. For example, enter sip:127.0.0.1:5060;lr;transport=TCP. If you do not define this attribute, then no outbound proxy will be used. |
The PresenceConsumerWebService MBean (described in Table 9-10) enables you to set the duration of watcher subscriptions.
Table 9-10 Attributes of the PresenceConsumerWebService MBean
| Attribute | Value |
|---|---|
|
Expires |
The default expiry time, in seconds, for watcher subscriptions. The value entered for this attribute should be optimized to match the value entered for the SessionTimeout attribute. |
|
SessionTimeout |
The timeout of the HTTP session, in seconds. The value entered for this attribute should be optimized to match the value entered for the Expires attribute. This timeout takes effect for new sessions only. |
|
SIPOutboundProxy |
The IP address of the outbound proxy server where all requests are sent on the first hop. Enter this address in the following format:
You can also enter the default port (5060) in this address. For example, enter sip:127.0.0.1:5060;lr;transport=TCP. If you do not define this attribute, then no outbound proxy will be used. |
MessagingWebServiceConfig (described in Table 9-11) enables you to designate how and when to delete messages stored by the web service.
Table 9-11 MessagingWebServiceConfig attributes
| Attribute | Value |
|---|---|
|
SessionTimeout |
The timeout of the HTTP session, in seconds. The value entered for this attribute should be optimized to match the value entered for the Expires attribute. This timeout takes effect for new sessions only |
|
SIPOutboundProxy |
The IP address of the outbound proxy server where all requests are sent on the first hop. Enter this address in the following format:
If you do not define this attribute, then no outbound proxy will be used. |
|
MessageLifetime |
Set the time in seconds after which messages expire from the message store. Setting this to 0 will cause messages to be kept in the store indefinitely (never expire). Messages will stay in the message store for at a maximum MessageLifetime + MessageScanPeriod seconds. Setting this attribute has immediate effect (for instance, reducing the value could cause some messages to be immediately expired if they are older than the lifetime). |
|
MessageScanPeriod |
Set the period in seconds for scanning for and deleting expired messages. Setting this to 0 disables scanning. Setting this attribute has immediate effect. |