org.osid.ontology

Interface SubjectNotificationSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface SubjectNotificationSession
extends OsidSession

This session defines methods to receive asynchronous notifications on adds/changes to Subject objects. This session is intended for consumers needing to synchronize their state with this service without the use of polling. Notifications are cancelled when this session is closed.

The views defined in this session correspond to the views in the SubjectLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeSubjectNotification(Id notificationId) Acknowledge a subject notification.
boolean	canRegisterForSubjectNotifications() Tests if this user can register for Subject notifications.
Ontology	getOntology() Gets the Ontology associated with this session.
Id	getOntologyId() Gets the Ontology Id associated with this session.
void	registerForChangedSubject(Id subjectId) Registers for notification of an updated subject.
void	registerForChangedSubjectHierarchy() Registers for notification of an updated subject hierarchy structure.
void	registerForChangedSubjectHierarchyForAncestors(Id subjectId) Registers for notification of an updated subject hierarchy structure.
void	registerForChangedSubjectHierarchyForDescendants(Id subjectId) Registers for notification of an updated subject hierarchy structure.
void	registerForChangedSubjects() Registers for notification of updated subjects.
void	registerForDeletedSubject(Id subjectId) Registers for notification of a deleted subject.
void	registerForDeletedSubjects() Registers for notification of deleted subjects.
void	registerForNewSubjects() Register for notifications of new subjects.
void	reliableSubjectNotifications() Reliable notifications are desired.
void	unreliableSubjectNotifications() Unreliable notifications are desired.
void	useFederatedOntologyView() Federates the view for methods in this session.
void	useIsolatedOntologyView() Isolates the view for methods in this session.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getOntologyId

Id getOntologyId()

Gets the Ontology Id associated with this session.

Returns:

the Ontology Id associated with this session

Compliance:

mandatory - This method must be implemented.

getOntology

Ontology getOntology()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the Ontology associated with this session.

Returns:

the Ontology associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForSubjectNotifications

boolean canRegisterForSubjectNotifications()

Tests if this user can register for Subject notifications. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer notification operations.

Returns:

false if notification methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useFederatedOntologyView

void useFederatedOntologyView()

Federates the view for methods in this session. A federated view will include notifications for subjects in ontologies which are children of this ontology in the ontology hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedOntologyView

void useIsolatedOntologyView()

Isolates the view for methods in this session. An isolated view restricts notifications to this ontology only.

Compliance:

mandatory - This method is must be implemented.

reliableSubjectNotifications

void reliableSubjectNotifications()

Reliable notifications are desired. In reliable mode, notifications are to be acknowledged using acknowledgeSubjectNotification() .

Compliance:

mandatory - This method is must be implemented.

unreliableSubjectNotifications

void unreliableSubjectNotifications()

Unreliable notifications are desired. In unreliable mode, notifications do not need to be acknowledged.

Compliance:

mandatory - This method is must be implemented.

acknowledgeSubjectNotification

void acknowledgeSubjectNotification(Id notificationId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Acknowledge a subject notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewSubjects

void registerForNewSubjects()
                            throws OperationFailedException,
                                   PermissionDeniedException

Register for notifications of new subjects. SubjectReceiver.newSubjects() is invoked when a new subject is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSubjects

void registerForChangedSubjects()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of updated subjects. SubjectReceiver.changedSubjects() is invoked when a subject is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSubject

void registerForChangedSubject(Id subjectId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of an updated subject. SubjectReceiver.changedSubjects() is invoked when the specified subject is changed.

Parameters:

subjectId - the Id of the Subject to monitor

Throws:

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedSubjects

void registerForDeletedSubjects()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of deleted subjects. SubjectReceiver.deletedSubjects() is invoked when a subject is removed from this ontology.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedSubject

void registerForDeletedSubject(Id subjectId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of a deleted subject. SubjectReceiver.changedSubjects() is invoked when the specified subject is removed from this ontology.

Parameters:

subjectId - the Id of the Subject to monitor

Throws:

NullArgumentException - subjectid is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSubjectHierarchy

void registerForChangedSubjectHierarchy()
                                        throws OperationFailedException,
                                               PermissionDeniedException

Registers for notification of an updated subject hierarchy structure. SubjectReceiver.changedChildOfSubjects() is invoked when a node experiences a change in its children.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSubjectHierarchyForAncestors

void registerForChangedSubjectHierarchyForAncestors(Id subjectId)
                                                    throws OperationFailedException,
                                                           PermissionDeniedException

Registers for notification of an updated subject hierarchy structure. SubjectReceiver.changedChildOfSubjects() is invoked when the specified node or any of its ancestors experiences a change in its children.

Parameters:

subjectId - the Id of the Subject node to monitor

Throws:

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSubjectHierarchyForDescendants

void registerForChangedSubjectHierarchyForDescendants(Id subjectId)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

Registers for notification of an updated subject hierarchy structure. SubjectReceiver.changedChildOfSubjects() is invoked when the specified node or any of its descendants experiences a change in its children.

Parameters:

subjectId - the Id of the Subject node to monitor

Throws:

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.