com.sun.jini.norm.event
Class EventType

java.lang.Object
  extended by com.sun.jini.norm.event.EventType
All Implemented Interfaces:
Serializable

public class EventType
extends Object
implements Serializable

Representation of an event type the supports a single registrant. The registrant, event ID, and event sequence number information portions of this object are preserved when serialized. The send monitor, and currently scheduled event sends are not.

Author:
Sun Microsystems, Inc.
See Also:
Serialized Form

Nested Class Summary
private  class EventType.SendTask
          Subclass of RetryTask used by EventType to send events.
 
Field Summary
private  long evID
          Our event ID
private  EventTypeGenerator generator
          Event type generator that created us.
private  MarshalledObject handback
          Handback object associated with current listener.
private  long lastSeqNum
          Last event sequence number we used
private  RemoteEventListener listener
          Transient cache of listener in unmarshalled form
private static Logger logger
          Logger for logging messages for this class
private  MarshalledObject marshalledListener
          Listener registered for events of this type.
private  SendMonitor monitor
          Object we check with to ensure leases have not expired and notify when we get a definite exception during an event send attempt.
private  ProxyPreparer recoveredListenerPreparer
          The proxy preparer to use to prepare a newly unmarshalled listener, or null if this instance was created using an already prepared listener, which is how instances are created initially.
private  long registrationNumber
          Sequence number of the current listener/handback pair, incremented every time a new listener is set (even if the objects are equivalent)
private static long serialVersionUID
           
 
Constructor Summary
EventType(EventTypeGenerator generator, SendMonitor monitor, long evID, RemoteEventListener listener, MarshalledObject handback)
          Simple constructor.
 
Method Summary
 long bumpSequenceNumber()
          Increment the sequence number and return the result.
private  void clearListener()
          Utility method to null out listener
 boolean clearListenerIfSequenceMatch(long oldSequenceNumber)
          Atomically clear the current registration if its sequence number matches the passed in sequence number.
 long getEventID()
          Return the long that was uniquely associated with this object when it was created.
 long getLastSequenceNumber()
          Return the sequence number of the last event that was scheduled to be sent.
private  RemoteEventListener getListener()
          Convince method to get the listener.
 boolean haveListener()
          Returns true if there is a listener registered for this event type.
 void restoreTransientState(EventTypeGenerator generator, SendMonitor monitor, ProxyPreparer recoveredListenerPreparer)
          Restore the transient state of this object after recovering it from a serialization stream.
 long sendEvent(EventFactory factory)
          Schedule the sending of an event.
 void setLastSequenceNumber(long seqNum)
          Set the object's notion of the last sequence number.
 void setListener(RemoteEventListener listener, MarshalledObject handback)
          (Re)set the listener for this type of event.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

logger

private static final Logger logger
Logger for logging messages for this class


marshalledListener

private MarshalledObject marshalledListener
Listener registered for events of this type. Stored in marshalled form so object the EventType object can be recovered even if the listener's codebase is not available. If this field is null, listener and handback will be also.


listener

private transient RemoteEventListener listener
Transient cache of listener in unmarshalled form


recoveredListenerPreparer

private transient ProxyPreparer recoveredListenerPreparer
The proxy preparer to use to prepare a newly unmarshalled listener, or null if this instance was created using an already prepared listener, which is how instances are created initially.


handback

private MarshalledObject handback
Handback object associated with current listener.


registrationNumber

private long registrationNumber
Sequence number of the current listener/handback pair, incremented every time a new listener is set (even if the objects are equivalent)


lastSeqNum

private long lastSeqNum
Last event sequence number we used


evID

private long evID
Our event ID


monitor

private transient SendMonitor monitor
Object we check with to ensure leases have not expired and notify when we get a definite exception during an event send attempt. If this field is null generator will be also.


generator

private transient EventTypeGenerator generator
Event type generator that created us. If this field is null monitor will be also.

Constructor Detail

EventType

EventType(EventTypeGenerator generator,
          SendMonitor monitor,
          long evID,
          RemoteEventListener listener,
          MarshalledObject handback)
    throws IOException
Simple constructor. Initially the last sequence number is set to 0.

Parameters:
generator - EventTypeGenerator that is creating this event type
monitor - Object which is to monitor the sending of events of this type
evID - event ID of this event type
listener - the listener events of this type should go to
handback - the object that should be passed to listener as part of the event
Throws:
IOException - if the listener cannot be serialized
Method Detail

clearListener

private void clearListener()
Utility method to null out listener


setListener

public void setListener(RemoteEventListener listener,
                        MarshalledObject handback)
                 throws IOException
(Re)set the listener for this type of event. Any pending events that have not yet been sent will be sent to the new listener, passing the new handback. Setting the listener to null will cancel the sending of all pending events.

Parameters:
listener - the listener events of this type should go to
handback - the object that should be passed to listener as part of the event
Throws:
IOException - if listener cannot be serialized

haveListener

public boolean haveListener()
Returns true if there is a listener registered for this event type.


getListener

private RemoteEventListener getListener()
Convince method to get the listener.

Returns:
the listener, or null if the listener can't be unpacked or prepared, or there is no listener

clearListenerIfSequenceMatch

public boolean clearListenerIfSequenceMatch(long oldSequenceNumber)
Atomically clear the current registration if its sequence number matches the passed in sequence number. If the replacement occurs it will have the same effect as calling setListener(null, null).

Can be used by code that needs to remove event registrations in response to exceptions thrown during event delivery without risking clobbering new registrations.

Parameters:
oldSequenceNumber - sequence number of the registration that had a problem
Returns:
true if the state of the object was changed and false otherwise
See Also:
setListener(net.jini.core.event.RemoteEventListener, java.rmi.MarshalledObject)

setLastSequenceNumber

public void setLastSequenceNumber(long seqNum)
Set the object's notion of the last sequence number. The next event scheduled to be sent will have a sequence number one greater than the value past to this call.

Note: this method is not synchronized.

Parameters:
seqNum - value for the last sequence number

getLastSequenceNumber

public long getLastSequenceNumber()
Return the sequence number of the last event that was scheduled to be sent. Intended primarily for creating EventRegistration objects and the like.


getEventID

public long getEventID()
Return the long that was uniquely associated with this object when it was created.


sendEvent

public long sendEvent(EventFactory factory)
Schedule the sending of an event. This event will be sent to the currently registered listener. If the listener changes before the the event is successfully sent the event will be sent to the new listener. If the current listener is null this call will have no affect aside from incrementing the sequence number.

Parameters:
factory - an object that will be used to create the Event object when necessary
Returns:
the sequence number assigned to the event
Throws:
IllegalStateException - if this method is called after the object has be deserialized and before restoreTransientState has been called
See Also:
restoreTransientState(com.sun.jini.norm.event.EventTypeGenerator, com.sun.jini.norm.event.SendMonitor, net.jini.security.ProxyPreparer)

bumpSequenceNumber

public long bumpSequenceNumber()
Increment the sequence number and return the result. This method is useful if an event occurs that needs to be noted but from some reason it is impossible to deliver the event.

Returns:
the new value for the sequence number

restoreTransientState

public void restoreTransientState(EventTypeGenerator generator,
                                  SendMonitor monitor,
                                  ProxyPreparer recoveredListenerPreparer)
Restore the transient state of this object after recovering it from a serialization stream. None of the arguments can be null.

Note: this method is not synchronized.

Parameters:
generator - the EventTypeGenerator that was used to create this EventType object originally
monitor - the object that monitors the progress of events set by this object
recoveredListenerPreparer - the proxy preparer to use to prepare listeners recovered from persistent storage


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.