Class COM.odi.osji.Notification

java.lang.Object
   |
   +----COM.odi.osji.Notification

public class Notification
extends Object

The Notification class allows different sessions, which can be in different Java virtual machines and on different network hosts, to communicate. One session sends out a notification, and any other session that has established a matching subscription receives the notification. An Object of class Notification identifies a persistent object, an integer called the kind, and a sequence of bytes called the data which can optionally be used to hold a String.

MAXIMUM_DATA_LENGTH: The maximum length of the "data" byte array in a notification.
MAXIMUM_NOTIFICATION_QUEUE_LENGTH: The maximum length to which the notification queue can be set.

Notification(Object, int): Make a Notification for the specified location (Java object).
Notification(Object, int, byte[]): Make a Notification for the specified location (Java object).
Notification(Object, int, String): Make a Notification for the specified location (Java object).

getData(): Get the byte array for this notification.
getKind(): Get the kind of the notification.
getLocation(): Get the location (Java object) from which this notification was made.
getMessage(): Get the string for this notification.
getPendingNotifications(): Determine the number of pending notifications in the notification queue for this session.
getQueueOverflows(): Determine the number of times that the notification queue for this session has overflowed.
getQueueSize(): Determine the size of the queue for the current session.
notifyImmediate(): Send this notification, immediately.
notifyImmediate(Notification[]): Notify all of the notifications in the array, immediately.
notifyOnCommit(): Send this notification when the current transaction commits.
notifyOnCommit(Notification[]): Notify all of the notifications in the array when the current transaction commits.
receive(int): Receive a notification from this session's queue of incoming messages.
setQueueSize(int): Set the size of the notification queue for the current session.
subscribe(Object): If the specified object is Placement, then subscribe to all objects therein.
subscribe(Placement): Subscribe to all objects in Placement.
unsubscribe(Object): If the specified object is Placement, then unsubscribe to all objects therein.
unsubscribe(Placement): Unsubscribe to all objects in Placement.

MAXIMUM_DATA_LENGTH

  public final static int MAXIMUM_DATA_LENGTH

The maximum length of the "data" byte array in a notification. Also the maximum length of the UTF-8 encoded representation of a String in a notification.

MAXIMUM_NOTIFICATION_QUEUE_LENGTH

  public final static int MAXIMUM_NOTIFICATION_QUEUE_LENGTH

The maximum length to which the notification queue can be set.

See Also:: setQueueSize

Notification

  public Notification(Object location,
                      int kind,
                      byte data[])

Make a Notification for the specified location (Java object). The byte array is expressed as a Java byte array.

Parameters:: location - The object.; kind - The kind of this notification.; data - The byte array data of this notification.
Throws: ObjectNotPersistentException: If the location is not already a persistent object. Possibly the application should call ObjectStore.migrate.
Throws: ObjectNotPersistenceCapableException: If the location is an object of a class that's not persistence-capable.
Throws: IllegalArgumentException: If the length of the byte array exceeds MAXIMUM_DATA_LENGTH bytes or one of the elements of the array is zero.
Throws: DatabaseException: If the location is in the transient segment.
Throws: NotificationException: The value of kind was reserved (negative).
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: ObjectNotFoundException: If the object in the notification has been destroyed.
Throws: ObjectException: If the object in the notification has become stale.
Throws: DatabaseNotOpenException: If the database containing the location is not open.

Notification

  public Notification(Object location,
                      int kind,
                      String message)

Make a Notification for the specified location (Java object). The byte array is expressed as a Java string.

Parameters:: location - The object.; kind - The kind of this notification.; message - The string of this notification.
Throws: ObjectNotPersistentException: If the location is not already a persistent object. Possibly the application should call ObjectStore.migrate.
Throws: ObjectNotPersistenceCapableException: If the location is an object of a class that's not persistence-capable.
Throws: IllegalArgumentException: If the length of the UTF-8 encoding of the string exceeds MAXIMUM_DATA_LENGTH bytes.
Throws: DatabaseException: If the location is in the transient segment.
Throws: NotificationException: If the value of kind was reserved (negative).
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: ObjectNotFoundException: If the object in the notification has been destroyed.
Throws: ObjectException: If the object in the notification has become stale.
Throws: DatabaseNotOpenException: If the database containing the location is not open.

Notification

  public Notification(Object location,
                      int kind)

Make a Notification for the specified location (Java object). The byte array is empty.

Parameters:: location - The object.; kind - The kind of this notification.
Throws: ObjectNotPersistentException: If the location is not already a persistent object. Possibly the application should call ObjectStore.migrate.
Throws: ObjectNotPersistenceCapableException: If the location is an object of a class that's not persistence-capable.
Throws: DatabaseException: If the location is in the transient segment.
Throws: NotificationException: If the value of kind was reserved (negative).
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: ObjectNotFoundException: If the object in the notification has been destroyed.
Throws: ObjectException: If the object in the notification has become stale.
Throws: DatabaseNotOpenException: If the database containing the location is not open.

getLocation

  public Object getLocation()

Get the location (Java object) from which this notification was made.

Returns:: The object.
Throws: ObjectNotFoundException: If the object has been destroyed.
Throws: NoTransactionInProgressException: If there is no transaction in progress.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

getKind

  public int getKind()

Get the kind of the notification.

Returns:: The kind.

getData

  public byte[] getData()

Get the byte array for this notification. If the notification was originally made from a string, return a byte array containing the UTF-8 encoding of the string.

Returns:: The byte array.

getMessage

  public String getMessage()

Get the string for this notification. The contents of the byte array are interpreted as the UTF-8 encoding of a string, and that string is returned.

Returns:: The string.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

notifyImmediate

  public void notifyImmediate()

Send this notification, immediately.

Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

notifyOnCommit

  public void notifyOnCommit()

Send this notification when the current transaction commits.

Throws: NoTransactionInProgressException: If there is no transaction in progress.

notifyImmediate

  public static void notifyImmediate(Notification notifications[])

Notify all of the notifications in the array, immediately.

Parameters:: notifications - An array of notifications to be notified.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

notifyOnCommit

  public static void notifyOnCommit(Notification notifications[])

Notify all of the notifications in the array when the current transaction commits.

Parameters:: notifications - An array of notifications to be notified.
Throws: NoTransactionInProgressException: If there is no transaction in progress.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

subscribe

  public static void subscribe(Placement placement)

Subscribe to all objects in Placement.

Parameters:: placement - The segment or database to subscribe to.
Throws: DatabaseNotOpenException: If the database containing the Placement is not open.
Throws: DatabaseException: If the Placement is the transient segment or database.
Throws: SegmentNotFoundException: If Placement is a segment that has been destroyed.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: NoTransactionInProgressException: If there is no transaction in progress.

subscribe

  public static void subscribe(Object location)

If the specified object is Placement, then subscribe to all objects therein. Otherwise, subscribe to that object.

Parameters:: location - The object, or a Placement, to subscribe to.
Throws: DatabaseNotOpenException: If the database containing the location or the Placement is not open.
Throws: SegmentException: If object is in the transient segment.
Throws: DatabaseException: If the Placement is the transient segment or database.
Throws: SegmentNotFoundException: If the segment has been destroyed.
Throws: ObjectNotFoundException: If the object has been destroyed.
Throws: ObjectException: If the object has become stale.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: ObjectNotPersistentException: If the location is not already a persistent object. Possibly the application should call ObjectStore.migrate.
Throws: ObjectNotPersistenceCapableException: If the location is an object of a class that's not persistence-capable.
Throws: NoTransactionInProgressException: If there is no transaction in progress.

unsubscribe

  public static void unsubscribe(Placement placement)

Unsubscribe to all objects in Placement.

Parameters:: placement - The segment or database to unsubscribe to.
Throws: DatabaseNotOpenException: If the database containing the Placement is not open.
Throws: DatabaseException: If the Placement is the transient segment or database.
Throws: SegmentNotFoundException: If Placement is a segment that has been destroyed.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: NoTransactionInProgressException: If there is no transaction in progress.

unsubscribe

  public static void unsubscribe(Object location)

If the specified object is Placement, then unsubscribe to all objects therein. Otherwise, unsubscribe to that object.

Parameters:: location - The object, or a Placement, to unsubscribe to.
Throws: DatabaseNotOpenException: If the database containing the location or the Placement is not open.
Throws: SegmentException: If object is in the transient segment.
Throws: DatabaseException: If the Placement is the transient segment or database.
Throws: SegmentNotFoundException: If the segment has been destroyed.
Throws: ObjectNotFoundException: If the object has been destroyed.
Throws: ObjectException: If the object has become stale.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.
Throws: ObjectNotPersistentException: If the location is not already a persistent object. Possibly the application should call ObjectStore.migrate.
Throws: ObjectNotPersistenceCapableException: If the location is an object of a class that's not persistence-capable.
Throws: NoTransactionInProgressException: If there is no transaction in progress.

getQueueSize

  public static int getQueueSize()

Determine the size of the queue for the current session.

Returns:: The size of the queue.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

setQueueSize

  public static void setQueueSize(int queueSize)

Set the size of the notification queue for the current session. This must not be called after the first subscription is done.

Parameters:: queueSize - The new queue size.
Throws: NotificationException: If setQueueSize was called after at least one subscription was done.
Throws: NotificationException: If the proposed new queue size exceeds MAXIMUM_NOTIFICATION_QUEUE_LENGTH.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

getPendingNotifications

  public static int getPendingNotifications()

Determine the number of pending notifications in the notification queue for this session.

Returns:: The number of pending notifications.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

getQueueOverflows

  public static int getQueueOverflows()

Determine the number of times that the notification queue for this session has overflowed.

Returns:: The number of notification queue overflows.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.

receive

  public static Notification receive(int timeout)

Receive a notification from this session's queue of incoming messages. This method is normally called in a separate cooperating thread, i.e. in a distinct thread that is associated with the same session as the thread that called the subscribe method. There need not be a transaction in progress; recieve operates independently of transactions.

Parameters:: timeout - A timeout value in milliseconds, or ObjectStore.WAIT_FOREVER to mean keep waiting without ever timing out. If timeout is zero, don't wait at all; return any notification already pending in the queue, otherwise return null.
Returns:: A notification object, or null if the timeout period has passed and no notification has arrived. Also, return null immediate if there are no subscriptions at all.
Throws: ObjectStoreException: If the current thread is not associated with a session and there is no global session.