Mailing-List: contact jdo-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jdo-dev@db.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Date: Tue, 10 Jul 2007 12:19:24 -0700
From: Craig L Russell <Craig.Russell@Sun.COM>
Subject: JDO Spec clarifications for mapping metadata
Sender: Craig.Russell@Sun.COM
To: Apache JDO project <jdo-dev@db.apache.org>,
        JDO Expert Group <jdo-experts-ext@Sun.COM>
Message-id: <4199328E-FA12-45C6-B9C6-7E2618452B07@SUN.com>
MIME-version: 1.0
Content-type: multipart/signed; protocol="application/pkcs7-signature";
 boundary=Apple-Mail-93--370465921; micalg=sha1

--Apple-Mail-93--370465921
Content-Transfer-Encoding: 7bit
Content-Type: text/plain;
	charset=US-ASCII;
	delsp=yes;
	format=flowed

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!


--Apple-Mail-93--370465921
Content-Transfer-Encoding: base64
Content-Type: application/pkcs7-signature;
	name=smime.p7s
Content-Disposition: attachment;
	filename=smime.p7s

MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIGUDCCAwkw
ggJyoAMCAQICECpJVMO68ii+Xfsc1O1YYFIwDQYJKoZIhvcNAQEFBQAwYjELMAkGA1UEBhMCWkEx
JTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQ
ZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBMB4XDTA2MTIwOTE5NTEwNVoXDTA3MTIwOTE5NTEw
NVowbDEQMA4GA1UEBBMHUnVzc2VsbDEUMBIGA1UEKhMLQ3JhaWcgTGFpcmQxHDAaBgNVBAMTE0Ny
YWlnIExhaXJkIFJ1c3NlbGwxJDAiBgkqhkiG9w0BCQEWFUNyYWlnLlJ1c3NlbGxAU3VuLkNPTTCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMNAB4Ih+ShsCt89HzqIdwEx8L4o1UHiY6V7
16mrCedfd4Y0/uI7z9Zam8ysgEh+F7aDnQEKmEsVFN35G4nPMfLU6dZYkvADwUjbq82t/dJ3FDDg
Q945nHHpqECZff/S/UMho9AFfj6PZvZBAlDCJAayb4RdKIlfuvPW9YcQStQ1IfVJcVuKnC0Q+tdc
a4A7zn7IzLOQohO1lTc3hXSBigEIGiGYn6Ny0wmexfA3X1WsXekFx5czd+M4GjDjswn8CNoBmnBr
jOTGK1mOsXR6GSRHnly2s9xTdE4qv9qimM+7C2yzMHbKcszV7OQoLsRsZKDh+6u9wYU+TrjcY4ym
bA8CAwEAAaMyMDAwIAYDVR0RBBkwF4EVQ3JhaWcuUnVzc2VsbEBTdW4uQ09NMAwGA1UdEwEB/wQC
MAAwDQYJKoZIhvcNAQEFBQADgYEAU/EpPDztnb55Fz7iGSVm1mYEVj5m2OQKTYG26POUAomCBRrt
/CdBBvqYmcHUTpra0qLELHAQadYFl2v11iQkqwF5PPJs19oU/zA0m5qFnOMTAiCvel7IprIwA2r6
eJR9siaPwDRgVJ/Sj71dD+utwf+nRrNy0/7PMNK5y+ocsYQwggM/MIICqKADAgECAgENMA0GCSqG
SIb3DQEBBQUAMIHRMQswCQYDVQQGEwJaQTEVMBMGA1UECBMMV2VzdGVybiBDYXBlMRIwEAYDVQQH
EwlDYXBlIFRvd24xGjAYBgNVBAoTEVRoYXd0ZSBDb25zdWx0aW5nMSgwJgYDVQQLEx9DZXJ0aWZp
Y2F0aW9uIFNlcnZpY2VzIERpdmlzaW9uMSQwIgYDVQQDExtUaGF3dGUgUGVyc29uYWwgRnJlZW1h
aWwgQ0ExKzApBgkqhkiG9w0BCQEWHHBlcnNvbmFsLWZyZWVtYWlsQHRoYXd0ZS5jb20wHhcNMDMw
NzE3MDAwMDAwWhcNMTMwNzE2MjM1OTU5WjBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3Rl
IENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWls
IElzc3VpbmcgQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMSmPFVzVftOucqZWh5owHUE
cJ3f6f+jHuy9zfVb8hp2vX8MOmHyv1HOAdTlUAow1wJjWiyJFXCO3cnwK4Vaqj9xVsuvPAsH5/Ef
kTYkKhPPK9Xzgnc9A74r/rsYPge/QIACZNenprufZdHFKlSFD0gEf6e20TxhBEAeZBlyYLf7AgMB
AAGjgZQwgZEwEgYDVR0TAQH/BAgwBgEB/wIBADBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3Js
LnRoYXd0ZS5jb20vVGhhd3RlUGVyc29uYWxGcmVlbWFpbENBLmNybDALBgNVHQ8EBAMCAQYwKQYD
VR0RBCIwIKQeMBwxGjAYBgNVBAMTEVByaXZhdGVMYWJlbDItMTM4MA0GCSqGSIb3DQEBBQUAA4GB
AEiM0VCD6gsuzA2jZqxnD3+vrL7CF6FDlpSdf0whuPg2H6otnzYvwPQcUCCTcDz9reFhYsPZOhl+
hLGZGwDFGguCdJ4lUJRix9sncVcljd2pnDmOjCBPZV+V2vf3h9bGCE6u9uo05RAaWzVNd+NWIXiC
3CEZNd4ksdMdRv9dX2VPMYIDEDCCAwwCAQEwdjBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhh
d3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVt
YWlsIElzc3VpbmcgQ0ECECpJVMO68ii+Xfsc1O1YYFIwCQYFKw4DAhoFAKCCAW8wGAYJKoZIhvcN
AQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMDcwNzEwMTkxOTI0WjAjBgkqhkiG9w0B
CQQxFgQUyuzhUcZTFwJEFiG/m3CVAU9CDc4wgYUGCSsGAQQBgjcQBDF4MHYwYjELMAkGA1UEBhMC
WkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0
ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAhAqSVTDuvIovl37HNTtWGBSMIGHBgsqhkiG
9w0BCRACCzF4oHYwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQ
dHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAhAq
SVTDuvIovl37HNTtWGBSMA0GCSqGSIb3DQEBAQUABIIBAHyk0jw48Rba5kkWa387eDsCaZ5WdTS+
lY9w/uTnkGNQgMiKvVfLVg+QDzp2nnekk/nkU3kqW8EGghPAEpK3fWx36tAnlzTRd7dIxBqIum3f
FJwATjwI/81V8Wp3IzIiZovslJ4OinQMPLCIZEqOVisJ7CfunU423lJ6gyJ4yHSgJ9ZM+NLDA4ar
z3uEdo1v6q3ZP+x74P7ioXlH8AlhcXUItq4e+llc14AuV4UOgKJuRtJi9bFEpliwKrLevOMiAlq1
/J9xZkmMJzM5EGNnwf6dcIeOpL7IUDHV2VwdOt1MTlGHeyl6LtzWNK9ATIC4mKXwbXnfVxGoynPn
rYb6PTgAAAAAAAA=

--Apple-Mail-93--370465921--