blackboard.persist
Class Id

java.lang.Object
  blackboard.persist.Id

All Implemented Interfaces:

java.lang.Comparable

Direct Known Subclasses:

PkId, UnsetId

public abstract class Id
extends java.lang.Object
implements java.lang.Comparable

Provides the basis for object identifiers within the persistence framework.

Since:

Bb 5.5

Version:

$Revision: #1 $ $Date: 2007/06/27 $

Field Summary

static Id

UNSET_ID

Constructor Summary

protected	Id(Container container, DataType dataType) Creates Id identifying it with the given container and data type values.
protected	Id(DataType dataType) Creates an Id identifying it with the given data type value.

Method Summary

void	assertIsSet() Asserts that this Id is "set" -- has a value.
void	assertMatchesContainer(Container targetContainer) Asserts that the Container value associated with this Id matches the provided Container value.
void	assertMatchesDataType(DataType targetDataType) Asserts that the DataType value associated with this Id matches the provided DataType value.
abstract int	compareTo(java.lang.Object obj) The sole method of the Comparable interface.
abstract boolean	equals(java.lang.Object obj) Overrides the equals() method in Object to provide a simple way to compare two Ids.
static Id	generateId(DataType dataType, int nKey1) Generates an Id instance using the default database persistence manager as given by context.
static Id	generateId(DataType dataType, int nKey1, int nKey2) Generates an Id instance using the default database persistence manager as given by context.
static Id	generateId(DataType dataType, java.lang.String strKey) Generates an Id instance using the default database persistence manager as given by context.
Container	getContainer() Returns the Container associated with this Id.
DataType	getDataType() Returns the DataType associated with this Id.
java.lang.String	getExternalString() A simple bean-based wrapper around the method toExternalString() which allows the external string to be accessed as a bean property.
boolean	getIsSet()
abstract int	hashCode() Returns a hash code value for the object.
boolean	hasSameContainer(Id id) Returns true if the given Id has the same Container as this Id instance.
boolean	hasSameDataType(Id id) Returns true if the given Id has the same DataType as this Id instance.
abstract boolean	isSet() Determines if the Id has been set (is not in default state).
static boolean	isValid(Id id) Determines if the given Id value is "valid".
BbObject	load() Loads the BbObject derived value that matches the current id value.
java.lang.Object	loadObject() Loads the Object derived value that matches the current id value.
boolean	matchesContainer(Container targetContainer) Returns true if the given Container matches the Container of this Id.
boolean	matchesDataType(DataType targetDataType) Returns true if the given DataType matches the DataType of this Id.
static Id	newId(DataType dataType) Returns a new Id instance, using a default implementation.
void	setContainer(Container container) Associates the given Container with this Id.
void	setDataType(DataType dataType) Associates the given DataType with this Id.
abstract java.lang.String	toExternalString() Converts the Id into its String representation.
abstract java.lang.String	toString() Converts the Id into its String representation.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNSET_ID

public static final Id UNSET_ID

Constructor Detail

Id

protected Id(Container container,
             DataType dataType)

Creates Id identifying it with the given container and data type values.

Parameters:

container - the Container in which the object this id refers to resides. Can not be null.

dataType - the DataType of the object that this id refers to. Can not be null. If no data type is presently desired pass in DataType.NULL_DATA_TYPE.

Id

protected Id(DataType dataType)

Creates an Id identifying it with the given data type value. This method of Id construction should be used when creating an Id that has no relationship to a container (such as UnsetId) and the normal Id constructor (Id(Container,DataType)) would therefore complain regarding a null container value being provided. This method of construction should never be used by an Id type that could be used with a Container since it bypasses the null checking performed on the container value.

Parameters:

container - the Container in which the object this Id refers to resides

dataType - the DataType of the object that this Id refers to. Can not be null. If no data type is presently desired pass in DataType.NULL_DATA_TYPE.

Method Detail

isSet

public abstract boolean isSet()

Determines if the Id has been set (is not in default state).

Returns:

true if the Id is set, false otherwise.

getIsSet

public boolean getIsSet()

assertIsSet

public final void assertIsSet()
                       throws KeyNotFoundException

Asserts that this Id is "set" -- has a value.

Throws:

KeyNotFoundException - if this Id has not been set

assertMatchesDataType

public final void assertMatchesDataType(DataType targetDataType)
                                 throws KeyNotFoundException

Asserts that the DataType value associated with this Id matches the provided DataType value.

Throws:

KeyNotFoundException - if the data type of this Id does not match the provided data type

assertMatchesContainer

public final void assertMatchesContainer(Container targetContainer)
                                  throws KeyNotFoundException

Asserts that the Container value associated with this Id matches the provided Container value.

Throws:

KeyNotFoundException - if the container of this Id does not match the provided container

hasSameDataType

public boolean hasSameDataType(Id id)

Returns true if the given Id has the same DataType as this Id instance. If the data type in the given Id is null, then true is returned only if this Id's data type is also null.

Parameters:

id - the Id value to use in the comparison

Returns:

true if the data type of the given Id matches the data type of this Id, false otherwise

hasSameContainer

public boolean hasSameContainer(Id id)

Returns true if the given Id has the same Container as this Id instance. If the container in the given Id is null, then true is returned only if this Id's container is also null.

Parameters:

id - the Id value to use in the comparison

Returns:

true if the container of the given Id matches the container of this Id, false otherwise

matchesDataType

public boolean matchesDataType(DataType targetDataType)

Returns true if the given DataType matches the DataType of this Id.

Parameters:

targetDataType - the DataType to use in the comparison

Returns:

true is the given data type matches the data type of this Id

matchesContainer

public boolean matchesContainer(Container targetContainer)

Returns true if the given Container matches the Container of this Id.

Parameters:

targetContainer - the Container to use in the comparison

Returns:

true is the given container matches the container of this Id

getContainer

public Container getContainer()

Returns the Container associated with this Id.

Returns:

the Container associated with this id

setContainer

public void setContainer(Container container)

Associates the given Container with this Id.

Parameters:

container - the Container to associate with this id. Can not be null.

getDataType

public DataType getDataType()

Returns the DataType associated with this Id.

Returns:

the DataType associated with this id

setDataType

public void setDataType(DataType dataType)

Associates the given DataType with this Id.

Parameters:

dataType - the DataType to associate with this Id. Can not be null. If no data type is presently desired pass in DataType.NULL_DATA_TYPE.

equals

public abstract boolean equals(java.lang.Object obj)

Overrides the equals() method in Object to provide a simple way to compare two Ids.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to be compared.

Returns:

true if the two Objects are the same, false otherwise.

compareTo

public abstract int compareTo(java.lang.Object obj)
                       throws java.lang.ClassCastException

The sole method of the Comparable interface. Used for sorting and natural-ordering algorithms.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the object to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.ClassCastException - thrown if the specified object's type prevents it from being compared to this Object

hashCode

public abstract int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.Hashtable .

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object as an int

toExternalString

public abstract java.lang.String toExternalString()

Converts the Id into its String representation. The output of this method is designed to create an able to be parsed (not necessarily human- readable) representation of this Id value. If a human-readable form of this Id is desired, use toString().

The string generated by this method is said to be "able to be parsed" because it is designed to be used as the key value input when generating a new id value using the methods provided in BbPersistenceManager and Container. The output of this method may be the same as that generated by toString(), but it is not guaranteed to be. As a result, this method should be used whenever a string value is desired that can later be converted back into a proper Id value.

Returns:

A String representation of the Id that is able to be parsed. If the id has not been set, the string ("{unset id}") should be returned.

See Also:

toString(), BbPersistenceManager.generateId(DataType,String), Container.generateId(DataType,String)

getExternalString

public java.lang.String getExternalString()

A simple bean-based wrapper around the method toExternalString() which allows the external string to be accessed as a bean property.

Returns:

A String representation of the Id consistent with the output generated by toExternalString()

See Also:

toExternalString()

toString

public abstract java.lang.String toString()

Converts the Id into its String representation. The output of this method is designed to create a human-readable (not necessarily able to be parsed) representation of this Id value. If an "able to be parsed" form of this Id is desired, use toExternalString().

Overrides:

toString in class java.lang.Object

Returns:

A String representation of the Id that is human-readable.

See Also:

toExternalString()

newId

public static Id newId(DataType dataType)

Returns a new Id instance, using a default implementation. The resulting Id will be typed according to the supplied DataType and have an automatically generated unique key value. The Id generated from this call is not associated (and can not be) with a container. It represents an object that has not come from a container but has been created in memory. As a result, the Ids generated by this call can not be used for performing container object lookups. Objects with ids generated from this method can be persisted to a container though. In order to generate Ids that can be used for performing Container lookups, see BbPersistenceManager and the Container type against which a lookup wishes to be performed.

Parameters:

dataType - the DataType to associate with created Id

Returns:

a new Id instance using a default implementation

See Also:

BbPersistenceManager.generateId(DataType,String), BbPersistenceManager.generateId(DataType,int,int), Container.generateId(DataType,String), Container.generateId(DataType,int,int)

isValid

public static boolean isValid(Id id)

Determines if the given Id value is "valid". Valid is defined as not being null, is set (see isSet()), and with a valid data type value.

This method should not be used to determine if an id value is a valid id for a specific container. To do that, use Container.isValidId(Id) instead.

Parameters:

id - the Id value to check

Returns:

true if the given Id is valid, false otherwise

generateId

public static Id generateId(DataType dataType,
                            java.lang.String strKey)
                     throws PersistenceException

Generates an Id instance using the default database persistence manager as given by context.

See BbPersistenceManager.generateId(DataType,String) for more information.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

strKey - the String value to use when generating the key value of the Id instance

Returns:

a database Id generated from the provided datatype and key

Throws:

PersistenceException

Since:

Bb 6.0.11

generateId

public static Id generateId(DataType dataType,
                            int nKey1,
                            int nKey2)
                     throws PersistenceException

Generates an Id instance using the default database persistence manager as given by context.

See BbPersistenceManager.generateId(DataType,int,int) for more information.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

nKey1 - an integer value to use when generating the key value of the Id instance

nKey2 - another integer value to use when generating the key value of the Id instance

Returns:

a database Id generated from the provided datatype and keys

Throws:

PersistenceException

Since:

Bb 6.0.11

generateId

public static Id generateId(DataType dataType,
                            int nKey1)
                     throws PersistenceException

Generates an Id instance using the default database persistence manager as given by context.

See BbPersistenceManager.generateId(DataType,int) for more information.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

nKey1 - an integer value to use when generating the key value of the Id instance

Returns:

a database Id generated from the provided datatype and key

Throws:

PersistenceException

Since:

Bb 6.0.11

load

public final BbObject load()
                    throws PersistenceException

Loads the BbObject derived value that matches the current id value.

The behavior of this method is Container specific. As such, each container-specific Id type should implement this method to suit the needs of that specific container. This, default implementation throws a RuntimeException.

Returns:

the BbObject derived value that matches the current id value

Throws:

PersistenceException - if an error occurs while loading the object

Since:

Bb 6.0.11

loadObject

public java.lang.Object loadObject()
                            throws PersistenceException

Loads the Object derived value that matches the current id value.

The behavior of this method is Container specific. As such, each container-specific Id type should implement this method to suit the needs of that specific container. This, default implementation throws a RuntimeException.

Returns:

the Object derived value that matches the current id value

Throws:

PersistenceException - if an error occurs while loading the object

Since:

7.2