Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

alma::acs::container::archive::UIDLibrary Class Reference

Collaboration diagram for alma::acs::container::archive::UIDLibrary:

Collaboration graph
[legend]
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

Private Attributes

final Logger logger
final HashMap< URI, RangeidRanges
final HashMap< URI, RangerefRanges

Static Private Attributes

volatile Range defaultRange

Detailed Description

Library-style class that facilitates the use of UID ranges obtained from the identifier archive. 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  )  [inline]
 

Creates the UIDLibrary without making any calls.

Parameters:
logger Logger used by this object.


Member Function Documentation

void alma::acs::container::archive::UIDLibrary::assignUniqueEntityId EntityT  entity,
URI  uri
throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx [inline]
 

convenience method for the above, printLogs is set to true

void alma::acs::container::archive::UIDLibrary::assignUniqueEntityId EntityT  entity,
URI  uri,
boolean  printLogs
throws AcsJRangeUnavailableEx, AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx [inline]
 

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

synchronized void alma::acs::container::archive::UIDLibrary::assignUniqueEntityId EntityT  entity,
IdentifierJ  identifier
throws AcsJUidAlreadyExistsEx, AcsJIdentifierUnavailableEx, AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx [inline]
 

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)

void alma::acs::container::archive::UIDLibrary::assignUniqueEntityRef EntityRefT  ref,
URI  uri
throws AcsJRangeUnavailableEx, AcsJRangeExhaustedEx, AcsJRangeUnlockedEx [inline]
 

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 

synchronized void alma::acs::container::archive::UIDLibrary::checkDefaultRange IdentifierJ  identifier  )  throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx [inline, 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")).

void alma::acs::container::archive::UIDLibrary::fetchRange URI  uri,
String  user,
IdentifierJ  identifier
throws AcsJRangeUnavailableEx [inline]
 

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
throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx [inline]
 

convenience method for the above, printLogs is set to true

URI alma::acs::container::archive::UIDLibrary::getNewRestrictedRange int  size,
String  user,
IdentifierJ  identifier,
boolean  printLogs
throws AcsJRangeUnavailableEx, AcsJIdentifierUnexpectedEx [inline]
 

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.

synchronized void alma::acs::container::archive::UIDLibrary::replaceUniqueEntityId EntityT  entity,
IdentifierJ  identifier
throws AcsJRangeUnavailableEx, AcsJIdentifierUnavailableEx, AcsJIdentifierUnexpectedEx [inline]
 

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)


Member Data Documentation

volatile Range alma::acs::container::archive::UIDLibrary::defaultRange [static, private]
 

final HashMap<URI, Range> alma::acs::container::archive::UIDLibrary::idRanges [private]
 

final Logger alma::acs::container::archive::UIDLibrary::logger [private]
 

final HashMap<URI, Range> alma::acs::container::archive::UIDLibrary::refRanges [private]
 


The documentation for this class was generated from the following file:
Generated on Thu Apr 30 02:52:31 2009 for ACS Java API by doxygen 1.3.8