com.sun.jini.mercury
Class MailboxImpl

java.lang.Object
  extended by com.sun.jini.mercury.MailboxImpl
All Implemented Interfaces:
DestroyAdmin, TimeConstants, Landlord, MailboxAdmin, MailboxBackEnd, ServiceProxyAccessor, Remote, Administrable, JoinAdmin, EventMailbox, PullEventMailbox, ProxyAccessor, ServerProxyTrust
Direct Known Subclasses:
ActivatableMercuryImpl, NonActivatableMercuryImpl, TransientMercuryImpl

 class MailboxImpl
extends Object
implements MailboxBackEnd, TimeConstants, ServerProxyTrust, ProxyAccessor

MailboxImpl implements the server side of the event mailbox service.

Client-side proxies make the appropriate transformation from client requests to the methods of this class.

Since:
1.1
Author:
Sun Microsystems, Inc.

Nested Class Summary
private static class MailboxImpl.AttrsAddedLogObj
          LogObj class whose instances are recorded to the log file whenever the set of lookup attributes is augmented.
private static class MailboxImpl.AttrsModifiedLogObj
          LogObj class whose instances are recorded to the log file whenever the set of lookup attributes is modified.
private  class MailboxImpl.DestroyThread
          Termination thread code.
private  class MailboxImpl.ExpirationThread
          Registration expiration thread code
private  class MailboxImpl.LocalLandlordAdaptor
          Adaptor class implementation of LocalLandlord.
private  class MailboxImpl.LocalLogHandler
          Handler class for the persistent storage facility.
private static interface MailboxImpl.LogRecord
          Interface defining the method(s) that must be implemented by each of the concrete LogObj classes.
private static class MailboxImpl.LookupGroupsChangedLogObj
          LogObj class whose instances are recorded to the log file whenever the set of groups to join is changed.
private static class MailboxImpl.LookupLocatorsChangedLogObj
          LogObj class whose instances are recorded to the log file whenever the set of locators of lookup services to join is changed.
private  class MailboxImpl.Notifier
          The notifier thread.
(package private)  class MailboxImpl.NotifyTask
          A task that represents an event notification task for a particular registration.
private static class MailboxImpl.RegistrationCancelledLogObj
          LogObj class whose instances are recorded to the log file whenever a registration is cancelled.
private static class MailboxImpl.RegistrationDisabledLogObj
          LogObj class whose instances are recorded to the log file whenever a registration is disabled.
private static class MailboxImpl.RegistrationEnabledLogObj
          LogObj class whose instances are recorded to the log file whenever a registration is enabled.
private static class MailboxImpl.RegistrationIteratorEnabledLogObj
          LogObj class whose instances are recorded to the log file whenever a registration iterator is enabled.
private static class MailboxImpl.RegistrationLogObj
          LogObj class whose instances are recorded to the log file whenever a new registration is created.
private static class MailboxImpl.RegistrationRenewedLogObj
          LogObj class whose instances are recorded to the log file whenever a registration is renewed.
private  class MailboxImpl.SnapshotThread
          Snapshot-taking thread.
private static class MailboxImpl.UnknownEventExceptionLogObj
          LogObj class whose instances are recorded to the log file whenever an UnknownEventException is received during event notification.
 
Nested classes/interfaces inherited from interface com.sun.jini.landlord.Landlord
Landlord.RenewResults
 
Field Summary
private  ActivationID activationID
          Our activation ID
private  boolean activationPrepared
          Whether the activation ID has been prepared
private  ActivationSystem activationSystem
          The activation system, prepared
private  Map activeReg
          Map of ServiceRegistrations that have event delivery enabled and have event delivery tasks currently scheduled.
(package private) static Logger adminLogger
          Logger for service administration related messages
private static String attrsAddedLogObjSourceClass
           
private static String attrsModifiedLogObjSourceClass
           
private  Entry[] baseLookupAttrs
          The attributes to use when joining lookup services
private  ReadersWriter concurrentObj
          Concurrent object (lock) to control read and write access
(package private) static Logger deliveryLogger
          Logger for event delivery related messages
private  Object destroyLock
          Object for coordinating the destroy process
private  boolean destroySucceeded
          Flag that denotes whether or not destroy has already been called.
private static String destroyThreadSourceClass
           
private  EventLogFactory eventLogFactory
          EventLogIterator generator
private  Object eventNotifier
          Object for coordinating actions with the notification thread
(package private) static Logger expirationLogger
          Logger for lease expiration related messages
private  Object expirationNotifier
          Object for coordinating actions with the expire thread
private static String expirationThreadSourceClass
           
private  MailboxImpl.ExpirationThread expirer
          Registration expirer thread
protected  Exporter exporter
          The exporter for exporting and unexporting
(package private) static Logger initLogger
          Logger for service initialization related messages
private  boolean inRecovery
          Flag indicating whether system is in a state of recovery
private  JoinManager joiner
          Manager for joining lookup services
private  LeaseFactory leaseFactory
          LandLordLeaseFactory we use to create leases
(package private) static Logger leaseLogger
          Logger for lease related messages
private  LeasePeriodPolicy leasePolicy
          LeasePeriodPolicy for this service
private  LifeCycle lifeCycle
          LifeCycle object used to notify starter framework that this object's implementation reference, if any, should not be held onto any longer.
private  ProxyPreparer listenerPreparer
          Proxy preparer for listeners
private  MailboxImpl.LocalLandlordAdaptor localLandlord
          LocalLandlord to use with LandlordUtil calls
private static ProxyPreparer locatorToJoinPreparer
           
private  ReliableLog log
          Reliable log to hold registration state information
private static int LOG_VERSION
          Log format version
private  int logFileSize
          Current number of records in the Log File since the last snapshot
protected  LoginContext loginContext
          The login context, for logging out
private  int logToSnapshotThreshold
          Log File must contain this many records before a snapshot is allowed
private  Entry[] lookupAttrs
           
private  DiscoveryManagement lookupDiscMgr
          DiscoveryManager for joining lookup services.
private  String[] lookupGroups
          The lookup groups we should join.
private static String lookupGroupsChangedLogObjSourceClass
           
private  LookupLocator[] lookupLocators
          The lookup locators we should join Default is to join with no locators.
private static String lookupLocatorsChangedLogObjSourceClass
           
private  MailboxAdminProxy mailboxAdminProxy
          The admin proxy of this server
private  MailboxProxy mailboxProxy
          The outter proxy of this server
private static String mailboxSourceClass
           
private static String MANUFACTURER
          ServiceInfo manufacturer value
private static int MAX_ATTEMPTS
          The maximum mnumber of times to retry event delivery
private static long MAX_TIME
          The maximum time to maintain a notification task
private  long maxUnexportDelay
          When destroying the space, how long to wait for a clean unexport (which allows the destroy call to return) before giving up calling unexport(true)
(package private) static String MERCURY
          Logger and configuration component name for Norm
private  long minRegExpiration
          Earliest expiration time of any registration
private  MailboxImpl.Notifier notifier
          Event delivery thread
private static String notifierSourceClass
           
private static String notifyTaskSourceClass
           
(package private) static Logger operationsLogger
          Logger for service operation messages
private  List pendingReg
          List of ServiceRegistrations that have event delivery enabled, but don't have any event delivery tasks currently scheduled.
private  String persistenceDirectory
          Name of persistence directory
(package private) static Logger persistenceLogger
          Logger for service persistence related messages
private  boolean persistent
          boolean flag used to determine persistence support.
private static String PRODUCT
          ServiceInfo product value
private  ReadyState readyState
          Object used to prevent access to this service during the service's initialization or shutdown processing.
(package private) static Logger receiveLogger
          Logger for event reception related messages
private static ProxyPreparer recoveredLocatorToJoinPreparer
           
(package private) static Logger recoveryLogger
          Logger for service recovery related messages
private  TreeMap regByExpiration
          Identity map of ServiceRegistration, ordered by lease expiration.
private  HashMap regByID
          Map from Uuid to ServiceRegistration
private static String registrationCancelledLogObjSourceClass
           
private static String registrationDisabledLogObjSourceClass
           
private static String registrationEnabledLogObjSourceClass
           
private static String registrationIteratorEnabledLogObjSourceClass
           
private static String registrationLogObjSourceClass
           
private static String registrationRenewedLogObjSourceClass
           
private  MailboxBackEnd serverStub
          The inner proxy of this server
private  Uuid serviceID
          ServiceID returned from the lookup registration process
private  Object snapshotNotifier
          Object on which the snapshot-taking thread will synchronize
private  Thread snapshotter
          Snapshot-taking thread
private static String snapshotThreadSourceClass
           
(package private) static Logger startupLogger
          Logger for (successful) service startup message
private  long unexportRetryDelay
          Length of time to sleep between unexport attempts
private static String unknownEventExceptionLogObjSourceClass
           
private static String VENDOR
          ServiceInfo vendor value
private static String VERSION
          ServiceInfo version value
 
Fields inherited from interface com.sun.jini.constants.TimeConstants
DAYS, HOURS, MINUTES, SECONDS
 
Constructor Summary
MailboxImpl(ActivationID activationID, MarshalledObject data)
          Activation constructor
MailboxImpl(String[] configArgs, LifeCycle lc, boolean persistent)
          Constructor for creating transient (i.e. non-activatable) service instances.
 
Method Summary
private  void addLogRecord(MailboxImpl.LogRecord rec)
          Add a state-change record to persistent storage.
 void addLookupAttributes(Entry[] attrSets)
          Add attribute sets for the service.
 void addLookupGroups(String[] groups)
          Add new groups to the set to join.
 void addLookupLocators(LookupLocator[] locators)
          Add locators for specific new lookup services to join.
private  void addRegistration(ServiceRegistration reg)
          Utility method used to add a registration to our state information.
private  void addUnknownEvent(Uuid regID, EventID evid)
          Utility method that adds the provided EventID to the given registration's "unknown" event list.
private  void addUnknownEventDo(Uuid regID, EventID evid)
          Performs the actual logic for adding an unknown event to the given registration's unknown event list.
 void addUnknownEvents(Uuid uuid, Collection unknownEvents)
          Get events for the given registration
private  void addUnknownEventsDo(Uuid uuid, Collection unknownEvents)
          Performs the actual logic for synchronously getting events for a particular registration.
 void cancel(Uuid cookie)
          Called by the lease when its cancel method is called.
 Map cancelAll(Uuid[] cookies)
          Called by the lease map when its cancelAll method is called.
private  Map cancelAllDo(Uuid[] cookie)
          Performs the actual cancelAll logic
private  void cancelDo(Uuid cookie)
          Performs the actual registration cancellation logic
private  void cleanup()
           
 void destroy()
          Destroy the service, if possible, including its persistent storage.
 void disableDelivery(Uuid uuid)
          Disable delivery of events for the given registration
private  void disableDeliveryDo(Uuid uuid)
          Performs the actual logic for disabling event delivery for a particular registration.
private  void disableRegistration(Uuid uuid)
          Utility method that disables event delivery for the registration associated with the given UUID
private  void disableRegistrationIterator(Uuid regId)
          Utility method that sets the valid iterator id for provided registration.
private  void doInit(Configuration config)
          Initialization common to both activatable and transient instances.
private  void doInitWithLogin(Configuration config, LoginContext loginContext)
          Method that attempts to login before delegating the rest of the initialization process to doInit
private static void dumpAttrs(Entry[] attrs, Logger logger, Level level)
          Utility method for displaying lookup service attributes
private static void dumpGroups(String[] grps, Logger logger, Level level)
          Utility method for displaying lookup group attributes
private static void dumpLocators(LookupLocator[] locs, Logger logger, Level level)
          Utility method for displaying lookup locator attributes
 void enableDelivery(Uuid uuid, RemoteEventListener target)
          Enable delivery of events for the given registration to the specified target
private  void enableDeliveryDo(Uuid uuid, RemoteEventListener preparedTarget)
          Performs the actual enable delivery logic
private  void enableRegistration(Uuid uuid, RemoteEventListener preparedTarget)
          Utility method that associates the given listener with the associated registration object.
private  void enableRegistrationIterator(Uuid regId, Uuid iterId)
          Utility method that sets the valid iterator id for provided registration.
private static boolean ensureCurrent(LeasedResource resource)
          Utility method that check for valid resource
 Object getAdmin()
          Returns an object that implements whatever administration interfaces are appropriate for the particular service.
private static File getEventLogPath(String parent, Uuid uuid)
          Utility method that returns the associated File object for the given Uuid's persistence directory
 Entry[] getLookupAttributes()
          Get the current attribute sets for the service.
 String[] getLookupGroups()
          Get the list of groups to join.
 LookupLocator[] getLookupLocators()
          Get the list of locators of specific lookup services to join.
 Collection getNextBatch(Uuid regId, Uuid iterId, long timeout, Object lastEventCookie)
          Get next batch of events for the given registration.
private  Collection getNextBatchDo(Uuid regId, Uuid iterId, long timeout, Object lastEventCookie)
          Does the actual logic for obtaining the next set of events for the given registration.
 Object getProxy()
          Returns a proxy object for this remote object.
 TrustVerifier getProxyVerifier()
          Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy.
 RemoteEventIteratorData getRemoteEvents(Uuid uuid)
          Get events for the given registration via the returned iterator.
private  RemoteEventIteratorData getRemoteEventsDo(Uuid uuid)
          Performs the actual logic for synchronously getting events for a particular registration.
 Object getServiceProxy()
          Returns a proxy object for this object.
private  ServiceRegistration getServiceRegistration(Uuid regID)
          Utility method that tries to obtain the ServiceRegistration object associated with the given Uuid.
private  void init(String[] configArgs)
          Initialization common to both activatable and transient instances.
protected  void initFailed(Throwable e)
          Log information about failing to initialize the service and rethrow the appropriate exception.
private static MarshalledObject[] marshalAttributes(Entry[] attrs)
          Marshals each element of the Entry[] array parameter.
 void modifyLookupAttributes(Entry[] attrSetTemplates, Entry[] attrSets)
          Modify the current attribute sets, using the same semantics as ServiceRegistration.modifyAttributes.
 void notify(Uuid registrationID, RemoteEvent theEvent)
          Collect remote events for the associated registration.
private  void notifyDo(Uuid registrationID, RemoteEvent theEvent)
          Performs the actual logic of handling received events and storing them.
private static LookupLocator[] prepareExistingLocators(ProxyPreparer preparer, LookupLocator[] lookupLocators)
           
private static void prepareNewLocators(ProxyPreparer preparer, LookupLocator[] locators)
          Using the given ProxyPreparer, attempts to prepare each element of the given LookupLocator array; replacing the original element of the array with the result of the call to the method ProxyPreparer.prepareProxy.
 MailboxPullRegistration pullRegister(long leaseDuration)
          Defines the interface to the event mailbox service.
private  void rebuildTransientState(ProxyPreparer recoveredListenerPreparer)
           
private  void recoverSnapshot(InputStream in)
          Retrieve the contents of the snapshot file and reconstitute the 'base' state of the Mercury from the retrieved data.
 MailboxRegistration register(long leaseDuration)
          Defines the interface to the event mailbox service.
private  Registration registerDo(long duration)
          Actual implementation of the registration process.
 void removeLookupGroups(String[] groups)
          Remove groups from the set to join.
 void removeLookupLocators(LookupLocator[] locators)
          Remove locators for specific lookup services from the set to join.
private  void removeRegistration(Uuid regID, ServiceRegistration reg)
          Utility method that calls the overloaded version that accepts a boolean, which is set to false.
private  void removeRegistration(Uuid regID, ServiceRegistration reg, boolean initializing)
          Utility method that consolidates registration removal activities.
 long renew(Uuid cookie, long extension)
          Called by the lease when its renew method is called.
 Landlord.RenewResults renewAll(Uuid[] cookies, long[] extension)
          Called by the lease map when its renewAll method is called.
private  Landlord.RenewResults renewAllDo(Uuid[] cookie, long[] extension)
          Performs the actual renewAll logic
private  long renewDo(Uuid cookie, long extension)
          Performs the actual registration renewal logic
 void setLookupGroups(String[] groups)
          Replace the list of groups to join with a new list.
 void setLookupLocators(LookupLocator[] locators)
          Replace the list of locators of specific lookup services to join with a new list.
private  void takeSnapshot(OutputStream out)
          Write the current state of the Mercury to persistent storage.
private static Entry[] unmarshalAttributes(MarshalledObject[] marshalledAttrs)
          Unmarshals each element of the MarshalledObject array parameter.
private  void validateIterator(Uuid regId, Uuid iterId)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MERCURY

static final String MERCURY
Logger and configuration component name for Norm

See Also:
Constant Field Values

leaseLogger

static final Logger leaseLogger
Logger for lease related messages


deliveryLogger

static final Logger deliveryLogger
Logger for event delivery related messages


adminLogger

static final Logger adminLogger
Logger for service administration related messages


initLogger

static final Logger initLogger
Logger for service initialization related messages


receiveLogger

static final Logger receiveLogger
Logger for event reception related messages


expirationLogger

static final Logger expirationLogger
Logger for lease expiration related messages


recoveryLogger

static final Logger recoveryLogger
Logger for service recovery related messages


persistenceLogger

static final Logger persistenceLogger
Logger for service persistence related messages


startupLogger

static final Logger startupLogger
Logger for (successful) service startup message


operationsLogger

static final Logger operationsLogger
Logger for service operation messages


mailboxSourceClass

private static final String mailboxSourceClass

notifierSourceClass

private static final String notifierSourceClass

notifyTaskSourceClass

private static final String notifyTaskSourceClass

destroyThreadSourceClass

private static final String destroyThreadSourceClass

expirationThreadSourceClass

private static final String expirationThreadSourceClass

registrationLogObjSourceClass

private static final String registrationLogObjSourceClass

registrationEnabledLogObjSourceClass

private static final String registrationEnabledLogObjSourceClass

registrationDisabledLogObjSourceClass

private static final String registrationDisabledLogObjSourceClass

registrationIteratorEnabledLogObjSourceClass

private static final String registrationIteratorEnabledLogObjSourceClass

lookupGroupsChangedLogObjSourceClass

private static final String lookupGroupsChangedLogObjSourceClass

lookupLocatorsChangedLogObjSourceClass

private static final String lookupLocatorsChangedLogObjSourceClass

attrsAddedLogObjSourceClass

private static final String attrsAddedLogObjSourceClass

attrsModifiedLogObjSourceClass

private static final String attrsModifiedLogObjSourceClass

registrationRenewedLogObjSourceClass

private static final String registrationRenewedLogObjSourceClass

registrationCancelledLogObjSourceClass

private static final String registrationCancelledLogObjSourceClass

unknownEventExceptionLogObjSourceClass

private static final String unknownEventExceptionLogObjSourceClass

snapshotThreadSourceClass

private static final String snapshotThreadSourceClass

PRODUCT

private static final String PRODUCT
ServiceInfo product value

See Also:
Constant Field Values

MANUFACTURER

private static final String MANUFACTURER
ServiceInfo manufacturer value

See Also:
Constant Field Values

VENDOR

private static final String VENDOR
ServiceInfo vendor value

See Also:
Constant Field Values

VERSION

private static final String VERSION
ServiceInfo version value

See Also:
Constant Field Values

serverStub

private MailboxBackEnd serverStub
The inner proxy of this server


mailboxProxy

private MailboxProxy mailboxProxy
The outter proxy of this server


mailboxAdminProxy

private MailboxAdminProxy mailboxAdminProxy
The admin proxy of this server


concurrentObj

private final ReadersWriter concurrentObj
Concurrent object (lock) to control read and write access


regByID

private HashMap regByID
Map from Uuid to ServiceRegistration


regByExpiration

private final TreeMap regByExpiration
Identity map of ServiceRegistration, ordered by lease expiration. This is a parallel data structure to regByID.


pendingReg

private List pendingReg
List of ServiceRegistrations that have event delivery enabled, but don't have any event delivery tasks currently scheduled.


activeReg

private Map activeReg
Map of ServiceRegistrations that have event delivery enabled and have event delivery tasks currently scheduled.


log

private ReliableLog log
Reliable log to hold registration state information


LOG_VERSION

private static final int LOG_VERSION
Log format version

See Also:
Constant Field Values

inRecovery

private boolean inRecovery
Flag indicating whether system is in a state of recovery


logFileSize

private int logFileSize
Current number of records in the Log File since the last snapshot


logToSnapshotThreshold

private int logToSnapshotThreshold
Log File must contain this many records before a snapshot is allowed


snapshotNotifier

private final Object snapshotNotifier
Object on which the snapshot-taking thread will synchronize


snapshotter

private Thread snapshotter
Snapshot-taking thread


loginContext

protected LoginContext loginContext
The login context, for logging out


persistenceDirectory

private String persistenceDirectory
Name of persistence directory


listenerPreparer

private ProxyPreparer listenerPreparer
Proxy preparer for listeners


exporter

protected Exporter exporter
The exporter for exporting and unexporting


serviceID

private Uuid serviceID
ServiceID returned from the lookup registration process


activationID

private ActivationID activationID
Our activation ID


activationPrepared

private boolean activationPrepared
Whether the activation ID has been prepared


activationSystem

private ActivationSystem activationSystem
The activation system, prepared


eventLogFactory

private final EventLogFactory eventLogFactory
EventLogIterator generator


leasePolicy

private LeasePeriodPolicy leasePolicy
LeasePeriodPolicy for this service


leaseFactory

private LeaseFactory leaseFactory
LandLordLeaseFactory we use to create leases


localLandlord

private MailboxImpl.LocalLandlordAdaptor localLandlord
LocalLandlord to use with LandlordUtil calls


joiner

private JoinManager joiner
Manager for joining lookup services


lookupDiscMgr

private DiscoveryManagement lookupDiscMgr
DiscoveryManager for joining lookup services. This can always be obtained from the JoinManager, so this is just used as a shortcut.


baseLookupAttrs

private Entry[] baseLookupAttrs
The attributes to use when joining lookup services


lookupAttrs

private Entry[] lookupAttrs

lookupGroups

private String[] lookupGroups
The lookup groups we should join. Default is to join no groups.


lookupLocators

private LookupLocator[] lookupLocators
The lookup locators we should join Default is to join with no locators.


locatorToJoinPreparer

private static ProxyPreparer locatorToJoinPreparer

recoveredLocatorToJoinPreparer

private static ProxyPreparer recoveredLocatorToJoinPreparer

notifier

private MailboxImpl.Notifier notifier
Event delivery thread


eventNotifier

private final Object eventNotifier
Object for coordinating actions with the notification thread


expirer

private MailboxImpl.ExpirationThread expirer
Registration expirer thread


minRegExpiration

private long minRegExpiration
Earliest expiration time of any registration


expirationNotifier

private final Object expirationNotifier
Object for coordinating actions with the expire thread


destroyLock

private final Object destroyLock
Object for coordinating the destroy process


destroySucceeded

private boolean destroySucceeded
Flag that denotes whether or not destroy has already been called. The variable is guarded by destroyLock.


maxUnexportDelay

private long maxUnexportDelay
When destroying the space, how long to wait for a clean unexport (which allows the destroy call to return) before giving up calling unexport(true)


unexportRetryDelay

private long unexportRetryDelay
Length of time to sleep between unexport attempts


readyState

private final ReadyState readyState
Object used to prevent access to this service during the service's initialization or shutdown processing.


lifeCycle

private LifeCycle lifeCycle
LifeCycle object used to notify starter framework that this object's implementation reference, if any, should not be held onto any longer. This is only used in the non-activatable case.


persistent

private boolean persistent
boolean flag used to determine persistence support. Defaulted to true, and overridden in the constructor overload that takes a boolean argument.


MAX_TIME

private static final long MAX_TIME
The maximum time to maintain a notification task

See Also:
Constant Field Values

MAX_ATTEMPTS

private static final int MAX_ATTEMPTS
The maximum mnumber of times to retry event delivery

See Also:
Constant Field Values
Constructor Detail

MailboxImpl

MailboxImpl(ActivationID activationID,
            MarshalledObject data)
      throws Exception
Activation constructor

Parameters:
activationID - activation ID passed in by the activation daemon.
data - state data needed to re-activate a Mercury server
Throws:
Exception

MailboxImpl

MailboxImpl(String[] configArgs,
            LifeCycle lc,
            boolean persistent)
      throws Exception
Constructor for creating transient (i.e. non-activatable) service instances. State information is still logged to persistent storage. This method is only intended for debugging purposes at this time.

Throws:
Exception
Method Detail

getProxy

public Object getProxy()
Description copied from interface: ProxyAccessor
Returns a proxy object for this remote object. If this remote object is not exported (and hence, no proxy is available), then null is returned.

Specified by:
getProxy in interface ProxyAccessor
Returns:
a proxy, or null

getServiceProxy

public Object getServiceProxy()
Description copied from interface: ServiceProxyAccessor
Returns a proxy object for this object. This value should not be null.

Specified by:
getServiceProxy in interface ServiceProxyAccessor
Returns:
a proxy object reference

getAdmin

public Object getAdmin()
                throws RemoteException
Description copied from interface: Administrable
Returns an object that implements whatever administration interfaces are appropriate for the particular service.

Specified by:
getAdmin in interface Administrable
Returns:
an object that implements whatever administration interfaces are appropriate for the particular service.
Throws:
RemoteException
See Also:
JoinAdmin

init

private void init(String[] configArgs)
           throws Exception
Initialization common to both activatable and transient instances.

Throws:
Exception

doInitWithLogin

private void doInitWithLogin(Configuration config,
                             LoginContext loginContext)
                      throws Exception
Method that attempts to login before delegating the rest of the initialization process to doInit

Throws:
Exception

doInit

private void doInit(Configuration config)
             throws Exception
Initialization common to both activatable and transient instances.

Throws:
Exception

rebuildTransientState

private void rebuildTransientState(ProxyPreparer recoveredListenerPreparer)

cleanup

private void cleanup()

register

public MailboxRegistration register(long leaseDuration)
                             throws RemoteException,
                                    LeaseDeniedException
Description copied from interface: EventMailbox
Defines the interface to the event mailbox service. Event mailbox clients utilize this service by invoking the register method to register themselves with the service.

Specified by:
register in interface EventMailbox
Parameters:
leaseDuration - the requested lease duration in milliseconds
Returns:
A new MailboxRegistration
Throws:
RemoteException - if there is a communication failure between the client and the service.
LeaseDeniedException - if the mailbox service is unable or unwilling to grant this registration request.

pullRegister

public MailboxPullRegistration pullRegister(long leaseDuration)
                                     throws RemoteException,
                                            LeaseDeniedException
Description copied from interface: PullEventMailbox
Defines the interface to the event mailbox service. Event mailbox clients utilize this service by invoking the pullRegister method to register themselves with the service.

Specified by:
pullRegister in interface PullEventMailbox
Parameters:
leaseDuration - the requested lease duration in milliseconds
Returns:
A new MailboxPullRegistration
Throws:
RemoteException - if there is a communication failure between the client and the service.
LeaseDeniedException - if the mailbox service is unable or unwilling to grant this registration request.

enableDelivery

public void enableDelivery(Uuid uuid,
                           RemoteEventListener target)
                    throws RemoteException,
                           ThrowThis
Description copied from interface: MailboxBackEnd
Enable delivery of events for the given registration to the specified target

Specified by:
enableDelivery in interface MailboxBackEnd
Parameters:
uuid - The unique registration identifier
target - The designated delivery target for event notifications
Throws:
RemoteException
ThrowThis
See Also:
MailboxRegistration.enableDelivery(net.jini.core.event.RemoteEventListener)

disableDelivery

public void disableDelivery(Uuid uuid)
                     throws RemoteException,
                            ThrowThis
Description copied from interface: MailboxBackEnd
Disable delivery of events for the given registration

Specified by:
disableDelivery in interface MailboxBackEnd
Parameters:
uuid - The unique registration identifier
Throws:
RemoteException
ThrowThis
See Also:
MailboxRegistration.disableDelivery()

getRemoteEvents

public RemoteEventIteratorData getRemoteEvents(Uuid uuid)
                                        throws RemoteException,
                                               ThrowThis
Description copied from interface: MailboxBackEnd
Get events for the given registration via the returned iterator.

Specified by:
getRemoteEvents in interface MailboxBackEnd
Parameters:
uuid - The unique registration identifier
Throws:
RemoteException
ThrowThis
See Also:
MailboxPullRegistration.getRemoteEvents()

getNextBatch

public Collection getNextBatch(Uuid regId,
                               Uuid iterId,
                               long timeout,
                               Object lastEventCookie)
                        throws InvalidIteratorException,
                               ThrowThis
Description copied from interface: MailboxBackEnd
Get next batch of events for the given registration.

Specified by:
getNextBatch in interface MailboxBackEnd
Parameters:
regId - The unique registration identifier
Throws:
InvalidIteratorException
ThrowThis

addUnknownEvents

public void addUnknownEvents(Uuid uuid,
                             Collection unknownEvents)
                      throws RemoteException,
                             ThrowThis
Description copied from interface: MailboxBackEnd
Get events for the given registration

Specified by:
addUnknownEvents in interface MailboxBackEnd
Parameters:
uuid - The unique registration identifier
unknownEvents - collection of unknown events to be added to the associated registration's unknown event list.
Throws:
RemoteException
ThrowThis
See Also:
MailboxPullRegistration.getRemoteEvents()

notify

public void notify(Uuid registrationID,
                   RemoteEvent theEvent)
            throws UnknownEventException,
                   RemoteException,
                   ThrowThis
Description copied from interface: MailboxBackEnd
Collect remote events for the associated registration.

Specified by:
notify in interface MailboxBackEnd
Parameters:
registrationID - The unique registration identifier
theEvent - The event to store and/or forward
Throws:
UnknownEventException
RemoteException
ThrowThis
See Also:
RemoteEventListener.notify(net.jini.core.event.RemoteEvent)

renew

public long renew(Uuid cookie,
                  long extension)
           throws LeaseDeniedException,
                  UnknownLeaseException,
                  RemoteException
Description copied from interface: Landlord
Called by the lease when its renew method is called. Renews the lease that is associated with the given cookie.

Specified by:
renew in interface Landlord
Parameters:
cookie - the Uuid associated with the lease who's renew method was called
extension - argument passed to the renew call
Returns:
The new duration the lease should have
Throws:
LeaseDeniedException - if the landlord is unwilling to renew the lease
UnknownLeaseException - if landlord does not know about a lease with the specified cookie
RemoteException - if a communications failure occurs

cancel

public void cancel(Uuid cookie)
            throws UnknownLeaseException,
                   RemoteException
Description copied from interface: Landlord
Called by the lease when its cancel method is called. Cancels the lease that is associated with the given cookie.

Specified by:
cancel in interface Landlord
Parameters:
cookie - the Uuid associated with the lease who's renew method was called
Throws:
UnknownLeaseException - if landlord does not know about a lease with the specified cookie
RemoteException - if a communications failure occurs

renewAll

public Landlord.RenewResults renewAll(Uuid[] cookies,
                                      long[] extension)
                               throws RemoteException
Description copied from interface: Landlord
Called by the lease map when its renewAll method is called. Should renew the lease that is associated with each element of cookies

Specified by:
renewAll in interface Landlord
Parameters:
cookies - an array of Uuids, each universally and uniquely identifying a lease granted by this Landlord
extension - an array of longs, each representing an a duration in milliseconds that the client wants the lease associated with the Uuid from the corresponding element of cookies renewed for
Returns:
A RenewResults object that contains the new duration of each lease that was successfully renewed or the exception encountered for each lease that could not be renewed
Throws:
RemoteException - if a communications failure occurs

cancelAll

public Map cancelAll(Uuid[] cookies)
              throws RemoteException
Description copied from interface: Landlord
Called by the lease map when its cancelAll method is called. Should cancel the lease that is associated with each element of cookies

Specified by:
cancelAll in interface Landlord
Parameters:
cookies - an array of Uuids, each universally and uniquely identifying a lease granted by this Landlord
Returns:
If all the leases specified in the cookies could be cancelled return null. Otherwise, return a Map that for each failed cancel attempt maps the corresponding cookie object to an exception describing the failure.
Throws:
RemoteException - if a communications failure occurs

destroy

public void destroy()
Description copied from interface: DestroyAdmin
Destroy the service, if possible, including its persistent storage. This method should (in effect) spawn a separate thread to do the actual work asynchronously, and make a reasonable attempt to let this remote call return successfully. As such, a successful return from this method does not mean that the service has been destroyed. Although the service should make a reasonable attempt to let this remote call return successfully, the service must not wait indefinitely for other (in-progress and subsequent) remote calls to finish before proceeding to destroy itself. Once this method has been called, the service can, but need not, reject all other (in-progress and subsequent) remote calls to the service.

Specified by:
destroy in interface DestroyAdmin

getLookupAttributes

public Entry[] getLookupAttributes()
                            throws RemoteException
Description copied from interface: JoinAdmin
Get the current attribute sets for the service.

Specified by:
getLookupAttributes in interface JoinAdmin
Returns:
the current attribute sets for the service
Throws:
RemoteException

addLookupAttributes

public void addLookupAttributes(Entry[] attrSets)
                         throws RemoteException
Description copied from interface: JoinAdmin
Add attribute sets for the service. The resulting set will be used for all future joins. The attribute sets are also added to all currently-joined lookup services.

Specified by:
addLookupAttributes in interface JoinAdmin
Parameters:
attrSets - the attribute sets to add
Throws:
RemoteException

modifyLookupAttributes

public void modifyLookupAttributes(Entry[] attrSetTemplates,
                                   Entry[] attrSets)
                            throws RemoteException
Description copied from interface: JoinAdmin
Modify the current attribute sets, using the same semantics as ServiceRegistration.modifyAttributes. The resulting set will be used for all future joins. The same modifications are also made to all currently-joined lookup services.

Specified by:
modifyLookupAttributes in interface JoinAdmin
Parameters:
attrSetTemplates - the templates for matching attribute sets
attrSets - the modifications to make to matching sets
Throws:
RemoteException
See Also:
ServiceRegistration.modifyAttributes(net.jini.core.entry.Entry[], net.jini.core.entry.Entry[])

getLookupGroups

public String[] getLookupGroups()
                         throws RemoteException
Description copied from interface: JoinAdmin
Get the list of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).

Specified by:
getLookupGroups in interface JoinAdmin
Returns:
an array of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).
Throws:
RemoteException
See Also:
JoinAdmin.setLookupGroups(java.lang.String[])

addLookupGroups

public void addLookupGroups(String[] groups)
                     throws RemoteException
Description copied from interface: JoinAdmin
Add new groups to the set to join. Lookup services in the new groups will be discovered and joined.

Specified by:
addLookupGroups in interface JoinAdmin
Parameters:
groups - groups to join
Throws:
RemoteException
See Also:
JoinAdmin.removeLookupGroups(java.lang.String[])

removeLookupGroups

public void removeLookupGroups(String[] groups)
                        throws RemoteException
Description copied from interface: JoinAdmin
Remove groups from the set to join. Leases are cancelled at lookup services that are not members of any of the remaining groups.

Specified by:
removeLookupGroups in interface JoinAdmin
Parameters:
groups - groups to leave
Throws:
RemoteException
See Also:
JoinAdmin.addLookupGroups(java.lang.String[])

setLookupGroups

public void setLookupGroups(String[] groups)
                     throws RemoteException
Description copied from interface: JoinAdmin
Replace the list of groups to join with a new list. Leases are cancelled at lookup services that are not members of any of the new groups. Lookup services in the new groups will be discovered and joined.

Specified by:
setLookupGroups in interface JoinAdmin
Parameters:
groups - groups to join
Throws:
RemoteException
See Also:
JoinAdmin.getLookupGroups()

getLookupLocators

public LookupLocator[] getLookupLocators()
                                  throws RemoteException
Description copied from interface: JoinAdmin
Get the list of locators of specific lookup services to join.

Specified by:
getLookupLocators in interface JoinAdmin
Returns:
the list of locators of specific lookup services to join
Throws:
RemoteException
See Also:
JoinAdmin.setLookupLocators(net.jini.core.discovery.LookupLocator[])

addLookupLocators

public void addLookupLocators(LookupLocator[] locators)
                       throws RemoteException
Description copied from interface: JoinAdmin
Add locators for specific new lookup services to join. The new lookup services will be discovered and joined.

Specified by:
addLookupLocators in interface JoinAdmin
Parameters:
locators - locators of specific lookup services to join
Throws:
RemoteException
See Also:
JoinAdmin.removeLookupLocators(net.jini.core.discovery.LookupLocator[])

removeLookupLocators

public void removeLookupLocators(LookupLocator[] locators)
                          throws RemoteException
Description copied from interface: JoinAdmin
Remove locators for specific lookup services from the set to join. Any leases held at the lookup services are cancelled.

Specified by:
removeLookupLocators in interface JoinAdmin
Parameters:
locators - locators of specific lookup services to leave
Throws:
RemoteException
See Also:
JoinAdmin.addLookupLocators(net.jini.core.discovery.LookupLocator[])

setLookupLocators

public void setLookupLocators(LookupLocator[] locators)
                       throws RemoteException
Description copied from interface: JoinAdmin
Replace the list of locators of specific lookup services to join with a new list. Leases are cancelled at lookup services that were in the old list but are not in the new list. Any new lookup services will be discovered and joined.

Specified by:
setLookupLocators in interface JoinAdmin
Parameters:
locators - locators of specific lookup services to join
Throws:
RemoteException
See Also:
JoinAdmin.getLookupLocators()

addUnknownEvent

private void addUnknownEvent(Uuid regID,
                             EventID evid)
Utility method that adds the provided EventID to the given registration's "unknown" event list. If the mailbox receives another event, on this registration's behalf, and its EventID is on this list, the service will throw a UnknownEventException back to the event sender.


addUnknownEventDo

private void addUnknownEventDo(Uuid regID,
                               EventID evid)
Performs the actual logic for adding an unknown event to the given registration's unknown event list. Assumes caller holds a write lock.


getServiceRegistration

private ServiceRegistration getServiceRegistration(Uuid regID)
                                            throws ThrowThis
Utility method that tries to obtain the ServiceRegistration object associated with the given Uuid. If there is no associated ServiceRegistration object, or it has expired, this method will throw a "wrapped" NoSuchObjectException. Note: If the NoSuchObjectException was not wrapped, then the RMI system would wrap into a ServerException (since it's a RemoteEvent). The proxies for this service know how to unwrap the ThrowThis object and re-throw the NoSuchObjectException back on the client-side.

Throws:
ThrowThis

removeRegistration

private void removeRegistration(Uuid regID,
                                ServiceRegistration reg)
Utility method that calls the overloaded version that accepts a boolean, which is set to false.


removeRegistration

private void removeRegistration(Uuid regID,
                                ServiceRegistration reg,
                                boolean initializing)
Utility method that consolidates registration removal activities. It's called when registration's are either expired or cancelled.


getEventLogPath

private static File getEventLogPath(String parent,
                                    Uuid uuid)
Utility method that returns the associated File object for the given Uuid's persistence directory


registerDo

private Registration registerDo(long duration)
Actual implementation of the registration process.


addRegistration

private void addRegistration(ServiceRegistration reg)
Utility method used to add a registration to our state information. This method is invoked from registerDo() as well as RegistrationLogObj.apply().


renewDo

private long renewDo(Uuid cookie,
                     long extension)
              throws UnknownLeaseException,
                     LeaseDeniedException
Performs the actual registration renewal logic

Throws:
UnknownLeaseException
LeaseDeniedException

cancelDo

private void cancelDo(Uuid cookie)
               throws UnknownLeaseException
Performs the actual registration cancellation logic

Throws:
UnknownLeaseException

renewAllDo

private Landlord.RenewResults renewAllDo(Uuid[] cookie,
                                         long[] extension)
                                  throws RemoteException
Performs the actual renewAll logic

Throws:
RemoteException

cancelAllDo

private Map cancelAllDo(Uuid[] cookie)
                 throws RemoteException
Performs the actual cancelAll logic

Throws:
RemoteException

enableDeliveryDo

private void enableDeliveryDo(Uuid uuid,
                              RemoteEventListener preparedTarget)
                       throws ThrowThis
Performs the actual enable delivery logic

Throws:
ThrowThis

enableRegistration

private void enableRegistration(Uuid uuid,
                                RemoteEventListener preparedTarget)
                         throws ThrowThis
Utility method that associates the given listener with the associated registration object.

Throws:
ThrowThis

disableDeliveryDo

private void disableDeliveryDo(Uuid uuid)
                        throws ThrowThis
Performs the actual logic for disabling event delivery for a particular registration.

Throws:
ThrowThis

disableRegistration

private void disableRegistration(Uuid uuid)
                          throws ThrowThis
Utility method that disables event delivery for the registration associated with the given UUID

Throws:
ThrowThis

enableRegistrationIterator

private void enableRegistrationIterator(Uuid regId,
                                        Uuid iterId)
                                 throws ThrowThis
Utility method that sets the valid iterator id for provided registration.

Throws:
ThrowThis

disableRegistrationIterator

private void disableRegistrationIterator(Uuid regId)
                                  throws ThrowThis
Utility method that sets the valid iterator id for provided registration.

Throws:
ThrowThis

addUnknownEventsDo

private void addUnknownEventsDo(Uuid uuid,
                                Collection unknownEvents)
                         throws ThrowThis
Performs the actual logic for synchronously getting events for a particular registration.

Throws:
ThrowThis

getRemoteEventsDo

private RemoteEventIteratorData getRemoteEventsDo(Uuid uuid)
                                           throws ThrowThis
Performs the actual logic for synchronously getting events for a particular registration.

Throws:
ThrowThis

getNextBatchDo

private Collection getNextBatchDo(Uuid regId,
                                  Uuid iterId,
                                  long timeout,
                                  Object lastEventCookie)
                           throws InvalidIteratorException,
                                  ThrowThis
Does the actual logic for obtaining the next set of events for the given registration. Assumes caller holds a write lock.

Throws:
InvalidIteratorException
ThrowThis

validateIterator

private void validateIterator(Uuid regId,
                              Uuid iterId)
                       throws InvalidIteratorException,
                              ThrowThis
Throws:
InvalidIteratorException
ThrowThis

notifyDo

private void notifyDo(Uuid registrationID,
                      RemoteEvent theEvent)
               throws UnknownEventException,
                      RemoteException,
                      ThrowThis
Performs the actual logic of handling received events and storing them.

Throws:
UnknownEventException
RemoteException
ThrowThis

marshalAttributes

private static MarshalledObject[] marshalAttributes(Entry[] attrs)
Marshals each element of the Entry[] array parameter. This method is static so that it may called from the static LogRecord classes when a set of attributes is being logged to persistent storage.

Parameters:
attrs - Entry[] array consisting of the attributes to marshal
Returns:
array of MarshalledObject[], where each element corresponds to an attribute in marshalled form

unmarshalAttributes

private static Entry[] unmarshalAttributes(MarshalledObject[] marshalledAttrs)
Unmarshals each element of the MarshalledObject array parameter. This method is static so that it may called from the static LogRecord classes when a set of attributes is being recovered from persistent storage.

Parameters:
marshalledAttrs - MarshalledObject array consisting of the attributes to unmarshal
Returns:
array of Entry[], where each element corresponds to an attribute that was successfully unmarshalled

addLogRecord

private void addLogRecord(MailboxImpl.LogRecord rec)
Add a state-change record to persistent storage.

Whenever a significant change occurs to the Mercury's state, this method is invoked to record that change in a file called a log file. Each record written to the log file is an object reflecting both the data used and the ACTIONS taken to make one change to the Mercury's state at a particular point in time. If the number of records contained in the log file exceeds the pre-defined threshold, a snapshot of the current state of the Mercury will be recorded.

Whenever one of the following state changes occurs, this method will be invoked with the appropriate implementation of the LogRecord interface as the input argument.

See Also:
MailboxImpl.LocalLogHandler

takeSnapshot

private void takeSnapshot(OutputStream out)
                   throws IOException
Write the current state of the Mercury to persistent storage.

A 'snapshot' of the Mercury's current state is represented by the data contained in certain fields of the Mercury. That data represents many changes -- over time -- to the Mercury's state. This method will record that data to a file referred to as the snapshot file.

The data written by this method to the snapshot file -- as well as the format of the file -- is shown below:

Each data item is written to the snapshot file in serialized form. Note that event state is kept separately and maintained by the event logging mechanism.

Throws:
IOException

recoverSnapshot

private void recoverSnapshot(InputStream in)
                      throws IOException,
                             ClassNotFoundException
Retrieve the contents of the snapshot file and reconstitute the 'base' state of the Mercury from the retrieved data.

The data retrieved by this method from the snapshot file is shown below:

During recovery, the state of the Mailbox at the time of a crash or outage is re-constructed by first reconstituting the 'base state' from the snapshot file; and then modifying that base state according to the records retrieved from the log file. This method is invoked to perform the first step in that reconstruction.

Throws:
IOException
ClassNotFoundException

dumpGroups

private static void dumpGroups(String[] grps,
                               Logger logger,
                               Level level)
Utility method for displaying lookup group attributes


dumpLocators

private static void dumpLocators(LookupLocator[] locs,
                                 Logger logger,
                                 Level level)
Utility method for displaying lookup locator attributes


dumpAttrs

private static void dumpAttrs(Entry[] attrs,
                              Logger logger,
                              Level level)
Utility method for displaying lookup service attributes


initFailed

protected void initFailed(Throwable e)
                   throws Exception
Log information about failing to initialize the service and rethrow the appropriate exception.

Parameters:
e - the exception produced by the failure
Throws:
Exception

prepareNewLocators

private static void prepareNewLocators(ProxyPreparer preparer,
                                       LookupLocator[] locators)
                                throws RemoteException
Using the given ProxyPreparer, attempts to prepare each element of the given LookupLocator array; replacing the original element of the array with the result of the call to the method ProxyPreparer.prepareProxy. If any attempt to prepare an element of the given array fails due to an exception, this method will propagate that exception. This method is a convenience method that is typically used to prepare new locators the service should discover and join that are inserted into, or removed from, the service's state through the use of one of the following methods:

Parameters:
preparer - the preparer to use to prepare each element of the input array
locators - array of LookupLocator instances in which each element will be prepared.
Throws:
RemoteException - when preparation of any of the elements of the input array fails because of a RemoteException
SecurityException - when preparation of any of the elements of the input array fails because of a SecurityException

prepareExistingLocators

private static LookupLocator[] prepareExistingLocators(ProxyPreparer preparer,
                                                       LookupLocator[] lookupLocators)

getProxyVerifier

public TrustVerifier getProxyVerifier()
Description copied from interface: ServerProxyTrust
Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy. The verifier should be able to verify all proxies for the service, including proxies for resources (such as leases and registrations).

Specified by:
getProxyVerifier in interface ServerProxyTrust
Returns:
a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service

ensureCurrent

private static boolean ensureCurrent(LeasedResource resource)
Utility method that check for valid resource



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