org.apache.river.norm.lookup

Class JoinState

java.lang.Object

org.apache.river.reliableLog.LogHandler

org.apache.river.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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
JoinState(Object service, LeaseRenewalManager lrm, Configuration config, Entry[] serviceAttributes, ProxyPreparer recoveredLookupLocatorPreparer, ServiceID serviceID) Simple constructor.

Method Summary

Modifier and Type	Method and Description
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 org.apache.river.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[])