atg.service.idgen
Class AbstractSequentialIdGenerator

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.service.idgen.AbstractSequentialIdGenerator

All Implemented Interfaces:

atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, IdGenerator, java.util.EventListener

Direct Known Subclasses:

PersistentIdGenerator, TransientIdGenerator

public abstract class AbstractSequentialIdGenerator
extends GenericService
implements IdGenerator

Base class for IdGenerator services that generate sequential ids. This class implements a simple counter mechanism for generating ids.

This class makes use of IdSpaces. Ids are unique within an IdSpace, but not necessarily across IdSpaces. This allows a single id generator to generate ids for a related set of objects.

This class provides the a default IdSpace, which is always available. This class does not make use of the batchSize or lastSeed properties of IdSpace.

See Also:

IdSpace

Field Summary

static java.lang.String	CLASS_VERSION Class version string
protected static java.lang.String	ERR_BAD_SPACE
protected static java.lang.String	ERR_ROLLBACK
protected static java.lang.String	ERR_UNSUPPORTED
protected java.util.Map	mSpaces currently defined id spaces
protected static java.lang.String	RESOURCE_BUNDLE_NAME resource bundle name
protected static java.util.ResourceBundle	sResourceBundle resource bundle

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

AbstractSequentialIdGenerator()
Construct a generator

Method Summary

boolean	addIdSpace(IdSpace pSpace) Add an id space to the id generator.
void	doStartService() Start the service
static java.lang.String	format(java.lang.String pMsgKey) Utility for formatting messages with no arguments
static java.lang.String	format(java.lang.String pMsgKey, java.lang.Object pArg) Utility for formatting messages with a single argument
static java.lang.String	format(java.lang.String pMsgKey, java.lang.Object[] pArgs) Utility for formatting predefined messages using the current resource bundle.
static java.lang.String	format(java.lang.String pMsgKey, java.lang.Object pArg1, java.lang.Object pArg2) Utility for formatting messages with two arguments
long	generateLongId() Generate a long id in the default name space
long	generateLongId(java.lang.String pIdSpaceName) Generate a long id in the specified name space.
java.lang.String	generateStringId() Generate a String id in the default name space.
java.lang.String	generateStringId(java.lang.String pIdSpaceName) Generate a string id in the specified name space.
boolean	getAutoCreate() Get property autoCreate
protected static java.util.ResourceBundle	getBundle() Get the resource bundle for this class to use.
IdSpace	getDefaultIdSpace() Get property DefaultIdSpace
java.lang.String	getDefaultIdSpaceName() Get property DefaultIdSpaceName
IdSpace	getIdSpace(java.lang.String pName) Get a copy of the named id space from the generator.
java.util.Map	getIdSpaces() Get a copy of all the spaces defined in the generator.
static java.lang.String	getResourceBundleName() Get name of resource bundle.
void	initialize() Initialize the generator.
boolean	isAutoCreate() Test property autoCreate
protected long	postGenerateLongId(java.lang.String pIdSpaceName, long pCandidateId) Hook for subclasses to change the generated id if desired.
protected java.lang.String	postGenerateStringId(java.lang.String pIdSpaceName, java.lang.String pCandidateId) Hook for subclasses to change the generated id if desired.
void	removeAllIdSpaces() Remove all id spaces from the id generator.
boolean	removeIdSpace(IdSpace pSpace) Remove an id space from the id generator.
void	setAutoCreate(boolean pAutoCreate) Set property autoCreate
void	setDefaultIdSpace(IdSpace pDefaultIdSpace) Set property DefaultIdSpace.
void	setDefaultIdSpaceName(java.lang.String pDefaultIdSpaceName) Set property DefaultIdSpaceName.
void	setHighWaterMark(java.lang.String pIdSpaceName, long pHighWaterMark) Set the high water mark for the specified id space.
java.lang.String	toString() Get a string representation of this object

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

sResourceBundle

protected static java.util.ResourceBundle sResourceBundle

resource bundle

RESOURCE_BUNDLE_NAME

protected static java.lang.String RESOURCE_BUNDLE_NAME

resource bundle name

ERR_UNSUPPORTED

protected static java.lang.String ERR_UNSUPPORTED

ERR_BAD_SPACE

protected static java.lang.String ERR_BAD_SPACE

ERR_ROLLBACK

protected static java.lang.String ERR_ROLLBACK

mSpaces

protected java.util.Map mSpaces

currently defined id spaces

Constructor Detail

AbstractSequentialIdGenerator

public AbstractSequentialIdGenerator()

Construct a generator

Method Detail

setDefaultIdSpaceName

public void setDefaultIdSpaceName(java.lang.String pDefaultIdSpaceName)

Set property DefaultIdSpaceName. If the DefaultIdSpace is non-null we use its name instead.

Parameters:

pDefaultIdSpaceName - new value to set

getDefaultIdSpaceName

public java.lang.String getDefaultIdSpaceName()

Get property DefaultIdSpaceName

Returns:

DefaultIdSpaceName

setDefaultIdSpace

public void setDefaultIdSpace(IdSpace pDefaultIdSpace)

Set property DefaultIdSpace. Causes the DefaultIdSpaceName property to be set as well.

Parameters:

pDefaultIdSpace - new value to set

getDefaultIdSpace

public IdSpace getDefaultIdSpace()

Get property DefaultIdSpace

Specified by:

getDefaultIdSpace in interface IdGenerator

Returns:

DefaultIdSpace

setAutoCreate

public void setAutoCreate(boolean pAutoCreate)

Set property autoCreate

Specified by:

setAutoCreate in interface IdGenerator

Parameters:

pAutoCreate - new value to set

getAutoCreate

public boolean getAutoCreate()

Get property autoCreate

Specified by:

getAutoCreate in interface IdGenerator

Returns:

autoCreate

isAutoCreate

public boolean isAutoCreate()

Test property autoCreate

Specified by:

isAutoCreate in interface IdGenerator

Returns:

autoCreate

generateLongId

public long generateLongId()
                    throws IdGeneratorException

Generate a long id in the default name space

Specified by:

generateLongId in interface IdGenerator

Returns:

the id

Throws:

IdGeneratorException - if there is an error generating the id

generateStringId

public java.lang.String generateStringId()
                                  throws IdGeneratorException

Generate a String id in the default name space.

Specified by:

generateStringId in interface IdGenerator

Returns:

the id

Throws:

IdGeneratorException - if there is an error generating the id

generateLongId

public long generateLongId(java.lang.String pIdSpaceName)
                    throws IdGeneratorException

Generate a long id in the specified name space. This method calls the postGenerateLongId() hook on the id generated.

Specified by:

generateLongId in interface IdGenerator

Parameters:

pIdSpaceName - name of id space to use, null means use the anonymous, default space

Returns:

the new id

Throws:

IdGeneratorException - if there is an error generating the id

generateStringId

public java.lang.String generateStringId(java.lang.String pIdSpaceName)
                                  throws IdGeneratorException

Generate a string id in the specified name space. This method generates a long id, converts it to a String and then adds the prefix and suffix defined to the specified id space. This method calls the postGenerateStringId() hook on the id generated, but it does not call the postGenerateLongId() hook.

Specified by:

generateStringId in interface IdGenerator

Parameters:

pIdSpaceName - name of id space to use, null means use the anonymous, default space

Returns:

the new id

Throws:

IdGeneratorException - if there is an error generating the id

getIdSpace

public IdSpace getIdSpace(java.lang.String pName)

Get a copy of the named id space from the generator.

Specified by:

getIdSpace in interface IdGenerator

Parameters:

name - of id space to get

Returns:

a copy of the named id space

getIdSpaces

public java.util.Map getIdSpaces()

Get a copy of all the spaces defined in the generator.

Specified by:

getIdSpaces in interface IdGenerator

Returns:

a Map of all the id spaces defined in the generator. The keys of the Map are the names of the spaces, and the values are IdSpace objects

addIdSpace

public boolean addIdSpace(IdSpace pSpace)
                   throws IdGeneratorException

Add an id space to the id generator. The id space must not be null.

Specified by:

addIdSpace in interface IdGenerator

Parameters:

pSpace - space to add, cannot be null

Returns:

true if the space is added, or false if a space with the same name already exists in this id generator

Throws:

java.lang.IllegalArgumentException - if the specified space is null or otherwise invalid

IdGeneratorException - if there is trouble adding the space

removeIdSpace

public boolean removeIdSpace(IdSpace pSpace)
                      throws IdGeneratorException

Remove an id space from the id generator. The id space must not be null. Removing an id space causes information associated with that id space to be lost. Take care that no facility is still using an id space before removing it.

Specified by:

removeIdSpace in interface IdGenerator

Parameters:

pSpace - space to remove, cannot be null

Returns:

true if the space is removed, or false if it is not known to this id generator

Throws:

java.lang.IllegalArgumentException - if the specified space is null or otherwise invalid

IdGeneratorException - if there is trouble removing the space

removeAllIdSpaces

public void removeAllIdSpaces()
                       throws IdGeneratorException

Remove all id spaces from the id generator. Removing id spaces causes information associated with those id spaces to be lost. Take care that no facility is still using any of the id spaces before removing them.

Specified by:

removeAllIdSpaces in interface IdGenerator

Throws:

IdGeneratorException - if there is trouble adding the space

initialize

public void initialize()
                throws IdGeneratorException

Initialize the generator. Wipe out all id spaces and install the default id space.

Specified by:

initialize in interface IdGenerator

Throws:

IdGeneratorException - if there is an error initializing

postGenerateLongId

protected long postGenerateLongId(java.lang.String pIdSpaceName,
                                  long pCandidateId)
                           throws IdGeneratorException

Hook for subclasses to change the generated id if desired. Default behavior is to return the id unchanged.

Parameters:

pCandidateId - suggested generated id

Returns:

generated id actually returned to applications

Throws:

IdGeneratorException - if there is an error generating the id

postGenerateStringId

protected java.lang.String postGenerateStringId(java.lang.String pIdSpaceName,
                                                java.lang.String pCandidateId)
                                         throws IdGeneratorException

Hook for subclasses to change the generated id if desired. Default behavior is to return the id unchanged.

Parameters:

pCandidateId - suggested generated id

Returns:

generated id actually returned to applications

Throws:

IdGeneratorException - if there is an error generating the id

doStartService

public void doStartService()
                    throws ServiceException

Start the service

Overrides:

doStartService in class GenericService

Throws:

ServiceException - if there is a problem starting up

toString

public java.lang.String toString()

Get a string representation of this object

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this object

setHighWaterMark

public void setHighWaterMark(java.lang.String pIdSpaceName,
                             long pHighWaterMark)
                      throws IdGeneratorException

Set the high water mark for the specified id space. If this method returns normally, the id generator guarantees it won't give out any ids whose integer component is less than or equal to the specified id.

Parameters:

pIdSpaceName - name of id space to use

pHighWaterMark - high water mark to set

Throws:

IdGeneratorException - if this feature is not supported for this id generator or if the id generator cannot guarantee that the specified high water mark can be set

format

public static java.lang.String format(java.lang.String pMsgKey,
                                      java.lang.Object[] pArgs)

Utility for formatting predefined messages using the current resource bundle.

Parameters:

pMsgKey - message id to format

pArgs - arguments to fill in in message

format

public static java.lang.String format(java.lang.String pMsgKey)

Utility for formatting messages with no arguments

format

public static java.lang.String format(java.lang.String pMsgKey,
                                      java.lang.Object pArg)

Utility for formatting messages with a single argument

format

public static java.lang.String format(java.lang.String pMsgKey,
                                      java.lang.Object pArg1,
                                      java.lang.Object pArg2)

Utility for formatting messages with two arguments

getResourceBundleName

public static java.lang.String getResourceBundleName()

Get name of resource bundle. Subclasses should override this to use their own resource bundles

Returns:

the fully qualified name of the bundle, suitable for loading as a system resource.

getBundle

protected static java.util.ResourceBundle getBundle()

Get the resource bundle for this class to use.

Returns:

resource bundle