org.osid.journaling

Interface BranchNotificationSession

All Superinterfaces:

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

public interface BranchNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Branch objects in this Journal. This also includes existing branches that may appear or disappear due to changes in the Journal hierarchy, 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 two views defined in this session correspond to the views in the BranchLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeBranchNotification(Id notificationId) Acknowledge a branch notification.
boolean	canRegisterForBranchNotifications() Tests if this user can register for Branch notifications.
Journal	getJournal() Gets the Journal associated with this session.
Id	getJournalId() Gets the Journal Id associated with this session.
void	registerForChangedBranch(Id branchId) Registers for notification of an updated branch.
void	registerForChangedBranches() Registers for notification of updated branches.
void	registerForDeletedBranch(Id branchId) Registers for notification of a deleted branch.
void	registerForDeletedBranches() Registers for notification of deleted branches.
void	registerForNewBranches() Register for notifications of new branches.
void	reliableBranchNotifications() Reliable notifications are desired.
void	unreliableBranchNotifications() Unreliable notifications are desired.
void	useFederatedJournalView() Federates the view for methods in this session.
void	useIsolatedJournalView() 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

getJournalId

Id getJournalId()

Gets the Journal Id associated with this session.

Returns:

the Journal Id associated with this session

Compliance:

mandatory - This method must be implemented.

getJournal

Journal getJournal()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Journal associated with this session.

Returns:

the Journal associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForBranchNotifications

boolean canRegisterForBranchNotifications()

Tests if this user can register for Branch 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.

useFederatedJournalView

void useFederatedJournalView()

Federates the view for methods in this session. A federated view will include branches in journals which are children of this journal in the journal hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedJournalView

void useIsolatedJournalView()

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

Compliance:

mandatory - This method is must be implemented.

reliableBranchNotifications

void reliableBranchNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableBranchNotifications

void unreliableBranchNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeBranchNotification

void acknowledgeBranchNotification(Id notificationId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Acknowledge a branch notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewBranches

void registerForNewBranches()
                            throws OperationFailedException,
                                   PermissionDeniedException

Register for notifications of new branches. BranchReceiver.newBranches() is invoked when a new Branch is appears in this journal.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBranches

void registerForChangedBranches()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of updated branches. BranchReceiver.changedBranches() is invoked when a branch in this journal is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBranch

void registerForChangedBranch(Id branchId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of an updated branch. BranchReceiver.changedBranches() is invoked when the specified branch in this journal is changed.

Parameters:

branchId - the Id of the Branch to monitor

Throws:

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedBranches

void registerForDeletedBranches()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of deleted branches. BranchReceiver.deletedBranches() is invoked when a branch is deleted or removed from this journal.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedBranch

void registerForDeletedBranch(Id branchId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of a deleted branch. BranchReceiver.deletedBranches() is invoked when the specified branch is deleted or removed from this journal.

Parameters:

branchId - the Id of the Branch to monitor

Throws:

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.