com.ibm.soa.parlayx21.presence
Interface PresenceSupplier

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
PresenceSupplier_RI
All Known Implementing Classes:
PresenceSupplierBindingStub, PresenceSupplierProxy

public interface PresenceSupplier
extends java.rmi.Remote

The interface containing the operations of the presence supplier.

These methods are used by the presentity to supply presence data and manage access to the data by its watchers. We assume that the presentity has been previously authenticated, so that his Identity is known.

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.


Method Summary
 void blockSubscription(java.net.URI watcher)
          With this operation the presentity can block entirely the flow of presence information to a certain subscribed watcher by cancelling the subscription.
 java.net.URI[] getMyWatchers()
          Returns an array of watching identities that are subscribed to the presentity's attributes.
 SubscriptionRequest[] getOpenSubscriptions()
          Called periodically by the presentity to see if any watcher wants to subscribe to presence data.
 PresenceAttributeType[] getSubscribedAttributes(java.net.URI watcher)
          Returns an array of attributes that a specific watcher has subscribed.
 void publish(PresenceAttribute[] presence)
          The presentity publishes data about herself.
 void updateSubscriptionAuthorization(java.net.URI watcher, PresencePermission[] decisions)
          The presentity answers with this operation to watcher subscriptions for which no authorization policy exists.
 

Method Detail

publish

void publish(PresenceAttribute[] presence)
             throws java.rmi.RemoteException,
                    PolicyException,
                    ServiceException

The presentity publishes data about herself. This data will then be filtered by the system and forwarded to the watchers who have ordered notifications.

Parameters:
presence - PresenceAttribute [0..unbounded]

The presence attributes the devices of the presentity supports.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getOpenSubscriptions

SubscriptionRequest[] getOpenSubscriptions()
                                           throws java.rmi.RemoteException,
                                                  PolicyException,
                                                  ServiceException

Called periodically by the presentity to see if any watcher wants to subscribe to presence data. The client will answer open requests with updateSubscriptionAuthorization().

Referenced faults

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

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

Returns:
getOpenSubscriptionsResponse result SubscriptionRequest [0..unbounded]

Any open requests.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

updateSubscriptionAuthorization

void updateSubscriptionAuthorization(java.net.URI watcher,
                                     PresencePermission[] decisions)
                                     throws java.rmi.RemoteException,
                                            PolicyException,
                                            ServiceException

The presentity answers with this operation to watcher subscriptions for which no authorization policy exists. The answer consists of the attribute and the watcher involved and the permissions for each attribute. Subscription requests that are not answered are assumed pending.

The operation can be used by the presentity to change anytime the authorization for a certain watcher or group to monitor one or several attributes.

If the watcher did not try to subscribe the attribute - for example, there is no pending subscription from this watcher to an attribute in the decisions array, a Presence-specific ServiceException (SVC0220) will be raised and the entire authorization request ignored.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses.
  * SVC0220: No subscription request.

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

Parameters:
watcher - xsd:anyURI

watcher or group of watchers.

decisions - PresencePermission [1..unbounded]

The answers to open requests.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getMyWatchers

java.net.URI[] getMyWatchers()
                             throws java.rmi.RemoteException,
                                    PolicyException,
                                    ServiceException

Returns an array of watching identities that are subscribed to the presentity's attributes. They are not necessarily users of the notification system, the mere fact that they are allowed to see the presentity's attributes is enough to be on this list.

Referenced faults

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

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

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

The list of identities who currently have access to the presentity's attributes.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getSubscribedAttributes

PresenceAttributeType[] getSubscribedAttributes(java.net.URI watcher)
                                                throws java.rmi.RemoteException,
                                                       PolicyException,
                                                       ServiceException

Returns an array of attributes that a specific watcher has subscribed.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0004: No valid addresses.
  * SVC0221: Not a watcher - if the URI in the watcher part is not a watcher of the presentity.

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

Parameters:
watcher - xsd:anyURI

The watcher whose subscriptions the presentity wants to know.

Returns:
result PresenceAttributeType [0..unbounded]

The attributes the watcher is subscribed to.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

blockSubscription

void blockSubscription(java.net.URI watcher)
                       throws java.rmi.RemoteException,
                              PolicyException,
                              ServiceException

With this operation the presentity can block entirely the flow of presence information to a certain subscribed watcher by cancelling the subscription. The watcher will be notified with a subscriptionEnded() message.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses.
  * SVC0221: Not a watcher - if the URI in the watcher part is not a watcher of the presentity.

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

Parameters:
watcher - xsd:anyURI

The watcher whose subscriptions the presentity wants to cancel.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.