alma.acs.container.archive

Class UIDLibrary

java.lang.Object

alma.acs.container.archive.UIDLibrary

public class UIDLibrary
extends java.lang.Object

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 Summary

Constructors

Constructor and Description
UIDLibrary(java.util.logging.Logger logger) Creates the UIDLibrary without making any calls.

Method Summary

Modifier and Type	Method and Description
void	assignUniqueEntityId(EntityT entity, IdentifierJ identifier) Assigns a UID from the default range to the EntityT castor class of an XML-based entity such as a SchedBlock.
void	assignUniqueEntityId(EntityT entity, java.net.URI uri) convenience method for the above, printLogs is set to true
void	assignUniqueEntityId(EntityT entity, java.net.URI uri, boolean printLogs) Assigns a uid to the EntityT from the specified range.
void	assignUniqueEntityRef(EntityRefT ref, java.net.URI uri) Assigns a UID to an entity reference.
protected void	checkDefaultRange(IdentifierJ identifier) 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).
void	fetchRange(java.net.URI uri, java.lang.String user, IdentifierJ identifier) Fetch an existing range from the archive and deserialise, only certain operations will be permitted.
java.net.URI	getNewRestrictedRange(int size, java.lang.String user, IdentifierJ identifier) convenience method for the above, printLogs is set to true
java.net.URI	getNewRestrictedRange(int size, java.lang.String user, IdentifierJ identifier, boolean printLogs) Fetches a new restricted range.
void	replaceUniqueEntityId(EntityT entity, IdentifierJ identifier) Similar to assignUniqueEntityId(EntityT, IdentifierJ), but allows replacing an existing ID.

Methods inherited from class java.lang.Object

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

Constructor Detail

UIDLibrary

public UIDLibrary(java.util.logging.Logger logger)

Creates the UIDLibrary without making any calls.

Parameters:

logger - Logger used by this object.

Method Detail

assignUniqueEntityId

public void 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")).

Throws:

AcsJUidAlreadyExistsEx

AcsJIdentifierUnavailableEx

AcsJRangeUnavailableEx

AcsJIdentifierUnexpectedEx

See Also:

ContainerServices#assignUniqueEntityId(EntityT)

replaceUniqueEntityId

public void 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")).

Throws:

AcsJRangeUnavailableEx

AcsJIdentifierUnavailableEx

AcsJIdentifierUnexpectedEx

See Also:

assignUniqueEntityId(EntityT, IdentifierJ)

checkDefaultRange

protected void checkDefaultRange(IdentifierJ identifier)
                          throws AcsJRangeUnavailableEx,
                                 AcsJIdentifierUnavailableEx

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")).

Throws:

AcsJRangeUnavailableEx

AcsJIdentifierUnavailableEx

getNewRestrictedRange

public java.net.URI getNewRestrictedRange(int size,
                                          java.lang.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).

Throws:

UniqueIdException - if the range cannot be obtained from the archive.

AcsJRangeUnavailableEx

AcsJIdentifierUnexpectedEx

getNewRestrictedRange

public java.net.URI getNewRestrictedRange(int size,
                                          java.lang.String user,
                                          IdentifierJ identifier)
                                   throws AcsJRangeUnavailableEx,
                                          AcsJIdentifierUnexpectedEx

convenience method for the above, printLogs is set to true

Throws:

AcsJRangeUnavailableEx

AcsJIdentifierUnexpectedEx

assignUniqueEntityId

public void assignUniqueEntityId(EntityT entity,
                                 java.net.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

Throws:

AcsJRangeUnavailableEx

AcsJUidAlreadyExistsEx

AcsJRangeLockedEx

AcsJRangeExhaustedEx

assignUniqueEntityId

public void assignUniqueEntityId(EntityT entity,
                                 java.net.URI uri)
                          throws AcsJRangeUnavailableEx,
                                 AcsJUidAlreadyExistsEx,
                                 AcsJRangeLockedEx,
                                 AcsJRangeExhaustedEx

convenience method for the above, printLogs is set to true

Throws:

AcsJRangeUnavailableEx

AcsJUidAlreadyExistsEx

AcsJRangeLockedEx

AcsJRangeExhaustedEx

fetchRange

public void fetchRange(java.net.URI uri,
                       java.lang.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")).

Throws:

AcsJRangeUnavailableEx

assignUniqueEntityRef

public void assignUniqueEntityRef(EntityRefT ref,
                                  java.net.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 -

Throws:

UniqueIdException

AcsJRangeUnavailableEx

AcsJRangeExhaustedEx

AcsJRangeUnlockedEx