net.jini.core.event

Class RemoteEvent

java.lang.Object

java.util.EventObject

net.jini.core.event.RemoteEvent

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

RemoteDiscoveryEvent, ServiceEvent

public class RemoteEvent
extends EventObject

The base class or superclass for remote events.

The abstract state contained in a RemoteEvent object includes a reference to the object in which the event occurred, a long which identifies the kind of event relative to the object in which the event occurred, a long which indicates the sequence number of this instance of the event kind, and a MarshalledObject that is to be handed back when the notification occurs. The combination of the event identifier and the object reference obtained from the RemoteEvent object should uniquely identify the event type.

The sequence number obtained from the RemoteEvent object is an increasing value that can act as a hint to the number of occurrences of this event relative to some earlier sequence number. Any object that generates a RemoteEvent is required to insure that for any two RemoteEvent objects with the same event identifier, the sequence number of those events differ if and only if the RemoteEvent objects are a response to different events. This guarantee is required to allow notification calls to be idempotent. A further guarantee is that if two RemoteEvents, x and y, come from the same source and have the same event identifier, then x occurred before y if and only if the sequence number of x is lower than the sequence number of y.

A stronger guarantee is possible for those generators of RemoteEvents that can support it. This guarantee states that not only do sequence numbers increase, but they are not skipped. In such a case, if RemoteEvent x and y have the same source and the same event identifier, and x has sequence number m and y has sequence number n, then if m < n there were exactly n-m-1 events of the same event type between the event that triggered x and the event that triggered y. Such sequence numbers are said to be "fully ordered".

An event registration that occurs within a transaction is considered to be scoped by that transaction. This means that any occurrence of the kind of event of interest that happens as part of the transaction will cause a notification to be sent to the recipients indicated by the registration that occurred in the transaction. Such events must have a separate event identifier to allow third-party store and forward entities to distinguish between an event that happens within a transaction and those that happen outside of the transaction. Notifications of these events will not be sent to entities that registered interest in this kind of event outside the scope of the transaction until and unless the transaction is committed.

Because of this, notifications sent from inside a transaction will have a different sequence number than the notifications of the same events would have outside of the transaction. Within a transaction, all RemoteEvent objects for a given kind of event are given a sequence number relative to the transaction. This is true even if the event that triggered the RemoteEvent object being sent occurs outside of the scope of the transaction (but is visible within the transaction). Immutable since 3.0.0

Since:

1.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected long	eventID The event identifier.
protected MarshalledObject	handback Deprecated.
protected MarshalledInstance	miHandback The registration handback object.
protected long	seqNum The event sequence number.

Fields inherited from class java.util.EventObject

source

Constructor Summary

Constructors

Constructor and Description
RemoteEvent(AtomicSerial.GetArg arg)
RemoteEvent(Object source, long eventID, long seqNum, MarshalledInstance miHandback) Constructs a RemoteEvent object.
RemoteEvent(Object source, long eventID, long seqNum, MarshalledObject handback) Deprecated.

Method Summary

Modifier and Type	Method and Description
long	getID() Returns the event identifier, used to identify the kind of event relative to the object in which the event occurred.
MarshalledInstance	getRegistrationInstance() Returns the handback object that was provided as a parameter to the event interest registration method, if any.
MarshalledObject	getRegistrationObject() Deprecated. Use getRegistrationInstance() instead.
long	getSequenceNumber() Returns the sequence number of this event.

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

eventID

protected long eventID

The event identifier.

seqNum

protected long seqNum

The event sequence number.

handback

@Deprecated
protected MarshalledObject handback

Deprecated.

The handback object.

miHandback

protected MarshalledInstance miHandback

The registration handback object.

Constructor Detail

RemoteEvent

public RemoteEvent(AtomicSerial.GetArg arg)
            throws IOException

Throws:

IOException

RemoteEvent

@Deprecated
public RemoteEvent(Object source,
                                long eventID,
                                long seqNum,
                                MarshalledObject handback)

Deprecated.

Constructs a RemoteEvent object.

The abstract state contained in a RemoteEvent object includes a reference to the object in which the event occurred, a long which identifies the kind of event relative to the object in which the event occurred, a long which indicates the sequence number of this instance of the event kind, and a MarshalledObject that is to be handed back when the notification occurs. The combination of the event identifier and the object reference obtained from the RemoteEvent object should uniquely identify the event type.

Parameters:

source - an Object representing the event source

eventID - a long containing the event identifier

seqNum - a long containing the event sequence number

handback - a MarshalledObject that was passed in as part of the original event registration.

RemoteEvent

public RemoteEvent(Object source,
                   long eventID,
                   long seqNum,
                   MarshalledInstance miHandback)

Constructs a RemoteEvent object.

The abstract state contained in a RemoteEvent object includes a reference to the object in which the event occurred, a long which identifies the kind of event relative to the object in which the event occurred, a long which indicates the sequence number of this instance of the event kind, and a MarshalledInstance that is to be handed back when the notification occurs. The combination of the event identifier and the object reference obtained from the RemoteEvent object should uniquely identify the event type.

Parameters:

source - an Object representing the event source

eventID - a long containing the event identifier

seqNum - a long containing the event sequence number

miHandback - a MarshalledInstance that was passed in as part of the original event registration.

Method Detail

getID

public long getID()

Returns the event identifier, used to identify the kind of event relative to the object in which the event occurred.

Returns:

a long representing the event identifier relative to the object in which the event occurred.

See Also:

EventRegistration.getID()

getSequenceNumber

public long getSequenceNumber()

Returns the sequence number of this event.

Returns:

a long representing the sequence number of this event.

getRegistrationObject

@Deprecated
public MarshalledObject getRegistrationObject()

Deprecated. Use getRegistrationInstance() instead.

Returns the handback object that was provided as a parameter to the event interest registration method, if any.

Returns:

the MarshalledObject that was provided as a parameter to the event interest registration method, if any.

getRegistrationInstance

public MarshalledInstance getRegistrationInstance()

Returns the handback object that was provided as a parameter to the event interest registration method, if any. Note that if the handback object was a MarshalledObject, it will be returned as a MarshalledInstance.

Returns:

the MarshalledInstance that was provided as a parameter to the event interest registration method, if any. Or the MarshalledObject that was provided, converted to a MarshalledInstance.