blackboard.persist
Class PkId

java.lang.Object
  blackboard.persist.Id
      blackboard.persist.PkId

All Implemented Interfaces:

java.lang.Comparable

public class PkId
extends Id

The PkId class provides the means of describing an Id within a Blackboard database container.

Since:

Bb 5.5

Version:

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

Field Summary

static int

DEFAULT_PK2

Fields inherited from class blackboard.persist.Id

UNSET_ID

Constructor Summary

PkId(Container container, DataType dataType, int nPk1, int nPk2)
Instantiate a new PkId with the given Container, DataType, and pk key values as integers.

PkId(Container container, DataType dataType, java.lang.String strPk)
Instantiate a new PkId with the given Container, DataType, and pk key values as a single string.

PkId(Container container, DataType dataType, java.lang.String strPk1, java.lang.String strPk2)
Instantiate a new PkId with the given Container, DataType, and pk key values as strings.

Method Summary

int	compareTo(java.lang.Object obj) The sole method of the Comparable interface.
boolean	equals(java.lang.Object obj) Overrides the equals() method in Object to provide a simple way to compare two PkIds.
int	getPk1() Returns the primary key value of this PkId (PK1).
int	getPk2() Returns the secondary key value of this PkId (PK2 or SOS_ID).
int	hashCode() Allow Ids to be used as a key in a hashtable.
boolean	isSet() Determines if the PkId has been set.
BbObject	load() Overrides load method in the base class to implement a "load by id" operation for a database id (and thus for a database container).
java.lang.String	toExternalString() Converts this PkId into its String representation.
java.lang.String	toString() Converts this PkId into its String representation.

Methods inherited from class blackboard.persist.Id

assertIsSet, assertMatchesContainer, assertMatchesDataType, generateId, generateId, generateId, getContainer, getDataType, hasSameContainer, hasSameDataType, matchesContainer, matchesDataType, newId, setContainer, setDataType

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PK2

public static final int DEFAULT_PK2

See Also:

Constant Field Values

Constructor Detail

PkId

public PkId(Container container,
            DataType dataType,
            int nPk1,
            int nPk2)
     throws java.lang.IllegalArgumentException

Instantiate a new PkId with the given Container, DataType, and pk key values as integers.

Parameters:

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

dataType - the DataType of the object that this Id refers to

nPk1 - An int representing the primary key value.

nPk2 - An int representing the secondary primary key value (SOS_ID).

Throws:

java.lang.IllegalArgumentException - thrown if either of the integer values is not a valid key representation (i.e., a negative value).

PkId

public PkId(Container container,
            DataType dataType,
            java.lang.String strPk1,
            java.lang.String strPk2)
     throws java.lang.IllegalArgumentException

Instantiate a new PkId with the given Container, DataType, and pk key values as strings.

Parameters:

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

dataType - the DataType of the object that this Id refers to

strPk1 - A String representing the primary key value.

strPk2 - A String representing the secondary primary key value (SOS_ID).

Throws:

java.lang.IllegalArgumentException - thrown if either of the String values is not a valid key representation (i.e., an int) or null.

PkId

public PkId(Container container,
            DataType dataType,
            java.lang.String strPk)
     throws java.lang.IllegalArgumentException

Instantiate a new PkId with the given Container, DataType, and pk key values as a single string. The string provided as the key value should be of the form as generated by toExternalString().

Parameters:

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

dataType - the DataType of the object that this id refers to

strPk - A String representing the intenal id value(s).

Throws:

java.lang.IllegalArgumentException - thrown if the String value can not be interpreted as a valid key representation.

Method Detail

isSet

public boolean isSet()

Determines if the PkId has been set.

Specified by:

isSet in class Id

Returns:

true -- a PkId instance is not allowed to be "unset"

getPk1

public int getPk1()

Returns the primary key value of this PkId (PK1).

Returns:

an int representing the primary key value of this pkId.

getPk2

public int getPk2()

Returns the secondary key value of this PkId (PK2 or SOS_ID).

Returns:

an int representing the secondary key value of this PkId.

equals

public boolean equals(java.lang.Object obj)

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

Specified by:

equals in class Id

Parameters:

obj - the object to be compared.

Returns:

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

compareTo

public 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

Specified by:

compareTo in class Id

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 int hashCode()

Allow Ids to be used as a key in a hashtable. For a mapping of Id to BbObject to work using the PkId class, all of the BbObjects in the collection must originate from the same database table. This could be resolved later by adding type information to the Id class.

Specified by:

hashCode in class Id

Returns:

a hash code value for this object as an int

toExternalString

public java.lang.String toExternalString()

Converts this PkId 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 PkId value. If a human- readable form of this PkId 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 PkId value.

Specified by:

toExternalString in class Id

Returns:

A String representation of this PkId that is able to be parsed.

See Also:

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

toString

public java.lang.String toString()

Converts this PkId 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 PkId value. If an "able to be parsed" form of this PkId is desired, use toExternalString().

Specified by:

toString in class Id

Returns:

A String representation of this PkId that is human- readable.

See Also:

toExternalString()

load

public BbObject load()
              throws PersistenceException

Overrides load method in the base class to implement a "load by id" operation for a database id (and thus for a database container).

An Id object contains enough information to uniquely identify an object in the system. First, it contains a Container, which for a PkId (us) should be a DatabaseContainer. This value describes the database the object should reside in. Second, an Id contains a DataType value. This value describes the type of object we are looking for, and thus for a PkId, describes what database loader we can use to pull the object. Finally, an Id contains a key. For a PkId, this value identifies the individual object (among the type) that we are looking. This typically means an individual row within an individual table in the database.

Overrides:

load in class Id

Returns:

the BbObject derived value that matches the current id value

Throws:

PersistenceException - if an error occurs while loading the object