A datastore identifier is a simple name of a database object, such as a column, table, index, or view, and is
composed of a sequence of letters, digits, and underscores ( _ ) that represents it's name. JPOX allows users to
specify the names of tables, columns, indexes etc but if the user doesn't specify these JPOX will generate
names.
Generation of identifier names is controlled by an IdentifierFactory, and JPOX provides a default implementation.
You can provide your own IdentifierFactory plugin to give your
own preferred naming if so desired (this is provided from JPOX version 1.1.2).
You set the IdentifierFactory by setting the PMF property org.jpox.identifierFactory. Set it to
the symbolic name of the factory you want to use. The following factories are provided
- jpox IdentifierFactory (default for JDO persistence)
- jpox2 IdentifierFactory
- jpa IdentifierFactory (default for JPA persistence)
In describing the different possible naming conventions available out of the box with JPOX we'll use the
following example
class MyClass
{
String myField1;
Collection<MyElement> elements1; // Using join table
Collection<MyElement> elements2; // Using foreign-key
}
class MyElement
{
String myElementField;
MyClass myClass2;
}
The default IdentifierFactory (when using JDO persistence) goes by the name "jpox" and provides a reasonable
default naming of datastore identifiers using the class and field names as its basis. JPOX has used this naming
convention for all versions (with the exception of 1.1.1 which had a regression in the naming of index fields
where "IDX" was used).
Using the example above, the rules in this IdentifierFactory mean that, assuming that the user doesnt
specify any <column> elements :-
- MyClass will be persisted into a table named MYCLASS
- When using datastore identity MYCLASS will have a column called MYCLASS_ID
- MyClass.myField1 will be persisted into a column called MY_FIELD1
- MyElement will be persisted into a table named MYELEMENT
- MyClass.elements1 will be persisted into a join table called MYCLASS_ELEMENTS1
- MYCLASS_ELEMENTS1 will have columns called MYCLASS_ID_OID (FK to owner table) and
MYELEMENT_ID_EID (FK to element table)
- MyClass.elements2 will be persisted into a column ELEMENTS2_MYCLASS_ID_OID (FK to owner) table
- Any discriminator column will be called DISCRIMINATOR
- Any index column in a List will be called INTEGER_IDX
- Any adapter column added to a join table to form part of the primary key will be called ADPT_PK_IDX
- Any version column for a table will be called OPT_VERSION
The IdentifierFactory "jpox2" changes a few things over the default "jpox" factory, attempting
to make the naming more concise and consistent (we retain "jpox" for backwards compatibility).
Using the same example above, the rules in this IdentifierFactory mean that, assuming that the user
doesnt specify any <column> elements :-
- MyClass will be persisted into a table named MYCLASS
- When using datastore identity MYCLASS will have a column called MYCLASS_ID
- MyClass.myField1 will be persisted into a column called MYFIELD1
- MyElement will be persisted into a table named MYELEMENT
- MyClass.elements1 will be persisted into a join table called MYCLASS_ELEMENTS1
- MYCLASS_ELEMENTS1 will have columns called MYCLASS_ID_OID (FK to owner table) and
MYELEMENT_ID_EID (FK to element table)
- MyClass.elements2 will be persisted into a column ELEMENTS2_MYCLASS_ID_OID (FK to owner) table
- Any discriminator column will be called DISCRIMINATOR
- Any index column in a List will be called IDX
- Any adapter column added to a join table to form part of the primary key will be called IDX
- Any version column for a table will be called VERSION
The IdentifierFactory "jpa" aims at providing a naming policy consistent with the "JPA1" specification.
Using the same example above, the rules in this IdentifierFactory mean that, assuming that the user
doesnt specify any <column> elements :-
- MyClass will be persisted into a table named MYCLASS
- When using datastore identity MYCLASS will have a column called MYCLASS_ID
- MyClass.myField1 will be persisted into a column called MYFIELD1
- MyElement will be persisted into a table named MYELEMENT
- MyClass.elements1 will be persisted into a join table called MYCLASS_MYELEMENT
- MYCLASS_ELEMENTS1 will have columns called MYCLASS_MYCLASS_ID (FK to owner table) and
ELEMENTS1_ELEMENT_ID (FK to element table)
- MyClass.elements2 will be persisted into a column ELEMENTS2_MYCLASS_ID (FK to owner) table
- Any discriminator column will be called DTYPE
- Any index column in a List will be called IDX
- Any adapter column added to a join table to form part of the primary key will be called IDX
- Any version column for a table will be called VERSION
The underlying datastore will define what case of identifiers are accepted. By default, JPOX will capitalise names
(assuming that the datastore supports it). You can however influence the case used for identifiers.
This is specifiable with the PMF property org.jpox.identifier.case, having the following values
- UpperCase: identifiers are in upper case
- LowerCase: identifiers are in lower case
- PreserveCase: No case changes are made to the name of the identifier provided by the user (class name or jdo metadata).
Please be aware that some datastores only support UPPERCASE or lowercase identifiers and so setting this parameter
may have no effect if your database doesn't support that option.
