Package com.onwbp.adaptation

Class PrimaryKey

  • public abstract class PrimaryKey
extends Object
    An instance of a PrimaryKey uniquely identifies a record in a table. The composition of a primary key is defined in the data model using the element osd:table/primaryKeys.

    A PrimaryKey is used to perform direct lookups in a table. The string that represents it internally is also used as the value of foreign keys, namely fields declared as osd:tableRef. However, the shortest way to look up a record from an osd:tableRef field is to directly invoke the method SchemaFacetTableRef.getLinkedRecord(ValueContext).

    External applications which access and input data containing osd:tableRef fields must conform to the internal syntax described below in Syntax of the internal String representation of primary keys.

    Factory and conversion

    Factory and conversion methods are as follows:

    Syntax of the internal String representation of primary keys

    To simplify declaration, representation, and persistence, a primary key is handled as a String, even when it is composed of several fields. Note that the fields composing a primary key are returned by the method SchemaNode.getTablePrimaryKeyNodes(). Specifically, the string is built as follows:

    1. The value of the primary key field is formatted according to the XML Schema standard, as implemented by the method SchemaNode.formatToXsString(Object).
    2. If the primary key is composed of several fields, field values are separated by a "|" pipe, represented by the constant SEPARATOR_CHAR. This may require the following "\" escapes (represented by the constant ESCAPE_CHAR) in a component field, in the case where its own value is not a foreign key:
      • each "|" character in the field value is escaped by a "\";
      • each "\" character in the field value is escaped by "\";

    In the following examples, the first column shows a primary key value that is composed of two fields, and the second column gives its corresponding tableRef or PrimaryKey value:

    Primary key field values String representation
    "1", "2" "1|2"
    "1", "2|3" "1|2\|3" if the second field is not a foreign key
    "1|2|3" if the second field is a foreign key
    "1|2", "3" "1\|2|3" if the first field is not a foreign key
    "1|2|3" if the first field is a foreign key
    "1\", "2" "1\\|2"

    Validity of the String representation of primary keys

    If the String representation of a primary key is not structurally valid, an InvalidPrimaryKeyException is thrown. The following table gives some examples:

    Key structure String representation Structural validity
    (xs:string) "" (empty string) Valid. Will look up a record with a single primary key field set to an empty string.
    (xs:int) "" (empty string) Invalid, throws an InvalidPrimaryKeyException.
    (xs:int) "aa" (invalid integer) Invalid, throws an InvalidPrimaryKeyException.
    (xs:int | xs:string) "aa|aaa" (invalid integer field) Invalid, throws an InvalidPrimaryKeyException.
    (xs:int | xs:string) "|aaa" Invalid, throws an InvalidPrimaryKeyException.
    (xs:int | xs:string) "" (empty string) Invalid, throws an InvalidPrimaryKeyException.
    (xs:int | xs:string) "aaa" Invalid, throws an InvalidPrimaryKeyException.
    See Also:
    AdaptationTable.lookupAdaptationByPrimaryKey(PrimaryKey, boolean)