alma.acs.container.archive

Class Range

java.lang.Object

alma.acs.container.archive.Range

public class Range
extends java.lang.Object

This class represents a range of UIDs as created by the Alma archive, and allows using them as XML document IDs or links to XML documents. A range is always limited to a finite number of UIDs, given either by an explicitly requested limit, or otherwise by Long.MAX_VALUE many UIDs.

This class is implemented as an intelligent wrapper for the castor class IdentifierRange which itself gets generated from the schema "IdentifierRange.xsd".

For a better description, see the Archive/UidLibrary wiki page.

General remark on the length of UIDs: there is no limit on the length of the three "/x012af" parts of a UID, as was confirmed by awicenec to hsommer on 2007-04-20. It is therefore the Archive's responsibility to ensure that all code dealing with UIDs (which should all be under archive responsibility anyway) be updated accordingly whenever the actually generated UIDs exceed the "Long" limit.

Author:

simon, hsommer

Constructor Summary

Constructors

Constructor and Description
Range(IdentifierRange identifierRange)

Method Summary

Modifier and Type	Method and Description
void	assignUniqueEntityId(EntityT entity) Assigns a UID to the EntityT castor object that should be a direct child of an Alma XML entity.
void	assignUniqueEntityRef(EntityRefT ref) Assigns a UID from the range to a given entity reference.
static java.lang.String	generateUID(java.lang.String _archiveID, java.lang.String _rangeID, long _localId) This method is only exposed for testing purposes, when a UID has to be generated from its constituent parts.
long	getLength()
boolean	hasNextID() Checks whether another UID can be pulled from this range without causing an exception due to an overflow.
boolean	isLocked() A range can be either locked or unlocked.
java.net.URI	next() cryptic comment from Simon: TODO: this needs to be moved to protected soon, will require the ArchiveID web service to be moved to this namespace
java.net.URI	rangeId() Gets the UID of this range document itself.
java.lang.String	rangeIdString() Gets a String representation of the UID of this range document itself.
void	replaceUniqueEntityId(EntityT entity) Assigns a UID to the EntityT castor object that should be a direct child of an Alma XML entity.

Methods inherited from class java.lang.Object

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

Constructor Detail

Range

public Range(IdentifierRange identifierRange)

Method Detail

getLength

public long getLength()

Returns:

number of UIDs in the range (no matter how many UIDs have been used so far)

isLocked

public boolean isLocked()

A range can be either locked or unlocked. This immutable property was originally called "serialised" but was considered too confusing since this logical concept has nothing to do with technically serializing the castor class to XML.

TODO: explain better the real meaning of this locking, and the forseen scenarios.

Returns:

true if this object represents a locked range.

assignUniqueEntityId

public void assignUniqueEntityId(EntityT entity)
                          throws AcsJUidAlreadyExistsEx,
                                 AcsJRangeLockedEx,
                                 AcsJRangeExhaustedEx

Assigns a UID to the EntityT castor object that should be a direct child of an Alma XML entity. As a means of protection, this call will fail if the entity already has a UID. If you actually need to replace a UID in some rare cases, please use replaceUniqueEntityId(EntityT).

The same functionality is offered in ContainerServices#assignUniqueEntityId(EntityT) which actually delegates to here.

Throws:

AcsJUidAlreadyExistsEx

AcsJRangeLockedEx

AcsJRangeExhaustedEx

replaceUniqueEntityId

public void replaceUniqueEntityId(EntityT entity)
                           throws AcsJUidAlreadyExistsEx,
                                  AcsJRangeLockedEx,
                                  AcsJRangeExhaustedEx

Assigns a UID to the EntityT castor object that should be a direct child of an Alma XML entity. Unlike #assignUniqueEntityID, this method will silently replace any existing UID, which is possibly dangerous. Therefore it should only be used in rare cases where replacing an existing ID is needed, for example when the ObsPrep tool might translate locally created documents into an archivable format.

Throws:

AcsJUidAlreadyExistsEx

AcsJRangeLockedEx

AcsJRangeExhaustedEx

assignUniqueEntityRef

public void assignUniqueEntityRef(EntityRefT ref)
                           throws AcsJRangeUnlockedEx,
                                  AcsJRangeExhaustedEx

Assigns a UID from the range to a given entity reference. Note that this is different from assigning a UID to an entity. This method only works if this range is locked, see isLocked().

Parameters:

ref -

Throws:

AcsJRangeUnlockedEx

AcsJRangeExhaustedEx

generateUID

public static final java.lang.String generateUID(java.lang.String _archiveID,
                                                 java.lang.String _rangeID,
                                                 long _localId)

This method is only exposed for testing purposes, when a UID has to be generated from its constituent parts. You should normally not use this method.

hasNextID

public boolean hasNextID()

Checks whether another UID can be pulled from this range without causing an exception due to an overflow.

Warning about thread safety: This method does not reserve a UID or anything like that, thus a returned true value does not necessarily mean that a later call to one of the assignXYZ etc methods will succeed.

Returns:

true if at least one more UID can be retrieved from this range.

next

public java.net.URI next()
                  throws AcsJIdentifierUnexpectedEx,
                         AcsJRangeExhaustedEx

cryptic comment from Simon: TODO: this needs to be moved to protected soon, will require the ArchiveID web service to be moved to this namespace

Returns:

Throws:

AcsJIdentifierUnexpectedEx

AcsJRangeExhaustedEx

rangeId

public java.net.URI rangeId()
                     throws AcsJIdentifierUnexpectedEx

Gets the UID of this range document itself.

Throws:

AcsJIdentifierUnexpectedEx - if the string from rangeIdString() cannot be turned into a URI

rangeIdString

public final java.lang.String rangeIdString()

Gets a String representation of the UID of this range document itself.