com.ibm.soa.parlayx21.presence
Class PresenceConsumerBindingStub

java.lang.Object
  extended by com.ibm.ws.webservices.engine.client.Stub
      extended by com.ibm.soa.parlayx21.presence.PresenceConsumerBindingStub
All Implemented Interfaces:
PresenceConsumer, java.rmi.Remote, javax.xml.rpc.Stub

public class PresenceConsumerBindingStub
extends com.ibm.ws.webservices.engine.client.Stub
implements PresenceConsumer


Nested Class Summary
 
Nested classes/interfaces inherited from class com.ibm.ws.webservices.engine.client.Stub
com.ibm.ws.webservices.engine.client.Stub.Invoke
 
Field Summary
 
Fields inherited from class com.ibm.ws.webservices.engine.client.Stub
cachedEndpoint, cachedhttpProxyHost, cachedhttpProxyPassword, cachedhttpProxyPort, cachedhttpProxyUser, cachedhttpRedirectEnabled, cachedhttpsProxyHost, cachedhttpsProxyPassword, cachedhttpsProxyPort, cachedhttpsProxyUser, cachedPassword, cachedPortName, cachedProperties, cachedRequestSoapHeaders, cachedRequestTransportHeaders, cachedResponseSoapHeaders, cachedResponseSoapHeaderTemplates, cachedResponseTransportHeaders, cachedResponseTransportHeadersTemplate, cachedSessionContext, cachedsslCfgName, cachedTimeout, cachedUsername, cachedWriteTimeout, connection, engine, maintainSession, maintainSessionSet, messageContexts, service
 
Fields inherited from interface javax.xml.rpc.Stub
ENDPOINT_ADDRESS_PROPERTY, PASSWORD_PROPERTY, SESSION_MAINTAIN_PROPERTY, USERNAME_PROPERTY
 
Constructor Summary
PresenceConsumerBindingStub(java.net.URL endpointURL, javax.xml.rpc.Service service)
           
 
Method Summary
 void endPresenceNotification(java.lang.String correlator)
          Indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator).
 PresenceAttribute[] getUserPresence(java.net.URI presentity, PresenceAttributeType[] attributes)
          Returns the aggregated presence data of a presentity.
 java.net.URI[] startPresenceNotification(java.net.URI presentity, PresenceAttributeType[] attributes, SimpleReference reference, TimeMetric frequency, TimeMetric duration, java.lang.Integer count, boolean checkImmediate)
          The notification pattern with correlation is used in order to be able to correlate the notification events with the request.
 void subscribePresence(java.net.URI presentity, PresenceAttributeType[] attributes, java.lang.String application, SimpleReference reference)
          We assume that the watcher has been previously authenticated, so that his identity is known and can be associated with the subscription at the server.
 
Methods inherited from class com.ibm.ws.webservices.engine.client.Stub
_getProperty, _getPropertyNames, _setProperty, convert, getPassword, getPortName, getTimeout, getTypeMapping, getUsername, primeMessageContext, setMaintainSession, setPassword, setPortName, setPortName, setTimeout, setUsername, setWriteTimeout, validateSoapHeadersHashMap, validateTransportPropertiesHashMap
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PresenceConsumerBindingStub

public PresenceConsumerBindingStub(java.net.URL endpointURL,
                                   javax.xml.rpc.Service service)
                            throws com.ibm.ws.webservices.engine.WebServicesFault
Throws:
com.ibm.ws.webservices.engine.WebServicesFault
Method Detail

subscribePresence

public void subscribePresence(java.net.URI presentity,
                              PresenceAttributeType[] attributes,
                              java.lang.String application,
                              SimpleReference reference)
                       throws java.rmi.RemoteException,
                              PolicyException,
                              ServiceException
Description copied from interface: PresenceConsumer

We assume that the watcher has been previously authenticated, so that his identity is known and can be associated with the subscription at the server.

The presentity is contacted and requested to authorize the watcher. As this process generally involves user interaction there cannot be an immediate response. The watcher is notified with notifySubscription(). If the presentity is a group, every member of the group will be contacted for authorization. The watcher will get one notification for each member.

Only after the subscription is completed (and the presentity has allowed access to attributes) may the watcher will get information when he uses getUserPresence() or startPresenceNotification().

Note that the SimpleReference contains the correlator string used in subsequent messages to the notification interface.

At this interface level, the subscription has no expiration, although at can be ended from the presentity of or the underlying layers (see subscriptionEnded operation).

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity address does not exist.

PolicyException from ES 202 391-1 [3]:
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.

Specified by:
subscribePresence in interface PresenceConsumer
Parameters:
presentity - xsd:anyURI

A presentity or a group of presentities whose attributes the watcher wants to monitor.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to access. (the same for all the group members). An empty array means subscription of all attributes.

application - xsd:string

Describes the application the watcher needs the data for.

reference - common:SimpleReference

The notification interface.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getUserPresence

public PresenceAttribute[] getUserPresence(java.net.URI presentity,
                                           PresenceAttributeType[] attributes)
                                    throws java.rmi.RemoteException,
                                           PolicyException,
                                           ServiceException
Description copied from interface: PresenceConsumer

Returns the aggregated presence data of a presentity. Only the attributes which the watcher is entitled to see will be returned. This method does not support group identities.

Before getting these attributes, the watcher has to subscribe to them (see above). The presentity needs not be informed of the access, as he has already consented when the watcher called subscribePresence().

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity address does not exist.

PolicyException from ES 202 391-1 [3]. The presentity has the possibility to cancel or block a subscription by manipulating the policy rules. The exception informs the watcher about this status change.
  * POL0002: Privacy error - if the watcher is not subscribed to the requested data.
  * POL0006: Groups not allowed.

Specified by:
getUserPresence in interface PresenceConsumer
Parameters:
presentity - xsd:anyURI

The presentity whose data the watcher wants to see.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to see. An empty array means all attributes.

Returns:
result PresenceAttribute [0..unbounded]

The actual presence data.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

startPresenceNotification

public java.net.URI[] startPresenceNotification(java.net.URI presentity,
                                                PresenceAttributeType[] attributes,
                                                SimpleReference reference,
                                                TimeMetric frequency,
                                                TimeMetric duration,
                                                java.lang.Integer count,
                                                boolean checkImmediate)
                                         throws java.rmi.RemoteException,
                                                PolicyException,
                                                ServiceException
Description copied from interface: PresenceConsumer

The notification pattern with correlation is used in order to be able to correlate the notification events with the request. The attributes represent a subset of the attributes subscribed and can be used as filter.

The watcher sets a notification trigger on certain user presence attribute changes. If the list of attributes is empty, the watcher wants to be notified on all subscribed attributes.

In case the presentity is a group the watcher will receive notifications for every single member of the group. The watcher will only get notifications for those attributes and presentities he subscribed successfully prior to the call. The service will return a list of presentities where the notifications could not be set up.

The presentity needs not be informed of the access, as he has already consented when the watcher called subscribePresence().

Note that the SimpleReference contains the correlator string used in subsequent messages to the notification interface.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity URI does not exist.
  * SVC0005: Duplicate correlator.

PolicyException from ES 202 391-1 [3]. The presentity has the possibility to cancel or block a subscription by manipulating the policy rules. The exception informs the watcher about this status change.
  * POL0001: Policy error.
  * POL0004: Unlimited notifications not supported.
  * POL0005: Too many notifications requested.
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.

Specified by:
startPresenceNotification in interface PresenceConsumer
Parameters:
presentity - xsd:anyURI

The presentity or group whose attributes the watcher wants to monitor.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to see.

reference - common:SimpleReference

The notification interface.

frequency - common:TimeMetric

Maximum frequency of notifications (can also be considered minimum time between notifications). In case of a group subscription the service must make sure this frequency is not violated by notifications for various members of the group, especially in combination with checkImmediate.

duration - common:TimeMetric

Length of time notifications occur for, do not specify to use default notification time defined by service policy.

count - xsd:int

Maximum number of notifications.For no maximum, either do not specify this part or specify a value of zero.

checkImmediate - xsd:boolean

Whether to check status immediately after establishing notification.

Returns:
result xsd:anyURI [0..unbounded]

The presentities whose attributes the watcher did not subscribe. Empty if all went fine.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

endPresenceNotification

public void endPresenceNotification(java.lang.String correlator)
                             throws java.rmi.RemoteException,
                                    PolicyException,
                                    ServiceException
Description copied from interface: PresenceConsumer

Indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator). Note that the subscription to presence data stays active; the caller of this method remains a watcher and can still use getUserPresence() or reactivate the notifications.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [3]:
  * POL0001: Policy error.

Specified by:
endPresenceNotification in interface PresenceConsumer
Parameters:
correlator - xsd:string

The notification the watcher wants to cancel.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.