alma.acs.container.archive.UIDLibrary Class Reference

List of all members.

Public Member Functions
	UIDLibrary (Logger logger)
synchronized void	assignUniqueEntityId (EntityT entity, IdentifierJ identifier) throws AcsJUidAlreadyExistsEx, AcsJIdentifierUnavailableEx, AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx
synchronized void	replaceUniqueEntityId (EntityT entity, IdentifierJ identifier) throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx, AcsJIdentifierUnexpectedEx
URI	getNewRestrictedRange (int size, String user, IdentifierJ identifier, boolean printLogs) throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx
URI	getNewRestrictedRange (int size, String user, IdentifierJ identifier) throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx
void	assignUniqueEntityId (EntityT entity, URI uri, boolean printLogs) throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx
void	assignUniqueEntityId (EntityT entity, URI uri) throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx
void	fetchRange (URI uri, String user, IdentifierJ identifier) throws AcsJRangeUnavailableEx
void	assignUniqueEntityRef (EntityRefT ref, URI uri) throws AcsJRangeUnavailableEx, AcsJRangeExhaustedEx, AcsJRangeUnlockedEx
Protected Member Functions
synchronized void	checkDefaultRange (IdentifierJ identifier) throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx

---

Detailed Description

Library-style class that facilitates the use of UID ranges obtained from the identifier archive.

• The most commonly used feature should be that of assigning a new UID to an XML entity that does not yet have a UID; the method assignUniqueEntityId(EntityT, IdentifierJ) could be used for this, although it is recommended to instead use the convenience method ContainerServices#assignUniqueEntityId(EntityT) from the ContainerServices. Here the caller is not expected to care about to which range of UIDs the new UID belongs, as long as it is a valid and unique ID.
• For exotic cases (perhaps ObsPrep) where an existing (e.g. locally created) UID must be replaced by a UID that's valid in the archive, this class offers the method replaceUniqueEntityId(EntityT, IdentifierJ).
• Other more specialized methods allow using specific ranges of UIDs, which is intended for cases where one component allocates a range and then some other component uses these IDs. As of 2006-09, the only known use case for this is an interaction between Control and Correlator, which will rely only on the C++ version of this class.

Implementation notes: this class has been pulled up from Archive to ACS in order to share the implementation between the ContainerServices and this library, which otherwise could have remained in the Archive modules. We did not want to split this class, therefore even the methods that ACS does not need are all included here.
Simon's original implementation has been thoroughly changed: most notably this class is no longer used as a singleton, which would have caused severe identity and lifecycle problems with logger and identifier archive objects getting shared among independent components. So far we've kept the original design that hides explicitly requested Range objects by only referring to them through their UIDs in methods assignUniqueEntityId(EntityT, URI), assignUniqueEntityRef(EntityRefT, URI) etc., but it is not clear how useful this is.

Author:

simon, hsommer

---

Constructor & Destructor Documentation

alma.acs.container.archive.UIDLibrary.UIDLibrary

(

Logger

logger

)

Creates the UIDLibrary without making any calls.

Parameters:

logger

Logger used by this object.

---

Member Function Documentation

synchronized void alma.acs.container.archive.UIDLibrary.assignUniqueEntityId	(	EntityT	entity,
		IdentifierJ	identifier
	)			throws AcsJUidAlreadyExistsEx, AcsJIdentifierUnavailableEx, AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx

Assigns a UID from the default range to the EntityT castor class of an XML-based entity such as a SchedBlock.

Implementation note: the default range of UIDs is retrieved from the archive at the first call and is then shared among instances in order to be frugal on UIDs and to minimize archive access. This means that often the passed in identifier will not be used at all but still must be provided, because the calling component can not know whether another component or the container has called this method before. This method is synchronized to avoid the very unlikely situation that defaultRange.hasNextId succeeds for one thread but then later assigning the UID still fails because of another thread having stolen the last free UID in the meantime.

Parameters:

identifier

the identifier archive from which a new Range can be obtained if necessary. Use ContainerServices.getTransparentXmlComponent(IdentifierJ.class, identRaw, IdentifierOperations.class); to create the required XML binding class aware interface from the plain-Corba Identifier object (identRaw) that is obtained, for example, by IdentifierHelper.narrow(getDefaultComponent("IDL:alma/xmlstore/Identifier:1.0")).

See also:

ContainerServices.assignUniqueEntityId(EntityT)

References alma.acs.container.archive.Range.assignUniqueEntityId(), and alma.acs.container.archive.UIDLibrary.checkDefaultRange().

Referenced by alma.acs.container.archive.UIDLibrary.assignUniqueEntityId(), and alma.acs.container.ContainerServicesImpl.assignUniqueEntityId().

void alma.acs.container.archive.UIDLibrary.assignUniqueEntityId	(	EntityT	entity,
		URI	uri,
		boolean	printLogs
	)			throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx

Assigns a uid to the EntityT from the specified range. This is not permitted with a locked Range object. This method should only be used in very special cases, see Archive/UidLibrary wiki page!

TODO: figure out if this is meant to work only if the Range referenced by uri has been loaded previously by this instance. If so, put a comment that fetchRange must be called first. Otherwise the fetch method could be called automatically.

Parameters:

	entity
	uri	the UID of the Range object
	printLogs	set to true, iff logs should be printed

References alma.acs.container.archive.Range.assignUniqueEntityId().

void alma.acs.container.archive.UIDLibrary.assignUniqueEntityId	(	EntityT	entity,
		URI	uri
	)			throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx

convenience method for the above, printLogs is set to true

References alma.acs.container.archive.UIDLibrary.assignUniqueEntityId().

void alma.acs.container.archive.UIDLibrary.assignUniqueEntityRef	(	EntityRefT	ref,
		URI	uri
	)			throws AcsJRangeUnavailableEx, AcsJRangeExhaustedEx, AcsJRangeUnlockedEx

Assigns a UID to an entity reference. This method should only be used in very special cases, see Archive/UidLibrary wiki page! Note that this operation is only permitted with a locked range.

Parameters:

	ref	the schema-generated entity reference
	uri

Exceptions:

UniqueIdException

References alma.acs.container.archive.Range.assignUniqueEntityRef().

synchronized void alma.acs.container.archive.UIDLibrary.checkDefaultRange

(

IdentifierJ

identifier

)

throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx [protected]

Creates a default range on demand, or sets a new default range if the old range has no more UID (which happens after pulling Long.MAX UIDs, or sooner if a limit was set).

Parameters:

identifier

the identifier archive from which a new Range can be obtained if necessary. Use ContainerServices.getTransparentXmlComponent(IdentifierJ.class, identRaw, IdentifierOperations.class); to create the required XML binding class aware interface from the plain-Corba Identifier object (identRaw) that is obtained, for example, by IdentifierHelper.narrow(getDefaultComponent("IDL:alma/xmlstore/Identifier:1.0")).

References alma.acs.container.archive.Range.hasNextID().

Referenced by alma.acs.container.archive.UIDLibrary.assignUniqueEntityId(), and alma.acs.container.archive.UIDLibrary.replaceUniqueEntityId().

void alma.acs.container.archive.UIDLibrary.fetchRange	(	URI	uri,
		String	user,
		IdentifierJ	identifier
	)			throws AcsJRangeUnavailableEx

Fetch an existing range from the archive and deserialise, only certain operations will be permitted. This method should only be used in very special cases, see Archive/UidLibrary wiki page!

Parameters:

	uri
	identifier	the identifier archive from which a new Range can be obtained if necessary. Use ContainerServices.getTransparentXmlComponent(IdentifierJ.class, identRaw, IdentifierOperations.class); to create the required XML binding class aware interface from the plain-Corba Identifier object (identRaw) that is obtained, for example, by IdentifierHelper.narrow(getDefaultComponent("IDL:alma/xmlstore/Identifier:1.0")).

Exceptions:

AcsJRangeUnavailableEx

URI alma.acs.container.archive.UIDLibrary.getNewRestrictedRange	(	int	size,
		String	user,
		IdentifierJ	identifier,
		boolean	printLogs
	)			throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx

Fetches a new restricted range. This will return a URI allowing access to the new Range. The range is automatically stored in the archive. This method should only be used in very special cases, see Archive/UidLibrary wiki page!

Parameters:

	identifier	the identifier archive from which a new Range can be obtained if necessary. Use ContainerServices.getTransparentXmlComponent(IdentifierJ.class, identRaw, IdentifierOperations.class); to create the required XML binding class aware interface from the plain-Corba Identifier object (identRaw) that is obtained, for example, by IdentifierHelper.narrow(getDefaultComponent("IDL:alma/xmlstore/Identifier:1.0")).
	printLogs	Emit logs, iff set to true.

Returns:

the UID of the range, which can be used for example as an argument in assignUniqueEntityId(EntityT, URI).

Exceptions:

UniqueIdException

if the range cannot be obtained from the archive.

References alma.acs.container.archive.Range.rangeId().

Referenced by alma.acs.container.archive.UIDLibrary.getNewRestrictedRange().

URI alma.acs.container.archive.UIDLibrary.getNewRestrictedRange	(	int	size,
		String	user,
		IdentifierJ	identifier
	)			throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx

convenience method for the above, printLogs is set to true

References alma.acs.container.archive.UIDLibrary.getNewRestrictedRange().

synchronized void alma.acs.container.archive.UIDLibrary.replaceUniqueEntityId	(	EntityT	entity,
		IdentifierJ	identifier
	)			throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx, AcsJIdentifierUnexpectedEx

Similar to assignUniqueEntityId(EntityT, IdentifierJ), but allows replacing an existing ID. Only in very special cases such as ObsPrep replacing locally-generated IDs with archive-generated UIDs should this method be used. Replacing UIDs can easily corrupt the archive because existing links would no longer hold!

Parameters:

identifier

the identifier archive from which a new Range can be obtained if necessary. Use ContainerServices.getTransparentXmlComponent(IdentifierJ.class, identRaw, IdentifierOperations.class); to create the required XML binding class aware interface from the plain-Corba Identifier object (identRaw) that is obtained, for example, by IdentifierHelper.narrow(getDefaultComponent("IDL:alma/xmlstore/Identifier:1.0")).

See also:

assignUniqueEntityId(EntityT, IdentifierJ)

References alma.acs.container.archive.UIDLibrary.checkDefaultRange(), and alma.acs.container.archive.Range.replaceUniqueEntityId().

---

The documentation for this class was generated from the following file:

• UIDLibrary.java