com.sapportals.wcm.repository.service.subscription
Interface ISubscription

[contained in: com.sap.km.cm.repository.service.par - km.shared.repository.service.app.subscription_api.jar]

public interface ISubscription

Represents a single subscription and provides methods to define, modify and access the details of a subscription.

Important details of a subscription are the:
- resources that are subscribed to
- recipients who get notifications
- channel that is used to communicate with recipients
- attributes that define a notification text, notification interval, expiry date and next send date for a notification
- condition that specifies the events carried out on a resource that are relevant for the subscription, for example, deletion. It also sets an interval at which resources are checked and notifications are sent. In the case of a collection, it also specifies how many levels of the hierarchy (recursion level) are relevant for the subscription.

The ISubscriptionManageradministrates all existing subscriptions.
Only the owner of a subscription or an administrator can change or delete a subscription. The owner is the user taken from the IResourceContext that is specified when the createSubscription or getSubscription methods of the ISubscriptionManager are called.

The code sample creates a subscription and finds out whether a user has subscribed:

 
 ISubscription subscription = subscriptionManager.createSubscription(context,
                                                                     name,
                                                                     condition,
                                                                     resources,
                                                                     channel,
                                                                     recipients,
                                                                     attributes);

 public boolean isUserSubscribed(IRecipient user) {
   return subscription.isUnsubscribed(user);
 }
 
 

Copyright (c) SAP AG

See Also:

ISubscriptionManager, IRecipient, IChannel, IResource, ISubscriptionCondition, ISubscriptionAttributes

Method Summary

void	addRecipient(IRecipient recipient) Adds a recipient to the subscription.
void	addResource(IResource resource) Adds a resource to the subscription.
void	delete() Deletes the subscription.
ISubscriptionAttributes	getAttributes() Gets the customizable attributes (like expiration date) of the subscription.
IChannel	getChannel() Gets the channel that is used for sending notifications to the recipients.
ISubscriptionCondition	getCondition() Gets the conditions (subscribed event, follow link, interval, RID tracking and recursion level) which leads to a notification for the subscription.
java.lang.String	getID() Gets the ID of the subscription.
java.util.Date	getLastCheckDate() Gets the last date the subscription was checked for changes.
java.util.Date	getLastModifiedDate() Gets the date of the last modification of the subscription.
ISubscriptionManager	getManager() Gets the subscription manager for this subscription.
java.lang.String	getName() Gets the name of the subscription that is displayed.
java.lang.String	getOwner() Gets the owner of the subscription.
IRecipientList	getRecipients() Gets the recipients of the subscription notifications.
IResourceList	getResources() Gets the resources assigned to the subscription.
IRidList	getRIDs() Gets the RIDs of the resources assigned to the subscription.
IRecipientList	getSubscribedRecipients() Gets the recipients of the subscription that have not unsubscribed.
IRecipientList	getUnsubscribedRecipients() Gets the recipients of the subscription that have unsubscribed.
IUriList	getURIs() Deprecated. As of EP 5.0 SP2, replaced by getRIDs()
boolean	isOnlyRecipient(IRecipient recipient) Checks if a recipient is the only recipient of a subscription.
boolean	isOnlyResource(IResource resource) Checks if a resource is the only resource of a subscription.
boolean	isUnsubscribed() Checks whether all recipients are unsubscribed.
boolean	isUnsubscribed(IRecipient recipient) Checks whether a recipient is unsubscribed.
boolean	isValidChannel(IChannel channel) Checks if a given channel is valid for this subscription's recipients.
boolean	isValidCondition(ISubscriptionCondition condition) Checks if a specified condition is valid for this subscription.
boolean	removeRecipient(IRecipient recipient) Removes a recipient from the subscription.
boolean	removeResource(IResource resource) Removes a resource from the subscription.
void	resetRecipient(IRecipient recipient) Reactivates all unsubscribed recipients for this subscription.
void	resetRecipients(IRecipientList recipientList) Resets recipients for the subscription notifications.
ISubscription	set(ISubscriptionCondition condition, IResource resource, IChannel channel, IRecipient recipient, ISubscriptionAttributes attributes) Changes or sets multiple parameters for a subscription in one operation.
ISubscription	set(ISubscriptionCondition condition, IResource resource, IChannel channel, IRecipientList recipients, ISubscriptionAttributes attributes) Changes or sets multiple parameters for a subscription in one operation.
ISubscription	set(ISubscriptionCondition condition, IResourceList resources, IChannel channel, IRecipient recipient, ISubscriptionAttributes attributes) Changes or sets multiple parameters for a subscription in one operation.
ISubscription	set(ISubscriptionCondition condition, IResourceList resources, IChannel channel, IRecipientList recipients, ISubscriptionAttributes attributes) Changes or sets multiple parameters for a subscription in one operation.
void	setAttributes(ISubscriptionAttributes attributes) Sets the customizable attributes of a subscription.
void	setChannel(IChannel channel) Sets the channel to use for sending notifications to the recipients.
void	setCondition(ISubscriptionCondition condition) Sets the subscription conditions (subscribed event, follow link, interval, RID tracking and recursion level) for which the subscription sends notifications.
void	setName(java.lang.String newName) Renames a subscription to a given new name.
boolean	setOwner(IRecipient newOwner) Sets a new owner for this subscription.
void	setRecipient(IRecipient recipient) Resets the subscription's recipient.
void	setRecipients(IRecipientList recipientList) Resets the subscription's recipients.
void	setResource(IResource resource) Resets the subscription's resource.
void	setResources(IResourceList resourceList) Resets the subscription's resources.
void	unsubscribe(IRecipient recipient) Unsubscribes a recipient and stops the subscription notifications for this recipient.

Method Detail

getManager

public ISubscriptionManager getManager()

Gets the subscription manager for this subscription.

Returns:

an ISubscriptionManager that manages this subscription

getID

public java.lang.String getID()

Gets the ID of the subscription.

Returns:

a String with the unique ID for this subscription and manager
The IDs must be unique for each manager.

getName

public java.lang.String getName()
                         throws WcmException

Gets the name of the subscription that is displayed.

Returns:

a String with a (displayable) name for this subscription.
The name is unique for each owner and manager.

Throws:

WcmException - if the operation fails

setName

public void setName(java.lang.String newName)
             throws WcmException

Renames a subscription to a given new name.

Parameters:

newName - The new name of the subscription.

Throws:

WcmException - if the operation fails

getOwner

public java.lang.String getOwner()
                          throws WcmException

Gets the owner of the subscription.

Owner of the subscription is the user from the context that is passed to the ISubscriptionManagers createSubscription(...) method while creating this subscription.

Returns:

a String with the ID of the user who owns (created) this subscription

Throws:

WcmException - if the operation fails.

getLastModifiedDate

public java.util.Date getLastModifiedDate()
                                   throws WcmException

Gets the date of the last modification of the subscription.
The last time a recipient, resource, attribute, channel or condition was added or changed for the subscription

Returns:

a Date with the timestamp of the last modification of the subscription

getLastCheckDate

public java.util.Date getLastCheckDate()
                                throws WcmException

Gets the last date the subscription was checked for changes.

Returns:

a Date with the timestamp of the last check for the subscription

Throws:

WcmException - if the operation fails

set

public ISubscription set(ISubscriptionCondition condition,
                         IResource resource,
                         IChannel channel,
                         IRecipient recipient,
                         ISubscriptionAttributes attributes)
                  throws WcmException

Changes or sets multiple parameters for a subscription in one operation.

If null is specified for a parameter, the subscription's current values are used.

Parameters:

condition - an ISubscriptionCondition with the condition to use for this subscription

resource - an IResource to be assigned to this subscription

channel - an IChannel to use for sending notifications

recipient - an IRecipient to send subscription notifications to

attributes - the ISubscriptionAttributes to use for this subscription

Returns:

the ISubscription, with the new attributes

Throws:

WcmException - if the operation fails

set

public ISubscription set(ISubscriptionCondition condition,
                         IResourceList resources,
                         IChannel channel,
                         IRecipient recipient,
                         ISubscriptionAttributes attributes)
                  throws WcmException

Changes or sets multiple parameters for a subscription in one operation.

If null is specified for a parameter, the subscription's current values are used.

Parameters:

condition - an ISubscriptionCondition with the condition to use for this subscription

resources - an IResourceList with a list of resources to be assigned to this subscription

channel - an IChannel to use for sending notifications

recipient - an IRecipient to send subscription notifications to

attributes - the ISubscriptionAttributes to use for this subscription

Returns:

the ISubscription, with the new attributes

Throws:

WcmException - if the operation fails

set

public ISubscription set(ISubscriptionCondition condition,
                         IResource resource,
                         IChannel channel,
                         IRecipientList recipients,
                         ISubscriptionAttributes attributes)
                  throws WcmException

Changes or sets multiple parameters for a subscription in one operation.

If null is specified for a parameter, the subscription's current values are used.

Parameters:

condition - an ISubscriptionCondition with the condition to use for this subscription

resource - an IResource to be assigned to this subscription

channel - an IChannel to use for sending notifications

recipients - an IRecipientList of recipients to send subscription notifications to

attributes - the ISubscriptionAttributes to use for this subscription

Returns:

the ISubscription, with the new attributes

Throws:

WcmException - if the operation fails

set

public ISubscription set(ISubscriptionCondition condition,
                         IResourceList resources,
                         IChannel channel,
                         IRecipientList recipients,
                         ISubscriptionAttributes attributes)
                  throws WcmException

Changes or sets multiple parameters for a subscription in one operation.

If null is specified for a parameter, the subscription's current values are used.

Parameters:

condition - an ISubscriptionCondition with the conditions to use for this subscription

resources - an IResourcesList with a list of resources to be assigned to this subscription

channel - an IChannel to use for sending notifications

recipient - an IRecipientList with a list of recipients to send subscription notifications to

attributes - the ISubscriptionAttributes to use for this subscription

Returns:

an ISubscription, with the new attributes

Throws:

WcmException - if the operation fails

getAttributes

public ISubscriptionAttributes getAttributes()
                                      throws WcmException

Gets the customizable attributes (like expiration date) of the subscription.

Returns:

the ISubscriptionAttributes, as the set of customizable attributes for this subscription

Throws:

WcmException - if the operation fails

setAttributes

public void setAttributes(ISubscriptionAttributes attributes)
                   throws WcmException

Sets the customizable attributes of a subscription.

Parameters:

attributes - the ISubscriptionAttributes to use for this subscription

Throws:

WcmException - if the operation fails

getCondition

public ISubscriptionCondition getCondition()
                                    throws WcmException

Gets the conditions (subscribed event, follow link, interval, RID tracking and recursion level) which
leads to a notification for the subscription.

Returns:

an ISubscriptionCondition with the conditions used by this subscription

Throws:

WcmException - if the operation fails

isValidCondition

public boolean isValidCondition(ISubscriptionCondition condition)
                         throws WcmException

Checks if a specified condition is valid for this subscription.

If parameter condition is null the default ISubscriptionCondition values for the first subscribed resource are taken.

Parameters:

condition - an ISubscriptionCondition to check against this subscription's conditions

Returns:

boolean true if the condition is valid for this subscription,
false if not

Throws:

WcmException - if the operation fails

setCondition

public void setCondition(ISubscriptionCondition condition)
                  throws WcmException

Sets the subscription conditions (subscribed event, follow link, interval, RID tracking and recursion level) for which the subscription sends notifications.

If parameter condition is null the default ISubscriptionCondition values of the first subscribed resource are used

Parameters:

condition - an ISubscriptionCondition with the condition to use for this subscription

Throws:

WcmException - if the operation fails

setOwner

public boolean setOwner(IRecipient newOwner)
                 throws WcmException

Sets a new owner for this subscription.

Parameters:

newOwner - an IRecipient who is the new owner of this subscription

Returns:

true if the new user could be set. false if the new owner could not be set to this subscription. This might be the case if the new owner has already a subscription with the name of this subscription.

Throws:

WcmException - if the operation fails

getURIs

public IUriList getURIs()
                 throws WcmException

Deprecated. As of EP 5.0 SP2, replaced by getRIDs()

Gets the URIs of the resources assigned to the subscription.

The list might contain null values for the URIs belonging to a resource that was subscribed to but is now deleted or hidden.

Deprecated: Please use getRIDs() instead.

Returns:

an IUriLists with the URIs of the resources assigned to this subscription

Throws:

WcmException - if the operation fails

getRIDs

public IRidList getRIDs()
                 throws WcmException

Gets the RIDs of the resources assigned to the subscription.

The list might contain null values for the RIDs belonging to a resource that was subscribed to but is now deleted or hidden.

Returns:

an IRidLists with the RIDs of the resources assigned to this subscription

Throws:

WcmException - if the operation fails

getResources

public IResourceList getResources()
                           throws WcmException

Gets the resources assigned to the subscription.

Please note: The list might contain null values for resources that are subscribed to but have been deleted or are invisible.

Returns:

an IResourceLists with the resources assigned to this subscription

Throws:

WcmException - if the operation fails

setResources

public void setResources(IResourceList resourceList)
                  throws WcmException

Resets the subscription's resources.

Resources that have already been subscribed to are deleted.

Parameters:

resourceList - an IResourceLists of resources to be assigned to this subscription

Throws:

WcmException - if the operation fails

setResource

public void setResource(IResource resource)
                 throws WcmException

Resets the subscription's resource.

Resources that have already been subscribed to are deleted.

Parameters:

resource - an IResources to be assigned to this subscription

Throws:

WcmException - if the operation fails

addResource

public void addResource(IResource resource)
                 throws WcmException

Adds a resource to the subscription.

Parameters:

resource - an IResource to add to the subscription's resources

Throws:

WcmException - if the operation failed or the parameter was null.

SubscriptionException - with type NOACCESS, if the user taken from the context does not own the subscription,
UNKNOWN_ID, if the subscription has already been deleted,
INVALID_CONDITION if the condition of the subscription will become invalid due to this resource

isOnlyResource

public boolean isOnlyResource(IResource resource)
                       throws WcmException

Checks if a resource is the only resource of a subscription.

Parameters:

resource - an IResource that should be checked to see if it is the only resource for the subscription in question

Returns:

a boolean true if the resource is the only one assigned to the subscription

Throws:

WcmException - if the operation failed.

removeResource

public boolean removeResource(IResource resource)
                       throws WcmException

Removes a resource from the subscription.

The entire subscription is also deleted if the resource is the last resource for this subscription
If parameter resource is null, false is returned

Parameters:

resource - an IResource with the resource object to be removed from the subscription

Returns:

a boolean true if the entire subscription was deleted, false if only the resource was removed from the subscription or the parameter resource was null

Throws:

WcmException - if the operation failed

getChannel

public IChannel getChannel()
                    throws WcmException

Gets the channel that is used for sending notifications to the recipients.

Returns:

an IChannel that is used for sending notifications on this subscription

Throws:

WcmException - if the operation fails

isValidChannel

public boolean isValidChannel(IChannel channel)
                       throws WcmException

Checks if a given channel is valid for this subscription's recipients.

If a subscribed recipient is not valid for the given channel, the check fails.
If parameter channel is null, the channel of the subscription's owner is used.

Parameters:

channel - an IChannel to check against the recipients of this subscription

Returns:

boolean true if the channel is valid for this subscription's recipients,
false if not

Throws:

WcmException - if the operation fails

setChannel

public void setChannel(IChannel channel)
                throws WcmException

Sets the channel to use for sending notifications to the recipients.

If parameter channel is null the channel of the subscription's owner is used.

Parameters:

channel - an IChannel to use for sending notifications

Throws:

WcmException - if the operation fails

getRecipients

public IRecipientList getRecipients()
                             throws WcmException

Gets the recipients of the subscription notifications.

Unsubscribed recipients are not added to the list and groups are not resolved into members.

Returns:

an IRecipientList of active recipients for this subscription

Throws:

WcmException - if the operation fails

getSubscribedRecipients

public IRecipientList getSubscribedRecipients()
                                       throws WcmException

Gets the recipients of the subscription that have not unsubscribed.

All unsubscribed recipients of the subscription do not appear in the list.

Returns:

an IRecipientList of recipients assigned to this subscription

Throws:

WcmException - if the operation fails

getUnsubscribedRecipients

public IRecipientList getUnsubscribedRecipients()
                                         throws WcmException

Gets the recipients of the subscription that have unsubscribed.

All subscribed recipients of the subscription do not appear in the list.

Returns:

an IRecipientList with recipients who are no longer assigned to this subscription

Throws:

WcmException - if the operation fails

setRecipients

public void setRecipients(IRecipientList recipientList)
                   throws WcmException

Resets the subscription's recipients.

Recipients that already belong to the subscription are deleted if they are not in the given IRecipientList.
Recipients that occur in the new IRecipientList and already belonged to this subscription keep their unsubscribe flag, if they were unsubscribed.

Parameters:

recipientList - an IRecipientList with recipients to send the subscription notifications to

Throws:

WcmException - if the operation fails

setRecipient

public void setRecipient(IRecipient recipient)
                  throws WcmException

Resets the subscription's recipient.

Recipients that already belong to the subscription are deleted.
If the given recipient already belongs to the subscription and was unsubscribed, he stays unsubscribed.

Parameters:

recipient - an IRecipient to send subscription notifications to

Throws:

WcmException - if the operation fails

resetRecipients

public void resetRecipients(IRecipientList recipientList)
                     throws WcmException

Resets recipients for the subscription notifications.

Use this method to reactivate unsubscribed recipients.
If parameter recipientList is null, the subscription owner is used.

Parameters:

recipientList - an IRecipientList with recipients to send the subscription notifications to

Throws:

WcmException - if the operation fails

SubscriptionException - with INVALID_CHANNEL if the channel of the subscription is invalid for the reactivated recipients.

resetRecipient

public void resetRecipient(IRecipient recipient)
                    throws WcmException

Reactivates all unsubscribed recipients for this subscription.

Use this method to reactivate an unsubscribed recipient.
If parameter recipient is null, the subscription owner is used.

Parameters:

recipient - an unsubscribed IRecipient that should now receive subscription notifications again

Throws:

WcmException - if the operation fails

addRecipient

public void addRecipient(IRecipient recipient)
                  throws WcmException

Adds a recipient to the subscription.

Parameters:

recipient - an IRecipient to add to the recipient list of this subscription

Throws:

WcmException - if the operation fails

SubscriptionException - with type
NOACCESS, if the user taken from the context does not own the subscription,
UNKNOWN_ID, if the subscription has already been deleted,
INVALID_CHANNEL if the channel of the subscription will become invalid due to this recipient.

isOnlyRecipient

public boolean isOnlyRecipient(IRecipient recipient)
                        throws WcmException

Checks if a recipient is the only recipient of a subscription.

If parameter recipient is null, the subscription owner is checked.

Parameters:

recipient - an IRecipient that should be checked to see if it's the only recipient for the subscription in question

Returns:

a boolean true if the recipient is the only one assigned to the subscription

Throws:

WcmException - if the operation fails

removeRecipient

public boolean removeRecipient(IRecipient recipient)
                        throws WcmException

Removes a recipient from the subscription.

The entire subscription is also deleted if the recipient is the last recipient of this subscription.
If parameter recipient is null the subscription owner is used.

Parameters:

recipient - an IRecipient that should be removed from this subscription

Returns:

a boolean true if the entire subscription is deleted,
false if only the given recipient is removed from the subscription

Throws:

WcmException - if the operation fails

isUnsubscribed

public boolean isUnsubscribed()
                       throws WcmException

Checks whether all recipients are unsubscribed.

Returns:

boolean true if all recipients of this subscription are already unsubscribed

Throws:

WcmException - if the operation fails

isUnsubscribed

public boolean isUnsubscribed(IRecipient recipient)
                       throws WcmException

Checks whether a recipient is unsubscribed.

If parameter recipient is null the owner of the subscription is checked.

Parameters:

recipient - an IRecipient with the recipient to be checked to see if he is unsubscribed

Returns:

a boolean true if the recipient is not found in the list of the subscription's recipients or if the recipient is marked as unsubscribed,
false if the recipient is still subscribed to this subscription

Throws:

WcmException - if the operation fails

unsubscribe

public void unsubscribe(IRecipient recipient)
                 throws WcmException

Unsubscribes a recipient and stops the subscription notifications for this recipient.

Unsubscribed recipients remain in the recipient list of the subscription but are marked as unsubscribed.
A unsubscribed recipient no longer receives notifications on this subscription.
The cancellation of the subscription for the IRecipient is possible with the resetRecipient(IRecipient) method.
If parameter recipient is null subscription owner is used.

Parameters:

recipient - an IRecipient to be unsubscribed

Throws:

WcmException - if the operation fails.

delete

public void delete()
            throws WcmException

Deletes the subscription.

A deletion (or any other change method) can only be initiated by the owner of the subscription (the user taken from the context on the manager's createSubscription()) or an adminstrative user.

Throws:

WcmException - if the deletion fails

SubscriptionException - with type NOACCESS, if the user taken from the context does not own the subscription,
UNKNOWN_ID, if the subscription has already been deleted