alma::acs::container::archive::Range Class Reference

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

Public Member Functions
	Range (IdentifierRange identifierRange)
long	getLength ()
boolean	isLocked ()
void	assignUniqueEntityId (EntityT entity) throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx
void	replaceUniqueEntityId (EntityT entity) throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx
void	assignUniqueEntityRef (EntityRefT ref) throws AcsJRangeUnlockedEx, AcsJRangeExhaustedEx
boolean	hasNextID ()
URI	next () throws AcsJIdentifierUnexpectedEx, AcsJRangeExhaustedEx
URI	rangeId () throws AcsJIdentifierUnexpectedEx
final String	rangeIdString ()
Static Public Member Functions
static final String	generateUID (String _archiveID, String _rangeID, long _localId)
Package Functions
long	getMaxDocumentId ()
Private Member Functions
void	setUniqueEntityId (EntityT entity, boolean allowReplacing) throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx
String	getNextID () throws AcsJRangeExhaustedEx
Private Attributes
final String	archiveid
final boolean	isLocked
final String	rangeid
final AtomicLong	documentid
final long	minDocumentid
final long	maxDocumentid

Detailed Description

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 & Destructor Documentation

alma::acs::container::archive::Range::Range ( IdentifierRange identifierRange ) [inline]

References archiveid, documentid, isLocked(), maxDocumentid, minDocumentid, and rangeid.

Member Function Documentation

void alma::acs::container::archive::Range::assignUniqueEntityId ( EntityT entity ) throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx [inline]

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.

References setUniqueEntityId().

Referenced by alma::acs::container::archive::UIDLibrary::assignUniqueEntityId().

void alma::acs::container::archive::Range::assignUniqueEntityRef ( EntityRefT ref ) throws AcsJRangeUnlockedEx, AcsJRangeExhaustedEx [inline]

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

References getNextID(), isLocked(), rangeIdString(), and alma::ArchiveIdentifierError::wrappers::AcsJRangeUnlockedEx::setRange().

Referenced by alma::acs::container::archive::UIDLibrary::assignUniqueEntityRef().

static final String alma::acs::container::archive::Range::generateUID	(	String	_archiveID,
		String	_rangeID,
		long	_localId
	)			`[inline, static]`

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.

Referenced by getNextID().

long alma::acs::container::archive::Range::getLength ( ) [inline]

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

References maxDocumentid, and minDocumentid.

long alma::acs::container::archive::Range::getMaxDocumentId ( ) [inline, package]

References maxDocumentid.

Referenced by getNextID().

String alma::acs::container::archive::Range::getNextID ( ) throws AcsJRangeExhaustedEx [inline, private]

Returns a UID that is constructed from the archiveID, the rangeID, and the running local document ID.

References archiveid, documentid, generateUID(), getMaxDocumentId(), maxDocumentid, rangeid, rangeIdString(), alma::ArchiveIdentifierError::wrappers::AcsJRangeExhaustedEx::setRange(), and alma::ArchiveIdentifierError::wrappers::AcsJRangeExhaustedEx::setRangeMaxDocumentId().

Referenced by assignUniqueEntityRef(), next(), and setUniqueEntityId().

boolean alma::acs::container::archive::Range::hasNextID ( ) [inline]

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.

References documentid, and maxDocumentid.

Referenced by alma::acs::container::archive::UIDLibrary::checkDefaultRange().

boolean alma::acs::container::archive::Range::isLocked ( ) [inline]

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.

Referenced by assignUniqueEntityRef(), Range(), and setUniqueEntityId().

URI alma::acs::container::archive::Range::next ( ) throws AcsJIdentifierUnexpectedEx, AcsJRangeExhaustedEx [inline]

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:

Exceptions:

AcsJIdentifierUnexpectedEx

References getNextID().

URI alma::acs::container::archive::Range::rangeId ( ) throws AcsJIdentifierUnexpectedEx [inline]

Gets the UID of this range document itself.

Exceptions:

AcsJIdentifierUnexpectedEx

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

References rangeIdString().

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

final String alma::acs::container::archive::Range::rangeIdString ( ) [inline]

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

References archiveid, and rangeid.

Referenced by assignUniqueEntityRef(), getNextID(), rangeId(), and setUniqueEntityId().

void alma::acs::container::archive::Range::replaceUniqueEntityId ( EntityT entity ) throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx [inline]

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.

References setUniqueEntityId().

Referenced by alma::acs::container::archive::UIDLibrary::replaceUniqueEntityId().

void alma::acs::container::archive::Range::setUniqueEntityId	(	EntityT	entity,
		boolean	allowReplacing
	)			throws AcsJUidAlreadyExistsEx, AcsJRangeLockedEx, AcsJRangeExhaustedEx `[inline, private]`