Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Introduction to Projects (ELUG)"

m
m
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''
 +
 +
----
 +
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Introduction to Projects (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Introduction to Projects (ELUG)|Related Topics]]</div>
−
A EclipseLink project encapsulates both mapping metadata and, where relevant, data source access information. The project is the primary object used by EclipseLink at run time. Each session (excluding the session broker) in a deployed application references a single project.
+
An EclipseLink project encapsulates both mapping metadata and, where relevant, data source access information. The project is the primary object used by EclipseLink at run time. Each session (excluding the session broker) in a deployed application references a single project.
  
  
Line 44: Line 48:
 
|}
 
|}
  
−
For more information, see:
+
For more information, see the following:
 
* [[Creating%20a%20Project%20(ELUG)|Creating a Project]]
 
* [[Creating%20a%20Project%20(ELUG)|Creating a Project]]
 
* [[Configuring%20a%20Project%20(ELUG)|Configuring a Project]]
 
* [[Configuring%20a%20Project%20(ELUG)|Configuring a Project]]
Line 60: Line 64:
 
* [[#Projects and Sequencing|Projects and Sequencing]]
 
* [[#Projects and Sequencing|Projects and Sequencing]]
 
* [[#XML Namespaces|XML Namespaces]]
 
* [[#XML Namespaces|XML Namespaces]]
−
 
  
  
Line 98: Line 101:
 
[[Introduction%20to%20Mappings%20(ELUG)#XML Mappings|XML Mappings]]
 
[[Introduction%20to%20Mappings%20(ELUG)#XML Mappings|XML Mappings]]
 
|}
 
|}
−
 
−
 
−
 
  
  
Line 109: Line 109:
  
 
Nonrelational projects persist Java objects to another (nonrelational) type of data source, or perform nonpersistent (see [[#Persistent and Nonpersistent Projects|Persistent and Nonpersistent Projects]]) data conversion. For example, to persist Java objects to an EIS data source by using a JCA adapter, use an EIS project. To perform nonpersistent (in-memory) conversions between Java objects and XML elements, use an XML project.
 
Nonrelational projects persist Java objects to another (nonrelational) type of data source, or perform nonpersistent (see [[#Persistent and Nonpersistent Projects|Persistent and Nonpersistent Projects]]) data conversion. For example, to persist Java objects to an EIS data source by using a JCA adapter, use an EIS project. To perform nonpersistent (in-memory) conversions between Java objects and XML elements, use an XML project.
−
 
  
  
Line 116: Line 115:
  
 
EclipseLink also supports projects you use for applications that require only nonpersistent (in-memory) data conversion. For example, use an XML project to perform nonpersistent (in-memory) conversion between Java objects and XML elements.
 
EclipseLink also supports projects you use for applications that require only nonpersistent (in-memory) data conversion. For example, use an XML project to perform nonpersistent (in-memory) conversion between Java objects and XML elements.
−
 
  
  
Line 133: Line 131:
 
* [[#POJO Session Role|POJO Session Role]]
 
* [[#POJO Session Role|POJO Session Role]]
 
* [[#Development Role|Development Role]]
 
* [[#Development Role|Development Role]]
−
 
  
  
Line 139: Line 136:
 
You create a session login in the <tt>sessions.xml</tt> file for EclipseLink applications that do not use container-managed persistence (CMP).
 
You create a session login in the <tt>sessions.xml</tt> file for EclipseLink applications that do not use container-managed persistence (CMP).
  
−
Typically, the EclipseLink runtime instantiates a project when you load a session from the <tt>sessions.xml</tt> file (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring and Using Sessions at Run Time]]). The runtime also instantiates a login and its platform based on the information in the <tt>sessions.xml</tt> file.
+
Typically, the EclipseLink runtime instantiates a project when you [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring and Using Sessions at Run Time|load a session from the <tt>sessions.xml</tt> file]]. The runtime also instantiates a login and its platform based on the information in the <tt>sessions.xml</tt> file.
  
 
The EclipseLink runtime uses the information in the session login whenever you perform a persistence operation using the session in your POJO EclipseLink application.
 
The EclipseLink runtime uses the information in the session login whenever you perform a persistence operation using the session in your POJO EclipseLink application.
Line 150: Line 147:
  
 
For information on configuring a session login, see [[Configuring%20a%20Session%20(ELUG)#Configuring a Session Login|Configuring a Session Login]].
 
For information on configuring a session login, see [[Configuring%20a%20Session%20(ELUG)#Configuring a Session Login|Configuring a Session Login]].
−
 
  
  
Line 161: Line 157:
  
 
For more information on creating a development login, see [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Development and Deployment Logins|Configuring Development and Deployment Logins]].
 
For more information on creating a development login, see [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Development and Deployment Logins|Configuring Development and Deployment Logins]].
−
 
  
  
Line 176: Line 171:
  
 
There is a platform type for each project type that persists to a data source. For a complete list of platform types available, see [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Platform Types|Data Source Platform Types]].
 
There is a platform type for each project type that persists to a data source. For a complete list of platform types available, see [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Platform Types|Data Source Platform Types]].
−
 
  
  
 
===Projects and Sequencing===
 
===Projects and Sequencing===
−
An essential part of [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|maintaining object identity ]] is sequencing: managing the assignment of unique values to distinguish one instance from another.
+
An essential part of [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|maintaining object identity]] is sequencing: managing the assignment of unique values to distinguish one instance from another.
  
 
Projects have different sequencing requirements, depending on their types:
 
Projects have different sequencing requirements, depending on their types:
  
 
* For relational projects, you typically obtain object identifier values from a separate sequence table (or database object) dedicated to managing object identifier values (see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Sequencing in Relational Projects]]).
 
* For relational projects, you typically obtain object identifier values from a separate sequence table (or database object) dedicated to managing object identifier values (see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Sequencing in Relational Projects]]).
−
* For EIS projects, you typically use a returning policy (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Returning Policy|Configuring Returning Policy]]) to obtain object identifier values managed by the EIS data source.
+
* For EIS projects, you typically [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Returning Policy|use a returning policy]] to obtain object identifier values managed by the EIS data source.
 
* For XML projects, because you are simply performing transformations between objects and XML documents, sequencing is not an issue.
 
* For XML projects, because you are simply performing transformations between objects and XML documents, sequencing is not an issue.
  
−
To configure sequencing, you must configure:
+
To configure sequencing, you must configure the following:
−
* How to obtain sequence values (see [[#Configuring How to Obtain Sequence Values|Configuring How to Obtain Sequence Values]]), and
+
* [[#Configuring How to Obtain Sequence Values|how to obtain sequence values]], and
−
* Where to write sequence values when an instance of a descriptor's reference class is created (see [[#Configuring Where to Write Sequence Values|Configuring Where to Write Sequence Values]])
+
* [[#Configuring Where to Write Sequence Values|where to write sequence values]] when an instance of a descriptor's reference class is created.
−
 
+
−
Depending on the type of sequencing you use and the architecture of your application, you may consider using a sequence connection pool. For more information, see [[Introduction%20to%20Data%20Access%20(ELUG)#Sequence Connection Pools|Sequence Connection Pools]].
+
  
 +
Depending on the type of sequencing you use and the architecture of your application, you may consider using [[Introduction%20to%20Data%20Access%20(ELUG)#Sequence Connection Pools|Sequence Connection Pools]].
  
  
Line 199: Line 192:
 
To determine how EclipseLink obtains sequence values, you configure EclipseLink sequencing at the project or session level, depending on the type of project you are building, as follows:
 
To determine how EclipseLink obtains sequence values, you configure EclipseLink sequencing at the project or session level, depending on the type of project you are building, as follows:
 
* In a POJO project, you can configure a session directly: in this case, you can use session-level sequence configuration instead of project-level sequence configuration or to override project level sequence configuration on a session-by-session basis, if required (see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|Configuring Sequencing at the Session Level]]).
 
* In a POJO project, you can configure a session directly: in this case, you can use session-level sequence configuration instead of project-level sequence configuration or to override project level sequence configuration on a session-by-session basis, if required (see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|Configuring Sequencing at the Session Level]]).
−
 
  
  
 
====Configuring Where to Write Sequence Values====
 
====Configuring Where to Write Sequence Values====
−
To tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created, you configure EclipseLink sequencing at the descriptor level (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Sequencing at the Descriptor Level|Configuring Sequencing at the Descriptor Level]]).
+
To tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created, you configure EclipseLink [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Sequencing at the Descriptor Level|sequencing at the descriptor level]].
−
 
+
  
  
Line 210: Line 201:
 
As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.
 
As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.
  
−
XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records (see [[Creating%20an%20EIS%20Project%20(ELUG)#Creating an EIS Project with XML Records|Creating an EIS Project with XML Records]]) and XML projects (see [[Introduction%20to%20XML%20Projects%20(ELUG)#XML Project Concepts|XML Project Concepts]]).
+
XML namespaces are applicable in projects that reference an XML schema: [[Creating%20an%20EIS%20Project%20(ELUG)#Creating an EIS Project with XML Records|EIS projects that use XML records]] and [[Introduction%20to%20XML%20Projects%20(ELUG)#XML Project Concepts|XML projects]].
  
 
For more information, see [[#XML Namespaces Overview|XML Namespaces Overview]]].
 
For more information, see [[#XML Namespaces Overview|XML Namespaces Overview]]].
Line 219: Line 210:
 
This section describes the following:
 
This section describes the following:
 
* [[#Project Inheritance Hierarchy|Project Inheritance Hierarchy]]
 
* [[#Project Inheritance Hierarchy|Project Inheritance Hierarchy]]
−
 
  
  
Line 230: Line 220:
 
As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.
 
As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.
  
−
XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records (see [[Creating%20an%20EIS%20Project%20(ELUG)|Creating an EIS Project with XML Records]]) and XML projects (see [[Introduction%20to%20XML%20Projects%20(ELUG)|XML Project Concepts]]).
+
XML namespaces are applicable in projects that reference an XML schema: [[Creating%20an%20EIS%20Project%20(ELUG)#Creating an EIS Project with XML Records|EIS projects that use XML records]] and [[Introduction%20to%20XML%20Projects%20(ELUG)#XML Project Concepts|XML projects]].
  
 
This section describes the following:
 
This section describes the following:
Line 236: Line 226:
 
* [[#Element and Attribute Form Options|Element and Attribute Form Options]]
 
* [[#Element and Attribute Form Options|Element and Attribute Form Options]]
 
* [[#EclipseLink Runtime Namespace Resolution|EclipseLink Runtime Namespace Resolution]]
 
* [[#EclipseLink Runtime Namespace Resolution|EclipseLink Runtime Namespace Resolution]]
−
 
  
  
 
===Workbench Namespace Resolution===
 
===Workbench Namespace Resolution===
 
Using Workbench, you can configure the XML schema namespace for your project. For more information, see [[Using%20Workbench%20(ELUG)#How to Configure XML Schema Namespace|How to Configure XML Schema Namespace]].
 
Using Workbench, you can configure the XML schema namespace for your project. For more information, see [[Using%20Workbench%20(ELUG)#How to Configure XML Schema Namespace|How to Configure XML Schema Namespace]].
−
 
  
  
Line 251: Line 239:
 
* [[#Element and Attribute Form Default Unqualified|Element and Attribute Form Default Unqualified]]
 
* [[#Element and Attribute Form Default Unqualified|Element and Attribute Form Default Unqualified]]
 
* [[#Element and Attribute Form Default Qualified|Element and Attribute Form Default Qualified]]
 
* [[#Element and Attribute Form Default Qualified|Element and Attribute Form Default Qualified]]
−
 
  
  
Line 260: Line 247:
 
<span id="Example 13-1"></span>
 
<span id="Example 13-1"></span>
 
''''' XML Schema with Element Form Default Qualified and Attribute Form Default Unqualified'''''
 
''''' XML Schema with Element Form Default Qualified and Attribute Form Default Unqualified'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
Line 278: Line 266:
 
     <xsd:element name="date-of-birth" type="xsd:date"/>
 
     <xsd:element name="date-of-birth" type="xsd:date"/>
 
  </xsd:schema>
 
  </xsd:schema>
−
 
+
</source>
−
 
+
  
 
This example shows an XML document that conforms to this XML schema.
 
This example shows an XML document that conforms to this XML schema.
Line 285: Line 272:
 
<span id="Example 13-2"></span>
 
<span id="Example 13-2"></span>
 
''''' XML Document'''''
 
''''' XML Document'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
Line 291: Line 279:
 
   
 
   
 
  </'''<tt>ns:</tt>'''customer>
 
  </'''<tt>ns:</tt>'''customer>
 +
</source>
  
−
 
+
The [[#Example 13-3|XML Descriptors and Mappings]] example shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring an XML Descriptor|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)#Configuring an XML Mapping|Configuring an XML Mapping]]).
−
 
+
−
The [[#Example 13-3|XML Descriptors and Mappings]] example shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)|Configuring an XML Mapping]]).
+
  
  
 
<span id="Example 13-3"></span>
 
<span id="Example 13-3"></span>
 
'''''XML Descriptors and Mappings'''''
 
'''''XML Descriptors and Mappings'''''
 +
<source lang="java">
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  namespaceResolver.put("ns", "urn:namespace-example");
 
  namespaceResolver.put("ns", "urn:namespace-example");
Line 320: Line 308:
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  customerDescriptor.addMapping(birthDateMapping);
 
  customerDescriptor.addMapping(birthDateMapping);
−
 
+
</source>
−
 
+
  
 
====Element and Attribute Form Default Unqualified====
 
====Element and Attribute Form Default Unqualified====
Line 329: Line 316:
 
<span id="Example 13-4"></span>
 
<span id="Example 13-4"></span>
 
''''' XML Schema with Element and Attribute Form Default Unqualified'''''
 
''''' XML Schema with Element and Attribute Form Default Unqualified'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
   
 
   
Line 348: Line 336:
 
   
 
   
 
  </xsd:schema>
 
  </xsd:schema>
−
 
+
</source>
−
 
+
  
 
This example shows an XML document that conforms to this XML schema.
 
This example shows an XML document that conforms to this XML schema.
Line 355: Line 342:
 
<span id="Example 13-5"></span>
 
<span id="Example 13-5"></span>
 
''''' XML Document'''''
 
''''' XML Document'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
Line 362: Line 350:
 
  </'''<tt>ns:</tt>'''customer>
 
  </'''<tt>ns:</tt>'''customer>
 
   
 
   
−
 
+
</source>
−
 
+
  
 
The [[#Example 13-6|XML Descriptors and Mappings]] example shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)|Configuring an XML Mapping]]).
 
The [[#Example 13-6|XML Descriptors and Mappings]] example shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)|Configuring an XML Mapping]]).
Line 370: Line 357:
 
<span id="'Example 13-6"></span>
 
<span id="'Example 13-6"></span>
 
'''''XML Descriptors and Mappings'''''
 
'''''XML Descriptors and Mappings'''''
−
+
<source lang="java">
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  namespaceResolver.put("ns", "urn:namespace-example");
 
  namespaceResolver.put("ns", "urn:namespace-example");
Line 392: Line 379:
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  customerDescriptor.addMapping(birthDateMapping);
 
  customerDescriptor.addMapping(birthDateMapping);
−
 
+
</source>
  
  
Line 401: Line 388:
 
<span id="Example 13-7"></span>
 
<span id="Example 13-7"></span>
 
'''''XML Schema with Element and Attribute Form Default Qualified'''''
 
'''''XML Schema with Element and Attribute Form Default Qualified'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
Line 419: Line 407:
 
     <xsd:element name="date-of-birth" type="xsd:date"/>
 
     <xsd:element name="date-of-birth" type="xsd:date"/>
 
  </xsd:schema>
 
  </xsd:schema>
−
 
+
</source>
−
 
+
  
 
This example shows an XML document that conforms to this XML schema.
 
This example shows an XML document that conforms to this XML schema.
Line 426: Line 413:
 
<span id="Example 13-8"></span>
 
<span id="Example 13-8"></span>
 
''''' XML Document'''''
 
''''' XML Document'''''
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" '''<tt>ns:</tt>'''id="1">
 
  <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" '''<tt>ns:</tt>'''id="1">
Line 432: Line 420:
 
   
 
   
 
  </'''<tt>ns:</tt>'''customer>
 
  </'''<tt>ns:</tt>'''customer>
 +
</source>
  
−
 
+
The [[#Example 13-9|XML Descriptors and Mappings]] exampel shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring an XML Descriptor|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)#Configuring an XML Mapping|Configuring an XML Mapping]]).
−
The [[#Example 13-9|XML Descriptors and Mappings]] exampel shows the Java code for a <tt>Customer</tt> class <tt>XMLDescriptor</tt> and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see [[Configuring%20an%20XML%20Descriptor%20(ELUG)|Configuring an XML Descriptor]] and [[Configuring%20an%20XML%20Mapping%20(ELUG)|Configuring an XML Mapping]]).
+
  
  
 
<span id="Example 13-9"></span>
 
<span id="Example 13-9"></span>
 
''''' XML Descriptors and Mappings'''''
 
''''' XML Descriptors and Mappings'''''
−
 
+
<source lang="java">
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  NamespaceResolver namespaceResolver = new NamespaceResolver();
 
  namespaceResolver.put("ns", "urn:namespace-example");
 
  namespaceResolver.put("ns", "urn:namespace-example");
Line 461: Line 449:
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 
  customerDescriptor.addMapping(birthDateMapping);
 
  customerDescriptor.addMapping(birthDateMapping);
−
 
+
</source>
−
 
+
  
 
===EclipseLink Runtime Namespace Resolution===
 
===EclipseLink Runtime Namespace Resolution===
Line 482: Line 469:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
−
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Concept]]
 
[[Category: Concept]]

Latest revision as of 11:23, 18 July 2012

Elug draft icon.png For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

An EclipseLink project encapsulates both mapping metadata and, where relevant, data source access information. The project is the primary object used by EclipseLink at run time. Each session (excluding the session broker) in a deployed application references a single project.


EclipseLink Project Types

This table lists the project types available in EclipseLink and indicates how to create each.

Project Type Description EclipseLink Workbench Java

Relational Projects

A project for transactional persistence of Java objects to a relational database or an object-relational data type database accessed using Java Database Connectivity (JDBC). Supports EclipseLink queries and expressions.

Supported

Supported

EIS Projects

A project for transactional persistence of Java objects to a nonrelational data source accessed using a Java EE Connector Architecture (JCA) adapter and any supported EIS record type, including indexed, mapped, or XML. Supports EclipseLink queries and expressions.

Supported

Supported

XML Projects

A project for nontransactional, nonpersistent (in-memory) conversion between Java objects and XML schema (XSD)-based documents using Java Architecture for XML Binding (JAXB). Does not support EclipseLink queries and expressions.

Supported

Supported

For more information, see the following:


Project Concepts

This section describes concepts unique to EclipseLink projects, including:


Project Architecture

The project type you choose determines the type of descriptors and mappings you can use. There is a project type for each data source type that EclipseLink supports.

This table summarizes the relationship between project, descriptor, and mappings.

Project, Descriptor, and Mapping Support

Project Descriptor Mapping

Relational Projects

Relational Descriptors and Object-Relational Data Type Descriptors

Relational Mappings and Object-Relational Data Type Mappings

EIS Projects

EIS Descriptor Concepts

EIS Mappings

XML Projects

XML Descriptor Concepts

XML Mappings


Relational and Nonrelational Projects

EclipseLink supports both relational and nonrelational projects.

Relational projects persist Java objects to a relational database.

Nonrelational projects persist Java objects to another (nonrelational) type of data source, or perform nonpersistent (see Persistent and Nonpersistent Projects) data conversion. For example, to persist Java objects to an EIS data source by using a JCA adapter, use an EIS project. To perform nonpersistent (in-memory) conversions between Java objects and XML elements, use an XML project.


Persistent and Nonpersistent Projects

EclipseLink supports projects you use for applications that require persistent storage of Java objects. For example, use a relational project to persist Java objects to a relational database, or an EIS project to persist Java objects to an EIS data source by way of a JCA adapter.

EclipseLink also supports projects you use for applications that require only nonpersistent (in-memory) data conversion. For example, use an XML project to perform nonpersistent (in-memory) conversion between Java objects and XML elements.


Projects and Login

The login (if any) associated with a project determines how the EclipseLink runtime connects to the project's data source.

A login includes details of data source access, such as authentication, use of connection pools, and use of external transaction controllers. A login owns a platform.

A platform includes options specific to a particular data source, such as binding, use of native SQL, use of batch writing, and sequencing. For more information about platforms, see Projects and Platforms.

For projects that do not persist to a data source, a login is not required. For projects that do persist to a data source, a login is always required.

In Workbench, the project type determines the type of login that the project uses, if applicable.

You can use a login in a variety of roles. A login's role determines where and how you create it. The login role you choose depends on the type of project you are creating and how you intend to use the login:


POJO Session Role

You create a session login in the sessions.xml file for EclipseLink applications that do not use container-managed persistence (CMP).

Typically, the EclipseLink runtime instantiates a project when you load a session from the sessions.xml file. The runtime also instantiates a login and its platform based on the information in the sessions.xml file.

The EclipseLink runtime uses the information in the session login whenever you perform a persistence operation using the session in your POJO EclipseLink application.

If you are using Workbench and your login is based on a relational database platform, you must also configure a development login.

If a sessions.xml file contains a login, this login overrides any other login definition.

There is a session login type for each project type that persists to a data source. For a complete list of login types available, see Data Source Login Types.

For information on configuring a session login, see Configuring a Session Login.


Development Role

Using Workbench, you create a development login in the Workbench project file when your project is based on a relational database platform.

Workbench uses the information in the development login whenever you perform a data source operation from within Workbench, for example, whenever you read or write schema information from or to a data store during application development. The development login information is never written to a sessions.xml or project.xml file.

The development login is never used when you deploy your application: it is overridden by either the sessions.xml file (see POJO Session Role) or the project.xml file.

For more information on creating a development login, see Configuring Development and Deployment Logins.


Projects and Platforms

The platform (if any) associated with a project tells the EclipseLink runtime what specific type of data source a project uses.

A platform includes options specific to a particular data source, such as binding, use of native SQL, use of batch writing, and sequencing.

A login includes details of data source access, such as authentication, use of connection pools, and use of external transaction controllers. A login owns a platform. For more information about logins, see Projects and Login.

For projects that do not persist to a data source, a platform is not required. For projects that do persist to a data source, a platform is always required.

In Workbench, the project type determines the type of platform that the project uses, if applicable.

There is a platform type for each project type that persists to a data source. For a complete list of platform types available, see Data Source Platform Types.


Projects and Sequencing

An essential part of maintaining object identity is sequencing: managing the assignment of unique values to distinguish one instance from another.

Projects have different sequencing requirements, depending on their types:

  • For relational projects, you typically obtain object identifier values from a separate sequence table (or database object) dedicated to managing object identifier values (see Sequencing in Relational Projects).
  • For EIS projects, you typically use a returning policy to obtain object identifier values managed by the EIS data source.
  • For XML projects, because you are simply performing transformations between objects and XML documents, sequencing is not an issue.

To configure sequencing, you must configure the following:

Depending on the type of sequencing you use and the architecture of your application, you may consider using Sequence Connection Pools.


Configuring How to Obtain Sequence Values

To determine how EclipseLink obtains sequence values, you configure EclipseLink sequencing at the project or session level, depending on the type of project you are building, as follows:

  • In a POJO project, you can configure a session directly: in this case, you can use session-level sequence configuration instead of project-level sequence configuration or to override project level sequence configuration on a session-by-session basis, if required (see Configuring Sequencing at the Session Level).


Configuring Where to Write Sequence Values

To tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created, you configure EclipseLink sequencing at the descriptor level.


XML Namespaces

As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.

XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records and XML projects.

For more information, see XML Namespaces Overview].


Project API

This section describes the following:


Project Inheritance Hierarchy

There is only one type of project: org.eclipse.eclipselink.sessions.Project.


XML Namespaces Overview

As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.

XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records and XML projects.

This section describes the following:


Workbench Namespace Resolution

Using Workbench, you can configure the XML schema namespace for your project. For more information, see How to Configure XML Schema Namespace.


Element and Attribute Form Options

The xsd:schema element provides attributes that you can use to specify how elements and attributes should be qualified by namespace.

This section describes the consequences of the following combinations of element and attribute form configuration:


Element Form Default Qualified and Attribute Form Default Unqualified

The XML Schema with Element Form Default Qualified and Attribute Form Default Unqualified example shows an XML schema in which a target namespace is set. It is coded with elementFormDefault set to qualified and attributeFormDefault set to unqualified. This means all elements must be namespace qualified and globally declared attributes must be namespace qualified and locally defined attributes must not be namespace qualified.


XML Schema with Element Form Default Qualified and Attribute Form Default Unqualified 

 <?xml version="1.0" encoding="UTF-8"?>
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     '''<tt>elementFormDefault="qualified"</tt>''' 
     '''<tt>attributeFormDefault="unqualified"</tt>'''
     xmlns="urn:namespace-example"
     targetNamespace="urn:namespace-example">
     <xsd:element name="customer" type="customer-type"/>
 
     <xsd:complexType name="customer-type">
         <xsd:sequence>
             <xsd:element name="name" type="xsd:string"/>
             <xsd:element ref="date-of-birth"/>
         </xsd:sequence>
         <xsd:attribute name="id" type="xsd:integer"/>
 
     </xsd:complexType>
     <xsd:element name="date-of-birth" type="xsd:date"/>
 </xsd:schema>

This example shows an XML document that conforms to this XML schema.

XML Document 

 <?xml version="1.0" encoding="UTF-8"?>
 <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
     <'''<tt>ns:</tt>'''name>Jane Doe</'''<tt>ns:</tt>'''name>
     <'''<tt>ns:</tt>'''date-of-birth>1975-02-21</'''<tt>ns:</tt>'''date-of-birth>
 
 </'''<tt>ns:</tt>'''customer>

The XML Descriptors and Mappings example shows the Java code for a Customer class XMLDescriptor and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see Configuring an XML Descriptor and Configuring an XML Mapping).


XML Descriptors and Mappings 

 NamespaceResolver namespaceResolver = new NamespaceResolver();
 namespaceResolver.put("ns", "urn:namespace-example");
 
 XMLDescriptor customerDescriptor = new XMLDescriptor();
 customerDescriptor.setJavaClass(Customer.class);
 customerDescriptor.setDefaultRootElement("'''<tt>ns:</tt>'''customer");
 customerDescriptor.setNamespaceResolver(namespaceResolver);
         XMLDirectMapping idMapping = new XMLDirectMapping();
 idMapping.setAttributeName("id");
 idMapping.setXPath("@id");
 customerDescriptor.addMapping(idMapping);
 
 XMLDirectMapping nameMapping = new XMLDirectMapping();
 nameMapping.setAttributeName("name");
 nameMapping.setXPath("'''<tt>ns:</tt>'''name/text()");
 customerDescriptor.addMapping(nameMapping);
 
 XMLDirectMapping birthDateMapping = new XMLDirectMapping();
 birthDateMapping.setAttributeName("birthDate");
 birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 customerDescriptor.addMapping(birthDateMapping);

Element and Attribute Form Default Unqualified

The XML Schema with Element and Attribute Form Default Unqualified example shows an XML schema in which a target namespace is set. It is coded with elementFormDefault and attributeFormDefault set to unqualified. This means that globally defined nodes must be namespace qualified and locally defined nodes must not be namespace qualified.


XML Schema with Element and Attribute Form Default Unqualified 

 <?xml version="1.0" encoding="UTF-8"?>
 
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     '''<tt>elementFormDefault="unqualified"</tt>''' 
     '''<tt>attributeFormDefault="unqualified"</tt>'''
     xmlns="urn:namespace-example"
     targetNamespace="urn:namespace-example">
     <xsd:element name="customer" type="customer-type"/>
     <xsd:complexType name="customer-type">
         <xsd:sequence>
 
             <xsd:element name="name" type="xsd:string"/>
             <xsd:element ref="date-of-birth"/>
         </xsd:sequence>
         <xsd:attribute name="id" type="xsd:integer"/>
     </xsd:complexType>
     <xsd:element name="date-of-birth" type="xsd:date"/>
 
 </xsd:schema>

This example shows an XML document that conforms to this XML schema.

XML Document 

 <?xml version="1.0" encoding="UTF-8"?>
 <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" id="1">
 
     <name>Jane Doe</name>
     <'''<tt>ns:</tt>'''date-of-birth>1975-02-21</'''<tt>ns:</tt>'''date-of-birth>
 </'''<tt>ns:</tt>'''customer>

The XML Descriptors and Mappings example shows the Java code for a Customer class XMLDescriptor and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see Configuring an XML Descriptor and Configuring an XML Mapping).


XML Descriptors and Mappings 

 
 NamespaceResolver namespaceResolver = new NamespaceResolver();
 namespaceResolver.put("ns", "urn:namespace-example");
 
 XMLDescriptor customerDescriptor = new XMLDescriptor();
 customerDescriptor.setJavaClass(Customer.class);
 customerDescriptor.setDefaultRootElement("'''<tt>ns:</tt>'''customer");
 customerDescriptor.setNamespaceResolver(namespaceResolver);
                         XMLDirectMapping idMapping = new XMLDirectMapping();
 idMapping.setAttributeName("id");
 idMapping.setXPath("@id");
 customerDescriptor.addMapping(idMapping);
 
 XMLDirectMapping nameMapping = new XMLDirectMapping();
 nameMapping.setAttributeName("name");
 nameMapping.setXPath("name/text()");
 customerDescriptor.addMapping(nameMapping);
 
 XMLDirectMapping birthDateMapping = new XMLDirectMapping();
 birthDateMapping.setAttributeName("birthDate");
 birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 customerDescriptor.addMapping(birthDateMapping);


Element and Attribute Form Default Qualified

The XML Schema with Element and Attribute Form Default Qualified example shows an XML schema in which a target namespace is set. It is coded with elementFormDefault and attributeFormDefault set to qualified. This means that all nodes must be namespace qualified.


XML Schema with Element and Attribute Form Default Qualified 

 <?xml version="1.0" encoding="UTF-8"?>
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     '''<tt>elementFormDefault="qualified"</tt>''' 
     '''<tt>attributeFormDefault="qualified"</tt>'''
     xmlns="urn:namespace-example"
     targetNamespace="urn:namespace-example">
     <xsd:element name="customer" type="customer-type"/>
 
     <xsd:complexType name="customer-type">
         <xsd:sequence>
             <xsd:element name="name" type="xsd:string"/>
             <xsd:element ref="date-of-birth"/>
         </xsd:sequence>
         <xsd:attribute name="id" type="xsd:integer"/>
 
     </xsd:complexType>
     <xsd:element name="date-of-birth" type="xsd:date"/>
 </xsd:schema>

This example shows an XML document that conforms to this XML schema.

XML Document 

 <?xml version="1.0" encoding="UTF-8"?>
 <'''<tt>ns:</tt>'''customer xmlns:ns="urn:namespace-example" '''<tt>ns:</tt>'''id="1">
     <'''<tt>ns:</tt>'''name>Jane Doe</'''<tt>ns:</tt>'''name>
     <'''<tt>ns:</tt>'''date-of-birth>1975-02-21</'''<tt>ns:</tt>'''date-of-birth>
 
 </'''<tt>ns:</tt>'''customer>

The XML Descriptors and Mappings exampel shows the Java code for a Customer class XMLDescriptor and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see Configuring an XML Descriptor and Configuring an XML Mapping).


XML Descriptors and Mappings 

 NamespaceResolver namespaceResolver = new NamespaceResolver();
 namespaceResolver.put("ns", "urn:namespace-example");
 
 XMLDescriptor customerDescriptor = new XMLDescriptor();
 customerDescriptor.setJavaClass(Customer.class);
 customerDescriptor.setDefaultRootElement("'''<tt>ns:</tt>'''customer");
 customerDescriptor.setNamespaceResolver(namespaceResolver);
                         XMLDirectMapping idMapping = new XMLDirectMapping();
 idMapping.setAttributeName("id");
 idMapping.setXPath("@'''<tt>ns:</tt>'''id");
 customerDescriptor.addMapping(idMapping);
 
 XMLDirectMapping nameMapping = new XMLDirectMapping();
 nameMapping.setAttributeName("name");
 nameMapping.setXPath("'''<tt>ns:</tt>'''name/text()");
 customerDescriptor.addMapping(nameMapping);
 
 XMLDirectMapping birthDateMapping = new XMLDirectMapping();
 birthDateMapping.setAttributeName("birthDate");
 birthDateMapping.setXPath("'''<tt>ns:</tt>'''date-of-birth/text()");
 customerDescriptor.addMapping(birthDateMapping);

EclipseLink Runtime Namespace Resolution

It is common for an XML document to include one or more namespaces. EclipseLink supports this using its NamespaceResolver. The namespace resolver maintains pairs of namespace prefixes and Uniform Resource Identifiers (URIs). EclipseLink uses these prefixes in conjunction with the XPath statements you specify on EIS mappings to XML records and XML mappings.

Although EclipseLink captures namespace prefixes in the XPath statements for mappings (if applicable), the input document is not required to use the same namespace prefixes. As the XML Descriptors and Mappings example shows, EclipseLink will use the namespace prefixes specified in the mapping when creating new documents.


Namespaces in EclipseLink

Namespaces in EclipseLink


Copyright Statement

Retrieved from "https://wiki.eclipse.org/index.php?title=Introduction_to_Projects_(ELUG)&oldid=310857"

This page was last modified 11:23, 18 July 2012 by Rick Sapir. Based on work by Liza Rekadze.

Back to the top