15 Introduction to Projects
A TopLink project encapsulates both mapping metadata and, where relevant, data source access information. The project is the primary object used by TopLink at run time. Each session (excluding the session broker) in a deployed application references a single project.
This chapter includes the following sections:
15.1 TopLink Project Types
Table 15-1 lists the project types available in TopLink, classifies each as basic or advanced, and indicates how to create each.
Table 15-1 TopLink Project Types
| Project Type | Description | Oracle JDeveloper |
TopLink Workbench | Java |
|---|---|---|---|---|
|
Relational (see Chapter 18, "Introduction to 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 TopLink queries and expressions. |
 |
|
|
|
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 TopLink queries and expressions. |
|
|
|
|
|
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 TopLink queries and expressions. |
|
|
|
For more information, see the following:
15.2 Project Concepts
This section describes concepts unique to TopLink projects, including the following:
15.2.1 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 TopLink supports.
Table 15-2 summarizes the relationship between project, descriptor, and mappings.
Table 15-2 Project, Descriptor, and Mapping Support
| Project | Descriptor | Mapping |
|---|---|---|
|
Relational (se)e Chapter 18, "Introduction to Relational Projects" |
The following:
|
The following:
|
|
EIS (see Section 17.7, "EIS Mappings" |
||
|
XML (see Section 17.6, "XML Mappings" |
15.2.2 Relational and Nonrelational Projects
TopLink 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 Section 15.2.3, "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.
15.2.3 Persistent and Nonpersistent Projects
TopLink 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.
TopLink 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.
15.2.4 Projects and Login
The login (if any) associated with a project determines how the TopLink 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 Section 15.2.5, "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 TopLink 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:
15.2.4.1 POJO Session Role
You create a session login in the sessions.xml file for TopLink applications that do not use container-managed persistence (CMP).
Typically, the TopLink runtime instantiates a project when you load a session from the sessions.xml file (see Chapter 90, "Acquiring and Using Sessions at Run Time"). The runtime also instantiates a login and its platform based on the information in the sessions.xml file.
The TopLink runtime uses the information in the session login whenever you perform a persistence operation using the session in your POJO TopLink application.
In this case, you do not configure a deployment login (see Section 15.2.4.2, "CMP Deployment Role").
If you are using TopLink Workbench and your login is based on a relational database platform, you must also configure a development login (see Section 15.2.4.3, "Development Role").
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 Section 96.1.2, "Data Source Login Types".
For information on configuring a session login, see Section 89.3, "Configuring a Session Login".
15.2.4.2 CMP Deployment Role
You create a deployment login in the project.xml file (also known as the toplink-ejb-jar.xml file) for a TopLink-enabled CMP application.
When you deploy your TopLink-enabled CMP application with its toplink-ejb-jar.xml file, the application server or EJB container uses the information in the deployment login whenever your business logic performs a persistence operation from within an entity bean with container-managed persistence.
In this case, you do not configure a session login (see Section 15.2.4.1, "POJO Session Role"). In fact, there is no session.xml file at all (see Section 9.1.2.4, "CMP Applications and Session Metadata").
If you are using TopLink Workbench and your login is based on a relational database platform, you must also configure a development login (see Section 15.2.4.3, "Development Role").
For information on creating a deployment login, see Section 20.5, "Configuring Development and Deployment Logins".
15.2.4.3 Development Role
Using TopLink Workbench, you create a development login in the TopLink Workbench project file when your project is based on a relational database platform.
TopLink Workbench uses the information in the development login whenever you perform a data source operation from within TopLink 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 Section 15.2.4.1, "POJO Session Role") or the project.xml file (see Section 15.2.4.2, "CMP Deployment Role").
For more information on creating a development login, see Section 20.5, "Configuring Development and Deployment Logins".
15.2.5 Projects and Platforms
The platform (if any) associated with a project tells the TopLink 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 Section 15.2.4, "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 TopLink 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 Section 96.1.3, "Data Source Platform Types".
15.2.6 Projects and Sequencing
An essential part of maintaining object identity (see Section 102.2.1, "Cache Type and 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 Section 18.2, "Sequencing in Relational Projects").
-
For EIS projects, you typically use a returning policy (see Section 119.27, "Configuring 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:
-
how to obtain sequence values (see Section 15.2.6.1, "Configuring How to Obtain Sequence Values"), and
-
where to write sequence values when an instance of a descriptor's reference class is created (see Section 15.2.6.2, "Configuring Where to Write Sequence Values").
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 Section 96.1.6.4, "Sequence Connection Pools".
15.2.6.1 Configuring How to Obtain Sequence Values
To determine how TopLink obtains sequence values, you configure TopLink sequencing at the project or session level, depending on the type of project you are building, as follows:
-
In a CMP project, you do not configure a session directly: in this case, you must configure sequences at the project level (see Section 20.3, "Configuring Sequencing at the Project 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 Section 98.4, "Configuring Sequencing at the Session Level").
15.2.6.2 Configuring Where to Write Sequence Values
To tell TopLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created, you configure TopLink sequencing at the descriptor level (see Section 23.3, "Configuring Sequencing at the Descriptor Level").
15.2.7 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 (see Section 72.2, "Creating an EIS Project with XML Records") and XML projects (see Section 47.1, "XML Project Concepts").
For more information, see Section 15.4, "XML Namespaces Overview".
15.3 Project API
This section describes the following:
15.3.1 Project Inheritance Hierarchy
There is only one type of project: oracle.toplink.sessions.Project.
15.4 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 (see Section 72.2, "Creating an EIS Project with XML Records") and XML projects (see Section 47.1, "XML Project Concepts").
You can use Oracle JDeveloper or TopLink Workbench to configure the XML schema namespae for your project.
This section describes the following:
15.4.1 TopLink Workbench Namespace Resolution
Using TopLink Workbench, you can configure the XML schema namespace for your project. For more information, see Section 5.6.5, "How to Configure XML Schema Namespace".
15.4.2 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:
15.4.2.1 Element Form Default Qualified and Attribute Form Default Unqualified
Example 15-1 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.
Example 15-1 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"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
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>
Example 15-2 shows an XML document that conforms to this XML schema.
<?xml version="1.0" encoding="UTF-8"?> <ns:customer xmlns:ns="urn:namespace-example" id="1"> <ns:name>Jane Doe</ns:name> <ns:date-of-birth>1975-02-21</ns:date-of-birth> </ns:customer>
Example 15-3 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 Chapter 52, "Configuring an XML Descriptor" and Chapter 54, "Configuring an XML Mapping").
Example 15-3 XML Descriptors and Mappings
NamespaceResolver namespaceResolver = new NamespaceResolver();
namespaceResolver.put("ns", "urn:namespace-example");
XMLDescriptor customerDescriptor = new XMLDescriptor();
customerDescriptor.setJavaClass(Customer.class);
customerDescriptor.setDefaultRootElement("ns: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("ns:name/text()");
customerDescriptor.addMapping(nameMapping);
XMLDirectMapping birthDateMapping = new XMLDirectMapping();
birthDateMapping.setAttributeName("birthDate");
birthDateMapping.setXPath("ns:date-of-birth/text()");
customerDescriptor.addMapping(birthDateMapping);
15.4.2.2 Element and Attribute Form Default Unqualified
Example 15-4 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.
Example 15-4 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"
elementFormDefault="unqualified"
attributeFormDefault="unqualified"
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>
Example 15-5 shows an XML document that conforms to this XML schema.
<?xml version="1.0" encoding="UTF-8"?> <ns:customer xmlns:ns="urn:namespace-example" id="1"> <name>Jane Doe</name> <ns:date-of-birth>1975-02-21</ns:date-of-birth> </ns:customer>
Example 15-6 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 Chapter 52, "Configuring an XML Descriptor" and Chapter 54, "Configuring an XML Mapping").
Example 15-6 XML Descriptors and Mappings
NamespaceResolver namespaceResolver = new NamespaceResolver();
namespaceResolver.put("ns", "urn:namespace-example");
XMLDescriptor customerDescriptor = new XMLDescriptor();
customerDescriptor.setJavaClass(Customer.class);
customerDescriptor.setDefaultRootElement("ns: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("ns:date-of-birth/text()");
customerDescriptor.addMapping(birthDateMapping);
15.4.2.3 Element and Attribute Form Default Qualified
Example 15-7 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.
Example 15-7 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"
elementFormDefault="qualified"
attributeFormDefault="qualified"
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>
Example 15-8 shows an XML document that conforms to this XML schema.
<?xml version="1.0" encoding="UTF-8"?> <ns:customer xmlns:ns="urn:namespace-example" ns:id="1"> <ns:name>Jane Doe</ns:name> <ns:date-of-birth>1975-02-21</ns:date-of-birth> </ns:customer>
Example 15-9 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 Chapter 52, "Configuring an XML Descriptor" and Chapter 54, "Configuring an XML Mapping").
Example 15-9 XML Descriptors and Mappings
NamespaceResolver namespaceResolver = new NamespaceResolver();
namespaceResolver.put("ns", "urn:namespace-example");
XMLDescriptor customerDescriptor = new XMLDescriptor();
customerDescriptor.setJavaClass(Customer.class);
customerDescriptor.setDefaultRootElement("ns:customer");
customerDescriptor.setNamespaceResolver(namespaceResolver);
XMLDirectMapping idMapping = new XMLDirectMapping();
idMapping.setAttributeName("id");
idMapping.setXPath("@ns:id");
customerDescriptor.addMapping(idMapping);
XMLDirectMapping nameMapping = new XMLDirectMapping();
nameMapping.setAttributeName("name");
nameMapping.setXPath("ns:name/text()");
customerDescriptor.addMapping(nameMapping);
XMLDirectMapping birthDateMapping = new XMLDirectMapping();
birthDateMapping.setAttributeName("birthDate");
birthDateMapping.setXPath("ns:date-of-birth/text()");
customerDescriptor.addMapping(birthDateMapping);
15.4.3 TopLink Runtime Namespace Resolution
It is common for an XML document to include one or more namespaces. TopLink supports this using its NamespaceResolver. The namespace resolver maintains pairs of namespace prefixes and Uniform Resource Identifiers (URIs). TopLink uses these prefixes in conjunction with the XPath statements you specify on EIS mappings to XML records and XML mappings.
Although TopLink captures namespace prefixes in the XPath statements for mappings (if applicable), the input document is not required to use the same namespace prefixes. As Example 15-9 shows, TopLink will use the namespace prefixes specified in the mapping when creating new documents.
