You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-dev@db.apache.org by Craig L Russell <Cr...@Sun.COM> on 2007/07/10 21:19:24 UTC
JDO Spec clarifications for mapping metadata
Here's a work in progress on some changes to annotations to better
align with xml metadata.
Mapping Basic Fields/Properties
Basic fields/properties are non-relationship fields and methods that
are typically mapped to a single column in the primary table for the
class/interface in the database. It is possible to map to multiple
columns but this behavior is not standardized. The column of the row
corresponding to the instance contains the value of the field/
property. If the mapped column is in the primary table for the class/
interface, then the column name is the only required mapping data. If
the column is in a secondary table, then the secondary table name,
column name in the secondary table, and join condition are needed.
The join condition can be specified either at the class/interface
level or at the field/property level.
The column in the join metadata refers to the column in the secondary
table that is joined to the target column in the primary table. The
default target column is the primary key column of the primary table.
The join column might be specified simply by name. For multiple
primary key columns, the join columns must be explicitly specified
with their corresponding target columns.
If the join condition is specified at the class/interface level, the
same join condition can be shared among several fields/properties. In
this case, the join metadata contains both the join and the secondary
table information.
If the join condition is specified at the field/property level, then
the join condition applies only to that field/property. In this case,
the table is specified by the field/property metadata and the join
condition is specified in the join metadata associated with the field/
property.
Mapping Direct Relationship Fields/Properties
Direct relationship fields/properties are of a type of a persistence-
capable class or interface, and are mapped to a column or columns in
the primary or secondary table. The column(s) contain the same value
(s) as the row(s) in the primary table of the related class. The
usage of join metadata is the same as for basic field/property mapping.
Mapping Both Sides of a Relationship
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Collection or subclass) then both sides
might be mapped to the same database artifact. In this case, the
direct side is mapped by specifying the column metadata and the multi-
valued side is mapped by specifying the corresponding field of the
other side.
Mapping Direct Relationships Using a Join Table
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Array or Collection) and the
relationship uses a join table, there will typically be a unique
constraint on the column(s) in the join table that are mapped to the
class containing the direct relationship. In this case, the join
table is considered a secondary table of the class/interface
containing the direct relationship, and the unique column(s) comprise
the join condition. There is no shared join information at the class/
interface level.
Mapping Key-Only Join Tables
Key-only join tables are used to represent many-to-many
relationships. Each of the types in the domain classes is a multi-
valued type referring to the other side. The mapping on one side
identifies the join table in the field/property metadata. There is no
shared join information at the class/interface level. The join
metadata of the field identifies the column(s) in the join table that
refer to the primary key column(s) in the primary table. The mapping
metadata on the other side names the corresponding field/property
where the mapping is specified.
Specifying Database Constraints and Indexes for Columns
There are several places where database constraints or indexes are
usefully applied to mapped columns. These fall into four categories:
primary key, foreign key, uniqueness constraints, and indexes.
Primary Key Constraints
Primary key constraints for primary tables are implied by declaring
the primary key field(s) for the class. Unless explicitly specified,
a system-defined primary key constraint name is generated. If a
primary key constraint name is desired, it can be specified using the
primary key metadata associated with the class/interface.
Primary key constraints for secondary tables need to be explicitly
declared if desired. If the primary key is associated with the joined
columns, the only additional information is the name of the primary
key constraint. In this case, the primary key name is specified via
the join metadata at either the class/interface level or the field/
property level. *[This is missing from the Join annotation].
Primary key constraints join tables for relationship field mappings
must be explicitly declared if desired. In this case, they are
declared as metadata on the field/property. The table on which the
primary keys are being declared is the table associated with the
field/property. The columns composing the primary key constraint are
named in the primary key metadata.
Foreign Key Constraints
Foreign key constraints associated with columns in the primary table
mapped to relationship fields/properties are declared on the
associated field/property. *[This is missing from the Field/Property
annotation].
Foreign key constraints associated with secondary tables are either
associated with the join condition or with the relationship to a
third table.
If a foreign key constraint is desired on the join condition, the
only additional information is the name of the foreign key
constraint. *[This is missing from the Join annotation].
If a foreign key constraint is desired on the relationship to a third
table, the name of the foreign key constraint is given on the foreign
key metadata associated with the field/property.
Unique Key Constraints
Unique key constraints associated with a column in the primary or
secondary table mapped to a field/property are declared on the
associated field/property. *[This is missing from the Field/Property
annotation].
Unique key constraints not associated with a column in the primary or
secondary table mapped to a field/property are declared in the
metadata for the class/interface.
Indexes
Indexes associated with a column in the primary or secondary table
mapped to a field/property are declared on the associated field/
property. *[This is missing from the Field/Property annotation].
Indexes not associated with a column in the primary or secondary
table mapped to a field/property are declared in the metadata for the
class/interface.
Changes needed to annotations:
1. Provide a way to specify the primary key name for Join annotation,
e.g. String primaryKey().
2. Provide a way to specify the foreign key name for Join annotation,
e.g. String foreignKey().
3. Provide a way to specify the foreign key name for a Field and
Property annotation, e.g. String foreignKey().
4. Provide a way to specify the unique key constraint name for Field
and Property annotation, e.g. String uniqueKey(). This element
provides the name of the unique key constraint and sets the String
unique() element to "true".
5. Provide a way to specify the index name for Field and Property
annotation, e.g. String index(). This element provides the name of
the index and sets the String indexed() element to "true".
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!
Re: JDO Spec clarifications for mapping metadata
Posted by Craig L Russell <Cr...@Sun.COM>.
Updated per Andy's comments of 16-July (thanks, Andy).
Mapping Basic Fields/Properties
Basic fields/properties are non-relationship fields and methods that
are typically mapped to a single column in the primary table for the
class/interface in the database. It is possible to map to multiple
columns but this behavior is not standardized. The column of the row
corresponding to the instance contains the value of the field/
property. If the mapped column is in the primary table for the class/
interface, then the column name is the only required mapping data. If
the column is in a secondary table, then the secondary table name,
column name in the secondary table, and join condition are needed.
The join condition can be specified either at the class/interface
level or at the field/property level.
The column in the join metadata refers to the column in the secondary
table that is joined to the target column in the primary table. The
default target column is the primary key column of the primary table.
The join column might be specified simply by name. For multiple
primary key columns, the join columns must be explicitly specified
with their corresponding target columns.
If the join condition is specified at the class/interface level, the
same join condition can be shared among several fields/properties. In
this case, the join metadata contains both the join and the secondary
table information.
If the join condition is specified at the field/property level, then
the join condition applies only to that field/property. In this case,
the table is specified by the field/property metadata and the join
condition is specified in the join metadata associated with the field/
property.
Mapping Direct Relationship Fields/Properties
Direct relationship fields/properties are of a type of a persistence-
capable class or interface, and are mapped to a column or columns in
the primary or secondary table. The column(s) contain the same value
(s) as the row(s) in the primary table of the related class. The
usage of join metadata is the same as for basic field/property mapping.
Mapping Both Sides of a Relationship
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Collection or subclass) then both sides
might be mapped to the same database artifact. In this case, the
direct side is mapped by specifying the column metadata and the multi-
valued side is mapped by specifying the corresponding field of the
other side.
Mapping Direct Relationships Using a Join Table
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Array or Collection) and the
relationship uses a join table, there will typically be a unique
constraint on the column(s) in the join table that are mapped to the
class containing the direct relationship. In this case, the join
table is considered a secondary table of the class/interface
containing the direct relationship, and the unique column(s) comprise
the join condition. There is no shared join information at the class/
interface level.
Mapping Key-Only Join Tables
Key-only join tables are used to represent many-to-many
relationships. Each of the types in the domain classes is a multi-
valued type referring to the other side. The mapping on one side
identifies the join table in the field/property metadata. There is no
shared join information at the class/interface level. The join
metadata of the field identifies the column(s) in the join table that
refer to the primary key column(s) in the primary table. The mapping
metadata on the other side names the corresponding field/property
where the mapping is specified.
Specifying Database Constraints and Indexes for Columns
There are several places where database constraints or indexes are
usefully applied to mapped columns. These fall into four categories:
primary key, foreign key, uniqueness constraints, and indexes.
Primary Key Constraints
Primary key constraints for primary tables are implied by declaring
the primary key field(s) for the class. Unless explicitly specified,
a system-defined primary key constraint name is generated. If a
primary key constraint name is desired, it can be specified using the
primary key metadata associated with the class/interface.
Primary key constraints for secondary tables need to be explicitly
declared if desired. If the primary key is associated with the joined
columns, the only additional information is the name of the primary
key constraint. In this case, the primary key name is specified via
the join metadata at either the class/interface level or the field/
property level. [*1 This is missing from the Join annotation].
Primary key constraints for join tables for relationship field
mappings must be explicitly declared if desired. In this case, they
are declared as metadata on the field/property. The table on which
the primary keys are being declared is the table associated with the
field/property. The columns composing the primary key constraint are
named in the primary key metadata.
Foreign Key Constraints
Foreign key constraints associated with columns in the primary table
mapped to relationship fields/properties are declared on the
associated field/property.
Foreign key constraints associated with secondary tables are either
associated with the join condition or with the relationship to a
third table.
If a foreign key constraint is desired on the join condition, the
only additional information is the name of the foreign key
constraint. [*2 This is missing from the Join annotation].
If a foreign key constraint is desired on the relationship to a third
table, the name of the foreign key constraint is given on the foreign
key metadata associated with the field/property.
If a foreign key constraint is desired on the element, key, or value
of a collection, map or array type field, the name of the foreign key
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*6 This is missing from the @Element, @Key, and @Value
annotation definition].
Unique Key Constraints
Unique key constraints associated with a column in the primary or
secondary table mapped to a field/property are declared on the
associated field/property.
Unique key constraints not associated with a column in the primary or
secondary table mapped to a field/property are declared in the
metadata for the class/interface.
If a unique constraint is desired on the element, key, or value of a
collection, map or array type field, the name of the unique
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*6 This is missing from the @Element, @Key, and @Value
annotation definition].
Indexes
Indexes associated with a column in the primary or secondary table
mapped to a field/property are declared on the associated field/
property.
Indexes not associated with a column in the primary or secondary
table mapped to a field/property are declared in the metadata for the
class/interface.
If a foreign key constraint is desired on the element, key, or value
of a collection, map or array type field, the name of the foreign key
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*6 This is missing from the @Element, @Key, and @Value
annotation definition].
Changes needed to annotations (numbering is preserved from previous
messages):
1. Provide a way to specify the primary key name for Join annotation,
e.g. String primaryKey().
2. Provide a way to specify the foreign key name for Join annotation,
e.g. String foreignKey().
6. Also need String foreignKey(), String index(), and String uniqueKey
() as elements of @Value, @Element, and @Key that would name the
foreign key constraint of the mapped columns for Map, Collection, and
Array type fields.
8. It's an error to specify conflicting requirements, e.g.
generateForeignKey="false" and provide a non-empty string value for
foreignKey; unique="false" and uniqueKey some non-empty string;
indexed="false" and index some non-empty string.
9. All names are trimmed of white space on both ends.
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!
Re: JDO Spec clarifications for mapping metadata
Posted by Andy Jefferson <an...@jpox.org>.
> 3. Provide a way to specify the foreign key name for a Field and
> Property annotation, e.g. String foreignKey().
Or @ForeignKey(name="MY_FK") on the field/property.
> 4. Provide a way to specify the unique key constraint name for Field
> and Property annotation, e.g. String uniqueKey(). This element
> provides the name of the unique key constraint and sets the String
> unique() element to "true".
Or @Unique(name="MY_IDX") on the field/property.
> 5. Provide a way to specify the index name for Field and Property
> annotation, e.g. String index(). This element provides the name of
> the index and sets the String indexed() element to "true".
Or @Index(name="MY_IDX") on the field/property.
> 7. To generate a foreign key using a system-generated name, specify
> generateForeignKey="true".
presumably in @Element, @Key, @Value ?
because to do that on a field/property add @ForeignKey against the
field/property.
PS. Is it possible to get a copy of the latest spec with all updates that have
gone in since 2.0-final ? Maybe distribute it on the EG alias ?
--
Andy (Java Persistent Objects - http://www.jpox.org)
Re: JDO Spec clarifications for mapping metadata
Posted by Craig L Russell <Cr...@Sun.COM>.
It looks like a couple of more annotation elements are needed. Please
see bottom of page...
On Jul 10, 2007, at 12:19 PM, Craig L Russell wrote:
Here's a work in progress on some changes to annotations to better
align with xml metadata.
Mapping Basic Fields/Properties
Basic fields/properties are non-relationship fields and methods that
are typically mapped to a single column in the primary table for the
class/interface in the database. It is possible to map to multiple
columns but this behavior is not standardized. The column of the row
corresponding to the instance contains the value of the field/
property. If the mapped column is in the primary table for the class/
interface, then the column name is the only required mapping data. If
the column is in a secondary table, then the secondary table name,
column name in the secondary table, and join condition are needed.
The join condition can be specified either at the class/interface
level or at the field/property level.
The column in the join metadata refers to the column in the secondary
table that is joined to the target column in the primary table. The
default target column is the primary key column of the primary table.
The join column might be specified simply by name. For multiple
primary key columns, the join columns must be explicitly specified
with their corresponding target columns.
If the join condition is specified at the class/interface level, the
same join condition can be shared among several fields/properties. In
this case, the join metadata contains both the join and the secondary
table information.
If the join condition is specified at the field/property level, then
the join condition applies only to that field/property. In this case,
the table is specified by the field/property metadata and the join
condition is specified in the join metadata associated with the field/
property.
Mapping Direct Relationship Fields/Properties
Direct relationship fields/properties are of a type of a persistence-
capable class or interface, and are mapped to a column or columns in
the primary or secondary table. The column(s) contain the same value
(s) as the row(s) in the primary table of the related class. The
usage of join metadata is the same as for basic field/property mapping.
Mapping Both Sides of a Relationship
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Collection or subclass) then both sides
might be mapped to the same database artifact. In this case, the
direct side is mapped by specifying the column metadata and the multi-
valued side is mapped by specifying the corresponding field of the
other side.
Mapping Direct Relationships Using a Join Table
If one side of a relationship is a direct relationship and the other
side is a multi-valued type (Array or Collection) and the
relationship uses a join table, there will typically be a unique
constraint on the column(s) in the join table that are mapped to the
class containing the direct relationship. In this case, the join
table is considered a secondary table of the class/interface
containing the direct relationship, and the unique column(s) comprise
the join condition. There is no shared join information at the class/
interface level.
Mapping Key-Only Join Tables
Key-only join tables are used to represent many-to-many
relationships. Each of the types in the domain classes is a multi-
valued type referring to the other side. The mapping on one side
identifies the join table in the field/property metadata. There is no
shared join information at the class/interface level. The join
metadata of the field identifies the column(s) in the join table that
refer to the primary key column(s) in the primary table. The mapping
metadata on the other side names the corresponding field/property
where the mapping is specified.
Specifying Database Constraints and Indexes for Columns
There are several places where database constraints or indexes are
usefully applied to mapped columns. These fall into four categories:
primary key, foreign key, uniqueness constraints, and indexes.
Primary Key Constraints
Primary key constraints for primary tables are implied by declaring
the primary key field(s) for the class. Unless explicitly specified,
a system-defined primary key constraint name is generated. If a
primary key constraint name is desired, it can be specified using the
primary key metadata associated with the class/interface.
Primary key constraints for secondary tables need to be explicitly
declared if desired. If the primary key is associated with the joined
columns, the only additional information is the name of the primary
key constraint. In this case, the primary key name is specified via
the join metadata at either the class/interface level or the field/
property level. *[This is missing from the Join annotation].
Primary key constraints join tables for relationship field mappings
must be explicitly declared if desired. In this case, they are
declared as metadata on the field/property. The table on which the
primary keys are being declared is the table associated with the
field/property. The columns composing the primary key constraint are
named in the primary key metadata.
Foreign Key Constraints
Foreign key constraints associated with columns in the primary table
mapped to relationship fields/properties are declared on the
associated field/property. *[This is missing from the Field/Property
annotation].
Foreign key constraints associated with secondary tables are either
associated with the join condition or with the relationship to a
third table.
If a foreign key constraint is desired on the join condition, the
only additional information is the name of the foreign key
constraint. *[This is missing from the Join annotation].
If a foreign key constraint is desired on the relationship to a third
table, the name of the foreign key constraint is given on the foreign
key metadata associated with the field/property.
If a foreign key constraint is desired on the element, key, or value
of a collection, map or array type field, the name of the foreign key
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*This is missing from the @Element, @Key, and @Value
annotation definition].
Unique Key Constraints
Unique key constraints associated with a column in the primary or
secondary table mapped to a field/property are declared on the
associated field/property. *[This is missing from the Field/Property
annotation].
Unique key constraints not associated with a column in the primary or
secondary table mapped to a field/property are declared in the
metadata for the class/interface.
If a unique constraint is desired on the element, key, or value of a
collection, map or array type field, the name of the unique
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*This is missing from the @Element, @Key, and @Value
annotation definition].
Indexes
Indexes associated with a column in the primary or secondary table
mapped to a field/property are declared on the associated field/
property. *[This is missing from the Field/Property annotation].
Indexes not associated with a column in the primary or secondary
table mapped to a field/property are declared in the metadata for the
class/interface.
If a foreign key constraint is desired on the element, key, or value
of a collection, map or array type field, the name of the foreign key
constraint is given on the @Element, @Key, or @Value annotation for
the field. [*This is missing from the @Element, @Key, and @Value
annotation definition].
Changes needed to annotations:
1. Provide a way to specify the primary key name for Join annotation,
e.g. String primaryKey().
2. Provide a way to specify the foreign key name for Join annotation,
e.g. String foreignKey().
3. Provide a way to specify the foreign key name for a Field and
Property annotation, e.g. String foreignKey().
4. Provide a way to specify the unique key constraint name for Field
and Property annotation, e.g. String uniqueKey(). This element
provides the name of the unique key constraint and sets the String
unique() element to "true".
5. Provide a way to specify the index name for Field and Property
annotation, e.g. String index(). This element provides the name of
the index and sets the String indexed() element to "true".
6. Also need String foreignKey(), String index(), and String uniqueKey
() as elements of @Value, @Element, and @Key that would name the
foreign key constraint of the mapped columns for Map, Collection, and
Array type fields.
7. To generate a foreign key using a system-generated name, specify
generateForeignKey="true".
8. It's an error to specify conflicting requirements, e.g.
generateForeignKey="false" and provide a non-empty string value for
foreignKey; unique="false" and uniqueKey some non-empty string;
indexed="false" and index some non-empty string.
9. All names are trimmed of white space on both ends.
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!