com.sun.jini.norm.lookup
Class JoinState

java.lang.Object
  extended by com.sun.jini.reliableLog.LogHandler
      extended by com.sun.jini.norm.lookup.JoinState
All Implemented Interfaces:
SubStore

public class JoinState
extends LogHandler
implements SubStore

Utility class that combines JoinManager with persistence.

Author:
Sun Microsystems, Inc.

Field Summary
private  Entry[] attributes
          Pass through to get attribute array from the log recovery method to the code that creates the JoinManager
private  Configuration config
          Configuration, to supply initial attributes, groups, and locators
private  DiscoveryManagement dm
          The DiscoveryManagement we are using to find lookups, which must also implement DiscoveryGroupManagement and DiscoveryLocatorManagement.
private  String[] groups
          Pass through to get lookup group array from the log recovery method to the code that creates the JoinManager
private  JoinManager joinMgr
          Our join manager
private  LookupLocator[] locators
          Pass through to get lookup locator array from the log recovery method to the code that creates the JoinManager
private  ReliableLog log
          Log we are using to persist our state to disk, or null if not persistent.
private static Logger logger
          Logger for logging messages
private  LeaseRenewalManager lrm
          Lease renewal manager (if any) that the client wants our JoinManager to use.
private static String NORM
          Logger and configuration component name for Norm
private  boolean recoveredData
          Set to true if there was existing persistent data that was recovered -- used to determine if the JoinState is being created for the first time.
private  ProxyPreparer recoveredLookupLocatorPreparer
          Proxy preparer for recovered lookup locators
(package private)  Object service
          Service we are registering with lookup services
private  Entry[] serviceAttributes
          Attributes supplied by the service
private  ServiceID serviceID
          The service ID, derived from the service's UUID.
 
Constructor Summary
JoinState(Object service, LeaseRenewalManager lrm, Configuration config, Entry[] serviceAttributes, ProxyPreparer recoveredLookupLocatorPreparer, ServiceID serviceID)
          Simple constructor.
 
Method Summary
 void addAttributes(Entry[] attrSets, boolean checkSC)
          Add attribute sets for the service.
 void addGroups(String[] groups)
          Add new groups to the set to join.
 void addLocators(LookupLocator[] locators)
          Add locators for specific new lookup services to join.
 void applyUpdate(Object update)
          This method always throws UnsupportedOperationException since JoinState should never update a log.
private  void createDiscoveryManager()
          Creates the discovery manager.
private  Object[] getArrayEntry(String name, Class type, Object defaultValue)
          Returns a configuration entry that is an array of objects, checking that all the elements of the array are non-null.
 Entry[] getAttributes()
          Get the current attribute sets for the service.
 String[] getGroups()
          Get the list of groups to join.
private  void getInitialEntries()
          Retrieves the initial values for attributes, groups, and locators from the configuration.
 LookupLocator[] getLocators()
          Get the list of locators of specific lookup services to join.
private static void logThrow(Level level, String method, String msg, Object[] msgParams, Throwable t)
          Logs a throw
 void modifyAttributes(Entry[] attrSetTemplates, Entry[] attrSets, boolean checkSC)
          Modify the current attribute sets, using the same semantics as ServiceRegistration.modifyAttributes.
 void prepareDestroy()
          Informs the SubStore that the service is being destroyed and it should perform any necessary cleanup (closing files for example).
private static Entry[] readAttributes(ObjectInputStream in)
          Utility method to read in an array of entities from a ObjectInputStream.
 void recover(InputStream in)
          Read the snapshot from a stream.
 void removeGroups(String[] groups)
          Remove groups from the set to join.
 void removeLocators(LookupLocator[] locators)
          Remove locators for specific lookup services from the set to join.
 void setDirectory(File dir)
          Gives the SubStore a piece of the file system to use for its store.
 void setGroups(String[] groups)
          Replace the list of groups to join with a new list.
 void setLocators(LookupLocator[] locators)
          Replace the list of locators of specific lookup services to join with a new list.
 void snapshot(OutputStream out)
          Writes the snapshot to a stream.
 String subDirectory()
          If this components wants its own sub-directory, it should return a non-null string that will be its sub-directory's name.
private  void takeSnapshot()
          Used by all the methods that change persistent state to commit the change to disk
 void terminateJoin()
          Terminate our participation in the Join and discovery Protocols.
private static void writeAttributes(Entry[] attributes, ObjectOutputStream out)
          Utility method to write out an array of entities to an ObjectOutputStream.
 
Methods inherited from class com.sun.jini.reliableLog.LogHandler
readUpdate, writeUpdate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NORM

private static final String NORM
Logger and configuration component name for Norm

See Also:
Constant Field Values

logger

private static final Logger logger
Logger for logging messages


service

final Object service
Service we are registering with lookup services


lrm

private final LeaseRenewalManager lrm
Lease renewal manager (if any) that the client wants our JoinManager to use.


config

private final Configuration config
Configuration, to supply initial attributes, groups, and locators


serviceAttributes

private final Entry[] serviceAttributes
Attributes supplied by the service


recoveredLookupLocatorPreparer

private final ProxyPreparer recoveredLookupLocatorPreparer
Proxy preparer for recovered lookup locators


serviceID

private final ServiceID serviceID
The service ID, derived from the service's UUID.


log

private ReliableLog log
Log we are using to persist our state to disk, or null if not persistent.


recoveredData

private boolean recoveredData
Set to true if there was existing persistent data that was recovered -- used to determine if the JoinState is being created for the first time.


attributes

private Entry[] attributes
Pass through to get attribute array from the log recovery method to the code that creates the JoinManager


groups

private String[] groups
Pass through to get lookup group array from the log recovery method to the code that creates the JoinManager


locators

private LookupLocator[] locators
Pass through to get lookup locator array from the log recovery method to the code that creates the JoinManager


dm

private DiscoveryManagement dm
The DiscoveryManagement we are using to find lookups, which must also implement DiscoveryGroupManagement and DiscoveryLocatorManagement.


joinMgr

private JoinManager joinMgr
Our join manager

Constructor Detail

JoinState

public JoinState(Object service,
                 LeaseRenewalManager lrm,
                 Configuration config,
                 Entry[] serviceAttributes,
                 ProxyPreparer recoveredLookupLocatorPreparer,
                 ServiceID serviceID)
          throws IOException
Simple constructor.

Parameters:
service - the object to register with lookup
lrm - a LeaseRenewalManager to pass to the JoinManager. May be null.
config - a configuration that supplies initial attributes, groups, and locators
serviceAttributes - attributes supplied by the service
recoveredLookupLocatorPreparer - proxy preparer for recovered lookup locators
serviceID - the service ID for the service
Throws:
IOException
Method Detail

subDirectory

public String subDirectory()
Description copied from interface: SubStore
If this components wants its own sub-directory, it should return a non-null string that will be its sub-directory's name. If it does not need its own sub-directory this method should return null.

Specified by:
subDirectory in interface SubStore

setDirectory

public void setDirectory(File dir)
                  throws IOException,
                         ConfigurationException
Description copied from interface: SubStore
Gives the SubStore a piece of the file system to use for its store.

Specified by:
setDirectory in interface SubStore
Parameters:
dir - the directory to use
Throws:
IOException - if there is a problem initializing its store or recovering its state
ConfigurationException - if this is a problem configuring this object

logThrow

private static void logThrow(Level level,
                             String method,
                             String msg,
                             Object[] msgParams,
                             Throwable t)
Logs a throw


getArrayEntry

private Object[] getArrayEntry(String name,
                               Class type,
                               Object defaultValue)
                        throws ConfigurationException
Returns a configuration entry that is an array of objects, checking that all the elements of the array are non-null.

Throws:
ConfigurationException

getInitialEntries

private void getInitialEntries()
                        throws ConfigurationException
Retrieves the initial values for attributes, groups, and locators from the configuration.

Throws:
ConfigurationException

createDiscoveryManager

private void createDiscoveryManager()
                             throws ConfigurationException,
                                    IOException
Creates the discovery manager.

Throws:
ConfigurationException
IOException

prepareDestroy

public void prepareDestroy()
Description copied from interface: SubStore
Informs the SubStore that the service is being destroyed and it should perform any necessary cleanup (closing files for example). The store does not need to delete it's data.

Specified by:
prepareDestroy in interface SubStore

terminateJoin

public void terminateJoin()
Terminate our participation in the Join and discovery Protocols. Note, this method leaves the logs intact.


snapshot

public void snapshot(OutputStream out)
              throws IOException
Description copied from class: LogHandler
Writes the snapshot to a stream. This callback is invoked when the client calls the snaphot method of ReliableLog.

Specified by:
snapshot in class LogHandler
Parameters:
out - the output stream
Throws:
IOException

recover

public void recover(InputStream in)
             throws Exception
Description copied from class: LogHandler
Read the snapshot from a stream. This callback is invoked when the client calls the recover method of ReliableLog.

Specified by:
recover in class LogHandler
Parameters:
in - the input stream
Throws:
Exception - can raise any exception

applyUpdate

public void applyUpdate(Object update)
                 throws Exception
This method always throws UnsupportedOperationException since JoinState should never update a log.

Specified by:
applyUpdate in class LogHandler
Parameters:
update - the update object
Throws:
Exception - can raise any exception

writeAttributes

private static void writeAttributes(Entry[] attributes,
                                    ObjectOutputStream out)
                             throws IOException
Utility method to write out an array of entities to an ObjectOutputStream. Can be recovered by a call to readAttributes()

Packages each attribute in its own MarshalledObject so a bad codebase on an attribute class will not corrupt the whole array.

Throws:
IOException

readAttributes

private static Entry[] readAttributes(ObjectInputStream in)
                               throws IOException,
                                      ClassNotFoundException
Utility method to read in an array of entities from a ObjectInputStream. Array should have been written by a call to writeAttributes().

Will try and recover as many attributes as possible. Attributes which can't be recovered won't be returned but they will remain in the log (though they will be lost when the next snapshot is taken).

Throws:
IOException
ClassNotFoundException

takeSnapshot

private void takeSnapshot()
                   throws IOException
Used by all the methods that change persistent state to commit the change to disk

Throws:
IOException

getGroups

public String[] getGroups()
Get the list of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).

Returns:
an array of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).

addGroups

public void addGroups(String[] groups)
Add new groups to the set to join. Lookup services in the new groups will be discovered and joined.

Parameters:
groups - groups to join

removeGroups

public void removeGroups(String[] groups)
Remove groups from the set to join. Leases are cancelled at lookup services that are not members of any of the remaining groups.

Parameters:
groups - groups to leave

setGroups

public void setGroups(String[] groups)
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.

Parameters:
groups - groups to join

getLocators

public LookupLocator[] getLocators()
Get the list of locators of specific lookup services to join.

Returns:
the list of locators of specific lookup services to join

addLocators

public void addLocators(LookupLocator[] locators)
Add locators for specific new lookup services to join. The new lookup services will be discovered and joined.

Parameters:
locators - locators of specific lookup services to join

removeLocators

public void removeLocators(LookupLocator[] locators)
Remove locators for specific lookup services from the set to join. Any leases held at the lookup services are cancelled.

Parameters:
locators - locators of specific lookup services to leave

setLocators

public void setLocators(LookupLocator[] locators)
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.

Parameters:
locators - locators of specific lookup services to join

getAttributes

public Entry[] getAttributes()
Get the current attribute sets for the service.

Returns:
the current attribute sets for the service

addAttributes

public void addAttributes(Entry[] attrSets,
                          boolean checkSC)
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.

Parameters:
attrSets - the attribute sets to add
checkSC - boolean flag indicating whether the elements of the set of attributes to add should be checked to determine if they are service controlled
Throws:
SecurityException - when the checkSC parameter is true, and at least one of the attributes to be added is an instance of the ServiceControlled marker interface

modifyAttributes

public void modifyAttributes(Entry[] attrSetTemplates,
                             Entry[] attrSets,
                             boolean checkSC)
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.

Parameters:
attrSetTemplates - the templates for matching attribute sets
attrSets - the modifications to make to matching sets
checkSC - boolean flag indicating whether elements of the set of attributes to add should be checked to determine if they are service controlled
Throws:
SecurityException - when the checkSC parameter is true, and at least one of the attributes to be added is an instance of the ServiceControlled marker interface
See Also:
ServiceRegistration.modifyAttributes(net.jini.core.entry.Entry[], net.jini.core.entry.Entry[])


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