diff --git a/docs/docs.ug/pom.xml b/docs/docs.ug/pom.xml new file mode 100644 index 00000000000..fbb4be35784 --- /dev/null +++ b/docs/docs.ug/pom.xml @@ -0,0 +1,97 @@ + + + + 4.0.0 + + Documentation - Solutions + Documentation - User Guide (Old) + org.eclipse.persistence + org.eclipse.persistence.documentation.userguide + 5.0.0-SNAPSHOT + pom + + + org.eclipse.persistence + org.eclipse.persistence.documentation + 5.0.0-SNAPSHOT + ../pom.xml + + + + main.adoc + ${project.basedir}/src/main/asciidoc + user-guide + + + + + + maven-resources-plugin + + + copy-source-documents + generate-resources + + + + + org.apache.maven.plugins + maven-dependency-plugin + + + unpack-shared-docs + generate-resources + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + generate-resources + + ${output.document.name}.html + + + + asciidoc-to-html-img-text + generate-resources + + + asciidoc-to-pdf + generate-resources + + ${output.document.name}.pdf + + + + asciidoc-to-epub + generate-resources + + ${output.document.name}.epub + + + + + + + diff --git a/docs/docs.ug/src/main/asciidoc/core/Acquiring_and_Using_Sessions_at_Run_Time_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Acquiring_and_Using_Sessions_at_Run_Time_(ELUG).adoc new file mode 100644 index 00000000000..cf482742bf6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Acquiring_and_Using_Sessions_at_Run_Time_(ELUG).adoc @@ -0,0 +1,732 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Acquiring_and_Using_Sessions_at_Run_Time_(ELUG)[Related +Topics] + +After you create and configure sessions, you can use the session manager +to acquire a session instance at run time. + +== Introduction to Session Acquisition + +We recommend that you export session instances from the Workbench to one +or more uniquely named `+sessions.xml+` files and then use the session +manager to load sessions from these `+sessions.xml+` files. + +The EclipseLink session manager lets you build a series of sessions that +are maintained under a single entity. The session manager is a static +utility class that loads EclipseLink sessions from the `+sessions.xml+` +file, caches the sessions by name in memory, and provides a single +access point for EclipseLink sessions. The session manager supports the +following session types: + +* Server Session +* Database Session +* SessionBroker + +See +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#CACJAFDF[Introduction +to EclipseLink Sessions] for detailed information on these available +sessions. + +The session manager has two main functions: it creates instances of the +sessions and it ensures that only a single instance of each named +session exists for any instance of a session manager. + +This is particularly useful for EJB applications in that an enterprise +bean can acquire the session manager and acquire the desired session +from it. + +=== Session Manager + +When a client application requires a session, it requests the session +from the EclipseLink session manager. The two main functions of the +session manager are to instantiate EclipseLink sessions for the server, +and to hold the sessions for the life of the application. The session +manager instantiates database sessions, server sessions, or session +brokers based on the configuration information in the `+sessions.xml+` +file. + +The session manager instantiates sessions as follows: + +* The client application requests a session by name. +* The session manager looks up the session name in the `+sessions.xml+` +file. If the session name exists, the session manager instantiates the +specified session; otherwise, it throws an exception. +* After instantiation, the session remains viable until the application +is shut down. + +=== Multiple Sessions + +We recommend that you acquire sessions from the session manager and +perform all persistence operations using a client session or the unit of +work. + +Note that in the case of a server session or a session broker that +contains server sessions, after you acquire the session you will acquire +a client session from it. From a given server session (or session broker +that contains server sessions), you can acquire as many client sessions +as you have clients. + +Each client can easily manage concurrent access and referential +constraints by acquiring a unit of work from its client session and +performing all persistence operations using the unit of work. + +== Acquiring the Session Manager + +EclipseLink maintains only one instance of the session manager class. +The singleton session manager maintains all the named EclipseLink +sessions at run time. When an application requests a session by name, +the session manager retrieves the specified session from the appropriate +configuration file. + +As the link:#Example_86-1[Acquiring a Session Manager Instance] example +illustrates, to access the session manager instance, use the +`+org.eclipse.persistence.tools.sessionmanagement.SessionManager+` +method `+getManager+`. You can then use the session manager instance to +load EclipseLink sessions. + +[#Example 86-1]## *_Acquiring a Session Manager Instance_* + +[source,java] +---- + import org.eclipse.persistence.tools.sessionmanagement.SessionManager; + SessionManager sessionManager = SessionManager.getManager(); +---- + +== Acquiring a Session from the Session Manager + +When the session manager loads a session that is not yet in its cache, +the session manager creates an instance of the appropriate session type +and configures it according to the `+sessions.xml+` file configuration. + +[width="100%",cols="<100%",] +|=== +|*Note:* To best use the methods associated with the session type that +is being instantiated, cast the session that is returned from the +`+getSession+` method. This type must match the session type that is +defined in the `+sessions.xml+` file for the named session. +|=== + +This section explains the following: + +* link:#How_to_Load_a_Session_from_sessions.xml_Using_Defaults[How to +Load a Session from sessions.xml Using Defaults] +* link:#How_to_Load_a_Session_from_sessions.xml_with_an_Alternative_Class_Loader[How +to Load a Session from sessions.xml with an Alternative Class Loader] +* link:#How_to_Load_a_Session_from_an_Alternative_Session_Configuration_File[How +to Load a Session from an Alternative Session Configuration File] +* link:#How_to_Load_a_Session_Without_Logging_In[How to Load a Session +Without Logging In] +* link:#How_to_Reload_and_Refresh_Session_Configuration[How to Reload +and Refresh Session Configuration] +* link:#How_to_Refresh_a_Session_when_the_Class_Loader_Changes[How to +Refresh a Session when the Class Loader Changes] + +=== How to Load a Session from sessions.xml Using Defaults + +If you have a single sessions configuration file (`+sessions.xml+`) that +contains all the session instances created by the Workbench, then you +can load a session by name, as this example illustrates. + +[#Example 86-2]## *_Acquiring a Named Session from Session Manager Using +Defaults_* + +[source,java] +---- + // Load a named session (mysession) defined in the sessions.xml file + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession("mysession"); +---- + +In this example, the following session manager default configuration +applies: + +* Class loader – The thread-based class loader is used to find and load +the `+sessions.xml+` resource and resolve any classes referenced in the +`+sessions.xml+` and `+project.xml+` files. If you acquire the session +in an application class, this will typically be the application’s class +loader, which is correct. In a Java EE application, it is best to +specify this as the class loader from a class in the same JAR file that +the `+sessions.xml+` file is deployed in. +* File – By default, the file named `+sessions.xml+` in the root +directory relative to the class loader is used. If the file is named +differently, or not in the root directory, the relative path must be +specified. Relative resource paths in Java must use `+" / "+`, not +`+" \ "+`. +* Session name – The name passed into the `+getSession+` call. This name +must be unique for the entire application server, not just unique within +the application. +* Login – `+true+`. The session will be connected by default. If you +must manually configure the session before login, set this option to +`+false+` (see link:#How_to_Load_a_Session_Without_Logging_In[How to +Load a Session Without Logging In]). +* Refresh – `+false+`. If already loaded, the same session will be +returned. Refresh should only be used, if it is known that the existing +session is not being used, and the configuration has changed, such as in +a Java EE environment redeployment scenario. +* Verify class loader – false. The session manager will not refresh the +session if the class loader changes. This should normally be set to +`+true+`. It must be set to `+true+` in a Java EE environment, if hot +deployment or redeployment to a running application server is required +(see link:#How_to_Refresh_a_Session_when_the_Class_Loader_Changes[How to +Refresh a Session when the Class Loader Changes]). + +=== How to Load a Session from sessions.xml with an Alternative Class Loader + +You can use an alternative class loader to load sessions. This is common +when your EclipseLink application integrates with a Java EE container. +The session manager uses the class loader to find and load the +`+sessions.xml+` resource and resolve any classes referenced in the +`+sessions.xml+` and `+project.xml+` files. + +In most cases, you use the class loader from the current thread context, +as the link:#Example_86-3[Loading a Session Using the Current Thread +Context Class Loader] example illustrates. In this example, the session +named `+mysession+` is loaded from the first file in the application +classpath named `+sessions.xml+` using the class loader associated with +the current thread context. + +[#Example 86-3]## *_Loading a Session Using the Current Thread Context +Class Loader_* + +[source,java] +---- + /* Use the specified ClassLoader to load a session (mysession) defined in the sessions.xml file */ + + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession( + "mysession", // session name to load + Thread.current().getContextClassLoader() // ClassLoader instance to use + ); +---- + +However, if your Java EE container does not support using the current +thread context class loader, you can use the class loader from the +current class, as this example illustrates. + +[#Example 86-4]## *_Loading a Session Using the Current Class’s Class +Loader_* + +[source,java] +---- + /* Use the specified ClassLoader to load a session (mysession) defined in the sessions.xml file */ + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession( + "mysession", // session name to load + this.getClass().getClassLoader() // ClassLoader instance to use + ); +---- + +[width="100%",cols="<100%",] +|=== +|*Note*: Oracle Containers for J2EE supports the use of the class loader +from the current thread. +|=== + +=== How to Load a Session from an Alternative Session Configuration File + +If your session instances are contained in multiple, uniquely named +session configuration files (`+sessions.xml+` files), then you must +explicitly create an `+XMLSessionConfigLoader+` object initialized with +the name of the `+sessions.xml+` file and pass that +`+XMLSessionConfigLoader+` into the `+SessionManager+` method +`+getSession+`, as the link:#Example_86-5[Loading a Session from an +Alternative Configuration File] example illustrates. + +The file path you specify is relative to the class loader root +directory. Relative resource paths in Java must use the forward slash ( +`+/+` ), not back slash ( `+\+` ). + +In this example, the session named `+mysession+` is loaded by the +specified class loader from the first file in the application classpath +named `+eclipselink-sessions.xml+`. + +[#Example 86-5]## *_Loading a Session from an Alternative Configuration +File_* + +[source,java] +---- + // XMLSessionConfigLoader loads the eclipselink-sessions.xml file + SessionManager manager = SessionManager.getManager(); + manager.getSession( + new XMLSessionConfigLoader("eclipselink-sessions.xml"), + "mysession", + this.class.getClassLoader() + ); +---- + +=== How to Load a Session Without Logging In + +The `+XMLSessionConfigLoader+` (see +link:#How_to_Load_a_Session_from_an_Alternative_Session_Configuration_File[How +to Load a Session from an Alternative Session Configuration File]) lets +you call a session using the `+SessionManager+` method `+getSession+`, +without invoking the `+Session+` method `+login+`, as the +link:#Example_86-6[Open Session with No Login] example shows. This lets +you prepare a session for use and leave login to the application. + +[#Example 86-6]## *_Open Session with No Login_* + +[source,java] +---- + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession( + new XMLSessionConfigLoader(), // XMLSessionConfigLoader (sessions.xml file) + "mysession", // session name + YourApplicationClass.getClassLoader(), // class loader + false, // do not log in session + false); // do not refresh session +---- + +=== How to Reload and Refresh Session Configuration + +You can tell the session manager to refresh an existing session from the +`+sessions.xml+` file. Typically, this would only ever be used in a Java +EE environment at redeployment time, or after a reset of a running +server. You should only use this option when you know that the existing +session is not being used. + +[#Example 86-7]## *_Forcing a Reparse of the sessions.xml File_* + +[source,java] +---- + //In this example, XMLSessionConfigLoader loads sessions.xml from the classpath + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession( + new XMLSessionConfigLoader(), // XMLSessionConfigLoader (sessions.xml file) + "mysession", // session name + YourApplicationClass.getClassLoader(), // class loader + true, // log in session + true // refresh session + ); +---- + +=== How to Refresh a Session when the Class Loader Changes + +In an unmanaged (POJO) Java EE environment, if you require hot +deployment or redeployment to a running application server, you must +tell the session manager to refresh your session if the class loader +changes, as the link:#Example_86-8[Forcing a Reparse of the sessions.xml +File] example shows. This option makes the session manager refresh the +session if the class loader changes, which occurs when the application +is redeployed. When this option is set to `+true+`, the same class +loader must always be used to retrieve the session. + +[#Example 86-8]## *_Forcing a Reparse of the sessions.xml File_* + +[source,java] +---- + //In this example, XMLSessionConfigLoader loads sessions.xml from the classpath + SessionManager manager = SessionManager.getManager(); + Session session = manager.getSession( + new XMLSessionConfigLoader(), // XMLSessionConfigLoader (sessions.xml file) + "mysession", // session name + YourApplicationClass.getClassLoader(), // class loader + true, // log in session''' + false, // do not refresh session when loaded + true // do refresh session if class loader changes + ); +---- + +== Acquiring a Client Session + +Before you can acquire a client session, you must first use the session +manager to acquire a server session or a session broker that contains +server sessions (see +link:#Acquiring_a_Session_from_the_Session_Manager[Acquiring a Session +from the Session Manager]). + +This table summarizes the methods used to acquire various types of +client sessions from a server session and a session broker session that +contains server sessions. + +[#Table 86-1]## *_Method Used to Acquire a Client Session_* + +[width="100%",cols="<22%,<40%,<38%",options="header",] +|=== +|*Client Session* |*Server Session Method* |*Session Broker Session +Method* +|Regular or Isolated |`+acquireClientSession()+` +|`+acquireClientSessionBroker()+` + +|Regular or Isolated |`+acquireClientSession(ConnectionPolicy)+` |_not +applicable_ + +|Historical |`+acquireHistoricalSession(AsOfClause)+` +|`+acquireHistoricalSession(AsOfClause)+` +|=== + +The `+acquireClientSession+` method returns a session of type +`+ClientSession+`. + +The `+acquireClientSessionBroker+` method returns a session of type +`+SessionBroker+`. + +In both cases, you should cast the returned object to type `+Session+` +and use it as you would any other session. + +For more information, see the following: + +* link:#How_to_Acquire_an_Isolated_Client_Session[ow to Acquire an +Isolated Client Session] +* link:#Acquiring_a_Historical_Session[Acquiring a Historical Session] +* link:#How_to_Acquire_a_Client_Session_that_Uses_Exclusive_Connections[How +to Acquire a Client Session that Uses Exclusive Connections] +* link:#How_to_Acquire_a_Client_Session_that_Uses_Connection_Properties[ow +to Acquire a Client Session that Uses Connection Properties] +* link:#How_to_Acquire_a_Client_Session_that_Uses_a_Named_Connection_Pool[How +to Acquire a Client Session that Uses a Named Connection Pool] +* link:#How_to_Acquire_a_Client_Session_that_Does_Not_Use_Lazy_Connection_Allocation[How +to Acquire a Client Session that Does Not Use Lazy Connection +Allocation] + +=== How to Acquire an Isolated Client Session + +If in your EclipseLink project you configure all classes as isolated +(see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Isolation_at_the_Project_Level[Configuring +Cache Isolation at the Project Level]), or one or more classes as +isolated (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]), then all client sessions that +you acquire from a parent server session will be isolated client +sessions (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]). + +Using a `+ConnectionPolicy+`, you can acquire an isolated client session +that uses exclusive connections (see +link:#How_to_Acquire_a_Client_Session_that_Uses_Exclusive_Connections[How +to Acquire a Client Session that Uses Exclusive Connections]). This +isolated client session can be configured with connection properties for +use with the Oracle Virtual Private Database (VPD) feature (see +link:#How_to_Acquire_a_Client_Session_that_Uses_Connection_Properties[How +to Acquire a Client Session that Uses Connection Properties]). +Typically, you use Oracle Database proxy authentication to pass user +credentials to the Oracle Database. For more information about Oracle +Database proxy authentication, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database Proxy Authentication]. + +For more information about VPD, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Isolated +Client Sessions and Oracle Virtual Private Database (VPD)]. + +=== How to Acquire a Client Session that Uses Exclusive Connections + +This example illustrates how to configure a `+ConnectionPolicy+` and use +it to acquire a client session that uses exclusive connections. + +[#Example 86-9]## *_Acquiring a Client Session that Uses Connection +Properties_* + +[source,java] +---- + ConnectionPolicy connectionPolicy = new ConnectionPolicy(); + // Use an exclusive connection for the session + connectionPolicy.setShouldUseExclusiveConnection(true); + + Session clientSession = server.acquireClientSession(connectionPolicy); + // By default, an exclusive connection will be acquired lazily +---- + +An exclusive connection is allocated from a shared connection pool. The +connection is dedicated to the client session that acquires it. + +Note: Typically, the life cycle of a client session is the duration of a +server request. However, if you are using JTA, it is the life cycle of a +JTA transaction. + +You cannot hold the client session across the JTA transaction +boundaries. If you are not using a unit of work in your transaction and +you are configuring a client session to use an exclusive connection (see +Configuring Exclusive Isolated Client Sessions for Virtual Private +Database), you must explicitly acquire and release the session when you +are finished using it. Although client sessions have a finalizer that +would release the session when it is garbage-collected, you must not +rely on the finalizer and release the exclusive client session (or a +non-lazy session) in the application to release the data source +connection. Note that the requirement to release the session is not +JTA-specific. + +If you are using a unit of work (see Using Advanced Unit of Work API), +you do not have to worry about releasing its client session as the unit +of work always automatically releases it at the end of the JTA +transaction. + +A named query can also use an exclusive connection (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Named Query +Advanced Options]). + +For more information, see the following: + +* link:#How_to_Acquire_a_Client_Session_that_Does_Not_Use_Lazy_Connection_Allocation[How +to Acquire a Client Session that Does Not Use Lazy Connection +Allocation] +* link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy] + +=== How to Acquire a Client Session that Uses Connection Properties + +The link:#Example_86-10[Acquiring an Isolated Session Using Connection +Properties] example illustrates how to configure a `+ConnectionPolicy+` +and use it to acquire a client session that uses connection properties. +In this example, the properties are used by the Oracle VPD feature (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Isolated +Client Sessions and Oracle Virtual Private Database (VPD)]). You can use +connection properties for other application purposes. + +[#Example 86-10]## *_Acquiring an Isolated Session Using Connection +Properties_* + +[source,java] +---- + ConnectionPolicy connectionPolicy = new ConnectionPolicy(); + // Set VPD specific properties to be used in the events + connectionPolicy.setProperty("userLevel", new Integer(5)); + + Session clientSession = server.acquireClientSession(connectionPolicy); +---- + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy]. + +=== How to Acquire a Client Session that Uses a Named Connection Pool + +Before you can acquire a client session that uses a named connection +pool, you must configure your session with a named connection pool. For +more information on named connection pools, see +link:Introduction%20to%20Data%20Access%20(ELUG)[Application-Specific +Connection Pools]. For more information on creating a named connection +pool, see +link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)[Introduction +to the Internal Connection Pool Creation]. + +To acquire a client session that uses a named connection pool, use +`+Server+` method `+acquireClientSession+`, passing in a +`+ConnectionPolicy+` configured with the desired connection pool. The +acquired `+ClientSession+` uses connections from the specified pool for +writes (reads still go through the `+Server+` read connection pool). + +This example illustrates how to configure a `+ConnectionPolicy+` to +specify a named connection pool named `+myConnectionPool+`. + +[#Example 86-11]## *_Acquiring a Client Session that Uses a Named +Connection Pool_* + +[source,java] +---- + // Assuming you created a connection pool named "myConnectionPool" + Session clientSession = server.acquireClientSession( + new ConnectionPolicy("myConnectionPool") + ); +---- + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy]. + +=== How to Acquire a Client Session that Does Not Use Lazy Connection Allocation + +By default, the server session does not allocate a data source +connection for a client session until a transaction starts (a lazy data +source connection). Alternatively, you can acquire a client session that +allocates a connection immediately. + +This example illustrates how to configure a `+ConnectionPolicy+` to +specify that lazy connection allocation is not used. + +[#Example 86-12]## *_Acquiring a Client Session that Does Not Use Lazy +Connections_* + +[source,java] +---- + ConnectionPolicy connectionPolicy = new ConnectionPolicy(); + connectionPolicy.setIsLazy(false); + Session clientSession = server.acquireClientSession(connectionPolicy); +---- + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy]. + +== Acquiring a Historical Session + +After you configure EclipseLink to access historical data (see +link:Configuring%20Historical%20Sessions%20(ELUG)#Introduction_to_Historical_Session_Configuration[Introduction +to Historical Session Configuration]), you can query historical data +using any session type. + +When you query historical data using a regular client session or +database session, you must always set `+ObjectLevelReadQuery+` method +`+maintainCache+` to `+false+` in order to prevent old (historical) data +from corrupting the session cache. However, you can query both current +and historical object versions. + +As a convenience, EclipseLink provides a historical session to simplify +this process. When you query historical data using a historical session, +you do not need to set `+ObjectLevelReadQuery+` method `+maintainCache+` +to `+false+`. However, you can query objects only as of the specified +time. + +Before you can acquire a historical session, you must first use the +session manager to acquire a server session. + +To acquire a historical session, use `+Server+` method +`+acquireHistoricalSession+` passing in an `+AsOfClause+`. + +The `+AsOfClause+` specifies a point in time that applies to all queries +and expressions subsequently executed on the historical session. The +historical session’s cache is a read-only snapshot of object versions as +of the specified time. Its cache is isolated from its parent server +session’s shared object cache. + +== Logging In to a Session + +Before you can use a session, you must first log in to the session using +`+Session+` method `+login+`. + +By default, when you load a session using the session manager, +EclipseLink automatically logs in to the session using the zero-argument +`+login+` method. For information on loading a session without +automatically logging into the session, see +link:#How_to_Load_a_Session_Without_Logging_In[How to Load a Session +Without Logging In]. + +If you load a session without logging in, you can choose from the +following signatures of the `+login+` method: + +* `+login()+`: Use the Login, user name, and password defined in the +corresponding `+sessions.xml+` file. +* `+login(Login login)+`: Override the `+Login+` defined in the +corresponding `+sessions.xml+` file with the specified `+Login+`. +* `+login(String username, String password)+`: Override the user name +and password defined in the corresponding `+sessions.xml+` file with the +specified user name and password. + +When you log in to a session broker, the session broker logs in all +contained sessions and initializes the descriptors in the sessions. +After login, the session broker appears and functions as a regular +session. EclipseLink handles the multiple database access transparently. + +== Using Session API + +For more information on using session API, for caching, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +For more information on using session API for queries, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Introduction to +EclipseLink Queries]. + +For more information on using session API for transactions, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. + +== Logging Out of a Session + +When you are finished using a server session, session broker session, or +database session, you must log out of the session using `+Session+` +method `+logout+`. Logging out of a session broker session logs out of +all sessions registered with the session broker. + +When you are finished using a client session, you must release the +session using `+Session+` method `+release+`. + +You can configure a `+Session+` with a finalizer to release the session +using `+Session+` method `+setIsFinalizersEnabled(true)+`. By default, +finalizers are disabled. If you choose to enable a finalizer for a +session, you should do so only as a last resort. We recommend that you +always log out of or release your sessions. + +== Storing Sessions in the Session Manager Instance + +Although we recommend that you export all session instances from the +Workbench to one or more `+sessions.xml+` files, alternatively, you can +manually create a session in your application and, as the +link:#Example_86-13[Storing Sessions Manually in the Session Manager] +example illustrates, manually store it in the session manager using +`+SessionManager+` method `+addSession+`. Then, you can acquire a +session by name using the `+SessionManager+` method `+getSession+`. + +[width="100%",cols="<100%",] +|=== +|*Note*: The `+addSession+` method is not necessary if you are loading +sessions from a session configuration file. +|=== + +[#Example 86-13]## *_Storing Sessions Manually in the Session Manager_* + +[source,java] +---- + // create and log in to the session programmatically + Session theSession = project.createDatabaseSession(); + theSession.login(); + // store the session in the SessionManager instance + SessionManager manager = SessionManager.getManager(); + manager.addSession("mysession", theSession); + // retrieve the session + Session session = SessionManager.getManager().getSession("mysession"); +---- + +== Destroying Sessions in the Session Manager Instance + +You can destroy sessions individually by name or destroy all sessions. + +[width="100%",cols="<100%",] +|=== +|*Note:* You should only do this when a Java EE application is +un-deployed, or when the entire application is shut down and only when +it is known that the session is no longer in use. You should log out of +a session before destroying it (see +link:#Logging_Out_of_a_Session[Logging Out of a Session]). If you do not +log out of a session, the session manager will at the time you use it to +destroy a session. +|=== + +To destroy one session instance by name, use `+SessionManager+` method +`+destroySession+`, as the link:#Example_86-14[Destroying a Session in +the Session Manager] example illustrates. If the specified session is +not in the session manager cache, a `+ValidationException+` is thrown. + +[#Example 86-14]## *_Destroying a Session in the Session Manager_* + +[source,java] +---- + SessionManager manager = SessionManager.getManager(); + Server server = (Server) manager.getSession("myserversession"); + … + // Destroy session by name. If the session named myserversession is not in the + // session manager cache, throw a ValidationException''' + manager.destroySession("myserversession"); +---- + +To destroy all session instances, use the `+SessionManager+` method +`+destoryAllSessions+`, as this example illustrates. + +[#Example 86-15]## *_Destroying All Sessions in the Session Manager_* + +[source,java] +---- + SessionManager manager = SessionManager.getManager(); + Server server = (Server) manager.getSession("myserversession"); + SessionBroker broker = (SessionBroker) manager.getSession("mysessionbroker"); + … + // Destroy all sessions stored in the session manager + manager.destroyAllSessions(); +---- + +> + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:Architecture.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:Architecture.adoc new file mode 100644 index 00000000000..72d5081756d --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:Architecture.adoc @@ -0,0 +1,14 @@ +*image:Elug_draft_icon.png[Warning,title="Warning"] This page is +obsolete. Please see the +_http://www.eclipse.org/eclipselink/documentation/[EclipseLink +Documentation Center]_ for current information.* + +This page lists all sections in the +_link:EclipseLink_UserGuide[EclipseLink User’s Guide 1.x]_, organized by +architecture. + +See +link:Introduction_to_EclipseLink_Application_Development_%28ELUG%29#Selecting_an_Architecture_with_EclipseLink[Selecting +an Architecture with EclipseLink] for more information. + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:DBWS.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:DBWS.adoc new file mode 100644 index 00000000000..c5e980fc4fc --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:DBWS.adoc @@ -0,0 +1,16 @@ +*'`image:Elug_draft_icon.png[Warning,title="Warning"] This page is +obsolete. Please see the +http://www.eclipse.org/eclipselink/documentation/[EclipseLink +Documentation Center]* for current information.`'’’ + +*NOTOC* + +[width="100%",cols="36%,64%",] +|=== +|image:Eclipselink_dbws.png‎[Image:Eclipselink_dbws.png‎,title="Image:Eclipselink_dbws.png‎"] +|This page lists all sections in the +_link:EclipseLink_UserGuide[EclipseLink User’s Guide 1.x]_ for *DBWS* +(Database Web Services) projects. +|=== + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:JPA.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:JPA.adoc new file mode 100644 index 00000000000..72f7e7c4591 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:JPA.adoc @@ -0,0 +1,51 @@ +*'`image:Elug_draft_icon.png[Warning,title="Warning"] This page is +obsolete. Please see the +http://www.eclipse.org/eclipselink/documentation/[EclipseLink +Documentation Center]* for current information.`'’’ + +*NOTOC* + +[width="100%",cols="25%,75%",] +|=== +|image:Eclipselink_jpa.png‎[Image:Eclipselink +jpa.png‎,title="Image:Eclipselink jpa.png‎"] |This page lists all sections +in the _link:EclipseLink_UserGuide[EclipseLink User’s Guide 1.x]_ for +*JPA* (Java Persistence API) projects. You can also use +:Category:ORM[EclipseLink’s Native ORM support] to extend JPA. +|=== + +== Developing Applications using EclipseLink JPA + +== Step 1 + +Define your persistence units in `+persistence.xml+`. + +* link:Introduction_to_Java_Persistence_API_(ELUG)#persistence.xml_File[About +the persistence.xml file] +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)#How_to_Specify_the_Persistence_Unit_Name[Specifying +the persistence unit] + +== Step 2 + +Annotate classes with @Entity, @Embeddable, and @MappedSuperClass and/or +define classes in your mapping file (orm.xml). + +* link:Introduction_to_EclipseLink_JPA_%28ELUG%29#Configuring_an_Entity[Configuring +an entity] +* link:Using_EclipseLink_JPA_Extensions_%28ELUG%29[EclipseLink +extensions] + +== Step 3 + +Configure your application with: + +* javax.persistence.transactionType +* javax.persistence.jtaDataSource +* javax.persistence.nonJtaDataSource + +* link:Developing_Applications_Using_EclipseLink_JPA_%28ELUG%29[Application +development] +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29[Packaging +and deployment] + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:SDO.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:SDO.adoc new file mode 100644 index 00000000000..20e248e6ab6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:SDO.adoc @@ -0,0 +1,37 @@ +*NOTOC* + +[width="100%",cols="36%,64%",] +|=== +|image:Eclipselink_sdo.png‎[Image:Eclipselink +sdo.png‎,title="Image:Eclipselink sdo.png‎"] |This page lists all sections +in the _link:EclipseLink_UserGuide[EclipseLink User’s Guide]_ for *SDO* +(Service Data Objects) projects. +|=== + +== Developing EclipseLink Applications using SDO + +== Step 1 + +Initialize. + +* loadSchema(); + +* Define SDO Types and Properties from an XML Schema + +== Step 2 + +Unmarshall the XML document. + +== Step 3 + +Modify the data objects. + +* augmentDocument + +== Step 4 + +Marshall the data objects. + +* marshallDataObject + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:Status.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:Status.adoc new file mode 100644 index 00000000000..ead23748407 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:Status.adoc @@ -0,0 +1,5 @@ +This page lists all sections in the +_link:EclipseLink_UserGuide[EclipseLink User’s Guide]_, organized by +*status*. + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:Type.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:Type.adoc new file mode 100644 index 00000000000..ade69ea19c1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:Type.adoc @@ -0,0 +1,5 @@ +This page lists all sections in the +_link:EclipseLink_UserGuide[EclipseLink User’s Guide]_, organized by +*information type*. + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Category:XML.adoc b/docs/docs.ug/src/main/asciidoc/core/Category:XML.adoc new file mode 100644 index 00000000000..d33fc3e8768 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Category:XML.adoc @@ -0,0 +1,19 @@ +’’’image:Elug_draft_icon.png[Warning,title="Warning"] This page is +obsolete. + +Please see the +_http://www.eclipse.org/eclipselink/documentation/latest/moxy/toc.htm[Developing +JAXB Applications Using EclipseLink MOXy]_ for current information.’’’ + +''''' + +[width="100%",cols="30%,70%",] +|=== +|image:Eclipselink_moxy.png‎[Image:Eclipselink +moxy.png‎,title="Image:Eclipselink moxy.png‎"] |This page lists all +sections in the _link:EclipseLink_UserGuide[EclipseLink User’s Guide]_ +for *MOXy* (Mapping Objects to XML), with support for Java Architecture +for XML Binding (JAXB). +|=== + +Category:EclipseLink_User's_Guide[Category:EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_Database_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_Database_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..2078cdd6d81 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_Database_Sessions_(ELUG).adoc @@ -0,0 +1,75 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_Database_Sessions_(ELUG)[Related +Topics] + +This table lists the configurable options for database sessions. + +[#Table 91-1]## + +Option + +Workbench + +Java + +Configuring External Connection Pools + +Configuring a Primary Mapping Project + +Configuring a Session Login + +Configuring Logging + +Configuring Multiple Mapping Projects + +Configuring a Performance Profiler + +Configuring an Exception Handler + +Configuring a Session Customizer Class + +Configuring the Server Platform + +Configuring Session Event Listeners + +Configuring a Coordinated Cache + +Configuring the Integrity Checker + +Configuring Named Queries at the Session Level + +== Configuring External Connection Pools + +Unlike a server session, a database session does not provide internal +connection pools. A database session only has a single database +connection that it uses for its life cycle. + +We recommend that you use a server and client session in a three-tier +environment. Alternatively, you can use a database session with an +external connection pool (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]): in this case, you should allocate a new +database session per user/thread or request. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Do not allow the concurrent use of a database session by +multiple users/threads.’’’ +|=== + +The usage of an external connection pool reduces the number of the +database session login and logout attempts to acquire the database +connection. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_Exclusive_Isolated_Client_Sessions_for_Virtual_Private_Database_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_Exclusive_Isolated_Client_Sessions_for_Virtual_Private_Database_(ELUG).adoc new file mode 100644 index 00000000000..50d1f9ccf99 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_Exclusive_Isolated_Client_Sessions_for_Virtual_Private_Database_(ELUG).adoc @@ -0,0 +1,231 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_Exclusive_Isolated_Client_Sessions_for_Virtual_Private_Database_(ELUG)[Related +Topics] + +This table lists the configurable options for isolated sessions. + +[#Table 88-1]## + +Option to Configure + +Workbench + +Java + +Configuring Cache Isolation at the Descriptor Level + +Configuring Connection Policy + +How to Configure Oracle Database Proxy Authentication Using Java + +Using PostAcquireExclusiveConnection Event Handler + +Using PreReleaseExclusiveConnection Event Handler + +Using NoRowsModifiedSessionEvent Event Handler + +Accessing Indirection + +These options are used throughout the isolated session life cycle (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Session_Life_Cycle[Isolated +Client Session Life Cycle]). + +== Using PostAcquireExclusiveConnection Event Handler + +EclipseLink raises this event after an exclusive connection is allocated +to an isolated session after the user has logged in to the database with +it. + +If you are using Oracle Database proxy authentication (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database Proxy Authentication]), then you do not need to implement this +session event handler. + +If you are not using Oracle Database proxy authentication, then, as part +of the isolated session life cycle, you must implement a +`+SessionEventListener+` for +`+SessionEvent.PostAcquireExclusiveConnection+`. + +[width="100%",cols="<100%",] +|=== +|*Note:* You must add this session event listener to the server session +from which you acquire your isolated client session. You cannot add them +to the isolated client session itself. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners] +|=== + +=== How to Use Java + +The `+SessionEvent.PostAcquireExclusiveConnection+` event listener is +your opportunity to authenticate your user and interact with the +underlying database platform: for example, to execute PL/SQL to create +VPD packages and set VPD context information. + +This example illustrates a typical session event listener used to handle +`+postAcquireExclusiveConnection+` events for an isolated session. + +[#Example 88-1]## *_Session Event Listener for an Isolated Session_* + +`+class VPDEventListener extends SessionEventAdaptor{+` +`+    public void postAcquireExclusiveConnection(SessionEvent event){+` +`+        ClientSession session = (ClientSession)event.getSession();+` +`+        +`*`+//\'\' \'\'Get\'\' \'\'property\'\' \'\'set\'\' \'\'on\'\' \'\'the\'\' \'\'ConnectionPolicy\'\' \'\'prior\'\' \'\'to\'\' \'\'acquiring\'\' \'\'the\'\' \'\'connection+`* +`+        String userLevel = session.getConnectionPolicy().getProperty("userLevel");+` +`+        +`*`+//\'\' \'\'Make\'\' \'\'the\'\' \'\'Stored\'\' \'\'Procedure\'\' \'\'call\'\' \'\'for\'\' \'\'VPD\'\' \'\'to\'\' \'\'set\'\' \'\'up\'\' \'\'the\'\' \'\'Context\'\' \'\'Information+`* + +`+        session.executeNonSelectingSQL("StoreProcSetContextUser("+ userLevel + ")");+` +`+    }+` `+}+` + +To get the required user credentials, use `+ClientSession+` method +`+getConnectionPolicy+` to get the associated `+ConnectionPolicy+`, and +then use `+ConnectionPolicy+` method `+getProperty+`. The +`+ConnectionPolicy+` associated with the `+ClientSession+` should +contain all required user credentials (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy]). + +After you implement the required `+SessionEventListener+`, add it to the +parent server session from which you acquire your isolated client +session. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. + +== Using PreReleaseExclusiveConnection Event Handler + +EclipseLink raises a `+SessionEvent.PreReleaseExclusiveConnection+` +event after you call the isolated session method `+release+`. + +If you are using Oracle Database proxy authentication (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database Proxy Authentication]), then you do not need to implement this +session event handler. + +If you are not using Oracle Database proxy authentication, then as part +of the isolated session life cycle, you must implement a +`+SessionEventListener+` for +`+SessionEvent.PreReleaseExclusiveConnection+`. + +[width="100%",cols="<100%",] +|=== +|*Note:* You must add this session event listener to the server session +from which you acquire your isolated client session. You cannot add them +to the isolated client session itself. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners] +|=== + +=== How to Use Java + +The `+SessionEvent.PreReleaseExclusiveConnection+` event listener gives +you an opportunity to interact with the underlying database platform: +for example, to perform any VPD-specific cleanup such as executing +PL/SQL to delete VPD packages or context information. + +This example illustrates a typical session event listener used to handle +`+preReleaseExclusiveConnection+` events for an isolated session. + +[#Example 88-2]## *_Session Event Listener for an Isolated Session_* + +`+class VPDEventListener extends SessionEventAdaptor{+` +`+    public void preReleaseExclusiveConnection(SessionEvent event){+` +`+        Session session event.getSession();+` +`+        +`*`+//\'\' \'\'Make\'\' \'\'the\'\' \'\'Stored\'\' \'\'Procedure\'\' \'\'call\'\' \'\'for\'\' \'\'VPD\'\' \'\'to\'\' \'\'reset\'\' \'\'the\'\' \'\'Context\'\' \'\'Information+`* +`+        session.executeNonSelectingSQL("StoreProcResetContext()");+` +`+    }+` `+}+` + +To get the required user credentials, use `+ClientSession+` method +`+getConnectionPolicy+` to get the associated `+ConnectionPolicy+`, and +then use `+ConnectionPolicy+` method `+getProperty+`. The +`+ConnectionPolicy+` associated with the `+ClientSession+` should +contain all required user credentials (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[Configuring +Connection Policy]). + +After you implement the required `+SessionEventListener+`, add it to the +parent server session, from which you acquire your isolated client +session. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. + +== Using NoRowsModifiedSessionEvent Event Handler + +As part of your general error handling strategy, you should implement a +`+SessionEventListener+` for +`+SessionEvent.NoRowsModifiedSessionEvent+`. + +EclipseLink raises this event when an update or delete query is executed +against the database, but no rows are updated, that is, a zero row count +is returned. + +If optimistic locking is not enabled and you query the database and +violate your VPD security configuration, no exception is thrown: the +query simply returns zero rows updated. + +If optimistic locking is enabled and you query the database and violate +your VPD security configuration, an `+OptimisticLockException+` is +thrown even though the root cause of the failure was a security +violation, not an optimistic locking issue. + +[width="100%",cols="<100%",] +|=== +|*Note:* You must add this session event listener to the server session +from which you acquire your isolated client session. You cannot add them +to the isolated client session itself. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners] +|=== + +=== How to Use Java + +This event listener gives you an opportunity to determine whether the +update failure was due to a security violation (in which case you should +not retry the operation), or due to an optimistic lock issue (in which +case a retry may be appropriate). + +You can use the existing session event API, such as +`+getQuery().getResult()+`, to get the affected object, if any. + +After you implement the required `+SessionEventListener+`, add it to the +parent server session, from which you acquire your isolated client +session. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. + +== Accessing Indirection + +As part of your general error handling strategy, your application should +be prepared to handle a `+ValidationException+` of type +`+ISOLATED_SESSION_IS_NO_LONGER_AVAILABLE+`. + +EclipseLink throws an `+ISOLATED_SESSION_IS_NO_LONGER_AVAILABLE+` when a +client triggers the indirection (lazy loading) on an isolated object +when the isolated session used to load that object is no longer +available, that is, after you call the isolated session method +`+release+`. + +Ensure that you have instantiated every relationship that you need prior +to calling the `+release+` method: to instantiate a one-to-one +relationship, call the `+get+` method; to instantiate a one-to-many +relationship, call the `+size+` method on the collection. + +Fore more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Exception_Handlers[Exception +Handlers] +* link:Configuring%20a%20Session%20(ELUG)#Configuring_an_Exception_Handler[Configuring +an Exception Handler] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_Historical_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_Historical_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..57a86ecbeca --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_Historical_Sessions_(ELUG).adoc @@ -0,0 +1,81 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_Historical_Sessions_(ELUG)[Related +Topics] + +For information on configuring a historical session using an Oracle +Database platform, see +link:#How_to_Configure_Historical_Sessions_Using_an_Oracle_Platform[How +to Configure Historical Sessions Using an Oracle Platform]. + +For information on configuring a historical session using any supported +database platform and a EclipseLink `+HistoryPolicy+`, see +link:#How_to_Configure_Historical_Sessions_Using_a_EclipseLink_HistoryPolicy[How +to Configure Historical Sessions Using a EclipseLink HistoryPolicy]. + +For more information about historical sessions, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical_Sessions[Historical +Sessions]. + +== Introduction to Historical Session Configuration + +There are two following ways to configure EclipseLink to access the +historical versions of objects maintained by your data source: + +* using an Oracle platform (see +link:#How_to_Configure_Historical_Sessions_Using_an_Oracle_Platform[How +to Configure Historical Sessions Using an Oracle Platform]) +* using EclipseLink `+HistoryPolicy+` (see +link:#How_to_Configure_Historical_Sessions_Using_a_EclipseLink_HistoryPolicy[How +to Configure Historical Sessions Using a EclipseLink HistoryPolicy]) + +=== How to Configure Historical Sessions Using an Oracle Platform + +Oracle9__i__ Database Server (or later) automatically maintains +historical versions of objects and extends SQL with an `+AS_OF+` clause +used to query this historical data. Oracle refers to these as flashback +queries. + +If you configure your `+Session+` with an `+OraclePlatform+` (see +link:Configuring%20a%20Database%20Login%20(ELUG)[Configuring a +Relational Database Platform at the Session Level]) for Oracle9__i__ +Database Server (or later), you can query the historical versions of +objects automatically maintained by Oracle Database. + +No further session configuration is required. + +For more information, see the following: + +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Historical_Session[Acquiring +a Historical Session] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Historical_Queries[Historical +Queries]. + +=== How to Configure Historical Sessions Using a EclipseLink HistoryPolicy + +If you use a schema that you designed to maintain historical versions of +objects and if that schema can be described by EclipseLink +`+HistoryPolicy+`, you can query the historical versions of objects +maintained by your database in accordance with your schema. + +For more information, see the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_History_Policy[Configuring +a History Policy] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Historical_Session[Acquiring +a Historical Session] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Historical_Queries[Historical +Queries]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_Server_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_Server_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..10264ff38bc --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_Server_Sessions_(ELUG).adoc @@ -0,0 +1,90 @@ +*TOC* Special:Whatlinkshere_Configuring_Server_Sessions_(ELUG)[Related +Topics] + +This table lists the configurable options for server and client +sessions. + +[#Table 87-1]## + +Option to Configure + +Workbench + +Java + +Configuring Internal Connection Pools + +Configuring a Primary Mapping Project + +Configuring a Session Login + +Configuring Logging + +Configuring External Connection Pools + +Configuring Multiple Mapping Projects + +Configuring a Performance Profiler + +Configuring an Exception Handler + +Configuring a Session Customizer Class + +Configuring the Server Platform + +Configuring Session Event Listeners + +Configuring a Coordinated Cache + +Configuring the Integrity Checker + +Configuring Named Queries at the Session Level + +== Configuring Internal Connection Pools + +An internal connection pool is a collection of reusable connections to a +single data source provided by any session that persists to a data +source. By default, such a session provides both an internal read and +write connection pool. + +In this case, you can do the following: + +* Configure read and write connection pool options such as minimum and +maximum number of connections, alternate connection configuration, and +properties (arbitrary, application-specific named values). +* Create named connection pools for whatever application-specific +purpose you choose. +* Create sequence connection pools that EclipseLink uses exclusively for +obtaining object identifiers. + +For more information about creating and configuring internal connection +pools, see the following: + +* link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)[Creating an +Internal Connection Pool] +* link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)[Configuring +an Internal Connection Pool] + +For more information about configuring the type of connection pool your +session uses, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]. + +== Configuring External Connection Pools + +An external connection pool is a collection of reusable connections to a +single data source provided by a JDBC driver or Java EE container. + +By default, a session uses internal connection pools (see +link:#Configuring_Internal_Connection_Pools[Configuring Internal +Connection Pools]). For more information about configuring a session to +use an external connection pool, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_Session_Broker_and_Client_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_Session_Broker_and_Client_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..b9146a54f8f --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_Session_Broker_and_Client_Sessions_(ELUG).adoc @@ -0,0 +1,86 @@ +*TOC* +Special:Whatlinkshere_Configuring_Session_Broker_and_Client_Sessions_(ELUG)[Related +Topics] + +This table lists the configurable options for session broker sessions. + +[#Table 90-1]## + +Option to Configure + +Workbench + +Java + +Removing, renaming, or adding sessions + +Primary mapping project + +Session login + +Logging + +Multiple mapping projects + +Performance profiler + +Exception handler + +Session customizer class + +Server platform + +Session event listeners + +Coordinated cache + +Integrity checker + +Named queries + +== Removing, Renaming, or Adding Sessions + +You can manage the sessions contained by a session broker with the +Workbench. + +[width="100%",cols="<100%",] +|=== +|*Note*: Add only sessions of the same type to any given session broker. +Do not mix sessions of different types within a session broker. +|=== + +=== How to Use Workbench to Remove, Rename, or Add Sessions + +To add sessions to, remove sessions from, or rename sessions in a +session broker, use this procedure: + +[arabic] +. Select a session broker in the *Navigator*. Its properties appear in +the Editor. +. Click the *General* tab. The General tab appears. +. Click the *Sessions* subtab. The Sessions subtab +appears.[#Figure 90-1]## *_General Tab, Sessions Subtab_* +image:sesbk.gif[General Tab, Sessions +Subtab,title="General Tab, Sessions Subtab"] +. To manage the sessions in this session broker, choose one of the +following: +* To remove a session, select the session in the Sessions tab’s list and +click *Remove*. +* To rename a session, select the session in the Sessions tab’s list and +click *Rename*. The Rename dialog box appears. Enter a new name and +click *OK*. +* To add a session, click *Add Session*. The Sessions dialog box appears +showing a list of all the sessions currently configured in the session +configuration that owns this session broker. [#Figure 90-2]##*’’ +Sessions Dialog Box*’’ image:sesbkadd.gif[Sessions Dialog +Box,title="Sessions Dialog Box"] ++ +Check the sessions in the Session dialog that you want to add to the +session broker and click *OK*. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_CORBA_Coordinated_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_CORBA_Coordinated_Cache_(ELUG).adoc new file mode 100644 index 00000000000..dfb57bbe92e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_CORBA_Coordinated_Cache_(ELUG).adoc @@ -0,0 +1,38 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_CORBA_Coordinated_Cache_(ELUG)[Related +Topics] + +[#Table 102-1]## *_Configurable Options for a CORBA Coordinated Cache_* + +Option to Configure + +EclipseLink Workbench + +Java + +Cache coordination change propagation at the descriptor level + +Synchronous change propagation mode + +Service channel + +Multicast group address + +Multicast port + +Naming service type + +Announcement delay + +Connection handling + +Context properties + +Packet time-to-live + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Coordinated_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Coordinated_Cache_(ELUG).adoc new file mode 100644 index 00000000000..3360296954a --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Coordinated_Cache_(ELUG).adoc @@ -0,0 +1,999 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_a_Coordinated_Cache_(ELUG)[Related +Topics] + +[#Table 99-1]## *_Configuring EclipseLink Coordinated Caches_* + +If you are configuring a… + +See… + +JMS Coordinated Cache + +Configuring a JMS Coordinated Cache + +RMI Coordinated Cache + +Configuring an RMI Coordinated Cache + +CORBA Coordinated Cache + +Configuring a CORBA Coordinated Cache + +Custom Coordinated Cache + +Configuring a Custom Coordinated Cache + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]. + +== Configuring Common Coordinated Cache Options + +This table lists the configurable options shared by two or more +EclipseLink coordinated cache types. In addition, you must configure the +options described for specific +link:Introduction%20to%20Cache%20(ELUG)#Coordinated_Cache_Types[Coordinated +Cache Types], as shown in the link:#Table_99-1[Configuring EclipseLink +Coordinated Caches] table. + +[#Table 99-2]## *_Common Coordinated Cache Options_* + +Option to Configure + +Workbench + +Java + +Cache coordination change propagation at the descriptor level + +Synchronous change propagation mode + +Service channel + +Multicast group address + +Multicast port + +Naming service type + +Announcement delay + +Connection handling + +Context properties + +Packet time-to-live + +== Configuring the Synchronous Change Propagation Mode + +You can configure whether the coordinated cache should propagate object +changes asynchronously or synchronously. + +The following table summarizes which coordinated caches support +propagation mode configuration. + +[#Table 99-3]## *_Coordinated Cache Support for Propagation Mode +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache (asynchronous only) + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +Synchronous propagation mode forces the session to wait for an +acknowledgement before sending the next object change notification: this +reduces the likelihood of stale data at the expense of performance. + +Asynchronous propagation mode allows the session to create separate +threads to propagate changes to remote servers. EclipseLink returns +control to the client immediately after the local commit operation, +whether or not the changes merge successfully on the remote servers. +This offers superior performance for applications that are somewhat +tolerant of stale data. + +For more information, +link:Introduction%20to%20Cache%20(ELUG)#Handling_Stale_Data[Handling +Stale Data]. + +=== How to Configure the Synchronous Change Propagation Mode Using Workbench + +To specify the change propagation mode, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-4[Coordinated Cache Support for Propagation Mode +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Synchronous Field_* image:sesrmisy.gif[Cache +Coordination Tab, Synchronous +Field,title="Cache Coordination Tab, Synchronous Field"] +. Select the *Synchronous* option to use synchronous change propagation. +Do not select this option to use asynchronous change propagation. + +=== How to Configure the Synchronous Change Propagation Mode Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.RemoteCommandManager+` +method `+setShouldPropagateAsynchronously+` to define whether changes +should be propagated synchronously or asynchronously for this +coordinated cache. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring a Service Channel + +The *service channel* is the name of the EclipseLink coordinated cache +channel to which sessions subscribe in order to participate in the same +coordinated cache. Such sessions use the service channel to exchange +messages with each other. Messages sent on other service channels will +not be exchanged with this coordinated cache. + +This table summarizes which coordinated caches support service channel +configuration. + +[#Table 99-4]## *_Coordinated Cache Support for Service Channel +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +=== How to Configure a Service Channel Using Workbench + +To specify the service channel, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-4[Coordinated Cache Support for Service Channel +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Channel Field_* image:cachchannel.gif[Cache +Coordination Tab, Channel +Field,title="Cache Coordination Tab, Channel Field"] +. In the *Channel* field, enter the name of the service channel for this +coordinated cache. + +=== How to Configure a Service Channel Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.RemoteCommandManager+` +method `+setChannel+` to set the name of the service channel for this +coordinated cache. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring a Multicast Group Address + +A multicast group address is an Internet Protocol (IP) address in the +range 224.0.0.0 to 239.255.255.255 that identifies the members of an IP +multicast group. To efficiently broadcast the same message to all +members of an IP multicast group, you configure each recipient with the +same multicast group address and send the message to that address. + +This table summarizes which coordinated caches support multicast group +address configuration. + +[#Table 99-5]## *_Coordinated Cache Support for Multicast Group Address +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +[width="100%",cols="<100%",] +|=== +|*Note:* Ensure your host and network are configured to support +multicast operation before configuring this option. +|=== + +In addition to configuring the multicast group address, you must also +configure the multicast port (see +link:#Configuring_a_Multicast_Port[Configuring a Multicast Port]) for +the coordinated cache types shown in the link:#Table_99-5[Coordinated +Cache Support for Multicast Group Address Configuration] table. + +=== How to Configure a Multicast Group Address Using Workbench + +To specify the multicast group address, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-5[Coordinated Cache Support for Multicast Group Address +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Multicast Group Address Field_* +image:rmiclumg.gif[Cache Coordination Tab, Multicast Group Address +Field,title="Cache Coordination Tab, Multicast Group Address Field"] +. Enter the multicast group address in the range 224.0.0.0 to +239.255.255.255 to subscribe this session to a given coordinated cache. + +=== How to Configure a Multicast Group Address Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.DiscoveryManager+` +method `+setMulticastGroupAddress+` to subscribe this session to a given +coordinated cache. Ensure that the address falls in the range 224.0.0.0 +to 239.255.255.255. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring a Multicast Port + +The multicast port is the port on which multicast messages are received. +Members of a multicast group (see +link:#Configuring_a_Multicast_Group_Address[Configuring a Multicast +Group Address]) rely on messages broadcast to their multicast group +address to communicate with one another. + +This table summarizes which coordinated caches support multicast port +configuration. + +[#Table 99-6]## *_Coordinated Cache Support for Multicast Port +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +[width="100%",cols="<100%",] +|=== +|*Note:* Ensure your host and network are configured to support +multicast operation before configuring this option +|=== + +=== How to Configure a Multicast Port Using Workbench + +To specify the multicast port, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-6[Coordinated Cache Support for Multicast Port +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Multicast Port Field_* +image:rmiclump.gif[Cache Coordination Tab, Multicast Port +Field,title="Cache Coordination Tab, Multicast Port Field"] +. Enter the multicast port on which messages broadcast to the multicast +group address are received. + +=== How to Configure a Multicast Port Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.DiscoveryManager+` +method `+setMulticastPort+` to define the multicast port on which +messages broadcast to the multicast group address are to be received. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring a Naming Service Type + +The session’s message transport service uses a naming service when it +looks up connections to other sessions in the coordinated cache. You can +configure the message transport service to look up remote objects using +an RMI registry or Java Naming and Directory Interface (JNDI). By +default, JNDI is used. + +This table summarizes which coordinated caches support naming service +configuration. + +[#Table 99-7]## *_Coordinated Cache Support for Naming Service +Configuration_* + +Coordinated Cache + +JNDI Naming Service + +RMI Registry Naming Service + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +== Configuring JNDI Naming Service Information + +The session’s message transport service uses a naming service when it +looks up connections to other sessions in the coordinated cache. If you +choose to use a JNDI naming service, you must configure JNDI naming +service information. + +This table summarizes which coordinated caches support JNDI naming +service configuration. + +[#Table 99-8]## *_Coordinated Cache Support for JNDI Naming Service +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +EclipseLink uses JNDI naming service information differently, depending +on the type of coordinated cache. + +For a JMS coordinated cache, when a particular session’s coordinated +cache starts up, it uses its JNDI naming service information to locate +and create a connection to the JMS server. The coordinated cache is +ready when all participating sessions are connected to the JMS server. +At this point, sessions can start sending and receiving object change +messages. You can then configure all sessions that are participating in +the same coordinated cache with the same JNDI naming service +information. + +For an RMI or CORBA coordinated cache, when a particular session’s +coordinated cache starts up, the session binds its connection in JNDI, +creates an announcement message (that includes its own JNDI naming +service information), and broadcasts the announcement to its multicast +group (see link:#Configuring_a_Multicast_Group_Address[Configuring a +Multicast Group Address] and +link:#Configuring_a_Multicast_Port[Configuring a Multicast Port]). When +a session that belongs to the same multicast group receives this +announcement, it uses the JNDI naming service information in the +announcement message to establish bidirectional connections with the +newly announced session’s coordinated cache. The coordinated cache is +ready when all participating sessions are interconnected in this way, at +which point, sessions can start sending and receiving object change +messages. You can then configure each session with JNDI naming +information that identifies the host on which the session is deployed. + +=== How to Configure JNDI Naming Service Information Using Workbench + +To specify the sessions’s JNDI naming service, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-8[Coordinated Cache Support for JNDI Naming Service +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, JNDI Naming Service Options_* +image:jndisrvc.gif[Cache Coordination Tab, JNDI Naming Service +Options,title="Cache Coordination Tab, JNDI Naming Service Options"] +. Complete the Naming Service options. + +Use the following information to enter data in the fields of the Cache +Coordination tab to configure the naming service options: + +Field + +Description + +URL + +The location of the JNDI naming service. + +For a JMS coordinated cache: If you are using the Oracle Containers for +J2EE (OC4J) JNDI naming service and all the hosts in your coordinated +cache can communicate using the OC4J proprietary RMI protocol ORMI, use +a URL similar to the following: + +ormi://: + +where JMS-host-IP is the IP address of the host on which the JMS service +provider is running and JMS-host-port is the port on which the JMS +service provider is listening for JMS requests. + +For an RMI or CORBA coordinated cache: If you are using the OC4J JNDI +naming service and all the hosts in your coordinated cache can +communicate using the OC4J proprietary RMI protocol ORMI on OC4J default +port 23791, use a URL similar to the following: + +ormi://:23791 + +where session-host-IP is the IP address of the host on which this +session is deployed. + +Username + +The user name required to log in to the JNDI naming service. + +The value you enter defines the Context.SECURITY_PRINCIPAL environment +property. + +Password + +The plain text (unencrypted) password required to log in to the JNDI +naming service. + +The password appears in plain text in Workbench, but it is encrypted +when written to the sessions.xml file. + +The value you enter defines the Context.SECURITY_CREDENTIALS environment +property. + +Initial Context Factory + +The name of the factory class, provided by your JNDI naming service +provider, that implements the javax.naming.spi.InitialContextFactory +interface. This factory class is used to create a javax.naming.Context +instance that can access the JNDI naming service provider’s context +implementation. + +The value you enter defines the Context.INITIAL_CONTEXT_FACTORY +environment property. + +Properties + +The JNDI context properties. + +Click Properties to configure custom JNDI context properties (see +Configuring Context Properties). + +=== How to Configure JNDI Naming Service Information Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` +method `+setNamingServiceType+` as follows: + +`+setNamingServiceType(TransportManager.JNDI_NAMING_SERVICE)+` + +Then use the following TransportManager methods to configure the JNDI +naming service options: + +* `+setUserName+`–Set the user name required to log in to the JNDI +naming service. The value you enter defines the +`+Context.SECURITY_PRINCIPAL+` environment property. +* `+setPassword+`–Set the unencrypted password required to log in to the +JNDI naming service. The value you enter defines the +`+Context.SECURITY_CREDENTIALS+` in the cached context properties. +* `+setEncriptedPassword+`–Set the encrypted password required to log in +to the JNDI naming service. The value you enter defines the +`+Context.SECURITY_CREDENTIALS+` in the cached context properties. +* `+setInitialContextFactoryName+`–The name of the factory class, +provided by your JNDI naming service provider, that implements the +`+javax.naming.spi.InitialContextFactory+` interface. This factory class +is used to create a `+javax.naming.Context+` instance that can access +the JNDI naming service provider’s context implementation. The value you +enter defines the `+Context.INITIAL_CONTEXT_FACTORY+` in the cached +context properties. +* `+setLocalContextProperties+`–Set the properties that will be used to +create the initial context for local JNDI access. For more information, +see … + +Do not forget to specify the location of the JNDI naming service by +providing its URL. Consider the following: + +* For a JMS coordinated cache, if you are using the OC4J JNDI naming +service and all the hosts in your coordinated cache can communicate +using the OC4J proprietary RMI protocol ORMI, use a URL similar to the +following: + +`+ormi://+``+:+` + +where `+JMS-host-IP+` is the IP address of the host on which the JMS +service provider is running, and `+JMS-host-port+` is the port on which +the JMS service provider is listening for JMS requests. + +* For an RMI or CORBA coordinated cache, if you are using the OC4J JNDI +naming service and all the hosts in your coordinated cache can +communicate using the OC4J proprietary RMI protocol ORMI on OC4J default +port 23791, use a URL similar to the following: + +`+ormi://+``+:23791+` + +where `+session-host-IP+` is the IP address of the host on which this +session is deployed. + +Note that the default protocol value is "`ormi`", and the default port +value is "`23791`". You can also use the +`+TransportManager.DEFAULT_URL_PROTOCOL+` and `+DEFAULT_URL_PORT+`. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring RMI Registry Naming Service Information + +The session’s message transport service uses a naming service when it +looks up connections to other sessions in the coordinated cache. If you +choose to use an RMI registry naming service, you can configure RMI +registry naming service options. + +This table summarizes which coordinated caches support RMI registry +naming service configuration. + +[#Table 99-9]## *_Coordinated Cache Support for RMI Registry Naming +Service Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java< + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server Cluster 10g Coordinated Cache + +Custom Coordinated Cache + +For an RMI coordinated cache, when a particular session’s coordinated +cache starts up, the session binds its connection in its RMI registry, +creates an announcement message (that includes its own naming service +information), and broadcasts the announcement to its multicast group +(see link:#Configuring_a_Multicast_Group_Address[Configuring a Multicast +Group Address] and link:#Configuring_a_Multicast_Port[Configuring a +Multicast Port]). When a session that belongs to the same multicast +group receives this announcement, it uses the JNDI naming service +information in the announcement message to establish bidirectional +connections with the newly announced session’s coordinated cache. The +coordinated cache is ready when all participating sessions are +interconnected in this way, at which point, sessions can start sending +and receiving object change messages. You can then configure each +session with RMI registry naming information that identifies the host on +which the session is deployed. + +=== How to Configure RMI Registry Naming Service Information Using Workbench + +To specify the sessions’s registry naming service, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor window. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-9[Coordinated Cache Support for RMI Registry Naming +Service Configuration] table). The cache coordination options appear on +the tab. *_Cache Coordination Tab, Naming Service Options_* +image:rmisrvc.gif[Cache Coordination Tab, Naming Service +Options,title="Cache Coordination Tab, Naming Service Options"] +. Complete the Registry Naming Service options. + +Use the following information to configure the naming service options: + +Field + +Description + +URL + +Assuming that you are using the OC4J JNDI naming service and that all +the hosts in your coordinated cache can communicate using the OC4J +proprietary RMI protocol ORMI on OC4J default port 23791, use a URL +similar to the following: + +ormi://:23791 + +where session-host-IP is the IP address of the host on which this +session is deployed. + +=== How to Configure RMI Registry Naming Service Information Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` +method `+setNamingServiceType+` as follows: + +`+setNamingServiceType(TransportManager.REGISTRY_NAMING_SERVICE)+` + +Then specify the location of the JNDI naming service by providing its +URL. Consider the following: + +For an RMI or CORBA coordinated cache, if you are using the OC4J JNDI +naming service and all the hosts in your coordinated cache can +communicate using the OC4J proprietary RMI protocol ORMI on OC4J default +port 23791, use a URL similar to the following: + +`+ormi://+``+:23791+` + +where `+session-host-IP+` is the IP address of the host on which this +session is deployed. + +Note that the default protocol value is "`ormi`", and the default port +value is "`23791`". You can also use the +`+TransportManager.DEFAULT_URL_PROTOCOL+` and `+DEFAULT_URL_PORT+` +contstants. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring an Announcement Delay + +Use the announcement delay option to set the amount of time (in +milliseconds) that a session should wait between the time that it is +available and the time that it broadcasts its announcement message to +the members of the coordinated cache. This additional delay may be +necessary to give some systems more time to post their connections into +the naming service (see +link:#Configuring_a_Naming_Service_Type[Configuring a Naming Service +Type]). + +This table summarizes which coordinated caches support announcement +delay configuration. + +[#Table 99-10]## *_Coordinated Cache Support for Announcement Delay +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +In addition to announcement delay, you may also need to consider packet +time-to-live configuration (see +link:#Configuring_a_Packet_Time-to-Live[Configuring a Packet +Time-to-Live]). + +=== How to Configure an Announcement Delay Using Workbench + +To specify the announcement delay (in milliseconds) for an RMI +coordinated cache, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-10[Coordinated Cache Support for Announcement Delay +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Announcement Delay Field_* +image:rmicluad.gif[Cache Coordination Tab, Announcement Delay +Field,title="Cache Coordination Tab, Announcement Delay Field"] +. Select the amount of time (in milliseconds) that this session should +wait between the time that it is available and the time that it +broadcasts its announcement message to the members of the coordinated +cache. + +See Also: + +link:#Configuring_a_Packet_Time-to-Live[Configuring a Packet +Time-to-Live] + +=== How to Configure an Announcement Delay Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.DiscoveryManager+` +method `+setAnnouncementDelay+` to select the amount of time (in +milliseconds) that this session should wait between the time that it is +available and the time that it broadcasts its announcement message to +the members of the coordinated cache. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring Connection Handling + +The session’s transport manager creates connections to the various +members of the coordinated cache. If a communication error occurs on one +of these connections, you can configure the session to either ignore the +error or remove the connection. + +This table summarizes which coordinated caches support connection +handling configuration. + +[#Table 99-11]## *_Coordinated Cache Support for Connection Handling +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +If you configure the session to remove the connection on error, the next +time the session tries to communicate with that coordinated cache +member, it will construct a new connection. + +If you configure the session to ignore the error, the next time the +session tries to communicate with that coordinated cache member, it will +continue to use the same connection. + +=== How to Configure Connection Handling Using Workbench + +To specify how EclipseLink handles session connections in the event of +an error, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-11[Coordinated Cache Support for Connection Handling +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Remove Connection on Error Option_* +image:clonerr.gif[Cache Coordination Tab, Remove Connection on Error +Option,title="Cache Coordination Tab, Remove Connection on Error Option"] +. Select the *Remove Connection on Error* option to configure the +session to remove the data source connection in the event of an error. + +=== How to Configure Connection Handling Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` +method `+setShouldRemoveConnectionOnError+` to configure the session to +remove the data source connection if an error occurs. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring Context Properties + +When you configure a coordinated cache to use a JNDI naming service (see +link:#Configuring_a_Naming_Service_Type[Configuring a Naming Service +Type]), you can add new environment properties to the environment of the +initial JNDI context. + +This table summarizes which coordinated caches support context +properties. + +[#Table 99-12]## *_Coordinated Cache Support for Context Properties_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache 1 + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +1When JNDI naming service is selected (see +link:#Configuring_a_Naming_Service_Type[Configuring a Naming Service +Type]). Using Workbench, EclipseLink uses the new environment properties +you add to create the initial context for both local and remote JNDI +access. + +Using Java, you can configure different properties for local and remote +JNDI access using a session customizer class to call +`+TransportManager+` methods `+setLocalContextProperties+` and +`+setRemoteContectProperties+` (for more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Customizer_Class[Configuring +a Session Customizer Class]). + +=== How to Configure Context Properties Using Workbench + +To define JNDI context properties, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-12[Coordinated Cache Support for Context Properties] +table). The cache coordination options appear on the tab. +. Ensure the *JNDI Naming Service* option is selected. See +link:#Configuring_a_Naming_Service_Type[Configuring a Naming Service +Type]. +. In the JNDI Naming Service area, click *Properties*. The Edit +Properties dialog box appears. *_Edit Properties Dialog Box_* +image:cachepropdialog.gif[Edit Properties Dialog +Box,title="Edit Properties Dialog Box"] +. Click *Add* to create a new property. The Add New Property dialog box +appears. + +Use this table to enter data in the following fields on the dialog box. + +[cols="<,<",options="header",] +|=== +|*Field* |*Description* +|*Name* |The name of the property. +|*Value* |The value of the property. +|=== + +To change (or delete) an existing property, select the property and +click *Edit* (or *Remove*). + +=== How to Configure Context Properties Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` +method `+setLocalContextProperties+` to define a `+Hashtable+` of the +JNDI context properties that will be used to create the initial context +for the local JNDI access. Note that the "`dedicated.connection`" is the +default key with the default value of "`true`". + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +== Configuring a Packet Time-to-Live + +The *packet time-to-live* is the number of hops that session data +*packets* can take before expiring. The default is 2. This allows for a +*hub* and an interface card, and prevents the data packets from leaving +the local network. If sessions are hosted on different local area +networks (LANs) that are part of wide area network (WAN), or if a +firewall configuration prevents it, the announcement sent by one session +may not reach the other sessions in the coordinated cache. In this case, +consult your network administrator for the correct time-to-live value. + +This table summarizes which coordinated caches support packet +time-to-live configuration. + +[#Table 99-13]## *_Coordinated Cache Support for Packet Time-to-Live +Configuration_* + +Coordinated Cache + +Using Workbench + +Using Java + +JMS Coordinated Cache + +RMI Coordinated Cache + +CORBA Coordinated Cache + +Oracle Application Server 10g Cluster Coordinated Cache + +Custom Coordinated Cache + +In addition to configuring packet time-to-live, you may also need to +configure announcement delay (see +link:#Configuring_an_Announcement_Delay[Configuring an Announcement +Delay]). + +=== How to Configure a Packet Time-to-Live Using Workbench + +To specify the number of hops that session data packets can take before +expiring, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (see the +link:#Table_99-12[Coordinated Cache Support for Packet Time-to-Live +Configuration] table). The cache coordination options appear on the tab. +*_Cache Coordination Tab, Packet Time to Live Field_* +image:rmipacket.gif[DCache Coordination Tab, Packet Time to Live +Field,title="DCache Coordination Tab, Packet Time to Live Field"] +. In the *Packet Time to Live* field, specify the number of hops +(default = `+2+`) that session data packets can take before expiring. + +=== How to Configure a Packet Time-to-Live Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.DiscoveryManager+` +method `+setPacketTimeToLive+` to specify the number of hops (default = +2) that session data packets can take before expiring. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination_API[Cache +Coordination API]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Custom_Coordinated_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Custom_Coordinated_Cache_(ELUG).adoc new file mode 100644 index 00000000000..2f22d79c9a7 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Custom_Coordinated_Cache_(ELUG).adoc @@ -0,0 +1,66 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Custom_Coordinated_Cache_(ELUG)[Related +Topics] + +[#Table 103-1]## *_Configurable Options for a Custom Coordinated Cache_* + +Option to Configure + +Workbench + +Java + +Configuring cache coordination change propagation at the descriptor +level + +Configuring a service channel + +Configuring transport class + +Configuring connection handling + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Custom_Coordinated_Cache[Custom +Coordinated Cache]. + +== Configuring Transport Class + +To configure a custom coordinated cache, you must specify your custom +instance of +`+org.eclipse.persistence.sessions.coordination.TransportManager+`. + +=== How to Configure Transport Class Using Workbench + +To select the transport class for the user defined coordinated cache, +use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected and the +*Type* is *User Defined* (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]). [#Figure 103-1]##*_Cache Coordination, Transport Class +Option_* image:chcusttr.gif[Cache Coordination, Transport Class +Option,title="Cache Coordination, Transport Class Option"] +. Click *Browse* and select the transport class for the user-defined +coordinated cache. + +=== How to Configure Transport Class Using Java + +Create a custom instance of the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` that +you use as a transport class for your coordinated cache. + +You obtain the `+TransportManager+` using the following `+Session+` API: + +`+Session.getCommandManager().getTransportManager()+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Data_Source_Login_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Data_Source_Login_(ELUG).adoc new file mode 100644 index 00000000000..9948e128e9c --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Data_Source_Login_(ELUG).adoc @@ -0,0 +1,392 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_a_Data_Source_Login_(ELUG)[Related +Topics] + +This table lists the types of EclipseLink data source logins that you +can configure, and provides a cross-reference to the type-specific +section that lists the configurable options supported by that type. + +[#Table 93-1]## *_Configuring EclipseLink Data Source Logins_* + +[width="100%",cols="<50%,<50%",options="header",] +|=== +|*If you are configuring a…* |*See…* +|link:Introduction%20to%20Data%20Access%20(ELUG)#DatabaseLogin[DatabaseLogin] +|link:Configuring%20a%20Database%20Login%20(ELUG)[Configuring a Database +Login] + +|link:Introduction%20to%20Data%20Access%20(ELUG)#EISLogin[EISLogin] +|link:Configuring%20an%20EIS%20Login%20(ELUG)#[Configuring an EIS Login] +|=== + +When using the `+sessions.xml+` file to configure login information, +EclipseLink will override any login information in the `+project.xml+` +and instead use the information from the `+sessions.xml+` configuration. + +For more information, see the following: + +* link:Introduction%20to%20Data%20Access%20(ELUG)#Introduction_to_Data_Access[Introduction +to Data Access] +* link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level] + +== Configuring Common Data Source Login Options + +The following table lists the configurable options shared by two or more +EclipseLink data source login types. In addition to the configurable +options described here, you must also configure the options described +for the specific data source login types (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Login_Types[Data +Source Login Types]), as shown in the link:#Table_93-1[Configuring +EclipseLink Data Source Logins] table. + +[#Table 93-2]## *_Common Data Source Login Options_* + +[width="99%",cols="<57%,<23%,<20%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_User_Name_and_Password[User name and password] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Password_Encryption[Password encryption] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_External_Connection_Pooling[Configuring external +connection pooling] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Properties[Configuring properties] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_a_Default_Null_Value_at_the_Login_Level[Default null +value at the login level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Configuring User Name and Password + +Optionally, you can specify the user name and password of a login. + +We recommend that you do not save the password with a deployment login. + +If you specify a password, using an EclipseLink tool or Java, enter the +plain text (not encrypted) value. EclipseLink will encrypt the password +using JCE encryption. + +By default, EclipseLink writes passwords to and read passwords from the +`+sessions.xml+` file in encrypted form using JCE encryption. + +By default, EclipseLink does not write passwords to and read passwords +from the `+project.xml+` file unless you configure your project-level +data source login accordingly. When you configure EclipseLink to write +passwords and read passwords from the `+project.xml+` file, by default, +it does so in encrypted form using JCE encryption. + +For more information, see the following: + +* link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level] +* link:#Configuring_Password_Encryption[Configuring Password Encryption] + +=== How to Configure User Name and Password Using Workbench + +To specify a user name and password, use this procedure: + +[arabic] +. Select a server or database session in the *Navigator*. Its properties +appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. +[#Figure 93-1]##*_Login Tab, Connection Subtab, User Name and Password +Fields_* image:unpwlog.gif[Login Tab, Connection Subtab, User Name and +Password +Fields,title="Login Tab, Connection Subtab, User Name and Password Fields"] +. Enter a user name and password in plain text (not encrypted). + +== Configuring Password Encryption + +By default, EclipseLink writes passwords to and read passwords from the +`+sessions.xml+` file in encrypted form using JCE encryption. + +By default, EclipseLink does not write passwords to and read passwords +from the `+project.xml+` file unless you configure your project-level +data source login accordingly. When you configure EclipseLink to write +passwords and read passwords from the `+project.xml+` file, by default, +it does so in encrypted form using JCE encryption. + +You can implement your own encryption class and configure your session +`+DatasourceLogin+` to use it. + +Currently, the Workbench does not support specifying the encryption +class used. To change the encryption class used, you must modify the +login in Java. + +For more information, see the following: + +* link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level] +* link:#Configuring_User_Name_and_Password[Configuring User Name and +Password] + +=== How to Configure Password Encryption Using Java + +To configure a password encryption class, follow this procedure: + +[arabic] +. Create your encryption class. Your encryption class must implement the +`+org.eclipse.persistence.internal.security.Securable+` interface, as +this example shows. ++ +[#Example 93-1]## *_Custom Encryption Class Implementing Securable_* ++ +`+import org.eclipse.persistence.internal.security.Securable;+` + +`+public class MyEncryptor implements Securable {+` + +`+    public String encryptPassword(String pswd) {+` `+    ...+` +`+    }+` + +`+    public String decryptPassword(String encryptedPswd) {+` +`+    ...+` `+    }+` `+}+` +. Create a session event listener class for the `+preLogin+` event that +calls `+DatasourceLogin+` method `+setEncryptionClassName+` to configure +your session with your encryption class. Use the `+SessionEventAdapter+` +to simplify your session event listener, as this examle shows. ++ +[#Example 93-2]## *_Specifying a Custom Encryption Class in a Session +Event Listener_* ++ +`+import org.eclipse.persistence.tools.sessionconfiguration.SessionEventAdapter;+` +`+import org.eclipse.persistence.sessions.SessionEvent;+` +`+import org.eclipse.persistence.sessions.Session;+` +`+import org.eclipse.persistence.sessions.DatasourceLogin;+` + +`+public class MySessionEventListener extends SessionEventAdapter {+` + +`+    public void preLogin(SessionEvent event) {+` +`+        Session session = event.getSession();+` +`+        DatasourceLogin login = session.getDatasourceLogin();+` +`+        login.setEncryptionClassName(MyEncryptor.class.getName());+` +`+    }+` `+}+` +. Associate your session event listener class with your session. For +more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. + +== Configuring External Connection Pooling + +For non-Java EE applications, you typically use +link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools] provided by EclipseLink. In this case, you can use +Workbench to configure connection pool options and to create a sequence +connection pool and application-specific (named) connection pools. + +For Java EE applications, you typically use +link:Introduction%20to%20Data%20Access%20(ELUG)#External_Connection_Pools[External +Connection Pools] provided by a JDBC driver or Java EE container. +Optionally, you can configure a read connection pool to use a +nontransactional login, and you can configure a sequence connection pool +to use a separate (preferably nontransactional) login of its own. + +Because JTA external transaction controllers are dependent upon the +external transaction service that the application server provides, you +must configure EclipseLink to use external connection pools if you are +using an external transaction controller (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]). + +External connection pools enable your EclipseLink application to do the +following: + +* Integrate into a Java EE-enabled system. +* Integrate with JTA transactions (JTA transactions require a +JTA-enabled data source). +* Leverage a shared connection pool in which multiple applications use +the same data source. +* Use a data source configured and managed directly on the server. + +For more information about connection pools, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[Connection +Pools]. + +=== How to Configure External Connection Pooling Using Workbench + +To specify if the session login uses external connection pooling, use +this procedure: + +[arabic] +. Configure a data source on the application server. If you are using +the external connection pool with an external transaction controller +(see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]), be sure to configure a JTA-enabled data source. +For more information, see your Java EE container documentation. +. Select a server or database session in the *Navigator*. Its properties +appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. *_Login +Tab, Connection Subtab, External Connection Pooling Field, Database +Driver_* image:ecpdblog.gif[Login Tab, Connection Subtab, External +Connection Pooling Field, Database +Driver,title="Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver"] ++ +*** Connection Tab, External Connection Pooling Field, Java EE Data +Source*** image:ecpj2log.gif[Connection Tab, External Connection Pooling +Field, Java EE Data +Source,title="Connection Tab, External Connection Pooling Field, Java EE Data Source"] +. Select the External Connection Pooling option. For a database driver, +external connection pooling is optional. For a Java EE data source, +external connection pooling is mandatory. Specify if this login uses +External Connection Pooling. For a database driver, external connection +pooling is optional. For a Java EE data source, external connection +pooling is mandatory. + +=== How to Configure External Connection Pooling Using Java + +To configure the use of an external connection pool in Java, do the +following: + +[arabic] +. Configure the data source on the application server. If you are using +the external connection pool with an external transaction controller +(see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]), be sure to configure a JTA-enabled data source. +For more information, see your Java EE container documentation. +. Configure the `+DatasourceLogin+` to specify the data source and to +use an external connection pool by using the +`+useExternalConnectionPooling+` method. + +== Configuring Properties + +For all `+DatasourceLogin+` types, you can specify custom named values, +called properties. Some data sources require additional, driver-specific +properties not supported in the `+DatasourceLogin+` API (for example, +see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Optimize_JDBC_Driver_Properties[How +to Optimize JDBC Driver Properties]). Add these properties to the +`+DatasourceLogin+` so that EclipseLink can pass them to the driver. + +For relational sessions, you must first enable advanced option *Use +Properties* (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Advanced_Options[Configuring +Advanced Options]). + +For EIS sessions, properties are always enabled. + +[width="100%",cols="<100%",] +|=== +|*Note:* Do not set a password as a property. Always use the Workbench +or `+DatabaseLogin+` method `+setPassword+`. For more information on +configuring a password, see +link:#Configuring_User_Name_and_Password[Configuring User Name and +Password]. +|=== + +When using Workbench, you can only set character values, which +EclipseLink returns as `+String+` objects (see +link:#How_to_Configure_Properties_Using_Workbench[How to Configure +Properties Using Workbench]). + +When using Java, you can set any `+Object+` value (see +link:#How_to_Configure_Properties_Using_Java[How to Configure Properties +Using Java]). + +=== How to Configure Properties Using Workbench + +To specify arbitrary named value pairs that EclipseLink associates with +a `+DatasourceLogin+`, use this procedure: + +[arabic] +. Select a server or database session in the *Navigator*. Its properties +appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. If necessary, enable support for properties: +* for relational sessions, you must first enable advanced option *Use +Properties* (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Advanced_Options[Configuring +Advanced Options]); +* for EIS sessions, properties are always enabled. +. Click the *Properties* subtab. The Properties subtab appears. *_Login +Tab, Properties Subtab_* image:sesprop.gif[Login Tab, Properties +Subtab,title="Login Tab, Properties Subtab"] +. You can add, edit, or remove properties using Add Property dialog box. +. To add (or change) a new *Name*/*Value* property, click *Add* (or +*Edit*). Add Property dialog box appears. + +Use the following information to add or edit a login property on the Add +Property dialog box: + +[width="100%",cols="<6%,<94%",options="header",] +|=== +|*Option* |*Description* +|*Name* |The name by which EclipseLink retrieves the property value +using the `+DatasourceLogin+` method `+getProperty+`. + +|*Value* |The value EclipseLink retrieves using the `+DatasourceLogin+` +method `+getProperty+` passing in the corresponding property name. Using +Workbench, you can set only character values that EclipseLink returns as +`+String+` objects. +|=== + +To delete an existing property, select the *Name*/*Value* row and click +*Remove*. + +=== How to Configure Properties Using Java + +Using Java, you can set any `+Object+` value using `+DatasourceLogin+` +method `+setProperty+`. To remove a property, use `+DatasourceLogin+` +method `+removeProperty+`. + +== Configuring a Default Null Value at the Login Level + +A default null value is the Java `+Object+` type and value that +EclipseLink uses instead of `+null+` when EclipseLink reads a `+null+` +value from a data source. + +When you configure a default null value at the login level, it applies +to all mappings used in a session. In this case, EclipseLink uses it to +translate in one direction only: when EclipseLink reads `+null+` from +the data source, it converts this `+null+` to the specified type and +value. + +You can also use EclipseLink to set a default null value on a +per-mapping basis (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Default_Null_Value_at_the_Mapping_Level[Configuring +a Default Null Value at the Mapping Level]). + +[width="100%",cols="<100%",] +|=== +|*Note*: A default null value must be an `+Object+`. To specify a +primitive value (such as `+int+`), you must use the corresponding +`+Object+` wrapper (such as `+Integer+`). +|=== + +=== How to Configure a Default Null Value at the Login Level Using Java + +Using Java API, you can configure a default null value for all mappings +used in a session with the `+DatabaseLogin+` method +`+setDefaultNullValue(Class,Object)+`. + +For example: + +*`+//\'\' \'\'Defaults\'\' \'\'all\'\' \'\'null\'\' \'\'String\'\' \'\'values\'\' \'\'read\'\' \'\'from\'\' \'\'the\'\' \'\'database\'\' \'\'to\'\' \'\'empty\'\' \'\'String+`* +`+session.getLogin().setDefaultNullValue(String.class, "");+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Database_Login_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Database_Login_(ELUG).adoc new file mode 100644 index 00000000000..8670d07b412 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Database_Login_(ELUG).adoc @@ -0,0 +1,921 @@ +*TOC* Special:Whatlinkshere_Configuring_a_Database_Login_(ELUG)[Related +Topics] + +In a relational database project, EclipseLink retrieves the table +information from the database, for each descriptor. Each Workbench +project contains an associated database. You can create multiple logins +for each database. + +The following table lists the configurable options for a database login. + +[#Table 94-1]## + +[width="100%",cols="<62%,<20%,<18%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_a_Relational_Database_Platform_at_the_Session_Level[Relational +database platform at the session level] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Database_Login_Connection_Options[Database login +connection options] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Sequencing_at_the_Session_Level[Sequencing at the +session level] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_JDBC_Options[JDBC options] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_User_Name_and_Password[User +name and password] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_a_Table_Qualifier[Table qualifier] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Advanced_Options[Advanced options] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Password_Encryption[Password +encryption] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[External +connection pooling] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Properties] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Oracle_Database_Proxy_Authentication[Oracle Database +proxy authentication] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Configuring a Relational Database Platform at the Session Level + +For each database session, you must specify the database platform (such +as Oracle9__i__ Database Server). This platform configuration overrides +the platform at the project level, if configured. + +For more information, see the following: + +* link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level] +* link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types] + +=== How to Configure a Relational Database Platform at the Session Level Using Workbench + +To specify the database platform options for a relational server (or +database) session login, use this procedure: + +[arabic] +. Select a relational server (or database) session in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. +[#Figure 94-1]##*_Login Tab, Connection Subtab, Database Platform +Option_* image:dplalog.gif[Login Tab, Connection Subtab, Database +Platform +Option,title="Login Tab, Connection Subtab, Database Platform Option"] +. Select the database platform from the menu of options. This menu +includes all instances of `+DatabasePlatform+` in the EclipseLink +classpath. + +== Configuring Database Login Connection Options + +You configure connection information at the session level for your +EclipseLink application. This information is stored in the +`+sessions.xml+` file. The EclipseLink runtime uses this information +whenever you perform a persistence operation using the session in your +application. + +This connection configuration overrides the connection information at +the project level, if configured. For more information about +project-level configuration, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins]. + +This connection configuration is overridden by the connection +information at the connection pool level. For more information, see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring_Connection_Pool_Connection_Options[Configuring +Connection Pool Connection Options]. + +=== How to Configure Database Login Connection Options Using Workbench + +To specify the connection options for a relational server (or database) +session login, use this procedure: + +[arabic] +. Select a relational server (or database) session in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. *_Login +Tab, Connection Subtab, Database Driver_* image:dbconn.gif[Login Tab, +Connection Subtab, Database +Driver,title="Login Tab, Connection Subtab, Database Driver"] *_Login +Tab, Connection Subtab_* image:j2cconn.gif[Login Tab, Connection +Subtab,title="Login Tab, Connection Subtab"] +. Complete each field on the Connection subtab. + +Use the following information to enter data in the driver fields on the +tab: + +Field + +Description + +Database Driver + +Specify the appropriate database driver: + +Driver Manager: specify this option to configure the driver class and +URL used to connect to the database. In this case, you must configure +the Driver Class and Driver URL fields. + +J2EE Data Source: specify this option to use a Java EE data source +already configured on your target application server. In this case, you +must configure the Datasource Name field. + +Note: If you select J2EE Datasource, you must use external connection +pooling. You cannot use internal connection pools with this Database +Driver option (for more information, see Configuring External Connection +Pooling). + +Driver Class 1 + +Configure this field when Database Driver is set to Driver Manager. +Select from the menu of options. This menu includes all JDBC drivers in +the EclipseLink classpath. + +Driver URL 1 + +Configure this field when Database Driver is set to Driver Manager. +Select from the menu of options relevant to the selected Driver Class, +and edit the URL to suit your data source. + +Data Source Name 2 + +Configure this field when Database Driver is set to J2EE Datasource. +Specify any valid JNDI name that identifies the Java EE data source +preconfigured on your target application server (example: +jdbc/EmployeeDB). + +By convention, all such names should resolve to the JDBC subcontext +(relative to the standard java:comp/env naming context that is the root +of all provided resource factories). + +Lookup Type2 + +Configure this field when Database Driver is set to J2EE Datasource. +Specify the lookup method for determining the JNDI name: + +Composite Name + +Compound Name + +String + +1Applicable only when *Database Driver* is set to *Driver Manager*. +2Applicable only when *Database Driver* is set to *J2EE Datasource*. + +== Configuring Sequencing at the Session Level + +You configure EclipseLink sequencing at the session or project level to +tell EclipseLink how to obtain sequence values: that is, what type of +sequences to use. + +You can configure a session directly by using a session-level sequence +configuration to override project-level sequence configuration, on a +session-by-session basis, if required. + +Using Workbench (see +link:#How_to_Configure_Sequencing_at_the_Session_Level_Using_Workbench[How +to Configure Sequencing at the Session Level Using Workbench]), you can +configure table sequencing (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing]) and native sequencing +(link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] and +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform]), and you can configure +a preallocation size that applies to all sequences (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_and_Preallocation_Size[Sequencing +and Preallocation Size]). + +Using Java (see +link:#How_to_Configure_Sequencing_at_the_Session_Level_Using_Java[How to +Configure Sequencing at the Session Level Using Java]), you can +configure any sequence type that EclipseLink supports ( +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_Types[Sequencing +Types]). You can create any number and combination of sequences. You can +create a sequence object explicitly or use the default sequence that the +platform creates. You can associate the same sequence with more than one +descriptor and you can configure a separate preallocation size for each +descriptor’s sequence. + +If you are migrating a WebLogic CMP application to OC4J and EclipseLink +persistence, after migration, you must manually configure your project +to use EclipseLink unary sequence tables if your application originally +used single-column sequence tables in WebLogic. + +After configuring the sequence type at the session (or project) level, +to enable sequencing, you must configure a descriptor with a sequence +field and a sequence name (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]). + +For more information about sequencing, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_in_Relational_Projects[Sequencing +in Relational Projects]. + +=== How to Configure Sequencing at the Session Level Using Workbench + +To specify the sequencing information for a relational server (or +database) session, use this procedure: + +[arabic] +. Select the session object in the *Navigator*. +. Click the *Login* tab in the *Editor*. +. Click the *Sequencing* subtab. The Sequencing subtab appears. +[#Figure 94-4]##*_Login Tab, Sequencing Subtab_* +image:sequence.gif[Login Tab, Sequencing +Subtab,title="Login Tab, Sequencing Subtab"] +. Complete each field on Login–Sequencing subtab. + +Use the following information to enter data in each field of the +Sequencing subtab to configure the persistence type: + +[width="100%",cols="<5%,<95%",options="header",] +|=== +|*Field* |*Description* +|*Preallocation Size* |Select the +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_and_Preallocation_Size[default +preallocation size]. Default is *50*. The preallocation size you +configure applies to all sequences. + +|*Default Sequence Table* |Select this option to use +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[table +sequencing] with default sequence table name `+SEQUENCE+`, default +sequence name field `+SEQ_NAME+`, and default sequence count field +`+SEQ_COUNT+`. + +|*Native Sequencing* |Select this option to use a sequencing object (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] or +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform]) created by the database +platform. This option applies to supported database platforms (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms]). + +|*Custom Sequence Table* |Select this option to use +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[table +sequencing] with a sequence table name, sequence name field, and +sequence count field name that you specify. + +|*Name* |Select the name of the sequence table. + +|*Name Field* |Select the name of the column used to store the sequence +name. + +|*Counter Field* |Select the name of the column used to store the +sequence count. +|=== + +=== How to Configure Sequencing at the Session Level Using Java + +Using Java, you can perform the following sequence configurations: + +* link:#Using_the_Platform_Default_Sequence[Platform Default Sequence] +* link:#Configuring_Multiple_Sequences[Multiple Sequences] +* link:#Configuring_Query_Sequencing[Query Sequencing] + +==== Using the Platform Default Sequence + +After you configure your login with a platform (see +link:#Configuring_a_Relational_Database_Platform_at_the_Session_Level[Configuring +a Relational Database Platform at the Session Level]), you can use the +default sequence that the platform provides. + +If you associate a descriptor with an unspecified sequence, the +EclipseLink runtime will create an instance of `+DefaultSequence+` to +provide sequencing for that descriptor. For more information, see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_the_Platform_Default_Sequence[Configuring +the Platform Default Sequence]. + +You can access the default platform sequence directly as the +link:#Example_94-1[Accessing the Platform Default Sequence] example +shows. For example, by default, a `+DatabasePlatform+` creates a table +sequence using the default table and column names (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing]). + +[#Example 94-1]## *_Accessing the Platform Default Sequence_* + +*`+//\'\' \'\'assume\'\' \'\'that\'\' \'\'dbLogin\'\' \'\'owns\'\' \'\'a\'\' \'\'DatabasePlatform+`* +`+TableSequence tableSeq2 = ((TableSequence)dbLogin.getDefaultSequence()).clone();+` +`+tableSeq2.setName("EMP_SEQ");+` +`+tableSeq2.setPreallocationSize(75);+` +`+dbLogin.addSequence(tableSeq2);+` + +To avoid having to clone the platform default sequence, you can use the +`+DefaultSequence+` class– a wrapper for the platform default +sequence–-as the following example shows. The new sequence named +`+EMP_SEQ+` will be of the same type as the platform default sequence. + +[#Example 94-2]## *_Using the DefaultSequence Class_* + +`+login.addSequence(new DefaultSequence("EMP_SEQ", 75));+` + +You can override the default platform sequence, as the +link:#Example_94-3[Overriding the Platform Default Sequence] example +shows. In this example, `+dbLogin+` owns a `+DatabasePlatform+` that +provides a default sequence of type `+TableSequence+`. After setting the +default sequence to type `+UnaryTableSequence+`, when you use the +`+DefaultSequence+` class, it will access the new default sequence type. +In this example, the sequence named `+EMP_SEQ+` will be of type +`+UnaryTableSequence+` and have a preallocation size of 75. + +[#Example 94-3]## *_Overriding the Platform Default Sequence_* + +*`+//\'\' \'\'assume\'\' \'\'that\'\' \'\'dbLogin\'\' \'\'owns\'\' \'\'a\'\' \'\'DatabasePlatform+`* +`+Sequence unaryTableSequence = new UnaryTableSequence();+` +`+unaryTableSequence.setPreallocationSize(40);+` +`+dbLogin.setDefaultSequence(unaryTableSequence);+` +`+dbLogin.addSequence(+` +`+    new DefaultSequence("EMP_SEQ", 75) +`*`+//\'\' \'\'UnaryTableSequence+`* +`+);+` + +==== Configuring Multiple Sequences + +In addition to using the platform default sequence (see +link:#Using_the_Platform_Default_Sequence[Using the Platform Default +Sequence]), you can explicitly create sequence instances and configure a +`+Login+` with any combination of sequence types, each with their own +preallocation size, as the link:#Example_94-4[Configuring Multiple +Sequences Explicitly] example shows. In this example, the sequence named +`+EMP_SEQ+` will provide sequence values exclusively for instances of +the `+Employee+` class and `+ADD_SEQ+` will provide sequence values +exclusively for instances of the `+Address+` class. The sequence named +`+PHONE_SEQ+` will use the platform default sequence with a +preallocation size of 30 to provide sequence values for the `+Phone+` +class. + +[#Example 94-4]## *_Configuring Multiple Sequences Explicitly_* + +`+login.addSequence(new TableSequence("EMP_SEQ", 25));+` +`+login.addSequence(new DefaultSequence("PHONE_SEQ", 30));+` +`+login.addSequence(new UnaryTableSequence("ADD_SEQ", 55));+` +`+login.addSequence(new NativeSequence("NAT_SEQ", 10));+` + +If login owned a `+DatabasePlatform+` (whose default sequence type is +`+TableSequence+`), you could configure your sequences using the +platform default sequence type, as the link:#Example_94-5[Configuring +Multiple Sequences Using the Default Sequence Type] example shows. In +this example, sequences `+EMP_SEQ+` and `+PHONE_SEQ+` share the same +`+TableSequence+` table: `+EMP_SEQ+` and `+PHONE_SEQ+` represent rows in +this table. + +[#Example 94-5]## *_Configuring Multiple Sequences Using the Default +Sequence Type_* + +`+login.addSequence(new DefaultSequence("EMP_SEQ", 25));+` +`+login.addSequence(new DefaultSequence("PHONE_SEQ", 30));+` +`+login.addSequence(new UnaryTableSequence("ADD_SEQ", 55));+` +`+login.addSequence(new NativeSequence("NAT_SEQ", 10));+` + +==== Configuring Query Sequencing + +You can configure the query that EclipseLink uses to update or read a +sequence value for any sequence type that extends `+QuerySequence+`. + +In most applications, the queries that EclipseLink automatically uses +are sufficient. However, if your application has special sequencing +needs–-for example, if you want to use stored procedures for +sequencing–-then you can configure the update and read queries that the +EclipseLink sequence uses. + +The following example illustrates how to specify a stored procedure that +updates a sequence and returns the new sequence value with a single SQL +select query. In this example, the stored procedure is named +`+UPDATE_SEQ+`. It contains one input argument–-the name of the sequence +to update (`+SEQ_NAME+`), and one output argument–-the value of the +sequence after the updated (`+SEQ_COUNT+`). The stored procedure +increments the sequence value associated with the sequence named +`+SEQ_NAME+` and returns the new sequence value in the output argument +named `+SEQ_COUNT+`. + +[#Example 94-6]## *_Using a Stored Procedure for both Sequence Update +and Select_* + +`+ValueReadQuery seqReadQuery = new ValueReadQuery();+` +`+StoredProcedureCall spCall = new StoredProcedureCall();+` +`+spCall.setProcedureName("UPDATE_SEQ");+` +`+seqReadQuery.addNamedArgument("SEQ_NAME");+` +`+seqReadQuery.addNamedOutputArgument("SEQ_COUNT");+` +`+seqReadQuery.setCall(spCall);+` +`+((QuerySequence)login.getDefaultSequence()).setSelectQuery(seqReadQuery);+` + +link:#Example_94-7[Using a Stored Procedure for Sequence Updates Only] +and link:#Example_94-8[Using a Stored Procedure for Sequence Selects +Only] examples illustrate how to specify separate stored procedures for +sequence update and select actions. + +In the link:#Example_94-7[Using a Stored Procedure for Sequence Updates +Only] example, the stored procedure is named UPDATE_SEQ, and it contains +one input argument–the name of the sequence to update (`+SEQ_NAME+`). +The stored procedure increments the sequence value associated with the +sequence named `+SEQ_NAME+`. + +[#Example 94-7]## *_Using a Stored Procedure for Sequence Updates Only_* + +`+DataModifyQuery seqUpdateQuery = new DataModifyQuery();+` +`+StoredProcedureCall spCall = new StoredProcedureCall();+` +`+spCall.setProcedureName("UPDATE_SEQ");+` +`+seqUpdateQuery.addNamedArgument("SEQ_NAME");+` +`+seqUpdateQuery.setCall(spCall);+` +`+((QuerySequence)login.getDefaultSequence()).setUpdateQuery(seqUpdateQuery);+` + +In the link:#Example_94-8[Using a Stored Procedure for Sequence Selects +Only] example, the stored procedure is named `+SELECT_SEQ+` and it takes +one argument: the name of the sequence to select from (`+SEQ_NAME+`). +The stored procedure reads one data value: the current sequence value +associated with the sequence name `+SEQ_NAME+`. + +[#Example 94-8]## *_Using a Stored Procedure for Sequence Selects Only_* + +`+ValueReadQuery seqReadQuery = new ValueReadQuery();+` +`+StoredProcedureCall spCall = new StoredProcedureCall();+` +`+spCall.setProcedureName("SELECT_SEQ");+` +`+seqReadQuery.addArgument("SEQ_NAME");+` +`+seqReadQuery.setCall(spCall);+` +`+login.((QuerySequence)getDefaultSequence()).setSelectQuery(seqReadQuery)+` + +You can also create a `+QuerySequence+` directly and add it to your +login, as this example shows. + +[#Example 94-9]## *_Using the QuerySequence Class_* + +*`+//\'\' \'\'Use\'\' \'\'the\'\' \'\'two-argument\'\' \'\'constructor:\'\' \'\'pass\'\' \'\'in\'\' \'\'sequence\'\' \'\'name\'\' \'\'and\'\' \'\'preallocation\'\' \'\'size.+`* +*`+//\'\' \'\'Alternatively,\'\' \'\'you\'\' \'\'can\'\' \'\'use\'\' \'\'zero-\'\' \'\'or\'\' \'\'one-argument\'\' \'\'(sequence\'\' \'\'name)\'\' \'\'constructor+`* +`+login.addSequence(new QuerySequence("SEQ1", 75));+` + +== Configuring a Table Qualifier + +Some databases (such as Oracle Database and DB2) require that all tables +be qualified by an identifier. This can be the creator of the table or +database name on which the table exists. When you specify a table +qualifier, EclipseLink uses this qualifier for all of the tables it +references. Specify a table qualifier only if required and only if all +of the tables have the same qualifier. + +=== How to Configure a Table Qualifier Using Workbench + +To specify a table qualifier, use this procedure: + +[arabic] +. Select a relational server (or database) session in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Options* subtab. The Options subtab +appears.[#Figure 94-5]## *_Login Tab, Options Subtab, Table Qualifier +Field_* image:sesopttc.gif[Login Tab, Options Subtab, Table Qualifier +Field,title="Login Tab, Options Subtab, Table Qualifier Field"] + +In the *Table Qualifier* field enter the identifier used to qualify +references to all tables in this database. + +=== How to Configure a Table Qualifier Using Workbench + +To set the default qualifier for all tables, use the +`+org.eclipse.persistence.sessions.DatabaseLogin+` method +`+setTableQualifier+`. + +== Configuring JDBC Options + +Most JDBC drivers support the run-time configuration of various options +to customize driver operation to meet user needs. EclipseLink provides +direct support (in API and the Workbench) for many of the most important +options, as this section describes, as well as more advanced options +(see link:#Configuring_Advanced_Options[Configuring Advanced Options]). + +You can also configure additional options by specifying properties (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Configuring +Properties]). + +[width="100%",cols="<100%",] +|=== +|*Note:* Not all drivers support all JDBC options. Selecting a +combination of options may result in different behavior from one driver +to another. Before selecting JDBC options, consult your JDBC driver +documentation. +|=== + +=== How to Configure JDBC Options Using Workbench + +To specify the JDBC options for a relational server (or database) +session login, use this procedure: + +[arabic] +. Select a relational server (or database) session in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Options* subtab. The Options subtab appears. +[#Figure 94-6]##*_Login Tab, Options Subtab, JDBC Options_* +image:jdbcopt.gif[Login Tab, Options Subtab, JDBC +Options,title="Login Tab, Options Subtab, JDBC Options"] +. Complete the JDBC fields on the tab. + +Use this table to enter data in the fields on the Options subtab to +select the JDBC options to use with this session login: + +Option + +Description + +Queries Should Bind All Parameters1 + +By default, EclipseLink binds all of the query’s parameters. + +Deselect this option if you do not want EclipseLink to bind parameters. + +Cache All Statements1 + +When selected, EclipseLink caches each prepared statement so that when +reexecuted, you avoid the SQL preparation time which improves +performance. + +Byte Array Binding1 + +Select this option if you query binary large object (BLOB) data. + +Streams for Binding1 + +Select this option if you use a JDBC driver that is more efficient at +handling BLOB data using java.io.InputStream and java.io.OutputStream. + +Native SQL + +By default, EclipseLink generates SQL using JDBC SQL grammar. Select +this option if you want EclipseLink to use database-specific SQL +grammar, for example, if your database driver does not support the full +JDBC SQL grammar. + +Batch Writing2 + +Select this option if you use a JDBC driver that supports sending groups +of INSERT, UPDATE, and DELETE statements to the database in a single +transaction, rather than individually. + +Select JDBC to use the batch writing capabilities of your JDBC driver. + +Select EclipseLink to use the batch writing capabilities that +EclipseLink provides. Select this option if your JDBC driver does not +support batch writing. + +Note: if you are using Oracle 9 Database platform, and you want to use +EclipseLink batch writing in combination with optimistic locking, then +you must enable parameter binding. + +String Binding1 + +Select this option if you query large java.lang.String objects. + +You can configure the maximum String length (default: 32000 characters). + +1For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. 2If you are using the `+MySQLPlatform+` +database platform (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types]), use *JDBC* batch writing (do not use +*EclipseLink* batch writing). For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Batch_Writing_for_Optimization[How +to Use Batch Writing for Optimization]. + +=== How to Configure JDBC Options Using Java + +To enable prepared statement caching for all queries, configure at the +`+Login+` level, as the following example shows. For more information, +see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. + +[#Example 94-10]## *_Prepared Statement Caching at the Login Level_* + +`+databaseLogin.cacheAllStatements();+` +`+databaseLogin.setStatementCacheSize(100);+` + +Parameter binding is enabled by default in EclipseLink. To disable +binding, configure at the `+Login+` level, as the following example +shows. For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. + +[#Example 94-11]## *_Disabling Parameter Binding at the Login Level_* + +`+databaseLogin.dontBindAllParameters();+` + +To enable JDBC batch writing, use `+Login+` method `+useBatchWriting+`, +as this example shows: + +[#Example 94-12]## *_Using JDBC Batch Writing_* + +`+project.getLogin().useBatchWriting();+` +`+project.getLogin().setMaxBatchWritingSize(100);+` + +== Configuring Advanced Options + +Most JDBC drivers support the run-time configuration of various options +to customize driver operation to meet user needs. EclipseLink provides +direct support (in API and Workbench) for many of the most important +options (see link:#Configuring_JDBC_Options[Configuring JDBC Options]), +as well as more advanced options, as this section describes. + +You can also configure additional options by specifying properties (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Configuring +Properties]). + +[width="100%",cols="<100%",] +|=== +|*Note:* Not all drivers support all JDBC options. Selecting a +combination of options may result in different behavior from one driver +to another. Before selecting JDBC options, consult your JDBC driver +documentation. +|=== + +=== How to Configure Advanced Options Using Workbench + +To specify the advanced options for a relational server (or database) +session login, use this procedure: + +[arabic] +. Select a relational server (or database) session in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Options* subtab. The Options subtab appears. +[#Figure 94-7]##*_Login Tab, Options Subtab, Advanced Options_* +image:sesadvopt.gif[Login Tab, Options Subtab, Advanced +Options,title="Login Tab, Options Subtab, Advanced Options"] +. Complete the Advanced Options fields on the tab. + +Use this table to enter data in the fields on the Options subtab to +select the advanced options to use with this session login: + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Option* |*Description* +|*Force Field Names to Uppercase* |By default, EclipseLink uses the case +of field names as returned by the database. If your application expects +field names to be uppercase but the database does not return consistent +case (for example, if you accessing different databases), enable this +option. + +|*Optimize Data Conversion* |By default, EclipseLink optimizes data +access by accessing the data from JDBC in the format the application +requires. If you are using an older JDBC driver that does not perform +data conversion correctly and conflicts with this optimization, disable +this optimization. + +|*Trim String* |By default, EclipseLink discards the trailing blanks +from `+CHAR+` field values. To read and write `+CHAR+` field values +literally (including any trailing blanks), disable this option. + +|*Properties* |Check this option to enable the use of properties for +this `+DatabaseLogin+` (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Configuring +Properties]). +|=== + +=== How to Configure Advanced Options Using Java + +Use the following methods of +`+org.eclipse.persistence.sessions.DatabaseLogin+` to configure advanced +options: + +* `+setShouldForceFieldNamesToUpperCase+`–By default, EclipseLink uses +the case of field names as returned by the database. If your application +expects field names to be uppercase but the database does not return +consistent case (for example, if you accessing different databases), use +this method. +* `+setShouldOptimizeDataConversion+`–By default, EclipseLink optimizes +data access by accessing the data from JDBC in the format the +application requires. If you are using an older JDBC driver that does +not perform data conversion correctly and conflicts with this +optimization, set this to `+false+`. +* `+setShouldTrimStrings+`–By default, EclipseLink discards the trailing +blanks from `+CHAR+` field values. To read and write `+CHAR+` field +values literally (including any trailing blanks), set this to `+false+`. +* `+setProperties+`–Set this to true to enable the use of properties for +this `+DatabaseLogin+` (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Configuring +Properties]). + +== Configuring Oracle Database Proxy Authentication + +You can configure a session to use Oracle Database proxy authentication +with an Oracle Database platform in JSE applications and JEE +applications using Oracle JDBC driver release 10.1.0.2.0 or later. If an +external connection pool is used, then it should either contain Oracle +connections directly (`+OracleDataSource+`), or the application server +should allow access to the underlying vendor-specific connection in the +managed connection. To achieve the latter, the server platform class in +Eclipselink needs to implement the `+java.sql.Connection+` method +`+unwrapConnection(java.sql.Connection connection)+`. + +There is no Workbench support for this feature. To configure EclipseLink +to use Oracle Database proxy authentication, you must use Java (see +link:#How_to_Configure_Oracle_Database_Proxy_Authentication_Using_Java[How +to Configure Oracle Database Proxy Authentication Using Java]). + +For more information, see +link:Configuring%20a%20EclipseLink%20JPA%20%20Application%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database Proxy Authentication]. + +For information on proxy authentication in JPA applications, see +link:Configuring%20a%20EclipseLink%20JPA%20Application%20(ELUG)#Configuring_Oracle_Database_Proxy_Authentication_for_a_JPA_Application[Configuring +Oracle Database Proxy Authentication for a JPA Application]. + +You can use EclipseLink support for Oracle Database proxy authentication +by doing the following: + +* link:#Providing_Authenticated_Reads_and_Writes_of_Secured_Data_Through_the_Use_of_an_Exclusive_Isolated_Client_Session[Providing +Authenticated Reads and Writes of Secured Data Through the Use of an +Exclusive Isolated Client Session] +* link:#Providing_Authenticated_Writes_for_Database_Auditing_Purposes_with_a_Client_Session[Providing +Authenticated Writes for Database Auditing Purposes with a Client +Session] +* link:#Providing_Authenticated_Reads_and_Writes_with_a_Database_Session[Providing +Authenticated Reads and Writes with a Database Session] + +*Providing Authenticated Reads and Writes of Secured Data Through the +Use of an Exclusive Isolated Client Session* + +In this configuration, the client session is an isolated client session +(see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]) that uses an exclusive proxy connection. You must +acquire the client session using properties that specify proxy +authentication user credentials. Reads and writes of secured data are +performed through the proxy-authenticated connection. Reads of +nonsecured data occur through nonproxy-authenticated connections. + +If you are using Oracle Private Virtual Database (VPD) (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Isolated +Client Sessions and Oracle Virtual Private Database (VPD)]), use this +configuration to set up VPD support entirely in the database. That is, +rather than making the isolated client session execute SQL (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PostAcquireExclusiveConnection_Event_Handler[Using +PostAcquireExclusiveConnection Event Handler] and +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PreReleaseExclusiveConnection_Event_Handler[Using +PreReleaseExclusiveConnection Event Handler]), the database performs the +required set up in an after login trigger using the proxy +`+session_user+`. + +*Providing Authenticated Writes for Database Auditing Purposes with a +Client Session* + +In this configuration, isolated data or exclusive connections are not +required. You must acquire the client session using properties that +specify the proxy authentication user credentials. + +Writes are performed through the proxy-authenticated connection. Reads +occur through nonproxy-authenticated connections. This enables the +database auditing process to access the user that performed the write +operations. + +*Providing Authenticated Reads and Writes with a Database Session* + +In this configuration, you use a `+DatabaseSession+` with proxy +properties. + +Note: We recommend that you exclusively use server and client sessions +in a three-tier environment. + +Do not use database sessions in a three-tier environment. Ensure that a +database session is used by a single user and not accessed concurrently. + +=== How to Configure Oracle Database Proxy Authentication Using Java + +To configure EclipseLink to use Oracle Database proxy authentication, do +the following: + +[arabic] +. Decide on the proxy type you want to use and create appropriate users +and roles. +[arabic] +.. User Name Authentication: To authenticate a proxy user `+sarah+` by +user name only, create the user account on the Oracle Database using the +following: ++ +`+alter user sarah grant connect through dbadminuser+` +`+    with roles clerk, reports;+` ++ +In this case, you will need to set the proxy properties shown in this +table. [#Table 94-2]## ++ +*_Proxy Properties for User Name Authentication_* ++ +[width="100%",cols="<50%,<50%",options="header",] +|=== +|*Property Name* |*Property Value* +|`+"eclipselink.oracle.proxy-type"+` |`+PROXYTYPE_USER_NAME+` +|`+PROXY_USER_NAME+` |`+"sarah"+` +|`+PROXY_ROLES+` |`+String[] {"role1", "role2", ...}+` +|=== +.. User Name and Password Authentication: To authenticate a proxy user +`+sarah+` by user name and password, create the user account on the +Oracle Database using the following: ++ +`+alter user sarah grant connect through dbadminuser+` +`+    authenticated using password+` `+    with roles clerk, reports;+` ++ +In this case, you will need to set the proxy properties shown in this +table. [#Table 94-3]## ++ +*_Proxy Properties for User Name and Password Authentication_* ++ +[width="100%",cols="<50%,<50%",options="header",] +|=== +|*Property Name* |*Property Value* +|`+"eclipselink.oracle.proxy-type"+` |`+PROXYTYPE_USER_NAME+` +|`+PROXY_USER_NAME+` |`+"sarah"+` +|`+PROXY_PASSWORD+` |`+"passwordforsarah"+` +|`+PROXY_ROLES+` |`+String[] {"role1", "role2", ...}+` +|=== +.. Distinguished Name Authentication: To authenticate a proxy user +`+sarah+` by globally unique distinguished name, create the user account +on the Oracle Database using the following: +`+create user sarah identified globally as+` ++ +`+    'CN=sarah,OU=americas,O=oracle,L=city,ST=ca,C=us';+` +`+alter user sarah grant connect through dbadminuser+` +`+    authenticated using distinguished name+` +`+    with roles clerk, reports;+` ++ +In this case, you will need to set the proxy properties shown in this +table. [#Table 94-4]## ++ +*_Proxy Properties for Distinguished Name Authentication_* ++ +[width="100%",cols="<40%,<60%",options="header",] +|=== +|*Property Name* |*Property Value* +|`+"eclipselink.oracle.proxy-type"+` |`+PROXYTYPE_DISTINGUISHED_NAME+` + +|`+PROXY_DISTINGUISHED_NAME+` +|`+"CN=sarah,OU=americas,O=oracle,L=city,ST=ca,C=us"+` + +|`+PROXY_ROLES+` |`+String[] {"role1", "role2", ...}+` +|=== +.. Certificate Authentication: To authenticate a proxy user `+sarah+` by +encrypted distinguished name, create the user account on the Oracle +Database using the following: ++ +`+alter user sarah grant connect through dbadminuser+` +`+    authenticated using certificate+` +`+    with roles clerk, reports;+` ++ +In this case, you will need to set the proxy properties shown in this +table. [#Table 94-5]## ++ +*_Proxy Properties for User Name Authentication_* ++ +[width="100%",cols="<48%,<52%",options="header",] +|=== +|*Property Name* |*Property Value* +|`+"eclipselink.oracle.proxy-type"+` |`+PROXYTYPE_CERTIFICATE+` +|`+PROXY_CERTIFICATE+` |`+byte[] {+`_`+EncryptedCertificate+`_`+}+` +|`+PROXY_ROLES+` |`+String[] {"role1", "role2", ...}+` +|=== +. [#SessionCustomizer-config]####Configure your session login using Java +code. Do this through a `+SessionCustomizer+`. ++ +*`+//\'\' \'\'If\'\' \'\'using\'\' \'\'Oracle\'\' \'\'VPD\'\' \'\'support,set\'\' \'\'the\'\' \'\'connection\'\' \'\'policy\'\' \'\'to\'\' \'\'exclusive+`*`+ +` +`+policy.setShouldUseExclusiveConnection(true);+` +. Acquire a proxy-authenticated session using properties that specify +the user credentials: ++ +`+Session session = server.acquireClientSession();+` +`+session.setProperty("eclipselink.oracle.proxy-type", OracleConnection.PROXYTYPE_USER_NAME);+` +`+session.setProperty(oracle.jdbc.OracleConnection.PROXY_USER_NAME, "sarah");+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..fa22cc111c4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Descriptor_(ELUG).adoc @@ -0,0 +1,4687 @@ +*TOC* Special:Whatlinkshere_Configuring_a_Descriptor_(ELUG)[Related +Topics] + +This section describes how to configure EclipseLink project options +common to two or more project types. + +The following table lists the types of EclipseLink descriptors that you +can configure and provides a cross-reference to the type-specific +chapter that lists the configurable options supported by that type. + +[#Table 115-1]## + +If you are creating… + +See… + +Relational Descriptors + +Configuring a Relational Descriptor + +Object-Relational Data Type Descriptors + +Configuring an Object-Relational Data Type Descriptor + +EIS Descriptor Concepts + +Configuring an EIS Descriptor + +XML Descriptor Concepts + +Configuring an XML Descriptor + +The link:#Table_115-2[Common Descriptor Options] table lists the +configurable options shared by two or more EclipseLink descriptor types. + +For more information, see: + +* link:Creating%20a%20Descriptor%20(ELUG)[Introduction to Descriptor +Creation] +* link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] + +== Configuring Common Descriptor Options + +This table lists the configurable options shared by two or more +EclipseLink descriptor types. In addition to the configurable options +described here, you must also configure the options described for the +specific +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Types[Descriptor +Types], as shown in the link:#Table_115-1[Configuring EclipseLink +Descriptor] table. + +[#Table 115-2]## + +Option to Configure + +EclipseLink Workbench + +Java + +Primary keys + +Read-only + +Unit of work conforming + +Alias + +Comments + +Classes + +Named queries + +Query timeout + +Cache refreshing + +Query keys + +Interface query keys + +Cache type and size + +Cache isolation + +Unit of work cache isolation + +Cache coordination change propagation + +Cache expiration + +Cache existence checking + +Reading subclasses on queries + +Inheritance for a child class descriptor + +Inheritance for a parent class descriptor + +Inheritance expressions for a parent class descriptor + +Inherited attribute mapping in a subclass + +Domain object method as an event handler + +Descriptor event listener as an event handler + +Locking policy + +Returning policy + +Instantiation policy + +Copy policy + +Change policy + +History policy + +Wrapper policy + +Fetch groups + +Amendment methods + +Mappings + +== Configuring Primary Keys + +A *primary key* is a unique identifier (made up of one or more +persistent attributes) that distinguishes one instance of a class from +all other instances of the same type. You use primary keys to define +relationships and to define queries. + +For the descriptors shown in the link:#Table_115-3[Descriptor Support +for Primary Keys] table, you must configure a primary key and you must +ensure that your class contains one or more persistent fields suitable +for this purpose. + +This table summarizes which descriptors support primary keys. + +[#Table 115-3]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +class descriptors] only. 2 +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +root descriptors] only. For a relational class (non-aggregate) +descriptor, choose any unique database field or set of unique database +fields from the descriptor’s +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[associated +table]. + +For an +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[EIS +root descriptor], choose any unique attribute or text node or set of +unique attributes or text nodes from +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Schema_Context_for_an_EIS_Descriptor[the +descriptor’s schema context]. + +=== How to Configure Primary Keys Using Workbench + +To associate a descriptor with one or more primary keys, use this +procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Primary Key Options_* +image:desinpk.gif[Descriptor Info Tab, Primary Key +Options,title="Descriptor Info Tab, Primary Key Options"] +. Complete the Primary Keys options on the tab. + +Use this table to enter data in Primary Keys field on the descriptor’s +*Descriptor Info* tab to specify the primary key(s): + +Field + +Description + +Primary Keys + +To specify the primary keys for the table, click Add in order to do the +following: + +For a relational class descriptor, select a database field from the +descriptor’s associated table. + +For an EIS root descriptor, select an attribute or text node from the +descriptor’s schema context. For more information on choosing an element +or attribute, see Choosing a Schema Context. + +To remove a primary key, select the key and click Remove. + +=== How to Configure Primary Keys Using Java + +You can use Java to configure primary keys for the following: + +* link:#Relational_Projects[Relational Projects] +* link:#EIS_Projects[EIS Projects] + +==== Relational Projects + +Use `+ClassDescriptor+` method `+addPrimaryKeyFieldName+` to specify the +primary key field of the descriptor’s table. This should be called for +each field that makes up the primary key of the table. + +If the descriptor has more than one table, and all other tables have the +same primary key, use the `+ClassDescriptor+` method +`+addPrimaryKeyFieldName+` to specify the the primary key in the first +table. + +If the descriptor has more than one table, and each table has a +different primary key, use `+ClassDescriptor+` method +`+addForeignKeyFieldNameForMultipleTable+` to map the source foreign key +field name to target primary key field name. + +==== EIS Projects + +Use `+EISDescriptor+` method `+addPrimaryKeyFieldName+` to specify the +primary key field of the descriptor’s class. Call this method for each +field that makes up the primary key. + +== Configuring Read-Only Descriptors + +You can configure a relational class or EIS root descriptor as +read-only. This indicates that instances of the reference class will +never be modified. + +Read-only descriptors are usually used within a unit of work as a +performance gain, because there is no need to register, clone, and merge +the read-only classes. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. + +This table summarizes which descriptors support read-only configuration. + +[#Table 115-4]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptor 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +class descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +root descriptors] only. + +[width="100%",cols="<100%",] +|=== +|*Note:* Relational aggregate and EIS composite descriptors get their +read-only setting from their owner. +|=== + +=== How to Configure Read-Only Descriptors Using Workbench + +To configure a descriptor as read-only use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +[#Figure 115-2]##*_Descriptor Info Tab, Read Only Option_* +image:desread.gif[Descriptor Info Tab, Read Only +Option,title="Descriptor Info Tab, Read Only Option"] +. Select the *Read-Only* option on the tab. Specify whether this +descriptor is read-only or not. + +*See Also* + +link:#Configuring_Read-Only_Descriptors[Configuring Read-Only +Descriptors] + +link:#Configuring_a_Descriptor[Configuring a Descriptor] + +=== How to Configure Read-Only Descriptors Using Java + +Use `+ClassDescriptor+` method `+setReadOnly+`. + +== Configuring Unit of Work Conforming at the Descriptor Level + +Conforming is a query feature that lets you include new, changed, or +deleted objects in queries within a unit of work prior to committing the +transaction. This feature enables you to query against your relative +logical or transaction view of a data source. + +This table summarizes which descriptors support descriptor level unit of +work conforming. + +[#Table 115-5]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. When you configure a descriptor to conform +results in a unit of work, when you execute a query in the unit of work, +EclipseLink filters the data source result set to the changes currently +made in the unit of work. EclipseLink adds new or changed objects that +correspond to the query’s selection criteria and removes changed objects +that no longer correspond to the query’s selection criteria. + +[width="100%",cols="<100%",] +|=== +|*Note:* For EIS root descriptors, only deleted objects would be +filtered, not new or changed objects. +|=== + +Conforming can reduce performance. Before you enable a descriptor for +conforming, be aware of its limitations (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_Conforming[How +to Use Conforming]) and make sure that conforming is actually necessary. + +For examples, see the following: + +* link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Conforming_Queries_and_Descriptors[Using +Conforming Queries and Descriptors] +* link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#What_You_May_Need_to_Know_About_Conforming_Query_Alternatives[What +You May Need to Know About Conforming Query Alternatives] + +=== How to Configure Unit of Work Conforming at the Descriptor Level Using Workbench + +To conform a descriptor’s results in a unit of work, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Conform Results in Unit of Work Option_* +image:desconform.gif[Descriptor Info Tab, Conform Results in Unit of +Work +Option,title="Descriptor Info Tab, Conform Results in Unit of Work Option"] +. Select the Conform Results in Unit of Work option on the tab. + +Enable or disable conforming: when enabled, this feature ensures that +any queries for this descriptor will conform the data source result with +the current changes in the unit of work. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_Conforming[How +to Use Conforming]. + +*See Also* + +link:#Configuring_Unit_of_Work_Conforming_at_the_Descriptor_Level[Configuring +Unit of Work Conforming at the Descriptor Level] + +link:#Configuring_a_Descriptor[Configuring a Descriptor] + +=== How to Configure Unit of Work Conforming at the Descriptor Level Using Java + +Use `+ClassDescriptor+` method +`+setShouldAlwaysConformResultsInUnitOfWork(true)+`. + +== Configuring Descriptor Alias + +This table summarizes which descriptors support descriptor alias +configuration. + +[#Table 115-6]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors 1 + +XML Descriptors + +1link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. + +[width="100%",cols="<100%",] +|=== +|*Note:* The alias is also used in JPA – it is the entity name. This is +the logical name referenced in JP QL queries. It defaults to the class +name without a path information. For more information, see +link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)[Introduction +to Java Persistence API] +|=== + +=== How to Configure Descriptor Alias Using Workbench + +To specify a descriptor alias, use this procedure: + +[arabic] +. In the *Navigator*, select a descriptor. +. Click the *Descriptor Info* tab in the Property window. *_Descriptor +Info Tab, Descriptor Alias Field_* image:desalias.gif[Descriptor Info +Tab, Descriptor Alias +Field,title="Descriptor Info Tab, Descriptor Alias Field"] +. In the *Descriptor Alias* field, enter an alias for this descriptor. +The default is the class name. + +=== How to Configure Descriptor Alias Using Java + +Use `+ClassDescriptor+` method `+setAlias+` passing in the descriptor +alias as a `+String+`. The descriptor alias defaults to the class name. + +== Configuring Descriptor Comments + +You can define a free-form textual comment for each descriptor. You can +use these comments however you whish: for example, to record important +project implementation details such as the purpose or importance of a +descriptor. + +Comments are stored in the Workbench project, in the EclipseLink +deployment XML file. There is no Java API for this feature. + +This table summarizes which descriptors support descriptor comment +configuration. + +[#Table 115-7]## + +Descriptor + +Using the Workbench + +How to Use Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +=== How to Configure Descriptor Comments Using Workbench + +To create a comment for a descriptor, use this procedure: + +[arabic] +. In the *Navigator*, select a descriptor. +. Click the *Descriptor Info* tab in the Property window. *_Descriptor +Info Tab, Comment Field_* image:descomment.gif[Descriptor Info Tab, +Comment Field,title="Descriptor Info Tab, Comment Field"] +. In the *Comment* field, enter a description of this descriptor. + +== Configuring Named Queries at the Descriptor Level + +A named query is an EclipseLink query that you create and store, by +name, in a descriptor’s `+DescriptorQueryManager+` for later retrieval +and execution. Named queries improve application performance because +they are prepared once and they (and all their associated supporting +objects) can be efficiently reused thereafter making them well suited +for frequently executed operations. + +If a named query is global to a `+Class+`, configure it at the +descriptor level. Alternatively, you can +link:Configuring%20a%20Session%20(ELUG)#Configuring_Named_Queries_at_the_Session_Level[configure +a named query at the session level]. + +Use named queries to specify SQL or EclipseLink `+Expression+` queries +to access your data source. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can use named queries in JPA (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Extensions_for_Stored_Procedure_Query[Using +EclipseLink JPA Extensions for Stored Procedure Query]). Because the +scope of JPA named queries is global to the session, ensure that each +named query has a unique name. +|=== + +link:#How_to_Configure_Named_Queries_at_the_Descriptor_Level_Using_Workbench[Using +the Workbench], you can configure named queries for a subset of query +types and store them in a descriptor’s `+DescriptorQueryManager+`. + +link:#How_to_Configure_Named_Queries_at_the_Descriptor_Level_Using_Java[Using +Java], you can create named queries for all query types and store them +in a descriptor’s `+DescriptorQueryManager+`. + +This table summarizes which descriptors support named query +configuration. + +[#Table 115-8]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors1 + +Object-Relational Data Type Descriptors + +EIS Descriptor2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. After you create a named query, you can execute +it by name and class on the EclipseLink session (see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_Named_Queries[Using +Named Queries]). + +For more information about named queries, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries]. + +=== How to Configure Named Queries at the Descriptor Level Using Workbench + +To create a named query, use this procedure + +[arabic] +. In the *Navigator*, select a descriptor. Its properties appear in the +Editor. +. Click the *Queries* tab in the *Editor*. The Queries tab appear with +three additional tabs. +. Click the *Named Queries* tab in the Queries tab. The Named Queries +tab appears. *_Queries Tab – Named Queries Subtab_* +image:qrnmdfnd.gif[Queries Tab – Named Queries +Subtab,title="Queries Tab – Named Queries Subtab"] +. Complete each field on the Named Queries tab. + +Use the following information to complete each field on this tab: + +Field + +Description + +Queries + +Lists the existing queries for this descriptor. + +To create a new query, click Add. + +To delete an existing query, select the query and click Delete. +Workbench prompts for confirmation. + +To rename an existing query, select the query and click Rename. The +Rename dialog box appears. Type a new name for the query and click OK. + +Query Variety + +Displays the variety of the currently selected query (see Adding Named +Queries). + +Quick View + +Lists the parameters and joined attributes defined for the query. +Clicking on a heading in the Quick View area selects the corresponding +subtab. You can also remove parameters or attributes from the Quick View +area by selecting the item and clicking Remove. + +The Named Queries tab includes the following subtabs: + +* *General* – See +link:#Configuring_Named_Query_Type_and_Parameters[Configuring Named +Query Type and Parameters]. +* *Selection Criteria* – See +link:#Configuring_Named_Query_Selection_Criteria[Configuring Named Query +Selection Criteria]. +* *Order* – This tab appears for `+ReadAllQuery+` queries only. See +link:#Configuring_Read_All_Query_Order[Configuring Read All Query +Order]. +* *Optimization* – See +link:#Configuring_Named_Query_Optimization[Configuring Named Query +Optimization]. +* *Attributes* – This tab appears for `+ReportQuery+` queries only. See +link:#Configuring_Named_Query_Attributes[Configuring Named Query +Attributes]. +* *Group/Order* – This tab appears for `+ReportQuery+` queries only. +link:#Configuring_Named_Query_Group_Order_Options[Configuring Named +Query Group/Order Options]. +* *Calls* – This tab appears for EIS root descriptors only (for +`+ReadAllQuery+` and `+ReadObjectQuery+` queries). See +link:#Creating_an_EIS_Interaction_for_a_Named_Query[Creating an EIS +Interaction for a Named Query]. +* *Options* – See link:#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +*See Also* + +link:#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level] + +==== Configuring Named Query Type and Parameters + +Use this tab to select the query type and add or remove parameters. + +[#Figure 115-8]## *_Named Queries, General Tab_* + +.Named Queries, General Tab +image::qrnmdgen.gif[Named Queries, General +Tab,title="Named Queries, General Tab"] + +Use the following information to complete each field on this tab: + +Field + +Description + +Type + +Select the type of query from the list. You can create any of the +following query types: + +ReadAllQuery + +ReadObjectQuery + +ReportQuery1 + +To create other types of query, you must use Java. + +When you change the type of an existing query, Workbench preserves any +configuration that is common between the old and new type and warns you +if changing the type will result in the loss of configuration that is +not shared by the new type. + +Parameters + +For queries that take parameters, specify the parameters: + +To add a new parameter, click Add. The Add Query Parameter dialog box +appears. Click Browse to select the type, specify a name, and click OK. + +To delete an existing parameter, select the parameter and click Remove. +Workbench prompts for confirmation. + +To modify an existing parameter, select the parameter and click Edit. +The Edit Query Parameter dialog box appears. Modify the name and type of +the parameter and click OK. + +To change the order of the parameters, select an existing parameter and +click Up or Down. + +Type + +Select the class of the parameter’s type. + +Name + +Enter the name of the parameter. + +1Relational descriptors only. *See Also* + +link:#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level] + +==== Configuring Named Query Selection Criteria + +Use this tab to specify the format of the named query and enter the +query string. + +*_Named Queries, Selection Criteria Tab_* + +.Named Queries, Selection Criteria Tab +image::qrnmdsel.gif[Named Queries, Selection Criteria +Tab,title="Named Queries, Selection Criteria Tab"] + +Use the following information to complete each field on this tab: + +Field + +Description + +Type + +Specify if query uses an EclipseLink Expression, SQL, or EJB QL. + +Expression or Query String + +If the Type is SQL or EJB QL, enter the query string (either SQL or EJB +QL). Workbench does not validate the query string. See a note that +follows this table for information on query syntax. + +Note: Use a combination of an escape character and a double-quote ( " ) +instead of just a double-quote ( ” ) when defining your query using SQL +or EJB QL. For example: + +SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = "Bob" + +If you fail to do so, the generated Java code would look as follows: + +query.setEJBQLString("`SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = `"Bob”“); + +The preceding code produces an error at compile time.If you define your +query using the correct syntax, the generated Java code will contain no +errors and be similar to the following: + +query.setEJBQLString("`SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = "Bob"`"); + +*See Also* + +link:#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level] + +==== Configuring Read All Query Order + +Use this tab to specify how the results of a read all query should be +ordered by attribute name. + +*_Named Queries, Order Tab_* + +.Named Queries, Order Tab +image::ordertab.gif[Named Queries, Order +Tab,title="Named Queries, Order Tab"] + +Select one of the following actions: + +* To add a new attribute by which to order query results, click *Add*. +The Add Ordering Attribute dialog box appears. Select the mapped +attribute to order by, specify ascending or descending order, and then +click *OK*. +* To change the order of the order attributes, select an existing +attribute and click *Up* or *Down*. +* To modify an existing order attribute’s ordering options, select an +existing attribute and click *Edit*. +* To remove an order attribute, select an existing attribute and click +*Remove*. + +==== Configuring Named Query Optimization + +You can optimize a named query by configuring batch (`+ReadAllQuery+` +only) or joining (`+ReadAllQuery+` and `+ReadObjectyQuery+`) attributes. + +For more information on using batch reading, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Queries[Optimizing +Queries], +Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Reading_Case_2:_Batch_Reading_Objects[Reading +Case 2: Batch Reading Objects], and +link:Using%20Basic%20Query%20API%20(ELUG)#Using_Batch_Reading[Using +Batch Reading]. + +For more information on joining, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Join_Reading_and_Object-Level_Read_Queries[Join +Reading and Object-Level Read Queries] and +link:Using%20Basic%20Query%20API%20(ELUG)#Using_Join_Reading_with_ObjectLevelReadQuery[Using +Join Reading with ObjectLevelReadQuery]. + +Use this tab to specify batch reading and joining attributes. + +[#Figure 115-11]## *_Named Queries, Optimization Tab_* + +.Named Queries, Optimization Tab +image::optimization.gif[Named Queries, Optimization +Tab,title="Named Queries, Optimization Tab"] + +Select one of the following actions for *Batch Read Attributes* +(`+ReadAllQuery+` only): + +* To add a new batch read attribute, click *Add*. The Add Batch Read +Attribute dialog box appears. Select the mapped attribute and click +*OK*. +* To change the order of the batch read attributes, select an existing +attribute and click *Up* or *Down*. +* To modify an existing batch read attribute’s options, select an +existing attribute and click *Edit*. +* To remove a batch read attribute, select an existing attribute and +click *Remove*. + +Select one of the following actions for *Joined Attributes* +(`+ReadAllQuery+` and `+ReadObjectQuery+`): + +* To add a new joined attribute, click *Add*. The Add Joined Attribute +dialog box appears. [#Figure 115-12]##*’’ Add Joined Attribute Dialog +Box*’’ image:addjoin.gif[Add Joined Attribute Dialog +Box,title="Add Joined Attribute Dialog Box"] ++ +Select the mapped attribute. Optionally, enable or disable *Allows Null* +or, for a `+Collection+` attribute, *Allows None*. Click *OK*. +* To change the order of the joined attributes, select an existing +attribute and click *Up* or *Down*. +* To modify an existing joined attribute’s options, select an existing +attribute and click *Edit*. +* To remove a joined attribute, select an existing attribute and click +*Remove*. + +==== Configuring Named Query Attributes + +For `+ReportQuery+` queries only, you can configure report query +functions to apply to one or more attributes. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report_Query[Report +Query]. + +Use this tab to configure report query attributes. + +[#Figure 115-13]## *_Named Queries, Attributes Tab_* + +.Named Queries, Attributes Tab +image::nqatab.gif[Named Queries, Attributes +Tab,title="Named Queries, Attributes Tab"] + +Select one of the following actions for *Attributes* (`+ReportQuery+` +only): + +* To add a new report query attribute, click *Add*. The Add Joined +Attribute dialog box appears. Continue with +link:#Adding_Report_Query_Attributes[Adding Report Query Attributes]. +* To change the order of the report query attribute attributes, select +an existing attribute and click *Up* or *Down*. +* To modify an existing report query attribute’s options, select an +existing attribute and click *Edit*. +* To remove a report query attribute, select an existing attribute and +click *Remove*. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can only choose attributes that are configured with a +direct mapping (converters included) or a user-defined query key. +|=== + +===== Adding Report Query Attributes + +Use this dialog box to add a report query attribute. + +[#Figure 115-14]## *_Add Report Query Attribute Dialog Box_* + +.Add Report Query Attribute Dialog Box +image::nqatt.gif[Add Report Query Attribute Dialog +Box,title="Add Report Query Attribute Dialog Box"] + +Select the attribute you want in this report query and use the following +table to complete the dialog box and add the report query attribute: + +Option + +’Description + +Allows None or Allows Null + +Use the Allows Null and Allows None options to define an expression with +an outer join. Check the Allows Null option to use the ExpressionBuilder +method getAllowingNull. + +Check the Allows None option for Collection attributes to use the +ExpressionBuilder method anyOfAllowingNone. For more information, see +Using EclipseLink Expression API for Joins. + +Function + +Select from the list of report query functions that EclipseLink +provides. This function will be applied to the specified attribute. You +must select an attribute for all functions, except Count. Alternatively, +you can enter the name of a custom function that you implement in your +database. For more information, see Expression method getFunction in the +EclipseLink API Reference. + +Name + +The name associated with the calculated value. By default, the name is +. + +Enter the necessary information and click *OK*. Workbench adds the +report query attribute to the list of attributes in the Attribute tab. + +==== Configuring Named Query Group/Order Options + +For `+ReportQuery+` queries only, you can configure grouping and +ordering attributes. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report_Query[Report +Query]. + +Use this tab to specify grouping and ordering attributes. + +[#Figure 115-15]## *_Named Queries, Group/Order Tab_* + +.Named Queries, Group/Order Tab +image::nqgror.gif[Named Queries, Group/Order +Tab,title="Named Queries, Group/Order Tab"] + +Select one of the following actions for *Grouping Attributes* +(`+ReportQuery+` only): + +* To add a new grouping attribute, click *Add*. The Add Grouping +Attribute dialog appears. Select the desired mapped attribute and click +*OK*. +* To change the order of the grouping attributes, select an existing +attribute and click *Up* or *Down*. +* To modify an existing grouping attribute’s options, select an existing +attribute and click *Edit*. +* To remove a grouping attribute, select an existing attribute and click +*Remove*. + +Select one of the four following actions for *Ordering Attributes* +(`+ReportQuery+` only): + +* To add a new ordering attribute, click *Add*. The Add Ordering +Attribute dialog box appears. Continue with +link:#Adding_Ordering_Attributes[Adding Ordering Attributes]. +* To change the order of the ordering attributes, select an existing +attribute and click *Up* or *Down*. +* To modify an existing ordering attribute’s options, select an existing +attribute and click *Edit*. +* To remove an ordering attribute, select an existing attribute and +click *Remove*. + +===== Adding Ordering Attributes + +Use this dialog box to add a report query ordering attribute. + +[#Figure 115-16]## *_Add Ordering Attribute Dialog Box_* + +.Add Ordering Attribute Dialog Box +image::nqaddor.gif[Add Ordering Attribute Dialog +Box,title="Add Ordering Attribute Dialog Box"] + +Use the following information to complete the fields on the dialog box +and add an ordering attribute: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Option* |*Description* +|*Selected Attribute* |Select this option to view a list of the report +query attributes you added (see +link:#Configuring_Named_Query_Attributes[Configuring Named Query +Attributes]). Select an attribute and choose its ordering option in the +*Order* field. + +|*New Attribute* |Select this option to view a list of all class +attributes. Select an attribute and choose its ordering option in the +*Order* field. + +|*Order* |Select ascending or descending. +|=== + +Enter the necessary information and click *OK*. Workbench adds the +report query attribute to the list of attributes in the Attribute tab. + +*See Also* + +link:#Configuring_Named_Query_Attributes[Configuring Named Query +Attributes] + +==== Creating an EIS Interaction for a Named Query + +For an EIS root descriptor, you can define EIS interactions to invoke +methods on an EIS. + +You can use EclipseLink to define an interaction as a named query for +read object and read all object queries, as described here. These +queries are not called for basic persistence operations +(link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Custom_EIS_Interactions_for_Basic_Persistence_Operations[Configuring +Custom EIS Interactions for Basic Persistence Operations]); you can call +these additional queries by name in your application for special +purposes. + +Use this tab to define an interaction as a named query for read object +and read all object queries. + +[#Figure 115-17]## *_Call Tab_* + +.Call Tab +image::nqcall.gif[Call Tab,title="Call Tab"] + +Use the following information to complete each field on the tab: + +Field + +Description + +Interaction Type + +Using Workbench, you can only use XML Interactions. You cannot change +this field. + +Function Name + +Specify the name of the EIS function that this call type (Read Object or +Read All) invokes on the EIS. + +Input Record Name + +Specify the name passed to the JCA adapter when creating the input +record. + +Input Root Element + +Specify the root element name to use for the input DOM. + +Input Arguments + +Specify the query argument name to map to the interaction field or XPath +nodes in the argument record. For example, if you are using XML records, +use this option to map input argument name to the XPath name/first-name. + +Output Arguments + +Specify the result record field or XPath nodes to map the correct nodes +in the record used by the descriptor’s mappings. For example, if you are +using XML records, use this option to map the output fname to +name/first-name. + +Output arguments are not required if the interaction returns an XML +result that matches the descriptor’s mappings. + +Input Result Path + +Use this option if the EIS interaction expects the interaction arguments +to be nested in the XML record. For example, specify arguments, if the +arguments were to be nested under the root element exec-find-order, then +under an arguments element. + +Output Result Path + +Use this option if the EIS interaction result record contains the XML +data that maps to the objects in a nested structure. For example, +specify order, if the results were return under a root element results, +then under an order element. + +Properties + +Specify any properties required by your EIS platform. For example, +property name operation (from AQPlatform.QUEUE_OPERATION) and property +value enqueue (from AQPlatform.ENQUEUE). + +==== Configuring Named Query Options + +Use this tab to configure additional options for the query. + +[#Figure 115-18]## *_Named Queries, Options Tab_* + +.Named Queries, Options Tab +image::qrnmdopt.gif[Named Queries, Options +Tab,title="Named Queries, Options Tab"] + +Use the following information to complete each field on the tab: + +Field + +Description + +Refresh Identity Map Results2 + +Refreshes the attributes of the object(s) resulting from the query. If +cascading is used, the private parts of the objects will also be +refreshed. + +Cache Statement1 + +Caches the prepared statements. This requires full parameter binding as +well (see Bind Parameters). + +Bind Parameters1 + +By default, EclipseLink binds all of the query’s parameters. Deselect +this option to disable binding. + +Cache Usage2 + +Selects how EclipseLink should use the session cache when a query is +executed: + +Use descriptor settings + +Do not check cache + +Check cache by exact primary key + +Check cache by primary key + +Check cache then database + +Check cache only + +Conform results in unit of workFor more information, see the following: + +Configuring Cache Usage for In-Memory Queries. + +Configuring Unit of Work Conforming at the Descriptor Level + +In Memory Query Indirection2 + +Selects how EclipseLink should handle indirection (lazy loading) when an +in-memory or conforming query is executed: + +Throw indirection exception – if this object uses indirection and +indirection has not been triggered, EclipseLink will throw an exception. + +Trigger indirection – if this object uses indirection and indirection +has not been triggered, EclipseLink will trigger indirection. + +Ignore exception return conformed – returns conforming if an untriggered +value holder is encountered. That is, you expect results from the +database to conform, and an untriggered value holder is taken to mean +that the underlying attribute has not changed. + +Ignore exception return not conformed – returns not conforming if an +untriggered value holder is encountered. + +For more information, see the following: + +Handling Exceptions Resulting from In-Memory Queries. + +Indirection (Lazy Loading). + +Return Choice3 + +Selects how EclipseLink should handle ReportQuery results: + +Result collection – return ReportQuery results as a Collection of +ReportQueryResult objects. + +Single result – return only the first ReportQueryResult object (not +wrapped in a Collection or Map). Use this option if you know that the +ReportQuery returns only one row. + +Single value – return only a single value. Use this option if you know +that the ReportQuery returns only one row that contains only one +attribute. + +Single attribute – return only a single Collection of values. If the +query returns multiple rows, but each row only has a single attribute, +this option will return a Collection of values, instead of a Collection +of ReportQueryResults. + +For more information, see Collection Query Results. + +Retrieve Primary Keys3 + +Selects whether or not EclipseLink retrieves the primary key values +within each result. You can use the primary keys to retrieve the real +objects. + +None – do not retrieve primary keys + +All – retrieve primary keys for each object read; + +First – return only the first primary key value (in the case of a +composite primary key). This can be used if you just want to know if +something exists or not, but do not really care about the value. + +1 For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[How to Use +Parameterized SQL (Parameter Binding) and Prepared Statement Caching for +Optimization]. 2For `+ReadObjectQuery+` and `+ReadAllQuery+` queries +only. 3For `+ReportQuery+` queries only. Click *Advanced* to configure +additional options. See +link:#Configuring_Named_Query_Advanced_Options[Configuring Named Query +Advanced Options]. + +*See Also* + +link:#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level] + +==== Configuring Named Query Advanced Options + +To configure additional advanced query options, use this procedure. + +[arabic] +. From the Named Queries – Options tab, click *Advanced*. The Advanced +Query Options dialog box appears.From the Named Queries – Options tab, +click *Advanced*. The Advanced Query Options dialog box appears. +[#Figure 115-19]##*_Advanced Query Options Dialog Box_* +image:advqropt.gif[Advanced Query Options Dialog +Box,title="Advanced Query Options Dialog Box"] +. Complete each field in the Advanced Query Options dialog box. + +Use the following information to enter data in each field and click +*OK*: + +Field + +Description + +Maintain Cache + +Specify whether to use the cache for the query or to build objects +directly from the database result. You should only use this option if +you are executing a Partial Object Query, whose results cannot be +cached. For more information, see How to Disable the Identity Map Cache +Update During a Read Query. + +Use Wrapper Policy + +Specify whether or not the named query will use the wrapper policy +configured for this descriptor. For more information, see Configuring +Wrapper Policy. + +Prepare SQL Once + +Specify the setShouldPrepare() for the named query. By default, +EclipseLink optimizes queries to generate their SQL only once. You may +need to disable this option for certain types of queries that require +dynamic SQL based on their arguments, such as the following: + +Expressions that use equal where the argument value could be null. This +may cause problems on databases that require IS NULL, instead of = NULL. + +Expressions that use in and use parameter binding. This will cause +problems as the in values must be bound individually. + +Cache Query Results + +Specify the cacheQueryResults method for the query. The query will only +access the database the first time it is executed. Subsequent execution +will return exactly the original result. For more information, see How +to Cache Results in a ReadQuery. + +Refresh Remote Identity Map Results + +Specify the refreshRemoteIdentityMapResult method for the query. +EclipseLink can refresh the attributes of the object(s) resulting from +the query. With cascading, EclipseLink will also refresh the private +parts of the object(s). + +Exclusive Connection + +Specify whether or not the named query will use an exclusive connection. +You can also configure exclusive connection acquisition at the session +level (see Configuring Connection Policy. + +Pessimistic Locking + +Specify the specific pessimistic locking policy for the query or use the +locking policy from the descriptor. + +Distinct State + +Specify if EclipseLink prints the DISTINCT clause, if a distinct has +been set. The DISTINCT clause allows you to remove duplicates from the +result set. + +Query Timeout + +Specify if the query will time out (or abort) after a specified number +of seconds. + +Maximum Rows + +Specify if the query will limit the results to a specified number of +rows. Use this to option for queries that could return an excessive +number of objects. + +*See Also* + +link:#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level] + +=== How to Configure Named Queries at the Descriptor Level Using Java + +To configure named queries in Java, Use a +link:#Configuring_Amendment_Methods[descriptor amendment method]. The +link:#Example_115-1[Creating a Named Query with an Amendment Method] +example illustrates an amendment method that creates a named query and +adds it to the `+DescriptorQueryManager+`. + +[#Example 115-1]## *_Creating a Named Query with an Amendment Method_* + +`+public class EmployeeAmmendmentMethodClass {+` `+....+` +`+    +`*`+//\'\' \'\'Create\'\' \'\'named\'\' \'\'query\'\' \'\'with\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* + +`+    public static void createEmployeeQuery(ClassDescriptor descriptor) {+` +`+        ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+        ExpressionBuilder emp = query.getExpressionBuilder();+` +`+        Expression firstNameExpression =+` +`+            emp.get("firstName").equal(emp.getParameter("firstName"));+` +`+        query.setSelectionCriteria(firstNameExpression);+` +`+        query.addArgument("firstName");+` + +`+        descriptor.getQueryManager().addQuery(+` +`+                            "employeeReadByFirstName", query);+` +`+    }+` `+}+` + +== Configuring Query Timeout at the Descriptor Level + +You can specify how the EclipseLink runtime handles the duration of +queries on a descriptor’s reference class. Specifying a query timeout at +the descriptor level applies to all queries on the descriptor’s +reference class. A query timeout ensures that your application does not +block forever over a hung or lengthy query that does not return in a +timely fashion. + +This table summarizes which descriptors support query timeout +configuration. + +[#Table 115-9]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptor + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. You can also configure a timeout on a per-query +basis. For more information, see the following: + +* link:#Configuring_Named_Query_Advanced_Options[Configuring Named Query +Advanced Options] +* link:Using%20Basic%20Query%20API%20(ELUG)#Configuring_Query_Timeout_at_the_Query_Level[Configuring +Query Timeout at the Query Level] + +=== How to Configure Query Timeout at the Descriptor Level Workbench + +To configure how EclipseLink handles the duration of queries to this +descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Queries* tab. The Queries tab appears. +. Click the *Settings* tab. The Settings tab appears. +[#Figure 115-20]##*_Descriptor Queries Settings Tab, Query Timeout +Options_* image:desqtimo.gif[Descriptor Queries Settings Tab, Query +Timeout +Options,title="Descriptor Queries Settings Tab, Query Timeout Options"] +. Select the Query Timeout options on the tab. + +Use the following table to enter data in the fields on the descriptor’s +*Settings* tab to specify how EclipseLink handles query duration: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Default Timeout* |EclipseLink throws a `+DatabaseException+` if a +query on this descriptor does not return within the timeout period you +configure on the parent descriptor. If there is no parent descriptor, +the query timeout defaults to *No Timeout*. + +|*No Timeout* |EclipseLink blocks until a query on this descriptor +returns. + +|*Timeout* |Enter the timeout period in seconds. EclipseLink throws a +`+DatabaseException+` if a query on this descriptor does not return +within this time. +|=== + +*See Also* + +link:#Configuring_Query_Timeout_at_the_Descriptor_Level[Configuring +Query Timeout at the Descriptor Level] + +=== How to Configure Query Timeout at the Descriptor Level Java + +Use `+DescriptorQueryManager+` method `+setQueryTimeout+` passing in the +timeout value as a number of milliseconds. + +== Configuring Cache Refreshing + +By default, EclipseLink caches objects read from a data source (see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]). +Subsequent queries for these objects will access the cache and thus +improve performance by reducing data source access and avoiding the cost +of rebuilding object’s and their relationships. Even if a query, such as +a read-all query, accesses the data source, if the objects corresponding +to the records returned are in the cache, EclipseLink will use the cache +objects. + +This can lead to stale data in the application. Although using an +appropriate link:#Configuring_Locking_Policy[locking policy] is the only +way to ensure that stale or conflicting data does not get committed to +the data source, sometimes certain data in the application changes so +frequently that it is desirable to always refresh the data, instead of +only refreshing the data when a conflict is detected. + +You can specify how the EclipseLink runtime handles cache refreshing for +all queries on a descriptor’s reference class. + +This table summarizes which descriptors support query cache refresh +configuration. + +[#'Table 115-10]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptor 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. Configuring descriptor-level cache refresh may +affect performance. As an alternative, consider configuring the +following: + +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Refresh_the_Cache[cache +refresh on a query-by-query basis] +* link:#Configuring_Cache_Expiration_at_the_Descriptor_Level[cache +expiration] +* link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[isolated +caching] + +For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Cache[Optimizing +Cache]. + +=== How to Configure Cache Refreshing Using Workbench + +To configure how EclipseLink refreshes the cache for queries to this +descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Queries* tab. The Queries tab appears. +. Click the *Settings* tab. The Settings tab appears. +[#Figure 115-21]##*_Descriptor Queries Settings Tab, Cache Refreshing +Options_* image:descache.gif[Descriptor Queries Settings Tab, Cache +Refreshing +Options,title="Descriptor Queries Settings Tab, Cache Refreshing Options"] +. Select the Refreshing Cache options on the tab. + +Use the following table to enter data in the fields on the descriptor’s +*Settings* tab to specify how EclipseLink will refresh the cache for +queries: + +Field + +Description + +Always Refresh + +Refreshes the cache on all queries. Avoids stale data by ensuring that +any query that accesses the data source will refresh the resulting +objects in the cache. This has no effect on queries that get a cache hit +and never access the data source, such as read-object primary key +queries or in-memory queries. + +Configuring descriptor level cache refresh may affect performance. As an +alternative, consider configuring: + +cache refresh on a query-by-query basis + +cache expiration + +isolated caching + +Only Refresh If Newer Version + +Refreshes the cache only if the object in the database is newer than the +object in the cache (as determined by the Optimistic Locking field). See +Configuring Locking Policy for more information. Improves performance by +avoiding unnecessary refreshing of an object if its version matches the +data source version. This option does not cause refreshing on its own: +you must use it in combination with Always Refresh, query refreshing, or +cache expiration. + +Disable Cache Hits + +When selected, EclipseLink bypasses the cache and goes to the database +for read object queries based on primary key. Using this option in +conjunction with Always Refresh ensures that EclipseLink always goes to +the database. This option ensures that all queries including read-object +primary key queries will always access the data source. This option does +not cause refreshing on its own: you must use it in combination with +Always Refresh. + +This option can cause a serious performance issue: avoid whenever +possible. + +[width="100%",cols="<100%",] +|=== +|*Caution*: Use the *Always Refresh* and *Disable Cache Hits* properties +with caution as they may lead to poor performance. As an alternative, +consider +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Refresh_the_Cache[configuring +cache refresh on a query-by-query basis] or +link:#Configuring_Cache_Expiration_at_the_Descriptor_Level[configuring +cache expiration]. For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Cache[Optimizing +Cache]. +|=== + +=== How to Configure Cache Refreshing Using Java + +Configure cache refresh options using the following `+ClassDescriptor+` +methods: + +* `+setShouldAlwaysRefreshCache+` +* `+setShouldAlwaysRefreshCacheOnRemote+` +* `+setShouldDisableCacheHits+` +* `+setShouldDisableCacheHitsOnRemote+` +* `+setShouldOnlyRefreshCacheIfNewerVersion+` + +Use these methods in link:#Configuring_Amendment_Methods[a descriptor +amendment method], as this example illustrates. + +[#Example 115-2]## *_Configuring Remote Refreshing_* + +`+public void addToDescriptor(ClassDescriptor descriptor) {+` +`+    descriptor.setShouldRefreshCacheOnRemote(true);+` +`+    descriptor.setShouldDisableCacheHitsOnRemote(true);+` `+}+` + +== Configuring Query Keys + +A *query key* is a schema-independent alias for a database field name. +For example, consider a class `+Employee+` with attribute `+firstName+` +mapped directly to a database field `+F_NAME+` in database table +`+EMPLOYEE+`. Without a query key, when you create a query or expression +that involves `+Employee+` attribute `+firstName+`, you must use the +database management system-specific field name `+F_NAME+`. This makes it +more difficult to build a query and ties the query to the schema. With a +query key, you can refer to this field using a schema-independent alias, +such as `+firstName+`. + +This table summarizes which descriptors support query keys. + +[#Table 115-11]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +Using query keys offers the following advantages: + +* Enhances code readability in EclipseLink expressions and simplifies +expression development. You can compose expressions entirely within the +context of your object model. +* Increases portability by making code independent of the database +schema. If you rename a field in your schema, you can redefine the query +key without changing any code that uses it. +* Query keys used with interface descriptors allow the implementor +descriptor’s tables to have different field names. + +Query keys are automatically generated for all mapped attributes. The +name of the query key is the name of the class attribute specified in +your object model. + +For information on how to use query keys in queries and expressions, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Query_Keys[Query +Keys]. + +When query keys are generated and how you can add or modify query keys +depends on the type of mapping or descriptor involved: + +* link:#Direct_Mappings[Direct Mappings] +* link:#Relationship_Mappings[Relationship Mappings] +* link:#Interface_Descriptors[Interface Descriptors] + +=== *Direct Mappings* + +Workbench automatically generates query keys for all direct mappings at +the time you create the mapping. + +Workbench provides support for adding or modifying query keys for simple +unmapped attributes that could be mapped by a direct mapping: for +example, the `+version+` field used for optimistic locking or the +`+type+` field used for inheritance. You cannot modify or remove +automatically generated query keys. + +=== *Relationship Mappings* + +EclipseLink automatically generates query keys for all relationship +mappings at run time. + +For example, if you have a class `+Customer+` with attribute `+orders+` +mapped in a one-to-many relationship to class `+PurchaseOrders+`, then +the EclipseLink runtime will generate a query key named `+orders+` for +this `+Customer+` attribute. + +The Workbench does not currently support adding or modifying the query +keys for relationship mappings. If you must add or modify such a query +key, you must do so in Java code, using a descriptor amendment method. + +=== *Interface Descriptors* + +link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Interface_Descriptors[Interface +descriptors] define only the query keys that are shared among their +implementors. In the descriptor for an interface, only the name of the +query key is specified. + +Workbench provides support for choosing the implementors of an interface +that share at least one common automatically generated +link:#Configuring_Interface_Query_Keys[query key]. + +=== How to Configure Query Keys Using Workbench + +To add query keys to simple unmapped fields and to view the query keys +automatically generated for directly mapped attributes, use this +procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Query Keys* tab in the *Editor*. +[#Figure 115-22]##*_Queries, Query Keys Tab_* +image:querykey.gif[Queries, Query Keys +Tab,title="Queries, Query Keys Tab"] + +To add a new query key, click *Add.* + +To delete an existing query key, select the query key and click +*Remove*. + +To rename an existing query key, select the query key and click +*Rename*. + +Use the *Field* list to select the field in the table associated with +the query key. + +=== How to Configure Query Keys Using Java + +To manually create a relationship query key, implement a +link:#Configuring_Amendment_Methods[descriptor amendment method] that +uses one of the following `+ClassDescriptor+` methods to register the +query keys: + +* `+addQueryKey+` – specify a query key using an instance of +`+QueryKey+` such as `+DirectQueryKey+`, `+DirectCollectionQueryKey+`, +`+ManyToManyQueryKey+`, `+OneToManyQueryKey+`, or `+OneToOneQueryKey+`. +* `+addDirectQueryKey+` – add a query key that maps directly to the +given database field. +* `+addAbstractQueryKey+` – add an abstract query key to an interface +descriptor. Any implementors of that interface must define the query key +defined by this abstract query key. + +The link:#Example_115-3[Defining a Query Key], +link:#Example_115-4[Defining a One-to-Many Query Key], and +link:#Example_115-5[Defining a Many-to-Many Query Key] examples +illustrate how to define a query key in Java code. + +[#Example 115-3]## *_Defining a Query Key_* + +*`+//\'\' \'\'Add\'\' \'\'a\'\' \'\'query\'\' \'\'key\'\' \'\'for\'\' \'\'the\'\' \'\'foreign\'\' \'\'key\'\' \'\'field\'\' \'\'using\'\' \'\'the\'\' \'\'direct\'\' \'\'method+`* +`+descriptor.addDirectQueryKey("managerId", "MANAGER_ID");+` + +*`+// The same query key can also be added through the addQueryKey method+`* +`+DirectQueryKey directQueryKey = new DirectQueryKey();+` +`+directQueryKey.setName("managerId");+` +`+directQueryKey.setFieldName("MANAGER_ID");+` +`+descriptor.addQueryKey(directQueryKey);+` + +*`+//\'\' \'\'Add\'\' \'\'a\'\' \'\'one-to-one\'\' \'\'query\'\' \'\'key\'\' \'\'for\'\' \'\'the\'\' \'\'large\'\' \'\'project\'\' \'\'of\'\' \'\'which\'\' \'\'the+`* +*`+//+`*`+employee is a leader (this assumes only one project)+` +`+OneToOneQueryKey projectQueryKey = new OneToOneQueryKey();+` +`+projectQueryKey.setName("managedLargeProject");+` +`+projectQueryKey.setReferenceClass(LargeProject.class);+` +`+ExpressionBuilder builder = new ExpressionBuilder();+` +`+projectQueryKey.setJoinCriteria(builder.getField(+` +`+    "PROJECT.LEADER_ID").equal(builder.getParameter("EMPLOYEE.EMP_ID")));+` +`+descriptor.addQueryKey(projectQueryKey);+` + +[#Example 115-4]## *_Defining a One-to-Many Query Key_* + +*`+//\'\' \'\'Add\'\' \'\'a\'\' \'\'one-to-many\'\' \'\'query\'\' \'\'key\'\' \'\'for\'\' \'\'the\'\' \'\'projects\'\' \'\'where\'\' \'\'the\'\' \'\'employee+`* +*`+//+`*`+manages multiple projects +` +`+OneToManyQueryKey projectsQueryKey = new OneToManyQueryKey();+` +`+projectsQueryKey.setName("managedProjects");+` +`+projectsQueryKey.setReferenceClass(Project.class);+` +`+ExpressionBuilder builder = new ExpressionBuilder();+` +`+projectsQueryKey.setJoinCriteria(builder.getField(+` +`+    "PROJECT.LEADER_ID").equal(builder.getParameter("EMPLOYEE.EMP_ID")));+` +`+descriptor.addQueryKey(projectsQueryKey);+` + +[#Example 115-5]## *_Defining a Many-to-Many Query Key_* + +*`+// Add a many-to-many query key to an employee project that uses a join table+`* +`+ManyToManyQueryKey projectsQueryKey = new ManyToManyQueryKey();+` +`+projectsQueryKey.setName("projects");+` +`+projectsQueryKey.setReferenceClass(Project.class);+` +`+ExpressionBuilder builder = new ExpressionBuilder();+` +`+projectsQueryKey.setJoinCriteria(+` +`+    (builder.getParameter("EMPLOYEE.EMP_ID").equal(+` +`+    builder.getTable("EMP_PROJ").getField("EMP_ID")).and(+` +`+    builder.getTable("EMP_PROJ").getField("PROJ_ID").equal(+` +`+    builder.getField("PROJECT.PROJ_ID")))));+` +`+descriptor.addQueryKey(projectsQueryKey);+` + +The link:#Example_115-6[Defining a One-to-One Query Key with an +Amendment Method] example illustrates how to implement a `+Descriptor+` +amendment method to define a one-to-one query key. In this example, the +object model for the `+Address+` class does not include a reference to +its owner, an `+Employee+` object. You can amend the `+Address+` class +descriptor to add a query key named `+owner+` to make up for this +deficiency. At run time, you can compose expressions that select +`+Address+` objects based on this `+owner+` query key. + +[#Example 115-6]## *_Defining a One-to-One Query Key with an Amendment +Method_* + +*`+//\'\' \'\'Static\'\' \'\'amendment\'\' \'\'method\'\' \'\'in\'\' \'\'Address\'\' \'\'class,\'\' \'\'addresses\'\' \'\'do\'\' \'\'not\'\' \'\'know+`* +*`+//+`*`+ their owners in the object model, however you can still+` +*`+//+`*`+ query on their owner if a user-defined query key is defined+` +`+public static void addToDescriptor(Descriptor descriptor) {+` +`+    OneToOneQueryKey ownerQueryKey = new OneToOneQueryKey();+` +`+    ownerQueryKey.setName("owner");+` +`+    ownerQueryKey.setReferenceClass(Employee.class);+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    ownerQueryKey.setJoinCriteria(+` +`+        builder.getField("EMPLOYEE.ADDRESS_ID").equal(+` +`+        builder.getParameter("ADDRESS.ADDRESS_ID")));+` +`+    descriptor.addQueryKey(ownerQueryKey);+` `+}+` + +== Configuring Interface Query Keys + +A query key is a schema independent alias for a database field name. For +more information about query keys, see +link:#Configuring_Query_Keys[Configuring Query Keys]. + +link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Interface_Descriptors[Interface +descriptors] are defined only with query keys that are shared among +their implementors. In the descriptor for an interface, only the name of +the query key is specified. + +In each implementor descriptor, the key must be defined with the +appropriate field from one of the implementor descriptor’s tables. + +This allows queries and relationship mappings to be defined on the +interface using the query key names. + +Interface query keys are supported in relational database projects only. + +This table summarizes which descriptors support interface query keys. + +[#Table 115-12]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +Consider an `+Employee+` that contains a contact of type `+Contact+`. +The `+Contact+` class is an interface with two implementors: `+Phone+` +and `+Email+`. The `+Phone+` class has attributes `+id+` and `+number+`. +The `+Email+` class has attributes `+id+` and `+address+`. This figure +illustrates the generated keys: + +[#Figure 115-23]## *_Automatically Generated Query Keys for Phone and +Email_* + +.Automatically Generated Query Keys for Phone and Email +image::atgenkey.gif[Automatically Generated Query Keys for Phone and +Email,title="Automatically Generated Query Keys for Phone and Email"] + +Both classes have an attribute, id, that is directly mapped to fields +that have different names. However, a query key is generated for this +attribute. For the `+Contact+` interface descriptor, you must indicate +that the `+id+` query key must be defined for each of the implementors. + +If either of the implementor classes did not have the `+id+` query key +defined the Workbench would flag that descriptor as deficient. + +Now that a descriptor with a commonly shared query key has been defined +for `+Contact+`, you can use it as the reference class for a variable +one-to-one mapping (see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Queries_on_Variable_One-to-One_Mappings[Using +Queries on Variable One-to-One Mappings]). + +For example, you can now create a variable one-to-one mapping for the +`+contact+` attribute of `+Employee+`. When you edit the foreign key +field information for the mapping, you must match the `+Employee+` +descriptor’s tables to query keys from the `+Contact+` interface +descriptor. + +=== How to Configure Interface Query Keys Using Workbench + +To choose the implementors of an interface that share at least one +common automatically generated query key, use this procedure. + +[arabic] +. Select an interface descriptor in the *Navigator*. Its properties +appear in the Editor. [#Figure 115-24]##*_Interface Descriptor Editor +Window_* image:conintds.gif[Interface Descriptor Editor +Window,title="Interface Descriptor Editor Window"] + +To choose an implementor of the selected interface that shares at least +one common query key, click *Add.* + +To remove an implementor of the selected interface, select the +implementor and click *Remove*. + +=== How to Configure Interface Query Keys Using Java + +This example shows how to define the `+Contact+` interface and `+Email+` +and `+Phone+` implementors in Java. + +[#Example 115-7]## *_Defining Interface Query Keys_* + +`+Descriptor contactInterfaceDescriptor = new Descriptor();+` +`+contactInterfaceDescriptor.setJavaInterface(Contact.class);+` +`+contactInterfaceDescriptor.addAbstractQueryKey("id");+` + +`+Descriptor emailClassDescriptor = new Descriptor();+` +`+emailClassDescriptor.setJavaClass(Email.class);+` +`+emailClassDescriptor.addDirectQueryKey("id", "E_ID");+` +`+emailClassDescriptor.getInterfacePolicy().addParentInterface(Contact.class);+` +`+emailClassDescriptor.setTableName("INT_EML");+` +`+emailClassDescriptor.setPrimaryKeyFieldName("E_ID");+` +`+emailClassDescriptor.setSequenceNumberName("SEQ");+` +`+emailClassDescriptor.setSequenceNumberFieldName("E_ID");+` +`+emailClassDescriptor.addDirectMapping("emailID", "E_ID");+` +`+emailClassDescriptor.addDirectMapping("address", "ADDR");+` + +`+Descriptor phoneClassDescriptor = new Descriptor();+` +`+phoneClassDescriptor.setJavaClass(Phone.class);+` +`+phoneClassDescriptor.getInterfacePolicy().addParentInterface(Contact.class);+` +`+phoneClassDescriptor.addDirectQueryKey("id", "P_ID");+` +`+phoneClassDescriptor.setTableName("INT_PHN");+` +`+phoneClassDescriptor.setPrimaryKeyFieldName("P_ID");+` +`+phoneClassDescriptor.setSequenceNumberName("SEQ");+` +`+phoneClassDescriptor.setSequenceNumberFieldName("P_ID");+` +`+phoneClassDescriptor.addDirectMapping("phoneID", "P_ID");+` +`+phoneClassDescriptor.addDirectMapping("number", "P_NUM");+` + +== Configuring Cache Type and Size at the Descriptor Level + +The EclipseLink cache is an in-memory repository that stores recently +read or written objects based on class and primary key values. +EclipseLink uses the cache to do the following: + +* improve performance by holding recently read or written objects and +accessing them in-memory to minimize database access; +* manage locking and isolation level; +* manage object identity. + +This table summarizes which descriptors support identity map +configuration. + +[#Table 115-13]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. This configuration overrides the default +identity map configuration +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Project_Level[defined +at the project level]. + +For detailed information on caching and object identity, and the +recommended settings to maximize EclipseLink performance, see to +link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity]. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +=== How to Configure Cache Type and Size at the Descriptor Level Using Workbench + +To specify the identity map information for a descriptor, use this +procedure: + +[arabic] +. Select the descriptor in the *Navigator*. +. Select the *Caching* tab in the *Editor*. The Caching tab appears. +*_Caching Tab, Identity Map Options_* image:desiden.gif[Caching Tab, +Identity Map Options,title="Caching Tab, Identity Map Options"] +. Complete the fields on the**Caching** tab to specify the default +identity map for the selected descriptor. + +Use the following table to enter data in following fields on the +*Caching* tab: + +Field + +Description + +Type1 + +Use the Type list to choose the identity map as follows: + +Weak with Soft Subcache (SoftCacheWeakIdentityMap) – cache first n +elements in soft space, anything after that in weak space (see Soft +Cache Weak Identity Map and Hard Cache Weak Identity Map) + +Weak with Hard Subcache (HardCacheWeakIdentityMap) – cache first n +elements in hard space, anything after that in weak space (see Soft +Cache Weak Identity Map and Hard Cache Weak Identity Map) + +Weak (WeakIdentityMap) – cache everything in weak space + +Soft (SoftIdentityMap) – cache everything in soft space + +Full (FullIdentityMap) – cache everything permanently + +None (NoIdentityMap) – cache nothing. + +For more information, see Cache Type and Object Identity. + +Changing the project’s default identity map does not affect descriptors +that already exist in the project. + +Size1 + +Specify the size of the cache as follows: + +When using Weak with Soft Subcache or Weak with Hard Subcache, the size +is the size of the subcache. + +When using Full or Weak, the size indicates the starting size of the +identity map. + +Default + +When you enter a cache size, the Default check box is cleared. To reset +the size to the default for the selected cache type, check the Default +check box. + +1If a descriptor is a child in an inheritance hierarchy, EclipseLink +makes this field read only and displays the options from the parent root +descriptor. + +=== How to Configure Cache Type and Size at the Descriptor Level Using Java + +Use one of the following `+ClassDescriptor+` methods to configure the +descriptor to use the appropriate type of identity map: + +* `+useFullIdentitMap+` +* `+useWeakIdentityMap+` +* `+useSoftIdentityMap+` +* `+useSoftCacheWeakIdentityMap+` +* `+useHardCacheWeakIdentityMap+` +* `+useNoIdentityMap+` + +Use the `+ClassDescriptor+` method `+setIdentityMapSize+` to configure +the size of the identity map. + +== Configuring Cache Isolation at the Descriptor Level + +If you plan to use +link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[isolated +sessions], you must configure descriptors as isolated for any object +that you want confined to an isolated session cache. + +Configuring a descriptor to be isolated means that EclipseLink will not +store the object in the shared session cache and the object will not be +shared across client sessions. Each client will have their own object +read directly from the database. Objects in an isolated client session +cache can reference objects in their parent server session’s shared +session cache, but no objects in the shared session cache can reference +objects in an isolated client session cache. Isolation is required when +using Oracle Database Virtual Private Database (VPD) support or database +user-based read security. Isolation can also be used if caching is not +desired across client sessions. + +This table summarizes which descriptors support cache isolation +configuration. + +[#Table 115-14]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. This configuration overrides the default cache +isolation configuration +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Isolation_at_the_Project_Level[defined +at the project level]. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you configure a descriptor as isolated, it cannot +participate in a coordinated cache (see +link:#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level]). +|=== + +=== How to Configure Cache Isolation at the Descriptor Level Using Workbench + +To specify the cache isolation options, use this procedure: + +[arabic] +. Select the descriptor in the *Navigator*. +. Select the *Caching* tab in the *Editor*. The Caching tab appears. +*_Caching Tab, Isolation Options_* image:desisol.gif[Caching Tab, +Isolation Options,title="Caching Tab, Isolation Options"] +. Complete the *Isolation* options on the *Caching* tab. + +Use the *Isolation* list to choose one of the following: + +* *Isolated* – if you want all objects confined to an isolated client +session cache. For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[Cache +Isolation]. +* *Shared* – if you want all objects visible in the shared session cache +(default). + +=== How to Configure Cache Isolation at the Descriptor Level Using Java + +To specify that a class is isolated, Use a +link:#Configuring_Amendment_Methods[descriptor amendment method] to call +`+ClassDescriptor+` method `+setIsIsolated+`, passing in a `+boolean+` +of `+true+`. + +== Configuring Unit of Work Cache Isolation at the Descriptor Level + +Use this policy to determine how a unit of work uses a session cache for +a specific class. This table lists the unit of work cache isolation +options. + +[#Table 115-15]## + +Option + +Description + +Using the Session Cache After the Transaction + +USE_SESSION_CACHE_AFTER_TRANSACTION + +Objects built from new data accessed after a unit of work early +transaction are stored in the session cache.This options is the most +efficient as it allows the cache to be used after an early transaction. + +Isolating New Data After the Transaction + +ISOLATE_NEW_DATA_AFTER_TRANSACTION (default) + +Objects built from new data accessed after a unit of work early +transaction are only stored in the unit of work. + +This still allows previously cached objects to be accessed in the unit +of work after an early transaction, while ensuring that uncommitted data +will never be put in the session cache by storing any object built from +new data only in the unit of work + +Isolating the Cache after the Transaction + +ISOLATE_CACHE_AFTER_TRANSACTIONAfter a unit of work early transaction +the session cache is no longer used for this class. Objects are directly +built from the database data and only stored in the unit of work, even +if previously cached. + +Note: This option may affect performance because you are bypassing the +session cache after an early transaction. + +Always Isolating the Cache + +ISOLATE_CACHE_ALWAYS + +The session cache will never be used for the class. Objects are directly +built from the database data and only stored in the unit of work. New +objects and changes will never be merged into the session cache. + +Note: This option my affect performance because you are bypassing the +session cache. However if this class is isolated or pessimistic locked +and always accessed in a transaction, this can avoid having to build two +copies of the object. + +Most of these options apply only to a unit of work in an early +transaction, such as the following: + +* A unit of work that was flushed (`+write changes+`). +* Issued a modify query. +* Acquired a pessimistic lock. + +=== How to Configure Unit of Work Cache Isolation at the Descriptor Level Using Java + +To specify that a class is isolated, use a +link:#Configuring_Amendment_Methods[descriptor amendment method] to call +`+ClassDescriptor+` method `+setUnitOfWorkCacheIsolationLevel+`. + +== Configuring Cache Coordination Change Propagation at the Descriptor Level + +If you plan to use a +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[coordinated +cache], you can configure how, and under what conditions, a coordinated +cache propagates changes for a given descriptor. + +This table summarizes which descriptors support cache isolation +configuration. + +[#Table 115-16]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. This configuration overrides the default cache +coordination change propagation configuration defined at the project +level (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Project_Level[Configuring +Cache Coordination Change Propagation at the Project Level]). + +To complete your coordinated cache configuration, see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Coordinated_Cache[Configuring +a Coordinated Cache]. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you configure a descriptor as isolated (see +link:#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]), it cannot participate in a +coordinated cache. +|=== + +=== How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Workbench + +To specify the coordinated cache change propagation options, use this +procedure: + +[arabic] +. Select the descriptor in the *Navigator*. +. Select the *Caching* tab in the *Editor*. The Caching tab appears. +[#Figure 115-27]##*_Caching Tab, Coordination Options_* +image:descord.gif[Caching Tab, Coordination +Options,title="Caching Tab, Coordination Options"] +. Complete the *Coordination* options on the *Caching* tab. + +Use the following information to enter data in the *Coordination* field: + +[width="100%",cols="<8%,<59%,<33%",options="header",] +|=== +|*Coordination Option* |*Description* |*When to Use* +|*None* |For both existing and new instances, do not propagate a change +notification. |Infrequently read or changed objects. + +|*Synchronize Changes* |For an existing instance, propagate a change +notification that contains each changed attribute. For a new instance, +propagate an object creation (along with all the new instance’s +attributes) only if the new instance is related to other existing +objects that are also configured with this change propagation option. +|Frequently read or changed objects that contain few attributes or in +cases where only a few attributes are frequently changed. Objects that +have many or complex relationships. + +|*Synchronize Changes and New Objects* |For an existing instance, +propagate a change notification that contains each changed attribute. +For a new instance, propagate an object creation (along with all the new +instance’s attributes). |Frequently read or changed objects that contain +few attributes or in cases where only a few attributes are frequently +changed. Objects that have few or simple relationships. + +|*Invalidate Changed Objects* |For an existing instance, propagate an +object invalidation that marks the object as invalid in all other +sessions. This tells other sessions that they must update their cache +from the data source the next time this object is read. For a new +instance, no change notification is propagated. |Frequently read or +changed objects that contain many attributes in cases where many of the +attributes are frequently changed. +|=== + +*See Also* + +link:#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level] + +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Project_Level[Configuring +Cache Coordination Change Propagation at the Project Level] + +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache] + +=== How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java + +Use a link:#Configuring_Amendment_Methods[descriptor amendment method] +to invoke `+ClassDescriptor+` method `+setCacheSynchronizationType+` +passing in one of the following parameters: + +* `+ClassDescriptor.DO_NOT_SEND_CHANGES+` +* `+ClassDescriptor.SEND_OBJECT_CHANGES+` +* `+ClassDescriptor.SEND_NEW_OBJECTS_WITH_CHANGES+` +* `+ClassDescriptor.INVALIDATE_CHANGED_OBJECTS+` + +== Configuring Cache Expiration at the Descriptor Level + +By default, objects remain in the cache until they are explicitly +deleted (see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Deleting_Objects[Deleting +Objects]) or garbage-collected when using a weak identity map (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Isolation_at_the_Project_Level[Configuring +Cache Isolation at the Project Level]). Alternatively, you can configure +an object with a `+CacheInvalidationPolicy+` that allows you to specify, +either automatically or manually, that an object is invalid: when any +query attempts to read an invalid object, EclipseLink will go to the +data source for the most up-to-date version of that object and update +the cache with this information. + +Using cache invalidation ensures that your application does not use +stale data. It provides a better performing alternative to always +refreshing (see link:#Configuring_Cache_Refreshing[Configuring Cache +Refreshing]). + +This table summarizes which descriptors support a cache invalidation +policy. + +[#Table 115-17]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. You can override the project-level cache +invalidation configuration (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Configuring +Cache Expiration at the Project Level]) by defining cache invalidation +at the descriptor or query level (see +link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Configure_Cache_Expiration_at_the_Query_Level[How +to Configure Cache Expiration at the Query Level]). + +You can customize how EclipseLink communicates the fact that an object +has been declared invalid to improve efficiency, if you are using a +coordinated cache. For more information, see +link:#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level]. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Invalidation[Cache +Invalidation]. + +=== How to Configure Cache Expiration at the Descriptor Level Using Workbench + +To specify the cache invalidation information for a descriptor, use this +procedure: + +[arabic] +. Select the descriptor in the *Navigator*. +. Select the *Caching* tab in the *Editor*. The *Caching* tab appears. +[#Figure 115-28]##*_Caching Tab, Expiration Options_* +image:idcacexp.gif[Caching Tab, Expiration +Options,title="Caching Tab, Expiration Options"] +. Complete the Cache Expiry options on the tab. + +Use this table to enter data in the following fields on the *Caching* +tab to specify the cache invalidation policy for the descriptors. + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Field* |*Description* +|*Project Default* |Use the project’s cache expiration options for this +descriptor. See +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Configuring +Cache Expiration at the Project Level] for more information. + +|*No Expiry* |Specify that objects in the cache do not expire. + +|*Time to Live Expiry* |Specify that objects in the cache will expire +after a specified amount of time. Use the *Expire After* field to +indicate the time (in milliseconds) after which the objects will expire. + +|*Daily Expiry* |Specify that objects in the cache will expire at a +specific time each day. Use the *Expire At* field to indicate the exact +time to the second (using a 24-hour clock) at which the objects will +expire. + +|*Update Read Time on Update* |Specify if EclipseLink should reset the +cached object’s expiry time after the EclipseLink successfully updates +the object. +|=== + +[width="100%",cols="<100%",] +|=== +|*Note:* These options apply per descriptor. See +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Configuring +Cache Expiration at the Project Level] for information on configuring +project-level options. +|=== + +*See Also* + +link:#Configuring_Cache_Expiration_at_the_Descriptor_Level[Configuring +Cache Expiration at the Descriptor Level] + +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Configuring +Cache Expiration at the Project Level] + +=== How to Configure Cache Expiration at the Descriptor Level Using Java + +Use `+ClassDescriptor+` method `+setCacheInvalidationPolicy+` to set an +appropriate instance of `+CacheInvalidationPolicy+`. + +== Configuring Cache Existence Checking at the Descriptor Level + +When EclipseLink writes an object to the database, EclipseLink runs an +existence check to determine whether to perform an insert or an update. + +When using JPA, EclipseLink checks against the database by default. When +using the EclipseLink Native API it checks against the cache by default. +We recommend that you use the default existence check option for most +applications. + +This table summarizes which descriptors support existence checking. + +[#Table 115-18]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors 1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. You can configure existence checking at the +descriptor level to override the project level configuration (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Existence_Checking_at_the_Project_Level[Configuring +Existence Checking at the Project Level]). + +For more information see the following: + +* link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Queries_and_the_Cache[Queries +and the Cache] +* link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_Registration_and_Existence_Checking[How +to Use Registration and Existence Checking] + +=== How to Configure Cache Existence Checking at the Descriptor Level Using Workbench + +To specify the existence checking information for a descriptor, use this +procedure: + +[arabic] +. Select the descriptor in the *Navigator*. +. Select the *Caching* tab in the *Editor*. The Caching tab appears. +*_Caching Tab, Existence Checking Options_* image:idexichk.gif[Caching +Tab, Existence Checking +Options,title="Caching Tab, Existence Checking Options"] +. Complete the *Existence Checking* options on the tab. + +Use this table to enter data in the following fields of the tab to +specify the existence checking options for newly created descriptors: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Check Cache* |Check the session cache. If the object is not in the +cache, assume that the object does not exist (do an insert). If the +object is in the cache, assume that the object exists (do an update). We +recommend using this option for most applications. + +|*Check Cache then Database* |If an object is not in the cache, query +the database to determine if the object exists. If the object exists, do +an update. Otherwise, do an insert. Selecting this option may negatively +impact performance. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Check_Database[Using +Check Database]. + +|*Assume Existence* |Always assume objects exist: always do an update +(never do an insert). For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Existence[Using +Assume Existence]. + +|*Assume Non-Existence* |Always assume objects do not exist: always do +an insert (never do an update). For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Nonexistence[Using +Assume Nonexistence]. +|=== + +=== How to Configure Cache Existence Checking at the Descriptor Level Using Java + +To configure existence checking at the descriptor level using Java, use +`+ClassDescriptor+` method `+getQueryManager+` to acquire the +`+DescriptorQueryManager+` from the descriptor and then use one of the +following `+DescriptorQueryManager+` methods (see the +link:#Example_115-8[Configuring Existence Checking Using Java] example): + +* `+checkCacheForDoesExist+` – check the session cache. If the object is +not in the cache, assume that the object does not exist (do an insert). +If the object is in the cache, assume that the object exists (do an +update). We recommend using this option for most applications. +* `+checkDatabaseForDoesExist+` – if an object is not in the cache, +query the database to determine if the object exists. If the object +exists, do an update. Otherwise, do an insert. Selecting this option may +negatively impact performance. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Check_Database[Using +Check Database]. +* `+assumeExistenceForDoesExist+` – always assume objects exist: always +do an update (never do an insert). For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Existence[Using +Assume Existence]. +* `+assumeNonExistenceForDoesExist+` – always assume objects do not +exist: always do an insert (never do an update). For more information, +see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Nonexistence[Using +Assume Nonexistence]. + +[#Example 115-8]## *_Configuring Existence Checking Using Java_* + +`+descriptor.getQueryManager().checkCacehForDoesExist();+` + +== Configuring Reading Subclasses on Queries + +If you are mapping an inheritance hierarchy, by default, queries on root +or branch classes return instances of the root class and their +subclasses. + +Alternatively, you can configure a root or branch class descriptor to do +the following: + +* not include subclasses when the root or branch class is queried; +* outer-join subclasses when the root or branch class is queried. + +You can also specify a database view to optimize the reading of +subclasses. The view can be used to optimize queries for root or branch +classes that have subclasses spanning multiple tables. The view must +apply an outer-join or union all of the subclass tables. + +Do not configure this option for leaf classes. + +This table summarizes which descriptors support inherited attribute +mapping configuration. + +[#Table 115-19]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +=== How to Configure Reading Subclasses on Queries Using Workbench + +To configure reading classes on subqueries, use this procedure: + +[arabic] +. In the *Navigator*, select a root or branch descriptor.If the +*Inheritance* advanced property is not visible for the descriptor, +right-click the descriptor and choose *Select Advanced Properties* > +*Inheritance* from context menu or from the *Selected* menu. +. Click the *Inheritance* tab. *_Inheritance Tab, Read Subclasses on +Query Option_* image:inhrqury.gif[Inheritance Tab, Read Subclasses on +Query Option,title="Inheritance Tab, Read Subclasses on Query Option"] +. Enter data in the Read Subclasses on Query section on the +*Inheritance* tab. + +Use the following information to enter data in Read Subclasses on Query +and Read Subclasses View fields of the tab: + +[width="100%",cols="<21%,<79%",options="header",] +|=== +|*Field* |*Description* +|*Read Subclasses on Query* |Select this option to configure the root +class descriptor to instantiate a subclass when the root class is +queried. + +|*Read Subclasses View* |Optionally select a database view to use for +reading subclasses. + +|*Outer Join All Subclasses* |Optionally use the +`+outerJoinAllSubclsses+` option to optimize the query. +|=== + +*See Also* + +link:#Configuring_Reading_Subclasses_on_Queries[Configuring Reading +Subclasses on Queries] + +=== How to Configure Reading Subclasses on Queries Using Java + +Create a link:#Configuring_Amendment_Methods[descriptor amendment +method] to customize the root or branch class descriptor’s +`+InheritancePolicy+`. + +This example shows an amendment method for the `+Person+` class. In this +example, you use the `+InheritancePolicy+` method +`+dontReadSubclassesOnQueries+` to configure the descriptor so that +subclasses are not read on queries. + +[#Example 115-9]## *_Configuring Reading Subclasses on Queries_* + +`+...+` +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().dontReadSubclassesOnQueries();+` +`+}+` `+...+` + +This example shows an amendment method for the `+Person+` class. In this +example, you use the `+InheritancePolicy+` method +`+setReadAllSubclassesViewName+` to optimize multiple table inheritance +queries. + +[#Example 115-10]## *_Configuring Reading Subclasses on Queries Using a +View Name_* + +`+...+` +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setReadAllSubclassesViewName(myView);+` +`+}+` `+...+` + +This example shows an amendment method for the `+Person+` class. In this +example, you use the `+InheritancePolicy+` method +`+setShouldOuterJoinSubclasses+` to configure the descriptor so that +subclasses are outer-joined on queries. + +[#Example 115-11]## *_Configuring Outer-Joining Subclasses on Queries_* + +`+...+` +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setShouldOuterJoinSubclasses(true);+` +`+}+` `+...+` + +== Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor + +Inheritance describes how a derived (child) class inherits the +characteristics of its superclass (parent). When you designate a class +as a child, you must also specify the descriptor that represents the +child’s parent in your inheritance hierarchy. + +This table summarizes which descriptors support child inheritance +configuration. + +[#Table 115-20]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For more information about inheritance, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +For more information about configuring inheritance for a parent (root) +class descriptor, see +link:#Configuring_Inheritance_for_a_Parent_(Root)_Descriptor[Configuring +Inheritance for a Parent (Root) Descriptor]. + +=== How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Workbench + +To create a child (branch or leaf class) for an inheritance, use this +procedure. + +[arabic] +. In the *Navigator*, select the descriptor you wish to specify as a +child. +. Choose the *Inheritance* tab in the *Property* window.If the +*Inheritance* tab is not visible, right-click the descriptor and choose +*Select Advanced Properties* > *Inheritance*. +. Select the *Is Child Descriptor* option to specify this descriptor is +a child class. The *Parent Descriptor* list is now enabled and the class +indicator information is disabled. *_Inheritance Tab, Child Descriptor +Option_* image:inhbr_lf.gif[Inheritance Tab, Child Descriptor +Option,title="Inheritance Tab, Child Descriptor Option"] +. Complete each child descriptor option on the Inheritance tab. + +Use the following information to enter data in each child descriptor +field on the tab: + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Field* |*Description* +|*Is Child Descriptor* |Specify that this descriptor is a child class to +be used in a branch or leaf. + +|*Parent Descriptor* |Use the list to select the parent of this +descriptor. See +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] for more information. +|=== + +*See Also* + +link:#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class +Descriptor]link:#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor] + +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] + +=== How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java + +Using Java, you can configure an inheritance child descriptor using +`+InheritancePolicy+` method `+setParentClass+`, as this example shows. + +[#Example 115-12]## *_Configuring an Inheritance Child Descriptor_* + +`+descriptor.getInheritancePolicy().setParentClass(ChildClass.class);+` + +== Configuring Inheritance for a Parent (Root) Descriptor + +Inheritance describes how a derived (child) class inherits the +characteristics of its superclass (parent). When you designate a class +as a parent, you can configure how EclipseLink handles the class’s +inheritance hierarchy. + +The following table summarizes which descriptors support parent +inheritance configuration. + +[#Table 115-21]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For more information about configuring inheritance for a child (branch +or leaf) class descriptor, see +link:#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor]. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +=== How to Configure Inheritance for a Parent (Root) Descriptor Using Workbench + +To create a root class for an inheritance, use this procedure. + +[arabic] +. In the *Navigator*, select the descriptor you wish to specify as the +root. +. Choose the *Inheritance* tab in the *Property* window.If the +*Inheritance* tab is not visible, right-click the descriptor and choose +*Select Advanced Properties* > *Inheritance*. +. Select the *Is Root Parent Descriptor* option to specify this +descriptor is a root class. [#Figure 115-32]##*_Inheritance Tab, +Configuring Inheritance for a Root Descriptor_* +image:didoeis.gif[Inheritance Tab, Configuring Inheritance for a Root +Descriptor,title="Inheritance Tab, Configuring Inheritance for a Root Descriptor"] +. Complete each root descriptor option on the Inheritance tab. + +Use this table to complete the following root descriptor field on the +Inheritance tab: + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Field* |*Description* +|*Is Root Parent Descriptor* |Select this option to specify this +descriptor as the root (parent) of the inheritance hierarchy. + +|*Use Class Extraction Method* |Choose this option to specify a class +indicator using a class extraction method, and select your static class +extraction method from the list. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Extraction_Methods[Using +Class Extraction Methods]. + +|*Use Class Indicator Field* |Choose this option to specify a class +indicator using a class indicator field. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Indicator_Fields[Using +Class Indicator Fields]. + +|*Field Selection* |Choose the field to use as the class indicator +field. + +|*Use XML Schema "`Type`" Attribute*1 |Select this option to use the +type attribute specified in the XML schema for this descriptor’s +reference class. + +|*Specify Field* |For a relational descriptor, select the field of the +database table associated with this descriptor (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]). For an EIS root descriptor (using XML records) or +an XML descriptor, click *Browse* to select an element attribute or text +node. + +|*Indicator Selection* |Choose between using a class name as the class +indicator field value or specifying specific class indicator field +values for each (nonabstract) child class. + +|*Use Class Name as Indicator* |Choose this option to use class names as +the class indicator field value. + +|*Use Class Indicator Dictionary* |Choose this option to specify +specific class indicator field values for each (nonabstract) child +class. When you choose this option, you must specify the data type of +the class indicator field and the specific class indicator field values +for each (nonabstract) child class. + +|*Indicator Type* |Select the data type from the list to specify the +data type of the class indicator field. To specify the specific class +indicator field values for each (nonabstract) child class, click *Edit* +and enter the appropriate value for each child class. +|=== + +1EIS root (see +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors]) or XML descriptors (see +link:Introduction%20to%20XML%20Descriptors%20(ELUG)#XML_Descriptor_Concepts[XML +Descriptor Concepts]) only. + +=== How to Configure Inheritance for a Parent (Root) Descriptor Using Java + +Create a link:#Configuring_Amendment_Methods[descriptor amendment +method] to customize the root class descriptor’s inheritance policy +using `+InheritancePolicy+` methods `+setParentClass+`, +`+setClassIndicatorFieldName+`, `+addClassIndicator+`, +`+useClassNameAsIndicator+` and `+setClassExtractionMethodName+`, as +required. + +The following example shows amendment methods for the `+Person+` and +`+Student+` classes where `+Student+` extends `+Person+` in a relational +project. In this example, a class indicator field is used (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Indicator_Fields[Using +Class Indicator Fields]). + +[#Example 115-13]## *_Configuring Inheritance for a Relational Root +Class_* + +`+...+` +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setClassIndicatorFieldName("CLIENT_TYPE");+` +`+    descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);+` +`+}+` + +`+public static void addToStudentDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setParentClass(Person.class);+` +`+}+` `+...+` + +If you are using a class-extraction method (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Extraction_Methods[Using +Class Extraction Methods]), you may also need to use +`+InheritancePolicy+` methods `+setOnlyInstancesExpression+` and +`+setWithAllSubclassesExpression+` (see +link:#Configuring_Inheritance_Expressions_for_a_Parent_(Root)_Class_Descriptor[Configuring +Inheritance Expressions for a Parent (Root) Class Descriptor]). + +The following example shows amendment methods for the `+Person+` and +`+Student+` classes where `+Student+` extends `+Person+` in an EIS +project using XML records. In this example, a class indicator field is +used (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Indicator_Fields[Using +Class Indicator Fields]). + +[#Example 115-14]## *_Configuring Inheritance for an EIS Root Class_* + +`+...+` +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setClassIndicatorField(new XMLField("@CLIENT_TYPE"));+` +`+    descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);+` +`+}+` + +`+public static void addToStudentDescriptor(Descriptor descriptor) {+` +`+    descriptor.getInheritancePolicy().setParentClass(Person.class);+` +`+    descriptor.getInheritancePolicy().setClassIndicatorField(new XMLField("@CLIENT_TYPE"));+` +`+}+` `+...+` + +== Configuring Inheritance Expressions for a Parent (Root) Class Descriptor + +If your class uses inheritance (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]) with a class extraction method (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Extraction_Methods[Using +Class Extraction Methods]) you must provide EclipseLink with expressions +to correctly filter sibling instances for all classes that share a +common table. + +This table summarizes which descriptors support inheritance expression +configuration. + +[#Table 115-22]## + +Descriptor + +How to Use Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +The link:#Figure_115-33[Example Inheritance Hierarchy] figure shows a +typical inheritance hierarchy. In this example, instances of both +`+Person+` and `+Student+` are stored in the same `+PERSON+` table, as +the link:#Figure_115-34[PERSON Table] figure shows: an instance of +`+Person+` has a `+null+` value for `+STUDENT_NUMBER+`. Instances of +`+Company+` are stored in a separate `+COMPANY+` table. + +[#Figure 115-33]## *_Example Inheritance Hierarchy_* + +.Example Inheritance Hierarchy +image::isinst.gif[Example Inheritance +Hierarchy,title="Example Inheritance Hierarchy"] + +[#Figure 115-34]## *_PERSON Table_* + +.PERSON Table +image::perstbl.gif[PERSON Table,title="PERSON Table"] + +Queries on inheritance classes that share a common table, such as +`+Person+` and `+Student+`, must filter out their sibling instances. +EclipseLink performs this filtering using the `+Expression+` instances +returned by the descriptor’s `+InheritancePolicy+` methods +`+getOnlyInstancesExpression+` and `+getWithAllSubclassesExpression+`. + +Queries on a class that has its own table for its specific data, such as +`+Company+`, and does not share this table with any sibling classes, do +not require these expressions. + +If you use a class indicator type field (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Indicator_Fields[Using +Class Indicator Fields]), EclipseLink automatically generates the +required expressions. + +If you use a class extraction method (see +link:Introduction%20to%20Descriptors%20(ELUG)#Using_Class_Extraction_Methods[Using +Class Extraction Methods]), you must provide EclipseLink with an +expressions to correctly filter sibling instances for all classes that +share a common table. + +For concrete classes, you must define an only- instances expression. + +For branch classes, you must define a with-all-subclasses expression. + +When EclipseLink queries for a leaf class, it uses the only- instances +expression to filter out any sibling classes. + +When EclipseLink queries for a root or branch class whose subclasses do +not define their own tables, it uses the with-all-subclasses expression. +This is also the case when a subclass view is used (see +link:#Configuring_Reading_Subclasses_on_Queries[Configuring Reading +Subclasses on Queries]). + +When querying for a root or branch class that has subclasses that span +multiple tables, a query is performed for each concrete class in the +inheritance hierarchy using the only- instances expression to filter +sibling classes. + +When a class extraction method is used the only-instances expression is +used to determine if a class is concrete. If a class does not require an +only instances expression, do not enable reading subclasses on queries +(see link:#Configuring_Reading_Subclasses_on_Queries[Configuring Reading +Subclasses on Queries]), otherwise EclipseLink will assume that the +class has no instances and it will skip that class on queries. + +For more information about inheritance expressions, see +link:Introduction%20to%20Descriptors%20(ELUG)#Specifying_Expressions_for_Only-Instances_and_With-All-Subclasses[Specifying +Expressions for Only-Instances and With-All-Subclasses]. + +=== How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java + +Create a link:#Configuring_Amendment_Methods[descriptor amendment +method] to customize the root class descriptor’s `+InheritancePolicy+` +using `+InheritancePolicy+` methods `+setOnlyInstancesExpression+` and +`+setWithAllSubclassesExpression+`, as required. + +This example shows amendment methods for the `+Person+` and `+Student+` +descriptors based on the class hierarchy shown in the +link:#Figure_115-33[Example Inheritance Hierarchy] figure and the +database table shown in the link:#Figure_115-34[PERSON Table] figure. + +[#Example 115-15]## *_Configuring Only-Instances Expressions_* + +`+...+` +*`+//\'\' \'\'Only-instances\'\' \'\'expression\'\' \'\'for\'\' \'\'Person+`* +`+public static void addToPersonDescriptor(Descriptor descriptor) {+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    descriptor.getInheritancePolicy().setOnlyInstancesExpression(+` +`+                              builder.getField("STUDENT_NUMBER").isNull());+` +`+}+` + +*`+//\'\' \'\'Only-instances\'\' \'\'expression\'\' \'\'for\'\' \'\'Student+`* +`+public static void addToStudentDescriptor(Descriptor descriptor) {+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    descriptor.getInheritancePolicy().setOnlyInstancesExpression(+` +`+                              builder.getField("STUDENT_NUMBER").notNull());+` +`+}+` `+...+` + +The link:#Example_115-16[Configuring Only-Instances and +With-All-Subclasses Expressions] example shows amendment methods for the +`+Bicycle+` and `+NonFueledVehicle+` descriptors based on the class +hierarchy shown in link:Introduction%20to%20Descriptors%20(ELUG)[Figure +14-1] if the vehicle hierarchy stored all of the classes in a single +vehicle table, and there was not a class indicator, but a class +extraction method instead. + +[#Example 115-16]## *_Configuring Only-Instances and With-All-Subclasses +Expressions_* + +*`+//\'\' \'\'Bicycle\'\' \'\'amemndment+`* +`+public static void addToBicycleDescriptor(Descriptor descriptor) {+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    descriptor.getInheritancePolicy().setOnlyInstancesExpression(+` +`+                              builder.getField("BICYCLE_DESCR").notNull());+` +`+}+` + +*`+//\'\' \'\'NonFueldVehicle\'\' \'\'ammendment+`* +`+public static void addToNonFueledVehicleDescriptor(Descriptor descriptor) {+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    descriptor.getInheritancePolicy().setWithAllSubclassesExpression(+` +`+                                    builder.getField("FUEL_TYPE").isNull());+` +`+}+` + +== Configuring Inherited Attribute Mapping in a Subclass + +If you are defining the descriptor for a class that inherits attributes +from another class, then you can create mappings for those attributes. +If you remap an attribute that was already mapped in the superclass, +then the new mapping applies to the subclass only. Any other siblings +that inherit the attribute are unaffected. + +If you leave inherited attributes unmapped, EclipseLink uses the mapping +(if any) from the superclass if the superclass’s descriptor has been +designated as the parent descriptor. + +This table summarizes which descriptors support inherited attribute +mapping configuration. + +[#Table 115-23]## *_Descriptor Support for Inherited Attribute Mapping +Configuration_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +=== How to Configure Inherited Attribute Mapping in a Subclass Using Workbench + +To map inherited attributes, use this procedure: + +[arabic] +. In the *Navigator*, right-click a descriptor and choose *Map Inherited +Attributes* > _selected class_ from the context menu or choose +*Selected* > *Map Inherited Attributes* from the menu.The mappings list +now includes all the attributes from the superclass of this class. +. Map any desired attributes. See +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping] for more +information. + +=== How to Configure Inherited Attribute Mapping in a Subclass Using Java + +Using Java, attributes inherited by a subclass from a superclass will be +visible and you can always create a mapping to these inherited +attributes. + +== Configuring a Domain Object Method as an Event Handler + +You can associate a domain object method with any of the descriptor +events shown in the link:#Table_115-25[Descriptor Events] table. You can +register any domain object method that complies with the following +criteria: + +* Is public. +* Returns void. +* Takes a single parameter of type `+DescriptorEvent+` + +This table summarizes which descriptors support domain object method +event handler configuration. + +[#Table 115-24]## *_Descriptor Support for Domain Object Method Event +Handler Configuration_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For example, you can add a method `+handlePostDelete+` (that is public, +returns void, and takes a single parameter of type `+DescriptorEvent+`) +to your `+Employee+` object to handle `+PostDeleteEvent+` descriptor +events. After you register that method with the +`+DescriptorEventManager+` owned by the `+Employee+` object’s descriptor +as the handler for `+PostDeleteEvent+` descriptor events, whenever the +EclipseLink runtime performs a post-delete operation on an instance of +the `+Employee+` object, the runtime dispatches a `+PostDeleteEvent+` to +the `+handlePostDelete+` method on the instance of the `+Employee+` +object associated with that `+PostDeleteEvent+`. + +The *Descriptor Event ID* column in the link:#Table_115-25[Descriptor +Events] table lists the `+DescriptorEventManager+` field name used to +identify a particular event. The `+DescriptorEvent+` method +`+getEventCode+` returns this value. For example: + +`+if (descriptorEvent.getEventCode() == DescriptorEventManager.PreUpdateEvent) {+` +`+    +`*`+//\'\' \'\'descriptorEvent\'\' \'\'represents\'\' \'\'a\'\' \'\'pre-update\'\' \'\'event+`* +`+}+` + +[#Table 115-25]## *_Descriptor Events_* + +Category + +Descriptor Event ID + +Description + +Delete + +PreDeleteEvent + +Occurs before an object is deleted from the data source. + +AboutToDeleteEvent + +Occurs when an object is deleted from the data source. + +PostDeleteEvent + +Occurs after an object is deleted from the data source. + +Insert + +PreInsertEvent + +Occurs before an object is inserted in the data source. + +AboutToInsertEvent + +Occurs when an object is inserted in the data source. + +PostInsertEvent + +Occurs after an object is inserted into the data source. + +Post-X + +PostBuildEvent + +Occurs after an object is built from the data source. + +PostCloneEvent + +Occurs after an object has been cloned into a unit of work. + +PostMergeEvent + +Occurs after an object has been merged from a unit of work. + +PostRefreshEvent + +Occurs after an object is refreshed from the data source. + +Update + +PreUpdateEvent + +Occurs before an object is updated in the data source. This may be +called in a unit of work even if the object has no changes and does not +require updating. + +AboutToUpdateEvent + +Occurs when an object is updated in the data source. This method is +called only if the object has changes in the unit of work. + +PostUpdateEvent + +Occurs after an object is updated in the data source. + +Write + +PreWriteEvent + +Occurs before an object is inserted or updated in the data source. This +occurs before PreInsertEvent and PreUpdateEvent. + +PostWriteEvent + +Occurs after an object is inserted or updated in the data source. This +occurs after PostInsertEvent and PostUpdateEvent. + +Alternatively, you can configure a descriptor event listener as an event +handler (see +link:#Configuring_a_Descriptor_Event_Listener_as_an_Event_Handler[Configuring +a Descriptor Event Listener as an Event Handler]). + +=== How to Configure a Domain Object Method as an Event Handler Using Workbench + +To select event methods, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor.If the *Events* advanced property is not visible for the +descriptor, then right-click the descriptor and choose *Select Advanced +Properties* > *Events* from context menu or from the *Selected* menu. +. Click the *Event* tab in the *Editor*. [#Figure 115-35]##*_Events +Tab_* image:descevt.gif[Description of +follows,title="Description of follows"] +. Select the appropriate method category from the list on the left. +. Choose the appropriate domain object method for each method in that +category. + +Use this table to enter data in the following fields to select the +appropriate domain object method: + +Category + +Option + +Description + +Deleting Methods + +Pre + +Select the domain object method that is invoked on an instance of its +reference class before the instance is deleted from the data source. + +Post + +Select the domain object method that is invoked on an instance of its +reference class after the instance is deleted from the data source. + +Inserting Methods + +Pre + +Select the domain object method that is invoked on an instance of its +reference class before the instance is inserted in the data source. + +About To + +Select the domain object method that is invoked on an instance of its +reference class when the instance is inserted in the data source. + +Post + +Select the domain object method that is invoked on an instance of its +reference class after the instance is inserted into the data source. + +Post-X Methods + +Build + +Select the domain object method that is invoked on an instance of its +reference class after the instance is built from the data source. + +Clone + +Select the domain object method that is invoked on an instance of its +reference class after the instance is cloned into a unit of work. + +Merge + +Select the domain object method that is invoked on an instance of its +reference class after the instance is merged from a unit of work. + +Refresh + +Select the domain object method that is invoked on an instance of its +reference class after the instance is refreshed from the data source. + +Updating Methods + +Pre + +Select the domain object method that is invoked on an instance of its +reference class before the instance is updated in the data source. This +may be called in a unit of work even if the object has no changes and +does not require updating. + +About to + +Select the domain object method that is invoked on an instance of its +reference class when the instance is updated in the data source. This +method is called only if the object has changes in the unit of work. + +Post + +Select the domain object method that is invoked on an instance of its +reference class after the instance is updated in the data source. + +Writing Methods + +Pre + +Select the domain object method that is invoked on an instance of its +reference class before the instance is inserted or updated in the data +source. Note: This occurs before Pre-Insert and Pre-Update event methods +are invoked. + +Post + +Select the domain object method that is invoked on an instance of its +reference class after the instance is inserted or updated in the data +source. Note: This occurs after Post-Insert or Post-Update event methods +are invoked. + +=== How to Configure a Domain Object Method as an Event Handler Using Java + +The link:#Example_115-17[Domain Object Method as a Descriptor Event +Handler] example shows a domain object class with method +`+handlePostDelete+` defined to handle `+PostDeleteEvent+` descriptor +events. The link:#Example_115-18[Registering a Domain Object Method as a +Descriptor Event Handler] example shows how to register this method as +the `+PostDeleteEvent+` event handler. Whenever the EclipseLink runtime +performs a post-delete operation on an instance of `+Employee+`, the +runtime will dispatch a `+PostDeleteEvent+` to the +`+DescriptorEventManager+` owned by the `+Employee+` object’s +descriptor. The `+DescriptorEventManager+` will then invoke the +`+handlePostDelete+` method on the instance of `+Employee+` associated +with that `+PostDeleteEvent+`. + +[#Example 115-17]## *_Domain Object Method as a Descriptor Event +Handler_* + +`+public class Employee {+` +`+    +`*`+//\'\' \'\'domain\'\' \'\'object\'\' \'\'methods+`* +`+    ...+` +`+    public void handlePostDelete(DescriptorEvent event) {+` +`+        +`*`+//\'\' \'\'handler\'\' \'\'implementation+`* `+    }+` +`+}+` + +[#Example 115-18]## *_Registering a Domain Object Method as a Descriptor +Event Handler_* + +`+employeeDescriptor.getEventManager().setPostDeleteSelector("handlePostDelete");+` + +== Configuring a Descriptor Event Listener as an Event Handler + +You can create your own `+DescriptorEventListner+` and register it with +a `+DescriptorEventManager+` in a descriptor amendment method. You can +also configure a `+DescriptorEventListner+` to be notified of events +through the Java event model. + +You can register any object that implements the +`+DescriptorEventListener+` interface with the +`+DescriptorEventManager+` owned by a domain object’s descriptor to +handle any descriptor event type (see the link:#Table_115-27[Descriptor +Events] table). To quickly implement this interface, you can extend +abstract class `+DescriptorEventAdapter+` and override only the methods +for the events you are interested in. + +This table summarizes which descriptors support descriptor event +listener configuration. + +[#Table 115-26]## *_Descriptor Support for Descriptor Event Listener +Configuration_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For example, you create a `+DescriptorEventListener+` to handle +`+PostBuildEvent+` descriptor events for `+Employee+` objects. After you +register this `+DescriptorEventListener+` with the +`+DescriptorEventManager+` owned by the `+Employee+` object’s +descriptor, whenever the EclipseLink runtime performs a post-build +operation on an instance of `+Employee+`, the runtime dispatches a +`+PostBuilEvent+` to the event listener’s `+postBuild+` method. + +The link:#Table_115-27[Descriptor Events] table lists the +`+DescriptorEventListener+` methods associated with each descriptor +event. The *Descriptor Event Listener Method* column lists the +`+DescriptorEventListener+` methods associated with each +`+DescriptorEvent+`. + +[#Table 115-27]## *_Descriptor Events_* + +Category + +Descriptor Event Listener Method + +Description + +Delete + +preDelete + +Occurs before an object is deleted from the data source. + +aboutToDelete + +Occurs when an object is deleted from the data source. + +postDelete + +Occurs after an object is deleted from the data source. + +Insert + +preInsert + +Occurs before an object is inserted in the data source. + +aboutToInsert + +Occurs when an object is inserted in the data source. + +postInsert + +Occurs after an object is inserted into the data source. + +Post-X + +postBuild + +Occurs after an object is built from the data source. + +postClone + +Occurs after an object has been cloned into a unit of work. + +postMerge + +Occurs after an object has been merged from a unit of work. + +postRefresh + +Occurs after an object is refreshed from the data source. + +Update + +preUpdate + +Occurs before an object is updated in the data source. This may be +called in a unit of work even if the object has no changes and does not +require updating. + +aboutToUpdate + +Occurs when an object is updated in the data source. This method is +called only if the object has changes in the unit of work. + +postUpdate + +Occurs after an object is updated in the data source. + +Write + +preWrite + +Occurs before an object is inserted or updated in the data source. This +occurs before PreInsertEvent and PreUpdateEvent. + +postWrite + +Occurs after an object is inserted or updated in the data source. This +occurs after PostInsertEvent and PostUpdateEvent. + +Alternatively, you can configure a domain object method as an event +handler (see +link:#Configuring_a_Domain_Object_Method_as_an_Event_Handler[Configuring +a Domain Object Method as an Event Handler]). + +=== How to Configure a Descriptor Event Listener as an Event Handler Using Workbench + +For more information, see +link:#How_to_Configure_a_Domain_Object_Method_as_an_Event_Handler_Using_Workbench[Using +the Workbench]. + +=== How to Configure a Descriptor Event Listener as an Event Handler Using Java + +The link:#Example_115-19[DescriptorEventListener] example shows a +`+DescriptorEventListener+` that handles `+PostBuildEvent+` descriptor +events. The link:#Example_115-20[Registering a DescriptorEventListener +with the DescriptorEventManager] example shows how to register this +`+DescriptorEventListener+` with the `+Employee+` object’s descriptor. +Whenever the EclipseLink runtime performs a post-build operation on an +instance of `+Employee+`, the runtime will dispatch a post build event +to the corresponding `+DescriptorEventListener+` method on each +registered event listener (in this case, it calls the `+postBuild+` +method). + +[#Example 115-19]## *_DescriptorEventListener_* + +`+public class MyDescriptorEventListener extends DescriptorEventAdapter {+` + +`+    public void postBuild(DescriptorEvent event) {+` +`+        +`*`+//\'\' \'\'handler\'\' \'\'implementation+`* `+    }+` +`+}+` + +[#Example 115-20]## *_Registering a DescriptorEventListener with the +DescriptorEventManager_* + +`+descriptor.getEventManager().addListener(new MyDescriptorEventListener());+` + +== Configuring Locking Policy + +You can configure a descriptor with a locking policy that prevents one +user writing over another user’s work. + +This table summarizes which descriptors support locking policies. + +[#Table 115-28]## *_Descriptor Support for Locking Policy_* + +Descriptor + +Optimistic Version Locking Policies + +Optimistic Field Locking Policies + +Pessimistic Locking Policy + +Using the Workbench + +Using Java + +Relational Descriptors1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. We recommend that you use a locking policy. You +should use a locking policy in any multiuser environment to prevent one +user writing over another user’s changes. Although locking can be +particularly important if multiple servers or multiple applications +access the same data, even in a single server application, the same +locking issue still exists. In a multiple-server environment, locking is +still relevant even if your application uses cache refreshing or cache +coordination. + +If you are building a three-tier application, in order to correctly lock +an object, you must obtain the lock before the object is sent to client +to be edited. The type of locking you choose has an influence on how you +can achieve this (see +link:Introduction%20to%20Descriptors%20(ELUG)#Locking_in_a_Three-Tier_Application[Locking +in a Three-Tier Application]). + +=== How to Configure Locking Policy UsingWorkbench + +To specify a descriptor’s locking policy, use this procedure: + +[arabic] +. In the *Navigator*, select a relational or EIS root descriptor.If the +*Locking* advanced property is not visible for the descriptor, +right-click the descriptor and choose *Select Advanced Properties* *>* +*Locking* from the context menu or from the *Selected* menu. +. Click the *Locking* tab. *_Locking Tab for a Descriptor_* +image:rellock.gif[Locking Tab for a +Descriptor,title="Locking Tab for a Descriptor"] ++ +*** Locking Tab for an EIS Root Descriptor*** image:eislock.gif[Locking +Tab for an EIS Root +Descriptor,title="Locking Tab for an EIS Root Descriptor"] +. Enter data in each field on the Locking tab. + +Use this table to enter data in the following fields on the tab of the +appropriate type: + +Field + +Description + +Optimistic Locking + +Specify that the descriptor uses optimistic locking. + +By Version + +Specify to use optimistic locking, based on versioning. + +Database Field + +Select the database field that contains the version value used for +optimistic locking. This field appears for relational descriptors only. + +XPath + +Click Browse to define the path to the element or attribute that stores +the version value. This field appears for EIS root descriptors +only.Ensure that the attribute’s type corresponds to the type of locking +policy you choose (numeric for Version Locking and timestamp for +Timestamp Locking). + +Version Locking + +Specify that the descriptor uses numeric version locking. The version +field (defined by the Database Field, for relational descriptors, or the +XPath, for EIS root descriptors) must be a numeric type + +Timestamp Locking + +Specify that the descriptor uses time stamp version locking, based on +time stamp. The version field (defined by the Database Field, for +relational descriptors, or the XPath, for EIS root descriptors) must be +a timestamp type. + +Store Version in Cache + +Specify whether or not you want to store the version information in the +cache. If you choose not to define a mapping for the version field, then +you must enable this option to configure the descriptor to store the +version value in the EclipseLink cache. + +If you choose to define a mapping for the version field, then you must +disable this option in order to store the version value in the object. +For more information, see Optimistic Locking in a Three-Tier +Application. + +By Fields 1 + +Specify to use optimistic locking, based on database fields. These +fields appear for relational descriptors only. + +All Fields + +Select all fields for optimistic locking. + +Changed Fields + +Select only the changed fields for optimistic locking. + +Selected Fields + +Click Add to select specific database fields for optimistic locking. + +Pessimistic Locking + +Ignore this option as it is EJB CMP-specific. + +Wait for Lock + +Ignore this option as it is EJB CMP-specific. + +1 You cannot use field locking with the +`+AttributeChangeTrackingPolicy+` (see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Attribute_Change_Tracking_Policy[Attribute +Change Tracking Policy]). + +=== How to Configure Locking Policy Using Java + +This section describes the following: + +* link:#Configuring_an_Optimistic_Locking_Policy[Configuring an +Optimistic Locking Policy] +* link:#Configuring_Optimistic_Locking_Policy_Cascading[Configuring +Optimistic Locking Policy Cascading] + +==== Configuring an Optimistic Locking Policy + +Use the `+ClassDescriptor+` method `+setOptimisticLockingPolicy+` to set +an instance of the appropriate optimistic field locking policy: + +* `+AllFieldsLockingPolicy+` +* `+ChangedFieldsLockingPolicy+` +* `+SelectedFieldsLockingPolicy+` +* `+VersionLockingPolicy+` +* `+TimestampLockingPolicy+` + +Use the `+ClassDescriptor+` method `+getOptimisticLockingPolicy+` to get +the selected locking policy type and configure it. + +==== Configuring Optimistic Locking Policy Cascading + +If you are using a `+VersionLockingPolicy+`, you can enable cascading to +configure EclipseLink to automatically force a version field update on a +parent object when its privately owned child object’s version field +changes. Use `+VersionLockingPolicy+` method `+setIsCascaded+` passing +in a `+boolean+` of `+true+` to enable cascading, or `+false+` to +disable cascading. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Optimistic_Version_Locking_Policies_and_Cascading[Optimistic +Version Locking Policies and Cascading]. + +== Configuring Returning Policy + +Using a `+ReturningPolicy+`, you can obtain field values from the data +source when inserting or updating an object. EclipseLink uses the values +that the data source returns to update the object attributes that map to +these fields. You can specify which fields to return for inserts and +updates. For insert fields, you can also specify whether or not to +include the field value in the insert operation. + +A `+ReturningPolicy+` is useful when the data source provides default or +initial field values through defaults, triggers, or stored procedures. +You can also use a `+ReturningPolicy+` to allow the data source to +assign a sequence or primary key value. + +Any object attribute that you do not configure in a descriptor’s +`+ReturningPolicy+` receives the default behavior: in the context of a +unit of work, if the attribute has changed, its value is written to the +database. If the SQL statement invokes a trigger or stored procedure +that modifies the database field, the database generated value is not +reflected by the object. + +Use caution when deciding on whether or not to use a +`+ReturningPolicy+`, as doing so may effect insert or update performance +and is not compatible with batch writing (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Batch_Writing_for_Optimization[How +to Use Batch Writing for Optimization]). + +By default, you can use a `+ReturningPolicy+` with an Oracle Database, +in which case, EclipseLink uses the Oracle `+RETURNING+` clause (see +link:#How_to_Configure_Returning_Policy_Using_Workbench[Using +Workbench]). + +You can use a `+ReturningPolicy+` with a non-Oracle database if you +configure your descriptor’s insert or update query to use a stored +procedure that returns the desired returned values as output parameters +(see link:#How_to_Configure_Returning_Policy_Using_Java[Using Java]). + +This table summarizes which descriptors support returning policy +configuration. + +[#Table 115-29]## *_Descriptor Support for Fetch Group Configuration_* + +Descriptor + +Using Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors1 + +XML Descriptors + +1link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. + +=== How to Configure Returning Policy Using Workbench + +To specify the return policy for a descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor.If the *Returning* advanced property is not visible for the +descriptor, right-click the descriptor and choose *Select Advanced +Properties* > *Returning* from the context menu or from the *Selected* +menu. +. Click the *Returning* tab in the *Editor*. *_Returning Tab_* +image:rettab.gif[Returning Tab,title="Returning Tab"] +. Complete the insert and update policies of the Returning tab. + +Use the following information to enter data in each field on the tab: + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*Field* |*Description* +|*Insert* |These options apply to insert operations: + +|*Name* |Click *Add* to add a database field to this `+ReturningPolicy+` +for insert operations. + +|*Return-only* |When selected, EclipseLink only returns a value for this +field; it will not include the field in the insert. When not selected, +EclipseLink returns a value for this field and includes the value in the +insert. + +|*Update* |These options apply to update operations: + +|*Name* |Click *Add* to add a database field to this `+ReturningPolicy+` +for update operations +|=== + +To remove a database field from the descriptor’s `+ReturningPolicy+`, +select the field in the *Insert* or *Update* window and click *Remove*. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using Workbench, you cannot configure a returning +policy for an attribute mapped with a transformation mapping (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping]). +|=== + +=== How to Configure Returning Policy Using Java + +You use a `+ReturningPolicy+` to configure how EclipseLink handles +returning with the attributes of an object on a field-by-field basis. +This table describes the `+ReturnPolicy+` methods you use to tell +EclipseLink how to handle a particular database field. Each method takes +a `+String+` or a `+DatabaseField+` type parameter as field name. + +[#Table 115-30]## *_Return Policy Methods_* + +[width="100%",cols="<21%,<25%,<29%,<25%",options="header",] +|=== +|*Method* |*Applies to SQL Statements of Type…* |*Writes Current Value +of Field to Database?* |*Returns Database- Generated Result?* +|`+addFieldForInsert+` |INSERT |Yes |Yes + +|`+addFieldForInsertReturnOnly+` |INSERT |No |Yes + +|`+addFieldForUpdate+` |UPDATE |Yes |Yes +|=== + +You configure a descriptor with a `+ReturningPolicy+` using +`+ClassDescriptor+` method `+setReturningPolicy+`. + +== Configuring Instantiation Policy + +The EclipseLink runtime instantiates new instances of a class according +to the instantiation policy you configure on the class’s descriptor. + +This table summarizes which descriptors support an instantiation policy. + +[#Table 115-31]## *_Descriptor Support for Instantiation Policy_* + +Descriptor + +Using Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +You can specify one of the following types of instantiation policy: + +* Default: EclipseLink creates a new instance of a class by calling the +class’s default constructor. +* Method: EclipseLink creates a new instance of a class by calling a +public static method that you define on the class descriptor. +* Factory: EclipseLink creates a new instance of a class by calling the +appropriate methods on a separate class that you implement according to +the Factory design pattern. + +=== How to Configure Instantiation Policy Using Workbench + +To set the instantiation policy for a descriptor, use this procedure: + +[arabic] +. In the *Navigator*, select a descriptor.If the Instantiation advanced +property is not visible for the descriptor, right-click the descriptor +and choose *Select Advanced Properties* > *Instantiation* from the +context menu or from the *Selected* menu. +. Click the *Instantiation* tab. *_Instantiation Tab_* +image:instant.gif[Instantiation Tab,title="Instantiation Tab"] +. Complete each field on the *Instantiation* tab. + +Use the following information to enter data in each field on the tab: + +Field + +Description + +Use Default Constructor + +Specify if the default constructor of the class instantiates a new +instance. + +Use Method + +Specify a method to execute to create objects from the database. + +Method + +Select the name of a method to be executed to create objects from the +database. The method must be a public, static method on the descriptor’s +class and must return a new instance of the object. + +Use Factory + +Specify an object factory method. + +Factory Class + +Select the class of the factory object that creates the new instances. + +Factory Method + +Select the method to be used to obtain a factory object. Choose to use +the default constructor. + +Instantiation Method + +Select the method to be called on the factory object to obtain a new +instance that will be populated with data from the data source. + +=== How to Configure Instantiation Policy Using Java + +Use one of the following `+ClassDescriptor+` methods to set the +appropriate type of instantiation policy: + +* `+useDefaultConstructorInstantiationPolicy+` +* `+useMethodInstantiationPolicy+` +* `+useFactoryInstantiationPolicy+` + +== Configuring Copy Policy + +The EclipseLink unit of work feature must be able to produce an exact +copy (clone) persistent objects. This table summarizes which descriptors +support a copy policy. + +[#Table 115-32]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +EclipseLink supports the following two ways of copying objects: + +* Instantiation policy: By default, EclipseLink creates a new copy of an +object by using the currently configured instantiation policy (see +link:#Configuring_Instantiation_Policy[Configuring Instantiation +Policy]). +* Method: EclipseLink creates a new copy of an object by calling a +method on the object that you specify. For example, you can specify the +object’s `+clone+` method (or any other appropriate method on the +object). Note that the clone method should return a shallow clone of the +object. + +=== How to Configure Copy Policy Using Workbench + +To specify the copy policy for a descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor.If the *Copying* advanced property is not visible for the +descriptor, right-click the descriptor and choose *Select Advanced +Properties* > *Copying* from the context menu or from the *Selected* +menu. +. Click the *Copying* tab in the *Editor*. *_Copying Tab_* +image:copying.gif[Copying Tab,title="Copying Tab"] +. Complete each field on the Copying tab. + +Use the following information to enter data in each field on the tab: + +[width="100%",cols="<15%,<85%",options="header",] +|=== +|*Field* |*Description* +|*Use Instantiation Policy* |Creates a new instance of the object using +the descriptor’s instantiation policy (see +link:#Configuring_Instantiation_Policy[Configuring Instantiation +Policy]). + +|*Use Clone Method* |Specifies whether or not to call the `+clone+` +method of the object. Select a method from the list. +|=== + +=== How to Configure Copy Policy Using Java + +Use one of the following `+ClassDescriptor+` methods to set the +appropriate type of copy policy: + +* `+useCloneCopyPolicy()+`: the object must provide a `+clone+` method +* `+useCloneCopyPolicy(java.lang.String cloneMethodName)+` +* `+useInstantiationCopyPolicy()+` + +== Configuring Change Policy + +Use a change policy to specify how EclipseLink should track changes made +to objects after you register them with a unit of work. This table +summarizes which descriptors support a change policy. + +[#Table 115-33]## + +Descriptor + +Deferred Change Detection Policy + +Object-Level Change Tracking Policy + +Attribute Change Tracking Policy + +Using the Workbench + +Using Java + +Relational Descriptors1 + +Object-Relational Data Type Descriptors + +EIS Descriptors 2 + +XML Descriptors + +1link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +Class Descriptors] only. +2link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] only. By default, EclipseLink uses the deferred change +detection policy. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many or many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading nor value holder indirection). + +Mutable basic mappings affect the overhead of change tracking. +EclipseLink can only weave an attribute change tracking policy for +immutable mappings. + +EclipseLink logs a warning message at the `+CONFIG+` log level if you +try to weave a descriptor that does not support change policy. + +EclipseLink supports alternative change policies (policies other than +`+DeferredChangeDetectionPolicy+`) for attributes that use a subset of +the mappings that EclipseLink supports. + +For JPA applications deployed to OC4J EclipseLink automatically uses the +attribute change tracking policy. + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Unit_of_Work_and_Change_Policy[Unit +of Work and Change Policy] +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Change_Policy_Mapping_Support[Change +Policy Mapping Support] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Weaving[Using +EclipseLink JPA Weaving] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Method_and_Direct_Field_Access[Using +Method and Direct Field Access] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Mutability[Mutability] + +=== How to Configure Change Policy Using Java + +This section describes how to configure a descriptor with a change +policy using Java, and how to implement persistent classes for those +change policies that are intrusive. It includes information on +configuring the following: + +* link:#Configuring_Deferred_Change_Detection_Policy[Configuring +Deferred Change Detection Policy] +* link:#Configuring_Object_Change_Tracking_Policy[Configuring Object +Change Tracking Policy] +* link:#Configuring_Attribute_Change_Tracking_Policy[Configuring +Attribute Change Tracking Policy] + +==== Configuring Deferred Change Detection Policy + +The `+DeferredChangeDetectionPolicy+` provides good unit of work commit +performance for a wide range of object change characteristics. It is the +default change policy. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Deferred_Change_Detection_Policy[Deferred +Change Detection Policy]). + +Because it is the default, you do not need to explicitly configure this +policy. + +To configure EclipseLink to use a `+DeferredChangeDetectionPolicy+`, +create a descriptor amendment method (see +link:#Configuring_Amendment_Methods[Configuring Amendment Methods]) that +sets the change policy, as the link:#Example_115-21[Setting the +ObjectChangeTrackingPolicy] example illustrates. + +==== Configuring Object Change Tracking Policy + +The `+ObjectChangeTrackingPolicy+` provides improved unit of work commit +performance for objects with few attributes, or with many attributes and +many changed attributes. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Object-Level_Change_Tracking_Policy[Object-Level +Change Tracking Policy]. + +For JPA applications deployed to an application server, for which +EclipseLink provides integration (see +link:Integrating%20EclipseLink%20with%20an%20Application%20Server_(ELUG)#Introduction_to_the_Application_Server_Support[Introduction +to the Application Server Support]), when you configure an entity’s +descriptor with an `+ObjectLevelChangeTrackingPolicy+`, EclipseLink +automatically generates code of a concrete subclass to implement the +EclipseLink `+ChangeTracker+` interface at deploy time. Configuring the +`+ObjectLevelChangeTrackingPolicy+` prevents EclipseLink from +automatically applying an `+AttributeChangeTrackingPolicy+` (see +link:#Configuring_Attribute_Change_Tracking_Policy[Configuring Attribute +Change Tracking Policy]). + +To configure EclipseLink to use an `+ObjectChangeTrackingPolicy+`, use +this procedure: + +[arabic] +. Create a descriptor amendment method (see +link:#Configuring_Amendment_Methods[Configuring Amendment Methods]) that +sets the change policy, as this example illustrates: [#Example 115-21]## +*_Setting the ObjectChangeTrackingPolicy_* ++ +`+descriptor.setObjectChangePolicy(new ObjectChangeTrackingPolicy());+` +. For plain Java objects, code each of your persistent classes to +implement the `+ChangeTracker+` interface, as this example illustrates: +[#Example 115-22]## *_Implementing the ChangeTracker Interface for the +ObjectChangeTrackingPolicy_* ++ +`+public class Employee implements ChangeTracker {+` + +`+    PropertyChangeListener listener;+` `+    String firstName;+` + +`+    public PropertyChangeListener getEclipseLinkPropertyChangeListener() {+` +`+      return this.listener;+` `+    }+` + +`+    public void setEclipseLinkPropertyChangeListener(PropertyChangeListener listener) {+` +`+      this.listener = listener;+` `+    }+` `+    ...+` +`+    public void setFirstName(String firstName) {+` +`+      propertyChange("firstName", getFirstName(), firstName);+` +`+      this.firstName = firstName;+` `+    }+` `+    ...+` +`+    public void propertyChange(String propertyName, Object oldValue, Object newValue) {+` +`+        if (listener != null) {+` +`+            if (oldValue != newValue) {+` +`+                listener.propertyChange(+` +`+                    new PropertyChangeEvent(this, propertyName, oldValue, newValue));+` +`+            }+` `+        }+` `+    }+` `+}+` + +==== Configuring Attribute Change Tracking Policy + +The `+AttributeChangeTrackingPolicy+` provides improved unit of work +commit performance for objects with many attributes and few changed +attributes. In general, this is the most efficient change policy. It is +the default change policy for JPA applications. For more information, +see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Attribute_Change_Tracking_Policy[Attribute +Change Tracking Policy]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use the `+AttributeChangeTrackingPolicy+` if you are +using any instance of `+FieldsLockingPolicy+` (see +link:Introduction%20to%20Descriptors%20(ELUG)#Optimistic_Field_Locking_Policies[Optimistic +Field Locking Policies]). +|=== + +When you deploy an EclipseLink-enabled JPA application, EclipseLink +automatically configures your persistent classes to use the +`+AttributeChangeTrackingPolicy+` and, using bytecode weaving, +configures your persistence classes to implement the EclipseLink +`+ChangeTracker+` interface. In this case, you do not need to explicitly +configure this change policy. + +To configure EclipseLink to use an `+AttributeChangeTrackingPolicy+` for +plain Java objects or other application servers, use this procedure: + +[arabic] +. Create a descriptor amendment method (see +link:#Configuring_Amendment_Methods[Configuring Amendment Methods]) that +sets the change policy, as this example illustrates: [#Example 115-23]## +*_Setting the DeferredChangeDetectionPolicy_* ++ +`+descriptor.setObjectChangePolicy(new AttributeChangeTrackingPolicy());+` +. Code each of your persistent classes to implement the +`+ChangeTracker+` interface, as this example illustrates: +[#Example 115-24]## *_Implementing the ChangeTracker Interface for the +AttributeChangeTrackingPolicy_* ++ +`+public class Employee implements ChangeTracker {+` + +`+   PropertyChangeListener listener;+` `+   String firstName;+` + +`+   public PropertyChangeListener getEclipseLink PropertyChangeListener() {+` +`+     return this.listener;+` `+   }+` + +`+   public void setEclipseLinkPropertyChangeListener(PropertyChangeListener listener) {+` +`+     this.listener = listener;+` `+   }+` `+   ...+` +`+   public void setFirstName(String firstName) {+` +`+     propertyChange("firstName", getFirstName(), firstName);+` +`+     this.firstName = firstName;+` `+   }+` `+   ...+` +`+   public void propertyChange(String propertyName, Object oldValue, Object newValue) {+` +`+       if (listener != null) {+` +`+           if (oldValue != newValue) {+` +`+               listener.propertyChange(+` +`+                   new PropertyChangeEvent(this, propertyName, oldValue, newValue));+` +`+           }+` `+       }+` `+   }+` `+}+` + +== Configuring a History Policy + +If you want to use historical sessions (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical_Sessions[Historical +Sessions]) to execute historical queries (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Historical_Queries[Historical +Queries]) against a historical schema of your own design, configure your +descriptors with an EclipseLink `+HistoryPolicy+` that describes your +historical schema. + +If you are using an Oracle Database platform for Oracle9__i__ Database +Server (or later), you can query the historical versions of objects +automatically maintained by the Oracle Database without the need for a +history policy. For more information, see +link:Configuring%20Historical%20Sessions%20(ELUG)#How_to_Configure_Historical_Sessions_Using_an_Oracle_Platform[How +to Configure Historical Sessions Using an Oracle Platform]. + +This table summarizes which descriptors support history policy +configuration. + +[#Table 115-34]## + +Descriptor + +How to Use Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +There are many ways to configure a historical database schema. +EclipseLink supports several historical schema configurations that you +can describe with a `+HistoryPolicy+` (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical_Session_Limitations[Historical +Session Limitations]). + +*Example Historical Schema* + +As shown in the link:#Table_115-35[Example Table for EMPLOYEE] and +link:#Table_115-36[Example History Table EMPLOYEE_HIST], a common +approach is to define a special history table to store past versions of +an object: one history table for each regular table that requires +historical persistence. The history table typically has the same fields +as the corresponding regular table plus fields (such as row start and +end) used to define an interval that represents the life time of a +particular version. + +[width="100%",cols="<100%",] +|=== +|*Note:* EclipseLink assumes that the current version of an object +corresponds to the historical table row whose row end field is `+NULL+`. +|=== + +EclipseLink will include the history tables described by a +`+HistoryPolicy+` when you execute a historical query. + +This table shows the schema for an `+EMPLOYEE+` table. The table +currently contains one `+EMPLOYEE+` instance. + +[#Table 115-35]## *_Example Table for EMPLOYEE_* + +[cols="<,<,<,<",options="header",] +|=== +|*EMP_ID* |*F_NAME* |*L_NAME* |*SALARY* +|1 |Jane |Doe |55000 +|=== + +This table shows one possible history table `+EMPLOYEE_HIST+` that +stores historical versions of employees. The table contains the current +`+EMPLOYEE+` (the version with a `+ROW_END+` value of `+NULL+`) and one +historical version. + +[#Table 115-36]## *_Example History Table EMPLOYEE_HIST_* + +[width="100%",cols="<19%,<15%,<15%,<15%,<19%,<17%",options="header",] +|=== +|*EMP_ID* |*F_NAME* |*L_NAME* |*SALARY* |*ROW_START* |*ROW_END* +|1 |Jane |Doe |50000 |29/08/2004 |31/08/2004 +|1 |Jane |Doe |55000 |31/08/2004 |NULL +|=== + +Because every record has a start and end interval, the history table can +store multiple versions of the same object (with the same primary key). +The unique identifier of a particular version is given by the existing +primary key, plus the value of the start field. For example, in +link:#Table_115-36[Example History Table EMPLOYEE_HIST], the unique +identifier of the current version is given by +`+(EMP_ID, START) = (1, 31/08/2004)+`. + +=== How to Configure a History Policy Using Java + +This example shows how to describe the schema shown in +link:#Table_115-35[Example Table for EMPLOYEE] and +link:#Table_115-36[Example History Table EMPLOYEE_HIST] using the +EclipseLink `+HistoryPolicy+`: + +[#Example 115-25]## *_HistoryPolicy for One Table_* + +`+HistoryPolicy policy = new HistoryPolicy();+` +`+policy.addStartFieldName("ROW_START");+` +`+policy.addEndFieldName("ROW_END");+` +`+policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");+` + +*`+//\'\' \'\'Assuming\'\' \'\'database\'\' \'\'triggers\'\' \'\'or\'\' \'\'stored\'\' \'\'procedures\'\' \'\'update\'\' \'\'history\'\' \'\'tables+`* +`+policy.setShouldHandleWrites(false);+` + +`+employeeDescriptor.setHistoryPolicy(policy);+` + +You can specify more than one table with a `+HistoryPolicy+` as shown in +this examle. In this example, all history tables have a start field +named `+ROW_START+` but the `+EMPLOYEE_HIST+` and `+SALARY_HIST+` tables +have different end fields. To avoid ambiguity, the end field names are +prefixed with their respective history table names. + +[#Example 115-26]## *_HistoryPolicy for Multiple Tables_* + +`+HistoryPolicy policy = new HistoryPolicy();+` +`+policy.addStartFieldName("ROW_START");+` +`+policy.addEndFieldName("EMPLOYEE_HIST.ROW_END");+` +`+policy.addEndFieldName("SALARY_HIST.VALID_UNTIL");+` +`+policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");+` +`+policy.addHistoryTableName("SALARY", "SALARY_HIST");+` +*`+//\'\' \'\'Assuming\'\' \'\'database\'\' \'\'triggers\'\' \'\'or\'\' \'\'stored\'\' \'\'procedures\'\' \'\'update\'\' \'\'history\'\' \'\'tables+`* +`+policy.setShouldHandleWrites(false);+` + +`+employeeDescriptor.setHistoryPolicy(policy);+` + +==== Configuring Write Responsibility + +Use `+HistoryPolicy+` method `+setShouldHandleWrites+` to specify +whether or not EclipseLink is responsible for writing data to history +tables. By default, `+setShouldHandleWrites+` is set to `+true+`. + +Either the database or EclipseLink can be responsible for writing data +to the history tables. + +You can configure the database to write data to history tables by way of +triggers or stored procedures that customize create, insert, and delete +operations to modify both the regular table and the history table +appropriately. + +== Configuring Wrapper Policy + +EclipseLink lets you use wrappers (or proxies) in cases where the +persistent class is not the same class that is to be presented to users. + +For example, in the EJB specification prior to 3.0, the entity bean +class (the class that implements `+javax.ejb.EntityBean+`) is +persistent, but is hidden from users who interact with a class that +implements `+javax.ejb.EJBObject+` (local or remote interface class). In +this example, the `+EJBObject+` acts as a proxy (or wrapper) for the +`+EntityBean+`. + +In cases where such a wrapper is used, EclipseLink continues to make the +class specified in the descriptor persistent, but returns the +appropriate instance of the wrapper whenever a persistent object is +requested. + +This table summarizes which descriptors support a wrapper policy. + +[#Table 115-37]## *_Descriptor Support for Wrapper Policy_* + +Descriptor + +How to Use Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +Use a wrapper policy to tell EclipseLink how to create wrappers for a +particular persistent class, and how to obtain the underlying persistent +object from a given wrapper instance. + +If you specify a wrapper policy, EclipseLink uses the policy to _wrap_ +and _unwrap_ persistent objects as required: + +* Wrapper policies implement the interface +`+org.eclipse.persistence.descriptors.WrapperPolicy+`. +* A wrapper policy is specified by setting the wrapper policy for the +EclipseLink descriptor. +* By default, no wrapper policy is used (the wrapper policy for a +descriptor is null by default). + +[width="100%",cols="<100%",] +|=== +|*Note*: Wrapper policies are advanced EclipseLink options. Using a +wrapper policy may not be compatible with some Workbench features. +|=== + +Wrapper policies cannot be set using the Workbench and can be set only +using Java code (see +link:#How_to_Configure_Wrapper_Policy_Using_Java[Using Java]). + +=== How to Configure Wrapper Policy Using Java + +Use the `+ClassDescriptor+` method `+setWrapperPolicy+` to set the +appropriate instance of `+WrapperPolicy+`. + +== Configuring Fetch Groups + +By default, when you execute an object-level read query for a particular +object class, EclipseLink returns all the persistent attributes mapped +in the object’s descriptor. With this single query, all the object’s +persistent attributes are defined, and calling their `+get+` methods +returns the value directly from the object. + +When you are interested in only some of the attributes of an object, it +may be more efficient to return only a subset of the object’s attributes +using a fetch group. + +Using a fetch group, you can define a subset of an object’s attributes +and associate the fetch group with either a `+ReadObjectQuery+` or +`+ReadAllQuery+` query. When you execute the query, EclipseLink +retrieves only the attributes in the fetch group. EclipseLink +automatically executes a query to fetch all the attributes excluded from +this subset when and if you call a `+get+` method on any one of the +excluded attributes. + +You can define more than one fetch group for a class. You can optionally +designate at most one such fetch group as the default fetch group. If +you execute either a `+ReadObjectQuery+` or `+ReadAllQuery+` query +without specifying a fetch group, EclipseLink will use the default fetch +group, unless you configure the query otherwise (see +link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Configure_Default_Fetch_Group_Behavior[How +to Configure Default Fetch Group Behavior]). + +You can use fetch groups in JPA projects for EJB objects, as well as for +POJO classes. For POJO classes, use partial object querying (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Partial_Object_Queries[Partial +Object Queries]). + +Before using fetch groups, we recommend that you perform a careful +analysis of system use. In many cases, the extra queries required to +load attributes not in the fetch group could well offset the gain from +the partial attribute loading. For more information about optimizing +read performance, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Read_Optimization_Examples[Read +Optimization Examples]. + +This table summarizes which descriptors support fetch group +configuration. + +[#Table 115-38]## + +Descriptor + +Using Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink uses fetch groups to improve performance. + +This section describes how to create a fetch group, store it in a +descriptor, and optionally designate a fetch group as the default fetch +group for its descriptor reference class. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#Fetch_Groups[Fetch +Groups] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Fetch_Groups_and_Object-Level_Read_Queries[Fetch +Groups and Object-Level Read Queries] +* link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Configure_Default_Fetch_Group_Behavior[How +to Configure Default Fetch Group Behavior] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Weaving[Using +EclipseLink JPA Weaving] + +=== How to Configure Fetch Groups Using Java + +To configure a fetch group, Use a +link:#Configuring_Amendment_Methods[descriptor amendment method] as this +example shows. + +[#Example 115-27]## *_Configuring a Fetch Group_* + +*`+//Create\'\' \'\'a\'\' \'\'FetchGroupManager\'\' \'\'for\'\' \'\'the\'\' \'\'descriptor+`* + +`+descriptor.setFetchGroupManager(new FetchGroupManager());+` +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'FetchGroup+`* +`+FetchGroup group = new FetchGroup("nameOnly");+` +*`+//\'\' \'\'Add\'\' \'\'attributes\'\' \'\'to\'\' \'\'FetchGroup.\'\' \'\'Alternatively,\'\' \'\'use+`* +*`+//\'\' \'\'FetchGroup\'\' \'\'method\'\' \'\'addAttributes,\'\' \'\'passing\'\' \'\'in\'\' \'\'a\'\' \'\'Set\'\' \'\'of\'\' \'\'String\'\' \'\'attribute\'\' \'\'names+`* +`+group.addAttribute("firstName");+` `+group.addAttribute("lastName");+` +*`+//\'\' \'\'Add\'\' \'\'the\'\' \'\'FetchGroup\'\' \'\'to\'\' \'\'the\'\' \'\'FetchGroupManager+`* +`+descriptor.getFetchGroupManager().addFetchGroup(group);+` +*`+//Set\'\' \'\'the\'\' \'\'default\'\' \'\'fetch\'\' \'\'group+`* +`+descriptor.getFetchGroupManager().setDefaultFetchGroup(group);+` + +Each instance of `+FetchGroup+` that you store in a descriptor must be +configured with a fetch group name that is unique for that descriptor +(that is, each descriptor owns a set of named fetch groups). + +When configuring fetch groups, note that the primary key fields and +other required fields (such as inheritance type and optimistic lock +version) are always included in all fetch groups.Fetch groups can +include direct and relationship attributes. Including a relationship +attribute in a fetch group does not cause the relationship to be joined +or instantiated: joining and indirection are set independently of fetch +groups. + +After you add a fetch group to a descriptor, you can configure a +`+ReadObjectQuery+` or `+ReadAllQuery+` query with this fetch group by +name (`+nameOnly+`) or rely on EclipseLink to use this fetch group by +default. For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Queries_with_Fetch_Groups[Using +Queries with Fetch Groups]. + +== Configuring a Descriptor Customizer Class + +A descriptor customizer class is a Java class that implements the +`+org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer+` +interface and provides a default (zero-argument) constructor. You can +use a descriptor customizer to customize a descriptor at run time on a +loaded session before login occurs, similar to how you can use an +amendment method (see link:#Configuring_Amendment_Methods[Configuring +Amendment Methods]). + +This table summarizes which sessions support customizer class +configuration. + +[#Table 115-39]## + +Descriptor + +How to Configure Customizer Class Using Workbench + +Using Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Customization[Descriptor +Customization]. + +=== How to Configure Customizer Class Using Java + +When using Java, create a customize class that implements the +`+org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer+` +interface. This example illustrates the creation of a descriptor +customizer. + +[#Example 115-28]## *_Creating a SessionCustomizer Class_* + +`+import org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer;+` +`+import org.eclipse.persistence.descriptors.ClassDescriptor;+` + +`+public class EmployeeDescriptorCustomizer implements DescriptorCustomizer {+` + +`+    public void customize(ClassDescriptor descriptor) {+` +`+        descriptor.setReadOnly();+` `+    }+` `+}+` + +== Configuring Amendment Methods + +Some EclipseLink descriptor features cannot be configured from the +Workbench. To use these features, you must write a Java method to amend +the descriptor after it is loaded as part of the project. This method +must have the following characteristics: + +* Be public static. +* Take a single parameter of type +`+org.persistence.descriptors.structures.ClassDescriptor+`. + +In the implementation of this method, you can configure advanced +features of the descriptor using any of the public descriptor and +mapping API. + +This table summarizes which descriptors support amendment methods. + +[#Table 115-40]## + +Descriptor + +Using the Workbench + +How to Use Java + +Relational Descriptors + +Object-Relational Data Type Descriptors + +EIS Descriptors + +XML Descriptors + +This section describes how to associate an amendment method with a +descriptor. + +For more information about how to implement an amendment method, see +link:Introduction%20to%20Descriptors%20(ELUG)#Amendment_and_After-Load_Methods[Amendment +and After-Load Methods]. + +Alternatively, you can use a descriptor customizer class (see +link:#Configuring_a_Descriptor_Customizer_Class[Configuring a Descriptor +Customizer Class]. + +To customize a session, use a session customizer class (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Customizer_Class[Configuring +a Session Customizer Class]). + +=== How to Configure Amendment Methods Using Workbench + +To use an amendment method with a descriptor (after it is loaded as part +of the project) use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor.If the *After load* advanced property is not visible for the +descriptor, right-click the descriptor and choose *Select Advanced +Properties* > *After Load* from context menu or from the *Selected* +menu. +. Click the *After Load* tab in the *Editor*. *_After Load Tab_* +image:aftrload.gif[After Load Tab,title="After Load Tab"] +. Complete each field on the After Load tab. + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*Field* |*Description* +|*Class* |Click *Browse* and choose the class of the method to execute. + +|*Static Method* |Use the *Static Method* list to choose the static +method to execute at run time, after loading the descriptor. The method +must be public static and take a single attribute of type +`+org.eclipse.persistence.descriptors.ClassDescriptor+`. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_JMS_Coordinated_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_JMS_Coordinated_Cache_(ELUG).adoc new file mode 100644 index 00000000000..00da673ef12 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_JMS_Coordinated_Cache_(ELUG).adoc @@ -0,0 +1,245 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_JMS_Coordinated_Cache_(ELUG)[Related +Topics] + +[#Table 100-1]## *_Configurable Options for a JMS Coordinated Cache_* + +Option to Configure + +EclipseLink Workbench + +Java + +Cache coordination change propagation at the descriptor level + +Synchronous change propagation mode + +JNDI naming service information + +Topic name + +Topic connection factory name + +Topic host URL + +Connection handling + +Context properties + +Packet time-to-live + +== Configuring a Topic Name + +A JMS topic identifies a publish/subscribe destination for a JMS server. +JMS users who wish to share messages subscribe to the same JMS topic. + +The topic name you configure is the name that EclipseLink uses to look +up the `+javax.jms.Topic+` instance from the JNDI service. You must +provide a fully qualified JNDI name, such as +`+jms/<+`_`+topic_name+`_`+>+`. + +All the members of the same JMS coordinated cache must use the same JMS +topic. + +=== How to Configure a Topic Name Using Workbench + +To specify the topic name for JMS cache coordination, use this +procedure: + +[arabic] +. Select a server session in the *Navigator*. Its properties appear in +the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure *Enable Cache Coordination* is selected and the *Type* is *JMS* +(see link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination] for more information). [#Figure 100-1]##*_Cache +Coordination Tab, Topic Name Field, JMS_* image:jmsclutn.gif[Cache +Coordination Tab, Topic Name Field, +JMS,title="Cache Coordination Tab, Topic Name Field, JMS"] +. Enter the topic name to use with the JMS coordinated cache for this +session. This must be a fully qualified JNDI name, such as `+jms/+`__. + +Enter the topic name to use with the JMS coordinated cache for this +session. This must be a fully qualified JNDI name, such as `+jms/+`__. + +=== How to Configure a Topic Name Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.broadcast.BroadcastTransportManager+` +method `+setTopicName+` to configure the Topic name for the Topic to +which this transport manager will be connecting. + +You obtain the `+BroadcastTransportManager+` using the following +`+Session+` API: + +`+Session.getCommandManager().getTransportManager()+` + +== Configuring a Topic Connection Factory Name + +A JMS topic connection factory creates connections with the JMS provider +for a specific JMS destination. Each connection factory contains the +specific configuration information to create a connection to a JMS +destination. + +The topic connection factory name you configure is the name that +EclipseLink uses to look up the `+javax.jms.TopicConnectionFactory+` +instance from the JNDI service. This must be a fully qualified JNDI +name, such as `+jms/<+`_`+resource_name+`_`+>+`. + +=== How to Configure a Topic Connection Factory Name Using Workbench + +To specify the topic connection factory for a JMS coordinated cache, use +this procedure: + +[arabic] +. Select a server session in the *Navigator*. Its properties appear in +the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure *Enable Cache Coordination* is selected and the *Type* is *JMS* +(see link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination] for more information). [#Figure 100-2]##*_Cache +Coordination Tab, Topic Connection Factory Name Field_* +image:jmscluto.gif[Cache Coordination Tab, Topic Connection Factory Name +Field,title="Cache Coordination Tab, Topic Connection Factory Name Field"] +. Enter the topic connection factory name to use with the JMS +coordinated cache for this session. This must be a fully qualified JNDI +name, such as `+jms/+`__. + +Enter the topic connection factory name to use with the JMS coordinated +cache for this session. This must be a fully qualified JNDI name, such +as `+jms/+`__. + +=== How to Configure a Topic Connection Factory Name Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.jms.JMSTopicTransportManager+` +method `+setTopicConnectionFactoryName+` to configure the the JMS Topic +connection factory name for the JMS Topic connections. + +You obtain the `+JMSTopicTransportManager+` using the following +`+Session+` API: + +`+Session.getCommandManager().getTransportManager()+` + +== Configuring a Topic Host URL + +The JMS topic host URL is the URL of the machine on the network that +hosts the JMS topic (see link:#Configuring_a_Topic_Name[Configuring a +Topic Name]). + +=== How to Configure a Topic Host URL Using Workbench + +To specify the topic host URL for a JMS coordinated cache, use this +procedure: + +[arabic] +. Select a server session in the *Navigator*. Its properties appear in +the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure *Enable Cache Coordination* is selected and the *Type* is *JMS* +(see link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination] for more information). [#Figure 100-3]##*_Cache +Coordination Tab, Topic Host URL Field_* image:jmsurl.gif[Cache +Coordination Tab, Topic Host URL +Field,title="Cache Coordination Tab, Topic Host URL Field"] + +Enter the URL of the machine on the network that hosts the JMS topic +(see link:#Configuring_a_Topic_Name[Configuring a Topic Name]) to use +with the JMS coordinated cache for this session. + +=== How to Configure a Topic Host URL Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.jms.JMSTopicTransportManager+` +method `+setTopicHostUrl+` to configure the URL of the computer on the +network that hosts the JMS Topic. + +You obtain the `+JMSTopicTransportManager+` using the following +`+Session+` API: + +`+Session.getCommandManager().getTransportManager()+` + +== Configuring Connection Handling + +The session’s transport manager creates connections to the various +members of the coordinated cache. If a communication error occurs on one +of these connections, you can configure the session to either ignore the +error or remove the connection. + +If you configure the session to remove the connection on error, the next +time the session tries to communicate with that coordinated cache +member, it will construct a new connection. If an error occurs during +the connection creation phase, EclipseLink will either throw a +`+RemoteCommandManagerException.ERROR_CREATING_JMS_CONNECTION+` (if the +error occurred while sending a message) or a +`+RemoteCommandManagerException.ERROR_CREATING_LOCAL_JMS_CONNECTION+` +(if the error occurred while receiving a message). If you want to +recover from this failure, consider the following options: + +* You may choose to take no action: messages will not be sent or +received. +* You may choose to handle the exception. You may do so by changing some +of the +`+org.eclipse.persistence.sessions.coordination.jms.JMSTopicTransportManager+` +settings and calling the `+createExternalConnection+` or +`+createInternalConnection+` method of the `+JMSTopicTransportManager+`. + +If you configure the session to ignore the error, the next time the +session tries to communicate with that coordinated cache member, it will +continue to use the same connection. In this case, if the listening +(local) connection gets a +`+RemoteCommandManagerException.ERROR_RECEIVING_JMS_MESSAGE+` exception, +the coordinated cache waits for 10 seconds before resuming listening. If +you want to recover from this failure, consider the following options: + +* You may choose to take no action (wait for the connection recovery). +* You may choose to handle the +`+RemoteCommandManagerException.ERROR_PROPAGATING_COMMAND+` or +`+RemoteCommandManagerException.ERROR_RECEIVING_JMS_MESSAGE+` exception. +You may do so by shutting down the remote command manager. + +In either case, if the coordinated cache receives a null JMS message, it +will throw a +`+RemoteCommandManagerException.ERROR_RECEIVED_JMS_MESSAGE_IS_NULL+` +exception. + +=== How to Configure Connection Handling Using Workbench + +To specify how EclipseLink handles session connections in the event of +an error, use this procedure: + +[arabic] +. Select a session or session broker in the *Navigator*. Its properties +appear in the Editor. +. Click the *Cache Coordination* tab. The Cache Coordination tab +appears. +. Ensure the *Enable Cache Coordination* option is selected, then select +the appropriate coordinated cache *Type* (JMS). The cache coordination +options appear on the tab. [#Figure 100-4]##*_Cache Coordination Tab, +Remove Connection on Error Option_* image:clonerr.gif[Cache Coordination +Tab, Remove Connection on Error +Option,title="Cache Coordination Tab, Remove Connection on Error Option"] +. Select the *Remove Connection on Error* option to configure the +session to remove the data source connection in the event of an error. + +=== How to Configure Connection Handling Using Java + +Use the +`+org.eclipse.persistence.sessions.coordination.TransportManager+` +method `+setShouldRemoveConnectionOnError+` to define whether +connections to remote services should be disconnected when an error +occurs. + +You obtain the `+TransportManager+` using the following `+Session+` API: + +`+Session.getCommandManager().getTransportManager()+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..ed72db2dc0b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Mapping_(ELUG).adoc @@ -0,0 +1,2353 @@ +*TOC* Special:Whatlinkshere_Configuring_a_Mapping_(ELUG)[Related Topics] + +This section describes how to configure EclipseLink mapping options +common to two or more mapping types. This table lists the types of +EclipseLink mappings that you can configure and provides a +cross-reference to the type-specific chapter that lists the configurable +options supported by that type. + +[#Table 117-1]## + +If you are creating… + +See… + +Relational Mappings + +Configuring a Relational Mapping + +Object-Relational Data Type Mappings + +Configuring an Object-Relational Data Type Mapping + +EIS Mappings + +Configuring an EIS Mapping + +XML Mappings + +Configuring an XML Mapping + +The link:#Table_117-2[Common Mapping Options] table lists the +configurable options shared by two or more EclipseLink mapping types. + +For more information, see the following: + +* link:Creating%20a%20Mapping%20(ELUG)#Introduction_to_Mapping_Creation[Introduction +to Mapping Creation] +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] + +== Configuring Common Mapping Options + +This table lists the configurable options shared by two or more +EclipseLink mapping types. In addition to the configurable options +described here, you must also configure the options described for the +specific mapping types (see +link:Introduction%20to%20Mappings%20(ELUG)#Mapping_Types[Mapping +Types]), as shown in the link:#Table_117-1[Configuring EclipseLink +Mappings] table. + +[#Table 117-2]## + +Option to Configure + +Workbench + +Java + +Read-only + +Indirection (lazy loading) + +XPath + +Default null value + +Method or direct field access + +Private or independent relationships + +Comments + +Serialized object converter + +Serialized type conversion converter + +Object type converter + +Simple type translator + +JAXB typesafe enumeration converter + +Container policy + +Attribute transformer + +Field transformer associations + +Mutable mappings + +Bidirectional relationship + +Use of a single node + +Use of CDATA + +== Configuring Read-Only Mappings + +Mappings that are read-only will not be affected during insert, update, +and delete operations. + +Use read-only mappings when multiple attributes in an object map to the +same fields in the database but only one of the mappings can write to +the field. + +You can also use read-only mappings with bi-directional many-to-many +mappings to designate which mapping will be responsible for updating the +many-to-many join table. + +[cols="<",] +|=== +|*Note*: The primary key mappings cannot not be read-only. +|=== + +Mappings defined for the write-lock or class indicator field must be +read-only, unless the write-lock is configured not to be stored in the +cache or the class indicator is part of the primary key. + +Use read-only mappings only if specific mappings in a descriptor are +read-only. If the _entire descriptor_ is read-only, use the +descriptor-level setting (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Read-Only_Descriptors[Configuring +Read-Only Descriptors]). + +This table summarizes which mappings support this option. + +[#Table 117-3]## + +Mapping + +Using the Workbench + +Using Java + +Relational Mappings + +Object-Relational Data Type Mappings + +EIS Mappings + +XML Mappings + +=== How to Configure Read-Only Mappings Using Workbench + +To specify a mapping as read-only, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-1]##*_General Tab, Read-Only Option_* +image:mpdbgen3.gif[General Tab, Read-Only +Option,title="General Tab, Read-Only Option"] + +Select the *Read-Only* option to set the mapping to be read-only and not +affected during update and delete operations. + +*See Also* + +link:#Configuring_Read-Only_Mappings[Configuring Read-Only Mappings] + +link:#Configuring_a_Mapping[Configuring a Mapping] + +=== How to Configure Read-Only Mappings Using Java + +Use the following `+DatabaseMapping+` methods to configure the read +access of a mapping: + +* `+readOnly+`–configures mapping read access to read-only; +* `+readWrite+`–configures mapping read access to read and write +(default). + +This example shows how to use these methods with a class that has a +read-only attribute named `+phones+`. + +[#Example 117-1]## *_Configuring Read Only Mappings in Java_* + +*`+//\'\' \'\'Map\'\' \'\'the\'\' \'\'phones\'\' \'\'attribute+`* +`+phonesMapping.setAttributeName("phones");+` `+ +` +*`+//\'\' \'\'Specify\'\' \'\'read-only+`* `+phonesMapping.readOnly();+` + +== Configuring Indirection (Lazy Loading) + +If indirection is not enabled, when EclipseLink retrieves a persistent +object, it retrieves all of the dependent objects to which it refers. +When you enable indirection (lazy loading) for an attribute mapped with +a relationship mapping, EclipseLink uses an indirection object as a +placeholder for the referenced object: EclipseLink defers reading the +dependent object until you access that specific attribute. This can +result in a significant performance improvement, especially if the +application is interested only in the contents of the retrieved object +rather than the objects to which it refers. + +We strongly recommend using indirection for all relationship mappings. +Not only does this allow you to optimize data source access, but it also +allows EclipseLink to optimize the unit of work processing, cache +access, and concurrency. + +This table summarizes which mappings support this option. + +[#Table 117-4]## + +Mapping + +Value Holder Indirection + +Transparent Indirect Container Indirection + +Proxy Indirection + +How to Configure Indirection Using Workbench + +How to Configure Indirection Using Java + +Relational Mappings + +Direct-to-Field Mapping + +Transformation Mapping + +One-to-One Mapping + +Variable One-to-One Mapping + +One-to-Many Mapping + +Many-to-Many Mapping + +Aggregate Collection Mapping + +Direct Collection Mapping + +Direct Map Mapping + +Object-Relational Data Type Mappings + +Object-Relational Data Type Reference Mapping + +Object-Relational Data Type Nested Table Mapping + +EIS Mappings + +EIS One-to-One Mapping + +EIS One-to-Many Mapping + +XML Mappings + +XML Transformation Mapping + +In general, we recommend that you use value holder indirection for +one-to-one mappings and transparent indirect container indirection for +collection mappings. Enable indirection for transformation mappings if +the execution of the transformation is a resource-intensive task (such +as accessing a database, in a relational project). + +When using indirection with EJB, the version of EJB and application +server you use affects how indirection is configured and what types of +indirection are applicable. + +When using indirection with an object that your application serializes, +you must consider the effect of any untriggered indirection objects at +deserialization time. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many or many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading nor value holder indirection). + +For more information, see the following: + +* link:Introduction%20to%20Mappings%20(ELUG)#Indirection_(Lazy_Loading)[Indirection +(Lazy Loading)] +* link:Introduction%20to%20Mappings%20(ELUG)#Value_Holder_Indirection[Value +Holder Indirection] +* link:Introduction%20to%20Mappings%20(ELUG)#Transparent_Indirect_Container_Indirection[Transparent +Indirect Container Indirection] +* link:Introduction%20to%20Mappings%20(ELUG)#Indirection,_Serialization,_and_Detachment[Indirection, +Serialization, and Detachment] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Weaving[Using +EclipseLink JPA Weaving] + +=== How to Configure Indirection Using Workbench + +To complete the indirection options on a mapping’s *General* tab use +this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-2]##*_General Tab, Indirection Options_* +image:indirection.gif[General Tab, Indirection +Options,title="General Tab, Indirection Options"] +. Select the *Use Indirection* option and indicate the type of +indirection to use. + +Use the following information to complete the *Indirection* fields on +the tab: + +[width="100%",cols="<10%,<90%",options="header",] +|=== +|*Field* |*Description* +|*Use Indirection* |Specify if this mapping uses indirection. + +|:*ValueHolder* |Specify that the mapping uses *Value Holder* +indirection. See +link:Introduction%20to%20Mappings%20(ELUG)#Value_Holder_Indirection[Value +Holder Indirection] for more information. + +|:*Proxy* |Specify that the mapping uses *Proxy* indirection. See +link:Introduction%20to%20Mappings%20(ELUG)#Proxy_Indirection[Proxy +Indirection] for more information. +|=== + +*See Also* + +link:#Configuring_Indirection_(Lazy_Loading)[Configuring Indirection +(Lazy Loading)] + +=== How to Configure Indirection Using Java + +When creating mappings through the Java API, all foreign reference +mappings default to using value-holder indirection and all +transformation mappings default to not using indirection. + +To disable indirection use `+ForeignReferenceMapping+` method +`+dontUseIndirection+`. + +To enable value holder indirection, use `+ForeignReferenceMapping+` +method `+useBasicIndirection+`. + +To enable transparent container indirection, use one of the following +`+CollectionMapping+` methods: + +* `+useTransparentCollection+` +* `+useTransparentList+` +* `+useTransparentMap+` +* `+useTransparentSet+` + +To enable proxy indirection, use `+ObjectReferenceMapping+` method +`+useProxyIndirection+`. + +This section provides additional information on the following: + +* link:#Configuring_ValueHolder_Indirection[Configuring ValueHolder +Indirection] +* link:#Configuring_ValueHolder_Indirection_With_Method_Accessing[Configuring +ValueHolder Indirection With Method Accessing] +* link:#Configuring_IndirectContainer_Indirection[Configuring +IndirectContainer Indirection] +* link:#Configuring_Proxy_Indirection[Configuring Proxy Indirection] + +==== Configuring Value Holder Indirection + +Instances of +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+` and +`+org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping+` +provide the `+useBasicIndirection+` method to configure a mapping to an +attribute that you code with an +`+org.eclipse.persistence.indirection.ValueHolderInterface+` between it +and the real object. + +If the attribute is of a `+Collection+` type (such as a `+Vector+`), +then you can either use an `+IndirectContainer+` (see +link:#Configuring_IndirectContainer_Indirection[Configuring +IndirectContainer Indirection]) or define the `+ValueHolder+` in the +constructor as follows: + +`+addresses = new ValueHolder(new Vector());+` + +This example illustrates the `+Employee+` class using `+ValueHolder+` +indirection. The class definition conceals the use of ValueHolder within +the existing getter and setter methods. + +[#Example 117-2]## *_Class Using ValueHolder Indirection_* + +`+public class Employee {+` + +`+    protected ValueHolderInterface address;+` + +`+    +`*`+//\'\' \'\'Initialize\'\' \'\'ValueHolders\'\' \'\'in\'\' \'\'constructor+`* + +`+    public Employee() {+` `+        address = new ValueHolder();+` +`+    }+` + +`+    public Address getAddress() {+` +`+        return (Address) this.addressHolder.getValue();+` `+    }+` + +`+    public void setAddress(Address address) {+` +`+        this.addressHolder.setValue(address);+` `+    }+` `+}+` + +This example shows how to configure a one-to-one mapping to the +`+address+` attribute. + +[#Example 117-3]## *_Mapping Using ValueHolder Indirection_* + +`+OneToOneMapping mapping = new OneToOneMapping();+` +`+mapping.useBasicIndirection();+` +`+mapping.setReferenceClass(Employee.class);+` +`+mapping.setAttributeName("address");+` + +The application uses `+Employee+` methods `+getAddress+` and +`+setAddress+` to access the `+Address+` object. Because basic +indirection is enabled, EclipseLink expects the persistent fields to be +of type `+ValueHolderInterface+`. + +==== Configuring Value Holder Indirection with Method Accessing + +If you are using `+ValueHolder+` indirection with method accessing (see +link:#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]), in addition to +changing your attributes types in your Java code to +`+ValueHolderInterface+`, you must also provide EclipseLink with two +pairs of getter and setter methods: + +* getter and setter of the _indirection_ object that are registered with +the mapping and used only by EclipseLink. They include a `+get+` method +that returns an instance that conforms to `+ValueHolderInterface+`, and +a `+set+` method that accepts one argument that conforms to the same +interface; +* getter and setter of the actual attribute value used by the +application. + +This example illustrates the `+Employee+` class using `+ValueHolder+` +indirection with method access. The class definition is modified so that +the `+address+` attribute of `+Employee+` is a `+ValueHolderInterface+` +instead of an `+Address+`, and appropriate getter and setter methods are +supplied. + +[#Example 117-4]## *_Class Using ValueHolder Indirection with Method +Accessing_* + +`+public class Employee {+` + +`+    protected ValueHolderInterface address;+` + +`+    +`*`+//\'\' \'\'Initialize\'\' \'\'ValueHolders\'\' \'\'in\'\' \'\'constructor+`* +`+    public Employee() {+` `+        address = new ValueHolder();+` +`+    }+` + +`+    +`*`+//\'\' \'\'getter\'\' \'\'and\'\' \'\'setter\'\' \'\'registered\'\' \'\'with\'\' \'\'the\'\' \'\'mapping\'\' \'\'and\'\' \'\'used\'\' \'\'only\'\' \'\'by\'\' \'\'EclipseLink+`* +`+    public ValueHolderInterface getAddressHolder() {+` +`+        return address;+` `+    }+` +`+    public void setAddressHolder(ValueHolderInterface holder) {+` +`+        address = holder;+` `+    }+` + +`+    +`*`+//\'\' \'\'getter\'\' \'\'and\'\' \'\'setter\'\' \'\'methods\'\' \'\'used\'\' \'\'by\'\' \'\'the\'\' \'\'application\'\' \'\'to\'\' \'\'access\'\' \'\'the\'\' \'\'attribute+`* +`+    public Address getAddress() {+` +`+        return (Address) address.getValue();+` `+    }+` + +`+    public void setAddress(Address theAddress) {+` +`+        address.setValue(theAddress);+` `+    }+` `+}+` + +This example shows how to configure a one-to-one mapping to the +`+address+` attribute. + +[#Example 117-5]## *_Mapping Using ValueHolder Indirection with Method +Accessing_* + +`+OneToOneMapping mapping = new OneToOneMapping();+` +`+mapping.useBasicIndirection();+` +`+mapping.setReferenceClass(Employee.class);+` +`+mapping.setAttributeName("address");+` +`+mapping.setGetMethodName("getAddressHolder");+` +`+mapping.setSetMethodName("setAddressHolder");+` + +The application uses `+Employee+` methods `+getAddress+` and +`+setAddress+` to access the `+Address+` object. Because basic +indirection is enabled, EclipseLink uses `+Employee+` methods +`+getAddressHolder+` and `+setAddressHolder+` methods when performing +persistence operations on instances of `+Employee+`. + +==== Configuring Value Holder Indirection with JPA + +When using indirection with JPA, if your application serializes any +indirection-enabled (lazily loaded) entity (see +link:Introduction%20to%20Mappings%20(ELUG)#Indirection,_Serialization,_and_Detachment[Indirection, +Serialization, and Detachment]), then, to preserve untriggered +indirection objects on deserialization, configure your client to use +EclipseLink agent, as follows: + +[arabic] +. Include the following JAR files (from +`+<+`_`+ECLIPSELINK_HOME+`_`+>\jlib+`) in your client classpath: +* `+eclipselink.jar+` +* `+.jar+` +. Add the following argument to the Java command line you use to start +your client: `+-javaagent:eclipselink-agent.jar+` + +You can also use +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Configure_Static_Weaving_for_JPA_Entities[static +weaving]. This will provide you with better error messages and will +resolve merging issues. + +[width="100%",cols="<100%",] +|=== +|*Note:* The use of static weaving will not affect serialization as it +functions without static weaving enabled. +|=== + +==== Configuring IndirectContainer Indirection + +Instances of +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+` and +`+org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping+` +provide the `+useContainerIndirection+` method to configure a mapping to +an attribute that you code with an +`+org.eclipse.persistence.indirection.IndirectContainer+` between it and +the real object. + +Using an `+IndirectContainer+`, a `+java.util.Collection+` class can act +as an EclipseLink indirection object: the `+Collection+` will only read +its contents from the database when necessary (typically, when a +`+Collection+` accessor is invoked). Without an `+IndirectContainer+`, +all members of the `+Collection+` must be retrieved when the +`+Collection+` attribute is accessed. + +The following example illustrates the `+Employee+` class using +`+IndirectContainer+` indirection with method access. Note that the fact +of using indirection is transparent. + +[#Example 117-6]## *_Class Using IndirectContainer Indirection_* + +`+public class Employee {+` + +`+    protected List addresses;+` + +`+    public Employee() {+` +`+        this.addresses = new ArrayList();+` `+    }+` `+  +` +`+    public List getAddresses() {+` `+        return this.addresses;+` +`+    }+` + +`+    public void setAddresses(List addresses) {+` +`+        this.addresses = addresses;+` `+    }+` `+}+` + +The following example shows how to configure a one-to-one mapping to the +`+addresses+` attribute. + +[#Example 117-7]## *_Mapping Using IndirectContainer Indirection_* + +`+OneToOneMapping mapping = new OneToOneMapping();+` +`+mapping.useBasicIndirection();+` +`+mapping.setReferenceClass(Employee.class);+` +`+mapping.setAttributeName("addresses");+` +`+mapping.setGetMethodName("getAddresses");+` +`+mapping.setSetMethodName("setAddresses");+` + +==== Configuring Proxy Indirection + +This example illustrates an `+Employee+` to `+Address+` one-to-one +relationship. + +[#Example 117-8]## *_Classes Using Proxy Indirection_* + +`+public interface Employee {+` + +`+    public String getName();+` `+    public Address getAddress();+` +`+    public void setName(String value);+` +`+    public void setAddress(Address value);+` `+    . . .+` `+}+` + +`+public class EmployeeImpl implements Employee {+` + +`+    public String name;+` `+    public Address address;+` +`+    . . .+` `+    public Address getAddress() {+` +`+        return this.address;+` `+    }+` + +`+    public void setAddress(Address value) {+` +`+        this.address = value;+` `+    }+` `+}+` + +`+public interface Address {+` + +`+    public String getStreet();+` +`+    public void setStreet(String value);+` `+    . . .+` `+}+` + +`+public class AddressImpl implements Address {+` + +`+    public String street;+` `+    . . .+` `+}+` + +In the preceding example, both the `+EmployeeImpl+` and the +`+AddressImpl+` classes implement public interfaces (`+Employee+` and +`+Address+` respectively). Therefore, because the `+AddressImpl+` class +is the target of the one-to-one relationship, it is the only class that +must implement an interface. However, if the `+EmployeeImpl+` is ever to +be the target of another one-to-one relationship using transparent +indirection, it must also implement an interface, as the following +example shows: + +`+Employee emp = (Employee) session.readObject(Employee.class);+` +`+System.out.println(emp.toString());+` +`+System.out.println(emp.getAddress().toString());+` +*`+//\'\' \'\'Would\'\' \'\'print:+`* `+[Employee] John Smith+` +`+{ IndirectProxy: not instantiated }+` +`+String street = emp.getAddress().getStreet();+` +*`+//\'\' \'\'Triggers\'\' \'\'database\'\' \'\'read\'\' \'\'to\'\' \'\'get\'\' \'\'Address\'\' \'\'information+`* +`+System.out.println(emp.toString());+` +`+System.out.println(emp.getAddress().toString());+` +*`+//\'\' \'\'Would\'\' \'\'print:+`* `+[Employee] John Smith+` +`+{ [Address] 123 Main St. }+` + +Using proxy indirection does not change how you instantiate your own +domain objects for an insert operation. You still use the following +code: + +`+Employee emp = new EmployeeImpl("John Smith");+` +`+Address add = new AddressImpl("123 Main St.");+` +`+emp.setAddress(add);+` + +The following example illustrates an `+Employee+` to `+Address+` +one-to-one relationship mapping. + +[#Example 117-9]## *_Mapping Using Proxy Indirection_* + +.... +OneToOneMapping mapping = new OneToOneMapping(); +mapping.useProxyIndirection(); +mapping.setReferenceClass(Employee.class); +mapping.setAttributeName("address"); +mapping.setGetMethodName("getAddress"); +mapping.setSetMethodName("setAddress"); +.... + +== Configuring XPath + +EclipseLink uses XPath statements to map the attributes of a Java object +to locations in an XML document. When you create an XML mapping or EIS +mapping using XML records, you can specify the XPath based on any of the +following: + +* Name +* Position +* Path and name + +This table summarizes which mappings support this option. + +[#Table 117-5]## + +Mapping + +Using the Workbench + +How to Use Java + +EIS Mappings 1 + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +EIS Composite Object Mapping2 + +EIS Composite Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Composite Object Mapping + +XML Composite Collection Mapping + +XML Any Object Mapping + +XML Any Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +XML Choice Collection Mapping + +XML Any Attribute Mapping + +1When used with +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Record_Format[XML +records only]. 2Supports the self XPath ("`.`") so that the EclipseLink +runtime performs all read and write operations in the parent’s element +and not an element nested within it (see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_the_jaxb:class_Customization[Mappings +and the jaxb:class Customization]). Before you can select an XPath for a +mapping, you must associate the descriptor with a schema context (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Schema_Context_for_an_EIS_Descriptor[Configuring +Schema Context for an EIS Descriptoror] +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_Schema_Context_for_an_XML_Descriptor[Configuring +Schema Context for an XML Descriptor]). + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_XPath[Mappings +and XPath]. + +=== How to Configure XPath Using Workbench + +Use this table to select the XPath for an XMl mapping or EIS mapping +using XML records: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. If necessary, click the *General* tab. The General tab appears. +[#Figure 117-3]##*_General Tab, XPath Options_* +image:dtxmlxpath.gif[General Tab, XPath +Options,title="General Tab, XPath Options"] ++ +{empty}[#'Figure 117-4]##*** XPath Options for Composite Object +Mappings*** image:coxxmlpath.gif[XPath Options for Composite Object +Mappings,title="XPath Options for Composite Object Mappings"] +. Click *Browse* and select the XPath to map to this attribute (see +link:#Choosing_the_XPath[Choosing the XPath]). + +For an EIS composite object mapping using XML records or an XML +composite object mapping, you can choose one of the following: + +* *Specify XPath*: select the XPath to map to this attribute (see +link:#Choosing_the_XPath[Choosing the XPath]). +* *Aggregate into parent element*: select the self XPath (`+"."+`) (see +link:Introduction%20to%20Mappings%20(ELUG)#Self_XPath[Self XPath]) so +that the EclipseLink runtime performs all read and write operations in +the parent’s element, and not an element nested within it (see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_the_jaxb:class_Customization[Mappings +and the jaxb:class Customization]). + +==== Choosing the XPath + +From the Choose XPath dialog box, select the XPath and click *OK*. +Workbench builds the complete XPath name. + +[#Figure 117-5 ]## *_Choose XPath Dialog Box_* + +.Choose XPath Dialog Box +image::choosexpath.gif[Choose XPath Dialog +Box,title="Choose XPath Dialog Box"] + +== Configuring a Default Null Value at the Mapping Level + +A default null value is the Java `+Object+` type and value that +EclipseLink uses instead of `+null+` when EclipseLink reads a null value +from a data source. + +When you configure a default null value at the mapping level, +EclipseLink uses it to translate in the following two directions: + +* When EclipseLink reads `+null+` from the data source, it converts this +`+null+` to the specified type and value. +* When EclipseLink writes or queries to the data source, it converts the +specified type and value back to `+null+`. + +This table summarizes which mappings support this option. + +[#Table 117-6]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Direct-to-Field Mapping + +Direct-to-XMLType Mapping + +EIS Mappings + +EIS Direct Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +[width="100%",cols="<100%",] +|=== +|*Note*: A default null value must be an `+Object+`. To specify a +primitive value (such as `+int+`), you must use the corresponding +`+Object+` wrapper (such as `+Integer+`). +|=== + +You can also use EclipseLink to set a default null value for all +mappings used in a session (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_a_Default_Null_Value_at_the_Login_Level[Configuring +a Default Null Value at the Login Level]). + +=== How to Configure a Default Null Value at the Mapping Level Using Workbench + +To configure a default null value for a mapping, use this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. *_General Tab, +Default Null Value Options_* image:mpdbgen2.gif[General Tab, Default +Null Value Options,title="General Tab, Default Null Value Options"] +. Complete the *Default Null Value* fields on the tab. + +Use the following information to complete the *Default Null Value* +fields on the tab: + +Field + +Description + +Default Null Value + +Specify if this mapping contains a default value in the event that the +data source is null. If selected, you must enter both the Type and Value +of the default. + +Type + +Select the Java type of the default value. + +Value + +Enter the default value. + +=== How to Configure a Default Null Value at the Mapping Level Using Java + +To configure a mapping null value using Java API, use the +`+AbstractDirectMapping+` method `+setNullValue+`. + +For example: + +*`+//\'\' \'\'Defaults\'\' \'\'a\'\' \'\'null\'\' \'\'salary\'\' \'\'to\'\' \'\'0+`* +`+salaryMapping.setNullValue(new Integer(0));+` + +== Configuring Method or Direct Field Accessing at the Mapping Level + +By default, EclipseLink uses direct access to access public attributes. +Alternatively, you can use getter and setter methods to access object +attributes when writing the attributes of the object to the database, or +reading the attributes of the object from the database. This is known as +method access. + +Using private, protected or package variable or method access requires +you to enable the Java reflect security setting. This is enabled by +default in most application servers (see +link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)#How_to_Set_Security_Permissions[How +to Set Security Permissions]), but may need to be enabled explicitly in +certain JVM configurations. If necessary, use the `+java.policy+` file +to grant `+ReflectPermission+` to the entire application or the +application’s code base. For example: + +`+grant{+` `+     permission java.lang.reflect.ReflectPermission;+` +`+};+` + +We recommend using _direct access_ whenever possible to improve +performance and avoid executing any application-specific behavior while +building objects. + +This table summarizes which mappings support this option. + +[#Table 117-7]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Object-Relational Data Type Mappings + +EIS Mappings + +XML Mappings + +For information on configuring method accessing at the project level, +see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Configuring +Method or Direct Field Access at the Project Level]. + +If you enable change tracking on a property (for example, you decorate +method `+getPhone+` with `+@ChangeTracking+`) and you access the field +(`+phone+`) directly, note that EclipseLink does not detect the change. +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Method_and_Direct_Field_Access[Using +Method and Direct Field Access]. + +=== How to Configure Method or Direct Field Accessing Using Workbench + +To complete the field access method for a mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-7]##*_General Tab, Method Accessing Options_* +image:mpgen1.gif[General Tab, Method Accessing +Options,title="General Tab, Method Accessing Options"] +. Complete the *Method Accessing* fields on the tab. + +Use the following information to complete the *Method Accessing* fields +on this tab: + +Field + +Description + +Method Accessing + +Specify if this mapping uses specific accessor methods instead directly +accessing public attributes. By default, this option is not selected +(that is, the mapping uses direct access). + +Get Method + +Select a specific get method. + +Set Method + +Select a specific set method. + +To change the default access type used by all new mappings, use the +Defaults tab on the project Editor window. See +link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Configuring +Method or Direct Field Access at the Project Level] for more +information. + +*See Also* + +link:#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] + +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Method_and_Direct_Field_Access[Using +Method and Direct Field Access] + +=== How to Configure Method or Direct Field Accessing Using Java + +Use the following `+DatabaseMapping+` methods to configure the +user-defined getters and setters that EclipseLink will use to access the +mapped attribute: + +For mappings not supported in Workbench, use the `+setGetMethodName+` +and `+setSetMethodName+` methods to access the attribute through +user-defined methods, rather than directly, as follows: + +* `+setGetMethodName+`–set the `+String+` name of the user-defined +method to get the mapped attribute; +* `+setSetMethodName+`–set the `+String+` name of the user-defined +method to set the mapped attribute. + +This example shows how to use these methods with a class that has an +attribute `+phones+` and accessor methods `+getPhones+` and +`+setPhones+` in an object-relational data type mapping. + +[#Example 117-9]## *_Configuring Access Method in Java_* + +*`+//\'\' \'\'Map\'\' \'\'the\'\' \'\'phones\'\' \'\'attribute+`* +`+phonesMapping.setAttributeName("phones");+` `+ +` +*`+//\'\' \'\'Specify\'\' \'\'access\'\' \'\'method+`* +`+phonesMapping.setGetMethodName("getPhones");+` +`+phonesMapping.setSetMethodName("setPhones");+` + +== Configuring Private or Independent Relationships + +In EclipseLink, object relationships can be either private or +independent: + +* In a private relationship, the target object is a private component of +the source object. The target object cannot exist without the source and +is accessible only through the source object. Destroying the source +object will also destroy the target object. +* In an independent relationship, the source and target objects are +public ones that exist independently. Destroying one object does not +necessarily imply the destruction of the other. + +[width="100%",cols="<100%",] +|=== +|*Tip*: EclipseLink automatically manages private relationships. +Whenever an object is written to the database, any private objects it +owns are also written to the database. When an object is removed from +the database, any private objects it owns are also removed. Be aware of +this when creating new systems, since it may affect both the behavior +and the performance of your application. +|=== + +This table summarizes which mappings support this option. + +[#Table 117-8]## + +Mapping + +Implicitly Private + +Private or Independent + +Using Workbench + +Using Java + +Relational Mappings + +One-to-One Mapping + +Variable One-to-One Mapping + +One-to-Many Mapping + +Many-to-Many Mapping + +Aggregate Collection Mapping + +Direct Collection Mapping + +Direct Map Mapping + +Aggregate Object Mapping + +Object-Relational Data Type Mappings + +Object-Relational Data Type Structure Mapping + +Object-Relational Data Type Reference Mapping + +Object-Relational Data Type Array Mapping + +Object-Relational Data Type Object Array Mapping + +Object-Relational Data Type Nested Table Mapping + +EIS Mappings + +EIS Composite Direct Collection Mapping + +EIS Composite Object Mapping + +EIS Composite Collection Mapping + +EIS One-to-One Mapping + +EIS One-to-Many Mapping + +XML Mappings + +XML Composite Direct Collection Mapping + +XML Composite Object Mapping + +XML Composite Collection Mapping + +=== How to Configure Private or Independent Relationships Using Workbench + +To create a privately owned mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-8]##*_General Tab, Private Owned option_* +image:oogenpri.gif[General Tab, Private Owned +option,title="General Tab, Private Owned option"] +. To create private ownership, select the *Private Owned* option. + +=== How to Configure Private or Independent Relationships Using Java + +For mappings not supported in the Workbench, use the +`+independentRelationship+` (default), `+privateOwnedRelationship+`, and +`+setIsPrivateOwned+` methods. + +This exampple shows how to use these methods with a class that has a +privately owned attribute, `+phones+`, in a mapping. + +[#Example 117-10]## *_Configuring Access Method in Java_* + +*`+//\'\' \'\'Map\'\' \'\'the\'\' \'\'phones\'\' \'\'attribute+`* +`+phonesMapping.setAttributeName("phones");+` `+ +` +*`+//\'\' \'\'Specify\'\' \'\'as\'\' \'\'privately\'\' \'\'owned+`* +`+phonesMapping.privateOwnedRelationship();+` + +== Configuring Mapping Comments + +You can define a free-form textual comment for each mapping. You can use +these comments however you wish: for example, to record important +project implementation details such as the purpose or importance of a +mapping. + +Comments are stored in the Workbench project, in the EclipseLink +deployment XML file. There is no Java API for this feature. + +This table summarizes which mappings support this option. + +[#Table 117-9]## + +Mapping + +Using Workbench + +How to Use Java + +Relational Mappings + +EIS Mappings + +XML Mappings + +=== How to Configure Mapping Comments Using Workbench + +To add a comment for a mapping, use this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-9]##*_General Tab, Comment_* image:mpcomment.gif[General +Tab, Comment,title="General Tab, Comment"] +. Enter a comment that describes this mapping. + +== Configuring a Serialized Object Converter + +A serialized object converter can be used to store an arbitrary object +or set of objects into a data source binary large object (BLOB) field. +It uses the Java serializer so the target must be serializable. + +For more information about the serialized object converter, see +link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter]. + +This table summarizes which mappings support this option. + +[#Table 117-10]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Direct-to-Field Mapping + +Object-Relational Data Type Mappings + +Object-Relational Data Type Array Mapping + +EIS Mappings + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +=== How to Configure a Serialized Object Converter Using Workbench + +To create an serialized object direct mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Converter* tab. The Converter tab appears. ++ +{empty}[#Figure 117-10 ]##*_Converter Tab, Serialized Object Converter +Option_* image:convr_so.gif[Converter Tab, Serialized Object Converter +Option,title="Converter Tab, Serialized Object Converter Option"] +. To specify a serialized object converter, select the *Serialized +Object Converter* option. + +=== How to Configure a Serialized Object Converter Using Java + +You can set an +`+org.eclipse.persistence.converters.SerializedObjectConverter+` on any +instance of +`+org.eclipse.persistence.mappings.foundation.AbstractCompositeDirectCollectionMapping+` +or its subclasses using the `+AbstractCompositeDirectCollectionMapping+` +method `+setValueConverter+`, as this example shows. + +[#Example 117-11]## *_Configuring a SerializedObjectConverter in Java_* + +*`+//\'\' \'\'Create\'\' \'\'SerializedObjectConverter\'\' \'\'instance+`* +`+SerializedObjectConverter serializedObjectConvter = new SerializedObjectConverter();+` + +*`+//\'\' \'\'Set\'\' \'\'SerializedObjectConverter\'\' \'\'on\'\' \'\'ArrayMapping+`* +`+ArrayMapping arrayMapping = new ArrayMapping();+` +`+arrayMapping.setValueConverter(serializedObjectConvter);+` +`+arrayMapping.setAttributeName("responsibilities");+` +`+arrayMapping.setStructureName("Responsibilities_t");+` +`+arrayMapping.setFieldName("RESPONSIBILITIES");+` +`+orDescriptor.addMapping(arrayMapping);+` + +You can also set a `+SerializedObjectConverter+` on any instance of +`+org.eclipse.persistence.mappings.foundation.AbstractDirectMapping+` or +its subclasses using the `+AbstractDirectMapping+` method +`+setConverter+`. + +== Configuring a Type Conversion Converter + +A type conversion converter is used to explicitly map a data source type +to a Java type. + +For more information about the type conversion converter, see +link:Introduction%20to%20Mappings%20(ELUG)#Type_Conversion_Converter[Type +Conversion Converter]. + +This table summarizes which mappings support this option. + +[#Table 117-11]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Direct-to-Field Mapping + +Object-Relational Data Type Mappings + +Object-Relational Data Type Array Mapping + +EIS Mappings + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +=== How to Configure a Type Conversion Converter Using Workbench + +To create an type conversion direct mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Converter* tab. The Converter tab appears. +. Select the *Type Conversion Converter* option. +[#Figure 117-11]##*_Converter Tab, Type Conversion Converter Option_* +image:convr_tc.gif[Converter Tab, Type Conversion Converter +Option,title="Converter Tab, Type Conversion Converter Option"] +. Complete Type Conversion Converter fields on the Converter tab. + +Use the following information to complete the Type Conversion Converter +fields on the Converter tab: + +[width="100%",cols="<26%,<74%",options="header",] +|=== +|*Field* |*Description* +|*Data Type* |Select the Java type of the data in the data source. + +|*Attribute Type* |Select the Java type of the attribute in the Java +class. +|=== + +=== How to Configure a Type Conversion Converter Using Java + +You can set an +`+org.eclipse.persistence.converters.TypeConversionConverter+` on any +instance of +`+org.eclipse.persistence.mappings.foundation.AbstractCompositeDirectCollectionMapping+` +or its subclasses using the `+AbstractCompositeDirectCollectionMapping+` +method `+setValueConverter+`, as this exmaple shows. + +[#Example 117-12]## *_Configuring a TypeConversionConverter_* + +*`+//\'\' \'\'Create\'\' \'\'TypeConversionConverter\'\' \'\'instance+`* +`+TypeConversionConverter typeConversionConverter = new TypeConversionConverter();+` +`+typeConversionConverter.setDataClass(java.util.Calendar.class);   +` +`+typeConversionConverter.setObjectClass(java.sql.Date.class);+` + +*`+//\'\' \'\'Set\'\' \'\'TypeConversionConverter\'\' \'\'on\'\' \'\'ArrayMapping+`* +`+ArrayMapping arrayMapping = new ArrayMapping();+` +`+arrayMapping.setValueConverter(typeConversionConverter);+` +`+arrayMapping.setAttributeName("date");+` +`+arrayMapping.setStructureName("Date_t");+` +`+arrayMapping.setFieldName("DATE");+` +`+orDescriptor.addMapping(arrayMapping);+` + +You can also set a `+TypeConversionConverter+` on any instance of +`+org.eclipse.persistence.mappings.foundation.AbstractDirectMapping+` or +its subclasses using the `+AbstractDirectMapping+` method +`+setConverter+`. + +Configure the `+TypeConversionConverter+` instance using the following +API: + +* `+setDataClass(java.lang.Class dataClass)+`–to specify the data type +class. +* `+setObjectClass(java.lang.Class objectClass)+`–to specify the object +type class. + +== Configuring an Object Type Converter + +An object type converter is used to match a fixed number of data source +data values to Java object values. It can be used when the values in the +data source and in Java differ. + +For more information about the object type converter, see +link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter]. + +This table summarizes which mappings support this option. + +[#Table 117-12]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Object-Relational Data Type Mappings + +Object-Relational Data Type Array Mapping + +EIS Mappings + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +=== How to Configure an Object Type Converter Using Workbench + +To add an object type converter to a direct mapping, use this procedure: + +[arabic] +. Select the mapping in the *Navigator*. Its properties appear in the +Editor. +. Click the *Converter* tab. The Converter tab appears. +[#Figure 117-12]##*_Converter Tab, Object Type Converter_* +image:convr_ot.gif[Converter Tab, Object Type +Converter,title="Converter Tab, Object Type Converter"] +. Select the *Object Type Converter* option on the tab. + +Use the following fields on the mapping’s *Converter* tab to specify the +object type converter options: + +Field + +Description + +Data Type + +Select the Java type of the data in the data source. + +Attribute Type + +Select the Java type of the attribute in the Java class. + +Conversion Values + +Click Add to add a new conversion value. Click Edit to modify an +existing conversion value. Click Remove to delete an existing conversion +value. Use to specify the selected value as the default value. If +EclipseLink retrieves a value from the database that is not mapped as a +valid Conversion Value, the default value will be used. + +Data Value + +Specify the value of the attribute in the data source. + +Attribute Value + +Specify the value of the attribute in the Java class + +Default Attribute Value + +Specify whether or not to use the selected value as the default value. +If EclipseLink retrieves a value from the database that is not mapped as +a valid Conversion Value, the default value will be used. + +=== How to Configure an Object Type Converter Using Java + +You can set an +`+org.eclipse.persistence.converters.ObjectTypeConverter+` on any +instance of +`+org.eclipse.persistence.mappings.foundation.AbstractCompositeDirectCollectionMapping+` +using `+AbstractCompositeDirectCollectionMapping+` method +`+setValueConverter+`. + +You can also set an `+ObjectTypeConverter+` on any instance of +`+org.eclipse.persistence.mappings.foundation.AbstractDirectMapping+` or +its subclasses using the `+AbstractDirectMapping+` method +`+setConverter+`, as the following example shows. + +[#Example 117-13]## *_Configuring an ObjectTypeConverter in Java_* + +*`+//\'\' \'\'Create\'\' \'\'ObjectTypeConverter\'\' \'\'instance+`* +`+ObjectTypeConverter objectTypeConvter = new ObjectTypeConverter();+` +`+objectTypeConverter.addConversionValue("F", "Female");+` + +*`+//\'\' \'\'Set\'\' \'\'ObjectTypeConverter\'\' \'\'on\'\' \'\'DirectToFieldMapping+`* +`+DirectToFieldMapping genderMapping = new DirectToFieldMapping();+` +`+genderMapping.setConverter(objectTypeConverter);+` +`+genderMapping.setFieldName("F");+` +`+genderMapping.setAttributeName("Female");+` +`+descriptor.addMapping(genderMapping);+` + +Configure the `+ObjectTypeConverter+` instance using the following API: + +* `+addConversionValue(java.lang.Object fieldValue, java.lang.Object attributeValue)+`–to +associate data-type values to object-type values. +* `+addToAttributeOnlyConversionValue(java.lang.Object fieldValue, java.lang.Object attributeValue)+`–to +add one-way conversion values. +* `+setDefaultAttributeValue(java.lang.Object defaultAttributeValue)+`–to +set the default value. + +== Configuring a Simple Type Translator + +The simple type translator allows you to automatically translate an XML +element value to an appropriate Java type based on the element’s +attribute, as defined in your XML schema. You can use a simple type +translator only when the mapping’s XPath goes to an element. You cannot +use a simple type translator if the mapping’s XPath goes to an +attribute. + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Simple_Type_Translator[Simple +Type Translator]. + +This table summarizes which mappings support this option. + +Mapping + +Using Workbench + +Using Java + +EIS Mappings + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +=== How to Configure a Simple Type Translator Using Workbench + +Use this table to qualify elements from the XML schema + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-13]##*_General Tab, Use XML Schema "`type`" Attribute +Option_* image:xmlschtyp.gif[General Tab, Use XML Schema "`type`" +Attribute +Option,title="General Tab, Use XML Schema "type" Attribute Option"] +. Select the *Field Uses XML Schema "`type`" attribute* field to qualify +elements from the XML schema. + +=== How to Configure a Simple Type Translator Using Java + +To create an XML mapping with a simple type translator with Java code in +your IDE, you need the following elements: + +* `+EISDirectMapping+` or `+EISCompositeDirectCollectionMapping+` or +`+XMLDirectMapping+` or `+XMLCompositeDirectCollectionMapping+` +* instance of `+Converter+` +* instance of `+TypedElementField+` + +This example shows how to implement your own simple type translator with +an `+XMLDirectMapping+` to override the built-in conversion for writing +XML so that EclipseLink writes a `+Byte+` array +(`+ClassConstants.ABYTE+`) as a `+Base64+` +(`+XMLConstants.BASE64_BINARY+`) encoded string. + +[#Example 117-14]## *_Creating a Type Translation XML Mapping_* + +`+XMLDirectMapping mapping = new XMLDirectMapping();+` +`+mapping.setConverter(new SerializedObjectConverter());+` +`+TypedElementField field = new TypedElementField("element");+` +`+field.getSimpleTypeTranslator().addJavaConversion(+` +`+                          ClassConstants.ABYTE,+` +`+                          new QName(XMLConstants.SCHEMA_URL, XMLConstants.BASE64_BINARY));+` +`+mapping.setField(field);+` + +== Configuring a JAXB Typesafe Enumeration Converter + +The JAXB typesafe enumeration converter allows you to automatically +translate an XML element value to an appropriate typesafe enumeration +value as defined in your XML schema. + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_JAXB_Typesafe_Enumerations[Mappings +and JAXB Typesafe Enumerations]. + +This table summarizes which mappings support this option. + +[#'Table 117-14]## + +Mapping + +How to Use Workbench + +Using Java + +EIS Mappings 1 + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +XML Fragment Mapping + +XML Fragment Collection Mapping + +1When used with +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Record_Format[XML +records only]. The Workbench does not support the +`+JAXBTypesafeEnumConverter+` directly: to configure a mapping with this +converter, you must use Java to create an amendment method (see +link:#How_to_Configure_a_JAXB_Typesafe_Enumeration_Converter_Using_Java[Using +Java]). + +If you create a project and object model using the EclipseLink JAXB +compiler (see +link:Creating%20an%20XML%20Project%20(ELUG)#Creating_an_XML_Project_from_an_XML_Schema[Creating +an XML Project from an XML Schema]), the compiler will create the type +safe enumeration class and a class with descriptor amendment methods and +register the required amendment methods automatically (see +link:Introduction%20to%20XML%20Projects%20(ELUG)#Typesafe_Enumeration_Converter_Amendment_Method_DescriptorAfterLoads_Class[Typesafe +Enumeration Converter Amendment Method DescriptorAfterLoads Class]). + +=== How to Configure a JAXB Typesafe Enumeration Converter Using Java + +To configure a mapping with a `+JAXBTypesafeEnumConverter+` in Java, use +a descriptor amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]). This example illustrates an amendment method that +configures an `+XMLDirectMapping+` with a `+JAXBTypesafeEnumConverter+`. +In this example, attribute `+_Val+` is mapped to a JAXB typesafe +enumeration corresponding to typesafe enumeration class +`+MyTypesafeEnum+`. + +[#Example 117-15]## *_Creating a JAXB Typesafe Enumeration XML Mapping_* + +`+public class DescriptorAfterLoads {+` + +`+    public static void amendRootImplDescriptor(ClassDescriptor descriptor) {+` +`+        DatabaseMapping _ValMapping = descriptor.getMappingForAttributeName("_Val");+` +`+        JAXBTypesafeEnumConverter _ValConverter = new JAXBTypesafeEnumConverter();+` +`+        ValConverter.setEnumClassName("MyTypesafeEnum");+` +`+        ((XMLDirectMapping) _ValMapping).setConverter(_ValConverter);+` +`+    }+` `+}+` + +== Configuring Container Policy + +Collection mapping container policy specifies the concrete class +EclipseLink should use when reading target objects from the database. + +Collection mappings can use any concrete class that implements the +`+java.util.List+`, `+java.util.Set+`, `+java.util.Collection+`, or +`+java.util.Map+` interface. You can map object attributes declared as +`+List+`, `+Set+`, `+Collection+`, `+Map+`, or any subinterface of these +interfaces, or as a class that implements one of these interfaces. + +By default, the EclipseLink runtime uses the following concrete classes +from the `+org.eclipse.persistence.indirection+` package for each of +these container types: + +* `+List+`–`+IndirectList+` or `+Vector+` +* `+Set+`–`+IndirectSet+` or `+HashSet+` +* `+Collection+`–`+IndirectList+` or `+Vector+` +* `+Map+`–`+IndirectMap+` or `+HashSet+` + +Alternatively, you can specify in the mapping the concrete container +class to be used. When EclipseLink reads objects from the database that +contain an attribute mapped with a collection mapping, the attribute is +set with an instance of the concrete class specified. For example, +EclipseLink does not sort in memory. If you want to sort in memory, +override the default `+Set+` type (`+IndirectList+`) with +`+java.util.TreeSet+` as the concrete collection type. By default, a +collection mapping’s container class is `+java.util.Vector+`. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using Workbench and you override the default +`+Collection+` class with a custom `+Collection+` class of your own, you +must put your custom `+Collection+` class on the Workbench classpath +(see +link:Using%20Workbench%20(ELUG)#Configuring_the_Workbench_Environment[Configuring +the Workbench Environment]). +|=== + +This table summarizes which mappings support this option. + +[#Table 117-15]## + +Mapping + +List + +Set + +Collection + +Map + +Using Workbench + +Using Java + +Relational Mappings + +One-to-Many Mapping + +Many-to-Many Mapping + +Aggregate Collection Mapping + +Direct Collection Mapping + +Direct Map Mapping + +Object-Relational Data Type Mappings + +Object-Relational Data Type Array Mapping + +Object-Relational Data Type Object Array Mapping + +Object-Relational Data Type Nested Table Mapping + +EIS Mappings + +EIS Composite Direct Collection Mapping + +EIS Composite Collection Mapping + +EIS One-to-Many Mapping + +XML Mappings + +XML Composite Direct Collection Mapping + +XML Composite Collection Mapping + +XML Any Collection Mapping + +XML Choice Collection Mapping + +XML Any Attribute Mapping + +XML Binary Data Collection Mapping + +XML Collection Reference Mapping + +=== How to Configure Container Policy Using Workbench + +To specify a mapping’s container policy, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +. Click the *Advanced* button. The Advanced Container Options appear on +the General tab. [#Figure 117-14]##*_General Tab, Advanced Container +Options_* image:onetomany_coll_cont.gif[General Tab, Advanced Container +Options,title="General Tab, Advanced Container Options"] +. Complete *Advanced Container Options* on the tab. + +Use the following Advanced Container Options fields on the *General* tab +to specify the container options: + +Field 1 + +Description + +Container Type + +Specify the type of Collection class to use: + +List–use a java.util.List + +Set–use a java.util.Set + +Collection–use a java.util.Collection + +Map–use a java.util.Map + +Override Default Class + +Specify to use a custom class as the mapping’s container policy. Click +Browse to select a different class. The container class must implement +(directly or indirectly) the java.util.Collection interface. + +Key Method + +If you configure Container Type as Map, use this option to specify the +name of the zero argument method whose result, when called on the target +object, is used as the key in the Hashtable or Map. This method must +return an object that is a valid key in the Hashtable or Map. + +1Not all mappings support all options. For more information, see the +link:#Table_117-15[Mapping Support for Container Policy] table. + +=== How to Configure Container Policy Using Java + +Classes that implement the +`+org.eclipse.persistence.mappings.ContainerMapping+` interface provide +the following methods to set the container policy: + +* `+useCollectionClass(java.lang.Class concreteClass)+`–Configure the +mapping to use an instance of the specified `+java.util.Collection+` +container class to hold the target objects. +* `+useMapClass(java.lang.Class concreteClass, java.lang.String methodName)+`–Configure +the mapping to use an instance of the specified `+java.util.Map+` +container class to hold the target objects. The key used to index a +value in the `+Map+` is the value returned by a call to the specified +zero-argument method. The method must be implemented by the class (or a +superclass) of any value to be inserted into the `+Map+`. + +Classes that extend +`+org.eclipse.persistence.mappings.CollectionMapping+` (which implements +the `+ContainerMapping+` interface) also provide the following methods +to set the container policy: + +* `+useSortedSetClass(java.lang.Class concreteClass, java.util.Comparator comparator)+`–Configure +the mapping to use an instance of the specified `+java.util.SortedSet+` +container class. Specify the `+Comparator+` to use to sort the target +objects. + +The following example shows how to configure a +`+DirectCollectionMapping+` to use a `+java.util.ArrayList+` container +class. + +[#'Example 117-16]## *_Direct Collection Mapping_* + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'new\'\' \'\'mapping\'\' \'\'and\'\' \'\'register\'\' \'\'it\'\' \'\'with\'\' \'\'the\'\' \'\'source\'\' \'\'descriptor+`* +`+DirectCollectionMapping phonesMapping = new DirectCollectionMapping();+` +`+phonesMapping.setAttributeName("phones");+` +`+phonesMapping.setGetMethodName("getPhones");+` +`+phonesMapping.setSetMethodName("setPhones");+` +`+phonesMapping.setReferenceTableName("PHONES_TB");+` +`+phonesMapping.setDirectFieldName("PHONES");+` +`+phonesMapping.useCollectionClass(ArrayList.class); +`*`+//\'\' \'\'set\'\' \'\'container\'\' \'\'policy+`* +`+descriptor.addMapping(phonesMapping);+` + +== Configuring Attribute Transformer + +A transformation mapping is made up of an attribute transformer for +field-to-attribute transformation at read (unmarshall) time and one or +more field transformers for attribute-to-field transformation at write +(marshall) time (see +link:#Configuring_Field_Transformer_Associations[Configuring Field +Transformer Associations]). + +This section describes how to configure the attribute transformer that a +transformation mapping uses to perform the field-to-attribute +transformation at read (unmarshal) time. + +You can do this using either a method or class-based transformer. + +A method-based transformer must map to a method in the domain object. + +A class-based transformer allows you to place the transformation code in +another class, making this approach non-intrusive: that is, your domain +object does not need to implement an EclipseLink interface or provide a +special transformation method + +This table summarizes which mappings support this option. + +[#Table 117-16]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Transformation Mapping + +EIS Mappings + +EIS Transformation Mapping + +XML Mappings + +XML Transformation Mapping + +=== How to Configure Attribute Transformer Using Workbench + +To specify a mapping’s attribute transformer, use this procedure: + +[arabic] +. Select the transformation mapping in the *Navigator*. Its properties +appear in the Editor. [#Figure 117-15]##*_Transformation Mapping, +Attribute Transformer Field_* image:trmapatt.gif[Transformation Mapping, +Attribute Transformer +Field,title="Transformation Mapping, Attribute Transformer Field"] +. Click *Edit*. The Specify Transformer dialog box appears. +[#'Figure 117-16]##*_Specify Transformer Dialog Box_* +image:spstrans.gif[Specify Transformer Dialog +Box,title="Specify Transformer Dialog Box"] +. Complete each field on the Specify Transformer dialog box and click +*OK*. + +Use the following information to enter data in each field of the dialog +box and click *OK*: + +[width="100%",cols="<20%,<80%",options="header",] +|=== +|*Field* |*Description* +|*Use Transformation Method* |Select a specific method to control the +transformation. A method based transformer must map to a method in the +domain object. + +|*Use Transformer Class* |Select a specific class to control the +transformation. The class must be available on the Workbench application +classpath. +|=== + +=== How to Configure Attribute Transformer Using Java + +You can configure a method-based attribute transformer using +`+AbstractTransformationMapping+` method `+setAttributeTransformation+`, +passing in the name of the domain object method to use. + +You can configure a class-based attribute transformer using +`+AbstractTransformationMapping+` method `+setAttributeTransformer+`, +passing in an instance of +`+org.eclipse.persistence.mappings.Transfomers.AttributeTransformer+`. + +A convenient way to create an `+AttributeTransformer+` is to extend +`+AttributeTransformerAdapter+`. + +== Configuring Field Transformer Associations + +A transformation mapping is made up of an attribute transformer for +field-to-attribute transformation at read (unmarshall) time (see +link:#Configuring_Attribute_Transformer[Configuring Attribute +Transformer]) and one or more field transformers for attribute-to-field +transformation at write (marshall) time. + +This section describes how to configure the field transformers that a +transformation mapping uses to perform the object attribute-to-field +transformation at write (marshal) time. + +You can do this using either a method or class-based transformer. + +A method-based transformer must map to a method in the domain object. + +A class-based transformer allows you to place the transformation code in +another class, making this approach non-intrusive: that is, your domain +object does not need to implement an EclipseLink interface or provide a +special transformation method. + +This table summarizes which mappings support this option. + +[#Table 117-17]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +Transformation Mapping + +EIS Mappings + +EIS Transformation Mapping + +XML Mappings + +XML Transformation Mapping + +=== How to Configure Field Transformer Associations Using Workbench + +Use this procedure to complete the *Object->Field Method* fields: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. [#Figure 117-17]##*_Transformation Mapping, Field +Transformer Associations_* image:trmapfie.gif[Transformation Mapping, +Field Transformer +Associations,title="Transformation Mapping, Field Transformer Associations"] +. Click *Add* to add the necessary Field Transformer Associations for +the mapping. + +To add a new association, click *Add*. Continue with +link:#Specifying_Field-to-Transformer_Associations[Specifying +Field-to-Transformer Associations]. + +To change an existing association, click *Edit*. Continue with +link:#Specifying_Field-to-Transformer_Associations[Specifying +Field-to-Transformer Associations]. + +To delete an existing association, select the field transformation +association and click *Delete*. + +==== Specifying Field-to-Transformer Associations + +To specify the actual transformation method or class used for the field +of a transformation mapping, use this procedure. + +[arabic] +. From the Transformation Mapping, Field Transformer Associations, click +*Add* or Edit. The Specify Field-Transformer Association dialog box +appears. [#Figure 117-18]##*_Specify Field-Transformer Association +Dialog Box_* image:fldtramt.gif[Specify Field-Transformer Association +Dialog Box,title="Specify Field-Transformer Association Dialog Box"] +. Complete each field on the dialog box. + +Use the following information to complete each field on the dialog box: + +Field + +Description + +Field + +Select the database field (from the descriptor’s associated table) for +this transformation. + +Transformer + +Select one of the following methods to control the transformation: + +Use Transformation Method + +Select a specific method to control the transformation. A method based +transformer must map to a method in the domain object. + +Use Transformer Class + +Select a specific class to control the transformation. The class must be +available on Workbench application classpath. + +=== How to Configure Field Transformer Associations Using Java + +You can specify a specific transformation method on your domain object +or an instance of +`+org.eclipse.persistence.mappings.Transfomers.FieldTransformer+` (you +can also extend the `+FieldTransformerAdapter+`). Using a +`+FieldTransformer+` is non-intrusive: that is, your domain object does +not need to implement an EclipseLink interface or provide a special +transformation method. + +You can configure a method-based field transformer using +`+AbstractTransformationMapping+` method `+addFieldTransformation+`, +passing in the name of the database field and the name of the domain +object method to use. + +You can configure a class-based field transformer using +`+AbstractTransformationMapping+` method `+addFieldTransformer+`, +passing in the name of the database field and an instance of +`+org.eclipse.persistence.mappings.Transfomers.FieldTransformer+`. + +A convenient way to create a `+FieldTransformer+` is to extend +`+FieldTransformerAdapter+`. + +== Configuring Mutable Mappings + +Direct mappings typically map simple, nonmutable values such as +`+String+` or `+Integer+`. Transformation mappings can potentially map +complex mutable object values, such as mapping several database field +values to an instance of a Java class. + +If a transformation mapping maps a mutable value, EclipseLink must clone +and compare the value in a unit of work (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Configuring +Copy Policy]). + +By default, EclipseLink assumes that all transformation mappings are +mutable. If the mapping maps a simple immutable value, you can improve +the unit of work performance by configuring the *IsMutable* option to +`+false+`. + +By default, EclipseLink also assumes that all direct mappings are +mutable unless a serialized converter is used. These mappings can also +set the *IsMutable* option. You should set it if you want to modify +`+Date+` or `+Calendar+` fields. + +This table summarizes which mappings support this option. + +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Mutability[Mutability]. + +[#Table 117-18]## + +Mapping + +Using Workbench + +How to Use Java + +Relational Mappings + +Transformation Mapping + +Direct-to-Field Mapping + +EIS Mappings + +EIS Transformation Mapping + +EIS Direct Mapping + +XML Mappings + +XML Transformation Mapping + +XML Direct Mapping + +=== How to Configure Mutable Mappings Using Workbench + +Use this table to complete the *Object->Field Method* fields: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. [#'Figure 117-19]##*_Transformation Mapping, Mutable +Option_* image:trmute.gif[Transformation Mapping, Mutable +Option,title="Transformation Mapping, Mutable Option"] +. By default, the *IsMutable* option is selected in all transformation +mappings. If the mapping maps to a simple atomic value, unselect this +option. + +=== How to Configure Mutable Mappings Using Java + +You can specify whether or not a mapping is mutable using +`+AbstractTransformationMapping+` method `+setIsMutable+` for +transformation mappings, and `+AbstractDirectMapping+` method +`+isMutable+` for direct mappings. + +== Configuring Bidirectional Relationship + +EclipseLink can automatically manage the bidirectional relationship: if +one side of the relationship is set or modified, EclipseLink will +automatically set the other side. To enable this functionality, use the +value holder indirection (see +link:Introduction%20to%20Mappings%20(ELUG)#Value_Holder_Indirection[Value +Holder Indirection]) for one-to-one mappings, and transparent +collections (see +link:Introduction%20to%20Mappings%20(ELUG)#Transparent_Indirect_Container_Indirection[Transparent +Indirect Container Indirection])–for one-to-many and many-to-many +mappings. + +Note: We do not recommend using this EclipseLink feature: if the object +model is used outside the persistence context it must be responsible for +managing the bidirectional relationship. + +Instead, your application should maintain the bidirectional relationship +in its getter and setter methods. + +This table summarizes which mappings support this option. + +[#Table 117-19]## + +Mapping + +Using Workbench + +Using Java + +Relational Mappings + +One-to-One Mapping + +One-to-Many Mapping + +Many-to-Many Mapping + +EIS Mappings + +EIS One-to-One Mapping + +EIS One-to-Many Mapping + +=== How to Configure Bidirectional Relationship Using Workbench + +To maintain a bidirectional relationship for a mapping, use this +procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#'Figure 117-20]##*General tab, Maintains Bidirectional Relationship +option*’’ image:oogenbid.gif[General tab, Maintains Bidirectional +Relationship +option,title="General tab, Maintains Bidirectional Relationship option"] +. Complete the Bidirectional Relationship fields. + +Use this table to enter data in the following fields on the tab: + +[width="100%",cols="<24%,<76%",options="header",] +|=== +|*Field* |*Description* +|*Maintains Bidirectional Relationship* |Specify if EclipseLink should +maintain the bidirectional link for this relational mapping. + +|*Relationship Partner* |Select the relationship partner (from the list +of mapped attributes of the *Reference Descriptor*) for this +bidirectional relationship. +|=== + +=== How to Configure Bidirectional Relationship Using Java + +If a mapping has a bidirectional relationship in which the two classes +in the relationship reference each other with one-to-one mappings, then +set up the foreign key information as follows: + +* One mapping must call the `+setForeignKeyFieldName+` method. +* The other must call the `+setTargetForeignKeyFieldName+` method. + +You can also set up composite foreign key information by calling the +`+addForeignKeyFieldName+` and `+addTargetForeignKeyFieldName+` methods. +Because EclipseLink enables indirection (lazy loading) by default, the +attribute must be a `+ValueHolderInterface+`. + +Note: When your application does not use a cache, enable indirection for +at least one object in a bidirectional relationship. In rare cases, +disabling indirection on both objects in the bidirectional relationship +can lead to infinite loops. For more information, see the following: + +Directionality + +Indirection (Lazy Loading) + +The following example demonstrates setting of bidirectional relationship +between the `+Policy+` and `+Carrier+` classes. The foreign key is +stored in the `+Policy+`’s table referencing the composite primary key +of the `+Carrier+`. + +[#Example 120–18]## *_Implementing a Bidirectional Mapping Between Two +Classes that Reference Each Other_* + +`+public class Policy {+` `+   ...+` +`+   +`*`+//\'\' \'\'create\'\' \'\'the\'\' \'\'mapping\'\' \'\'that\'\' \'\'references\'\' \'\'the\'\' \'\'Carrier\'\' \'\'class+`* +`+   OneToOneMapping carrierMapping = new OneToOneMapping();+` +`+   carrierMapping.setAttributeName("carrier");+` +`+   carrierMapping.setReferenceClass(Carrier.class);+` +`+   carrierMapping.addForeignKeyFieldName("INSURED_ID", "CARRIER_ID");+` +`+   carrierMapping.addForeignKeyFieldName("INSURED_TYPE", "TYPE");+` +`+   descriptor.addMapping(carrierMapping);+` `+   ...+` `+}+` + +`+public class Carrier {+` `+   ...+` +`+   +`*`+//\'\' \'\'create\'\' \'\'the\'\' \'\'mapping\'\' \'\'that\'\' \'\'references\'\' \'\'the\'\' \'\'Policy\'\' \'\'class+`* +`+   OneToOneMapping policyMapping = new OneToOneMapping();+` +`+   policyMapping.setAttributeName("masterPolicy");+` +`+   policyMapping.setReferenceClass(Policy.class);+` +`+   policyMapping.addTargetForeignKeyFieldName("INSURED_ID", "CARRIER_ID");+` +`+   policyMapping.addTargetForeignKeyFieldName("INSURED_TYPE", "TYPE");+` +`+   descriptor.addMapping(policyMapping);+` `+   ...+` `+}+` + +== Configuring the Use of a Single Node + +For the XML-based mappings that the link:#Table_117-20[Mapping Support +for Use Single Node] table summarizes, when you map a list value, you +can configure whether or not the mapping unmarshalls (writes) the list +to a single node, like `+aaa bbb ccc+`, or to multiple nodes, like the +following: + +`+aaa+` `+bbb+` `+ccc+` + +This table summarizes which mappings support this option. + +[#Table 117-20]## + +Mapping + +Using Workbench + +Using Java + +EIS Mappings 1 + +EIS Direct Mapping + +EIS Composite Direct Collection Mapping + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +1When used with +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Record_Format[XML +records only]. + +=== How to Configure the Use of a Single Node Using Workbench + +o configure a mapping to use a single node, use this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 117-21]##*_General Tab, Use Single Node Option_* +image:usesingle.gif[General Tab, Use Single Node +Option,title="General Tab, Use Single Node Option"] +. Complete the *Use single node* field on the tab. + +To configure the mapping to unmarshall (write) a list value to a single +node (like `+aaa bbb ccc+`), click *Use single node*. + +By default, the mapping unmarshalls a list value to separate nodes. + +=== How to Configure the Use of a Single Node Using Java + +Use `+AbstractCompositeDirectCollectionMapping+` method +`+setUsesSingleNode+` to configure the mapping to write a list value to +a single node by passing in a value of `+true+`. To configure the +mapping to write a list value to multiple nodes, pass in a value of +`+false+`. + +For any mapping that takes an `+XMLField+`, use `+XMLField+` method +`+setUsesSingleNode+` to configure the mapping to write a list value to +a single node by passing in a value of `+true+`. To configure the +mapping to write a list value to multiple nodes, pass in a value of +`+false+`. This example shows how to use this method with an +`+XMLDirectMapping+`: + +[#Example 117-17]## *_Using XMLField Method setUsesSingleNode_* + +`+XMLDirectMapping tasksMapping = new XMLDirectMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+XMLField myField = new XMLField("tasks/text()"); +`*`+//\'\' \'\'pass\'\' \'\'in\'\' \'\'the\'\' \'\'XPath+`* +`+myField.setUsesSingleNode(true);+` `+tasksMapping.setField(myField);+` + +== Configuring the Use of CDATA + +For the XML-based mappings that the link:#Table_117-6[Mapping Support +for Default Null Values] table summarizes, when you create a mapping, +you can configure whether or not the mapping’s text is wrapped in a +statement. + +This table summarizes which mappings support this option. + +[#Table 117-21]## + +Mapping + +Using Workbench + +Using Java + +XML Mappings + +XML Direct Mapping + +XML Composite Direct Collection Mapping + +XML Binary Data Mapping + +XML Binary Data Collection Mapping + +=== How to Configure the Use of CDATA Using Java + +Use the `+isCDATA()+` method on an `+XMLDirectMapping+` or +`+XMLCompositeDirectCollectionMapping+` to specify if the mapping’s text +is wrapped in a statement. The following example shows the results of +using this method: + +[#Example 117-18]## *_Using CDATA_* + +When `+isCDATA = false+` on the name mapping, EclipseLink writes the +text as a regular text node: + +`+  +``+Jane Doe+` + +When `+isCDATA = true+` on the name mapping, EclipseLink wraps the text +in a statement: + +`+  +` `+    +` `+  +` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Release_1[Category: Release 1] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Project_(ELUG).adoc new file mode 100644 index 00000000000..93387e980c6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Project_(ELUG).adoc @@ -0,0 +1,915 @@ +*TOC* Special:Whatlinkshere_Configuring_a_Project_(ELUG)[Related Topics] + +This section describes how to configure EclipseLink project options +common to two or more project types. + +This table lists the types of EclipseLink projects that you can +configure and provides a cross-reference to the type-specific chapter +that lists the configurable options supported by that type. + +[#Table 113-1]## + +If you are creating… + +See also… + +Relational Projects + +Configuring a Relational Project + +EIS Projects + +Configuring an EIS Project + +XML Projects + +Configuring an XML Project + +The link:#Table_113-2[Common Project Options] table lists the +configurable options shared by two or more EclipseLink project types. + +For more information, see the following: + +* link:Creating%20a%20Project%20(ELUG)#Introduction_to_the_Project_Creation[Introduction +to the Project Creation] +* link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects] + +== Configuring Common Project Options + +This table lists the configurable options shared by two or more +EclipseLink project types. In addition to the configurable options +described here, you must also configure the options described for the +specific EclipseLink project types (see +link:Introduction%20to%20Projects_(ELUG)#EclipseLink_Project_Types[EclipseLink +Project Types]), as shown in the link:#Table_113-1[Configuring +EclipseLink Projects] table. + +[#Table 113-2]## + +Option to Configure + +EclipseLink Workbench + +Java + +Project save location + +Classpath + +Method or direct field access + +Default descriptor advanced properties + +Existence checking + +Deployment XML options + +Model Java source code options + +Cache type and size + +Cache isolation + +Cache coordination change propagation + +Cache expiration + +Comments + +== Configuring Project Save Location + +You can configure a project save location only when using Workbench. + +This table summarizes which projects support a project save location. + +[#Table 113-3]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +=== How to Configure Project Save Location Using Workbench + +The Project Save Location field on the project’s General tab is for +display only. This field shows the full directory path for the project. +All relative locations used in the project are based on this location. + +{empty}[#Figure 113-1]## *’’ General Tab, Project Save Location*’’ +image:saveloc.gif[General Tab, Project Save +Location,title="General Tab, Project Save Location"] + +To select a new location, right-click on the project in the *Navigator* +and select *Save As* from the context menu. See +link:Creating%20a%20Project%20(ELUG)#How_to_Save_Projects[How to Save +Projects] for more information. + +== Configuring Project Classpath + +The EclipseLink project uses a classpath – a set of directories, JAR +files, and ZIP files – when importing Java classes and defining object +types. + +This table summarizes which projects support project classpath +configuration. + +[#Table 113-4]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +Do not include JDBC drivers or other elements required to access the +data source in the project classpath. Use the `+setenv+` file to specify +these application-level settings (see +link:Using%20Workbench%20(ELUG)#Configuring_the_Workbench_Environment[Configuring +the Workbench Environment]). + +After you configure the project classpath, you can use Workbench to +import classes into your project (see +link:Using%20Workbench%20(ELUG)#How_to_Import_and_Update_Classes[How to +Import and Update Classes]). + +=== How to Configure Project Classpath Using Workbench + +To specify the project classpath information, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Click the *General* tab in the *Editor*. The General tab appears. +[#Figure 113-2]##*_General Tab, Classpath Options_* +image:genclassp.gif[General Tab, Classpath +Options,title="General Tab, Classpath Options"] + +To add a new classpath entry, click *Add Entry* or *Browse* and select +the directory, `+.jar+` file, or `+.zip+` file for this project. To +create a relative classpath, select an entry and edit the path, as +necessary. The path will be relative to the *Project Save Location*. + +To remove a classpath entry, select the entry and click *Remove*. + +To change the order of the entries, select the entry and click *Up* or +*Down*. + +== Configuring Method or Direct Field Access at the Project Level + +By default, when EclipseLink performs a persistence operation, it +accesses the persistent attributes of an object directly: this is known +as direct field access. Alternatively, you can configure EclipseLink to +access persistent attributes using accessor methods of the object: this +is known as method access. + +We recommend using field access for mappings. Not only is it more +efficient, but using method access may cause issues if the method +produces unexpected side-effects. + +This table summarizes which projects support mapped field access +configuration. + +[#Table 113-5]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +This section describes configuring mapped field access at the project +level: by default, this configuration applies to all descriptors and +their mappings. + +[width="100%",cols="<100%",] +|=== +|*Note*: If you change the access default, existing mappings retain +their current access settings, but new mappings will be created with the +new default. +|=== + +You can also configure mapped field access at the mapping level to +override this project-level configuration on a mapping-by-mapping basis. +For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]. + +If you enable change tracking on a property (for example, you decorate +method `+getPhone+` with `+@ChangeTracking+`) and you access the field +(`+phone+`) directly, note that EclipseLink does not detect the change. +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Method_and_Direct_Field_Access[Using +Method and Direct Field Access]. + +=== How to Configure Method or Direct Field Access at the Project Level Using Workbench + +To specify the field access method information, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-3]##*_Defaults Tab, Field Accessing Options_* +image:genfield.gif[Defaults Tab, Field Accessing +Options,title="Defaults Tab, Field Accessing Options"] +. Complete the Mapped Field Accessing options. + +== Configuring Default Descriptor Advanced Properties + +You can configure default descriptor advanced properties when using the +Workbench. + +By default, Workbench displays a subset of features for each descriptor +type. You can modify this subset so that descriptors include additional +advanced properties by default. + +You can also select specific advanced properties for individual +descriptors (see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring +a Descriptor]). + +This table summarizes which projects support default descriptor advanced +property configuration. + +[#Table 113-6]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +=== How to Configure Default Descriptor Advanced Properties Using Workbench + +To specify the default advanced properties for newly created descriptors +in your project, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-4]##*_Defaults Tab, Descriptor Advanced Properties_* +image:desadv.gif[Defaults Tab, Descriptor Advanced +Properties,title="Defaults Tab, Descriptor Advanced Properties"] + +Select which *Descriptor Advanced Properties* to add to newly created +descriptors. The list of advanced properties will vary, depending on the +project type. + +*See Also* + +link:#Configuring_Default_Descriptor_Advanced_Properties[Configuring +Default Descriptor Advanced Properties] + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +link:#Configuring_a_Project[Configuring a Project] + +== Configuring Existence Checking at the Project Level + +When EclipseLink writes an object to the database, it runs an existence +check to determine whether to perform an insert or an update operation. + +By default, EclipseLink checks against the cache. We recommend that you +use this default existence check option for most applications. Checking +the database for existence can cause a performance bottleneck in your +application. + +This table summarizes which projects support existence checking +configuration. + +[#Table 113-7]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +By default, this configuration applies to all descriptors in a project. +You can also configure existence checking at the descriptor level to +override this project-level configuration on a descriptor-by-descriptor +basis. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Existence_Checking_at_the_Descriptor_Level[Configuring +Cache Existence Checking at the Descriptor Level]. + +For more information see the following: + +* link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Queries_and_the_Cache[Queries +and the Cache] +* link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_Registration_and_Existence_Checking[How +to Use Registration and Existence Checking] + +=== How to Configure Existence Checking at the Project Level Using Workbench + +To specify the existence checking information, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-5]##*_Defaults Tab, Existence Checking Options_* +image:existnc.gif[Defaults Tab, Existence Checking +Options,title="Defaults Tab, Existence Checking Options"] +. Complete the Existence Checking options on the tab. + +Use this table to enter data in following fields to specify the +existence checking options for newly created descriptors: + +[width="100%",cols="<7%,<93%",options="header",] +|=== +|*Field* |*Description* +|*Check Cache* |Check the session cache. If the object is not in the +cache, assume that the object does not exist (do an insert). If the +object is in the cache, assume that the object exists (do an update). We +recommend using this option for most applications. + +|*Check Database* |If an object is not in the cache, query the database +to determine if the object exists. If the object exists, do an update. +Otherwise, do an insert. Selecting this option may negatively impact +performance. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Check_Database[Using +Check Database]. + +|*Assume Existence* |Always assume objects exist: always do an update +(never do an insert). For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Existence[Using +Assume Existence]. + +|*Assume Nonexistence* |Always assume objects do not exist: always do an +insert (never do an update). For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Assume_Nonexistence[Using +Assume Nonexistence]. +|=== + +== Configuring Project Deployment XML Options + +You can configure project deployment XML options when using Workbench. + +Using Workbench, you can specify the default file names, class names, +and directories, when exporting or generating deployment XML. +Directories are relative to the project save location (see +link:#Configuring_Project_Save_Location[Configuring Project Save +Location]), and will contain folders for each generated package. + +This table summarizes which projects support deployment XML options. + +[#Table 113-8]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +=== How to Configure Project Deployment XML Options Using Workbench + +To specify the default export options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Options* tab in the *Editor*. The Options tab appears. +[#Figure 113-6]##*_Options Tab, Project Deployment XML Options_* +image:prjoptxml.gif[Options Tab, Project Deployment XML +Options,title="Options Tab, Project Deployment XML Options"] +. Complete the fields on the [topicid:project.options.deployment Project +Deployment XML options] on the tab. + +Use this table to enter data in following fields to specify the default +Project Deployment XML options: + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Field* |*Description* +|*File Name* |File name (such as `+project.xml+`) to use when generating +project deployment XML. + +|*Directory* |Directory in which to save the generated deployment XML +file. +|=== + +*See Also* + +link:#Configuring_Project_Deployment_XML_Options[Configuring Project +Deployment XML Options] + +link:#Configuring_a_Project[Configuring a Project] + +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information] + +== Configuring Model Java Source Code Options + +You can configure model java source code options when using the +Workbench. + +Using Workbench, you can specify the default file names, class names, +and directories, when exporting or generating Java source code for your +domain objects. Directories are relative to the project save location +(see link:#Configuring_Project_Save_Location[Configuring Project Save +Location]), and will contain folders for each generated package. + +This table summarizes which projects support model Java source code +options. + +[#Table 113-9]## *_Project Support for Model Java Source Options_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +=== How to Configure Model Java Source Code Options Using Workbench + +To specify the default export options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Options* tab in the *Editor*. The Options tab appears. +[#Figure 113-7]##*_Options Tab, Model Java Source options_* +image:prjoptmd.gif[Options Tab, Model Java Source +options,title="Options Tab, Model Java Source options"] +. Complete the fields on the Model Java Source options on the tab. +. Specify the project root directory to which Workbench generates model +Java source files. For more information, see +link:Creating%20a%20Descriptor%20(ELUG)#Generating_Java_Code_for_Descriptors[Generating +Java Code for Descriptors]. + +*See Also* + +link:#Configuring_a_Project[Configuring a Project] + +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information] + +== Configuring Cache Type and Size at the Project Level + +The EclipseLink cache is an in-memory repository that stores recently +read or written objects based on class and primary key values. +EclipseLink uses the cache to achieve the following: + +* improve performance by holding recently read or written objects and +accessing them in-memory to minimize database access; +* manage locking and isolation level; +* manage object identity. + +This table summarizes which projects support identity map configuration. + +[#'Table 113-10]## *_Project Support for Identity Map Configuration_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +The cache options you configure at the project level apply globally to +all descriptors. Use this section to define global cache options for an +EclipseLink project. + +You can override the project-level identity map configuration by +defining identity map configuration at the descriptor level. For +information on caching and defining identity map configuration for a +specific descriptor, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]. + +[width="100%",cols="<100%",] +|=== +|*Note*: When using Workbench, changing the project’s default identity +map does not affect descriptors that already exist in the project; only +newly added descriptors ar affected. +|=== + +For detailed information on caching and object identity, and the +recommended settings to maximize EclipseLink performance, see to +link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity]. + +For more information about the cache, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +=== How to Configure Cache Type and Size at the Project Level Using Workbench + +To specify the cache identity map, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-8]##*_Defaults Tab, Cache Identity Map Options_* +image:projident.gif[Defaults Tab, Cache Identity Map +Options,title="Defaults Tab, Cache Identity Map Options"] +. Complete the *Caching* options on the tab. + +Use this table to enter data in each of the following fields to specify +the caching options: + +Field + +Description + +Type + +Use the Type list to choose the identity map as follows: + +Weak with Soft Subcache – cache first n elements in soft space, anything +after that in weak space (see SoftCacheWeakIdentityMap). + +Weak with Hard Subcache – cache first n elements in soft space, anything +after that in hard space (see HardCacheWeakIdentityMap). + +Weak – cache everything in weak space (see WeakIdentityMap). + +Soft – cache everything in soft space (see SoftIdentityMap). + +Full – cache everything permanently (see FullIdentityMap). + +None – cache nothing (see No Identity Map|NoIdentityMap). + +For more information, see Cache Type and Object Identity. + +Changing the project’s default identity map does not affect descriptors +that already exist in the project. + +Size + +Specify the size of the cache as follows: + +When using Weak with Soft Subcache or Weak with Hard Subcache, the size +is the maximum number of objects stored in the identity map. + +When using Full or Weak, the size indicates the starting size of the +identity map. + +=== How to Configure Cache Type and Size at the Project Level Using Java + +Use one of the following `+ClassDescriptor+` methods to configure the +descriptor to use the appropriate type of identity map: + +* `+useFullIdentitMap+` +* `+useWeakIdentitMap+` +* `+useSoftIdentitMap+` +* `+useSoftCacheWeakIdentitMap+` +* `+useHardCacheWeakIdentityMap+` +* `+useNoIdentityMap+` + +Use the `+ClassDescriptor+` method `+setIdentityMapSize+` to configure +the size of the identity map. + +== Configuring Cache Isolation at the Project Level + +If you plan to use isolated sessions (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[Cache +Isolation]), you must configure descriptors as isolated for any object +that you want confined to an isolated session cache. + +Configuring a descriptor to be isolated means that EclipseLink will not +store the object in the shared session cache and the object will not be +shared across client sessions. This means that each client will have +their own object read directly from the database. Objects in an isolated +client session cache can reference objects in their parent server +session’s shared session cache, but no objects in the shared session +cache can reference objects in an isolated client session cache. +Isolation is required when using Oracle Database Virtual Private +Database (VPD) support or database user-based read security. Isolation +can also be used if caching is not desired across client sessions. + +This table summarizes which projects support cache isolation +configuration. + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +The cache isolation options you configure at the project level apply +globally to all descriptors. Use this section to define global options +for an EclipseLink project. + +You can override the project-level configuration by defining cache +isolation options at the descriptor level. For information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]. + +[width="100%",cols="<100%",] +|=== +|*Note*: When using Workbench, changing the project’s default cache +isolation option does not affect descriptors that already exist in the +project; only newly added descriptors ar affected. +|=== + +=== How to Configure Cache Isolation at the Project Level Using Workbench + +To specify the cache isolation options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-9]##*_Defaults Tab, Cache Isolation Options_* +image:projisol.gif[Defaults Tab, Cache Isolation +Options,title="Defaults Tab, Cache Isolation Options"] +. Complete the Isolation option on the tab. Use the *Isolation* list to +choose one of the following: +* *Isolated* – if you want all objects confined to an isolated client +session cache. For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[Cache +Isolation]. +* *Shared* – if you want all objects visible in the shared session cache +(default). + +== Configuring Cache Coordination Change Propagation at the Project Level + +If you plan to use a coordinated cache (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]), you can configure how and under what conditions a +coordinated cache propagates changes. + +This table summarizes which projects support cache coordination change +propagation configuration. + +[#Table 113-12]## *_Project Support for Cache Coordination Change +Propagation Configuration_* + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +The cache coordination change propagation options you configure at the +project level apply globally to all descriptors. Use this section to +define global options for an EclipseLink project. + +You can override the project-level configuration by defining cache +coordination change propagation options at the descriptor level. For +information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level]. + +To complete your coordinated cache configuration, see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Coordinated_Cache[Configuring +a Coordinated Cache]. + +[width="100%",cols="<100%",] +|=== +|*Note*: When using Workbench, changing the project’s default cache +coordination change propagation option does not affect descriptors that +already exist in the project; only newly added descriptors ar affected. +|=== + +=== How to Configure Cache Coordination Change Propagation at the Project Level Using Workbench + +To specify the coordinated cache change propagation options, use this +procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-10]##*_Defaults Tab, Coordination Options_* +image:projcord.gif[Defaults Tab, Coordination +Options,title="Defaults Tab, Coordination Options"] +. Complete the *Coordination* option] on the tab. + +Use the following information to enter data in the Coordination field: + +[width="100%",cols="<8%,<59%,<33%",options="header",] +|=== +|*Coordination Option* |*Description* |*When to Use* +|*None* |For both existing and new instances, do not propagate a change +notification. |Infrequently read or changed objects. + +|*Synchronize Changes* |For an existing instance, propagate a change +notification that contains each changed attribute. For a new instance, +propagate an object creation (along with all the new instance’s +attributes) only if the new instance is related to other existing +objects that are also configured with this change propagation option. +|Frequently read or changed objects that contain few attributes or in +cases where only a few attributes are frequently changed. Objects that +have many or complex relationships. + +|*Synchronize Changes and New Objects* |For an existing instance, +propagate a change notification that contains each changed attribute. +For a new instance, propagate an object creation (along with all the new +instance’s attributes). |Frequently read or changed objects that contain +few attributes or in cases where only a few attributes are frequently +changed. Objects that have few or simple relationships. + +|*Invalidate Changed Objects* |For an existing instance, propagate an +object invalidation that marks the object as invalid in all other +sessions. This tells other sessions that they must update their cache +from the data source the next time this object is read. For a new +instance, no change notification is propagated. |Frequently read or +changed objects that contain many attributes in cases where many of the +attributes are frequently changed. +|=== + +== Configuring Cache Expiration at the Project Level + +By default, objects remain in the cache until they are explicitly +deleted (see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Deleting_Objects[Deleting +Objects]) or garbage-collected when using a weak identity map (see +link:#Configuring_Cache_Type_and_Size_at_the_Project_Level[Configuring +Cache Type and Size at the Project Level]). Alternatively, you can +configure an object with a `+CacheInvalidationPolicy+` that lets you +specify, either automatically or manually, that an object is invalid: +when any query attempts to read an invalid object, EclipseLink will go +to the data source for the most up-to-date version of that object and +update the cache with this information. + +Using cache invalidation ensures that your application does not use +stale data. It provides a better performing alternative to refreshing +(see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Refreshing[Configuring +Cache Refreshing]). + +This table summarizes which projects support cache invalidation +configuration. + +[#Table 113-13]## + +Descriptor + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +The cache invalidation options you configure at the project level apply +globally to all descriptors. Use this section to define global cache +invalidation options for an EclipseLink project. + +You can override the project-level cache invalidation configuration by +defining cache invalidation at the descriptor (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Expiration_at_the_Descriptor_Level[Configuring +Cache Expiration at the Descriptor Level]) or query level (see +link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Configure_Cache_Expiration_at_the_Query_Level[How +to Configure Cache Expiration at the Query Level]). + +You can customize how EclipseLink communicates the fact that an object +has been declared invalid to improve efficiency if you are using a +coordinated cache. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level]. + +[width="100%",cols="<100%",] +|=== +|*Note*: When using Workbench, changing the project’s default cache +invalidation does not affect descriptors that already exist in the +project; only newly added descriptors are affected. +|=== + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Invalidation[Cache +Invalidation]. + +=== How to Configure Cache Expiration at the Project Level Using Workbench + +To specify the cache expiration options for the project, use this +procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 113-11]##*_Defaults Tab, Cache Expiry Options_* +image:cachexp.gif[Defaults Tab, Cache Expiry +Options,title="Defaults Tab, Cache Expiry Options"] +. Complete the Cache Expiry options on the tab. + +Use this table to enter data in the following fields on this tab: + +[width="100%",cols="<14%,<86%",options="header",] +|=== +|*Field* |*Description* +|*No Expiry* |Specify that objects in the cache do not expire. + +|*Time to Live Expiry* |Specify that objects in the cache will expire +after a specified amount of time. Use the *Expire After* field to +indicate the time (in milliseconds) after which the objects will expire. + +|*Daily Expiry* |Specify that objects in the cache will expire at a +specific time each day. Use the *Expire At* field to indicate the exact +time to the second (using a 24-hour clock) at which the objects will +expire. + +|*Update Read Time on Update* |Specify if the expiry time should be +reset after updating an object. +|=== + +[width="100%",cols="<100%",] +|=== +|*Note:* These options apply to all descriptors in a project. See +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Expiration_at_the_Descriptor_Level[Configuring +Cache Expiration at the Descriptor Level] for information on configuring +descriptor-specific options. +|=== + +== Configuring Project Comments + +You can define a free-form textual comment for each project. You can use +these comments however you whish: for example, to record important +project implementation details such as the purpose or importance of a +project. + +In a Workbench project, the comments are stored in the EclipseLink +deployment XML file. There is no Java API for this feature. + +This table summarizes which projects support this option. + +[#Table 113-14]## + +Project Type + +Using the Workbench + +Using Java + +Relational Projects + +EIS Projects + +XML Projects + +=== How to Configure Project Comments Using Workbench + +To specify a comment for the project, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *General* tab in the *Editor*. The General tab appears. +[#Figure 113-12]##*_General Tab, Comments Options_* +image:gencomment.gif[General Tab, Comments +Options,title="General Tab, Comments Options"] +. Enter descriptive text information in the *Comment* field. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..445eacc1f98 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,94 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Aggregate_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +[width="100%",cols="<100%",] +|=== +|*Note*: To use a relational aggregate collection mapping with +Workbench, you must use +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[an +amendment method]. +|=== + +This table lists the configurable options for a relational aggregate +collection mapping. + +[#Table 40-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_a_Database_Field[Database +field] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Reference +descriptor] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Container +policy] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Batch +reading] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Bidirectional +relationship] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Query_Key_Order[Query +key order] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Configuring +Configuring Table and Field References] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a aggregate collection mapping and add +it to a descriptor using Java code. + +[#Example 42-1]## *_Aggregate Collection Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + AggregateCollectionMapping mapping = new AggregateCollectionMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +Collection Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Object_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Object_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..7a8487fc87e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Aggregate_Object_Mapping_(ELUG).adoc @@ -0,0 +1,165 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Aggregate_Object_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +[width="100%",cols="<100%",] +|=== +|*Note:* You configure the relational aggregate object mapping in the +source object’s descriptor. However, before doing so, you must designate +the target object’s descriptor as an aggregate (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Configuring +a Relational Descriptor as a Class or Aggregate Type]). +|=== + +This table lists the configurable options for a relational aggregate +object mapping. + +[#Table 42-1]## + +[width="100%",cols="<64%,<16%,<20%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Reference +descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Allowing_Null_Values[Allowing null values] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:#Configuring_Aggregate_Fields[Aggregate fields] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a aggregate object mapping and add it +to a descriptor using Java code. + +[#Example 44-1]## *_Aggregate Object Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + AggregateObjectMapping mapping = new AggregateObjectMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Object_Mapping[Aggregate +Object Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +== Configuring Aggregate Fields + +When you designate a descriptor as an aggregate, EclipseLink allows you +to specify a mapping type for each field in the target class, but defers +associating the field with a database table until you configure the +aggregate object mapping in the source class descriptor. In other words, +the target class descriptor defines how each target class field is +mapped but the source class descriptor defines where each target class +field is mapped. + +This section explains how to configure the source class descriptor to +define where each target class field is mapped. + +For more information on how to configure the target class descriptor to +define how each target class field is mapped, see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Configuring +a Relational Descriptor as a Class or Aggregate Type]. + +=== How to Configure Aggregate Fields Using Workbench + +To specify the mapped fields of an aggregate mapping, use this +procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Fields* tab. The Fields tab appears. +[#Figure 42-1]##*_Fields Tab_* image:agmapfie.gif[Fields +Tab,title="Fields Tab"] +. Complete the fields on the *Fields* tab. + +Use the following information to complete each field on the tab: + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*Field* |*Description* +|*Field Description* |This column shows the name of the fields from the +target object, whose descriptor is designated +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[as +an aggregate]. These are for display only and cannot be changed. + +|*Fields* |Use this column to select the source object database table +field that EclipseLink will map to the corresponding target object +field. +|=== + +=== How to Configure Aggregate Fields Using Java + +Using the `+AggregateObjectMapping+` method `+addFieldNameTranslation+` +you can set a field name translation that maps from a field name in the +source table to a field name in the aggregate descriptor + +For more information about the available methods for +`+AggregateObjectMapping+`, see the _EclipseLink API Reference_. + +== Configuring Allowing Null Values + +If all the fields in the database row for the aggregate object are +`+null+`, then, by default, EclipseLink places `+null+` in the +appropriate source object, as opposed to filling an aggregate object +with `+null+` values. + +=== How to Configure Allowing Null Values Using Workbench + +To allow a mapping to contain a null value, use this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 42-2]##*_General Tab, Allow Null Option_* +image:agmapnul.gif[General Tab, Allow Null +Option,title="General Tab, Allow Null Option"] +. Select the *Allows Null* option to allow this mapping to contain a +null value. + +=== How to Configure Allowing Null Values Using Java + +You can configure whether or not to allow null values using the +`+AggregateObjectMapping+` methods `+allowNull+` and `+dontAllowNull+`. + +For more information about the available methods for +`+AggregateObjectMapping+`, see the _EclipseLink API Reference_. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..a15c38b7df2 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Descriptor_(ELUG).adoc @@ -0,0 +1,960 @@ +*TOC* +Special:Whatlinkshere_Creating_a_Relational_Descriptor_(ELUG)[Related +Topics] + +For information on how to create relational descriptors, see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating a +Relational Descriptor]. + +This table lists the default configurable options for a relational +descriptor. + +[width="100%",cols="<66%,<17%,<17%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_Associated_Tables[Associated tables] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[Primary +keys] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Sequencing_at_the_Descriptor_Level[Sequencing] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Read-Only_Descriptors[Read-only +descriptors] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Unit_of_Work_Conforming_at_the_Descriptor_Level[Unit +of work conforming] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Descriptor_Alias[Descriptor +alias] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Descriptor_Comments[Descriptor +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Using%20Workbench%20(ELUG)#How_to_Configure_Classes[Classes] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Queries_at_the_Descriptor_Level[Named +queries] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Custom_SQL_Queries_for_Basic_Persistence_Operations[Custom +SQL queries for basic persistence operations] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Query_Timeout_at_the_Descriptor_Level[Query +timeout] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Refreshing[Cache +refreshing] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Query_Keys[Query +keys] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Interface_Query_Keys[Interface +query keys] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_Interface_Alias[Interface alias] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Cache +type and size] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Cache +isolation] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Cache +coordination change propagation] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Expiration_at_the_Descriptor_Level[Cache +expiration] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Existence_Checking_at_the_Descriptor_Level[Cache +existence Checking] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Relational +descriptor as a class or aggregate type] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Reading_Subclasses_on_Queries[Reading +subclasses on queries] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Inheritance +for a child class descriptor] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Parent_(Root)_Descriptor[Inheritance +for a parent class descriptor] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_Expressions_for_a_Parent_(Root)_Class_Descriptor[Inheritance +expressions for a parent class descriptor] +|image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inherited_Attribute_Mapping_in_a_Subclass[Inherited +attribute mapping in a subclass] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_Multitable_Information[(see] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Domain_Object_Method_as_an_Event_Handler[Domain +object method as an event handler] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Descriptor_Event_Listener_as_an_Event_Handler[Descriptor +event listener as an event handler] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Locking +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Returning_Policy[Returning +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Instantiation_Policy[Instantiation +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Copy +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[Change +policy] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_History_Policy[History +policy] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Wrapper_Policy[Wrapper +policy] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Fetch_Groups[Fetch +groups] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods#Configuring_Amendment_Methods[Amendment +methods] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Mapping[Mappings] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see +link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Introduction +to Relational Descriptors]. + +== Configuring Associated Tables + +Each relational class descriptor (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Class Descriptors]) must be associated with a database table for storing +instances of that class. This does not apply to relational aggregate +descriptors (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). + +=== How to Configure Associated Tables Using Workbench + +To associate a descriptor with a database table, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Associated Table Options +_*image:desasstbl.gif[Descriptor Info Tab, Associated Table +Options,title="Descriptor Info Tab, Associated Table Options"] +. Use the *Associated Table* list to select a database table for the +descriptor. You must associate a descriptor with a database table +_before_ specifying primary keys. + +See Also: + +link:#Configuring_Associated_Tables[Configuring Associated Tables] + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +=== How to Configure Associated Tables Using Java + +To configure a descriptor’s associated table(s) using Java, use +`+RelationalDescriptor+` methods `+setTableName+` or `+addTableName+`. + +== Configuring Sequencing at the Descriptor Level + +Sequencing allows EclipseLink to automatically assign the primary key or +ID of an object when the object is inserted. + +You configure EclipseLink sequencing at the +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[project +level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[session +level] to tell EclipseLink how to obtain sequence values: that is, what +type of sequences to use. + +To enable sequencing, you must then configure EclipseLink 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. + +Only descriptors that have been configured with a sequence field and a +sequence name will be assigned sequence numbers. + +The sequence field is the database field that the sequence number will +be assigned to: this is almost always the +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[primary +key field]. The sequence name is the name of the sequence to be used for +this descriptor. The purpose of the sequence name depends on the type of +sequencing you are using: + +When using table sequencing, the sequence name refers to the row’s +SEQ_NAME value used to store this sequence. + +When using Oracle native sequencing, the sequence name refers to the +Oracle sequence object that has been created in the database. When using +native sequencing on other databases, the sequence name does not have +any direct meaning, but should still be set for compatibility. + +The sequence name can also refer to a custom sequence defined in the +project. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_in_Relational_Projects[Sequencing +in Relational Projects]. + +=== How to Configure Sequencing at the Descriptor Level Using Workbench + +To configure sequencing for a descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Sequencing Options_* image:desseq.gif[Descriptor +Info Tab, Sequencing +Options,title="Descriptor Info Tab, Sequencing Options"] +. Complete the Sequencing options on the tab. + +Use the following information to specify sequencing options: + +Field + +Description + +Use Sequencing + +Specify if this descriptor uses sequencing. If selected, specify the +Name, Table, and Field for sequencing. + +Name + +Enter the name of the sequence. + +For table sequencing: Enter the name of the value in the sequence name +column (for default table sequencing, the column named SEQ_NAME) of the +sequence table (for default table sequencing, the table named SEQUENCE) +that EclipseLink uses to look up the corresponding sequence count value +(for default table sequencing, the corresponding value in the SEQ_COUNT +column) for this descriptor’s reference class. For more information, see +Table Sequencing. + +For native sequencing (Oracle platform): Enter the name of the sequence +object that Oracle Database creates to manage sequencing for this +descriptor’s reference class. For more information, see Native +Sequencing with an Oracle Database Platform + +For native sequencing (non-Oracle platform): For database compatibility, +enter a generic name for the sequence, such as SEQ. For more +information, see Native Sequencing with a Non-Oracle Database Platform. + +Table + +Specify the name of the database table that contains the field (see +Field) into which EclipseLink is to write the sequence value when a new +instance of this descriptor’s reference class is created. This is almost +always this descriptor’s primary table. + +Field + +Specify the name of the field in the specified table (see Table) into +which EclipseLink is to write the sequence value when a new instance of +this descriptor’s reference class is created. This field is almost +always the class’s primary key (see Configuring Primary Keys). + +For native sequencing (non-Oracle platform): Ensure that your database +schema specifies the correct type for this field (see Native Sequencing +with a Non-Oracle Database Platform). + +See Also: + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +link:Configuring%20a%20Relational%20Project%20(ELUG)[Configuring +Sequencing at the Project Level] + +link:Configuring%20a%20Database%20Login%20(ELUG)[Configuring Sequencing +at the Session Level] + +=== How to Configure Sequencing at the Descriptor Level Using Java + +Using Java, you can configure sequencing to use multiple different types +of sequence for different descriptors. You configure the sequence +objects on the session’s login and reference them from the descriptor by +their name. The descriptor’s sequence name refers to the sequence +object’s name you register in the session’s login. + +The following examples assume the session sequence configuration shown +in this example: + +[#Example 28-1]## *_Example Sequences_* + +[source,java] +---- + dbLogin.addSequence(new TableSequence("EMP_SEQ", 25)); + dbLogin.addSequence(new DefaultSequence("PHONE_SEQ", 30)); + dbLogin.addSequence(new UnaryTableSequence("ADD_SEQ", 55)); + dbLogin.addSequence(new NativeSequence("NAT_SEQ", 10)); +---- + +Using Java code, you can perform the following sequence configurations: + +* link:#Configuring_a_Sequence_by_Name[Configuring a Sequence by Name] +* link:#Configuring_the_Same_Sequence_for_Multiple_Descriptors[Configuring +the Same Sequence for Multiple Descriptors] +* link:#Configuring_the_Platform_Default_Sequence[Configuring the +Platform Default Sequence] + +==== Configuring a Sequence by Name + +As the link:#Example_28-2[Associating a Sequence with a Descriptor] +example shows, you associate a sequence with a descriptor by sequence +name. The sequence `+EMP_SEQ+` was added to the login for this project +in the link:#Example_28-1[Example Sequences] example. When a new +instance of the `+Employee+` class is created, the EclipseLink runtime +will use the sequence named `+EMP_SEQ+` (in this example, a +`+TableSequence+`) to obtain a value for the `+EMP_ID+` field. + +[#Example 28-2]## *_Associating a Sequence with a Descriptor_* + +[source,java] +---- + empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field + empDescriptor.setSequenceNumberName("EMP_SEQ"); +---- + +==== Configuring the Same Sequence for Multiple Descriptors + +As the link:#Example_28-3[Configuring a Sequence for Multiple +Descriptors] example shows, you can associate the same sequence with +more than one descriptor. In this example, both the `+Employee+` +descriptor and `+Phone+` descriptor use the same `+NativeSequence+`. +Having descriptors share the same sequence can improve pre-allocation +performance. For more information on pre-allocation, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_and_Preallocation_Size[Sequencing +and Preallocation Size]. + +[#Example 28-3]## *_Configuring a Sequence for Multiple Descriptors_* + +[source,java] +---- + empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field + empDescriptor.setSequenceNumberName("NAT_SEQ"); + phoneDescriptor.setSequenceNumberFieldName("PHONE_ID"); // primary key field + phoneDescriptor.setSequenceNumberName("NAT_SEQ"); +---- + +==== Configuring the Platform Default Sequence + +In the link:#Example_28-4[Configuring a Default Sequence] exmple, you +associate a nonexistent sequence (`+NEW_SEQ+`) with a descriptor. +Because you did not add a sequence named `+NEW_SEQ+` to the login for +this project in the link:#Example_28-1[Example Sequences] example, the +EclipseLink runtime will create a `+DefaultSequence+` named `+NEW_SEQ+` +for this descriptor. For more information about `+DefaultSequence+`, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Default_Sequencing[Default +Sequencing]. + +[#Example 28-4]## *_Configuring a Default Sequence_* + +[source,java] +---- + descriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field + descriptor.setSequenceNumberName("NEW_SEQ"); +---- + +== Configuring Custom SQL Queries for Basic Persistence Operations + +You can use EclipseLink to define an SQL query for each basic +persistence operation (insert, update, delete, read-object, read-all, or +does-exist) so that when you query and modify your relational-mapped +objects, the EclipseLink runtime will use the appropriate SQL query +instead of the default SQL query. + +SQL strings can include any fields that the descriptor maps, as well as +arguments. You specify arguments in the SQL string using +`+#+`, such as: + +`+select * from EMP where EMP_ID = #EMP_ID+` + +The insert and update SQL strings can take any field that the descriptor +maps as an argument. + +The read-object, delete and does-exist SQL strings can only take the +primary key fields as arguments. + +The read-all SQL string must return all instances of the class and thus +can take no arguments. + +You can define a custom SQL string for insert, update, delete, +read-object, and read-all +link:#How_to_Configure_Custom_SQL_Queries_for_Basic_Persistence_Operations_Using_Workbench[using +the Workbench]. + +You can define a custom SQL string or `+Call+` object for insert, +update, delete, read-object, read-all, and does-exist +link:#How_to_Configure_Custom_SQL_Queries_for_Basic_Persistence_Operations_Using_Java[using +Java]. Using a `+Call+`, you can define more complex SQL strings and +invoke custom stored procedures. + +Note: When you customize the update persistence operation for an +application that uses optimistic locking (see Configuring Locking +Policy), the custom update string must not write the object if the row +version field has changed since the initial object was read. In +addition, it must increment the version field if it writes the object +successfully. For example: + +update Employee set F_NAME = #F_NAME, VERSION = VERSION + 1 where (EMP_ID = #EMP_ID) AND (VERSION = #VERSION) + +The update string must also maintain the row count of the database. + +[width="100%",cols="<100%",] +|=== +|*_’Note_*: EclipseLink does not validate the SQL code that you enter. +Enter the SQL code appropriate for your database platform (see +link:Introduction%20to%20Data%20Access%20(ELUG)[Data Source Platform +Types]). +|=== + +=== How to Configure Custom SQL Queries for Basic Persistence Operations Using Workbench + +To configure custom SQL queries for basic persistence operations: + +[arabic] +. In the *Navigator*, select a descriptor in a relational database +project. +. Click the *Queries* tab in the *Editor*. +. Click the *Custom SQL* tab. *_Queries, Custom SQL Tab_* +image:qrsqltab.gif[Queries, Custom SQL +Tab,title="Queries, Custom SQL Tab"] +. Enter data on each tab on the Custom SQL tab. + +Click the appropriate SQL function tab and type your own SQL string to +control these actions for a descriptor. Use the following information to +complete the tab: + +Tab + +Description + +Insert + +Defines the insert SQL that EclipseLink uses to insert a new object’s +data into the database. + +Update + +Defines the update SQL that EclipseLink uses to update any changed +existing object’s data in the database. When you define a descriptor’s +update query, you must conform to the following: + +If the application uses optimistic locking, you must ensure that the row +is not written if the version field has changed since the object was +read. + +The update query must increment the version field if the row is written. + +The update string must maintain the row count of the database. + +Delete + +Defines the delete SQL that EclipseLink uses to delete an object. + +Read Object + +Defines the read SQL that EclipseLink uses in any ReadObjectQuery, whose +selection criteria is based on the object’s primary key. When you define +a descriptor’s read-object query, your implementation overrides any +ReadObjectQuery, whose selection criteria is based on the object’s +primary key. EclipseLink generates dynamic SQL for all other Session +readObject method signatures. + +To customize other Session readObject method signatures, define +additional named queries and use them in your application instead of the +Session methods. + +Read All + +Defines the read-all SQL that EclipseLink uses when you call Session +method readAllObjects(java.lang.Class) passing in the java.lang.Class +that this descriptor represents. When you define a descriptor’s read-all +query, your implementation overrides only the Session method +readAll(java.lang.Class), not the version that takes a Class and +Expression. As a result, this query reads every single instance. +EclipseLink generates dynamic SQL for all other Session readAll method +signatures. + +To customize other Session readAll method signatures, define additional +named queries and use them in your application instead of the Session +methods. + +=== How to Configure Custom SQL Queries for Basic Persistence Operations Using Java + +The `+DescriptorQueryManager+` generates default SQL for the following +persistence operations: + +* Insert +* Update +* Delete +* Read-object +* Read-all +* Does-exist + +Using Java code, you can use the descriptor query manager to provide +custom SQL strings to perform these functions on a class-by-class basis. + +Use `+ClassDescriptor+` method `+getQueryManager+` to acquire the +`+DescriptorQueryManager+`, and then use the `+DescriptorQueryManager+` +methods that this table lists. + +[#Table 28-2]## *_Descriptor Query Manager Methods for Configuring +Custom SQL_* + +[width="100%",cols="<46%,<54%",options="header",] +|=== +|*To Change the Default SQL for…* |*Use Descriptor Query Manager +Method…* +|Insert |`+setInsertQuery (InsertObjectQuery query)+` + +| |`+setInsertSQLString (String sqlString)+` + +| |`+setInsertCall(Call call)+` + +|Update |`+setUpdateQuery (UpdateObjectQuery query)+` + +| |`+setUpdateSQLString (String sqlString)+` + +| |`+setUpdateCall(Call call)+` + +|Delete |`+setDeleteQuery (DeleteObjectQuery query)+` + +| |`+setDeleteSQLString (String sqlString)+` + +| |`+setDeleteCall(Call call)+` + +|Read |`+setReadObjectQuery (ReadObjectQuery query)+` + +| |`+setReadObjectSQLString (String sqlString)+` + +| |`+setReadObjectCall(Call call)+` + +|Read all |`+setReadAllQuery (ReadAllQuery query)+` + +| |`+setReadAllSQLString (String sqlString)+` + +| |`+setReadAllCall(Call call)+` + +|Does exist |`+setDoesExistQuery(DoesExistQuery query)+` + +| |`+setDoesExistSQLString(String sqlString)+` + +| |`+setDoesExistCall(Call call)+` +|=== + +The link:#Example_28-5[Configuring a Descriptor Query Manager with +Custom SQL Strings] example shows how to implement an amendment method +to configure a descriptor query manager to use custom SQL strings. +Alternatively, using an `+SQLCall+`, you can specify more complex SQL +strings using features such as in, out, and in-out parameters and +parameter types (see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_SQLCall[Using a +SQLCall]). + +[#Example 28-5]## *_Configuring a Descriptor Query Manager with Custom +SQL Strings_* + +[source,java] +---- + public static void addToDescriptor(ClassDescriptor descriptor) { + + // Read-object by primary key procedure + descriptor.getQueryManager().setReadObjectSQLString( + "select * from EMP where EMP_ID = #EMP_ID"); + + // Read-all instances procedure + descriptor.getQueryManager().setReadAllSQLString("select * from EMP"); + + // Insert procedure + descriptor.getQueryManager().setInsertSQLString( + "insert into EMP (EMP_ID, F_NAME, L_NAME, MGR_ID) values + (#EMP_ID, #F_NAME, #L_NAME, #MGR_ID)"); + + // Update procedure + descriptor.getQueryManager().setUpdateSQLString( + "update EMP set (F_NAME, L_NAME, MGR_ID) values + (#F_NAME, #L_NAME, #MGR_ID) where EMP_ID = #EMP_ID"); + } +---- + +The link:#Example_28-6[Configuring a Descriptor Query Manager with +Custom Stored Procedure Calls] example shows how to implement an +amendment method to configure a descriptor query manager to use Oracle +stored procedures using a `+StoredProcedureCall+` (see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_StoredProcedureCall[Using +a StoredProcedureCall]). This example uses output cursors to return the +result set (see +link:Using%20Advanced%20Query%20API%20(ELUG)#Handling_Cursor_and_Stream_Query_Results[Handling +Cursor and Stream Query Results]). + +[#Example 28-6]## *_Configuring a Descriptor Query Manager with Custom +Stored Procedure Calls_* + +[source,java] +---- + public static void addToDescriptor(ClassDescriptor descriptor) { + + // Read-object by primary key procedure + StoredProcedureCall readCall = new StoredProcedureCall(); + readCall.setProcedureName("READ_EMP"); + readCall.addNamedArgument("P_EMP_ID", "EMP_ID"); + readCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); + descriptor.getQueryManager().setReadObjectCall(readCall); + + // Read-all instances procedure + StoredProcedureCall readAllCall = new StoredProcedureCall(); + readAllCall.setProcedureName("READ_ALL_EMP"); + readAllCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); + descriptor.getQueryManager().setReadAllCall(readAllCall ); + + // Insert procedure + StoredProcedureCall insertCall = new StoredProcedureCall(); + insertCall.setProcedureName("INSERT_EMP"); + insertCall.addNamedArgument("P_EMP_ID", "EMP_ID"); + insertCall.addNamedArgument("P_F_NAME", "F_NAME"); + insertCall.addNamedArgument("P_L_NAME", "L_NAME"); + insertCall.addNamedArgument("P_MGR_ID", "MGR_ID"); + descriptor.getQueryManager().setInsertCall(insertCall); + + // Update procedure + StoredProcedureCall updateCall = new StoredProcedureCall(); + updateCall.setProcedureName("UPDATE_EMP"); + updateCall.addNamedArgument("P_EMP_ID", "EMP_ID"); + updateCall.addNamedArgument("P_F_NAME", "F_NAME"); + updateCall.addNamedArgument("P_L_NAME", "L_NAME"); + updateCall.addNamedArgument("P_MGR_ID", "MGR_ID"); + descriptor.getQueryManager().setUpdateCall(updateCall); + } +---- + +== Configuring Interface Alias + +An interface alias allows an interface to be used to refer to a +descriptor instead of the implementation class. This can be useful for +classes that have public interface and the applications desire to refer +to the class using the public interface. Specifying the interface alias +allows any queries executed on an EclipseLink session to use the +interface as the reference class instead of the implementation class. + +Each descriptor can have one interface alias. Use the interface in +queries and relationship mappings. + +[width="100%",cols="<100%",] +|=== +|*_Note_*: If you use an interface alias, do not associate an interface +descriptor with the interface. +|=== + +This section includes information on configuring an interface alias. +Interfaces cannot be _created_ in the Workbench; you must add the Java +package or class to your Workbench project before configuring it. + +=== How to Configure Interface Alias Using Workbench + +To specify an interface alias, use this procedure: + +[arabic] +. In the *Navigator*, select a descriptor.If the *Interface Alias* +advanced property is not visible for the descriptor, right-click the +descriptor and choose *Select Advanced Properties* > *Interface Alias* +from context menu or from the Selected menu. +. Click the *Interface Alias* tab.*_ Interface Alias Tab_* +image:intralis.gif[Interface Alias Tab,title="Interface Alias Tab"] +. In the *Interface Alias* field, click *Browse* and select an +interface. + +See Also: + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +link:Creating%20a%20Descriptor%20(ELUG)[Creating a Descriptor] + +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] + +=== How to Configure Interface Alias Using Java + +To configure a descriptor with an interface alias using Java, create an +amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]) and use `+InterfacePolicy+` method +`+addParentInterface+` as this example shows. + +[#Example 28-7]## *_Configuring an Interface Alias_* + +[source,java] +---- + public static void addToDescriptor(Descriptor descriptor) { + descriptor.getInterfacePolicy().addParentInterface(MyInterface.class); + } +---- + +== Configuring a Relational Descriptor as a Class or Aggregate Type + +By default, when you add a Java class to a relational project (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]), Workbench create a relational class descriptor for +it. A class descriptor is applicable to any persistent object except an +object that is owned by another in an aggregate relationship. In this +case, you must describe the owned object with an aggregate descriptor. +Using a class descriptor, you can configure any relational mapping +except aggregate collection and aggregate object mappings. + +An aggregate object is an object that is strictly dependent on its +owning object. Aggregate descriptors do not define a table, primary key, +or many of the standard descriptor options as they obtain these from +their owning descriptor. If you want to configure an aggregate mapping +to associate data members in a target object with fields in a source +object’s underlying database tables (see +link:Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)[Configuring +a Relational Aggregate Collection Mapping] and +link:Configuring%20a%20Relational%20Aggregate%20Object%20Mapping_(ELUG)[Configuring +a Relational Aggregate Object Mapping]), you must designate the target +object’s descriptor as an aggregate. + +Alternatively, you can remove the aggregate designation from a +relational descriptor and return it to its default type. + +You can configure inheritance for a descriptor designated as an +aggregate (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor]), however, in +this case, _all_ the descriptors in the inheritance tree must be +aggregates. Aggregate and class descriptors cannot exist in the same +inheritance tree. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Aggregate_and_Composite_Descriptors_and_Inheritance[Aggregate +and Composite Descriptors and Inheritance]. + +For more information, see +link:Introduction%20to%20XML%20Descriptors%20(ELUG)#XML_Descriptors_and_Aggregation[XML +Descriptors and Aggregation]. + +=== How to Configure a Relational Descriptor as a Class or Aggregate Type Using Workbench + +To configure a relational descriptor as class or aggregate, use this +procedure. + +[arabic] +. In the *Navigator*, select a relational descriptor. +. Click the *Class* or *Aggregate* descriptor button on the mapping +toolbar. You can also select the descriptor and choose *Selected* > +*Descriptor Type* > *Class* or *Aggregate* from the menu or by +right-clicking on the descriptor in the *Navigator* window and selecting +*Descriptor Type* > *Class* or *Aggregate* from the context menu. +. image:dtfmpbtn.gif[Direct to Field Mapping +button,title="Direct to Field Mapping button"] If you select +*Aggregate*, specify each of the aggregate descriptor’s attributes as a +direct to field mapping. See +link:Configuring%20a%20Relational%20Direct-to-Field%20Mapping_(ELUG)[Configuring +a Relational Direct-to-Field Mapping] for more information. + +image:dtfmpbtn.gif[Direct to Field Mapping +button,title="Direct to Field Mapping button"] Specify each of the +aggregate descriptor’s attributes as a direct to field mapping. See +link:Configuring%20a%20Relational%20Direct-to-Field%20Mapping_(ELUG)[Configuring +a Relational Direct-to-Field Mapping] for more information. + +Although the attributes of a target class are not mapped directly to a +data source until you configure an aggregate object mapping, you must +still specify their mapping type in the target class’s descriptor. This +tells EclipseLink what type of mapping to use when you do configure the +aggregate mapping in the source object’s descriptor. For more +information, see +link:Introduction%20to%20Relational%20Descriptors%20(ELUG)#Aggregate_and_Composite_Descriptors_in_Relational_Projects[Aggregate +and Composite Descriptors in Relational Projects]. + +See Also: + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +link:#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Configuring +a Relational Descriptor as a Class or Aggregate Type] + +=== How to Configure a Relational Descriptor as a Class or Aggregate Type Using Java + +Using Java, to configure a relational descriptor as an aggregate, use +`+ClassDescriptor+` method `+descriptorIsAggregate+`. + +To configure a relational descriptor for use in an aggregate collection +mapping, use `+ClassDescriptor+` method +`+descriptorIsAggregateCollection+`. + +To configure a relational descriptor as a nonaggregate, use +`+ClassDescriptor+` method `+descriptorIsNormal+`. + +== Configuring Multitable Information + +Descriptors can use multiple tables in mappings. Use multiple tables +when either of the following occurs: + +* A subclass is involved in inheritance, and its superclass is mapped to +one table, while the subclass has additional attributes that are mapped +to a second table. +* A class is not involved in inheritance and its data is spread out +across multiple tables. + +When a descriptor has multiple tables, you must be able to join a row +from the primary table to all the additional tables. By default, +EclipseLink assumes that the primary key of the first, or primary, table +is included in the additional tables, thereby joining the tables. +EclipseLink also supports custom methods for joining tables. If the +primary key field names of the multiple tables do not match, a foreign +key can be used to join the tables. The foreign key can either be from +the primary table to the secondary table, or from the secondary table to +the primary table, or between two of the secondary tables (see +link:#How_to_Configure_Multitable_Information_Using_Workbench[How to +Configure Multitable Information Using Workbench]). + +For complex multitable situations, a more complex join expression may be +required. These include requiring the join to also check a type code, or +using an outer-join. EclipseLink provides support for a +multiple-table-join-expression for these cases (see +link:#How_to_Configure_Multitable_Information_Using_Java[How to +Configure Multitable Information Using Java]). + +=== How to Configure Multitable Information Using Workbench + +To associate multiple tables with a descriptor, use this procedure. + +[arabic] +. In the *Navigator*, select a descriptor.If the *Multitable Info* +advanced property is not visible for the descriptor, right-click the +descriptor and choose *Select Advanced Properties* > *Multitable Info* +from the context menu or from the *Selected* menu. +. Click the *Multitable Info* tab. *_Multitable Info Tab_* +image:multiinf.gif[Multitable Info Tab,title="Multitable Info Tab"] +. Complete each field on the *Multitable Info* tab. + +Use the following information to enter data in each field of the tab: + +Field + +Description + +Primary Table + +The primary table for this descriptor. This field is for display only. + +Additional Tables + +Use Add and Remove to add or remove additional tables. + +Association to Primary Table + +Specify how each Additional Table is associated to the Primary Table: + +Primary Keys Have Same Names–when associating tables by identically +named primary keys, EclipseLink requires no additional configuration. + +Reference–when associating an additional table to the primary table with +a Reference (that is, a foreign key), you can specify the Table +Reference, as well as the Source and Target fields. Continue with +Associating Tables with References. + +*Associating Tables with References* + +When associating a table using *Reference*, additional options appear. +You must choose a reference that relates the correct fields in the +primary table to the primary keys in the selected table. + +[#Figure 28-6]## *_Multitable Info Tab, Associated by Reference_* + +.Multitable Info Tab, Associated by Reference +image::multiref.gif[Multitable Info Tab, Associated by +Reference,title="Multitable Info Tab, Associated by Reference"] + +Choose a *Table Reference* that defines how the primary keys of the +primary table relate to the primary keys of the selected table. Click +*Add* to add a primary key association. + +=== How to Configure Multitable Information Using Java + +Using Java, configure a descriptor with multitable information using the +following `+org.eclipse.persistence.descriptors.ClassDescriptor+` +methods: + +* `+addTableName(java.lang.String tableName)+` +* `+addForeignKeyFieldNameForMultipleTable(java.lang.String sourceForeignKeyFieldName, java.lang.String targetPrimaryKeyFieldName)+` + +To specify a complex multiple-table-join-expression, create a descriptor +amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]) and add the join expression using +`+org.eclipse.persistence.descriptors.DescriptorQueryManager+` method +`+setMultipleTableJoinExpression+`. For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Appending_Additional_Join_Expressions[Appending +Additional Join Expressions]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Concept[Category: Concept] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-Field_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-Field_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..3439677d2a5 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-Field_Mapping_(ELUG).adoc @@ -0,0 +1,66 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Direct-to-Field_Mapping_(ELUG)[Related +Topics] "`wikilink`") + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational +direct-to-field mapping. + +[#Table 34-1]## + +Option to Configure + +Workbench + +Java + +Database field + +Method or direct field access + +Default null value + +Read-only + +Mapping comments + +Serialized object converter + +Type conversion converter + +Object type converter + +This example shows how to create a direct-to-field mapping and add it to +a descriptor using Java code. + +[#Example 36-1]## *_Direct-to-Field Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + DirectToFieldMapping mapping = new DirectToFieldMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-XMLType_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-XMLType_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..0497f18bf57 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct-to-XMLType_Mapping_(ELUG).adoc @@ -0,0 +1,101 @@ +*TOC* +Special:Whatlinkshere_Introduction_to_Relational_Mappings_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational +direct-to-`+XMLType+` mapping. + +[#Table 35-1]## + +[width="100%",cols="<61%,<19%,<20%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_a_Database_Field[Database +field] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Cofiguring_Method_or_direct_field_access[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Read_Whole_Document[Configuring Read Whole Document] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] +|=== + +This example shows how to create a direct-to-XMLType mapping and add it +to a descriptor using Java code. + +[#Example 37-1]## *_Direct-to-XMLType Mapping_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+   DirectToXMLTypeMapping mapping = new DirectToXMLTypeMapping();  +` + +`+   // configure mapping+` `+   mapping.setAttributeName("document");+` + +`+   // add mapping to descriptor+` +`+   descriptor.addMapping(mapping);+` `+}+` + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +== Configuring Read Whole Document + +When mapping an XML Type to a Document Object Model (DOM), by default +EclipseLink uses the database representation of the DOM. This allows for +lazy loading of the XML data from the database. + +However, if you require the entire DOM, (or if you require the DOM to be +available in a disconnected fashion from the database connection) use +the *Read Whole* option to retrieve the entire DOM from the database. + +=== How to Configure Read Whole Document Using Workbench + +To specify that this mapping reads the whole XML document, use this +procedure: + +[arabic] +. Select the mapping in the *Navigator*. Its properties appear in the +Editor. +. Click *General*. The General tab appears. [#Figure 35-1]##*_Direct to +XML Mapping Property Sheet, Read Whole Document Option_* +image:readwhl.gif[Direct to XML Mapping Property Sheet, Read Whole +Document +Option,title="Direct to XML Mapping Property Sheet, Read Whole Document Option"] +. Choose the *Read Whole Document* option to read the whole XML +document. If you do not select this option, the connection must remain +open for EclipseLink to read the database values. + +=== How to Configure Read Whole Document Using Java + +Use the following `+DirectToXMLTypeMapping+` methods: + +* `+setShouldReadWholeDocument+` +* `+shouldReadWholeDocument+` + +For more information about the available methods for +`+DirectToXMLTypeMapping+`, see the _EclipseLink API Reference_. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..0f273f93187 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,207 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Direct_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational direct +collection mapping. + +[#Table 41-1]## + +[width="100%",cols="<68%,<16%,<16%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:#Configuring_Target_Table[Target table] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Direct_Value_Field[Direct value field] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Batch +reading] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Indirection +(lazy loading)] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Container +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Configuring +a Serialized Object Converter] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Type +conversion converter] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Object +type converter] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Table +and field references] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a direct collection mapping and add it +to a descriptor using Java code. + +[#Example 43-1]## *_Direct Collection Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + DirectCollectionMapping mapping = new DirectCollectionMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Collection_Mapping[Direct +Collection Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on using JPA to configure direct collection mappings, +see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@BasicCollection_Annotation[How +to Use the @BasicCollection Annotation]. + +== Configuring Target Table + +Each direct collection stores reference information in a target table. +In the +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure_32-6[Direct +Collection Mappings] figure, the `+RESPONS+` table contains the primary +key and object of the instance owning the collection. You must create +this table in your database. + +=== How to Configure a Target Table Using Workbench + +To specify the direct collection specifics, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 41-1]##*_General Tab, Target Table Options_* +image:dcmaptar.gif[General Tab, Target Table +Options,title="General Tab, Target Table Options"] + +Use the *Target Table* list to select the table that contains the +reference fields for the direct collection mapping. + +=== How to Configure a Target Table Using Java + +Direct collection mappings store collections of Java objects that are +not EclipseLink-enabled. Direct collections usually store Java types, +such as `+String+`. + +Direct collection mappings are instances of the +`+DirectCollectionMapping+` class and require the following elements: + +* The attribute mapped, set by using the `+setAttributeName+` method. +* The database table that holds the values to be stored in the +collection, set by using the `+setReferenceTableName+` method. +* The field in the reference table from which the values are read and +placed into the collection; this is called the direct field. Set it +using the `+setDirectFieldName+` method. +* The foreign key information, which you specify using the +`+setReferenceKeyFieldName+` method and passing the name of the field +that is a foreign reference to the primary key of the source object. + +[width="100%",cols="<100%",] +|=== +|*Note:* If the target primary key is composite, call the +`+addReferenceKeyFieldName+` method for each of the fields that make up +the key. +|=== + +[#Example 41-1]## *_Configuring a Simple Direct Collection Mapping_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+    DirectCollectionMapping directCollectionMapping = new DirectCollectionMapping();+` +`+    directCollectionMapping.setAttributeName ("responsibilitiesList");+` +`+    directCollectionMapping.setReferenceTableName ("RESPONS"); +`*`+//\'\' \'\'target\'\' \'\'table+`* +`+    directCollectionMapping.setDirectFieldName ("DESCRIP");+` +`+    directCollectionMapping.setReferenceKeyFieldName ("EMP_ID");+` +`+    directCollectionMapping.useCollectionClass (Collection.class); +`*`+//\'\' \'\'default+`* + +`+    +`*`+//\'\' \'\'add\'\' \'\'this\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* +`+    descriptor.addMapping (directCollectionMapping);+` `+}+` + +In addition to the API that the link:#Example_41-1[Configuring a Simple +Direct Collection Mapping] example illustrates, other common API for use +with direct collection mappings include the following: + +* `+useBasicIndirection+`: implements EclipseLink value holder +indirection. +* `+useTransparentCollection+`: if you use transparent indirection, this +element places a special collection in the source object’s attribute. +* `+dontUseIndirection+`: implements no indirection. + +For more information about the available methods for +`+DirectCollectionMapping+`, see the _EclipseLink API Reference_. + +== Configuring Direct Value Field + +The direct value field, located in the reference table, stores the +primitive data value. In the +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure_32-6[Direct +Collection Mappings] figure, the `+DESCRIP+` field stores the +collection. + +=== How to Configure a Direct Value Field Using Workbench + +To specify the direct collection specifics, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 41-2]##*_General Tab, Direct Value Field_* +image:dcmapdir.gif[General Tab, Direct Value +Field,title="General Tab, Direct Value Field"] +. Use the *Direct Value Field* list to select the field from the *Target +Table* table that contains the object of the collection. + +=== How to Configure Direct Value Field Using Java + +The link:#Example_41-1[Configuring a Simple Direct Collection Mapping] +example demonstrates how to create and configure a direct collection +mapping, including the setting of a direct field. The example also shows +how to add this mapping to the descriptor. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Map_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Map_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..b484fd1184e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Direct_Map_Mapping_(ELUG).adoc @@ -0,0 +1,245 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Direct_Map_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational direct map +mapping. + +[#Table 43-1]## + +[width="100%",cols="<63%,<18%,<19%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Direct%20Collection%20Mapping_(ELUG)#Configuring_Target_Table[Configuring +Target Table] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Direct_Value_Field[Direct value field] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Direct_Key_Field[Direct key field] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Batch +reading] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)[Indirection (lazy loading)] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Container +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:#Configuring_Key_Converters[Key converters] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Value_Converters[Value converters] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Joining_at_the_Mapping_Level[Table +and field references] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a direct map mapping and add it to a +descriptor using Java code. + +[#Example 36-1]## *_Direct Map Mapping_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+   DirectMapMapping mapping = new DirectMapMapping();  +` + +`+   // configure mapping+` `+   ... +` + +`+   // add mapping to descriptor+` +`+   descriptor.addMapping(mapping);+` `+}+` + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Map_Mapping[Direct +Map Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on using JPA to configure direct map mappings, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@BasicMap_Annotation[How +to Use the @BasicMap Annotation]. + +== Configuring Direct Value Field + +The direct value field in the reference table stores the primitive data +value of the map value. If the value’s object value and database value +are different types, use a converter (see +link:#Configuring_Value_Converters[Configuring Value Converters]). + +=== How to Configure Direct Value Fields Using Workbench + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. *_General Tab, +Direct Value Field_* image:dmdirval.gif[General Tab, Direct Value +Field,title="General Tab, Direct Value Field"] +. Use the *Direct Value Field* list to select the field from the *Target +Table* table that contains the object of the direct map mapping. + +=== How to Configure Direct Value Fields Using Java + +Use the `+DirectMapMapping+` method `+setDirectFieldName+` to set the +direct fields for your mapping. + +For more information about the available methods for +`+DirectMapMapping+`, see the _EclipseLink API Reference_. + +== Configuring Direct Key Field + +The direct key field in the reference table stores the primitive data +value of the map key. If the key’s object value and database value are +different types, use a converter (see +link:#Configuring_Key_Converters[Configuring Key Converters]). + +=== How to Configure Direct Key Field Using Workbench + +To specify the direct key field in the reference table, use this +procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. *_General Tab, +Direct Key Field_* image:dmdirkey.gif[General Tab, Direct Key +Field,title="General Tab, Direct Key Field"] +. Use the *Direct Key Field* list to select the key from the *Target +Table* table that contains the object of the direct map mapping. + +=== How to Configure Direct Key Field Using Java + +Use the `+DirectMapMapping+` method `+setDirectKeyFieldName+` to set the +direct key field for your mapping. + +For more information about the available methods for +`+DirectMapMapping+`, see the _EclipseLink API Reference_. + +== Configuring Key Converters + +If the key’s object value and database value are different types, use a +converter. EclipseLink supports the following key converters: + +* link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter] + +=== How to Configure Key Converters Using Workbench + +Use this procedure to specify the converter for a direct map mapping +key: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Converter* tab. The Converter tab appears. +. Click the *Key Converter* tab. The Key Converter tab appears. +*_Converter Tab, Key Converter Subtab_* image:keyconv.gif[Converter Tab, +Key Converter Subtab,title="Converter Tab, Key Converter Subtab"] +. Select the appropriate Key Converter. + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*Converter* |*Description* +|*No Converter* |Do not use a Key Converter for this mapping. + +|*Serialized Object* *Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Configuring +a Serialized Object Converter]. + +|*Type Conversion Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +|*Object Type* *Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Configuring +an Object Type Converter]. +|=== + +=== How to Configure Key Converters Using Java + +You can configure whether or not to allow null values using the +`+DirectMapMapping+` method `+setKeyConverter+`. + +For more information about the available methods for +`+DirectMapMapping+`, see the _EclipseLink API Reference_. + +== Configuring Value Converters + +If the value’s object value and database value are different types, use +a converter. EclipseLink supports the following value converters: + +* link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter] + +=== How to Configure Value Converters Using Workbench + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Converter* tab. The Converter tab appears. +. Click the *Value Converter* tab. The Value Converter tab appears. +*_Converter Tab, Value Converter Subtab_* image:valconv.gif[Converter +Tab, Value Converter +Subtab,title="Converter Tab, Value Converter Subtab"] +. Select the appropriate Value Converter. + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*Converter* |*Description* +|*No Converter* |Do not use a Value Converter for this mapping. + +|*Serialized Object* *Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Configuring +a Serialized Object Converter] + +|*Type Conversion Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter] + +|*Object Type Converter* |See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Configuring +an Object Type Converter] +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Release_1[Category: Release 1] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Many-to-Many_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Many-to-Many_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..abcc7785a1d --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Many-to-Many_Mapping_(ELUG).adoc @@ -0,0 +1,183 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Many-to-Many_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational many-to-many +mapping. + +[width="100%",cols="<69%,<15%,<16%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Configuring +Reference Descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Private_or_Independent_relationships[Private +or Independent relationships] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Batch +reading] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(lazy_loading)[Indirection +(lazy loading)] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Bidirectional +relationship] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Container +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:#Configuring_a_Relation_Table[Relational table] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Table +and field references] (Source) +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Table +and field references] (Target) +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Query_Key_Order[Query +key order] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a many-to-many mapping and add it to a +descriptor using Java code. + +[#Example 41-1]## *_Many-to-Many Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + ManyToManyMapping mapping = new ManyToManyMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-Many +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on using JPA to configure many-to-many mappings, see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToMany[@ManyToMany]. + +== Configuring a Relation Table + +The relation table contains the columns for the primary keys of the +source table and target table involved in the many-to-many mapping. You +must create this table in the database before completing the mapping. +See link:Using%20Workbench%20(ELUG)#Using_Databases[Using Databases] for +information on creating database tables. + +In the +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure_32-5[Many-to-Many +Relationships] figure, the `+PROJ_EMP+` table serves as the relation +table between the `+PROJECT+` and `+EMPLOYEE+` tables. + +=== How to Configure a Relation Table Using Workbench + +To select a relation table for a mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 39-1]##*_Table Reference Tab, Relation Table Option_* +image:mmreltabl.gif[Table Reference Tab, Relation Table +Option,title="Table Reference Tab, Relation Table Option"] +. Use the *Relation Table* field to select a database table to define +this mapping. + +=== How to Configure a Relation Table Using Java + +Many-to-many mappings represent the relationships between a collection +of source objects and a collection of target objects. This requires an +intermediate table that manages the associations between the source and +target records. + +Many-to-many mappings are instances of the `+ManyToManyMapping+` class +and requires the following elements: + +* The attribute mapped, set by using the `+setAttributeName+` method. +* The reference class, set by using the `+setReferenceClass+` method. +* The relation table, set by using the `+setRelationTableName\'\'()+` +method. +* The foreign key information (for noncomposite target primary keys), +which you specify by calling the `+setSourceRelationKeyFieldName+` and +`+setTargetRelationKeyFieldName+` methods. +* The foreign key information if the source or target primary keys are +composite, which you specify by sending the +`+addSourceRelationKeyFieldName+` or `+addTargetRelationKeyFieldName+` +methods. + +[#Example 39-1]## *_Configuring a Relational Table_* + +`+public void customize(ClassDescriptor descriptor) { +` +*`+//\'\' \'\'In\'\' \'\'the\'\' \'\'Employee\'\' \'\'class,\'\' \'\'create\'\' \'\'the\'\' \'\'mapping\'\' \'\'that\'\' \'\'references\'\' \'\'Project\'\' \'\'class+`* +`+    ManyToManyMapping manyToManyMapping = new ManyToManyMapping();+` +`+    manyToManyMapping.setAttributeName("projects");+` +`+    manyToManyMapping.setReferenceClass(Project.class);+` + +`+    +`*`+//\'\' \'\'Configure\'\' \'\'the\'\' \'\'relational\'\' \'\'table+`* +`+    manyToManyMapping.setRelationTableName("PROJ_EMP");+` +`+    manyToManyMapping.setSourceRelationKeyFieldName ("EMPID");+` +`+    manyToManyMapping.setTargetRelationKeyFieldName ("PROJID");+` + +`+    +`*`+//\'\' \'\'Add\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* + +`+    descriptor.addMapping(manyToManyMapping);+` `+}+` + +In addition to the API that link:#Example_39-1[Configuring a Relational +Table] illustrates, other common API for use with many-to-many mappings +include the following: + +* `+useBasicIndirection+`: implements EclipseLink value holder +indirection. +* `+useTransparentCollection+`: if you use transparent indirection, this +element places a special collection in the source object’s attribute. +* `+dontUseIndirection+`: implements no indirection. + +For more information about the available methods for +`+ManyToManyMapping+`, see the _EclipseLink API Reference_. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..a6e76421d29 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Mapping_(ELUG).adoc @@ -0,0 +1,838 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the types of relational mappings that you can configure +and provides a cross-reference to the type-specific chapter that lists +the configurable options supported by that type. + +[#Table 33-1]## + +[width="100%",cols="<47%,<53%",options="header",] +|=== +|*If you are creating…* |*See…* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping] +|link:Configuring_a_Relational_Direct-to-Field_Mapping_(ELUG)[Configuring +a Relational Direct-to-Field Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping] +|link:Configuring%20a%20Relational%20Transformation%20Mapping%20(ELUG)[Configuring +a Relational Transformation Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mapping] +|link:Configuring_a_Relational_Direct-to-XMLType_Mapping_(ELUG)[Configuring +a Relational Direct-to-XMLType Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-One +Mapping] +|link:Configuring%20a%20Relational%20One-to-One%20Mapping%20(ELUG)[Configuring +a Relational One-to-One Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Variable_One-to-One_Mapping[Variable +One-to-One Mapping] +|link:Configuring%20a%20Relational%20Variable%20One-to-One%20Mapping%20(ELUG)[Configuring +a Relational Variable One-to-One Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-Many +Mapping] +|link:Configuring_a_Relational_One-to-Many_Mapping_(ELUG)[Configuring a +Relational One-to-Many Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-Many +Mapping] +|link:Configuring_a_Relational_Many-to-Many_Mapping_(ELUG)[Configuring a +Relational Many-to-Many Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +Collection Mapping] +|link:Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)[Configuring +a Relational Aggregate Collection Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Collection_Mapping[Direct +Collection Mapping] +|link:Configuring_a_Relational_Direct_Collection_Mapping_(ELUG)[Configuring +a Relational Direct Collection Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Map_Mapping[Direct +Map Mapping] +|link:Configuring%20a%20Relational%20Direct%20Map%20Mapping%20(ELUG)[Configuring +a Relational Direct Map Mapping] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Object_Mapping[Aggregate +Object Mapping] +|link:Configuring_a_Relational_Aggregate_Object_Mapping_(ELUG)[Configuring +a Relational Aggregate Object Mapping] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)[Introduction +to Relational Mappings] + +== Configuring Common Relational Mapping Options + +This table lists the configurable options shared by two or more +relational mapping types. + +[#Table 33-2]## + +[width="100%",cols="<65%,<17%,<18%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_a_Database_Field[Database field] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Reference_Descriptor[Reference descriptor] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Container +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Default_Null_Value_at_the_Mapping_Level[Default +null value] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Indirection +(lazy loading)] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Private_or_Independent_Relationships[Private +or Independent relationships] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Serialized +object converter] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Type +conversion converter] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Object +type conversion] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Bidirectional +relationship] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Batch_Reading[Batch reading] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Query_Key_Order[Query key order] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Table +and field references] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Joining_at_the_Mapping_Level[Joining] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Configuring a Database Field + +You can associate an object attribute with a database field. + +This table summarizes which relational mappings support this option. + +[#Table 33-3]## + +[width="100%",cols="<48%,<36%,<16%",options="header",] +|=== +|*Mapping* +|*link:#How_to_Configure_a_Database_Field_Using_Workbench[Using the +Workbench]* |*How to Use Java* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mapping] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +When choosing the database field, you must consider Java and database +field type compatibility. + +EclipseLink supports the following Java types: + +* `+java.lang+`: `+Boolean+`, `+Float+`, `+Integer+`, `+String+`, +`+Double+`, `+Long+`, `+Short+`, `+Byte+`, `+Byte[ ]+`, `+Character+`, +`+Character[ ]+`; all the primitives associated with these classes +* `+java.math+`: `+BigInteger+`, `+BigDecimal+` +* `+java.sql+`: `+Date+`, `+Time+`, `+Timestamp+` +* `+java.util+`: `+Date+`, `+Calendar+` + +While executing reads, the mappings in the link:#Table_33-6[Relational +Mapping Support for Reference Descriptor] table perform the simple +one-way data conversions that the link:#Table_33-4[Type Conversions +Provided by Direct-to-Field Mappings] table describes. For two-way or +more complex conversions, You must +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Converters_and_Transformers[use +converters]). + +The mappings in this table also allow you to specify a null value. This +may be required if primitive types are used in the object, and the +database field allows `+null+` values. For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Default_Null_Value_at_the_Mapping_Level[Configuring +a Default Null Value at the Mapping Level]. + +[#Table 33-4]## *_Type Conversions Provided by Direct-to-Field +Mappings_* + +[width="100%",cols="<48%,<52%",options="header",] +|=== +|*Java type* |*Database type* +|`+Integer+`, `+Float+`, `+Double+`, `+Byte+`, `+Short+`, +`+BigDecimal+`, `+BigInteger+`, `+int+`, `+float+`, `+double+`, +`+byte+`, `+short+` |NUMBER, NUMERIC, DECIMAL, FLOAT, DOUBLE, INT, +SMALLINT, BIT, BOOLEAN + +|`+Boolean+`, `+boolean+` |BOOLEAN, BIT, SMALLINT, NUMBER, NUMERIC, +DECIMAL, FLOAT, DOUBLE, INT + +|`+String+` |VARCHAR, CHAR, VARCHAR2, CLOB, TEXT, LONG, LONG VARCHAR, +MEMOThe following types apply only to Oracle9: NVARCHAR2, NCLOB, NCHAR + +|`+byte[ ]+` |BLOB, LONG RAW, IMAGE, RAW, VARBINARY, BINARY, LONG +VARBINARY + +|`+Time+` |TIME + +|`+java.sql.Date+` |DATE + +|`+Timestamp+`, `+java.util.Date+`, `+Calendar+` |TIMESTAMP +|=== + +*Support for oracle.sql.TimeStamp* + +EclipseLink provides additional support for mapping Java date and time +data types to Oracle Database `+DATE+`, `+TIMESTAMP+`, and +`+TIMESTAMPTZ+` data types when you use the Oracle JDBC driver with +Oracle9__i__ Database Server or later and the `+Oracle9Platform+` in +EclipseLink. + +In a direct-to-field mapping, you are not required to specify the +database type of the field value; EclipseLink determines the appropriate +data type conversion. + +This table lists the supported direct-to-field mapping combinations. + +*_Supported Oracle Database Date and Time Direct-to-Field Mappings_* + +Java Type + +Database Type + +Description + +java.sql.Time + +TIMESTAMP + +Full bidirectional support. + +TIMESTAMPTZ + +Full bidirectional support. + +DATE + +Full bidirectional support. + +java.sql.Date + +TIMESTAMP + +Full bidirectional support. + +TIMESTAMPTZ + +Full bidirectional support. + +DATE + +Full bidirectional support. + +java.sql.Timestamp + +TIMESTAMP + +Full bidirectional support. + +TIMESTAMPTZ + +Full bidirectional support. + +DATE + +Nanoseconds are not stored in the database. + +java.util.Date + +TIMESTAMP + +Full bidirectional support. + +TIMESTAMPTZ + +Full bidirectional support. + +DATE + +Milliseconds are not stored in the database. + +java.util.Calendar + +TIMESTAMP + +Native SQL or binding gives Calendar timezone. + +Note: The TIMESTAMP database value has no timezone – the Calendar object +provides the local timezone by default. If the database is not in this +timezone, you must obtain the database timezone by some other means and +update the Calendarobject accordingly. For this reason, TIMESTAMPTZ may +be a better choice. + +TIMESTAMPTZ + +Native SQL or binding stores timezone; standard SQL is based on the +local timezone. + +DATE + +Neither timezone nor milliseconds are stored in the database. + +Note that some of these mappings result in a loss of precision: avoid +these combinations if you require this level of precision. For example, +if you create a direct-to-field mapping between a `+java.sql.Date+` +attribute and a `+TIMESTAMPTZ+` database field, there is no loss of +precision. However, if you create a direct-to-field mapping between a +`+java.sql.Timestamp+` attribute and a `+DATE+` database field, the +nanoseconds or milliseconds of the attribute are not stored in the +database. + +=== How to Configure a Database Field Using Workbench + +Use this procedure to select a specific database field for a direct +mapping. + +[arabic] +. Select the direct mapping attribute in the *Navigator*. Its properties +appear in the Editor. +. Click the *General* tab. The General tab appears. *_Direct Mapping +General Tab, Database Field Option_* image:mpdtfdfd.gif[Direct Mapping +General Tab, Database Field +Option,title="Direct Mapping General Tab, Database Field Option"] +. Use the *Database Field* field to select a field for this direct +mapping. You must have previously associated the descriptor with a +database table as described in +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +[width="100%",cols="<100%",] +|=== +|*Note*: For direct-to-field mappings of an aggregate descriptor (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)[Configuring a +Relational Descriptor as a Class or Aggregate Type]), this field is for +display only and cannot be changed. +|=== + +== Configuring Reference Descriptor + +In relational mappings that extend +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+`, attributes +reference other EclipseLink descriptors–not the data source. You can +select any descriptor in the project. + +This table summarizes which relational mappings support this option. + +[#Table 33-6]## + +[width="100%",cols="<47%,<37%,<16%",options="header",] +|=== +|*Mapping* +|*link:#How_to_Configure_a_Reference_Descriptor_Using_Workbench[Using +the Workbench]* |*How to Use Java* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-one] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Variable_One-to-One_Mapping[Variable +one-to-one] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +collection] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Object_Mapping[Aggregate +object] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +=== How to Configure a Reference Descriptor Using Workbench + +To specify a reference descriptor for a relational mapping, use this +procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. *_General Tab, +Reference Descriptor Field_* image:mpgenref.gif[General Tab, Reference +Descriptor Field,title="General Tab, Reference Descriptor Field"] +. Use the *Reference Descriptor* field to select the descriptor +referenced by this relationship mapping. + +Note: For aggregate mappings the Reference Descriptor must be an +aggregate. See Configuring a Relational Descriptor as a Class or +Aggregate Type for more information. + +For variable one-to-one mappings, the Reference Descriptor must be an +interface. See Configuring a Relational Variable One-to-One Mapping for +more information. + +You can specify a reference descriptor that is not in the current +Workbench project. For example, to create a mapping to an `+Employee+` +class that does not exist in the current project, do the following: + +[arabic] +. Add the `+Employee+` class to your current project. See +link:Creating%20a%20Project%20(ELUG)[Working with Projects]. +. Create the relationship mapping to the `+Employee+` descriptor. +. Deactivate the `+Employee+` descriptor. See +link:Using%20Workbench%20(ELUG)[Active and Inactive Descriptors]. + +When you generate the deployment XML for your project, the _mapping_ to +the `+Employee+` class will be included, but not the `+Employee+` class. + +See Also: + +link:#Configuring_Reference_Descriptor[Configuring Reference Descriptor] + +== Configuring Batch Reading + +Batch reading can be used in most of the relational mappings. This +feature should be used only if it is known that the related objects are +always required with the source object. + +This table summarizes which relational mappings support this option. + +[#Table 33-7]## + +[width="100%",cols="<41%,<32%,<27%",options="header",] +|=== +|*Mapping* |*link:#How_to_Configure_Batch_Reading_Using_Workbench[Using +the Workbench]* |*link:#How_to_Configure_Batch_Reading_Using_Java[Using +Java]* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-one] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Collection_Mapping[Direct +collection] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Map_Mapping[Direct +map] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Object_Mapping[Aggregate +object] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +=== How to Configure Batch Reading Using Workbench + +To use batch reading in a relationship mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. *_General Tab, Batch +Reading Option_* image:oogenbat.gif[General Tab, Batch Reading +Option,title="General Tab, Batch Reading Option"] +. To specify that this mapping using batch reading, select the *Batch +Reading* option. + +=== How to Configure Batch Reading Using Java + +This example shows how to use a `+DescriptorCustomizer+` class to add +batch reading to a mapping. + +[#Example 33-1]## *_Query Optimization Using Batching_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + OneToManyMapping phoneNumbersMapping = new OneToManyMapping(); + phoneNumbersMapping = (OneToManyMapping)descriptor.getMappingForAttributeName("phones"); + phoneNumbersMapping.useBatchReading(); + } +---- + +== Configuring Query Key Order + +You can configure EclipseLink to maintain collections in order by query +key. + +This table summarizes which relational mappings support this option. + +[#Table 33-8]## + +[width="100%",cols="<43%,<31%,<26%",options="header",] +|=== +|*Mapping* +|*link:#How_to_Configure_Query_Key_Order_Using_Workbench[Using the +Workbench]* |*link:#How_to_Configure_Query_Key_Order_Using_Java[Using +Java]* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +collection] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +=== How to Configure Query Key Order Using Workbench + +To specify the order of a mapping’s query keys, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Ordering* tab. The Ordering tab appears. *_Ordering Tab_* +image:onetomany_coll_ord.gif[Ordering Tab,title="Ordering Tab"] +. Complete the *Ordering* options on the tab. + +Field + +Description + +Query Key + +Specify the query key to order by. + +Click Add to add query keys to, or Remove to remove query keys from the +ordering operation. + +Click Up or Down to change the sort order of selected query keys. + +Order + +Specify if EclipseLink orders the selected query key in Ascending or +Descending (alphabetical) order. + +=== How to Configure Query Key Order Using Java + +This example shows how to use the `+DescriptorCustomizer+` class to add +complex ordering to a mapping. + +[#'Example 33-2]## *_Configuring Query Key Order_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + + OneToManyMapping phoneNumbersMapping = new OneToManyMapping(); + + phoneNumbersMapping = (OneToManyMapping)descriptor.getMappingForAttributeName("phones"); + + phoneNumbersMapping.addAscendingOrdering("areaCode"); + + ExpressionBuilder phone = phoneNumbersMapping.getSelectionQuery().getExpressionBuilder(); + + phoneNumbersMapping.getSelectionQuery().addOrdering( + phone.get("type").toUpperCase().ascending()); + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You can provide the same functionality by using a descriptor +amendment method (see +link:Customizing%20the%20EclipseLink%20Application%20(ELUG)#Using_the_Descriptor_Amendment_Methods[Using +the Descriptor Amendment Methods]). +|=== + +== Configuring Table and Field References (Foreign and Target Foreign Keys) + +A foreign key is a combination of one or more database columns that +reference a unique key, usually the primary key, in another table. +Foreign keys can be any number of fields (similar to a primary key), all +of which are treated as a unit. A foreign key and the parent key it +references must have the same number and type of fields. + +Mappings that extend +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+` use foreign +keys to find information in the database so that the target object(s) +can be instantiated. For example, if every `+Employee+` has an attribute +`+address+` that contains an instance of `+Address+` (which has its own +descriptor and table) then, the one-to-one mapping for the `+address+` +attribute would specify foreign key information to find an `+Address+` +for a particular `+Employee+`. + +EclipseLink classifies foreign keys into two categories in +mappings–*foreign keys* and *target foreign keys*: + +* In a _foreign key,_ the key is found in the table associated with the +mapping’s own descriptor. For example, an `+Employee+` foreign key to +`+ADDRESS+` would be in the `+EMPLOYEE+` table. +* In a _target foreign key_, the reference is from the target object’s +table back to the key from the mapping’s descriptor’s table. For +example, the `+ADDRESS+` table would have a foreign key to `+EMPLOYEE+`. + +[width="100%",cols="<100%",] +|=== +|*Caution*: Make sure you fully understand the distinction between +_foreign key_ and _target foreign key_ before defining a mapping. +|=== + +The table reference is the database table that contains the foreign key +references. + +This table summarizes which relational mappings support this option. + +[width="100%",cols="<32%,<36%,<32%",options="header",] +|=== +|*Mapping* +|*link:#How_to_Configure_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)_Using_Workbench[Using +the Workbench]* +|*link:#How_to_Configure_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)_Using_Java[Using +Java]* +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-one] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-many] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +collection] |image:unsupport.gif[Unsupported.,title="Unsupported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Collection_Mapping[Direct +collection] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Map_Mapping[Direct +map] |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +Using Workbench, you can either import this table from your database or +create it. If you import tables from the database (see +link:Using%20Workbench%20(ELUG)[Importing Tables from a Database]), +EclipseLink creates references that correspond to existing database +constraints (if supported by the driver). You can also define references +in EclipseLink without creating similar constraints on the database. + +=== How to Configure Table and Field References (Foreign and Target Foreign Keys) Using Workbench + +To specify a table for a mapping reference, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Table Reference* tab. The Reference tab appears. *_Table +Reference Tab, Table Reference Field_* image:onetomany_tab_ref.gif[Table +Reference Tab, Table Reference +Field,title="Table Reference Tab, Table Reference Field"] +. Complete the fields on the Table Reference tab. + +Use the following information to select the field references on the tab: + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Field* |*Description* +|*Table Reference* |Select an existing table, or click *New* to create a +new table reference. + +|*Source and Target Field* |Click *Add* to create new foreign key +reference. To delete an existing key pair reference, select the *Source* +and *Target* fields and click *Remove*. + +|*Source Field* |Select the database field from the _source_ table for +this foreign key reference. + +|*Target Field* |Select the database field from the _target_ table for +this foreign key reference. + +|*Target Foreign Key* |Specify whether or not the reference is from the +target object’s table back to the key from the mapping’s descriptor’s +table. +|=== + +See Also: + +link:#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Configuring +Table and Field References (Foreign and Target Foreign Keys)] + +=== How to Configure Table and Field References (Foreign and Target Foreign Keys) Using Java + +Use the `+addTargetForeignKeyFieldName+` method (and pass the name of +the field name of the target foreign key and the source of the primary +key in the source table) to specify foreign key information. + +For composite source primary keys, use the +`+addTargetForeignKeyFieldName+` method for each of the fields that +comprise the primary key. + +This esxample shows how to use the `+DescriptorCustomizer+` class to add +complex join to a mapping. + +[#Example 33-3]## *_Adding Complex Join to a Mapping_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + + OneToManyMapping phoneNumbersMapping = new OneToManyMapping(); + phoneNumbersMapping = (OneToManyMapping)descriptor.getMappingForAttributeName("cellPhones"); + + ExpressionBuilder phone = phoneNumbersMapping.getSelectionQuery().getExpressionBuilder(); + + phoneNumbersMapping.addTargetForeignKeyFieldName("PHONE.EMP_ID", "EMP.ID"); + + phoneNumbersMapping.getSelectionQuery( + phone.getField("PHONE.EMP_ID").equal(phone.getParameter("EMP.ID"). + and(phone.getField("PHONE.TYPE').equal("CELL"))); + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You can provide the same functionality by using a descriptor +amendment method (see +link:Customizing%20the%20EclipseLink%20Application%20(ELUG)#Using_the_Descriptor_Amendment_Methods[Using +the Descriptor Amendment Methods]). +|=== + +== Configuring Joining at the Mapping Level + +EclipseLink supports configuring an inner or outer join at the mapping +level for a `+ForeignReferenceMapping+`. When a class that owns the +mapping is read, the EclipseLink runtime will always get the class and +the target of the reference mapping with one database hit. + +Use this feature only if the target object is _always_ required with the +source object, or when indirection (lazy loading) is _not_ used. For +more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Indirection_(Lazy_Loading)[Indirection +(Lazy Loading)]. + +You can also configure join reading at the query level. For more +information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Join_Reading_and_Object-Level_Read_Queries[Join +Reading and Object-Level Read Queries]. + +For more information about joins, see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Expressions +for Joining and Complex Relationships]. + +=== How to Configure Joining at the Mapping Level Using Workbench + +To use joining in a relationship mapping, use this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#'Figure 33-6]##*_General Tab, Use Joining Option_* +image:oogenjoi.gif[General Tab, Use Joining +Option,title="General Tab, Use Joining Option"] +. To use joining with this relationship, select the *Use Joining* +option. + +See Also: + +link:#Configuring_Joining_at_the_Mapping_Level[Configuring Joining at +the Mapping Level] + +=== How to Configure Joining at the Mapping Level Using Java + +This example shows how to use the `+DescriptorCustomizer+` class to add +complex join at the mapping level. + +[#Example 33-4]## *_Adding Join at the Mapping Level_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + + OneToManyMapping addressMapping = new OneToManyMapping(); + addressMapping = (OneToManyMapping)descriptor.getMappingForAttributeName("address"); + addressMapping.useJoining(); + ... + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You can provide the same functionality by using a descriptor +amendment method (see +link:Customizing%20the%20EclipseLink%20Application%20(ELUG)#Using_the_Descriptor_Amendment_Methods[Using +the Descriptor Amendment Methods]). +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-Many_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-Many_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..49a35adaf52 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-Many_Mapping_(ELUG).adoc @@ -0,0 +1,99 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_One-to-Many_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational one-to-many +mapping. + +[#Table 38-1]## *_Configurable Options for Relational One-to-Many +Mapping_* + +[width="100%",cols="<65%,<17%,<18%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Configuring +Reference Descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Configuring +Mapping Comments] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Configuring +Batch Reading] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Configuring +Mapping Comments] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Configuring +Bidirectional Relationship] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Configuring +Mapping Comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Joining_at_the_Mapping_Level[Configuring +Joining at the Mapping Level] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Query_Key_Order[Configuring +Query Key Order] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a one-to-many mapping and add it to a +descriptor using Java code. + +[#Example 40-1]## *_One-to-Many Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + OneToManyMapping mapping = new OneToManyMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-Many +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on using JPA to configure one-to-many mappings, see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany[@OneToMany]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-One_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-One_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..6a4c4954589 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_One-to-One_Mapping_(ELUG).adoc @@ -0,0 +1,90 @@ +*TOC* Special:Whatlinkshere_One-to-One_Mapping_(ELUG)[Related Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational one-to-one +mapping. + +[#Table 36-1]## + +[width="100%",cols="<68%,<16%,<16%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Reference +descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Private_or_Independent_Relationships[Private +or Independent relationships] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Batch_Reading[Batch +reading] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Joining_at_the_Mapping_Level[Joining] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Indirection +(lazy loading)] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Bidirectional +relationship] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Table +and field references] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a one-to-one mapping and add it to a +descriptor using Java code. + +[#Example 38-1]## *_One-to-One Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + OneToOneMapping mapping = new OneToOneMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-One +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on using JPA to configure one-to-one mappings, see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne[@OneToOne]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Project_(ELUG).adoc new file mode 100644 index 00000000000..4d488ced6ff --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Project_(ELUG).adoc @@ -0,0 +1,654 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Project_(ELUG)[Related +Topics] + +This section describes the various components that you must configure in +order to use a relational project. + +This section also describes logging into a database during development +when using Workbench. For more information, see +link:#Logging_In_to_the_Database[Logging In to the Database]. + +For information on how to create relational projects, see +link:Creating%20a%20Relational%20Project%20(ELUG)[Creating a Relational +Project]. + +This table lists the configurable options for relational projects. In +addition to the configurable options described here, you must also +configure the base class options described in +link:Configuring%20a%20Project%20(ELUG)[Configuring a Project]. + +[#Table 25-1]## + +[width="100%",cols="<66%,<16%,<18%",options="header",] +|=== +|*Option to Configure* |*EclipseLink Workbench* |*Java* +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Save_Location[Project +save location] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Project +classpath] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Comments[Project +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Method +or direct field access]) |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Default_Descriptor_Advanced_Properties[Default +descriptor advanced properties] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Existence_Checking_at_the_Project_Level[Existence +checking] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Deployment_XML_Options[Project +deployment XML options] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Model_Java_Source_Code_Options[Model +Java source code options] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Relational_Database_Platform_at_the_Project_Level[Relational +database] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Sequencing_at_the_Project_Level[Sequencing] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Login_Information_at_the_Project_Level[Login +information] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Development_and_Deployment_Logins[Development and +deployment logins] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Project_Level[Cache +type and size] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Isolation_at_the_Project_Level[Cache +isolation] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Project_Level[Cache +coordination change propagation] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Cache +expiration] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:#Configuring_Named_Query_Parameterized_SQL_and_Statement_Caching_at_the_Project_Level[Named +query parameterized SQL and statement caching] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:#Configuring_Table_Generation_Options[Table generation options] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:#Configuring_Table_Creator_Java_Source_Options[Table creator Java +source options] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:#Configuring_Project_Java_Source_Code_Options[Project Java source +code options] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|=== + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Introduction to +Relational Projects]. + +== Configuring Relational Database Platform at the Project Level + +For each relational project, you must specify the database platform +(such as Oracle Database 10__g__). This platform configuration is +overridden by the session login, if configured. + +For more information, see the following: + +* link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_a_Relational_Database_Platform_at_the_Session_Level[Configuring +a Relational Database Platform at the Session Level] +* link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types] + +=== How to Configure Relational Database Platform at the Project Level Using Workbench + +To specify the database platform of a relational project, use this +procedure: + +[arabic] +. Select the database object in the *Navigator*. The Database property +sheet appears. *_Database Property Sheet, Database Platform Options_* +image:dbplat.gif[Database Property Sheet, Database Platform +Options,title="Database Property Sheet, Database Platform Options"] +. Complete the Database Platform option on the property sheet. +. Click *Change* to select a new database platform for the project. For +more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types]. + +== Configuring Sequencing at the Project Level + +Sequencing allows EclipseLink to automatically assign the primary key or +ID of an object when the object is inserted. + +You configure EclipseLink sequencing at the project or session level to +tell EclipseLink how to obtain sequence values: that is, what type of +sequences to use. + +In a POJO project, you can configure a session directly: in this case, +you can use a session-level sequence configuration to override +project-level sequence configuration, on a +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[session-by-session +basis]), if required (see . + +link:#How_to_Configure_Sequencing_at_the_Project_Level_Using_Workbench[Using +the Workbench], you can configure +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing] and native sequencing (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] and +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform]), and you can configure +a preallocation size that applies to all sequences (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_and_Preallocation_Size[Sequencing +and Preallocation Size]). + +link:#How_to_Configure_Sequencing_at_the_Project_Level_Using_Java[Using +Java], you can configure any sequence type that EclipseLink supports +(see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_Types[Sequencing +Types]). You can create any number and combination of sequences. You can +create a sequence object explicitly or use the default sequence that the +platform creates. You can associate the same sequence with more than one +descriptor and you can configure a separate preallocation size for each +descriptor’s sequence. + +After configuring the sequence type at the project (or session) level, +to enable sequencing, you must +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[configure +a descriptor with a sequence field and a sequence name]. + +For more information about sequencing, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_in_Relational_Projects[Sequencing +in Relational Projects]. + +=== How to Configure Sequencing at the Project Level Using Workbench + +To specify the sequencing information for the project, use this +procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Sequencing* tab in the *Editor*. The Sequencing tab +appears. *_Sequencing Tab_* image:sequence.gif[Sequencing +Tab,title="Sequencing Tab"] +. Complete each field on Sequencing tab. + +Use this table to enter data in the following fields to configure the +sequencing information: + +[width="100%",cols="<6%,<94%",options="header",] +|=== +|*Field* |*Description* +|*Preallocation Size* |Specify the default preallocation size (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Sequencing and +Preallocation Size]). Default is *50*. The preallocation size you +configure applies to all sequences. + +|*Default Sequence Table* |Select this option to use table sequencing +(see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing]) with default sequence table name `+SEQUENCE+`, default +sequence name field `+SEQ_NAME+`, and default sequence counter field +`+SEQ_COUNT+`. + +|*Native Sequencing* |Select this option to use a sequencing object (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] or +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform]) created by the database +platform. This option applies only to Oracle, Sybase, Microsoft SQL, and +IBM Informix database platforms. + +|*Custom Sequence Table* |Select this option to use table sequencing +(see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing]) with a sequence table name, sequence name field, and +sequence counter field name that you specify. + +|*Name* |Specify the name of the sequence table. + +|*Name Field* |Specify the name of the column used to store the sequence +name. + +|*Counter Field* |Specify the name of the column used to store the +sequence count. +|=== + +=== How to Configure Sequencing at the Project Level Using Java + +Using Java, you can configure a project to use multiple, different +sequences, as this exmaple shows. + +[#Example 25-1]## *_Configuring Sequencing at the Project Level in +Java_* + +[source,java] +---- + // Enable native sequencing for the project as the default. Configured the default + // preallocation size''' + project.getLogin().useNativeSequencing(); + project.getLogin().setSequencePreallocationSize(50); + + // Configure the EMP_SEQ to not use preallocation + DefaultSequence empSequence = new DefaultSequence("EMP_SEQ", 1); + project.getLogin().addSequence(empSequence); + + // Configure the PROJ_SEQ to use a seperate sequence table + UnarySequence projSequence = new UnarySequence("PROJ_SEQ_TAB", "COUNTER"); + project.getLogin().addSequence(projSequence); +---- + +== Configuring Login Information at the Project Level + +This section describes how to define a login to a relational database. +After you define a login, you must +link:#Configuring_Development_and_Deployment_Logins[designate its role]. + +After you +link:#Configuring_Login_Information_at_the_Project_Level[create a login] +and specify it as a +link:#Configuring_Development_and_Deployment_Logins[development login], +you can link:#Logging_In_to_the_Database[log in to a database instance]. + +=== How to Configure Login Information at the Project Level UsingWorkbench + +To create or edit a database login, use this procedure: + +[arabic] +. Select the database object in the *Navigator*. The Database property +sheet appears. *_Database Property Sheet, Database Login Fields_* +image:dbdefine.gif[Database Property Sheet, Database Login +Fields,title="Database Property Sheet, Database Login Fields"] +. Click *Add* to create a new Defined Login. +. Complete the Database Login fields on the property sheet. + +Use this table to enter data in the following fields on the Database +property sheet to configure the database login: + +Field + +Description + +Defined Logins + +Login used to access the database. Click Add to add a new login, or +Remove to delete an existing login. + +Driver Class + +The JDBC driver to use to connect to the database. + +URL + +The URL used to connect to the appropriate database. + +User Name + +The name required to log in to the database. + +Password + +The password required to log in to the database. + +Save Password + +Whether or not to save the Password for this Defined Login. + +We recommend that you do not save the password with a deployment login. + +Note: If you select Save Password, then when you export Java source and +deployment XML, Workbench writes the database password using JCE +encryption (when using JDK 1.4 or later). For information on how to +specify password encryption options, see Configuring Password +Encryption. + +Default: unselected. + +See Also: + +link:#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level] + +link:#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level] + +link:#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins] + +== Configuring Development and Deployment Logins + +This section describes how to designate a defined login’s role. For +information on how to define a login, see +link:#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]. EclipseLink recognizes the +following login roles: + +* link:#Development_Role[Development Role] +* link:#POJO_Session_Role[POJO Session Role] + +*Development Role* + +While using Workbench to develop a project (see +link:Introduction%20to%20Projects_(ELUG)#Development_Role[Development +Role]), you must define a login (see +link:#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]) and designate it as the +development login. The development login is stored in the EclipseLink +project file. Workbench use the information in the development login +whenever you perform a data source operation from within Workbench. For +example, when you read or write schema information from or to a data +source during application development, the development login information +is never written to a `+sessions.xml+` or `+project.xml+` file and is +overridden by the deployment login (or the session login) at run time. + +For more information on how to use a development login to connect to a +database, see link:#Logging_In_to_the_Database[Logging In to the +Database]. + +*POJO Session Role* + +If you are creating a +link:Introduction%20to%20Projects_(ELUG)#POJO_Session_Role[POJO +project], we recommend that you use the `+sessions.xml+` file to store +the sessions your project uses at run time (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Login_Types[Data +Source Login Types]). + +=== How to Configure Development and Deployment Logins Using Workbench + +To specify different development and deployment database logins, use +this procedure: + +[arabic] +. Select the database object in the *Navigator*. The Database property +sheet appears. *_Database Property Sheet, Development and Deployment +Login Options_* image:dblogins.gif[Database Property Sheet, Development +and Deployment Login +Options,title="Database Property Sheet, Development and Deployment Login Options"] +. Complete the Development and Deployment Login options on the property +sheet by selecting from the logins you configured previously. + +Use this table to enter data in the following fields on the Database +property sheet to configure the login: + +Field + +Description + +Development Login + +The Defined Login to be used by Workbench during development to connect +with the database, and to read or write table information. + +For more information on how to use a development login to connect to a +database, see Logging In to the Database. + +Deployment Login + +The Defined Login to be used by your EclipseLink-enabled application +during deployment. + +See Also: + +link:#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins] + +link:Introduction%20to%20Projects_(ELUG)#Development_Role[Development +Role] + +== Logging In to the Database + +Using Workbench, after you +link:#Configuring_Login_Information_at_the_Project_Level[create a login] +and specify it as a +link:#Configuring_Development_and_Deployment_Logins[development login], +you can log in to a database instance. + +You must log in to the database before importing or exporting table +information. + +To log in to the database using Workbench, use one of the following +procedures: + +* Select the database object in the *Navigator* and click *Login* +image:loginbtn.gif[Database Login button,title="Database Login button"]. +Workbench logs in to the database. +* Right-click on the database object in the *Navigator* and choose *Log +In to Database* from the context menu, or choose *Selected > Log In to +Database* from the menu. + +image:logindb.gif[Database Logged In +icon,title="Database Logged In icon"] The database icon in the Navigator +window changes to indicate you are now logged in to the database. + +== Configuring Named Query Parameterized SQL and Statement Caching at the Project Level + +You can configure EclipseLink to use parameterized SQL (parameter +binding) and prepared statement caching for all named queries and +finders. + +By default, EclipseLink uses parameterized SQL. + +The use of parameterized SQL lets you create and store queries that are +complete except for one or more bound parameters. The EclipseLink +runtime binds the current parameter values when executing the query. +This approach avoids the preparation of SQL execution and, thus, +improves the performance of frequently executed SQL statements. + +This section describes configuring parameterized SQL and statement +caching options at the project level. This configuration applies to +_all_ named queries or finders (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Named Queries]) +you create on the descriptors in this project–not to all queries in +general or write operations. + +You can also configure parameterized SQL and statement caching options +at the named query or finder-level to override this project-level +configuration on a query-by-query basis (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]) or at the session login-level (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_JDBC_Options[Configuring +JDBC Options]). + +For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. + +[width="100%",cols="<100%",] +|=== +|*Note*: For applications using a Java EE data source or external +connection pool, you must configure statement caching in the Java EE +server’s data source–not in EclipseLink. +|=== + +This table summarizes which projects support parameterized SQL and +statement caching configuration. + +[#Table 25-2]## *_Project Support for Default Named Query Caching and +Binding_* + +[width="100%",cols="<11%,<69%,<20%",options="header",] +|=== +|*Descriptor* +|*link:#How_to_Configure_Named_Query_Parameterized_SQL_and_Statement_Caching_at_the_Project_Level_Using_Workbench[How +to use the Workbench]* |*How to Use Java* +|Relational Projects |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|EIS Projects |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|XML Projects |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|=== + +=== How to Configure Named Query Parameterized SQL and Statement Caching at the Project Level Using Workbench + +To specify the named query options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Defaults* tab in the *Editor*. The Defaults tab appears. +[#Figure 25-5]##*_Defaults Tab, Named Queries Options_* +image:nmdqropt.gif[Defaults Tab, Named Queries +Options,title="Defaults Tab, Named Queries Options"] +. Complete the *Named Query* options on the tab. + +Use this table to enter data in following fields on the Defaults tab to +specify the named query options for newly created descriptors.: + +[width="100%",cols="<21%,<79%",options="header",] +|=== +|*Field* |*Description* +|*Cache All Statements* |Caches the query’s prepared statement in the +EclipseLink statement cache. + +|*Bind All Parameters* |By default, EclipseLink binds all of the query’s +parameters. Deselect this option to disable binding. +|=== + +See Also: + +link:#Configuring_Named_Query_Parameterized_SQL_and_Statement_Caching_at_the_Project_Level[Configuring +Named Query Parameterized SQL and Statement Caching at the Project +Level] + +link:Configuring%20a%20Project%20(ELUG)[Configuring a Project] + +== Configuring Table Generation Options + +Using Workbench, you can configure options that apply when you generate +database tables from the descriptors you define in your Workbench +project. The resulting tables and columns will conform to the naming +restrictions of the project’s target database. + +=== How to Configure Table Generation Options Using Workbench + +To specify the default table generation options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Options* tab in the *Editor*. The Options tab appears. +[#Figure 25-6]##*_Options Tab, Table Generation Options_* +image:prjtbgen.gif[Options Tab, Table Generation +Options,title="Options Tab, Table Generation Options"] +. Complete the fields on the Table Generation defaults on the tab. + +Use this table to enter data in the following fields to specify the +default export and generation options. + +[width="100%",cols="<32%,<68%",options="header",] +|=== +|*Field* |*Description* +|*Default Primary Key* |Enter the default name to use when generating +primary keys. + +|*Primary Key Search Pattern* |Enter the default search pattern to use +when generating primary keys. +|=== + +== Configuring Table Creator Java Source Options + +Using Workbench, you can configure options that apply when you export +Java source code that you can use to create database tables. + +=== How to Configure Table Creator Java Source Options Using Workbench + +To specify the default Java code generation options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Options* tab in the *Editor*. The Options tab appears. +[#Figure 25-7]##*_Options Tab, Table Creator Java Source Options_* +image:prjtblcrt.gif[Options Tab, Table Creator Java Source +Options,title="Options Tab, Table Creator Java Source Options"] +. Complete the fields on the Table Creator Java Source defaults on the +tab. + +Use this table to enter data in the following fields to specify the +default table creator options. + +[width="100%",cols="<20%,<80%",options="header",] +|=== +|*Field* |*Description* +|*Class Name* |Base class name to use when generating table’s Java +source code from the project. + +|*Root Directory* |Directory for storing the generated source code. +|=== + +== Configuring Project Java Source Code Options + +Using Workbench, you can export a project as Java source. You can +configure the class name and root directory that Workbench uses when +exporting the project to Java source code. + +For more information on exporting a project as Java source, see +link:Creating%20a%20Relational%20Project%20(ELUG)#How_to_Export_Project_Java_Source_Using_Workbench[How +to Export Project Java Source Using Workbench]. + +=== How to Configure Project Java Source Code Options Using Workbench + +To specify the default Java code generation options, use this procedure: + +[arabic] +. Select the project object in the *Navigator*. +. Select the *Options* tab in the *Editor*. The Options tab +appears.[#Figure 25-8]## *_Options Tab, Project Java Source Options_* +image:prjavasrc.gif[Options Tab, Project Java Source +Options,title="Options Tab, Project Java Source Options"] +. Complete the fields on the Project Java Source defaults on the tab. + +Use this table to enter data in the following fields to specify the +default export and generation options: + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*Field* |*Description* +|*Class Name* |Base class name to use when generating Java source code +from the project. + +|*Root Directory* |Directory for storing the generated source code. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Transformation_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Transformation_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..6a94cc61474 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Transformation_Mapping_(ELUG).adoc @@ -0,0 +1,76 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Transformation_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational +transformation mapping. + +[width="100%",cols="<65%,<17%,<18%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Attribute_Transformer[Attribute +transformer] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Field_Transformer_Associations[Field +transformer associations] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Indirection +(lazy loading)] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Mapping +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Read-only +mapping] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a transformation mapping and add it to +a descriptor using Java code. + +[#Example 46-1]## *_Transformation Mapping_* + +.... +public void customize(ClassDescriptor descriptor) { + TransformationMapping mapping = new TransformationMapping(); + + // configure mapping + ... + + // add mapping to descriptor + descriptor.addMapping(mapping); +} +.... + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Concept[Category: Concept] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Variable_One-to-One_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Variable_One-to-One_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..d4d90f85908 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Relational_Variable_One-to-One_Mapping_(ELUG).adoc @@ -0,0 +1,529 @@ +*TOC* +Special:Whatlinkshere_Configuring_a_Relational_Variable_One-to-One_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a relational variable +one-to-one mapping. + +[#Table 37-1]## + +[width="100%",cols="<63%,<18%,<19%",options="header",] +|=== +|*Option* |*Workbench* |*Java* +|link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Reference_Descriptor[Configuring +Reference Descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mapping_Comments[Configuring +Mapping Comments] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)[Configuring Mapping Comments] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)[Configuring Mapping Comments] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Supported,title="Supported"] + +|link:#Configuring_Query_Key_Association[Configuring Query Key +Association] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Class_Indicator[Configuring Class Indicator] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Unique_Primary_Key[Configuring Unique Primary Key] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +This example shows how to create a variable one-to-one mapping and add +it to a descriptor using Java code. + +[#Example 39-1]## *_Variable One-to-One Mapping_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+   VariableOneToOneMapping mapping = new VariableOneToOneMapping();  +` + +`+   // configure mapping+` `+   ... +` + +`+   // add mapping to descriptor+` +`+   descriptor.addMapping(mapping);+` `+}+` + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Variable_One-to-One_Mapping[Variable +One-to-One Mapping] +* link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring a +Relational Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +== Configuring Class Indicator + +In variable one-to-one mappings, you can use an indicator column in the +source table to specify the correct target table, as illustrated in +link:#Figure_37-1[Variable One-to-One Mapping using Class indicator +Field]. This section includes information on implementing class +indicators. + +A source table has an indicator column that specifies the target table +through the class indicator field. + +The link:#Figure_37-1[Variable One-to-One Mapping using Class indicator +Field] figure illustrates the `+EMPLOYEE+` table that has a `+TYPE+` +column that indicates the target for the row (either `+PHONE+` or +`+EMAIL+`). + +[#Figure 37-1]## *_Variable One-to-One Mapping using Class indicator +Field_* + +.Variable One-to-One Mapping using Class indicator Field +image::clinfig.gif[Variable One-to-One Mapping using Class indicator +Field,title="Variable One-to-One Mapping using Class indicator Field"] + +The principles of defining such a variable class relationship are +similar to defining a normal one-to-one relationship, except: + +* The reference class is a Java _interface_, not a Java _class_. +However, the method to set the interface is identical. +* You must specify a type indicator field. +* You specify the class indicator values on the mapping so that mapping +can determine the class of object to create. +* You must specify the foreign key names and the respective abstract +query keys from the target interface descriptor. + +Alternatively, you can use unique primary keys to specify the correct +target. See link:#Configuring_Unique_Primary_Key[Configuring Unique +Primary Key] for more information. + +=== How to Configure a Class Indicator Using Workbench + +To specify the class indicators for a variable one-to-one mapping, use +this procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Class Indicator Info* tab. The Class Indicator Info tab +appears. '`**’Figure 37-2 Class Indicator Info Tab**`' +image:clindfld.gif[Class Indicator Info +Tab,title="Class Indicator Info Tab"] +. Use the *Class Indicator Field* to select the field on the database +table (associated with the mapping’s descriptor) to use as the indicator +for the variable mapping. +. Use the *Indicator Type* to specify the data type of the class +indicator field by selecting the data type from the list. +. To specify the specific class indicator field values for each +(nonabstract) child class, click *Edit* and enter the appropriate value +for each child class. + +=== How to Configure a Class Indicator Using Java + +This example illustrates how to define a variable one-to-one mapping +using a class (type) indicator in Java code. + +[#Example 37-1]## *_Defining Variable One-to-One Mapping Using a Class +Indicator_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+    VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();  +` +`+    variableOneToOneMapping.setAttributeName("contact");  +` +`+    variableOneToOneMapping.setReferenceClass (Contact.class);  +` +`+    variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");  +` +`+    variableOneToOneMapping.setTypeFieldName("TYPE");  +` + +`+    +`*`+//\'\' \'\'configure\'\' \'\'class\'\' \'\'indicators+`* +`+    variableOneToOneMapping.addClassIndicator(Email.class, "Email");   +` +`+    variableOneToOneMapping.addClassIndicator(Phone.class, "Phone");  +` + +`+    variableOneToOneMapping.dontUseIndirection();  +` +`+    variableOneToOneMapping.privateOwnedRelationship();  +` + +`+    +`*`+//\'\' \'\'add\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* +`+    descriptor.addMapping(variableOneToOneMapping);+` `+}+` + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +== Configuring Unique Primary Key + +In variable one-to-one mappings, you can use a unique primary key in the +source table to specify the correct target table, as illustrated in the +link:#Figure_37-4[Variable One-to-One Relationship with Unique Primary +Key] figure. This section includes information on implementing class +indicators. + +Alternatively, you can use a class indicator to specify the correct +target. See link:#Configuring_Class_Indicator[Configuring Class +Indicator] for more information. + +=== How to Configure a Unique Primary Key UsingWorkbench + +To specify the variable one-to-one mapping with a primary key, use this +procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Class Indicator Info* tab. The Class Indicator Info tab +appears. *_Figure 37-3 Class Indicator Info Tab, Configuring Primary +Key_* image:var11_map_conf_pk.gif[Class Indicator Info Tab, Configuring +Primary Key,title="Class Indicator Info Tab, Configuring Primary Key"] +* Use the *Class Indicator Field* to select none. +* Use the *Indicator Type* to select none. +* Use the *Indicator Value* column to specify none. +. After choosing the reference descriptor for the mapping, deselect the +*Include* check boxes. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot deselect the value in the Class Indicator Field, +unless the foreign key values in the source table are unique. +|=== + +=== How to Configure a Unique Primary Key Using Java + +This example illustrates how to define a variable one-to-one mapping +using a unique primary key in Java code. + +[#Example 37-2]## *_Defining Variable One-to-One Mapping Using a Unique +Primary Key_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+    VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();  +` +`+    variableOneToOneMapping.setAttributeName("contact");  +` +`+    variableOneToOneMapping.setReferenceClass (Contact.class);  +` +`+    variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");  +` +`+    variableOneToOneMapping.dontUseIndirection();  +` +`+    variableOneToOneMapping.privateOwnedRelationship();+` + +`+    +`*`+//\'\' \'\'add\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* +`+    descriptor.addMapping(variableOneToOneMapping);+` `+}+` + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +=== What You May Need to Know About Unique Primary Keys + +As the link:#Figure_37-4[Variable One-to-One Relationship with Unique +Primary Key] figure illustrates, the value of the foreign key in the +source table (`+C_ID+`) mapped to the primary key of the target table is +unique. No primary key values among the target tables are the same, so +primary key values are not unique just in the table, but also among the +tables. + +[#Figure 37-4]## *_Variable One-to-One Relationship with Unique Primary +Key_* + +.Variable One-to-One Relationship with Unique Primary Key +image::uniquepk.gif[Variable One-to-One Relationship with Unique Primary +Key,title="Variable One-to-One Relationship with Unique Primary Key"] + +If there is no indicator stored in the source table, EclipseLink cannot +determine to which target table the foreign key value is mapped. +Therefore, EclipseLink reads through all the target tables until it +finds an entry in one of the target tables. This is an inefficient way +of setting up a relation model. The class indicator is much more +efficient as it reduces the number of reads performed on the tables to +get the data. In the class indicator method, EclipseLink knows exactly +which target table to look into for the data. + +The principles of defining such a variable class relationship are +similar to defining class indicator variable one-to-one relationships, +except the following: + +* A type indicator field is not specified. +* The class indicator values are not specified. + +The type indicator field and its values are not needed, because +EclipseLink goes through all the target tables until data is finally +found. + +== Configuring Query Key Association + +This section includes information on configuring query key assosications +using development tools, as well as Java. + +=== How to Configure a Query Key Association Using Workbench + +To specify the query keys used for a variable one-to-one mapping, use +this procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Query Key Associations* tab. The Query Key Associations tab +appears [#Figure 37-5]##*_Query Key Associations Tab_* +image:qkassoc.gif[Query Key Associations +Tab,title="Query Key Associations Tab"] +. Complete each field on the Query Key Associations tab. +. Use the *Indicator Type* to specify the data type of the class +indicator field by selecting the data type from the list. + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Foreign Key* |The field from the database table to use as the foreign +key in this relationship. + +|*Query Key Name* |The name of the query key (from the referenced +descriptor) for this association. See +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Query_Keys[Configuring +Query Keys] for more information. +|=== + +=== How to Configure a Query Key Association Using Java + +The API to configure query key associations is +`+org.eclipse.persistence.mappings.VariableOneToOneMapping+` method +`+addForeingQueryKeyName(String, String)+`. + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +== Configuring Class Indicator + +In variable one-to-one mappings, you can use an indicator column in the +source table to specify the correct target table, as illustrated in the +link:#Figure_37-1[Variable One-to-One Mapping using Class indicator +Field] figure. This section includes information on implementing class +indicators. + +A source table has an indicator column that specifies the target table +through the class indicator field. + +The link:#Figure_37-1[Variable One-to-One Mapping using Class indicator +Field] figure illustrates the `+EMPLOYEE+` table that has a `+TYPE+` +column that indicates the target for the row (either `+PHONE+` or +`+EMAIL+`). + +[#Figure 37-1]## *_Variable One-to-One Mapping using Class indicator +Field_* + +.Variable One-to-One Mapping using Class indicator Field +image::clinfig.gif[Variable One-to-One Mapping using Class indicator +Field,title="Variable One-to-One Mapping using Class indicator Field"] + +The principles of defining such a variable class relationship are +similar to defining a normal one-to-one relationship, except: + +* The reference class is a Java _interface_, not a Java _class_. +However, the method to set the interface is identical. +* You must specify a type indicator field. +* You specify the class indicator values on the mapping so that mapping +can determine the class of object to create. +* You must specify the foreign key names and the respective abstract +query keys from the target interface descriptor. + +Alternatively, you can use unique primary keys to specify the correct +target. See link:#Configuring_Unique_Primary_Key[Configuring Unique +Primary Key] for more information. + +=== How to Configure a Class Indicator Using Workbench + +To specify the class indicators for a variable one-to-one mapping, use +this procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Class Indicator Info* tab. The Class Indicator Info tab +appears. [#Figure 37-2]##'`**’ Class Indicator Info Tab**`' +image:clindfld.gif[Class Indicator Info +Tab,title="Class Indicator Info Tab"] +. Use the *Class Indicator Field* to select the field on the database +table (associated with the mapping’s descriptor) to use as the indicator +for the variable mapping. +. Use the *Indicator Type* to specify the data type of the class +indicator field by selecting the data type from the list. +. To specify the specific class indicator field values for each +(nonabstract) child class, click *Edit* and enter the appropriate value +for each child class. + +=== How to Configure a Class Indicator Using Java + +This example illustrates how to define a variable one-to-one mapping +using a class (type) indicator in Java code. + +[#Example 37-1]## *_Defining Variable One-to-One Mapping Using a Class +Indicator_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+    VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();  +` +`+    variableOneToOneMapping.setAttributeName("contact");  +` +`+    variableOneToOneMapping.setReferenceClass (Contact.class);  +` +`+    variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");  +` +`+    variableOneToOneMapping.setTypeFieldName("TYPE");  +` + +`+    +`*`+//\'\' \'\'configure\'\' \'\'class\'\' \'\'indicators+`* +`+    variableOneToOneMapping.addClassIndicator(Email.class, "Email");   +` +`+    variableOneToOneMapping.addClassIndicator(Phone.class, "Phone");  +` + +`+    variableOneToOneMapping.dontUseIndirection();  +` +`+    variableOneToOneMapping.privateOwnedRelationship();  +` + +`+    +`*`+//\'\' \'\'add\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* +`+    descriptor.addMapping(variableOneToOneMapping);+` `+}+` + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +== Configuring Unique Primary Key + +In variable one-to-one mappings, you can use a unique primary key in the +source table to specify the correct target table, as illustrated in the +link:#Figure_37-4[Variable One-to-One Relationship with Unique Primary +Key] figure. This section includes information on implementing class +indicators. + +Alternatively, you can use a class indicator to specify the correct +target. See link:#Configuring_Class_Indicator[Configuring Class +Indicator] for more information. + +=== How to Configure a Unique Primary Key UsingWorkbench + +To specify the variable one-to-one mapping with a primary key, use this +procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Class Indicator Info* tab. The Class Indicator Info tab +appears. [#Figure 37-3]##*_Class Indicator Info Tab, Configuring Primary +Key_* image:var11_map_conf_pk.gif[Class Indicator Info Tab, Configuring +Primary Key,title="Class Indicator Info Tab, Configuring Primary Key"] +. Use the *Class Indicator Field* to select none. +. Use the *Indicator Type* to select none. +. Use the *Indicator Value* column to specify none. +. After choosing the reference descriptor for the mapping, deselect the +*Include* check boxes. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot deselect the value in the Class Indicator Field, +unless the foreign key values in the source table are unique. +|=== + +=== How to Configure a Unique Primary Key Using Java + +This example illustrates how to define a variable one-to-one mapping +using a unique primary key in Java code. + +[#Example 37-2]## *_Defining Variable One-to-One Mapping Using a Unique +Primary Key_* + +`+public void customize(ClassDescriptor descriptor) { +` +`+    VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();  +` +`+    variableOneToOneMapping.setAttributeName("contact");  +` +`+    variableOneToOneMapping.setReferenceClass (Contact.class);  +` +`+    variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");  +` +`+    variableOneToOneMapping.dontUseIndirection();  +` +`+    variableOneToOneMapping.privateOwnedRelationship();+` + +`+    +`*`+//\'\' \'\'add\'\' \'\'mapping\'\' \'\'to\'\' \'\'descriptor+`* +`+    descriptor.addMapping(variableOneToOneMapping);+` `+}+` + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +=== What You May Need to Know About Unique Primary Keys + +As the link:#Figure_37-4[Variable One-to-One Relationship with Unique +Primary Key] figure illustrates, the value of the foreign key in the +source table (`+C_ID+`) mapped to the primary key of the target table is +unique. No primary key values among the target tables are the same, so +primary key values are not unique just in the table, but also among the +tables. + +[#Figure 37-4]## *_Variable One-to-One Relationship with Unique Primary +Key_* + +.Variable One-to-One Relationship with Unique Primary Key +image::uniquepk.gif[Variable One-to-One Relationship with Unique Primary +Key,title="Variable One-to-One Relationship with Unique Primary Key"] + +If there is no indicator stored in the source table, EclipseLink cannot +determine to which target table the foreign key value is mapped. +Therefore, EclipseLink reads through all the target tables until it +finds an entry in one of the target tables. This is an inefficient way +of setting up a relation model. The class indicator is much more +efficient as it reduces the number of reads performed on the tables to +get the data. In the class indicator method, EclipseLink knows exactly +which target table to look into for the data. + +The principles of defining such a variable class relationship are +similar to defining class indicator variable one-to-one relationships, +except the following: + +* A type indicator field is not specified. +* The class indicator values are not specified. + +The type indicator field and its values are not needed, because +EclipseLink goes through all the target tables until data is finally +found. + +== Configuring Query Key Association + +This section includes information on configuring query key assosications +using development tools, as well as Java. + +=== How to Configure a Query Key Association Using Workbench + +To specify the query keys used for a variable one-to-one mapping, use +this procedure: + +[arabic] +. Select the variable one-to-one mapping in the *Navigator*. Its +attributes appear in the Editor. +. Click the *Query Key Associations* tab. The Query Key Associations tab +appears. [#Figure 37-5]##*_Query Key Associations Tab_* +image:qkassoc.gif[Query Key Associations +Tab,title="Query Key Associations Tab"] +. Complete each field on the Query Key Associations tab. +. Use the *Indicator Type* to specify the data type of the class +indicator field by selecting the data type from the list. + +Use the following information to enter data in each field on the tab: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Foreign Key* |The field from the database table to use as the foreign +key in this relationship. + +|*Query Key Name* |The name of the query key (from the referenced +descriptor) for this association. See +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Query_Keys[Configuring +Query Keys] for more information. +|=== + +=== How to Configure a Query Key Association Using Java + +The API to configure query key associations is +`+org.eclipse.persistence.mappings.VariableOneToOneMapping+` method +`+addForeingQueryKeyName(String, String)+`. + +For more information about the available methods for +`+VariableOneToOneMapping+`, see the _EclipseLink API Reference_. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Session_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Session_(ELUG).adoc new file mode 100644 index 00000000000..ba9e7c7d8bf --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_a_Session_(ELUG).adoc @@ -0,0 +1,1346 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_a_Session_(ELUG)[Related topics] + +This table lists the types of EclipseLink sessions that you can +configure and provides a cross-reference to the type-specific chapter +that lists the configurable options supported by that type. + +[#Table 85-1]## + +If you are creating… + +See… + +Server and client sessions + +Configuring Server Sessions + +Unit of Work Sessions + +Introduction to EclipseLink Transactions + +Isolated Client Sessions + +Configuring Exclusive Isolated Client Sessions for Virtual Private +Database + +Historical sessions + +Configuring Historical Sessions + +Session broker and client sessions + +Configuring Session Broker and Client Sessions + +Database sessions + +Configuring Database Sessions + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Introduction +to EclipseLink Sessions] +* link:Creating%20a%20Session%20(ELUG)[Creating a Session] + +== Configuring Common Session Options + +This table lists the configurable options shared by two or more +EclipseLink session types. In addition to the configurable options +described here, you must also configure the options described for the +specific +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Types[Session +Types], as shown in The link:#Table_85-1[Configuring EclipseLink +Sessions] table. + +[#Table 85-2]## + +Option to Configure + +EclipseLink Workbench + +Java + +Primary mapping project + +Session login + +Logging + +Multiple mapping projects + +Performance profiler + +Exception handler + +Session customizer class + +Server platform + +Session event listener + +Configuring a Coordinated Cache + +Integrity checker + +Connection policy + +Named queries + +== Configuring a Primary Mapping Project + +The mapping project contains your EclipseLink mapping metadata (see +link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects]), +including descriptors and mappings. Each session is associated with at +least one project so that the session can register the descriptors. + +This table summarizes which sessions support a primary mapping project +configuration. + +[#Table 85-3]## + +Session + +Using the Workbench + +Using Java + +Server and Client Sessions + +Session broker and client sessions + +Database sessions + +Using the Workbench, you can export your mapping metadata as either a +deployment XML file or as a Java class. Consequently, in a session, you +can specify the mapping project as an XML file or as a Java class. + +If you export your mapping metadata as a Java class, you must compile it +and +link:Creating%20a%20Session%20(ELUG)#Configuring_a_Sessions_Configuration[add +it to the session configuration classpath] before adding it to a +session. + +Note: When specifying the mapping project using XML, you can specify the +Java resource path. In most applications, the sessions.xml and +project.xml files are deployed inside the JAR file, and the project XML +path is specified as a Java resource path. When specifying the Java +resource path, ensure that you are using the forward slash character ( / +) for directories, not the back slash (  ). + +For example, com/myapp/mypersistence/my-project.xml, or +META-INF/my-project.xml. + +See link:#Configuring_Multiple_Mapping_Projects[Configuring Multiple +Mapping Projects] for information on configuring additional EclipseLink +projects for the session. + +=== How to Configure a Primary Mapping Project Using Workbench + +To specify the primary EclipseLink project metadata for your session, +use this procedure: + +[arabic] +. Select a server or database session in the *Navigator*. Its properties +appear in the Editor. +. Click the *General* tab. The General tab appears. +. Click the *Project* subtab. The Project subtab appears. +[#Figure 85-1]##*_General Tab, Project Subtab, Primary Project Option_* +image:sesgen.gif[General Tab, Project Subtab, Primary Project +Option,title="General Tab, Project Subtab, Primary Project Option"] +. Select the following options: +* Click *Edit* to define the primary project. The Edit PrimaryProject +dialog box appears. +* Use the *Multiple Projects* option to +link:#Configuring_Multiple_Mapping_Projects[add additional projects to +the session]. [#Figure 85-2]##*_Edit Primary Project Dialog Box_* +image:editprj.gif[Edit Primary Project Dialog +Box,title="Edit Primary Project Dialog Box"] +. Complete each field on the Edit Primary Project dialog box. + +Use this information to enter date in each field of the Edit Primary +Project dialog box: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*XML* |Select *XML* to add a mapping project as a deployment XML file. +Click *Browse* to select the file. + +|*Class* |Select *Class* to add a mapping project as a _compiled_ Java +class file. Click *Browse* to select the file. +|=== + +=== How to Configure a Primary Mapping Project Using Java + +Using Java, you can register descriptors with a session using the +following API: + +* `+Project+` API – Read your `+project.xml+` file (or instantiate your +project class) and create your session using `+Project+` method +`+createServerSession+` or `+createDatabaseSession+`. +* `+Session+` API – Add a descriptor or set of descriptors to a session +using the `+DatabaseSession+` API that the following table lists. +Descriptors should be registered before login, but independent sets of +descriptors can be added after login. + +[#Table 85-4]## *_DatabaseSession API for Registering Descriptors_* + +[width="100%",cols="<29%,<71%",options="header",] +|=== +|*Session Method* |*Description* +|`+addDescriptors(Project)+` |Add to the session all the descriptors +owned by the passed in `+Project+`. + +|`+addDescriptors(Vector)+` |Add to the session all the descriptors in +the passed in `+Vector+`. + +|`+addDescriptor(Descriptor)+` |Add an individual descriptor to the +session. +|=== + +== Configuring a Session Login + +A session login encapsulates details of data source access for any +session that persists to a data source. The session login overrides any +other login configuration. + +This table summarizes which sessions support session login +configuration. + +[#Table 85-5]## + +Session + +Session Login + +Server and Client Sessions + +Session Broker and Client Sessions + +Database Sessions + +The session login provides access to a variety of features, including +the following: + +* Connection configuration such as whether or not to use external +connection pooling. +* Sequencing configuration (that overrides sequencing configuration made +at the project level, if any). +* Miscellaneous options specific to your chosen data source. +* Properties (arbitrary, application-specific named values). + +For more information, see the following: + +* link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Login_Types[Data +Source Login Types] +* link:Configuring%20a%20Data%20Source%20Login%20(ELUG)[Configuring a +Data Source Login] + +== Configuring Logging + +Use the EclipseLink logging framework to record EclipseLink behavior to +a log file or session console. + +This table summarizes which sessions support logging configuration. + +[#Table 85-6]## + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Unit of work sessions + +Session broker and client sessions + +Database sessions + +[width="100%",cols="<100%",] +|=== +|*Note*: If the session belongs to a session broker, you must specify +the logging information in the session broker – not in the session +itself. +|=== + +By default, EclipseLink uses its own native logger. Alternatively, you +can configure EclipseLink to +link:#How_to_Configure_a_Session_to_use_the_java.util.logging_Package[use +the `+java.util.logging+` package]. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging[Logging]. + +=== How to Configure Logging Using Workbench + +To specify the logging information for a session, use this procedure: + +[arabic] +. Select a database session in the *Navigator*. Its properties appear in +the Editor. +. Click the *Logging* tab. The Logging tab appears. +[#Figure 85-3]##*_Logging Tab_* image:seslog.gif[Logging +Tab,title="Logging Tab"] +. Complete the Logging fields on the tab. + +Use the following information to enter data in each field of the Logging +tab to select the profiler option to use with this session: + +Option + +Description + +No Logging + +Select this option to specify that nothing is logged for this session. + +Server + +Select this option to use logging capabilities of the application server +to which you are deploying this application. + +Java + +Select this option to use java.util.logging package. + +Standard + +Select this option to use the EclipseLink logging framework. When +selected, you can optionally configure the following options. + +Logging Level + +Define the amount of logging information to record (in ascending order +of information): + +Config – Log only login, JDBC connection, and database information. + +Info (default) – Log the login/logout per sever session, with user name. +After acquiring the session, detailed information is logged. + +Warning – Log exceptions that do not force EclipseLink to stop, +including all exceptions not logged with Severe level. This does not +include a stack trace. + +Severe – Log exceptions indicating EclipseLink cannot continue, and any +exceptions generated during login. This includes a stack trace. + +Fine – Log SQL (including thread information). + +Finer – Similar to warning. Includes stack trace. + +Finest – Includes additional low-level information. + +All – Log everything. + +Console + +Select this option to display logging information to the standard +console output. + +File + +Select this option to record logging information in a file. Click Browse +to specify the name and location of the log file. + +Options + +Select this option to override additional logging option defaults for +Java and Standard logging only. + +Log Exception Stack Trace + +Select this option to include the stack trace with any exception written +to the log. + +Default: For SEVERE messages, log stack trace. For WARNING messages, +only log stack trace at log level FINER or lower. + +Print Connection + +Select this option to include the connection identifier in any +connection related log messages. + +Default: Enabled for all message and log levels. + +Print Date + +Select this option to include the date and time at which the log message +was generated. + +Default: Enabled for all message and log levels. + +Print Session + +Select this option to include the session name in any session related +log messages. + +Default: Enabled for all message and log levels. + +Print Thread + +Select this option to include the thread name in any thread related log +messages. + +Default: Log only at log level FINER or lower. + +=== How to Configure Logging Using Session API in Java + +If you use EclipseLink native logging (the default), then at run time, +you can configure logging options using +`+org.eclipse.persistence.sessions.Session+` logging API. + +The `+Session+` interface defines the following logging methods: + +* `+setSessionLog+` – specify the type of logging to use (any +implementor of `+org.eclipse.persistence.logging.SessionLog+`) +* `+dontLogMessages+` – disable logging +* `+setLog+` – specify the `+java.io.Writer+` to which the session logs +messages +* `+setLogLevel+` – specify the level at which the session logs using +`+org.eclipse.persistence.logging.SessionLog+` constants: +** `+OFF+` +** `+SEVERE+` +** `+WARNING+` +** `+INFO+` +** `+CONFIG+` +** `+FINE+` +** `+FINER+` +** `+FINEST+` +** `+ALL+` + +This example illustrates how to configure a session to use +`+java.util.logging+` package. + +[#Example 85-1]## *_Configuring a Session to Use java.util.logging_* + +`+session.setSessionLog(new JavaLog());+` + +This example illustrates how to configure a session to use the server +log that OC4J provides. For more information about server logging, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server_Logging[Server +Logging]. + +*_Configuring a Session to Use Application Server Logging_* + +`+session.setSessionLog(new OjdlLog());+` + +This example illustrates how to configure a session to log to a +`+java.io.Writer+`: + +[#Example 85-3]## *_Configuring a Session to Log to a java.io.Writer_* + +`+session.setLog(myWriter);+` + +=== How to Configure a Session to use the java.util.logging Package + +If you use `+java.util.logging+` package, then you configure logging +options in the __`+/lib/logging.properties+` file. Messages are written +to zero or multiple destinations based on this configuration file. + +If you configure a session to use `+java.util.logging+` package, +consider the following: + +* link:#logging.properties[logging.properties] +* link:#Formatters[Formatters] +* link:#Namespace[Namespace] + +==== logging.properties + +Configure the `+logging.properties+` file as this example illustrates: + +[#Example 85-4]## *_java.util.logging Configuration in +logging.properties_* + +[source,java] +---- + handlers = java.util.logging.ConsoleHandler + java.util.logging.ConsoleHandler.level = CONFIG + java.util.logging.ConsoleHandler.formatter = org.eclipse.persistence.logging.LogFormatter + org.eclipse.persistence.LoggingSession.connection.level = CONFIG +---- + +For information about the types of formatters available, see +link:#Formatters[Formatters]. + +==== Formatters + +EclipseLink provides two formatters: `+LogFormatter+` and +`+XMLLogFormatter+`. They override the `+SimpleFormatter+` and +`+XMLFormatter+` `+java.util.logging+` formatters and always log session +and connection info when available. They also log thread and exception +stack trace information at certain levels as specified by the logging +level. + +==== Namespace + +Namespace is supported for `+java.util.logging+`. This table lists the +static constants defined in +`+org.eclipse.persistence.sessions.SessionLog+` for EclipseLink +components and the corresponding strings in `+logging.properties+`. + +[#Table 85-7]## *_Logging Property FIle Names_* + +[width="100%",cols="<25%,<75%",options="header",] +|=== +|*SessionLog* |*logging.properites* +|Not Applicable |`+org.eclipse.persistence+` +|Not Applicable |`+org.eclipse.persistence.+` +|`+SQL+` |`+org.eclipse.persistence.+``+.sql+` +|`+TRANSACTION+` |`+org.eclipse.persistence.+``+.transaction+` +|`+EVENT+` |`+org.eclipse.persistence.+``+.event+` +|`+CONNECTION+` |`+org.eclipse.persistence.+``+.connection+` +|`+QUERY+` |`+org.eclipse.persistence.+``+.query+` +|`+CACHE+` |`+org.eclipse.persistence.+``+.cache+` +|`+PROPAGATION+` |`+org.eclipse.persistence.+``+.propagation+` +|`+SEQUENCING+` |`+org.eclipse.persistence.+``+.sequencing+` +|`+EJB+` |`+org.eclipse.persistence.+``+.ejb+` +|`+EJB_OR_METADATA+` |`+org.eclipse.persistence.+``+.ejb_or_metadata+` +|`+WEAVER+` |`+org.eclipse.persistence.+``+.weaver+` +|`+PROPERTIES+` |`+org.eclipse.persistence.+``+.properties+` +|`+SERVER+` |`+org.eclipse.persistence.+``+.server+` +|=== + +In the `+logging.properties+` names listed in the +link:#Table_85-7[Logging Property FIle Names] table, note that is the +name of the session that the application is running in. For example, if +the name of the session is `+MyApplication+`, then you would use +`+org.eclipse.persistence.MyApplication.sql+` for the SQL logging +property. + +An application can also define its own namespace and write to it through +the logging API, as long as the logger for that namespace is defined in +the logging configuration. Otherwise messages are written to the parent +logger, `+org.eclipse.persistence.+`. + +== Configuring Multiple Mapping Projects + +Each session is associated with at least +link:#Configuring_a_Primary_Mapping_Project[one mapping project]. You +can include additional EclipseLink mapping projects for a session. + +This table summarizes which sessions support additional mapping project +configuration. + +[#Table 85-8]## + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session Broker and Client Sessions + +Database sessions + +=== How to Configure Multiple Mapping Projects Using Workbench + +To specify additional EclipseLink projects for your session, use this +procedure: + +[arabic] +. Select a server or database session in the *Navigator*. Its properties +appear in the Editor. +. Click the *General* tab. The General tab appears. +. Click the *Project* subtab. The Project subtab appears. +[#Figure 85-4 ]##*_General Tab, Project Subtab, Multiple Projects +Options_* image:sesgenad.gif[General Tab, Project Subtab, Multiple +Projects +Options,title="General Tab, Project Subtab, Multiple Projects Options"] +. Select *Multiple Projects* option. The Multiple Projects subtab +appears. +. Click the *Multiple Projects* subtab. ++ +*_General Tab, Multiple Projects Subtab_* image:sesadv.gif[General Tab, +Multiple Projects Subtab,title="General Tab, Multiple Projects Subtab"] +. To add an additional mapping project to this session, click *Add*. For +more information, see +link:#Configuring_a_Primary_Mapping_Project[Configuring a Primary +Mapping Project]. To remove EclipseLink mapping projects, select the +project file and click *Remove*. + +=== How to Configure Multiple Mapping Projects Using Java + +Using Java, you can register descriptors from more than one project with +a session using the `+DatabaseSession+` API that this table lists. You +can register descriptors before login, but you can add independent sets +of descriptors after login. + +[#Table 85-9]## *_DatabaseSession API for Registering Descriptors_* + +[width="100%",cols="<26%,<74%",options="header",] +|=== +|*Session Method* |*Description* +|`+addDescriptors(Project)+` |Add additional descriptor to the session +in the form of a project. + +|`+addDescriptors(Vector)+` |Add a vector of individual descriptor files +to the session in the form of a project. + +|`+addDescriptor(Descriptor)+` |Add individual descriptor to the +session. +|=== + +== Configuring a Performance Profiler + +To successfully improve the performance of an EclipseLink application, +you must measure performance before and after each optimization. +EclipseLink provides a variety of built-in performance measuring +features (known as profilers) that you can configure at the session +level. + +This table summarizes which sessions support performance profiler +configuration. + +[#Table 85-10]## + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +EclipseLink provides the following profilers: + +* EclipseLink profiler: logs performance statistics for every executed +query in a given session (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring_EclipseLink_Performance_with_the_EclipseLink_Profiler[Measuring +EclipseLink Performance with the EclipseLink Profiler]) + +=== How to Configure a Performance Profiler Using Workbench + +To specify the type of profiler in a session, use this procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Options* tab. The Options tab appears. *_Options Tab, +Profiler Options_* image:sespro.gif[Options Tab, Profiler +Options,title="Options Tab, Profiler Options"] +. Complete the *Profiler* field on the tab. + +Use the following information to select the profiler option to use with +this session: + +Option + +Description + +No Profiler + +Disable all profiling. + +Standard (EclipseLink) + +Enable EclipseLink profiling. For more information, see the following: + +How to Configure the EclipseLink Performance Profiler + +Measuring EclipseLink Performance with the EclipseLink Profiler + +=== How to Configure a Performance Profiler Using Java + +You can use Java to configure a session with a profiler using +`+Session+` method `+setProfiler+`, as this example shows. + +[#Example 85-5]## *_Configuring a Session with an EclipseLink Profiler_* + +`+session.setProfiler(new PerformanceProfiler());+` + +To end a profiling session, use `+Session+` method `+clearProfiler+`. + +== Configuring an Exception Handler + +You can associate a single exception handling class with each session. +This class must implement the +`+org.eclipse.persistence.exceptions.ExceptionHandler+` interface. + +This table summarizes which sessions support exception handler +configuration. + +[#Table 85-11]## *_Session Support for Exception Handler Configuration_* + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +For an example exception handler implementation, see +link:#How_to_Configure_an_Exception_Handler_Using_Java[Using Java]. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Exception_Handlers[Exception +Handlers]. + +=== How to Configure an Exception Handler Using Workbench + +To specify the exception handler class in a session, use this procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Options* tab. The Options tab appears. *_Options Tab, +Exception Handler Field_* image:sescust.gif[Options Tab, Exception +Handler Field,title="Options Tab, Exception Handler Field"] +. Complete the *Exception Handler* field. +. Click *Browse* and select the exception handler class for this +session. + +=== How to Configure an Exception Handler Using Java + +This example shows an example exception handler implementation. In this +implementation, the exception handler always tries to reestablish the +connection if it has been reset by peer, but only retries a query if it +is an instance of `+ReadQuery+`. Note that this exception handler either +returns the result of the reexecuted `+ReadQuery+` or throws an +exception. + +[#Example 85-6]## *_Implementing an Exception Handler_* + +[source,java] +---- + session.setExceptionHandler( + new ExceptionHandler() { + public Object handleException(RuntimeException exception) { + if (exception instanceof DatabaseException) { + DatabaseException dbex = (DatabaseException) exception; + if ((dbex.getInternalException() instanceof SQLException) && + (((SQLException) dbex.getInternalException()).getErrorCode() == MyDriver.CONNECTION_RESET_BY_PEER)) { + dbex.getAccessor().reestablishConnection(dbex.getSession()); + if (dbex.getQuery() instanceof ReadQuery) { + return dbex.getSession().executeQuery(dbex.getQuery(), dbex.getQuery().getTranslationRow()); + } + throw exception; + } + } + throw exception; + } + } + ); +---- + +[width="100%",cols="<100%",] +|=== +|*Note*: Unhandled exceptions must be rethrown by the exception handler +code. +|=== + +== Configuring a Session Customizer Class + +A session customizer class is a Java class that implements the +`+org.eclipse.persistence.internal.sessions.factories.SessionCustomizer+` +interface and provides a default (zero-argument) constructor. You can +use a session customizer to customize a session at run time on a loaded +session before login occurs, similar to how you can use an +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[amendment +method to customize a descriptor]) For example, you can use a session +customizer class to define and register session event listeners with the +session event manager (see +link:#Configuring_Session_Event_Listeners[Configuring Session Event +Listeners]). + +This table summarizes which sessions support customizer class +configuration. + +[#Table 85-12]## *_Session Support for Customizer Class Configuration_* + +Session + +Using the Workbench + +How to Use Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Customization[Session +Customization]. + +=== How to Configure Customizer Class Using Workbench + +To specify the session customizer class in a session, use this +procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Options* tab. The Options tab appears. *_Options Tab, +Session Customizer Class Field_* image:sestran.gif[Options Tab, Session +Customizer Class +Field,title="Options Tab, Session Customizer Class Field"] +. Complete the *Session Customizer Class* field. +. Click *Browse* and select the customizer class for this session. + +=== How to Configure Customizer Class Using Java + +When using Java, create a customize class that implements the +`+org.eclipse.persistence.internal.sessions.factories.SessionCustomizer+` +interface. This example illustrates the creation of the session +customizer. The `+customize+` method contains the configuration of the +`+Login+` owned by the `+Session+` with the appropriate transaction +isolation. + +[#Example 85-7]## *_Creating a SessionCustomizer Class_* + +[source,java] +---- + import org.eclipse.persistence.internal.sessions.factories.SessionCustomizer; + import org.eclipse.persistence.sessions.Session; + import org.eclipse.persistence.sessions.DatabaseLogin; + + public class EmployeeSessionCustomizer implements SessionCustomizer { + + public void customize(Sesssion session) { + DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin(); + login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED); + } + } +---- + +== Configuring the Server Platform + +The EclipseLink server platform defines how a session integrates with a +Java EE server including the following: + +* Run-time services: Enables the deployment of a Java Management +Extensions (JMX) MBean that allows monitoring of the EclipseLink +session. +* External transaction controller: Integrates the EclipseLink session +with the server’s Java Transaction API (JTA) service. This should always +be used when using EJB or JTA transactions. You configure EclipseLink to +integrate with the container’s external transaction service by +specifying an EclipseLink external transaction controller. For more +information on external transaction services, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Unit_of_Work_Transaction_Demarcation[Unit +of Work Transaction Demarcation]. + +This table summarizes which sessions support a server platform. + +[#Table 85-13]## *_Session Support for Server Platform_* + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +=== How to Configure the Server Platform Using Workbench + +To specify the server platform options for a session, use this +procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *General* tab. The General tab appears. +. Click the *Server Platform* subtab. The Server Platform subtab +appears. *_General Tab, Server Platform Subtab_* image:sessp.gif[General +Tab, Server Platform Subtab,title="General Tab, Server Platform Subtab"] +. Enter complete each field on the Server Platform subtab. + +Use the following information to enter data in each field of the Server +Platform subtab: + +Field + +Description + +Server Platform + +Check this field if you intend to deploy your application to a Java EE +application server. + +If you check this field, you must configure the target application +server by selecting a Platform. + +Platform + +Select the Java EE application server to which you will deploy your +application. + +EclipseLink supports the following Java EE application servers: + +OC4J 10.1.3 + +SunAS 9 + +WebLogic 10.3 + +WebLogic 10 + +WebLogic 9.0 + +WebSphere 6.1 + +JBoss 4.2.2 + +JBoss 4.2.2 + +GlassFish 2.1 + +GlassFish 3 + +Custom + +EclipseLink supports the following Java Servlet container servers: + +Tomcat 6 + +For detailed information about supported application server versions and +configuration requirements, see Integrating EclipseLink with an +Application Server. Select Custom if you have created your own +org.eclipse.persistence.platform.server.ServerPlatform class to use an +application server not currently supported by EclipseLink or to override +an existing ServerPlatform. If you select Custom, you must specify your +custom ServerPlatform class by selecting a Server Platform Class. + +The server platform you select overrides the default server platform set +at the sessions configuration leve. + +Enable Runtime Services + +Check this field to configure the EclipseLink runtime to enable the +deployment of a JMX MBean that allows monitoring of the EclipseLink +session. + +Enable External Transaction Controller (JTA) + +Check this field if you intend to integrate your application with an +external transaction controller. For more information, see Unit of Work +Transaction Demarcation. + +If you configure Platform for a Java EE application server that +EclipseLink supports, the EclipseLink runtime will automatically select +the appropriate external transaction controller class. + +If you configure Platform as Custom, you must specify an external +transaction controller class by selecting an External Transaction +Controller. + +Server Platform Class + +This option is only available if you configure Platform as Custom. + +Click Browse to select your custom ServerPlatform class. + +Transaction Controller Class (JTA) + +This option is only available if you configure Platform as Custom. + +If you checked Enable External Transaction Controller (JTA), click +Browse to select the transaction controller class that corresponds with +your custom ServerPlatform class. + +=== How to Configure the Server Platform Using Java + +When using Java, you must pass the session in a server platform +constructor. This example illustrates using a session customizer (see +link:Customizing%20the%20EclipseLink%20Application_(ELUG)#Using_the_Session_Customizer_Class[Using +the Session Customizer Class]) to configure a session with a server +platform from the `+org.eclipse.persistence.platform.server+` package. + +[#Example 85-8]## *_Configuring a Session with a Server Platform_* + +[source,java] +---- + import org.eclipse.persistence.internal.sessions.factories.SessionCustomizer; + ... + public class MySessionCustomizer implements SessionCustomizer { + public void customize (Session session) { + Server server = (Server)session; + server.setServerPlatform(new Oc4j_11_1_1_Platform(DatabaseSession)server)): + } + } +---- + +== Configuring Session Event Listeners + +As you perform persistence operations with a session, the session +produces various events (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Event_Manager_Events[Session +Event Manager Events]) that the EclipseLink runtime uses to coordinate +its various components. You can configure a session with one or more +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Event_Listeners[session +event listeners] to customize session behavior and debug session +operations. For example, session event listeners play an important role +in the +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Configuring_Exclusive_Isolated_Client_Sessions_for_Virtual_Private_Database[configuration +of isolated sessions]. + +This table summarizes which sessions support event listeners +(SessionEventListener). + +[#Table 85-14]## *_Session Support for Event Listeners_* + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +=== How to Configure Session Event Listeners Using Workbench + +*Session Event Listeners* + +To specify the event listener class in a session, use this procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Options* tab. The Options tab appears. *_Options Tab, Event +Listeners field_* image:sesevnt.gif[Options Tab, Event Listeners +field,title="Options Tab, Event Listeners field"] +. To add a new event listener, click *Add*, then select the event +listener class for this session. To remove an existing event listener, +select the *Event Listener* and click *Remove*. + +=== How to Configure Session Event Listeners Using Java + +This example illustrates how to use Java to register a session event +listener with a session. EclipseLink provides a `+SessionEventAdapter+` +to simplify creating a `+SessionEventListener+`. The +`+SessionEventAdapter+` provides a default implementation of all the +methods of the `+SessionEventListener+` interface. You need only +override the specific methods of interest. Typically, you would define +session event listeners in a +link:#Configuring_a_Session_Customizer_Class[session customizer class]. + +[#Example 85-9]## *_Using the Session Event Adapter to Create a Session +Event Listener_* + +[source,java] +---- + ... + SessionEventAdapter myEventListener = new SessionEventAdapter() { + // Listen for PostCommitUnitOfWork events + public void postCommitUnitOfWork(SessionEvent event) { + // Call the handler routine + unitOfWorkCommitted(); + } + }; + mySession.getEventManager().addListener(myEventListener); + ... +---- + +For information on how to add logging to your listeners, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging[Logging]. + +== Configuring the Integrity Checker + +When you log into a session, EclipseLink initializes and validates the +descriptors you registered with it. By configuring the integrity +checker, you can customize this validation process to do the following: + +* link:#Check_Database[Check Database] +* link:#Catch_All_Exceptions[Catch All Exceptions] +* link:#Catch_Instantiation_Policy_Exceptions[Catch Instantiation Policy +Exceptions] + +This table summarizes which sessions support descriptor integrity +checking configuration. + +[#Table 85-15]## *_Session Support for Checking Descriptor Integrity_* + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +*Check Database* + +The `+IntegrityChecker+` method `+setShouldCheckDatabase+` specifies +whether or not the integrity checker should verify the descriptor’s +metadata against the database metadata. This will report any errors due +to missing or incorrect table or fields specified in the descriptors. +This is turned off by default as it adds a significant overhead to +connecting a session. + +*Catch All Exceptions* + +By default, the integrity checker catches all exceptions that occur +during initialization, and throws a single exception at the end of +initialization reporting all of the errors detected. If you only want +the first exception encountered, you can disable this feature using +`+IntegrityChecker+` method `+setShouldCatchExceptions(false)+`. + +*Catch Instantiation Policy Exceptions* + +By default, the integrity checker tests the default or configured +constructor for each descriptor initialized in the session. To disable +this feature, use `+IntegrityChecker+` method +`+setShouldCheckInstantiationPolicy(false)+`. + +=== How to Configure the Integrity Checker Using Java + +As this example shows, you can configure the integrity checker +validation process. + +[#Example 85-10]## *_Configuring the Integrity Checker_* + +[source,java] +---- + session.getIntegrityChecker().setShouldCheckDatabase(true); + session.getIntegrityChecker().setShouldCatchExceptions(false); + session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false); + session.login(); +---- + +== Configuring Connection Policy + +Using a connection policy, you can control how an EclipseLink session +acquires and uses read and write connections, including the following: + +* link:#Exclusive_Write_Connections[Exclusive Write Connections] +* link:#Lazy_Connection_Acquisition[Lazy Connection Acquisition] + +This table summarizes which sessions support connection policy +configuration. + +[#Table 85-16]## *_Session Support for Connection Policy_* + +Session + +Using Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +*Exclusive Write Connections* + +An exclusive connection is one that EclipseLink allocates to a client +session for reading (of isolated data) and writing for the duration of +the client session’s life cycle. + +By default, exclusive connections are not used and a client session uses +the server session’s read connection pool for all non-pessimistic read +queries. A connection is obtained from the read connection pool for each +read query execution and released back to the pool after the query is +executed. A connection is only obtained from the write connection pool +for the unit of work commit operation, or, potentially, earlier if data +modify queries, or read queries using pessimistic locking are used. The +connection will be release back to the write connection pool after the +unit of work is committed or released. Exclusive connections are +provided for use with database read security or Virtual Private Database +(VPD) support. When using an exclusive connection, you will obtain it +from the server session’s write connection pool. When you acquire the +client, the exclusive connection will be used for read queries to +isolated classes (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]), exclusive read queries, pessimistic read queries, and +for the unit of work commit operation. The exclusive connection will +only be released when the client session is released. EclipseLink still +acquires a shared connection from the read connection pool for reading +nonisolated data. If you use a JTA-managed external connection pool with +exclusive connections, do not reuse a client session across JTA +transaction boundaries, as the physical JTA database connection is +released and acquired from the connection pool relative to the JTA +transaction life cycle. A new client session, or the active unit of +work, should be used for each JTA transaction. For more information, see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring_Exclusive_Read_Connections[Configuring +Exclusive Read Connections]. + +You can also configure exclusive connections on a +client-session-by-client-session basis (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_Exclusive_Connections[How +to Acquire a Client Session that Uses Exclusive Connections]) and for +named queries (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Advanced_Options[Configuring +Named Query Advanced Options]). + +[width="100%",cols="<100%",] +|=== +|*Note*: If any client session contains an exclusive connection, you +must release the session (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Logging_Out_of_a_Session[Logging +Out of a Session]) when you are finished using it. We do not recommend +relying on the finalizer to release the connection when the session is +garbage-collected. If you are using an active unit of work in a JTA +transaction, you do not need to release the client session–the unit of +work will release it after the JTA transaction completes. +|=== + +*Lazy Connection Acquisition* + +By default, EclipseLink acquires write connections lazily, when you +perform the first unit of work commit operation, exclusive read query, +or pessimistic read query with your client session. The write connection +will also be released after each unit of work it committed or released. + +Alternatively, you can configure EclipseLink to acquire the write +connection at the time you acquire a client session, and release the +connection when you release the client session. + +You can also configure lazy connection acquisition on a +client-session-by-client-session basis (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Does_Not_Use_Lazy_Connection_Allocation[How +to Acquire a Client Session that Does Not Use Lazy Connection +Allocation]). + +=== How to Configure Connection Policy Using Workbench + +To specify the connection policy in a session, use this procedure: + +[arabic] +. Select a session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Connection Policy* tab. The Connection Policy tab appears. +*_Connection Policy Tab_* image:sescpol.gif[Connection Policy +Tab,title="Connection Policy Tab"] + +=== How to Configure Connection Policy Using Java + +To configure whether or not an exclusive connection is allocated to a +particular isolated session, use the +`+org.eclipse.persistence.sessions.server.ConnectionPolicy+` method +`+setExclusiveMode+`. You can set the `+ExclusiveMode+` to one of the +following: + +* `+Transactional+` - triggers the creation of a `+ClientSession+`. You +can also enable this option by selecting *Acquire Connections Lazily* in +link:#How_to_Configure_Connection_Policy_Using_TopLink_Workbench[Workbench]. +* `+Isolated+` - triggers the creation of an +`+ExclusiveIsolatedClientSession+`. You can also enable this option by +selecting *Acquire Exclusive Connection* in +link:#How_to_Configure_Connection_Policy_Using_TopLink_Workbench[Workbench]. +* `+Asways+` - also triggers the creation of an +`+ExclusiveIsolatedClientSession+`. Note that this mode allows the usage +of an exclusive connection without requiring isolation. You cannot use +Workbench to set this option. + +To define a map of properties used to support an isolated session, use +the following `+ConnectionPolicy+` methods: + +* `+setProperty(Object key, Object value)+`: Adds the property `+value+` +to the `+Map+` under `+key+`, overwriting the existing value if `+key+` +already exists in the `+Map+`. Note that these properties are not +specifically geared toward an isolated client session. EclipseLink +runtime makes them available during the creation of a client session in +a `+PostAcquireExclusiveConnection+` event, but does not pass them to +any event. Instead, it keeps these properties in the +`+ConnectionPolicy+`, which, in turn, is kept by the client session. +* `+Object getProperty(Object key)+`: Returns the value associated with +`+key+` as an `+Object+`. +* `+boolean hasProperties+`: Returns `+true+` if one or more properties +exist in the `+Map+`; otherwise returns false. + +The EclipseLink runtime passes this `+Map+` into `+SessionEvent+` events +`+PostAcquireExclusiveConnection+` and `+PreReleaseExclusiveConnection+` +so that your implementation can make the appropriate PL/SQL calls to the +underlying database platform (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PostAcquireExclusiveConnection_Event_Handler[Using +PostAcquireExclusiveConnection Event Handler] and +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PreReleaseExclusiveConnection_Event_Handler[Using +PreReleaseExclusiveConnection Event Handler]). + +To configure the session to use a named connection pool, use the +`+ConnectionPool+` constructor that takes a `+String+` connection pool +name as an argument, as follows: + +`+Session clientSession = server.acquireClientSession(new ConnectionPolicy("myConnectionPool"));+` + +== Configuring Named Queries at the Session Level + +A *named query* is an EclipseLink query that you create and store, by +name, in a session for later retrieval and execution. Named queries +improve application performance, because they are prepared once and they +(and all their associated supporting objects) can be efficiently reused +thereafter making them well-suited for frequently executed operations. + +If a named query is global to a project, configure it at the session +level. Alternatively, you can configure a named query at the descriptor +level (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Queries_at_the_Descriptor_Level[Configuring +Named Queries at the Descriptor Level]). + +Use named queries to specify SQL, EJB QL, or EclipseLink `+Expression+` +queries to access your data source. + +This table summarizes which sessions support named query configuration. + +[#Table 85-17]## + +Session + +Using the Workbench + +Using Java + +Server and client sessions + +Session broker and client sessions + +Database sessions + +After you create a named query, you can execute it by name on the +EclipseLink session (see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_Named_Queries[Using +Named Queries]). + +For more information about named queries, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries]. + +=== How to Configure Named Queries at the Session Level Using Java + +You can store a query by name in a `+Session+` using `+Session+` method +`+addQuery(String name, DatabaseQuery query)+`. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..9f768fe1362 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,46 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_Composite_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the configurable options for an EIS composite +collection mapping. + +[#Table 78-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Reference Descriptors + +Configuring Method or Direct Field Accessing at the Mapping Level + +Read-only mappings + +Configuring Container policy + +Mapping comments + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Collection_Mapping[EIS +Composite Collection Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)#CHDHFGAH[Configuring an +EIS Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Direct_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Direct_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..fd7eb9486c4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Direct_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,56 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_Composite_Direct_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the configurable options for an EIS composite direct +collection mapping. + +[#Table 76-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Simple type translator + +Use of a single node + +Configuring Method or Direct Field Accessing at the Mapping Level + +Read-only mappings + +Container policy + +Mapping comments + +Serialized object converter + +Type conversion converter + +Object type converter + +JAXB typesafe enumerated converter + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Direct_Collection_Mapping[EIS +Composite Direct Collection Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)#CHDHFGAH[Configuring an +EIS Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CBBHHHJC[Configuring a +Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Object_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Object_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..581aff131ac --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Composite_Object_Mapping_(ELUG).adoc @@ -0,0 +1,44 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_Composite_Object_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the configurable options for an EIS composite object +mapping. + +[#Table 77-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Configuring Reference Descriptors + +Method or direct field access at the mapping level + +Read-only mappings + +Mapping comments + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)#CHDHFGAH[Configuring an +EIS Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..62df4dac3e5 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Descriptor_(ELUG).adoc @@ -0,0 +1,484 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_an_EIS_Descriptor_(ELUG)[Related +Topics] + +For information on how to create EIS descriptors, see +link:Creating%20an%20EIS%20Descriptor%20(ELUG)[Creating an EIS +Descriptor]. + +This table lists the default configurable options for an EIS descriptor. + +[#Table 72-1]## + +Option to Configure + +EclipseLink Workbench + +Java + +How to Configure XML Schema Namespace + +How to Configure an XML Schema Reference + +Configuring Schema Context for an EIS Descriptor + +Configuring Default Root Element + +Configuring Primary Keys 1 + +Configuring Read-Only Descriptors + +Configuring Unit of Work Conforming at the Descriptor Level + +Configuring Descriptor Alias + +Configuring Descriptor Comments) + +Configuring Record Format + +How to Create Classes + +Configuring Named Queries at the Descriptor Level + +Configuring Custom EIS Interactions for Basic Persistence Operations + +Configuring Cache Refreshing + +Configuring Cache Type and Size at the Descriptor Level + +Configuring Cache Isolation at the Descriptor Level + +Configuring Cache Coordination Change Propagation at the Descriptor +Level + +Configuring Cache Expiration at the Descriptor Level + +Configuring Cache Existence Checking at the Descriptor Level + +Configuring an EIS Descriptor as a Root or Composite Type + +Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor + +Configuring Inheritance for a Parent (Root) Descriptor + +Configuring Inherited Attribute Mapping in a Subclass + +Configuring a Domain Object Method as an Event Handler + +Configuring a Descriptor Event Listener as an Event Handler + +Configuring Locking Policy + +Configuring Returning Policy + +Configuring Instantiation Policy + +Configuring Copy Policy + +Configuring Change Policy + +Configuring Wrapper Policy + +Configuring Amendment Methods + +Configuring a Mapping + +1EIS root descriptors only (see +link:#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]). For more information, +see link:Introduction%20to%20EIS%20Descriptors%20(ELUG)[Introduction to +EIS Descriptors]. + +== Configuring Schema Context for an EIS Descriptor + +Workbench uses the schema context to associate the class that the EIS +descriptor describes with a simple or complex type in one of the schemas +associated with the EIS project (see +link:Using%20Workbench%20(ELUG)#How_to_Configure_an_XML_Schema_Reference[How +to Configure an XML Schema Reference]). This allows Workbench to display +the appropriate attributes available for mapping in that context. + +You must configure the schema context for an EIS root descriptor (see +link:#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]) only if you are using +the Workbench. + +=== How to Configure Schema Context for an EIS Descriptor Using Workbench + +To associate an EIS descriptor with a simple or complex type in this +project’s schema, use this procedure: + +[arabic] +. Select an EIS descriptor in the *Navigator*. Its properties appear in +the Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +[#Figure 72-1]##*_Descriptor Info Tab, Schema Context Option_* +image:desschcx.gif[Descriptor Info Tab, Schema Context +Option,title="Descriptor Info Tab, Schema Context Option"] +. Complete the *Schema Context* option on the tab. +. Click *Browse* to select the schema element to associate with this +descriptor. For more information, see +link:#Configuring_a_Schema_Context[Configuring a Schema Context]. + +==== Choosing a Schema Context + +Use the Choose Schema Context dialog box to select a specific schema +element (such as when mapping an element). + +[#Figure 72-2]## *_Choose Schema Context Dialog Box_* + +.Choose Schema Context Dialog Box +image::schcontx.gif[Choose Schema Context Dialog +Box,title="Choose Schema Context Dialog Box"] + +Select the schema element and click *OK*. + +=== How to Configure Schema Context for an EIS Descriptor Using Java + +For an EIS descriptor, the EclipseLink runtime does not need the schema +context: the runtime can determine the schema context based on the +mappings you configure on the descriptor. No further configuration is +required. + +== Configuring Default Root Element + +You must configure the default root element for +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[EIS +Root Descriptors] so that the EclipseLink runtime knows the data source +data type associated with the class the descriptor describes. +Descriptors used only in composite relationship mappings do not require +a default root element. + +[width="100%",cols="<100%",] +|=== +|*Note:* Although you select an element from your project’s schema to +configure this attribute, you are choosing the element’s simple or +complex type. +|=== + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Default_Root_Element[Default +Root Element]. + +=== How to Configure Default Root Element Using Workbench + +When you create an EIS project using Workbench, you must use XML +records. Consequently, you must configure a default root element so that +Workbench knows what element to start with when persisting an instance +of the class that the EIS descriptor describes. + +To specify a schema element as the default root element for the +descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +[#Figure 72-3]##*_Descriptor Info Tab, Default Root Element Option_* +image:didocroot.gif[Descriptor Info Tab, Default Root Element +Option,title="Descriptor Info Tab, Default Root Element Option"] +. Use the *Default Root Element* option to select the root element for +this descriptor. Click *Browse* to select the schema element to identify +as the root element. See link:#onfiguring_a_Root_Element[Configuring a +Root Element] for more information. + +==== Choosing a Root Element + +Use the Choose Root Element dialog box to select a specific root +element. + +[#Figure 72-4]## *_Choose Root Element Dialog Box_* + +.Choose Root Element Dialog Box +image::rootelem.gif[Choose Root Element Dialog +Box,title="Choose Root Element Dialog Box"] + +Select the root element and click *OK*. + +=== How to Configure Default Root Element Using Java + +When you create an EIS project using Java code, use the +`+EISDescriptor+` method `+setDataTypeName+` to specify the XML schema +complex type name (if you are using XML records) or the JCA record name +(if you are using indexed or mapped records) corresponding to the class +that the EIS descriptor describes. For more information, see +_EclipseLink API Reference_. + +== Configuring Record Format + +The EIS descriptor record format determines the EIS record type to which +the descriptor’s EIS mappings map. + +When you create an EIS project using Workbench, EclipseLink configures +all EIS descriptors with a record format of XML. + +When you create an EIS project in Java, you can configure the EIS +descriptor record type to any of the supported types, as this table +shows. + +[#Table 72-2]## + +EISDescriptor Method + +EIS Record Type + +useMappedRecordFormat + +All EIS mappings owned by this descriptor map to EIS mapped records. + +useIndexedRecordFormat + +All EIS mappings owned by this descriptor map to EIS indexed records. + +useXMLRecordFormat + +All EIS mappings owned by this descriptor map to EIS XML records.If you +use the XML record format, you must specify one or more XML schemas in +your EIS project (see How to Import an XML Schema). The EclipseLink +runtime performs XML data conversion based on one or more XML schemas. +In an EIS XML project, Workbench does not directly reference schemas in +the deployment XML, but insteadexports mappings configured with respect +to the schemas you specify. + +For information on EclipseLink support for XML namespaces, see XML +Namespaces. + +For more information, see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Record_Type[EIS +Record Type]. + +=== How to Configure Record Format Using Java + +To configure the EIS record format for an EIS descriptor, use one of the +`+EISDescriptor+` methods listed in the link:#Table_72-2[EIS Record +Formats] table, as shown in this example. + +[#Example 72-1]## *_Configuring EISDescriptor Record Format_* + +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.useIndexedRecordFormat();+` + +== Configuring Custom EIS Interactions for Basic Persistence Operations + +You can use EclipseLink to define an interaction for each basic +persistence operation (*insert*, *update*, *delete*, *read object*, +*read all*, or *does exist*) so that when you query and modify your +EIS-mapped objects, the EclipseLink runtime will use the appropriate EIS +interaction instead of the default EIS interaction. + +You can configure custom EIS interactions for basic persistence +operations only for EIS descriptors designated as root descriptors ( +link:#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]). + +Using Workbench, you can create `+XMLInteraction+` objects, in which +there is a single query per interaction (see +link:#How_to_Configure_Custom_EIS_Interactions_for_Basic_Persistence_Operations_Using_Workbench[How +to Configure Custom EIS Interactions for Basic Persistence Operations +Using Workbench]). + +Using Java, you can create any `+EISInteraction+` type. For some EIS +projects, it is common for multiple interactions to be used in a single +query. For example, one interaction–to enqueue a request, and another–to +dequeue the response. Because Workbench does not support setting +multiple interactions on a single query, you must use an amendment +method to create and configure the interaction in Java (see +link:#How_to_Configure_Custom_EIS_Interactions_for_Basic_Persistence_Operations_Using_Java[How +to Configure Custom EIS Interactions for Basic Persistence Operations +Using Java]). + +[width="100%",cols="<100%",] +|=== +|*Note:* In a one-to-one or one-to-many EIS mapping, you must also +specify a selection interaction that EclipseLink uses to acquire target +objects. You can use either the target object’s read interaction (the +default) or specify a separate selection interaction, if necessary. For +more information, see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]). +|=== + +=== How to Configure Custom EIS Interactions for Basic Persistence Operations Using Workbench + +To configure custom EIS interactions for basic persistence operations, +use the following procedure: + +[arabic] +. In the *Navigator*, select an EIS root descriptor in a EIS project. +. Click the *Queries* tab in the *Editor*. The Queries tab appears. +. Click the *Custom Calls* tab. The Custom Calls tab appears. +[#Figure 72-5]##*_Queries, Custom Calls Tab for EIS Calls_* +image:Qrcalltab.gif[Queries, Custom Calls Tab for EIS +Calls,title="Queries, Custom Calls Tab for EIS Calls"] +. Click the appropriate interaction type from the list (*Insert*, +*Update*, *Delete*, *Read Object*, *Read All*, or *Does Exist*) and use +the following table to enter data in each field + +[width="100%",cols="<7%,<93%",options="header",] +|=== +|*Field* |*Description* +|*Interaction Type* |Using Workbench, you can only use XML Interactions. +You cannot change this field. + +|*Function Name* |The name of the EIS function that this call type (Read +Object or Read All) invokes on the EIS. + +|*Input Record Name* |The name passed to the JCA adapter when creating +the input record. + +|*Input Root Element* |The root element name to use for the input DOM. + +|*Input Arguments* |The query argument name to map to the interaction +field or XPath nodes in the argument record. For example, if you are +using XML records, use this option to map input argument `+name+` to the +XPath `+name/first-name+`. + +|*Output Arguments* |The result record field or XPath nodes to map to +the correct nodes in the record used by the descriptor’s mappings. For +example, if you are using XML records, use this option to map the output +`+fname+` to `+name/first-name+`.Output arguments are not required if +the interaction returns an XML result that matches the descriptor’s +mappings. + +|*Input Result Path* |Use this option if the EIS interaction expects the +interaction arguments to be nested in the XML record. For example, +specify `+arguments+`, if the arguments were to be nested under the root +element `+exec-find-order+`, then under an `+arguments+` element. + +|*Output Result Path* |Use this option if the EIS interaction result +record contains the XML data that maps to the objects in a nested +structure. For example, specify `+order+`, if the results were return +under a root element `+results+`, then under an `+order+` element. + +|*Properties* |Any properties required by your EIS platform. For +example, property name `+operation+` (from +`+AQPlatform.QUEUE_OPERATION+`) and property value `+enqueue+` (from +`+AQPlatform.ENQUEUE+`). +|=== + +=== How to Configure Custom EIS Interactions for Basic Persistence Operations Using Java + +Using Java, you can create any type of +link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[EIS +interaction] that EclipseLink supports. + +For some EIS projects, it is common for multiple interactions to be used +in a single query: for example, one interaction to enqueue a request and +another to dequeue the response. Because Workbench does not support +setting multiple interactions on a single query, you must use an +amendment method to create and configure the interaction in Java, as +this examle shows. + +[#Example 72-2]## *_Creating an XML Interaction for an AQ Platform_* + +`+public static void addXMLInteractions(ClassDescriptor descriptor) {+` +`+    +`*`+//\'\' \'\'find\'\' \'\'order\'\' \'\'interaction+`* +`+    XMLInteraction request = new XMLInteraction();+` +`+    request.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.ENQUEUE);+` +`+    request.setProperty(AQPlatform.QUEUE, "ORDER_INBOUND_QUEUE");+` +`+    request.setProperty(AQPlatform.SCHEMA, "AQUSER");+` +`+    request.setInputRootElementName("READ_ORDER");+` +`+    request.addArgument("@id");+` `+ +` +`+    XMLInteraction response = new XMLInteraction();+` +`+    response.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.DEQUEUE);+` +`+    response.setProperty(AQPlatform.QUEUE, "ORDER_OUTBOUND_QUEUE");+` +`+    response.setProperty(AQPlatform.SCHEMA, "AQUSER");+` `+ +` +`+    ReadObjectQuery query = new ReadObjectQuery();+` +`+    query.addCall(request);+` `+    query.addCall(response);+` +`+    descriptor.getQueryManager().setReadObjectQuery(query);+` `+ +` +`+    +`*`+//\'\' \'\'place\'\' \'\'order\'\' \'\'interaction+`* +`+    XMLInteraction insert = new XMLInteraction();+` +`+    insert.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.ENQUEUE);+` +`+    insert.setProperty(AQPlatform.QUEUE, "ORDER_INBOUND_QUEUE");+` +`+    insert.setProperty(AQPlatform.SCHEMA, "AQUSER");+` +`+    insert.setInputRootElementName("INSERT_ORDER");+` +`+                +` +`+    descriptor.getQueryManager().setInsertCall(insert);+` `+}+` + +== Configuring an EIS Descriptor as a Root or Composite Type + +You can designate an EIS descriptor as +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Root_Descriptors[root] +or +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Composite_Descriptors[composite]. + +When you designate an EIS descriptor as a root, you tell the EclipseLink +runtime that the EIS descriptor’s reference class is a parent classš–no +other class will reference it by way of a composite object mapping or +composite collection mapping. Using an EIS root descriptor, you can +configure all supported mappings and you can configure the descriptor +with +link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[EIS +interactions]. However, if you configure the EIS root descriptor with a +composite object mapping or composite collection mapping, the reference +descriptor you define must be an EIS composite descriptor; it cannot be +another EIS root descriptor. + +When you designate an EIS descriptor as a composite (the default), you +tell the EclipseLink runtime that the EIS descriptor’s reference class +may be referenced by a +link:Configuring%20an%20EIS%20Composite%20Object%20Mapping%20(ELUG)[composite +object] or +link:Configuring%20an%20EIS%20Composite%20Collection%20Mapping_(ELUG)[composite +collection] mapping. Using an EIS composite descriptor, you can +configure all supported mappings, but you cannot configure it with EIS +interactions. + +You can configure inheritance for a descriptor designated as a composite +(see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor]), however, in +this case, _all_ the descriptors in the inheritance tree must be +aggregates. Aggregate and class descriptors cannot exist in the same +inheritance tree. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Aggregate_and_Composite_Descriptors_and_Inheritance[Aggregate +and Composite Descriptors and Inheritance]. + +If you configure a descriptor as a composite using Workbench, you cannot +configure the descriptor with EJB information. + +For more information, see the following: + +* link:Introduction%20to%20XML%20Descriptors%20(ELUG)#XML_Descriptors_and_Aggregation[XML +Descriptors and Aggregation] +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#Composite_and_Reference_EIS_Mappings[Composite +and Reference EIS Mappings] + +=== How to Configure an EIS Descriptor as a Root or Composite Type Using Workbench + +To configure an EIS descriptor as a root or composite EIS descriptor, +use this procedure: + +[arabic] +. In the *Navigator*, select an EIS composite descriptor. +. Click the *Root* or *Composite* descriptor button on the mapping +toolbar.You can also select the descriptor and choose *Selected* > +*Descriptor Type* > *Root* or *Composite* from the menu or by +right-clicking on the descriptor in the *Navigator* and selecting +*Descriptor Type* > *Root* or *Composite* from the context menu. + +=== How to Configure an EIS Descriptor as a Root or Composite Type Using Java + +To configure an EIS descriptor as root or composite using Java, create a +descriptor amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]) and use the following `+EISDescriptor+` methods: + +* To designate an EIS descriptor as a root descriptor, use +`+EISDescriptor+` method `+descriptorIsNormal+`. +* To designate an EIS descriptor as a composite (nonroot) descriptor, +use `+EISDescriptor+` method `+descriptorIsAggregate+`. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Direct_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Direct_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..48b01689ee0 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Direct_Mapping_(ELUG).adoc @@ -0,0 +1,55 @@ +*NOTOC* +Special:Whatlinkshere_Configuring_an_EIS_Direct_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an EIS direct mapping. + +[#Table 75-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Use of a single node + +Simple type translator + +Method or direct field access at the mapping level + +Default null value at the mapping level + +Read-only mappings + +Mapping comments + +Serialized object converter + +Type conversion converter + +Object type converter + +JAXB typesafe enumerated converter + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Direct_Mapping[EIS +Direct Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)[Configuring an EIS +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Login_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Login_(ELUG).adoc new file mode 100644 index 00000000000..5beeb946984 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Login_(ELUG).adoc @@ -0,0 +1,149 @@ +*TOC* Special:Whatlinkshere_Configuring_an_EIS_Login_(ELUG)[Related +Topics] + +[#Table 95-1]## *_Configurable Options for EIS Login_* + +[width="100%",cols="<63%,<20%,<17%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_an_EIS_Data_Source_Platform_at_the_Session_Level[Data +source platform at the session level] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_EIS_Connection_Specification_Options_at_the_Session_Level[Connection +specification options at the session level] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_User_Name_and_Password[User +name and password] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Password_Encryption[Password +encryption] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[External +connection pooling] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Properties] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Configuring an EIS Data Source Platform at the Session Level + +For each EIS session, you must specify the platform (such as AQ). This +platform configuration overrides the platform at the project level, if +configured. + +For more information, see the following: + +* link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level] +* link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Login_Types[Data +Source Login Types] + +=== How to Configure an EIS Data Source Platform at the Session Level Using Workbench + +To specify the database platform options for an EIS session login, use +this procedure: + +[arabic] +. Select an EIS session in the *Navigator*. Its properties appear in the +Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. *_Login +Tab, Connection Subtab, Platform Options_* image:eispla.gif[Connection +Subtab, Platform Options,title="Connection Subtab, Platform Options"] +. Complete the *Platform* option on the Connection tab. + +Use the following information to enter data in the Platform field on the +Connection tab to configure the platform: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Platform* |The EIS platform for the session. Select from the menu of +options. This menu includes all instances of `+EISPlatform+` in the +EclipseLink classpath. +|=== + +See Also: + +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level] + +== Configuring EIS Connection Specification Options at the Session Level + +You can configure connection information at the session level for an EIS +application. This information is stored in the `+sessions.xml+` file. +The EclipseLink runtime uses this information whenever you perform a +persistence operation using the session in your EIS application. + +This connection configuration overrides the connection information at +the project level, if configured. For more information about +project-level configuration, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins] and +link:Configuring%20an%20EIS%20Project%20(ELUG)#Configuring_EIS_Connection_Specification_Options_at_the_Project_Level[Configuring +EIS Connection Specification Options at the Project Level]. + +This connection configuration is overridden by the connection +information at the connection pool level. For more information about +connection pool-level configuration, see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring_Connection_Pool_Connection_Options[Configuring +Connection Pool Connection Options]. + +=== How to Configure EIS Connection Specification Options at the Session Level Using Workbench + +Use this procedure to specify the connection options for an EIS session +login. + +[arabic] +. Select an EIS session in the Navigator window. Its properties appear +in the Editor window. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection tab appears. +[#Figure 95-2]##*_Login Tab, Connection Subtab_* image:eisconn.gif[Login +Tab, Connection Subtab,title="Login Tab, Connection Subtab"] +. Complete fields on the Login-–Connection tab. + +Use the following information to enter data in the connection fields on +the tab: + +Field + +Description + +Connection Specification Class + +Specify the appropriate connection specification class for the selected +Platform. Click Browse to choose from all the classes in the EclipseLink +classpath. (For example: if Platform is +org.eclipse.persistence.eis.aq.AQPlatform, use +org.eclipse.persistence.eis.aq.AQEISConnectionSpec). + +For more information on platform configuration, see Configuring an EIS +Data Source Platform at the Session Level. + +Connection Factory URL + +Specify the appropriate connection factory URL for the selected +Connection Specification Class (For example: +jdbc:oracle:thin@:localhost:1521:orcl). + +See Also: + +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..44f7b908bdc --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Mapping_(ELUG).adoc @@ -0,0 +1,298 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_an_EIS_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the types of EIS mappings that you can configure and +provides a cross-reference to the type-specific chapter that lists the +configurable options supported by that type. + +[#Table 74-1]## + +If you are creating… + +See… + +EIS direct mapping + +Configuring an EIS Direct Mapping + +EIS composite direct collection mapping + +Configuring an EIS Composite Direct Collection Mapping + +EIS composite object mapping + +Configuring an EIS Composite Object Mapping + +EIS composite collection mapping + +Configuring an EIS Composite Collection Mapping + +EIS one-to-one mapping + +Configuring an EIS One-to-One Mapping + +EIS one-to-many mapping + +Configuring an EIS One-to-Many Mapping + +EIS transformation mapping + +Configuring an EIS Transformation Mapping + +Fore more information, see the following: + +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Mapping_Types[EIS +Mapping Types] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +== Configuring Common EIS Mapping Options + +This table lists the configurable options shared by two or more EIS +mapping types. In addition to the configurable options described here, +you must also configure the options described for the specific EIS +mapping types (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Mapping_Types[EIS +Mapping Types]), as shown in the following table. + +[#Table 74-2]## + +Option to Configure + +Workbench + +Java + +Read-only + +Indirection (lazy loading) + +XPath + +Default null value + +Reference descriptors + +Configuring Method or Direct Field Accessing at the Mapping Level + +Private or independent relationships + +Comments + +Serialized object converter + +Type conversion converter + +Object type converter + +Simple type translator + +Container policy + +Selection interaction + +Use of a single node + +JAXB typesafe enumeration converter + +== Configuring Reference Descriptors + +In EIS mappings that extend +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+` or +`+org.eclipse.persistence.mappings.AggregateMapping+` class, attributes +reference other EclipseLink descriptors–not the data source. You can +select a descriptor in the current project, or a descriptor from some +other project. + +This table summarizes which EIS mappings support this option. + +[#Table 74-3]## *_Mapping Support for Reference Descriptor_* + +Mapping + +Using the Workbench + +Using Java + +Direct mapping + +Composite direct collection mapping + +Composite object mapping + +Composite collection mapping + +One-to-one mapping + +One-to-many mapping + +Transformation mapping + +=== How to Configure Reference Descriptors Using Workbench + +To specify a reference descriptor for an EIS mapping, use this +procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 74-1]##*_General Tab, Reference Descriptor Field_* +image:mpgenref.gif[General Tab, Reference Descriptor +Field,title="General Tab, Reference Descriptor Field"] +. Use the *Reference Descriptor* field to select the descriptor +referenced by this relationship mapping. + +[width="100%",cols="<100%",] +|=== +|*Note:* For one-to-one and one-to-many EIS mappings, the reference +descriptor must be a root descriptor. See +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]. +|=== + +You can specify a reference descriptor that is not in the current +Workbench project. For example, to create a mapping to an `+Employee+` +class that does not exist in the current project, do the following: + +[arabic] +. Add the `+Employee+` class to your current project. See +link:Creating%20a%20Project%20(ELUG)#Working_with_Projects[Working with +Projects]. +. Create the relationship mapping to the `+Employee+` descriptor. +. Deactivate the `+Employee+` descriptor. See +link:Using%20Workbench%20(ELUG)#Active_and_Inactive_Descriptors[Active +and Inactive Descriptors]. + +When you generate the deployment XML for your project, the mapping to +the `+Employee+` class will be included, but not the `+Employee+` class +itself. + +== Configuring Selection Interaction + +In EIS mappings that extend +`+org.eclipse.persistence.mappings.ForeignReferenceMapping+` class, +EclipseLink uses a selection interaction to acquire the instance of the +target object to which the mapping refers. + +By default, EclipseLink uses the read interaction you define for the +mapping’s reference descriptor (see +link:#Configuring_Reference_Descriptors[Configuring Reference +Descriptors]). In most cases, this interaction is sufficient. If the +reference descriptor’s read interaction is not sufficient, you can +define a separate interaction. + +This table summarizes which EIS mappings support this option. + +[#Table 74-4]## *_Mapping Support for Selection Interaction_* + +Mapping + +Using the Workbench + +Using Java + +Direct mapping + +Composite direct collection mapping + +One-to-one mapping + +One-to-many mapping + +Composite object mapping + +Composite collection mapping + +Transformation mapping + +For more information about how EclipseLink uses the selection criteria, +see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#Reference_EIS_Mappings[Reference +EIS Mappings]. + +=== How to Configure Selection Interaction Using Workbench + +To specify the selection interaction (such as Read Object) for the EIS +mapping, use this procedure: + +[arabic] +. Select the one-to-many EIS mapping in the *Navigator*. Its properties +appear in the Editor. +. Click the *Selection Interaction* tab. The Selection Interaction tab +appears. [#Figure 74-2 ]##*_Selection Interaction Tab_* +image:selinter.gif[Selection Interaction +Tab,title="Selection Interaction Tab"] +. Complete each field on the tab. + +Use the following information to enter data in each field on the tab: + +Field + +Description + +Function Name + +The name of the EIS function that this call type (Read Object or Read +All) invokes on the EIS. + +Input Record Name + +The name passed to the JCA adapter when creating the input record. + +Input Root Element Name + +The root element name to use for the input DOM. + +Input Arguments + +The query argument name to map to the interaction field or XPath nodes +in the argument record. For example, if you are using XML records, use +this option to map input argument name to the XPath name/first-name. + +Output Arguments + +The result record field or XPath nodes to map to the correct nodes in +the record used by the descriptor’s mappings. For example, if you are +using XML records, use this option to map the output fname to +name/first-name. + +Output arguments are not required if the interaction returns an XML +result that matches the descriptor’s mappings. + +Input Result Path + +Use this option if the EIS interaction expects the interaction arguments +to be nested in the XML record. For example, specify arguments, if the +arguments were to be nested under the root element exec-find-order, then +under an arguments element. + +Output Result Path + +The name of the EIS function that this call type (Read Object or Read +All) invokes on the EIS. + +Properties + +Any properties required by your EIS platform. For example, property name +operation (from AQPlatform.QUEUE_OPERATION) and property value enqueue +(from AQPlatform.ENQUEUE). + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-Many_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-Many_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..641414733dc --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-Many_Mapping_(ELUG).adoc @@ -0,0 +1,198 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_One-to-Many_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the configurable options for an EIS one-to-many +mapping. + +[#Table 80-1]## + +Option to Configure + +Workbench + +Java + +Reference descriptors + +Foreign key pairs + +Bidirectional relationship + +Method or direct field access at the mapping level + +Read-only mappings + +Private or independent relationships + +Indirection (lazy loading) + +Container policy + +Mapping comments + +Selection interaction + +Delete all interactions + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)[EIS One-to-Many +Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)#CHDHFGAH[Configuring an +EIS Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +== Configuring Foreign Key Pairs + +In a one-to-many EIS mapping, you relate a source object attribute to a +target object attribute by specifying one or more pairs of source and +target object fields. + +In a one-to-many EIS mapping with key on source (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_One-to-Many_Mappings_with_Key_on_Source[EIS +One-to-Many Mappings with Key on Source]) using XML records, EclipseLink +puts the target XML field value into the source object’s record as a +simple value. By default, these values are not grouped, as this example +shows. + +[#Example 80-1]## *_Source Object XML Record without Grouping_* + +`+    +``+Jane+` `+    +``+3+` `+    +``+4+` + +If you specify more than one source and target XML field pair, you must +specify a grouping element, as this example shows. + +[#Example 80-2]## *_Source Object XML Record with Grouping_* + +`+    +``+Jane+` + +`+    +` `+        +``+3+` `+        +``+Project 3+` `+    +` `+    +` + +`+        +``+4+` `+        +``+Project 4+` `+    +` + +In a one-to-one EIS mapping with key on target (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_One-to-Many_Mappings_with_Key_on_Target[EIS +One-to-Many Mappings with Key on Target]) using XML records, EclipseLink +uses the source XML field value in the selection interaction to acquire +the appropriate instances of target object. + +=== How to Configure Foreign Key Pairs Using Workbench + +To specify the source and target XML field pairs for a one-to-many EIS +mapping, use this procedure: + +[arabic] +. Select the one-to-one EIS mapping in the *Navigator*. Its properties +appear in the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 80-1]##*_Foreign Keys Field on General Tab_* +image:onemeisfk.gif[Foreign Keys Field on General +Tab,title="Foreign Keys Field on General Tab"] +. Complete the Foreign Keys fields on the General tab. + +Use the following information to complete the Foreign Keys fields on the +*General* tab: + +Field + +Description + +Foreign Keys Located On Target + +Select if you are creating a one-to-many EIS mapping with key on target +(see EIS One-to-Many Mappings with Key on Target). + +Foreign Keys Located On Source + +Select if you are creating a one-to-many EIS mapping with key on source +(see EIS One-to-Many Mappings with Key on Source). + +Grouping Element + +Specify the element in which foreign key pairs are grouped in the source +object’s EIS record. If you specify only one pair of source and target +XML fields, this is optional. + +If you specify more than one pair of source and target XML fields, this +is required. + +Field Pairs + +Click Add to add a pair of source and target XML fields. Specify Field +Pair dialog box opens. Click Browse to add a foreign key for the Source +XPath and Target XPath fields. + +== Configuring Delete All Interactions + +The EclipseLink query and expression framework supports delete all +queries. If your JCA adapter provides access to an EIS Delete All +function, you can configure a delete all interaction to support +EclipseLink delete all queries. + +=== How to Configure Delete All Interactions Using Workbench + +To specify the DeleteAll interaction for an EIS one-to-many mapping, use +this procedure: + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *Delete All Interaction* tab. The Delete All Interaction tab +appears.[#Figure 80-2]## *_Delete All Interaction Tab_* +image:deletealltab.gif[Delete All Interaction +Tab,title="Delete All Interaction Tab"] +. Complete the fields on the Delete All Interaction tab. + +Use the following information to enter data in each field on the Delete +All Interaction tab: + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*Field* |*Description* +|*Function Name* |The name of the EIS function that this call type (Read +Object or Read All) invokes on the EIS. + +|*Input Record Name* |The name passed to the JCA adapter when creating +the input record. + +|*Input Root Element Name* |The root element name to use for the input +DOM. + +|*Input Arguments* |The query argument name to map to the interaction +field or XPath nodes in the argument record. For example, if you are +using XML records, use this option to map input argument `+name+` to the +XPath `+name/first-name+`. + +|*Output Arguments* |The result record field or XPath nodes to map to +the correct nodes in the record used by the descriptor’s mappings. For +example, if you are using XML records, use this option to map the output +`+fname+` to `+name/first-name+`.Output arguments are not required if +the interaction returns an XML result that matches the descriptor’s +mappings. + +|*Input Result Path* |Use this option if the EIS interaction expects the +interaction arguments to be nested in the XML record. For example, +specify `+arguments+`, if the arguments were to be nested under the root +element `+exec-find-order+`, then under an `+arguments+` element. + +|*Output Result Path* |The name of the EIS function that this call type +(Read Object or Read All) invokes on the EIS. + +|*Properties* |Any properties required by your EIS platform. For +example, property name `+operation+` (from +`+AQPlatform.QUEUE_OPERATION+`) and property value `+enqueue+` (from +`+AQPlatform.ENQUEUE+`). +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-One_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-One_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..f259f59ee35 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_One-to-One_Mapping_(ELUG).adoc @@ -0,0 +1,88 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_One-to-One_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping]. + +This table lists the configurable options for an EIS one-to-one mapping. + +[#Table 79-1]## + +Option to Configure + +Workbench + +Java + +Reference descriptors + +Foreign key pairs + +Bidirectional relationship + +Method or direct field access at the mapping level + +Read-only mappings + +Private or independent relationships + +Indirection (lazy loading) + +Mapping comments + +Selection interaction + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_One-to-One_Mapping[EIS +One-to-One Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)#CHDHFGAH[Configuring an +EIS Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +== Configuring Foreign Key Pairs + +In a one-to-one EIS mapping, you relate a source object attribute to a +target object attribute by specifying one or more pairs of source and +target object fields. + +In a one-to-one EIS mapping with key on source (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_One-to-One_Mappings_with_Key_on_Source[EIS +One-to-One Mappings with Key on Source]) using XML records, EclipseLink +puts the target XML field value into the source object’s record as a +simple value. + +In a one-to-one EIS mapping with key on target (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_One-to-One_Mappings_with_Key_on_Target[EIS +One-to-One Mappings with Key on Target]) using XML records, EclipseLink +uses the source XML field value in the selection interaction to acquire +the appropriate instance of target object. + +=== How to Configure Foreign Key Pairs Using Workbench + +To specify the source and target XML field pairs for a one-to-one EIS +mapping, use this procedure: + +[arabic] +. Select the one-to-one EIS mapping in the *Navigator*. Its properties +appear in the Editor. +. Click the *General* tab. The General tab opens. +[#Figure 79-1]##*_General Tab, Foreign Keys Field_* +image:onetoone_eis_fk.gif[General Tab, Foreign Keys +Field,title="General Tab, Foreign Keys Field"] +. Click *Add* in the Foreign Keys area to add a key pair. The Specify +Field Pair dialog box appears. [#Figure 79-2]##*_Specify Field Pair +Dialog Box_* image:spfldpr.gif[Specify Field Pair Dialog +Box,title="Specify Field Pair Dialog Box"] +. Click *Browse* to add a foreign key for the *Source XPath* and *Target +XPath* fields. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Project_(ELUG).adoc new file mode 100644 index 00000000000..6420d17f86d --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Project_(ELUG).adoc @@ -0,0 +1,168 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_an_EIS_Project_(ELUG)[Related +Topics] + +This section describes the various components that you must configure in +order to use an EIS project. + +For information on how to create EIS projects, see +link:Creating%20an%20EIS%20Project%20(ELUG)[Creating an EIS Project]. + +This table lists the configurable options for EIS projects. + +[#Table 69-1]## + +Option to Configure + +EclipseLink Workbench + +Java + +Configuring Project Save Location + +Configuring Project Classpath + +Configuring Project Comments + +Configuring Method or Direct Field Access at the Project Level + +Configuring Default Descriptor Advanced Properties + +Configuring Existence Checking at the Project Level + +Configuring Project Deployment XML Options + +Configuring Model Java Source Code Options + +Configuring EIS Data Source Platform at the Project Level + +Configuring EIS Connection Specification Options at the Project Level + +Configuring XML Parser Platform + +How to Import an XML Schema + +How to Configure XML Schema Namespace + +Configuring Cache Type and Size at the Project Level + +Configuring Cache Isolation at the Project Level + +Configuring Cache Coordination Change Propagation at the Project Level + +Configuring Cache Expiration at the Project Level + +For more information, see +link:Introduction%20to%20EIS%20Projects%20(ELUG)[Introduction to EIS +Projects]. + +== Configuring EIS Data Source Platform at the Project Level + +For each EIS project, you must specify one of the following JCA data +source platforms that you will be using: + +* Oracle AQ +* Attunity Connect +* IBM MQSeries + +This platform configuration is overridden by the session login, if +configured. + +For more information, see the following: + +* link:Configuring%20an%20EIS%20Login%20(ELUG)#Configuring_an_EIS_Data_Source_Platform_at_the_Session_Level[Configuring +an EIS Data Source Platform at the Session Level] +* link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types] + +=== How to Configure EIS Data Source Platform at the Project Level Using Workbench + +To specify the data source platform of an EIS project, use this +procedure: + +[arabic] +. Select an EIS project object in the *Navigator*. +. Select the *Connection Specifications* tab in the *Editor*. The +Connection Specifications tab appears. +. Select the *Connection* tab. The Connection tab appears. +[#Figure 69-1]##*_Connection Tab, Platform Option_* +image:eispplat.gif[Connection Tab, Platform +Option,title="Connection Tab, Platform Option"] +. Select the EIS platform for this project from the list of options. For +more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types]. + +== Configuring EIS Connection Specification Options at the Project Level + +You can configure connection information at the project level for an EIS +application. This information is stored in the `+project.xml+` file. The +EclipseLink runtime uses this information as its deployment login: +whenever your EIS application performs a persistence operation when +deployed in a Java EE application server. + +This connection configuration is overridden by the connection +information at the session level, if configured. For more information +about session level configuration, see +link:Configuring%20an%20EIS%20Login%20(ELUG)#Configuring_EIS_Connection_Specification_Options_at_the_Session_Level[Configuring +EIS Connection Specification Options at the Session Level]. + +=== How to Configure EIS Connection Specification Options at the Project Level Using Workbench + +To specify the connection information for an EIS project, use this +procedure. + +[arabic] +. Select an EIS project object in the *Navigator*. +. Select the *Connection Specifications* tab in the *Editor*. The +Connection Specifications tab appears. +. Select the *Connection* tab. The Connection tab appears. +[#Figure 69-2]##*_Connection Tab, Connection Specification Options_* +image:eispcsc.gif[Connection Tab, Connection Specification +Options,title="Connection Tab, Connection Specification Options"] +. Complete the fields on the Connection tab. + +Use this table to enter data in the following fields to configure the +connection specification options: + +[width="100%",cols="<7%,<93%",options="header",] +|=== +|*Field* |*Description* +|*Connection Specification Class* |Specify the appropriate connection +specification class for the selected *Platform*. Click *Browse* to +choose from all the classes in the EclipseLink class path. (example: if +*Platform* is `+org.eclipse.persistence.eis.aq.AQPlatform+`, use +`+org.eclipse.persistence.eis.aq.AQEISConnectionSpec+`). For more +information on platform configuration, see +link:Configuring%20an%20EIS%20Login%20(ELUG)#Configuring_an_EIS_Data_Source_Platform_at_the_Session_Level[Configuring +an EIS Data Source Platform at the Session Level]. + +|*Connection Factory URL* |Specify the appropriate connection factory +URL (as a Java EE JNDI name) for the selected *Connection Specification +Class* (example: `+java:comp/env/eis/attuntiy+`). + +|*Username* |Specify the name required to log in to the data source. + +|*Password* |Specify the password required to log in to the data source. +*Note:* When exporting Java source and deployment XML (see +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information]), Workbench writes the database password (if +applicable) using JCE encryption (when using JDK 1.4). For information +on how to specify password encryption options, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Password_Encryption[Configuring +Password Encryption]. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Transformation_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Transformation_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..bb633d50f3b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_EIS_Transformation_Mapping_(ELUG).adoc @@ -0,0 +1,46 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_EIS_Transformation_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an EIS transformation +mapping. + +[#Table 81-1]## + +Option to Configure + +Workbench + +Java + +Attribute transformer + +Field transformer associations + +Method or direct field access at the mapping level + +Read-only mappings + +Mutable mappings + +Mapping comments + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Transformation_Mapping[EIS +Transformation Mapping] +* link:Configuring%20an%20EIS%20Mapping%20(ELUG)[Configuring an EIS +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Internal_Connection_Pool_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Internal_Connection_Pool_(ELUG).adoc new file mode 100644 index 00000000000..6af2fdc9663 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Internal_Connection_Pool_(ELUG).adoc @@ -0,0 +1,372 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Configuring_an_Internal_Connection_Pool_(ELUG)[Related +Topics] + +When you are using server sessions, you can configure the *default read +connection pool* and *write connection pool*. You can also configure the +optional *named connection pools* and *sequence connection pools* you +may have created (see +link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Creation[Introduction +to the Internal Connection Pool Creation]). + +[#Table 97-1]## *_Configurable Options for Connection Pools_* + +[width="100%",cols="<60%,<20%,<20%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:#Configuring_Connection_Pool_Sizes[Connection pool sizes] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_Exclusive_Read_Connections[Exclusive read +connections] 1 |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_a_Nontransactional_Read_Login[Nontransactional read +login]1 |image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_Properties[Properties] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:#Configuring_Connection_Pool_Connection_Options[Connection pool +connection options] 2, 3 +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] +|=== + +1Read connection pools only. 2Not applicable to write connection pools. +2Available for sequence connection pools. + +== Configuring Connection Pool Sizes + +By default, if using EclipseLink internal connection pooling, the +EclipseLink write connection pool maintains a minimum of five +connections and a maximum of ten. The read connection pool maintains a +minimum and maximum of two connections. + +Connection pool size can significantly influence the concurrency of your +application and should be set to be large enough to handle your expected +application load. + +[width="100%",cols="<100%",] +|=== +|*Tip*: To maintain compatibility with JDBC drivers that do not support +many connections, the default number of connections is small. If your +JDBC driver supports it, use a larger number of connections for reading +and writing. +|=== + +The smallest value you can enter is 0. Setting the maximum number of +connections to 0 will make it impossible for EclipseLink to allocate any +connections. + +The minimum number of connections should always be less than or equal to +the maximum number of connections. + +If the maximum number of connections is in use, the next connection +request will be blocked until a connection is available. + +=== How to Configure Connection Pool Size Using Workbench + +To specify the minimum and maximum number of connections in an +EclipseLink internal connection pool, use this procedure: + +[arabic] +. Expand a server session to reveal its connection pools in the +*Navigator*. +. Select a connection pool in the *Navigator*. Its properties appear in +the Editor. +. Click the *General* tab. The General tab appears. +[#Figure 97-1]##*_General Tab, Connection Count Options_* +image:cpcount.gif[General Tab, Connection Count +Options,title="General Tab, Connection Count Options"] + +Enter the desired minimum and maximum number of connections and press +*Enter* or use the increment and decrement arrows. + +For more information, see the following: + +* link:#Configuring_Connection_Pool_Sizes[Configuring Connection Pool +Sizes] +* link:Configuring%20a%20Session%20(ELUG)#Configuring_Common_Session_Options[Configuring +Common Session Options] + +== Configuring Properties + +For all connection pools, except write connection pools, you can specify +arbitrary named values, called properties. + +Some data sources require additional, driver-specific properties not +supported in the `+ConnectionPool+` API. Add these properties to the +`+ConnectionPool+` so that EclipseLink can pass them to the driver. + +=== How to Configure Properties Using Workbench + +To specify arbitrary named value pairs that EclipseLink associates with +a `+ConnectionPool+`, use this procedure: + +[arabic] +. Expand a server session to reveal its connection pools in the +*Navigator*. +. Select a read, named, or sequence connection pool in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Properties* subtab. The Properties subtab appears. +[#Figure 97-2]##*_Login Tab, Properties Subtab_* image:cpprop.gif[Login +Tab, Properties Subtab,title="Login Tab, Properties Subtab"] +. You can add, edit, or remove properties using Add Property dialog box +that appears upon clicking Add, Edit or Remove. + +Complete the *Add Property* dialog box. + +Use the following information to add or edit a login property on the Add +Property dialog box to add or edit a login property: + +[width="100%",cols="<6%,<94%",options="header",] +|=== +|*Option* |*Description* +|*Name* |The name by which EclipseLink retrieves the property value +using the `+DatasourceLogin+` method `+getProperty+`. + +|*Value* |The value EclipseLink retrieves using the `+DatasourceLogin+` +method `+getProperty+` passing in the corresponding property name. Using +Workbench, you can set only character values which EclipseLink returns +as `+String+` objects. +|=== + +To add (or change) a new *Name*/*Value* property, click *Add* (or +*Edit*). + +To delete an existing property, select the *Name*/*Value* row and click +*Remove*. + +For more information, see link:#Configuring_Properties[Configuring +Properties] + +=== How to Configure Properties Using Java + +Using Java, you can set any `+Object+` value using the +`+DatasourceLogin+` method `+setProperty+`. To remove a property, use +the `+DatasourceLogin+` method `+removeProperty+`. + +== Configuring a Nontransactional Read Login + +When you use an external transaction controller (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]), establishing a connection requires not only the +usual connection setup overhead, but also transactional overhead. If +your application reads data only to display it and only infrequently +modifies data, you can configure an internal read connection pool to use +its own connection specification that does not use the external +transaction controller. This may improve performance by reducing the +time it takes to establish a new read connection. + +=== How to Configure Nontransactional Read Login Using Workbench + +To enable the configuration of nontransactional connection information +for an EclipseLink read connection pool, use this procedure: + +[arabic] +. Expand a server session to reveal its connection pools in the +*Navigator*. +. Select a read connection pool in the *Navigator*. Its properties +appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. +[#Figure 97-3]## *_Login Tab, Connection Subtab_* +image:cpnontrn.gif[Login Tab, Connection +Subtab,title="Login Tab, Connection Subtab"] + +To enable a nontransactional read login, select the *Use +Non-Transactional Read Login* option (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Externally_Managed_Transactional_Data_Sources[Externally +Managed Transactional Data Sources]). Continue with +link:#Configuring_Connection_Pool_Connection_Options[Configuring +Connection Pool Connection Options] to specify the connection +information. + +For more information, see +link:#Configuring_a_Nontransactional_Read_Login[Configuring a +Nontransactional Read Login]. + +=== How to Configure Nontransactional Read Login Using Java + +Use the `+getLogin+` method of your connection pool to obtain a +`+DatabaseLogin+`, and then use the following `+DatabaseLogin+` methods +to configure the nontransactional read login options: + +* `+useExternalTransactionController+` +* `+setDriverClass+` +* `+setDriverClassName+` +* `+setDriverURLHeader+` + +== Configuring Connection Pool Connection Options + +By default, connection pools use the login configuration specified for +their session (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Database_Login_Connection_Options[Configuring +Database Login Connection Options] and +link:Configuring%20an%20EIS%20Login%20(ELUG)#Configuring_EIS_Connection_Specification_Options_at_the_Session_Level[Configuring +EIS Connection Specification Options at the Session Level]). + +For read, named, and sequence connection pools, you can override the +session login configuration on a per-connection pool basis. + +To configure login configuration for a read connection pool, you must +first enable it for link:#Configuring_a_Nontransactional_Read_Login[a +nontransactional read login]). + +=== How to Configure Connection Pool Connection Options Using Workbench + +To configure connection information for an EclipseLink read, named, or +sequence connection pool, use this procedure: + +[arabic] +. Expand a server session to reveal its connection pools in the +*Navigator*. +. Select a read, named, or sequence connection pool in the *Navigator*. +Its properties appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. +[#Figure 97-4]##*_Login Tab, Connection Subtab, Relational Session +Connection Pool Options_* image:cpcon.gif[Login Tab, Connection Subtab, +Relational Session Connection Pool +Options,title="Login Tab, Connection Subtab, Relational Session Connection Pool Options"] +[#Figure 97-5]##*** Login Tab, Connection Subtab, EIS Session Connection +Pool Options*** image:cpconeis.gif[Login Tab, Connection Subtab, EIS +Session Connection Pool +Options,title="Login Tab, Connection Subtab, EIS Session Connection Pool Options"] +. Ensure the *Use Non-Transaction Read Login* option is selected. +. Complete each field on the Connection tab. + +Use the following information to complete fields on the Connection +subtab: + +Field + +Description + +Database Driver1 + +Specify the appropriate database driver: + +Driver Manager: Specify this option to configure the driver class and +URL used to connect to the database. In this case, you must configure +the Driver Class and Driver URL fields. + +J2EE Datasource: Specify this option to use a Java EE data source +already configured on your target application server. In this case, you +must configure the Datasource Name field. + +Note: If you select J2EE Datasource, you must use external connection +pooling. You cannot use internal connection pools with this Database +Driver option (for more information, see Configuring External Connection +Pooling). + +Driver Class1 + +Configure this field when Database Driver is set to Driver Manager. +Select from the menu of options. This menu includes all JDBC drivers in +the EclipseLink application classpath. + +URL1 + +Configure this field when Database Driver is set to Driver Manager. +Select from the menu of options relevant to the selected Driver Class +and edit the URL to suit your data source. + +Datasource Name1 + +Configure this field when Database Driver is set to J2EE Datasource. +Specify any valid JNDI name that identifies the Java EE data source +preconfigured on your target application server (For example: +jdbc/EmployeeDB). By convention, all such names should resolve to the +JDBC subcontext (relative to the standard java:comp/env naming context +that is the root of all provided resource factories). + +Connection Specification Class2 + +Specify the appropriate connection specification class for the selected +Platform. Click Browse to choose from all the classes in the EclipseLink +classpath. (For example: if Platform is +org.eclipse.persistence.eis.aq.AQPlatform, use +org.eclipse.persistence.eis.aq.AQEISConnectionSpec). For more +information on platform configuration, see Configuring an EIS Data +Source Platform at the Session Level. + +Connection Factory URL2 + +Specify the appropriate connection factory URL for the selected +Connection Specification Class (For example: +jdbc:oracle:thin@:localhost:1521:orcl). + +1For sessions that contain a `+DatabaseLogin+`. 2For sessions that +contain an `+EISLogin+`. + +For more information, see +link:#Configuring_Connection_Pool_Connection_Options[Configuring +Connection Pool Connection Options] + +== Configuring Exclusive Read Connections + +An exclusive connection is one that EclipseLink allocates specifically +to a given session and one that is never used by any other session. + +Allowing concurrent reads on the same connection reduces the number of +read connections required and reduces the risk of having to wait for an +available connection. However, many JDBC drivers do not support +concurrent reads. + +If you are using +link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools], you can configure EclipseLink to acquire an exclusive +connection from the read connection pool. + +By default, EclipseLink acquires exclusive read connections. + +If you are using external connection pools, read connections are always +exclusive. + +=== How to Configure Exclusive Read Connections Using Workbench + +To configure an EclipseLink read connection pool to allocate exclusive +connections, use this procedure: + +[arabic] +. Expand a server session to reveal its connection pools in the +*Navigator*. +. Select a read connection pool in the *Navigator*. Its properties +appear in the Editor. +. Click the *Login* tab. The Login tab appears. +. Click the *Connection* subtab. The Connection subtab appears. +[#Figure 97-6]##*_Login Tab, Connection Subtab, Exclusive Connections +Option_* image:exclus.gif[Login Tab, Connection Subtab, Exclusive +Connections +Option,title="Login Tab, Connection Subtab, Exclusive Connections Option"] + +Select the *Exclusive Connections* option to configure EclipseLink to +acquire an exclusive connection from the read connection pool. + +Deselect the *Exclusive Connections* option to configure EclipseLink to +share read connections and allow concurrent reads. Before selecting this +option, ensure that your JDBC driver supports concurrent reads. + +For more information, see +link:#Configuring_Exclusive_Read_Connections[Configuring Exclusive Read +Connections] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Array_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Array_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..102ffddf0ef --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Array_Mapping_(ELUG).adoc @@ -0,0 +1,84 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Array_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +[width="100%",cols="<100%",] +|=== +|*Note:* To map a collection of aggregate structures, use an +object-relational data type object array mapping (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Object_Array_Mapping[Object-Relational +Data Type Object Array Mapping]). To store information in a separate +table from the parent structure’s table, use an object-relational data +type nested table mapping (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Nested_Table_Mapping[Object-Relational +Data Type Nested Table Mapping]). +|=== + +This table lists the configurable options for an object-relational data +type array mapping. + +[#Table 48-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Attribute_Name[Configuring +Attribute Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Field_Name[Configuring +Field Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Structure_Name[Configuring +Structure Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Configuring +a Serialized Object Converter] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Configuring +an Object Type Converter] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Array_Mapping[Object-Relational +Data Type Array Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] +* link:Configuring%20a%20Mapping_(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..ce003ef7bff --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc @@ -0,0 +1,95 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Descriptor_(ELUG)[Related +Topics] + +For information on how to create object-relational data type +descriptors, see +link:Creating%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)[Creating +an Object-Relational Data Type Descriptor]. + +This table lists the configurable options for an object-relational data +type descriptor. + +[#Table 31-1]## + +Option to Configure + +EclipseLink Workbench + +Java + +Field ordering + +Primary keys + +Read-only descriptors + +Unit of work conforming + +Query keys + +Cache expiration + +Amendment methods + +Reading subclasses on queries + +Inheritance for a child class descriptor + +Inheritance for a parent class descriptor + +Inheritance expressions for a parent class descriptor + +Inherited attribute mapping in a subclass + +Cache type and size + +Domain object method as an event handler + +Descriptor event listener as an event handler + +Locking policy + +Copy policy + +Instantiation policy + +Wrapper policy + +History policy + +Returning policy + +For more information, see +link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Introduction +to Relational Descriptors]. + +== Configuring Field Ordering + +If your object-relational data type data source driver uses JDBC indexed +arrays, you can specify the order in which EclipseLink persists object +attributes to define the field index. + +=== How to Configure Field Ordering Using Java + +Use `+ObjectRelationalDescriptor+` method `+addFieldOrdering+` to +specify the field ordering. This example shows how to specify the order +of the object-relational data type database fields `+OBJECT_ID+`, +`+F_NAME+`, and `+L_NAME+` for the `+Employee+` descriptor. + +[#Example 31-1]## *_Field Ordering_* + +[source,java] +---- + descriptor.addFieldOrdering("ID"); + descriptor.addFieldOrdering("F_NAME"); + descriptor.addFieldOrdering("L_NAME"); +---- + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..72ae43d663b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Mapping_(ELUG).adoc @@ -0,0 +1,297 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the types of object-relational data type mappings that +you can configure and provides a cross-reference to the type-specific +chapter that lists the configurable options supported by that type. + +[#Table 50-1]## + +If you are creating… + +See… + +Object-relational data type structure mapping + +Configuring an Object-Relational Data Type Structure Mapping + +Object-relational data type reference mapping + +Configuring an Object-Relational Data Type Reference Mapping + +Object-relational data type array mapping + +Configuring an Object-Relational Data Type Array Mapping + +Object-relational data type object array mapping + +Configuring an Object-Relational Data Type Object Array Mapping + +Object-relational data type nested table mapping + +Configuring an Object-Relational Data Type Nested Table Mapping + +For more information, see the following: + +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)[Introduction +to Relational Mappings] + +== Configuring Common Object-Relational Data Type Mapping Options + +Thist able lists the configurable options shared by two or more +object-relational data type mapping types. In addition to the +configurable options described here, you must also configure the options +described for the specific object-relational data type mapping types +(see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Mapping_Types[Object-Relational +Data Type Mapping Types]), as shown in the following table. + +[#Table 50-2]## + +Option to Configure + +Workbench + +Java + +Reference class + +Attribute name + +Field name + +Structure name + +Read-only + +Method or direct field access + +Indirection (lazy loading) + +Container policy + +== Configuring Reference Class + +When mapping an attribute that involves a relationship to another class, +you must specify the reference class–the Java class to which the mapped +attribute refers. + +This table summarizes which object-relational data type mappings support +this option. + +[#Table 50-3]## + +Mapping + +Using the Workbench + +Using Java + +Object-relational data type structure mapping + +Object-relational data type reference mapping + +Object-relational data type array mapping + +Object-relational data type object array mapping + +Object-relational data type nested table mapping + +=== How to Configure Reference Class Using Java + +Use `+org.eclipse.persistence.mappings.ForeignReferenceMapping+` method +`+setReferenceClass+` to specify the target class of the attribute being +mapped. + +Tihs example shows how to use this method with a `+ReferenceMapping+` +that maps the `+manager+` attribute of the `+Employee+` class. + +[#Example 50-1]## *_Configuring Reference Class in Java_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + ReferenceMapping managerMapping = new ReferenceMapping(); + managerMapping.setReferenceClass("Employee.class"); // set reference class + managerMapping.setAttributeName("manager"); + + // add this mapping to descriptor + descriptor.addMapping (managerMapping); + } +---- + +For more information, see the _EclipseLink API Reference_. + +== Configuring Attribute Name + +All object-relational data type mappings map an attribute in a Java +object to field in the database. The attribute name is the name of the +attribute being mapped. The name is as specified in the reference class +(see link:#Configuring_Reference_Class[Configuring Reference Class]). + +This table summarizes which object-relational data type mappings support +this option. + +[#Table 50-4]## + +Mapping + +Using the Workbench + +Using Java + +Object-relational data type structure mapping + +Object-relational data type reference mapping + +Object-relational data type array mapping + +Object-relational data type object array mapping + +Object-relational data type nested table mapping + +=== How to Configure Attribute Name Using Java + +Use `+org.eclipse.persistence.mappings.DatabaseMapping+` method +`+setAttributeName+` to specify the name of the attribute being mapped. + +This table shows how to use this method with a `+ReferenceMapping+` that +maps the `+manager+` attribute of the `+Employee+` class. + +[#Example 50-2]## *_Configuring Attribute Name in Java_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + ReferenceMapping managerMapping = new new ReferenceMapping(); + managerMapping.setReferenceClass("Employee.class"); + managerMapping.setAttributeName("manager"); // set attribute name + + '''// add this mapping to descriptor''' + descriptor.addMapping (managerMapping); + } +---- + +For more information, see the _EclipseLink API Reference_. + +== Configuring Field Name + +All object-relational data type mappings require the name of database +field to which their specified attribute is mapped. This field name can +be the column name of a database table or the name of a field in an +object type created on the database. + +This table summarizes which object-relational data type mappings support +this option. + +[#Table 50-5]## + +Mapping + +Using the Workbench + +Using Java + +Object-relational data type structure mapping + +Object-relational data type reference mapping + +Object-relational data type array mapping + +Object-relational data type object array mapping + +Object-relational data type nested table mapping + +=== How to Configure Field Name Using Java + +Use the object-relational data type mapping method `+setFieldName+` to +specify the database field to which the attribute is mapped. + +This example shows how to use this method with an `+ObjectArrayMapping+` +that maps the `+Employee+` class attribute `+phone+` to database field +name `+PHONE_NUMBER+`. + +[#Example 50-3]## *_Configuring Field Name in Java_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + ObjectArrayMapping phonesMapping = new ObjectArrayMapping(); + phonesMapping.setReferenceClass("Employee.class"); + phonesMapping.setAttributeName("phone"); + phonesMapping.setFieldName("PHONE_NUMBER"); '''// set field name''' + + '''// add this mapping to descriptor''' + descriptor.addMapping (phonesMapping); + } +---- + +For more information, see the _EclipseLink API Reference_. + +== Configuring Structure Name + +Certain object-relational data type mappings require the specification +of the data type or structure name of the field being mapped. The +structure name is the name of the array or table type that defines the +field. + +This table summarizes which object-relational data type mappings support +this option. + +[#Table 50-6]## + +Mapping + +Using the Workbench + +Using Java + +Object-relational data type structure mapping + +Object-relational data type reference mapping + +Object-relational data type array mapping + +Object-relational data type object array mapping + +Object-relational data type nested table mapping + +=== How to Configure Structure Name Using Java + +Use the object-relational data type mapping method `+setStructureName+` +to specify the structure of the attribute being mapped. + +This example shows how to use this method with an `+ObjectArrayMapping+` +that maps the `+Employee+` class attribute `+phones+` to database field +name `+PHONE_NUMBERS+` of type `+PHONE_ARRAY_TYPE+`. + +[#Example 50-4]## *_Configuring Structure Name in Java_* + +[source,java] +---- + public void customize(ClassDescriptor descriptor) { + ObjectArrayMapping phonesMapping = new ObjectArrayMapping(); + phonesMapping.setReferenceClass("Employee.class"); + phonesMapping.setAttributeName("phones"); + phonesMapping.setFieldName("PHONE_NUMBERS"); + phonesMapping.setStructureName("PHONE_ARRAY_TYPE"); // set structure name + + // add this mapping to descriptor + descriptor.addMapping (phonesMapping); + } +---- + +For more information, see the _EclipseLink API Reference_. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Nested_Table_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Nested_Table_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..a639287ce19 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Nested_Table_Mapping_(ELUG).adoc @@ -0,0 +1,76 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Nested_Table_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +[width="100%",cols="<100%",] +|=== +|*Note:* For an equivalent mapping for basic or other structured data +types, use object-relational data type array (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Array_Mapping[Object-Relational +Data Type Array Mapping]) or object array (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Object_Array_Mapping[Object-Relational +Data Type Object Array Mapping]) mappings. +|=== + +This table lists the configurable options for an object-relational data +type nested table mapping. + +[#Table 51-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Reference_Class[Configuring +Reference Class] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Attribute_Name[Configuring +Attribute Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Field_Name[Configuring +Field Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Structure_Name[Configuring +Structure Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Configuring +Indirection (Lazy Loading)] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Nested_Table_Mapping[Object-Relational +Data Type Nested Table Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Object_Array_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Object_Array_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..bf7362f17b6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Object_Array_Mapping_(ELUG).adoc @@ -0,0 +1,61 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Object_Array_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an object-relational data +type object array mapping. + +[#Table 49-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Reference_Class[Configuring +Reference Class] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Attribute_Name[Configuring +Attribute Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Field_Name[Configuring +Field Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Structure_Name[Configuring +Structure Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)[Object-Relational +Data Type Object Array Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Reference_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Reference_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..740f24737ff --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Reference_Mapping_(ELUG).adoc @@ -0,0 +1,70 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Reference_Mapping_(ELUG)[Related +Topics] + +This section describes the various components that you must configure in +order to use an object-relational data type reference mapping. + +For information on how to configure EclipseLink mappings options common +to two or more mapping types, see +link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an object-relational data +type reference mapping. + +[#Table 47-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Reference_Class[Configuring +Reference Class] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Attribute_Name[Configuring +Attribute Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Field_Name[Configuring +Field Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Private_or_Independent_Relationships[Configuring +Private or Independent Relationships] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Configuring +Indirection (Lazy Loading)] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Reference_Mapping[Object-Relational +Data Type Reference Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] +* link:Configuring%20a%20Mapping_(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Structure_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Structure_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..4fcec4ed4fe --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_Object-Relational_Data_Type_Structure_Mapping_(ELUG).adoc @@ -0,0 +1,53 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_Object-Relational_Data_Type_Structure_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an object-relational data +type structure mapping. + +[#Table 46-1]## + +[width="100%",cols="<70%,<16%,<14%",options="header",] +|=== +|*Option to Configure* |*Workbench* |*Java* +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Reference_Class[Configuring +Reference Class] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Attribute_Name[Configuring +Attribute Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)#Configuring_Field_Name[Configuring +Field Name] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see the following: + +* link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Structure_Mapping[Object-Relational +Data Type Structure Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] +* link:Configuring%20a%20Mapping_(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Configuring_an_RMI_Coordinated_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_RMI_Coordinated_Cache_(ELUG).adoc new file mode 100644 index 00000000000..a7b598ec63f --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Configuring_an_RMI_Coordinated_Cache_(ELUG).adoc @@ -0,0 +1,38 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_RMI_Coordinated_Cache_(ELUG)[Related +Topics] + +[#Table 101-1]## *_Configurable Options for an RMI Coordinated Cache_* + +Option to Configure + +EclipseLink Workbench + +Java + +Cache coordination change propagation at the descriptor level + +Synchronous change propagation mode + +Service channel + +Multicast group address + +Multicast port + +Naming service type + +Announcement delay + +Connection handling + +Context properties + +Packet time-to-live + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_EclipseLink_Files_for_Deployment_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_EclipseLink_Files_for_Deployment_(ELUG).adoc new file mode 100644 index 00000000000..79d2d545816 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_EclipseLink_Files_for_Deployment_(ELUG).adoc @@ -0,0 +1,325 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Creating_EclipseLink_Files_for_Deployment_(ELUG)[Related +Topics] + +This section includes EclipseLink information that you need when +creating deployment files for various types of applications. + +For more information on packaging and deployment, see the following: + +* link:#Introduction_to_the_EclipseLink_Deployment_File_Creation[Introduction +to the EclipseLink Deployment File Creation] +* link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server] +* link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging a +EclipseLink Application] +* link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying a +EclipseLink Application] +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Packaging +and Deploying EclipseLink JPA Applications] +* link:EclipseLink_UserGuide_Creating_Deployment_Files_for_EclipseLink_Database_Web_Services_%28ELUG%29[Creating +Deployment Files for EclipseLink Web Services] + +== Introduction to the EclipseLink Deployment File Creation + +Depending on the type of application you are deploying, you may need to +create any of the following deployment files: + +* link:#project.xml_File[project.xml File] +* link:#sessions.xml_File[sessions.xml File] + +Workbench provides the ability to +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[create +deployment files from a Workbench project] "`wikilink`"). After you +build a project, you have two options to create the deployment files: + +* Create XML deployment files that require no compiling. +* Create Java source files, which you compile and deploy outside of +Workbench. + +We recommend XML deployment because XML files are easier to deploy and +troubleshoot than compiled Java files. This approach gives you a very +flexible configuration that enables you to make changes safely and +easily. XML deployment files do not require third-party applications or +compilers to deploy successfully. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using JPA, you can use annotations to specify most +of what you formerly specified in deployment descriptors. Use deployment +descriptors to override annotations or specify options not supported by +annotations. +|=== + +=== project.xml File + +The `+project.xml+` file is the core of your application. It contains +the descriptors and mappings you define and also includes any named +queries or finders associated with your project. + +==== XSD File Format + +The `+project.xml+` file XSD is `+persistence_1_0.xsd+` and it is +located in the __`+\xsds+` directory. + +See link:EclipseLink_XSDs[EclipseLink/XSDs] for more information. + +==== POJO Applications and Project Metadata + +For a POJO application, you define your project metadata in a +`+project.xml+` file. + +The `+project.xml+` file provides a simple and flexible way to +configure, modify, and troubleshoot the project metadata. Because of +these attributes, the `+project.xml+` file is the preferred way to +configure an EclipseLink project.Workbench provides a graphical tool to +build and edit the `+project.xml+` file. For information on creating +projects with Workbench, see +link:#Creating_the_project.xml_File_with_Workbench[Creating the +project.xml File with Workbench]. + +==== JPA Applications and Project Metadata + +For a JPA application, you can express project metadata using JPA +annotations, `+persistence.xml+`, `+orm.xml+`, and EclipseLink JPA +annotation and `+persistence.xml+` property extensions. The EclipseLink +JPA persistence provider interprets all these sources of metadata to +create an in-memory EclipseLink session and project at run time. + +Using EclipseLink JPA, you also have the option of specifying your +metadata using EclipseLink `+sessions.xml+` and `+project.xml+` while +accessing your persistent classes using JPA and an `+EntityManager+`. +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]. + +==== Creating the project.xml File with Workbench + +Because you must synchronize the `+project.xml+` file with the classes +and data source associated with your application, we recommend that you +not modify this file manually. Workbench ensures proper synchronization, +and is the best way to make changes to the project. Simply modify the +project in Workbench and redeploy the `+project.xml+` file. Using this +option reduces development time by eliminating the need to regenerate +and recompile Java code each time the project changes. + +See +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information] for detailed information on exporting the +deployment XML information. + +[width="100%",cols="<100%",] +|=== +|*Note*: You can name this file with a name other than `+project.xml+`; +however, for clarity, this discussion assumes that the file has not been +renamed. +|=== + +==== Creating project.xml Programatically + +Optionally, you can use the `+DeploymentXMLGenerator+` API to +programatically generate the `+project.xml+` file in either of the +following ways: + +* From an application, instantiate the `+DeploymentXMLGenerator+` and +your java source. Call the following +method:`+generate (+`_`++`_`+,+` +_`++`_`+)+` +* From the command line, use the following: + +`+java -classpath eclipselink.jar;eclispelinkmw.jar;+` +`+org.eclipse.persistence.tools.workbench.mappings.DeploymentXMLGenerator +`_`++`_`+ +`_`++`_ + +Before you use either method, ensure that your classpath includes the +__`+\jlib\eclipselink.jar+` and +__`+\utils\workbench\jlib\eclipselinkmw.jar+` files. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using EJB 3.0, you can use annotations to specify +most of what you formerly specified in the `+project.xml+` file. To +override annotations or specify options not supported by annotations, +you can still provide a `+project.xml+` file in your EJB 3.0 +application. +|=== + +=== sessions.xml File + +Each EclipseLink project belongs to an EclipseLink _session_. A session +is the facade through which an application accesses EclipseLink +functionality (for more information on sessions, see +link:EclipseLink_UserGuide_Using_EclipseLink_Sessions_(ELUG)[EclipseLink +Sessions]). + +==== XSD File Format + +The `+sessions.xml+` file XSD is +`+eclipse_persistence_sessions_1_0.xsd+` and it is located in the +__`+\xsds+` directory as well as on the web at +http://www.eclipse.org/eclipselink/xsds/eclipse_persistence_sessions_1_0.xsd. + +When you use the XSD formatted `+sessions.xml+` file, the EclipseLink +run time separates `+sessions.xml+` file validation from session +instantiation. Separating XML file formatting problems from Session +Manager session instantiation problems simplifies troubleshooting. +Exceptions thrown during validation clearly indicate that the failure is +due to an invalid `+sessions.xml+` file, as the following illustrates. + +[#Example 8-1]## *_Enhanced Validation Exceptions_* + +`+Exception [ECLIPSELINK-9010] (EclipseLink): org.eclipselink.exceptions.SessionLoaderException+` +`+Exception Description: A End tag does not match start tag 'session'. was thrown while parsing the XML file against the XML schema.+` +`+Internal Exception: oracle.xml.parser.v2.XMLParseException: End tag does not match start tag 'session'.+` + +==== POJO Applications and Session Metadata + +For a POJO application, you define your sessions in a `+sessions.xml+` +file. + +The `+sessions.xml+` file provides a simple and flexible way to +configure, modify, and troubleshoot the application sessions. Because of +these attributes, the `+sessions.xml+` file is the preferred way to +configure an EclipseLink session.EclipseLink provides graphical toosl to +build and edit the `+sessions.xml+` file. For information see +link:Creating%20a%20Session%20(ELUG)[Creating a Session]. + +==== JPA Applications and Session Metadata + +For a JPA application, you can express session metadata using JPA +annotations, `+persistence.xml+`, `+orm.xml+`, and EclipseLink JPA +annotation and `+persistence.xml+` property extensions. The EclipseLink +JPA persistence provider interprets all these sources of metadata to +create an in-memory EclipseLink session and project at run time. + +Using EclipseLink JPA, you also have the option of specifying your +metadata using EclipseLink `+sessions.xml+` and `+project.xml+` while +accessing your persistent classes using JPA and an `+EntityManager+`. +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]. + +== Creating Deployment Files for Java Applications + +In a Java application, EclipseLink does not use a Java EE container for +deployment. Instead, it relies on EclipseLink mechanisms to provide +functionality and persistence. The key elements of this type of +application are the lack of a Java EE container and the fact that you +deploy the application by placing the application JAR file on the +classpath. + +Java applications require the following deployment files: + +* link:#project.xml_File[project.xml File] +* link:#sessions.xml_File[sessions.xml File] + +== Creating Deployment Files for JavaServer Pages and Servlet Applications + +Many designers build EclipseLink applications that use JavaServer Pages +(JSP) and Java servlets. This type of design generally supports +Web-based applications. + +JSP and servlet applications require the following deployment files: + +* link:#project.xml_File[project.xml File] +* link:#sessions.xml_File[sessions.xml File] + +== Creating Deployment Files for Session Bean Applications + +Session beans generally model a process, operation, or service and as +such, are not persistent. You can build EclipseLink applications that +wrap interaction with EclipseLink in session beans. Session beans +execute all EclipseLink-related operations on behalf of the client. + +This type of design uses JTS and externally managed transactions, but +does not incur the overhead associated with persistence applications. +Session bean applications also scale and deploy easily. + +This section describes the following: + +* link:#How_to_Create_Deployment_Files_for_EJB_3.0_Session_Bean_Applications[How +to Create Deployment Files for EJB 3.0 Session Bean Applications] + +=== How to Create Deployment Files for EJB 3.0 Session Bean Applications + +We recommend using JPA annotations and persistence unit properties, or a +special-case `+eclipselink.sessions-xml+` persistence unit property (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#EclipseLink_JPA_Persistence_Unit_Properties_for_Database,_Session,_and_Application_Server[EclipseLink +JPA Persistence Unit Properties for Database, Session, and +Application Server]) in your EJB 3.0 session bean application. + +You may also choose to use the link:#project.xml_File[project.xml File] +and link:#sessions.xml_File[sessions.xml File]. + +For more information, see the following: + +* link:Introduction_to_Java_Persistence_API_(ELUG)#Java_Persistence_API_Overview[Java +Persistence API Overview] +* link:Introduction_to_EclipseLink_JPA_(ELUG)#EclipseLink_JPA_Overview[EclipseLink +JPA Overview] +* link:Developing_Applications_Using_EclipseLink_JPA_(ELUG)#Application_Development_with_EclipseLink_JPA[Application +Development with EclipseLink JPA)] + +== Creating Deployment Files for JPA Applications + +See +link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Packaging +and Deploying EclipseLink JPA Applications] for information on how to +create deployment files for your JPA application. + +== Configuring the weblogic-ejb-jar.xml File for WebLogic Server + +Before you deploy a EclipseLink application to Oracle WebLogic Server, +you must modify the `+weblogic-ejb-jar.xml+` file. + +Avoid the `+weblogic-ejb-jar.xml+` tags that EclipseLink either does not +support or does not require (see +link:#What_You_May_Need_to_Know_About_Unsupported_weblogic-ejb-jar.xml_File_Tags[What +You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags]). + +=== What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags + +The `+weblogic-ejb-jar.xml+` file includes the following tags that +EclipseLink either does not support or does not require: + +* `+concurrency-strategy+`: This tag specifies how Oracle WebLogic +Server manages concurrent users for a given bean. Because EclipseLink +manages concurrent access internally, it does not require this tag. For +more information about the EclipseLink concurrency strategy, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. +* `+db-is-shared+`: Because EclipseLink does not make any assumptions +about the exclusivity of database access, EclipseLink does not require +this tag. EclipseLink addresses multiuser access issues through various +locking and refreshing policies. +* `+delay-updates-until-end-of-tx+`: EclipseLink always delays updates +until the end of a transaction, and does not require this tag. +* `+finders-load-bean+`: EclipseLink always loads the bean upon +execution of the finder, and does not require this tag. +* `+pool+`: EclipseLink does not use a pooling strategy for entity +beans. This avoids object-identity problems that can occur due to +pooling. +* `+lifecycle+`: This element manages beans that follow a pooling +strategy. Because EclipseLink does not use a pooling strategy, +EclipseLink ignores this tag. +* `+is-modified-method-name+`: EclipseLink does not require a bean +developer-defined method to detect changes in the object state. +* `+isolation-level+`: Because isolation level settings for the cache or +database transactions are specified in the EclipseLink project, +EclipseLink ignores this tag. +* `+cache+`: Because you define EclipseLink cache properties in +Workbench, this tag is unnecessary. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_a_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..8e0738bf941 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Descriptor_(ELUG).adoc @@ -0,0 +1,62 @@ +*TOC* Special:Whatlinkshere_Creating_a_Descriptor_(ELUG)[Related Topics] + +This section describes how to create EclipseLink descriptors. For +information on creating different types of descriptors, see: + +* link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating a +Relational Descriptor] +* link:Creating%20an%20EIS%20Descriptor%20(ELUG)[Creating an EIS +Descriptor] +* link:Creating%20an%20XML%20Descriptor%20(ELUG)[Creating an XML +Descriptor] + +After you create a descriptor, you must +link:Configuring%20a%20Descriptor%20(ELUG)[configure its various +options] and use it to define mappings. + +For complete information on the various types of mapping that +EclipseLink supports, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] and +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +For complete information on the various types of descriptor that +EclipseLink supports, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Types[Descriptor +Types]. + +== Validating Descriptors + +You can validate descriptors in the following ways: + +* Run the project in a test environment and watch for and interpret any +exceptions that occur. +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Integrity_Checker[Run +the EclipseLink integrity checker]. +* link:Creating%20a%20Project%20(ELUG)#How_to_Generate_the_Project_Status_Report[Review +the project status report]. + +== Generating Java Code for Descriptors + +Typically, you capture descriptor configuration in the `+project.xml+` +file and the EclipseLink runtime reads this information, and then +creates and configures all necessary descriptor objects. + +Alternatively, for relational projects only, you can export an +EclipseLink project as a Java class +(`+org.eclipse.persistence.sessions.Project+`) that contains all +descriptor configuration in Java. This lets you use Workbench to quickly +create and configure descriptors, and then, manually code features that +Workbench does not support. This gives you the best of both Workbench +and Java access to your descriptors. After configuring your Java project +class, compile it and include it in your application’s JAR file. + +For more information, see +link:Creating%20a%20Relational%20Project%20(ELUG)#How_to_Export_Project_Java_Source_Using_Workbench[How +to Export Project Java Source Using Workbench]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_a_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..f8ad727db45 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Mapping_(ELUG).adoc @@ -0,0 +1,238 @@ +*TOC* Special:Whatlinkshere_Creating_a_Mapping_(ELUG)[Related Topics] + +You can create a database mapping using the Workbench or Java code. We +recommend using the Workbench to create and manage your mappings. + +For more information on creating mappings in Java, see +link:Introduction_to_EclipseLink_JPA_(ELUG)[EclipseLink API Reference]. + +For complete information on the various types of mapping that +EclipseLink supports, see +link:Introduction%20to%20Mappings%20(ELUG)#Mapping_Types[Mapping Types]. + +During development, you can create mappings individually (see +link:#Creating_Mappings_Manually_During_Development[Creating Mappings +Manually During Development]) or you can allow Workbench to +automatically map all attributes (see +link:#Creating_Mappings_Automatically_During_Development[Creating +Mappings Automatically During Development]). + +For JPA projects, you can create mappings using JPA annotations (see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Object_Relational_Mapping_with_EclipseLink_JPA[Object +Relational Mapping with EclipseLink JPA]). JPA lets you create mappings +automatically at run time. + +After you create a mapping, you must configure its various options (see +link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]). + +== Creating Mappings Manually During Development + +You can manually create a mapping from each persistent field of a class +to a data source using Workbench or Java code. We recommend that you use +Workbench. + +=== How to Create Mappings Manually During Development Using Workbench + +To manually create a mapping using Workbench, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. On the *Descriptor Info* tab, associate the descriptor with its data +source: +[arabic] +.. For a relational project, in the *Editor*, select the table for this +descriptor from the *Associated Table* menu. The Workbench populates +this menu with tables from the database login you associated with your +project. For more information, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]. +.. For an XML project, in the *Editor*, select the appropriate schema +context for this descriptor by clicking on the *Browse* button next to +the *Schema Context* field. The Workbench displays the schema context +from the XML schema you associated with your project. For more +information, see link:Using%20Workbench%20(ELUG)#Using_XML_Schemas[Using +XML Schemas]. +. In the *Navigator*, expand the descriptor to display its attributes. +. Select an attribute and do one of the following: +[arabic] +.. Click the appropriate mapping on the toolbar (see +link:Using%20Workbench%20(ELUG)#Using_Context_Toolbar[Using Context +Toolbar]). +.. Right-click the attribute and select *Map As >* to choose a specific +mapping type from the context menu (see +link:Using%20Workbench%20(ELUG)#Using_Context_Menus[Using Context +Menus]). + +Continue with link:Configuring%20a%20Mapping%20(ELUG)[Configuring a +Mapping] to complete the mapping. + +*See Also* + +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Mapping[Configuring +a Mapping] + +link:#Creating_Mappings_Automatically_During_Development[Creating +Mappings Automatically During Development] + +=== How to Create Mappings During Development Using Java + +You create mappings using the constructor of the particular mapping +type, as the following examples show: + +[#Example 116-1]## *_Creating Relational One-to-One Mapping_* + +`+ org.eclipse.persistence.mappings.OneToOneMapping oom = new OneToOneMappiing();+` + +[#Example 116-2]## *_Creating Relational Direct Collection Mapping_* + +`+org.eclipse.persistence.mappings.DirectCollectionMapping dcm =new DirectCollectionMappiing();+` + +[#Example 116-3]## *_Creating Object-Relational Data Type Structure +Mapping_* + +`+org.eclipse.persistence.mappings.structures.StructureMapping sm = new StructureMappiing();+` + +[#Example 116-4]## *_Creating Object-Relational Data Type Array +Mapping_* + +`+org.eclipse.persistence.mappings.structures.ArrayMapping am = new ArrayMappiing();+` + +== Creating Mappings Automatically During Development + +For relational database projects, the Workbench can automatically map +class attributes to a similarly named database field. For example, these +tools can map the attribute `+province+` to the database field `+PROV+`, +the attribute `+street+` to the field `+ST+`, and the attribute +`+postalCode+` to the field `+POSTAL_CODE+`. + +The Automap function creates mappings only for unmapped attributes–it +does not change previously defined mappings. + +You can automatically map classes for an entire project or for specific +classes or descriptors. + +[width="100%",cols="<100%",] +|=== +|*Note*: Associating a descriptor with a database table (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]) before using the Automap function can aid the +automapper if it cannot guess the correct table for a class. +|=== + +=== How to Create Mappings Automatically During Development Using Workbench + +To automatically map _all_ the descriptors in a project, right-click the +project icon in the *Navigator* window and choose *Automap* from the +context menu or choose *Selected* *>* *Automap* from the menu. + +To automatically map a _specific_ descriptor or attribute, choose the +descriptor or attributes and right-click, and then select *Automap* from +the context menu or choose *Selected* *>* *Automap* from the menu. + +*See Also* + +link:#Creating_Mappings_Manually_During_Development[Creating Mappings +Manually During Development] + +link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +== Creating Mappings to Oracle LOB Database Objects + +In an Oracle Database, large amounts of binary or character data is +stored as a `+BLOB+` (binary large object) or `+CLOB+` (character large +object), respectively. Depending on the size of the `+LOB+` value and +your Oracle Database database version, the value may be stored either +inside or outside of the table, as follows: + +* With Oracle8i version 8.1.6 and earlier, `+LOB+` values less than 4K +are stored inline; values more than 4K are stored outside the table. +* With Oracle8i version 8.1.7 and later, `+LOB+` values less than 5.9K +are stored inline; values more than 5.9K are stored outside the table. + +A client application (such as EclipseLink) must use a LOB locator to +write a LOB value, if the value is stored outside of the database. The +Oracle JDBC OCI driver and server driver handle these LOB (large object) +values differently than the Oracle JDBC thin driver. + +=== How to Create Mappings to Oracle LOB Database Objects Using the Oracle JDBC Thin Driver + +When using the Oracle JDBC thin driver, EclipseLink is responsible for +acquiring the LOB locator before writing the value. You can use a type +conversion mapping (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]) to retrieve the locator during a commit +operation. + +Use this procedure to map `+LOB+` values using the Oracle JDBC thin +driver: + +[arabic] +. Use a type conversion mapping to map the attributes of a EclipseLink +descriptor to a LOB value. The followiing figure shows a type conversion +mapping to a `+BLOB+` value in Workbench. The +link:#Example_116-11[Mapping a BLOB in Java Code] example shows the Java +code for the same mapping. [#Example 116-10]##*_Mapping a BLOB in +Workbench_* image:blob.gif[Mapping a BLOB in +Workbench,title="Mapping a BLOB in Workbench"] [#Example 116-11]## *** +Mapping a BLOB in Java Code*** ++ +`+TypeConversionMapping pictureMapping = new TypeConversionMapping();+` +`+pictureMapping.set.AttributeName("picture");+` +`+pictureMapping.setFieldName("IMAGE.PICTURE");+` +`+pictureMapping.setFieldClassification(java.sql.Blob.class);+` +`+descriptor.addMapping(pictureMapping);+` +. Acquire the `+DatabaseLogin+` from the session: +`+DatabaseLogin login = session.getLogin();+` +. Configure a platform that provides locator support, as follows: +* For Oracle8i, use the +`+org.eclipse.persistence.oraclespecific.Oracle8Platform+` class: ++ +`+   login.usePlatform(new Oracle8Platform());+` +* For Oracle9__i__ Database Server, use the +`+org.eclipse.persistence.oraclespecific.Oracle9Platform+` class: ++ +`+   login.usePlatform(new Oracle9Platform());+` +* Oracle Database 10__g__, use the +`+org.eclipse.persistence.oraclespecific.Oracle10Platform+` class: ++ +`+   login.usePlatform(new Oracle10Platform());+` ++ +In Workbench, select the appropriate platform in the Database +editor.[#Figure 116-1]## *_Selecting Database Platform in Workbench_* +image:dplalog.gif[Selecting Database Platform in +Workbench,title="Selecting Database Platform in Workbench"] + +== Removing Mappings + +If you are using the Workbench, you can unmap any mapped attribute. + +=== How to Remove Mappings Using Workbench + +To unmap an attribute (that is, remove its mapping), use this procedure: + +image:unmapbtn.gif[Unmap button,title="Unmap button"] Select the +attribute in the *Navigator* window and click *Unmap*. You can also +unmap the attribute by right-clicking the attribute and selecting *Map +As > Unmapped* from the context menu. + +To unmap all the attributes in a descriptor or Java package, use this +procedure: + +image:unmapbtn.gif[Unmap all Descriptors +button,title="Unmap all Descriptors button"] Right-click the descriptor +or Java package in the *Navigator* window and select *Unmap > Unmap +Selected Descriptor* or *Unmap All Descriptors in Package* from the +context menu. + +=== How to Remove Mappings Using Java + +Use the `+ClassDescriptor+` method `+removeMappingForAttributeName+` to +unmap an attribute. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_a_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Project_(ELUG).adoc new file mode 100644 index 00000000000..c738c9b7a85 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Project_(ELUG).adoc @@ -0,0 +1,383 @@ +*TOC* Special:Whatlinkshere_Creating_a_Project_(ELUG)[Related Topics] + +This section describes how to create EclipseLink projects. For +information on the various types of projects available, see +link:Introduction%20to%20Projects_(ELUG)#EclipseLink_Project_Types[EclipseLink +Project Types]. + +You can create a project using the Workbench or Java code. We recommend +link:#How_to_Create_a_Project_Using_the_Workbench[using the Workbench] +to create projects and generate deployment XML or Java source versions +of the project for use at run time. + +Alternatively, you can create projects +link:#How_to_Create_a_Project_Using_Java[in Java code]. For an EIS +project that uses a record type other than XML, you must use Java code. + +=== How to Create a Project Using the Workbench + +When you create a project using the Workbench, all project information +is stored in the project file ( .`+mwp+` file). This file references +additional XML data files that contain the information about how the +Java classes map to database tables or XML elements. + +Using the Workbench, you can link:#Exporting_Project_Information[export +this information as an EclipseLink project XML file] (that is, the +deployment XML file) that is read in by the EclipseLink runtime. You can +also export this information as a Java class. + +The Workbench displays projects and their contents in the Navigator +window. When you select a project, its attributes are displayed in the +Editor window. See +link:Using%20Workbench%20(ELUG)#How_to_Use_the_Navigator[How to Use the +Navigator] for more information. The Workbench supports the following +project types: + +* image:projdb.gif[Relational Database project +icon,title="Relational Database project icon"] Relational project +* image:projxml.gif[XML Project icon,title="XML Project icon"] XML +project +* image:projeis.gif[EIS project icon,title="EIS project icon"] EIS +project + +==== Creating New Workbench Projects + +This section includes information on creating a new Workbench project. +To create a new project from an existing persistence application, see +link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server]. To create a new project from +JAXB, see +link:Introduction%20to%20XML%20Projects%20(ELUG)#EclipseLink_Support_for_Java_Architecture_for_XML_Binding_(JAXB)[EclipseLink +Support for Java Architecture for XML Binding (JAXB)]. + +To create a new Workbench project, use this procedure: + +[arabic] +. Click *New* image:creatbtn.gif[New Project +icon,title="New Project icon"] on the toolbar and select *Project*. The +Create New Workbench Project dialog box appears. You can also create a +new project by choosing *File* > *New > Project* from the menu.*_ +[#Figure 112-1]## Create New Workbench Project Dialog Box_* +image:create.gif[Create New Workbench Project Dialog +Box,title="Create New Workbench Project Dialog Box"] +. Enter data in each field on the Create New Workbench Project dialog +box, and then click *OK*. + +Use the following information to enter data in each field of this dialog +box: + +Field + +Description + +Name + +Enter the name of the Workbench project. This project name will also +become the name of the .mwp file. + +Data Source + +Use these options to specify the type of project to create, and its data +source. + +Database + +Select Database to create a relational project to a relational database. +Use the Platform list to select the specific database platform. + +EIS + +Select EIS to create an EIS project to a nonrelational data source using +XML records. Use the Platform list to specify the JCA adapter to use. + +XML + +Select XML to create a nontransactional, nonpersistent XML project to an +XML schema. Alternatively, you can generate both an XML project and +object model classes (see Creating an XML Project from an XML Schema). + +For more project information, continue with the following: + +* link:Configuring%20a%20Project%20(ELUG)[Configuring the project]. +* Add mappings and descriptors (see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] and link:Introduction%20to%20Mappings%20(ELUG)[Introduction +to Mappings]). +* link:#Exporting_Project_Information[Export the project for use with +the EclipseLink runtime]. + +=== How to Create a Project Using Java + +To create a project using Java code, use this procedure: + +[arabic] +. Implement a project class that extends the +`+org.eclipse.persistence.sessions.Project+` class (see the +link:#Example_112-1[Specifying an EclipseLink Project in Code] example). +. Compile the project class. + +[#Example 112-1]## *_Specifying an EclipseLink Project in Code_* + +*`+/**+`* +`+'''* The class EmployeeProject is an example of an EclipseLink project defined in+` +`+'''* Java code. The individual parts of the project - the Login and the descriptors,+` +`+'''* are built inside of methods that are called by the constructor. Note that+` +`+'''* EmployeeProject extends the class org.eclipse.persistence.sessions.Project+` +`+'''*/+` +`+public class EmployeeProject extends org.eclipse.persistence.sessions.Project {+` + +*`+/**+`* +`+'''* Supply a zero-argument constructor that initializes all aspects of the project.+` + +`+'''* Make sure that the login and all the descriptors are initialized and added to+` +`+'''* the project. Project-level properties, such as the name of the project, should+` +`+'''* be specified here+` `+'''*/+` `+public EmployeeProject() {+` +`+  setName("EmployeeProject");+` `+  applyLogin();+` `+  +` +`+  addDescriptor(buildAddressDescriptor());+` +`+  addDescriptor(buildEmployeeDescriptor());+` +`+  addDescriptor(buildPhoneNumberDescriptor());+` `+}+` + +*`+//\'\' \'\'Data\'\' \'\'source\'\' \'\'information+`* +`+public void applyLogin() {+` +`+  DatabaseLogin login = new DatabaseLogin();+` + +`+  +`*`+//\'\' \'\'use\'\' \'\'platform\'\' \'\'appropriate\'\' \'\'for\'\' \'\'underlying\'\' \'\'database+`* +`+  login.usePlatform(+` +`+    new org.eclipse.persistence.platform.database.oracle.Oracle9Platform());+` +`+  login.setDriverClassName("oracle.jdbc.OracleDriver");+` +`+  login.setConnectionString("jdbc:oracle:thin:@HOST:PORT:SID");+` +`+  login.setUserName("USER NAME");+` +`+  login.setEncryptedPassword("PASSWORD, ENCRYPTED");+` + +`+  +`*`+//\'\' \'\'Configuration\'\' \'\'Properties+`* + +`+    setDatasourceLogin(login);+` `+}+` + +*`+/**+`* +`+'''* Descriptors are built by defining table info, setting properties+` +`+'''* (caching, etc.) and by adding mappings to the descriptor+` +`+'''*/+` + +*`+//\'\' \'\'SECTION:\'\' \'\'DESCRIPTOR+`* +`+public ClassDescriptor buildAddressDescriptor() {+` + +`+  RelationalDescriptor descriptor = new RelationalDescriptor();+` + +`+  +`*`+//\'\' \'\'specify\'\' \'\'the\'\' \'\'class\'\' \'\'to\'\' \'\'be\'\' \'\'made\'\' \'\'persistent+`* +`+  descriptor.setJavaClass(examples.servletjsp.model.Address.class);+` + +`+  +`*`+//\'\' \'\'specify\'\' \'\'the\'\' \'\'tables\'\' \'\'to\'\' \'\'be\'\' \'\'used\'\' \'\'and\'\' \'\'primary\'\' \'\'key+`* + +`+  descriptor.addTableName("ADDRESS");+` +`+  descriptor.addPrimaryKeyFieldName("ADDRESS.ADDRESS_ID");+` + +`+  +`*`+//\'\' \'\'Descriptor\'\' \'\'Properties+`* +`+  descriptor.useSoftCacheWeakIdentityMap();   +` +`+  descriptor.setIdentityMapSize(100) +` +`+  descriptor.useRemoteSoftCacheWeakIdentityMap()+` +`+  descriptor.setRemoteIdentityMapSize(100)+` +`+  descriptor.setSequenceNumberFieldName("ADDRESS.ADDRESS_ID")+` +`+  descriptor.setSequenceNumberName("ADD_SEQ");   +` +`+  descriptor.setAlias("Address");+` + +`+  +`*`+//\'\' \'\'Mappings+`* +`+  DirectToFieldMapping cityMapping = new DirectToFieldMapping();+` +`+  cityMapping.setAttributeName("city");+` +`+  cityMapping.setFieldName("ADDRESS.CITY");+` +`+  descriptor.addMapping(cityMapping);+` + +`+  +`*`+//\'\' \'\'Additional\'\' \'\'mappings\'\' \'\'are\'\' \'\'added\'\' \'\'to\'\' \'\'the\'\' \'\'descriptor\'\' \'\'using\'\' \'\'the\'\' \'\'addMapping\'\' \'\'method+`* + +`+  return descriptor;}+` + +[width="100%",cols="<100%",] +|=== +|*Note*: Using Workbench provides a starting point for a custom project +class. For more information, see +link:Creating%20a%20Relational%20Project%20(ELUG)#How_to_Export_Project_Java_Source_Using_Workbench[How +to Export Project Java Source Using Workbench]. +|=== + +== Working with Projects + +Using Workbench, you can perform the following project functions: + +* link:#How_to_Open_Existing_Projects[How to Open Existing Projects] +* link:#How_to_Save_Projects[How to Save Projects] +* link:#How_to_Generate_the_Project_Status_Report[How to Generate the +Project Status Report] + +See link:Configuring%20a%20Project%20(ELUG)[Configuring a Project] for +additional information on working with Workbench projects. + +=== How to Open Existing Projects + +Use this procedure to open an existing project: + +[arabic] +. Click *Open Project* image:openbtn.gif[Open Project +button,title="Open Project button"] on the toolbar. The Choose a File +dialog box appears. You can also open a project by choosing *File* > +*Open* from the menu. + +[width="100%",cols="<100%",] +|=== +|*Note*:The *File* menu option contains a list of recently opened +projects. You can select one of these projects to open. See +link:Using%20Workbench%20(ELUG)#How_to_Use_General_Preferences[How to +Use General Preferences] for information on customizing this list. +|=== + +*See Also* + +link:#Working_with_Projects[Working with Projects] + +link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects] + +=== How to Save Projects + +Workbench does not automatically save your project. Be sure to save your +project often to avoid losing data. + +To save your project(s), use this procedure: + +[arabic] +. Click *Save* image:savebtn.gif[Save Selected Project +button.,title="Save Selected Project button."] or *Save All* +image:saveall.gif[Save All Projects +button.,title="Save All Projects button."] to save your project(s). You +can also save a project by choosing *File* > *Save* or *File* > *Save +All* from the menu. +. If you close Workbench while there are currently unsaved changes, the +Save Project dialog box appears. [#Figure 112-3]##*_Save Projects Dialog +Box_* image:save.gif[Save Projects Dialog +Box,title="Save Projects Dialog Box"] +. Select the project(s) to save and click *OK*.Click *Select All* to +select all the available projects. + +To save your project with a new name or location, see +link:#Saving_Projects_with_a_New_Name_or_Location[Saving Projects with a +New Name or Location]. + +==== Saving Projects with a New Name or Location + +To save your project with a different name or location, use this +procedure: + +[arabic] +. Choose *File* > *Save As* image:saveasbt.gif[Save As +button,title="Save As button"]. The Save As dialog box appears. +[#Figure 112-4]##*_Save As Dialog Box_* image:saveas.gif[Save As Dialog +Box,title="Save As Dialog Box"] +. Select a name and location, then click *Save*. + +[width="100%",cols="<100%",] +|=== +|*Caution*:Do not rename the `+.mwp+` file outside of Workbench. To +rename a project, use the *Save As* option. +|=== + +=== How to Generate the Project Status Report + +Use the project status report to display a list of all warnings and +errors in the Workbench project. This report is similar to the Problems +window (see link:Using%20Workbench%20(ELUG)[Using Workbench]), but lets +you easily copy and paste the errors into documents or messages. To +generate the project status report, use this procedure: + +[arabic] +. image:strptbtn.gif[Project Status Report +button,title="Project Status Report button"] Right-click the *Problems* +label above the *Problems* window and select *Problem Report*. The +Project Status Report dialog box appears, displaying the status of each +Workbench project. You can also generate the project status report by +selecting *Tools* > *Problem Report* from the menu. +[#Figure 112-5]##*_Problem Report Dialog Box_* image:statrpt.gif[Problem +Report Dialog Box,title="Problem Report Dialog Box"] +. See link:EclipseLink_Workbench_Error_Reference_(ELUG)[EclipseLink +Workbench Error Reference (ELUG)] for information on each reported +error. +. To copy the report to another application, click *Copy*. + +== Exporting Project Information + +To use your project with the EclipseLink Foundation Library at run time, +you must either generate deployment XML or export the project to Java +source code. + +For all project types, Workbench can generate and export the following +project information: + +* Deployment information (see +link:#How_to_Export_Deployment_XML_Information_Using_Workbench[How to +Export Deployment XML Information Using Workbench]) (`+project.xml+` +file) +* Model Java source (see +link:#How_to_Export_Model_Java_Source_Using_Workbench[ow to Export Model +Java Source Using Workbench]) + +[width="100%",cols="<100%",] +|=== +|*Note*:When exporting Java source and deployment XML, Workbench writes +the database password (if applicable) using Java Cryptography Extension +(JCE) encryption. For information on how to specify password encryption +options, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)[Configuring +Password Encryption]. +|=== + +=== How to Export Deployment XML Information Using Workbench + +To export your deployment XML file (`+project.xml+`), use this procedure +(see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] for detailed information): + +[arabic] +. Select the project and click *Export Deployment XML* +image:expxml.gif[expxml,title="expxml.gif"]. You can also right-click +the project in the *Navigator* and choose *Export* > *Project Deployment +XML* from the context menu or choose *Selected* > *Export* > *Project +Deployment XML* from the menu. +. If you have not defined deployment and source code generation defaults +(see link:Configuring%20a%20Project%20(ELUG)[Configuring a Project]) +Workbench prompts for a file name and directory. + +[width="100%",cols="<100%",] +|=== +|*Note*: If your project contains errors, the `+project.xml+` may not be +valid. See for information on each reported error. +|=== + +=== How to Export Model Java Source Using Workbench + +To generate the project model’s Java source code, use this procedure: + +[arabic] +. Right-click the project, package, or specific descriptor in the +*Navigator* and choose *Export* > *Export Model Java Source* from the +context menu. Workbench creates a `+.java+` file for each selected +descriptor. You can also choose *Workbench* > *Export* > *Export Model +Java Source* or *Selected* > *Export* > *Model Java Source* from the +menu or click *Generate Source Code* on the *Class* tab. See +link:Using%20Workbench%20(ELUG)[Configuring Class Information] for more +information. +. Click *Generate Source Code* to generate the project’s model Java +source. + +If you have not defined deployment and source code generation defaults +(see link:Configuring%20a%20Project%20(ELUG)[Configuring a Project]) +Workbench prompts for a root directory. + +[width="100%",cols="<100%",] +|=== +|*Note*: If your Workbench project uses UTF-8 character set, you must +use a compatible JDK when compiling the exported Java source. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..98d69de3625 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Descriptor_(ELUG).adoc @@ -0,0 +1,146 @@ +*TOC* +Special:Whatlinkshere_Creating_a_Relational_Descriptor_(ELUG)[Related +Topics] + +After you create a descriptor, you must configure its various options +(see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a +Descriptor]) and use it to define mappings. + +For information on the various types of mapping that EclipseLink +supports, see link:Introduction%20to%20Mappings%20(ELUG)[Introduction to +Mappings] and link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +For information on the various types of descriptor that EclipseLink +supports, see link:Introduction%20to%20Descriptors%20(ELUG)[Descriptor +Types]. + +For more information, see +link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Introduction +to Relational Descriptors]. + +== Creating a Relational Descriptor + +You can create a relational descriptor using +link:#How_to_Create_a_Relational_Descriptor_Using_Workbench[the +Workbench] or +link:#How_to_Create_a_Relational_Descriptor_Using_Java[Java code]. + +=== How to Create a Relational Descriptor Using Workbench + +Using Workbench, you can create the following types of descriptor in a +relational project: + +* link:#Creating_Relational_Class_Descriptors[Relational class +descriptors]; +* link:#Creating_Relational_Aggregate_Descriptors[Relational aggregate +descriptors]; +* link:#Creating_Relational_Interface_Descriptors[Relational interface +descriptors]. + +==== Creating Relational Class Descriptors + +image:clsesin.gif[Class descriptor icon,title="Class descriptor icon"] +By default, when you add a Java class to a relational project (see +link:Configuring%20a%20Project%20(ELUG)[Configuring Project Classpath]), +the Workbench creates a relational class descriptor for it. A class +descriptor is applicable to any persistent object except an object that +is owned by another in an aggregate relationship. In this case, you must +describe the owned object with +link:#Creating_Relational_Aggregate_Descriptors[an aggregate +descriptor]. Using a class descriptor, you can configure any relational +mapping except aggregate collection and aggregate object mappings. + +==== Creating Relational Aggregate Descriptors + +image:agdesbtn.gif[Aggregate Descriptor +button,title="Aggregate Descriptor button"] An aggregate object is an +object that is strictly dependent on its owning object. Aggregate +descriptors do not define a table, primary key, or many of the standard +descriptor options as they obtain these from their owning descriptor. If +you want to configure an aggregate mapping to associate data members in +a target object with fields in a source object’s underlying database +tables (see +link:Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)[Configuring +a Relational Aggregate Collection Mapping] and +link:Configuring%20a%20Relational%20Aggregate%20Object%20Mapping_(ELUG)[Configuring +a Relational Aggregate Object Mapping]), you must designate the target +object’s descriptor as +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[an +aggregate]. + +==== Creating Relational Interface Descriptors + +.Interface descriptor icon +image::ifdescin.gif[Interface descriptor +icon,title="Interface descriptor icon"] + +If you add an interface to a relational project (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]), the Workbench creates an interface descriptor for +it. + +An interface is a collection of abstract behavior that other classes can +use. It is a purely Java concept and has no representation on the +relational database. Therefore, a descriptor defined for the interfaces +does not map any relational entities on the database. + +The interface descriptor includes the following elements: + +* The Java interface it describes. +* The parent interface(s) it implements. +* A list of abstract query keys. + +An interface descriptor does not define any mappings, because there is +no concrete data or table associated with it. A list of abstract query +keys is defined so that you can issue +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Interface_Query_Keys[queries +on the interfaces]. A read query on the interface results in reading one +or more of its implementors. + +=== How to Create a Relational Descriptor Using Java + +This example shows how to create a relational descriptor using Java +code. + +[#Example 27-1]## *_Creating a Relational Descriptor in Java_* + +[source,java] +---- + RelationalDescriptor descriptor = new RelationalDescriptor(); + descriptor.setJavaClass(YourClass.class); +---- + +To designate a relational descriptor as an aggregate, use +`+ClassDescriptor+` method `+descriptorIsAggregate+`. For a +`+RelationalDescriptor+` configured as an aggregate, you do not define a +primary key, but when using Java, you must configure the +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[associated +table] and link:Introduction%20to%20Mappings%20(ELUG)[field mappings]. + +To allow a relational descriptor to participate in an +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Collection_Mapping[Aggregate +Collection Mapping], use `+ClassDescriptor+` method +`+descriptorIsAggregateCollection+`. For a `+RelationalDescriptor+` +configured for use with an aggregate collection mapping, you do +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[define +primary keys] and an +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Associated_Tables[associated +table], but you do not have to map the primary keys if they are shared +from their parent. + +To configure a relational descriptor for an interface, use +`+ClassDescriptor+` method `+setJavaInterface+`, passing in the +`+java.lang.Class+` of the interface. You should only use an interface +descriptor for an interface that has multiple implementors. If an +interface has only a single implementor, then rather than creating an +interface descriptor, just set the implementor descriptor’s +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Interface_Alias[interface +alias]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Concept[Category: Concept] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Project_(ELUG).adoc new file mode 100644 index 00000000000..50c1194c5a1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_a_Relational_Project_(ELUG).adoc @@ -0,0 +1,165 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Creating_a_Relational_Project_(ELUG)[Related +Topics] + +You can create a project using the Workbench or Java code. We recommend +using the Workbench to create projects and generate deployment XML or +Java source versions of the project for use at run time. For more +information, see the following: + +* link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[How +to Create a Project Using the Workbench] +* link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_Java[How +to Create a Project Using Java]. + +You can use EclipseLink to create a relational project, if any of the +following conditions are met: + +* You have both an object and data model: see +link:#Creating_a_Project_from_an_Existing_Object_and_Data_Model[Creating +a Project from an Existing Object and Data Model]. +* You have an object model, but no data model yet: see +link:#Creating_a_Project_from_an_Existing_Object_Model[Creating a +Project from an Existing Object Model]. +* You have a data model, but no object model yet: +link:#Creating_a_Project_from_an_Existing_Data_Model[Creating a Project +from an Existing Data Model]. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Introduction to +Relational Projects]. + +== Creating a Project from an Existing Object and Data Model + +If you have both an existing object model (Java classes for your domain +objects) and data model (such as an existing database schema), use this +procedure to create your EclipseLink project. + +=== How to Create a Project from an Existing Object and Data Model Using Workbench + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configure +the project classpath]. +. link:Using%20Workbench%20(ELUG)#How_to_Import_and_Update_Classes[Import +classes]. +. link:Using%20Workbench%20(ELUG)#Importing_Tables_from_a_Database[Import +database tables]. +. link:Creating%20a%20Mapping%20(ELUG)#How_to_Create_Mappings_Automatically_During_Development_Using_Workbench[Automatically +create mappings]. +. link:Configuring%20a%20Project%20(ELUG)[Configure project options]. + +== Creating a Project from an Existing Object Model + +If you have an existing object model (Java classes for your domain +objects), but you do not have a corresponding data model, use this +procedure to create your EclipseLink project and automatically generate +the corresponding data model. + +=== How to Create a Project from an Existing Object Model Using Workbench + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configure +the project classpath]. +. link:Using%20Workbench%20(ELUG)#How_to_Import_and_Update_Classes[Import +classes]. +. Generate database tables. For more information, see the following: +* link:Using%20Workbench%20(ELUG)#Creating_New_Tables[Creating New +Tables] +* link:Using%20Workbench%20(ELUG)#Generating_Tables_on_the_Database[Generating +Tables on the Database] +* link:Configuring%20a%20Relational%20Project%20(ELUG)[How to Configure +Table Creator Java Source Options Using Workbench] +* link:#How_to_Export_Table_Creator_Files_Using_Workbench[How to Export +Table Creator Files Using Workbench] +. link:Configuring%20a%20Project%20(ELUG)[Configure project options]. + +== Creating a Project from an Existing Data Model + +If you have an existing data model (such as a database schema), but you +do not have a corresponding data model (Java classes for domain +objects), use this procedure to create your EclipseLink project and +automatically generate the corresponding object model. + +=== How to Create a Project from an Existing Data Model Using Workbench + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Using%20Workbench%20(ELUG)#Importing_Tables_from_a_Database[Import +database tables]. +. link:Using%20Workbench%20(ELUG)#Generating_Classes_and_Descriptors_from_Database_Tables[Generate +classes]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_a_Project[Configure +project options]. + +== Exporting Project Information + +Workbench generates and exports the following project information: + +* link:#How_to_Export_Project_Java_Source_Using_Workbench[Project Java +source] +* link:#How_to_Export_Table_Creator_Files_Using_Workbench[Table creator +files] + +=== How to Export Project Java Source Using Workbench + +For relational projects only, you can convert the project to Java source +code. Generally, the generated code executes faster and deploys easier +than XML files. See +link:Creating%20a%20Descriptor%20(ELUG)#Generating_Java_Code_for_Descriptors[Generating +Java Code for Descriptors] to export the model source for a _specific +descriptor_ in a project. To convert your relational project to Java +source, use this procedure: + +[arabic] +. Right-click the project in the *Navigator* and choose *Export* > +*Project Java Source* from the context menu.image:expjava.gif[Export to +Java Source button,title="Export to Java Source button"] You can also +choose *Workbench* > *Export* > *Export Java Source* or *Selected* > +*Export* > *Project Java Source* from the menu. If you have not defined +deployment and source code generation defaults (see +link:Configuring%20a%20Project%20(ELUG)[Configuring a Project]), +Workbench prompts for a project class name and directory. + +[width="100%",cols="<100%",] +|=== +|*_Note:_* If your Workbench project uses the UTF-8 character set, you +must use a compatible JDK when compiling the exported Java source. If +your project contains errors, the `+project.xml+` file may not be valid. +See +link:Troubleshooting_an_EclipseLink_Application_(ELUG)[Troubleshooting +an EclipseLink Application] for information on each reported error. +|=== + +=== How to Export Table Creator Files Using Workbench + +For relational projects only, you can create Java source code to +generate database tables defined in the project using this procedure: + +[arabic] +. Right-click the project in the *Navigator* and choose *Export* > +*Table Creator Java Source* from the context menu.You can also choose +*Workbench* > *Export* > *Table Creator Java Source* or *Selected* > +*Export* > *Table Creator Java Source* from the menu. + +If you have not defined deployment and source code generation defaults +(see link:Configuring%20a%20Project%20(ELUG)[Configuring a Project]) +Workbench prompts for a class name and root directory. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..65c83878a68 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Descriptor_(ELUG).adoc @@ -0,0 +1,103 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Creating_an_EIS_Descriptor_(ELUG)[Related +Topics] + +This section explains how to create descriptor options specific to an +EIS descriptor. + +After you create a descriptor, you must configure its various options +(see link:Configuring%20an%20EIS%20Descriptor%20(ELUG)[Configuring an +EIS Descriptor]) and use it to define mappings. + +For information on the various types of mapping that EclipseLink +supports, see link:Introduction%20to%20Mappings%20(ELUG)[Introduction to +Mappings] and link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a +Mapping]. + +For information on the various types of descriptor that EclipseLink +supports, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Types[Descriptor +Types]. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#CHECEAAE[Introduction to +Descriptors] +* link:Introduction%20to%20EIS%20Descriptors%20(ELUG)[Introduction to +EIS Descriptors] + +== Creating an EIS Descriptor + +You can create an EIS descriptor using +link:#How_to_Create_an_EIS_Descriptor_Using_Workbench[the Workbench] or +link:#How_to_Create_an_EIS_Descriptor_Using_Java[Java code]. We +recommend that you use the Workbench to create and manage your EIS +descriptors. + +=== How to Create an EIS Descriptor Using Workbench + +Using Workbench, you can create the following types of EIS descriptor in +an EIS project: + +* link:#EIS_Root_Descriptors[EIS Root Descriptors] +* link:#EIS_Composite_Descriptors[EIS Composite Descriptors] + +==== EIS Root Descriptors + +image:eisdesin.gif[EIS root descriptor +button,title="EIS root descriptor button"] You can modify an EIS +descriptor’s behavior by configuring it as a root EIS descriptor (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]). When you designate an +EIS descriptor as a root, you tell the EclipseLink runtime that the EIS +descriptor’s reference class is a parent class: no other class will +reference it by way of a composite object mapping or composite +collection mapping. Using an EIS root descriptor, you can configure all +supported mappings. You can also configure an EIS root descriptor with +link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[EIS +Interactions]. However, if you configure the EIS root descriptor with a +composite object mapping or composite collection mapping, the reference +descriptor you define must be an EIS composite descriptor; it cannot be +another EIS root descriptor. + +==== EIS Composite Descriptors + +image:eisdescompicon.gif[EIS composite descriptor +button,title="EIS composite descriptor button"] By default, when you add +a class to an EIS project (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]), Workbench creates an EIS descriptor for the class, +and designates the EIS descriptor as a composite. When you designate an +EIS descriptor as a composite, you tell the EclipseLink runtime that the +EIS descriptor’s reference class may be referenced by a composite object +mapping or composite collection mapping. Using an EIS composite +descriptor, you can configure all supported mappings. However, you +cannot configure an EIS composite descriptor with EIS interactions: for +this, you need an link:#EIS_Root_Descriptors[EIS Root Descriptor]. + +=== How to Create an EIS Descriptor Using Java + +This example shows how to create a relational descriptor using Java +code. + +[#Example 71-1]## *_Creating an EIS Descriptor in Java_* + +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.setJavaClass(YourClass.class);+` + +To designate an EIS descriptor as a composite, use `+ClassDescriptor+` +method `+descriptorIsAggregate+`. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Project_(ELUG).adoc new file mode 100644 index 00000000000..896b23ebf2e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_an_EIS_Project_(ELUG).adoc @@ -0,0 +1,101 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Creating_an_EIS_Project_(ELUG)[Related +Topics] + +This section describes the various components that you must configure in +order to create an EIS project. + +For information on how to configure EIS projects, see +link:Configuring%20an%20EIS%20Project%20(ELUG)[Configuring an EIS +Project]. + +You can create a project using the Workbench or Java code. + +We recommend using the Workbench to create projects and generate +deployment XML or Java source versions of the project for use at run +time. For more information on how to create a project using Workbench, +see +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[How +to Create a Project Using the Workbench]. For information on how to +create a project using Java, see +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_Java[How +to Create a Project Using Java]. + +For more information, see +link:Introduction%20to%20EIS%20Projects%20(ELUG)[Introduction to EIS +Projects]. + +For an EIS project that uses a record type other than XML, you must use +Java code. For more information, see the following: + +* link:#Creating_an_EIS_Project_with_Indexed_or_Mapped_Records[Creating +an EIS Project with Indexed or Mapped Records] +* link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_Java[How +to Create a Project Using Java] +* _EclipseLink API Reference_. + +== Creating an EIS Project with XML Records + +Workbench provides complete support for creating EIS projects that map +Java objects to EIS XML records. + +Using Workbench, you can create an EIS project for transactional +persistence of Java objects to a non-relational data source accessed +using a JCA adapter and EIS XML records. + +The EclipseLink runtime performs XML data conversions based on one or +more XML schemas. In an EIS project, Workbench does not directly +reference schemas in the deployment XML, but instead exports mappings +configured in accordance to specific schemas. + +EIS queries use `+XMLInteraction+`. For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[Using +EIS Interactions]. + +=== How to Create an EIS Project with XML Records Using Workbench + +Refer to +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[How +to Create a Project Using the Workbench] for this information. + +== Creating an EIS Project with Indexed or Mapped Records + +Workbench does not currently support non-XML EIS projects. You must +create such an EIS project in Java. + +Using Java, you can create an EIS project for transactional persistence +of Java objects to a nonrelational data source accessed using a JCA +adapter and any supported EIS record type including indexed, mapped, or +XML records. + +If you use XML records, the EclipseLink runtime performs XML data +conversion based on one or more XML schemas. When you create an EIS +project in Java, you configure mappings with respect to these schemas, +but the EclipseLink runtime does not directly reference them. + +You can base queries on any supported EIS interaction: +`+IndexedInteraction+`, `+MappedInteraction+` (including +`+QueryStringInteraction+`), or `+XMLInteraction+` (including +`+XQueryInteraction+`). For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[Using +EIS Interactions]. + +=== How to Create an EIS Project with Indexed or Mapped Records Using Java + +Refer to +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_Java[How +to Create a Project Using Java] for this information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_an_Internal_Connection_Pool_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_an_Internal_Connection_Pool_(ELUG).adoc new file mode 100644 index 00000000000..800e9dabcb3 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_an_Internal_Connection_Pool_(ELUG).adoc @@ -0,0 +1,124 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Creating_an_Internal_Connection_Pool_(ELUG)[Related +Topics] + +For information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools]. + +== Introduction to the Internal Connection Pool Creation + +You can create internal connection pools only for server sessions (not +for any other session type, including database sessions). For more +information, see link:#Creating_an_Internal_Connection_Pool[Creating an +Internal Connection Pool]. + +After you create an internal connection pool, you must configure its +various options. + +After you create and configure a sequence connection pool, EclipseLink +uses it whenever it needs to assign an identifier to a new object. + +After you create and configure a named connection pool, you use it in +your application by passing in a `+ConnectionPolicy+` when you acquire a +client session (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_a_Named_Connection_Pool[How +to Acquire a Client Session that Uses a Named Connection Pool]). + +== Creating an Internal Connection Pool + +You can create an internal connection pool using the Workbench (see +link:#How_to_Create_an_Internal_Connection_Pool_Using_Workbench[How to +Create an Internal Connection Pool Using Workbench]) or Java code. We +recommend that you use the Workbench to create and manage your internal +connection pools. + +Alternatively, you can create internal connection pools in Java. For +more information on creating sessions in Java, see the ’’EclipseLink API +Reference. + +=== How to Create an Internal Connection Pool Using Workbench + +Before you create a connection pool, you must first create a server +session (see +link:Creating%20a%20Session%20(ELUG)#Creating_a_Server_Session[Creating +a Server Session]). + +To create a new EclipseLink internal connection pool, use this +procedure: + +[arabic] +. Select the server session in the *Navigator* in which you want to +create a connection pool. +. image:conpolbt.gif[Create New Sequence Connection Pool +button,title="Create New Sequence Connection Pool button"] Click the +appropriate button on the toolbar to create the type of connection pool +you want: +* To create a named connection pool, select *Create a New Named +Connection Pool*, enter a name, and click *OK*. +* To create a sequence connection pool, select *Add the Sequence +Connection Pool*. +* To create a write connection pool, select *Add the Write Connection +Pool*. + +You can also create a new internal connection pool by right-clicking the +server session configuration in the *Navigator* and selecting *New > +Named Connection Pool*, *Sequence Connection Pool*, or *Write Connection +Pool* from the context menu. + +=== How to Create an Internal Connection Pool Using Java + +Using Java, you can create read, write, and named connection pools. The +#Example:Creating_Connection_Pools[Creating Connection Pools example] +shows how to create connection pools. The +#Example:Using_a_Single_Pool_for_Read_and_Write[Using a Single Pool for +Read and Write example] shows an optimized connection pool, using the +same connetion for both read and write operations. + +[#Example:Creating Connection Pools]## *_Creating Connection Pools_* + +`+// Read+` `+ConnectionPool pool = new ConnectionPool();+` +`+pool.setName("read");+` `+pool.setLogin(login);+` +`+pool.setMaxNumberOfConnections(50);+` +`+pool.setMinNumberOfConnections(50);+` +`+serverSession.setReadConnectionPool(pool);+` + +`+// Write+` `+ConnectionPool pool = new ConnectionPool();+` +`+pool.setName("default");+` `+pool.setLogin(login);+` +`+pool.setMaxNumberOfConnections(50);+` +`+pool.setMinNumberOfConnections(50);+` +`+serverSession.addConnectionPool(pool);+` + +`+// Named+` `+ConnectionPool pool = new ConnectionPool();+` +`+pool.setName("admin");+` `+pool.setLogin(login);+` +`+pool.setMaxNumberOfConnections(2);+` +`+pool.setMinNumberOfConnections(2);+` +`+serverSession.addConnectionPool(pool);+` + +[#Using a Single Pool for Read and Write]## You can also use a single +connection pools for both read and write operations, when the read and +write pools use the same login information. This method requires fewer +connections + +*_Using a Single Pool for Read and Write_* + +`+ConnectionPool pool = new ConnectionPool();+` +`+pool.setName("default");+` `+pool.setLogin(login);+` +`+pool.setMaxNumberOfConnections(50);+` +`+pool.setMinNumberOfConnections(50);+` +`+serverSession.setReadConnectionPool(pool);+` +`+serverSession.addConnectionPool(pool);+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..61ff9fcfde1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_an_Object-Relational_Data_Type_Descriptor_(ELUG).adoc @@ -0,0 +1,120 @@ +*TOC* +Special:Whatlinkshere_Creating_an_Object-Relational_Data_Type_Descriptor_(ELUG)[Related +Topics] + +After you create a descriptor, you must configure its various options +(see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a +Descriptor]) and use it to define mappings. + +For complete information on the various types of mapping that +EclipseLink supports, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] and +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +For complete information on the various types of descriptor that +EclipseLink supports, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Types[Descriptor +Types]. + +For more information, see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)[Introduction +to Object-Relational Data Type Descriptors]. + +== Creating an Object-Relational Data Type Descriptor + +You cannot create an object-relational data type descriptor using the +Workbench: you must use Java code. For more information on creating +descriptors in Java code, see the _EclipseLink API Reference_. + +For more information, see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)#Object-Relational_Data_Type_Descriptors[Object-Relational +Data Type Descriptors]. + +=== How to Create an Object-Relational Data Type Descriptor Using Java + +Use the `+ObjectRelationalDescriptor+` class to define an +object-relational data type descriptor. This class extends +`+RelationalDescriptor+` to add the following methods: + +* `+setStructureName+`: call this method to set the name of the +object-relational data type structure that represents the object class +in the data source. +* `+addFieldOrdering+`: call this method repeatedly to define the order +in which object attributes are persisted to the data source. This +defines a field index that EclipseLink uses if your object-relational +data type data source driver uses JDBC indexed arrays. + +This example shows an `+Employee+` object that is mapped to an Oracle +Database using its object-relational data type features. + +[#Example 30-1]## *_Employee Class_* + +[source,java] +---- + public class Employee { + Long id; + String firstName; + String lastName; + + ... + } +---- + +This example shows the object-relational data type database type +(`+Employee_t+`) created to model the `+Employee+` object within the +database. Such an object-relational data type database type is also +known as a structure. This example also shows how to create and populate +a database table (called `+department+`) that stores instances of the +`+Employee_t+` audio tape. + +[#Example 30-2]## *_Employee Object-Relational Data Type Data Model_* + +[source,sql] +---- + CREATE TYPE EMPLOYEE_T AS OBJECT(ID NUMBER(10), + F_NAME VARCHAR2(100), + L_NAME VARCHAR2(100),) NOT FINAL; + CREATE TABLE EMPLOYEES OF EMPLOYEE_T; +---- + +This example shows how to code an object-relational data type descriptor +in Java to describe the object-relational data type database type +`+Employee_t+`. + +[#Example 30-3]## *_Creating an Object-Relational Data Type Descriptor +in Java_* + +[source,java] +---- + import org.eclipse.persistence.mappings.structures.*; + ... + ObjectRelationalDescriptor descriptor = new ObjectRelationalDescriptor(); + descriptor.setJavaClass(Employee.class); + descriptor.setTableName("EMPLOYEES"); + descriptor.setStructureName("EMPLOYEE_T"); + descriptor.setPrimaryKeyFieldName("ID"); + descriptor.addFieldOrdering("ID"); + descriptor.addFieldOrdering("F_NAME"); + descriptor.addFieldOrdering("L_NAME"); + descriptor.addDirectMapping("id", "OBJECT_ID"); + descriptor.addDirectMapping("firstName", "F_NAME"); + descriptor.addDirectMapping("lastName", "L_NAME"); +---- + +For more information on configuring object-relational data type +descriptors, see +link:Configuring%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)[Configuring +an Object-Relational Data Type Descriptor]. + +For more information on the object-relational data type mappings that +EclipseLink supports, see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)[Introduction +to Object-Relational Data Type Mappings]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..89332e14b11 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Descriptors_(ELUG).adoc @@ -0,0 +1,18 @@ +This part describes the EclipseLink artifact used to describe persistent +objects. It contains the following sections. + +* link:Creating_a_Descriptor_(ELUG)[Creating a Descriptor (ELUG)] – +Contains procedures for creating EclipseLink descriptors. + +* link:Configuring_a_Descriptor_(ELUG)[Configuring a Descriptor (ELUG)] +– Explains how to configure EclipseLink descriptor options common to two +or more descriptor types. + +*Special:Whatlinkshere_Creating_and_Configuring_Descriptors_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..3e37d261762 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Mappings_(ELUG).adoc @@ -0,0 +1,17 @@ +This part describes general mapping information. It contains the +following sections: + +* link:Creating_a_Mapping_(ELUG)[Creating a Mapping (ELUG)] – Contains +procedures for creating EclipseLink mappings. +* link:Configuring_a_Mapping_(ELUG)[Configuring a Mapping (ELUG)] – +Explains how to configure EclipseLink mapping options common to two or +more mapping types. + +*Special:Whatlinkshere_Creating_and_Configuring_Mappings_(ELUG)[Related +Topics] "`wikilink`")* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Projects_(ELUG).adoc new file mode 100644 index 00000000000..0af154e3387 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Creating_and_Configuring_Projects_(ELUG).adoc @@ -0,0 +1,19 @@ +This part describes the EclipseLink artifact used to contain mapping and +data source-specific information. It contains the following sections: + +* link:Creating_a_Project_(ELUG)[Creating a Project (ELUG)] – Contains +procedures for creating EclipseLink projects. + +* link:Configuring_a_Project_(ELUG)[Configuring a Project (ELUG)] – +Explains how to configure EclipseLink project options common to two or +more project types. + +*Special:Whatlinkshere_Creating_and_Configuring_Projects_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Customizing_the_EclipseLink_Application_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Customizing_the_EclipseLink_Application_(ELUG).adoc new file mode 100644 index 00000000000..8cc35b738e3 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Customizing_the_EclipseLink_Application_(ELUG).adoc @@ -0,0 +1,141 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Customizing_the_EclipseLink_Application_(ELUG)[Related +Topics] + +There are multiple ways to customize your EclipseLink application, +ranging from creating custom data types to using JPA extensions. + +[#Introduction to Customization]####By design, EclipseLink can adapt to +a variety of relational and nonrelational data sources. + +To integrate EclipseLink with a data source that is not directly +supported by the EclipseLink API,we recommend that you use an +link:Introduction%20to%20EIS%20Projects%20(ELUG)[EIS project] or a +link:Introduction%20to%20XML%20Projects%20(ELUG)[XML project]). + +Using an EIS project, you can integrate your EclipseLink-enabled +application with any nonrelational data source that supports a JCA +adapter and any supported EIS record type, including indexed, mapped, or +XML. If no JCA adapter exists for your target data source, you can +concentrate your integration efforts on creating an adapter. +Simultaneously, you can build your application according to JCA +specifications. Although this still requires custom development effort, +it is more efficient than trying to extend EclipseLink classes and +provides you with a JCA adapter that you can leverage in any other +project (making it a better value). + +Using an XML project, you can integrate your EclipseLink-enabled +application with Web services or other XML-message based designs. + +The remainder of this chapter describes other customization options +provided by the EclipseLink API. + +== Creating Custom Data Types + +EclipseLink provides support for all the most common Java data types. +This table lists the EclipseLink mapping extensions that you can use to +support custom data types. You can also create your object converter to +allow conversion between a data type and your own Java type. + +[#Table 15-1]## *_Mapping Extensions for Custom Data Types_* + +[width="100%",cols="<25%,<75%",options="header",] +|=== +|*Extension* |*Description* +|link:Introduction%20to%20Mappings%20(ELUG)[Object Type Converter] |An +extension of direct and direct collection mappings that lets you match a +fixed number of data values to Java objects. Use this converter when the +values in the schema differ from those in Java + +|link:Introduction%20to%20Mappings%20(ELUG)[Serialized Object Converter] +|An extension of direct and direct collection mappings that lets you map +serializable objects, such as multimedia data, to a binary format in a +data source, such as a base64 element in an XML document or Binary Large +Object (BLOB) field in a database + +|link:Introduction%20to%20Mappings%20(ELUG)[Type Conversion Converter] +|An extension of direct and direct collection mappings that lets you +explicitly map a data source type to a Java type. For example, a +`+java.util.Date+` in Java can be mapped to a `+java.sql.Date+` in the +data source. + +|link:Introduction%20to%20Mappings%20(ELUG)[Simple Type Translator] |An +extension of direct and direct collection mappings that lets you +automatically translate an XML element value to an appropriate Java type +based on the element’s attribute as defined in your XML schema. +|=== + +== Using the Session Customizer Class + +You can customize a session at run time by specifying a session +customizer–a Java class that implements the +`+org.eclipse.persistence.config.SessionCustomizer+` interface. + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Customization[Session +Customization] +* link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Customizer_Class[Configuring +a Session Customizer Class] +* Persistence unit property `+eclipselink.session.customizer+` in +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#EclipseLink_JPA_Persistence_Unit_Properties_for_Customization_and_Validation[EclipseLink +JPA Persistence Unit Properties for Customization and Validation] + +== Using the Descriptor Customizer Class + +You can customize a descriptor at run time by specifying a descriptor +customizer–a Java class that implements the +`+org.eclipse.persistence.config.DescriptorCustomizer+` interface. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Customization[Descriptor +Customization] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Descriptor_Customizer_Class[Configuring +a Descriptor Customizer Class] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[How to Use the +@Customizer Annotation] +* Persistence unit property `+eclipselink.descriptor.customizer.+` in +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#EclipseLink_JPA_Persistence_Unit_Properties_for_Customization_and_Validation[EclipseLink +JPA Persistence Unit Properties for Customization and Validation] + +== Using the Descriptor Amendment Methods + +To customize descriptors, you can use their amendment methods. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#Amendment_and_After-Load_Methods[Amendment +and After-Load Methods] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods] + +== Using EclipseLink JPA Extensions + +If you are developing an EclipseLink JPA application, use EclipseLink +JPA metadata annotations and XML extensions for customization. + +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions]. + +== Using Oracle Database Proxy Authentication in JPA Applications + +For information, see +link:Configuring%20a%20EclipseLink%20JPA%20Application%20(ELUG)#Configuring_Oracle_Database_Proxy_Authentication_for_a_JPA_Application[Configuring +Oracle Database Proxy Authentication for a JPA Application]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Deploying_a_EclipseLink_Application_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Deploying_a_EclipseLink_Application_(ELUG).adoc new file mode 100644 index 00000000000..abcd03b6d1a --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Deploying_a_EclipseLink_Application_(ELUG).adoc @@ -0,0 +1,117 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Deploying_an_EclipseLink_Application_(ELUG)[Related +Topics] + +For more information, see the following: + +* link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server] +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] +* link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging an +EclipseLink Application] + +== Deploying Java Applications + +Build the JAR file (see +link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging Java +Applications]) and place it on the classpath. + +For more information on accessing EclipseLink from your client +application, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[Acquiring +and Using Sessions at Run Time]. + +== Deploying JavaServer Pages and Servlets + +After you build the WAR and JAR files (see +link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging +JavaServer Pages and Servlet Applications]), build them into an EAR file +for deployment. To deploy the EAR to your JSP servlet server, copy the +EAR to a commonly used directory. You may also need to use +server-specific deployment tools. For more information, see the server +documentation. + +For more information on accessing EclipseLink from your client +application, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[How +to Load a Session from sessions.xml with an Alternative Class Loader]. + +== Deploying Session Bean Applications + +After you build the WAR and JAR files (see +link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging +Session Bean Applications]), build them into an EAR file for deployment. +To deploy the EAR file to your Java EE server, copy the EAR to a +commonly used directory. You may also need to use server-specific +deployment tools. For more information, see the server documentation. + +For more information on accessing EclipseLink from your client +application, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[How +to Load a Session from sessions.xml with an Alternative Class Loader]. + +Optionally, you may also consider +link:#Performing_Hot_Deployment_of_EJB[Performing Hot Deployment of +EJB]. + +== Deploying JPA Applications + +After you packaged your JPA application, deploy it to an application +server of your choice. + +For more information, see +link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Deploying +an EclipseLink JPA Application]. + +== Performing Hot Deployment of EJB + +Many Java EE containers support _hot deployment_, a feature that enables +you to deploy EJB on a running server. Hot deployment allows you to do +the following: + +* Deploy newly developed EJB to a running production system. +* Remove (undeploy) deployed EJB from a running server. +* Modify (redeploy) the behavior of deployed EJB by updating the bean +class definition. + +The client receives deployment exceptions when attempting to access +undeployed or re-deployed bean instances. The client application must +catch and handle the exceptions. + +How you configure hot deployment of EJB depends on the type of Java EE +application you are deploying: + +* POJO application (see +link:#How_to_Perform_Hot_Deployment_in_a_POJO_Application[How to Perform +Hot Deployment in a POJO Application]). + +For more information about hot deployment, see the Java EE container +documentation. + +=== How to Perform Hot Deployment in a POJO Application + +When you take advantage of hot deployment in a POJO application, you +must refresh the EclipseLink session using the `+SessionManager+` method +`+getSession+` with the appropriate arguments (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[How +to Refresh a Session when the Class Loader Changes]. + +If you do not use this `+SessionManager+` method, then your application +is responsible for destroying or refreshing the session when a hot +deployment (or hot redeployment) occurs. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EIS_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EIS_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..78ce2354e13 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EIS_Descriptors_(ELUG).adoc @@ -0,0 +1,19 @@ +The following sections contain general information about EIS +descriptors, as well as detailed information on how to create and +configure these descriptors: + +* link:Introduction_to_EIS_Descriptors_(ELUG)[Introduction to EIS +Descriptors] + +* link:Creating_an_EIS_Descriptor_(ELUG)[Creating an EIS Descriptor] + +* link:Configuring_an_EIS_Descriptor_(ELUG)[Configuring an EIS +Descriptor] + +*Special:Whatlinkshere_EIS_Descriptors_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EIS_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EIS_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..f58d6c332c9 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EIS_Mappings_(ELUG).adoc @@ -0,0 +1,27 @@ +== Creating and Configuring EIS Mappings + +EclipseLink enterprise information system (EIS) mappings provide support +for accessing legacy data sources and enterprise applications through +Java EE Connector architecture (JCA) adapter. EclipseLink EIS mappings +use the JCA Common Client Interface (CCI) to access the EIS through its +resource adapter. This provides the ability to directly map from an +existing Java object model to any transactional data source, such as +mainframes with flat file/hierarchical data. An EIS mapping transforms +object data members to the EIS record format defined by the object’s +descriptor. + +Consider the following sections: + +* link:Introduction_to_EIS_Mappings_(ELUG)[Introduction to EIS Mappings] +– describes each of the different EclipseLink EIS mapping types and +important EIS mapping concepts. + +* link:Configuring_an_EIS_Mapping_(ELUG)[Configuring an EIS Mapping] + +*Special:Whatlinkshere_Relational_Mappings_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Exception_Error_Reference_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Exception_Error_Reference_(ELUG).adoc new file mode 100644 index 00000000000..c3feed2a1a4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Exception_Error_Reference_(ELUG).adoc @@ -0,0 +1,5095 @@ +*TOC* +Special:Whatlinkshere_EclipseLink_Exception_Error_Reference_(ELUG)[Related +topics] + +This section lists EclipseLink exceptions and provides numerical ranges +of their error codes. Each exception code corresponds to an exception +class and includes the following information: + +* The exception number in the format of +`+EXCEPTION [ECLIPSELINK-+`[.codeinlineitalic]#`+XXXX+`#`+]+` +* A description of the problem, taken from the raised exception + +== Descriptor Exceptions (1 – 202) + +`+DescriptorException+` is a development exception that is raised when +insufficient information is provided to the descriptor. The message that +is returned includes the name of the descriptor or mapping that caused +the exception. If a mapping within the descriptor caused the error, then +the name and parameters of the mapping are part of the returned message, +as this exampledemonstrates. + +Internal exception, mapping and descriptor appear only if EclipseLink +has enough information about the source of the problem to provide this +information. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` `+INTERNAL EXCEPTION: Message+` +`+MAPPING: Database mapping+` `+DESCRIPTOR: Descriptor+` + +[#Example A-1]## *_Descriptor Exception_* + +`+EXCEPTION [ECLIPSELINK – 75]: org.eclipse.persistence.exceptions.DescriptorException+` +`+EXCEPTION DESCRIPTION: The reference class is not specified.+` + +[.msg]#ECLIPSELINK-00001: The attribute [\{0}] is not declared as type +ValueHolderInterface, but its mapping uses indirection.# *Cause*: +attributeName is not declared as type ValueHolderInterface, but the +mapping uses indirection. The mapping is set to use indirection, but the +related attribute is not defined as type ValueHolderInterface. It is +raised on foreign reference mappings. + +*Action*: If you want to use indirection on the mapping, change the +attribute to type ValueHolderInterface. Otherwise, change the mapping +associated with the attribute so that it does not use indirection. + +[.msg]#ECLIPSELINK-00002: The attribute [\{0}] is declared as type +ValueHolderInterface, but its mapping does not use indirection.# +*Cause*: attributeName is declared as type ValueHolderInterface, but +EclipseLink is unable to use indirection. The attribute is defined to be +of type ValueHolderInterface, but the mapping is not set to use +indirection. It is raised on foreign reference mappings. + +*Action*: If you do not want to use indirection on the mapping, change +the attribute so it is not of type ValueHolderInterface. Otherwise, +change the mapping associated with the attribute to use indirection. + +[.msg]#ECLIPSELINK-00006: Attribute name is missing.# *Cause*: The +attribute name is missing or not specified in the mapping definition. + +*Action*: Specify the attribute name in the mapping by calling the +method setAttributeName(String attributeName). + +[.msg]#ECLIPSELINK-00007: The attribute [\{0}] should be of type Vector +(or a type that implements Map or Collection, if using Java 2).# +*Cause*: When using Java 2, the specified attributeName is not defined +as type vector, or a type that implements the Map or Collection +interface. This occurs in one-to-many mapping, many-to-many mapping, and +collection mapping when mapping is set not to use indirection, and the +attribute type is not declared. + +*Action*: Declare the attribute to be of type java.util.Vector. + +[.msg]#ECLIPSELINK-00008: The descriptor [\{0}] has been set to use +inheritance, but a class indicator field has not been defined. \{2}When +using inheritance, a class indicator field or class extraction method +must be set. \{2}Parent Descriptor: [\{1}]# *Cause*: The class indicator +field is defined, but the descriptor is set to use inheritance. When +using inheritance, a class indicator field or class extraction method +must be set. The class indicator field is used to create the right type +of domain object. + +*Action*: Set either a class indicator field or class extraction method. + +[.msg]#ECLIPSELINK-00009: This mapping does not have a direct field name +set.# *Cause*: The direct field name from the target table is not set in +the direct collection mapping. + +*Action*: Specify the direct field name by calling the method +setDirectFieldName(String fieldName). + +[.msg]#ECLIPSELINK-00010: This mapping does not have a field name set.# +*Cause*: The field name is not set in the mapping. It is raised from +direct to field mapping, array mapping, and structure mapping. + +*Action*: Specify the field name by calling the method +setFieldName(String fieldName). + +[.msg]#ECLIPSELINK-00011: The foreign key information for this mapping +is defined incorrectly.# *Cause*: One-to-one mapping foreign key is +defined incorrectly. Multiple foreign key fields were set for one-to-one +mapping by calling the method setForeignKeyFieldName(String fieldName). + +*Action*: Use the method addForeignKeyFieldName(String +sourceForeignKeyName, String targetPrimaryKeyFieldName) to add multiple +foreign key fields. + +[.msg]#ECLIPSELINK-00012: Descriptors must use an identity map in order +to use the "`Check Cache`" existence checking option.# *Cause*: The +descriptor has been set not to use identity map, but the existence +checking is set to be performed on identity map: the descriptor must use +an identity map to use the Check cache does exist option. + +*Action*: Either use identity map, or set the existence checking to some +other option. + +[.msg]#ECLIPSELINK-00013: The instance variable [\{0}] in the object +[\{1}] is inaccessible.# *Cause*: EclipseLink is unable to access the +attributeName instance variable in object objectName. The instance +variable in the domain object is not accessible. This exception is +raised when EclipseLink tries to access the instance variable using the +java.lang.reflect Java package. The error is a purely Java exception, +and EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00014: Problem in cloning the object [\{0}]. The +clone method [\{1}] is not accessible.# *Cause*: EclipseLink is unable +to clone the object domainObject because the clone method methodName is +not accessible. The method name specified using +useCloneCopyPolicy(String cloneMethodName) or the clone() method to +create the clone on the domain object, is not accessible by EclipseLink +using Java reflection. The error is a purely Java exception, and +EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00015: This class does not define a default +constructor, which EclipseLink requires.# *Cause*: The domain class does +not define a public default constructor, which EclipseLink needs to +create new instances of the domain class. + +*Action*: Define a public default constructor or use a different +instantiation policy. + +[.msg]#ECLIPSELINK-00016: The descriptor callback method [\{0}], with +parameter (DescriptorEvent), is inaccessible.# *Cause*: The descriptor +callback method eventMethodName with DescriptorEvent as an argument is +not accessible. This exception is raised when EclipseLink tries to +access the event method using Java reflection. The error is a purely +Java exception, and EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00017: Trying to access the method [\{0}] on the +object [\{1}]. The underlying method is inaccessible.# *Cause*: Attempt +to invoke inaccessible methodName on the object objectName. The +underlying getter method to access an attribute in the domain object is +not accessible. This exception is raised when EclipseLink tries to +access an attribute through a method using the java.lang.reflect Java +package. The error is a purely Java exception, and EclipseLink wraps +only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00018: Illegal method access in a Transformation +mapping using a ValueHolder.# *Cause*: The method used by the +transformation mapping using a value holder is invalid. This exception +is raised when EclipseLink tries to access the method using Java +reflection. The problem occurs when the method base valueholder is +instantiated. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00019: Illegal access while invoking the attribute +method on a Transformation mapping. The underlying method is +inaccessible.# *Cause*: On transformation mapping, the underlying +attribute method that is used to retrieve values from the database row +while reading the transformation mapped attribute is not accessible. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00020: The method [\{0}] is inaccessible.# *Cause*: +On transformation mapping, the method methodName that is used to +retrieve value from the object while writing the transformation mapped +attribute is not accessible. The error is a purely Java exception, and +EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00021: Problem in extracting class from row [\{0}]. +The static method [\{1}], with parameter (DatabaseRow), is not +accessible.# *Cause*: EclipseLink is unable to extract data row, because +EclipseLink cannot access the row specified in the databaseRow argument +of the method. The method to extract class from row on the domain object +is not accessible. The error is a purely Java exception, and EclipseLink +wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00022: Problem in creating new instance. The creation +method [\{0}] is not accessible.# *Cause*: EclipseLink is unable to +create a new instance, because the method methodName that creates +instances on the domain class is not accessible. The error is a purely +Java exception, and EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00023: The descriptor callback method [\{0}], with +parameter (Session), is inaccessible.# *Cause*: The descriptor callback +method eventMethodName with Session as an argument is inaccessible. This +exception is raised when EclipseLink tries to access the event method +using Java reflection. The error is a purely Java exception, and +EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00024: The instance variable [\{0}] in the object +[\{1}] is inaccessible. \{3}Argument: [\{2}]# *Cause*: The attributeName +instance variable in the object objectName is not accessible through +Java reflection. The error is raised by Java, and EclipseLink wraps only +the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00025: The method [\{0}] with argument [\{1}] is not +accessible.# *Cause*: EclipseLink is unable to invoke a method +setMethodName on the object with parameter parameter. The attribute’s +set accessor method is not accessible through Java reflection. The error +is raised by Java and EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00026: Trying to get value for instance variable +[\{0}] of type [\{1}] from the object [\{2}]. The specified object is +not an instance of the class or interface declaring the underlying +field.# *Cause*: EclipseLink is unable to get a value for an instance +variable attributeName of type typeName from the object. The specified +object is not an instance of the class or interface declaring the +underlying field. An object is accessed to get the value of an instance +variable that does not exist. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00027: Trying to invoke the method [\{0}] on the +object [\{1}]. The number of actual and formal parameters differs, or an +unwrapping conversion has failed.# *Cause*: EclipseLink is unable to +invoke method methodName on the object objectName. The get accessor +method declaration on the domain object differs from the one that is +defined. The number of actual and formal parameters differ, or an +unwrapping conversion has failed. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00028: Illegal argument while instantiating a +method-based proxy in a Transformation mapping.# *Cause*: The method +that the method-based proxy uses in a transformation mapping is +receiving invalid arguments when the valueholder is being instantiated. +This exception is raised when EclipseLink tries to access the method +using the java.lang.reflect Java package. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00029: The number of actual and formal parameters +differs, or an unwrapping conversion has failed.# *Cause*: The number of +actual and formal parameters differs, or an unwrapping conversion has +failed. On transformation mapping, the method used to retrieve values +from the database row while reading the transformation mapped attribute +is getting an invalid argument. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00030: The number of actual and formal parameters +differs for method [\{0}], or an unwrapping conversion has failed.# +*Cause*: The number of actual and formal parameters differs for method +methodName, or an unwrapping conversion has failed. On transformation +mapping, the method used to retrieve value from the object while writing +the transformation mapped attribute is getting an invalid argument. The +error is a purely Java exception, and EclipseLink wraps only the +reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00031: The number of actual and formal parameters for +the descriptor callback method [\{0}] differs, or an unwrapping +conversion has failed.# *Cause*: The number of actual and formal +parameters for the descriptor callback method eventMethodName differs, +or an unwrapping conversion has failed. The callback event method is +invoked with an invalid argument. This exception is raised when +EclipseLink tries to invoke the event method using Java reflection. The +error is a purely Java exception, and EclipseLink wraps only the +reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00032: Trying to set value [\{0}] for instance +variable [\{1}] of type [\{2}] in the object. The specified object is +not an instance of the class or interface declaring the underlying +field, or an unwrapping conversion has failed.# *Cause*: An invalid +value is being assigned to the attribute instance variable. EclipseLink +is unable to set a value for an instance variable attributeName of type +typeName in the object. The specified object is not an instance of the +class or interface that is declaring the underlying field, or an +unwrapping conversion has failed. EclipseLink assigns value by using +Java reflection. Java raises the error and EclipseLink wraps only the +reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00033: Trying to invoke [\{0}] on the object [\{1}]. +The number of actual and formal parameters differs, or an unwrapping +conversion has failed.# *Cause*: An illegal argument is being passed to +the attribute’s set accessor method. EclipseLink is unable to invoke +method setMethodName on the object. The number of actual and formal +parameters differs, or an unwrapping conversion has failed. Java raises +the error and EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00034: This class does not define a public default +constructor, or the constructor raised an exception.# *Cause*: The class +does not define a public default constructor, or the constructor raised +an exception. This error occurs when you invoke the default constructor +for the domain object to create a new instance of the object while +building new domain objects if:The class represents an abstract class, +an interface, an array class, a primitive type, or void.The +instantiation fails for some other reason. Java raises the error and +EclipseLink wraps only the reflection exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00035: Invalid event.# *Cause*: Applications should +never encounter this exception. This exception usually occurs at the +time of developing EclipseLink, although in cases, where you write new +mapping, it is possible to get this exception. In direct collection +mapping and many-to-many mapping, the target table and relational table +are populated at the end of the commit process, and if a data +modification event is sent to any other mapping, then this exception is +raised. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00036: Invalid event code [\{0}].# *Cause*: An +application should never encounter this exception. This exception +usually occurs at the time of developing EclipseLink, although in cases, +where you write new mappings, it is possible to get this exception. In +direct collection mapping and many-to-many mapping, the target table and +relational table are populated at the end of the commit process, and if +a data modification event is sent to these two mappings with wrong event +code, then this exception is raised. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00037: Invalid descriptor event code [\{0}].# +*Cause*: An application should never encounter this exception. This +exception usually occurs at the time of developing EclipseLink. The +exception means that the descriptor event manager does not support the +event code passed in the event. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00038: Identity map constructor failed because an +invalid identity map was specified.# *Cause*: The identity map +constructor failed because an invalid identity map was specified. The +identity map class given in the descriptor cannot be instantiated. The +exception is a Java exception that is raised by a Java reflection when +EclipseLink instantiates the identity map class. EclipseLink wraps only +the Java exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00039: This descriptor does not specify a Java +class.# *Cause*: The descriptor does not define a Java class. The Java +class is not specified in the descriptor. + +*Action*: Specify the Java class. + +[.msg]#ECLIPSELINK-00040: Descriptor is missing for [\{0}]. It was +probably not added to the Session.# *Cause*: A descriptor for the +referenced interface is not added to the session. + +*Action*: Add that descriptor to the session. + +[.msg]#ECLIPSELINK-00041: A non-read-only mapping must be defined for +the sequence number field.# *Cause*: A non-read-only mapping is not +defined for the sequence number field. A mapping is required so that +EclipseLink can put and extract values for the primary key. + +*Action*: Define a mapping. + +[.msg]#ECLIPSELINK-00043: Missing class for indicator field value [\{0}] +of type [\{1}].# *Cause*: EclipseLink is missing the class for indicator +field value classFieldValue of type type. There was no class entry found +in the inheritance policy for the indicator field value that was read +from the database. It is likely that the method addClassIndicator(Class +class, Object typeValue) was not called for the field value. The class +and typeValue are stored in a hash table, and later the class is +extracted from the hash table by passing typeValue as a key. Because +Integer(1) is not equivalent to Float(1), this exception occurs when the +type of typeValue is incorrectly specified. + +*Action*: Verify the descriptor. + +[.msg]#ECLIPSELINK-00044: Missing class indicator field from database +row [\{0}].# *Cause*: The class indicator field is missing from the +database row that was read from the database. This is performed in the +inheritance model where after reading rows from the database, child +domain objects are to be constructed depending upon the type indicator +values. + +*Action*: Verify the printed row for correct spelling. + +[.msg]#ECLIPSELINK-00045: Missing mapping for field [\{0}].# *Cause*: +EclipseLink is missing a mapping for field; a mapping for the field is +not specified. + +*Action*: Define a mapping for the field. + +[.msg]#ECLIPSELINK-00046: There should be one non-read-only mapping +defined for the primary key field [\{0}].# *Cause*: A mapping for the +primary key is not specified. There should be one non-read-only mapping +defined for the primary key field. + +*Action*: Define a mapping for the primary key. + +[.msg]#ECLIPSELINK-00047: The multiple table primary key mapping must be +specified when a custom multiple table join is used.# *Cause*: The +multiple table primary key mapping is not specified when a custom +multiple table join is used. If multiple tables are specified in the +descriptor and the join expression is customized, then the primary keys +for all the tables must be specified. If the primary keys are not +specified, then the exception occurs. + +*Action*: Call the method addMultipleTablePrimaryKeyFieldName(String +fieldNameInPrimaryTable, String fieldNameInSecondaryTable) on the +descriptor to set the primary keys. + +[.msg]#ECLIPSELINK-00048: Multiple writable mappings exist for the field +[\{0}]. Only one may be defined as writable, all others must be +specified read-only.# *Cause*: Multiple writable mappings for the field +fieldName are defined in the descriptor. Exactly one must be defined as +writable; the others must be specified as read-only. When multiple write +mappings are defined for the field, EclipseLink is unable to choose the +appropriate mapping for writing the value of the field in the database +row. Therefore, the exception is raised during the validation process of +descriptors. The most common cause of this problem is when the field has +direct-to-field mapping, as well as one-to-one mapping. In this case, +the one-to-one mapping must either be read-only or a target foreign key +reference. + +*Action*: Make one of those mappings read-only. + +[.msg]#ECLIPSELINK-00049: An attribute transformation method name is not +specified for this mapping.# *Cause*: The attribute transformation +method name in the transformation mapping is not specified. This method +is invoked internally by EclipseLink to retrieve value to store in the +domain object. + +*Action*: Define a method and set the method name on the mapping by +calling the method setAttributeTransformation(String methodName). + +[.msg]#ECLIPSELINK-00050: A field name is not set for this mapping.# +*Cause*: No field name is specified in direct-to-field mapping. + +*Action*: Set the field by calling setFieldName(String fieldName). + +[.msg]#ECLIPSELINK-00051: No foreign keys have been specified for this +mapping.# *Cause*: Neither the selection criteria nor the foreign keys +were specified on one-to-one mapping. If the selection criterion is not +specified, then EclipseLink tries to build one from the foreign keys +specified in the mapping. + +*Action*: Specify the fields. + +[.msg]#ECLIPSELINK-00052: No reference key has been specified for this +mapping.# *Cause*: No query key named queryKey is found in descriptor. +No reference key from the target table is specified on direct collection +mapping. + +*Action*: Specify the fields by calling the method +setReferenceKeyFieldName(String fieldName). + +[.msg]#ECLIPSELINK-00053: The relation table name is not set for this +mapping.# *Cause*: The relation table name is not set in this +many-to-many mapping. + +*Action*: Set the relation table name by calling the method +setRelationTableName(String tableName). + +[.msg]#ECLIPSELINK-00054: There are no source relation keys specified +for this mapping.# *Cause*: There are no source relation keys specified +in this many-to-many mapping. + +*Action*: Add source relation keys to the mapping. + +[.msg]#ECLIPSELINK-00055: The descriptor callback method [\{0}] cannot +be found. It must take a Session or a DescriptorEvent as its argument.# +*Cause*: EclipseLink cannot find the descriptor callback method on the +domain class. It must take a Session or a DescriptorEvent as its +argument. EclipseLink tries to invoke the method using Java reflection. +It is a Java exception and EclipseLink is wrapping only the main +exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00056: The method [\{0}] with parameters (Record) or +(Record, Session) is not found.# *Cause*: EclipseLink cannot find the +method methodName(Record databaseRow) or methodName(Record databaseRow, +Session session). EclipseLink wraps the Java reflection exception that +is caused when the method is being created from the method name. This +method is set by calling setAttributeMethodName(String aMethodName). + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00057: Inaccessible constructor.# *Cause*: The +constructor is inaccessible to EclipseLink. EclipseLink wraps the Java +reflection exception that is caused when it is creating a new instance +of the domain. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00058: The method [\{0}] with parameters () or +(Session) not found.# *Cause*: EclipseLink failed to find a method with +signature methodName() or +methodName(org.eclipse.persistence.sessions.Session). EclipseLink wraps +the Java reflection exception that was raised by its attempt to create a +Method type (java.lang.reflect) from the method names in the +transformation mapping. + +*Action*: Ensure that the method methodName is defined on the domain +class that owns the attribute mapped by the transformation mapping. + +[.msg]#ECLIPSELINK-00059: The instance variable [\{0}] is not defined in +the domain class [\{1}], or it is not accessible.# *Cause*: The instance +variable attributeName is not defined in the domain class, or it is not +accessible. EclipseLink wraps the Java reflection exception that is +caused when it is creating a Field type (java.lang.reflect.Field) from +the attribute name. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00060: The method [\{0}] or [\{1}] is not defined in +the object [\{2}].# *Cause*: The method setMethodName or getMethodName +is not defined for the attribute in the domain class javaClassName, or +it is not accessible. EclipseLink wraps the Java reflection exception +that is caused when it is creating a Method type from the method name. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00061: The static class extraction method [\{0}], +with parameter (Record), does not exist, or is not accessible.# *Cause*: +The static class extraction method methodName(Record databaseRow) does +not exist, or is not accessible. A Java reflection exception wrapped in +an EclipseLink exception is raised when a class extraction method is +being created from the method name in the inheritance policy. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00062: The clone method [\{0}], with no parameters, +does not exist, or is not accessible.# *Cause*: The clone method +methodName() does not exist, or is not accessible. A Java reflection +exception wrapped in an EclipseLink exception is raised when a method to +create clones is being created from the method name in the copy policy. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00063: The instance creation method [\{0}], with no +parameters, does not exist, or is not accessible.# *Cause*: The instance +creation method methodName() does not exist, or is not accessible. A +Java reflection exception wrapped in an EclipseLink exception is raised +when a method to create the new instance is being created from the +method name in the instantiation policy. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00064: No target foreign keys have been specified for +this mapping.# *Cause*: The foreign keys in the target table are not +specified in one-to-many mappings. These fields are not required if a +selection criterion is given in the mapping, but otherwise they must be +specified. + +*Action*: Set target foreign keys or selection criteria. + +[.msg]#ECLIPSELINK-00065: No target relation keys have been specified +for this mapping.# *Cause*: There are no target relation keys specified +in many-to-many mappings. + +*Action*: Call method addTargetRelationKeyFieldName(String +targetRelationKeyFieldName, String targetPrimaryKeyFieldName) to set the +fields. + +[.msg]#ECLIPSELINK-00066: Could not deserialize object from byte array.# +*Cause*: Attempt to deserialize an object from the byte array that is +read from the database. The exception is raised when the serialized +object mapping is converting the byte array into an object. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00067: Could not serialize object into byte array.# +*Cause*: Attempt to serialize an object into a byte array. The exception +is raised when a serialized object mapping is converting the object into +a byte array. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00068: The value of an aggregate in object [\{0}] is +null. Null values not allowed for Aggregate mappings unless "`Allow +Null`" is specified.# *Cause*: The value of the aggregate in the source +object object is null. Null values are not allowed for aggregate +mappings unless allow null is specified in the aggregate mapping. + +*Action*: Call the mapping method allowNull. Provide parameters only if +you are making a distinction between foo() and foo(integer). + +[.msg]#ECLIPSELINK-00069: A NullPointerException was thrown while +extracting a value from the instance variable [\{0}] in the object +[\{1}].# *Cause*: An object is accessed to get the value of an instance +variable through Java reflection. This exception is raised only on some +JVMs. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00070: A NullPointerException was thrown while +extracting a value through the method [\{0}] in the object [\{1}].# +*Cause*: The getter method is invoked to get the value of an attribute +through Java reflection. This exception is raised only on some JVM. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00071: A NullPointerException was thrown while +setting the value of the instance variable [\{0}] to the value [\{1}].# +*Cause*: A NullPointerException has been raised while setting the value +of the attributeName instance variable in the object to value. An object +is accessed to set the value of an instance variable through Java +reflection. This exception is raised only on some JVMs. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00072: A NullPointerException was thrown while +setting a value through the method [\{0}] with argument [\{1}].# +*Cause*: A NullPointerException has been raised while setting the value +through setMethodName method in the object with an argument argument. +The set accessor method is invoked to set the value of an attribute +through Java reflection. This exception is raised only on some JVMs. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00073: Cannot find descriptor for parent class +[\{0}].# *Cause*: EclipseLink is unable to find the descriptor for the +parent class. The descriptor of a subclass has no parent descriptor. + +*Action*: The method setParentClass(Class parentClass) must be called on +the subclass descriptor. + +[.msg]#ECLIPSELINK-00074: The primary key fields are not set for this +descriptor.# *Cause*: The primary key fields are not set for this +descriptor. + +*Action*: Add primary key field names using method +setPrimaryKeyFieldName(String fieldName). + +[.msg]#ECLIPSELINK-00075: The reference class is not specified for this +descriptor.# *Cause*: The reference class is not specified in the +foreign reference mapping. + +*Action*: Set the reference class by calling the method +setReferenceClass(Class aClass). + +[.msg]#ECLIPSELINK-00077: The reference descriptor for [\{0}] should be +set to be an Aggregate descriptor.# *Cause*: The referenced descriptor +for class className is not set to an aggregate descriptor. An aggregate +mapping should always reference a descriptor that is aggregate. + +*Action*: Call the method descriptorIsAggregate on the referenced +descriptor. + +[.msg]#ECLIPSELINK-00078: The reference field [\{0}] for this mapping +must exist in the reference table.# *Cause*: The table for the reference +field is not the reference table. If the reference field name that is +specified in the direct collection mapping is qualified with the table +name, then the table name should match the reference table name. + +*Action*: Qualify the field with the proper name, or change the +reference table name. + +[.msg]#ECLIPSELINK-00079: The reference table is not specified for this +mapping.# *Cause*: The reference table name in the direct collection +mapping is not specified. + +*Action*: Use the method setReferenceTableName(String tableName) on the +mapping to set the table name. + +[.msg]#ECLIPSELINK-00080: The relation key field [\{0}] for this mapping +must exist in the relation table.# *Cause*: The table for the relation +key field is not the relation table. If the source and target relation +fields names that are specified in the many-to-many mapping are +qualified with the table name, then the table name should match the +relation table name. + +*Action*: Qualify the field with the proper name, or change the relation +table name. + +[.msg]#ECLIPSELINK-00081: The method [\{0}] should return the type of +the mapped attribute, not void.# *Cause*: The method attributeMethodName +that is specified in the transformation mapping does not have a return +type set in the attribute, as it should because this method is used to +extract value from the database row. + +*Action*: Verify the method and make appropriate changes. + +[.msg]#ECLIPSELINK-00082: The descriptor callback method [\{0}], with +parameter (DescriptorEvent), is not accessible.# *Cause*: The descriptor +callback method with DescriptorEvent as an argument is not accessible. +Java raises a security exception when a Method type is created from the +method name using Java reflection. The method is a descriptor event +callback on the domain object that takes DescriptorEvent as its +parameter. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00083: The descriptor callback method [\{0}], with +parameter (Session), is not accessible.# *Cause*: The descriptor +callback method with Session as an argument is not accessible. Java +raises a security exception when a Method type is created from the +method name using Java reflection. The method is a descriptor event +callback on the domain object, which takes class and session as its +parameters. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00084: The method [\{0}], with parameters (Record) or +(Record, Session), is not accessible.# *Cause*: Access to the method +methodName(Record databaseRow) or methodName(Record databaseRow, Session +session) has been denied. Java raises a security exception when a Method +type is created from the attribute method name using Java reflection. +The attribute method that is specified in the transformation mapping is +used to extract value from the database row and set by calling +setAttributeTransformation(String methodName). + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00085: The method [\{0}], with parameters () or +(Session), is not accessible.# *Cause*: EclipseLink failed to find a +method with signature methodName() or +methodName(org.eclipse.persistence.sessions.Session). Java raises a +security exception when a Method type is created from the method name +using Java reflection. These are the methods that extract the field +value from the domain object in the transformation mapping. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00086: The instance variable [\{0}] in the class +[\{1}] is not accessible.# *Cause*: Access to the instance variable +attributeName in the class javaClassName is denied. Java raises a +security exception when creating a Field type from the given attribute +name using Java reflection. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00087: The methods [\{0}], [\{1}] in the object +[\{2}] are not accessible# *Cause*: The methods setMethodName and +getMethodName in the object javaClassName are inaccessible. Java raises +a security exception when creating a Method type from the given +attribute accessor method name using Java reflection. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00088: The static class extraction method [\{0}], +with parameter (Record), is not accessible.# *Cause*: The static class +extraction method methodName(Record databaseRow) is not accessible. Java +raises a security exception when creating a Method type from the given +class extraction method name using Java reflection. The method is used +to extract the class from the database row in the inheritance policy. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00089: The clone method [\{0}], with no parameters, +is not accessible.# *Cause*: The clone method methodName() is +inaccessible. Using ClassDescriptor method useCloneCopyPolicy +(java.lang.String methodName), you can specify that the creation of +clones within a unit of work is done by sending the methodName method to +the original object. If the clone method methodName with no arguments is +inaccessible (your application does not have sufficient privileges to +call the method), Java raises a security exception when reflectively +accessing the method with the given method name using the +java.lang.reflect Java package. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00090: The instance creation method [\{0}], with no +parameters, is not accessible.# *Cause*: The instance creation method +methodName() is inaccessible. Using any of the ClassDescriptor methods +useFactoryInstantiationPolicy (java.lang.Class factoryClass, +java.lang.String methodName), useFactoryInstantiationPolicy +(java.lang.Class factoryClass, java.lang.String methodName, +java.lang.String factoryMethodName), useFactoryInstantiationPolicy +(java.lang.Object factory, java.lang.String methodName), or +useMethodInstantiationPolicy(java.lang.String staticMethodName), you can +specify how new instances are created. If any of the methods or factory +methods are inaccessible (your application does not have sufficient +privileges to call the method), Java raises a security exception when +reflectively accessing the method with the given method name using the +java.lang.reflect Java package. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00091: To use sequence-generated IDs, both the +"`Sequence Number Name`" and "`Sequence Number Field Name`" properties +must be set for this descriptor.# *Cause*: Either the sequenceNumberName +or the sequenceNumberFieldName property is not set. To use +sequence-generated IDs, both the sequenceNumberName and +sequenceNumberFieldName properties must be set for the descriptor. + +*Action*: To use sequence-generated IDs, set both the sequence number +name and field name properties. + +[.msg]#ECLIPSELINK-00092: The size of the target’’s primary key does not +match the size of the foreign key.# *Cause*: The size of the primary +keys on the target table does not match the size of the foreign keys on +the source in one-to-one mapping. + +*Action*: Verify the mapping and the reference descriptor’s primary +keys. + +[.msg]#ECLIPSELINK-00093: The table [\{0}] is not present in this +descriptor.# *Cause*: The table tableName is not present in the +descriptor. + +*Action*: Verify the qualified field names that are specified in the +mappings and descriptor so that any fields that are qualified with the +table name reference the correct table. + +[.msg]#ECLIPSELINK-00094: Descriptors must have a table name defined.# +*Cause*: No table is specified in the descriptor. The descriptor must +have a table name defined. + +*Action*: Call the method addTableName(String tableName) or +setTableName(String tableName) to set the tables on the descriptor. + +[.msg]#ECLIPSELINK-00096: The number of target keys does not match the +number of source keys.# *Cause*: The size of the foreign keys on the +target table does not match the size of the source keys on the source +table in the one-to-many mapping. + +*Action*: Verify the mapping. + +[.msg]#ECLIPSELINK-00097: Problem cloning the object [\{0}]. The clone +method [\{0}] triggered an exception.# *Cause*: EclipseLink has +encountered a problem in cloning the object domainObject clone method. +The methodName triggered an exception. Java raises this exception when +the cloned object is invoked while the object is being cloned. The clone +method is specified on the copy policy that is usually invoked to create +clones in unit of work. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00098: The underlying descriptor callback method +[\{0}], with parameter (DescriptorEvent), triggered an exception.# +*Cause*: A descriptor callback method eventMethodName(DescriptorEvent +event) is not accessible. The exception occurs when the descriptor event +method is invoked using Java reflection. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00099: The method [\{0}] on the object [\{1}] +triggered an exception.# *Cause*: The method methodName on the object +objectName is throwing an exception. Java is throwing an exception while +getting an attribute value from the object through a method accessor. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00100: A method has triggered an exception.# *Cause*: +A method has raised an exception. Java raises this exception while +instantiating a method based proxy and instantiating transformation +mapping. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00101: The underlying method triggered an exception.# +*Cause*: The underlying method raises an exception. Java is throwing an +exception while invoking an attribute transformation method on +transformation mapping. The method is invoked to extract value from the +database row to set into the domain object. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00102: The method [\{0}] triggered an exception.# +*Cause*: The method methodName is throwing an exception. Java is +throwing exception while invoking field transformation method on +transformation mapping. The method is invoked to extract value from the +domain object to set into the database row. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00103: Problem in extracting class from row [\{0}], +using static method [\{1}], with parameter (DatabaseRow). An exception +was triggered.# *Cause*: EclipseLink encountered a problem extracting +the class type from row rowName while invoking a class extraction +method. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00104: Problem in creating new instance using +creation method [\{0}]. The creation method triggered an exception.# +*Cause*: EclipseLink is unable to create a new instance. The creation +method methodName caused an exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00105: The underlying descriptor callback method +[\{0}], with parameter (Session), triggered an exception.# *Cause*: The +underlying descriptor callback method eventMethodName(Session session) +raises an exception. Java is throwing an exception while invoking a +descriptor event method that takes a session as its parameter. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00106: The method [\{0}] on the object is throwing an +exception. \{2}Argument: [\{1}]# *Cause*: The method setMethodName on +the object raises an exception. Java is throwing an exception while +invoking a set accessor method on the domain object to set an attribute +value into the domain object. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00108: Cannot find value in class indicator mapping +in parent descriptor [\{0}].# *Cause*: The indicator value is not found +in the class indicator mapping in the parent descriptor for the class. + +*Action*: Verify the addClassIndicator(Class childClass, Object +typeValue) on the inheritance policy. + +[.msg]#ECLIPSELINK-00109: This descriptor should not have a write lock +field defined because it is a child descriptor. It inherits its parent +descriptor’’s write lock field.# *Cause*: The child descriptor has a +write-lock field defined. This is unnecessary, because it inherits any +required locking from the parent descriptor. + +*Action*: Check your child descriptor, and remove the field. + +[.msg]#ECLIPSELINK-00110: Descriptor is missing for class [\{0}].# +*Cause*: The descriptor for the reference class className is missing +from the mapping. + +*Action*: Verify the session to see if the descriptor for the reference +class was added. + +[.msg]#ECLIPSELINK-00111: Multiple table primary key field names must be +fully qualified.# *Cause*: Multiple table primary key field names are +not fully qualified. These field names are given on the descriptor if it +has more than one table. + +*Action*: Specify the field names with the table name. + +[.msg]#ECLIPSELINK-00112: Only one table can be added by using +setTableName(String). Use addTableName(String) to add multiple tables to +a descriptor.# *Cause*: Attempt to enter more than one table through +this method. + +*Action*: Use the method addTableName(String tableName) to add multiple +tables to the descriptor. + +[.msg]#ECLIPSELINK-00113: The constructor was inaccessible.# *Cause*: +The constructor is inaccessible. Java is throwing this exception while +invoking a default constructor to create new instances of the domain +object. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00114: Problem in creating new instance using +creation method [\{0}]. The creation method is not accessible.# *Cause*: +The new instance methodName creation method is inaccessible. Java is +throwing an exception while calling a method to a build new instance of +the domain object. This method is given by the user to override the +default behavior of creating new instances through a class constructor. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-00115: No conversion value provided for the attribute +[\{0}].# *Cause*: The field conversion value for the attribute value +attributeValue was not given in the object type mapping. + +*Action*: Verify the attribute value, and provide a corresponding field +value in the mapping. + +[.msg]#ECLIPSELINK-00116: No conversion value provided for the value +[\{0}] in field [\{1}].# *Cause*: The attribute conversion value for the +fieldValue was not given in the object type mapping. + +*Action*: Verify the field value, and provide a corresponding attribute +value in the mapping. + +[.msg]#ECLIPSELINK-00118: The object [\{0}] must not have read-only +mappings to its write lock fields.# *Cause*: The domain object className +cannot have a read-only mapping for the write-lock fields when the +version value is stored in the object. + +*Action*: Verify the mappings on the write-lock fields. + +[.msg]#ECLIPSELINK-00119: The object’’s [\{0}] mappings to its write +lock fields must be read-only.# *Cause*: The domain object className +does not have a read-only mapping for the write-lock fields when the +version value is stored in the cache. + +*Action*: Verify the mappings on write-lock fields. + +[.msg]#ECLIPSELINK-00120: The query key [\{0}] is defined in the parent +descriptor [\{1}], but not in the child descriptor [\{2}].# *Cause*: The +query key queryKeyName is defined in the parent descriptor, but not in +the child descriptor. The descriptor has not defined the abstract query +key. + +*Action*: Define any class that implements the interface descriptor by +the abstract query key in the interface descriptor. + +[.msg]#ECLIPSELINK-00122: setExistenceCheck() with argument [\{0}] is +not understood.# *Cause*: The interface descriptor parent does not have +at least one abstract query key defined. The string given to the method +setExistenceChecking(String token) is not understood. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00125: The mapping for the attribute [\{0}] uses +indirection, and so must be initialized to a new ValueHolder. Currently +the value is: [\{1}].# *Cause*: The mapping for the attribute +getAttributeName() uses indirection and must be initialized to a new +value holder. + +*Action*: Ensure that the mapping uses indirection and that the +attribute is initialized to a new value holder. + +[.msg]#ECLIPSELINK-00126: No subclass matches this class [\{0}] for this +Aggregate mapping with inheritance.# *Cause*: No subclass matches this +class theClass when inheritance is in aggregate relationship mapping. + +*Action*: Verify the subclass and the relationship mapping. + +[.msg]#ECLIPSELINK-00127: The get method for the attribute [\{0}] does +not return a ValueHolderInterface, but the mapping uses indirection.# +*Cause*: The return type of the method used to get the attribute +getAttributeName() of a mapping is not declared as type +ValueHolderInterface, but the mapping is using indirection. + +*Action*: Verify that the method used to get the attribute named +getAttributeName() of DatabaseMapping returns a value holder, or change +the mapping so it does not use indirection. + +[.msg]#ECLIPSELINK-00128: The get method for the attribute [\{0}] +returns a ValueHolderInterface, but the mapping does not use +indirection.# *Cause*: The return type of the method used to get the +attribute getAttributeName() of DatabaseMapping is declared as type +ValueHolderInterface, but the mapping is not using indirection. + +*Action*: Ensure that the mapping is using indirection, or change the +return type from value holder. + +[.msg]#ECLIPSELINK-00129: The set method for the attribute [\{0}] does +not take a ValueHolderInterface as its parameter, but the mapping uses +indirection.# *Cause*: The return type of the method used to set the +attribute getAttributeName() of DatabaseMapping is not declared as type +ValueHolderInterface, but the mapping is using indirection. + +*Action*: Ensure that the set method parameter is declared as a +valueholder, or change the mapping so it does not use indirection. + +[.msg]#ECLIPSELINK-00130: The set method for the attribute [\{0}] takes +a ValueHolderInterface as its parameter, but the mapping does not use +indirection.# *Cause*: The return type of the method used to set the +attribute getAttributeName() of DatabaseMapping is declared as type +ValueHolderInterface, but the mapping is not using indirection. + +*Action*: Ensure that the mapping is changed to use indirection, or that +the method parameter is not declared as a value holder. + +[.msg]#ECLIPSELINK-00131: The get method for the attribute [\{0}] should +return a Vector (or a type that implements Map or Collection, if using +Java 2).# *Cause*: The return type of the method used to get the +attribute getAttributeName() of DatabaseMapping is not declared as type +Vector (or a type that implements the Map or Collection interface if +using Java 2). + +*Action*: Declare the return type of the method used to get the +attribute getAttributeName() of DatabaseMapping as type Vector (or a +type that implements the map or collection interface if using Java 2). + +[.msg]#ECLIPSELINK-00133: The set method for the attribute [\{0}] should +take a Vector as its parameter (or a type that implements Map or +Collection, if using Java 2).# *Cause*: The parameter type of the method +used to set the attribute getAttributeName() of DatabaseMapping is not +declared as type Vector (or a type that implements the map or collection +interface, if using Java 2). + +*Action*: Declare the parameter type of the method used to set the +attribute getAttributeName() of DatabaseMapping as type Vector (or a +type that implements the Map or Collection interface, if using Java 2). + +[.msg]#ECLIPSELINK-00135: The multiple table foreign key relationship +refers to an unknown table [\{0}].# *Cause*: The table in the multiple +table foreign key relationship refers to an unknown table. + +*Action*: Verify the table name. + +[.msg]#ECLIPSELINK-00138: The attribute [\{0}] is not declared as a +superclass of [\{1}], but the mapping uses transparent indirection.# +*Cause*: The attribute getAttributeName() of DatabaseMapping is not +declared as a supertype of validTypeName, but the mapping is using +transparent indirection. + +*Action*: Verify the attribute’s type and the mapping setup. + +[.msg]#ECLIPSELINK-00139: The get method for the attribute [\{0}] does +not return a superclass of [\{1}], but the mapping uses transparent +indirection.# *Cause*: The return type of the method used to get the +attribute getAttributeName() of DatabaseMapping is not declared as a +super-type of validTypeName, but the mapping is using transparent +indirection. + +*Action*: Verify the attribute’s type and the mapping setup. + +[.msg]#ECLIPSELINK-00140: The set method for the attribute [\{0}] does +not take a superclass of [\{1}] as its parameter, but the mapping uses +transparent indirection.# *Cause*: The parameter type of the method used +to set the attribute getAttributeName() of DatabaseMapping is not +declared as a supertype of validTypeName, but the mapping is using +transparent indirection. + +*Action*: Verify the attribute’s type and the mapping setup. + +[.msg]#ECLIPSELINK-00141: The field [\{0}] is not present in the table +[\{1}] in the database.# *Cause*: The field fieldname is not present in +the table tableName in the database. + +*Action*: Verify the field name for the attribute. + +[.msg]#ECLIPSELINK-00142: The table [\{0}] is not present in the +database.# *Cause*: The table whose name is provided by the Descriptor +method getTableName is not present in the database. + +*Action*: Verify the table name for the descriptor. + +[.msg]#ECLIPSELINK-00143: The multiple table insert order Vector +specified, [\{0}], has more or fewer tables than are specified in the +descriptor. \{2}All of the tables [\{1}] must be included in the insert +order Vector.# *Cause*: The multiple table insert order vector specified +the Descriptor method getMultipleTableInsertOrder has fewer or more +tables than are specified in the Descriptor method getTables. All the +tables must be included in the insert order vector. + +*Action*: Ensure that all table names for the descriptor are present and +that there are no extra tables. + +[.msg]#ECLIPSELINK-00144: Transparent indirection can only be used with +CollectionMappings.# *Cause*: Transparent indirection is being used with +a mapping other than a CollectionMapping. + +*Action*: Verify the mapping. It must be a collection mapping. + +[.msg]#ECLIPSELINK-00145: The indirect container class [\{0}] must +implement the constructor [\{1}] with parameter (ValueHolderInterface).# +*Cause*: The indirect container class does not implement the +constructor. + +*Action*: Implement the constructor for the container. + +[.msg]#ECLIPSELINK-00146: The indirect container class [\{0}] could not +be instantiated using the constructor \{1}(ValueHolderInterface).# +*Cause*: EclipseLink is unable to instantiate the indirect container +class using the constructor. + +*Action*: Validate the constructor for the indirect container class. + +[.msg]#ECLIPSELINK-00147: The container policy [\{0}] should only be +used in JDK 1.1.x. It was instantiated for [\{1}].# *Cause*: You have +used a container policy with an incompatible version of the JDK. This +container policy must only be used with JDK 1.3.1 or later. + +*Action*: Validate the container policy being used. + +[.msg]#ECLIPSELINK-00148: The container policy [\{0}] is not compatible +with transparent indirection.# *Cause*: The container policy is +incompatible with transparent indirection. + +*Action*: Change the container policy to be compatible with transparent +indirection, or do not use transparent indirection. + +[.msg]#ECLIPSELINK-00149: NoIndirectionPolicy objects should not receive +this message.# *Cause*: NoIndirectionPolicy object calls this method. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00150: The mapping for the attribute [\{0}] uses +transparent indirection so the attribute [\{0}] must be initialized to +an appropriate container. Currently the value is [\{1}]. \{2} - Must be +instance of an implementor of Collection or Map.# *Cause*: The mapping +for the attribute getAttributeName() of DatabaseMapping uses transparent +indirection and must be initialized to an appropriate container. + +*Action*: Initialize the mapping to an appropriate container. + +[.msg]#ECLIPSELINK-00151: The operation [\{0}] is invalid for this +mapping.# *Cause*: An invalid mapping operation has been used. + +*Action*: See the documentation for valid mapping operations. + +[.msg]#ECLIPSELINK-00152: The operation [\{1}] is invalid for this +indirection policy [\{0}].# *Cause*: An invalid indirection policy +operation has been used. + +*Action*: See the documentation for valid indirection policy operations. + +[.msg]#ECLIPSELINK-00153: The reference descriptor for [\{0}] should be +set to be an Aggregate Collection descriptor.# *Cause*: The reference +descriptor for className is not set to an aggregate collection +descriptor. + +*Action*: Set the reference descriptor to an aggregate collection +descriptor. + +[.msg]#ECLIPSELINK-00154: The indirection container class [\{0}] does +not implement IndirectContainer.# *Cause*: An invalid indirection +container class has been used. + +*Action*: Verify the container class. + +[.msg]#ECLIPSELINK-00155: This mapping does not include a foreign key +field linked to the primary key field [\{0}].# *Cause*: The mapping does +not include a foreign key field linked to the primary key field. + +*Action*: Link the foreign key to the appropriate primary key. + +[.msg]#ECLIPSELINK-00156: The structure name is not set for this +mapping.# *Cause*: The structure name is not set. + +*Action*: Set the structure name appropriately. + +[.msg]#ECLIPSELINK-00157: Normal descriptors do not support +non-relational extensions.# *Cause*: Relational descriptors do not +support nonrelational extensions. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00158: This descriptor’’s parent class has been set +to itself.# *Cause*: The descriptor’s parent class has been set to +itself. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-00159: Proxy indirection is available only in JDK +1.3-compliant or higher virtual machines.# *Cause*: An attempt to use +proxy indirection has been made, but JDK 1.3.1 or later is not being +used. + +*Action*: Use JDK 1.3.1 or later. + +[.msg]#ECLIPSELINK-00160: The attribute [\{0}] of class [\{1}] is typed +as [\{2}], which was not specified in the list of interfaces given to +the useProxyIndirection() method. \{4}Valid interfaces are: [\{3}].# +*Cause*: The attribute was not specified in the list of interfaces given +to use proxy indirection. + +*Action*: Verify the attribute. + +[.msg]#ECLIPSELINK-00161: The method [\{0}] in class [\{1}] returns a +value of type [\{2}], which was not specified in the list of interfaces +given to the useProxyIndirection() method. \{4}Valid interfaces are: +[\{3}].# *Cause*: The return type for the indirection policy is invalid +for the indirection policy. + +*Action*: Ensure that the parameter type of the getter method is correct +for the indirection policy. + +[.msg]#ECLIPSELINK-00162: The method [\{0}] in class [\{1}] takes a +parameter of type [\{2}], which was not specified in the list of +interfaces given to the useProxyIndirection() method.\{4}Valid +interfaces are: [\{3}].# *Cause*: The parameter for the setter method is +incorrect for the indirection type. + +*Action*: Ensure that the parameter type of the setter method is correct +for the indirection policy. + +[.msg]#ECLIPSELINK-00163: This mapping’’s attribute class does not match +the collection class. [\{1}] cannot be assigned to [\{0}].# *Cause*: The +container policy is invalid for the collection type. + +*Action*: Ensure that the container policy is correct for the collection +type. + +[.msg]#ECLIPSELINK-00164: The amendment method [\{1}], in amendment +class [\{0}], is invalid, not public, or cannot be found. \{2}Descriptor +amendment methods must be declared "`public static void`" with +(ClassDescriptor) as the single parameter.# *Cause*: The amendment +method that is provided is invalid, not public, or cannot be found. + +*Action*: Ensure that the amendment method is public, static, returns +void, and has a single argument: Descriptor. + +[.msg]#ECLIPSELINK-00165: This descriptor’’s amendment method [\{1}] in +amendment class [\{0}] triggered an exception.# *Cause*: The specified +amendment method threw an exception. + +*Action*: Examine the returned exception for further information. + +[.msg]#ECLIPSELINK-00166: There is no mapping for the attribute [\{0}].# +*Cause*: There is no mapping for the attribute. + +*Action*: Validate the mapping and attribute. + +[.msg]#ECLIPSELINK-00167: A valid constructor was not found for the +indirection container class [\{0}].# *Cause*: A valid constructor was +not found for the indirection container class. + +*Action*: Add a default constructor or a constructor with a +ValueHolderInterface in the container class. + +[.msg]#ECLIPSELINK-00168: Problem in creating new instance using the +default constructor. The default constructor triggered an exception.# +*Cause*: The constructor is missing. + +*Action*: Create the required constructor. + +[.msg]#ECLIPSELINK-00169: Problem in creating new instance of factory +using the default constructor. The default constructor triggered an +exception.# *Cause*: The constructor is missing. + +*Action*: Create the required constructor. + +[.msg]#ECLIPSELINK-00170: Problem (illegal access) in creating new +instance of factory using the default constructor.# *Cause*: Permissions +do not allow access to the constructor. + +*Action*: Adjust the Java security permissions to permit access to the +constructor. + +[.msg]#ECLIPSELINK-00171: The factory class does not define a public +default constructor, or the constructor raised an exception.# *Cause*: +An instantiation failed inside the associated constructor. + +*Action*: Determine which objects are being instantiated, and verify +that all are instantiated properly. + +[.msg]#ECLIPSELINK-00172: Factory constructor not found.# *Cause*: A +method call from inside the constructor is invalid because this method +does not exist. + +*Action*: Ensure that the factory has a default constructor for the +called method. + +[.msg]#ECLIPSELINK-00173: The factory constructor was inaccessible.# +*Cause*: A method on a null object was called from inside a constructor. +The factory constructor was inaccessible. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-00174: Problem in creating factory. The creation +method [\{0}] is not accessible.# *Cause*: A method was called on an +object from inside a factory instantiation, and Java has determined this +method to be invalid. + +*Action*: Determine why the method is invalid, and replace the method +with a valid one. + +[.msg]#ECLIPSELINK-00175: Problem creating factory using creation method +[\{0}]. The creation method triggered an exception.# *Cause*: A problem +was encountered creating factory using creation method. The creation +method triggered an exception. + +*Action*: Examine the exception and take the corresponding action. + +[.msg]#ECLIPSELINK-00176: Problem in creating factory using creation +method [\{0}]. The creation method is not accessible.# *Cause*: A method +called to instantiate a factory threw a NullPointerException. The +creation method is not accessible. + +*Action*: Do not use that method to instantiate a factory. + +[.msg]#ECLIPSELINK-00177: Mapping is missing for the attribute: [\{0}].# +*Cause*: Mapping is missing for the attribute attributeName. + +*Action*: The attribute must be mapped. + +[.msg]#ECLIPSELINK-00178: Cannot find mapping for attribute [\{0}] in +entity bean [\{1}]. The attribute must mapped.# *Cause*: Cannot find +mapping for an attribute attributeName in an entity bean beanName. + +*Action*: Map the attribute. + +[.msg]#ECLIPSELINK-00179: The attribute, [\{0}] uses Bidirectional +Relationship Maintenance, but has ContainerPolicy, [\{1}] which does not +support it. The attribute should be mapped with a different collection +type.# *Cause*: The attribute uses bidirectional relationship +maintenance, but has ContainerPolicy, which does not support it. + +*Action*: The attribute must be mapped with a different collection type. + +[.msg]#ECLIPSELINK-00181: The AttributeTransformer class, [\{0}] cannot +be found.# *Cause*: The AttributeTransformer class cannot be found. + +*Action*: Ensure that the AttributeTransformer class exists and is on +the classpath. + +[.msg]#ECLIPSELINK-00182: The FieldTransformer class, [\{0}] cannot be +found.# *Cause*: The FieldTransformer class cannot be found. + +*Action*: Ensure that the FieldTransformer class exists and is on the +classpath. + +[.msg]#ECLIPSELINK-00183: The class, [\{0}] cannot be used as an +AttributeTransformer.# *Cause*: Invalid use of a class className as an +AttributeTransformer. + +*Action*: Examine the internal exception stack trace and make the +appropriate correction. + +[.msg]#ECLIPSELINK-00184: The class, [\{0}] cannot be used as a +FieldTransformer.# *Cause*: Invalid use of a class className as a +FieldTransformer. + +*Action*: Do not use the class as a FieldTransformer. + +[.msg]#ECLIPSELINK-00185: ReturningPolicy contains field, [\{0}] with +two different types: [\{1}] and [\{2}].# *Cause*: ReturningPolicy +contains field with two different types. + +*Action*: The field was added to ReturningPolicy twice with different +types. The field must be added to ReturningPolicy once. You must remove +excessive addFieldForInsert and/or addInsertField calls. + +[.msg]#ECLIPSELINK-00186: ReturningPolicy contains field, [\{0}] added +twice: using addInsertField and addInsertFieldReturnOnly.# *Cause*: +ReturningPolicy contains field that has been added twice using +addInsertField and addInsertFieldReturnOnly. + +*Action*: A field must be added to ReturningPolicy only once. You must +remove excessive addField calls. + +[.msg]#ECLIPSELINK-00187: ReturningPolicy contains field, [\{0}] with +type [\{1}], but the same field in descriptor has type [\{2}].# *Cause*: +ReturningPolicy contains field with type Type, but the same field in +descriptor has type differentType. + +*Action*: Specify field type in addField method only in the event that +it cannot be obtained from the descriptor. + +[.msg]#ECLIPSELINK-00188: ReturningPolicy contains unmapped field, +[\{0}] which requires type.# *Cause*: ReturningPolicy contains unmapped +field fieldName that requires type. + +*Action*: You must specify field type in the addField method. + +[.msg]#ECLIPSELINK-00189: ReturningPolicy contains mapped field, [\{0}] +which requires type.# *Cause*: ReturningPolicy contains mapped field +fieldName that requires type. + +*Action*: You must specify field type in the addField method. + +[.msg]#ECLIPSELINK-00190: ReturningPolicy contains field, [\{0}] mapped +with [\{1}] mapping which is not supported.# *Cause*: ReturningPolicy +contains a field that is mapped with unsupported mapping. + +*Action*: You cannot use ReturningPolicy with this field. Do not add it +to ReturningPolicy. + +[.msg]#ECLIPSELINK-00191: ReturningPolicy contains field, [\{0}] which +is not supported: it is either sequence field, or class type indicator, +or used for locking.# *Cause*: ReturningPolicy contains a field +fieldName that is not supported. Field is either sequence field, class +type indicator, or used for locking. + +*Action*: You cannot use ReturningPolicy with this field. Do not add it +to ReturningPolicy. + +[.msg]#ECLIPSELINK-00192: ReturningPolicy contains field, [\{0}] but +custom [\{1}] doesn’t output it.# *Cause*: ReturningPolicy contains a +field fieldName, but custom query queryName does not output it. + +*Action*: Update the custom query so that it outputs a value for this +field. + +[.msg]#ECLIPSELINK-00193: There is no custom [\{0}] set, but +ReturningPolicy contains field(s) to be returned and [\{1}] doesn’t +support generating call with returning.# *Cause*: There is no custom +query set, but ReturningPolicy contains one or more fields to be +returned and doesn’t support generating call with return. + +*Action*: Specify a custom InsertObjectQuery or UpdateObjectQuery +through DescriptorQueryManager setInsertQuery, setInsertCall, +setUpdateQuery, or setUpdateCall methods that outputs values for fields +added to ReturningPolicy. + +[.msg]#ECLIPSELINK-00194: The class extraction method [\{0}], must be a +static method on the descriptor’s class.# *Cause*: The class extraction +method must be a static method on the descriptor’s class. + +*Action*: Make the class extraction method a static method on the +descriptor’s class. + +[.msg]#ECLIPSELINK-00195: The shared class \{1} must not reference the +isolated class \{0}.# *Cause*: The shared class must not reference the +isolated class. + +*Action*: Ensure that the shared class does not reference the isolated +class. + +[.msg]#ECLIPSELINK-00196: UpdateAllFields has not been set or has been +set to false. When using CMPPolicy.setForceUpdate(true) you must also +call CMPPolicy.setUpdateAllFields(true)# *Cause*: updateAllFields flag +has not been set or has been set to false. When using +setForceUpdate(true) method of CMPPolicy you must also call +setUpdateAllFields(true) method of CMPPolicy. + +*Action*: Ensure that updateAllFields is set to true if forceUpdate is +true. + +[.msg]#ECLIPSELINK-00197: The mapping [\{0}] is not the appropriate type +for this descriptor# *Cause*: A mapping of an inappropriate type has +been set for this descriptor. + +*Action*: The mapping type has to map the descriptor type, e.g. +relational mapping for relational descriptor, EIS mapping for EIS +descriptor, and XML mapping for XML descriptor. + +[.msg]#ECLIPSELINK-00198: In order to use ObjectChangeTrackingPolicy or +AttributeChangeTrackingPolicy, \{0} has to implement ChangeTracker +interface.# *Cause*: The object does not implement the ChangeTracker +interface. + +*Action*: Ensure that the object implements ChangeTrackerInterface in +order to use ObjectChangeTrackingPolicy or +AttributeChangeTrackingPolicy. + +[.msg]#ECLIPSELINK-00199: In order to use Fetch Group, the domain class +(\{0}) has to implement FetchGroupTracker interface.# *Cause*: The +domain class does not implement the FetchGroupTracker interface. + +*Action*: Ensure that the domain class implements the FetchGroupTracker +interface in order to use the fetch group. + +[.msg]#ECLIPSELINK-00200: Attempt to register an object with dead +indirection as a new object. Possibly the object was deleted or removed +from the cache during a merge of a serialized clone. This is a +concurrency violation, consider a locking strategy.# *Cause*: Attempt to +register an object with dead indirection as a new object. Possibly, the +object was deleted or removed from the cache during a merge of a +serialized clone or did not exist in the cache at the time of the merge. +This is a concurrency violation. + +*Action*: Ensure that the object exists in the cache before attempting +to merge a deserialized version into the cache. Consider a locking +strategy. For more information, see "`Merging Changes in Working Copy +Clones`" on page 112-12 and "`Indirection, Serialization, and +Detachment`" on page 17-11. + +[.msg]#ECLIPSELINK-00201: An object was attempted to be built in the +session cache, but the descriptor is marked as isolated in the unit of +work, so should never be accessed outside of a unit of work.# *Cause*: +Attempt to built and object in the session cache, but the descriptor is +marked as isolated in the unit of work. + +*Action*: Ensure that the descriptor is never accessed outside of a unit +of work. + +== Concurrency Exceptions (2001 – 2009) + +`+ConcurrencyException+` is a development exception that is raised when +a Java concurrency violation occurs. Only when a running thread is +interrupted, causing the JVM to throw an `+InterruptedException+`, is an +internal exception information displayed with the error message, as this +exampleshows. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` `+INTERNAL EXCEPTION: Message+` + +[#Example A-2]## *_Concurrency Exception_* + +`+EXCEPTION [ECLIPSELINK – 2004]: org.eclipse.persistence.exceptions.ConcurrencyException+` +`+EXCEPTION DESCRIPTION: Signal attempted before wait on concurrency manager. +` +`+This usually means that an attempt was made to commit or roll back a transaction before being started, or rolled back twice.+` + +[.msg]#ECLIPSELINK-02001: Wait was interrupted. \{0}Message: [\{1}]# +*Cause*: In a multi threaded environment, one of the waiting threads was +interrupted. + +*Action*: Such exceptions are application-dependent. + +[.msg]#ECLIPSELINK-02002: Wait failure on ServerSession.# *Cause*: A +request for a connection from the connection pool has been forced to +wait, and that wait has been interrupted. + +*Action*: Such exceptions are application-dependent. + +[.msg]#ECLIPSELINK-02003: Wait failure on ClientSession.# *Cause*: A +request for a connection from the connection pool has been forced to +wait, and that wait has been interrupted. + +*Action*: Such exceptions are application-dependent. + +[.msg]#ECLIPSELINK-02004: A signal was attempted before wait() on +ConcurrencyManager. This normally means that an attempt was made to +\{0}commit or rollback a transaction before it was started, or to +rollback a transaction twice.# *Cause*: A signal was attempted before a +wait on concurrency manager. This usually means that an attempt was made +to commit or roll back a transaction before it was started, or to +rollback a transaction twice. + +*Action*: Verify transactions in the application. + +[.msg]#ECLIPSELINK-02005: Wait failure on Sequencing Connection Handler +for DatabaseSession.# *Cause*: An InterruptedException was raised while +DatabaseSession sequencing waited for a separate connection to become +available. + +*Action*: Examine concurrency issues involving object creation with your +DatabaseSession. + +[.msg]#ECLIPSELINK-02006: Attempt to acquire sequencing values through a +single Connection(\{0}) simultaneously in multiple threads# *Cause*: +Several threads attempted to concurrently obtain sequence objects from +the same DatabaseSession or ClientSession. + +*Action*: Avoid concurrent writing through the same DatabaseSession or +ClientSession. + +[.msg]#ECLIPSELINK-02007: Max number of attempts to lock object: \{0} +exceded. Failed to clone the object.# *Cause*: Maximum number of +attempts to lock object was exceed resulting in a failure to clone the +object. + +*Action*: Ensure that the number of attempts is within the limit. + +[.msg]#ECLIPSELINK-02008: Max number of attempts to lock object: \{0} +exceded. Failed to merge the transaction.# *Cause*: Maximum number of +attempts to lock object was exceed resulting in a failure to merge the +transaction. + +*Action*: Ensure that the number of attempts is within the limit. + +[.msg]#ECLIPSELINK-02009: Max number of attempts to lock object exceded. +Failed to build the object. Thread: \{0} has a lock on the object but +thread: \{1} is building the object# *Cause*: Maximum number of attempts +to lock object was exceed resulting in a failure to build the object: +thread threadNumber has a lock on the object, but thread +anotherThreadNumber is building the object + +*Action*: Ensure that the number of attempts is within the limit. + +== Conversion Exceptions (3001– 3008) + +`+ConversionException+` is a development exception that is raised when a +conversion error occurs by an incompatible type conversion. The message +that is returned indicates which type cast caused the exception. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` `+INTERNAL EXCEPTION: Message+` + +[#Example A-3]##*_Conversion Exception_* + +`+EXCEPTION [ECLIPSELINK – 3006]: org.eclipse.persistence.exceptions.ConversionException+` +`+EXCEPTION DESCRIPTION: object must be of even length to be converted to a ByteArray+` + +[.msg]#ECLIPSELINK-03001: The object [\{0}], of class [\{1}], could not +be converted to [\{2}].# *Cause*: Attempt to convert an object object of +class ObjectClass to JavaClass. The object cannot be converted to a +given type. + +*Action*: Ensure that the object being converted is of the right type. + +[.msg]#ECLIPSELINK-03002: The object [\{0}], of class [\{1}], from +mapping [\{2}] with descriptor [\{3}], could not be converted to +[\{4}].# *Cause*: Attempt to convert an object object of class +ObjectClass from mapping mappingType to JavaClass. The object cannot be +converted to a given type. + +*Action*: Ensure that the object being converted is of the right type. + +[.msg]#ECLIPSELINK-03003: Incorrect date format: [\{0}] (expected +[YYYY-MM-DD])# *Cause*: The date in dateString is in an incorrect +format. The expected format is YYYY-MM-DD. + +*Action*: Verify the date format. + +[.msg]#ECLIPSELINK-03004: Incorrect time format: [\{0}] (expected +[HH:MM:SS])# *Cause*: The time in timeString is in an incorrect format. +The expected format is HH:MM:SS. + +*Action*: Verify the time format. + +[.msg]#ECLIPSELINK-03005: Incorrect timestamp format: [\{0}] (expected +[YYYY-MM-DD HH:MM:SS.NNNNNNNNN])# *Cause*: The timestamp timestampString +is in an incorrect format. The expected format is YYYY-MM-DD +HH:MM:SS.NNNNNNNNN. + +*Action*: Verify the timestamp format. + +[.msg]#ECLIPSELINK-03006: [\{0}] must be of even length to be converted +to a byte array.# *Cause*: Attempt to convert String object of uneven +length to a ByteArray. This object cannot be converted to a ByteArray. + +*Action*: Verify the object being converted. + +[.msg]#ECLIPSELINK-03007: The object [\{0}], of class [\{1}], could not +be converted to [\{2}]. Please ensure that the class [\{0}] is on the +CLASSPATH. You may need to use alternate API passing in the appropriate +class loader as required, or setting it on the default +ConversionManager# *Cause*: Attempt to convert an object object of class +ObjectClass to JavaClass. The class JavaClass is not on the classpath. + +*Action*: Ensure that the class JavaClass is on the classpath. + +[.msg]#ECLIPSELINK-03008: Incorrect date-time format: [\{0}] (expected +[YYYY-MM-DD’T’HH:MM:SS])# *Cause*: Incorrect date-time format object. +The expected format is YYYY-MM-DD’T’HH:MM:SS. + +*Action*: Ensure that the date-time object is in the expected format of +YYYY-MM-DD’T’HH:MM:SS. + +== Database Exceptions (4003 – 4018) + +`+DatabaseException+` is a run-time exception that is raised when data +read from the database, or the data that is to be written to the +database, is incorrect. The exception may also act as a wrapper for +`+SQLException+`. If this is the case, the message contains a reference +to the error code and error message, as shown in this example + +This exception can occur on any database operation. If an execution of a +SQL script is involved in a database operation causing +`+DatabaseException+`, the exception’s message, accessible through the +`+getMessage+` method, contains the SQL that caused this exception. + +This exception includes internal exception and error code information +when the exception is wrapping a `+SQLException+`. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` `+INTERNAL EXCEPTION: Message+` +`+ERROR CODE: Error code+` + +[#Example A-4]##*_Database Exception_* + +`+EXCEPTION [ECLIPSELINK – 4002]: org.eclipse.persistence.exceptions.DatabaseException+` +`+EXCEPTION DESCRIPTION: java.sql.SQLException: [INTERSOLV][ODBC dBase driver] Incompatible datatypes in expression: >+` + +`+INTERNAL EXCEPTION: java.sql.SQLException: [INTERSOLV][ODBC dBase driver] Incompatible datatypes in expression: >+` +`+ERROR CODE: 3924+` + +[.msg]#ECLIPSELINK-04003: Configuration error. Class [\{0}] not found.# +*Cause*: The driver class name was not found. + +*Action*: Verify the class name given in JDBCLogin. + +[.msg]#ECLIPSELINK-04005: DatabaseAccessor not connected.# *Cause*: The +session is not connected to the database while attempting to read or +write on the database. + +*Action*: An application may have to log in again because the connection +to the database might have been lost. + +[.msg]#ECLIPSELINK-04006: Error reading BLOB data from stream in +getObject().# *Cause*: An error occurred reading BLOB data from the +database. There are two possibilities for this exception: either the +BLOB data was not read properly from the result set or EclipseLink +cannot process the BLOB data using ByteArrayOutputStream. + +*Action*: Verify whether the underlying driver supports BLOBs properly. +If it does, then report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-04007: Could not convert object type due to an +internal error. \{0}java.sql.TYPES: [\{1}]# *Cause*: Attempt to convert +an object type on internal error.java.sql.TYPES = type. The object from +the result set cannot be converted to the type that was returned from +the metadata information. + +*Action*: Verify whether the underlying driver supports the conversion +type properly. If it does, then report this problem to Oracle Support +Services. + +[.msg]#ECLIPSELINK-04008: You cannot logout while a transaction is in +progress.# *Cause*: Attempt to log out while the transaction is still in +progress. You cannot log out while a transaction is in progress. + +*Action*: Wait until the transaction is finished. + +[.msg]#ECLIPSELINK-04009: The sequence table information is not +complete.# *Cause*: The sequence information given to EclipseLink is not +sufficiently complete to get the set of sequence numbers from the +database. This usually happens on native sequencing on an Oracle +database. + +*Action*: Verify the data provided, especially the sequence name +provided in EclipseLink. + +[.msg]#ECLIPSELINK-04011: Error preallocating sequence numbers. The +sequence table information is not complete.# *Cause*: An error occurred +preallocating sequence numbers on the database; the sequence table +information is not complete. + +*Action*: Ensure the sequence table was properly created on the +database. + +[.msg]#ECLIPSELINK-04015: Synchronized UnitOfWork does not support the +commitAndResume() operation.# *Cause*: A synchronized UnitOfWork does +not support the commitAndResume operation. When the EclipseLink session +is configured with an ExternalTransactionController, any unit of work +requested by a client must operate within the context of a JTS external +global transaction (see ). The JTS specification does not support the +concept of check pointing a transaction-that is, committing the work +performed and then continuing to work within the same transaction +context. JTS does not support nested transactions, either. As a result, +if a client code invokes commitAndResume on a synchronized unit of work, +this error is reported. + +*Action*: None required. + +[.msg]#ECLIPSELINK-04016: Configuration error. Could not instantiate +driver [\{0}].# *Cause*: A configuration error occurred when EclipseLink +attempted to instantiate the given driver class. EclipseLink cannot +instantiate the driver. + +*Action*: Check the driver. + +[.msg]#ECLIPSELINK-04017: Configuration error. Could not access driver +[\{0}].# *Cause*: A configuration error occurred when EclipseLink +attempted to instantiate the given driver class. EclipseLink cannot +instantiate the driver. + +*Action*: Check the driver. + +[.msg]#ECLIPSELINK-04018: The TransactionManager has not been set for +the JTS driver.# *Cause*: The transaction manager has not been set for +the JTSSynchronizationListener. + +*Action*: Set a transaction manager for the JTSSynchronizationListener. + +== Optimistic Lock Exceptions (5001 – 5009) + +`+OptimisticLockException+` is a run-time exception that is raised when +the row on the database that matches the desired object is missing or +when the value on the database does not match the registered number. It +is used in conjunction with the optimistic locking feature. This applies +only on an update or delete operation, as shown in this example. + +For more information about optimistic locking, see the section on +optimistic locking in a stateless environment in +link:Introduction_to_EclipseLink_Application_Development_(ELUG)[Introduction +to EclipseLink Application Development]. These exceptions should be +handled in a try-catch block. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception Name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-5]##*_Optimistic Lock Exception_* + +`+EXCEPTION [ECLIPSELINK – 5003]: org.eclipse.persistence.exceptions.OptimisticLockException+` +`+EXCEPTION DESCRIPTION: The object, object.toString() cannot be deleted because it has changed or been deleted since it was last read.+` + +[.msg]#ECLIPSELINK-05001: An attempt was made to delete the object +[\{0}], but it has no version number in the identity map. \{3}It may not +have been read before the delete was attempted. \{3}Class> \{1} Primary +Key> \{2}# *Cause*: Attempt to delete the object object that does not +have a version number in the identity map. This object either was never +read or has already been deleted. + +*Action*: Use SQL logging to determine the reason for the exception. The +last delete operation shows the object being deleted when the exception +was raised. + +[.msg]#ECLIPSELINK-05003: The object [\{0}] cannot be deleted because it +has changed or been deleted since it was last read. \{3}Class> \{1} +Primary Key> \{2}# *Cause*: The object state has changed in the +database. The object object cannot be deleted because it has changed or +been deleted since it was last read. This usually means that the row in +the table was changed by some other application. + +*Action*: Refresh the object, which updates it with the new data from +the database. + +[.msg]#ECLIPSELINK-05004: An attempt was made to update the object +[\{0}], but it has no version number in the identity map. \{3}It may not +have been read before the update was attempted. \{3}Class> \{1} Primary +Key> \{2}# *Cause*: An attempt has been made to update the object object +that does not have a version number in the identity map. It may not have +been read before being updated, or it has been deleted. + +*Action*: Use SQL logging to determine the reason for the exception. The +last update operation shows the object being updated when the exception +was raised. + +[.msg]#ECLIPSELINK-05006: The object [\{0}] cannot be updated because it +has changed or been deleted since it was last read. \{3}Class> \{1} +Primary Key> \{2}# *Cause*: The object state has changed in the +database. The object object cannot be updated because it has changed or +been deleted since it was last read. This usually means that the row in +the table was changed by some other application. + +*Action*: Refresh the object, which updates it with the new data from +the database. + +[.msg]#ECLIPSELINK-05007: The object [\{0}] must have a non-read-only +mapping to the version lock field.# *Cause*: The object object does not +have a non-read-only mapping corresponding to the version lock field. +The mapping, which is needed when the lock value is stored in the domain +object rather than in a cache, was not defined for the locking field. + +*Action*: Define a mapping for the field. + +[.msg]#ECLIPSELINK-05008: Must map the version lock field to +java.sql.Timestamp when using Timestamp Locking# *Cause*: A write lock +value that is stored in a domain object is not an instance of +java.sql.Timestamp. + +*Action*: Change the value of the attribute to be an instance of +java.sql.Timestamp. + +[.msg]#ECLIPSELINK-05009: The object of class [\{1}] with primary key +[\{0}] cannot be unwrapped because it was deleted since it was last +read.# *Cause*: Attempt to unwrapped an object of class className with +primary key key-the object was deleted since it had been last read. + +*Action*: Ensure the existence of the object being upwrapped. + +== Query Exceptions (6001 – 6129) + +`+QueryException+` is a development exception that is raised when +insufficient information has been provided to the query. If possible, +the message indicates the query that caused the exception. A query is +optional and is displayed if EclipseLink is able to determine the query +that caused this exception, as shown in this example + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` `+QUERY:+` + +[#Example A-6]##*_Query Exception_* + +`+EXCEPTION [ECLIPSELINK – 6026]: org.eclipse.persistence.exceptions.QueryException+` +`+EXCEPTION DESCRIPTION: The query is not defined. When executing a +` +`+query on the session, the parameter that takes the query is null.+` + +[.msg]#ECLIPSELINK-06001: Cursored SQL queries must provide an +additional query to retrieve the size of the result set.# *Cause*: +Additional size-retrieving query was not specified: cursored SQL queries +must provide an additional query to retrieve the size of the result set. +Failure to include the additional query causes this exception. + +*Action*: Specify a size query. + +[.msg]#ECLIPSELINK-06002: Aggregated objects cannot be +written/deleted/queried independently from their owners. \{1}Descriptor: +[\{0}]# *Cause*: An aggregated object was deleted independently of its +owner: aggregate objects cannot be written or deleted independent of +their owners. No identity is maintained on such objects. + +*Action*: Do not try to delete aggregate objects directly. + +[.msg]#ECLIPSELINK-06003: The number of arguments provided to the query +for execution does not match the number of arguments in the query +definition.# *Cause*: The number of arguments provided to the query for +execution does not match the number of arguments provided with the query +definition. + +*Action*: Check the query and the query execution. + +[.msg]#ECLIPSELINK-06004: The object [\{0}], of class [\{1}], with +identity hashcode (System.identityHashCode()) [\{2}], \{3}is not from +this UnitOfWork object space, but the parent session’’s. The object was +never registered in this UnitOfWork, \{3}but read from the parent +session and related to an object registered in the UnitOfWork. Ensure +that you are correctly\{3}registering your objects. If you are still +having problems, you can use the UnitOfWork.validateObjectSpace() method +to \{3}help debug where the error occurred. For more information, see +the manual or FAQ.# *Cause*: The object clone of class clone.getClass() +with identity hash code (System.identityHashCode()) +(System.identityHashCode(clone)) is not from this unit of work space, +but from the parent session. The object was never registered in this +unit of work, but read from the parent session and related to an object +registered in the unit of work. + +*Action*: Verify that you are correctly registering your objects. If you +are still having problems, use the validateObjectSpace method of the +UnitOfWork to help debug where the error occurred. + +[.msg]#ECLIPSELINK-06005: The object [\{0}], of class [\{1}], with +identity hashcode (System.identityHashCode()) [\{2}], \{3}is the +original to a registered new object. The UnitOfWork clones registered +new objects, so you must ensure that an object \{3}is registered before +it is referenced by another object. If you do not want the new object to +be cloned, use the\{3}UnitOfWork.registerNewObject(Object) API. If you +are still having problems, you can use the +UnitOfWork.validateObjectSpace() \{3}method to help debug where the +error occurred. For more information, see the manual or FAQ.# *Cause*: +The object clone of class clone.getClass() with identity hash code +(System.identityHashCode()) (System.identityHashCode(clone)) is the +original to a registered new object. Because the unit of work clones new +objects that are registered, ensure that an object is registered before +it is referenced by another object. If you do not want the new object to +be cloned, use the registerNewObject(Object) method of the UnitOfWork. + +*Action*: Verify that you are correctly registering your objects. If you +are still having problems, use the validateObjectSpace method of the +UnitOfWork to help debug where the error occurred. + +[.msg]#ECLIPSELINK-06006: The mapping [\{0}] does not support batch +reading.# *Cause*: The mapping that does not support batch reading was +used. The optimization of batch reading all the target rows is not +supported for the mapping. + +*Action*: The problem is an EclipseLink development problem, and you +should never encounter this error code unless the mapping is a new +custom mapping. Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06007: Missing descriptor for [\{0}].# *Cause*: The +descriptor for the reference class is missing. The descriptor related to +the class or the object is not found in the session. + +*Action*: Verify whether or not the related descriptor was added to the +session, and whether or not the query is performed on the right object +or class. + +[.msg]#ECLIPSELINK-06008: Missing descriptor for [\{0}] for query named +[\{1}].# *Cause*: The descriptor DomainClassName for the query named +queryName is missing. The descriptor where named query is defined is not +added to the session. + +*Action*: Verify whether or not the related descriptor was added to the +session, and whether or not the query is performed on the right class. + +[.msg]#ECLIPSELINK-06013: Incorrect size query given to CursoredStream.# +*Cause*: The size query given on the queries returning cursor streams is +not correct. The execution of the size query did not return any size. + +*Action*: If the cursor stream query was a custom query, then check the +size of the query that was specified, or report this problem to Oracle +Support Services. + +[.msg]#ECLIPSELINK-06014: Objects cannot be written during a UnitOfWork, +they must be registered.# *Cause*: Attempt to write an object in a unit +of work using modify queries. These objects must be registered. + +*Action*: Prior to modification, register objects in the unit of work, +so during commit the unit of work can perform the required changes to +the database. + +[.msg]#ECLIPSELINK-06015: Invalid query key [\{0}] in expression.# +*Cause*: The query key key does not exist. Usually this happens because +of a misspelled query key. + +*Action*: Check the query key that was specified in the expression and +verify that a query key was added to the descriptor. + +[.msg]#ECLIPSELINK-06016: Objects or the database cannot be changed +through a ServerSession. All changes must be done through a +ClientSession’’s UnitOfWork.# *Cause*: Attempt to change an object or a +database through the server session: all changes must be performed +through a client session’s unit of work. The objects cannot be changed +on the server session by modifying queries. Objects are changed in the +client sessions that are acquired from this server session. + +*Action*: Use the client session’s unit of work to change the object. + +[.msg]#ECLIPSELINK-06020: No concrete class indicated for the type in +the row [\{0}].# *Cause*: No concrete class is indicated for the type in +this row. The type indicator read from the database row has no entry in +the type indicator hash table or if class extraction method was used, it +did not return any concrete class type. The exception is raised when +subclasses are being read. + +*Action*: Check the class extraction method, if specified, or check the +descriptor to verify all the type indicator values were specified. + +[.msg]#ECLIPSELINK-06021: Cursors are not supported for interface +descriptors, or abstract class multiple table descriptors using +expressions. Consider using custom SQL or multiple queries.# *Cause*: No +cursor support is provided for abstract class multiple table descriptors +using expressions. + +*Action*: Consider using custom SQL or multiple queries. + +[.msg]#ECLIPSELINK-06023: The list of fields to insert into the table +[\{0}] is empty. You must define at least one mapping for this table.# +*Cause*: There are no fields to be inserted into the table. The fields +to insert into the table table, are empty. + +*Action*: Define at least one mapping for this table. + +[.msg]#ECLIPSELINK-06024: Modify queries require an object to modify.# +*Cause*: An object to modify has not been specified for a modify query. + +*Action*: Verify that the query contains an object before executing. + +[.msg]#ECLIPSELINK-06026: Query named [\{0}] is not defined. Domain +class: [\{1}]# *Cause*: The query is not defined. When executing a query +on the session, the parameter that takes the query is null. + +*Action*: Verify that the query is passed properly. + +[.msg]#ECLIPSELINK-06027: Query sent to a unactivated UnitOfWork.# +*Cause*: The unit of work has been released and is now inactive. + +*Action*: The unit of work, once released, cannot be reused unless the +commitAndResume method is called. + +[.msg]#ECLIPSELINK-06028: An attempt to read beyond the end of stream +occurred.# *Cause*: Attempt to read from the cursor streams beyond its +limits (beyond the end of the stream). + +*Action*: Ensure that the stream is checked for an end of stream +condition before attempting to retrieve more objects. + +[.msg]#ECLIPSELINK-06029: A reference class must be provided.# *Cause*: +The reference class in the query is not specified: a reference class +must be provided. + +*Action*: Ensure that the query is correct. + +[.msg]#ECLIPSELINK-06030: Refreshing is not possible if caching is not +enabled.# *Cause*: Attempt to refresh while the caching is not set: the +read queries that skip the cache to read objects cannot be used to +refresh the objects. Refreshing is not possible without identity. + +*Action*: Ensure that the query is correct. + +[.msg]#ECLIPSELINK-06031: size() is only supported on expression +queries, unless a size query is given.# *Cause*: EclipseLink did not +find a size query. Size is supported only on expression queries unless a +size query is given. + +*Action*: The cursor streams on a custom query should also define a size +query. + +[.msg]#ECLIPSELINK-06032: The SQL statement has not been properly set.# +*Cause*: The SQL statement has not been properly set. The user should +never encounter this error code unless queries have been customized. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06034: Invalid query item expression [\{0}].# +*Cause*: EclipseLink is unable to validate a query item expression. + +*Action*: Validate the expression being used. + +[.msg]#ECLIPSELINK-06041: The selection object passed to a +ReadObjectQuery was null.# *Cause*: The selection object that was passed +to a ReadObjectQuery (or refresh) was null. + +*Action*: Check setSelectionObject method on read query. + +[.msg]#ECLIPSELINK-06042: A session name must be specified for +non-object-level queries. See the setSessionName(String) method.# +*Cause*: Data read and data modify queries are being executed without +the session name. Only object-level queries can be directly executed by +the session broker, unless the query is named. + +*Action*: Specify the session name. + +[.msg]#ECLIPSELINK-06043: ReportQueries without primary keys cannot use +readObject(). \{1}ReportQueryResult: [\{0}].# *Cause*: Attempt to read +the object by a ReportQuery without a primary key: the report query +result that was returned is without primary key values. An object from +the result can be created only if primary keys were also read. + +*Action*: See the documentation about retrievePrimaryKeys method on +report query. + +[.msg]#ECLIPSELINK-06044: The primary key read from the row [\{0}] +during the execution of the query was detected to be null. Primary keys +must not contain null.# *Cause*: The primary key that was read from the +row databaseRow during the execution of the query was detected to be +null: primary keys must not contain null. + +*Action*: Check the query and the table on the database. + +[.msg]#ECLIPSELINK-06045: The subclass [\{0}], indicated in the row +while building the object, has no descriptor defined for it.# *Cause*: +The subclass has no descriptor defined for it. + +*Action*: Ensure the descriptor was added to the session, or check class +extraction method. + +[.msg]#ECLIPSELINK-06046: Cannot delete an object of a read-only class. +The class [\{0}] is declared as read-only in this UnitOfWork.# *Cause*: +Attempt to delete a read-only class. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06047: Invalid operator [\{0}] in expression.# +*Cause*: The operator used in the expression is not valid. + +*Action*: Check ExpressionOperator class to see a list of all the +operators that are supported. + +[.msg]#ECLIPSELINK-06048: Illegal use of getField() [\{0}] in +expression.# *Cause*: Invalid use of getField method’s data in the +expression. This is an EclipseLink development exception that you should +not encounter. + +*Action*: Report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-06049: Illegal use of getTable() [\{0}] in +expression.# *Cause*: Invalid use of getTable method’s data in the +expression. This is an EclipseLink development exception that you should +not encounter. + +*Action*: Report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-06050: ReportQuery result size mismatch. Expecting +[\{0}], but retrieved [\{1}]# *Cause*: The number of attributes +requested does not match the attributes returned from the database in +report query. This can happen as a result of a custom query on the +report query. + +*Action*: Check the custom query to ensure it is specified, or report +the problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-06051: Partial object queries are not allowed to +maintain the cache or be edited. You must use dontMaintainCache().# +*Cause*: Attempt to cache a partial object: partial objects are never +put in the cache. Partial object queries are not allowed to maintain the +cache or to be edited. Use the dontMaintainCache method. + +*Action*: Call the dontMaintainCache method before executing the query. + +[.msg]#ECLIPSELINK-06052: An outer join (getAllowingNull or +anyOfAllowingNone) is only valid for OneToOne, OneToMany, ManyToMany, +AggregateCollection and DirectCollection Mappings, and cannot be used +for the mapping [\{0}].# *Cause*: Invalid use of an outer join: an outer +join (getAllowingNull method) is valid only for one-to-one mappings and +cannot be used for the mapping. + +*Action*: Do not attempt to use the getAllowingNull method for mappings +other than one-to-one. + +[.msg]#ECLIPSELINK-06054: Cannot add the object [\{0}], of class [\{1}], +to container class [\{2}] using policy [\{3}].# *Cause*: EclipseLink is +unable to add an object to a container class using policy. This is +EclipseLink development exception, and you should never encounter this +problem unless a custom container policy has been written. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06055: The method invocation of the method [\{0}] on +the object [\{1}], of class [\{2}], triggered an exception.# *Cause*: +The invocation of a method on the object anObject threw a Java +reflection exception while accessing the method. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06056: Cannot create a clone of object [\{0}], of +class [\{1}], using [\{2}].# *Cause*: Attempt to create a clone of the +object anObject using policy. This is an EclipseLink development +exception, and you should never encounter this problem unless a custom +container policy has been written. + +*Action*: Report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-06057: The method [\{0}] is not a valid method to +call on object [\{1}].# *Cause*: Invalid call of the method methodName +on object aReceiver. This is an EclipseLink development exception, and +you should never encounter this problem unless a custom container policy +has been written. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06058: The method [\{0}] was not found in class +[\{1}].# *Cause*: The method named methodName was not found in the class +aClass. This exception is raised when looking for a clone method on the +container class. The clone is needed to create clones of the container +in unit of work. + +*Action*: Define a clone method on the container class. + +[.msg]#ECLIPSELINK-06059: The class [\{0}] cannot be used as the +container for the results of a query because it cannot be instantiated.# +*Cause*: Attempt to instantiate a class aClass as the container for the +results of a query-this class cannot be instantiated as a container. The +exception is a Java exception that is raised when a new interface +container policy is being created using Java reflection. EclipseLink +wraps only the Java exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06060: Could not use object [\{0}] of type [\{1}] as +a key into [\{2}] of type [\{3}]. The key cannot be compared with the +keys currently in the Map.# *Cause*: Attempt to use the object anObject +of type ObjectClass as a key into aContainer which is of type +ContainerClass. The key cannot be compared with the keys currently in +the map. This raises a Java reflection exception while accessing the +method. EclipseLink wraps only the Java exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06061: Cannot reflectively access the method [\{0}] +for object [\{1}], of class [\{2}].# *Cause*: Attempt to reflectively +access the method aMethod for object: anObject of type ObjectClass. This +raises a Java reflection exception while accessing the method. +EclipseLink wraps only the Java exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06062: The method [\{0}], called reflectively on +object [\{1}], of class [\{2}], triggered an exception.# *Cause*: The +method aMethod was called reflectively on objectClass and threw an +exception. The method aMethod raises a Java reflection exception while +accessing a method. EclipseLink wraps only the Java exception. + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06063: Invalid operation [\{0}] on cursor.# *Cause*: +Invalid operation operationName on the cursor. The operation is not +supported. + +*Action*: Check the class documentation and look for the corresponding +method to use. + +[.msg]#ECLIPSELINK-06064: Cannot remove the object [\{0}], of class +[\{1}], from container class [\{2}] using policy [\{3}].# *Cause*: +Attempt to remove anObject of type anObjectClass from aContainerClass +using policy. This is an EclipseLink development exception and you +should never encounter this problem unless a custom container policy has +been written. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06065: Cannot add the object [\{0}], of class [\{1}], +to container [\{2}].# *Cause*: Attempt to add an element to the +collection container policy (cannot add object anObject of type +ObjectClass to a ContainerClass). + +*Action*: Inspect the internal exception, and refer to the Java +documentation. + +[.msg]#ECLIPSELINK-06066: The object [\{0}], of class [\{1}], with +identity hashcode (System.identityHashCode()) [\{2}], \{3}has been +deleted, but still has references. Deleted objects cannot be referenced +after being deleted. \{3}Ensure that you are correctly registering your +objects. If you are still having problems, you can use the +UnitOfWork.validateObjectSpace() \{3}method to help debug where the +error occurred. For more information, see the manual or FAQ.# *Cause*: +Object references remained after the deletion of the object: the object +clone of class clone.getClass with identity hash code +(System.identityHashCode()) (System.identityHashCode(clone)) has been +deleted, but it still has references. + +*Action*: Ensure that you are correctly registering your objects. If you +are still having problems, use the validateObjectSpace() method of the +UnitOfWork to help identify where the error occurred. + +[.msg]#ECLIPSELINK-06068: Cannot compare table reference to [\{0}] in +expression.# *Cause*: Attempt to compare table reference to data in +expression. + +*Action*: Check the expression. + +[.msg]#ECLIPSELINK-06069: The field [\{0}] in this expression has an +invalid table in this context.# *Cause*: Field has invalid table in this +context for field fieldName in expression. + +*Action*: Check the expression. + +[.msg]#ECLIPSELINK-06070: Invalid use of a query key [\{0}] representing +a "`to-many`" relationship in an expression. Use anyOf() rather than +get().# *Cause*: Invalid use of a query key representing a one-to-many +relationship in expression. + +*Action*: Use the anyOf operator instead of the get operator. + +[.msg]#ECLIPSELINK-06071: Invalid use of anyOf() for a query key [\{0}] +not representing a to-many relationship in an expression. Use get() +rather than anyOf().# *Cause*: Invalid use of anyOf for a query key not +representing a to-many relationship in expression. + +*Action*: Use the get operator instead of the anyOf operator. + +[.msg]#ECLIPSELINK-06072: Querying across a VariableOneToOneMapping is +not supported. \{2}Descriptor: [\{0}] \{2}Mapping: [\{1}]# *Cause*: +Attempt to query across a variable one-to-one mapping. This is not +supported. + +*Action*: Change the expression such that the query is not performed +across a variable one-to-one mapping. + +[.msg]#ECLIPSELINK-06073: Malformed expression in query. Attempting to +print an object reference into an SQL statement for query key [\{0}].# +*Cause*: Ill-formed expression in query that is attempting to print an +object reference into a SQL statement for queryKey. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06074: This expression cannot determine if the object +conforms in memory. You must set the query to check the database.# +*Cause*: Expression cannot determine if the object conforms in memory. + +*Action*: Set the query to check the database; change the query such +that it does not attempt to conform to the results of the query. + +[.msg]#ECLIPSELINK-06075: Object comparisons can only use the equal() or +notEqual() operators. Other comparisons must be done through query keys +or direct attribute level comparisons. \{1}Expression: [\{0}]# *Cause*: +Invalid operator was used for the object comparison: object comparisons +can use only the equal or notEqual operators; other comparisons must be +performed through query keys or direct attribute level comparisons. + +*Action*: Ensure the query uses only equal and notEqual if object +comparisons are being used. + +[.msg]#ECLIPSELINK-06076: Object comparisons can only be used with +OneToOneMappings. Other mapping comparisons must be done through query +keys or direct attribute level comparisons. \{2}Mapping: [\{0}] +\{2}Expression: [\{1}]# *Cause*: Unsupported type of mapping was used +for the object comparison: object comparisons can be used only with +one-to-one mappings; other mapping comparisons must be performed through +query keys or direct attribute level comparisons. + +*Action*: Use a query key instead of attempting to compare objects +across the mapping. + +[.msg]#ECLIPSELINK-06077: Object comparisons cannot be used in parameter +queries. You must build the expression dynamically. \{1}Expression: +[\{0}]# *Cause*: Object comparison was parameterized: object comparisons +cannot be used in parameter queries. + +*Action*: Change the query so that it does not attempt to use objects +when using parameterized queries. + +[.msg]#ECLIPSELINK-06078: The class of the argument for the object +comparison is incorrect. \{3}Expression: [\{0}] \{3}Mapping: [\{1}] +\{3}Argument: [\{2}]# *Cause*: An incorrect class of the argument was +used for the object comparison. + +*Action*: Ensure the class for the query is correct. + +[.msg]#ECLIPSELINK-06079: Object comparison cannot be used for target +foreign key relationships. Query on the source primary key instead. +\{3}Expression: [\{0}] \{3}Mapping: [\{1}] \{3}Argument: [\{2}]# +*Cause*: Object comparison was used for target foreign key +relationships: object comparisons cannot be used for target foreign key +relationships + +*Action*: Query on the source primary key. + +[.msg]#ECLIPSELINK-06080: Invalid database call [\{0}]. The call must be +an instance of DatabaseCall.# *Cause*: Invalid database call: the call +must be an instance of DatabaseCall. + +*Action*: Ensure the call being used is a DatabaseCall. + +[.msg]#ECLIPSELINK-06081: Invalid database accessor [\{0}]. The accessor +must be an instance of DatabaseAccessor.# *Cause*: Invalid database +accessor: the accessor must be an instance of DatabaseAccessor. + +*Action*: Ensure the accessor being used is a DatabaseAccessor. + +[.msg]#ECLIPSELINK-06082: The method [\{0}] with argument types [\{1}] +cannot be invoked on Expression.# *Cause*: The nonexisting method +methodName with argument type argTypes was invoked on an expression. + +*Action*: Ensure the method being used is a supported method. + +[.msg]#ECLIPSELINK-06083: Queries using in() cannot be parameterized. +Disable either query preparation or binding.# *Cause*: The query that +was using IN was parameterized: queries using IN cannot be +parameterized. + +*Action*: Disable the query prepare or binding. + +[.msg]#ECLIPSELINK-06084: The redirection query was not configured +properly. The class or method name was not set.# *Cause*: The +redirection query was not configured properly: the class or method name +was not set. + +*Action*: Verify the configuration for the redirection class. + +[.msg]#ECLIPSELINK-06085: The redirection query’’s method is not defined +or defined with the wrong arguments. It must be declared "`public +static`" and have arguments (DatabaseQuery, Record, Session) or +(Session, Vector). \{2}Class: [\{0}] \{2}Method: [\{1}]# *Cause*: The +redirection query’s method is not defined or it is defined with the +wrong arguments. It must be public static and have the following +arguments: DatabaseQuery, DatabaseRow, or Session (the interface). + +*Action*: Check the redirection query’s method. + +[.msg]#ECLIPSELINK-06086: The redirection query’’s method invocation +triggered an exception.# *Cause*: The static invoke method provided to +MethodBaseQueryRedirector threw an exception when invoked. + +*Action*: Check the static invoke method for problems. + +[.msg]#ECLIPSELINK-06087: The example object class [\{0}] does not match +the reference object class [\{1}].# *Cause*: There is a class mismatch +between the example object and the reference class specified for this +query. + +*Action*: Ensure that the example and reference classes are compatible. + +[.msg]#ECLIPSELINK-06088: There are no attributes for the ReportQuery.# +*Cause*: A ReportQuery has been built with no attributes specified. + +*Action*: Specify the attribute for the query. + +[.msg]#ECLIPSELINK-06089: The expression has not been initialized +correctly. Only a single ExpressionBuilder should be used for a query. +\{1}For parallel expressions, the query class must be provided to the +ExpressionBuilder constructor, and the query’’s ExpressionBuilder must +\{1}always be on the left side of the expression. \{1}Expression: +[\{0}]# *Cause*: The expression has not been initialized correctly. Only +a single ExpressionBuilder should be used for a query. For parallel +expressions, the query class must be provided to the ExpressionBuilder +constructor, and the query’s ExpressionBuilder must always be on the +left side of the expression. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06090: Cannot set ReportQuery to "`check cache +only`".# *Cause*: The checkCacheOnly method was invoked on a +ReportQuery. You cannot invoke the checkCacheOnly method on a +ReportQuery, because a ReportQuery returns data rather than objects and +the EclipseLink cache is built with objects. + +*Action*: Do not use a ReportQuery in this case. + +[.msg]#ECLIPSELINK-06091: The type of the constant [\{0}], used for +comparison in the expression, does not match the type of the attribute +[\{1}].# *Cause*: The type of the constant used for comparison in the +expression does not match the type of the attribute. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-06092: Uninstantiated ValueHolder detected. You must +instantiate the relevant Valueholders to perform this in-memory query.# +*Cause*: Uninstantiated value holders have been detected. + +*Action*: Instantiate the value holders for the collection on which you +want to query. + +[.msg]#ECLIPSELINK-06094: The parameter name [\{0}] in the query’’s +selection criteria does not match any parameter name defined in the +query.# *Cause*: An unmapped field was used in a parameterized +expression. + +*Action*: Map the field or define an alternate expression that does not +rely on the unmapped field. + +[.msg]#ECLIPSELINK-06095: Public clone method is required.# *Cause*: A +delegate class of an IndirectContainer implementation does not implement +Cloneable. If you implement IndirectContainer you must also implement +Cloneable. For example, see +org.eclipse.persistence.indirection.IndirectSet. The clone method must +clone the delegate. For example, the IndirectSet implementation uses +reflection to invoke the clone method because it is not included in the +common interface shared by IndirectSet and its base delegate class, +HashSet. + +*Action*: Ensure that your IndirectContainer implementation or its +delegate class implements Cloneable. + +[.msg]#ECLIPSELINK-06096: Clone method is inaccessible.# *Cause*: A +delegate class of an IndirectContainer implementation implements +Cloneable but the IndirectContainer implementation does not have access +to the specified clone method. That is, a +java.lang.IllegalAccessException is raised when the delegate’s clone +method is invoked. + +*Action*: Ensure that both the delegate clone method and the delegate +class are public. Ensure permission is set for Java reflection in your +VM security settings. See also the invoke method of +java.lang.reflect.Method. + +[.msg]#ECLIPSELINK-06097: clone method threw an exception: \{0}.# +*Cause*: A delegate class of an IndirectContainer implementation +implements Cloneable and the IndirectContainer implementation has access +to the specified clone method, but the specified clone method raises a +java.lang.reflect.InvocationTargetException when invoked. + +*Action*: Verify the implementation of the delegate’s clone method. + +[.msg]#ECLIPSELINK-06098: Unexpected Invocation Exception: \{0}.# +*Cause*: A proxy object method raises an unexpected exception when +invoked (that is, some exception other than InvocationTargetException +and ValidationException.) + +*Action*: Review the proxy object to see where it is throwing the +exception described in the exception message. Ensure this exception is +no longer raised. + +[.msg]#ECLIPSELINK-06099: Joining across inheritance class with multiple +table subclasses not supported: \{0}, \{1}# *Cause*: Joining with query +across inheritance class with multiple table subclasses. This is not +supported: joining cannot be used on relationships with inheritance +classes that have subclasses that span multiple tables as this requires +multiple separate queries. The multiple queries cannot be joined into a +single query. + +*Action*: Use batch reading on the relationship instead, as this will +provide equivalent or better performance. + +[.msg]#ECLIPSELINK-06100: Multiple values detected for single-object +read query.# *Cause*: Multiple values detected for single-object read +query. This is a CMP compliance option that ensures the finder methods +for a single object only return a single row. + +*Action*: Set the system property toplink.cts.checkMultipleRows to +false, or ensure that the finder query only returns a single row from +the database. + +[.msg]#ECLIPSELINK-06101: Executing this query could violate the +integrity of the global session cache which must contain only the latest +versions of objects. In order to execute a query that returns objects as +of a past time, try one of the following: Use a HistoricalSession +(acquireSessionAsOf), all objects read will be cached and automatically +read as of the same time. This will apply even to triggering object +relationships. Set shouldMaintainCache to false. You may make any object +expression as of a past time, provided none of its fields are +represented in the result set (i.e. used only in the where clause).# +*Cause*: Executing this query could violate the integrity of the global +session cache which must contain only the latest versions of objects. + +*Action*: To execute a query that returns objects of a historical +nature, you must do one of the following:Use a HistoricalSession +(acquireSessionAsOf). All objects read will be cached and automatically +read at that time. This applies also to triggering object +relationships.Set shouldMaintainCache to false. You may make any object +expression as of a previous time, provided none of its fields are +represented in the result set (i.e. used in the where clause). + +[.msg]#ECLIPSELINK-06102: At present historical queries only work with +Oracle 9R2 or later databases, as it uses Oracle’s Flashback feature.# +*Cause*: Invalid database was used: historical queries only work with +Oracle 9.2.0.4 or later databases, as it uses the Oracle database +Flashback feature. + +*Action*: Ensure that historical queries are only used with an Oracle +9.2.0.4 or later database. + +[.msg]#ECLIPSELINK-06103: You may not execute a WriteQuery from inside a +read-only HistoricalSession. To restore past objects, try the following: +read the same object as it is now with a UnitOfWork and commit the +UnitOfWork.# *Cause*: Invalid query was executed on a historical +session: you may not execute a WriteQuery from inside a read-only +HistoricalSession. To restore historical objects, try the following: +read the same object as it is now with a UnitOfWork and commit the +UnitOfWork. + +*Action*: To restore historical objects, read the same object as it is +now with a UnitOfWork and commit the UnitOfWork. + +[.msg]#ECLIPSELINK-06104: The object, \{0}, does not exist in the +cache.# *Cause*: The object does not exist in the cache. + +*Action*: Ensure that the object exists in the cache. + +[.msg]#ECLIPSELINK-06105: Query has to be reinitialized with a cursor +stream policy.# *Cause*: The cursor stream policy was not used on the +query instantiation. + +*Action*: Reinitialize the query with a cursor stream policy. + +[.msg]#ECLIPSELINK-06106: The object of type [\{0}] with primary key +[\{1}] does not exist in the cache.# *Cause*: The object with primary +key does not exist in the cache. + +*Action*: Ensure that the object exists in the cache. + +[.msg]#ECLIPSELINK-06107: Missing update statements on UpdateAllQuery.# +*Cause*: Missing update statements on UpdateAllQuery. + +*Action*: Add update statements using the addUpdate method. + +[.msg]#ECLIPSELINK-06108: Update all query does not support inheritance +with multiple tables# *Cause*: For UpdateAllQuery, inheritance was used +with multiple tables: UpdateAllQuery does not support inheritance with +multiple tables. + +*Action*: Do not use UpdateAllQuery in this situation. + +[.msg]#ECLIPSELINK-06109: The named fetch group (\{0}) is not defined at +the dscriptor level.# *Cause*: The named fetch group is not defined at +the descriptor level. + +*Action*: Ensure the fetch group is defined in the descriptor. + +[.msg]#ECLIPSELINK-06110: Read query cannot conform the unfetched +attribute (\{0}) of the partially fetched object in the unit of work +identity map.# *Cause*: Read query cannot conform to the unfetched +attribute of the partially fetched object in the unit of work identity +map. + +*Action*: Do not use unfetched attribute conforming, or explicitly fetch +the attribute before conforming. + +[.msg]#ECLIPSELINK-06111: The fetch group attribute (\{0}) is not +defined or not mapped.# *Cause*: The fetch group attribute is not +defined or mapped. + +*Action*: Ensure that any attribute defined in a fetch group is defined +in the class and mapped. + +[.msg]#ECLIPSELINK-06112: Fetch group cannot be set on report query.# +*Cause*: A fetch group was set on report query: fetch groups cannot be +set on report queries. + +*Action*: Remove the fetch group setting on ReportQuery, or use +ReadObjectQuery or ReadObjectQuery instead. + +[.msg]#ECLIPSELINK-06113: Fetch group cannot be used along with partial +attribute reading.# *Cause*: Fetch group was used together with partial +attribute reading: fetch groups cannot be used together with partial +attribute reading. + +*Action*: Remove the partial attribute reading setting in the query. + +[.msg]#ECLIPSELINK-06114: You must define a fetch group manager at +descriptor (\{0}) in order to set a fetch group on the query (\{1})# +*Cause*: A fetch group manager is not defined at the descriptor while +attempting to set a fetch group on a query. + +*Action*: You must define a fetch group manager at the descriptor in +order to set a fetch group on the query. + +[.msg]#ECLIPSELINK-06115: Queries on isolated classes, or queries set to +use exclusive connections, must not be executed on a ServerSession or, +in CMP, outside of a transaction.# *Cause*: An isolated query was +executed on a server session: queries on isolated classes, or queries +set to use exclusive connections, must not be executed on a +ServerSession or in CMP outside of a transaction. + +*Action*: Do not execute queries on isolated classes or queries set to +use exclusive connections on a ServerSession or in CMP outside of a +transaction. + +[.msg]#ECLIPSELINK-06116: No Call or Interaction was specified for the +attempted operation.# *Cause*: No call or interaction method was +specified for the attempted operation. + +*Action*: Specify a call or interaction method. + +[.msg]#ECLIPSELINK-06117: Can not set a query, that uses a cursored +result, to cache query results.# *Cause*: A query that uses a cursored +result to cache query results was set. + +*Action*: Do not cache query results or do not use a cursor policy. + +[.msg]#ECLIPSELINK-06118: A query on an Isolated class must not cache +query results on the query.# *Cause*: Query on an isolated class +attempted to cache query results on the query. + +*Action*: Do not cache query results for a query on an isolated class. + +[.msg]#ECLIPSELINK-06119: The join expression \{0} is not valid, or for +a mapping type that does not support joining.# *Cause*: The join +expression is not valid, or is for a mapping type that does not support +joining. + +*Action*: Joining is supported only for one-one and one-many mappings. + +[.msg]#ECLIPSELINK-06120: The partial attribute \{0} is not a valid +attribute of the class \{1}.# *Cause*: The partial attribute +attributeName is not a valid attribute of the class className. + +*Action*: Ensure that this attribute exists, and is mapped. + +[.msg]#ECLIPSELINK-06121: The query has not been defined correctly, the +expression builder is missing. For sub and parallel queries ensure the +queries builder is always on the left.# *Cause*: The query has not been +defined correctly: the expression builder is missing. + +*Action*: Ensure the queries builder is always on the left for sub +queries and parallel queries. + +[.msg]#ECLIPSELINK-06122: The expression is not a valid expression. +\{0}# *Cause*: Attempt to use an invalid expression expression. + +*Action*: Ensure the correctness of the expression. + +[.msg]#ECLIPSELINK-06123: The container class specified [\{0}] cannot be +used because the container needs to implement \{1}.# *Cause*: Invalid +container class specified: the container class className cannot be used, +because the container needs to implement interfaceName. + +*Action*: Ensure that the class specified as a container implements the +correct interface. + +[.msg]#ECLIPSELINK-06124: Required query of \{0}, found \{1}# *Cause*: +EclipseLink was expecting to find the query queryName, but instead found +an incorrect query queryName. + +[.msg]#ECLIPSELINK-06124: Required query of \{0}, found \{1}# *Cause*: +EclipseLink was expecting to find the query queryName, but instead found +an incorrect query queryName. + +*Action*: Provide the correct query. + +[.msg]#ECLIPSELINK-06125: ReadQuery.clearQueryResults() can no longer be +called. The call to clearQueryResults now requires that the session be +provided. clearQueryResults(session) should be called.# *Cause*: The +ReadQuery method clearQueryResults() was called: this method cannot be +called anymore. The call to the clearQueryResults method now requires +that the session be provided. + +*Action*: Call the ReadQuery method clearQueryResults(session). + +[.msg]#ECLIPSELINK-06126: A query is being executed that uses both +conforming and cached query results. These two settings are +incompatible.# *Cause*: A query is being executed that uses both +conforming and cached query results. These two settings are +incompatible. + +*Action*: Ensure that the query uses either conforming or cached query +results. + +[.msg]#ECLIPSELINK-06127: A reflective call failed on the EclipseLink +class \{0}, your environment must be set up to allow Java reflection.# +*Cause*: A reflective call failed on the EclipseLink class classNAME. + +*Action*: Set up your environment to allow Java reflection + +[.msg]#ECLIPSELINK-06128: Batch Reading is not supported on Queries +using custom Calls.# *Cause*: Attempt to use batch reading on a query +using a custom call: batch reading is not supported on queries using +custom calls. + +*Action*: Do not use batch reading on queries using custom calls. + +[.msg]#ECLIPSELINK-06129: Refreshing is not possible if the query does +not go to the database.# *Cause*: Attempt to refreshing the query that +does not go to the database. This is not possible. + +*Action*: Avoid refreshing queries that do not go to the database. + +== Validation Exceptions (7001 – 7200) + +`+ValidationException+` is a development exception that is raised when +an incorrect state is detected or an API is used incorrectly. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-7]##*_Validation Exception_* + +`+EXCEPTION [ECLIPSELINK – 7008]: org.eclipse.persistence.exceptions.ValidationException+` +`+EXCEPTION DESCRIPTION: The Java type javaClass is not a valid database type. The Java type of the field to be written to the database has no corresponding type on the database.+` + +[.msg]#ECLIPSELINK-07001: You must login to the ServerSession before +acquiring ClientSessions.# *Cause*: Attempt to allocate client sessions +before logging in to the server. + +*Action*: Ensure you have called login method on your server session or +database session. This error also appears in multi-threaded environments +as a result of concurrency issues. Check that all your threads are +synchronized. + +[.msg]#ECLIPSELINK-07002: The pool named [\{0}] does not exist.# +*Cause*: The pool name used while acquiring client session from the +server session does not exist. + +*Action*: Verify the pool name given while acquiring client session and +all the existing pools on the server session. + +[.msg]#ECLIPSELINK-07003: Max size must be greater than min size.# +*Cause*: The maximum number of connections in a connection pool is less +than the minimum number of connections. The connection pool size must be +greater than the minimum number of connections. + +*Action*: Check addConnectionPool(String poolName, JDBCLogin login, int +minNumberOfConnections, int maxNumberOfConnections) method on the server +session. + +[.msg]#ECLIPSELINK-07004: Pools must be configured before login.# +*Cause*: Attempt to add connection pools after logging in to the server +session: pools must all be added before login on the server session has +been done. Once logged in, you cannot add pools. + +*Action*: Check addConnectionPool(String poolName, JDBCLogin login, int +minNumberOfConnections, int maxNumberOfConnections) on server session. +This method should be called before logging in on the server session. + +[.msg]#ECLIPSELINK-07008: The Java type [\{0}] is not a valid database +type.# *Cause*: The Java type javaClass is not a valid database type. +The Java type of the field to be written to the database has no +corresponding type on the database. + +*Action*: Check the table or stored procedure definition. + +[.msg]#ECLIPSELINK-07009: Missing descriptor for [\{0}]. Verify that the +descriptor has been properly registered with the Session.# *Cause*: The +descriptor className is not found in the session. + +*Action*: Ensure that the related descriptor to the class was properly +registered with the session. + +[.msg]#ECLIPSELINK-07010: Start index is out of range.# *Cause*: This is +an EclipseLink development exception and you should never encounter this +problem. It happens when a copy of a vector is created with a start and +end index. + +*Action*: Report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-07011: Stop index is out of range.# *Cause*: This is +an EclipseLink development exception and you should never encounter this +problem. It happens when a copy of a vector is created with a start and +end index. + +*Action*: Report this problem to Oracle Support Services. + +[.msg]#ECLIPSELINK-07012: Fatal error occurred.# *Cause*: This is an +EclipseLink development exception and you should never encounter this +problem. It happens when test cases are executed. + +*Action*: Report this problem to Oracle Support Services. This error +commonly occurs if you attempt to call the commit method on an invalid +(or previously committed) unit of work. If cannotCommitUOWAgain method +of ValidationException appears in the stack trace, verify that the +commit method was called on valid UnitOfWork instances. + +[.msg]#ECLIPSELINK-07013: You are using the deprecated SessionManager +API and no ECLIPSELINKLink.properties file could be found in your +classpath. No sessions could be read in from file.# *Cause*: The +toplink.properties file cannot be found on the system classpath. + +*Action*: Ensure that there is a toplink.properties file located on the +system classpath. + +[.msg]#ECLIPSELINK-07017: Child descriptors do not have an identity map, +they share their parent’’s# *Cause*: An identity map is added to the +child descriptor. A child descriptor shares its parent’s identity map. + +*Action*: Check the child descriptor and remove the identity map from +it. + +[.msg]#ECLIPSELINK-07018: File error.# *Cause*: You should never +encounter this problem. It happens when test cases are executed. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07023: Incorrect login instance provided. A +DatabaseLogin must be provided.# *Cause*: The login instance provided to +the login method is incorrect. A JDBCLogin must be provided. + +*Action*: Use a JDBCLogin. + +[.msg]#ECLIPSELINK-07024: Invalid merge policy.# *Cause*: This is an +EclipseLink development exception and you should never encounter it. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07025: The only valid keys for DatabaseRows are +Strings and DatabaseFields.# *Cause*: The key on the database row is not +either of type String or of type DatabaseField. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07027: The sequence named [\{0}] is setup +incorrectly. Its increment does not match its pre-allocation size.# +*Cause*: The sequence sequenceName is set up incorrectly: increment does +not match preallocation size. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07028: writeObject() is not allowed within a +UnitOfWork.# *Cause*: Attempt to use writeObject() method in a +UnitOfWork. + +*Action*: Ensure that a writeObject() method is not in the UnitOfWork. + +[.msg]#ECLIPSELINK-07030: You cannot set read pool size after login.# +*Cause*: Attempt to set read pool size after the server session has +already been logged in. + +*Action*: Set the pool size before login. + +[.msg]#ECLIPSELINK-07031: You cannot add descriptors to a +SessionBroker.# *Cause*: Attempt to add a descriptor directly to a +session broker. + +*Action*: Descriptors are added to the sessions contained in the session +broker. + +[.msg]#ECLIPSELINK-07032: There is no session registered for the class +[\{0}].# *Cause*: The descriptor related to the domain class domainClass +was not found in any of the sessions registered in the session broker. + +*Action*: Check the sessions. + +[.msg]#ECLIPSELINK-07033: There is no session registered with the name +[\{0}].# *Cause*: A session sessionName is not registered in the session +broker. + +*Action*: Check the session broker. + +[.msg]#ECLIPSELINK-07038: Error while logging message to Session log.# +*Cause*: Error while logging message to session’s log. + +*Action*: Check the internal exception. + +[.msg]#ECLIPSELINK-07039: Cannot remove from the set of read-only +classes in a nested UnitOfWork. \{0}A nested UnitOfWork’'`s set of +read-only classes must be equal to or a superset of its parent`'’s set +of read-only classes.# *Cause*: Attempt to remove from the set of +read-only classes in a nested unit of work. A nested unit of work’s set +of read-only classes must be equal to or be a superset of its parent’s +set of read-only classes. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07040: Cannot change the set of read-only classes in +a UnitOfWork after that UnitOfWork has been used. \{0}Changes to the +read-only set must be made when acquiring the UnitOfWork or immediately +after.# *Cause*: Attempt to change the set of read-only classes in a +unit of work after that unit of work has been used. Changes to the +read-only set must be made when acquiring the unit of work or +immediately after. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07042: Database platform class [\{0}] not found.# +*Cause*: The platform class className was not found and a reflection +exception is raised. + +*Action*: Check the internal exception. + +[.msg]#ECLIPSELINK-07043: [\{0}] does not have any tables to create on +the database.# *Cause*: A project project does not have any tables to +create on the database. + +*Action*: Validate the project and tables you are attempting to create. + +[.msg]#ECLIPSELINK-07044: The container class specified [\{0}] cannot be +used as a container because it does not implement Collection or Map.# +*Cause*: Illegal attempt to use the class className as the +container-this class does not implement the Collection or Map +interfaces. + +*Action*: Implement either the Collection or Map interfaces in the +container class. + +[.msg]#ECLIPSELINK-07047: The container specified [\{0}] does not +require keys. You tried to use the method [\{1}].# *Cause*: Invalid Map +class was specified for the container policy. The container specified +(of Class aPolicyContainerClass) does not require keys. You tried to use +the method methodName. + +*Action*: Use map class that implements the Map interface. + +[.msg]#ECLIPSELINK-07048: Neither the instance method or field named +[\{0}] exists for the item class [\{1}], and therefore cannot be used to +create a key for the Map.# *Cause*: The key method on the map container +policy is not defined. The instance method methodName does not exist in +the reference class className and therefore cannot be used to create a +key in a map. A map container policy represents the way to handle an +indexed collection of objects. Usually the key is the primary key of the +objects stored, so the policy needs to know the name of the primary key +getter method in order to extract it from each object using reflection. +For instance, a user might call policy.setKeyMethodName("`getId`"). + +*Action*: Check the second parameter of the useMapClass method of +DatabaseQuery. + +[.msg]#ECLIPSELINK-07051: Missing attribute [\{1}] for descriptor +[\{0}], called from [\{2}]# *Cause*: Missing attribute attributeName for +descriptor descriptor called from methodName. This is an EclipseLink +development exception, and you should never encounter it. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07052: An attempt was made to use [\{0}] (with the +key method [\{1}]) as a container for a DirectCollectionMapping [\{0}]. +The useMapClass() method cannot be used, only the useCollectionClass() +API is supported for DirectCollectionMappings.# *Cause*: The method +useMapClass was called on a DirectCollectionMapping. It is invalid to +call the useMapClass method on a DirectCollectionMapping. EclipseLink +cannot instantiate Java attributes mapped using a +DirectCollectionMapping with a map. The useMapClass method is supported +for OneToManyMapping and ManyToManyMapping. The Java 2 Collection +interface is supported using the useCollectionClass method. + +*Action*: Use the useCollectionClass method. Do not call the useMapClass +method on DirectCollectionMapping. + +[.msg]#ECLIPSELINK-07053: release() attempted on a Session that is not a +ClientSession. Only ClientSessions may be released.# *Cause*: +EclipseLink is unable to release a session that is not a client session. +Only client sessions can be released. + +*Action*: Modify the code to ensure the client session is not released. + +[.msg]#ECLIPSELINK-07054: acquire() attempted on a Session that is not a +ServerSession. ClientSessions may only be acquired from ServerSessions.# +*Cause*: EclipseLink is unable to acquire a session that is not a client +session. Client sessions can be acquired only from server sessions. + +*Action*: Modify the code to ensure an acquire session is attempted only +from server sessions. + +[.msg]#ECLIPSELINK-07055: Optimistic Locking is not supported with +stored procedure generation.# *Cause*: Attempt to use optimistic locking +with stored procedure generation. This is not supported. + +*Action*: Do not use optimistic locking with stored procedure +generation. + +[.msg]#ECLIPSELINK-07056: The wrong object was registered into the +UnitOfWork. The object [\{0}] should be the object from the parent cache +[\{1}].# *Cause*: The wrong object was registered into the unit of work. +It should be the object from the parent cache. + +*Action*: Ensure that the object is from the parent cache. + +[.msg]#ECLIPSELINK-07058: Invalid Connector [\{0}] (must be of type +DefaultConnector).# *Cause*: The connector selected is invalid and must +be of type DefaultConnector. + +*Action*: Ensure that the connector is of type DefaultConnector. + +[.msg]#ECLIPSELINK-07059: Invalid data source name [\{0}].# *Cause*: +Invalid data source name dsName. + +*Action*: Verify the data source name. + +[.msg]#ECLIPSELINK-07060: Cannot acquire data source [\{0}].# *Cause*: +EclipseLink is unable to acquire the data source with the name dsName, +or an error has occurred in setting up the data source. + +*Action*: Verify the data source name. Check the nested SQL exception to +determine the cause of the error. Typical problems include:The +connection pool was not configured in your config.xml file.The driver is +not on the classpath.The user or password is incorrect.The database +server URL or driver name is not properly specified. + +[.msg]#ECLIPSELINK-07061: Exception occurred within JTS.# *Cause*: An +exception occurred within the Java Transaction Service (JTS). + +*Action*: Examine the JTS exception and see the JTS documentation. + +[.msg]#ECLIPSELINK-07062: Field-level locking is not supported outside +of a UnitOfWork. To use field-level locking, a UnitOfWork must be used +for ALL writing.# *Cause*: Attempt to use FieldLevelLocking outside a +unit of work. This is not supported. In order to use field-level +locking, a unit of work must be used for all write operations. + +*Action*: Use a unit of work for writing. + +[.msg]#ECLIPSELINK-07063: Exception occurred within EJB container.# +*Cause*: An exception occurred within the EJB container. + +*Action*: Examine the EJB exception and see the JTS documentation. + +[.msg]#ECLIPSELINK-07064: Exception occurred in reflective EJB primary +key extraction. Please ensure your primary key object is defined +correctly. \{2}Key: [\{0}] \{2}Bean: [\{1}]# *Cause*: An exception +occurred in the reflective enterprise bean primary key extraction. + +*Action*: Ensure that your primary key object is defined correctly. + +[.msg]#ECLIPSELINK-07065: The remote class for the bean cannot be loaded +or found. Ensure that the correct class loader is set. \{2}Bean: [\{0}] +\{2}Remote Class: [\{1}]# *Cause*: The remote class for the bean cannot +be loaded or found. + +*Action*: Ensure that the correct class loader is set properly. + +[.msg]#ECLIPSELINK-07066: Cannot create or remove beans unless a JTS +transaction is present. \{1}Bean: [\{0}]# *Cause*: Attempt to create or +remove an enterprise bean outside of a transaction: EclipseLink is +unable to create or remove enterprise beans unless a JTS transaction is +present, bean=bean. + +*Action*: Ensure that the JTS transaction is present. + +[.msg]#ECLIPSELINK-07068: The project class [\{0}] was not found for the +project [\{1}] using the default class loader.# *Cause*: The platform +class platformName was not found for the project projectName using the +default class loader. + +*Action*: Validate the project and platform. + +[.msg]#ECLIPSELINK-07069: An exception occurred looking up or inovking +the project amendment method, ’'`\{0}`'’ on the class ’'`\{1}`'’.# +*Cause*: An exception occurred while looking up or invoking the project +amendment method amendmentMethod on the class amendmentClass. + +*Action*: Validate the amendment method and class. + +[.msg]#ECLIPSELINK-07070: an EclipseLINKLink.properties resource bundle +must be located on the CLASSPATH in an EclipseLink directory.# *Cause*: +Attempt to load toplink.properties resource bundle outside the +classpath: the resource bundle must be located on the classpath in an +EclipseLink directory. + +*Action*: Validate the classpath and the location of the EclipseLink +resource bundle. + +[.msg]#ECLIPSELINK-07071: Cannot use input/output parameters without +using binding.# *Cause*: Attempt to use input or output parameters +without using binding. + +*Action*: Use binding on the StoredProcedureCall. + +[.msg]#ECLIPSELINK-07072: The database platform class [\{0}] was not +found for the project [\{1}] using the default class loader.# *Cause*: +SessionManager failed to load the class identified by the value +associated with properties platform-class or +external-transaction-controller-class during initialization when it +loads the EclipseLink session common properties from the EclipseLink +global properties file (sessions.xml for non-EJB applications, or +toplink-ejb-jar.xml for EJB applications). + +*Action*: Ensure that your EclipseLink global properties file is +correctly configured. Pay particular attention to the platform-class and +external-transaction-controller-class properties. + +[.msg]#ECLIPSELINK-07073: The Oracle object type with type name [\{0}] +is not defined.# *Cause*: The Oracle object type with type name typeName +is not defined. + +*Action*: Ensure that the Oracle object type is defined. + +[.msg]#ECLIPSELINK-07074: The Oracle object type name [\{0}] is not +defined.# *Cause*: The Oracle object type typeName is not defined. + +*Action*: Ensure that the Oracle object type is defined. + +[.msg]#ECLIPSELINK-07075: Maximum size is not defined for the Oracle +VARRAY type [\{0}]. A maximum size must be defined.# *Cause*: The Oracle +VARRAY type typeName maximum size is not defined. + +*Action*: Verify the maximum size for the Oracle VARRAY. + +[.msg]#ECLIPSELINK-07076: When generating the project class, the +project’’s descriptors must not be initialized. \{1}Descriptor: [\{0}]# +*Cause*: Attempt to generate a project class while descriptors have +already been initialized: when generating the project class, the +descriptors must not be initialized. + +*Action*: Ensure that the descriptors are not initialized before +generating the project class. + +[.msg]#ECLIPSELINK-07077: The home interface [\{0}], specified during +creation of the BMPWrapperPolicy, does not contain a correct +findByPrimaryKey() method. A findByPrimaryKey() method must exist that +takes the PrimaryKey class for this bean.# *Cause*: The home interface +toString method specified during creation of BMPWrapperPolicy does not +contain a correct findByPrimaryKey method. A findByPrimaryKey method +must exist that takes the PrimaryKey class for this bean. + +*Action*: Ensure that a findByPrimaryKey method exists and is correct. + +[.msg]#ECLIPSELINK-07078: The "`sessionName`" [\{0}], specified on the +deployment descriptor for [\{1}], does not match any session specified +in the EclipseLink properties file.# *Cause*: The sessionName specified +on the deployment descriptor does not match any session specified in the +toplink.properties file. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07079: The descriptor for [\{0}] was not found in the +session [\{1}]. Check the project being used for this session.# *Cause*: +The descriptor was not found in the session. + +*Action*: Check the project being used for this session. + +[.msg]#ECLIPSELINK-07080: A FinderException was thrown when trying to +load [\{0}], of class [\{1}], with primary key [\{2}].# *Cause*: A +FinderException is raised when attempting to load an object from the +class with the primary key. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07081: The aggregate object [\{0}] cannot be directly +registered in the UnitOfWork. It must be associated with the source +(owner) object.# *Cause*: Attempt to register an aggregate object +directly in the unit of work. This is not supported. The aggregate +object must be associated with the source (owner) object. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07082: The EclipseLink properties file [\{0}] +specified multiple project files for the server named [\{1}]. Please +specify one of [projectClass], [projectFile], or [xmlProjectFile].# +*Cause*: The toplink.properties file specified multiple project files +for the server. Only one project file can be specified. + +*Action*: Specify either projectClass, projectFile, or xmlProjectFile. + +[.msg]#ECLIPSELINK-07083: The EclipseLink properties file [\{0}] did not +include any information on the EclipseLink project to use for the server +named [\{1}]. Please specify one of [projectClass], [projectFile], or +[xmlProjectFile].# *Cause*: The toplink.properties file does not include +any information on the EclipseLink project to use for the server. One +project file must be specified. + +*Action*: Specify either projectClass, projectFile, or xmlProjectFile. + +[.msg]#ECLIPSELINK-07084: The file [\{0}] is not a valid type for +reading. ProjectReader must be given the deployed XML Project file.# +*Cause*: The specified file is not a valid type for reading. +ProjectReader must be given the deployed XML project file. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07085: At least one sub session need to be defined in +the EclipseLink session broker \{0}# *Cause*: EclipseLink is unable to +create an instance of the external transaction controller specified in +the properties file. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07086: The session type ’'`\{0}`'’ of the session +name ’'`\{1}`'’ was not defined properly.# *Cause*: The session manager +cannot load the class corresponding to the session’s type class name. + +*Action*: Ensure that the class name of the session’s type is fully +qualified in the sessions.xml file or toplink.properties file. + +[.msg]#ECLIPSELINK-07087: The session type ’'`\{0}`'’ was not found for +the ’'`\{1}`'’ using default class loader.# *Cause*: The session manager +cannot load the class corresponding to the session’s type class name. + +*Action*: Ensure that the class name of the session’s type is fully +qualified in the sessions.xml file or toplink.properties file. + +[.msg]#ECLIPSELINK-07088: Cannot create an instance of the external +transaction controller [\{0}], specified in the properties file.# +*Cause*: The session manager cannot load the class corresponding to the +external transaction controller’s class name. + +*Action*: Ensure that the class name of the external transaction +controller is valid and fully qualified in the sessions.xml file or +toplink.properties file. + +[.msg]#ECLIPSELINK-07089: An exception occurred looking up or invoking +the session amendment method [\{0}] on the class [\{1}] with parameters +[\{2}].# *Cause*: The session manager cannot load the class +corresponding to the amendment class name, or it cannot load the method +on the amendment class corresponding to the amendment method name. + +*Action*: Ensure that the class name of the amendment class is fully +qualified, and the amendment method exists in the amendment class in the +sessions.xml file or toplink.properties file. + +[.msg]#ECLIPSELINK-07091: Cannot set listener classes!# *Cause*: +EclipseLink is unable to create the listener class that implements +SessionEventListener for the internal use of SessionXMLProject. + +*Action*: Contact Oracle Support Services. + +[.msg]#ECLIPSELINK-07092: Cannot add a query whose types conflict with +an existing query. Query To Be Added: [\{0}] is named: [\{1}] with +arguments [\{2}].The existing conflicting query: [\{3}] is named: [\{4}] +with arguments: [\{5}].# *Cause*: EclipseLink has detected a conflict +between a custom query with the same name and arguments to a session. + +*Action*: Ensure that no query is added to the session more than once or +change the query name so that the query can be distinguished from +others. + +[.msg]#ECLIPSELINK-07093: In the query named [\{0}], the class [\{2}] +for query argument named [\{1}] cannot be found. Please include the +missing class on your classpath.# *Cause*: EclipseLink is unable to +create an instance of the query argument type. + +*Action*: Ensure that the argument type is a fully qualified class name +and the argument class is included in the classpath environment. + +[.msg]#ECLIPSELINK-07095: The sessions.xml resource [\{0}] was not found +on the resource path. Check that the resource name/path and classloader +passed to the SessionManager.getSession are correct. The sessions.xml +should be included in the root of the application’s deployed jar, if the +sessions.xml is deployed in a sub-directory in the application’s jar +ensure that the correct resource path using "`/`" not "`\`" is used.# +*Cause*: The sessions.xml or toplink.properties file cannot be loaded. + +*Action*: Ensure that the path to either of the files exists on the +classpath environment. The sessions.xml should be included in the root +of the deployed JAR file. When using a WAR file, the sessions.xml file +should be located in the WEB-INF/classes directory. When using EJB 3.0, +EclipseLink automatically loads the ejb3-toplink-sessions.xml file. + +[.msg]#ECLIPSELINK-07096: Cannot use commit() method to commit +UnitOfWork again.# *Cause*: EclipseLink cannot invoke commit method on +an inactive unit of work that was committed or released. + +*Action*: Ensure you invoke commit method on a new unit of work or +invoke commitAndResume method so that the unit of work can be reused. +For more information about the commitAndResume method, see Oracle +EclipseLink API Reference. + +[.msg]#ECLIPSELINK-07097: Operation not supported: [\{0}].# *Cause*: +EclipseLink cannot invoke an unsupported operation on an object. + +*Action*: Do not use the operation indicated in the stack trace. + +[.msg]#ECLIPSELINK-07099: The deployment project xml resource [\{0}] was +not found on the resource path. Check that the resource name/path and +classloader passed to the XMLProjectReader are correct. The project xml +should be included in the root of the application’s deployed jar, if the +project xml is deployed in a sub-directory in the application’s jar +ensure that the correct resource path using "`/`" not "`\`" is used.# +*Cause*: The file name specified for the XML-based project is incorrect. + +*Action*: Verify the name and location of the file. + +[.msg]#ECLIPSELINK-07101: No "`meta-inf/toplink-ejb-jar.xml`" could be +found in your classpath. The CMP session could not be read in from +file.# *Cause*: The toplink-ejb-jar.xml file was not found. + +*Action*: Ensure that the file is on your classpath. + +[.msg]#ECLIPSELINK-07102: Encountered a null value for a cache key while +attempting to remove\{2}an object from the identity map: +[\{0}]\{2}containing an object of class: [\{1}] (or a class in this +hierarchy)\{2}The most likely cause of this situation is that the object +has already been garbage-\{2}collected and therefore does not exist +within the identity map.\{2}Please consider using an alternative +identity map to prevent this situation.\{2}For more details regarding +identity maps, please refer to the EclipseLink documentation.# *Cause*: +Encountered a null value for a cache key while attempting to remove an +object from the identity map. The most likely cause of this situation is +that the object has already been garbage-collected and therefore does +not exist within the identity map. + +*Action*: Ignore. The removeFromIdentityMap method of the Session is +intended to allow garbage collection, which has already been done. + +[.msg]#ECLIPSELINK-07103: A null reference was encountered while +attempting to invoke\{1}method: [\{0}] on an object which uses proxy +indirection.\{1}Please check that this object is not null before +invoking its methods.# *Cause*: A null reference was encountered while +attempting to invoke a method on an object that uses proxy indirection. + +*Action*: Check that this object is not null before invoking its +methods. + +[.msg]#ECLIPSELINK-07104: Sequencing login should not use External +Transaction Controller.# *Cause*: A separate connection(s) for +sequencing was requested, but the sequencing login uses the external +transaction controller. + +*Action*: Either provide a sequencing login that does not use an +external transaction controller or do not use separate connection(s) for +sequencing. + +[.msg]#ECLIPSELINK-07105: Error encountered converting encryptiong +class: [\{0}]# *Cause*: Error encountered while converting encryption +class. + +*Action*: Ensure the encryption class name is correctly specified in the +sessions.xml file and that the encryption class specified is available +on the classpath. A common reason for this exception is the usage of JDK +1.3 and earlier versions. The EclipseLink JCE encryption mechanism +requires JDK 1.4 and later (or JDK 1.3 configured with the JCE plug-in) +to function properly. + +[.msg]#ECLIPSELINK-07106: Error encountered during string encryption.# +*Cause*: Error encountered during password string encryption. + +*Action*: An error is raised while trying to encrypt the password +string. A common reason for this exception is the usage of JDK 1.3 and +earlier versions. The EclipseLink JCE encryption mechanism requires JDK +1.4 and later (or JDK 1.3 configured with the JCE plug-in) to function +properly. + +[.msg]#ECLIPSELINK-07107: Error encountered during string decryption.# +*Cause*: Error encountered during password string decryption. + +*Action*: An exception was raised while trying to decrypt the password +string. A common reason for this exception is the usage of JDK 1.3 and +earlier versions. The EclipseLink JCE encryption mechanism requires JDK +1.4 and later (or JDK 1.3 configured with the JCE plug-in) to function +properly. + +[.msg]#ECLIPSELINK-07108: This operation is not supported for +non-relational platforms.# *Cause*: Attempt to use an operation that is +not supported for nonrelational platforms. + +*Action*: Do not use this operation on the current platform, or use a +relational database platform. + +[.msg]#ECLIPSELINK-07109: The login in the project used to create the +session is null, it must be a valid login.# *Cause*: The login in the +project used to create the session is null meaning no login was +specified for the EclipseLink project. The login used for the project +must be a valid login. + +*Action*: Add login information using EclipseLink Workbench or using +Java code. + +[.msg]#ECLIPSELINK-07110: At present HistoricalSession only works with +Oracle 9R2 or later databases, as it uses Oracle’s Flashback feature.# +*Cause*: Attempt to use a HistoricalSession with a non-Oracle database. +At present, HistoricalSession only works with Oracle databases that have +a Flashback feature (Oracle database 9.2.0.4 or later).Generic history +support (see org.eclipse.persistence.history.HistoryPolicy) works for +any database. If a HistoryPolicy is incorrectly set, EclipseLink may be +defaulting to using flashback instead. An AsOfSCNClause is implicitly +flashback only. + +*Action*: Ensure that the HistoryPolicy is set correctly. + +[.msg]#ECLIPSELINK-07111: You may not acquire a HistoricalSession from a +UnitOfWork, another HistoricalSession, a ServerSession, or a +ServerSessionBroker. You may acquire one from a regular session, a +ClientSession, or a ClientSessionBroker.# *Cause*: Invalid attempt to +acquire a HistoricalSession: you may not acquire a HistoricalSession +from a unit of work, another HistoricalSession, a ServerSession, or a +ServerSessionBroker. You may acquire a HistoricalSession from a regular +session, a ClientSession, or a ClientSessionBroker. + +*Action*: To recover objects, read the objects in both a +HistoricalSession and UnitOfWork, and call +mergeCloneWithReferences(historicalObject) method on the UnitOfWork. + +[.msg]#ECLIPSELINK-07112: You have specified that Toplink use the +feature : \{0}, but this feature is not available in the currently +running JDK version :\{1}.# *Cause*: Attempt to use an EclipseLink +feature that is not available in the current JDK version. + +*Action*: You must use the version of the JDK that supports this +feature. + +[.msg]#ECLIPSELINK-07113: \{0} does not support call with returning.# +*Cause*: Attempt to use an unsupported call with returning for a +platform. + +*Action*: Set stored procedures with output parameters in +setInsertQuery, setInsertCall, setUpdateQuery, or setUpdateCall methods +of the DescriptorQueryManager. + +[.msg]#ECLIPSELINK-07114: Isolated Data is not currently supported +within a Client Session Broker. Session named \{0} contains descriptors +representing isolated data.# *Cause*: Attempt to use isolated data +within a ClientSessionBroker: isolated data is not currently supported +within a ClientSessionBroker. Session contains descriptors representing +isolated data. + +*Action*: Ensure that isolated data is not used. + +[.msg]#ECLIPSELINK-07115: A Exclusive Connection cannot be used for +ClientSession reads without isolated data. Please update the +ConnectionPolicy, used, to remove ExclusiveConnection configuration or +the project to set certain data to be exclusive.# *Cause*: Attempt to +use ExclusiveConnection for ClientSession reads without isolated data. +This is not supported. + +*Action*: You must update the ConnectionPolicy used to remove +ExclusiveConnection configuration, or the project to set certain data to +be exclusive. + +[.msg]#ECLIPSELINK-07116: Invalid arguments are used. Please refer to +public API of the calling method and use valid values for the +arguments.# *Cause*: Invalid arguments are used in the method. + +*Action*: Refer to the public API of the calling method and use valid +values for the arguments. + +[.msg]#ECLIPSELINK-07117: There is an attempt to use more than one +cursor in SQLCall \{0}# *Cause*: Attempt to use more than one cursor in +a SQLCall. + +*Action*: EclipseLink currently supports only one cursor per call. + +[.msg]#ECLIPSELINK-07118: setCustomSQLArgumentType method was called on +SQLCall \{0}, but this call doesn’t use custom SQL# *Cause*: The +setCustomSQLArgumentType method was invoked on SQLCall, but this method +does not use custom SQL. + +*Action*: Don’t call this method on SQLCall that does not use custom +SQL. + +[.msg]#ECLIPSELINK-07119: Unprepared SQLCall \{0} attempted translation# +*Cause*: Unprepared SQLCall attempted translation. + +*Action*: SQLCall must be prepared before translation. + +[.msg]#ECLIPSELINK-07120: Parameter \{0} in SQLCall \{1} cannot be used +as a cursor, because it is has parameter type other than OUT# *Cause*: +Attempt to use parameter in SQLCall as a cursor, but this parameter is +of type other than OUT. + +*Action*: Ensure that the parameter used as a cursor has parameter type +OUT. + +[.msg]#ECLIPSELINK-07121: \{0} does not support stored functions# +*Cause*: Attempt to use stored functions for a platform that does not +support stored functions. + +*Action*: Do not define stored functions on this platform. + +[.msg]#ECLIPSELINK-07122: The exclusive connection associated with the +session is unavailable for the query on \{0}# *Cause*: The exclusive +connection associated with the session is unavailable for the query on +the object.Isolated objects with indirection read through an +ExclusiveIsolatedClientSession must not have indirection triggered after +the ExclusiveIsolatedClientSession has been released. + +*Action*: Reread the objects through the current +ExclusiveIsolatedClientSession. + +[.msg]#ECLIPSELINK-07123: A successful writeChanges() has been called on +this UnitOfWork. As the commit process has been started but not yet +finalized, the only supported operations now are commit, +commitAndResume, release, any non-object level query or SQLCall +execution. The operation \{0} is not allowed at this time.# *Cause*: +Attempt to perform an operation that is not allowed at this time: a +successful writeChanges operation has been called on this UnitOfWork. As +the commit process has been started, but not yet finalized, the only +supported operations now are commit, commitAndResume, release, any +nonobject level query, or SQLCall execution. + +*Action*: Execute one of the supported operations to continue. + +[.msg]#ECLIPSELINK-07124: An unsuccessful writeChanges() has been called +on this UnitOfWork. Given the danger that partial changes have been +written to the datastore but not rolled back (if inside external +transaction), the only supported operations now are release, global +transaction rollback, any non-object level query or SQLCall execution. +The operation \{0} was attempted.# *Cause*: Attempt to perform an +operation that is not allowed at this time: an unsuccessful writeChanges +operation has been called on this UnitOfWork. Given the possibility that +partial changes have been written to the data store but not rolled back +(if inside external transaction), the only supported operations now are +release, global transaction rollback, any nonobject level query or +SQLCall execution. + +*Action*: Determine the cause of the original failure and retry in a new +UnitOfWork. + +[.msg]#ECLIPSELINK-07125: Once the UnitOfWork has been committed and/or +released, no further operation should be performed on it. The operation +\{0} was attempted on it.# *Cause*: Attempt to perform an operation on +an inactive unit of work: once the UnitOfWork has been committed and/or +released, no further operation should be performed on it. + +*Action*: Acquire a new UnitOfWork, or use the commitAndResume method +instead of commit method in the future. + +[.msg]#ECLIPSELINK-07126: writeChanges cannot be called on a +NestedUnitOfWork. A nested UnitOfWork never writes changes directly to +the datastore, only the parent UnitOfWork does.# *Cause*: Attempt to +call a writeChanges method on a NestedUnitOfWork. This is not supported: +a nested UnitOfWork never writes changes directly to the data store, +only the parent UnitOfWork does. + +*Action*: Call the commit method instead, and then the writeChanges +method on the parent UnitOfWork. + +[.msg]#ECLIPSELINK-07127: You can only writes changes to the datastore +once, just as you can only call commit once.# *Cause*: Attempt to write +changes to the data store more than once: you can only write changes to +the data store once. + +*Action*: You must either roll back the transaction, or call the commit +method on this UnitOfWork and start a new transaction. + +[.msg]#ECLIPSELINK-07128: Session [\{0}] is already logged in.# *Cause*: +Attempt to log in to a session more than once. + +*Action*: Do not try to login again. + +[.msg]#ECLIPSELINK-07129: The method’’s arguments cannot have null +value.# *Cause*: Attempt to use null values for arguments in a method +that cannot have null values. + +*Action*: Ensure that the method’s arguments do not have a null value. + +[.msg]#ECLIPSELINK-07130: Nested unit of work is not supported for +attribute change tracking.# *Cause*: Attempt to use a nested UnitOfWork +with attribute change tracking. This is not supported. + +*Action*: Do not use a nested UnitOfWork with attribute change tracking. + +[.msg]#ECLIPSELINK-07131: \{0} is the wrong type. The collection change +event type has to be add or remove.# *Cause*: The collection change +event is of the wrong type. The collection change event type has to be +added or removed. + +*Action*: Ensure that the collection change event type used is defined +in CollectionChangeEvent. + +[.msg]#ECLIPSELINK-07132: \{0} is the wrong event class. Only +PropertyChangeEvent and CollectionChangeEvent are supported.# *Cause*: +Wrong event class. Only PropertyChangeEvent and CollectionChangeEvent +classes are supported. + +*Action*: Ensure that the event class is either PropertyChangeEvent or +CollectionChangeEvent. + +[.msg]#ECLIPSELINK-07133: Old commit is not supported for attribute +change tracking.# *Cause*: Attempt to use old commit for attribute +change tracking. This is not supported. + +*Action*: Do not try to use attribute change tracking with an old +commit. + +[.msg]#ECLIPSELINK-07134: Server platform \{0} is read only after +login.# *Cause*: Attempt to make changes to the server platform after +login: the server platform is read-only after login. + +*Action*: Changes to the server platform must be made before login. You +must either:CMP application: define a class that implements +oracle.toplink.ejb.cmp.DeploymentCustomization, and customize its public +String beforeLoginCustomization(Session session) method to change your +server platform. Consult the documentation for defining a customization +class in your orion-ejb-jar.xml file.Non-CMP/POJO application: define a +subclass of org.eclipse.persistence.sessions.SessionEventAdapter, and +override the public void preLogin(SessionEvent event) method to change +your server platform. The session is contained in the event. Consult the +documentation for sessions.xml and using SessionEventAdapter. + +[.msg]#ECLIPSELINK-07135: You cannot commit and resume a unit of work +containing any modify all queries# *Cause*: Attempt to commit and resume +a UnitOfWork containing an UpdateAllQuery. This is not supported. + +*Action*: You must either commit and continue in a new UnitOfWork, or do +not use UpdateAllQuery. + +[.msg]#ECLIPSELINK-07136: Nested unit of work is not supported for a +modify all query# *Cause*: Attempt to use a nested UnitOfWork for an +UpdateAll query. This is not supported. + +*Action*: Do not use a nested UnitOfWork for an UpdateAllQuery. + +[.msg]#ECLIPSELINK-07137: The object is partially fetched (using fecth +group), the unfetched attribute (\{0}) is not editable.# *Cause*: +Attempt to edit an unfetched attribute: the object is partially fetched +(using fetch group), the unfetched attribute is not editable. + +*Action*: Do not edit the unfetched attribute, or explicitly fetch the +attribute before editing it. + +[.msg]#ECLIPSELINK-07139: Modify all queries cannot be issued within a +unit of work containing other write operations.# *Cause*: Attempt to +issue an UpdateAll query within a UnitOfWork containing other write +operations. + +*Action*: Do not use UpdateAllQuery within a UnitOfWork containing other +write operations. + +[.msg]#ECLIPSELINK-07140: Sequence type \{0} doesn’’t have method \{1}.# +*Cause*: Sequence type does not have the method. + +*Action*: Do not call this method on this type of sequence. + +[.msg]#ECLIPSELINK-07144: \{0}: platform \{1} doesn’’t support \{2}.# +*Cause*: Platform does not support sequence. + +*Action*: Do not use this sequence type on this platform. + +[.msg]#ECLIPSELINK-07145: \{2} attempts to connect to sequence \{0}, but +it is already connected to \{1}. Likely the two sessions share the +DatasourcePlatform object# *Cause*: Two attempts have been made to +connect to sequence, but the sequence is already connected to a +platform. Likely the two sessions share the DatasourcePlatform object. + +*Action*: Ensure that the sequence is used by a single session only. + +[.msg]#ECLIPSELINK-07146: QuerySequence \{1} doesn’’t have select +query.# *Cause*: QuerySequence does not have select query. + +*Action*: Ensure that the sequence has a select query. + +[.msg]#ECLIPSELINK-07147: Platform \{0} cannot create platform default +sequence - it doesn’’t override createPlatformDefaultSequence method# +*Cause*: Attempt to create platform default sequence by a platform that +does not override the createPlatformDefaultSequence method. + +*Action*: You must either override the createPlatformDefaultSequence +method on the platform, or explicitly set default sequence by calling +setDefaultSequence on DatasourceLogin. + +[.msg]#ECLIPSELINK-07148: commitAndResume() cannot be used with a +JTA/synchronized unit of work.# *Cause*: Attempt to use +commitAndResume() method with a JTA or a synchronized unit of work. + +*Action*: Do not use commitAndResume() with a JTA or a synchronized unit +of work. + +[.msg]#ECLIPSELINK-07149: The composite primary key attribute [\{2}] of +type [\{4}] on entity class [\{0}] should be of the same type as defined +on its primary key class [\{1}]. That is, it should be of type [\{3}].# +*Cause*: Attempt to provide an invalid specification of the composite +primary key: the names of the primary key fields or properties in the +primary key class PKClassName and those of the entity bean class +ClassName must correspond and their types must be the same. + +*Action*: Ensure that the names of the primary key fields or properties +in the primary key class PKClassName and those of the entity bean class +ClassName correspond, and their types are the same. + +[.msg]#ECLIPSELINK-07150: Invalid composite primary key specification. +The names of the primary key fields or properties in the primary key +class [\{1}] and those of the entity bean class [\{0}] must correspond +and their types must be the same. Also, ensure that you have specified +id elements for the corresponding attributes in XML and/or an @Id on the +corresponding fields or properties of the entity class.# *Cause*: +Attempt to specify an invalid LAZY fetch type on an attribute +attributeName within entity class ClassName. + +*Action*: Provide the fetch type other than LAZY on an attribute +attributeName within entity class ClassName. + +[.msg]#ECLIPSELINK-07151: The type [\{1}] for the attribute [\{0}] on +the entity class [\{2}] is not a valid type for an enumerated mapping. +The attribute must be defined as a Java enum.# *Cause*: An invalid EJB +3.0 annotation annotation has been specified in the entity class +ClassName on accessor method methodName. It is not supported. + +*Action*: Specify a valid annotation on this accessor method. + +[.msg]#ECLIPSELINK-07152: Table per class inheritance is not supported. +Entity class [\{0}].# *Cause*: Table per class inheritance is not +supported. Entity class ClassName. + +*Action*: Use different approach. + +[.msg]#ECLIPSELINK-07153: Mapping annotations cannot be applied to +fields or properties that are transient or have a @Transient specified. +[\{0}] is in violation of this restriction.# *Cause*: The descriptor +named query query already exists. Named query names must be unique. + +*Action*: Provide a unique name for the query. + +[.msg]#ECLIPSELINK-07154: The attribute [\{3}] in entity class [\{2}] +has a mappedBy value of [\{1}] which does not exist in its owning entity +class [\{0}]. If the owning entity class is a @MappedSuperclass, this is +invalid, and your attribute should reference the correct subclass.# +*Cause*: An annotation @AssociationTable was not found on either the +owning mapping class ClassName, or nonowning mapping class +DifferentClassName for the @ManyToMany annotation. + +*Action*: Ensure that the annotation @AssociationTable exists. + +[.msg]#ECLIPSELINK-07155: The type [\{1}] for the attribute [\{0}] on +the entity class [\{2}] is not a valid type for a serialized mapping. +The attribute type must implement the Serializable interface.# *Cause*: +An annotation @AttributeOverride columns was not specified on a mapping +mapping from entity class ClassName. + +*Action*: Specify this annotation. + +[.msg]#ECLIPSELINK-07156: Unable to find the class named [\{0}]. Ensure +the class name/path is correct and available to the classloader.# +*Cause*: EclipseLink was unable to find the class ClassName. Ensure the +class name/path is correct and available to the class loader. + +*Action*: Ensure the class name and/or path is correct and available to +the class loader. + +[.msg]#ECLIPSELINK-07157: Entity class [\{0}] must use a @JoinColumn +instead of @Column to map its relationship attribute [\{1}].# *Cause*: +Attempt to use an invalid@Column annotation by the entity class +ClassName to map its relationship attribute attribute. + +*Action*: Ensure the entity class ClassName uses a @JoinColumn attribute +instead of a @Column attribute to map its relationship attribute +attributeName. + +[.msg]#ECLIPSELINK-07158: Error encountered when building the +@NamedQuery [\{1}] from entity class [\{0}].# *Cause*: Error encountered +when building the @NamedQuery annotation from entity class ClassName. + +*Action*: Ensure the correctness of the annotation specification. + +[.msg]#ECLIPSELINK-07159: The map key [\{0}] on the entity class [\{1}] +could not be found for the mapping [\{2}].# *Cause*: Invalid use of an +unnamed @NamedQuery annotation with the query string string by an entity +class ClassName . + +*Action*: Specify a name for @NamedQuery. + +[.msg]#ECLIPSELINK-07160: @OneToMany for attribute name [\{1}] in entity +class [\{0}] should not have @JoinColumn(s) specified. In the case where +the @OneToMany is not mapped by another entity (that is, it is the +owning side and is uni-directional), it should specify (optional through +defaulting) a @JoinTable.# *Cause*: @OneToMany annotation for attribute +attributeName in entity class ClassName has both an @AssocationTable and +@JoinColumn(s) annotations specified. + +*Action*: Specify one annotation only: @AssocationTable or +@JoinColumn(s). + +[.msg]#ECLIPSELINK-07161: Entity class [\{0}] has no primary key +specified. It should define either an @Id, @EmbeddedId or an @IdClass. +If you have defined PK using any of these annotations then please make +sure that you do not have mixed access-type (both fields and properties +annotated) in your entity class hierarchy.# *Cause*: Primary key +annotation is not specified for the entity class ClassName. + +*Action*: Define either an @Id, @EmbeddedId or an @IdClass annotation. + +[.msg]#ECLIPSELINK-07162: Entity class [\{0}] has multiple @EmbeddedId’s +specified (on attributes [\{1}] and [\{2}]). Only one @EmbeddedId can be +specified per entity.# *Cause*: Multiple @EmbeddedId annotations are +specified (on attributeName and differentAttributeName) for entity class +ClassName. + +*Action*: Specify only one @EmbeddedId annotation for this entity. + +[.msg]#ECLIPSELINK-07163: Entity class [\{0}] has both an @EmbdeddedId +(on attribute [\{1}]) and an @Id (on attribute [\{2}]. Both id types +cannot be specified on the same entity.# *Cause*: Entity class ClassName +has both an @EmbdeddedId (on attribute attributeName) and an @Id (on +attribute differentAttributeName). + +*Action*: Specify only one ID type on this entity: either @EmbdeddedId +or @Id. + +[.msg]#ECLIPSELINK-07164: The type [\{1}] for the attribute [\{0}] on +the entity class [\{2}] is not a valid type for a lob mapping. For a lob +of type BLOB, the attribute must be defined as a java.sql.Blob, byte[], +Byte[] or a Serializable type. For a lob of type CLOB, the attribute +must be defined as a java.sql.Clob, char[], Character[] or String type.# +*Cause*: Attribute attributeName in an entity class ClassName has an +invalid type for a @Lob annotation of type BLOB. + +*Action*: Define this attribute as a java.sql.Blob, byte[], Byte[] or a +Serializable type. + +[.msg]#ECLIPSELINK-07165: The type [\{1}] for the attribute [\{0}] on +the entity class [\{2}] is not a valid type for a temporal mapping. The +attribute must be defined as java.util.Date or java.util.Calendar.# +*Cause*: Attribute attributeName in entity class ClassName has an +invalid type for a @Lob annotation of type CLOB. + +*Action*: Define this attribute as a java.sql.Clob, char[], Character[] +or String type. + +[.msg]#ECLIPSELINK-07166: A table generator that uses the reserved name +[\{0}] for its '`name`' has been found in [\{1}]. It cannot use this +name since it is reserved for defaulting a sequence generator’s +'`sequence name`'.# *Cause*: Conflict between annotations @Annotation +and @DifferentAnnotation. + +*Action*: Ensure that these two annotations are not conflicting. + +[.msg]#ECLIPSELINK-07167: A sequence generator that uses the reserved +name [\{0}] for its '`sequence name`' has been found in [\{1}]. It +cannot use this name since it is reserved for defaulting a table +generator’s '`name`'.# *Cause*: Attempt to use a reserved annotation +name AnnotationName by an entity class ClassName: cannot use this name, +because it is reserved for name. + +*Action*: Specify a different name for this annotation. + +[.msg]#ECLIPSELINK-07168: The attribute [\{0}] of type [\{1}] on the +entity class [\{2}] is not valid for a version property. The following +types are supported: int, Integer, short, Short, long, Long, Timestamp.# +*Cause*: Attempt to specify a generator with type Type by an annotation +@Annotation. + +*Action*: Ensure that this annotation specifies a generator of a +different type. + +[.msg]#ECLIPSELINK-07169: Class [\{0}] has two @GeneratedValues: for +fields [\{1}] and [\{2}]. Only one is allowed.# *Cause*: The callback +method methodName on the entity listener ListenerClassName has an +incorrect signature. + +*Action*: Provide only one parameter of type Object for this method. + +[.msg]#ECLIPSELINK-07172: Error encountered when instantiating the class +[\{0}].# *Cause*: EclipseLink was unable to instantiate the entity +listener using the @EntityListener annotation. + +*Action*: Ensure that the annotation is correctly specified. + +[.msg]#ECLIPSELINK-07173: A property change event has been fired on a +property with name [\{1}] in [\{0}]. However this property does not +exist.# *Cause*: Attempt to fire a property change event on a +nonexisting property propertyName in a change event EventClassName. + +*Action*: Ensure that this property exists. + +[.msg]#ECLIPSELINK-07174: The getter method [\{1}] on entity class +[\{0}] does not have a corresponding setter method defined.# *Cause*: +The getter method methodName on an entity class ClassName does not have +a corresponding setter method defined. + +*Action*: Define a corresponding setter method. + +[.msg]#ECLIPSELINK-07175: The mapping [\{0}] does not support cascading +version optimistic locking.# *Cause*: Attempt to use the mapping +MappingType that does not support cascading version optimistic locking. + +*Action*: Use a different mapping. + +[.msg]#ECLIPSELINK-07176: The mapping [\{0}] does not support cascading +version optimistic locking because it has a custom query.# *Cause*: +Attempt to use the mapping MappingType that does not support cascading +version optimistic locking. This mapping has a custom query. + +*Action*: Use a different mapping. + +[.msg]#ECLIPSELINK-07177: The aggregate descriptor [\{0}] has +privately-owned mappings. Aggregate descriptors do not support cascading +version optimistic locking.# *Cause*: Attempt to use an aggregate +descriptor DescriptorName that has privately-owned mappings: aggregate +descriptors do not support cascading version optimistic locking. + +*Action*: Use a different descriptor. + +[.msg]#ECLIPSELINK-07178: OracleOCIProxyConnector requires +OracleOCIConnectionPool datasource.# *Cause*: Attempt to use invalid +arguments in an entity callback method methodName on a +OracleOCIProxyConnector: it requires the OracleOCIConnectionPool data +source. + +*Action*: Provide OracleOCIProxyConnector with the +OracleOCIConnectionPool argument. + +[.msg]#ECLIPSELINK-07179: OracleJDBC10_1_0_2ProxyConnector requires +datasource producing OracleConnections.# *Cause*: Attempt to use invalid +arguments in an entity callback method methodName on a +OracleJDBC10_1_0_2ProxyConnector. + +*Action*: Provide OracleJDBC10_1_0_2ProxyConnector with data source +producing Oracle Connections. + +[.msg]#ECLIPSELINK-07180: OracleJDBC10_1_0_2ProxyConnector requires +Oracle JDBC version 10.1.0.2 or higher so that OracleConnection declares +openProxySession method.# *Cause*: Attempt to use the +OracleJDBC10_1_0_2ProxyConnector with Oracle JDBC version 10.1.0.1 or +earlier: OracleJDBC10_1_0_2ProxyConnector requires Oracle JDBC version +10.1.0.2 or later. + +*Action*: Provide OracleJDBC10_1_0_2ProxyConnector with Oracle JDBC +version 10.1.0.2 or later in order for the OracleConnection to declare +the openProxySession method. + +[.msg]#ECLIPSELINK-07181: OracleJDBC10_1_0_2ProxyConnector requires +'`’proxytype`'’ property to be an int converted to String, for instance +Integer.toString(OracleConnection.PROXYTYPE_USER_NAME)# *Cause*: Attempt +to use an invalid type for the proxytype property on the +OracleJDBC10_1_0_2ProxyConnector: it requires the proxytype property to +be an int converted to a String. + +*Action*: On the OracleJDBC10_1_0_2ProxyConnector, provide the proxytype +property of type int converted to a String. For example, +Integer.toString(OracleConnection.PROXYTYPE_USER_NAME). + +[.msg]#ECLIPSELINK-07182: EC - Could not find driver class [\{0}]# +*Cause*: EclipseLink could not find the driver class. + +*Action*: Ensure that the driver class exists and is on the classpath. + +[.msg]#ECLIPSELINK-07183: Error closing persistence.xml file.# *Cause*: +EclipseLink cannot close persistence.xml file. + +*Action*: If you modified the persistence.xml, ensure that this file is +not read-only. + +[.msg]#ECLIPSELINK-07184: [\{0}] system property not specified. It must +be set to a class that defines a '`’getContainerConfig()`'’ method.# +*Cause*: The system property propertyName is not specified. + +*Action*: Set this property to a class that defines a +getContainerConfig() method. + +[.msg]#ECLIPSELINK-07185: Cannot find class [\{0}] specified in [\{1}]# +*Cause*: EclipseLink cannot find class ClassName. + +*Action*: Ensure that the class exists and is properly specified. + +[.msg]#ECLIPSELINK-07186: Cannot invoke method [\{0}] on class [\{1}] +specified in [\{2}]# *Cause*: EclipseLink cannot invoke method +methodName on configuration class ClassName. + +*Action*: Ensure that this method exists in this class. + +[.msg]#ECLIPSELINK-07187: [\{0}] should define a public static method +[\{1}] that has no parameters and returns Colleciton# *Cause*: Class +ClassName does not define a public static method methodName. + +*Action*: In the class ClassName, define a public static method +methodName that has no parameters and returns a Collection. + +[.msg]#ECLIPSELINK-07188: Non-null class list is required.# *Cause*: +Class list is null. + +*Action*: Provide a non-null class list. + +[.msg]#ECLIPSELINK-07189: Cannot create temp classloader from current +loader: [\{0}]# *Cause*: EclipseLink cannot create a temporary class +loader from the current loader ClassLoaderName. + +*Action*: Ensure the validity of the current class loader. + +[.msg]#ECLIPSELINK-07190: [\{0}] failed# *Cause*: Failure in the +execution of the methodName method. + +*Action*: Ensure the correctness of the method. + +[.msg]#ECLIPSELINK-07191: The entity class [\{0}] was not found using +class loader [\{1}].# *Cause*: An entity class ClassName was not found +using class loader ClassLoaderName. + +*Action*: Ensure that the entity class exists and is on the classpath. + +[.msg]#ECLIPSELINK-07192: ClassFileTransformer [\{0}] throws an +exception when performing transform() on class [\{1}].# *Cause*: Class +file transformer TransformerName threw an exception when performing +transform() method on class ClassName. + +*Action*: Ensure the correctness of the transform() method. Check the +internal exception for details on the root cause of this exception + +[.msg]#ECLIPSELINK-07193: Jar files in persistence XML are not supported +in this version of EclipseLink.# *Cause*: Attempt to use JAR files in +the persistence.xml file: JAR files are not supported in this version of +Toplink. + +*Action*: Do not use JAR files. + +[.msg]#ECLIPSELINK-07194: Could not bind: [\{0}] to: [\{1}].# *Cause*: +Attempt to use an unsupported method setFlushMode(). + +*Action*: Do not use this method. + +[.msg]#ECLIPSELINK-07195: Exception configuring EntityManagerFactory.# +*Cause*: EclipseLink could not bind name to anotherName. + +*Action*: Ensure the correct use of this binding. + +[.msg]#ECLIPSELINK-07196: [\{0}] of type [\{1}] cannot be casted to +[\{2}].# *Cause*: Exception configuring EntityManagerFactory. + +*Action*: Ensure the correct configuration of this factory class. Check +the internal exception for details on the root cause of this exception + +[.msg]#ECLIPSELINK-07197: This operation is not supported for this +class: [\{0}], [\{1}].# *Cause*: EclipseLink could not calculate +changes, because the primary key is set to null. + +*Action*: Set the primary key to a non-null value. + +[.msg]#ECLIPSELINK-07198: Class: [\{0}] was not found while converting +from class names to classes.# *Cause*: Attempt to cast an instance of +class ClassName to AnotherClassName. This is an invalid cast. + +*Action*: Provide a valid cast. + +[.msg]#ECLIPSELINK-07199: A primary table was not defined for entity +\{0} in the entity-mappings file: \{1}. A primary table is required to +process an entity relationship.# *Cause*: An attribute attributeName in +an entity class ClassName has a mappedBy value of value. This value does +not exist in its owning entity class ClassName. + +*Action*: If the owning entity class is an @EmbeddableSuperclass, this +is invalid. Make your attribute reference the correct subclass. + +[.msg]#ECLIPSELINK-07200: The attribute [\{1}] was not found on the +embeddable class [\{0}]. It is referenced in the @AttributeOverride for +the @Embedded attribute [\{3}] on class [\{2}].# *Cause*: Either name or +referencedColumnName element is not specified: if there is more than one +join column, both the name and the referencedColumnName elements must be +specified in each @JoinColumn annotation. + +*Action*: Ensure that both the name and the referencedColumnName +elements are specified in each @JoinColumn annotation. + +== Session Loader Exceptions (9000 - 9010) + +`+SessionLoaderException+` is a run-time exception that is raised if the +session manager encounters a problem loading session information from a +`+sessions.xml+` (for non-EJB applications) + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-9]##*_Session Loader Exception_* + +`+EXCEPTION [ECLIPSELINK – 9004]: org.eclipse.persistence.exceptions.SessionLoaderException+` +`+EXCEPTION DESCRIPTION: The +``+ file MyProject was not found +` +`+on the classpath, nor on the filesystem.+` + +[.msg]#ECLIPSELINK-09000: Several [\{0}] SessionLoaderExceptions were +thrown:# *Cause*: The session loader caught one or more XML parsing +exceptions while loading session information. The specific XML +exceptions follow. + +*Action*: Verify your session configuration XML file. + +[.msg]#ECLIPSELINK-09001: Unknown tag name: [\{0}] in XML node: [\{1}].# +*Cause*: An unknown tag was encountered in the specified XML node. + +*Action*: Examine the specified XML node in your session configuration +XML file. Ensure that you use only the tags defined for that node in the +appropriate EclipseLink XSD. See the directory where you installed +EclipseLink (for example, /toplink/config/xsds) + +[.msg]#ECLIPSELINK-09002: Unable to load Project class [\{0}].# *Cause*: +The specified class loader could not load a class with the name given by +the project-name property. + +*Action*: Verify the value of the project-name property and if correct, +ensure that a class with that name is in your classpath. + +[.msg]#ECLIPSELINK-09003: Unable to process XML tag [\{0}] with value +[\{1}].# *Cause*: The session loader caught an exception while either +parsing the value of the specified tag or calling the setter method +associated with the specified tag. + +*Action*: Verify the value shown for the specified tag. + +[.msg]#ECLIPSELINK-09004: The project-xml file [\{0}] was not found on +the classpath, nor on the filesystem.# *Cause*: The session loader could +not find the file identified by the project-xml tag on either the +classpath or the file system. + +*Action*: Verify the value of the project-xml tag and if correct, ensure +that a project.xml file with that name exists in your classpath or file +system. + +[.msg]#ECLIPSELINK-09005: An exception was thrown while loading the +project-xml file [\{0}].# *Cause*: The session loader caught an +exception while trying to load the file identified by the project-xml +tag either because the file could not be found, or because the file +could not be parsed. + +*Action*: Verify the configuration of the project XML file and ensure +that a project.xml file with that name specified by the project-xml tag +exists in your classpath or file system. + +[.msg]#ECLIPSELINK-09006: A \{0} was thrown while parsing the XML file. +It occurs at line \{1} and column \{2} in the XML document.# *Cause*: +The session loader caught a SAX exception while trying to parse the XML +at the given line and column of the specified XML file. EclipseLink 10g +supports only UTF-8 encoding. The EclipseLink SAXParseException occurs +if you attempt to read a non-UTF-8 formatted XML file. + +*Action*: Verify that the XML is correctly formatted at the given line +and column. Alternatively, ensure the Oracle parser is in your classpath +and that it appears before any other XML parser. + +[.msg]#ECLIPSELINK-09007: An exception was thrown while parsing the XML +file.# *Cause*: The session loader caught an exception unrelated to XML +parsing (for example, a premature end-of-file exception) while trying to +parse the specified XML file. + +*Action*: Verify the integrity of the XML file. + +[.msg]#ECLIPSELINK-09008: Unexpected value [\{0}] of tag [\{1}].# +*Cause*: The value of an XML tag does not correspond to any known +EclipseLink required values. + +*Action*: Please verify the list of values for this tag. + +[.msg]#ECLIPSELINK-09009: Tag [\{0}] has unknown attribute.# *Cause*: +There is an incorrect name value pair when processing transport +properties for the XSD tag. + +*Action*: Please verify that all properties have both the name and the +value filled in, in the session configuration XML file. + +[.msg]#ECLIPSELINK-09010: A \{0} was thrown while parsing the XML file +against the XML schema.# *Cause*: An exception was raised while parsing +the XML file against the XML schema. + +*Action*: Examine the exception and take the appropriate action. + +== Communication Exceptions (12000 - 12003) + +`+CommunicationException+` is a run-time exception that wraps all RMI, +CORBA, or input and output exceptions that occur. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-11]##*_Communication Exception_* + +`+EXCEPTION [ECLIPSELINK – 12000]: org.eclipse.persistence.exceptions.CommunicationException+` +`+EXCEPTION DESCRIPTION: Error Sending connection service to myService.+` + +[.msg]#ECLIPSELINK-12000: Error Sending connection service to \{0}.# +*Cause*: Failed to add a connection to CacheSynchronizationManager or +RemoteCommandManager. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-12001: Unable to Connect to \{0}.# *Cause*: +CacheSynronizationManager failed to connect to the specified service. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-12002: Unable to propagate changes to \{0}.# *Cause*: +CacheSynronizationManager failed to propagate changes to the specified +service. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-12003: Error in invocation: \{0}.# *Cause*: Error +invoking a remote call. + +*Action*: See the generated exception for the root cause. + +== EIS Exceptions (17007 – 17025), 90000, 91000 + +`+EISException+` is a run-time exception that is raised when invoking +EIS interactions. For more information on EIS interactions, see +link:Introduction_to_EclipseLink_Queries_(ELUG)#Enterprise_Information_System_(EIS)_Interactions[Enterprise +Information System (EIS) Interactions]. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-12]##*_JMS Processing Exception_* + +`+EXCEPTION [ECLIPSELINK – 17010]: org.eclipse.persistence.eis.EISException+` +`+EXCEPTION DESCRIPTION: Output record contains an unsupported message type.+` + +[.msg]#ECLIPSELINK-17007: \{0} property must be set.# *Cause*: The +specified property is not set. + +*Action*: Verify your interaction and ensure that the specified property +is set (see "`Configuring Custom EIS Interactions for Basic Persistence +Operations`" on page 73-6 or "`Creating an EIS Interaction for a Named +Query`" on page 116-26). + +[.msg]#ECLIPSELINK-17008: Invalid \{0} property encountered.# *Cause*: +Invalid property encountered. + +*Action*: Verify your interaction and remove the specified property (see +"`Configuring Custom EIS Interactions for Basic Persistence Operations`" +on page 73-6 or "`Creating an EIS Interaction for a Named Query`" on +page 116-26). + +[.msg]#ECLIPSELINK-17009: \{0} or \{1} property must be set.# *Cause*: +The specified properties are not set. + +*Action*: Verify your interaction and ensure that the specified +properties are set (see "`Configuring Custom EIS Interactions for Basic +Persistence Operations`" on page 73-6 or "`Creating an EIS Interaction +for a Named Query`" on page 116-26). + +[.msg]#ECLIPSELINK-17010: Output record contains an unsupported message +type# *Cause*: The output record contains an unsupported message type. + +*Action*: Verify your interaction and ensure that you specify a +supported message type. Ensure that the required connector JAR file is +on your classpath (see "`EIS Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17011: No connection factory has been specified.# +*Cause*: The connection factory is not specified. + +*Action*: Verify your interaction and ensure that you specify a +connection factory (see "`Configuring EIS Connection Specification +Options at the Project Level`" on page 70-3 or "`Configuring EIS +Connection Specification Options at the Session Level`" on page 96-2 ). + +[.msg]#ECLIPSELINK-17012: InteractionSspec must be a +CciJMSInteractionSpec.# *Cause*: InteractionSpec is not a +CciJMSInteractionSpec. + +*Action*: Verify your interaction and ensure that you specify a valid +interaction specification type (CciJMSInteractionSpec). Ensure that the +required connector JAR file is on your classpath (see "`EIS Project +Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17013: Record must be a CciJMSRecord.# *Cause*: +Record is not a CciJMSRecord. + +*Action*: Verify your interaction and ensure that you specify a valid +record type (CciJMSRecord). Ensure that the required connector JAR file +is on your classpath (see "`EIS Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17014: Unknown interaction specification type# +*Cause*: Unknown interaction specification type. + +*Action*: Verify your interaction and ensure that you specify a valid +interaction specification type. Ensure that the required connector JAR +file is on your classpath (see "`EIS Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17015: Input must contain a single text element.# +*Cause*: Invalid input: input must contain a single text element. + +*Action*: Verify your interaction and ensure that you specify valid +input-a single text element (see "`Configuring Custom EIS Interactions +for Basic Persistence Operations`" on page 73-6 or "`Creating an EIS +Interaction for a Named Query`" on page 116-26). + +[.msg]#ECLIPSELINK-17016: A timeout occurred - no message was received.# +*Cause*: A time-out occurred-no message was received. + +*Action*: Verify your interaction and the EIS on which you invoked it. + +[.msg]#ECLIPSELINK-17017: Input record contains an unsupported message +type.# *Cause*: Input record contains an unsupported message type. + +*Action*: Verify your interaction and ensure that you specify a valid +message type. Ensure that the required connector JAR file is on your +classpath (see "`EIS Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17018: Cannot invoke "`begin()`" on a non-transacted +session.# *Cause*: EclipseLink cannot invoke begin method on a +nontransacted session. + +*Action*: To be determined. + +[.msg]#ECLIPSELINK-17019: Problem testing for transacted session:# +*Cause*: Problem testing for transacted session. + +*Action*: To be determined. + +[.msg]#ECLIPSELINK-17020: InteractionSspec must be an +AQInteractionSpec.# *Cause*: InteractionSpec is not an +AQInteractionSpec. + +*Action*: Verify your interaction and ensure that you specify a valid +Oracle AQ interaction specification type (AQInteractionSpec). Ensure +that the required connector JAR file is on your classpath (see "`EIS +Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17021: Record must be an AQRecord.# *Cause*: Record +is not an AQRecord. + +*Action*: Verify your interaction and ensure that you specify a valid +Oracle AQ record type (AQRecord). Ensure that the required connector JAR +file is on your classpath (see "`EIS Project Concepts`" on page 68-1). + +[.msg]#ECLIPSELINK-17022: Input must contain a single raw element.# +*Cause*: Invalid input: input must contain a single raw element. + +*Action*: Verify your Oracle AQ interaction and ensure that you specify +valid input-a single raw element (see "`Configuring Custom EIS +Interactions for Basic Persistence Operations`" on page 73-6 or +"`Creating an EIS Interaction for a Named Query`" on page 116-26). + +[.msg]#ECLIPSELINK-17023: An exception occurred setting +MQQueueConnectionFactory attributes.# *Cause*: An exception occurred +setting MQQueueConnectionFactory attributes. + +*Action*: Verify your interaction and ensure that you specify an +appropriate IBM MQSeries connection factory (see "`Configuring EIS +Connection Specification Options at the Project Level`" on page 70-3 or +"`Configuring EIS Connection Specification Options at the Session +Level`" on page 96-2). + +[.msg]#ECLIPSELINK-17024: Could not delete file: \{0}# *Cause*: +EclipseLink cannot delete the specified file. + +*Action*: To be determined. + +[.msg]#ECLIPSELINK-17025: This mapping requires a foreign key grouping +element, as mulitple foreign keys exist.# *Cause*: No grouping element +is specified: this mapping requires a foreign key grouping element, as +mulitple foreign keys exist. + +*Action*: Verify your EIS mappings (see Chapter 74, "`Introduction to +EIS Mappings`". + +== Discovery Exceptions (22001 - 22004) + +`+DiscoveryException+` is a run-time exception that is raised when +`+DiscoveryManager+` is operating. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-15]##*_Discovery Exception_* + +`+EXCEPTION [ECLIPSELINK – 22001]: org.eclipse.persistence.exception.DiscoveryException+` +`+EXCEPTION DESCRIPTION: Could not join multicast group.+` + +[.msg]#ECLIPSELINK-22001: Could not join multicast group# *Cause*: +DiscoveryManager failed to join a multicast group due to a +java.io.IOException: either a MulticastSocket could not be created, or +the invocation of the joingGroup method of the MulticastSocket failed. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-22002: Could not send service announcement# *Cause*: +DiscoveryManager failed to inform other services that its service had +started up. + +*Action*: Consider increasing the announcement delay: the amount of time +in milliseconds that the service should wait between the time that this +remote service is available and a session announcement is sent out to +other discovery managers. This may be needed to give some systems more +time to post their connections into the naming service. See the +setAnnouncementDelay method of the DiscoveryManager. + +[.msg]#ECLIPSELINK-22003: Failed doing lookup of local host# *Cause*: +DiscoveryManager failed to do the lookup of a local host. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-22004: Failed trying to receive a service +announcement from a remote service# *Cause*: DiscoveryManager caught a +java.io.IOException while blocking for announcements from other +DiscoveryManagers. + +*Action*: See the generated exception for the root cause. + +== Remote Command Manager Exceptions (22101 - 22111) + +`+RemoteCommandManagerException+` is a run-time exception that is raised +when the remote command module is used. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-16]##*_Remote Command Manager Exception_* + +`+EXCEPTION [ECLIPSELINK – 22104]: org.eclipse.persistence.exceptions.RemoteCommandManagerException+` +`+EXCEPTION DESCRIPTION: Could not look up host name.+` + +[.msg]#ECLIPSELINK-22101: Could not obtain JNDI context with properties +\{0}# *Cause*: Failure to get a JNDI context with the specified +properties due to a javax.naming.NamingException. + +*Action*: See the generated exception for root cause. Verify that the +properties for looking up the context are correct. + +[.msg]#ECLIPSELINK-22102: Could not post connection in local naming +service under name \{0}# *Cause*: Failure to post a connection in the +local naming service with the name serviceName. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-22103: Could not look up remote connection under name +\{0} with URL \{1}# *Cause*: Failure to look up a remote connection with +the specified name and URL. + +*Action*: See the generated exception for the root cause. Verify that +the remote connection and URL are correct. + +[.msg]#ECLIPSELINK-22104: Could not look up hostname# *Cause*: The +getLocalHost method of the java.net.InetAddress failed to look up the +specified host name. + +*Action*: See the generated exception for the root cause. Verify that +the host is online and reachable. + +[.msg]#ECLIPSELINK-22105: Could not propagate command to \{0}# *Cause*: +Failure to propagate a command to the specified connection. + +*Action*: See the generated exception for the root cause. Verify that +the remote host of the specified connection is online and reachable if +the generated exception included a CommunicationException. + +[.msg]#ECLIPSELINK-22106: Could not create external JMS connection with +Topic \{0}, Topic Factory \{1}, and Context properties \{2}# *Cause*: +Failure to create JMS connection with Topic, Topic Factory, and Context +properties. + +*Action*: Verify that the JMS Topic is configured correctly with the +application server and the specified Topic. Topic Factory and Context +properties info can be used by a Java client to the JMS Topic. + +[.msg]#ECLIPSELINK-22107: Could not remove local connection in local +naming service under name \{0}# *Cause*: Failure to establish a remove +local connection in local naming service under name. + +*Action*: Restart the application server or use the application server +tool to remove name from its JNDI if this tool is available. + +[.msg]#ECLIPSELINK-22108: Could not serialize or desiralize command# +*Cause*: Failure to serialize or deserialize command. + +*Action*: If the command is a user defined command, make sure it is +serializable. If it is an EclipseLink command, file a bug report +including the stack trace. + +[.msg]#ECLIPSELINK-22109: Failed to receive JMS message from JMS +provider# *Cause*: Failure to receive JMS message from JMS provider. + +*Action*: Make sure that EclipseLink sessions are the only publishers to +the JMS Topic and that the EclipseLink sessions use the same project. + +[.msg]#ECLIPSELINK-22110: Failed to discover local host IP address.# +*Cause*: Failure to discover local host IP address. + +*Action*: Replace the $HOST string of the URL with the known host name +or IP address. + +[.msg]#ECLIPSELINK-22111: Failed to get ServerPlatform. The +ServerPlatform must be set either on Session or RemoteCommandManager.# +*Cause*: Failure to get server platform. The server platform must be set +on Session or RemoteCommandManager. + +*Action*: Set the correct ServerPlatform on the RemoteCommandManager. +This exception is raised when the user does not use an EclipseLink +Session and implements the CommandProcessor. + +== Transaction Exceptions (23001 - 23015) + +`+TransactionException+` is a run-time exception that is raised when an +error is encountered during a transaction. When this occurs, the message +contains a reference to the error code and error message. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-17]##*_Transaction Exception_* + +`+EXCEPTION [ECLIPSELINK – 23001]: org.eclipse.persistence.exceptions.TransactionException+` +`+EXCEPTION DESCRIPTION: Error looking up external Transaction resource under JNDI name.+` + +[.msg]#ECLIPSELINK-23001: Error looking up external Transaction resource +under JNDI name [\{0}]# *Cause*: Error looking up external transaction +resource under JNDI name name. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23002: Error obtaining status of current externally +managed transaction# *Cause*: Error obtaining the status of the current +externally-managed transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23003: Error obtaining current externally managed +transaction# *Cause*: Error obtaining the current externally managed +transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23004: Error obtaining the Transaction Manager# +*Cause*: Error obtaining the transaction manager. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23005: Error binding to externally managed +transaction# *Cause*: Error binding to the externally managed +transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23006: Error beginning new externally managed +transaction# *Cause*: Error beginning a new externally managed +transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23007: Error committing externally managed +transaction# *Cause*: Error committing the externally managed +transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23008: Error rolling back externally managed +transaction# *Cause*: Error rolling back the externally managed +transaction. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23009: Error marking externally managed transaction +for rollback# *Cause*: Error marking the externally managed transaction +for rollback. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23010: No externally managed transaction is currently +active for this thread# *Cause*: No externally managed transaction is +currently active for this thread. + +*Action*: Ensure that the transaction is still active. + +[.msg]#ECLIPSELINK-23011: UnitOfWork [\{0}] was rendered inactive before +associated externally managed transaction was complete.# *Cause*: A +UnitOfWork was rendered inactive before the associated externally +managed transaction was complete. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23012: No transaction is currently active# *Cause*: +Attempt to use an EntityTransaction while using JTA. This is an invalid +operation. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23013: Transaction is currently active# *Cause*: +Attempt to enlist multiple data sources in the transaction. + +*Action*: Enlist only one data source per transaction. + +[.msg]#ECLIPSELINK-23014: Cannot use an EntityTransaction while using +JTA.# *Cause*: Exception occurred in Proxy execution. + +*Action*: Examine the internal exception and take the appropriate +action. + +[.msg]#ECLIPSELINK-23015: Cannot enlist multiple datasources in the +transaction.# *Cause*: No entity transaction is currently active for +this thread. + +*Action*: Ensure that the transaction is active. + +== XML Marshal Exceptions (25001 – 25020) + +`+XMLMarshalException+` is raised when an error is encountered during +the XML marshalling process. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-19]##*_XML Marshal Exception_* + +`+EXCEPTION [ECLIPSELINK – 25001]: org.eclipse.persistence.exceptions.XMLMarshalException+` +`+EXCEPTION DESCRIPTION: Error while trying to create session.+` + +[.msg]#ECLIPSELINK-25001: Invalid XPath string: \{0}# *Cause*: Attempt +to use an invalid XPath string. + +*Action*: Ensure that the XPath is specified correctly. + +[.msg]#ECLIPSELINK-25002: An integer index could not be parsed from this +XPath string: \{0}# *Cause*: An integer index could not be parsed from +this XPath string. + +*Action*: Update any XPath strings that contain an index, and ensure +that only a single integer value is contained between the square braces. + +[.msg]#ECLIPSELINK-25003: An error occurred marshalling the object# +*Cause*: An error occurred marshalling the object. + +*Action*: Check the nested exception to determine the cause of the +problem. Typically, there is a problem with the object being written. + +[.msg]#ECLIPSELINK-25004: An error occurred unmarshalling the document# +*Cause*: An error occurred unmarshalling the document. + +*Action*: Check the nested exception to determine the cause of the +problem. Typically, there is a problem with the XML document being read. + +[.msg]#ECLIPSELINK-25005: An error occurred validating the object# +*Cause*: An error occurred validating the object. + +*Action*: The XML generated from the object is invalid according to the +schema. Ensure that any values set in the domain classes do not violate +any schema constraints when marshalled. + +[.msg]#ECLIPSELINK-25006: A default root element was not specified for +the XMLDescriptor mapped to \{0}# *Cause*: A default root element is not +specified for the XMLDescriptor mapped to target. + +*Action*: Specify the default root element for the descriptor. + +[.msg]#ECLIPSELINK-25007: A descriptor for class \{0} was not found in +the project# *Cause*: A descriptor for a class was not found in the +project. + +*Action*: Make sure that any classes referenced through CompositeObject +and/or CompositeCollection mappings have descriptors in the project. + +[.msg]#ECLIPSELINK-25008: A descriptor with default root element \{0} +was not found in the project# *Cause*: A descriptor with a default root +element was not found in the project. + +*Action*: Set a default root element on any descriptor that maps to the +root of a document. Make sure that the root element of the XML document +being read in is mapped to a descriptor in the project. + +[.msg]#ECLIPSELINK-25010: A schema reference was not specified for the +XMLDescriptor mapped to \{0}# *Cause*: A schema reference is not +specified for the XMLDescriptor mapped to target. + +*Action*: Specify the schema reference for the descriptor. + +[.msg]#ECLIPSELINK-25011: A null argument was encountered# *Cause*: A +null argument was encountered. + +*Action*: Ensure that this argument is not null. + +[.msg]#ECLIPSELINK-25012: An error occurred resolving the XML Schema.# +*Cause*: An error occurred resolving the XML Schema. + +*Action*: Check any schema references and make sure that the schema can +be accessed by the application at runtime. + +[.msg]#ECLIPSELINK-25013: An error occurred while trying to set the +schemas.# *Cause*: An error occurred while trying to set the schemas. + +*Action*: An error was encountered while attempting to set schemas on an +XML parser. Check the nested exception to determine the correct course +of action. + +[.msg]#ECLIPSELINK-25014: An error occurred while trying to instantiate +the schema platform.# *Cause*: An error occurred while trying to +instantiate the schema platform. + +*Action*: An error was encountered while instantiating the schema +platform. Check the nested exception to determine the correct course of +action. + +[.msg]#ECLIPSELINK-25015: An error occurred trying to resolve the +namespace URI for \{0}. A namespace resolver was not specified on the +descriptor.# *Cause*: An error occurred while trying to resolve the +namespace URI for a target. A namespace resolver was not specified on +the descriptor. + +*Action*: Ensure that any descriptors that make use of namespaces have a +namespace resolver specified on them. + +[.msg]#ECLIPSELINK-25016: A namespace for the prefix \{0} was not found +in the namespace resolver.# *Cause*: A namespace for the prefix was not +found in the namespace resolver. + +*Action*: Ensure that any namespace prefix which is used by a descriptor +or mapping has a corresponding entry in that descriptor’s namespace +resolver. + +[.msg]#ECLIPSELINK-25017: Either enumClass or enumClassName must be set +on the JAXBTypesafeEnumConverter.# *Cause*: Enumeration class is not +specified. + +*Action*: Set either enumClass or enumClassName on the +JAXBTypesafeEnumConverter. + +[.msg]#ECLIPSELINK-25018: The fromString method on the enum class \{0} +does not exist or could not be invoked.# *Cause*: Error during the +invocation of the fromString method on the enumeration class ClassName: +the method does not exist or could not be invoked. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-25019: The specified enum class \{0} could not be +found.# *Cause*: The specified enumeration class ClassName was not +found. + +*Action*: Ensure the correct specification of the enumeration class. + +[.msg]#ECLIPSELINK-25020: The method getResult() must not be called +before the endDocument() event has been called.# *Cause*: Attempt to +call the method getResult before the call to the endDocument event. + +*Action*: Call the getResult method after the endDocument event has been +called. + +== XML Conversion Exceptions (25501) + +`+XMLConversionException+` is a run-time exception that is raised when a +conversion between EclipseLink instances and XML fails. This exception +is used in cache coordination that uses XML change sets. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-18]##*_XML Conversion Exception_* + +`+EXCEPTION [ECLIPSELINK – 25001]: org.eclipse.persistence.exceptions.XMLConversionException+` +`+EXCEPTION DESCRIPTION: Cannot create URL for file  [\\FILE_SERVER\command.xml].+` + +[.msg]#ECLIPSELINK-25501: Cannot create URL for file [\{0}] .# *Cause*: +Failure to create a URL for the specified file. + +*Action*: Ensure that all specified XPath strings on mappings are valid +and correct. + +== XML Platform Exceptions (27001 – 27006, 27101 – 27103, 27201 – 27202) + +`+XMLPlatformException+` is raised when an error related to XML platform +is encountered. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-21]##*_EJB JAR XML Exception_* + +`+EXCEPTION [ECLIPSELINK – 27001]: org.eclipse.persistence.platform.xml.XMLPlatformException+` +`+EXCEPTION DESCRIPTION: The XML platform class ClassName was not found.+` + +[.msg]#ECLIPSELINK-27001: The XML Platform class was not found: \{0}# +*Cause*: The XML platform class ClassName was not found. + +*Action*: Ensure that this class is on the classpath. + +[.msg]#ECLIPSELINK-27002: The XML Platform could not be instantiated: +\{0}# *Cause*: Failure to instantiate the XML platform ClassName. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27003: A new XML document could not be created.# +*Cause*: The XML platform failed to create a new XML document. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27004: The XPath was invalid.# *Cause*: The XPath is +invalid. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27005: An error occurred while validating the +document.# *Cause*: Error during the document validation. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27006: Could not resolve XML Schema: \{0}# *Cause*: +Failure to resolve an XML Schema schema: XML platform parser error +occurred. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27101: An error occurred while parsing the document.# +*Cause*: Failure to parse the document. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27102: File not found: [\{0}]# *Cause*: Failure to +find the XML platform parser file. + +*Action*: Ensure that the parser file exists and is accessible (on the +classpath). + +[.msg]#ECLIPSELINK-27103: ** Parsing error, line [\{0}], uri [\{1}] +[\{2}]# *Cause*: SAX parser error at line lineNumber, URI uri. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27201: An error occurred while transforming the +document.# *Cause*: Error during the transforming of the document. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-27202: Unknown type encountered: \{0}# *Cause*: +Unknown type type encountered. + +*Action*: See the generated exception for the root cause. + +== Entity Manager Setup Exceptions (28001 – 28007) + +`+EntityManagerSetupException+` is raised when an error is encountered +during the process of setting up an entity manager. + +*_Format_* + +`+EXCEPTION [ECLIPSELINK – error code]: Exception name+` +`+EXCEPTION DESCRIPTION: Message+` + +[#Example A-22]##*_Entity Manager Setup Exception_* + +`+EXCEPTION [ECLIPSELINK – 28001]: org.eclipse.persistence.exceptions.EntityManagerSetupException+` +`+EXCEPTION DESCRIPTION: Error while trying to create session.+` + +[.msg]#ECLIPSELINK-28001: A ValidationException was thrown while trying +to create session: [\{0}] . The most likely causes of this issue are +that your [\{1}] file is not available on the classpath or it does not +contain a session called: [\{0}].# *Cause*: A ValidationException was +thrown while trying to create a session sessionName. + +*Action*: Ensure that your fileName file is on the classpath. If it is +on the classpath, ensure that this file contains the session +sessionName. + +[.msg]#ECLIPSELINK-28002: EclipseLink is attempting to load a +ServerSession named [\{0}] from [\{1}], and not getting a +ServerSession.# *Cause*: Failure to load a ServerSession sessionName +from sourceName. + +*Action*: Ensure that the server session’s type is correct. + +[.msg]#ECLIPSELINK-28003: EclipseLink has loaded Session [\{0}] from +[\{1}] and it either does not have a server platform specified or +specifies a server platform that does not use an external transaction +controller. Please specify an appropriate server platform if you plan to +use JTA.# *Cause*: Server platform specification was not found: +EclipseLink has loaded a session sessionName from sourceName, but this +session either does not have a server platform specified, or specifies a +server platform that does not use an external transaction controller. + +*Action*: If you plan to use JTA, specify an appropriate server +platform. + +[.msg]#ECLIPSELINK-28004: Error in setup of EntityManager factory: +JavaSECMPInitializer.initializeFromMain returned false.# *Cause*: Error +while setting up an +oracle.toplink.sessions.entitymanager.EntityManagerFactory. + +*Action*: Ensure the correct setup of the EntityManagerFactory: +initializeFromMain method of the EntityContainer returns true. + +[.msg]#ECLIPSELINK-28005: An Exception was thrown in setup of +EntityManager factory.# *Cause*: Error during the setup of +oracle.toplink.sessions.entitymanager.EntityManagerFactory. + +*Action*: See the generated exception for the root cause. + +[.msg]#ECLIPSELINK-28006: ClassNotFound: [\{0}] specified in [\{1}] +property.# *Cause*: Failure to find the class ClassName specified in the +property propertyName. + +*Action*: Ensure that the class exists and is on the classpath. + +[.msg]#ECLIPSELINK-28007: Failed to instantiate ServerPlatform of type +[\{0}] specified in [\{1}] property.# *Cause*: Failure to instantiate a +server platform of type ServerPlatformType specified in the property +propertyName. + +*Action*: See the generated exception for the root cause. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Accessing_Data_with_EclipseLink_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Accessing_Data_with_EclipseLink_(ELUG).adoc new file mode 100644 index 00000000000..db312da6da1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Accessing_Data_with_EclipseLink_(ELUG).adoc @@ -0,0 +1,24 @@ +== Data Access + +The following sections describe how EclipseLink defines connections to a +data source: + +* link:Introduction_to_Data_Access_(ELUG)[Introduction to Data Access] - +describes each of the different EclipseLink data source login types and +important data access concepts. + +* link:Configuring_a_Data_Source_Login_(ELUG)[Configuring a Data Source +Login] - explains how to configure EclipseLink data source login options +common to two or more data source login types. + +* link:Creating_an_Internal_Connection_Pool_(ELUG)[Creating an Internal +Connection Pool] + +* link:Configuring_an_Internal_Connection_Pool_(ELUG)[Configuring an +Internal Connection Pool] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG).adoc new file mode 100644 index 00000000000..02e47f77203 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG).adoc @@ -0,0 +1,18 @@ +== Cache + +The following sections describe how to use the EclipseLink object cache +in both distributed and nondistributed applications: + +* link:Introduction_to_Cache_(ELUG)[Introduction to Cache] - describes +each of the different EclipseLink cache types and important cache +concepts. + +* link:Configuring_a_Coordinated_Cache_(ELUG)[Configuring a Coordinated +Cache] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Contributor_Guidelines.adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Contributor_Guidelines.adoc new file mode 100644 index 00000000000..8033e1b3fbf --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Contributor_Guidelines.adoc @@ -0,0 +1,102 @@ +This page contains guidelines and information for EclipseLink users who +would like to contribute to the link:EclipseLink_UserGuide[EclipseLink +User’s Guide]. + +== General Markup and Formatting + +The _EclipseLink User’s Guide_ is created with the +link:Main_Page[Eclipse Wiki (Eclipsepedia)] which uses +http://www.mediawiki.org[Mediawiki]. See +http://meta.wikimedia.org/wiki/Help:Wikitext_examples[Wikitext Examples] +for information on using wiki markup and formatting. + +== Page Names + +* Do not use "`CamelCase`" or "`WikiWords`" when creating new pages. +This makes the page name difficult to read. The Eclipsepedia wiki is +capable of using spaces and other punctuation in wiki page names. +* Append *(ELUG)* to the end of each _EclipseLink User’s Guide_ page. +This allows users to filter searches to include _only_ pages from the +guide. + +== Categories + +Categories help users find information that pertains only to specific +EclipseLink uses. We use :Category:EclipseLink_User%27s_Guide[these +categories]: + +* Architecture +** :Category:JPA[JPA] +** :Category:ORM[ORM] +** :Category:EIS[EIS] +** :Category:XML[XML] +* Status +** :Category:Draft[Draft] +** Final +* Type +** :Category:Concept[Concept] +** :Category:Task[Task] +* Version +** 1.0 + +== Figures + +* Include an anchor point for all figures. This allows incoming links +directly to the figure. Use [#'''XXXXX''']## where *XXXXX* is a unique +identifier. +* Include a title for each figure. Use *_bold+italic_* for the title. +* When referencing (and linking to) figures, use the format: + +For more information see the Foo figure. + +== Examples + +* Include an anchor point for all examples. This allows incoming links +directly to the example. Use [#'''XXXXX''']## where *XXXXX* is a unique +identifier. +* Include a title for each figure. Use *_bold+italic_* for the title. +* When referencing (and linking to) figures, use the format: + +For more information see the Foo example. + +* To show multiple lines of code examples correctly, simply indent the +first characters (single space) of each line. For example: + +`+example line 1+` `+example line 2+` `+example line 3+` + +* To show examples inline, in example font, use: `+Example+` to produce +`+Example+`. + +== Tables + +* Include an anchor point for all tables. This allows incoming links +directly to the table. Use [#'''XXXXX''']## where *XXXXX* is a unique +identifier. +* Include a title for each table, if necessary. Use *_bold+italic_* for +the title. +* When referencing (and linking to) tables, use the format: + +For more information see the Foo table. + +== Documentation Bugs + +If you find an error in the _EclipseLink User’s Guide_, you can log in +and make the correction. If you’re unsure of the correction, or want to +request a new section, please +https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EPS%28EclipseLink%29[log +a documentation bug] using: + +* Classification: RT +* Product: EclipseLink +* Keyword: Documentation +* URL: Specific URL of the ELUG + +== API Links + +When linking to the API/Javadocs, use the following link syntax: + +`+http://www.eclipse.org/eclipselink/api/latest+` + +This will automatically link to the latest available (current) version. + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Copyright_Statement.adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Copyright_Statement.adoc new file mode 100644 index 00000000000..2be1610dec0 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Copyright_Statement.adoc @@ -0,0 +1,4 @@ +The initial contribution of the EclipseLink User’s Guide is based on +work copyrighted by Oracle and was submitted with permission. + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_EIS_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_EIS_Projects_(ELUG).adoc new file mode 100644 index 00000000000..d4ebfc19859 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_EIS_Projects_(ELUG).adoc @@ -0,0 +1,22 @@ +== EIS Projects + +The following sections describe EIS projects, descriptors and mappings: + +* link:Introduction_to_EIS_Projects_(ELUG)[Introduction to EIS Projects] + +* link:Creating_an_EIS_Project_(ELUG)[Creating an EIS Project] + +* link:Configuring_an_EIS_Project_(ELUG)[Configuring an EIS Project] + +* link:EIS_Descriptors_(ELUG)[Creating and Configuring EIS Descriptors] + +* link:EIS_Mappings_(ELUG)[Creating and Configuring EIS Mappings] + +*Special:Whatlinkshere_EclipseLink_UserGuide_Developing_EIS_Projects_(ELUG)[Related +topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_Relational_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_Relational_Projects_(ELUG).adoc new file mode 100644 index 00000000000..37020193803 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Developing_Relational_Projects_(ELUG).adoc @@ -0,0 +1,89 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*NOTOC* + +== Developing Relational Projects + +=== From an Existing Object and Data Model + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configure +the project classpath]. +. link:Using%20Workbench%20(ELUG)#How_to_Import_and_Update_Classes[Import +classes]. +. link:Using%20Workbench%20(ELUG)#Importing_Tables_from_a_Database[Import +database tables]. +. link:Creating%20a%20Mapping%20(ELUG)#How_to_Create_Mappings_Automatically_During_Development_Using_Workbench[Automatically +create mappings]. +. link:Configuring%20a%20Project%20(ELUG)[Configure project options]. ++ + +=== From an Existing Object Model + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configure +the project classpath]. +. link:Using%20Workbench%20(ELUG)#How_to_Import_and_Update_Classes[Import +classes]. +. link:Using%20Workbench%20(ELUG)#Creating_New_Tables[Generate database +tables] +. link:Configuring%20a%20Project%20(ELUG)[Configure project options]. ++ + +=== From an Existing Data Model + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +the project]. +. link:Using%20Workbench%20(ELUG)#Importing_Tables_from_a_Database[Import +database tables]. +. link:Using%20Workbench%20(ELUG)#Generating_Classes_and_Descriptors_from_Database_Tables[Generate +classes]. +. link:Configuring%20a%20Project%20(ELUG)#Configuring_a_Project[Configure +project options]. ++ + +=== EclipseLink User’s Guide + +The following sections describe relational projects: + +* link:Introduction_to_Relational_Projects_(ELUG)[Introduction to +Relational Projects] + +* link:Creating_a_Relational_Project_(ELUG)[Creating a Relational +Project] + +* link:Configuring_a_Relational_Project_(ELUG)[Configuring a Relational +Project] – explains how to configure project options specific to +relational project. + +* link:Relational_Descriptors_(ELUG)[Creating and Configuring Relational +Descriptors] + +* link:Relational_Mappings_(ELUG)[Creating and Configuring Relational +Mappings] + +* link:Object-Relational_Data_Type_Descriptors_(ELUG)[Creating and +Configuring Object-Relational Data Type Descriptors] + +* link:Object-Relational_Data_Type_Mappings_(ELUG)[Creating and +Configuring Object-Relational Data Type Mappings] + +*Special:Whatlinkshere_EclipseLink_UserGuide_Developing_Relational_Projects_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Glossary_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Glossary_(ELUG).adoc new file mode 100644 index 00000000000..3acfc91c737 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Glossary_(ELUG).adoc @@ -0,0 +1,551 @@ +*TOC* + +This glossary contains terms and abbreviations that you should be +familiar with when using EclipseLink. + +== A + +*attribute* + +A variable of a class or object. In EclipseLink, an attribute describes +all instance variables of a class. Every attribute contains a single +mapping. Attributes store primitive data such as integers, and simple +Java types such as `+String+` or `+Date+`. + +*authentication* + +The means by which a data source validates a user’s identity and +determines whether or not the user has sufficient privileges to perform +a given action. + +== B + +*bean class* + +The implementation of the bean. The bean is accessed from the client +using the home and remote interfaces. bean-managed persistence (BMP) + +A scheme for persisting entity beans that requires the developer to +manually code the methods that perform the persistence. + +Compare to link:#C[container-managed persistence (CMP)]. + +*branch class* + +Has a persistent superclass and also has subclasses. By default, queries +performed on the branch class return instances of the branch class and +any of its subclasses. However, the branch class can be configured so +that queries on it return only instances of itself without instances of +its subclasses. + +Compare to link:#L[leaf class]. + +== C + +*class* + +A category of objects. Classes allow data and method to be grouped +together. + +*class indicator field* + +A field in the table of the root class that indicates which subclass +should be instantiated + +*client session broker* + +A collection of client sessions, one from each server session associated +with the session broker. + +*connection pool* + +A collection of reusable connections to a single data source. + +*custom SQL* + +Refers to any non-EclipseLink-generated SQL used through EclipseLink. +This includes hard-coded SQL and stored procedure calls. + +== D + +*data definition language (DDL)* + +The data definition part of the structured query language (SQL). The +Workbench can generate DDL creation scripts that can be used to create +tables on the desired database. + +*database session* + +A database session provides a client application with a single data +store connection, for simple, standalone applications in which a single +connection services all data store requests for one user. + +*default mapping* + +A relational persistence framework term that refers to making the +framework automatically generate the object descriptor metadata +(including such things as mappings, login data, database platform, +locking, and foreign keys). Default mapping is available for EclipseLink +projects using EJB 2.0 CMP applications with OC4J. + +*dependent class path (IBM WebSphere)* + +Location where nonbean classes are specified. EclipseLink requires that +the bean classes be included here since they are referenced by the +project. + +*deployment descriptor* + +A set of XML files that provide the additional required information to +install an EJB within its server. Typically, this incudes security, +transaction, relationship, and persistence information. + +Compare with link:#E[EclipseLink descriptors]. + +*descriptors* + +An EclipseLink object that describes how an object’s attributes and +relationships are to be represented in relational database table(s). An +"`EclipseLink descriptor`" is not the same as a deployment descriptor, +although it plays a similar role. + +*direct access* + +By default, EclipseLink accesses public attributes directly when writing +the attributes of the object to the database or reading the attributes +of the object from the database. + +Compare to link:#M[method access]. + +*direct mapping* + +There are two basic ways of storing object attributes directly in a +table: + +* The information can be stored directly if the attribute type is +comparable to a database type. +* If there is no database primitive type that is logically comparable to +the attribute’s type, it must be transformed on its way to and from the +database + +EclipseLink provides five classes of direct mappings. + +Compare to link:#R[relationship mapping]. + +== E + +*EclipseLink session broker* + +A mechanism that enables client applications to transparently access +multiple databases through a single EclipseLink session. + +’’’Enterprise Java Beans (EJB) + +EJB are server-side domain objects that fit into a standard +component-based architecture for building enterprise applications with +Java. They are objects that become distributed, transactional, and +secure components. Workbench uses three types of EJB: session beans, +entity beans, and message-driven beans. + +*expressions* + +The EclipseLink equivalent of an SQL conditional clause. EclipseLink +expressions are specified using the `+Expression+` and +`+ExpressionBuilder+` classes. + +*entity beans* + +EJB that represent a persistent data object. EclipseLink uses two +schemes for persisting entity beans: bean-managed persistence (BMP) and +container-managed persistence (CMP). + +== F + +*fetch group* + +A performance enhancement that defines a subset of object attributes to +be loaded initially and ensures that all other attributes are loaded on +demand. + +== H + +*hub* + +A common connection point for devices in a network. + +== I + +*identity map* + +Used to cache objects for performance and to maintain object identity. + +See also link:#O[object identity]. + +*independent relationship* + +A relationship in which the source and target are public objects that +exist independently; the destruction of one object does not necessarily +imply the destruction of the other. + +Compare to link:#P[private relationship]. + +*indirection* + +The EclipseLink term for lazy loading. + +By default, when EclipseLink retrieves a persistent object, it retrieves +all of the dependent objects to which it refers. When you configure +indirection (also known as lazy loading, lazy reading, and just-in-time +reading) for an attribute mapped with a relationship mapping, +EclipseLink uses an indirection object as a place holder for the +referenced object: EclipseLink defers reading the dependent object until +you access that specific attribute. This can result in a significant +performance improvement, especially if the application is interested +only in the contents of the retrieved object, rather than the objects to +which it is related. + +EclipseLink supports a variety of types of indirection, including: value +holder indirection, transparent indirect container indirection, and +proxy indirection. + +*inheritance* + +Describes how a child class inherits the characteristics of its parent +class. EclipseLink supports multiple approaches to database +implementations that preserve the inheritance relationship. + +*in-memory query* + +A query that is run against the shared session cache. + +*instantiate* + +Create an instance of a Java class. + +== J + +*JCA* + +The Java EE Connector architecture (JCA) adapter is a way to persist +Java objects to a nonrelational data source, such as XML. + +*Java SE* + +The Java Platform, Standard Edition (Java SE) is the core Java +technology platform. It provides software compilers, tools, runtimes, +and APIs for writing, deploying, and running applets and applications in +Java. + +*Java EE* + +The Java Platform, Enterprise Edition (Java EE) is an environment for +developing and deploying enterprise applications. Java EE includes a set +of services, APIs, and protocols for developing multitiered web-based +applications. + +*Java EE Containers* + +A Java EE container is a run-time environment for Enterprise Java Beans +(EJB) that includes such basic functions as security, life cycle +management, transaction management, and deployment services. Java EE +containers are usually provided by a Java EE server, such as Oracle +Containers for J2EE. + +*Java Messaging Service (JMS)* + +The JMS API is a protocol for communication that provides asynchronous +communication between components in a distributed computing environment. + +*Java Naming and Directory Interface (JNDI)* + +The JDBC specification recommends using a JNDI naming service to acquire +a connection to a database. EclipseLink supports acquiring a database +connection in this fashion. To take advantage of this feature, construct +and configure an instance of +`+org.eclipse.persistence.sessions.JNDIConnector+` and pass it to the +project login object using the `+setConnector+` method. + +*Java Persistence API (JPA)* + +The Java Persistence API (JPA) provides a POJO persistence model for +object-relational mapping in both Java EE and Java SE applications. + +*Java Transaction API (JTA)* + +The Java Transaction API (JTA) specifies the interfaces between a +transaction manager, a resource manager, an application server, and +transactional applications involved in a distributed transaction system. + +*just-in-time reading* + +A synonym for link:#I[indirection]. + +== L + +*lazy loading* + +A synonym for link:#I[indirection.] This is the term used for +indirection in the Java Persistence API (JPA). + +*lazy reading* + +A synonym for indirection. + +*leaf class* + +Has a persistent superclass in the hierarchy but does not have +subclasses; queries performed on the leaf class can return only +instances of the leaf class. + +Compare to link:#B[branch class]. + +*locking policy* + +A mechanism that ensures one user does not overwrite another users’s +work. EclipseLink descriptors support optimistic and pessimistic locking +policies. + +== M + +*mappings* + +Describe how individual Java objects and attributes relate to a data +source. + +*message-driven beans* + +An EJB that processes asynchronous Java Messaging Service (JMS) +messages. For EclipseLink clients, a message-driven bean is simply a JMS +consumer with no conversational state and no home or remote interfaces. + +*method access* + +The application registers accessor methods for the attribute. + +Compare to link:#D[direct access]. + +== N + +*named query* + +An EclipseLink query that is created and stored, by name, in a session +for later retrieval and execution. + +== O + +*object identity* + +Ensures that each object is represented by one and only one instance in +the application; that is, multiple retrievals of the same object return +references to the same object instance, not multiple copies of the same +object. Violating object identity can corrupt the object model. + +See also link:#I[identity map]. + +*object-relational data type* + +The object-relational data type paradigm extends traditional relational +databases to include object-oriented functions. Oracle, IBM DB2, +Informix, and other DBMS databases allow users to store, access, and use +complex data in more sophisticated ways.The object-relational data type +standard is an evolving standard concerned mainly with extending the +database data structures and SQL (SQL 3). + +Object-relational data type descriptors describe Java objects that you +map to special relational database types that correspond more closely to +object types. Using these special object-relational data type database +types can simplify mapping objects to relational database tables. Not +all relational databases support these special object-relational data +type database types. + +*optimistic locking* + +Also known as write locking; allows unlimited read access to objects. A +client can write an object to the database only if the object has not +changed since it was last read. + +Compare to link:#P[pessimistic locking]. + +== P + +*packet* + +A piece of a message transmitted over a packet-switching network. One of +the key features of a packet is that it contains the destination address +in addition to the data. + +*packet time-to-live* + +A number of hops that session data packets can take before expiring. The +default is 2. + +See also link:#P[packet]. + +*persist* + +In object technology, the storage of an Java object by a data source. +pessimistic locking + +Objects are locked before they are edited, which ensures that only one +client is editing the object at any given time. + +Compare to link:#O[optimistic locking]. + +*POJO* + +Plain Old Java Object. + +In EclipseLink, POJO means just a regular Java object model class and is +used to refer to using the EclipseLink API directly rather than using +EclipseLink API indirectly by way of CMP or JPA. + +*primary key* + +A field (or combination of fields) that uniquely identifies a record in +the data source. + +*private relationship* + +A relationship in which the target object is considered to be a private +component of the source object; the target object cannot exist without +the source and is accessible only through the source object; +furthermore, if the source object is destroyed, the target object is +destroyed as well. + +Compare to link:#I[independent relationship]. + +*proxy indirection* + +A type of EclipseLink indirection. + +The Java class Proxy lets you to use dynamic proxy objects as +place-holders for a defined interface. Certain EclipseLink mappings can +be configured to use proxy indirection, which gives you the benefits of +EclipseLink indirection without the need to include EclipseLink classes +in your domain model or use weaving. + +== Q + +*query manager* + +An object, owned by a descriptor, that controls the way the descriptor +accesses the database. The query manager generates its own default SQL +to access the database in a transparent manner. + +*query optimization* + +EclipseLink supports two forms of query optimization: *joining* and +*batch reading*. Their purpose is to optimize database access through +reducing the number of database calls required to read a group of +objects. + +== R + +*relationship* + +In EclipseLink, a reference between two EclipseLink-enabled objects. + +*relationship mapping* + +Persistent objects use relationship mappings to store references to +instances of other persistent classes. The appropriate mapping class is +chosen primarily by the cardinality of the relationship. EclipseLink +provides five classes of relationship mappings. + +Compare to link:#D[direct mapping.] + +*Remote Method Invocation (RMI)* + +A set of protocols that enable Java objects to communicate remotely with +other Java objects. + +*remote session* + +A remote session is a client-side session that communicates over RMI +with a corresponding client session and server session on the server +side. Remote sessions handle object identity and marshalling and +unmarshalling between client side and server side. + +== S + +*service channel* + +A name of the EclipseLink coordinated cache channel to which sessions +subscribe in order to participate in the same coordinated cache. + +*session beans* + +EJB that represent a business operation, task, or process. EclipseLink +can use session beans to make the regular Java objects they access +persistent, or to wrap other legacy applications. + +*stale data* + +An artifact of caching, in which an object in the cache is not the most +recent version committed to the data source. + +== T + +*transparent indirect container indirection* + +A type of EclipseLink link:#I[indirection]. + +Using this type of EclipseLink indirection, you can configure +indirection for any relationship attribute of a persistent class that +holds a collection of related objects as any of the following: + +* `+java.util.Collection+` +* `+java.util.Hastable+` +* `+java.util.List+` +* `+java.util.Map+` +* `+java.util.Set+` +* `+java.util.Vector+` + +EclipseLink will use an indirection object that implements the +appropriate interface and also performs just-in-time reading of the +related objects. When using transparent indirection, you do not have to +declare the attributes as `+ValueHolderInterface+`. + +Newly created collection mappings use transparent indirection by default +if their attribute is not a `+ValueHolderInterface+`. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings and +transparent indirect container indirection for collection mappings. + +== U + +*unit of work* + +A transactional EclipseLink session that allows for a transaction to +occur at the object level not only the database level. Changes to +objects are not visible globally until the unit of work is committed. + +== V + +*value holder indirection* + +A type of EclipseLink link:#I[indirection]. + +Persistent classes that use indirection must replace relationship +attributes with value holder attributes. A value holder is an instance +of a class that implements the `+ValueHolderInterface+` interface, such +as `+ValueHolder+`. This object stores the information necessary to +retrieve the object it is replacing from the database. If the +application does not access the value holder, the replaced object is +never read from the database. To obtain the object that the value holder +replaces, use the `+getValue+` and `+setValue+` methods of the +`+ValueHolderInterface+`. A convenient way of using these methods is to +hide the `+getValue+` and `+setValue+` methods of the +`+ValueHolderInterface+` inside get and set methods. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings and +transparent indirect container indirection for collection mappings. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG).adoc new file mode 100644 index 00000000000..eb5288dbb08 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG).adoc @@ -0,0 +1,21 @@ +== Optimizing and Customizing an EclipseLink Application + +The following sections describe how to optimize and customize an +EclipseLink application: + +* link:Optimizing_the_EclipseLink_Application_(ELUG)[Optimizing the +EclipseLink Application] – contains information on the diverse set of +features EclipseLink provides to optimize performance. + +* link:Customizing_the_EclipseLink_Application_(ELUG)[Customizing the +EclipseLink Application] – describes how to customize various aspects of +EclipseLink, based on your application’s specific needs. + +*Special:Whatlinkshere_EclipseLink_UserManual_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Deployment_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Deployment_(ELUG).adoc new file mode 100644 index 00000000000..4d4e87707c8 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Deployment_(ELUG).adoc @@ -0,0 +1,29 @@ +== Overview of EclipseLink Application Deployment + +The following sections describe how to package and deploy an EclipseLink +application to an application server: + +* link:Integrating_EclipseLink_with_an_Application_Server_(ELUG)[Integrating +EclipseLink with an Application Server] – contains information on +software requirements for integrating EclipseLink with your specific +application server. + +* link:Creating_EclipseLink_Files_for_Deployment_(ELUG)[Creating +EclipseLink Files for Deployment] – describes how to create the +necessary EclipseLink files for deployment to your application server. + +* link:Packaging_a_EclipseLink_Application_(ELUG)[Packaging an +EclipseLink Application] – explains how to package the deployment files. + +* link:Deploying_a_EclipseLink_Application_(ELUG)[Deploying an +EclipseLink Application] – provides procedures for deploying different +types of EclipseLink applications in a variety of environments. + +*Special:Whatlinkshere_EclipseLink_UserManual_Overview_of_EclipseLink_Application_Deployment_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Development_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Development_(ELUG).adoc new file mode 100644 index 00000000000..ebb2658aff8 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Development_(ELUG).adoc @@ -0,0 +1,24 @@ +== EclipseLink Application Development Overview + +The following sections describe the architecture of EclipseLink and how +EclipseLink fits into your development process: + +* link:Introduction_to_EclipseLink_(ELUG)[Introduction to EclipseLink] – +general information on EclipseLink including the EclipseLink application +space, development process, components, and the EclipseLink metamodel. +* link:Introduction_to_EclipseLink_Application_Development_(ELUG)[Introduction +to EclipseLink Application Development] – overview of the key stages in +the EclipseLink development process including choosing an application +architecture and platform, object and relational mapping, building the +persistence layer, and deploying and maintaining an EclipseLink +application. + +*Special:Whatlinkshere_EclipseLink_UserManual_Overview_of_EclipseLink_Application_Development_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Development_Tools_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Development_Tools_(ELUG).adoc new file mode 100644 index 00000000000..73705e495df --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Development_Tools_(ELUG).adoc @@ -0,0 +1,25 @@ +The following sections describe the development tools and tool support +EclipseLink provides: + +* link:Introduction_to_EclipseLink_Development_Tools_(ELUG)[Introduction +to EclipseLink Development Tools] – describes the development tools and +tool support EclipseLink provides. + +* link:Using_Workbench_(ELUG)[Using Workbench] – describes how to use +Workbench including working with databases, generating data from +database tables, and creating and editing a sessions.xml file. + +* link:Using_the_Schema_Manager_(ELUG)[Using the Schema Manager] – +explains how to use the EclipseLink schema manager to create databases, +tables, stored procedures, and to populate database tables. + +* link:Using_an_Integrated_Development_Environment_(ELUG)[Using an +Integrated Development Environment] – explains how to integrate +EclipseLink with an IDE. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Mappings_and_Project_Configuration_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Mappings_and_Project_Configuration_(ELUG).adoc new file mode 100644 index 00000000000..a84374033ef --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Overview_of_EclipseLink_Mappings_and_Project_Configuration_(ELUG).adoc @@ -0,0 +1,36 @@ +== Overview of EclipseLink Mappings and Project + +The following sections provide an overview of how to use EclipseLink to +map persistent objects to a data source and how to capture that +information for use with the EclipseLink run-time component: + +* link:Introduction_to_EclipseLink_Mapping_and_Configuration_(ELUG)[Introduction +to EclipseLink Mapping and Configuration] – Introduces the metadata, +contained in the descriptor, used by EclipseLink to generate SQL +statements that create, read, modify, and delete objects. + +* link:Introduction_to_Projects_(ELUG)[Introduction to Projects] – +Describes each of the different EclipseLink project types and important +project concepts. + +* link:Introduction_to_Descriptors_(ELUG)[Introduction to Descriptors] – +Describes each of the different EclipseLink descriptor types and +important descriptor concepts. + +* link:Introduction_to_Mappings_(ELUG)[Introduction to Mappings] – +Describes each of the different EclipseLink mapping types and important +mapping concepts. + +* link:Introduction_to_Persistence_Layer_(ELUG)[Introduction to +Persistence Layer] – Provides an overview of how to use sessions, +queries, and transactions in your application. + +*Special:Whatlinkshere_EclipseLink_UserGuide_Overview_of_EclipseLink_Mappings_and_Project_Configuration_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Packaging_an_Application.adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Packaging_an_Application.adoc new file mode 100644 index 00000000000..6ca126a945c --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Packaging_an_Application.adoc @@ -0,0 +1,220 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Packaging_a_EclipseLink_Application_(ELUG)[Related +Topics] + +How you package the components of your application depends on the type +of application and how you plan to deploy it. + +This section describes EclipseLink-specific details applicable to the +common packaging strategies used for various types of applications. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using EJB 3.0, you may be using annotations instead +of some deployment files. Include deployment descriptors to override +annotations or specify options not supported by annotations. +|=== + +For more information, see the following: + +* link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server] +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] +* link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying a +EclipseLink Application] + +== Packaging Java Applications + +For non-Java EE Java applications, it is common to package the +application in a single JAR file, as this example shows. + +[#Example 9-1]## *_Packaging a non-Java EE Java Application_* + +`+ domain_module.jar+` +`+     Java classes that represent the objects mapped+` +`+     project.xml+` `+     session.xml+` `+     META-INF+` +`+         Manifest.mf+` + +This JAR contains the EclipseLink files and domain objects required by +the application, including the following: + +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml_File[sessions.xml +File]; +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File] (or the compiled `+Project+` class file if you are not using XML +files for deployment); +* The mapped classes required by the application, in a fully-resolved +directory structure. + +When you create the JAR file, the JAR building utility automatically +creates a directory structure within the JAR. Ensure that the +`+sessions.xml+` file and the `+project.xml+` file (or project class +file) appear at the root of the JAR file. Ensure that the class +directory structure starts at the root of the JAR. + +If you do not store the `+project.xml+` or `+sessions.xml+` files at the +root of the JAR file, see +link:#Packaging_with_EclipseLink_Metadata_File_Resource_Paths[Packaging +with EclipseLink Metadata File Resource Paths]. + +== Packaging JavaServer Pages and Servlet Applications + +For simple Java EE applications without EJB, it is common to package the +application in an Enterprise Archive (EAR) file made up of various Java +EE application component archives, as this example shows. + +[#Example 9-2]## *_Packaging a Java EE JSP or Servlet Application +Without EJB_* + +`+ appname.ear+` `+     META-INF+` `+         application.xml+` +`+         orion-application.xml+` `+     domain_module.jar+` +`+         Java classes that represent the object mapped+` +`+         project.xml+` `+         session.xm+` `+         META-INF+` +`+             Manifest.mf+` `+     web_module.war+` +`+         html pages, JSP’s, etc.+` `+         META-INF+` +`+             web.xml+` `+             orion-web.xml+` +`+         classes+` `+             servlet classes+` `+         lib+` +`+     client_module.jar+` `+         Client classes+` +`+         META-INF+` `+             application-client.xml+` +`+             orion-application-client.xml+` + +The component archives with EclipseLink dependencies include EclipseLink +domain JAR (see link:#How_to_Create_the_EclipseLink_Domain_JAR[How to +Create the EclipseLink Domain JAR]). + +=== How to Create the EclipseLink Domain JAR + +The domain JAR contains the EclipseLink files and domain objects +required by the application, including the following: + +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml_File[sessions.xml +File]; +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File] (or the compiled `+Project+` class file, if you are not using XML +files for deployment); +* The mapped classes required by the application, in a fully resolved +directory structure. + +When you create the JAR file, the JAR building utility automatically +creates a directory structure within the JAR. Ensure that the +`+sessions.xml+` file and the `+project.xml+` file (or `+project.class+` +file) appear at the root of the JAR file. Also ensure that the class +directory structure starts at the root of the JAR. + +If you do not store the `+project.xml+` or `+sessions.xml+` files at the +root of the JAR file, see +link:#Packaging_with_EclipseLink_Metadata_File_Resource_Paths[Packaging +with EclipseLink Metadata File Resource Paths]. + +== Packaging Session Bean Applications + +This section contains information on +link:#How_to_Package_an_EJB_3.0_Session_Bean_Application[How to Package +an EJB 3.0 Session Bean Application]. + +=== How to Package an EJB 3.0 Session Bean Application + +For information on how to package an EJB 3.0 session bean application, +see +link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Packaging +a EclipseLink JPA Application]. + +=== How to Create the EclipseLink Domain JAR + +The domain JAR contains the EclipseLink files and domain objects +required by the application, including the following: + +* `+sessions.xml+` (see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml_File[sessions.xml +File]); +* `+project.xml+` (see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File]) (or the compiled `+Project.class+` file if you are not using XML +files for deployment); +* The mapped classes required by the application, in a fully-resolved +directory structure. + +When you create the JAR file, the JAR building utility automatically +creates a directory structure within the JAR. Ensure that the +`+sessions.xml+` file and the `+project.xml+` file (or `+project.class+` +file) appear at the root of the JAR file. Also ensure that the class +directory structure starts at the root of the JAR. + +If you do not store the `+project.xml+` or `+sessions.xml+` files at the +root of the JAR file, see +link:#Packaging_with_EclipseLink_Metadata_File_Resource_Paths[Packaging +with EclipseLink Metadata File Resource Paths]. + +== Packaging JPA Applications + +See +link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Packaging +a EclipseLink JPA Application] for information on how to package your +JPA application. + +== Packaging a POJO Application for Weaving + +To package a POJO application for weaving, you create a JAR that +contains a `+sessions.xml+` file and a `+persistence.xml+` file. + +For more information on weaving, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)[To +Package a POJO Application for Weaving]. + +== Packaging with EclipseLink Metadata File Resource Paths + +If you do not store the `+project.xml+` or `+sessions.xml+` files at the +root of the JAR file, then you must provide the full resource path to +the files when accessing them. Ensure that you use "``+/+``" in +resources paths, not "``+\+``". Using "``+\+``" will not work in Java. + +For example, in the `+jar+` element, reference the `+project.xml+` and +`+sessions.xml+` files as follows: + +`+/myapp/ordersys/persist/sessions.xml+` +`+/myapp/ordersys/persist/project.xml+` + +In the `+sessions.xml+` file, reference the `+project.xml+` as follows: + +`+myapp/ordersys/persist/project.xml+` + +To acquire the session, use the following: + +[source,java] +---- + SessionManager.getManager().getSession( + new XMLSessionConfigLoader("myapp/ordersys/persist/sessions.xml"), + "OrdersysSession", + getClass().getClassLoader() + ); +---- + +For more information about acquiring sessions at run time, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[Acquiring +a Session from the Session Manager]. + +== Packaging Directories with a Dot (.) + +When packaging applications, avoid using a dot (.) in a directory in a +WAR file as this may cause deployment to fail. For example, if your WAR +includes: + +`+WEB-INF/classes/.foo/jsp_servlet/bar.jspx+` + +deployment may fail during persistence unit processing because the +application could not find a class named .foo.jsp_servlet.bar.jspx. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Queries_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Queries_(ELUG).adoc new file mode 100644 index 00000000000..93552251296 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Queries_(ELUG).adoc @@ -0,0 +1,25 @@ +== Queries + +The following sections describe how to build EclipseLink queries and use +them to create, read, update, and delete objects: + +* link:Introduction_to_EclipseLink_Queries_(ELUG)[Introduction to +EclipseLink Queries] - describes each of the different EclipseLink query +types and important query concepts. + +* link:Using_Basic_Query_API_(ELUG)[Using Basic Query API] + +* link:Introduction_to_EclipseLink_Expressions_(ELUG)[Introduction to +EclipseLink Expressions] - describes the EclipseLink expressions +framework and how to use it with EclipseLink queries. + +* link:Using_Advanced_Query_API_(ELUG)[Using Advanced Query API] + +* link:Introduction_to_EclipseLink_Support_for_Oracle_Spatial_(ELUG)[Introduction +to EclipseLink Support for Oracle Spatial] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Transactions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Transactions_(ELUG).adoc new file mode 100644 index 00000000000..29c1b41cf81 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Transactions_(ELUG).adoc @@ -0,0 +1,24 @@ +== Transactions + +The following sections describe how to use the EclipseLink unit of work +to transactionally perform create, read, update, and delete operations +with and without an external transaction processor: + +* link:Introduction_to_EclipseLink_Transactions_(ELUG)[Introduction to +EclipseLink Transactions] - describes how to use the unit of work, the +EclipseLink wrapper for a transaction, and how EclipseLink integrates +with transaction management and other important query concepts. + +* link:Using_Basic_Unit_of_Work_API_(ELUG)[Using Basic Unit of Work API] + +* link:Using_Advanced_Unit_of_Work_API_(ELUG)[Using Advanced Unit of +Work API] + +*Special:Whatlinkshere:EclipseLink_UserGuide_Transactions_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Using_EclipseLink_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Using_EclipseLink_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..ac2e313f640 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_UserGuide_Using_EclipseLink_Sessions_(ELUG).adoc @@ -0,0 +1,22 @@ +== EclipseLink Sessions + +The following sections describe the EclipseLink artifact used to +associate an EclipseLink project with a particular instance of a data +source: + +* link:Introduction_to_EclipseLink_Sessions_(ELUG)[Introduction to +EclipseLink Sessions] – describes each EclipseLink session type and +important session concepts. + +* link:Creating_a_Session_(ELUG)[Creating a Session] + +* link:Configuring_a_Session_(ELUG)[Configuring a Session] + +* link:Acquiring_and_Using_Sessions_at_Run_Time_(ELUG)[Acquiring and +Using Sessions at Run Time] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Workbench_Error_Reference_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Workbench_Error_Reference_(ELUG).adoc new file mode 100644 index 00000000000..17d102e7eb6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/EclipseLink_Workbench_Error_Reference_(ELUG).adoc @@ -0,0 +1,1769 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_EclipseLink_Workbench_Error_Reference_(ELUG)[Related +topics] + +EclipseLink checks each project, descriptor, and mapping to ensure that +you have properly defined the required settings. Errors and warnings are +displayed in the +link:Using_Workbench_(ELUG)#How_to_Use_the_Problems_Window[Problems +window] of the EclipseLink Workbench. + +You can also create a +link:Creating_a_Project_(ELUG)#How_to_Generate_the_Project_Status_Report[project +status report] that contains all errors in a specific project. + +This section also includes information on the following: + +* link:#Common_Classpath_Problems[Common Classpath Problems] +* link:#Database_Connection_Problems[Database Connection Problems] + +== Miscellaneous Errors (1 – 89, 106 – 133) + +This section lists EclipseLink Workbench error codes, information about +the likely cause of the problem, and a possible corrective action. + +13: No class indicator field should be defined for the abstract class +[class]. *Cause*: Abstract classes should not be included or contain an +*Indicator Value* on a descriptor’s *Inheritance* tab. + +*Action*: You must either remove the *Include* option for the class on +the *Inheritance* tab, or remove the *abstract modifier* option on the +descriptor’s *Class Info – Class* tab. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +54: No class indicator field is selected for this root class. *Cause*: +You selected the *Use Class Indicator Field* option for the root +descriptor in the inheritance hierarchy, but did not specify an +indicator field for the root and its children. + +*Action*: Use the *Field Selection* list on the *Inheritance* tab for +the root class. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +55: No class indicator value is defined for this included descriptor +[class] *Cause*: You selected the *Use Class Indicator Dictionary* +option for the root descriptor in the inheritance hierarchy, but did not +specify an indicator value for the root and its children. + +*Action*: Use the *Indicator Type* list on the **Inheritance**tab for +the root class. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +89: Root class does not include an indicator mapping for this +descriptor. *Cause*: The root class in the inheritance hierarchy is set +to the *Use Class Indicator Dictionary* option. The dictionary does not +contain an indicator value for this child class. + +*Action*: Select an *Indicator Type* on the **Inheritance**tab of the +root class that includes the child types. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +106: Mulitple mapping [mappings] write to the database field [db field] +. *Cause*: One database field is populated by more than one mapping + +*Action*: Ensure the "`one mapping per field`" ratio for write +operations. + +118: The selected parent descriptor for this descriptor’s inheritance +policy does not have an associated inheritance policy. *Cause*: Missing +descriptor’s inheritance policy. + +*Action*: Ensure that the descriptor you are using has a valid +associated inheritance policy (`+InheritancePolicy+`). See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_Inheritance_for_a_Parent_(Root)_Descriptor[Configuring +Inheritance for a Parent (Root) Descriptor]. + +123: This root class has no class indicator mappings for its hierarchy. +*Cause*: You created an inheritance policy with the **Use Class +Indicator Dictionary**option but did not specify the indicator values +for all subclasses. + +*Action*: Specify the indicator values for all subclasses on the +descriptor’s **Inheritance**tab. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor]. + +[width="100%",cols="<100%",] +|=== +|*Note*: EclipseLink displays a list of each subclass and indicator +value if you have identified the subclasses’ parent descriptor. +|=== + +126: Writable mappings defined for the class indicator field [field +name]. *Cause*: You selected the **Use Class Indicator Field**option for +the root descriptor in the inheritance hierarchy, but the mappings for +this field are writable. + +*Action*: Select a **Use Class Indicator Field**on the descriptor’s +**Inheritance**tab that does not contain any writable mappings. See the +following: + +* link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] +* link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor] +* link:Configuring_a_Descriptor_(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor] +* link:Configuring_a_Descriptor_(ELUG)#Configuring_Inherited_Attribute_Mapping_in_a_Subclass[Configuring +Inherited Attribute Mapping in a Subclass] + +132: The implemented interface [interface] is not an interface. *Cause*: +You selected a noninterface (a class) as an implemented interface. + +*Action*: Ensure that you select an interface. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +133: The superclass for [class] is an interface, classes cannot extend +interfaces. *Cause*: You selected an interface instead of a class as a +parent for your child class. + +*Action*: Use the **Inheritance**tab for the root class. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] and +link:Configuring_a_Descriptor_(ELUG)#Configuring_a_Descriptor[Configuring +a Descriptor]. + +== Project Errors (100 – 102) + +This section lists EclipseLink Workbench project errors. + +100: The project caches all statments by default for queries, but does +not bind all parameters. *Cause*: A named query that caches statements +must also bind parameters. + +*Action*: On the **Named Queries – Options**tab, change the **Cache +Statement**field to *False*, or change the **Bind Parameters**field to +*True*. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +101: The project uses a custom sequence table, but the counter field is +not specified. *Cause*: On the project’s **Sequencing**tab, you selected +*Use Custom Sequence Table*, but did not complete the **Counter +Field**field. + +*Action*: Select the field to use as the Counter Field for this sequence +table. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] for details. + +102: The project uses a custom sequence table, but the name field is not +specified. *Cause*: On the project’s **Sequencing**tab, you selected +*Use Custom Sequence Table*, but did not complete the **Name +Field**field. + +*Action*: Select the field to use as the **Name Field**for this sequence +table. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] for details. + +== Descriptor Errors (200 – 399) + +This section lists EclipseLink Workbench descriptor errors. + +200: The descriptor’s class is not public. *Cause*: The descriptor must +use a public access modifier. + +*Action*: On the descriptor’s **Class Info – Class**tab, change the +**Access Modifier**option to *Public*. See +link:Using_Workbench_(ELUG)#How_to_Configure_Classes[How to Configure +Classes] and +link:Using_Workbench_(ELUG)#Configuring_Class_Modifiers[Configuring +Class Modifiers]. + +201: This class is a subclass of a final class. *Cause*: If you select +the **Final**option on the descriptor’s **Class Info – Class**tab for a +class, then the class cannot contain subclasses. + +*Action*: See link:Using_Workbench_(ELUG)#How_to_Configure_Classes[How +to Configure Classes] and +link:Using_Workbench_(ELUG)#Configuring_Class_Information[Configuring +Class Information]. + +210: Two methods [method name1] [method name2] cannot have the same +signature. *Cause*: You created methods with identical signatures. + +*Action*: On the **Class Info – Methods**tab, change the information for +one of the methods. See +link:Using_Workbench_(ELUG)#How_to_Configure_Classes[How to Configure +Classes] and link:Using_Workbench_(ELUG)#Adding_Methods[Adding Methods]. + +211: The format for [date] must be in the format HH-MM-SS or HH:MM:SS. +Literal argument of expression [line number] on query [query name] is +invalid. *Cause*: You attempted to use an invalid argument on a query. + +*Action*: Use HH-MM-SS or HH:MM:SS format. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] and +link:Configuring_a_Mapping_(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +212: The format for [date] must be in the format YYYY/MM/DD HH:MM:SS or +YYYY-MM-DD HH:MM:SS. Literal argument of expression [line number] on +query [query name] is invalid. *Cause*: You attempted to use an invalid +argument on a query. + +*Action*: Use YYYY/MM/DD HH:MM:SS or YYYY-MM-DD HH:MM:SS format. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] and +link:Configuring_a_Mapping_(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +213: The format for [date] must be in the format YYYY/MM/DD or +YYYY-MM-DD. Literal argument of expression [line number] on query [query +name] is invalid. *Cause*: You attempted to use an invalid argument on a +query. + +*Action*: Use YYYY/MM/DD or YYYY-MM-DD format. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] and +link:Configuring_a_Mapping_(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +214: The format for [date] must be in the format YYYY/MM/DD HH:MM:SS, +YYYY/MM/DD, or YYYY-MM-DD. Literal argument of expression [line number] +on query [query name] is invalid. *Cause*: You attempted to use an +invalid argument on a query. + +*Action*: Use YYYY/MM/DD HH:MM:SS, YYYY/MM/DD, or YYYY-MM-DD format. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] and +link:Configuring_a_Mapping_(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +215: The format for [argument] must be an even length HEX string. +Literal argument of expression [line number] on query [query name] is +invalid. *Cause*: You attempted to use an invalid argument on a query. + +*Action*: Use HEX format. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter]. + +216: The format for [argument] must be a string. Literal argument of +expression [line number] on query [query name] is invalid. *Cause*: You +attempted to use an invalid argument on a query. + +*Action*: Use a `+String+`. See +link:Introduction_to_Mappings_(ELUG)#Type_Conversion_Converter[Type +Conversion Converter]. + +217: Literal argument of expression [line number] on query [query name] +is invalid. The format is illegal. *Cause*: You attempted to use an +invalid argument on a query. + +*Action*: Use a valid format. + +220: An aggregate shared by multiple source descriptors cannot have +one-to-many or many-to-many mappings. *Cause*: You attempted to create +multiple one-to-many and many-to-many, or one-to-one mappings in which +the target is the aggregate. Aggregate descriptors that are shared by +multiple source descriptors cannot have mappings that contain a target +object that references the descriptor. + +*Action*: For aggregate descriptors that are shared by multiple source +descriptors, remove mappings that contain a target object that +references the descriptor. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors[Descriptors] and +link:Creating_a_Relational_Descriptor_(ELUG)#Creating_Relational_Aggregate_Descriptors[Creating +Relational Aggregate Descriptors]. + +221: Classes cannot reference an aggregate target with one-to-one, +one-to-many, or many-to-many mappings. *Cause*: You tried to select an +aggregate descriptor as a reference. + +*Action*: Do not select an aggregate descriptor as the **Reference +Descriptor**for a one-to-one, one-to-many, or many-to-many mapping. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors[Descriptors] and +link:Creating_a_Relational_Descriptor_(ELUG)#Creating_Relational_Aggregate_Descriptors[Creating +Relational Aggregate Descriptors]. + +225: The implementor [implementor name] no longer implements this +interface. *Cause*: One descriptor listed as an implementation method +for this interface descriptor no longer implements this descriptor’s +interface. + +*Action*: Either remove the descriptor from the list of implementation +methods or alter the descriptor’s class so that it implements this +descriptor’s interface. See +link:Introduction_to_Descriptors_(ELUG)#Descriptors[Descriptors] and +link:Creating_a_Relational_Descriptor_(ELUG)#Creating_Relational_Interface_Descriptors[Creating +Relational Interface Descriptors]. + +230: No primary table is specified. *Cause*: The descriptor is not +associated with a database table. + +*Action*: On the descriptor’s **Descriptor Info**tab, use the +**Associated Table**field to select a primary table. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +231: No primary key(s) specified in [table name] table. *Cause*: You did +not specify a primary key for each database table. When importing tables +from a database into EclipseLink Workbench, the primary key information +will be retained only if the JDBC driver supports the `+getPrimaryKeys+` +method. + +*Action*: Ensure that a primary key is specified for each descriptor on +the **Descriptor Info**tab. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +232: The following primary key field is unmapped [field name]. *Cause*: +The primary key field does not have a writable mapping. + +*Action*: Ensure that the primary key(s) are mapped. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +233: The number of primary keys does not match the number of primary +keys on the parent. *Cause*: In an inheritance hierarchy, the child +class does not have the same number of primary keys as the parent class. + +*Action*: Ensure that the parent and child class have the same number of +primary keys on the descriptor’s **Descriptor Info**tab. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +234: The primary keys do not match parent’s primary keys. *Cause*: In an +inheritance hierarchy, the child’s primary key(s) does not match the +root’s primary key(s). + +*Action*: Ensure that each child’s **Primary Key**on the **Descriptor +Info**tab matches the parent’s primary key. Ensure that the parent and +child class have the same primary keys on the descriptor’s **Descriptor +Info**tab. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +235: The following primary field field does not have writable mappings: +[field name]. *Cause*: You attempted to have multiple mappings write to +the same database field. + +*Action*: Ensure that each database field has a single, writable +mapping. See link:Configuring_a_Relational_Descriptor_(ELUG)[Configuring +a Relational Descriptor]. + +236: No sequence field is selected. *Cause*: You selected **Use +Sequencing**on a descriptor’s **Descriptor Info**tab, but did not +specify the sequence information. + +*Action*: Specify a *Name*, *Table*, and *Field*. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]. + +237: No sequence name is selected. *Cause*: You selected Use Sequencing +on a descriptor’s Descriptor Info tab but did not specify the sequence +information. + +*Action*: Specify a Name, Table, and Field. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]. + +238: No sequence table is selected. *Cause*: You selected Use Sequencing +on a descriptor’s Descriptor Info tab but did not specify the sequence +information. + +*Action*: Specify a Name, Table, and Field. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]. + +239: The selected sequence table is not one of the descriptor’s +associated tables. *Cause*: The tabled used for sequencing is not +associated with the descriptor. + +*Action*: You must either associate the sequencing table with the +descriptor, or select a table that is already associated with the +descriptor. +Seelink:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level] and +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables]. + +240: Two queries [query name1] [query name2] cannot have the same +signature. *Cause*: Two queries for this descriptor share the same +signature (query name + parameter names). This is not allowed. + +*Action*: You must either remove one of the queries, rename one of the +queries, or change the parameters so that the signatures no longer +match. + +241: The query [query name] has Cache Statement set to true, but does +not bind parameters. *Cause*: A named query that caches statements does +not bind parameters. It must do so. + +*Action*: On the Named Queries – Options tab, either change the Cache +Statements field to False, or change the Bind Parameters field to True. +See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +242: The query [query name] does not maintain cache but does refresh the +remote identity map results. *Cause*: The query has Refresh Remote +Identity Map selected, but does not have Maintain Cache selected. + +*Action*: You must either select Maintain Cache for the descriptor, or +deselect Refresh Remote Identity Map. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +243: The query [query name] does not maintain cache but does refresh the +identity map results. *Cause*: The query has Refresh Identity Map +selected but does not have Maintain Cache selected. + +*Action*: You must either select Maintain Cache for the descriptor, or +deselect Refresh Identity Map. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +245: The query [query name] refreshes identity map results but does not +refresh remote identity map results. *Cause*: Refresh Identity Map +Results is selected for the query, but Refresh Remote Identity Map +Results is not. + +*Action*: You must either select Refresh Remote Identity Maps or +deselect Refresh Identity Maps. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]. + +246: The query key [query key] does not have an associated database +field. *Cause*: The query key is missing an associated database field. +Each query key must be associated with a database field. + +*Action*: On the Query Keys tab, use the Field option to select a +database field for the query key. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Query_Keys[Configuring +Query Keys]. + +247: The database field selected for query key [query key] does not +exist on this descriptor’s associated tables. *Cause*: The database +field selected for this query key does not exist on this descriptor’s +associated tables. Each database field associated with a query key must +exist on database table associated with the query key’s descriptor. + +*Action*: You must either change the database field associated with the +query key, or associate the descriptor with a database table that +includes the database field associated with the query key. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Query_Keys[Configuring +Query Keys]. + +248: The expression [line number] on query [query name] is invalid +because a parameter has not been specified. *Cause*: One of the +arguments in the query expression is missing or invalid. + +*Action*: Edit the query and ensure that all query keys and parameters +have been specified. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Query_Keys[Configuring +Query Keys]. + +249: The expression [line number] on query [query name] is invalid +because a query key has not been specified. *Cause*: One of the +arguments in the query expression is missing or invalid. + +*Action*: Edit the query and ensure that all query keys and parameters +have been specified. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Query_Keys[Configuring +Query Keys]. + +250: The expression [line number] on query [query name] is invalid +because the chosen query key is not a valid mapping type in an +expression. *Cause*: One of the arguments in the query expression is +invalid. + +*Action*: Edit the query and ensure that all query keys and parameters +have been specified. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Query_Keys[Configuring +Query Keys]. + +251: The expression [line number] on query [query name] is invalid. When +querying on a reference mapping, only unary operators (Is Null, Not +Null) are supported. *Cause*: You created an expression node that +includes a reference mapping with an invalid operator. + +*Action*: On the Expression Builder dialog box, select the node and +change the Operator field to IS NULL or NOT NULL. + +252: The query [query name] has no attribute chosen for the ordering +attribute at index [index]. *Cause*: The ordering attribute is missing +from the query. + +*Action*: Edit the query and add an ordering attribute. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Read_All_Query_Order[Configuring +Read All Query Order]. + +253: The ordering attribute \{0} for query \{1} is not valid. +ReadAllQuery ordering items must be either query keys or direct-to-field +mappings. *Cause*: The ordering attribute is invalid. + +*Action*: Edit the query and ensure that ordering attribue is a query +key or has a direct-to-field mapping. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Read_All_Query_Order[Configuring +Read All Query Order]. + +254: The query \{0} has no attribute chosen for the joined attribute at +index \{1}. *Cause*: The joined attribute is missing from the query. + +*Action*: Edit the query and add a joined attribute. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Optimization[Configuring +Named Query Optimization]. + +255: The joined attribute \{0} for query \{1} is not valid. Joined +attributes must be 1-1, 1-m, m-m, direct collection, or aggregate +collection mappings. *Cause*: The joined attribute is invalid. + +*Action*: Edit the query and ensure that joined attribute has a +one-to-one, one-to-many, many-to-many, direct collection, or aggregate +collection mapping. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Optimization[Configuring +Named Query Optimization]. + +256: The query \{0} has no attribute chosen for the batch read attribute +at index \{1}. *Cause*: The batch read attribute is missing from the +query. + +*Action*: Edit the query and add a batch read attribute. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Optimization[Configuring +Named Query Optimization]. + +257: The batch read attribute \{0} for query \{1} is not valid. Batch +read attributes must be 1-1, 1-m, m-m, direct collection, aggregate +collection, or direct-to-field mappings. *Cause*: The batch read +attribute is invalid. + +*Action*: Edit the query and ensure that batch attribute has a +one-to-one, one-to-many, many-to-many, direct collection, aggregate +collection, or direct-to-field mapping. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Optimization[Configuring +Named Query Optimization]. + +258: The query \{0} has no attribute chosen for the grouping attribute +at index \{1}. *Cause*: The grouping attribute is missing from the +query. + +*Action*: Edit the query and add a grouping attribute. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Group_Order_Options[Configuring +Named Query Group/Order Options]. + +259: The query \{0} has no attribute chosen for the report attribute +\{1}. *Cause*: The report query attribute is missing from the query. + +*Action*: Edit the query and add a report query attribute. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Group_Order_Options[Configuring +Named Query Group/Order Options]. + +260: The report attribute \{0} for query \{1} is not valid. Report query +attributes must be either query keys or direct mappings. *Cause*: The +report attribute is invalid. + +*Action*: Edit the query and ensure that report attribute is a query key +or has a direct-to-field mapping. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Named_Query_Group_Order_Options[Configuring +Named Query Group/Order Options]. + +262: The format for \{2} must be between 0 and 127 inclusive. Literal +argument of expression (line \{0}) on query \{1} is invalid. *Cause*: +The literal value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a Byte type must be between 1 and 127. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +263: The format for \{2} must be either '`true`' or '`false`'. Literal +argument of expression (line \{0}) on query \{1} is invalid. *Cause*: +The literal value of the expression is invalid. + +*Action*: Edit the literal value of Second Argument in Expression +Builder. The literal value of a Boolean type must be `+true+` or +`+false+`. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +264: The format for \{2} must be a single character. Literal argument of +expression (line \{0}) on query \{1} is invalid. *Cause*: The literal +value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a Character type must be a single +character. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +265: The format for \{2} must be between \{3} and \{4}. Literal argument +of expression (line \{0}) on query \{1} is invalid. *Cause*: The literal +value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value must be between 3 and 4. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +266: The format for \{2} must be a string. Literal argument of +expression (line \{0}) on query \{1} is invalid. *Cause*: The literal +value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a String type must be a string. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +267: The format for \{2} must contain only digits, '`-`', and '`.`'. +Literal argument of expression (line \{0}) on query \{1} is invalid. +*Cause*: The literal value of the expression is invalid.. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a Double or Float type must contain +digits, ’ - '`, and`' . ’. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +268: The format for \{2} must contain only digits, '`-`', and '`.`'. +Literal argument of expression (line \{0}) on query \{1} is invalid. +*Cause*: The literal value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a Double or Float type must contain +digits, ’ - '`, and`' . ’. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +269: The format for \{2} must be in the format YYYY/MM/DD or YYYY-MM-DD. +Literal argument of expression (line \{0}) on query \{1} is invalid. +*Cause*: The literal value of the expression is invalid. + +*Action*: Edit the literal value of second argument in Expression +Builder. The literal value of a Date type must be in YYYY/MM/DD or +YYYY-MM-DD format. See +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Creating_an_Expression[Creating +an Expression]. + +270: No schema context is specified. *Cause*: Each descriptor in an XML +or EIS project must be associated with an XML schema context. + +*Action*: Select the EIS or XML descriptor in the Navigator and complete +the Schema Context field on the Descriptor Info tab. + +271: The descriptor represents a document root object, but no default +root element is chosen. *Cause*: Each root descriptor must have a +default root element. + +*Action*: On the descriptor’s Descriptor Info tab, complete the Default +Root Element field. + +280: A descriptor that represents \"`anyType\`" cannot support +inheritance. *Cause*: The descriptor was supporting inheritance. + +*Action*: Edit the descriptor properties and remove the inheritance +support. + +281: A descriptor that represents \"`anyType\`" may contain only a +single Any (Object or Collection) mapping. *Cause*: The descriptor was +supporting more than one Any (Object or Collection) mapping. + +*Action*: Edit the descriptor properties and ensure that descriptor +supports only one Any (Object or Collection) mapping. + +282: A default root element type has been selected and the default root +element is not. Either select a default root element or clear the +default root element type *Cause*: The default root element was not +selected. + +*Action*: Select the default root element or clear the default root +element type. See +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_Default_Root_Element[Configuring +Default Root Element]. + +290: No primary keys specified. *Cause*: Although you have associated +the descriptor with a database table, you have not identified the +primary keys. + +*Action*: Use the Primary Keys area of the descriptor’s Descriptor Info +tab to select the primary keys for the descriptor. + +291–304: The event policy’s [method type] method is no longer a visible +member of this descriptor’s associated class. *Cause*: You changed the +class hierarchy within the project, causing the method to no longer be +visible to the class. + +*Action*: Ensure that the selected method is visible to the class. + +305: The write-lock field is stored in an object, but there is not a +writable mapping to the field. *Cause*: If the write lock field is +stored in object, there must be a non-read-only mapping to it. + +*Action*: On the mapping’s General tab, ensure that Read-Only is not +selected. + +306: Database fields specified for Selected Fields type Locking Policy +must be mapped: [field name] *Cause*: You selected an unmapped database +field for a descriptor’s locking policy. + +*Action*: On the descriptor’s Locking tab, ensure that you have selected +a mapped database field as the Selected Field. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +307: Database fields specified for Selected Fields type Locking Policy +must not be primary key fields: [field name] *Cause*: The database +fields you selected for the optimistic locking policy (by fields) +contains the primary keys for the database table. + +*Action*: In the By Fields area of the descriptor’s Locking tab, select +different fields. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +308: Version locking is chosen as the Locking Policy, but the field is +not specified. *Cause*: If you select to use version locking with an +optimistic locking policy, you must identify which database field to use +for version control. + +*Action*: Use the Database Field field on the descriptor’s Locking tab +to select a field to use for version control. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +309: The Version Locking database field selected does not exist on this +descriptor’s associated tables. *Cause*: The database field you selected +for optimistic version locking does not exist on the descriptor’s +associated table. + +*Action*: You must either select a different database field on the +descriptor’s Locking tab, or associate the descriptor with a different +database table. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +310: Database fields specified for Selected Fields type Locking Policy +do not exist on this descriptor’s associated tables: [field name] +*Cause*: The database fields you selected for the optimistic locking +policy (by fields) do not exist on the descriptor’s associated table. + +*Action*: You must either select a different database field on the +descriptor’s Locking tab, or associate the descriptor with a different +database table. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +311: The method you have specified for the instantiation policy’s method +on this descriptor is no longer a visible member of this class. *Cause*: +The method selected as the instantiation method has either been removed, +or its visibility has been reduced so that it is no longer publicly +visible. + +*Action*: Deselect this method as the instantiation method. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +312: The method you have specified for the instantiation policy’s +factory instantiation method on this descriptor is no longer a visible +member of this class. *Cause*: The method selected as the factory +instantiation method has either been removed, or its visibility reduced +so that it is no longer publicly visible. + +*Action*: Deselect this method as the factory instantiation method. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Instantiation_Policy[Configuring +Instantiation Policy]. + +313: The method you have specified for the instantiation policy’s +factory method on this descriptor is no longer a visible member of this +class. *Cause*: The method selected as the factory method has either +been removed, or its visibility reduced so that it is no longer publicly +visible. + +*Action*: Deselect this method as the factory method. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Instantiation_Policy[Configuring +Instantiation Policy]. + +314: "`Use factory`" is specified for the Instantiation policy, but all +required information is not specified. *Cause*: You selected the Use +Factory option on the descriptor’s Instantiation Policy tab, but did not +specify the Factory Class, Factory Method, or Instantiation Method +fields. + +*Action*: Complete the Factory Class, Factory Method, or Instantiation +Method fields on the descriptor’s Instantiation tab. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Instantiation_Policy[Configuring +Instantiation Policy]. + +315: "`Use method`" is selected for the Instantiation policy, but no +method is selected. *Cause*: You selected the Use Method option on the +descriptor’s Instantiation Policy tab, but did not specify the field. + +*Action*: Select the Method on the descriptor’s Instantiation tab. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Instantiation_Policy[Configuring +Instantiation Policy]. + +316: The class does not have an accessible zero argument constructor. +*Cause*: No accessible zero argument constructor exists for the class +associated with this descriptor. + +*Action*: Make the zero argument constructor accessible if it exists, or +create a accessible zero argument constructor if it doesn’t exist. + +317: No method was specified for the copying policy. *Cause*: You +specified that the descriptor should use a specific clone method for +copying, but you did not select a method. + +*Action*: Complete the Use Clone Method field on the descriptor’s +Copying tab to select a method. + +318: The method specified for the copy policy on this descriptor is no +longer a visible member of this class. *Cause*: You changed the class +hierarchy within the project, causing the copy policy to no longer be +visible to the class. + +*Action*: Ensure that the copy policy is visible to the class. + +319: Primary keys do not match across associated tables and no +reference(s) specified in multiple table policy information. *Cause*: +You attempted to associate multiple tables using a primary key. + +*Action*: Primary key field names must match across associated tables, +or references must be defined from the base table to each derived table. + +320: The multiple table reference should be defined from the base table +[table name] to the derived table. *Cause*: This descriptor has +Inheritance and Multitable advanced properties defined on it. + +*Action*: The multiple table relationship that is defined between the +base class’ table and this derived class’ table must be defined from +base to derived. + +321: The multiple table reference should not be defined on the database. +*Cause*: When using multitables with differently named primary keys, you +must set a reference from the TOP table to the BOTTOM table. This +reference must not be an actual constraint on the database. + +*Action*: Select the table in which this is defined, and deselect the On +Database option. + +322: A class containing the desired after loading method should be +specified. *Cause*: You added an after-load method to a descriptor, but +you did not specify a class. + +*Action*: Complete the After Load tab. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]. + +323: An after-load method must be specified. *Cause*: You added an +after-load method to a descriptor, but did not select an amendment +method. + +*Action*: Complete the After Load tab. See +link:Configuring_a_Descriptor_(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]. + +324: An interface class must be specified for the interface alias. +*Cause*: You added an interface alias to a descriptor, but did not +select an amendment method. + +*Action*: Complete the Interface Alias tab. + +325: The inheritance hierarchy originating in this descriptor cannot +contain both aggregate and nonaggregate child descriptors. *Cause*: +Aggregate and class descriptors cannot be in the same inheritance +hierarchy. + +*Action*: Ensure that the inheritance hierarchy contains either +aggregate or nonaggregate children, but not both. + +326: The inheritance hierarchy originating in this descriptor cannot +contain both root and composite child descriptors. *Cause*: There is a +mixture of root and composite descriptors among the descendents of this +descriptor. + +*Action*: Make all descendents of this descriptor the same type by +either making them all root, or making them all composite. You can do +this by removing the differing descriptor from the hierarchy, or +changing their type to be consistent with the other descriptors in the +hierarchy. + +330: The returning policy insert fields do not exist on this +descriptor’s associated tables: [field name] *Cause*: The field you +selected on the descriptor’s Returning tab does not exist on the +database table associated with the descriptor. + +*Action*: Select a different database table in the Insert area of the +descriptor’s Returning tab. + +331: The returning policy update field [field name] does not exist on +this descriptor’s associated tables. *Cause*: The field you selected on +the descriptor’s Returning tab does not exist on the database table +associated with the descriptor. + +*Action*: Select a different database table in the Update area of the +descriptor’s Returning tab. + +350: Descriptors with Unknown Primary Keys must use sequencing. *Cause*: +Unknown Primary Key Class is selected for this descriptor, but the +descriptor does not use sequencing. + +*Action*: Change the descriptor so that it uses sequencing, or so that +it no longer uses an unknown primary key class. + +== Mapping Errors (400 – 483) + +This section lists EclipseLink Workbench mapping errors. + +400: Method accessors have not been selected. *Cause*: You selected Use +Method Accessing for a mapping, but you did not select a method. + +*Action*: You must select a Get and Set method on the mapping’s General +tab. See +link:Configuring_a_Mapping_(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]. + +401, 402: The [get/set access method] method for this mapping’s method +accessing field is no longer visible to this descriptor. *Cause*: You +changed the class hierarchy within the project, causing the method +access type (`+get+` or `+set+`) to no longer be visible to the class. + +*Action*: Ensure that the selected method is visible to the class. + +403: Mappings for EJB 2.0 CMP descriptors that use Value Holder +Indirection must not use method accessing. *Cause*: You cannot use +method accessing on mappings for EJB 2.0 CMP descriptors that use +ValueHolder Indirection. + +*Action*: Because EJB attributes are code-generated, reference mappings +should not be set to use method access. The attributes are +code-generated to be of type ValueHolder but the abstract methods are +defined to return the local interface type of the related bean. + +404: Mapping references a write-lock field, but it is not read-only. +*Cause*: You specified a locking policy for a descriptor, but one of the +attribute mappings is not read-only. + +*Action*: Select the Read Only option on the mapping’s General tab. + +410: No direct field is specified. *Cause*: For direct collection +mappings, you must specify the direct collection information. + +*Action*: Select a Target Table and Direct Field that the direct +collection specifies. + +415: No direct key field is specified. *Cause*: For direct map mappings, +you must specify a direct key field in the reference table that stores +the primitive data value of the map key. + +*Action*: On the direct map mapping’s General tab, select a Direct Key +Field. See +link:Configuring_a_Relational_Direct_Map_Mapping_(ELUG)#Configuring_Direct_Key_Field[Configuring +Direct Key Field]. + +420: No database field is selected. *Cause*: You created a +direct-to-field or type conversion mapping without selecting a database +field. + +*Action*: For attributes with direct-to-field mappings, you must specify +a Database Field on the mapping’s General tab. For attributes with type +conversion mappings, you must specify a Database Field on the mapping’s +General tab. + +421: The selected database field does not exist on this descriptor’s +associated tables. *Cause*: The database field mapped to an attribute is +not included in the table associated with the attribute’s descriptor. + +*Action*: Ensure that the Database Field field on a mappings General tab +is included in the table that you associated with the attribute’s +descriptor. See +link:Configuring_a_Relational_Descriptor_(ELUG)#Configuring_Associated_Tables[Configuring +Associated Tables] and +link:Configuring_a_Relational_Mapping_(ELUG)#Configuring_a_Database_Field[Configuring +a Database Field]. + +430, 431: No null value type has been selected. *Cause*: You selected to +Use Default Value When Database Field is Null for a mapping, but did not +specify the value. + +*Action*: Specify a default Type or Value, or both on the mapping’s +General tab. See +link:Configuring_a_Mapping_(ELUG)#Configuring_a_Default_Null_Value_at_the_Mapping_Level[Configuring +a Default Null Value at the Mapping Level]. This message may also appear +after using the Package Rename tool when upgrading an older EclipseLink +Workbench project. + +440: XML type mappings are supported only on the Oracle9i Platform. +*Cause*: You created a Direct to XML Type mapping in relational project +that uses a non-Oracle9i database. + +*Action*: Select an Oracle9i platform as the database platform for the +data source. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level]. + +450: No reference descriptor is selected. *Cause*: You created a +mapping, but did not specify the reference descriptor + +*Action*: You must select a **Reference Descriptor**for each +relationship mapping on the mapping’s *General* tab. + +451: [descriptor name]references [descriptor name], which is not active. +*Cause*: You tried to select an inactive descriptor as a Reference +Descriptor on the mapping’s General tab. + +*Action*: You must either select a new Reference Descriptor, or make the +descriptor active. + +460: No table reference is selected. *Cause*: You created a relationship +mapping, but did not specify a reference table. + +*Action*: Select (or create) a table reference for each relationship +mapping on the mapping’s Table Reference tab. + +461: Table reference is invalid. *Cause*: The table reference selected +for this mapping is invalid. + +*Action*: Select a different table reference for this mapping. + +462: The reference [table reference] does not have any field +associations. *Cause*: You selected a table reference for a mapping, but +did not add a key pair. + +*Action*: You must specify source and target key pairs for the +reference. + +463: A key pair has not been completely specified for a reference. +*Cause*: You created a table reference without a key pair. + +*Action*: You must specify a foreign key reference for the database +table. Use the database table’s Reference tab to add a key pair. + +464: No relationship partner is specified. *Cause*: You selected the +Maintains Bidirectional Relationship option for a relationship mapping, +but did not select a mapping to use as the relationship partner. + +*Action*: Select a mapped attribute (from the reference descriptor) for +this relationship. See +link:Configuring_a_Mapping_(ELUG)#Configuring_Bidirectional_Relationship[Configuring +Bidirectional Relationship]. + +465: The relationship partner must be a one-to-one, one-to-many, or +many-to-many mapping. *Cause*: You selected an invalid attribute as the +Relationship Partner in a bidirectional relationship. + +*Action*: In the Relationship Partner field, select a one-to-one, +one-to-many, or many-to-many mapping. See +link:Configuring_a_Mapping_(ELUG)#Configuring_Bidirectional_Relationship[Configuring +Bidirectional Relationship]. + +466: The specified relationship partner mapping does not specify this +mapping as its own relationship partner. *Cause*: Maintains +Bidirectional Relationship is selected for this mapping, but the mapping +selected as the relationship partner does not have this mapping selected +as its relationship partner. + +*Action*: You must either select a different mapping for this mappings +relationship partner, which has this mapping selected as it +bidirectional relationship partner, or select this mapping as the +bidirectional relationship partner of the mapping selected as the +bidirectional relationship partner for this mapping. + +467: The chosen reference descriptor is not a valid reference descriptor +for this mapping. *Cause*: The descriptor selected as the reference +descriptor for this mapping is not a valid reference descriptor. + +*Action*: Select a valid reference descriptor for this mapping. + +470: No container class is selected. *Cause*: No container class has +been selected for this collection mapping. + +*Action*: Select a `+Container+` class for this `+Collection+` mapping. + +471: The container policy uses a Collection class, but the container +class is not a Collection. *Cause*: The selected container class for +this collection mapping is not a Collection, but Use Collection Class is +selected. + +*Action*: Select a `+Container+` class that is a `+Collection+` for this +mapping. + +472: The container policy uses a Map class, but the container class is +not a Map. *Cause*: The selected `+Container+` class for this +`+Collection+` mapping is not a `+Map+` class, but Use Map Class is +selected. + +*Action*: Select a `+Container+` class that is a `+Map+` class. + +473: The container class must be instantiable. *Cause*: The selected +`+Container+` class for this `+Collection+` mapping is not +instantiatable. + +*Action*: Select a `+Container+` class this is instantiatable, (not an +`+Interface+`, `+Abstract+` class, or `+Primitive+` class). + +474: The container class does not agree with the instance variable. +*Cause*: The selected `+Container+` class for this `+Collection+` +mapping, does not agree with the instance variable that is associated +with the mapping. Either the variable is a `+Map+` class and the +selected `+Container+` class is a `+Collection+` or vice versa. + +*Action*: You must either select a `+Container+` class that agrees with +the type of instance variable with which it is associated, or change the +instance variable to agree with the selected `+Container+` class. + +475: The container class is a Map, but the key method is not selected. +*Cause*: Use Map Class is selected for the `+Container+` policy for this +`+Collection+` mapping, but a key method has not been selected. + +*Action*: You must either select a key method for this `+Container+` +policy, or change the `+Container+` policy to not use a map class. + +4 76: The key method specified for this mapping is no longer visible to +the owning descriptor’s class. *Cause*: The selected key method for the +`+Container+` policy for this `+Collection+` mapping policy is not +visible to the descriptor’s class. + +*Action*: You must either select a different method that is visible to +the descriptor’s class, or change the selected method so that it is +visible. + +477: The key method specified for this mapping is not valid. *Cause*: +The selected key method for the `+Container+` policy for this +`+Collection+` mapping is invalid because it does not have the correct +return type, or it does not accept more than zero parameters. + +*Action*: You must either select a different method that is valid, or +change the selected method so that it will return the correct type and +accept more than zero parameters. + +478: One-to-Many and Many-to-Many mappings in EJB 2.0 CMP descriptors +may not use ValueHolder indirection. *Cause*: A one-to-many or +many-to-many mapping in an EJB 2.0 CMP descriptor is using +`+ValueHolder+` indirection. + +*Action*: You must either change the mapping to use no indirection or +non-`+ValueHolder+` indirection. + +480: No relation table is selected. *Cause*: You created a many-to-many +mapping, but did not specify a relation table. The relation table +represents the relationship between the primary keys of the source table +and target table. + +*Action*: Select or create a Relation Table on the mapping’s General +tab. + +481: The relation table is not dedicated to single, writable +many-to-many mapping. *Cause*: More than one many-to-many mapping in the +project are using the same relation table. + +*Action*: Each relation table should be used in one and only one +many-to-many mapping. + +482: No source reference is selected. *Cause*: You created a +many-to-many mapping, but did not select (or create) a source table +reference on the mapping’s Source Reference tab. + +*Action*: The source table reference must contain a Source field (from +the mapping’s relation table) and a Target field (from one of the +descriptor’s associated tables). + +483: No target reference is selected. *Cause*: You created a +many-to-many mapping, but did not select (or create) a target table +reference on the mapping’s Source Reference tab. + +*Action*: The target table reference must contain a Source field (from +the mapping’s relation table) and a Target field (from one of the +descriptor’s associated tables). + +== Table Errors (500 – 610) + +This section lists EclipseLink Workbench table errors. + +500: You cannot use joining because the source and target (reference) +descriptors are the same type. *Cause*: You selected the Use Joining +option on a one-to-one mapping in which the source and reference +descriptors are the same. + +*Action*: You must either deselect the Use Joining option or select a +difference Reference Descriptor on the One-to-One Mapping General tab. + +510: No query key associations have been defined. *Cause*: You created a +variable one-to-one mapping, but did not define a key pair. + +*Action*: Create or select a key pair on the mapping’s Query Key +Association tab. + +511: Not all query key associations have foreign key fields specified. +*Cause*: You created a query key association without a foreign key. + +*Action*: You must specify a foreign key field for each query key +association on the Query Key Association tab for variable one-to-one +mapping. + +512: The following specified query key names are no longer valid: [query +key] *Cause*: The query keys listed for this mapping no longer refer to +the reference descriptor for this mapping. The query keys are now +invalid. + +*Action*: You must either remove the invalid query keys, or change the +reference descriptor so that it corresponds with the query keys. + +513: No indicator field is selected. *Cause*: You created a variable +one-to-one mapping, but did not specify a database field in which to +store indicator values. + +*Action*: Select the Class Indicator Field on the Class Indicator Info +tab. + +514: No indicator values are specified. *Cause*: You created a variable +one-to-one mapping, but did not specify indicator values for each object +type. + +*Action*: Select the Indicator Type on the Class Indicator Info tab. + +515: [descriptor name] is not an implementor of the [descriptor name] +interface, so it cannot have an indicator value. *Cause*: You included a +descriptor on the Variable One-to-One Class Indicator Info tab that is +an implementor. + +*Action*: Deselect the descriptor on the Variable One-to-One Class +Indicator Info tab or add the descriptor to the Implementor tab. + +516: The chosen reference descriptor is not an interface descriptor. +*Cause*: This variable one-to-one mapping has a reference descriptor +selected which is not an interface descriptor. The reference descriptor +for a variable one-to-one mapping must be an interface descriptor for +the mapping to be valid. + +*Action*: You must either choose a reference descriptor that is an +interface descriptor, or change the mapping to no longer be variable. + +520: No attribute transformer is specified. *Cause*: No attribute +transformer is specified for this transformation mapping. + +*Action*: Select an attribute transformer for this transformation +mapping. + +521: The attribute transformer class is missing. *Cause*: No class has +been specified for the attribute transformer for this transformation +mapping. + +*Action*: Select a class for the attribute transformer. + +522: The attribute transformer class [class name] is not a valid +transformer class. *Cause*: The attribute transformer class that is +selected is not a valid attribute transformer class. + +*Action*: Select a valid attribute transformer class for the +transformation mapping. + +523: The attribute transformer method is missing. *Cause*: No method has +been selected for the attribute transformer for the transformation +mapping. + +*Action*: Select a method for the attribute transformer. + +524: The attribute transformer method [method name] is not visible to +the parent descriptor’s class. *Cause*: The selected attribute +transformer method is not visible to the descriptor class for this +mapping. + +*Action*: You must either select a different method that is visible, or +change the method in the class to make it visible. + +525: The attribute transformer method [method name] is not a valid +transformer method. *Cause*: The selected attribute transformer method +either has the wrong return type or accepts the wrong parameters to be a +valid transformer method for this transformation mapping. + +*Action*: You must either select a method with the correct return type +and parameters, or change the selected method so that it meets these +criteria. + +526: No field transformer associations are specified. *Cause*: No field +transformer association has been specified for this transformation +mapping. + +*Action*: Specify at least one field transformer association. + +527: No transformer is specified for the field [field name]. *Cause*: No +transformer specified for the given field. + +*Action*: Specify a transformer for this field. + +528: There is a missing field in the field transformer association. +*Cause*: There is no field specified for a field transformer association +for this transformation mapping. + +*Action*: Specify a field for all the field transformer associations for +this transformation mapping. + +529: There is a missing transformer class for the field [field name]. +*Cause*: The `+Transformer+` class is specified for this field +transformer association, but the `+Transformer+` class is unspecified. + +*Action*: Specify a `+Transformer+` class for the field transformer +association for this field. + +530: The transformer class [class name] for the field [field name] is +not a valid transformer class. *Cause*: The specified `+Transformer+` +class for the field of this field transformer association is invalid. + +*Action*: Specify a valid `+Transformer+` class for the field +transformer association for this transformation mapping. + +531: There is a missing transformer method for the field [field name]. +*Cause*: A transformer method is specified for this field transformer +association, but the transformer method is unspecified. + +*Action*: Specify a transformer method for the field transformer +association for this field. + +532: The transformer method [method name] for the field [field name] is +not visible to the parent descriptor’s class. *Cause*: The specified +transformer method for the field transformer association for this field +is not visible to the descriptor or the class of this mapping. + +*Action*: You must either choose a method that is visible to the class, +or change the method so that it is visible. + +533: The field transformer method [method name] for the field [field +name] is not a valid transformer method. *Cause*: The specified method +for the field transformer association for this field either has the +incorrect return type, or accepts the wrong parameters. + +*Action*: You must either select a method that has the correct return +type and parameters, or change the currently selected method so that is +has the correct return type and parameters. + +540: No object type is selected. *Cause*: You created an object type +mapping, but did not select the type. + +*Action*: You must select the Object Type and Database Type on the +General tab of the mapping. + +542: No object-type mappings have been specified. *Cause*: You created +an object type mapping, but did not create n object-to-database mapping. + +*Action*: You must specify at least one mapping (Database Value and +Object Value) on the General tab of the mapping. + +545: NCharacter, NString, and NClob database types are currently +supported only on the Oracle9i platform. *Cause*: You attempted to map a +database type that is not supported by your database. + +*Action*: The database type for a type conversion mapping or +direct-to-field mapping can be `+NCharacter+`, `+NString+`, or `+NCLOB+` +only if you are using an Oracle9i database. + +550: Attribute is typed as a ValueHolderInterface, but the mapping does +not use Value Holder Indirection. *Cause*: You did not specify +indirection or transparent indirection for the mapping. + +*Action*: If the class attribute is of type `+ValueHolderInterface+`, +you must use `+ValueHolder+` indirection for the mapping. + +551: Mapping uses ValueHolder Indirection, but its associated attribute +is not a ValueHolderInterface. *Cause*: You selected indirection without +a `+ValueHolderInterface+`. + +*Action*: If you select the Use Indirection (ValueHolder) option for a +one-to-many, many-to-many, or direct collection mapping, the associated +class attribute must be `+ValueHolderInterface+`. + +560: The container class for this mapping must implement +org.eclipse.persistence.indirection.IndirectContainer. *Cause*: This +mapping uses transparent indirection, but the `+Container+` class +selected for its container policy is not an `+IndirectContainer+`. + +*Action*: You must either select a `+Container+` class that is an +`+IndirectContainer+`, or remove transparent indirection from the +mapping. + +570: The chosen reference descriptor is not an aggregate descriptor. +*Cause*: This is an aggregate mapping, but the selected reference +descriptor is not an aggregate descriptor. + +*Action*: You must either select a reference descriptor for this mapping +that is an aggregate descriptor, or change this mapping to no longer be +an aggregate mapping. + +571: Aggregate fields are not specified. *Cause*: You created an +aggregate mapping without specifying specific fields. + +*Action*: Every Field Description on the Fields tab must contain a +unique Field for aggregate mappings. + +572: Aggregate mapping fields must be unique. *Cause*: You created an +aggregate mapping without specifying unique fields. + +*Action*: Every Field Description on the Fields tab must contain a +unique Field for aggregate mappings. + +573: The selected field does not exist on this descriptor’s associated +tables. *Cause*: The field selected for one of the +aggregate-path-to-fields for this aggregate mapping does not exist on +any of the descriptor’s associated tables. + +*Action*: You must either select a different field for the +path-to-field, or add the field to the appropriate table. + +580: No XML field specified. *Cause*: You mapped an attribute in an XML +or EIS descriptor, but did not select an XML field. + +*Action*: You must complete the XML Field field on the General tab of +the mapping. + +581: The specified XPath is not valid within the current schema. +*Cause*: The XPath specified for this mapping does not resolve in the +schema. + +*Action*: You must either select a different XPath, or alter the schema +so that this XPath will resolve. + +582: The specified XPath does not represent text data. *Cause*: The +XPath specified for this direct mapping does not resolve to a direct +field in the schema. + +*Action*: You must either select a different XPath, alter the schema so +that this XPath will resolve to a direct field, or change the mapping +type. + +583: The specified XPath does not represent a single xml field. *Cause*: +The XPath specified for this mapping resolves to a field which is a +collection, but this is not a collection mapping. + +*Action*: You must either select a different XPath, alter the schema so +that this XPath will resolve to a singular field, or change the mapping +type. + +590: The chosen reference descriptor is not a root eis descriptor. +*Cause*: The reference descriptor selected for this EIS reference +mapping is not a root descriptor. Reference mappings in EIS descriptors +must be root descriptors. + +*Action*: You must either select a different reference descriptor for +this mapping which is a `+root+` descriptor, or change the mapping type. + +591: No relationship partner is specified. *Cause*: This mapping has +Maintains Bidirectional Relationship selected, but no relationship +partner is specified. + +*Action*: You must either deselect Maintains Bidirectional Relationship, +or select a relationship partner. + +592: The relationship partner must be an EIS One-to-One or EIS +One-to-Many mapping. *Cause*: The relationship partner selected for this +mapping is not of the type `+EIS+` one-to-one or EIS one-to-many. + +*Action*: You must select an `+EIS+` one-to-one or EIS one-to-many +mapping as the relationship partner for this mapping, or deselect +Maintains Bidirectional Relationship. + +593: The specified relationship partner mapping does not specify this +mapping as its own relationship partner. *Cause*: The mapping selected +as the relationship partner for this mapping does not have this mapping +selected as its relationship partner. For these relationships to be +bidirectional, you must select the relationship partner for both +mappings. + +*Action*: You must either go to the mapping selected as the relationship +partner for this mapping and select this mapping as its relationship +partner, or select a different relationship partner mapping for this +mapping to maintain this mapping as its relationship partner. + +594: There is a missing source XML field. *Cause*: No field has been +specified as the source XML field for this mapping. + +*Action*: You must specify a source XML field. + +595: There is a missing target XML field. *Cause*: No field has been +specified as the target XML field for this mapping. + +*Action*: You must specify a target XML field. + +600: A foreign key grouping element is required if there are multiple +field pairs. *Cause*: No foreign key grouping element is specified for +this mapping and multiple field pairs. + +*Action*: You must specify a foreign key grouping element. + +601: The foreign key grouping element does not contain all foreign keys +fields. *Cause*: The specified foreign key grouping element does not +contain all the foreign key fields. + +*Action*: You must either remove the foreign key fields not contained in +this foreign key grouping element, or pick a foreign key grouping +element that contains all the foreign key fields. + +602: A delete all interaction is specified, but the mapping is not +private owned. *Cause*: A `+deleteall+` interaction is specified for +this mapping, but the mapping is not private owned. + +*Action*: You must either make the mapping private owned, or remove the +`+deleteall+` interaction. + +610: At least one field pair must be specified, unless the mapping has +no selection interaction and is read-only. *Cause*: No field pairs are +specified, and this mapping has a `+selection+` interaction specified +and/or is not read-only. + +*Action*: You must either specify a field pair for the mapping, or make +the mapping read-only and remove the `+selection+` interaction. + +== XML Schema Errors (700 – 706) + +This section lists EclipseLink Workbench XML schema errors. + +701: A database table can only have one IDENTITY column defined. +*Cause*: You defined more than one identity column for this table. + +*Action*: On the database table’s Columns tab, leave only one identity +(Identity) column. See +link:Using_Workbench_(ELUG)#Working_with_Column_Properties[Working with +Column Properties]. + +702: A size is required for the column [column]. *Cause*: You did not +specify any size for this column. The default size is 0. + +*Action*: On the database table’s Columns tab, specify the size (Size) +for the column (field). See +link:Using_Workbench_(ELUG)#Working_with_Column_Properties[Working with +Column Properties]. + +703: The reference [table reference] does not have any field pairs. +*Cause*: You added a reference for a table, but the reference does not +include a key pair. + +*Action*: On the database table’s References tab, specify source and +target field pairs for the table reference. See +link:Using_Workbench_(ELUG)#Creating_Table_References[Creating Table +References]. + +704: A key pair has not been completely specified for a reference. +*Cause*: A reference table is missing a complete key pair (source and +target fields). + +*Action*: You must specify a foreign key reference for the database +table. On the database table’s References tab, add a complete key pair. +link:Using_Workbench_(ELUG)#Creating_Table_References[Creating Table +References]. + +705: A development login has not been specified. *Cause*: You created a +relational EclipseLink Workbench project, but did not specify a +development login. + +*Action*: On the Database property sheet, select a Development Login +from the available defined logins, or add a new login. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins]. + +706: A deployment login has not been specified. *Cause*: You created a +relational EclipseLink Workbench project, but did not specify a +deployment login. + +*Action*: On the Database property sheet, select a Deployment Login from +the available defined logins, or add a new login. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Development_and_Deployment_Logins[Configuring +Development and Deployment Logins]. + +== Session Errors (800 – 812) + +This section lists the EclipseLink Workbench sessions XML errors. + +801: [session name] Login - The connection URL has to be specified. +*Cause*: You have not specified a connection URL for the session (when +using a database driver manager). Each session must have at least one +login connection. + +*Action*: On the session’s Login – Connection tab, complete the Driver +URL field. See +link:Configuring_a_Session_(ELUG)#Configuring_a_Session_Login[Configuring +a Session Login]. + +802: [session name] Login - The driver class has to be specified. +*Cause*: You have not specified a driver class for the session (when +using a data source database driver). + +*Action*: On the session’s Login – Connection tab, complete the Driver +Class field. See +link:Configuring_a_Session_(ELUG)#Configuring_a_Session_Login[Configuring +a Session Login]. + +803: [session or connection pool name]Login - Login - The data source +name has to be specified. *Cause*: You have not specified a driver class +for the session login (when using a Java EE data source database +driver). + +*Action*: On the session’s or connection pool’s Login – Connection tab, +complete the Data Source field. See +link:Configuring_a_Session_(ELUG)#Configuring_a_Session_Login[Configuring +a Session Login]. + +804: Login - Session Broker - It has to have at least one session, +either a server or a database session. *Cause*: You created a session +broker but did not add any sessions. Each session broker must contain a +session. + +*Action*: On the session broker’s General – Sessions tab, select a +session to add to this broker. See +link:Configuring_Session_Broker_and_Client_Sessions_(ELUG)#Configuring_Session_Broker_and_Client_Sessions[Configuring +Session Broker and Client Sessions]. + +805: [session name] Database Session - It has to have at least one XML +file or a class specified. *Cause*: Your database session does not have +a primary project (an associated deployment XML file or Java class +file). + +*Action*: On the session’s Project – General tab, complete the Primary +Project field. See +link:Configuring_a_Session_(ELUG)#Configuring_a_Primary_Mapping_Project[Configuring +a Primary Mapping Project]. + +806: Login - The transport class has to be specified. *Cause*: You +selected a custom (user-defined) cache coordination type, but did not +specify the transport class for cache coordination. + +*Action*: On the session’s Cache Coordination tab, complete the +Transport Class field, or select a different cache coordination type. +See +link:Configuring_a_Coordinated_Cache_(ELUG)#Configuring_a_Coordinated_Cache[Configuring +a Coordinated Cache]. + +807: [session name] Login - The location of the log file has to be +specified. *Cause*: You are using standard logging and selected to have +the log saved to a file, but did not select a file name and location. + +*Action*: On the session’s Logging tab, complete the Log Location field. +See link:Configuring_a_Session_(ELUG)#Configuring_Logging[Configuring +Logging]. + +811: [session or broker name] - An external transaction controller (JTA) +has to be specified. *Cause*: You selected a custom server platform, but +did not specify the JTA for the platform. + +*Action*: On the session or session broker’s General – Server Platform +tab, complete the External Transaction Controller (JTA) field. See +link:Configuring_a_Session_(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]. + +812: [session or broker name] - A server class has to be specified. +*Cause*: You selected a custom server platform, but did not specify the +server class for the platform. + +*Action*: On the session or session broker’s General – Server Platform +tab, complete the Server Class field. See +link:Configuring_a_Session_(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]. + +== Common Classpath Problems + +The following are some common EclipseLink Workbench error messages that +may result from invalid classpath information. See +link:Configuring_a_Project_(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath] for more information. + +The EclipseLink Workbench does not display the class(es) to import. +*Cause*: Your classes are not available for import on the Select Classes +dialog box. + +*Action*: Ensure that the class is in your project’s classpath (on the +project’s General properties tab). Ensure that the class is in the +`+.zip+` or `+.jar+` file. You cannot import compressed classes. + +The EclipseLink Workbench generates an exception error when importing +classes. *Cause*: EclipseLink class import utility did not start +correctly. One of the classes includes a static initialization method, +which may cause the import utility to fail. + +*Action*: Ensure that your project’s classpath points to the root +directory of your package hierarchy. For example, to import the +`+com.company.class+` package in the `+C:\classes\com\company+` +directory, your project classpath should be `+C:\classes\+`. + +The EclipseLink Workbench fails to import the class, but does not +generate an exception error. *Cause*: The classpath containing your JDBC +drivers should still be on your system CLASSPATH. EclipseLink Workbench +classpath is for domain classes only. + +*Action*: Ensure that you have properly indicated the directories that +contain your domain class(es) to map on the project’s General tab. + +== Database Connection Problems + +This section describes common errors and problems you may encounter when +communicating with or logging in to the database. + +The class [class] was not found. *Cause*: You attempted to log in to the +database, but EclipseLink could not find the JDBC driver for the +database. + +*Action*: Ensure that the `+JDBC_CLASSPATH+` in the `+setenv.cmd+` file +points to your JDBC driver JAR files. Verify that your PATH includes all +files (for example, native `+.dll+` files) required by the driver. If +the path to your JDBC driver JAR files contains spaces, then the path +must be enclosed in double-quotes in the `+setenv.cmd+` file. For +example: + +`+set JDBC_CLASSPATH="C:\Program Files\some directory\driver.jar\"+` + +For more information, see +link:Using_Workbench_(ELUG)#Configuring_the_EclipseLink_Workbench_Environment[Configuring +the EclipseLink Workbench Environment]. + +Username or password could be invalid. *Cause*: EclipseLink was unable +to log in to the database. + +*Action*: Ensure that the Username and Password for the database are +correct.Verify with your DBA that the database is set up and operating +correctly. + +You must define a development login. *Cause*: You attempted to log in to +the database from EclipseLink Workbench, but you did not define a +development login. + +*Action*: On the database property sheet, select a Development Login, or +create a new Defined Login. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]. + +No database driver has been specified. *Cause*: You attempted to log in +to the database from EclipseLink Workbench, but you did not complete the +login information. + +*Action*: Complete all the required fields on the database property +sheet for the selected development login. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]. + +Invalid URL specified. *Cause*: You attempted to log in to the database +from EclipseLink Workbench, but the URL is incorrect. + +*Action*: Complete the URL field on the database property sheet for the +selected development login. See +link:Configuring_a_Relational_Project_(ELUG)#Configuring_Login_Information_at_the_Project_Level[Configuring +Login Information at the Project Level]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] diff --git a/docs/docs.ug/src/main/asciidoc/core/Integrating_EclipseLink_with_an_Application_Server_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Integrating_EclipseLink_with_an_Application_Server_(ELUG).adoc new file mode 100644 index 00000000000..1a767e48c33 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Integrating_EclipseLink_with_an_Application_Server_(ELUG).adoc @@ -0,0 +1,922 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Integrating_EclipseLink_with_an_Application_Server_(ELUG)[Related +Topics] + +This section describes how to configure EclipseLink for use with Java EE +containers and application servers. + +For more information, see the following: + +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] +* link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging a +EclipseLink Application] +* link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying a +EclipseLink Application] + +== Introduction to the Application Server Support + +EclipseLink can be used with _any_ Java EE application server that meets +the link:#What_Are_the_Software_Requirements[software requirements] +through the EclipseLink API. + +There is EclipseLink-specific integration support for the following +servers: + +* link:#Integrating_EclipseLink_with_Oracle_WebLogic_Server[Oracle +WebLogic Server] +* link:#Integrating_EclipseLink_with_Oracle_Containers_for_J2EE_(OC4J)[Oracle +Containers for J2EE (OC4J)] +* link:#Integrating_EclipseLink_with_IBM_WebSphere_Application_Server[IBM +WebSphere Application Server] +* link:#Integrating_EclipseLink_with_Sun_Application_Server[Sun +Application Server] +* link:#Integrating_EclipseLink_with_JBoss_Application_Server[JBoss +Application Server] +* link:#Integrating_EclipseLink_with_SAP_NetWeaver_Application_Server[SAP +NetWeaver Application Server] + +== Integrating EclipseLink with an Application Server + +This section describes concepts unique to EclipseLink application server +integration, including the following: + +* link:#What_Are_the_Software_Requirements[What Are the Software +Requirements] +* link:#How_to_Configure_the_XML_Parser_Platform[How to Configure the +XML Parser Platform] +* link:#How_to_Set_Security_Permissions[How to Set Security Permissions] +* link:#How_to_Integrate_Clustering[How to Integrate Clustering] + +=== What Are the Software Requirements + +To run a EclipseLink application within a Java EE container, your system +must meet the following software requirements: + +* An application server or Java EE container +* XML parser (see link:#How_to_Configure_the_XML_Parser_Platform[How to +Configure the XML Parser Platform]); +* A JDBC driver configured to connect with your local database system +(for more information, see your database administrator); +* A Java development environment, such as the following: +** Eclipse IDE; +** Oracle JDeveloper; +** IBM WebSphere Studio Application Developer (WSAD); +** Sun Java Development Kit (JDK) 1.5 or later; +* Any other Java environment that is compatible with the Sun JDK 1.5 or +later; +* A command-line JVM executable (such as `+java.exe+` or `+jre.exe+`). + +=== How to Configure the XML Parser Platform + +The EclipseLink run-time environment uses an XML parser to do the +following: + +* Read and write XML configuration files (see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File] "`wikilink`") and +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml_File[sessions.xml +File]); +* Read and write Workbench project files (see +link:Using%20Workbench%20(ELUG)#Introduction_to_Workbench[Introduction +to Workbench]); +* Perform object-to-XML transformations in EIS projects using XML +records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)[Introduction to EIS +Mappings]); +* Perform object-to-XML transformations in XML projects (see +link:Introduction%20to%20XML%20Mappings%20(ELUG)[Introduction to XML +Mappings]); + +Application servers use an XML parser to read deployment files, such as +`+ejb-jar.xml+` and `+<+`__`+Java EE container+`__>`+-ejb-jar.xml+` +files (see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment]). + +To avoid XML parser conflicts, you must configure your EclipseLink +application to use the same XML parser as that used by the application +server on which you deploy your application. + +Internally, EclipseLink accesses its XML parser using an instance of +`+org.eclipse.persistence.platform.xml.XMLPlatform+` class. + +You can configure EclipseLink to use any XML parser for which an +`+XMLPlatform+` class exists (see +link:#Configuring_XML_Parser_Platform[Configuring XML Parser Platform]). + +You can also create your own `+XMLPlatform+` to provide access to an XML +parser not currently supported by EclipseLink (see +link:#Creating_an_XML_Parser_Platform[Creating an XML Parser Platform]). + +==== Configuring XML Parser Platform + +EclipseLink provides the `+XMLPlatform+` instances shown in the +following table. + +[#table_7_1]## *_Supported XML Platforms_* + +XMLPlatform… + +Provides Access to… + +Use with… + +org.eclipse.persistence.platform.xml.xdk.XDKPlatform + +XDKParser: this class provides access to the Oracle XML Developer’s Kit +(XDK) XML parser (see +http://www.oracle.com/technology/tech/xml/xdkhome.html). + +Integrating EclipseLink with Oracle Containers for J2EE (OC4J) + +org.eclipse.persistence.platform.xml.jaxp.JAXPPlatform1 + +JAXPParser: this class provides access to the Java SDK XML parser in the +javax.xml.parsers package (see +http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPIntro2.html). + +See the following: + +Integrating EclipseLink with Oracle WebLogic Server + +Integrating EclipseLink with IBM WebSphere Application Server + +1Default. + +[width="100%",cols="<100%",] +|=== +|*Note*: To use an XML parser not listed in this table, create your own +`+XMLPlatform+` (see link:#Creating_an_XML_Parser_Platform[Creating an +XML Parser Platform]). +|=== + +To configure your EclipseLink application to use a particular instance +of the `+XMLPlatform+` class, set system property +`+eclipse.persistence.xml.platform+` to the fully qualified name of your +`+XMLPlatform+` class, as the following example shows. + +[#Example 7-1]## *_Configuring XML Platform_* + +`+eclipse.persistence.xml.platform=org.eclipse.persistence.platform.xml.jaxp.JAXPPlatform+` + +==== Creating an XML Parser Platform + +Using the `+org.eclipse.persistence.internal.xml+` classes you can +create your own instance of the +`+org.eclipse.persistence.platform.xml.XMLPlatform+` class to specify an +XML parser not listed in the link:#table_7_1[Supported XML Platforms] +table. + +After creating your `+XMLPlatform+`, configure EclipseLink to use it +(see link:#Configuring_XML_Parser_Platform[Configuring XML Parser +Platform]). + +==== XML Parser Limitations + +Crimson +(http://xml.apache.org/crimson/[`+http://xml.apache.org/crimson/+`]) is +the XML parser supplied in the Java Platform, Standard Edition (Java SE) +and in some JAXP reference implementations. + +If you use Crimson with the JAXP API to parse XML files whose system +identifier is not a fully qualified URL, then XML parsing will fail with +a _not valid URL_ exception. + +Other XML parsers defer validation of the system identifier URL until it +is specifically referenced. + +If you are experiencing this problem, consider one of the following +alternatives: + +* Ensure that your XML files use a fully qualified system identifier +URL. +* Use another XML parser (such as the OracleAS XML Parser for Java v2). + +=== How to Set Security Permissions + +By default, when you run a EclipseLink-enabled application in a JVM +configured with a nondefault `+java.lang.SecurityManager+`, the +EclipseLink run-time environment executes certain internal functions by +executing a `+PrivilegedAction+` with `+java.security.AccessController+` +method `+doPrivileged+`. This ensures that you do not need to grant many +permissions to EclipseLink for it to perform its most common operations. +You need only grant certain permissions depending on the types of +optional EclipseLink features you use. + +For more information, see link:#Defining_Security_Permissions[Defining +Security Permissions]. + +If you run a EclipseLink-enabled application in a JVM without a +nondefault `+SecurityManager+`, you do not need to set any permissions. + +=== How to Integrate Clustering + +Most application servers include a clustering service that you can use +with your EclipseLink application. + +To use EclipseLink with an application server cluster, use this general +procedure: + +[arabic] +. Install the `+eclipselink.jar+` file (and include it in the classpath) +on each application server in the cluster to which you deploy +EclipseLink applications. +. Configure EclipseLink cache consistency options appropriate for your +application. For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. +. Configure clustering on each application server. For more information, +see your application server documentation. + +== Integrating EclipseLink with Oracle WebLogic Server + +To integrate an EclipseLink application with Oracle WebLogic Server, you +must consider the following: + +* link:#How_to_Configure_the_WebLogic_Classpath[How to Configure the +WebLogic Classpath] +* link:#How_to_Integrate_with_the_WebLogic_JTA[How to Integrate with the +WebLogic JTA] + +* link:#How_to_Integrate_the_Security_Manager[How to Integrate the +Security Manager] + +In addition to configuring these Oracle WebLogic Server-specific +options, you must also consider the general application server +integration issues in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Configure the WebLogic Classpath + +EclipseLink works out of the box in Oracle WebLogic Server 10.3. The +EclipseLink library resides in the following location on the server: + +`+$BEA_HOME/modules/org.eclipse.persistence_*.jar+` + +Ensure that your EclipseLink application defines an XML parser platform +(see link:#How_to_Configure_the_XML_Parser_Platform[How to Configure the +XML Parser Platform]). + +=== How to Integrate with the WebLogic JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== How to Integrate JMX + +By default, when you deploy an EclipseLink application to Oracle +WebLogic Server, the EclipseLink runtime deploys the following Java +Management Extensions (JMX) MBeans to the Oracle WebLogic Server JMX +service for each EclipseLink session: + +* `+org.eclipse.persistence.services.DevelopmentServices+` - This class +is meant to provide facilities for managing an EclipseLink session +internal to EclipseLink over JMX. +* `+org.eclipse.persistence.services.RuntimeServices+` - This class is +meant to provide facilities for managing an EclipseLink session external +to EclipseLink over JMX. + +Use the API that this JMX MBean exposes to access and configure your +EclipseLink sessions at run time using JMX code that you write, or to +integrate your EclipseLink application with a third-party JMX management +application, such as JConsole. + +==== Setting Up the Environment for EclipseLink JMX MBeans + +Perform the following steps: + +[arabic] +. *Set breakpoints:* the `+eclipselink.jar+` deployed in the +`+$WEBLOGIC_HOME/modules/org.eclipse.persistence_n.n.n.jar+` needs a +source attachment. You set a breakpoint on the `+undeploy+` method of +the `+org.eclipse.persistence.internal.jpa.EntityManagerSetupImpl+` +pointing to the source JAR file or your workspace projects, and then +redeploy. This will result in any breakpoints set in the `+predeploy+` +method or prior to the first login to be hit. +. *Enable remote access on the Oracle WebLogic Server JVM* by adding the +following JVM option to your WebLogic startup script: +`+C:\opt\wls103\user_projects\domains\base_domain\bin\startWebLogic.cmd+` +`+set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.sun.management.jmxremote+` +. *Enable MBean registration (deployment)* by adding one or both of the +two MBean system properties, as follows: +`+rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=true+` +`+rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=true+` +By default, EclipseLink does not register MBeans for Oracle WebLogic +Server. If you enable the registration, it will occur as a post step +during the first login to the session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Login[Configuring +a Session Login]). If both `+eclipselink.register.dev.mbean+` and +`+eclipselink.register.run.mbean+` properties are missing, MBean +registration will not proceed for that bean. +. *Configure Oracle WebLogic Server domain security*. For more +information, see +_http://wiki.eclipse.org/EclipseLink/Examples/JPA/WebLogic_Web_Tutorial[EclipseLink +JMX MBean Support in Oracle WebLogic Server tutorial]_. + +==== Accessing EclipseLink JMX MBeans Using a Third-Party JMX Management Application + +After you deploy your EclipseLink application, you can use any +JMX-compliant management application to access and use the full public +API that EclipseLink MBeans provide. + +*To access EclipseLink JMX MBeans using a third-party JMX management +application:* + +[arabic] +. Package and deploy your EclipseLink application to Oracle WebLogic +Server. For more information, see +link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying an +EclipseLink Application]. +. Optionally, examine Oracle WebLogic Server logs and look for the +appropriate log messages. Note that for a JPA application, EclipseLink +session instantiation and login occurs at `+EntityManager+` +instantiation time. +. Launch your third-party JMX management application. For example, +launch JConsole (`+JDK_HOME\bin\jconsole.exe+`) using the command +prompt, and then select the running `+weblogic.Server+` local process, +as the following figure shows. ++ +.Image:Jconsole_attach_to_weblogic_server_jvm.jpg +image::Jconsole_attach_to_weblogic_server_jvm.jpg[Image:Jconsole_attach_to_weblogic_server_jvm.jpg,title="Image:Jconsole_attach_to_weblogic_server_jvm.jpg"] + +[arabic] +. Optionally, launch JRockit Mission Control *JMC.exe*, attach to the +JVM process and navigate to the MBeans tab - you will see the following +screen showing the EclipsLink MBeans for your session. + +.Image:Jrockit_jconsole_mbeans_via_non_jndi_generic_spec_lookup.JPG +image::Jrockit_jconsole_mbeans_via_non_jndi_generic_spec_lookup.JPG[Image:Jrockit_jconsole_mbeans_via_non_jndi_generic_spec_lookup.JPG,title="Image:Jrockit_jconsole_mbeans_via_non_jndi_generic_spec_lookup.JPG"] + +==== Disabling EclipseLink JMX Support + +There are a number of ways to disable EclipseLink JMX support. + +*To disable deployment of MBeans to Oracle WebLogic Server for your +EclipseLink application using system properties*, remove, disable, or do +not add in the first place `+eclipselink.register.dev.mbean+` and +`+eclipselink.register.run.mbean+` MBean system properties. The +following example shows how to disable these properties: +`+rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=false+` +`+rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=false+`. + +*To disable deployment of MBeans to Oracle WebLogic Server for your +EclipseLink application using deployment XML*, use an EclipseLink +`+sessions.xml+` file (assuming your application has one): + +[arabic] +. Undeploy your EclipseLink application on Oracle WebLogic Server. +. Edit your EclipseLink application’s Oracle WebLogic Server platform to +disable run-time services. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]. +. Package your EclipseLink application and redeploy on Oracle WebLogic +Server. For more information, see +link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying an +EclipseLink Application]. +. Confirm that EclipseLink JMX MBean instances for your application no +longer exist. + +If your application does not include an EclipseLink `+sessions.xml+` +file, you can use a `+preLogin+` event handler to disable this feature +(see the following section). + +*To disable deployment of MBeans to Oracle WebLogic Server for your +EclipseLink application using the EclipseLink session preLogin event +handler*: + +[arabic] +. Undeploy your EclipseLink application on Oracle WebLogic Server. +. Create an EclipseLink session customizer. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Customizer_Class[Configuring +a Session Customizer Class]. +. In your session customizer, create a session event listener for the +`+preLogin+` session event and register the listener with the session +event manager, as the following example shows. ++ +`+import oracle.eclipselink.tools.sessionconfiguration.SessionCustomizer;+` +`+import oracle.eclipselink.sessions.Session;+` +`+import oracle.eclipselink.sessions.SessionEvent;+` +`+import oracle.eclipselink.sessions.SessionEventAdapter;+` +`+import oracle.eclipselink.platform.server.ServerPlatform;+` +`+public class EmployeeSessionCustomizer implements SessionCustomizer {+` +`+  +` `+  public void customize(Sesssion session) {+` +`+      SessionEventAdapter myEventListener = new SessionEventAdapter() {+` +`+          +`*`+//\'\' \'\'Listen\'\' \'\'for\'\' \'\'preLogin\'\' \'\'event+`* +`+          public void preLogin(SessionEvent event) {+` +`+              +`*`+//\'\' \'\'Disable\'\' \'\'runtime\'\' \'\'services+`* +`+              Session session event.getSession();+` +`+              ServerPlatform serverPlatform = session.getServerPlatform();+` +`+              serverPlatform.disableRuntimeServices();+` +`+          }+` `+      };+` +`+      +`*`+//\'\' \'\'Register\'\' \'\'session\'\' \'\'event\'\' \'\'listener+`* +`+      session.getEventManager().addListener(myEventListener);+` +`+  }+` `+}+` ++ +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. +. Package your EclipseLink application, including your session +customizer, and redeploy on Oracle WebLogic Server. For more +information, see +link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging an +EclipseLink Application] and +link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying an +EclipseLink Application]. +. Confirm that EclipseLink JMX MBean instances for your application are +not deployed. + +[width="100%",cols="<100%",] +|=== +|*Note*: Follow the preceding procedure if you EclipseLink application +does not include an Oracle WebLogic Server `+sessions.xml+` file (such +as a EclipseLink JPA application). +|=== + +==== What You May Need to Know About EclipseLink JMX Support + +For more information on EclipseLink and Oracle WebLogic Server JMX +support, see the following: + +* Oracle WebLogic Server: Developing Manageable Applications with JMX +* Oracle WebLogic Server: Developing Custom Management Utilities with +JMX + +For more information on JMX in general, see +http://java.sun.com/docs/books/tutorial/jmx/index.html + +=== How to Integrate the Security Manager + +If you use a security manager, specify a security policy file in the +`+weblogic.policy+` file (normally located in the WebLogic install +directory), as follows: + +`+-Djava.security.manager+` +`+-Djava.security.policy==c:\weblogic\weblogic.policy+` + +The WebLogic installation procedure includes a sample security policy +file. You need to edit the `+weblogic.policy+` file to grant permission +for EclipseLink to use reflection. + +The following example illustrates only the permissions that EclipseLink +requires, but most `+weblogic.policy+` files contain more permissions +than are shown in this example. + +[#Example 7-5]## *_A Subset of a "`Grant`" Section from a +WebLogic.policy File_* + +[source,java] +---- + grant { + '''// "enableSubstitution" required to run the WebLogic console''' + permission java.io.SerializablePermission "enableSubstitution"; + '''// "modifyThreadGroup" required to run the WebLogic Server''' + permission java.lang.RuntimePermission "modifyThreadGroup"; + '''// grant permission for EclipseLink to use reflection''' + + permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; + }; +---- + +== Integrating EclipseLink with Oracle Containers for J2EE (OC4J) + +To integrate a EclipseLink application with OC4J, you must consider +link:#How_to_Integrate_with_the_OC4J_JTA[integration with the OC4J JTA]. + +In addition to configuring these OC4J-specific options, you must also +consider the general application server integration issues described in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Integrate with the OC4J JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== How to Configure the OC4J Application Server Classpath + +To configure EclipseLink support for OC4J, add the `+eclipselink.jar+` +file to the application server classpath in the global `+applib+` +directory. Place the `+eclipselink.jar+` as noted by the element element +in the `+$OC4J_HOME/config/server.xml+` file in the +`+$OC4J_HOME/applib+` directory, as follows: + +`+/oc4j/j2ee/home/applib/eclipselink.jar+` + +== Integrating EclipseLink with IBM WebSphere Application Server + +To integrate a EclipseLink application with IBM WebSphere Application +Server, you must consider the following: + +* link:#How_to_Configure_the_WebSphere_Classpath[How to Configure the +WebSphere Classpath] +* link:#How_to_Configure_Class_Loader_Order[How to Configure Class +Loader Order] +* link:#How_to_Integrate_with_the_WebSphere_JTA[How to Integrate with +the WebSphere JTA] + +In addition to configuring these IBM WebSphere application +server-specific options, you must also consider the general application +server integration issues in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Configure the WebSphere Classpath + +You configure the IBM WebSphere application server classpath differently +depending on what version of this server you are using: + +==== Configuring Classpath for IBM WebSphere Application Server 6.1 and Later + +EclipseLink provides JTA and general integration support for IBM +WebSphere application server 6.1 and later. To configure the classpath +for this version, do the following: + +[arabic] +. Create a shared library that contains the +__`+\jlib\eclipselink.jar''+` file and associate the shared library with +the application. +. Ensure that your EclipseLink application defines an XML parser +platform (see link:#How_to_Configure_the_XML_Parser_Platform[How to +Configure the XML Parser Platform]). + +=== How to Configure Class Loader Order + +If you are deploying a EclipseLink enabled application that uses +EclipseLink `+sessions.xml+` or XML project deployment, you must use the +WebSphere Application Server Administrative Console to set *Class loader +order* to *Class loaded with application class loader first*. + +=== How to Integrate with the WebSphere JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== How to Configure Clustering on IBM WebSphere Application Server + +For information on integrating a EclipseLink application with an +application server cluster, see link:#How_to_Integrate_Clustering[How to +Integrate Clustering]. + +== Integrating EclipseLink with Sun Application Server + +To integrate a EclipseLink application with Sun Application Server +(SunAS), you must consider the following: + +* link:#How_to_Configure_the_Sun_Application_Server_Classpath[How to +Configure the Sun Application Server Classpath] +* link:#How_to_Integrate_with_the_Sun_Application_Server_JTA[How to +Integrate with the Sun Application Server JTA] + +In addition to configuring these SunAS-specific options, you must also +consider the general application server integration issues in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Configure the Sun Application Server Classpath + +To configure EclipseLink support for SunAS, do the following: + +[arabic] +. Add the __`+\jlib\eclipselink.jar+` file to the application server +classpath. +. Ensure that your EclipseLink application defines an XML parser +platform (see link:#How_to_Configure_the_XML_Parser_Platform[How to +Configure the XML Parser Platform]). + +=== How to Integrate with the Sun Application Server JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session (see link:Configuring%20a%20Session%20(ELUG)[Configuring the +Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +== Integrating EclipseLink with JBoss Application Server + +These instructions apply to JBoss AS versions prior to AS7. AS7 changes +the setup quite dramatically; the best available documentation is +currently here: +https://community.jboss.org/wiki/HowToUseEclipseLinkWithAS7 + +To integrate a EclipseLink application with JBoss Application Server, +you must consider the following: + +* link:#How_to_Configure_the_JBoss_Classpath[How to Configure the JBoss +Classpath] +* link:#How_to_Integrate_with_the_JBoss_JTA[How to Integrate with the +JBoss JTA] + +In addition to configuring these JBoss-specific options, you must also +consider the general application server integration issues in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Configure the JBoss Classpath + +To configure EclipseLink support for JBoss, do the following: + +[arabic] +. Add the __`+\jlib\eclipselink.jar+` file to the application server +classpath. +. Ensure that your EclipseLink application defines an XML parser +platform (see link:#How_to_Configure_the_XML_Parser_Platform[How to +Configure the XML Parser Platform]). + +=== How to Integrate with the JBoss JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== How to Configure JPA Application Deployment to JBoss 4.2 Application Server + +For JPA applications, to enable the container to manage entities, +statically weave the entities and reference JBoss as the target server +in the `+persistence.xml+` file. + +Perform the following deployment changes: + +[arabic] +. If weaving is required, statically weave the entities before EAR +packaging. Use either the command-line weaver or the weaving Ant task +(see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Configure_Static_Weaving_for_JPA_Entities[How +to Configure Static Weaving for JPA Entities]). +. Ensure that the `+eclipselink.target-server+` property (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Extensions_for_Session,_Target_Database_and_Target_Application_Server[Using +EclipseLink JPA Extensions for Session, Target Database and Target +Application Server]) is set in the `+persistence.xml+` file of all +persistence units deployed to the JBoss container: ++ ++ +Otherwise, even though the container-managed entities are predeployed, +they will not be managed at run time. + +For more information and examples, see the following: + +* http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/JBoss +* link:Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#How_to_Deploy_an_Application_to_Generic_Java_EE_5_Application_Servers[How +to Deploy an Application to Generic Java EE 5 Application Servers] + +== Integrating EclipseLink with SAP NetWeaver Application Server + +To integrate a EclipseLink application with SAP NetWeaver Application +Server, you must consider the following: + +* link:#How_to_Configure_the_NetWeaver_Classpath[How to Configure the +NetWeaver Classpath] +* link:#How_to_Integrate_with_the_NetWeaver_JTA[How to Integrate with +the NetWeaver JTA] + +In addition to configuring these NetWeaver-specific options, you must +also consider the general application server integration issues in +link:#Integrating_EclipseLink_with_an_Application_Server[Integrating +EclipseLink with an Application Server]. + +=== How to Configure the NetWeaver Classpath + +To configure EclipseLink support for NetWeaver, do the following: + +[arabic] +. Create and deploy a standard library (i.e. an SDA file) that contains +the __`+\jlib\eclipselink.jar+` file and associate the library with the +application. +. Ensure that your EclipseLink application defines an XML parser +platform (see link:#How_to_Configure_the_XML_Parser_Platform[How to +Configure the XML Parser Platform]). + +=== How to Integrate with the NetWeaver JTA + +For applications that require JTA integration, specify the external +transaction controller when you configure the server platform in your +session. See +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform] for general information on configuring the server +platform and +link:EclipseLink_Development_ServerPlatform_NetweaverPlatform[EclipseLink/Development/ServerPlatform/NetweaverPlatform] +for a description of the NetWeaver server platform. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +== Defining Security Permissions + +By default, when you run a EclipseLink-enabled application in a JVM +configured with a nondefault `+java.lang.SecurityManager+`, the +EclipseLink run time executes certain internal functions by executing a +`+PrivilegedAction+` with `+java.security.AccessController+` method +`+doPrivileged+`. This ensures that you do not need to grant many +permissions to EclipseLink for it to perform its most common operations. +You need only grant certain permissions depending on the types of +optional EclipseLink features you use (see +link:#How_to_Define_Permissions_Required_by_EclipseLink_Features[How to +Define Permissions Required by EclipseLink Features]). + +While using `+doPrivileged+` method provides enhanced security, it will +severely impact overall performance. Alternatively, you can configure +EclipseLink to disable the use of `+doPrivileged+` method even when a +nondefault `+SecurityManager+` is present (see +link:#How_to_Disable_doPrivileged_Operation[How to Disable doPrivileged +Operation]). In this case, you must grant EclipseLink all required +permissions (see +link:#How_to_Define_Permissions_Required_by_EclipseLink_Features[How to +Define Permissions Required by EclipseLink Features] and +link:#How_to_Define_Permissions_Required_when_doPrivileged_Is_Disabled[How +to Define Permissions Required when doPrivileged Is Disabled]). + +[width="100%",cols="<100%",] +|=== +|*Note*: While enabling the use of `+doPriviledged+` method enhances +EclipseLink application security, it does not guarantee that secure code +cannot be called by application code in ways that the system did not +intend. You must consider the use of `+doPriviledged+` method within the +context of your overall application security strategy. For more +information, see +http://java.sun.com/security/index.jsp[`+http://java.sun.com/security/index.jsp+`]. +|=== + +If you run a EclipseLink-enabled application in a JVM without a +nondefault `+SecurityManager+`, you do not need to grant any +permissions. + +=== How to Define Permissions Required by EclipseLink Features + +When you run a EclipseLink-enabled application in a JVM configured with +a nondefault `+java.lang.SecurityManager+` and `+doPrivileged+` +operation is enabled, you may need to grant additional permissions if +your application requires any of the following: + +* link:#Defining_System_Properties[Defining System Properties] +* link:#Loading_project.xml_or_sessions.xml_Files[Loading project.xml or +sessions.xml Files] +* link:#Defining_Cache_Coordination[Defining Cache Coordination] +* link:#Accessing_a_Data_Source_by_Port[Accessing a Data Source by Port] +* link:#Logging_with_java.util.logging[Logging with java.util.logging] +* link:#Granting_Permissions_for_Java_EE_Application_Deployment[Granting +Permissions for Java EE Application Deployment] + +==== Defining System Properties + +By default, a EclipseLink-enabled application requires access to the +system properties granted in the default +`+<+`_`+JAVA_HOME+`_`+>/lib/security/java.policy+` file. If your +application requires access to other platform-specific, environment, or +custom properties, then grant further `+PropertyPermission+` +permissions, as the following example shows. + +[#Example 7-6]## *_Permissions for System Properties_* + +`+permission java.util.PropertyPermission "my.property", "read";+` + +==== Loading project.xml or sessions.xml Files + +Most EclipseLink-enabled applications read in `+project.xml+` and +`+sessions.xml+` files directly. Grant permissions to the specific files +or file locations, as the following example shows. This example assumes +that both `+project.xml+` and `+sessions.xml+` files are located in the +same directory (given by application-specific system property +`+deployment.xml.home+`). Alternatively, you can specify a separate +`+FilePermission+` for each file. + +[#Example 7-7]## *_Permissions for Loading Deployment XML Files_* + +`+permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";+` + +For information on `+FilePermission+` settings for Java EE applications, +see +link:#Granting_Permissions_for_Java_EE_Application_Deployment[Granting +Permissions for Java EE Application Deployment]. + +==== Defining Cache Coordination + +If your application uses cache coordination (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]), then grant `+accept+`, `+connect+`, `+listen+`, and +`+resolve+` permissions to the specific sockets used by your coordinated +cache, as the following example shows. This example assumes that the +coordinated cache multicast port (see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Multicast_Port[Configuring +a Multicast Port]) is 1024. + +[#Example 7-8]## *_Permissions for Cache Coordination_* + +`+permission java.net.SocketPermission "localhost:1024-", "accept, connect, listen, resolve";+` + +==== Accessing a Data Source by Port + +If your EclipseLink-enabled application accesses a data source using a +socket, then grant `+connect+` and `+resolve+` permissions for that +socket, as the following example shows. This example assumes that the +host name (or IP address) of the remote host that provides the data +source (such as a relational database server host) is given by +application-specific system property `+remote.data.source.host+` and +that this host accepts data source connections on port 1025. + +[#Example 7-9]## *_Permissions for non-Java EE Data Source Connections_* + +`+permission java.net.SocketPermission "${remote.data.source.host}:1025-", "connect, resolve";+` + +For Java EE applications, data source socket permissions are usually +handled by the application server. + +==== Logging with java.util.logging + +If you configure your EclipseLink-enabled application to use +`+java.util.logging+` package (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging]), then grant your application `+control+` permissions, as this +example shows. + +[#Example 7-10]## *_Permissions for java.util.logging_* + +`+permission java.util.logging.LoggingPermission "control"+` + +==== Granting Permissions for Java EE Application Deployment + +If you are deploying a EclipseLink-enabled Java EE application, you must +grant permissions for the following: + +* The `+eclipselink.jar+` file. For example: + +`+grant codeBase "file:+``+/jlib/eclipselink.jar" {+` +`+    permission java.security.AllPermission;+` `+};+` + +If you are using an XML platform, you must also grant the following +permissions: + +* The `+eclipse.persistence.xml.platform+` system property. For Example: + +`+permission java.util.PropertyPermission "eclipse.persistence.xml.platform", "read"+` + +=== How to Define Permissions Required when doPrivileged Is Disabled + +If you disable `+doPrivileged+` operation when you run a +EclipseLink-enabled application in a JVM configured with a nondefault +`+java.lang.SecurityManager+`, you must grant the following permissions: + +* `+java.lang.reflect.RelectPermission "suppressAccessChecks"+` +* `+java.lang.RuntimePermission "accessDeclaredMembers"+` +* `+java.lang.RuntimePermission "getClassLoader"+` + +You may also have to grant additional permissions depending on the +EclipseLink features your application uses. For more information, see +link:#How_to_Define_Permissions_Required_by_EclipseLink_Features[How to +Define Permissions Required by EclipseLink Features]. + +=== How to Disable doPrivileged Operation + +To disable `+doPrivileged+` operation when you run a EclipseLink-enabled +application in a JVM configured with a nondefault +`+java.lang.SecurityManager+`, set system property +`+oracle.j2ee.security.usedoprivileged+` to `+false+`. If you are using +OC4J, set system property `+oracle.j2ee.security.usedoprivileged+` to +`+false+`. + +To enable `+doPrivileged+` operation, set these system properties to +`+true+`. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Cache_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Cache_(ELUG).adoc new file mode 100644 index 00000000000..e2124893198 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Cache_(ELUG).adoc @@ -0,0 +1,1000 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_Cache_(ELUG)[Related Topics] + +The EclipseLink cache is an in-memory repository that stores recently +read or written objects based on class and primary key values. +EclipseLink uses the cache to do the following: + +* Improve performance by holding recently read or written objects and +accessing them in-memory to minimize database access. +* Manage locking and isolation level. +* Manage object identity. + +== Cache Architecture + +EclipseLink uses two types of cache: the *session cache* maintains +objects retrieved from and written to the data source; and the *unit of +work cache* holds objects while they participate in transactions. When a +unit of work successfully commits to the data source, EclipseLink +updates the session cache accordingly. + +[width="100%",cols="<100%",] +|=== +|*_Note_*: You can also configure a query to cache its results (see +link:Using%20Advanced%20Query%20API%20(ELUG)[How to Cache Results in a +ReadQuery]) +|=== + +As this figure shows, the session cache and the unit of work cache work +together with the data source connection to manage objects in an +EclipseLink application. The object life cycle relies on these three +mechanisms. + +[#Figure 98-1]## *_Object Life Cycle and the EclipseLink Caches_* + +.Object Life Cycle and the EclipseLink Caches +image::cacharch.gif[Object Life Cycle and the EclipseLink +Caches,title="Object Life Cycle and the EclipseLink Caches"] + +=== Session Cache + +The session cache is a shared cache that services clients attached to a +given session. When you read objects from or write objects to the data +source using a client session, EclipseLink saves a copy of the objects +in the parent server session’s cache and makes them accessible to all +other processes in the session. + +EclipseLink adds objects to the session cache from the following: + +* The data store, when EclipseLink executes a read operation +* The unit of work cache, when a unit of work successfully commits a +transaction + +An isolated client session is a special type of client session that +provides its own session cache isolated from the shared object cache of +its parent server session. The isolated client session cache can be used +to improve user-based security or to avoid caching highly volatile data. +Developers can choose on a per object type whether default shared +session cache or the isolated client session cache is used. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]. + +=== Unit of Work Cache + +The unit of work cache services operations within the unit of work. It +maintains and isolates objects from the session cache, and writes +changed or new objects to the session cache after the unit of work +commits changes to the data source. + +== Cache Concepts + +This section describes concepts unique to the EclipseLink cache, +including the following: + +* link:#Cache_Type_and_Object_Identity[Cache Type and Object Identity] +* link:#Querying_and_the_Cache[Querying and the Cache] +* link:#Stale_Data[Stale Data] +* link:#Query_Refreshes[Query Refreshes] +* link:#Cache_Invalidation[Cache Invalidation] +* link:#Cache_Coordination[Cache Coordination] +* link:#Cache_Isolation[Cache Isolation] +* link:#Cache_Locking_and_Transaction_Isolation[Cache Locking and +Transaction Isolation] +* link:#Cache_Optimization[Cache Optimization] + +=== Cache Type and Object Identity + +EclipseLink preserves object identity through its cache using the +primary key attributes of a persistent entity. These attributes may or +may not be assigned through sequencing (see +link:Introduction%20to%20Projects_(ELUG)#Projects_and_Sequencing[Projects +and Sequencing]). In a Java application, object identity is preserved if +each object in memory is represented by one, and only one, object +instance. Multiple retrievals of the same object return references to +the same object instance–not multiple copies of the same object. + +Maintaining object identity is extremely important when the +application’s object model contains circular references between objects. +You must ensure that the two objects are referencing each other +directly, rather than copies of each other. Object identity is important +when multiple parts of the application may be modifying the same object +simultaneously. + +We recommend that you always maintain object identity. Disable object +identity only if absolutely necessary, for example, for read-only +objects (see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring +Read-Only Descriptors]). + +You can configure how object identity is managed on a class-by-class +basis. The `+ClassDescriptor+` object provides the cache and identity +map options described in this table. + +[#Table 98-1]## *_Cache and Identity Map Options_* + +Option (Identity Map) + +Caching + +Guaranteed Identity + +Memory Use + +Full Identity Map + +Yes + +Yes + +Very High + +Weak Identity Map + +Yes + +Yes + +Low + +Soft Identity Map + +Yes + +Yes + +High + +Soft Cache Weak Identity Map and Hard Cache Weak Identity Map + +Yes + +Yes + +Medium-high + +No Identity Map + +No + +No + +None + +For more information, see +link:#Guidelines_for_Configuring_the_Cache_and_Identity_Maps[Guidelines +for Configuring the Cache and Identity Maps]. + +==== Full Identity Map + +This option provides full caching and guaranteed identity: objects are +never flushed from memory unless they are deleted. + +It caches all objects and does not remove them. Cache size doubles +whenever the maximum size is reached. This method may be +memory-intensive when many objects are read. Do not use this option on +batch operations. + +We recommend using this identity map when the data set size is small and +memory is in large supply. + +==== Weak Identity Map + +This option is similar to the full identity map, except that the map +holds the objects by using weak references. This method allows full +garbage collection and provides full caching and guaranteed identity. + +The weak identity map uses less memory than full identity map but also +does not provide a durable caching strategy across client/server +transactions. Objects are available for garbage collection when the +application no longer references them on the server side (that is, from +within the server JVM). + +==== Soft Identity Map + +This option is similar to the weak identity map, except that the map +uses soft references instead of weak references. This method allows full +garbage collection and provides full caching and guaranteed identity. + +The soft identity map allows for optimal caching of the objects, while +still allowing the JVM to garbage collect the objects if memory is low. + +==== Soft Cache Weak Identity Map and Hard Cache Weak Identity Map + +These options are similar to the weak identity map except that they +maintain a most frequently used subcache. The subcache uses soft or hard +references to ensure that these objects are garbage-collected only if +the system is low on memory. + +The soft cache weak identity map and hard cache weak identity map +provide more efficient memory use. They release objects as they are +garbage-collected, except for a fixed number of most recently used +objects. Note that weakly cached objects might be flushed if the +transaction spans multiple client/server invocations. The size of the +subcache is proportional to the size of the identity map as specified by +the `+ClassDescriptor+` method `+setIdentityMapSize+`. You should set +this cache size to be as large as the maximum number of objects (of the +same type) referenced within a transaction (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]). + +We recommend using this identity map in most circumstances as a means to +control memory used by the cache. + +For more information, see +link:#What_you_may_need_to_Know_About_the_Internals_of_Weak,_Soft,_and_Hard_Identity_Maps[What +you may need to Know About the Internals of Weak, Soft, and Hard +Identity Maps]. + +==== No Identity Map + +This option does not preserve object identity and does not cache +objects. + +We do not recommend using the no identity map option. Instead, review +the alternatives of cache invalidation and isolated caching. + +==== Guidelines for Configuring the Cache and Identity Maps + +You can configure the cache at the project +(link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Project_Level[Configuring +Cache Type and Size at the Project Level]) or descriptor +(link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]) level. + +Use the following guidelines when configuring your cache and identity +map: + +* If objects with a long life span and object identity are important, +use a `+SoftIdentityMap+`, `+SoftCacheWeakIdentityMap+` or +`+HardCacheWeakIdentityMap+` policy. For more information on when to +choose one or the other, see +link:#What_you_may_need_to_Know_About_the_Internals_of_Weak,_Soft,_and_Hard_Identity_Maps[What +you may need to Know About the Internals of Weak, Soft, and Hard +Identity Maps]. +* If object identity is important, but caching is not, use a +`+WeakIdentityMap+` policy. +* If an object has a long life span or requires frequent access, or +object identity is important, use a `+FullIdentityMap+` policy. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Use the `+FullIdentityMap+` only if the class has a small +number of finite instances. Otherwise, a memory leak will occur.’’’ +|=== + +* If an object has a short life span or requires frequent access, and +identity is not important, use a `+CacheIdentityMap+` policy. + +* If objects are discarded immediately after being read from the +database, such as in a batch operation, use a `+NoIdentityMap+` policy. +The `+NoIdentityMap+` does not preserve object identity. + +[width="100%",cols="<100%",] +|=== +|*Note:* We do not recommend the use of `+CacheIdentityMap+` and +`+NoIdentityMap+` policies. +|=== + +==== What You May Need to Know About the Internals of Weak, Soft, and Hard Identity Maps + +The `+WeakIdentiyMap+` and `+SoftIdentityMap+` use JVM weak and soft +references to ensure that any object referenced by the application is +held in the cache. Once the application releases its’ reference to the +object, the JVM is free to garbage collection the objects. When a weak +and soft reference is garbage collected - is determined by the JVM. In +general one could expect a weak reference to be garbage collected on +each JVM garbage collector, and a soft reference to be garbage collected +when the JVM determines memory is low. + +The `+SoftCacheWeakIdentityMap+` and `+HardCacheWeakIdentityMap+` types +of identity map contain the following two caches: + +* Reference cache: implemented as a `+LinkedList+` that contains soft or +hard references, respectively. +* Weak cache: implemented as a `+HashMap+` that contains weak +references. + +When you create a `+SoftCacheWeakIdentityMap+` or +`+HardCacheWeakIdentityMap+` with a specified size, the reference cache +`+LinkedList+` is exactly this size. The weak cache `+HashMap+` is +initialized to 100 percent of the specified size: the weak cache will +grow when more objects than the specified size are read in. Because +EclipseLink does not control garbage collection, the JVM can reap the +weakly held objects whenever it sees fit. + +Because the reference cache is implemented as a `+LinkedList+`, new +objects are added to the end of the list. Because of this, it is by +nature a least recently used (LRU) cache: fixed size, object at the top +of the list is deleted, provided the maximum size has been reached. + +The `+SoftCacheWeakIdentityMap+` and `+HardCacheWeakIdentityMap+` are +essentially the same type of identity map. The +`+HardCacheWeakIdentityMap+` was constructed to work around an issue +with some JVMs. + +If your application reaches a low system memory condition frequently +enough, or if your platform’s JVM treats weak and soft references the +same, the objects in the reference cache may be garbage-collected so +often that you will not benefit from the performance improvement +provided by it. If this is the case, we recommend that you use the +`+HardCacheWeakIdentityMap+`. It is identical to the +`+SoftCacheWeakIdentityMap+` except that it uses hard references in the +reference cache. This guarantees that your application will benefit from +the performance improvement provided by it. + +When an object in a `+HardCacheWeakIdentityMap+` or +`+SoftCacheWeakIdentityMap+` is pushed out of the reference cache, it +gets put in the weak cache. Although it is still cached, EclipseLink +cannot guarantee that it will be there for any length of time because +the JVM can decide to garbage-collect weak references at anytime. + +=== Querying and the Cache + +A query that is run against the shared session cache is known as an +*in-memory query*. Careful configuration of in-memory querying can +improve performance (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Use_In-Memory_Queries[How +to Use In-Memory Queries]). + +By default, a query that looks for a single object based on primary key +attempts to retrieve the required object from the cache first, searches +the data source only if the object is not in the cache. All other query +types search the database first, by default. You can specify whether a +given query runs against the in-memory cache, the database, or both. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Queries and the +Cache]. + +=== Handling Stale Data + +*Stale data* is an artifact of caching, in which an object in the cache +is not the most recent version committed to the data source. To avoid +stale data, implement an appropriate cache locking strategy. + +By default, EclipseLink optimizes concurrency to minimize cache locking +during read or write operations. Use the default EclipseLink isolation +level, unless you have a very specific reason to change it. For more +information on isolation levels in EclipseLink, see +link:#Cache_Isolation[Cache Isolation]. + +Cache locking regulates when processes read or write an object. +Depending on how you configure it, cache locking determines whether a +process can read or write an object that is in use within another +process. + +A well-managed cache makes your application more efficient. There are +very few cases in which you turn the cache off entirely, because the +cache reduces database access, and is an important part of managing +object identity. + +To make the most of your cache strategy and to minimize your +application’s exposure to stale data, we recommend the following: + +* link:#Configuring_a_Locking_Policy[Configuring a Locking Policy] +* link:#Configuring_the_Cache_on_a_Per-Class_Basis[Configuring the Cache +on a Per-Class Basis] +* link:#Forcing_a_Cache_Refresh_when_Required_on_a_Per-Query_Basis[Forcing +a Cache Refresh when Required on a Per-Query Basis] +* link:#Configuring_Cache_Invalidation[Configuring Cache Invalidation] +* link:#Configuring_Cache_Coordination[Configuring Cache Coordination] + +==== Configuring a Locking Policy + +Make sure you configure a locking policy so that you can prevent or at +least identify when values have already changed on an object you are +modifying. Typically, this is done using optimistic locking. EclipseLink +offers several locking policies such as numeric version field, +time-stamp version field, and some or all fields. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Locking Policy]. + +==== Configuring the Cache on a Per-Class Basis + +If other applications can modify the data used by a particular class, +use a weaker style of cache for the class. For example, the +`+SoftCacheWeakIdentityMap+` or `+WeakIdentityMap+` minimizes the length +of time the cache maintains an object whose reference has been removed. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]. + +==== Forcing a Cache Refresh when Required on a Per-Query Basis + +Any query can include a flag that forces EclipseLink to go to the data +source for the most up-to-date version of selected objects and update +the cache with this information. + +For more information, see the following: + +* link:#Cache_Refresh_API[Cache Refresh API] +* link:Using%20Basic%20Query%20API%20(ELUG)#Using_DatabaseQuery_Queries[Using +DatabaseQuery Queries] +* link:Using%20Basic%20Query%20API%20(ELUG)#Using_Named_Queries[Using +Named Queries] + +==== Configuring Cache Invalidation + +Using descriptor API, you can designate an object as invalid: when any +query attempts to read an invalid object, EclipseLink will go to the +data source for the most up to date version of that object and update +the cache with this information. You can manually designate an object as +invalid or use a `+CacheInvalidationPolicy+` to control the conditions +under which an object is designated invalid. + +For more information, see link:#Cache_Invalidation[Cache Invalidation]. + +==== Configuring Cache Coordination + +If your application is primarily read-based and the changes are all +being performed by the same Java application operating with multiple, +distributed sessions, you may consider using the EclipseLink cache +coordination feature. Although this will not prevent stale data, it +should greatly minimize it. + +For more information, see link:#Cache_Coordination[Cache Coordination]. + +=== Explicit Query Refreshes + +Some distributed systems require only a small number of objects to be +consistent across the servers in the system. Conversely, other systems +require that several specific objects must always be guaranteed to be +up-to-date, regardless of the cost. If you build such a system, you can +explicitly refresh selected objects from the database at appropriate +intervals, without incurring the full cost of distributed cache +coordination. + +To implement this type of strategy, do the following: + +[arabic] +. Configure a set of queries that refresh the required objects. +. Establish an appropriate refresh policy. +. Invoke the queries as required to refresh the objects. + +==== Refresh Policy + +When you execute a query, if the required objects are in the cache, +EclipseLink returns the cached objects without checking the database for +a more recent version. This reduces the number of objects that +EclipseLink must build from database results, and is optimal for +noncoordinated cache environments. However, this may not always be the +best strategy for a coordinated cache environment. + +To override this behavior, set a refresh policy that specifies that the +objects from the database always take precedence over objects in the +cache. This updates the cached objects with the data from the database. + +You can implement this type of refresh policy on each EclipseLink +descriptor, or just on certain queries, depending upon the nature of the +application. + +For more information, see the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Cache +Refreshing] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[How to Refresh +the Cache] + +[cols="<",] +|=== +|*Note:* Refreshing does not prevent phantom reads from occurring. +|=== + +=== Cache Invalidation + +By default, objects remain in the session cache until they are +explicitly deleted (see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)[Deleting Objects]) +or garbage collected when using a weak identity map (see +link:Configuring%20a%20Project%20(ELUG)[Configuring Cache Type and Size +at the Project Level]). + +Alternatively, you can configure any object with a +`+CacheInvalidationPolicy+` that lets you specify, either automatically +or manually, under what circumstances a cached object is invalid: when +any query attempts to read an invalid object, EclipseLink will go to the +data source for the most up-to-date version of that object, and update +the cache with this information. + +You can use any of the following `+CacheInvalidationPolicy+` instances: + +* `+DailyCacheInvalidationPolicy+`: the object is automatically flagged +as invalid at a specified time of day. +* `+NoExpiryCacheInvalidationPolicy+`: the object can only be flagged as +invalid by explicitly calling +`+org.eclipse.persistence.sessions.IdentityMapAccessor+` method +`+invalidateObject+`. +* `+TimeToLiveCacheInvalidationPolicy+`: the object is automatically +flagged as invalid after a specified time period has elapsed since the +object was read. + +You can configure a cache invalidation policy in the following ways: + +* At the project level that applies to all objects ( +link:Configuring%20a%20Project%20(ELUG)[Configuring Cache Expiration at +the Project Level]) +* At the descriptor level to override the project level configuration on +a per-object basis ( +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Cache Expiration +at the Descriptor Level]) +* At the query level that applies to the results returned by the query +(link:Using%20Advanced%20Query%20API%20(ELUG)[How to Configure Cache +Expiration at the Query Level]) + +If you configure a query to cache results in its own internal cache (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[How to Cache +Query Results in the Query Cache]), the cache invalidation policy you +configure at the query level applies to the query’s internal cache in +the same way it would apply to the session cache. + +If you are using a coordinated cache (see link:#Cache_Coordination[Cache +Coordination]), you can customize how EclipseLink communicates the fact +that an object has been declared invalid. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[Configuring +Cache Coordination Change Propagation at the Descriptor Level]. + +=== Cache Coordination + +The need to maintain up-to-date data for all applications is a key +design challenge for building a distributed application. The difficulty +of this increases as the number of servers within an environment +increases. EclipseLink provides a distributed cache coordination feature +that ensures data in distributed applications remains current. + +Cache coordination reduces the number of optimistic lock exceptions +encountered in a distributed architecture, and decreases the number of +failed or repeated transactions in an application. However, cache +coordination in no way eliminates the need for an effective locking +policy. To effectively ensure working with up-to-date data, cache +coordination must be used with optimistic or pessimistic locking. We +recommend that you use cache coordination with an optimistic locking +policy (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]). + +You can use cache invalidation to improve cache coordination efficiency. +For more information, see link:#Cache_Invalidation[Cache Invalidation]. + +=== Cache Isolation + +Isolated client sessions provide a mechanism for disabling the shared +server session cache. Any classes marked as isolated only cache objects +relative to the life cycle of their client session. These classes never +utilize the shared server session cache. This is the best mechanism to +prevent caching as it is configured on a per-class basis allowing +caching for some classes, and denying for others. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]. + +=== Cache Locking and Transaction Isolation + +By default, EclipseLink optimizes concurrency to minimize cache locking +during read or write operations. Use the default EclipseLink transaction +isolation configuration unless you have a very specific reason to change +it. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Database +Transaction Isolation Levels]. + +=== Cache Optimization + +Tune the EclipseLink cache for each class to help eliminate the need for +distributed cache coordination. Always tune these settings before +implementing cache coordination. + +For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[Optimizing +Cache]. + +== Cache Coordination + +As the following figure shows, cache coordination is a session feature +that allows multiple, possibly distributed, instances of a session to +broadcast object changes among each other so that each session’s cache +is either kept up-to-date or notified that the cache must update an +object from the data source the next time it is read. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use isolated client sessions (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]) with cache coordination. +|=== + +[#Figure 98-2]## *_Cache Coordination_* + +.Cache Coordination +image::cachcord.gif[Cache Coordination,title="Cache Coordination"] + +When sessions are distributed, that is, when an application contains +multiple sessions (in the same JVM, in multiple JVMs, possibly on +different servers), as long as the servers hosting the sessions are +interconnected on the network, sessions can participate in cache +coordination. Coordinated cache types that require discovery services +also require the servers to support User Datagram Protocol (UDP) +communication and multicast configuration (for more information, see +link:#Coordinated_Cache_Architecture[Coordinated Cache Architecture]). + +This section describes the following: + +* link:#When_to_Use_Cache_Coordination[When to Use Cache Coordination] +* link:#Coordinated_Cache_Architecture[Coordinated Cache Architecture] +* link:#Coordinated_Cache[Coordinated Cache Types] +* link:#Custom_Coordinated_Cache[Custom Coordinated Cache] + +For more information, see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)[Configuring a +Coordinated Cache]. + +=== When to Use Cache Coordination + +Cache coordination can enhance performance and reduce the likelihood of +stale data for applications that have the following characteristics: + +* Changes are all being performed by the same Java application operating +with multiple, distributed sessions +* Primarily read-based +* Regularly requests and updates the same objects + +To maximize performance, avoid cache coordination for applications that +do not have these characteristics. For more information about +alternatives to cache coordination, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Cache[Optimizing +Cache]. + +Cache coordination enhances performance mainly by avoiding data source +access. + +Cache coordination reduces the occurrence of stale data by increasing +the likelihood that distributed caches are kept up-to-date with changes +and are notified when one of the distributed caches must update an +object from the data source the next time it is read. + +Cache coordination reduces the number of optimistic lock exceptions +encountered in a distributed architecture, and decreases the number of +failed or repeated transactions in an application. However, cache +coordination in no way eliminates the need for an effective locking +policy. To effectively ensure working with up-to-date data, cache +coordination must be used with optimistic or pessimistic locking. We +recommend that you use cache coordination with an optimistic locking +policy (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]). + +For other options to reduce the likelihood of stale data, see +link:#Stale_Data[Stale Data]. + +=== Coordinated Cache Architecture + +EclipseLink provides coordinated cache implementations that perform +discovery and message transport services using various technologies +including the following: + +* Java Message Service (JMS) – See link:#JMS_Coordinated_Cache[JMS +Coordinated Cache] +* Remote Method Invocation (RMI) – See link:#RMI_Coordinated_Cache[RMI +Coordinated Cache] +* Common Object Request Broker Architecture (CORBA) – See +link:#CORBA_Coordinated_Cache[CORBA Coordinated Cache] + +Regardless of the type of discovery and message transport you choose to +use, the following are the principal objects that provide coordinated +cache functionality: + +* link:#Session[Session] +* link:#Descriptor[Descriptor] +* link:#Unit_of_Work[Unit of Work] + +==== Session + +When you enable a session for change propagation, the session provides +discovery and message transport services using either JMS, RMI, CORBA, +or Oracle Application Server 10g Cluster. + +Discovery services ensure that sessions announce themselves to other +sessions participating in cache coordination. Discovery services use UDP +communication and multicast configuration to monitor sessions as they +join and leave the coordinated cache. All coordinated cache types +(except JMS) require discovery services. + +Message transport services allow the session to broadcast object change +notifications to other sessions participating in cache coordination when +a unit of work from this session commits a change. + +==== Descriptor + +You can configure how object changes are broadcast on a +descriptor-by-descriptor basis. This lets you fine-tune the type of +notification to make. + +For example, for an object with few attributes, you can configure its +descriptor to send object changes. For an object with many attributes, +it may be more efficient to configure its descriptor so that the object +is flagged as invalid (so that other sessions will know to update the +object from the data source the next time it is read). + +==== Unit of Work + +Only changes committed by a unit of work are subject to propagation when +cache coordination is enabled. The unit of work computes the appropriate +change set based on the descriptor configuration of affected objects. + +=== Coordinated Cache Types + +You can create the following types of coordinated cache: + +* link:#JMS_Coordinated_Cache[JMS Coordinated Cache] +* link:#RMI_Coordinated_Cache[RMI Coordinated Cache] +* link:#CORBA_Coordinated_Cache[CORBA Coordinated Cache] + +==== JMS Coordinated Cache + +For a JMS coordinated cache, when a particular session’s coordinated +cache starts up, it uses its JNDI naming service information to locate +and create a connection to the JMS server. The coordinated cache is +ready when all participating sessions are connected to the same topic on +the same JMS server. At this point, sessions can start sending and +receiving object change messages. You can then configure all sessions +that are participating in the same coordinated cache with the same JMS +and JNDI naming service information. + +Because you must supply the necessary information to connect to the JMS +Topic, a JMS coordinated cache does not use a discovery service. + +If you do use cache coordination, we recommend that you use JMS cache +coordination: JMS is robust, easy to configure, and provides efficient +support for asynchronous change propagation. + +For more information, see +link:Configuring%20a%20JMS%20Coordinated%20Cache%20(ELUG)#Configuring_a_JMS_Coordinated_Cache[Configuring +a JMS Coordinated Cache]. + +For more information on configuring JMS, refer to your see JMS +provider’s documentation. + +==== RMI Coordinated Cache + +For an RMI coordinated cache, when a particular session’s coordinated +cache starts up, the session binds its connection in its naming service +(either an RMI registry or JNDI), creates an announcement message (that +includes its own naming service information), and broadcasts the +announcement to its multicast group (see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Multicast_Group_Address[Configuring +a Multicast Group Address] and +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Multicast_Port[Configuring +a Multicast Port]). When a session that belongs to the same multicast +group receives this announcement, it uses the naming service information +in the announcement message to establish bidirectional connections with +the newly announced session’s coordinated cache. The coordinated cache +is ready when all participating sessions are interconnected in this way, +at which point sessions can start sending and receiving object change +messages. You can then configure each session with naming information +that identifies the host on which the session is deployed. + +If you do use cache coordination, we recommend that you use RMI cache +coordination only if you require synchronous change propagation (see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_the_Synchronous_Change_Propagation_Mode[Configuring +the Synchronous Change Propagation Mode]). + +EclipseLink also supports cache coordination using RMI over the Internet +Inter-ORB Protocol (IIOP). An RMI/IIOP coordinated cache uses RMI (and a +JNDI naming service) for discovery and message transport services. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you use an RMI coordinated cache, we recommend that you use +RMI/IIOP only if absolutely necessary. +|=== + +For more information, see +link:Configuring%20an%20RMI%20Coordinated%20Cache%20(ELUG)#Configuring_an_RMI_Coordinated_Cache[Configuring +an RMI Coordinated Cache]. + +==== CORBA Coordinated Cache + +For a CORBA coordinated cache, when a particular session’s coordinated +cache starts up, the session binds its connection in JNDI, creates an +announcement message (that includes its own JNDI naming service +information), and broadcasts the announcement to its multicast group +(see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Multicast_Group_Address[Configuring +a Multicast Group Address] and +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_a_Multicast_Port[Configuring +a Multicast Port]). When a session that belongs to the same multicast +group receives this announcement, it uses the naming service information +in the announcement message to establish bidirectional connections with +the newly announced session’s coordinated cache. The coordinated cache +is ready when all participating sessions are interconnected in this way, +at which point, sessions can start sending and receiving object change +messages. You can then configure each session with naming information +that identifies the host on which the session is deployed. + +Currently, EclipseLink provides support for the Sun Object Request +Broker. + +For more information on configuring a CORBA coordinated cache, see +link:Configuring%20a%20CORBA%20Coordinated%20Cache%20(ELUG)[Configuring +a CORBA Coordinated Cache]. + +=== Custom Coordinated Cache + +Using the classes in `+org.eclipse.persistence.sessions.coordination+` +package, you can define your own coordinated cache for custom solutions. + +Once you have created the required cache coordination classes, for more +information on configuring a user-defined coordinated cache, see +link:Configuring%20a%20Custom%20Coordinated%20Cache%20(ELUG)[Configuring +a Custom Coordinated Cache]. + +== Cache API + +To configure the EclipseLink cache, you use the appropriate API in the +following objects: + +* link:#Object_Identity_API[Object Identity API] +* link:#Cache_Refresh_API[Cache Refresh API] +* link:#Cache_Invalidation_API[Cache Invalidation API] +* link:#Cache_Coordination_API[Cache Coordination API] + +=== Object Identity API + +You configure object identity using the following `+ClassDescriptor+` +API: + +[#Example 98-1]## + +`+useCacheIdentityMap()+` + +`+useFullIdentityMap()+` + +`+useHardCacheWeakIdentityMap()+` + +`+useNoIdentityMap()+` + +`+useSoftCacheWeakIdentityMap()+` + +`+useWeakIdentityMap()+` + +`+useSoftIdentityMap() +` + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]. + +=== Cache Refresh API + +You configure cache refresh using the following `+ClassDescriptor+` API: + +[#Example 98-2]## + +`+alwaysRefreshCache()+` + +`+alwaysRefreshCacheOnRemote()+` + +`+disableCacheHits()+` + +`+disableCacheHitsOnRemote()+` + +`+onlyRefreshCacheIfNewerVersion()+` + +You can also configure cache refresh using the following API calls: + +* `+Session+`: `+refreshObject+` method +* `+DatabaseSession+` and `+UnitOfWork: refreshAndLockObject+` methods +* `+ObjectLevelReadQuery: refreshIdentityMapResult+` and +`+refreshRemoteIdentityMapResult+` methods + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Refreshing[Configuring +Cache Refreshing]. + +=== Cache Invalidation API + +You configure cache invalidation using `+ClassDescriptor+` methods +`+getCacheInvalidationPolicy+` and `+setCacheInvalidationPolicy+` to +configure an +`+org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy+`. + +You can use any of the following `+CacheInvalidationPolicy+` instances: + +* `+DailyCacheInvalidationPolicy+`: The object is automatically flagged +as invalid at a specified time of day. +* `+NoExpiryCacheInvalidationPolicy+`: The object can only be flagged as +invalid by explicitly calling +`+org.eclipse.persistence.sessions.IdentityMapAccessor+` method +`+invalidateObject+`. +* `+TimeToLiveCacheInvalidationPolicy+`: The object is automatically +flagged as invalid after a specified time period has elapsed since the +object was read. + +You can also configure cache invalidation using a variety of API calls +accessible through the `+Session+`. The +`+org.eclipse.persistence.sessions.IdentityMapAccessor+` provides the +following methods: + +* `+getRemainingValidTime+`: Returns the remaining life of the specified +object. This time represents the difference between the next expiry time +of the object and its read time. +* `+invalidateAll+`: Sets all objects for all classes to be invalid in +EclipseLink identity maps. +* `+invalidateClass(Class klass)+` and +`+invalidateClass(Class klass, boolean recurse)+`: Set all objects of a +specified class to be invalid in EclipseLink identity maps. +* `+invalidateObject(Object object)+`, +`+invalidateObject(Record rowWithPrimaryKey, Class klass)+` and +`+invalidateObject(Vector primaryKey, Class klass)+`: Set an object to +be invalid in EclipseLink identity maps. +* `+invalidateObjects(Expression selectionCriteria)+` and +`+invalidateObjects(Vector collection)+`: Set all objects from the +specified Expression/collection to be invalid in EclipseLink identity +maps. +* `+isValid(Record recordContainingPrimaryKey, Class theClass)+`, +`+isValid(Object object)+` and +`+isValid(java.util.Vector primaryKey, Class theClass)+`: Return +`+true+` if the object is valid in EclipseLink identity maps. + +For more information, see the following: + +* link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Expiration_at_the_Project_Level[Configuring +Cache Expiration at the Project Level] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Expiration_at_the_Descriptor_Level[Configuring +Cache Expiration at the Descriptor Level] +* link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Configure_Cache_Expiration_at_the_Query_Level[How +to Configure Cache Expiration at the Query Level] + +=== Cache Coordination API + +Configure cache coordination using the following `+Session+` methods: + +[#Example 98-3]## + +`+Session.getCommandManager().+` +`+    setShouldPropagateAsynchronously(boolean)+` + +`+Session.getCommandManager().getDiscoveryManager().+` +`+    setAnnouncementDelay()+` `+    setMulticastGroupAddress()+` +`+    setMulticastPort()+` `+    setPacketTimeToLive()+` + +`+Session.getCommandManager().getTransportManager().+` +`+    setEncryptedPassword()+` `+    setInitialContextFactoryName()+` +`+    setLocalContextProperties(Hashtable)+` +`+    setNamingServiceType() +`_`+passing\'\' \'\'in\'\' \'\'one\'\' \'\'of:+`_ +`+        TransportManager.JNDI_NAMING_SERVICE+` +`+        TransportManager.REGISTRY_NAMING_SERVICE+` +`+    setPassword()+` `+    setRemoteContextProperties(Hashtable)+` +`+    setShouldRemoveConnectionOnError()+` `+    setUserName()+` + +You configure how object changes are propagated using the following +`+ClassDescriptor+` methods: + +[#Example 98-4]## + +`+setCacheSynchronizationType() +`_`+passing\'\' \'\'in\'\' \'\'one\'\' \'\'of:+`_ +`+    ClassDescriptor.DO_NOT_SEND_CHANGES+` +`+    ClassDescriptor.INVALIDATE_CHANGED_OBJECTS+` +`+    ClassDescriptor.SEND_NEW_OBJECTS_WITH_CHANGES+` +`+    ClassDescriptor.SEND_OBJECT_CHANGES+` + +For more information, see +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#i1128398[Configuring +Common Coordinated Cache Options]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Data_Access_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Data_Access_(ELUG).adoc new file mode 100644 index 00000000000..b46cc95a935 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Data_Access_(ELUG).adoc @@ -0,0 +1,649 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_Data_Access_(ELUG)[Related +Topics] + +One of the most important functions of a session is to provide access to +a data source. + +== Data Access Concepts + +This section describes concepts unique to EclipseLink data access. + +=== Externally Managed Transactional Data Sources + +A EclipseLink transactional data source is _externally managed_ if the +connection pool is managed by a transaction service (such as an +application server controlled transaction or a JTA transaction). A JTA +managed data source or connection pool is commonly used in Java EE +applications and normally required in EJB applications. Use an +externally-managed connection pool as follows: + +* Configure the session to use an `+ExternalTransactionController+` to +integrate EclipseLink’s unit of work with the external transaction +service (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]). +* Use the `+external-transaction-control+` option to specify the +connection’s login and inform EclipseLink that the connection is +maintained by the external controller (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]). +* You may need to configure the EclipseLink read connection pool or +sequence connection pool to use a non-JTA connection pool in order to +avoid transactional overhead (see +link:#Default_(Write)_and_Read_Connection_Pools[Default (Write) and Read +Connection Pools]). + +For more information on transactional data sources, see the following: + +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#JTA_Controlled_Transactions[JTA +Controlled Transactions] +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#OTS_Controlled_Transactions[OTS +Controlled Transactions] + +Refer to +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions] for more information on EclipseLink +transactions. + +=== Data Source Login Types + +The login (if any) associated with a session 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 data source platform. + +A data source platform includes options specific to a particular data +source including such as binding, use of native SQL, use of batch +writing, and sequencing. For more information about platforms, see +link:#Data_Source_Platform_Types[Data Source Platform Types]. + +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, as +follows: + +* link:Introduction%20to%20Projects_(ELUG)#POJO_Session_Role[POJO +Session Role] +* link:Introduction%20to%20Projects_(ELUG)#Development_Role[Development +Role] + +There is a session login type for each project type that persists to a +data source. The following are the types: + +* link:#DatabaseLogin[DatabaseLogin] +* link:#EISLogin[EISLogin] + +Note that there is no XML login. EclipseLink XML projects are used for +nonpersistent, in-memory object to XML data transformation and +consequently there is no data source to log in to. For more information +about persistent and nonpersistent projects, see +link:Introduction%20to%20Projects_(ELUG)#Persistent_and_Nonpersistent_Projects[Persistent +and Nonpersistent Projects]. + +For additional information, see the following: + +* link:Introduction%20to%20Projects_(ELUG)#Projects_and_Login[Projects +and Login] +* link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Common_Data_Source_Login_Options[Configuring +Common Data Source Login Options] + +==== DatabaseLogin + +If you are creating a project that accesses a relational database, you +must configure the project with a `+DatabaseLogin+`. Your choice of +`+DatabasePlatform+` further customizes your project for a particular +type of database (see link:#Database_Platforms[Database Platforms]). + +For more information, see +link:Configuring%20a%20Database%20Login%20(ELUG)#Introduction_to_Database_Login_Configuration[Introduction +to Database Login Configuration]. + +==== EISLogin + +If you are creating a project that accesses a nonrelational data source +using a JCA adapter, you must configure the project with an +`+EISLogin+`. Your choice of `+EISPlatform+` further customizes your +project for a particular JCA adapter and specifies what record type +EclipseLink uses to exchange data with the EIS (see +link:#EIS_Platforms[EIS Platforms]). + +For more information, see +link:Configuring%20an%20EIS%20Login%20(ELUG)#Introduction_to_EIS_Login_Configuration[Introduction +to EIS Login Configuration]. + +=== Data Source Platform Types + +EclipseLink abstracts the details of your underlying data source using +data source platform classes. EclipseLink provides the following data +source platforms: + +* link:#Database_Platforms[Database Platforms] +* link:#EIS_Platforms[EIS Platforms] + +A data source platform is owned by your project’s `+Login+`. For more +information about logins, see link:#Data_Source_Login_Types[Data Source +Login Types]. + +To configure most platform options, you must use an amendment method +(see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]), or a `+preLogin+` event listener (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Managing_Session_Events_with_the_Session_Event_Manager[Managing +Session Events with the Session Event Manager]). + +==== Database Platforms + +EclipseLink interacts with databases using structured query language +(SQL). Because each database platform uses its own variation on the +basic SQL language, EclipseLink must adjust the SQL it uses to +communicate with the database to ensure that the application runs +smoothly. + +The type of database platform you choose determines the specific means +by which the EclipseLink runtime accesses the database, including the +type of Java Database Connectivity (JDBC) driver to use. JDBC is an +application programming interface (API) that gives Java applications +access to a database. EclipseLink relational projects rely on JDBC +connections to read objects from, and write objects to, the database. +EclipseLink applications use either individual JDBC connections or a +JDBC connection pool (see link:#Connection_Pools[Connection Pools]), +depending on the application architecture. + +EclipseLink provides a variety of database-specific platforms that let +you customize your project for your target database. + +Oracle Database platforms are located in +`+org.eclipse.persistence.platform.database.oracle+` package and include +the following: + +* `+OraclePlatform+` +* `+Oracle8Platform+` +* `+Oracle9Platform+` +* `+Oracle10Platform+` +* `+Oracle11Platform+` + +Non-Oracle Database platforms are located in +`+org.eclipse.persistence.platform.database+` package and include the +following: + +* `+AccessPlatform+` for Microsoft Access databases +* `+AttunityPlatform+` for Attunity Connect JDBC drivers +* `+CloudscapePlatform+` +* `+DB2MainframePlatform+` +* `+DB2Platform+` +* `+DBasePlatform+` +* `+DerbyPlatform+` +* `+HSQLPlatform+` +* `+InformixPlatform+` +* `+JavaDBPlatform+` +* `+MySQLPlatform+` +* `+PointBasePlatform+` +* `+PostgreSQLPlatform+` +* `+SQLAnyWherePlatform+` +* `+SQLServerPlatform+` +* `+SybasePlatform+` +* `+TimesTen7Platform+` for TimesTen 7 database + +Specify your database platform at the project level (see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Relational_Database_Platform_at_the_Project_Level[Configuring +Relational Database Platform at the Project Level]) for all sessions, or +override this project-level configuration at the session level (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_a_Relational_Database_Platform_at_the_Session_Level[Configuring +a Relational Database Platform at the Session Level]). + +If you set your database platform in Workbench, then Workbench manages +the database platform configuration for you automatically. + +==== EIS Platforms + +EclipseLink interacts with an EIS data source indirectly by way of a JCA +adapter. EclipseLink abstracts the details of an EIS data source using +the `+org.eclipse.persistence.eis.EISPlatform+` class. + +The type of EIS platform you choose determines the specific means by +which the EclipseLink runtime accesses the EIS, including the type of +JCA adapter to use. EclipseLink EIS projects rely on EIS connections to +read objects from, and write objects to, the EIS. EclipseLink +applications use individual EIS connections returned by the EIS +connection factory specified by the EIS platform. + +EclipseLink provides a variety of `+EISPlaform+` classes that let you +customize your project for your target EIS. + +EIS platforms for production are located in +`+org.eclipse.persistence.eis.adapters+` package and include the +following: + +* `+org.eclipse.persistence.eis.adapters.aq.AQPlatform+` to access an +EIS using Oracle Advanced Queuing messages. +* `+org.eclipse.persistence.eis.adapters.attunity.AttunityPlatform+` to +access an EIS using an Attunity JCA adapter. +* `+org.eclipse.persistence.eis.adapters.jms.JMSPlatform+` to access an +EIS using JMS messages. +* `+org.eclipse.persistence.eis.adapters.mqseries.MQPlatform+` to access +an EIS using IBM MQSeries messages. + +EIS platforms for testing are also located in +`+org.eclipse.persistence.eis.adapters+` and include the following: + +* `+org.eclipse.persistence.eis.adapters.blackbox.BlackBoxPlatform+` for +testing your EIS project with the Sun BlackBox reference adapter using +indexed records only. +* `+org.eclipse.persistence.eis.adapters.xmlfile.XMLFilePlatform+` for +testing your EIS project with an EIS emulated as one or more XML files +in the local file system using XML records. + +Specify your EIS platform at the session level (see +link:Configuring%20an%20EIS%20Login%20(ELUG)#Configuring_an_EIS_Data_Source_Platform_at_the_Session_Level[Configuring +an EIS Data Source Platform at the Session Level]). + +If you set your platform in Workbench, then Workbench manages the EIS +platform configuration for you automatically. + +=== Authentication + +*Authentication* is the means by which a data source validates a user’s +identity and determines whether or not the user has sufficient +privileges to perform a given action. + +For two-tier applications, simple JDBC authentication is usually +sufficient (see link:#Simple_JDBC_Authentication[Simple JDBC +Authentication]). + +For three-tier applications, you can use simple JDBC authentication or, +proxy authentication (see +link:#Oracle_Database_Proxy_Authentication[Oracle Database Proxy +Authentication]) when using the Oracle Call Interface (OCI) JDBC driver. + +Authentication plays a central role in data security and user +accountability and auditing (see link:#Auditing[Auditing]). + +==== Simple JDBC Authentication + +When you configure a EclipseLink database login with a user name and +password (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_User_Name_and_Password[Configuring +User Name and Password]), EclipseLink provides these credentials to the +JDBC driver that you configure your application to use (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Database_Login_Connection_Options[Configuring +Database Login Connection Options]). + +By default, EclipseLink writes passwords to and reads them from the +`+sessions.xml+` file in encrypted form using JCE encryption. +Optionally, you can configure a different encryption class (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Password_Encryption[Configuring +Password Encryption]). + +==== Oracle Database Proxy Authentication + +EclipseLink supports proxy authentication with the Oracle Database in +JSE applications and JEE applications using OC4J native or managed data +sources with Oracle JDBC driver release 10.1.0.2.0 or later and external +connection pools only (see link:#External_Connection_Pools[External +Connection Pools]). + +[width="100%",cols="<100%",] +|=== +|*Note:* EclipseLink does not support Oracle Database proxy +authentication with JTA. +|=== + +Oracle Database proxy authentication delivers the following security +benefits: + +* A limited trust model, by controlling the users on whose behalf middle +tiers can connect, and the roles the middle tiers can assume for the +user. +* Scalability, by supporting user sessions through Oracle Call Interface +(OCI) and thick JDBC, and eliminating the overhead of reauthenticating +clients. +* Accountability, by preserving the identity of the real user through to +the database, and enabling auditing of actions taken on behalf of the +real user. +* Flexibility, by supporting environments in which users are known to +the database, and in which users are merely "`application users`" of +which the database has no awareness. + +[width="100%",cols="<100%",] +|=== +|*Note:* Oracle Database supports proxy authentication in three-tiers +only; it does not support it across multiple middle tiers. +|=== + +For more information about authentication in an Oracle Database, see +"`Preserving User Identity in Multitiered Environments`" in the +_http://www.oracle.com/technology/documentation/index.html[Oracle +Database Security Guide]_. + +Configure your EclipseLink database login to use proxy authentication +(see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Oracle_Database_Proxy_Authentication[Configuring +Oracle Database Proxy Authentication]) to do the following: + +* address the complexities of authentication in a three-tier +architecture (such as client-to-middle-tier and middle-tier-to-database +authentication, and client reauthentication through the middle -tier to +the database); +* enhance database audit information (for even triggers and stored +procedures) by using a specific user for database operations, rather +than the generic pool user; +* simplify VPD/OLS configuration (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Isolated +Client Sessions and Oracle Virtual Private Database (VPD)]) by using a +proxy user, rather than setting user information directly in the session +context with stored procedures. + +==== Auditing + +Regardless of what type of authentication you choose, EclipseLink logs +the name of the user associated with all database operations. This +example shows the `+CONFIG+` level EclipseLink logs when a +`+ServerSession+` connects through the main connection for the sample +user "`scott`", and a `+ClientSession+` uses proxy connection "`jeff`". + +[#Example 92-1]## *_EclipseLink Logs with Oracle Database Proxy +Authentication_* + +`+[EclipseLink Config]--ServerSession(13)--Connection(14)--Thread(Thread[main,5,main])--connecting(DatabaseLogin( platform=>Oracle9Platform   user name=> "scott" connector=>OracleJDBC10_1_0_2ProxyConnector datasource name=>DS))+` +`+[EclipseLink Config]--ServerSession(13)--Connection(34)--Thread(Thread[main,5,main])--Connected: jdbc:oracle:thin:@localhost:1521:orcl+` +`+User: SCOTT+` +`+[EclipseLink Config]--ClientSession(53)--Connection(54)--Thread(Thread[main,5,main])--connecting(DatabaseLogin(platform=>Oracle9Platform user name=> "scott" connector=>OracleJDBC10_1_0_2ProxyConnector datasource name=>DS))+` +`+[EclipseLink Config]--ClientSession(53)--Connection(56)--Thread(Thread[main,5,main])--Connected: jdbc:oracle:thin:@localhost:1521:orcl+` +`+User: jeff+` + +For more information on configuring EclipseLink log level and log +options, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging]. + +Your database server likely provides additional user auditing options. +Consult your database server documentation for details. + +Alternatively, you may consider using the EclipseLink unit of work in +conjunction with your database schema for auditing purposes (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Implementing_User_and_Date_Auditing_with_the_Unit_of_Work[Implementing +User and Date Auditing with the Unit of Work]). + +=== Connections + +A connection is an object that provides access to a data source by way +of the driver you configure your application to use (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Database_Login_Connection_Options[Configuring +Database Login Connection Options]). Relational projects use JDBC to +connect to the data source; EIS and XML projects use JCA. EclipseLink +uses the interface +`+org.eclipse.persistence.internal.databaseaccess.Accessor+` to wrap +data source connections. This interface is accessible from certain +events (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Event_Manager[Descriptor +Event Manager]). + +Typically, when using a server session, EclipseLink uses a a different +connection for both reading and writing. This lets you use +nontransactional connections for reading and avoid maintaining +connections when not required. See +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Reading_Through_the_Write_Connection[Reading +Through the Write Connection] and +link:Configuring%20a%20Session%20(ELUG)#Exclusive_Write_Connections[Exclusive +Write Connections] for more information. + +By default, a EclipseLink server session acquires connections lazily: +that is, only during the commit operation of a unit of work. +Alternatively, you can configure EclipseLink to acquire a write +connections at the time you acquire a client sessions (see +link:Configuring%20a%20Session%20(ELUG)#Lazy_Connection_Acquisition[Lazy +Connection Acquisition]). + +Connections can be allocated from internal or external connection pools +(see link:#Connection_Pools[Connection Pools]). + +=== Connection Pools + +A *connection pool* is a service that creates and maintains a shared +collection (pool) of data source connections on behalf of one or more +clients. The connection pool provides a connection to a process on +request, and returns the connection to the pool when the process is +finished using it. When it is returned to the pool, the connection is +available for other processes. Because establishing a connection to a +data source can be time-consuming, reusing such connections in a +connection pool can improve performance. + +EclipseLink uses connection pools to manage and share the connections +used by server and client sessions. This feature reduces the number of +connections required and allows your application to support many +clients. + +You can configure your session to use internal connection pools provided +by EclipseLink or external connection pools provided by a JDBC driver or +Java EE container. + +You can use the following connection pools in your EclipseLink +application for a variety of purposes, such as reading, writing, +sequencing, and other application-specific functions: + +* link:#Internal_Connection_Pools[Internal Connection Pools] +* link:#External_Connection_Pools[External Connection Pools] +* link:#Default_(Write)_and_Read_Connection_Pools[Default (Write) and +Read Connection Pools] +* link:#Sequence_Connection_Pools[Sequence Connection Pools] +* link:#Application-Specific_Connection_Pools[Application-Specific +Connection Pools] + +==== Internal Connection Pools + +For non-Java EE applications, you typically use _internal_ connection +pools. By default, EclipseLink sessions use internal connection pools. + +Using internal connection pools, you can use Workbench to configure the +default (write) and read connection pools (see +link:#Default_(Write)_and_Read_Connection_Pools[Default (Write) and Read +Connection Pools]) and you can create additional connection pools for +object identity (see link:#Sequence_Connection_Pools[Sequence Connection +Pools]), or any other purpose (see +link:#Application-Specific_Connection_Pools[Application-Specific +Connection Pools]). + +Using internal connection pools, you can optimize the creation of read +connections for applications that read data only to display it and only +infrequently modify data (see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring_a_Nontransactional_Read_Login[Configuring +a Nontransactional Read Login]). + +For information on selecting the type of connection pool to use, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]. + +For more information on creating and configuring internal connection +pools, see the following: + +* link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Creation[Introduction +to the Internal Connection Pool Creation] +* link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Configuration[Introduction +to the Internal Connection Pool Configuration] + +==== External Connection Pools + +For Java EE applications, you typically use _external_ connection pools. + +If you are using an external transaction controller (JTA), you must use +external connection pools to integrate with the JTA (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]). + +Using external connection pools, you can use either Workbench or Java to +configure the default (write) and read connection pools (see +link:#Default_(Write)_and_Read_Connection_Pools[Default (Write) and Read +Connection Pools]) and create additional connection pools for object +identity (see link:#Sequence_Connection_Pools[Sequence Connection +Pools]), or any other purpose (see +link:#Application-Specific_Connection_Pools[Application-Specific +Connection Pools]). + +For more information on selecting the type of connection pool to use, +see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]. + +==== Default (Write) and Read Connection Pools + +A server session provides a read connection pool and a write connection +pool. These could be different pools, or if you use external connection +pooling, the same connection pool. + +All read queries use connections from the read connection pool and all +queries that write changes to the data source use connections from the +write connection pool. You can configure attributes of the default read +and write connection pools. + +Whenever a new connection is established, EclipseLink uses the +connection configuration you specify in your session’s +`+DatasourceLogin+`. Alternatively, when you use an external transaction +controller, you can define a separate connection configuration for a +read connection pool to avoid the additional overhead, if appropriate +(see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring_a_Nontransactional_Read_Login[Configuring +a Nontransactional Read Login]). + +For more information on configuring read and write connection pools, see +link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Configuration[Introduction +to the Internal Connection Pool Configuration]. + +==== Sequence Connection Pools + +An essential part of maintaining object identity (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity]) is sequencing–managing the assignment of +unique values to distinguish one instance from another. For more +information, see +link:Introduction%20to%20Projects_(ELUG)#Projects_and_Sequencing[Projects +and Sequencing]. + +Sequencing involves reading and writing a special sequence resource +maintained by your data source. + +By default, EclipseLink includes sequence operations in a separate +transaction. This avoids complications during the write transaction, +which may lead to deadlocks over the sequence resource. However, when +using an external transaction controller (such as a JTA data source or +connection pool), EclipseLink cannot use a different transaction for +sequencing. Use a sequence connection pool to configure a non-JTA +transaction pool for sequencing. This is required only for table +sequencing–not native sequencing. + +In each server session, you can create one connection pool, called a +sequence connection pool, that EclipseLink uses exclusively for +sequencing. With a sequence connection pool, EclipseLink satisfies a +request for a new object identifier outside of the transaction from +which the request originates. This allows EclipseLink to immediately +commit an update to the sequence resource, which avoids deadlocks. + +[width="100%",cols="<100%",] +|=== +|*Note*: If you use a sequence connection pool and the original +transaction fails, the sequence operation does not roll back. +|=== + +You should use a sequence connection pool, if the following applies: + +* You use table sequencing (that is, non-native sequencing). See +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing] and +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Unary_Table_Sequencing[Unary +Table Sequencing] for more information. +* You use external transaction controller (JTA). + +You should not use a sequence connection pool, if the following applies: + +* You do not use sequencing, or use the data source’s native sequencing +(see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] and +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform]). +* You have configured the sequence table to avoid deadlocks. +* You use non-JTA data sources. + +For more information, see the following: + +* link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Creation[Introduction +to the Internal Connection Pool Creation] +* link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Configuration[Introduction +to the Internal Connection Pool Configuration] + +==== Application-Specific Connection Pools + +When you use internal EclipseLink connection pools in a session, you can +create one or more connection pools that you can use for any application +purpose. These are called named connection pools, as you can give them +any name you want and use them for any purpose. + +Typically, use these named connection pools to provide pools of +different security levels. For example, the "`default`" connection pool +may only allow access to specific tables but the "`admin`" connection +pool may allow access to all tables. + +For more information, see the following: + +* link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Creation[Introduction +to the Internal Connection Pool Creation] +* link:Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction_to_the_Internal_Connection_Pool_Configuration[Introduction +to the Internal Connection Pool Configuration] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_a_Named_Connection_Pool[How +to Acquire a Client Session that Uses a Named Connection Pool] + +== Data Access API + +Consider the following types of inheritance hierarchy: + +* link:#Login_Inheritance_Hierarchy[Login Inheritance Hierarchy] +* link:#Platform_Inheritance_Hierarchy[Platform Inheritance Hierarchy] + +=== Login Inheritance Hierarchy + +This example illustrates the login types that are derived from the +abstract class `+org.eclipse.persistence.sessions.DatasourceLogin+`. + +[#Example 92-2]## *_Login Inheritance Hierarchy_* + +`+class org.eclipse.persistence.sessions.DatasourceLogin+` +`+    class org.eclipse.persistence.sessions.DatabaseLogin+` +`+    class org.eclipse.persistence.eis.EISLogin+` + +=== Platform Inheritance Hierarchy + +This example illustrates the platform type class hierarchy. + +[#Example 92-3]## *_Platform Inheritance Hierarchy_* + +`+org.eclipse.persistence.platform.database+` `+   AccessPlatform+` +`+   AttunityPlatform+` `+   CloudscapePlatform+` +`+   DatabasePlatform+` `+   DB2MainframePlatform+` `+   DB2Platform+` +`+   DBasePlatform+` `+   DerbyPlatform+` `+   HSQLPlatform+` +`+   InformixPlatform+` `+   JavaDBPlatform+` `+   PointBasePlatform+` +`+   PostgreSQLPlatform+` `+   SQLAnyWherePlatform+` +`+   SQLServerPlatform+` `+   SybasePlatform+` `+   TimesTen7Platform+` +`+org.eclipse.persistence.platform.database.oracle+` +`+   Oracle8Platform+` `+   Oracle9Platform+` `+   OraclePlatform+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..be30144052b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Descriptors_(ELUG).adoc @@ -0,0 +1,1033 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_Descriptors_(ELUG)[Related +Topics] + +EclipseLink uses descriptors to store the information that describes how +an instance of a particular class can be represented by a data source. +Descriptors own mappings that associate class instance variables with a +data source and transformation routines that are used to store and +retrieve values. As such, the descriptor acts as the connection between +a Java object and its data source representation. + +== Descriptor Types + +This table lists the descriptor types you use to describe the classes in +your object model and how to create each type. + +[#Table 14-1]## + +Descriptor Type + +Description + +EclipseLink Workbench + +Java + +Relational + +Describes Java objects that you map to tables in a relational database. +Applicable to all relational databases that EclipseLink supports. + +Object-relational + +Describes Java objects that you map to tables in a relational database +that provides special database data types that correspond more closely +to object types. Applicable only to the relational databases that +EclipseLink supports that provide these special data types. + +EIS + +Describes Java objects that you map to an EIS data source by way of a +JCA adapter. + +XML + +Describes Java objects that you map, in memory, to complex types in XML +documents defined by an XML schema document (XSD). + +For more information, see the following: + +* link:Creating%20a%20Descriptor%20(ELUG)[Creating a Descriptor] +* link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +== Descriptor Concepts + +This section introduces descriptor concepts unique to EclipseLink, +including the following: + +* link:#Descriptor_Architecture[Descriptor Architecture] +* link:#Descriptors_and_Inheritance[Descriptors and Inheritance] +* link:#Fetch_Groups[Fetch Groups] +* link:#Descriptors_and_Aggregation[Descriptors and Aggregation] +* link:#Descriptor_Customization[Descriptor Customization] +* link:#Amendment_and_After-Load_Methods[Amendment and After-Load +Methods] +* link:#Descriptor_Event_Manager[Descriptor Event Manager] +* link:#Descriptor_Query_Manager[Descriptor Query Manager] +* link:#Descriptors_and_Sequencing[Descriptors and Sequencing] +* link:#Descriptors_and_Locking[Descriptors and Locking] +* link:#Default_Root_Element[Default Root Element] + +=== Descriptor Architecture + +A *descriptor* stores all the information describing how an instance of +a particular object class can be represented in a data source. + +EclipseLink descriptors contain the following information: + +* The persistent Java class it describes and the corresponding data +source (database tables, XML complex type, or EIS interaction) +* A collection of mappings, which describe how the attributes and +relationships for that class are stored in the database +* The primary key information (or equivalent) of the data source +* A list of query keys (or aliases) for field names +* Information for sequence numbers +* A set of optional properties for tailoring the behavior of the +descriptor, including support for caching refresh options, identity +maps, optimistic locking, the event manager, and the query manager + +There is a descriptor type for each data source type that EclipseLink +supports. In some cases, multiple descriptor types are valid for the +same data source type. The type of descriptor you use determines the +type of mappings that you can define. + +This table summarizes the relationship between project, descriptor, and +mappings. + +[#Table 14-2]## *_Project, Descriptor, and Mapping Support_* + +[width="100%",cols="<17%,<42%,<41%",options="header",] +|=== +|*Project* |*Descriptor* |*Mapping* +|link:Introduction%20to%20Relational%20Projects%20(ELUG)[Relational +Projects] +|link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Relational +Descriptors] and +link:Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)[Object-Relational +Data Type Descriptors] +|link:Introduction%20to%20Mappings%20(ELUG)#Relational_Mappings[Relational +Mappings] and +link:Introduction%20to%20Mappings%20(ELUG)#Object-Relational_Data_Type_Mappings[Object-Relational +Data Type Mappings] + +|link:Introduction%20to%20EIS%20Projects%20(ELUG)[EIS Projects] +|link:Introduction%20to%20EIS%20Descriptors%20(ELUG)[EIS Descriptor +Concepts] |link:Introduction%20to%20Mappings%20(ELUG)#EIS_Mappings[EIS +Mappings] + +|link:Introduction%20to%20XML%20Projects%20(ELUG)[XML Projects] +|link:Introduction%20to%20XML%20Descriptors%20(ELUG)[XML Descriptor +Concepts] |link:Introduction%20to%20Mappings%20(ELUG)#XML_Mappings[XML +Mappings] +|=== + +=== Descriptors and Inheritance + +*Inheritance* describes how a derived (child) class inherits the +characteristics of its superclass (parent). You can use descriptors to +describe the inheritance relationships between classes in relational, +EIS, and XML projects. + +In the descriptor for a child class, you can override mappings that have +been specified in the descriptor for a parent class, or map attributes +that have not been mapped at all in the parent class descriptor. + +For more information, see link:#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +=== Fetch Groups + +By default, when you execute an object-level read query for a particular +object class, EclipseLink returns all the persistent attributes mapped +in the object’s descriptor. With this single query, all the object’s +persistent attributes are defined, and calling their `+get+` methods +returns the value directly from the object. + +When you are interested in only some of the attributes of an object, it +may be more efficient to return only a subset of the object’s attributes +using a fetch group with which you can define a subset of an object’s +attributes and associate the fetch group with either a +`+ReadObjectQuery+` or `+ReadAllQuery+` query. + +For more information, see the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Fetch_Groups[Configuring +Fetch Groups] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Fetch_Groups_and_Object-Level_Read_Queries[Fetch +Groups and Object-Level Read Queries] + +=== Descriptors and Aggregation + +Two objects – a source (parent or owning) object and a target (child or +owned) object – are related by aggregation if there is a strict +one-to-one relationship between them, and all the attributes of the +target object can be retrieved from the same data source representation +as the source object. This means that if the source object exists, then +the target object must also exist, and if the source object is +destroyed, then the target object is also destroyed. + +In this case, the descriptors for the source and target objects must be +designated to reflect this relationship. + +In EJB 3.0, an aggregate is known as an embeddable. In the EJB 3.0 +specification, an embeddable may not contain another embeddable (that +is, the EJB 3.0 specification does not support nested aggregates). + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Descriptors%20(ELUG)#Aggregate_and_Composite_Descriptors_in_Relational_Projects[Aggregate +and Composite Descriptors in Relational Projects] +* link:Introduction%20to%20EIS%20Descriptors%20(ELUG)#EIS_Descriptors_and_Aggregation[EIS +Descriptors and Aggregation] +* link:Introduction%20to%20XML%20Descriptors%20(ELUG)#Composite_Descriptors_in_XML_Projects[Composite +Descriptors in XML Projects] + +=== Descriptor Customization + +You can customize a descriptor at run time by specifying a descriptor +customizer – a Java class that implements the +`+org.eclipse.persistence.sessions.factories.DescriptorCustomizer+` +interface and provides a default (zero-argument) constructor. + +You use a descriptor customizer to customize a descriptor at run time +through code API similar to how you use an amendment method to customize +a descriptor (see link:#Amendment_and_After-Load_Methods[Amendment and +After-Load Methods]). + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Descriptor_Customizer_Class[Configuring +a Descriptor Customizer Class]. + +=== Amendment and After-Load Methods + +Using Workbench, you can associate a static Java method that is called +when a descriptor is loaded at run time. This method can amend the +run-time descriptor instance through the descriptor Java code API. Use +this method to make some advanced configuration options that may not be +currently supported by Workbench. + +You can only modify descriptors before the session has been connected; +you should not modify descriptors after the session has been connected. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Amendment +Methods]. + +=== Descriptor Event Manager + +In relational and EIS projects, EclipseLink raises various instances of +`+DescriptorEvent+` (see the +link:Configuring%20a%20Descriptor%20(ELUG)#Table_115-25[Descriptor +Events] and +link:Configuring%20a%20Descriptor%20(ELUG)#Table_115-27[Descriptor +Events] tables) during the persistence life cycle. Each descriptor owns +an instance of `+DescriptorEventManager+` that is responsible for +receiving these events and dispatching them to the descriptor event +handlers registered with it. + +Using a descriptor event handler, you can execute your own application +specific logic whenever descriptor events occur, allowing you to take +customized action at various points in the persistence life-cycle. For +example, using a descriptor event handler, you can do the following: + +* Synchronize persistent objects with other systems, services, and +frameworks. Maintain nonpersistent attributes of which EclipseLink is +not aware. +* Notify other objects in the application when the persistent state of +an object changes. +* Implement complex mappings or optimizations not directly supported by +EclipseLink mappings. + +For more information, see the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Domain_Object_Method_as_an_Event_Handler[Configuring +a Domain Object Method as an Event Handler] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Descriptor_Event_Listener_as_an_Event_Handler[Configuring +a Descriptor Event Listener as an Event Handler] + +=== Descriptor Query Manager + +Each relational and EIS descriptor provides an instance of +`+DescriptorQueryManager+` that you can use to configure the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Queries_at_the_Descriptor_Level[named +queries] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Configure_Default_Query_Implementations[custom +default queries for basic persistence operations] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Configure_Additional_Join_Expressions[additional +join expressions] + +For more information on using the query manager, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Descriptor_Query_Manager_Queries[Descriptor +Query Manager Queries]. + +=== Descriptors and Sequencing + +An essential part of maintaining object identity is managing the +assignment of unique values (that is, a specific sequence) to +distinguish one object instance from another. For more information, see +link:Introduction%20to%20Projects_(ELUG)#Projects_and_Sequencing[Projects +and Sequencing]. + +Sequencing options you configure at the project (or session) level +determine the type of sequencing that EclipseLink uses. In a POJO +project, you can use session-level sequence configuration to override +project-level sequence configuration, on a session-by-session basis, if +required (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]). + +After configuring the sequence type, for each descriptor’s reference +class, you must associate one attribute, typically the attribute used as +the primary key (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[Configuring +Primary Keys]), with its own sequence (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]). + +=== Descriptors and Locking + +You can configure a descriptor with any of the following locking +policies to control concurrent access to a domain object: + +* Optimistic – All users have read access to the data. When a user +attempts to make a change, the application checks to ensure the data has +not changed since the user read the data (see +link:#Optimistic_Version_Locking_Policies[Optimistic Version Locking +Policies] and link:#Optimistic_Field_Locking_Policies[Optimistic Field +Locking Policies]). +* Pessimistic – The first user who accesses the data with the purpose of +updating it locks the data until completing the update (see +link:#Pessimistic_Locking_Policy[Pessimistic Locking Policy]). +* No locking – The application does not prevent users overwriting each +other’s changes. + +We recommend using optimistic locking for most types of applications to +ensure that users do not overwrite each other’s changes. + +For more information, see the following: + +* link:#Descriptors_and_Locking[Descriptors and Locking] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy] + +=== Default Root Element + +You configure EIS root descriptors ( +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Default_Root_Element[Configuring +Default Root Element]) and XML descriptors ( +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_Default_Root_Element[Configuring +Default Root Element]) with a default root element so that the +EclipseLink runtime knows the data source data type associated with the +class the descriptor describes. + +[width="100%",cols="<100%",] +|=== +|*Note:* The undefined document root element of a referenced object is +ignored during marshalling with an any collection mapping and object +mapping. +|=== + +This section describes what a default root element is and how +EclipseLink uses it. + +Consider the `+Customer+` and `+Address+` classes and their mappings, +shown in this example: + +[#Example 14-1]## *_Customer and Address Classes_* + +*`+Class:+`*`+ Customer+` + +*`+Default Root:+`*`+ customer+` *`+Attributes and Mappings:+`* +`+    name:String                Drect Mapping to                name/text()+` +`+    billingAddress:Address     Composite Object Mapping to     billing-address+` +`+    shippingAddress:Address    Composite Object Mapping to     shipping-address+` + +*`+Class:+`*`+ Address+` *`+Default Root:+`*`+ address+` +*`+Attributes and Mappings:+`* +`+    street:String              Direct Mapping to               street/text()+` +`+    city:String                Direct Mapping to               city/text()+` + +These classes correspond to the XML schema, shown in this example. + +[#Example 14-2]## *_Customer and Address Schema_* + +`+    +` `+        +` + +`+            +` `+            +` `+        +` `+    +` `+    +` +`+    +` + +`+        +` `+            +` `+            +` `+            +` +`+        +` `+    +` + +When an instance of the `+Customer+` class is persisted to XML, the +EclipseLink runtime performs the following: + +[arabic] +. Gets the default root element.The `+Customer+` class instance +corresponds to the root of the XML document. The EclipseLink runtime +uses the default root element specified on the descriptor (`+customer+`) +to start the XML document. EclipseLink then uses the mappings on the +descriptor to marshal the object’s attributes: ++ +`+    +``+…+` +. When the EclipseLink runtime encounters an object attribute such as +`+billingAddress+`, it checks the mapping associated with it to +determine with what element (`+billing-address+`) to continue: ++ +`+    +``+…+` `+    +` ++ +The EclipseLink runtime checks the mapping’s reference descriptor +(`+Address+`) to determine what attributes to persist: ++ +`+    +``+…+` `+    +` `+        +``+…+` `+        +``+…+` + +`+    +` + +== Descriptors and Inheritance + +Inheritance describes how a derived class inherits the characteristics +of its superclass. You can use descriptors to describe the inheritance +relationships between classes in relational, EIS, and XML projects. + +The link:#Figure_14-1[Example Inheritance Hierarchy] figure illustrates +the `+Vehicle+` object model – a typical Java inheritance hierarchy. The +root class `+Vehicle+` contains two branch classes: `+FueledVehicle+` +and `+NonFueledVehicle+`. Each branch class contains a leaf class: +`+Car+` and `+Bicycle+`, respectively. + +[#Figure 14-1]## *_Example Inheritance Hierarchy_* + +.Example Inheritance Hierarchy +image::javainhr.gif[Example Inheritance +Hierarchy,title="Example Inheritance Hierarchy"] + +EclipseLink recognizes the following three types of classes in an +inheritance hierarchy: + +[arabic] +. The root class stores information about _all_ instantiable classes in +its subclass hierarchy. By default, queries performed on the root class +return instances of the root class and its instantiable subclasses. +However, the root class can be configured so queries on it return only +instances of itself, without instances of its subclasses. For example, +the `+Vehicle+` class in the link:#Figure_14-1[Example Inheritance +Hierarchy] figure is a root class. +. Branch classes have a persistent superclass and also have subclasses. +By default, queries performed on the branch class return instances of +the branch class and any of its subclasses. However, as with the root +class, the branch class can be configured so queries on it return only +instances of itself without instances of its subclasses. For example, +the `+FueledVehicle+` class in the link:#Figure_14-1[Example Inheritance +Hierarchy] figure is a branch class. +. Leaf classes have a persistent superclass in the hierarchy but do not +have subclasses. Queries performed on the leaf class can only return +instances of the leaf class. For example, the `+Car+` class in the +link:#Figure_14-1[Example Inheritance Hierarchy] figure is a leaf class. + +In the descriptor for a child class, you can override mappings that have +been specified in the descriptor for a parent class, or map attributes +that have not been mapped at all in the parent class descriptor. + +This section includes information on the following topics: + +* link:#How_to_Specify_a_Class_Indicator[How to Specify a Class +Indicator] +* link:#Inheritance_and_Primary_Keys[Inheritance and Primary Keys] +* link:#Single_and_Multi-Table_Inheritance[Single and Multi-Table +Inheritance] +* link:#Aggregate_and_Composite_Descriptors_and_Inheritance[Aggregate +and Composite Descriptors and Inheritance] + +For more information about configuring inheritance for a parent (root) +class descriptor, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Inheritance for a +Parent (Root) Descriptor]. + +For more information about configuring inheritance for a child (branch +or leaf) class descriptor, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor]. + +=== How to Specify a Class Indicator + +When configuring inheritance, you configure the root class descriptor +with the means of determining which subclasses it should instantiate. + +You can do this in one of the following ways: + +* link:#Using_Class_Indicator_Fields[Using Class Indicator Fields] +* link:#Using_Class_Extraction_Methods[Using Class Extraction Methods] + +[width="100%",cols="<100%",] +|=== +|*Note*: All leaf classes in the hierarchy must have a class indicator +and they must have the same type of class indicator (field or class +extraction method). +|=== + +==== Using Class Indicator Fields + +You can use a persistent attribute of a class to indicate which subclass +should be instantiated. For example, in a relational descriptor, you can +use a class indicator field in the root class table. The indicator field +should not have an associated direct mapping unless it is set to +read-only. + +[width="100%",cols="<100%",] +|=== +|*Note*: If the indicator field is part of the primary key, define a +write-only transformation mapping for the indicator field (see +link:Configuring%20a%20Relational%20Transformation%20Mapping%20(ELUG)#Configuring_a_Relational_Transformation_Mapping[Configuring +a Relational Transformation Mapping]). +|=== + +You can use strings or numbers as values in the class indicator field. + +The root class descriptor must specify how the value in the class +indicator field translates into the class to be instantiated. + +One approach is to configure the root class descriptor with a class +indicator dictionary: a collection of key-values that associates a +simple key, stored in the class indicator field, with a class to +instantiate. The link:#Table_14-3[Class Indicator Dictionary for the +Vehicle Class] table illustrates the class indicator dictionary for the +`+Vehicle+` class’ subclasses, as shown in the link:#Figure_14-1[Example +Inheritance Hierarchy] figure. + +[#Table 14-3]## *_Class Indicator Dictionary for the Vehicle Class_* + +[cols="<,<",options="header",] +|=== +|*Key* |*Value* +|*F* |FueledVehicle +|*N* |NonFueledVehicle +|*C* |Car +|*B* |Bicycle +|=== + +Another approach is to simply use the class name itself as the value +stored in the class indicator field. This avoids having to define unique +indicators for each class at the expense of a slightly larger key value +(depending on the length of your class names). + +==== Using Class Extraction Methods + +You can define a Java method to compute the class indicator based on any +available information in the object’s data source record. Such a method +is called a class extraction method. + +Using a class extraction method, you do not need to include an explicit +class indicator field in your data model and you can handle +relationships that are too complex to describe using class indicator +fields. + +A class extraction method must have the following characteristics: + +* it must be defined on the root descriptor’s class; +* it must be static; +* it must take a `+Record+` as an argument; +* it must return the `+java.lang.Class+` object to use for the +`+Record+` passed in. + +You may also need to define only-instances and with-all-subclasses +expressions (see +link:#Specifying_Expressions_for_Only-Instances_and_With-All-Subclasses[Specifying +Expressions for Only-Instances and With-All-Subclasses]). + +For example, the link:#Table_14-4[EMPLOYEE Table] lists the rows in the +`+EMPLOYEE+` table. The `+Employee+` class is the base class. +`+Director+`, `+Manager+`, `+Programmer+`, and `+TechWriter+` classes +each derive from the `+Employee+` class. However, in your application, +instances of `+Manager+`, `+Programmer+`, and `+TechWriter+` classes +must be represented as `+Employee+` instances and instances of +`+Director+` must be represented as `+Director+` instances. Because +there is no a one-to-one correspondence between class and `+JOB_TYPE+` +field value, the `+JOB_TYPE+` field alone cannot serve as a class +indicator field (see link:#Using_Class_Indicator_Fields[Using Class +Indicator Fields]). To resolve this issue, you could use the class +extraction method, shown in the link:#Example_14-3[Class Extraction +Method] example. + +[#Table 14-4]## *_EMPLOYEE Table_* + +[cols="<,<,<,<",options="header",] +|=== +|*ID* |*NAME* |*JOB_TYPE* |*JOB_TITLE* +|732 |Bob Jones |1 |Manager +|733 |Sarah Smith |3 |Technical Writer +|734 |Ben Ng |2 |Director +|735 |Sally Johnson |3 |Programmer +|=== + +[#Example 14-3]## *_Class Extraction Method_* + +`+...+` +*`+//\'\' \'\'If\'\' \'\'the\'\' \'\'JOB_TYPE\'\' \'\'field\'\' \'\'value\'\' \'\'in\'\' \'\'record\'\' \'\'equals\'\' \'\'2,\'\' \'\'return\'\' \'\'the\'\' \'\'Director\'\' \'\'class.+`* +*`+//\'\' \'\'Return\'\' \'\'the\'\' \'\'Employee\'\' \'\'class\'\' \'\'for\'\' \'\'all\'\' \'\'other\'\' \'\'JOB_TYPE\'\' \'\'field\'\' \'\'values+`* + +`+public static Class getClassFromRecord(Record record) {+` +`+    if (record.get("JOB_TYPE").equals(new Integer(2)) {+` +`+        return Director.class;+` `+    }+` `+    else {+` +`+        return Employee.class;+` `+    }+` `+}+` + +When configuring inheritance using a class extraction method, +EclipseLink does not generate SQL for queries on the root class. + +===== Specifying Expressions for Only-Instances and With-All-Subclasses + +If you use a class extraction method (see +link:#Using_Class_Extraction_MethodsUsing_Class_Extraction_Methods[Using +Class Extraction MethodsUsing Class Extraction Methods]), you must +provide EclipseLink with expressions to correctly filter sibling +instances for all classes that share a common table (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_Expressions_for_a_Parent_(Root)_Class_Descriptor[Configuring +Inheritance Expressions for a Parent (Root) Class Descriptor]). + +=== Inheritance and Primary Keys + +For relational and EIS projects, EclipseLink assumes that all of the +classes in an inheritance hierarchy have the same primary key, as set in +the root descriptor. + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Descriptors%20(ELUG)#Inheritance_and_Primary_Keys_in_Relational_Projects[Inheritance +and Primary Keys in Relational Projects] +* link:Introduction%20to%20EIS%20Descriptors%20(ELUG)#Inheritance_and_Primary_Keys_in_EIS_Projects[Inheritance +and Primary Keys in EIS Projects] + +=== Single and Multi-Table Inheritance + +In a relational project, you can map your inheritance hierarchy to a +single table (see +link:Introduction_to_Relational_Descriptors_(ELUG)#Single-Table_Inheritance[Single-Table +Inheritance]) or to multiple tables (see +link:Introduction_to_Relational_Descriptors_(ELUG)#Multi-Table_Inheritance[Multi-Table +Inheritance]). + +=== Aggregate and Composite Descriptors and Inheritance + +You can designate relational descriptors as aggregates, and EIS +descriptors as composites. XML descriptors are always composites (see +link:Introduction%20to%20XML%20Descriptors%20(ELUG)#XML_Descriptors_and_Aggregation[XML +Descriptors and Aggregation]). + +When configuring inheritance for a relational aggregate descriptor, all +the descriptors in the inheritance tree must be aggregates. The +descriptors for aggregate and non-aggregate classes cannot exist in the +same inheritance tree. + +Similarly, when configuring inheritance for an EIS composite descriptor, +all the descriptors in the inheritance tree must be composites. The +descriptors for composite and noncomposite classes cannot exist in the +same inheritance tree. + +When configuring inheritance for an XML descriptor, because all XML +descriptors are composites, descriptor type does not restrict +inheritance. + +== Descriptors and Locking + +This section describes the various types of locking policy that +EclipseLink supports, including the following: + +* link:#Optimistic_Version_Locking_Policies[Optimistic Version Locking +Policies] +* link:#Optimistic_Version_Locking_Policies_and_Cascading[Optimistic +Version Locking Policies and Cascading] +* link:#Optimistic_Locking_and_Rollbacks[Optimistic Locking and +Rollbacks] +* link:#Optimistic_Field_Locking_Policies[Optimistic Field Locking +Policies] +* link:#Pessimistic_Locking_Policy[Pessimistic Locking Policy] +* link:#Locking_in_a_Three-Tier_Application[Locking in a Three-Tier +Application] + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +=== Optimistic Version Locking Policies + +With optimistic locking, all users have read access to the data. When a +user attempts to make a change, the application checks to ensure the +data has not changed since the user read the data. + +Optimistic version locking policies enforce optimistic locking by using +a version field (also known as a write-lock field) that you provide in +the reference class that EclipseLink updates each time an object change +is committed. + +EclipseLink caches the value of this version field as it reads an object +from the data source. When the client attempts to write the object, +EclipseLink compares the cached version value with the current version +value in the data source in the following way: + +* If the values are the same, EclipseLink updates the version field in +the object and commits the changes to the data source. +* If the values are different, the write operation is disallowed because +another client must have updated the object since this client initially +read it. + +EclipseLink provides the following version-based optimistic locking +policies: + +* `+VersionLockingPolicy+`: requires a _numeric_ version field; +EclipseLink updates the version field by incrementing its value by one. +* `+TimestampLockingPolicy+`: requires a _timestamp_ version field; +EclipseLink updates the version field by inserting a new timestamp (this +policy can be configured to get the time from the data source or +locally; by default, the policy gets the time from the data source). + +Note: In general, we recommend numeric version locking because of the +following: + +accessing the timestamp from the data source can have a negative impact +on performance; + +time stamp locking is limited to the precision that the database stores +for timestamps. + +Whenever any update fails because optimistic locking has been violated, +EclipseLink throws an `+OptimisticLockException+`. This should be +handled by the application when performing any database modification. +The application must notify the client of the locking contention, +refresh the object, and have the client reapply its changes. + +You can choose to store the version value in the object as a mapped +attribute, or in the cache. In three-tier applications, you typically +store the version value in the object to ensure it is passed to the +client when updated (see +link:#Locking_in_a_Three-Tier_Application[Locking in a Three-Tier +Application]). + +If you store the version value in the cache, you do not need to map it. +If you do map the version field, you must configure the mapping as +read-only (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Read-Only_Mappings[Configuring +Read-Only Mappings]). + +To ensure that the parent object’s version field is updated whenever a +privately owned child object is modified, consider +link:#Optimistic_Version_Locking_Policies_and_Cascading[Optimistic +Version Locking Policies and Cascading]. + +When using optimistic version locking with the unit of work, consider +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Optimistic_Read_Locking_with_the_forceUpdateToVersionField_Method[Using +Optimistic Read Locking with the forceUpdateToVersionField Method]. + +If you are using a stored procedure to update or delete an object, your +database may not return the row-count required to detect an optimistic +lock failure, so your stored procedure is responsible for checking the +optimistic lock version and throwing an error if they do not match. Only +version locking is directly supported with a `+StoredProcedureCall+`. +Because timestamp and field locking require two versions of the same +field to be passed to the call, an SQL call that uses an `+##+` +parameter to access the translation row could be used for other locking +policies. For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)[Using a StoredProcedureCall] +and +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_StoredFunctionCall[Using +a StoredFunctionCall]. + +=== Optimistic Version Locking Policies and Cascading + +If your database schema is such that both a parent object and its +privately owned child object are stored in the same table, then if you +update the child object, the parent object’s version field will be +updated. + +However, if the parent and its privately owned child are stored in +separate tables, then changing the child will not, by default, update +the parent’s version field. + +To ensure that the parent object’s version field is updated in this +case, you can either manually update the parent object’s version field +(see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Optimistic_Read_Locking_with_the_forceUpdateToVersionField_Method[Using +Optimistic Read Locking with the forceUpdateToVersionField Method]) or, +if you are using a `+VersionLockingPolicy+`, you can configure +EclipseLink to automatically cascade the child object’s version field +update to the parent (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Optimistic_Locking_Policy_Cascading[Configuring +Optimistic Locking Policy Cascading]). + +After you enable optimistic version locking cascading, when a privately +owned child object is modified, EclipseLink will traverse the privately +owned foreign reference mappings, updating all the parent objects back +to the root. + +Optimistic version locking cascading is only applied if the child object +is registered in a unit of work. + +EclipseLink supports optimistic version locking cascading for: + +* object changes in privately owned one-to-one and one-to-many mappings +* relationship changes (adding or removing) in the following collection +mappings (privately owned or not): +** direct collection +** one-to-many +** many-to-many +** aggregate collection + +Consider the example object graph shown in this figure: + +[#Figure 14-2]## *_Optimistic Version Locking Policies and Cascading +Example_* + +.Optimistic Version Locking Policies and Cascading Example +image::oplckcas.gif[Optimistic Version Locking Policies and Cascading +Example,title="Optimistic Version Locking Policies and Cascading Example"] + +In this example, `+ObjectA+` privately owns `+ObjectB+`, and `+ObjectB+` +privately owns `+ObjectC+`, and `+ObjectC+` privately owns `+ObjectD+`. + +Suppose you register `+ObjectB+` in a unit of work, modify an +`+ObjectB+` field, and commit the unit of work. In this case, +`+ObjectB+` checks the cache for `+ObjectA+` and, if not present, +queries the database for `+ObjectA+`. `+ObjectB+` then notifies +`+ObjectA+` of its change. `+ObjectA+` forces an update on its version +optimistic locking field even though it has no changes to its +corresponding table. + +Suppose you register `+ObjectA+` in a unit of work, access its +`+ObjectB+` to access its `+ObjectC+` to access its `+ObjectD+`, modify +an `+ObjectD+` field, and commit the unit of work. In this case, +`+ObjectD+` notifies `+ObjectC+` of its changes. `+ObjectC+` forces an +update on its version optimistic locking field even though it has no +changes to its corresponding table. `+ObjectC+` then notifies +`+ObjectB+` of the `+ObjectD+` change. `+ObjectB+` then notifies +`+ObjectA+` of the `+ObjectD+` change. `+ObjectA+` forces an update on +its version optimistic locking field even though it has no changes to +its corresponding table. + +=== Optimistic Locking and Rollbacks + +With optimistic locking, use the `+UnitOfWork+` method +`+commitAndResumeOnFailure+` (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Resuming_a_Unit_of_Work_After_Commit[Resuming +a Unit of Work After Commit]) to rollback a locked object’s value, if +you store the optimistic lock versions in the cache. + +If you store the locked versions in an object, you must refresh the +objects (or their versions) on a failure. Alternatively, you can acquire +a new unit of work on the failure and reapply any changes into the new +unit of work. + +=== Optimistic Field Locking Policies + +Optimistic field locking policies enforce optimistic locking by using +one or more of the fields that currently exist in the table to determine +if the object has changed since the client read the object. + +The unit of work caches the original state of the object when you first +read the object or register it with the unit of work. At commit time, +the unit of work compares the original values of the lock fields with +their current values on the data source during the update. If any of the +lock field’s values have changed, an optimistic lock exception is +thrown. + +EclipseLink provides the following optimistic field locking policies: + +* `+AllFieldsLockingPolicy+`: For update and delete operations, +EclipseLink compares all the fields of the object with all the fields in +the data source. If the original value of any fields differ from that in +the data source, the write operation is disallowed.For example, if you +changed a customer’s last name, EclipseLink might produce SQL like: + +`+UPDATE CUSTOMER SET LNAME='new last name' WHERE ID=7 AND LNAME='old last name' AND FNAME='Donald' +` +`+AND B_DAY='1972' AND CREDIT_RATING='A+' AND EYE_COLOR='Blue'+` + +The main disadvantage of this field locking policy is that it is not the +most efficient, especially if the changed object has many attributes. + +[width="100%",cols="<100%",] +|=== +|*Note*: This comparison is only on a per table basis. If an update +operation is performed on an object that is mapped to multiple tables +(multiple table inheritance), then only the changed fields for each +table changed appear in the `+where+` clause. +|=== + +* `+ChangedFieldsLockingPolicy+`: For update operations, EclipseLink +compares only the fields of the object that have changed with the +corresponding fields in the data source. If the original value of any +such field differs from that in the data source, the write operation is +disallowed. EclipseLink does not make any field comparisons for +deletes.The main advantage of this field locking policy is that it +allows concurrent updates of different fields. For example, if one +thread updates a customer’s last name and another thread updates the +same customer’s credit rating, and you configure the `+Customer+` +descriptor with `+ChangedFieldsLockingPolicy+`, then EclipseLink might +produce SQL like: + +*`+//\'\' \'\'Unit\'\' \'\'of\'\' \'\'work\'\' \'\'1+`* +`+UPDATE CUSTOMER SET LNAME='new name' WHERE ID=7 AND LNAME='old name'+` +*`+//\'\' \'\'Unit\'\' \'\'of\'\' \'\'work\'\' \'\'2+`* +`+UPDATE CUSTOMER SET CREDIT_RATING='B' WHERE ID=7 AND CREDIT_RATING='A+'+` + +* `+SelectedFieldsLockingPolicy+`: For update and delete operations, +EclipseLink compares only the selected fields of the object with the +corresponding fields in the data source. If the cached value of any such +field differs from that in the data source, the write operation is +disallowed.For example, if you select `+Customer+` attributes `+LNAME+` +and `+CREDIT_RATING+`, then at run time, EclipseLink might produce SQL +like: + +`+UPDATE CUSTOMER SET LNAME='new name' WHERE ID=7 AND LNAME='old name' AND CREDIT_RATING='A+'+` + +Whenever any update fails because optimistic locking has been violated, +EclipseLink throws an `+OptimisticLockException+`. This should be +handled by the application when performing any database modification. +The application must notify the client of the locking contention, +refresh the object, and have the client reapply its changes. + +When using field locking policies, a unit of work must be employed for +updating the data source. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use an instance of `+FieldsLockingPolicy+` if you +are using `+AttributeChangeTrackingPolicy+` (see +link:Introduction_to_EclipseLink_Transactions_(ELUG)#Attribute_Change_Tracking_Policy[Attribute +Change Tracking Policy]). +|=== + +=== Pessimistic Locking Policy + +With pessimistic locking, the first user who accesses the data with the +purpose of updating it locks the data until completing the update. + +When using a pessimistic locking policy, you can configure the policy to +either fail immediately or to wait until the read lock is acquired. + +You can also use pessimistic locking (but not a pessimistic locking +policy) at the query level (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]). + +EclipseLink provides an optimization for pessimistic locking when this +locking is used with entity beans with container-managed persistence: if +you set your query to pessimistic locking and run the query in its own +new transaction (which will end after the execution of the finder), then +EclipseLink overrides the locking setting and does not append +`+FOR UPDATE+` to the SQL. However, the use of this optimization may +produce an undesirable result if the pessimistic lock query has been +customized by the user with a SQL string that includes FOR UPDATE. In +this case, if the conditions for the optimization are present, the query +will be reset to nonpessimistic locking, but the SQL will remain the +same resulting in the locking setting of the query conflicting with the +query’s SQL string. To avoid this problem, you can take one of the +following two approaches: + +* Use an EclipseLink expression (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#CJAGGAGJ[Introduction +to EclipseLink Expressions]) for the selection criteria. This will give +EclipseLink control over the SQL generation. +* Place the finder in a transaction to eliminate conditions for the +optimization. + +=== Locking in a Three-Tier Application + +If you are building a three-tier application, in order to correctly lock +an object, you must obtain the lock before the object is sent to client +for editing. + +==== Optimistic Locking in a Three-Tier Application + +If you are using optimistic locking, you have the following two choices +for locking objects correctly: + +[arabic] +. Map the optimistic lock field in your object as not read-only and pass +the version to the client on the read and back to the server on the +update. You must define a non-read-only mapping for the version field +and make the optimistic locking policy store the version value in the +object, not the cache (in Workbench, this is done on the Locking tab by +unchecking *Store Version in Cache* (see +link:Configuring%20a%20Descriptor%20(ELUG)#How_to_Configure_Locking_Policy_Using_Workbench[How +to Configure Locking Policy Using Workbench]). Ensure that the original +version value is sent to the client when it reads the object for the +update. The client must then pass the original version value back with +the update information, and this version must be set into the object to +be updated after it is registered/read in the new unit of work on the +server. +. Hold the unit of work for the duration of the interaction with the +client. Either through a stateful session bean, or in an HTTP session, +store the unit of work used to read the object for the update for the +duration of the client interaction. You must read the object through +this unit of work before passing it to the client for the update. This +ensures that the version value stored in the unit of work cache or in +the unit of work clone will be the original value. This same unit of +work must be used for the update. + +The first option is more commonly used, and is required if developing a +stateless application. + +==== Pessimistic Locking in a Three-Tier Application + +If you are using pessimistic locking, you must use the unit of work to +start a database transaction before the object is read. You must hold +this unit of work and database transaction while the client is editing +the object and until the client updates the object. You must use this +same unit of work to update the object. If you are building a three-tier +Web application (where it is not normally desirable to hold a database +transaction open across client interactions), optimistic locking is +normally more desirable than pessimistic locking (see +link:#Optimistic_Locking_in_a_Three-Tier_Application[Optimistic Locking +in a Three-Tier Application]). + +== Descriptor API + +The descriptor API can be used to define, or amend EclipseLink +descriptors through Java code. The descriptor API classes are mainly in +the `+org.eclipse.persistence.descriptors+` package. These include the +following classes: + +* `+ClassDescriptor+` (abstract generic descriptor API) +* `+RelationalDescriptor+` (relational project-specific API) +* `+DescriptorEventManager+` (event API) +* `+DescriptorQueryManager+` (query API) +* `+InheritancePolicy+` +* `+InterfacePolicy+` +* `+ReturningPolicy+` +* Locking policies (various optimistic locking policies) + +For object-relational data type, EIS, and XML projects, descriptor +classes are in the `+org.eclipse.persistence.mappings.structures+`, +`+org.eclipse.persistence.eis+`, and `+org.eclipse.persistence.ox+` +packages, respectively. + +This section describes the important descriptor classes in the +EclipseLink Foundation Library, including the +link:#Descriptor_Inheritance_Hierarchy[Descriptor Inheritance +Hierarchy]. + +=== Descriptor Inheritance Hierarchy + +This example illustrates the descriptor types that derive from class +`+org.eclipse.persistence.descriptors.ClassDescriptor+`. + +[#Example 14-4]## *_Descriptor Inheritance Hierarchy_* + +`+class org.eclipse.persistence.descriptors.ClassDescriptor+` +`+    class org.eclipse.persistence.descriptors.RelationalDescriptor+` +`+        class org.eclipse.persistence.mappings.structures.ObjectRelationalDescriptor+` +`+    class org.eclipse.persistence.eis.EISDescriptor+` +`+    class org.eclipse.persistence.ox.XMLDescriptor+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..995c7beb666 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Descriptors_(ELUG).adoc @@ -0,0 +1,121 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EIS_Descriptors_(ELUG)[Related +Topics] + +This section introduces options specific to an EIS descriptor. + +For information on descriptor concepts and features common to more than +one type of EclipseLink descriptors, see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors]. + +== EIS Descriptor Concepts + +EIS descriptors describe Java objects that you map to an EIS data source +by way of a JCA adapter. + +Using EIS descriptors in an EIS project created with Workbench, you can +configure EIS mappings (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)[EIS Mapping Types]) to +XML records. + +Using EIS descriptors in an EIS project that you create in Java, you can +configure EIS mappings to any supported EIS record type: XML, mapped, or +indexed. + +See link:Creating_and_Configuring_Descriptors_(ELUG)[Creation and +Configuration of Descriptors] for information on how to create and +configure descriptors regardless of their type. + +For information specific to creation and configuration of EIS +descriptors, see the following: + +* link:Creating%20an%20EIS%20Descriptor%20(ELUG)[Creating an EIS +Descriptor] +* link:Configuring%20an%20EIS%20Descriptor%20(ELUG)[Configuring an EIS +Descriptor] + +== EIS Descriptors and Aggregation + +When working with descriptors for a parent (source) and a child (target) +objects, you have to accomplish the following: + +* if the source object exists, then you must ensure that the target +object also exists; +* if the source object is destroyed, then you must ensure that the +target object is also destroyed. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Aggregation[Descriptors +and Aggregation]. + +In your EIS project, designate the descriptors for the source and target +objects to reflect this relationship as +link:#Root_and_Composite_Descriptors_in_EIS_Projects[Root and Composite +Descriptors in EIS Projects]. + +=== Root and Composite Descriptors in EIS Projects + +In an EIS project, you can designate the descriptor as a composites (see +link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Composite_Descriptors[EIS +Composite Descriptors]). + +The type of EIS mapping you whish to create will determine whether you +configure an EIS descriptor as a composite or root (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#Composite_and_Reference_EIS_Mappings[Composite +and Reference EIS Mappings]). + +For more information, see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]. + +You can configure inheritance for an EIS descriptor designated as a +composite (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]), however, in this case, _all_ the descriptors in the +inheritance tree must be composites. Composite and root descriptors +cannot exist in the same inheritance tree. + +== EIS Descriptors and Inheritance + +You can use descriptors to describe the inheritance relationships +between classes in your EIS project. For more information, see the +following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Parent_(Root)_Descriptor[Configuring +Inheritance for a Parent (Root) Descriptor] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_Expressions_for_a_Parent_(Root)_Class_Descriptor[Configuring +Inheritance Expressions for a Parent (Root) Class Descriptor] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inherited_Attribute_Mapping_in_a_Subclass[Configuring +Inherited Attribute Mapping in a Subclass] + +=== Inheritance and Primary Keys in EIS Projects + +For EIS projects, EclipseLink assumes that all of the classes in an +inheritance hierarchy have the same primary key, as set in the root +descriptor. Child descriptors associated with data source +representations that have different primary keys must define the mapping +between the root primary key and the local one. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[Configuring +Primary Keys]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_EIS[Category: EIS] +Category:_Concept[Category: Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..475dca7581c --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Mappings_(ELUG).adoc @@ -0,0 +1,928 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_EIS_Mappings_(ELUG)[Related +Topics] + +EclipseLink enterprise information system (EIS) mappings provide support +for accessing legacy data sources and enterprise applications through +Java EE Connector architecture (JCA) adapter. EclipseLink EIS mappings +use the JCA Common Client Interface (CCI) to access the EIS through its +resource adapter. This provides the ability to directly map from an +existing Java object model to any transactional data source, such as +mainframes with flat file/hierarchical data. + +An EIS mapping transforms object data members to the EIS record format +defined by the object’s descriptor. + +For information on mapping concepts and features common to more than one +type of EclipseLink mappings, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings]. + +== EIS Mapping Types + +EclipseLink supports the EIS mappings listed in this table. + +[#Table 73-1]## + +EIS Mapping Type + +Description + +EclipseLink Workbench + +Java + +EIS Direct Mapping + +Map a simple object attribute directly to an EIS record. + +EIS Composite Direct Collection Mapping + +Map a collection of Java attributes directly to an EIS record. + +EIS Composite Object Mapping + +Map a Java object to an EIS record in a privately owned one-to-one +relationship. Composite object mappings represent a relationship between +two classes. + +EIS Composite Collection Mapping + +Map a Map or Collection of Java objects to an EIS record in a privately +owned one-to-many relationship. + +EIS One-to-One Mapping + +Define a reference mapping that represents the relationship between a +single source object and a single mapped persistent Java object. + +EIS One-to-Many Mapping + +Define a reference mapping that represents the relationship between a +single source object and a collection of mapped persistent Java objects. + +EIS Transformation Mapping + +Create custom mappings where one or more EIS record fields can be used +to create the object to be stored in a Java class’s attribute. + +== EIS Mapping Concepts + +This section describes concepts unique to EclipseLink EIS mappings, +including the following: + +* link:#EIS_Record_Type[EIS Record Type] +* link:#XPath_Support[XPath Support] +* #xsd:list_and_xsd:union_Support[xsd:list and xsd:union Support] +* #jaxb:class_Support[jaxb:class Support] +* link:#Typesafe_Enumeration_Support[Typesafe Enumeration Support] +* link:#Composite_and_Reference_EIS_Mappings[Composite and Reference EIS +Mappings] +* link:#EIS_Mapping_Architecture[EIS Mapping Architecture] + +=== EIS Record Type + +EclipseLink supports the following JCA EIS record types: + +* link:#Indexed_Records[Indexed Records] +* link:#Mapped_Records[Mapped Records] +* link:#[XML RecordsXML Records] + +You configure the record type at the EIS descriptor level (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Record_Format[Configuring +Record Format]). EIS mappings use the record type of their EIS +descriptor to determine how to map Java attributes. That is, you use the +same EIS mapping regardless of the record type, with which you configure +an EIS descriptor. + +[width="100%",cols="<100%",] +|=== +|*Note:* Not all JCA adapters support all record types. Consult your JCA +adapter documentation for details. +|=== + +==== Indexed Records + +The `+javax.resource.cci.IndexedRecord+` represents an ordered +collection of record elements based on the `+java.util.List+` interface. + +The EclipseLink runtime maps Java objects to indexed record elements or +subrecords of an indexed record depending on the type of EIS mapping you +use (see link:#Composite_and_Reference_EIS_Mappings[Composite and +Reference EIS Mappings]). + +==== Mapped Records + +The `+javax.resource.cci.MappedRecord+` represents a key-value map-based +collection of record elements based on the `+java.util.Map+` interface. + +The EclipseLink runtime maps Java objects to mapped record elements or +subrecords of a mapped record depending on the type of EIS mapping you +use (see link:#Composite_and_Reference_EIS_Mappings[Composite and +Reference EIS Mappings]). + +==== XML Records + +An XML record represents a `+javax.resource.cci.Record+` as an XML +schema (XSD)-based XML document. Not all JCA adapters support XML +records. + +The EclipseLink runtime maps Java objects to XML documents according to +your XSD and the behavior defined for XML mappings. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)[Introduction to XML +Mappings]. + +=== XPath Support + +When using XML records, EclipseLink EIS mappings use XPath statements to +efficiently map the attributes of a Java object to locations in an XML +record. For more information about using XPath with XML mappings, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_XPath[Mappings +and XPath]. + +=== xsd:list and xsd:union Support + +When using XML records, you can use EIS direct (see +link:#EIS_Direct_Mapping[EIS Direct Mapping]) and composite direct +collection (see link:#EIS_Composite_Direct_Collection_Mapping[EIS +Composite Direct Collection Mapping]) mappings to map to `+xsd:list+` +and `+xsd:union+` types in an XML record. + +For more information, see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_xsd:list_and_xsd:union_Types[Mappings +and xsd:list and xsd:union Types]. + +=== jaxb:class Support + +When using XML records, you can configure an EIS composite object +mapping (see link:#EIS_Composite_Object_Mapping[EIS Composite Object +Mapping]) to accommodate `+jaxb:class+` customizations with the +following XSD structures: + +* `+all+` +* `+sequence+` +* `+choice+` +* `+group+` + +For more information, see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_the_jaxb:class_Customization[Mappings +and the jaxb:class Customization]. + +=== Typesafe Enumeration Support + +You can map a Java attribute to a `+typesafe+` enumeration using the +`+JAXBTypesafeEnumConverter+` with an `+EISDirectMapping+` or +`+EISCompositeDirectCollectionMapping+` with XML records. + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_JAXB_Typesafe_Enumerations[Mappings +and JAXB Typesafe Enumerations]. + +=== Composite and Reference EIS Mappings + +EclipseLink supports composite and reference EIS mappings. Although +there is a source and target object in both mapping types, the +EclipseLink runtime handles interactions with each differently. This +section explains how. + +==== Composite EIS Mappings + +In a composite EIS mapping ( +link:#EIS_Composite_Direct_Collection_Mapping[EIS Composite Direct +Collection Mapping], link:#EIS_Composite_Object_Mapping[EIS Composite +Object Mapping], and link:#EIS_Composite_Collection_Mapping[EIS +Composite Collection Mapping]), the source object contains (owns) the +target object. + +EclipseLink puts the attributes of the target (owned) object (or the +owned collection of objects) into the source (owning) object’s record as +a subrecord. The target object needs not be a root object type (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]): it needs not have +interactions defined for it. + +The link:#Figure_73-1[EIS Composite Mappings] figure illustrates a read +interaction on an instance of the `+Customer+` class using indexed +records. For the composite object EIS mapping defined for the +`+address+` attribute, EclipseLink creates an `+Address+` subrecord in +the `+Customer+` record. + +[#Figure 73-1]## *_EIS Composite Mappings_* + +.EIS Composite Mappings +image::eiscomp.gif[EIS Composite +Mappings,title="EIS Composite Mappings"] + +==== Reference EIS Mappings + +In a reference EIS mapping ( link:#EIS_One-to-One_Mapping[EIS One-to-One +Mapping] and link:#EIS_One-to-Many_Mapping[EIS One-to-Many Mapping]), +the source object contains only a foreign key (pointer) to the target +object or, alternatively, the target object contains a foreign key to +the source object (key on target). + +EclipseLink puts the foreign key of the target object into the source +object’s record as a simple value. When an interaction is executed on +the source object, EclipseLink uses the selection interaction that you +define on its descriptor to retrieve the appropriate target object +instance and creates a record for it in the source object’s transaction. +By default, the selection interaction is the target object’s read +interaction. If the read interaction is not sufficient, you can define a +separate selection interaction (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]). Because both the source and target object use +interactions, they must both be of a root object type (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]). + +The link:#Figure_73-2[EIS Reference Mappings] figure illustrates a read +interaction on an instance of the `+Order+` class using indexed records. +For the one-to-one EIS mapping defined for the `+customer+` attribute, +EclipseLink puts the target `+Customer+` object’s foreign key into the +`+Order+` record as a simple value. EclipseLink then uses the selection +interaction you configure on the `+Order+` descriptor to retrieve the +appropriate instance of `+Customer+` and creates a record for it in the +`+Order+` object’s transaction. + +[#Figure 73-2]## *_EIS Reference Mappings_* + +.EIS Reference Mappings +image::eisref.gif[EIS Reference Mappings,title="EIS Reference Mappings"] + +=== EIS Mapping Architecture + +The link:#Figure_73-3[Possible EIS Mapping Architectures] figure +illustrates the following possible EclipseLink EIS mapping +architectures: + +* JDBC database gateway (such as Oracle Database 10__g__) +* JDBC adapter +* Proprietary adapter (such as Oracle Interconnect) +* JCA + +[#Figure 73-3]## *_Possible EIS Mapping Architectures_* + +.Possible EIS Mapping Architectures +image::eisarch.gif[Possible EIS Mapping +Architectures,title="Possible EIS Mapping Architectures"] + +The best solution may vary, depending on your specific EIS and +infrastructure. + +== EIS Direct Mapping + +An EIS direct mapping maps a simple object attribute directly to an EIS +record according to its descriptor’s record type, as shown in this +table. + +[#Table 73-2]## *_EIS Direct Mapping by EIS Record Type_* + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*EIS Record Type* |*Mapping Behavior* +|Indexed |Maps directly to a field in the indexed record. +|Mapped |Maps directly to a field in the mapped record. +|XML |Maps directly to an attribute or text node in the XML record 1. +|=== + +1See also +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Direct_Mapping[XML +Direct Mapping]. This figure illustrates a direct EIS mapping between +`+Order+` class attribute `+orderedBy+` and XML record attribute +`+ordered_by+` within the `+order+` element. + +[#Figure 73-4]## *_EIS Direct Mappings_* + +.EIS Direct Mappings +image::onetoone_eis_fig.gif[EIS Direct +Mappings,title="EIS Direct Mappings"] + +See +link:Configuring%20an%20EIS%20Direct%20Mapping%20(ELUG)#Configuring_an_EIS_Direct_Mapping[Configuring +an EIS Direct Mapping] for more information. + +== EIS Composite Direct Collection Mapping + +An EIS composite direct collection mapping maps a collection of Java +attributes directly to an EIS record according to its descriptor’s +record type, as shown in this table. + +[#Table 73-3]## *_EIS Composite Direct Collection Mapping by EIS Record +Type_* + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*EIS Record Type* |*Mapping Behavior* +|Indexed |Maps directly to a subrecord in the indexed record 1. +|Mapped |Maps directly to a subrecord in the mapped record 1. +|XML |Maps directly to an attribute or text node in the XML record 2. +|=== + +1See also link:#Composite_EIS_Mappings[Composite EIS Mappings]. 2See +also +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Direct_Collection_Mapping[XML +Composite Direct Collection Mapping]. The link:#Figure_73-5[EIS +Composite Direct Collection Mapping] figure illustrates a composite +direct collection mapping between `+Order+` class attribute `+items+` +and an XML record. The `+Order+` attribute `+items+` is a collection +type (such as `+Vector+`). It is mapped to an XML record composed of an +`+order+` element that contains a sequence of `+item+` elements. + +[#Figure 73-5]## *_EIS Composite Direct Collection Mapping_* + +.EIS Composite Direct Collection Mapping +image::eiscdc.gif[EIS Composite Direct Collection +Mapping,title="EIS Composite Direct Collection Mapping"] + +See +link:Configuring%20an%20EIS%20Composite%20Direct%20Collection%20Mapping%20(ELUG)[Configuring +an EIS Composite Direct Collection Mapping] for more information. + +== EIS Composite Object Mapping + +An EIS composite object mapping maps a Java object to a privately owned +one-to-one relationship in an EIS record according to its descriptor’s +record type, as shown in this table. + +[#Table 73-4]## *_EIS Composite Object Mapping by EIS Record Type_* + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*EIS Record Type* |*Mapping Behavior* +|Indexed |Maps directly to a subrecord in the indexed record1. +|Mapped |Maps directly to a subrecord in the mapped record 1. +|XML |Maps directly to an attribute or text node in the XML record2. +|=== + +1See also link:#Composite_EIS_Mappings[Composite EIS Mappings]. 2See +also +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The link:#Figure_73-6[EIS Composite Object +Mappings] figure illustrates a composite object EIS mapping between +`+Order+` class attribute `+address+` and an XML record. `+Order+` +attribute `+address+` is mapped to an XML record composed of an +`+order+` element that contains an `+address+` element. + +[#Figure 73-6]## *_EIS Composite Object Mappings_* + +.EIS Composite Object Mappings +image::coeisfig.gif[EIS Composite Object +Mappings,title="EIS Composite Object Mappings"] + +You can use an EIS composite object mapping with a change policy (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[Configuring +Change Policy]. + +See +link:Configuring%20an%20EIS%20Composite%20Object%20Mapping%20(ELUG)[Configuring +an EIS Composite Object Mapping] for more information. + +== EIS Composite Collection Mapping + +An EIS composite collection mapping maps a collection of Java objects to +a privately owned one-to-many relationship in an EIS record according to +its descriptor’s record type, as shown in the following table. Composite +collection mappings can reference any class that has an EclipseLink +descriptor. + +[#Table 73-5]## *_EIS Composite Collection Mapping by EIS Record Type_* + +[width="100%",cols="<22%,<78%",options="header",] +|=== +|*EIS Record Type* |*Mapping Behavior* +|Indexed |Maps directly to a subrecord in the indexed record 1. +|Mapped |Maps directly to a subrecord in the mapped record 1. +|XML |Maps directly to an attribute or text node in the XML record2. +|=== + +1See also link:#Composite_EIS_Mappings[Composite EIS Mappings]. 2See +also +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Collection_Mapping[XML +Composite Collection Mapping]. This figure illustrates a composite +collection EIS mapping between `+Phone+` class attribute +`+phoneNumbers+` and an XML record. `+Employee+` attribute +`+phoneNumbers+` is mapped to an XML record composed of an `+EMPLOYEE+` +element that contains a sequence of `+PHONE_NUMBER+` elements. + +[#Figure 73-7]## *_EIS Composite Collection Mappings_* + +.EIS Composite Collection Mappings +image::comclfig.gif[EIS Composite Collection +Mappings,title="EIS Composite Collection Mappings"] + +See +link:Configuring%20an%20EIS%20Composite%20Collection%20Mapping_(ELUG)[Configuring +an EIS Composite Collection Mapping] for more information. + +== EIS One-to-One Mapping + +An EIS one-to-one mapping is a reference mapping that represents the +relationship between a single source and target object. The source +object usually contains a foreign key (pointer) to the target object +(key on source). Alternatively, the target object may contain a foreign +key to the source object (key on target). Because both the source and +target object use interactions, they must both be of a root object type +(see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]) + +This table summarizes the behavior of this mapping depending on the EIS +record type you are using. + +[#Table 73-6]## *_EIS One-to-One Mapping by EIS Record Type_* + +EIS Record Type + +Mapping Behavior + +Indexed + +A new indexed record is created for the target object1: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +Mapped + +A new mapped record is created for the target object 1: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +XML + +A new XML record is created for the target object: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +1See also link:#Reference_EIS_Mappings[Reference EIS Mappings]. This +section describes the following: + +* link:#EIS_One-to-One_Mappings_with_Key_on_Source[EIS One-to-One +Mappings with Key on Source] +* link:#EIS_One-to-One_Mappings_with_Key_on_Target[EIS One-to-One +Mappings with Key on Target] + +See +link:Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)[Configuring +an EIS One-to-One Mapping] for more information. + +=== EIS One-to-One Mappings with Key on Source + +This figure illustrates a EIS one-to-one mapping between the +`+Employee+` class attribute `+project+` and the `+Project+` class using +XML records in a *key on source* design. + +[#Figure 73-8]## *_EIS One-to-One Mapping with Key on Source_* + +.EIS One-to-One Mapping with Key on Source +image::eisoto.gif[EIS One-to-One Mapping with Key on +Source,title="EIS One-to-One Mapping with Key on Source"] + +When a read interaction is executed on the `+Employee+` object, +EclipseLink puts the target `+Project+` object’s primary key into the +`+Employee+` record as a simple value. EclipseLink then uses the +selection interaction you configure on the `+Employee+` descriptor to +retrieve the appropriate instance of `+Project+` and creates a record +for it in the `+Employee+` object’s transaction. In this example, you +can designate the `+Project+` class’s read interaction as the selection +interaction. + +The general procedure for creating and configuring this mapping is as +follows: + +[arabic] +. Create a one-to-one EIS mapping on `+Employee+` attribute `+project+`. +. Configure the reference descriptor as `+Project+` (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Reference_Descriptors[Configuring +Reference Descriptors]). +. Configure the source and target foreign keys (see +link:Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring_Foreign_Key_Pairs[Configuring +Foreign Key Pairs]).In this example: +* Source XML Field: `+@project-id+` +* Target XML Field: `+@id+` +. Configure the selection interaction (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]).In this example, you can designate the +`+Project+` class’s read interaction as the selection interaction. + +Given the XSD shown in the link:#Example_73-1[XML Schema for EIS +One-to-One Mapping with Key on Source] example, you can configure an EIS +one-to-one mapping with key on source, as the link:#Example_73-2[EIS +One-to-One Mapping with Key On Source] example shows. In this case, the +source object contains a foreign key reference to the target object. In +the following example, the source object is `+Employee+` and the target +object is `+Project+`. Here, the `+Employee+` object has a `+Project+` +that is referenced using the project’s id. + +[#Example 73-1]## *_XML Schema for EIS One-to-One Mapping with Key on +Source_* + +`+    +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                    +` `+                +` `+            +` +`+        +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+        +` `+    +` + +[#Example 73-2]## *_EIS One-to-One Mapping with Key On Source_* + +*`+//\'\' \'\'Employee\'\' \'\'descriptor+`* +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.setJavaClass(Employee.class);+` +`+descriptor.setDataTypeName("employee");+` +`+descriptor.setPrimaryKeyFieldName("name/text()");+` + +`+EISOneToOneMapping projectMapping = new EISOneToOneMapping();+` +`+projectMapping.setReferenceClass(Project.class);+` +`+projectMapping.setAttributeName("project");+` +`+projectMapping.dontUseIndirection();+` +`+projectMapping.addForeignKeyFieldName("project/project-id/text()", "id/text()");+` + +=== EIS One-to-One Mappings with Key on Target + +The link:#Figure_73-9[EIS One-to-One Mapping with Key on Target] figure +illustrates EIS one-to-one mapping between the `+Employee+` class +attribute `+project+` and the `+Project+` class using XML records in a +*key on target* design. You still configure a one-to-one EIS mapping +between `+Employee+` and `+Project+`, but in this design, the +`+Project+` attribute `+leader+` contains the foreign key of the +`+Employee+` object. + +[#Figure 73-9]## *_EIS One-to-One Mapping with Key on Target_* + +.EIS One-to-One Mapping with Key on Target +image::eisotok.gif[EIS One-to-One Mapping with Key on +Target,title="EIS One-to-One Mapping with Key on Target"] + +When a read interaction is executed on the `+Employee+` object, +EclipseLink uses the selection interaction you configure on the +`+Employee+` descriptor to retrieve the appropriate instance of +`+Project+` and creates a record for it in the `+Employee+` object’s +transaction. In this example, the `+Project+` class’s read interaction +is unlikely to be sufficient: it is likely implemented to read based on +`+Project+` attribute `+Id+`, not on `+leader+`. If this is the case, +you must define a separate selection interaction on the `+Employee+` +descriptor that does the following: finds the `+Project+`, whose +`+leader+` equals X, where X is the value of `+Employee+` attribute +`+firstName+`. + +Note that in this configuration, `+Project+` attribute `+leader+` is not +persisted. If you want this attribute persisted, you must configure a +one-to-one EIS mapping from it to `+Employee+` attribute `+firstName+`. + +The general procedure for creating and configuring this mapping is as +follows: + +[arabic] +. Create a one-to-one EIS mapping on `+Employee+` attribute `+project+`. +. Configure the reference descriptor as `+Project+` (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Reference_Descriptors[Configuring +Reference Descriptors]). +. Configure the source and target foreign keys (see +link:Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring_Foreign_Key_Pairs[Configuring +Foreign Key Pairs]). In this example: +* Source XML Field: `+firstName/text()+` +* Target XML Field: `+leader/text()+` +. Configure the selection interaction (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]). In this example, you must define a separate +selection interaction on the `+Employee+` descriptor. + +Given the XSD shown in the link:#Example_73-3[XML Schema for EIS +One-to-One Mapping with Key on Target] example, you can configure an EIS +one-to-one mapping with key on target, as the link:#Example_73-4[EIS +One-to-One Mapping with Key on Target] example shows. In this case, the +target object contains a foreign key reference to the source object. In +the following example, the source object is `+Employee+`, and the target +object is `+Project+`. Here, a `+Project+` references its `+leader+` +using the employee’s name. + +[#Example 73-3]## *_XML Schema for EIS One-to-One Mapping with Key on +Target_* + +`+    +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                    +` `+                +` `+            +` +`+        +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+        +` `+    +` +`+    +` + +[#Example 73-4]## *_EIS One-to-One Mapping with Key on Target_* + +*`+//\'\' \'\'Project\'\' \'\'descriptor+`* +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.setJavaClass(Project.class);+` +`+descriptor.setDataTypeName("project");+` +`+descriptor.setPrimaryKeyFieldName("id/text()");+` + +`+EISOneToOneMapping leaderMapping = new EISOneToOneMapping();+` +`+leaderMapping.setReferenceClass(Employee.class);+` +`+leaderMapping.setAttributeName("leader");+` +`+leaderMapping.dontUseIndirection();+` +`+leaderMapping.addForeignKeyFieldName("leader/text()", "name/text()");+` + +== EIS One-to-Many Mapping + +An EIS one-to-many mapping is a reference mapping that represents the +relationship between a single source object and a collection of target +objects. The source object usually contains a foreign key (pointer) to +the target objects (key on source); alternatively, the target objects +may contain a foreign key to the source object (key on target). Because +both the source and target objects use interactions, they must all be of +a root object type (see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_an_EIS_Descriptor_as_a_Root_or_Composite_Type[Configuring +an EIS Descriptor as a Root or Composite Type]). + +This table summarizes the behavior of this mapping depending on the EIS +record type you are using. + +[#Table 73-7]## *_EIS One-to-Many Mapping by EIS Record Type_* + +EIS Record Type + +Mapping Behavior + +Indexed + +A new indexed record is created for each target object1: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object for each target object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +Mapped + +A new mapped record is created for each target object1: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +XML + +A new XML record is created for each target object: + +With the Key on Source use case, the foreign key(s) is added to the +record for the source object for each target object. + +With the Key on Target use case, the foreign key(s) is added to the +record for the target object + +1See also link:#Reference_EIS_Mappings[Reference EIS Mappings]. This +section describes the following: + +* link:#EIS_One-to-Many_Mappings_with_Key_on_Source[EIS One-to-Many +Mappings with Key on Source] +* link:#EIS_One-to-Many_Mappings_with_Key_on_Target[EIS One-to-Many +Mappings with Key on Target] + +See +link:Configuring%20an%20EIS%20One-to-Many%20Mapping%20(ELUG)[Configuring +an EIS One-to-Many Mapping] for more information. + +=== EIS One-to-Many Mappings with Key on Source + +This figure illustrates an EIS one-to-many mapping between the +`+Employee+` class attribute `+projects+` and multiple `+Project+` class +instances using XML records in a key on source design. + +[#'Figure 73-10]## *_EIS One-to-Many Mapping with Key on Source_* + +.EIS One-to-Many Mapping with Key on Source +image::eisotm.gif[EIS One-to-Many Mapping with Key on +Source,title="EIS One-to-Many Mapping with Key on Source"] + +When a read interaction is executed on the `+Employee+` object, +EclipseLink puts each target `+Project+` object’s foreign key into the +`+Employee+` record as a subelement. If you specify only one pair of +source and target XML fields, by default, the foreign keys are not +grouped in the `+Employee+` record. If you specify more than one pair of +source and target XML fields, you must choose a grouping element (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Reference_Descriptors[Configuring +Reference Descriptors]). The link:#Figure_73-10[EIS One-to-Many Mapping +with Key on Source] figure shows an `+Employee+` record with grouping +element `+Project+`. EclipseLink then uses the selection interaction you +configure on the `+Employee+` descriptor to retrieve the appropriate +instances of `+Project+` and creates a record for each in the +`+Employee+` object’s transaction. In this example, you can designate +the `+Project+` class’s read interaction as the selection interaction. + +The general procedure for creating and configuring this mapping is as +follows: + +[arabic] +. Create a one-to-many EIS mapping on `+Employee+` attribute +`+project+`. +. Configure the reference descriptor as `+Project+` (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Reference_Descriptors[Configuring +Reference Descriptors]). +. Configure the source and target foreign keys (see +link:Configuring%20an%20EIS%20One-to-Many%20Mapping%20(ELUG)#Configuring_Foreign_Key_Pairs[Configuring +Foreign Key Pairs]). In this example: +* Source XML Field: `+PROJECT+` +* Target XML Field: `+@ID+` +. Configure the selection interaction (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]). In this example, you can designate the +`+Project+` class’s read interaction as the selection interaction. + +Given the XSD shown in link:#Example_73-3[XML Schema for EIS One-to-One +Mapping with Key on Target], you can configure an EIS one-to-many +mapping with key on source, as the link:#Example_73-4[EIS One-to-One +Mapping with Key on Target] example shows. In this case, the source +object contains a foreign key reference to the target object. In the +following example, the source object is `+Employee+`, and the target +object is `+Project+`. Here, the `+Employee+` object has one or more +`+Project+` instances that are referenced by `+Project+` id. + +[#Example 73-5]## *_XML Schema for EIS One-to-Many Mapping with Key on +Source_* + +`+    +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                    +` `+                +` `+            +` +`+        +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+        +` `+    +` + +[#Example 73-6]## *_EIS One-to-Many Mapping with Key on Source_* + +*`+//\'\' \'\'Employee\'\' \'\'descriptor+`* +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.setJavaClass(Employee.class);+` +`+descriptor.setDataTypeName("employee");+` +`+descriptor.setPrimaryKeyFieldName("name/text()");+` + +`+EISOneToManyMapping projectMapping = new EISOneToManyMapping();+` +`+projectMapping.setReferenceClass(Project.class);+` +`+projectMapping.setAttributeName("projects");+` +`+projectMapping.setForeignKeyGroupingElement("projects"); projectMapping.setIsForeignKeyRelationship(true); projectMapping.dontUseIndirection();+` +`+projectMapping.addForeignKeyFieldName("project-id/text()", "id/text()");+` + +=== EIS One-to-Many Mappings with Key on Target + +The link:#Figure_73-9[EIS One-to-Many Mapping with Key on Target] figure +illustrates an EIS one-to-many mapping between the `+Employee+` class +attribute `+projects+` and multiple `+Project+` class instances using +XML records in a key on target design. You still configure a one-to-one +EIS mapping between `+Employee+` and `+Project+` but in this design, the +`+Project+` attribute `+leader+` contains the foreign key of the +`+Employee+` object. + +[#'Figure 73-11]## *_EIS One-to-Many Mapping with Key on Target_* + +.EIS One-to-Many Mapping with Key on Target +image::eisotmk.gif[EIS One-to-Many Mapping with Key on +Target,title="EIS One-to-Many Mapping with Key on Target"] + +When a read interaction is executed on the `+Employee+` object, +EclipseLink uses the selection interaction you configure on the +`+Employee+` descriptor to retrieve the appropriate instances of +`+Project+` and creates a record for each in the `+Employee+` object’s +transaction. In this example, the `+Project+` class’s read interaction +is unlikely to be sufficient: it is likely implemented to read based on +`+Project+` attribute `+Id+`, not on `+leader+`. If this is the case, +you must define a separate selection interaction on the `+Employee+` +descriptor that does the following: finds the `+Project+`, whose +`+leader+` equals X, where X is "`Jane`". + +Note that in this configuration, `+Project+` attribute `+leader+` is not +persisted. If you want this attribute persisted, you must configure a +one-to-one EIS mapping from it to `+Employee+` attribute `+firstName+`. + +The general procedure for creating and configuring this mapping is as +follows: + +[arabic] +. Create a one-to-one EIS mapping on `+Employee+` attribute `+project+`. +. Configure the reference descriptor as `+Project+` (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Reference_Descriptors[Configuring +Reference Descriptors]). +. Configure the source and target foreign keys (see +link:Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring_Foreign_Key_Pairs[Configuring +Foreign Key Pairs]). In this example, you select *Foreign Keys Located +On Source* and specify one pair of source and target XML fields: +* Source XML Field: +* Target XML Field: +. Configure the selection interaction (see +link:Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring_Selection_Interaction[Configuring +Selection Interaction]). In this example, you must define a separate +selection interaction on the `+Employee+` descriptor. + +Given the XSD shown in the link:#Example_73-3[XML Schema for EIS +One-to-Many Mapping with Key on Target] example, you can configure an +EIS one-to-many mapping with key on target, as the +link:#Example_73-4[EIS One-to-Many Mapping with Key on Target] example +shows. In this case, the target object contains a foreign key reference +to the source object. In the following example, the source object is +`+Employee+`, and the target object is `+Project+`. Here, each +`+Project+` references its `+leader+` using the employee’s name. + +[#Example 73-7]##[#Example 73-3]## *_XML Schema for EIS One-to-Many +Mapping with Key on Target_* + +`+    +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                    +` `+                +` `+            +` +`+        +` `+    +` `+    +` + +`+        +` `+            +` `+            +` `+        +` `+    +` + +[#Example 73-8]##[#Example 73-4]## *_EIS One-to-Many Mapping with Key on +Target_* + +*`+//\'\' \'\'Project\'\' \'\'descriptor+`* +`+EISDescriptor descriptor = new EISDescriptor();+` +`+descriptor.setJavaClass(Project.class);+` +`+descriptor.setDataTypeName("project");+` +`+descriptor.setPrimaryKeyFieldName("id/text()");+` + +`+EISOneToManyMapping leaderMapping = new EISOneToOneMapping();+` +`+leaderMapping.setReferenceClass(Employee.class);+` +`+leaderMapping.setAttributeName("leader");+` +`+leaderMapping.dontUseIndirection();+` +`+leaderMapping.addForeignKeyFieldName("leader/text()", "name/text()");+` + +== EIS Transformation Mapping + +A transformation EIS mapping lets you create a custom mapping, where one +or more fields in an EIS record can be used to create the object to be +stored in a Java class’s attribute. + +This table summarizes the behavior of this mapping depending on the EIS +record type you are using. + +[#Table 73-8 EIS]## *_Transformation Mapping by EIS Record Type_* + +[width="100%",cols="<15%,<85%",options="header",] +|=== +|*EIS Record Type* |*Mapping Behavior* +|Indexed |The field transformer adds data to the indexed record (you +have access to the indexed record in the attribute transformer). + +|Mapped |The field transformer adds data to the mapped record (you have +access to the mapped record in the attribute transformer). + +|XML |The field transformer adds data to the XML record (you have access +to the XML record in the attribute transformer). +|=== + +As the link:#Figure_73-12[EIS Transformation Mappings] figure +illustrates, you configure the transformation mapping with an +`+org.eclipse.persistence.mappings.transformers.AttributeTransformer+` +instance to perform the XML instance-to-Java attribute transformation at +unmarshall time. In this example, the `+AttributeTransformer+` combines +two XML text nodes into a single Java object. + +[#Figure 73-12]## *_EIS Transformation Mappings_* + +.EIS Transformation Mappings +image::transfig.gif[EIS Transformation +Mappings,title="EIS Transformation Mappings"] + +See +link:Configuring%20an%20EIS%20Transformation%20Mapping%20(ELUG)[Configuring +an EIS Transformation Mapping] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Projects_(ELUG).adoc new file mode 100644 index 00000000000..4278d7f592f --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EIS_Projects_(ELUG).adoc @@ -0,0 +1,126 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_EIS_Projects_(ELUG)[Related +Topics] + +This section provides an overview of EIS projects and their components. + +For information on project concepts and features common to more than one +type of EclipseLink projects, see +link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects]. + +== EIS Project Concepts + +Use an EIS project for transactional persistence of Java objects to a +_nonrelational_ data source accessed using a Java EE Connector +Architecture (JCA) adapter and EIS records. + +JCA provides a Common Client Interface (CCI) API to access nonrelational +EIS. This provides a similar interface to nonrelational data sources as +JDBC provides for relational data sources. This API defines several +types of nonrelational record types including mapped and indexed. XML +has emerged as the standard format to exchange data, and most leading +JCA adapter providers have extended the CCI API to define XML data +records. + +To use a JCA adapter with EclipseLink EIS, the JCA adapter must support +the JCA CCI interface. At run time, your JCA adapter and the Java +`+connector.jar+` file (that contains the `+javax.resource.cci+` and +`+javax.resource.spi+` interfaces that EclipseLink EIS uses) must be on +your application or application server classpath. + +If you are using Workbench, you must add your JCA adapter to the +Workbench classpath. By default, Workbench updates its classpath to +include the Java 1.5._n_ `+connector.jar+` file from +`+<+`_`+ECLIPSELINK_HOME+`_`+>/utils/workbench/jlib+`. If this version +of the `+connector.jar+` file is incompatible with your environment, +edit the `+workbench.cmd+` or `+workbench.sh+` file in +`+<+`_`+ECLIPSELINK_HOME+`_`+>/utils/workbench/bin+` to change the path +to this file. For more information, see +link:Using%20Workbench%20(ELUG)#Configuring_the_Workbench_Environment[Configuring +the Workbench Environment]. + +EIS includes legacy data sources, enterprise applications, legacy +applications, and other information systems. These systems include such +sources as Custormer Information Control System (CICS), Virtual Storage +Access Method (VSAM), Information Management System (IMS), ADABASE +database, and flat files. + +We recommend using EIS projects to integrate EclipseLink with a legacy +or nonrelational data source. Other methods of accessing EIS data +sources include: + +* Using a specialized JDBC driver that allows connecting to an EIS +system as if it were a relational database. You could use an +link:Introduction%20to%20Relational%20Projects%20(ELUG)[EclipseLink +relational project] with these drivers. +* Linking to or integrating with the EIS data from a relational +database, such as Oracle Database. +* Using a proprietary API to access the EIS system. In this case it may +be possible to wrap the API with a JCA CCI interface to allow usage with +an EclipseLink EIS project. + +EclipseLink provides support for mapping Java objects to EIS mapped, +indexed, and XML records, through JCA, using the +link:EIS_Mappings_(ELUG)[EclipseLink EIS mappings]. + +You configure an EclipseLink EIS descriptor to use a +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring_Record_Format[particular +EIS record format]. EclipseLink EIS mappings use their EIS descriptor’s +record format configuration to determine how to map their Java objects +to EIS records. + +If you use XML records, the EclipseLink runtime performs XML data +conversion based on one or more XML schemas. In an EIS project that uses +XML records, Workbench directly references schemas in the deployment +XML, and exports mappings configured with respect to the schemas you +specify. For information on how to use Workbench with XML schemas, see +link:Using%20Workbench%20(ELUG)#Using_XML_Schemas[Using XML Schemas]. +For information on how EclipseLink supports XML namespaces, see +link:Introduction%20to%20Projects_(ELUG)#XML_Namespaces_Overview[XML +Namespaces Overview]. + +This table describes the components of an EIS project. + +[#Table 67-1]## *_EIS Project Components_* + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Component* |*Supported Types* +|Data Source +|link:Introduction%20to%20Data%20Access%20(ELUG)#EISLogin[EISLogin] and +link:Introduction%20to%20Data%20Access%20(ELUG)#EIS_Platforms[EIS +Platforms] + +|Descriptors +|link:Introduction%20to%20EIS%20Descriptors%20(ELUG)#EIS_Descriptor_Concepts[EIS +Descriptor Concepts] + +|Mappings |link:EIS_Mappings_(ELUG)[EIS Mappings] +|=== + +You can create an EIS project with Workbench for use with +link:Creating%20an%20EIS%20Project%20(ELUG)#Creating_an_EIS_Project_with_XML_Records[EIS +XML records] or you can build an EIS project in Java for use with +link:Creating%20an%20EIS%20Project%20(ELUG)#Creating_an_EIS_Project_with_Indexed_or_Mapped_Records[any +supported EIS record type]. + +In an EIS project, your +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Enterprise_Information_System_(EIS)_Interactions[EIS +interactions] can make full use of +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[EclipseLink +queries]. However, you cannot use EclipseLink expressions with EIS: in +an EIS project, interactions replace expressions. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_EIS[Category: EIS] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_(ELUG).adoc new file mode 100644 index 00000000000..5906ad9d322 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_(ELUG).adoc @@ -0,0 +1,276 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_EclipseLink_(ELUG)[Related +Topics] + +EclipseLink is an advanced, object-persistence and object-transformation +framework that provides development tools and run-time capabilities that +reduce development and maintenance efforts, and increase enterprise +application functionality. + +== What Is EclipseLink? + +EclipseLink builds high-performance applications that store persistent +object-oriented data in a relational database. It successfully +transforms object-oriented data into either relational data or +Extensible Markup Language (XML) elements. + +*_EclipseLink Runtime Architecture_* + +.EclipseLink Runtime Architecture +image::under02.gif[EclipseLink Runtime +Architecture,title="EclipseLink Runtime Architecture"] + +Using EclipseLink, you can integrate persistence and +object-transformation into your application, while staying focused on +your primary domain problem by taking advantage of an efficient, +flexible, and field-proven solution (see +link:#What_Is_the_Object-Persistence_Impedance_Mismatch[What Is the +Object-Persistence Impedance Mismatch]). + +EclipseLink is suitable for use with a wide range of Java 2 Enterprise +Edition (Java EE) and Java application architectures (see +link:#EclipseLink_Application_Architectures[EclipseLink Application +Architectures]). Use EclipseLink to design, implement, deploy, and +optimize an advanced, object-persistence and object-transformation layer +that supports a variety of data sources and formats, including the +following: + +* Relational–for transactional persistence of Java objects to a +relational database accessed using Java Database Connectivity (JDBC) +drivers. +* Object-Relational Data Type–for transactional persistence of Java +objects to special purpose structured data source representations +optimized for storage in object-relational data type databases such as +Oracle Database. +* Enterprise information system (EIS)–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. +* XML–for nontransactional, nonpersistent (in-memory) conversion between +Java objects and XML Schema Document (XSD)-based XML documents using +Java Architecture for XML Binding (JAXB). + +EclipseLink includes support for EJB 3.0 and the Java Persistence API +(JPA) in Java EE and Java SE environments including integration with a +variety of application severs including: Oracle WebLogic Server, OC4J, +Glassfish/SunAS, JBoss, and IBM WebSphere application server. +EclipseLink lets you quickly capture and define object-to-data source +and object-to-data representation mappings in a flexible, efficient +metadata format (see +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Working_with_EclipseLink_Metadata[Working +with EclipseLink Metadata]). + +The EclipseLink runtime lets your application exploit this mapping +metadata with a simple session facade that provides in-depth support for +data access, queries, transactions (both with and without an external +transaction controller), and caching. + +For more information, see link:#EclipseLink_Key_Features[EclipseLink Key +Features]. + +== What Is the Object-Persistence Impedance Mismatch + +Java-to-data source integration is a widely underestimated problem when +creating enterprise Java applications. This complex problem involves +more than simply reading from and writing to a data source. The data +source elements include tables, rows, columns, and primary and foreign +keys. The Java and Java EE include entity classes (regular Java classes +or Enterprise JavaBeans (EJB) entity beans), business rules, complex +relationships, and inheritance. In a nonrelational data source, you must +match your Java entities with EIS records or XML elements and schemas. +These differences (as shown in the following figure) are known as the +object-persistence impedance mismatch. + +*_Solving Object-Persistence Impedance Mismatch_* + +.Solving Object-Persistence Impedance Mismatch +image::mismatch.gif[Solving Object-Persistence Impedance +Mismatch,title="Solving Object-Persistence Impedance Mismatch"] + +Successful solution requires bridging these different technologies, and +solving the object-persistence impedance mismatch–a challenging and +resource-intensive problem. To solve this problem, you must resolve the +following issues between Java EE and data source elements: + +* Fundamentally different technologies. +* Different skill sets. +* Different staff and ownership for each of the technologies. +* Different modeling and design principles. + +As an application developer, you need a product that lets integrate Java +applications with any data source, without compromising ideal +application design or data integrity. In addition, as a Java developer, +you need the ability to store (that is, *persist*) and retrieve business +domain objects using a relational database or a nonrelational data +source as a repository. + +=== EclipseLink Solution + +EclipseLink addresses the disparity between Java objects and data +sources. EclipseLink is a persistence framework that manages relational, +object-relational data type, EIS, and XML mappings in a seamless manner. +This lets you rapidly build applications that combine the best aspects +of object technology and the specific data source. EclipseLink lets you +do the following: + +* Persist Java objects to virtually _any_ relational database supported +by a JDBC-compliant driver. +* Persist Java objects to virtually _any_ nonrelational data source +supported by a Java EE Connector architecture (JCA) adapter using +indexed, mapped, or XML enterprise information system (EIS) records. +* Perform in-memory conversions between Java objects and XML Schema +(XSD) based XML documents using JAXB. +* Map _any_ object model to _any_ relational or nonrelational schema, +using the Workbench graphical mapping tool or Oracle JDeveloper +EclipseLink editor. +* Use EclipseLink successfully, even if you are unfamiliar with SQL or +JDBC, because EclipseLink offers a clear, object-oriented view of data +sources. + +== EclipseLink Key Features + +EclipseLink provides an extensive and thorough set of features. You can +use these features to rapidly build high-performance enterprise +applications that are both scalable and maintainable. + +Some of the primary features of EclipseLink are the following: + +* Nonintrusive, flexible, metadata-based architecture (see +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Working_with_EclipseLink_Metadata[Working +with EclipseLink Metadata]) +* Architectural flexibility: Java Persistence API (JPA), Plain Old Java +Objects (POJO), Java API for XML Binding (JAXB), and Web services. +* Advanced mapping support and flexibility: relational, +object-relational data type, Enterprise Information Systems (EIS), and +XML. +* Optimized for highly scalable performance and concurrency with +extensive performance tuning options. +* Comprehensive object caching support including cluster integration. +* Extensive query capability including: EclipseLink Expressions +framework, Java Persistence Query Language (JP QL), and native SQL. +* Just-in-time reading +* Object-level transaction support and integration with popular +application servers and databases. +* Optimistic and pessimistic locking options and locking policies. +* Comprehensive visual design tools. + +For additional information, see the EclipseLink page: +http://www.eclipse.org/eclipselink/. + +== EclipseLink Application Architectures + +You can use EclipseLink in a variety of application architectures, +including three- and two-tier architectures, with or without Java EE, to +access a variety of data types on both relational and nonrelational data +sources. + +*_EclipseLink and Your Application Architecture_* + +.EclipseLink and Your Application Architecture +image::whytl.gif[EclipseLink and Your Application +Architecture,title="EclipseLink and Your Application Architecture"] + +For more information on strategies for incorporating EclipseLink into +your application architecture, see +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Designing_Your_Application_with_EclipseLink[Designing +Your Application with EclipseLink]. + +This section introduces some of the following common enterprise +architectures used by EclipseLink applications: + +* *Three-Tier* – The three-tier (or Java EE Web) application is one of +the most common EclipseLink architectures. This architecture is +characterized by a server-hosted environment in which the business +logic, persistent entities, and the EclipseLink Foundation Library all +exist in a single Java Virtual Machine (JVM). See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_Three-Tier_Architecture[Considering +Three-Tier Architecture] for more information. The most common example +of this architecture is a simple three-tier application in which the +client browser accesses the application through servlets, JavaServer +Pages (JSP) and HTML. The presentation layer communicates with +EclipseLink through other Java classes in the same JVM, to provide the +necessary persistence logic. This architecture supports multiple servers +in a clustered environment, but there is no separation across JVMs from +the presentation layer and the code that invokes the persistence logic +against the persistent entities using EclipseLink. +* *EJB Session Bean Facade*– A popular variation on the three-tier +application involves wrapping the business logic, including the +EclipseLink access, in EJB session beans. This architecture provides a +scalable deployment and includes integration with transaction services +from the host application server. See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_EJB_Session_Bean_Facade_Architecture[Considering +EJB Session Bean Facade Architecture] for more information. +Communication from the presentation layer occurs through calls to the +EJB session beans. This architecture separates the application into +different tiers for the deployment. The session bean architecture can +persist either Java objects or EJB entity beans. +* *EJB 3.0 Entities with JPA* – The EJB 3.0 specification includes an +additional persistence specification called the Java Persistence API +(JPA). You can use this API for creating, reading, updating, and +deleting plain old Java objects (POJO) within both a compliant EJB 3.0 +Java EE container and a standard Java SE 5 (or later) environment. +EclipseLink JPA is a standards compliant JPA persistence provider built +on the EclipseLink foundation library. EclipseLink JPA offers a variety +of vendor extensions (annotations and persistence properties) that give +you full access to the underlying EclipseLink API. For more information, +see: +** link:Introduction_to_Java_Persistence_API_(ELUG)#Java_Persistence_API_Overview[Java +Persistence API Overview] +** link:Introduction_to_EclipseLink_JPA_(ELUG)#EclipseLink_JPA_Overview[EclipseLink +JPA Overview] +** link:Developing_Applications_Using_EclipseLink_JPA_(ELUG)[Application +Development with EclipseLink JPA] +** http://www.oracle.com/technology/products/ias/toplink/jpa/index.html[`+http://www.oracle.com/technology/products/ias/toplink/jpa/index.html+`] +** link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_JPA_Entity_Architecture[Considering +JPA Entity Architecture] + +* *Web Services* – A Web services architecture is similar to the +three-tier or session-bean architecture. However, in a Web services +architecture you encapsulate business logic (the service) in a Web +service instead of (or in addition to) using session beans. In a Web +services architecture, clients communicate with your application using +XML. As in any architecture, you can use EclipseLink to persist objects +to relational or EIS data sources. However, in a Web services +architecture you can also use EclipseLink to map your object model to an +XML schema for use with the Web service or as the Web service XML +serializer. See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_Web_Services_Architecture[Considering +Web Services Architecture] for more information +* *EclipseLink Database Web Services* – EclipseLink database Web +services architecture (introduced in 1.1) is similar to the Web services +architecture. However, in an EclipseLink database Web services +architecture, you use EclipseLink to automatically generate Web services +that expose database operations such as queries, DML statements, and +stored procedures and stored functions. Using EclipseLink database Web +services, you can provide Java EE compliant, client-neutral access to a +relational database without having to write Java code. As in any Web +services architecture, clients communicate with your application using +SOAP (XML) messages. However, in an EclipseLink database Web services +architecture you need only specify an XSD for persistent classes. +Clients need only invoke the operations the EclipseLink database Web +service exposes to create, read, update, and delete these persistent +objects. EclipseLink database Web services return objects or row set +data, depending on the type of operation. See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_EclipseLink_Database_Web_Service_Architecture[Considering +EclipseLink Database Web Service Architecture] for more information. +* *Two-Tier* – A two-tier (or client/server) application is one in which +the EclipseLink application accesses the database directly. Although +less common than the other architectures discussed here, EclipseLink +supports this architecture for smaller or embedded data processing +applications. See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Considering_Two-Tier_Architecture[Considering +Two-Tier Architecture] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.1[Category: Release 1.1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Application_Development_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Application_Development_(ELUG).adoc new file mode 100644 index 00000000000..482c8dd73f1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Application_Development_(ELUG).adoc @@ -0,0 +1,2175 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Application_Development_(ELUG)[Related +Topics] + +This section describes how to build an EclipseLink application, +including suggested development processes, architectures, and +technologies. + +To ensure the best design for your EclipseLink application, we recommend +that you follow an iterative step-by-step development process. The +flexibility of EclipseLink lets you use _any_ development tool. + +=== Typical Development Stages + +This section describes the general development stages of an EclipseLink +application. The following figure illustrates the EclipseLink +development process. + +*_EclipseLink Development Process_* + +.EclipseLink Development Process +image::process.gif[EclipseLink Development +Process,title="EclipseLink Development Process"] + +*Design the Application (1)* + +Define your application requirements, select an architecture, and +determine the target platform. See +link:#Designing_Your_Application_with_EclipseLink[Designing Your +Application with EclipseLink] for more information. Remember, +EclipseLink works with _any_ architecture and _any_ platform. + +When designing the application, you should also create an object model +for the application. See link:#Persisting_Objects[Persisting Objects] +for more information. It is important to create the object model +_before_ using EclipseLink to map objects, because defining persistent +mappings for an incorrect or rapidly changing model can be very +difficult. + +*Develop the Application (2, 3, 4)* + +Create the Java classes and decide how the classes should be implemented +by the data source. When working with a legacy system, decide how the +classes relate to the existing data. If there is no legacy data source +to integrate, decide how to store each class in the data source and +create the required schema. Alternatively, you may use EclipseLink to +create your initial tables. + +You have several choices in how you map your classes. When using JPA you +can use either annotations or XML. You can code or write the XML by +hand, or use an IDE that supports JPA such as Eclipse Dali, or Oracle +JDeveloper. When using EclipseLink’s native API’s, MOXy or EIS you can +use the EclipseLink Workbench. + +Using the Workbench, create descriptors and mappings for the persistent +classes. Use EclipseLink sessions to manipulate the persistent classes, +including querying and changing data. See +link:EclipseLink_UserGuide_Overview_of_EclipseLink_Development_Tools_(ELUG)[EclipseLink +Development Tools Overview] for more information. + +Avoid mapping all your model’s classes in a single iteration. Start with +a small subset of your classes. Build and test their mappings, then +gradually add classes and relationships. This lets you catch common +problems before they proliferate through your entire design. + +Your runtime application code can use JPA, the native EclipseLink API’s, +or JAXB when using MOXy. For JPA write Java code to use the +EntityManager. For native EclipseLink API write Java code to use +EclipseLink sessions. Sessions are used to query for database objects +and write objects to the database. See +link:Introduction_to_EclipseLink_Sessions_(ELUG)[Introduction to +EclipseLink Sessions] for more information. + +*Deploy the Application (5)* + +Generate, package, then deploy the necessary files to your application +server. The required information will vary, depending on your +environment and architecture. See +link:EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Deployment_(ELUG)[Introduction +to EclipseLink Application Deployment] for more information. + +*Maintain the Application (6)* + +EclipseLink includes many options that can enhance application +performance. You can customize most aspects of EclipseLink to suit your +requirements. Use advanced EclipseLink features or write custom querying +routines to access the database in specific ways, and to optimize +performance. See +link:EclipseLink_UserGuide_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG)[Optimization +and Customization of an EclipseLink Application] for more information. + +== Designing Your Application with EclipseLink + +When you design your application, you must choose how and where to use +EclipseLink. You can use EclipseLink to perform a variety of persistence +and data transformation functions (see +link:#How_to_Use_EclipseLink_in_Your_Application_Design[How to Use +EclipseLink in Your Application Design]) on a variety of Java-supporting +platforms (see link:#Target_Platforms[Target Platforms]). When you +design your application architecture, keep these capabilities in mind +(see link:#Selecting_an_Architecture_with_EclipseLink[Selecting an +Architecture with EclipseLink]). + +=== How to Use EclipseLink in Your Application Design + +This section describes the basic ways in which you can use EclipseLink, +including the following usage types: + +* link:#Relational_Database_Usage[Relational Database Usage] +* link:#Object-Relational_Data_Type_Database_Usage[Object-Relational +Data Type Database Usage] +* link:#Oracle_XML_Database_(XDB)_Usage[Oracle XML Database (XDB) Usage] +* link:#Enterprise_Information_System_(EIS)_Usage[Enterprise Information +System (EIS) Usage] +* link:#XML_Usage[XML Usage] +* link:#EclipseLink_Database_Web_Services_Usage[EclipseLink Database Web +Services Usage] + +==== Relational Database Usage + +You can use EclipseLink to persist Java objects to relational databases +that support SQL data types accessed using JDBC. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#How_to_Build_Relational_Projects_for_a_Relational_Database[How +to Build Relational Projects for a Relational Database]. + +==== Object-Relational Data Type Database Usage + +You can use EclipseLink to persist Java objects to object-relational +data type databases that support data types specialized for object +storage (such as Oracle Database) accessed using JDBC. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#How_to_Build_Relational_Projects_for_an_Object-Relational_Data_Type_Database[How +to Build Relational Projects for an Object-Relational Data Type +Database]. + +==== Oracle XML Database (XDB) Usage + +You can use EclipseLink to persist XML documents to an Oracle XML +database using EclipseLink direct-to-XMLType mappings. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Introduction to +Relational Projects] and +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mapping]. + +==== Enterprise Information System (EIS) Usage + +You can use EclipseLink to persist Java objects to an EIS data source +using a JCA adapter. + +In this scenario, the application invokes EIS data source-defined +operations by sending EIS interactions to the JCA adapter. Operations +can take (and return) EIS records. Using EclipseLink EIS descriptors and +mappings, you can easily map Java objects to the EIS record types +supported by your JCA adapter and EIS data source. + +This usage is common in applications that connect to legacy data sources +and is also applicable to Web services. + +For more information, see +link:Introduction%20to%20EIS%20Projects%20(ELUG)[Introduction to EIS +Projects]. + +==== XML Usage + +You can use EclipseLink for in-memory, nonpersistent Java object-to-XML +transformation with XML Schema (XSD) based XML documents and JAXB. + +You can use the EclipseLink JAXB compiler with your XSD to generate both +JAXB-specific artifacts (such as content and element interfaces, +implementation classes, and object factory class) and +EclipseLink-specific artifacts (such as sessions and project XML files +and Workbench project). For more information, see +link:Introduction%20to%20XML%20Projects%20(ELUG)#EclipseLink_Support_for_Java_Architecture_for_XML_Binding_(JAXB)[EclipseLink +Support for Java Architecture for XML Binding (JAXB)]. + +This usage has many applications, including messaging and Web services. + +For more information, see +link:Introduction%20to%20XML%20Projects%20(ELUG)[Introduction to XML +Projects]. + +==== EclipseLink Database Web Services Usage + +You can use EclipseLink Database Web Services (DBWS) (introduced in +Release 1.1) to automatically generate JAX-WS 2.0 compliant Web services +that expose database operations such as queries, DML statements, and +stored procedures and stored functions. Using EclipseLink DBWS services, +you can provide Java EE-compliant, client-neutral access to a relational +database without having to write Java code. + +EclipseLink DBWS services use document literal format as the WSDL +specification defines and use wrapped elements +(http://java.sun.com/webservices/jaxrpc/overview.html[see the JAX-RPC +1.1 specification]). + +EclipseLink DBWS services have been tested with the Web services stack +in Oracle WebLogic 10.3. For testing purposes, you can also deploy +EclipseLink DBWS services as a Java SE 6 '`containerless`' +http://java.sun.com/javase/6/docs/api/javax/xml/ws/Endpoint.html[Endpoint]. + +You can use EclipseLink DBWS services with any database that providers a +JDBC driver that returns +http://java.sun.com/javase/6/docs/api/java/sql/DatabaseMetaData.html[DatabaseMetaData] +(tested on Oracle, MySQL, and so on). + +For more information, see the following: + +* http://wiki.eclipse.org/Category:DBWS[EclipseLink DBWS Documentation] +* http://wiki.eclipse.org/EclipseLink/Examples/DBWS[EclipseLink DBWS +Examples] + +=== Target Platforms + +EclipseLink supports any enterprise architecture that uses Java, +including the following: + +* Java EE +* Spring +* OSGI +* Java Web servers such as Tomcat +* Java clients such as Java SE and Web browsers +* Server Java platforms + +Application packaging requirements of the specific target platform (for +deployment in the host Java or Java EE environment) influences how you +use and configure EclipseLink. For example, you package a Java EE +application in an Enterprise Archive (EAR) file. Within the EAR file, +there are several ways to package persistent entities within Web Archive +(WAR) and Java Archive (JAR). How you configure EclipseLink depends, in +part, on how you package the application and how you use the host +application server class loader. + +For detailed information about supported application server versions, +custom integration, and configuration requirements, see +link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server]. + +== Selecting an Architecture with EclipseLink + +This section describes some of the key aspects of application +architecture that apply to EclipseLink and discusses the various options +available for each, including the following: + +* link:#Tiers[Tiers] +* link:#Service_Layer[Service Layer] +* link:#Data_Access[Data Access] +* link:#caching1[Caching] +* link:#Locking[Locking] + +=== Tiers + +This section describes choices you need to make when deciding on how to +separate client and server functionality in your application +architecture. + +These choices can be summarized as follows: + +* link:#Three_Tier[Three Tier] +** link:#Java_EE_or_Non-Java_EE[Java EE or Non-Java EE] +** link:#Client1[Client] +*** Web client +*** XML/Web service client +*** Java (fat) client +* link:#Two_Tier[Two Tier] + +==== Three Tier + +We recommend a three-tier application architecture. With a three-tier +architecture, we recommend using EclipseLink JPA or EclipseLink +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server_and_Client_Sessions[Server +and Client Sessions] and the +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[EclipseLink +unit of work]. + +For more information, see +link:#Considering_Three-Tier_Architecture[Considering Three-Tier +Architecture]. + +===== Java EE or Non-Java EE + +You can use EclipseLink in a Java EE or non-Java EE application +architecture. We recommend that you use a Java EE application +architecture. + +With a Java EE application, you should use +link:Introduction%20to%20Data%20Access%20(ELUG)#External_Connection_Pools[External +Connection Pools]. You may consider using JPA, EJB session beans, and +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#JTA_Controlled_Transactions[Java +Transaction API (JTA) integration]. + +With a non-Java EE application, you should use +link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools]. You may still consider using JPA. + +===== [#Client1]#Client# + +In a three-tier application architecture, you can implement any of the +following types of client: + +* Web client – We recommend that you implement a Web client. +* XML/Web service client – With this client type, you can +link:#XML_Usage[use EclipseLink XML]. +* Java (fat) client – With this client type, you can choose the means of +communicating with the server: +** EJB session beans – We recommend this approach. You may consider +using the `+UnitOfWork+` method `+mergeClone+` to handle merging +deserialized objects (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Merging_Changes_in_Working_Copy_Clones[Merging +Changes in Working Copy Clones]). The disadvantage of this approach is +that your application must handle serialization. Avoid serializing deep +object graphs. You should use indirection, also known in JPA as +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[lazy +loading]. Consider using the data-transfer-object pattern. +** XML/Web service – Use link:#XML_Usage[EclipseLink XML]. +** RMI – You may consider using an +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Remote_Sessions[EclipseLink +remote session]. The disadvantage of this approach is that a remote +session is stateful and may not scale well. + +See also link:#Service_Layer[Service Layer]. + +==== Two Tier + +With a two-tier application architecture, we recommend using JPA or +EclipseLink +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Database +Sessions] and the +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[EclipseLink +unit of work]. The disadvantages of this architecture are that it is not +Web-enabled and does not scale well to large deployments. + +For more information, see +link:#Considering_Two-Tier_Architecture[Considering Two-Tier +Architecture]. + +=== Service Layer + +This section describes choices you need to make when deciding on how to +encapsulate your application’s business logic (or service). + +These choices can be summarized as follows: + +* link:#EJB_Session_Beans[EJB Session Beans] +** link:#Stateful[Stateful] +** link:#Stateless[Stateless] +* link:#JPA-Entities1[JPA Entities] +* link:#Plain_Old_Java_Objects_(POJO)[Plain Old Java Objects (POJO)] + +See also: + +* link:#Data_Access[Data Access] +* link:#caching1[Caching] + +==== EJB Session Beans + +We recommend using EJB session beans. + +With EJB session beans, you should use +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#JTA_Controlled_Transactions[JTA +integration] and +link:Introduction%20to%20Data%20Access%20(ELUG)[External Connection +Pools]. You can use JPA or the EclipseLink native API. If using JPA you +can inject your JPA EntityManager into your SessionBeans. If using the +native API, you should acquire a unit of work using `+Server+` method +`+getActiveUnitOfWork+` (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Acquire a +Unit of Work with an External Transaction Service]). If your session +bean and client are not in the same JVM, you may consider using +`+UnitOfWork+` method `+mergeClone+` to handle +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Merging_Changes_in_Working_Copy_Clones[merging +deserialized objects]. + +For more information, see +link:#Considering_EJB_Session_Bean_Facade_Architecture[Considering EJB +Session Bean Facade Architecture]. + +===== Stateful + +If you are using stateful session beans, then note that a reference to a +client session cannot be passivated. In this case, you must +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Acquiring_a_Session_at_Run_Time_with_the_Session_Manager[reacquire +a client session] on activate or per request. + +===== Stateless + +If you are using stateless session beans, you must +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Acquiring_a_Session_at_Run_Time_with_the_Session_Manager[acquire +new client session] for each request. + +==== [#JPA-Entities1]#JPA Entities# + +We recommend you use JPA. + +Java Persistence API (JPA) is a specification for persistence in Java EE +and Java SE applications. In JPA, a persistent class is referred to as +an entity. An entity is a link:#Plain_Old_Java_Objects_(POJO)[plain old +Java object (POJO) class] that is mapped to the database and configured +for usage through JPA using annotations, persistence XML, or both. + +With JPA, when your application is running inside a container, all of +the benefits of the container support and ease of use apply. Note that +you can configure the same application to run outside the container. + +You can use link:#EJB_Session_Beans[EJB Session Beans] as the means for +your application to interact with JPA. + +EclipseLink JPA is a standards compliant JPA persistence provider built +on the EclipseLink foundation library. EclipseLink JPA offers a variety +of vendor extensions (annotations and persistence properties) that give +you full access to the underlying EclipseLink API to take advantage of +additional functionality and performance benefits. + +For more information, see the following: + +* link:#Considering_JPA_Entity_Architecture[Considering JPA Entity +Architecture] +* link:Introduction%20to%20EclipseLink%20(ELUG)#EclipseLink_Application_Architectures[EclipseLink +Application Architectures] +* link:Introduction_to_Java_Persistence_API_(ELUG)[Introduction to Java +Persistence API] +* link:Introduction_to_EclipseLink_JPA_(ELUG)[Introduction to +EclipseLink JPA] + +==== Plain Old Java Objects (POJO) + +If you choose to build your service layer with non-EJB Java objects with +a Java EE application server, you should use +link:Introduction%20to%20Data%20Access%20(ELUG)#External_Connection_Pools[External +Connection Pools], and may consider using JTA integration (see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#JTA_Controlled_Transactions[JTA +Controlled Transactions]). If you use a non-Java EE Web server, you +should use +link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools]. + +=== Data Access + +This section describes choices you need to make when deciding on what +type of data your application architecture must support. + +These choices can be summarized as follows: + +* link:#Data_Type[Data Type] +* link:#Multiple_Data_Sources[Multiple Data Sources] +* link:#Isolating_Data_Access[Isolating Data Access] +* link:#Historical_Data_Access[Historical Data Access] + +See also link:#Locking[Locking]. + +==== Data Type + +You can use EclipseLink to manage any of the following types of data: + +* link:#Relational_Database_Usage[relational]; +* link:#Object-Relational_Data_Type_Database_Usage[object-relational +data type]; +* link:#Oracle_XML_Database_(XDB)_Usage[Oracle XDB]; +* link:#Enterprise_Information_System_(EIS)_Usage[EIS, +nonrelational, legacy data]; +* link:#XML_Usage[XML and Web service data]. + +==== Multiple Data Sources + +If your application architecture must access more than one data source, +we recommend that you use a +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session_Broker_and_Client_Sessions[session +broker] and JTA integration (see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#JTA_Controlled_Transactions[JTA +Controlled Transactions]) for two-phase commit. + +Alternatively, you may use multiple sessions. + +==== Isolating Data Access + +If your application architecture requires that some data be restricted +to a private cache and isolated from the EclipseLink shared session +cache, we recommend that you use an +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Session]. You can also use an isolated session with the +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Oracle +Virtual Private Database (VPD) feature]. + +==== Historical Data Access + +If your data source maintains past or historical versions of objects, we +recommend that you use an EclipseLink historical session +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical_Sessions[Historical +Session] to access this historical data so that you can express read +queries conditional on how your objects are changing over time. + +=== [#caching1]#Caching# + +This section describes choices you need to make when deciding on how to +use the link:Introduction%20to%20Cache%20(ELUG)[EclipseLink cache] in +your application architecture. + +These choices can be summarized as follows: + +* link:#Cache_Type[Cache Type] +* link:#Refreshing[Refreshing] +* link:#Cache-Coordination1[Cache Coordination] +** link:#Protocol[Protocol] +** link:#Synchronization[Synchronization] + +See also link:#Locking[Locking]. + +==== Cache Type + +Choose a +link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type] appropriate for the type of data your application processes. For +example, consider a weak identity map for volatile data (see +link:Introduction%20to%20Cache%20(ELUG)#Guidelines_for_Configuring_the_Cache_and_Identity_Maps[Guidelines +for Configuring the Cache and Identity Maps]). + +==== Refreshing + +Consider how your application architecture may be affected by stale data +(see +link:Introduction%20to%20Cache%20(ELUG)#Handling_Stale_Data[Handling +Stale Data]): for example, consider using query or descriptor +link:#Refreshing[refresh options]) or +link:Introduction%20to%20Cache%20(ELUG)[Cache Invalidation], consider +using an isolated session’s cache (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated_Client_Sessions[Isolated +Client Sessions]) for volatile data. + +Avoid using link:Introduction%20to%20Cache%20(ELUG)#No_Identity_Map[No +Identity Map] for objects that are involved in relationships or that +require object identity. + +==== [#Cache-Coordination1]#Cache Coordination# + +EclipseLink provides a distributed cache coordination feature that +allows multiple, possibly distributed, instances of a session to +broadcast object changes among each other so that each session’s cache +is kept up to date (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]). Before using cache coordination, ensure that it is +appropriate for your application (see +link:Introduction%20to%20Cache%20(ELUG)#When_to_Use_Cache_Coordination[When +to Use Cache Coordination]). + +===== Protocol + +You can configure a coordinated cache to broadcast changes using any of +the following communication protocols: + +* Java Message Service (JMS) – We recommend using a +link:Introduction%20to%20Cache%20(ELUG)#JMS_Coordinated_Cache[JMS +Coordinated Cache]. +* Remote Method Invocation (RMI) – We recommend that you use RMI cache +coordination only if you require +link:Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring_the_Synchronous_Change_Propagation_Mode[synchronous +change propagation]. For more information, see +link:Introduction%20to%20Cache%20(ELUG)#RMI_Coordinated_Cache[RMI +Coordinated Cache]. +* Common Object Request Broker Architecture (CORBA) – Currently, +EclipseLink provides support for the Sun ORB (see +link:Introduction%20to%20Cache%20(ELUG)#CORBA_Coordinated_Cache[CORBA +Coordinated Cache]). + +===== Synchronization + +You can configure synchronization strategy that a coordinated cache uses +to determine what it broadcasts when an object changes. You can +configure this at the +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Project_Level[project +level] or +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Coordination_Change_Propagation_at_the_Descriptor_Level[descriptor +level] level as follows: + +* Invalidate changed objects – Propagate an object invalidation that +marks the object as invalid in all other sessions. This tells other +sessions that they must update their cache from the data source the next +time this object is read. We recommend using this synchronization +strategy. +* Synchronize changes – Propagate a change notification that contains +each changed attribute. +* Synchronize changes and new objects – Propagate a change notification +that contains each changed attribute. For new objects, propagate an +object creation (along with all the new instance’s attributes). + +=== Locking + +This section describes choices you need to make when deciding on how to +use EclipseLink locking options in your application architecture. We +strongly recommend always using a locking policy in a concurrent system +(see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]). + +These choices can be summarized as follows: + +* link:#Optimistic_Locking[Optimistic Locking] +* link:#Pessimistic_Locking[Pessimistic Locking] + +If you are building a three-tier application, be aware of how that +architecture affects the way you use locking (see +link:Introduction%20to%20Descriptors%20(ELUG)#Locking_in_a_Three-Tier_Application[Locking +in a Three-Tier Application]). + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Locking[Descriptors +and Locking]. + +==== Optimistic Locking + +We recommend using EclipseLink optimistic locking. With optimistic +locking, all users have read access to the data. When a user attempts to +write a change, the application checks to ensure the data has not +changed since the user read the data. + +You can use +link:Introduction%20to%20Descriptors%20(ELUG)#Optimistic_Version_Locking_Policies[Optimistic +Version Locking] or +link:Introduction%20to%20Descriptors%20(ELUG)#Optimistic_Field_Locking_Policies[Optimistic +Field Locking] locking policies. We recommend using version locking +policies. + +==== Pessimistic Locking + +With pessimistic locking, the first user who accesses the data with the +purpose of updating it locks the data until completing the update. The +disadvantage of this approach is that it may lead to reduced concurrency +and deadlocks. + +Consider using pessimistic locking support at the query level (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]). + +== Building and Using the Persistence Layer + +EclipseLink requires that classes must meet certain minimum requirements +before they can become persistent. EclipseLink also provides +alternatives to most requirements. EclipseLink uses a nonintrusive +approach by employing a metadata architecture that allows for minimal +object model intrusions. + +This section includes the following information: + +* link:#Implementation_Options[Implementation Options] +* link:#Persistent_Class_Requirements[Persistent Class Requirements] +* link:#Persistence_Layer_Components[Persistence Layer Components] +* link:#How_to_Use_the_Persistence_Layer[How to Use the Persistence +Layer] + +=== Implementation Options + +When implementing your persistence layer using EclipseLink, consider the +following options: + +* link:#Using_EclipseLink_JPA_Metatdata,_Annotations,_and_XML[Using +EclipseLink JPA Metatdata, Annotations, and XML] +* link:#Using_EclipseLink_Metatdata_XML[Using EclipseLink Metatdata XML] +* link:#Using_EclipseLink_Metadata_Java_API[Using EclipseLink Metadata +Java API] +* link:#Using_Method_and_Direct_Field_Access[Using Method and Direct +Field Access] +* link:#Using_Weaving_Technique[Using Weaving Technique] + +==== Using EclipseLink JPA Metatdata, Annotations, and XML + +We recommend using JPA metadata. + +When using JPA, you can specify persistence layer components using any +combination of standard JPA annotations and `+persistence.xml+`, +EclipseLink JPA annotation extensions, and EclipseLink JPA +`+persistence.xml+` extensions. + +For more information, see the following: + +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Introduction_to_Java_Persistence_API[Introduction +to Java Persistence API] +* link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)[Introduction to +EclipseLink JPA] + +==== Using EclipseLink Metatdata XML + +Persistence layer components may be generated as metadata from the +Workbench. + +When using the native API, we recommend using the Workbench to create +the necessary metadata (stored as XML). You can easily export and update +the `+project.xml+` and `+sessions.xml+` files. This reduces development +effort by eliminating the need to regenerate and recompile Java code +each time you change the project. With Workbench, you write Java code +only for your own application classes and any necessary amendment +methods. For information about the XML structure of the `+project.xml+` +and `+sessions.xml+` files, refer to the appropriate XML schemas (XSD) +in the _`+ECLIPSELINK_HOME+`_`+/xsds+` directory. + +Workbench provides Ant tasks that you can use to integrate Workbench +with your automated builds. + +For more information, see the following: + +* link:#Working_with_EclipseLink_Metadata[Working with EclipseLink +Metadata] +* link:Using%20Workbench%20(ELUG)#Integrating_Workbench_with_Apache_Ant[Integrating +Workbench with Apache Ant] + +==== Using EclipseLink Metadata Java API + +Persistence layer components may be coded or generated as Java from +Workbench. + +To use Java code, you must manually write code for each element of the +EclipseLink project including: project, login, platform, descriptors, +and mappings. This may be more efficient if your application is +model-based and relies heavily on code generation. Depending on the type +of project you are creating, the Workbench can export Java code for +projects, tables, and your model source. + +EclipseLink provides Ant tasks that you can use to integrate Workbench +with your automated builds. + +For more information, see the following: + +* link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information] +* link:Using%20Workbench%20(ELUG)#Integrating_Workbench_with_Apache_Ant[Integrating +Workbench with Apache Ant] + +==== Using Method and Direct Field Access + +You can configure EclipseLink to access the fields (data members) of a +class by using a getter/setter method (also known as property access) or +by accessing the field itself directly. We recommend using field access. + +When considering using method or direct field access in EclipseLink, +consider the following. + +If you use method access in EclipseLink, ensure you have no side effects +in the getter/setter methods used for persistence. Setter methods that +set the inverse relationship, or that access the value being sent can +disable optimizations such as lazy loading, and can potentially corrupt +your object model. If you require side effects in your getter/setter +methods, consider using separate methods for persistence than your +application uses, or use field access. + +If you enable change tracking for your class and use method acess, then +EclipseLink tracks changes accordingly when the setter methods are +called. If you access the field directly, EclipseLink may not detect the +change (EclipseLink will detect the changes made within the class if the +field is named the same as the property, but not direct field changes +made from external classes). + +Similarly, if you enable change tracking for your class and use field +access, then EclipseLink tracks changes accordingly when the field is +set within the class (direct field changes made from external classes +are not detected). + +For more information, see the following: + +* link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Configuring +Method or Direct Field Access at the Project Level] +* link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level] +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Unit_of_Work_and_Change_Policy[Unit +of Work and Change Policy] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@ChangeTracking_Annotation[How +to Use the @ChangeTracking Annotation] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[Configuring +Change Policy] + +==== Using Weaving Technique + +Weaving is a technique of manipulating the byte-code of compiled Java +classes. + +EclipseLink uses weaving to enhance both JPA entities and Plain Old Java +Object (POJO) classes for such things as lazy loading, change tracking, +fetch groups, and internal optimizations. + +For more information, see link:#Using_Weaving[Using Weaving]. + +=== Persistent Class Requirements + +The following requirements apply to plain Java objects: + +* You can use direct access on private or protected attributes. For +more, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]. +* When using _nontransparent_ indirection, the attributes must be of the +type`+ValueHolderInterface+` rather than the original attribute type. +The value holder does not instantiate a referenced object until it is +needed. +* EclipseLink provides _transparent_ indirection for `+Collection+`, +`+List+`, `+Set+`, and `+Map+` attribute types for any collection +mappings. Using transparent indirection does not require the use of the +`+ValueHolderInterface+` or any other object model requirements. + +If you are using weaving, the `+ValueHolderInterface+` is not required. +For more information, see link:#Using_Weaving[Using Weaving]. + +See +link:Introduction%20to%20Mappings%20(ELUG)#Indirection_(Lazy_Loading)[Indirection +(Lazy Loading)] for more information on indirection and transparent +indirection. + +=== Persistence Layer Components + +Typically, the EclipseLink persistence layer contains the following +components: + +* link:#Mapping_Metadata[Mapping Metadata] +* link:#session1[Session] +* link:#Cache[Cache] +* link:#Queries_and_Expressions[Queries and Expressions] +* link:#Transactions[Transactions] + +==== Mapping Metadata + +The EclipseLink application metadata model is based on the EclipseLink +project. The project includes descriptors, mappings, and various +policies that customize the run-time capabilities. You associate this +mapping and configuration information with a particular data source and +application by referencing the project from a session. + +For more information, see the following: + +* link:#Creating_Project_Metadata[Creating Project Metadata] +* link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects] +* link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] + +==== [#session1]#Session# + +A session is the primary interface between the client application and +EclipseLink, and represents the connection to the underlying data +source. + +EclipseLink offers +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[several +different session types], each optimized for different design +requirements and architectures. The most commonly used session is the +server session, a session that clients access on the server through a +client session. The server session provides a shared cache and shared +connection resources. You define a session with session metadata. + +For EclipseLink JPA projects, the `+EntityManager+` represents (wraps) +the EclipseLink session. + +For more information, see the following: + +* link:#Creating_Session_Metadata[Creating Session Metadata] +* link:#How_to_Use_the_Persistence_Layer[How to Use the Persistence +Layer] + +==== Cache + +By default, an EclipseLink session provides an object-level cache that +guarantees object identity and enhances performance by reducing the +number of times the application needs to access the data source. +EclipseLink provides a variety of cache options, including locking, +refresh, invalidation, isolation, and coordination. Using cache +coordination, you can configure EclipseLink to synchronize changes with +other instances of the deployed application. You configure most cache +options at the session level. You can also configure cache options on a +per-query basis or on a descriptor to apply to all queries on the +reference class. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +==== Queries and Expressions + +EclipseLink provides several object and data query types, and offers +flexible options for query selection criteria, including the following: + +* EclipseLink expressions +* JPQL (Java Persistence Query Language) +* SQL +* Stored procedures +* Query by example + +With these options, you can build any type of query. We recommend using +named queries over dynamic application queries. Named queries are held +in the project metadata and referenced by name. This simplifies +application development and encapsulates the queries to reduce +maintenance costs. + +Regardless of the architecture or persistent entity type, you are free +to use any of the query options. Queries can be defined through JPA +annotations, XML or code. If using the native EclipseLink metadata the +Workbench provides the simplest way to define queries. Alternatively, +you can build queries in code, using the EclipseLink API. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Introduction to +EclipseLink Queries] and +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions]. + +==== Transactions + +EclipseLink provides the ability to write transactional code isolated +from the underlying database and schema by using a *unit of work*, a +specific transactional session. + +The unit of work isolates changes in a transaction from other threads +until it successfully commits the changes to the database. Unlike other +transaction mechanisms, the unit of work automatically manages changes +to the objects in the transaction, the order of the changes, and changes +that might invalidate other EclipseLink caches. The unit of work manages +these issues by calculating a minimal change set, ordering the database +calls to comply with referential integrity rules and deadlock avoidance, +and merging changed objects into the shared cache. In a clustered +environment, the unit of work also synchronizes changes with the other +servers in the coordinated cache. + +If an application uses JPA, you do not access the unit of work API +directly, but you still benefit from its’ features: the integration +between the EclipseLink runtime and JPA transactions or JTA transactions +use the unit of work to the application’s best advantage. + +For more information, see +link:Introduction_to_EclipseLink_Transactions_%28ELUG%29[Introduction to +EclipseLink Transactions]. + +=== How to Use the Persistence Layer + +At run time, your application uses the EclipseLink metadata (see +link:#Working_with_EclipseLink_Metadata[Working with EclipseLink +Metadata]). + +For a JPA project, your application loads a `+persistence.xml+` file at +run time using the `+Persistence+` class, or injection. Using the +EntityManager, your application accesses the EclipseLink runtime and the +mapping metadata. + +For a POJO project using the native API, your application loads a +`+sessions.xml+` file at run time using the session manager (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_and_Using_Sessions_at_Run_Time[Acquiring +and Using Sessions at Run Time]). The `+sessions.xml+` file contains a +reference to the mapping metadata `+project.xml+` file. Using the +session, your application accesses the EclipseLink runtime and the +`+project.xml+` mapping metadata. + +== Deploying the Application + +Application packaging (for deployment in the host Java or Java EE +environment) influences EclipseLink use and configuration. For example, +you package a Java EE application in an EAR file. Within the EAR file, +there are several ways to package persistent entities within WAR and +JAR. How you configure EclipseLink depends, in part, on how you package +the application and how you use the class loader of the host application +server. + +This section discusses packaging and deployment from an EclipseLink +perspective. However, if you deploy your application to a Java EE +container, you must configure elements of your application to enable +EclipseLink container support. + +This section includes the following information: + +* link:#About_Deployments[About Deployments] +* link:#How_to_Use_EclipseLink_in_a_Java_EE_Application[How to Use +EclipseLink in a Java EE Application] + +For more information, see +link:EclipseLink_UserGuide_Overview_of_EclipseLink_Application_Deployment_%28ELUG%29[Overview +of EclipseLink Application Deployment]. + +=== About Deployments + +The EclipseLink approach to deployment involves packaging application +files into a single file, such as a JAR file, or an EAR file. This +approach lets you create clean and self-contained deployments that do +not require significant file management. + +After creating these files, deploy the project. + +=== How to Use EclipseLink in a Java EE Application + +The typical deployment process involves the following steps: + +[arabic] +. Build the project elements, including beans, classes, and data +sources. +. Define the application mappings in JPA annotations or XML, or native +metadata using the Workbench. +. Build the application deployment files. +. Package and deploy the application. +. Add code to the client application to enable it to access the +EclipseLink application. + +== Optimizing and Customizing the Application + +EclipseLink provides a diverse set of features to optimize performance +including the following: + +* Enhancing queries +* Tuning the cache +* Scaling to multiple server configuration + +You enable or disable most features in the descriptors or session, +making any resulting performance gains global. + +Using link:#Enterprise_Information_System_(EIS)_Usage[EclipseLink EIS], +you can integrate an EclipseLink application with legacy data sources +using a JCA adapter. This is the most efficient way to customize an +EclipseLink application to accommodate unusual or nonstandard systems. + +Using link:#XML_Usage[EclipseLink XML], you can integrate an EclipseLink +application with legacy data sources using a Web service. + +See +link:EclipseLink_UserGuide_Optimizing_and_Customizing_an_EclipseLink_Application_(ELUG)[Optimization +and Customization of an EclipseLink Application] for details on +optimizing and customizing EclipseLink. + +== Troubleshooting the Application + +See for information on troubleshooting all aspects of an EclipseLink +application including development and deployment. + +== Persisting Objects + +This section includes a brief description of relational mapping and +provides important information and restrictions to guide object and +relational modeling. This information is useful when building +EclipseLink applications. + +This section includes information on the following: + +* link:#Application_Object_Model[Application Object Model] +* link:#Data_Storage_Schema[Data Storage Schema] +* link:#Primary_Keys_and_Object_Identity[Primary Keys and Object +Identity] +* link:#Mappings1[Mappings] +* link:#Foreign_Keys_and_Object_Relationships[Foreign Keys and Object +Relationships] +* link:#Inheritance1[Inheritance] +* link:#Concurrency1[Concurrency] +* link:#Caching[Caching] +* link:#Nonintrusive_Persistence[Nonintrusive Persistence] +* link:#Indirection1[Indirection] +* link:#Mutability[Mutability] + +These sections contain additional detail on these features, and explain +how to implement and use them with EclipseLink. + +=== Application Object Model + +Object modeling refers to the design of the Java classes that represent +your application objects. With EclipseLink, you can use your favorite +integrated development environment (IDE) or Unified Modeling Language +(UML) modeling tool to define and create your application object model. + +Any class that registers a descriptor with an EclipseLink database +session is called a persistent class. EclipseLink does not require that +persistent classes provide public accessor methods for any private or +protected attributes stored in the database. Refer to +link:#Persistent_Class_Requirements[Persistent Class Requirements] for +more information. + +=== Data Storage Schema + +Your data storage schema refers to the design that you implement to +organize the persistent data in your application. This schema refers to +the data itself–not the actual data source (such as a relational +database or nonrelational legacy system). + +During the design phase of the EclipseLink application development +process (see link:#Typical_Development_Stages[Typical Development +Stages]), you should decide how to implement the classes in the data +source. When integrating existing data source information, you must +determine how the classes relate to the existing data. If no legacy +information exists to integrate, decide how you will store each class, +then create the necessary schema. + +You can also link:Using%20Workbench%20(ELUG)[use the Workbench] or +link:Using%20the%20Schema%20Manager%20(ELUG)[database schema manager] to +create the necessary information. If using JPA you can have the schema +created automatically when you first access your application. + +=== Primary Keys and Object Identity + +When making objects persistent, each object requires an _identity_ to +uniquely identify it for storage and retrieval. Object identity is +typically implemented using a unique primary key. This key is used +internally by EclipseLink to identify each object, and to create and +manage references. Violating object identity can corrupt the object +model. + +In a Java application, object identity is preserved if each object in +memory is represented by one, and only one, object instance. Multiple +retrievals of the same object return references to the same object +instance–not multiple copies of the same object. + +EclipseLink supports multiple identity maps to maintain object identity +(including composite primary keys). Refer to +link:Introduction%20to%20Cache%20(ELUG)#Cache_Type_and_Object_Identity[Cache +Type and Object Identity] for additional information. + +=== [#Mappings1]#Mappings# + +EclipseLink uses the metadata produced by the Workbench (see +link:#Working_with_EclipseLink_Metadata[Working with EclipseLink +Metadata]) to describe how objects and beans map to the data source. +This approach isolates persistence information from the object model–you +are free to design their ideal object model, and DBAs are free to design +their ideal schema. + +You use the Workbench to create and manage the mapping information. At +run time, EclipseLink uses the metadata to seamlessly and dynamically +interact with the data source, as required by the application. + +EclipseLink provides an extensive mapping hierarchy that supports the +wide variety of data types and references that an object model might +contain. For more information, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings]. + +=== Foreign Keys and Object Relationships + +A *foreign key* is a combination of columns that reference a unique key, +usually the primary key, in another table. Foreign keys can be any +number of fields (similar to primary key), all of which are treated as a +unit. A foreign key and the primary parent key it references must have +the same number and type of fields. + +Foreign keys represents relationships from a column or columns in one +table to a column or columns in another table. For example, if every +`+Employee+` has an attribute `+address+` that contains an instance of +`+Address+` (which has its own descriptor and table), the one-to-one +mapping for the `+address+` attribute would specify foreign key +information to find an address for a particular `+Employee+`. + +Refer to +link:Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring_Table_and_Field_References_(Foreign_and_Target_Foreign_Keys)[Configuring +Table and Field References (Foreign and Target Foreign Keys)] for more +information. + +=== [#Inheritance1]#Inheritance# + +Object-oriented systems allow classes to be defined in terms of other +classes. For example: motorcycles, sedans, and vans are all _kinds of +vehicles_. Each of the vehicle types is a _subclass_ of the `+Vehicle+` +class. Similarly, the `+Vehicle+` class is the _superclass_ of each +specific vehicle type. Each subclass inherits attributes and methods +from its superclass (in addition to having its own attributes and +methods). + +Inheritance provides several application benefits, including the +following: + +* Using subclasses to provide specialized behaviors from the basis of +common elements provided by the superclass. By using inheritance, you +can reuse the code in the superclass many times. +* Implementing _abstract_ superclasses that define generic behaviors. +This abstract superclass may define and partially implement behavior, +while allowing you to complete the details with specialized subclasses. + +Refer to +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descripto[Configuring +Inheritance for a Child (Branch or Leaf) Class Descriptor] and +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inherited_Attribute_Mapping_in_a_Subclass[Configuring +Inherited Attribute Mapping in a Subclass] for detailed information on +using inheritance with EclipseLink. + +=== [#Concurrency1]#Concurrency# + +To have concurrent clients logged in at the same time, the server must +spawn a dedicated thread of execution for each client. Java EE +application servers do this automatically. Dedicated threads enable each +client to work without having to wait for the completion of other +clients. EclipseLink ensures that these threads do not interfere with +each other when they make changes to the identity map or perform +database transactions. Using the EclipseLink `+UnitOfWork+` class, your +client can make transactional changes in an isolated and thread safe +manner. The unit of work manages clones for the objects you modify to +isolate each client’s work from other concurrent clients and threads. +The unit of work is essentially an object-level transaction mechanism +that maintains all of the ACID (Atomicity, Consistency, Isolation, +Durability) transaction principles as a database transaction. For more +information on the unit of work, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. + +EclipseLink supports configurable optimistic and pessimistic locking +strategies to let you customize the type of locking that the EclipseLink +concurrency manager uses. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Locking[Descriptors +and Locking]. + +=== Caching + +EclipseLink caching improves application performance by automatically +storing data returned as objects from the database for future use. This +caching provides several advantages: + +* Reusing Java objects that have been previously read from the database +minimizes database access +* Minimizing SQL calls to the database when objects already exist in the +cache +* Minimizing network access to the database +* Setting caching policies a class-by-class and bean-by-bean basis +* Basing caching options and behavior on Java garbage collection + +EclipseLink supports several caching polices to provide extensive +flexibility. You can fine-tune the cache for maximum performance, based +on individual application performance. Refer to +link:EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG)[Cache] for +more information. + +=== Nonintrusive Persistence + +The EclipseLink nonintrusive approach of achieving persistence through a +metadata architecture (see +link:#Working_with_EclipseLink_Metadata[Working with EclipseLink +Metadata]) means that there are almost no object model intrusions. + +To persist Java objects, EclipseLink does not require any of the +following: + +* Persistent superclass or implementation of persistent interfaces +* Store, delete, or load methods required in the object model +* Special persistence methods +* Generating source code into or wrapping the object model + +See link:#Building_and_Using_the_Persistence_Layer[Building and Using +the Persistence Layer] for additional information on this nonintrusive +approach. + +=== [#Indirection1]#Indirection# + +An indirection object takes the place of an application object so the +application object is not read from the database until it is needed. +Using indirection, or lazy loading in JPA, allows EclipseLink to create +_stand-ins_ for related objects. This results in significant performance +improvements, especially when the application requires the contents of +only the retrieved object rather than all related objects. + +Without indirection, each time the application retrieves a persistent +object, it also retrieves _all_ the objects referenced by that object. +This may result in lower performance for some applications. + +[cols="<",] +|=== +|*Note:* We recommend that you use indirection in all situations. +|=== + +EclipseLink provides several indirection models, such as proxy +indirection, transparent indirection, and value holder indirection. + +See +link:Introduction%20to%20Mappings%20(ELUG)#Indirection_(Lazy_Loading)[Indirection +(Lazy Loading)] for more information. + +=== Mutability + +Mutability is a property of a complex field that specifies whether or +not the field value may be changed or not changed as opposed to +replaced. + +An immutable mapping is one in which the mapped object value cannot +change unless the object ID of the object changes: that is, unless the +object value is replaced by another object value altogether. + +A mutable mapping is one in which the mapped object value can change +without changing the object ID of the object. + +By default, EclipseLink assumes the following: + +* all `+TransformationMapping+` instances are mutable; +* all JPA `+@Basic+` mapping types, except `+Serializable+` types, are +immutable (including `+Date+` and `+Calendar+` types); +* all JPA `+@Basic+` mapping `+Serializable+` types are mutable. + +Whether a value is immutable or mutable largely depends on how your +application uses your persistent classes. For example, by default, +EclipseLink assumes that a persistent field of type `+Date+` is +immutable: this means that as long as the value of the field has the +same object ID, EclipseLink assumes that the value has not changed. If +your application uses the set methods of the `+Date+` class, you can +change the state of the `+Date+` object value without changing its +object ID. This prevents EclipseLink from detecting the change. To avoid +this, you can configure a mapping as mutable: this tells EclipseLink to +examine the state of the persistent value, not just its object ID. + +You can configure the mutability of the following: + +* `+TransformationMapping+` instances; +* any JPA `+@Basic+` mapping type (including `+Date+` and `+Calendar+` +types) individually; +* all `+Date+` and `+Calendar+` types. + +Mutability can affect change tracking performance. For example, if a +transformation mapping maps a mutable value, EclipseLink must clone and +compare the value in a unit of work (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Configuring +Copy Policy]). If the mapping maps a simple immutable value, you can +improve unit of work performance by configuring mapping as immutable. + +Mutability also affects weaving. EclipseLink can only weave an attribute +change tracking policy for immutable mappings. + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Unit_of_Work_and_Change_Policy[Unit +of Work and Change Policy] +* link:#Using_Weaving[Using Weaving] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@Mutable_Annotation[How +to Use the @Mutable Annotation] +* link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Mutable_Mappings[Configuring +Mutable Mappings] + +== Working with EclipseLink Metadata + +The EclipseLink metadata is the bridge between the development of an +application and its deployed run-time environment. Capture the metadata +using: + +* JPA annotations, `+persistence.xml+`, `+orm.xml+`, and EclipseLink JPA +annotation and `+persistence.xml+` property extensions: the EclipseLink +JPA persistence provider interprets all these sources of metadata to +create an in-memory EclipseLink session and project at run time. +* The Workbench (see link:#Creating_Project_Metadata[Creating Project +Metadata] and link:#Creating_Session_Metadata[Creating Session +Metadata]) to create EclipseLink `+sessions.xml+` and `+project.xml+` +files which you pass to the EclipseLink run-time environment. +* Java and the EclipseLink API (this approach is the most +labor-intensive). + +The metadata lets you pass configuration information into the run-time +environment. The run-time environment uses the information in +conjunction with the persistent classes (Java objects, JPA entities, or +EJB entity beans) and the code written with the EclipseLink API, to +complete the application. + +Using EclipseLink JPA, you also have the option of specifying your +metadata using EclipseLink `+sessions.xml+` and `+project.xml+` while +accessing your persistent classes using JPA and an `+EntityManger+`. For +more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]. + +[#Figure 2-2]## *_EclipseLink Metadata_* + +.EclipseLink Metadata +image::meta.gif[EclipseLink Metadata,title="EclipseLink Metadata"] + +This section describes the following: + +* link:#Advantages_of_the_EclipseLink_Metadata_Architecture[Advantages +of the EclipseLink Metadata Architecture] +* link:#Creating_Project_Metadata[Creating Project Metadata] +* link:#Creating_Session_Metadata[Creating Session Metadata] +* link:#Deploying_Metadata[Deploying Metadata] + +=== Advantages of the EclipseLink Metadata Architecture + +The EclipseLink metadata architecture provides many important benefits, +including the following: + +* Stores mapping information in XML descriptors–not in the domain model +objects +* By using the metadata, EclipseLink does not intrude in the object +model or the database schema +* Allows you to design the object model as needed, without forcing any +specific design +* Allows DBAs to design the database as needed, without forcing any +specific design +* Does not rely on code-generation (which can cause serious design, +implementation, and maintenance issues) +* Is unintrusive: adapts to the object model and database schema, rather +than requiring you to design their object model or database schema to +suit EclipseLink + +Using EclipseLink JPA, you have the flexibility of expressing +persistence metadata using standard JPA annotations, deployment XML, or +both and you can optionally take advantage of EclipseLink JPA annotation +and persistence.xml property extensions. + +=== Creating Project Metadata + +An EclipseLink project contains the mapping metadata that the +EclipseLink runtime uses to map objects to a data source. The project is +the primary object used by the EclipseLink runtime. + +This section describes the principal contents of project metadata, +including the following: + +* link:#Descriptors_and_Mappings[Descriptors and Mappings] +* link:#Data_Source_Login_Information[Data Source Login Information] + +Using EclipseLink JPA, the EclipseLink runtime constructs an in-memory +project based on any combination of JPA annotations, +`+persistence.xml+`, `+orm.xml+`, and EclipseLink JPA annotation and +`+persistence.xml+` property extensions. The use of a `+project.xml+` +file is optional (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]). + +For more information about creating `+project.xml+` metadata, see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File]. + +==== Descriptors and Mappings + +EclipseLink maps persistent entities to the database in the application, +using the descriptors and mappings you build with theWorkbench. These +tools support several approaches to project development, including the +following: + +* Importing classes and tables for mapping +* Importing classes and generating tables and mappings +* Importing tables and generating classes and mappings +* Creating both class and table definitions + +Workbench supports all these options. The most common solution is to +develop the persistent entities using a development tool, such as an +integrated development environment (IDE), or a modeling tool, and to +develop the relational model through appropriate relational design +tools. You then use the Workbench to construct mappings that relate +these two models. + +Although the Workbench offers the ability to generate persistent +entities or the relational model components for an application, this +utilities are intended only to assist in rapid initial development +strategies–not complete round-trip application development. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] and link:Introduction%20to%20Mappings%20(ELUG)[Introduction +to Mappings]. + +===== Amending Descriptors + +An amendment method lets you implement an EclipseLink feature that is +not currently supported by the Workbench. Simply write a Java method to +amend the descriptor after it is loaded, and specify the method in the +Workbench for inclusion in the project metadata. See +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods] for detailed information on implementing an amendment +method for an EclipseLink descriptor. + +==== Data Source Login Information + +For POJO projects, you configure a session login in the session metadata +that specifies the information required to access the data source (see +link:#Creating_Session_Metadata#Creating_Session_Metadata[Creating +Session Metadata]). + +For more information, see +link:Introduction%20to%20Projects_(ELUG)#Projects_and_Login[Projects and +Login]. + +=== Creating Session Metadata + +An EclipseLink session contains a reference to a particular +`+project.xml+` file, plus the information required to access the data +source. The session is the primary object used by your application to +access the features of the EclipseLink runtime. In a POJO project, your +application acquires and accesses a session directly (see +link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#POJO_Applications_and_Session_Metadata[POJO +Applications and Session Metadata]). + +Using EclipseLink JPA, the EclipseLink runtime constructs an in-memory +session based on any combination of JPA annotations, +`+persistence.xml+`, `+orm.xml+`, and EclipseLink JPA annotation and +`+persistence.xml+` property extensions. The use of a `+sessions.xml+` +file is optional (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]). + +=== Deploying Metadata + +The `+project.xml+` and `+sessions.xml+` file are packaged for +deployment differently according to the type of application you are +deploying. + +For more information, see the following: + +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] +* link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging an +EclipseLink Application] + +Using EclipseLink JPA, you also have the option of specifying your +metadata using EclipseLink `+sessions.xml+` and `+project.xml+` while +accessing your persistent classes using JPA and an `+EntityManger+`. For +more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms[What +You May Need to Know About EclipseLink JPA Overriding Mechanisms]. + +== Using Weaving + +Weaving is a technique of manipulating the byte-code of compiled Java +classes. EclipseLink uses weaving to enhance both JPA entities and Plain +Old Java Object (POJO) classes for such things as lazy loading, change +tracking, fetch groups, and internal optimizations. + +This section describes the following: + +* link:#Configuring_Dynamic_Weaving_Using_the_EclipseLink_Agent[Configuring +Dynamic Weaving Using the EclipseLink Agent] +* link:#Configuring_Static_Weaving[Configuring Static Weaving] +* link:#Disabling_Weaving_Using_EclipseLink_Persistence_Unit_Properties[Disabling +Weaving Using EclipseLink Persistence Unit Properties] +* link:#Packaging_a_POJO_Application_for_Weaving[Packaging a POJO +Application for Weaving] +* link:#What_You_May_Need_to_Know_About_Weaving_and_POJO_Classes[What +You May Need to Know About Weaving and POJO Classes] +* link:#What_You_May_Need_to_Know_About_Weaving_and_Java_EE_Application_Servers[What +You May Need to Know About Weaving and Java EE Application Servers] + +=== Configuring Dynamic Weaving Using the EclipseLink Agent + +Use this option to weave applicable class files one at a time, as they +are loaded at run time. For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Configure_Dynamic_Weaving_for_JPA_Entities_Using_the_EclipseLink_Agent[How +to Configure Dynamic Weaving for JPA Entities Using the EclipseLink +Agent]. + +==== To Configure Dynamic Weaving Using the EclipseLink Agent + +For information, see the following: + +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#To_Configure_Dynamic_Weaving_for_JPA_Entities_Using_the_EclipseLink_Agent[To +Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent] +* link:#Packaging_a_POJO_Application_for_Weaving[Packaging a POJO +Application for Weaving] + +=== Configuring Static Weaving + +Consider this option to weave all applicable class files at build time +so that you can deliver prewoven class files. For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Configure_Static_Weaving_for_JPA_Entities[How +to Configure Static Weaving for JPA Entities]. + +Alternatively, you can weave classes at run time. For more information, +see +link:#Configuring_Dynamic_Weaving_Using_the_EclipseLink_Agent[Configuring +Dynamic Weaving Using the EclipseLink Agent]. + +Note that for weaving, you use a `+persistence.xml+` file in both JPA +and POJO applications. + +For information on packaging and deployment of POJO applications, see +link:#Packaging_a_POJO_Application_for_Weaving[Packaging a POJO +Application for Weaving]. + +=== Disabling Weaving Using EclipseLink Persistence Unit Properties + +To disable weaving, you use persistence unit properties in both JPA and +POJO applications. For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Disable_Weaving_Using_EclipseLink_Persistence_Unit_Properties[How +to Disable Weaving Using EclipseLink Persistence Unit Properties]. + +For information on packaging and deployment of POJO application, see +link:#Packaging_a_POJO_Application_for_Weaving[Packaging a POJO +Application for Weaving]. + +=== Packaging a POJO Application for Weaving + +To package a POJO application for weaving, you create a JAR that +contains a `+sessions.xml+` file and a `+persistence.xml+` file. + +==== To Package a POJO Application for Weaving + +[arabic] +. For any one to one or many to one relationship you want to be woven +for lazy loading, enable ValueHolder indirection. +. Create a `+sessions.xml+` file for your application. For more +information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Introduction to +EclipseLink Sessions]. +. Create a `+persistence.+`xml file for your application and reference +your `+sessions.xml+` file, as the following example shows. +[#Example 2-8]##*_persistence.xml File for an EclipseLink JPA +Application_* ++ ++ ++ +`+    +` `+        +``+false+` `+        +` ++ +`+            +` `+            +` `+        +` `+    +` ++ +. Create a JAR file that contains your POJO classes, +`+project deployment+` XML file (the specific name is user +defined),`+sessions.xml+` file, and `+persistence.xml+` file, as the +following example shows. Put the `+project deployment XML+`, +`+persistence.xml+` and `+sessions.xml+` files in a `+META-INF+` +directory. [#Example 2-9]## *_JAR File for a POJO Application_* ++ +`+appname.jar+` `+    META-INF+` `+        persistence.xml+` +`+        sessions.xml+` `+        project.xml+` `+    *.java+` +. Weave the JAR. For more information, see the following: +* link:#Configuring_Dynamic_Weaving_Using_the_EclipseLink_Agent[Configuring +Dynamic Weaving Using the EclipseLink Agent] +* link:#Configuring_Static_Weaving[Configuring Static Weaving] + +=== What You May Need to Know About Weaving and POJO Classes + +EclipseLink uses weaving to enable the following for POJO classes: + +* link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[lazy +loading (indirection)] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +tracking] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Fetch_Groups[fetch +groups] +* internal optimizations. + +EclipseLink weaves all the POJO classes in the JAR you create when you +package a POJO application for weaving. For more information, see +link:#Packaging_a_POJO_Application_for_Weaving[Packaging a POJO +Application for Weaving]. + +EclipseLink weaves all the classes defined in the `+persistence.xml+` +file. That is the following: + +* all the classes you list in the persistence.xml file; +* all classes relative to the JAR containing the `+persistence.xml+` +file if element is `+false+`. + +=== What You May Need to Know About Weaving and Java EE Application Servers + +The default EclipseLink weaving behavior applies in any Java EE +JPA-compliant application server using the EclipseLink JPA persistence +provider.To change this behavior, modify your `+persistence.xml+` (for +your JPA entities or POJO classes) to use EclipseLink JPA properties, +EclipseLink JPA annotations, or both. + +For lazy loading (indirection) differences between Java EE and Java SE +applications, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#EclipseLink_JPA_Support_for_Lazy_Loading_by_Mapping_Type[EclipseLink +JPA Support for Lazy Loading by Mapping Type]. + +== Considering Three-Tier Architecture + +The three-tier Web application architecture generally includes the +connection of a server-side Java application to the database through a +JDBC connection (see the link:#Figure_2-3[Three Tier Architecture] +figure). In this pattern, EclipseLink resides within a Java server (a +Java EE server or a custom server), with several possible server +integration points. The application can support Web clients such as +servlets, Java clients, and generic clients using XML or Common Object +Request Broker Architecture (CORBA). + +The three-tier application is a common architecture in which EclipseLink +resides within a Java server (either a Java EE server or a custom +server). In this architecture, the server session provides clients with +shared access to JDBC connections and a shared object cache. Because it +resides on a single JVM, this architecture is simple and easily +scalable. The EclipseLink persistent entities in this architecture are +generally Java objects. + +This architecture often supports Web-based applications in which the +client application is a Web client, a Java client, or a server +component. + +{empty}[#Figure 2-3]## *_Three Tier Architecture_* +image:threetierov.gif[Three Tier +Architecture,title="Three Tier Architecture"] + +Although not all three-tier applications are Web-based, this +architecture is ideally suited to distributed Web applications. In +addition, although it is also common to use EJB in a Web application, +this EclipseLink architecture does not. + +=== [#Example-Implementations1]#Example Implementations# + +Examples of three-tier architecture implementation include the +following: + +* A Model-View-Controller Model 2 architectural design pattern that runs +in a Java EE container with servlets and JSP that uses EclipseLink to +access data without EJB. +* A Swing or Abstract Window Toolkit (AWT) client that connects to a +server-side Java application through RMI, without an application server +or container. + +=== [#Advantages-and-Disadvantages1]#Advantages and Disadvantages# + +The three-tier Web application architecture offers the following +advantages: + +* High performance, lightweight persistent objects +* High degree of flexibility in deployment platform and configuration + +The disadvantage of this architecture is it is less standard than EJB. + +=== Variation Using Remote Sessions + +EclipseLink includes a session type called remote session. The session +offers the full session API and contains a cache of its own, but exists +on the client system rather than on the EclipseLink server. +Communications can be configured to use RMI or RMI-Internet Inter-Object +Request Broker Protocol (IIOP). + +Remote session operations require a corresponding client session on the +server. + +Although this is an excellent option for you if you wish to simplify the +access from the client tier to the server tier, it is less scalable than +using a client session and does not easily allow changes to server-side +behavior. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Remote_Sessions[Remote +Sessions]. + +=== [#Technical-Challenges1]#Technical Challenges# + +The three-tier application with a stateless client presents several +technical challenges, including the following: + +* Transaction management in a stateless environment A common design +practice is to delimit client requests within a single unit of work +(transactional session). In a stateless environment, this may affect how +you design the presentation layer. For example, if a client requires +multiple pages to collect information for a transaction, then the +presentation layer must retain the information from page to page until +the application accumulates the full set of changes or requests. At that +point, the presentation layer invokes the unit of work to modify the +database. +* Optimistic locking in a stateless environmentIn a stateless +environment, take care to avoid processing out-of-date (stale) data A +common strategy for avoiding stale data is to implement optimistic +locking, and store the optimistic lock values in the object. This +solution requires careful implementation if the stateless application +serializes the objects, or sends the contents of the object to the +client in an alternative format. In this case, transport the optimistic +lock values to the client in the HTTP contents of an edit page. You must +then use the returned values in any write transaction to ensure that the +data did not change while the client was performing its work. For more +information about locking, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. +* External JDBC pools By default, EclipseLink manages its own connection +pools. You can also configure EclipseLink to use connection pooling +offered by the host application server. This feature is useful for +shared connection pools and is required for JTA/JTS integration (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]). +* JTA/JTS Integration JTA and JTS are standard Java components that +enable sessions to participate in distributed transactions. You must +configure EclipseLink to use JTA/JTS to use session beans in the +architecture (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]). +* Cache coordination If you choose to use multiple servers to scale your +application, you may require EclipseLink +link:Introduction%20to%20Cache%20(ELUG)[Cache Coordination]. + +== Considering Two-Tier Architecture + +A two-tier application generally includes a Java client that connects +directly to the database through EclipseLink. The two-tier architecture +is most common in complex user interfaces with limited deployment. The +database session provides EclipseLink support for two-tier applications. + +For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Introduction to +EclipseLink Sessions]. + +{empty}[#Figure 2-4]## *_Two-Tier Architecture_* +image:dsessov.gif[Two-Tier Architecture,title="Two-Tier Architecture"] + +Although the two-tier architecture is the simplest EclipseLink +application pattern, it is also the most restrictive, because each +client application requires its own session. As a result, two-tier +applications do not scale as easily as other architectures. + +Two-tier applications are often implemented as user interfaces that +directly access the database (see link:#Figure_2-4[Two-Tier +Architecture]). They can also be non-interface processing engines. In +either case, the two-tier model is not as common as the three-tier +model. + +The following are key elements of an efficient two-tier (client-server) +architecture with EclipseLink: + +* Minimal dedicated connections from the client to the database +* An isolated object cache + +=== [#Example-Implementations2]#Example Implementations# + +An example of a two-tier architecture implementation is a Java user +interface (Swing/AWT) and batch data processing. + +=== [#Advantages-and-Disadvantages2]#Advantages and Disadvantages# + +The advantage of the two-tier design is its simplicity. The EclipseLink +database session that builds the two-tier architecture provides all the +EclipseLink features in a single session type, thereby making the +two-tier architecture simple to build and use. + +The most important limitation of the two-tier architecture is that it is +not scalable, because each client requires its own database session. + +=== [#Technical-Challenges2]#Technical Challenges# + +The current trend toward multitiered Web applications makes the two-tier +architecture less common in production systems, but no less viable. +Because there is no shared cache in a two-tier system, you risk +encountering stale data if you run multiple instances of the +application. This risk increases as the number of individual database +sessions increases. + +To minimize this problem, EclipseLink offers support for several data +locking strategies. These include pessimistic locking and several +variations of optimistic locking. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy]. + +== Considering EJB Session Bean Facade Architecture + +This architecture is an extension of the three-tier pattern, with the +addition of EJB session beans wrapping the access to the application +tier. Session beans provide public API access to application operations, +enabling you to separate the presentation tier from the application +tier. The architecture also lets you use session beans within a Java EE +container.This type of architecture generally includes JTA integration, +and serialization of data to the client. + +{empty}[#Figure 2-5]## *_Three-Tier Architecture Using Session Beans and +Java Objects_* image:sessbnov.gif[Three-Tier Architecture Using Session +Beans and Java +Objects,title="Three-Tier Architecture Using Session Beans and Java Objects"] + +A common extension to the three-tier architecture is to combine session +beans and persistent Java objects managed by EclipseLink. The resulting +application includes session beans and Java objects on an EclipseLink +three-tier architecture (see the link:#Figure_2-5[Three-Tier +Architecture Using Session Beans and Java Objects] figure). + +The three-tier architecture creates a server session and shares it +between the session beans in the application. When a session bean needs +to access an EclipseLink session, the bean obtains a client session from +the shared server session. This architecture has the following key +features: + +* Session beans delimit transactions. Configure EclipseLink to work with +a JTA system and its associated connection pool. +* Accessing the persistent objects on the client side causes them to be +serialized. Ensure that when the objects re-emerge on the server side, +they properly merge into the cache to maintain identity. + +=== Example Implementation + +An example of the EJB session bean facade architecture implementation is +a Model-View-Controller Model 2 architectural design pattern that runs +in a Java EE container with servlets and JSP and uses the session bean +enabled by EclipseLink to access data without EJB. + +=== [#Advantages-and-Disadvantages3]#Advantages and Disadvantages# + +The EJB session bean facade architecture is a popular and effective +compromise between the performance of persistent Java objects, and the +benefits of EJB for standardized client development and server +scalability. It offers the following advantages: + +* Less overhead than an EJB CMP application EclipseLink shares access to +the project, descriptor, and login information across the beans in the +application. +* Future compatibility with other servers This design isolates login and +EJB server-specific information from the beans, which lets you migrate +the application from one application server to another without major +recoding or rebuilding. +* Shared read cacheThis design offers increased efficiency by providing +a shared cache for reading objects. + +The key disadvantage of this model is the need to transport the +persistent model to the client. If the model involves complex object +graphs in conjunction with indirection (lazy loading), this can present +many challenges with inheritance, indirection, and relationships. + +=== What Are Session Beans + +Session beans model a process, operation, or service and as such, are +not persistent entities. However, session beans can use persistence +mechanisms to perform the services they model. + +Under the session bean model, a client application invokes methods on a +session bean that, in turn, performs operations on Java objects enabled +by EclipseLink. Session beans execute all operations related to +EclipseLink on behalf of the client. + +The EJB specifications describe session beans as either stateless or +stateful. + +* *Stateful beans* maintain a conversational state with a client; that +is, they retain information between method calls issued by a particular +client. This enables the client to use multiple method calls to +manipulate persistent objects. +* *Stateless beans* do not retain data between method calls. When the +client interacts with stateless session beans, it must complete any +object manipulations within a single method call. + +=== [#Technical-Challenges3]#Technical Challenges# + +Your application can use both stateful and stateless session beans with +an EclipseLink client session or database session. When you use session +beans with an EclipseLink session, the type of bean used affects how it +interacts with the session: + +* Stateless session beans and the EclipseLink session Stateless beans +store no information between method calls from the client. As a result, +reestablish the connection of the bean to the session for each client +method call. Each method call through EclipseLink obtains a client +session, makes the appropriate calls, and releases the reference to the +client session. +* Stateful session beans and the EclipseLink session Your EJB server +configuration includes settings that affect the way it manages +beans–settings designed to increase performance, limit memory footprint, +or set a maximum number of beans. When you use stateful beans, the +server may deactivate a stateful session bean enabled by EclipseLink out +of the JVM memory space between calls to satisfy one of these settings. +The server then reactivates the bean when required, and brings it back +into memory. This behavior is important, because an EclipseLink session +instance does not survive passivation. To maintain the session between +method calls, release the session during the passivation process and +re-obtain it when you reactivate the bean. +* External JDBC pools By default, EclipseLink manages its own connection +pools. For the session bean architecture, you must configure EclipseLink +to use connection pooling offered by the host application server. This +feature is useful for shared connection pools and is required for +JTA/JTS integration (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_External_Connection_Pooling[Configuring +External Connection Pooling]). +* JTA/JTS integration JTA and JTS are standard Java components that +enable sessions to participate in distributed transactions. You must +configure EclipseLink to use JTA/JTS to use session beans in the +architecture (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]). +* Cache coordination If you choose to use multiple servers to scale your +application, you may require EclipseLink +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]. + +=== What Is a Unit of Work Merge + +You can use a unit of work to enable your client application to modify +objects on the database. The unit of work merge functions employ +mappings to copy the values from the serialized object into the unit of +work, and to calculate changes. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Merging_Changes_in_Working_Copy_Clones[Merging +Changes in Working Copy Clones]. + +== Considering JPA Entity Architecture + +A part of the EJB 3.0 specification, the Java Persistence API (JPA) is a +lightweight, POJO-based framework for Java persistence. JPA focuses on +object relational mapping and contains a full object relational mapping +specification supporting the use of Java language metadata annotations +and/or XML descriptors to define the mapping between Java objects and a +relational database. Object relational mapping with the JPA is +completely metadata-driven. JPA supports a SQL-like query language for +both static and dynamic queries. It also supports the use of pluggable +persistence providers. + +JPA includes the following concepts: + +* Entity–any application-defined object with the following +characteristics can be an entity: +** it can be made persistent; +** it has a persistent identity (a key that uniquely identifies an +entity instance and distinguishes it from other instances of the same +entity type. An entity has a persistent identity when there is a +representation of it in a data store); +** it is partially transactional in a sense that a persistence view of +an entity is transactional (an entity is created, updated and deleted +within a transaction, and a transaction is required for the changes to +be committed in the database). However, in-memory entities can be +changed without the changes being persisted. +** it is not a primitive, a primitive wrapper, or built-in object. An +entity is a fine-graned object that has a set of aggregated state that +is typically stored in a single place (such as a row in a table), and +have relationships to other entities. +* Entity metadata–describes every entity. Metadata could be expressed as +annotations (specifically defined types that may be attached to or place +in front of Java programming elements) or XML (descriptors). +* Entity manager–enables API calls to perform operations on an entity. +Until an entity manager is used to create, read, or write an entity, the +entity is just a regular nonpersistent Java object. When an entity +manager obtains a reference to an entity, that entity becomes managed by +the entity manager. The set of managed entity instances within an entity +manager at any given time is called its persistence context–only one +Java instance with the same persistent identity may exist in a +persistence context at any time. You can configure an entity manager to +be able to persist or manage certain types of objects, read or write to +a particular database, and be implemented by a specific persistence +provider. The persistence provider supplies the backing implementation +engine for JPA, including the `+EntityManager+` interface +implementation, the `+Query+` implementation, and the SQL +generation.Entity managers are provided by an `+EntityManagerFactory+`. +The configuration for an entity manager is bound to the +`+EntityManagerFactory+`, but it is defined separately as a persistence +unit. You name persistence units to allow differentiation between +`+EntityManagerFactory+` objects. This way your application obtains +control over which configuration to use for operations on a specific +entity. The configuration that describes the persistence unit is defined +in a `+persistence.xml+` file. The following description expresses +relationships between JPA concepts: +** `+Persistence+` creates one or more `+EntityManagerFactory+` objects; +** each `+EntityManagerFactory+` is configured by one persistence unit; +** `+EntityManagerFactory+` creates one or more `+EntityManager+` +objects; +** one or more `+EntityManager+` manages one `+PersistenceContext+`. + +For more information, see the following: + +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)[Introduction +to Java Persistence API] +* link:Introduction_to_EclipseLink_JPA_(ELUG)[EclipseLink JPA Overview] +* http://www.oracle.com/technology/products/ias/toplink/jpa/indexl[`+http://www.oracle.com/technology/products/ias/toplink/jpa/indexl+`] +* _http://download.oracle.com/docs/cd/B32110_01/web.1013/b28221/toc.htm[Oracle +Fusion Middleware Enterprise JavaBeans Developer’s Guide for Oracle +Containers for Java EE]_ + +=== [#Example-Implementations3]#Example Implementations# + +An example of the entity beans with bean-managed persistence +implementation is a Model-View-Controller Model 2 architectural design +pattern that runs in a Java EE container, with servlets and JSP that +access session beans and EJB 3.0-compliant entities using the +EclipseLink-based JPA persistence provider. + +=== [#Advantages-and-Disadvantages4]#Advantages and Disadvantages# + +The use of EclipseLink JPA entities offers the following advantages: + +* POJO persistence–in JPA, persistent objects are POJOs. +* Object relational mapping is completely metadata-driven. +* The persistence API exists as a separate layer from the persistent +objects and does not intrude upon them. +* Using the query framework you can query across entities and their +relationships without having to use concrete foreign keys or database +columns. + +Also, you can define queries statically in metadata or create them +dynamically by passing query criteria on construction. Queries can +return entities as results. + +* Entities are mobile–objects are able to move from one JVM to another +and back, and at the same time be usable by the application. +* You can configure persistence features through the use of Java SE 5 +annotations, or XML, or a combination of both. You may also rely on +defaults. +* If your application is running inside a container, the container +provides support and ease of use; you can configure the same application +to run outside a container. + +== Considering Web Services Architecture + +A Web services architecture is similar to the +link:#Considering_Three-Tier_Architecture[Three-Tier Architecture] or +link:#Considering_EJB_Session_Bean_Facade_Architecture[Session Bean +Architecture] architecture, however, in a Web services architecture, you +encapsulate business logic (the service) in a Web service instead of (or +in addition to) using session beans. In a Web services architecture, +clients communicate with your application using SOAP messages (XML over +HTTP). + +[#Figure 2-6]## *_Figure 2-6 Web Services Architecture_* +image:websarch.gif[Web Services +Architecture,title="Web Services Architecture"] As in any architecture, +you can use EclipseLink to persist objects to relational or EIS data +sources. However, in a Web services architecture, you can also use +EclipseLink to map your object model to an XML schema for use with the +Web service or as the Web service XML serializer. + +=== [#Example-Implementations4]#Example Implementations# + +An example of a Web services architecture implementation is the use of a +Web service to expose parts of an existing application to a remote +client (typically another application) by way of SOAP messages. In this +application, you can use EclipseLink XML to unmarshall XML messages to +Java objects to facilitate requests and marshall Java object responses +back into XML for transmission to the client. + +=== [#Advantages-and-Disadvantages5]#Advantages and Disadvantages# + +Using EclipseLink in Web services architecture has many advantages, +including, but not limited to, the following: + +* you can map XML messages to an existing Java object model; +* you can achieve a high level of complexity of mapping support; +* compliance with the JAXB standards; +* providing a scalable, high-performing solution. + +One debatable disadvantage is this solution’s complexity over a simple +RMI session bean service. + +=== [#Technical-Challenges4]#Technical Challenges# + +As with any technology, there are technical challenges associated with +the use of EclipseLink in Web services architecture. These technical +challenges are mostly related to special-case scenarios, such as when +you need to implement a custom serializer because you have both the Java +objects and the schema. + +For more information, see link:XML_Mappings_(ELUG)[XML Mappings]. + +== Considering EclipseLink Database Web Services (DBWS)Architecture + +EclipseLink DBWS allows you to access relational database artifacts +through a web service. EclipseLink DBWS includes two components: a +design-time tooling component and a runtime provider component. The +runtime provider uses EclipseLink to bridge between the database and the +XML SOAP Messages used by a Web Service client. + +Using DBWS requires JDK 1.6 (or higher). + +See http://wiki.eclipse.org/EclipseLink/UserGuide/DBWS/Overview[DBWS for +more information]. + +== Considering EclipseLink Service Data Objects (SDO) Architecture + +An EclipseLink SDO architecture uses the SDO 2.1 framework for data +application and development. The EclipseLink implementation provides +additional features beyond the SDO specification provides and is +primarily used for converting Java objects to XML. See +link:Introduction_to_XML_Projects_(ELUG)#EclipseLink_Support_for_Java_Architecture_for_XML_Binding_(JAXB)[EclipseLink +Support for Java Architecture for XML Binding (JAXB)] for more +information. + +=== Example Implementation + +The EclipseLink implementation can be used with application similar to +JAXB or OX mappings. Typical implementations include: + +* Reading in XML with no Types or Properties (metadata) defined. In this +case the user is returned a graph of DataObjects that can be accesses +much like a DO +* Reading in XML with Types and Properties defined, but no generated +classes. In this case the user is returned a graph of DataObjects with +associated Types that allow the user to introspect the objects. In this +case the user is using a very dynamic but still typed, object model. +* Reading in XML with Types and Properties defined using generated +classes. In this case the user is returned a graph of bean like objects. +This is very similar to JAXB except that the user will have access to +both the static and dynamic APIs. + +=== [#Advantages-and-Disadvantages6]#Advantages and Disadvantages# + +Using EclipseLink with SDO has many advantages, including, but not +limited to the following: + +* generation of Java SDO classes from an XML schema; +* generation of SDO types and properties at runtime, to create dynamic +SDOs; +* generation of an XML XML schema that corresponds to the types and +properties of your SDO model; ability to capture and marshall (to XML) +the set of changes made to an SDO object graph in an SDO Change Summary. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.1[Category: Release 1.1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Development_Tools_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Development_Tools_(ELUG).adoc new file mode 100644 index 00000000000..944f3af5e03 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Development_Tools_(ELUG).adoc @@ -0,0 +1,90 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Development_Tools_(ELUG)[Related +Topics] + +The EclipseLink runtime provides Java or Java EE applications with +access to persistent entities stored in a data source. In addition to +run-time capabilities, the EclipseLink Foundation Library includes the +EclipseLink Application Programming Interface (API). This API enables +applications to access EclipseLink run-time features. + +EclipseLink includes additional development tools that simplify +application development. These tools capture mapping and run-time +configuration information in metadata files that EclipseLink passes to +the application at run time. + +The EclipseLink Workbench development tool is primarily for developing +when using the native EclipseLink API, MOXy, or EIS. When using JPA, +other development tools such as Eclipse Dali, or Oracle JDeveloper can +be used. + +EclipseLink metadata is the link between the two (see +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Working_with_EclipseLink_Metadata[Working +with EclipseLink Metadata]). + +The following figure illustrates how these elements interact with the +data source. + +[#Figure 3-1]## *_EclipseLink Components in Development Lifecycle_* + +.EclipseLink Components in Development Lifecycle +image::under01.gif[EclipseLink Components in Development +Lifecycle,title="EclipseLink Components in Development Lifecycle"] + +== Development Environment + +To create an EclipseLink application, use the Workbench to map objects +to data sources using relational and nonrelational models. Capture the +resulting mappings and additional run-time configurations in the +EclipseLink project file (`+project.xml+`) and build a session +configuration file (`+sessions.xml+`). These files together represent +your entire EclipseLink project, as shown in the +link:#Figure_3-2[following figure]. + +During development, you can use the EclipseLink API to define query and +transaction logic. When you use entity beans, there is generally little +or no direct use of the EclipseLink API and there is no session or +`+sessions.xml+` file. + +[#Figure 3-2 ]## *_Workbench in Development Environment_* + +.Workbench in Development Environment +image::under03.gif[Workbench in Development +Environment,title="Workbench in Development Environment"] + +Workbench can import compiled entity classes (Java objects or EJB entity +beans), as well as relational or nonrelational schemas through a JDBC +driver (configured by you). Because EclipseLink imports the object and +relational models for mapping, you can develop the two models relatively +independently from the mapping phase of a project development. + +== EclipseLink Run-Time Environment + +The EclipseLink Foundation Library provides the EclipseLink run-time +component. Access the run-time component either directly through the +EclipseLink API or indirectly through a Java EE container when using +entity beans with container-managed persistence. The run-time +environment is not a separate or external process–it is embedded within +the application. Application calls invoke EclipseLink to provide +persistence behavior. This function allows for transactional and +thread-safe access to shared database connections and cached objects. + +In addition to Java EE environments, EclipseLink fully supports non-Java +EE environments as well. See +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Selecting_an_Architecture_with_EclipseLink[Selecting +an Architecture with EclipseLink] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Expressions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Expressions_(ELUG).adoc new file mode 100644 index 00000000000..d9deedaab64 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Expressions_(ELUG).adoc @@ -0,0 +1,1039 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Expressions_(ELUG)[Related +Topics] + +Using the EclipseLink expressions framework, you can specify query +search criteria based on your domain object model. + +== Expression Framework + +The EclipseLink expression framework provides methods through the +following classes: + +* The `+Expression+` class provides most general functions, such as +`+toUpperCase+`. +* The `+ExpressionMath+` class supplies mathematical methods. + +This example illustrates how to use the `+Expression+` class. + +[#Example 106-1]## *_Using the Expression Class_* + +`+expressionBuilder.get("lastName").equal("Smith");+` + +This example illustrates how to use the `+ExpressionMath+` class. + +[#Example 106-2]## *_Using the ExpressionMath Class_* + +`+ExpressionMath.abs(ExpressionMath.subtract(emp.get("salary"),+` +`+emp.get("spouse").get("salary")).greaterThan(10000)+` + +This division of functionality enables EclipseLink expressions to +provide similar mathematical functionality to the `+java.lang.Math+` +class, but keeps both the `+Expression+` and `+ExpressionMath+` classes +from becoming unnecessarily complex. + +=== Expressions Compared to SQL + +Expressions offer the following advantages over SQL when you access a +database: + +* Expressions are easier to maintain because the database is abstracted. +* Changes to descriptors or database tables do not affect the querying +structures in the application. +* Expressions enhance readability by standardizing the `+Query+` +interface so that it looks similar to traditional Java calling +conventions. For example, the Java code required to get the street name +from the `+Address+` object of the `+Employee+` class looks like this: + +`+emp.getAddress().getStreet().equals("Meadowlands");+` + +The expression to get the same information is similar: + +`+emp.get("address").get("street").equal("Meadowlands");+` + +* Expressions allow read queries to transparently query between two +classes that share a relationship. If these classes are stored in +multiple tables in the database, EclipseLink automatically generates the +appropriate join statements to return information from both tables. +* Expressions simplify complex operations. For example, the following +Java code retrieves all employees that live on "`Meadowlands`" whose +salary is greater than 10,000: + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+Expression exp = emp.get("address").get("street").equal("Meadowlands");+` +`+Vector employees = session.readAllObjects(Employee.class,+` +`+                   exp.and(emp.get("salary").greaterThan(10000)));+` + +EclipseLink automatically generates the appropriate SQL from that code: + +`+SELECT t0.VERSION, t0.ADDR_ID, t0.F_NAME, t0.EMP_ID, t0.L_NAME, t0.MANAGER_ID, t0.END_DATE, t0.START_DATE, t0.GENDER, t0.START_TIME, t0.END_TIME,t0.SALARY FROM EMPLOYEE t0, ADDRESS t1 WHERE (((t1.STREET = 'Meadowlands')AND (t0.SALARY > 10000)) AND (t1.ADDRESS_ID = t0.ADDR_ID))+` + +== Expression Components + +A simple expression usually consists of the following three parts: + +[arabic] +. The _attribute_, which represents a mapped attribute or query key of +the persistent class. +. The _operator_, which is an expression method that implements boolean +logic, such as `+GreaterThan+`, `+Equal+`, or `+Like+`. +. The _constant_ or _comparison_, which refers to the value used to +select the object. + +In the following code fragment: + +`+expressionBuilder.get("lastName").equal("Smith"); +` + +* The attribute is `+lastName+`. +* The operator is `+equal+`. +* The constant is the string "``+Smith+``". + +The `+expressionBuilder+` substitutes for the object or objects to be +read from the database. In this example, `+expressionBuilder+` +represents employees. + +You can use the following components when constructing an +`+Expression+`: + +* link:#Boolean_Logic[Boolean Logic] +* link:#Database_Functions_and_Operators[Database Functions and +Operators] +* link:#Mathematical_Functions[Mathematical Functions] +* link:#XMLType_Functions[XMLType Functions] +* link:#Platform_and_User-Defined_Functions[Platform and User-Defined +Functions] +* link:#Expressions_for_One-to-One_and_Aggregate_Object_Relationships[Expressions +for One-to-One and Aggregate Object Relationships] +* link:#Expressions_for_Joining_and_Complex_Relationships[Expressions +for Joining and Complex Relationships] + +=== Boolean Logic + +Expressions use standard boolean operators, such as `+AND+`, `+OR+`, and +`+NOT+`, and you can combine multiple expressions to form more complex +expressions. The link:#Example_106-3[Using Boolean Logic in an +Expression] example illustrates a code fragment that queries for +projects managed by a selected person, and that have a budget greater +than or equal to 1,000,000. + +[#Example 106-3]## *_Using Boolean Logic in an Expression_* + +`+ExpressionBuilder project = new ExpressionBuilder();+` +`+Expression hasRightLeader, bigBudget, complex;+` +`+Employee selectedEmp = someWindow.getSelectedEmployee();+` +`+hasRightLeader = project.get("teamLeader").equal(selectedEmp);+` +`+bigBudget = project.get("budget").greaterThanEqual(1000000);+` +`+complex = hasRightLeader.and(bigBudget);+` +`+Vector projects = session.readAllObjects(Project.class, complex);+` + +=== Database Functions and Operators + +*Functions* + +EclipseLink expressions support a variety of database functions, +including, but not limited to, the following: + +* `+toUpperCase+` +* `+toLowerCase+` +* `+toDate+` +* `+decode+` +* `+locate+` +* `+monthsBetween+` +* `+nextDay+` +* `+replace+` +* `+reverse+` +* `+substring+` +* `+translate+` + +[cols="<",] +|=== +|*Note:* Some functions may be database platform-specific. +|=== + +Database functions let you define more flexible queries. You can use +these functions in either a report query items using a `+SELECT+` +clause, or with comparisons in a query’s selection criteria using a +`+WHERE+` clause. The following example illustrates a code fragment that +matches several last names, including "`SMART`", "`Smith`", and +"`Smothers`": + +[#Example 106-4]## *_Using a Database Function Supported by the +Expression API_* + +`+emp.get("lastName").toUpperCase().like("SM%")+` + +You access most functions using `+Expression+` methods such as +`+toUpperCase+`. + +Some functions have very specific purpose: you can use `+ascending+` and +`+descending+` functions only within an ordering expression to place the +result in ascending or descending order, as this example shows: + +[#Example 106-5]## *_Using an Ordering Database Function_* + +`+readAllQuery.addOrderBy(expBuilder.get("address").get("city").ascending())+` + +[width="100%",cols="<100%",] +|=== +|*Note:* Ordering is not supported for in-memory queries (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[How to Use +In-Memory Queries]). +|=== + +You can use aggregate functions, such as `+average+`, `+minimum+`, +`+maximum+`, `+sum+` and so forth, with the `+ReportQuery+` (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Report Query]). + +*Operators* + +Operators are relation operations that compare two values. EclipseLink +expressions support the following operators: + +* `+like+` +* `+notLike+` +* `+equal+` +* `+notEqual+` +* `+lessThan+` +* `+lessThanEqual+` +* `+equalsIgnoreCase+` +* `+greaterThan+` +* `+greaterThanEqual+` +* `+in+` +* `+notIn+` +* `+between+` +* `+notBetween+` + +The link:#Example_106-4[Using a Database Function Supported by the +Expression API’] example demonstrates the use of the like operator. + +=== Mathematical Functions + +Mathematical functions are available through the `+ExpressionMath+` +class. Mathematical function support in expressions is similar to the +support provided by the Java class `+java.lang.Math+`. This example +illustrates using the `+abs+` and `+subtract+` methods. + +[#'Example 106-6]## *_Using Mathematical Functions in an Expression_* + +`+ExpressionMath.abs(ExpressionMath.subtract(emp.get("salary"),+` +`+                   emp.get("spouse").get("salary")).greaterThan(10000)+` + +=== XMLType Functions + +You can use the following operators when constructing queries against +data mapped to an Oracle Database XMLType column: + +* `+extract+`: Takes an XPath string and returns an XMLType which +corresponds to the part of the original document that matches the XPath. +* `+extractValue+`: Takes an Xpath string and returns either a numerical +or string value based on the contents of the node pointed to by the +XPath. +* `+existsNode+`: Takes an Xpath expression and returns the number of +nodes that match the Xpath. +* `+getStringVal+`: Gets the string representation of an XMLType object. +* `+getNumberVal+`: Gets the numerical representation of an XMLType +object. +* `+isFragment+`: Evaluates to 0 if the XML is a well formed document. +Evaluates to 1 if the document is a fragment. + +This example illustrates how to use the extract operator in a query: + +[#Example 106-7]## *_Using the XMLType Extract Operator_* + +`+Expression criteria = builder.get("resume").extract("//education/degree/text()").getStringVal().equal("BCS");+` +`+Vector employees = session.readAllObject(Employee.class, criteria); +` + +=== Platform and User-Defined Functions + +You can use the `+Expression+` method `+getFunction+` to access database +functions that EclipseLink does not support directly. The following +example illustrates how to access a database function named +`+VacationCredit+` from within an expression, even though there is no +support for such a function in the `+Expression+` API. + +[#Example 106-8]## *_Using a Database Function Not Supported by the +Expression API_* + +`+emp.get("lastName").getFunction("VacationCredit").greaterThan(42)+` + +This expression produces the following SQL: + +`+SELECT . . . WHERE VacationCredit(EMP.LASTNAME) > 42+` + +The `+Expression+` API includes additional forms of the `+getFunction+` +method that allow you to specify arguments. For more information, see +_EclipseLink API Reference_. + +You can also access a custom function that you create. For more +information on creating a custom function in EclipseLink, see +link:#Creating_and_Using_a_User-Defined_Function[Creating and Using a +User-Defined Function]. + +=== Expressions for One-to-One and Aggregate Object Relationships + +Expressions can include an attribute that has a one-to-one relationship +with another persistent class. A one-to-one relationship translates +naturally into a SQL join that returns a single row. + +This example illustrates a code fragment that accesses fields from an +employee’s address. + +[#Example 106-9]## *_Using an Expression with a One-to-One +Relationship_* + +`+emp.get("address").get("country").like("S%")+` + +The preceding example corresponds to joining the `+EMPLOYEE+` table to +the `+ADDRESS+` table, based on the `+address+` foreign key, and +checking for the country name. + +You can nest these relationships infinitely, so it is possible to ask +for complex information, as follows: + +`+project.get("teamLeader").get("manager").get("manager").get("address").get("street")+` + +=== Expressions for Joining and Complex Relationships + +You can query against complex relationships, such as one-to-many, +many-to-many, direct collection, and aggregate collection relationships. +Expressions for these types of relationships are more complex to build, +because the relationships do not map directly to joins that yield a +single row per object. + +This section describes the following: + +* link:#What_You_May_Need_to_Know_About_Joins[What You May Need to Know +About Joins] +* link:#Using_EclipseLink_Expression_API_for_Joins[Using EclipseLink +Expression API for Joins] + +==== What You May Need to Know About Joins + +A *join* is a relational database query that combines rows from two or +more tables. Relational databases perform a join whenever multiple +tables appear in the query’s `+FROM+` clause. The query’s select list +can select any columns from any of these tables. + +An inner join (sometimes called a "`simple join`") is a join of two or +more tables that returns only those rows that satisfy the join +condition. + +An outer join extends the result of an inner join. An outer join returns +all rows that satisfy the join condition and also returns some or all of +those rows from one table for which no rows from the other satisfy the +join condition. Outer joins can be categorized as left or right: + +* A query that performs a left outer join of tables A and B returns all +rows from A. For all rows in A that have no matching rows in B, the +database returns null for any select list expressions containing columns +of B. +* A query that performs a right outer join of tables A and B returns all +rows from B. For all rows in B that have no matching rows in A, the +database returns null for any select list expressions containing columns +of A. + +When you query with a join expression, EclipseLink can use joins to +check values from other objects or other tables that represent parts of +the same object. Although this works well under most circumstances, it +can cause problems when you query against a one-to-one relationship, in +which one side of the relationship is not present. + +For example, `+Employee+` objects may have an `+Address+` object, but if +the `+Address+` is unknown, it is `+null+` at the object level and has a +null foreign key at the database level. When you attempt a read that +traverses the relationship, missing objects cause the query to return +unexpected results. Consider the following expression: + +`+(emp.get("firstName").equal("Steve")).or(emp.get("address"). get("city").equal("Ottawa"))+` + +In this case, employees with no address do not appear in the result set, +regardless of their first name. Although not obvious at the object +level, this behavior is fundamental to the nature of relational +databases. + +Outer joins rectify this problem in the databases that support them. In +this example, the use of an outer join provides the expected result: all +employees named Steve appear in the result set, even if their address is +unknown. + +To implement an outer join, use `+Expression+` method +`+getAllowingNull+`, rather than `+get+`, and `+Expression+` method +`+anyOfAllowingNone+`, rather than `+anyOf+`. + +For example: + +`+(emp.get("firstName").equal("Steve")).or(+` +`+emp.getAllowingNull("address").get("city").equal("Ottawa"))+` + +Support and syntax for outer joins vary widely between databases and +database drivers. EclipseLink supports outer joins for most databases. + +==== Using EclipseLink Expression API for Joins + +You can use joins anywhere expressions are used, including: +selection-criteria, ordering (see +link:Using%20Basic%20Query%20API%20(ELUG)[Specifying Read Ordering]), +report queries (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Report Query]), +partial objects (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Partial Object +Queries]), one-to-one relational mappings (see +link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring Joining +at the Mapping Level]), and join reading (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Join Reading and +Object-Level Read Queries]). + +Use the expression API shown in this table to configure inner and outer +join expressions. + +[#Table 106-1]## *_Expression API for Joins_* + +[cols="<,<,<",options="header",] +|=== +|*Expression API* |*Type of Join* |*Type of Mapping* +|`+get+` |inner |one-to-one +|`+getAllowingNull+` |outer |one-to-one +|`+anyOf+` |inner |one-to-many, many-to-many +|`+anyOfAllowingNone+` |outer |one-to-many, many-to-many +|=== + +To query across a one-to-many or many-to-many relationship, use the +`+anyOf+` operation. As its name suggests, this operation supports +queries that return all items on the "`many`" side of the relationship +that satisfy the query criteria. + +The following example illustrates an expression that returns employees +who manage at least one employee (through a one-to-many relationship) +with a salary less than $10,000. + +[#Example 106-10]## *_Using an Expression with a One-to-Many +Relationship_* + +`+emp.anyOf("managedEmployees").get("salary").lessThan(10000);+` + +The following example illustrates how to query across a many-to-many +relationship using a similar strategy: + +[#Example 106-11]## *_Using an Expression with a Many-to-Many +Relationship_* + +`+emp.anyOf("projects").equal(someProject)+` + +EclipseLink translates these queries into SQL that joins the relevant +tables using a `+DISTINCT+` clause to remove duplicates. EclipseLink +translates the link:#Example_106-10[Using an Expression with a +One-to-Many Relationship] example into the following SQL: + +`+SELECT DISTINCT . . . FROM EMP t1, EMP t2 WHERE+` +`+t2.MANAGER_ID = t1.EMP_ID AND t2.SALARY < 10000+` + +You can use one-to-one and one-to-many join expressions in an +`+ObjectLevelReadyQuery+` to configure joins on a per-query basis (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Join Reading and +Object-Level Read Queries]). + +You can also configure joins at the mapping level (see +link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring Joining +at the Mapping Level]). + +[width="100%",cols="<100%",] +|=== +|*Note:* Calling `+anyOf+` once would result in a different outcome than +if you call it twice. For example, if you query for an employee with a +telephone area code of 613 and a number of 123-4599, you would use a +single `+anyOf+` and a temporary variable. If you query for an employee, +who has a telephone with an area code of 613, and who has a telephone +with a number of 123-4599, you would call `+anyOf+` twice. +|=== + +== Parameterized Expressions + +A relationship mapping differs from a regular query because it retrieves +data for many different objects. To be able to specify these queries, +supply arguments when you execute the query. Use the `+getParameter+` +and `+getField+` methods to acquire values for the arguments. + +A parameterized expression executes searches and comparisons based on +variables instead of constants. This approach lets you build expressions +that retrieve context-sensitive information. This technique is useful +when you define EJB finders (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[EJB Finders]). + +Parameterized expressions require that the relationship mapping know how +to retrieve an object or collection of objects based on its current +context. For example, a one-to-one mapping from `+Employee+` to +`+Address+` must query the database for an address based on foreign key +information from the `+Employee+` table. Each mapping contains a query +that EclipseLink constructs automatically based on the information +provided in the mapping. To specify expressions yourself, use the +mapping customization mechanisms. + +You can use parameterized expressions to create reusable queries (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Named Queries]). + +=== Expression Method getParameter + +The `+Expression+` method `+getParameter+` returns an expression that +becomes a parameter in the query. This lets you create a query that +includes user input in the search criteria. The parameter must be either +the fully qualified name of the field from a descriptor’s row, or a +generic name for the argument. + +Parameters you construct this way are global to the current query, so +you can send this message to any expression object. + +The following example illustrates how to use a custom query to find an +employee by first name. + +[#Example 106-12]## *_Using a Parameterized Expression in a Custom +Query_* + +`+Expression firstNameExpression;+` + +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+ExpressionBuilder emp = query.getExpressionBuilder();+` +`+firstNameExpression = emp.get("firstName").equal(emp.getParameter("firstName"));+` +`+query.setSelectionCriteria(firstNameExpression);+` +`+query.addArgument("firstName");+` `+List args = new ArrayList();+` +`+args.addElement("Sarah");+` +`+Employee e = (Employee) session.executeQuery(query, args);+` + +The following example illustrates how to use a custom query to find all +employees that live in the same city as a given employee. + +[#Example 106-13]## *_Using Nested Parameterized Expressions_* + +`+Expression addressExpression;+` +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+ExpressionBuilder emp = query.getExpressionBuilder();+` +`+addressExpression = +` `+    emp.get("address").get("city").equal(+` +`+    emp.getParameter("employee").get("address").get("city"));+` +`+query.setName("findByCity");+` +`+query.setSelectionCriteria(addressExpression);+` +`+query.addArgument("employee");+` `+List args = new ArrayList();+` +`+args.addElement(employee);+` +`+Employee e = (Employee) session.executeQuery(query, args);+` + +The following example illustrates how to obtain a simple one-to-many +mapping from class `+PolicyHolder+` to `+Policy+` using a nondefault +selection criteria. The `+SSN+` field of the `+POLICY+` table is a +foreign key to the `+SSN+` field of the `+HOLDER+` table. + +[#Example 106-14]## *_Using a Parameterized Expression in a Mapping_* + +`+OneToManyMapping mapping = new OneToManyMapping();+` +`+mapping.setAttributeName("policies");+` +`+mapping.setGetMethodName("getPolicies");+` +`+mapping.setSetMethodName("setPolicies");+` +`+mapping.setReferenceClass(Policy.class);+` + +*`+//\'\' \'\'Build\'\' \'\'a\'\' \'\'custom\'\' \'\'expression\'\' \'\'here\'\' \'\'rather\'\' \'\'than\'\' \'\'using\'\' \'\'the\'\' \'\'defaults+`* +`+ExpressionBuilder policy = new ExpressionBuilder();+` +`+mapping.setSelectionCriteria(policy.getField("POLICY.SSN")).equal(policy.getParameter("HOLDER.SSN")));+` + +=== Expression Method getField + +The `+Expression+` method `+getField+` returns an expression that +represents a database field with the given name. Use this method to +construct the selection criteria for a mapping. The argument is the +fully qualified name of the required field. Because fields are not +global to the current query, you must send this method to an expression +that represents the table from which this field is derived. See also +link:#Data_Queries_and_Expressions[Data Queries and Expressions]. + +The following example illustrates how to use the `+Expression+` method +`+getField+`. + +[#Example 106-15]## *_Using Expression Method getParameter_* + +`+ExpressionBuilder address = new ExpressionBuilder();+` +`+Expression exp = address.getField("ADDRESS.EMP_ID").equal(address.getParameter("EMPLOYEE.EMP_ID"));+` +`+exp = exp.and(address.getField("ADDRESS.TYPE").equal(null));+` + +== Query Keys and Expressions + +A query key is a schema-independent alias for a database field name. + +Query keys are supported in relational database projects only. + +Query keys are generated automatically for all direct and relationship +mappings. The name of the query key is the class attribute name. + +For more information on how query keys are created and modified, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Query Keys]. + +The following example illustrates how to use the query key `+firstName+` +for the corresponding directly mapped `+Employee+` attribute. + +[#Example 106-16]## *_Using an Automatically Generated Query Key in an +Expression_* + +`+Vector employees = session.readAllObjects(Employee.class,+` +`+  new ExpressionBuilder().get("firstName").equal("Bob"));+` + +The following example illustrates how to use a one-to-one query key +within the EclipseLink expression framework. + +[#Example 106-17]## *_Using a One-to-One Query Key in an Expression_* + +`+ExpressionBuilder employee = new ExpressionBuilder();+` +`+Vector employees = session.readAllObjects(Employee.class,+` +`+                   employee.get("address").get("city").equal("Ottawa"));+` + +To access one-to-many and many-to-many query keys that define a distinct +join across a collection relationship, use `+Expression+` method +`+anyOf+`. + +== Multiple Expressions + +Expressions support subqueries (SQL subselects) and parallel selects. To +create a subquery, use a single expression builder. With parallel +selects, use multiple expression builders when you define a single +query. This lets you specify joins for unrelated objects at the object +level. + +=== How to Use Subselects and Subqueries + +Some queries compare the results of other, contained queries (or +subqueries). SQL supports this comparison through subselects. +EclipseLink expressions provide subqueries to support subselects. + +Subqueries lets you define complex expressions that query on aggregated +values (`+counts+`, `+min+`, `+max+`) and unrelated objects (`+exists+`, +`+in+`, `+comparisons+`). To obtain a subquery, pass an instance of a +report query to any expression comparison operation, or use the +`+subQuery+` operation on an expression builder. The subquery is not +required to have the same reference class as the parent query, and it +must use its own expression builder. + +You can nest subqueries, or use them in parallel. Subqueries can also +make use of custom SQL. + +For expression comparison operations that accept a single value +(`+equal+`, `+greaterThan+`, `+lessThan+`), the subquery result must +return a single value. For expression comparison operations that accept +a set of values (`+in+`, `+exists+`), the subquery result must return a +set of values. + +The following example illustrates how to create an expression that +matches all employees with more than five managed employees. + +[#Example 106-18]## *_A Subquery Expression Using a Comparison and Count +Operation_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+ExpressionBuilder managedEmp = new ExpressionBuilder();+` +`+ReportQuery subQuery = new ReportQuery(Employee.class, managedEmp);+` +`+subQuery.addCount();+` +`+subQuery.setSelectionCriteria(managedEmp.get("manager").equal(emp));+` +`+Expression exp = emp.subQuery(subQuery).greaterThan(5);+` + +The following example illustrates how to create an expression that +matches the employee with the highest salary in the city of Ottawa. + +[#Example 106-19]## *_A Subquery Expression Using a Comparison and Max +Operation_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+ExpressionBuilder ottawaEmp = new ExpressionBuilder();+` +`+ReportQuery subQuery = new ReportQuery(Employee.class, ottawaEmp);+` +`+subQuery.addMax("salary");+` +`+subQuery.setSelectionCriteria(ottawaEmp.get("address").get("city").equal("Ottawa"));+` +`+Expression exp =   emp.get("salary").equal(subQuery).and(emp.get("address").get("city").equal("Ottawa"));+` + +The following example illustrates how to create an expression that +matches all employees that have no projects. + +[#Example 106-20]## *_A Subquery Expression Using a Not Exists +Operation_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+ExpressionBuilder proj = new ExpressionBuilder();+` +`+ReportQuery subQuery = new ReportQuery(Project.class, proj);+` +`+subQuery.addAttribute("id");+` +`+subQuery.setSelectionCriteria(proj.equal(emp.anyOf("projects"));+` +`+Expression exp = emp.notExists(subQuery);+` + +=== How to Use Parallel Expressions + +Parallel expressions enable you to compare unrelated objects. Parallel +expressions require multiple expression builders, but do not require the +use of report queries. Each expression must have its own expression +builder, and you must use the constructor for expression builder that +takes a `+class+` as an argument. The class does not have to be the same +for the parallel expressions, and you can create multiple parallel +expressions in a single query. + +Only one of the expression builders is considered the primary expression +builder for the query. This primary builder makes use of the zero +argument expression constructor, and EclipseLink obtains its class from +the query. + +The following example illustrates how to create an expression that +matches all employees with the same last name as another employee of +different gender, and accounts for the possibility that returned results +could be a spouse. + +[#Example 106-21]## *_A Parallel Expression on Two Independent +Employees_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+ExpressionBuilder spouse = new ExpressionBuilder(Employee.class);+` +`+Expression exp = emp.get("lastName").equal(spouse.get("lastName"))+` +`+                 .and(emp.get("gender").notEqual(spouse.get("gender"));+` + +== Data Queries and Expressions + +You can use expressions to retrieve data rather than objects. This is a +common approach when you work with unmapped information in the database, +such as foreign keys and version fields. + +Expressions that query for objects generally refer to object attributes, +which may in turn refer to other objects. Data expressions refer to +tables and their fields. You can combine data expressions and object +expressions within a single query. EclipseLink provides two main methods +for expressions that query for data: `+getField+` and `+getTable+`. + +=== How to Use the getField Method + +The `+getField+` method lets you retrieve data from either an unmapped +table or an unmapped field from an object. In either case, the field +must be part of a table represented by that object’s class; otherwise, +EclipseLink raises an exception when you execute the query. + +You can also use the `+getField+` method to retrieve the foreign key +information for an object. + +This example illustrates how to use the data expression method +(operator) `+getField+` with an object. + +[#'Example 106-22]## *_Using getField with an Object_* + +`+builder.getField("+`_`+[FIELD_NAME]+`_`+").greaterThan("+`_`+[ARGUMENT]+`_`+");+` + +=== How to Use the getTable Method + +The `+getTable+` method returns an expression that represents an +unmapped table in the database. This expression provides a context from +which to retrieve an unmapped field when you use the `+getField+` +method. + +The following example illustrates how to combine both `+getField+` and +`+getTable+` in the same expression. + +[#Example 106-23]## *_Using getTable and getField Together_* + +`+builder.getTable("+`_`+[TABLE_NAME]+`_`+").getField("+`_`+[FIELD_NAME]+`_`+").equal("+`_`+[ARGUMENT]+`_`+");+` + +A common use for the `+getTable+` and `+getField+` methods is to +retrieve information from a link table (or reference table) that +supports a many-to-many relationship. + +The following example reads a many-to-many relationship that uses a link +table and also checks an additional field in the link table. This code +combines an object query with a data query, using the employee’s manager +as the basis for the data query. It also features parameterization for +the project ID. + +[#Example 106-24]## *_Using a Data Query Against a Link Table_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+Expression manager = emp.get("manager"); +` +`+Expression linkTable = manager.getTable("PROJ_EMP");+` +`+Expression empToLink = emp.getField("EMPLOYEE   .EMP_ID").equal(linkTable.getField("PROJ_EMP.EMP_ID");+` +`+Expression projToLink = linkTable.getField("PROJ_EMP.PROJ_ID").equal(emp.getParameter("PROJECT.PROJ_ID"));+` +`+Expression extra = linkTable.getField("PROJ_EMP.TYPE").equal("W");+` +`+query.setSelectionCriteria((empToLink.and(projToLink)).and(extra));+` + +== Creating an Expression + +You can create an expression using the Workbench or Java. + +Use the Workbench for creating basic expressions for use in named +queries (see link:#How_to_Create_an_Expression_Using_Workbench[How to +Create an Expression Using Workbench]). + +Use Java code to create more complex expressions and to take full +advantage of the features in the expressions API (see +link:#How_to_Create_an_Expression_Using_Java[How to Create an Expression +Using Java]). + +=== How to Create an Expression Using Workbench + +To create EclipseLink expressions for named queries, use this procedure: + +[arabic] +. From the *Named Queries Format* tab, click *Edit* (or double-click a +query string). The Expression Builder dialog box appears. See +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Named Queries] +for more information. [#Figure 106-1]## *_Expression Builder Dialog_* +image:expbld.gif[Expression Builder +Dialog,title="Expression Builder Dialog"] + +The numbered callouts identify the following user-interface components: + +[arabic] +. {blank} +[arabic] +.. Expression tree +.. Arguments +. Click *Add* or *Add Nested* to create a new expression. EclipseLink +assigns a sequence number to each node and nested node. Click *Remove* +to remove an existing expression. +. Select the node and use the *Logical Operator* list to specify the +operator for the node (*AND*, *OR*, *Not AND*, or *Not OR*). +. Choose the expression and complete the fields on the Expression +Builder dialog. + +Use this table to complete the argument fields for each expression: + +Field + +Description + +First Argument + +Click Edit and select the query key for the first argument. The Choose +Query Key dialog box appears. + +Continue with Adding Arguments. + +Operator + +Specify how EclipseLink should evaluate the expression. + +Valid operators include: Equal, Not Equal, Equal Ignore Case, Greater +Than, Greater Than Equal, Less Than, Less Than Equal, Like, Not Like, +Like Ignore Case, Is Null, and Not Null. + +Second Argument + +Specify the second argument: + +Literal–Select the Type and enter a literal value for Value. + +Query Key–Click Edit and select the query key. + +Parameter–Click Add to add a new parameter and then select from the +list. + +Continue with Adding Arguments + +Click *OK*. Workbench adds the expression to the *Named Queries* tab. + +==== Adding Arguments + +Each expression contains elements (_arguments_) to evaluate. Expressions +using the Is Null or Not Null operators require only a single argument. + +To add new arguments, use this procedure: + +[arabic] +. Select an existing expression or click *Add* (or *Add Nested*) to add +a new expression to the named query. +. For the *First Argument*, click *Edit*. The Choose Query Key dialog +box appears. [#Figure 106-2]## *_Choose Query Key_* +image:choseqk.gif[Choose Query Key,title="Choose Query Key"] +. Select the attribute, specify if the query allows a null value, and +click *OK*. Use the *Allows Null* and *Allows None* options to define an +expression with an outer join. Check the *Allows Null* option to use the +`+ExpressionBuilder+` method `+getAllowingNull+`. Check the *Allows +None* option to use the `+ExpressionBuilder+` method +`+anyOfAllowingNone+`. For more information, see +link:#Using_EclipseLink_Expression_API_for_Joins[Using EclipseLink +Expression API for Joins]. +. Use the *Operator* list to specify how EclipseLink should evaluate the +expression. +. For the *Second Argument*, select *Literal*, *Query Key*, or +*Parameter*: +* For *Literal* arguments, choose the literal type (such as *String* or +*Integer*) and enter the literal value. +* For *Query Key* arguments, click *Edit*. The Choose Query Key dialog +box appears (see step #3 and link:#Figure_106-2[Choose Query Key] +dialog). +* For *Parameter* arguments, click *Add* to add a parameter and then use +the list to select it. + +Repeat this procedure for each expression or subexpression. + +[#Example 106-25]## *_Sample Expression_* + +The following expression will find employees who: + +* have a manager with the last name Jones or have no manager, and +* work on projects with the name Beta or project ID 4, and +* live in Canada and have a salary of more than 25,000, or live in the +United States and have a salary of more than 37,500 + +`+AND+` `+  1.manager(Allows Null).lastName EQUAL "Jones"+` `+  2.OR+` +`+    2.1.projects.name LIKE "BETA"+` `+    2.2.projects.id EQUAL "4"+` +`+  3.OR+` `+    3.1.AND+` +`+      3.1.1.address.country EQUAL "Canada"+` +`+      3.1.2.salary GREATER THAN "25000"+` `+    3.2.AND+` +`+      3.1.1.address.country EQUAL "United States"+` +`+      3.1.2.salary GREATER THAN "37500"+` + +=== How to Create an Expression Using Java + +To create an expression in Java code, use the `+Expression+` class or +`+ExpressionBuilder+` method `+get+`. + +The `+ExpressionBuilder+` acts as a substitute for the objects that you +query. To construct a query, call methods on the `+ExpressionBuilder+` +that correspond to the attributes of the objects. We recommend that you +name `+ExpressionBuilder+` objects according to the type of objects +against which you do a query. + +[width="100%",cols="<100%",] +|=== +|*Note:* An instance of `+ExpressionBuilder+` is specific to a +particular query. Do not attempt to build another query using an +existing builder, because it still contains information related to the +first query. +|=== + +This example illustrates how to use the query key `+lastName+` to +reference the field name `+L_NAME+`. + +[#Example 106-26]## *_Using ExpressionBuilder to Build a Simple +Expression_* + +`+Expression expression = new ExpressionBuilder().get("lastName").equal("Young");+` + +This example illustrates how to create a complex expression by combining +two smaller expressions with a logical `+and+` operator. + +[#Example 106-27]## *_Combining Two Expressions with a Logical AND +Operator_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+Expression exp1, exp2;+` `+exp1 = emp.get("firstName").equal("Ken");+` +`+exp2 = emp.get("lastName").equal("Young");+` +`+return exp1.and(exp2);+` + +This example illustrates how to create an expression using the +`+notLike+` operator. + +[#Example 106-28]## *_Using Database Function notLike in an Expression_* + +`+Expression expression = new ExpressionBuilder().get("lastName").notLike("%ung");+` + +== Creating and Using a User-Defined Function + +Different databases sometimes implement the same functions in different +ways. For example, an argument that specifies that data returns in +ascending order might be `+ASC+` or `+ASCENDING+`. To manage +differences, EclipseLink recognizes functions and other operators that +vary according to the relational database. + +Although most platform-specific operators exist in EclipseLink, if +necessary, you can create your own operators. + +To create a user-defined function, use the `+ExpressionOperator+` class. + +An `+ExpressionOperator+` has a selector and a `+Vector+` of strings: + +* The selector is the identifier (_id_) by which users refer to the +function. +* The strings are the constant strings used in printing the function. +When printed, the strings alternate with the function arguments. + +You can also specify whether the operator is prefix or postfix. In a +prefix operator, the first constant string prints before the first +argument; in a postfix, it prints afterwards. + +Where you create a user-defined function and how you add it to the +EclipseLink expression framework depends on whether you want the new +function available to all database platforms or to only a specific +database platform. + +This section describes the following: + +* link:#How_to_Make_a_User-Defined_Function_Available_to_a_Specific_Platform[How +to Make a User-Defined Function Available to a Specific Platform] +* link:#How_to_Make_a_User-Defined_Function_Available_to_All_Platforms[How +to Make a User-Defined Function Available to All Platforms] + +=== How to Make a User-Defined Function Available to a Specific Platform + +To make the function that overrides a specific operation on your own +platform, use the following procedure: + +[arabic] +. Create a subclass of the desired +`+org.eclipse.persistence.platform.database.DatabasePlatform+` that +provides a public method that calls the protected superclass method +`+addOperator+`: ++ +`+...+` `+public class MyDatabasePlatform extends DatabasePlatform {+` + +`+    protected void initializePlatformOperators() {+` +`+        super.initializePlatformOperators();+` +`+        +`*`+//\'\' \'\'Create\'\' \'\'user-defined\'\' \'\'function+`* + +`+        ExpressionOperator toUpper = new ExpressionOperator();+` +`+        toUpper.setSelector(ExpressionOperator.ToUpperCase);+` +`+        List args = new ArrayList();+` +`+        args.addElement("UPPERCASE(");+` +`+        args.addElement(")");+` `+        toUpper.printAs(args);+` +`+        toUpper.bePrefix();+` +`+        toUpper.setNodeClass(FunctionExpression.class);+` + +`+        +`*`+//\'\' \'\'Make\'\' \'\'it\'\' \'\'available\'\' \'\'to\'\' \'\'this\'\' \'\'platform\'\' \'\'only+`* +`+        addOperator(toUpper);+` `+    }+` `+}+` +. Configure your session to use your platform subclass (see +link:Configuring%20a%20Relational%20Project%20(ELUG)[Configuring +Relational Database Platform at the Project Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)[Configuring a +Relational Database Platform at the Session Level]). + +=== How to Make a User-Defined Function Available to All Platforms + +To make the function available to all platforms, use +`+ExpressionOperator+` method `+addOperator+`, as this example shows. + +[#Example 106-29]## *_Adding a toUpper Function for All Platforms_* + +`+ExpressionOperator toUpper = new ExpressionOperator();+` +`+toUpper.setSelector(600);+` `+List args = new ArrayList();+` +`+args.addElement("NUPPER(");+` `+args.addElement(")");+` +`+toUpper.printAs(args);+` `+toUpper.bePrefix();+` +`+toUpper.setNodeClass(FunctionExpression.class);+` + +`+ExpressionOperator.addOperator(toUpper);+` + +[width="100%",cols="<100%",] +|=== +|*Note:* Represent the number in the `+setSelector+` method by a +constant value. Ensure that this number is greater than 500 (numbers +below 500 are reserved in EclipseLink). +|=== + +==== Using a User-Defined Function + +Regardless of whether you added the function for all platforms or for a +specific platform, the following example illustrates how to use the +`+Expression+` method `+getFunction+` to access the user-defined +expression operator represented by a constant with the value 600. + +[#Example 106-30]## *_Accessing a User-Defined Function_* + +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+ExpressionBuilder builder = query.getExpressionBuilder();+` +`+Expression functionExpression = builder.get("firstName").getFunction(600).equal("BOB");+` +`+query.setSelectionCriteria(functionExpression);+` +`+session.executeQuery(query);+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Mapping_and_Configuration_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Mapping_and_Configuration_(ELUG).adoc new file mode 100644 index 00000000000..ace6b031fef --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Mapping_and_Configuration_(ELUG).adoc @@ -0,0 +1,101 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Mapping_and_Configuration_(ELUG)[Related +Topics] + +EclipseLink uses +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Working_with_EclipseLink_Metadata[metadata] +to describe how objects relate to a data source representation. Your +mapping and configuration activities construct this metadata. + +After creating the metadata, you can use it in any number of +applications by referencing the metadata from +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[a session]. The +EclipseLink runtime uses this metadata in all persistence and data +transformation operations. + +== Mapping and Configuration Concepts + +This section describes concepts unique to EclipseLink mapping and +configuration, including the following: + +* link:#Projects[Projects] +* link:#Descriptors[Descriptors] +* link:#Mappings[Mappings] + +=== Projects + +The `+Project+` class is the primary container in which EclipseLink +stores its mapping and configuration metadata. A project relates a set +of object classes to a data source at the data model level. + +A project contains link:#Descriptors[a descriptor] for each class and +each descriptor contains link:#Mappings[a mapping] for each data member +that EclipseLink should persist or transform. + +Using the Workbench, you can export mapping and configuration metadata +into a deployment XML file called `+project+`. For more information, see +link:Creating%20a%20Project%20(ELUG)#Exporting_Project_Information[Exporting +Project Information]. + +After creating the project XML file, you must associate it with a +session so that EclipseLink can use it at run time. For more +information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Primary_Mapping_Project[Configuring +a Primary Mapping Project]. + +For Enterprise JavaBeans (EJB) applications where there is no session, +deploy the project XML file to the target application server. In this +context, the project XML file is also known as the deployment XML file. + +For more information, see the following: + +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml_File[sessions.xml +File] +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml_File[project.xml +File] +* link:Introduction_to_Projects_(ELUG)[Introduction to Projects]. + +=== Descriptors + +Descriptors describe how a Java class relates to a data source +representation. They relate object classes to the data source at the +data model level. For example, persistent class attributes may map to +database columns. + +EclipseLink uses descriptors to store the information that describes how +an instance of a particular class can be represented in a data source +(see link:#Mappings[Mappings]). Most descriptor information can be +defined by the Workbench, then read from the project XML file at run +time. + +See link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] for more information. + +=== Mappings + +Mappings describe how individual object attributes relate to a data +source representation. Mappings can involve a complex transformation or +a direct entry. + +EclipseLink uses mappings to determine how to transform data between +object and data source representation. Most mapping information can be +defined by the Workbench, then read from the project XML file at run +time. Mappings are owned by link:#Descriptors[Descriptors]. + +See link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] +for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Queries_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Queries_(ELUG).adoc new file mode 100644 index 00000000000..ed4f64a124e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Queries_(ELUG).adoc @@ -0,0 +1,2194 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Queries_(ELUG)[Related +Topics] + +EclipseLink enables you to create, read, update, and delete persistent +objects or data using queries in both Java EE and non-Java EE +applications for both relational and nonrelational data sources. + +== Query Types + +This table lists the query types that you can build in EclipseLink. + +[#Table 104-1]## + +Query Type + +Description + +EclipseLink Workbench + +Java + +Session Queries + +A query implicitly constructed and executed by a Session based on input +parameters used to perform the most common data source actions on +objects. + +Database Queries + +A query also known as a query object query. An instance of DatabaseQuery +that you create and then execute to perform any data source action on +either objects or data. You can further refine a DatabaseQuery by also +creating and configuring its Call (see Call Queries). + +Named Queries + +An instance of DatabaseQuery stored by name in a Session or a +descriptor’s DescriptorQueryManager where it is constructed and prepared +once. Such a query can then be repeatedly executed by name. + +Call Queries + +An instance of Call that you create and then either execute directly, +using a special Session API to perform limited data source actions on +data only, or execute indirectly in the context of a DatabaseQuery. +EclipseLink supports Call instances for custom SQL, stored procedures, +and EIS interactions. + +Redirect Queries + +An instance of MethodBasedQueryRedirector (taking the name of a static +method and the Class in which it is defined as parameters) set on a +named query. When the query is executed, the static method is invoked. + +Historical Queries + +Any query executed in the context of a historical session using the +time-aware features of the EclipseLink Expression framework. + +Interface and Inheritance Queries + +Any query that references an interface type or super and subclasses of +an inheritance hierarchy. + +Descriptor Query Manager Queries + +The DescriptorQueryManager defines a default DatabaseQuery for each +basic data source operation (create, read, update, and delete), and +provides an API with which you can customize either the DatabaseQuery or +its Call. + +For more information, see the following: + +* link:Using%20Basic%20Query%20API%20(ELUG)[Using Basic Query API] +* link:Using%20Advanced%20Query%20API%20(ELUG)[Using Advanced Query API] +* link:#Query_Concepts[Query Concepts] + +== Query Concepts + +In general, querying a data source means performing an action on or +interacting with the contents of the data source. To do this, you must +be able to perform the following: + +* Define an action in a syntax native to the data source being queried +* Apply the action in a controlled fashion +* Manage the results returned by the action (if any) + +Specific to EclipseLink, you must also consider how the query affects +the EclipseLink cache. For more information, see +link:#Queries_and_the_Cache[Queries and the Cache]. + +This section introduces the following query concepts unique to +EclipseLink: + +* link:#Call[Call] +* link:#DatabaseQuery[DatabaseQuery] +* link:#Data-Level_and_Object-Level_Queries[Data-Level and Object-Level +Queries] +* link:#Summary_Queries[Summary Queries] +* link:#Descriptor_Query_Manager[Descriptor Query Manager] +* link:#EclipseLink_Expressions[EclipseLink Expressions] +* link:#Query_Keys[Query Keys] +* link:#Query_Languages[Query Languages] + +=== Call + +In EclipseLink, the `+Call+` object encapsulates an operation or action +on a data source. EclipseLink provides a variety of `+Call+` types such +as structured query language (SQL), Enterprise Java Beans Query Language +(EJB QL), Java Persistence Query Language (JP QL), Extensible Markup +Language (XML), and enterprise information system (EIS). + +You can execute a `+Call+` directly or in the context of a +`+DatabaseQuery+`. + +=== DatabaseQuery + +A `+DatabaseQuery+` object is an abstraction that associates additional +customization and optimization options with the action encapsulated by a +`+Call+`. By separating these options from the `+Call+`, EclipseLink can +provide sophisticated query capabilities across all `+Call+` types. + +For more information, see link:#Database_Queries[Database Queries]. + +=== Data-Level and Object-Level Queries + +In EclipseLink, queries can be defined for objects or data, as follows: + +* *Object-level* queries (see link:#Object-Level_Read_Query[Object-Level +Read Query] and link:#Object-Level_Modify_Query[Object-Level Modify +Query]) are object-specific and return data as objects in your domain +model. They are the preferred type of query for mapped data. By far, +object-level `+DatabaseQuery+` queries are the most common query used in +EclipseLink. +* *Data-level* queries (see link:#Data-Level_Read_Query[Data-Level Read +Query] and link:#Data-Level_Modify_Query[Data-Level Modify Query]) are +used to query database tables directly, and are an appropriate way to +work with unmapped data. + +=== Summary Queries + +While data-level queries return raw data and object-level queries return +objects in your domain model, summary queries return data about objects. +EclipseLink provides link:#Partial_Object_Queries[Partial Object +Queries] to return a set of objects with only specific attributes +populated, and link:#Report_Query[Report Queries] to return summarized +(or rolled-up) data for specific attributes of a set of objects. + +=== Descriptor Query Manager + +In addition to storing named queries applicable to a particular class +(see link:#Named_Queries[Named Queries]), you can also use the +`+DescriptorQueryManager+` to override the default action that +EclipseLink defines for common data source operations. For more +information, see link:#Descriptor_Query_Manager_Queries[Descriptor Query +Manager Queries]. + +=== EclipseLink Expressions + +EclipseLink expressions let you specify query search criteria based on +your domain object model. When you execute the query, EclipseLink +translates these search criteria into the appropriate query language for +your platform. + +EclipseLink provides the following two public classes to support +expressions: + +* The `+Expression+` class represents an expression that can be anything +from a simple constant to a complex clause with boolean logic. You can +manipulate, group, and integrate expressions. +* The `+ExpressionBuilder+` class is the factory for constructing new +expressions. + +You can specify a selection criterion as an `+Expression+` with +`+DatabaseQuery+` method `+setSelectionCriteria+` (see +link:#Database_Queries[Database Queries]), and in a finder that takes an +`+Expression+` (see link:#Expression_Finders[Expression Finders]). + +For more information about using EclipseLink expressions, see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions]. + +=== Query Keys + +A query key is a schema-independent alias for a database field name. +Using a query key, you can refer to a field using a schema-independent +alias. In relational projects only, EclipseLink automatically creates +query keys for all mapped attributes. The name of the query key is the +name of the class attribute specified in your object model. + +You can configure query keys in a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Query_Keys[class +descriptor] or +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Interface_Query_Keys[interface +descriptor]. + +You can use query keys +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Query_Keys_and_Expressions[in +expressions] and to query +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Queries_on_Variable_One-to-One_Mappings[variable +one-to-one mappings]. + +=== Query Languages + +Using EclipseLink, you can express a query using any of the following +query languages: + +* link:#SQL_Queries[SQL Queries] +* link:#JP_QL_Queries[JP QL Queries] +* link:#XML_Queries[XML Queries] +* link:#EIS_Interactions[EIS Interactions] +* link:#Query-by-Example[Query-by-Example] +* link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Expressions] + +In most cases, you can compose a query directly in a given query +language or, preferably, you can construct a `+DatabaseQuery+` with an +appropriate `+Call+` and specify selection criteria using an EclipseLink +`+Expression+`. Although composing a query directly in SQL appears to be +the simplest approach (and for simple operations or operations on +unmapped data, it is), using the `+DatabaseQuery+` approach offers the +compelling advantage of confining your query to your domain object model +and avoiding dependence on data source schema implementation details. + +We recommend that you compose your queries using JP QL or +`+Expression+`. + +==== SQL Queries + +SQL is the most common query language for applications that use a +relational database data source. + +You can execute custom SQL directly using `+Session+` methods +`+executeSelectingCall+` and `+executeNonSelectingCall+`, or you can +construct a `+DatabaseQuery+` with an appropriate `+Call+`. + +EclipseLink provides a variety of link:#SQL_Calls[SQL `+Call+` objects] +for use with stored procedures and, with Oracle Databases, stored +functions. + +EclipseLink also supports PL/SQL call for Oracle stored procedures with +PL/SQL data types. For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using%20a%20StoredProcedureCall[Using +a StoredProcedureCall]. + +==== JP QL Queries + +See +link:Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)[What +You May Need to Know About Querying with Java Persistence Query +Language] for more information. + +==== XML Queries + +You can use EclipseLink XML to query XML data stored in an Oracle +Database XMLType field. For more information, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#CHDFIFEF[Direct-to-XMLType +Mapping] and +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#CJADHIHG[XMLType +Functions]. + +==== EIS Interactions + +When you execute an EclipseLink query using an +link:#Enterprise_Information_System_(EIS)_Interactions[EIS `+Call+`], +EclipseLink converts your selection criteria into an XML format +appropriate for your JCA adapter. + +If supported by your JCA adapter, you can use the XQuery language by +executing an link:#XQueryInteraction[XQueryInteraction] either directly +or in the context of a `+DatabaseQuery+`. + +==== Query-by-Example + +Query-by-example is a simple and intuitive way to express a query. To +specify a query-by-example, provide a sample instance of the persistent +object to query, and set appropriate values on only the data members on +which you wish to query. + +You can use a constructor with a reference class argument to create a +sample instance or example object. Alternatively, you can use a +combination of any other type of constructor and a `+setReferenceClass+` +method of your query object. If you fail to specify the reference class, +a `+QueryException+` will be thrown. + +Query-by-example lets you query for an object based on any attribute +that uses a direct mapping or a one-to-one relationship (including those +with nesting). + +[width="100%",cols="<100%",] +|=== +|*Note*: Query-by-example does not support any other relationship +mapping types. +|=== + +Set only the attributes on which you base the query; set all other +attributes to `+null+`. By default, EclipseLink ignores attributes in +the sample instance that contain `+null+`, zero (0), empty strings, and +`+FALSE+`. You can modify this list of values (and define other query by +example options) by specifying +link:Using%20Basic%20Query%20API%20(ELUG)#Defining_a_QueryByExamplePolicy[a +`+QueryByExamplePolicy+`]. + +Query-by-example uses the `+AND+` operator to tie the attribute +comparisons together. By default, attribute values in the sample +instance are compared against corresponding values of candidate objects +using `+EQUALS+` operator. You can modify this behaviour using the +`+QueryByExamplePolicy+`. + +Both `+ReadAllQuery+` and `+ReadObjectQuery+` provide a +`+setExampleObject+` method and `+setQueryByExamplePolicy+` method that +you can use to specify selection criteria based on an example object +instance. + +For more information and examples, see +link:Using%20Basic%20Query%20API%20(ELUG)#Reading_Objects_Using_Query-By-Example[Reading +Objects Using Query-By-Example]. + +== Building Queries + +You can build queries using Workbench or Java, using the EclipseLink +API. + +Some queries are implicitly constructed for you based on passed in +arguments and executed in one step (for example, session queries, as +described in link:#Session_Queries[Session Queries]) and others you +explicitly create, configure, and then execute (for example, +link:#Database_Queries[Database Queries]). + +For more information, see the following: + +* link:Using%20Basic%20Query%20API%20(ELUG)[Using Basic Query API] +* link:Using%20Advanced%20Query%20API%20(ELUG)[Using Advanced Query API] + +== Executing Queries + +In EclipseLink, you execute most queries using the `+Session+` API +summarized in the link:#Table_104-2[Session Methods for Executing a +Query] table. + +[#Table 104-2]## *_Session Methods for Executing a Query_* + +Query Type + +Session Method + +Advantages and Disadvantages + +Session Queries + +readObjectreadAllObjects writeObject writeAllObjects deleteObject +deleteAllObjects insertObject updateObject + +Advantages: the most convenient way to perform common data source +operations on objects. + +Disadvantages: less control over query execution and results; less +efficient for frequently executed queries. + +Database Queries Named Queries Redirect Queries + +executeQuery + +Advantages: greatest configuration and execution flexibility; can take +advantage of named queries for efficiency. + +Disadvantages: you must explicitly create and configure DatabaseQuery +and possibly Call objects. + +Call Queries + +executeSelectingCall executeNonSelectingCall + +Advantages: convenient way to directly apply an action to unmapped data. + +Disadvantages: least control over query execution and results; your +application must do more work to handle raw data results. + +Note: We recommend that you perform all data source operations using a +unit of work: doing so is the most efficient way to manage transactions, +concurrency, and referential constraints. For more information, see +Introduction to EclipseLink Transactions. + +Alternatively, you can execute queries outside of a unit of work using a +session API directly, but doing so places greater responsibility on your +application to manage transactions, concurrency, and referential +constraints. + +EclipseLink executes `+DescriptorQueryManager+` queries when you execute +a session query. For more information, see +link:#Descriptor_Query_Manager_Queries[Descriptor Query Manager +Queries]. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +(for example: +`+setSQLString(String sql), readAllObjects(Class class, String sql)+` +methods) makes your application vulnerable to SQL injection attacks. +|=== + +For more information, see the following: + +* link:Using%20Basic%20Query%20API%20(ELUG)[Using Basic Query API] +* link:Using%20Advanced%20Query%20API%20(ELUG)[Using Advanced Query API] + +== Handling Query Results + +EclipseLink queries generally return Java objects as their result set. +EclipseLink queries can return any of the following: + +* Entire objects, with all attributes populated and the object reflected +in the cache. +* link:#Collection_Query_Results[Collections of objects]. +* Partial objects, with only the attributes you specify populated and +without the object reflected in the cache (see +link:#Report_Query_Results[Report Query Results]). +* link:#Stream_and_Cursor_Query_Results[Streams of objects]. +* Collections of records. +* Report summaries. + +=== Collection Query Results + +A collection is a group of Java objects contained by an instance of +`+Collection+` or `+Map+` + +By default, queries that return more than one object return their +results in a `+Vector+`. + +You can configure EclipseLink to return query results in any concrete +instance of `+Collection+` or `+Map+`. + +Collection results are supported by all EclipseLink query types. + +For information and examples on how to configure and handle collection +query results, see link:Using%20Basic%20Query%20API%20(ELUG)[Handling +Collection Query Results]. + +=== Report Query Results + +A `+ReportQuery+` (a type of partial object query) returns summary data +for selected objects using the database reporting functions and features +supported by your platform. Although the report query returns data (not +objects), it does enable you to query the returned data and specify it +at the object level. + +By default, a `+ReportQuery+` returns a collection (see +link:#Collection_Query_Results[Collection Query Results]) of +`+ReportQueryResult+` objects, one collection per database row returned. +You can use the `+ReportQuery+` API to configure how a `+ReportQuery+` +returns its results. For more information see +link:Using%20Basic%20Query%20API%20(ELUG)[Handling Report Query +Results]. + +For more information, see the following: + +* link:#Report_Query[Report Query] +* link:Using%20Basic%20Query%20API%20(ELUG)#Handling_Report_Query_Results[Handling +Report Query Results] +* link:#Partial_Object_Queries[Partial Object Queries]. + +=== Stream and Cursor Query Results + +A stream is a view of a collection, which can be a file, a device, or a +`+Vector+`. A stream provides access to the collection, one element at a +time in sequence. This makes it possible to implement stream classes in +which the stream does not contain all the objects of a collection at the +same time. + +Large result sets can be resource-intensive to collect and process. To +improve performance and give the client more control over the returned +results, configure EclipseLink queries to use a cursor or stream. + +Cursors & streams are supported by all subclasses of `+DataReadQuery+` +and `+ReadAllQuery+`. + +For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Handling_Cursor_and_Stream_Query_Results[Handling +Cursor and Stream Query Results]. + +== Session Queries + +Sessions provide query methods that lets you perform the object +operations listed in the following table. + +[#Table 104-3]## *_Session Object Query Summary_* + +Session Type + +Create + +Read + +Update + +Delete + +UnitOfWork + +registerObject + +readObject readAllObjects + +NA + +deleteObject deleteAllObjects + +Server + +NA + +NA + +NA + +NA + +ClientSession + +NA + +readObject readAllObjects + +NA + +NA + +DatabaseSession + +insertObject + +readObject readAllObjects + +updateObject writeObject writeAllObjects + +deleteObject deleteAllObjects + +[width="100%",cols="<100%",] +|=== +|*Note*: We recommend that you perform all data source operations using +a unit of work: doing so is the most efficient way to manage +transactions, concurrency, and referential constraints. For more +information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. +|=== + +These methods implicitly construct and execute a `+DatabaseQuery+` based +on any of the following input parameters and return `+Object+` or +`+Object+` collection: + +* Reference `+Class+` (the `+Class+` of objects that the query accesses) +* Reference `+Class+` and `+Call+` +* Reference `+Class+` and `+Expression+` +* Example object with primary key set + +These methods are a convenient way to perform the most common data +source operations on objects. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into these +methods makes your application vulnerable to SQL injection attacks. +|=== + +To access all configurable options to further refine and optimize a +query, consider using a corresponding `+DatabaseQuery+` directly. For +more information, see link:#Database_Queries[Database Queries]. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_Session_Queries[Using +Session Queries]. + +=== Read-Object Session Queries + +Read-object queries return the first instance of an `+Object+` that +matches the specified selection criteria, and read-all object queries +return all such instances. + +You can also pass in a domain `+Object+` with its primary key set and +EclipseLink will construct and execute a read-object query to select +that object. This is one form of +link:#Query-by-Example[Query-by-Example]. + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Read Objects with a Session Query]. + +=== Create, Update, and Delete Object Session Queries + +We recommend that you create and update objects using a unit of work: +doing so is the most efficient way to manage transactions, concurrency, +and referential constraints. For more information, see +link:Introduction_to_EclipseLink_Transactions_(ELUG)[Introduction to +EclipseLink Transactions]. + +However, you can also create and update objects using a session query. +These session queries are a convenient way to modify objects directly on +the database when you manage simple, nonbusiness object data that has no +relationships (for example, user preferences). + +If you know an object is new, you can use an `+insertObject+` method to +avoid having EclipseLink perform an existence check. If you do not know +if an object is new, use the `+updateObject+`, `+writeObject+`, or +`+writeAllObject+` methods: EclipseLink performs an existence check if +necessary. + +When you execute a write session query, it writes both the object and +its privately owned parts to the database. To manage this behavior, use +a corresponding `+DatabaseQuery+` (see +link:#Object-Level_Modify_Queries_and_Privately_Owned_Parts[Object-Level +Modify Queries and Privately Owned Parts]). + +Using the `+Session+` method `+deleteObject+`, you can delete a specific +object. Using the Session method `+deleteAllObjects+`, you can delete a +collection of objects. Each specified object and all its privately owned +parts are deleted. In the case of `+deleteAllObjects+`, all deletions +are performed within a single transaction. + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Create, Update, and Delete Objects with a Session Query]. + +== Database Queries + +All session types provide an `+executeQuery+` method that takes any of +the following types of `+DatabaseQuery+`: + +* link:#Object-Level_Read_Query[Object-Level Read Query] +* link:#Data-Level_Read_Query[Data-Level Read Query] +* link:#Object-Level_Modify_Query[Object-Level Modify Query] +* link:#Data-Level_Modify_Query[Data-Level Modify Query] +* link:#Report_Query[Report Query] + +Using `+DatabaseQuery+` method `+setCall+`, you can define your own +`+Call+` to accommodate a variety of data source options such as SQL +(including stored procedures and stored functions), EJB QL queries, and +EIS interactions. For more information, see link:#Call_Queries[Call +Queries]. + +Using `+DatabaseQuery+` method `+setSelectionCriteria+`, you can specify +your selection criteria using an EclipseLink `+Expression+`. For more +information, see link:#EclipseLink_Expressions[EclipseLink Expressions]. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_DatabaseQuery_Queries[Using +DatabaseQuery Queries]. + +=== Object-Level Read Query + +Using an `+ObjectLevelReadQuery+`, you can query your data source and +return `+Object+` instances that match the specified selection criteria. +This section describes the following: + +* link:#ReadObjectQuery[ReadObjectQuery] +* link:#ReadAllQuery[ReadAllQuery] +* link:#Partial_Object_Queries[Partial Object Queries] +* link:#Read-Only_Query[Read-Only Query] +* link:#Join_Reading_and_Object-Level_Read_Queries[Join Reading and +Object-Level Read Queries] +* link:#Fetch_Groups_and_Object-Level_Read_Queries[Fetch Groups and +Object-Level Read Queries] + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#How_to_Read_Objects_Using_a_DatabaseQuery[How +to Read Objects Using a DatabaseQuery]. + +==== ReadObjectQuery + +Using a `+ReadObjectQuery+`, you can query your data source and return +the first object that matches the specified selection criteria. + +==== ReadAllQuery + +Using a `+ReadAllQuery+`, you can query your data source and return a +`+Collection+` of all the objects that match the specified selection +criteria. + +==== Partial Object Queries + +By default, an `+ObjectLevelReadQuery+` returns all attributes of the +objects read. + +If you require only certain attributes from selected objects, you can +create a partial object query by using `+ObjectLevelReadQuery+` method +`+addPartialAttributes+`. Using this method, you can improve query +performance by making EclipseLink return objects with only specified +attributes populated. + +Applications frequently use partial object queries to compile a list for +further selection. For example, a query to find the names and addresses +of all employees over the age of 40 returns a list of data (the names +and addresses) that partially represents objects (the employees). A +common next step is to present this list so the user can select the +required object or objects from the list. Later retrieval of a complete +object is simplified because EclipseLink always includes the primary key +attribute (even if you do not add it as a partial attribute. + +Consider the following when you use partial object queries: + +* You cannot edit or cache partial objects. +* Unspecified attributes will be left `+null+`. +* You cannot have two partial attributes of the same type. +* You cannot add a partial attribute which is of the same type as the +class being queried. + +If you require only summary information for certain attributes from +selected objects, it is more efficient to use a +link:#Report_Query[Report Query]. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Reading_Objects_Using_Partial_Object_Queries[Reading +Objects Using Partial Object Queries]. + +==== Read-Only Query + +In cases where you know that data is read-only, you can improve +performance by specifying a query as read-only: this tells EclipseLink +that any object returned by the query is immutable. + +For more information, see the following: + +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Read-Only_Descriptors[Configuring +Read-Only Descriptors] +* link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Read-Only_Queries[Using +Read-Only Queries] +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Read-Only_Queries_for_Optimization[How +to Use Read-Only Queries for Optimization] + +==== Join Reading and Object-Level Read Queries + +Join reading is a query optimization feature that allows a single query +for a class to return the data to build the instances of that class and +its related objects. Use this feature to improve query performance by +reducing database access. By default, relationships are not join-read: +each relationship is fetched separately when accessed if you are using +indirection (lazy loading) or as a separate database query if you are +not using indirection. For more information, see +link:Introduction%20to%20Mappings%20(ELUG)[Indirection (Lazy Loading)]. + +You can use join reading with `+ReadObjectQuery+` and `+ReadAllQuery+` +to join the mapped relationships that the link:#Table_104-4[Join Reading +by Mapping Type] table lists. Join reading is not currently supported +for any other relationship mappings. + +[#Table 104-4]## *_Join Reading by Mapping Type_* + +Query + +Mapping Type + +ReadObjectQuery + +One-to-One Mapping + +One-to-Many Mapping + +ReadAllQuery + +Many-to-Many Mapping + +Direct Collection Mapping + +Direct Map Mapping + +Aggregate Collection Mapping + +Join reading can specify multiple and nested relationships to be joined. +Nested joins are expressed through using expressions (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Expressions +for Joining and Complex Relationships]). + +Outer joins can also be used with join reading through using the +expression outer join API. If an outer join is not used, objects with +missing one-to-one relationships or empty one-to-many relationships will +be filtered from the result set. You can also configure an object-level +read query to allow inherited subclasses to be outer-joined to avoid the +cost of a single query per class. You can also specify inner or outer +joins using the `+useInnerJoinFetch+` or `+useOuterJoinFetch+` method of +any of the mappings listed in the link:#Table_104-4[Join Reading by +Mapping Type] table. + +You can use join reading with custom SQL or stored procedures, but the +query must ensure that all of the required data to build all of the +join-read objects is returned. If the result set includes the same +tables or fields, they must be returned in the same table order as +EclipseLink would have generated. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)[Using Join Reading with +ObjectLevelReadQuery]. + +===== Avoiding Join-Reading Duplicate Data + +Join reading can result in returning duplicate data if a one-to-many or +a shared one-to-one relationship is joined. Although EclipseLink +correctly filters the duplicate results from the object result, the +duplicate data still must be fetched from the database and can degrade +performance, especially if multiple one-to-many relationships are +joined. In general, batch reading can be used as a better alternative to +join reading, as it does not require fetching duplicate data. + +We recommend that you use one-to-many joining with caution, because it +does not scale well in many situations. + +Because the main cost of a `+ReadObjectQuery+` is SQL execution, the +performance of a one-to-many join in this case is usually better than a +query without joining. + +However, because the main cost of a `+ReadAllObjectQuery+` is +row-fetching, which the duplicate data of a join increases, the +performance of a one-to-many join in this case is less efficient than +batch reading in many scenarios (even though one-to-many joining is more +efficient than reading the objects one-by-one). + +This is mainly due to the fact that a one-to-many join reads in +duplicate data: the data for each source object will be duplicated for +each target object. Depending on the size of the one-to-many +relationship and the size of the source object’s row, this can become +very inefficient, especially if the source object has a Large Object +(LOB). + +If you use multiple or nested one-to-many joins in the same query, the +problem is compounded: the source object’s row is duplicated _n*m_ +times, and each target object _n_ and _m_ times respectively. This can +become a major performance issue. + +To handle empty collections, you must use outer joins, so the queries +can easily become very database intensive. Batch reading has the +advantage of only returning the required data, and does not require +outer joins. + +We recommend that you use batch reading to optimize querying +relationships in read-all applications. + +For more information, see the following: + +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[How to Use +Batch and Join Reading for Optimization] +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[Reading +Case 2: Batch Reading Objects] + +==== Fetch Groups and Object-Level Read Queries + +You can use a fetch group with a `+ReadObjectQuery+` or +`+ReadAllQuery+`. When you execute the query, EclipseLink retrieves only +the attributes in the fetch group. EclipseLink automatically executes a +query to fetch all the attributes excluded from this subset when and if +you call a getter method on any one of the excluded attributes. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)[Fetch Groups] +* link:Using%20Advanced%20Query%20API%20(ELUG)[Using Queries with Fetch +Groups] + +=== Data-Level Read Query + +Using a `+DataLevelReadQuery+`, you can query your data source and +return `+Object+` instances that match the specified selection criteria. +This section describes the following: + +* link:#DataReadQuery[DataReadQuery] +* link:#DirectReadQuery[DirectReadQuery] +* link:#ValueReadQuery[ValueReadQuery] + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Read Data with a DatabaseQuery]. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into +constructors of such objects as `+DataReadQuery+`, `+DirectReadQuery+` +and `+ValueReadQuery+` makes your application vulnerable to SQL +injection attacks. +|=== + +==== DataReadQuery + +Use a `+DataReadQuery+` to execute a selecting SQL string that returns a +`+Collection+` of the `+Record+` objects representing the result set. + +==== DirectReadQuery + +Use a `+DirectReadQuery+` to read a single column of data (that is, one +field) that returns a `+Collection+` of values representing the result +set. + +==== ValueReadQuery + +Use a `+ValueReadQuery+` to read a single data value (that is, one +field). A single data value is returned, or null if no rows are +returned. + +=== Object-Level Modify Query + +With an `+ObjectLevelModifyQuery+`, you can query your data source to +create, update, and delete objects, using the following: + +* link:#WriteObjectQuery[WriteObjectQuery] +* link:#UpdateObjectQuery[UpdateObjectQuery] +* link:#InsertObjectQuery[InsertObjectQuery] +* link:#DeleteObjectQuery[DeleteObjectQuery] +* link:#UpdateAllQuery[UpdateAllQuery] +* link:#DeleteAllQuery[DeleteAllQuery] +* link:#Object-Level_Modify_Queries_and_Privately_Owned_Parts[Object-Level +Modify Queries and Privately Owned Parts] + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Create, Update, and Delete Objects with a DatabaseQuery]. + +[width="100%",cols="<100%",] +|=== +|*Note:* We recommend that you create and update objects using an +EclipseLink `+UnitOfWork+`: doing so is the most efficient way to manage +transactions, concurrency, and referential constraints. For more +information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. +|=== + +==== WriteObjectQuery + +If you do not know whether or not an object is new, use a +`+WriteObjectQuery+`: EclipseLink performs an existence check if +necessary to determine whether to perform an insert or an update. + +If you do know whether or not an object exists, you can avoid the +existence check by using an link:#UpdateObjectQuery[UpdateObjectQuery] +or link:#InsertObjectQuery[InsertObjectQuery]. + +==== UpdateObjectQuery + +If you know that the object you want to modify exists, use an +`+UpdateObjectQuery+` to avoid having EclipseLink perform an existence +check. + +==== InsertObjectQuery + +If you know an object is new, you can use an `+InsertObjectQuery+` to +avoid having EclipseLink perform an existence check. + +==== DeleteObjectQuery + +To delete a specific object, construct a `+DeleteObjectQuery+` with a +single specific object as an argument. + +==== UpdateAllQuery + +The `+UpdateAllQuery+` allows you to take an expression and update a set +of objects (at the object level) without loading the objects into +memory. You can updated to either a specific or relative value. For +example, you can set the value to 5 or to increase by 5 percent. + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Create, Update, and Delete Objects with a DatabaseQuery]. + +==== DeleteAllQuery + +To delete multiple objects, construct a `+DeleteAllQuery+` and use its +`+setObjects+` method to configure the collection of specific objects to +delete. Use the `+DeleteAllQuery+` method `+setReferenceClass+` to +configure the reference class of the objects to delete. Each specified +object is deleted, but its privately owned parts are not. + +In the case of a `+DeleteAllQuery+`, all deletions are performed within +a single transaction. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)[Using DeleteAll Queries]. + +==== Object-Level Modify Queries and Privately Owned Parts + +When you execute a create or update object `+DatabaseQuery+`, it writes +both the object and its privately owned parts to the database by +default. To create a query that does not update privately owned parts, +use the `+DatabaseQuery+` method `+dontCascadeParts+`. Use this method +to do the following: + +* Increase performance when you know that only the object’s direct +attributes have changed. +* Manually resolve referential integrity dependencies when you write +large groups of new, independent objects. + +[width="100%",cols="<100%",] +|=== +|*Note*: Because the unit of work resolves referential integrity +internally, this method is not required if you use the unit of work to +write to the data source. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. +|=== + +=== Data-Level Modify Query + +Using a `+DataModifyQuery+`, you can query your data source to execute a +nonselecting SQL statement. It is equivalent to `+Session+` method +`+executeNonSelectingCall+`. + +For more information, see link:Using%20Basic%20Query%20API%20(ELUG)[How +to Update Data with a DatabaseQuery]. + +=== Report Query + +If you want to summarize (or roll up) certain attributes of a set of +objects, you can use a `+ReportQuery+`. + +A `+ReportQuery+` returns summary data from a set of objects and their +related objects. That is, it returns data about objects. It can also +return multiple objects. A `+ReportQuery+` lets you you query and +specify the data at the object level. To build a report query, you +specify the search criteria, the data you require about the objects, and +how that data should be summarized. + +For example, you can create a report query to compute the average age of +all employees in your company. The report query is not interested in the +specific objects (the employees), but rather, summary information about +them (their average age). + +A `+ReportQuery+` lets you do the following: + +* Specify a subset of the object’s attributes and its related object’s +attributes, which allows you to query for lightweight information. +* Build complex object-level expressions for the selection criteria and +ordering criteria. +* Use data source aggregation functions (supported by your platform), +such as `+SUM+`, `+MIN+`, `+MAX+`, `+AVG+`, and `+COUNT+`. +* Use expressions to group data. +* Request primary key attributes with each `+ReportQueryResult+`. This +makes it easy to request the real object from a lightweight result. + +A `+ReportQuery+` is the most efficient form of +link:#Partial_Object_Queries[Partial Object Queries], because it takes +advantage of the reporting capabilities of your data source (if +available). We recommend that you use `+ReportQuery+` to do partial +object queries. + +The `+ReportQuery+` API returns a collection of `+ReportQueryResult+` +objects, similar in structure and behavior to a `+Record+` or a `+Map+`. +For more information, see link:#Report_Query_Results[Report Query +Results]. + +For more information, see the following: + +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[Reading +Case 1: Displaying Names in a List] +* link:Using%20Basic%20Query%20API%20(ELUG)[Reading Objects Using Report +Queries] +* link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Named Queries +at the Descriptor Level] + +== Named Queries + +When you use a session query method like `+readAllObjects+` (see +link:#Session_Queries[Session Queries]), EclipseLink creates a +corresponding `+ReadAllQuery+`, which builds other objects it needs to +perform its task. When EclipseLink finishes execution of the +`+readAllObjects+` method, these objects are discarded. Each time you +call this session method, EclipseLink creates these related objects +again, uses them once, and then discards them. + +Alternatively, you can create a `+DatabaseQuery+` (see +link:#Database_Queries[Database Queries]) and store it by name at the +descriptor-level (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Named Queries at +the Descriptor Level]) or session-level (see +link:Configuring%20a%20Session%20(ELUG)[Configuring Named Queries at the +Session Level]). + +EclipseLink prepares a named query once, and it (and all its associated +supporting objects) can be efficiently reused thereafter making a named +query well suited for frequently executed operations. + +Using the `+Session+` API (see +link:Using%20Basic%20Query%20API%20(ELUG)[Using Named Queries]), you can +execute these queries by name, passing in any required arguments. + +*When to Use Named Queries* + +For a reasonably complex query that you execute frequently, you should +consider making the query a named query. + +If a query is global to a project, +link:Configuring%20a%20Session%20(ELUG)#Configuring_Named_Queries_at_the_Session_Level[configure +the named query at the session level]. + +If a query is global to a `+Class+`, +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Queries_at_the_Descriptor_Level[configure +the named query at the descriptor level]. For more information about +descriptor level query configuration, see +link:#Descriptor_Query_Manager_Queries[Descriptor Query Manager +Queries]. + +For a very complex query, you can delegate query execution to your own +static method using a special form of a named query called a +link:#Redirect_Queries[Redirect Query]. + +*When Not to Use Named Queries* + +Rarely used queries may be more efficient when built on an as-needed +basis. If you seldom use a given query, it may not be worthwhile to +build and store that query when you invoke a session. + +== Call Queries + +All session types provide `+executeSelectingCall+` and +`+executeNonSelectingCall+` methods that take any of the following +`+Call+` types: + +* link:#SQL_Calls[SQL Calls] +* link:#Enterprise_Information_System_(EIS)_Interactions[EIS +Interactions] + +You can also execute a `+Call+` in the context of a `+DatabaseQuery+`. +For more information on `+DatabaseQuery+`, see +link:#Database_Queries[Database Queries]. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +(for example: `+executeSelectingCall(String sql)+` method) makes your +application vulnerable to SQL injection attacks. +|=== + +=== SQL Calls + +SQL calls access fields in a relational database. EclipseLink supports +the following SQL calls: + +* link:##SQLCall[SQLCall] +* link:#StoredProcedureCall[StoredProcedureCall] +* link:#StoredFunctionCall[StoredFunctionCall] + +Using the `+Call+` API (or SQL string conventions), you can specify +input, output, and input-output parameters and assign values for input +and input/output parameters. + +Using a descriptor `+ReturningPolicy+`, you can control whether or not +EclipseLink writes a parameter out, retrieves a value generated by the +database, or both. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Returning +Policy]. + +==== SQLCall + +Using a `+SQLCall+`, you can specify any arbitrary SQL statement and +execute it on a data source. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +makes your application vulnerable to SQL injection attacks. +|=== + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_SQLCall[Using a +SQLCall]. + +==== StoredProcedureCall + +A stored procedure is composed of one or more procedural language +statements, such as Procedural Language/Structured Query Language +(PLSQL), stored by name in the database. Most relational databases +support stored procedures. + +You invoke a stored procedure to execute logic and access data from the +data source. + +Using a `+StoredProcedureCall+`, you can detect execution errors, +specify input parameters, output parameters, and input/output +parameters. However, stored procedures do not provide a return value. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_StoredProcedureCall[Using +a StoredProcedureCall]. + +==== StoredFunctionCall + +A stored function is an Oracle Database feature that provides all the +functionality of a stored procedure as well as the ability to return a +value. + +Using a `+StoredFunctionCall+`, you can specify all the features of a +`+StoredProcedureCall+` as well as the field name of the return value. + +For more information, see +link:Using%20Basic%20Query%20API%20(ELUG)#Using_a_StoredFunctionCall[Using +a StoredFunctionCall]. + +=== Enterprise Information System (EIS) Interactions + +To invoke a query through a Java EE Connector Architecture (JCA) adapter +to a remote EIS, you use an `+EISInteraction+`, an instance of `+Call+`. +EclipseLink supports the following `+EISInteraction+` types: + +* link:#IndexedInteraction[IndexedInteraction] +* link:#MappedInteraction[MappedInteraction] +* link:#XMLInteraction[XMLInteraction] +* link:#XQueryInteraction[XQueryInteraction] +* link:#QueryStringInteraction[QueryStringInteraction] + +In each of these interactions, you specify a functional interface +(similar to a stored procedure) that identifies the function to invoke +on the EIS. This functional interface contains the following: + +* the function name; +* the record name (if different than the function name); +* a list of input arguments; +* a list of output arguments. + +For more information, see the following: + +* link:Introduction%20to%20EIS%20Projects%20(ELUG)#Introduction_to_EIS_Projects[Introduction +to EIS Projects] +* link:Using%20Basic%20Query%20API%20(ELUG)#Using_EIS_Interactions[Using +EIS Interactions] + +==== IndexedInteraction + +In an `+IndexedInteraction+`, you exchange data with the EIS using +indexed records. The order of the specification of the arguments must +match the order of the values defined in the indexed record. + +==== MappedInteraction + +In a `+MappedInteraction+`, you exchange data with the EIS using mapped +records. The arguments you specify map by name to fields in the mapped +record. + +==== XMLInteraction + +An `+XMLInteraction+` is a `+MappedInteraction+` that maps data to an +XML record. For an `+XMLInteraction+`, you may also provide an optional +root element name. + +==== XQueryInteraction + +If your JCA adapter supports the XQuery dynamic query language, you can +use an `+XQueryInteraction+`, which is an `+XMLInteraction+` that lets +you specify your XQuery string. + +==== QueryStringInteraction + +If your JCA adapter supports a query string based dynamic query +language, you can use a `+QueryStringInteraction+`, which is a +`+MappedInteraction+` that lets you specify the dynamic query string. + +== Redirect Queries + +To accommodate complex query logic, you can implement a *redirect +query*: a named query that delegates query execution control to your +application. For more information, see link:#Named_Queries[Named +Queries]. + +Redirect queries lets you define the query implementation in code as a +static method. When you invoke the query, the call redirects to the +specified static method. Redirect queries accept any arbitrary +parameters passed into them packaged in a `+Vector+`. + +Although most EclipseLink queries search for objects directly, a +redirect query generally invokes a method that exists on another class +and waits for the results. Redirect queries let you build and use +complex operations, including operations that might not otherwise be +possible within the query framework. + +By delegating query invocation to a method you provide, redirect queries +let you dynamically make decisions about how a query should be executed +based on argument values. + +Using a redirect query, you can do the following: + +* Dynamically configure the query options based on the arguments (for +example, ordering and query optimization). +* Dynamically define the selection criteria based on the arguments. +* Pass query-by-example objects or expressions as the arguments. +* Post-process the query results. +* Perform multiple queries or special operations. + +If you execute the query on a `+UnitOfWork+`, the results register with +that instance of `+UnitOfWork+`, so any objects you attempt to retrieve +with the invoke method must come from the `+Session+` cache. + +To create a redirect query, you implement the `+QueryRedirector+` +interface and set your implementation on a named query. + +We recommend that you take advantage of the +`+MethodBasedQueryRedirector+`, an instance of `+QueryRedirector+` that +EclipseLink provides. It takes the name of a static method and the +`+Class+` in which it is defined as parameters. When you set a +`+MethodBasedQueryRedirector+` on a named query, whenever +`+invokeQuery+` method is called on this instance, EclipseLink uses +reflection to invoke your static method instead. + +The advantages of using a `+MethodBasedQueryRedirector+` are as follows: + +* You can specify the static method and its `+Class+` dynamically. +* The class that provides the static method does not need to implement +`+QueryRedirector+`. +* Your static method can have any name. +* You can restrict the parameters to your static method to only a +`+Session+` and a `+Vector+` of arguments. + +For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Redirect_Queries[Using +Redirect Queries]. + +== Historical Queries + +By default, a session represents a view of the most current version of +objects and when you execute a query in that session, it returns the +most current version of selected objects. + +If your data source maintains past or historical versions of objects, +you can configure EclipseLink to access this historical data (see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Historical +Sessions]). + +Once you configure EclipseLink to take advantage of this historical +data, you can access historical versions using the historical queries +that the following table summarizes. + +[width="100%",cols="<100%",] +|=== +|*Note:* Flashback queries do not support view selects. This means you +cannot use a flashback query on objects with an inheritance policy for +read-all-subclasses views. For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. +|=== + +[#Table 104-5]## + +Historical Query Type + +Session + +Cache + +Must set maintainCache to false? + +Query both current and historical versions? + +Using an ObjectLevelReadQuery with an AsOfClause + +Regular1 + +Global + +Read-only + +Contains current versions + +Yes + +No + +Using an ObjectLevelReadQuery with Expression Operator asOf + +Regular1 + +Global + +Read and write + +Contains current versions + +No + +Yes + +Using an ObjectLevelReadQuery in a Historical Session + +Historical2 + +Isolated + +Read-only + +Contains static snapshot as of specified time + +No + +No + +1A server or database session based on an `+OraclePlatform+` for an +Oracle9i (or later) or based on an EclipseLink `+HistoryPolicy+`. 2A +session returned by a server or database session based on an +`+OraclePlatform+` or EclipseLink `+HistoryPolicy+` using the +`+acquireHistoricalSession+` method passing in an `+AsOfClause+`. + +=== Using an ObjectLevelReadQuery with an AsOfClause + +You can query historical versions of objects using an +`+ObjectLevelReadQuery+` configured with an `+AsOfClause+` (set by +`+ObjectLevelReadQuery+` method `+setAsOfClause+`) that specifies a +point in time that applies to every `+Expression+` used in the query. + +This type of historical query lets you query a static snapshot of object +versions as of the specified time. + +[width="100%",cols="<100%",] +|=== +|*Note*: To prevent corrupting the global shared cache with old versions +of objects, you must set `+ObjectLevelReadQuery+` method +`+maintainCache+` to `+false+` in this historical query. If you do not, +EclipseLink will throw an exception when you execute the query. +|=== + +For more information and examples of using an `+ObjectLevelReadQuery+` +with an `+AsOfClause+`, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Historical_Queries[Using +Historical Queries]. + +=== Using an ObjectLevelReadQuery with Expression Operator asOf + +You can query historical versions of objects using an +`+ObjectLevelReadQuery+` (such as `+ReadObjectQuery+` or +`+ReadAllQuery+`) containing one or more expressions that use +`+Expression+` operator `+asOf+` to specify a point in time on an +`+Expression+`-by-`+Expression+` basis. + +This type of historical query lets you combine both current and +historical versions of objects in the same query. + +If you configure the `+ObjectLevelReadQuery+` with an `+AsOfClause+`, +that point in time overrides the point in time specified in any +`+Expression+` in the query (see +link:#Using_an_ObjectLevelReadQuery_with_an_AsOfClause[Using an +ObjectLevelReadQuery with an AsOfClause]). + +For more information and examples of using an `+ObjectLevelReadQuery+` +with `+Expression+` operator `+asOf+`, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Historical_Queries[Using +Historical Queries]. + +=== Using an ObjectLevelReadQuery in a Historical Session + +Given a session that maintains historical versions of objects (based on +an appropriate `+OraclePlatform+` or EclipseLink `+HistoryPolicy+`), you +can use `+Session+` method `+acquireHistoricalSession+` passing in an +`+AsOfClause+` that specifies a point in time that applies to all +queries and expressions. + +This method returns a lightweight, read-only snapshot of object versions +as of the specified time. The cache used in this type of session is +isolated from the global shared cache. You do not need to set +`+ObjectLevelReadQuery+` method `+maintainCache+` to `+false+` in this +case. + +For more information and examples of using an `+ObjectLevelReadQuery+` +with a historical session, see +link:Using%20Advanced%20Query%20API%20(ELUG)[Using Historical Queries]. + +== Interface and Inheritance Queries + +When you define an interface descriptor (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Interface Descriptors]), you can perform queries on interfaces and +inheritance hierarchies. + +For more information, see the following: + +* link:Using%20Advanced%20Query%20API%20(ELUG)[Querying on Interfaces] +* link:Using%20Advanced%20Query%20API%20(ELUG)[Querying on an +Inheritance Hierarchy] + +== Oracle Extensions + +When you use EclipseLink with an Oracle Database, you can make use of +the following Oracle-specific query features from within your +EclipseLink applications: + +* link:#Hints[Hints] +* link:#Hierarchical_Queries[Hierarchical Queries] +* link:#Flashback_Queries[Flashback Queries] +* link:#Stored_Functions[Stored Functions] + +=== Hints + +Oracle lets you specify SQL query additions called hints that can +influence how the database server SQL optimizer works. This lets you +influence decisions usually reserved for the optimizer. You use hints to +specify things such as join order for a join statement, or the +optimization approach for a SQL call. + +You specify hints using the `+DatabaseQuery+` method `+setHintString+`. + +For more information, see the following: + +* link:#Database_Queries[Database Queries] +* link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Use_Oracle_Hints[How +to Use Oracle Hints] +* Your database _Performance Tuning Guide and Reference_. + +=== Hierarchical Queries + +Oracle Database Hierarchical Queries mechanism lets you select database +rows based on hierarchical order. For example, you can design a query +that reads the row of a given employee, followed by the rows of people +the employee manages, followed by their managed employees, and so on. + +You specify a hierarchical query clause using `+DatabaseQuery+` subclass +`+ReadAllQuery+` method `+setHierarchicalQueryClause+`. For more +information on `+DatabaseQuery+` queries, see +link:#Database_Queries[Database Queries]. + +For more information on configuring a `+ReadAllQuery+` with an Oracle +hierarchical query clause, see +link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Use_Hierarchical_Queries[How +to Use Hierarchical Queries]. + +=== Flashback Queries + +When using EclipseLink with Oracle9i (or later), you can acquire a +special historical session where all objects are read as of a past time, +and then you can express read queries depending on how your objects are +changing over time. + +For more information, see link:#Historical_Queries[Historical Queries]. + +=== Stored Functions + +A stored function is an Oracle Database mechanism that provides all the +capabilities of a stored procedure in addition to returning a value. + +For more information, see link:#StoredFunctionCall[StoredFunctionCall]. + +== Descriptor Query Manager Queries + +Each `+Descriptor+` owns an instance of `+DescriptorQueryManager+` that +you can use for the following: + +* Configuring named queries (see +link:#How_to_Configure_Named_Queries[How to Configure Named Queries]) +* Configuring default query implementation (see +link:#How_to_Configure_Default_Query_Implementations[How to Configure +Default Query Implementations]) +* Configuring additional join expressions (see +link:#How_to_Configure_Additional_Join_Expressions[How to Configure +Additional Join Expressions]) + +=== How to Configure Named Queries + +The `+DescriptorQueryManager+` provides API for storing and retrieving +frequently used queries by name. + +For more information, see link:#Named_Queries[Named Queries]. + +=== How to Configure Default Query Implementations + +The `+DescriptorQueryManager+` of each `+Descriptor+` lets you customize +the query implementation that EclipseLink uses for the following data +source operations: + +* insert object +* update object +* read object +* read all objects +* delete object + +For example, if you need to insert an object using a stored procedure, +you can override the default `+SQLCall+` used by the +`+DescriptorQueryManager+` insert object query. + +Whenever you execute a query on a given `+Class+`, EclipseLink consults +the `+DescriptorQueryManager+` to determine how to perform the given +data source operation. + +You can use this capability for a variety of purposes such as to extend +EclipseLink behavior, access nonrelational data, or use stored +procedures or customized SQL calls. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +makes your application vulnerable to SQL injection attacks. +|=== + +For information and examples on customizing these default query +implementations, see the following: + +* link:Configuring%20a%20Relational%20Descriptor%20(ELUG)[Configuring +Custom SQL Queries for Basic Persistence Operations] +* link:Configuring%20an%20EIS%20Descriptor%20(ELUG)[Configuring Custom +EIS Interactions for Basic Persistence Operations] + +=== How to Configure Additional Join Expressions + +You can configure the `+DescriptorQueryManager+` to automatically append +an expression to every query it performs on a class. For example, you +can add an expression that filters the data source for the valid +instances of a given class. + +For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)[Appending Additional Join +Expressions]. + +== Queries and the Cache + +When you execute a query, EclipseLink retrieves the information from +either the database or the EclipseLink session cache. You can configure +the way queries use the EclipseLink cache to optimize performance. + +EclipseLink maintains a client-side cache to reduce the number of read +operations required from the database. EclipseLink caches objects +written to and read from the database to maintain object identity. The +sequence in which a query checks the cache and database affects query +performance. By default, primary key queries check the cache before +accessing the database, and all queries check the cache before +rebuilding an object from its row. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can override the default behavior in the caching policy +configuration information in the EclipseLink descriptor. For more +information, see link:Introduction%20to%20Cache%20(ELUG)[Explicit Query +Refreshes]. +|=== + +This section illustrates ways to manipulate the relationship between +query and cache, and explains the following: + +* link:#How_to_Configure_the_Cache[How to Configure the Cache] +* link:#How_to_Use_In-Memory_Queries[How to Use In-Memory Queries] +* link:#Primary_Key_Queries_and_the_Cache[Primary Key Queries and the +Cache] +* link:#How_to_Disable_the_Identity_Map_Cache_Update_During_a_Read_Query[How +to Disable the Identity Map Cache Update During a Read Query] +* link:#How_to_Refresh_the_Cache[How to Refresh the Cache] +* link:#How_to_Cache_Query_Results_in_the_Session_Cache[How to Cache +Query Results in the Session Cache] +* link:#How_to_Cache_Query_Results_in_the_Query_Cache[How to Cache Query +Results in the Query Cache] + +=== How to Configure the Cache + +The cache in an EclipseLink application holds objects that have already +been read from or written to the database. Use of the cache in an +EclipseLink application reduces the number of accesses to the database. +Because accessing the database consumes time and resources, an effective +caching strategy is important to the efficiency of your application. + +For more information about configuring and using the cache, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +=== How to Use In-Memory Queries + +An in-memory query is a query that is run against the shared session +cache. Careful configuration of in-memory querying improves performance, +but not all queries benefit from in-memory querying. For example, +queries for individual objects based on primary keys generally see +performance gains from in-memory querying; queries not based on primary +keys are less likely to benefit.By default, queries that look for a +single object based on primary keys attempt to retrieve the required +object from the cache first, and then to search the database if the +object is not in the cache. All other query types search the database +first, by default. You can specify whether a given query runs against +the in-memory cache, the database, or both. In-memory querying lets you +perform queries on the cache rather than the database. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot expect an ordered result from an in-memory query as +ordering is not supported for these queries. +|=== + +In-memory querying supports the following relationships: + +* One-to-one +* One-to-many +* Many-to-many +* Aggregate collection +* Direct collection + +[width="100%",cols="<100%",] +|=== +|*Note:* By default, the relationships themselves must be in memory for +in-memory traversal to work. Ensure that you trigger all value holders +to enable in-memory querying to work across relationships. +|=== + +This section describes the following: + +* link:#Configuring_Cache_Usage_for_In-Memory_Queries[Configuring Cache +Usage for In-Memory Queries] +* link:#Expression_Options_for_In-Memory_Queries[Expression Options for +In-Memory Queries] +* link:#Handling_Exceptions_Resulting_from_In-Memory_Queries[Handling +Exceptions Resulting from In-Memory Queries] + +==== Configuring Cache Usage for In-Memory Queries + +You can configure in-memory query cache usage at the query level using +`+ReadObjectQuery+` and `+ReadAllQuery+` methods: + +* `+checkCacheByPrimaryKey+`: The default setting; if a read-object +query contains an expression that compares at least the primary key, you +can obtain a cache hit if you process the expression against the objects +in memory. +* `+checkCacheByExactPrimaryKey+`: If a read-object query contains an +expression where the primary key is the only comparison, you can obtain +a cache hit if you process the expression against the object in memory. +* `+checkCacheThenDatabase+`: You can configure any read-object query to +check the cache completely before you resort to accessing the database. +* `+checkCacheOnly+`: You can configure any read-all query to check only +the parent session cache (not the unit of work cache) and return the +result from the parent session cache without accessing the database. +* `+conformResultsInUnitOfWork+`: You can configure any read-object or +read-all query within the context of a unit of work to conform the +results with the changes to the object made within that unit of work. +This includes new objects, deleted objects and changed objects. For more +information and limitations on conforming, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Using Conforming +Queries and Descriptors]. + +Alternatively, you can configure cache usage using the +`+ObjectLevelReadQuery+` method `+setCacheUsage+`, passing in the +appropriate `+ObjectLevelReadQuery+` field: `+CheckCacheByPrimaryKey+`, +`+CheckCacheByExactPrimaryKey+`, `+CheckCacheThenDatabase+`, +`+CheckCacheOnly+`, `+ConformResultsInUnitOfWork+`, or +`+DoNotCheckCache+`. + +==== Expression Options for In-Memory Queries + +You can use a subset of `+Expression+` (see the +link:#Table_104-6[Expressions Operator Support for In-Memory Queries] +table) and `+ExpressionMath+` (see the link:#Table_104-7[ExpressionMath +Operator Support for In-Memory Queries] table) methods with in-memory +queries. For more information about these options, see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions]. + +[#Table 104-6]## *_Expressions Operator Support for In-Memory Queries_* + +Expressions Operator + +In-Memory Query Support + +addMonths + +and + +anyof1 + +anyofAllowingNone1 + +asciiValue + +between + +concat + +currentDate + +dateToString + +decode + +equal + +get1 + +getAllowingNull1 + +getFunction + +greaterThan + +greaterThanEqual + +hexToRaw + +ifNull + +in + +isNull + +lastDay + +leftPad + +leftTrim + +length + +lessThan + +lessThanEqual + +like + +monthsBetween + +newTime + +nextDay + +notBetween + +notIn + +notNull + +or + +ref + +replace + +rightPad + +rightTrim + +subQuery + +substring + +toCharacter + +toDate + +toLowerCase + +toNumber + +toUpperCase + +toUpperCasedWords + +translate + +trim + +truncateDate + +1For more information, see +link:#Join_Reading_and_Object-Level_Read_Queries[Join Reading and +Object-Level Read Queries]. + +[#Table 104-7]## *_ExpressionMath Operator Support for In-Memory +Queries_* + +ExpressionMath Operator + +In-Memory Query Support + +abs + +acos + +add + +asin + +atan + +atan2 + +ceil + +chr + +cos + +cosh + +exp + +floor + +ln + +log + +max + +min + +mod + +none + +power + +round + +sign + +sin + +sinh + +sqrt + +subtract + +tan + +tanh + +trunc + +==== Handling Exceptions Resulting from In-Memory Queries + +In-memory queries may fail for several reasons, the most common of which +are the following: + +* The query expression is too complex to execute in memory. +* There are untriggered value holders in which indirection (lazy +loading) is used. All object models that use indirection must first +trigger value holders before they conform on the relevant objects. + +EclipseLink provides a mechanism to handle indirection exceptions. To +specify how the application must handle these exceptions, use the +following `+InMemoryQueryIndirectionPolicy+` methods: + +* `+throwIndirectionException+`: The default setting; it is the only +setting that throws indirection exceptions. +* `+triggerIndirection+`: Triggers all valueholders to eliminate the +problem. +* `+ignoreIndirectionExceptionReturnConformed+`: Returns conforming if +an untriggered value holder is encountered. That is, results from the +database are expected to conform, and an untriggered value holder is +taken to mean that the underlying attribute has not changed. +* `+ignoreIndirectionExceptionReturnNotConformed+`: Returns not +conforming if an untriggered value holder is encountered. + +[width="100%",cols="<100%",] +|=== +|*Note*: When you build new applications, consider throwing all conform +exceptions. This provides more detailed feedback for unsuccessful +in-memory queries. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Handling +Exceptions During Conforming]. +|=== + +=== Primary Key Queries and the Cache + +When a query searches for a single object by a primary key, EclipseLink +extracts the primary key from the query and attempts to return the +object from the cache without accessing the database. If the object is +not in the cache, the query executes against the database, builds the +resulting object(s), and places it in the identity map. + +If the query is based on a nonprimary key selection criteria or is a +read-all query, the query executes against the database (unless you are +using `+ReadObjectQuery+` or `+ReadAllQuery+` method +`+checkCacheOnly+`). The query matches primary keys from the result set +to objects in the cache, and returns the cached objects, if any, in the +result set. + +If an object is not in the cache, EclipseLink builds the object. If the +query is a refreshing query, EclipseLink updates the contents of any +objects with the results from the query. Use "`equals`" on the object +identity to properly configure and use an identity map. + +Clients can refresh objects when they want to ensure that they have the +latest data at a particular time. + +*Traversing Relationships with Compound Primary Keys* + +When getting objects by using compound primary keys to traverse +relationships, you must create use query keys (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Query Keys +and Expressions]). By adding a query key for each mapped attribute in a +class with a complex primary key, EclipseLink can use the primary key on +the cache. + +Consider the class `+MyClass+` with two attributes: `+A+` and `+B+`. +Both `+A+` and `+B+` are mapped as 1:1 mappings to the database and +designated primary keys. + +You should create a query key for each attribute (such as +`+MyQueryKeyA+` and `+MyQueryKeyB+`) that will map the attributes of the +primary key of MyClass _without_ going through the other classes. You +can then use the query key to find the object in the cache and query the +object’s primary key: + +`+builder.get("MyQueryKeyA").equal(new Long("123456"));+` + +=== How to Disable the Identity Map Cache Update During a Read Query + +To disable the identity map cache update, which is normally performed by +a read query, call the `+dontMaintainCache+` method. This improves the +query performance when you read objects that are not needed later by the +application and can avoid exceptions during partial object queries (see +link:Using%20Basic%20Query%20API%20(ELUG)[Reading Objects Using Partial +Object Queries]). + +This example demonstrates how code reads `+Employee+` objects from the +database and writes the information to a file. + +[#Example 104-1]## *_Disabling the Identity Map Cache Update_* + +*`+//\'\' \'\'Reads\'\' \'\'objects\'\' \'\'from\'\' \'\'the\'\' \'\'employee\'\' \'\'table\'\' \'\'and\'\' \'\'writes\'\' \'\'them\'\' \'\'to\'\' \'\'an\'\' \'\'employee\'\' \'\'file+`*`+ +` +`+void writeEmployeeTableToFile(String filename, Session session) {+` +`+    Vector employeeObjects;+` +`+    +`*`+//\'\' \'\'Create\'\' \'\'ReadAllQuery\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+    ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+    ExpressionBuilder builder = query.getExpressionBuilder();+` +`+    query.setSelectionCriteria(builder.get("id").greaterThan(100)); +` +`+    query.dontMaintainCache();+` +`+    Vector employees = (Vector) session.executeQuery(query);+` +`+    +`*`+//\'\' \'\'Write\'\' \'\'all\'\' \'\'the\'\' \'\'employee\'\' \'\'data\'\' \'\'to\'\' \'\'a\'\' \'\'file+`* +`+    Employee.writeToFile(filename, employees);+` `+}+` + +=== How to Refresh the Cache + +You can refresh objects in the cache to ensure that they are current +with the database, while preserving object identity. This section +describes how to use query API to perform the following: + +* Configure query refreshing at the descriptor level (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Cache +Refreshing]) to apply cache refreshing to all queries of a particular +object type. Before configuring cache refresh options, consider their +effect on performance (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[Optimizing +Cache]). + +==== Object Refresh + +To refresh objects in the cache with the data in the database, call the +`+Session+` method `+refreshObject+` or the `+ReadObjectQuery+` method +`+setShouldRefreshIdentityMapResult(true)+`. + +==== Cascading Object Refresh + +You can control the depth at which a refreshing updates objects and +their related objects. There are the following three options: + +[arabic] +. `+CascadePrivateParts+`: Default refresh behavior. Refreshes the local +level object and objects that are referenced in privately owned +relationships. +. `+CascadeNone+`: Refreshes only the first level of the object, but +does not refresh related objects. +. `+CascadeAll+`: Refreshes the entire object tree, stopping when it +reaches leaf objects. +. `+CascadeMapping+`: Refreshes each mapping that is configured to +cascade refresh + +==== Refreshing the Identity Map Cache During a Read Query + +Include the `+refreshIdentityMapResult+` method in a query to force +refreshing of an identity map with the results of the query, as the +following example shows: + +[#Example 104-2]## *_Refreshing the Result of a Query in the Identity +Map Cache During a Read Query_* + +*`+//\'\' \'\'Create\'\' \'\'ReadObjectQuery\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+ExpressionBuilder builder = query.getExpressionBuilder();+` +`+query.setSelectionCriteria(builder.get("lastName").equal("Smith")); +` +`+query.refreshIdentityMapResult();+` +`+Employee employee = (Employee) session.executeQuery(query);+` + +The `+refreshIdentityMapResult+` method refreshes the object’s +attributes, but not the attributes of its privately owned parts. +However, under most circumstances, you should refresh an object’s +privately owned parts and other related objects to ensure consistency +with the database. + +To refresh privately owned or related parts, use the following methods: + +* `+cascadePrivateParts+`: Refreshes all privately owned objects +* `+cascadeAllParts+`: Refreshes all related objects + +[#Example 104-3]## *_Using the cascadePrivateParts Method_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.refreshIdentityMapResult();+` `+query.cascadePrivateParts();+` +`+Vector employees = (Vector) session.executeQuery(query);+` + +[width="100%",cols="<100%",] +|=== +|*Note*: If the object is in the session cache, you can also use the +`+refreshObject+` method to refresh an object and its privately owned +parts. +|=== + +=== How to Cache Query Results in the Session Cache + +By default, EclipseLink stores query results in the session cache +enabling EclipseLink to execute the query repeatedly, without accessing +the database. This is useful when you execute queries that run against +static data. + +By default, a read-all query always goes to the database, as it does not +know how many objects it is seeking. However if the object already +exists in the cache, time can be saved by not having to build a new +object from the row. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +=== How to Cache Query Results in the Query Cache + +In addition to EclipseLink’s object cache, EclipseLink also supports a +query cache. There is the following distinction between the two: + +* The _object cache_ indexes objects by their primary key, allowing +primary key queries to obtain cache hits. By using the object cache, +queries that access the data source can avoid the cost of building the +objects and their relationships if the object is already present. +* The _query cache_ is distinct from the object cache. The query cache +is indexed by the query and the query parameters–not the object’s +primary key. This allows for any query executed with the same parameters +to obtain a query cache hit and return the same result set. + +By default, a `+ReadQuery+` does not cache its query result set. You +can, however, configure the query to cache its result set. This is +useful for frequently executed queries whose result set infrequently +changes. The query cache always maintains hard references to the result +set; the number of results sets for distinct parameters stored in the +query cache is configurable. The query cache maintains its size number +of the last executed queries with distinct parameters. + +For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)[How to Cache Results in a +ReadQuery]. + +You can apply a cache invalidation policy to the query’s internal cache +(see link:Using%20Advanced%20Query%20API%20(ELUG)[How to Configure Cache +Expiration at the Query Level]). For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Cache Invalidation]. + +==== Internal Query Cache Restrictions + +EclipseLink does not support the use of the query cache with cursors: if +you use query caching with cursors, EclipseLink will throw an exception. +For information on cursor query results, see +link:#Stream_and_Cursor_Query_Result[Stream and Cursor Query Resultss] +and link:Using%20Advanced%20Query%20API%20(ELUG)[Handling Cursor and +Stream Query Results]. + +== Query API + +The following table summarizes the query support provided by each type +of session. For each session type, it shows the type of query operation +(create, read, update, delete) that you can perform and whether or not +you can execute a `+DatabaseQuery+` or `+Call+`. For example, using a +unit of work, you can use session queries to read and delete; using a +server session, you can use session queries to create, read, update, and +delete. + +[#Table 104-8]## *_Session Query API Summary_* + +Session + +Create + +Read + +Update + +Delete + +Execute Database Query + +Execute Call + +Unit of work + +Database + +Server + +Client + +This example summarizes the important EclipseLink packages that provide +query and expression support: + +[#Example 104-4]## *_Query and Expression Packages_* + +`+org.eclipse.persistence.queries+` +`+org.eclipse.persistence.expressions+` +`+org.eclipse.persistence.query.keys+` +`+org.eclipse.persistence.descriptors.DescriptorQueryManager+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Sessions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Sessions_(ELUG).adoc new file mode 100644 index 00000000000..e231565956e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Sessions_(ELUG).adoc @@ -0,0 +1,2091 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Sessions_(ELUG)[Related +Topics] + +An EclipseLink session provides the primary access to the EclipseLink +runtime. It is the means by which your application performs all +persistence operations with the data source that contains persistent +objects. + +A session associates data source platform information, data source login +information, and mapping metadata for a particular application. You can +reuse mapping metadata in different applications by defining different +sessions. + +EclipseLink provides different session types, each optimized for +different design requirements and data access strategies. You can +combine different session types in the same application. + +== Session Types + +This table lists the session types that you can use in a POJO +EclipseLink application. + +[#Table 83-1]## + +Session Type + +Description + +Workbench + +Java + +Server and Client Sessions + +Server sessions provide session management to a single data source +(including shared object cache and connection pools) for multiple +clients in a three-tier architecture using database or EIS platforms. +This is the most flexible, scalable, and commonly used session. + +You acquire a client session from a server session at run time to +provide access to a single data source for each client. + +Unit of Work Sessions + +Acquired from any session type (directly, or by way of an external +transaction controller) to transactionally modify objects. + +Isolated Client Session + +A special type of client session that uses a session cache isolated from +the shared object cache of its parent server session. + +Historical Sessions + +A special type of client session that provides a read-only snapshot of +object versions as of a specified time and uses a session cache isolated +from the shared object cache of its parent server session. + +Session Broker and Client Sessions + +Provides session management to multiple data sources for multiple +clients by aggregating two or more server sessions (can also be used +with database sessions). + +You acquire a client session from a session broker at run-time to +provide access to all the data sources managed by the session broker for +each client. + +Database Sessions + +Provides session management to a single database for a single client +suitable for simple or two-tiered applications. We do not recommend this +session type in three-tiered applications because it does not offer the +same flexibility and scalability as the server session. + +Remote Sessions + +A client-side session that communicates over RMI with a corresponding +dedicated client session and shared server session. Remote sessions +handle object identity and marshalling and unmarshalling between +client-side and server-side. + +For more information, see the following: + +* link:Creating%20a%20Session%20(ELUG)[Creating a Session] +* link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session[Configuring +a Session] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_and_Using_Sessions_at_Run_Time[Acquiring +and Using Sessions at Run Time] + +== Session Concepts + +This section describes concepts unique to EclipseLink sessions, +including the following: + +* link:#Session_Architecture[Session Architecture] +* link:#Session_Configuration_and_the_sessions.xml_File[Session +Configuration and the sessions.xml File] +* link:#Session_Customization[Session Customization] +* link:#Acquiring_a_Session_at_Run_Time_with_the_Session_Manager[Acquiring +a Session at Run Time with the Session Manager] +* link:#Managing_Session_Events_with_the_Session_Event_Manager[Managing +Session Events with the Session Event Manager] +* link:#Logging[Logging] +* link:#Profiler[Profiler] +* link:#Integrity_Checker[Integrity Checker] +* link:#Exception_Handlers[Exception Handlers] +* link:#Registering_Descriptors[Registering Descriptors] +* link:#Sessions_and_Sequencing[Sessions and Sequencing] + +=== Session Architecture + +As the link:#Figure_83-1[Simple EclipseLink Session Architecture] figure +illustrates, a session instance is composed of the following components: + +* link:#Object_Cache[Object Cache] +* link:#Connection_Pools[Connection Pools] +* link:#Query_Mechanism[Query Mechanism] +* link:#Java_Object_Builder[Java Object Builder] + +[#Figure 83-1]## *_Simple EclipseLink Session Architecture_* + +.Simple EclipseLink Session Architecture +image::sessarch.gif[Simple EclipseLink Session +Architecture,title="Simple EclipseLink Session Architecture"] + +How these session components are implemented and how they interact +depends on the type of session. For example, for server and client +sessions, the server session provides a connection pool and shared +object cache on behalf of all client sessions acquired from it. + +==== Object Cache + +EclipseLink sessions provide an object cache. This cache, known as the +*session cache*, retains information about objects that are read from or +written to the database, and is a key element for improving the +performance of an EclipseLink application. + +Typically, a server session’s object cache is shared by all client +sessions acquired from it. That is, for a Server session +`+myServerSession+`, each client session acquired by calling server +session method `+acquireClientSession+` shares the same object cache as +`+myServerSession+`. + +Isolated and historical sessions provide their own session cache +isolated from the shared object cache of their parent server session. +For more information, see link:#Isolated_Client_Sessions[Isolated Client +Sessions] and link:#Historical_Sessions[Historical Sessions]. + +You can easily manage concurrent access to this shared cache by using a +unit of work session acquired from any session. For more information, +see link:#Unit_of_Work_Sessions[Unit of Work Sessions]. + +For more information, see link:#Sessions_and_the_Cache[Sessions and the +Cache]. + +==== Connection Pools + +A *connection pool* is a collection of reusable connections to a single +data source. + +[width="100%",cols="<100%",] +|=== +|*Note*: To simultaneously access multiple databases from within a +single session, use a session broker. For more information, see +link:#Session_Broker_and_Client_Sessions[Session Broker and Client +Sessions]. +|=== + +Because creating a data source connection is usually expensive, a +properly configured connection pool significantly improves performance. + +You can configure your session to use internal connection pools provided +by EclipseLink or external connection pools provided by a JDBC driver or +Java EE container. By default, EclipseLink uses internal connection +pools. + +Internal connection pools are usually used in non-EJB applications, or +when an external transaction controller (JTA) is not used. If you +configure your session to use internal connection pools, you can +configure its default read and write connection pools. You can create +special purpose connection pools for application-specific purposes +(named connection pools) or exclusively for sequencing (sequence +connection pool). For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[Internal +Connection Pools]. + +External connection pools are usually used in EJB applications and when +an external transaction controller (JTA) is used. For more information, +see +link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[External +Connection Pools]. + +For more information about data access configuration in general, see +link:Introduction%20to%20Data%20Access%20(ELUG)#CHDJBDEA[Introduction to +Data Access]. + +==== Query Mechanism + +At run time, your application uses a session to perform all persistence +operations: creating, reading, updating, and deleting objects. You +perform these operations using EclipseLink queries and expressions with +the session query API. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#CACJAFJD[Introduction +to EclipseLink Queries]. + +==== Java Object Builder + +When you use object-level read queries, EclipseLink automatically builds +Java objects from the data retrieved. When you use object-level write +queries, EclipseLink automatically converts the affected Java objects +into the appropriate data native to your data source. + +=== Session Configuration and the sessions.xml File + +EclipseLink provides two ways to configure your sessions: through Java +code using the `+Session+` API, or using Workbench to build a session +configuration file, the `+sessions.xml+` file. + +In most cases, you configure sessions for the application using the +`+sessions.xml+` file. This file is an Extensible Markup Language (XML) +file that contains all sessions that are associated with the +application. The `+sessions.xml+` file can contain any number of +sessions and session types. + +We recommend that you use the `+sessions.xml+` file to deploy an +EclipseLink application, because it provides the following advantages: + +* It is easy to create and maintain in Workbench. +* It is easy to troubleshoot. +* It provides access to most session configuration options. +* It offers excellent flexibility, including the ability to modify +deployed applications without recompiling. + +For more information on creating a session in the `+sessions.xml+` file, +see +link:Creating%20a%20Session%20(ELUG)#Introduction_to_the_Session_Creation[Introduction +to the Session Creation]. + +=== Session Customization + +You can customize a session at run time by specifying a session +customizer–a Java class that implements the +`+org.eclipse.persistence.config.SessionCustomizer+` interface and +provides a default (zero-argument) constructor. + +You use a session customizer to customize a session at run time through +code API similar to how you use an +link:Introduction%20to%20Descriptors%20(ELUG)#Amendment_and_After-Load_Methods[amendment +method] to customize a descriptor. + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Customizer_Class[Configuring +a Session Customizer Class]. + +=== Acquiring a Session at Run Time with the Session Manager + +The EclipseLink session manager lets you build a series of sessions that +are maintained under a singleton object called the session manager. + +The session manager is a static utility class that loads EclipseLink +sessions from the +link:#Session_Configuration_and_the_sessions.xml_File[`+sessions.xml+`] +file, caches the sessions by name in memory, and provides a single +access point for EclipseLink sessions. + +At run time, EclipseLink will attempt to load the `+sessions.xml+` file +from the two following default resource names: `+sessions.xml+` and +`+META-INF/sessions.xml+`. Refer to +link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging an +EclipseLink Application] for additional information. + +The session manager supports the following session types: + +* link:#Server_and_Client_Sessions[`+ServerSession+`] +* link:#Session_Broker_and_Client_Sessions[`+SessionBroker+`] +* link:#Database_Sessions[`+DatabaseSession+`] + +The session manager has two main functions: it creates instances of +these sessions and it ensures that only a single instance of each named +session exists for any instance of a session manager. + +The session manager instantiates sessions as follows: + +[arabic] +. The client application requests a session by name. +. The session manager looks up the session name in the `+sessions.xml+` +file. If the session name exists, the session manager instantiates the +specified session; otherwise, it raises an exception. +. After instantiation, the session remains viable until you shut down +the application. + +Once you have a session instance, you can use it to acquire additional +types of sessions for special tasks. For example, you can acquire a unit +of work from any session to perform transactional operations. You can +acquire a client session from a server session to perform client +operations in a three-tier architecture. + +For more information, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[Acquiring +and Using Sessions at Run Time]. + +=== Managing Session Events with the Session Event Manager + +Sessions raise *session events* for most session operations. Session +events help you debug or coordinate the actions of multiple sessions. + +The session event manager handles information about session events. +Applications register session event listeners with the session event +manager to receive session events. + +For example, session event listeners play an important role in the +configuration of isolated sessions (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)[Configuring +Exclusive Isolated Client Sessions for Virtual Private Database]). In an +isolated session, if the EclipseLink runtime raises a +`+SessionEvent.NoRowsModified+` event, it is handled by your +`+SessionEventListener+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_NoRowsModifiedSessionEvent_Event_Handler[Using +NoRowsModifiedSessionEvent Event Handler]). This event listener is your +opportunity to determine whether the update failure was due to a +security violation (in which case you should not retry the operation) or +due to an optimistic lock issue (in which case a retry may be +appropriate). See link:#Logging[Logging] for information on adding +logging to your event listeners. + +Another example is the use of session event listeners to configure proxy +authentication in an Oracle Database. (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Oracle_Database_Proxy_Authentication[Configuring +Oracle Database Proxy Authentication]). + +This section explains how to use session events, including the +following: + +* link:#Session_Event_Manager_Events[Session Event Manager Events] +* link:#Session_Event_Listeners[Session Event Listeners] + +==== Session Event Manager Events + +The session event manager supports the session events listed in the +following tables: + +* link:#Table_83-2[Session Events] +* link:#Table_83-3[Unit of Work Events] + +[#Table 83-2]## *_Session Events_* + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Event* |*Description* +|MissingDescriptor |Raised if a descriptor is missing for a class being +persisted. You can use this event to lazy register the descriptor or set +of descriptors. + +|MoreRowsDetected |Raised when a `+ReadObjectQuery+` detects more than +one row returned from the database. This event can indicate a possible +error condition in your application. + +|NoRowsModified |Raised after update or delete SQL has been sent to the +database and a row count of zero is returned. + +|OutputParametersDetected |Raised after a stored procedure call with +output parameters executes. This event enables you to retrieve a result +set and output parameters from a single stored procedure. + +|PostAcquireClientSession |Raised after a client Session is acquired. + +|PostAcquireConnection |Raised after acquiring a connection. + +|PostAcquireExclusiveConnection |Raised when a client session, with +isolated data, acquires an exclusive connection. + +|PostBeginTransaction |Raised after a database transaction starts. + +|PostCommitTransaction |Raised after a database transaction commits. + +|PostConnect |Raised after connecting to the database. + +|PostExecuteQuery |Raised after the execution of every query on the +session. + +|PostLogin |Raised after the session initializes and acquires +connections. + +|PostReleaseClientSession |Raised after releasing a client session. + +|PostRollbackTransaction |Raised after a database transaction rolls +back. + +|PreBeginTransaction |Raised before a database transaction starts. + +|PreCommitTransaction |Raised before a database transaction commits. + +|PreExecuteQuery |Raised before the execution of every query on the +session. + +|PreLogin |Raised before the session initializes and acquires +connections. + +|PreReleaseClientSession |Raised before releasing a client session. + +|PreReleaseConnection |Raised before releasing a connection. + +|PreReleaseExclusiveConnection |Raised before a client session, with +isolated data, releases its exclusive connection. + +|PreRollbackTransaction |Raised before a database transaction rolls +back. +|=== + +[#Table 83-3]## *_Unit of Work Events_* + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Event* |*Description* +|PostAcquireUnitOfWork |Raised after a `+UnitOfWork+` is acquired + +|PostCalculateUnitOfWorkChangeSet |Raised after the commit has begun on +the `+UnitOfWork+` and after the changes are calculated. The +`+UnitOfWorkChangeSet+`, at this point, will contain change sets without +the version fields updated and without identity field type primary keys. +These will be updated after the insert, or update, of the object. + +|PostCommitUnitOfWork |Raised after a `+UnitOfWork+` commits + +|PostDistributedMergeUnitOfWorkChangeSet |Raised after a `+UnitOfWork+` +change set has been merged when that change set has been received from a +distributed session. + +|PostMergeUnitOfWorkChangeSet |Raised after a `+UnitOfWork+` change set +has been merged. + +|PostReleaseUnitOfWork |Raised on a `+UnitOfWork+` after it is released. + +|PostResumeUnitOfWork |Raised on a `+UnitOfWork+` after it resumes. + +|PreCalculateUnitOfWorkChangeSet |Raised after the commit has begun on +the `+UnitOfWork+` but before the changes are calculated. + +|PreCommitUnitOfWork |Raised before a `+UnitOfWork+` commits. + +|PreDistributedMergeUnitOfWorkChangeSet |Raised before a `+UnitOfWork+` +change set has been merged when that change set has been received from a +distributed session. + +|PreMergeUnitOfWorkChangeSet |Raised before a `+UnitOfWork+` change set +has been merged. + +|PrepareUnitOfWork |Raised after the a `+UnitOfWork+` flushes its SQL, +but before it commits its transaction. + +|PreReleaseUnitOfWork |Raised on a `+UnitOfWork+` before it is released. +|=== + +==== Session Event Listeners + +You can create session event listeners in two ways: either by +implementing the `+SessionEventListener+` interface, or by extending the +`+SessionEventAdapter+` class. + +To register a `+SessionEventListener+` for session events, register it +with a session using the `+SessionEventManager+` method `+addListener+`. + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners]. + +=== Logging + +You can configure a session to write run-time information to an +EclipseLink log. This information includes status, diagnostic, SQL, and, +when profiling is enabled, performance data (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring_EclipseLink_Performance_with_the_EclipseLink_Profiler[Measuring +EclipseLink Performance with the EclipseLink Profiler]). + +Logging options are configurable at the session level (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging]). + +Note: To facilitate debugging, you can add logging to your listeners to +only log the events that are of the interest to your application. Within +the session context, use the following logging utility: + +Session.getSessionLog().log(int level, String message)  + +Without the session context, use the following logging utility: + +AbstractSessionLog.getLog().log(int level, String message) + +Both the getSessionLog and getLog methods return a session log (an +instance of a SessionLog interface) loaded with an accessor’s log +messages and SQL. Then the session log performs logging at the level +that you specify. For more information on session event listeners, see +Session Event Listeners. + +For information on using the third-party logging utilities in your +EclipseLink application, see +http://wiki.eclipse.org/EclipseLink/Foundation/Logging + +This section describes session log options, including the following: + +* link:#Log_Types[Log Types] +* link:#Log_Output[Log Output] +* link:#Log_Level[Log Level] +* link:#Logging_SQL[Logging SQL] +* link:#Logging_Chained_Exceptions[Logging Chained Exceptions] +* link:#Logging_Inside_Oracle_Application_Server[Logging Inside Oracle +Application Server] +* link:#Logging_Inside_a_non-Oracle_Java_EE_Container[Logging Inside a +non-Oracle Java EE Container] +* link:#Logging_Outside_of_a_Java_EE_Container[Logging Outside of a Java +EE Container] + +==== Log Types + +EclipseLink supports the following types of logging: + +* link:#EclipseLink_Native_Logging[EclipseLink Native Logging] +* link:#java.util_Logging[java.util Logging] +* link:#Server_Logging[Server Logging] + +===== EclipseLink Native Logging + +EclipseLink native logging is the default session log type. It is +provided by `+org.eclipse.persistence.logging.DefaultSessionLog+`. The +link:#Example_83-1[Sample EclipseLink Log Message] example shows a +typical EclipseLink native log message. + +You can configure EclipseLink native logging options using Workbench +(see +link:Configuring%20a%20Session%20(ELUG)#How_to_Configure_Logging_Using_Workbench[How +to Configure Logging Using Workbench]). + +[#Example 83-1]## *_Sample EclipseLink Log Message_* + +`+[EclipseLink Info]: +`_`+DATE+`_ + +_`+TIME+`_`+-DatabaseSession(12345)-Thread(12345)-EclipseLink, version: EclipseLink+` +`+[EclipseLink Config]: DATE+` +`+TIME-DatabaseSession(12345)-Thread(12345)-Connection(12345)-+` +`+  connecting(DatabaseLogin(+` +`+             platform=>Oracle9Platform+` +`+             user name=> "+`_`+username+`_`+"+` +`+             datasource URL=> "jdbc:oracle:thin:@144.23.214.115:1521:eclipselink"+` +`+))+` `+[EclipseLink Config]: DATE +` +`+TIME-DatabaseSession(12345)-Thread(12345)-Connection(12345)-+` +`+  Connected: jdbc:oracle:thin:@144.23.214.115:1521:eclipselink+` +`+  User: +`_`+USERNAME+`_ +`+  Database: Oracle Version: Oracle9i Enterprise Edition - Production+` +`+With the Partitioning, OLAP and Oracle Data Mining options+` +`+JServer Release 9.2.0.3.0 - Production+` +`+  Driver: Oracle JDBC driver Version: 9.2.0.3.0+` +`+[EclipseLink Info]: +`_`+DATE+`_ +`+TIME-DatabaseSession(12345)-Thread(12345)-loggingTestSession login+` +`+successful+` + +===== java.util Logging + +This type of logging makes EclipseLink conform to the +`+java.util.logging+` package. It is provided by +`+org.eclipse.persistence.logging.JavaLog+`. Logging options are +configured in the __`+/lib/logging.properties+` file. Messages are +written to any number of destinations based on this configuration. The +link:#Example_83-2[Sample java.util.logging Log Messages] example shows +a typical `+java.util.logging+` log message. + +For more information on using `+java.util.logging+` package, see +link:Configuring%20a%20Session%20(ELUG)#How_to_Configure_a_Session_to_use_the_java.util.logging_Package[ow +to Configure a Session to use the java.util.logging Package]. + +[#Example 83-2]## *_Sample java.util.logging Log Messages_* + +`+Dec 9, 2003 2:05:05 PM org.eclipse.persistence.loggingTestSession DatabaseSession(32603767) Thread(10)+` +`+INFO: EclipseLink, version: EclipseLink +` +`+Dec 9, 2003 2:05:07 PM org.eclipse.persistence.loggingTestSession.connection DatabaseSession(32603767) Connection(927929) Thread(10)+` +`+CONFIG: connecting(DatabaseLogin(+` `+    platform=>Oracle9Platform+` +`+    user name=> "coredev8"+` +`+    datasource URL=> "jdbc:oracle:thin:@144.23.214.115:1521:eclipselink"+` +`+))Dec 9, 2003 2:05:08 PM org.eclipse.persistence.loggingTestSession.connection DatabaseSession(32603767) Connection(927929) Thread(10)+` +`+CONFIG: Connected: jdbc:oracle:thin:@144.23.214.115:1521:eclipselink+` +`+    User: COREDEV8+` +`+    Database: Oracle  Version: Oracle9i Enterprise Edition Release 9.2.0.3.0 - Production+` +`+With the Partitioning, OLAP and Oracle Data Mining options+` +`+JServer Release 9.2.0.3.0 - Production+` +`+    Driver: Oracle JDBC driver  Version: 9.2.0.3.0+` +`+Dec 9, 2003 2:05:08 PM org.eclipse.persistence.loggingTestSession DatabaseSession(32603767) Thread(10)+` +`+INFO: loggingTestSession login successful+` + +===== Server Logging + +Server logging is used to integrate EclipseLink logging with an +application server log. + +The EclipseLink runtime determines the server log type to use given the +server platform you configure when you create your project +(link:Creating%20a%20Project%20(ELUG)#Introduction_to_the_Project_Creation[Introduction +to the Project Creation]). + +For example, if your project uses the WebLogic platform, EclipseLink +uses the `+org.eclipse.persistence.platform.server.wls.WlsLog+`; if your +project uses the OC4J platform, EclipseLink uses the +`+org.eclipse.persistence.platform.server.oc4j.OjdlLog+`. + +==== Log Output + +If you are using EclipseLink native logging, you can configure +EclipseLink to write log messages to a file or to the console (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging]). + +If you are using `+java.util.logging+`, EclipseLink writes log messages +to the destinations you configure in the __`+/lib/logging.properties+` +file (see +link:Configuring%20a%20Session%20(ELUG)#How_to_Configure_a_Session_to_use_the_java.util.logging_Package[How +to Configure a Session to use the java.util.logging Package]). + +If you are using server logging, EclipseLink writes log messages to the +application server’s log file (there is no separate EclipseLink log file +in this case). + +==== Log Level + +You can control the amount and detail of log output by configuring the +log level (in ascending order of information) in the following way: + +* `+OFF+`–Logs nothing. +* `+SEVERE+`–Logs exceptions indicating EclipseLink cannot continue, as +well as any exceptions generated during login. This includes a stack +trace. +* `+WARNING+`–Logs exceptions that do not force EclipseLink to stop, +including all exceptions not logged with severe level. This does not +include a stack trace. +* `+INFO+` (default)–Logs the login/logout per server session, including +the user name. After acquiring the session, detailed information is +logged. +* `+CONFIG+`–Logs only login, JDBC connection, and database information. +* `+FINE+`–Logs SQL (including thread information). +* `+FINER+`–Similar to warning. Includes stack trace. +* `+FINEST+`–Includes additional low level information +* `+ALL+`–Logs everything. + +By default, EclipseLink logs at the +`+org.eclipse.persistence.logging.SessionLog.INFO+` level so that some +information is logged by default. + +At run time, set the log level using `+Session+` method `+setLogLevel+`, +passing in one of the log level constants provided by +`+org.eclipse.persistence.logging.SessionLog+`. + +==== Logging SQL + +In a relational project, EclipseLink accesses the database using SQL +strings that it generates internally. This feature enables applications +to use the session methods or query objects without having to perform +their own SQL translation. + +If, for debugging purposes, you want to review a record of the SQL that +is sent to the database, set the session log level to +`+org.eclipse.persistence.logging.SessionLog.FINE+`–the session will log +all executed SQL to the session log. + +This example shows how to configure the log destination using the +`+setLog()+` method on the session. + +[#Example 83-3]## *_Configuring the Log Destination_* + +[source,java] +---- + private static SessionEventListener buildListener() { + return new SessionEventAdapter() { + public void preLogin(SessionEvent event) { + File file = new + File("C:\\eclipse\eclipselink\\examples\\2-TierEmployee\\eclipselink.log"); + try { + System.out.println("FILE: " + file.getAbsolutePath()); + FileWriter writer = new FileWriter(file); + event.getSession().setLog(writer); + } + catch (IOException ioe) { + ioe.printStackTrace(); + throw new RuntimeException("Failed to setup logging to: " + + file.getAbsolutePath()); + } + } + }; + } +---- + +==== Logging Chained Exceptions + +The logging chained exception facility enables you to log causality when +one exception causes another as part of the standard stack back-trace. +Causal chains appear automatically in your logs. + +==== Logging Inside Oracle Application Server + +When you deploy an EclipseLink-enabled application to Oracle Application +Server, EclipseLink JPA defaults to `+ServerLog+` with no log level so +that EclipseLink uses the configuration in `+j2ee-logging.xml+`. + +For more information, see the following: + +* link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging] +* _http://download.oracle.com/docs/cd/E12524_01/core.1013/e10403/toc.htm[Oracle +Fusion Middleware Administrator’s Guide]_ + +==== Logging Inside a non-Oracle Java EE Container + +When you deploy an EclipseLink-enabled application to a non-Oracle +application server or EJB container, JPA defaults to `+ServerLog+` with +no log level so that EclipseLink uses the configuration in +`+j2ee-logging.xml+`. + +==== Logging Outside of a Java EE Container + +When you deploy an EclipseLink-enabled application outside of an EJB +container, the logging defaults revert to `+DefaultSessionLog+` and +`+INFO+` log level. + +If you are using EclipseLink native logging (to a file) or the +`+java.util.logging+` package outside of a Java EE container, you +control logging using the +`+<+`_`+JRE_HOME+`_`+>/lib/logging.properties+` file. + +For more information, see the following: + +* link:Configuring%20a%20Session%20(ELUG)#Configuring_Logging[Configuring +Logging] +* link:Configuring%20a%20Session%20(ELUG)#How_to_Configure_a_Session_to_use_the_java.util.logging_Package[How +to Configure a Session to use the java.util.logging Package] + +=== Profiler + +The EclipseLink session provides profiling API that lets you identify +performance bottlenecks in your application (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Performance_Profiler[Configuring +a Performance Profiler]). When enabled, the profiler logs a summary of +the performance statistics for every query that the application +executes. + +EclipseLink allows you to measure application performance using the +following tools: + +* link:#EclipseLink_Profiler[EclipseLink Profiler] + +==== EclipseLink Profiler + +The EclipseLink profiler is a high-level logging service. Instead of +logging SQL statements, the profiler logs a summary of each query you +execute. The summary includes a performance breakdown of the query that +lets you identify performance bottlenecks. The profiler also provides a +report summarizing the query performance for an entire session. + +For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring_EclipseLink_Performance_with_the_EclipseLink_Profiler[Measuring +EclipseLink Performance with the EclipseLink Profiler]. + +=== Integrity Checker + +When you log into a session, EclipseLink initializes and validates the +descriptors you registered with it. By configuring the integrity +checker, you can customize this validation process. + +For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Integrity_Checker[Configuring +the Integrity Checker]. + +=== Exception Handlers + +Exception handlers allow any exception that occurs in a session to be +caught and processed. Exception handlers can be used for debugging +purposes, or to resolve database timeouts or failures. + +To use exception handlers, register an implementor of the +`+org.eclipse.persistence.exceptions.ExceptionHandler+` interface with +the session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_an_Exception_Handler[Configuring +an Exception Handler]). + +If an exception occurs during a session operation, such as executing a +query, the exception is passed to the exception handler. The exception +handler can either rethrow the exception, or handle the exception and +retry the operation. When handling exceptions, ensure that the following +conditions are met: + +* If you are performing a write query and you are within a transaction, +you should not retry the operation. +* If you are performing a read query, you may retry the operation, and, +if successful, return the query result. + +If your exception handler cannot proceed, you should throw an +appropriate application-specific exception. + +=== Registering Descriptors + +You use a session to perform persistence operations on the objects +described by EclipseLink mapping metadata represented as an EclipseLink +project (see link:Introduction%20to%20Projects_(ELUG)[Introduction to +Projects]). Each session must therefor be associated with the +descriptors of at least one EclipseLink project. You associate +descriptors with a session by registering them with the session. + +The preferred way to register descriptors with a session is to use the +Workbench to configure the session with a mapping project (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Primary_Mapping_Project[Configuring +a Primary Mapping Project] and +link:Configuring%20a%20Session%20(ELUG)#Configuring_Multiple_Mapping_Projects[Configuring +Multiple Mapping Projects]). + +=== Sessions and Sequencing + +An essential part of maintaining object identity is managing the +assignment of unique values to distinguish one instance from another. +For more information, see +link:Introduction%20to%20Projects_(ELUG)#Projects_and_Sequencing[Projects +and Sequencing]. + +Sequencing options you configure in a `+sessions.xml+` (or +`+project.xml+`) file determine the type of sequencing that EclipseLink +uses. + +In a POJO project, you can use session-level sequence configuration to +override project-level sequence configuration, on a session-by-session +basis, if required (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]). + +After configuring the sequence type at the session (or project) level, +for each descriptor you must also configure sequencing options for that +descriptor to use sequencing (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Sequencing[Descriptors +and Sequencing]). + +== Server and Client Sessions + +A server session manages the server side of client/server +communications, providing shared resources, including a shared object +cache and connection pools to a single data source. + +A client session is a server-side communications mechanism that works +together with the server session to provide the client/server +connection. You acquire client sessions from a server session at run +time as required. By default, a client session shares the session cache +of its parent server session. Each client session serves one client. A +client session communicates with the server session on behalf of the +client application. + +Each client session can have only one associated server session, but a +server session can support any number of client sessions. + +As the link:#Figure_83-2[Typical EclipseLink Server Session with Client +Session Architecture] figure illustrates, together, the client session +and server session provide a three-tier architecture that you can scale +easily, by adding more client sessions. A server session is the most +common EclipseLink session type because it supports this three-tier +architecture that is common in enterprise applications. Because of this +scalability, we recommend that you use the three-tier architecture to +build your EclipseLink applications. + +[#Figure 83-2]## *_Typical EclipseLink Server Session with Client +Session Architecture_* + +.Typical EclipseLink Server Session with Client Session Architecture +image::Sessclie.gif[Typical EclipseLink Server Session with Client +Session +Architecture,title="Typical EclipseLink Server Session with Client Session Architecture"] + +This section explains the advantages of using server sessions and client +sessions in your EclipseLink application, including the following: + +* link:#Three-Tier_Architecture_Overview[Three-Tier Architecture +Overview] +* link:#Advantages_of_the_EclipseLink_Three-Tier_Architecture[Advantages +of the EclipseLink Three-Tier Architecture] + +For more information, see the following: + +* link:Creating%20a%20Session%20(ELUG)#Creating_a_Server_Session[Creating +a Server Session] +* link:Configuring%20Server%20Sessions%20(ELUG)[Configuring Server +Sessions] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Session_from_the_Session_Manager[Acquiring +a Session from the Session Manager] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Client_Session[Acquiring +a Client Session] + +=== Three-Tier Architecture Overview + +In an EclipseLink three-tier architecture, client sessions and server +sessions both reside on the server. Client applications access the +EclipseLink application through a client session, and the client session +communicates with the database using the server session. + +[#Figure 83-3]## *_Server Session and Client Session Usage_* + +.Server Session and Client Session Usage +image::cliserv.gif[Server Session and Client Session +Usage,title="Server Session and Client Session Usage"] + +=== Advantages of the EclipseLink Three-Tier Architecture + +Although the server session and the client session are two different +session types, you can treat them as a single unit in most cases, +because they are both required to provide three-tier functionality to +the application. The server session provides the client session to +client applications, and also supplies the majority of the session +functionality. + +This section discusses some of the advantages and general concepts +associated with the EclipseLink three-tier design, including the +following: + +* link:#Shared_Resources[Shared Resources] +* link:#Providing_Read_Access[Providing Read Access] +* link:#Providing_Write_Access[Providing Write Access] +* link:#Security_and_User_Privileges[Security and User Privileges] +* link:#Concurrency[Concurrency] +* link:#Connection_Allocation[Connection Allocation] + +==== Shared Resources + +The three-tier design enables multiple clients to share persistent +resources. The server session provides its client sessions with a shared +live object cache, read and write connection pooling, and parameterized +named queries. Client sessions also share descriptor metadata. + +You can use client sessions and server sessions in any application +server architecture that allows for shared memory and supports multiple +clients. These architectures can include HyperText Markup Language +(HTML), Servlet, JavaServer Pages (JSP), Remote Method Invocation (RMI), +Common Object Request Broker Architecture (CORBA), web services, and +EJB. + +To support a shared object cache, client sessions must do the following: + +* Implement any changes to the database with the EclipseLink unit of +work. +* Share a common database login for reading (you can implement separate +logins for writing). + +==== Providing Read Access + +To read objects from the database, the client must first acquire a +client session from the server session. Acquiring a client session gives +the client access to the session cache and the database through the +server session. The server session behaves as follows: + +* If the object or data is in the session cache, then the server session +returns the information back to the client. +* If the object or data is not in the cache, then the server session +reads the information from the database and stores the object in the +session cache. The objects are then available for retrieval from the +cache. + +Because a server session processes each client request in a separate +thread, this enables multiple clients to access the database connection +pool concurrently. + +This figure illustrates how multiple clients read from the database +using the server session. + +[#Figure 83-4]## *_Multiple Client Sessions Reading the Database Using +the Server Session_* + +.Multiple Client Sessions Reading the Database Using the Server Session +image::multiread.gif[Multiple Client Sessions Reading the Database Using +the Server +Session,title="Multiple Client Sessions Reading the Database Using the Server Session"] + +To read objects from the database using a client session, do the +following: + +[arabic] +. Acquire a `+Session+` from the `+Server+`: ++ +`+Server server = (Server)SessionManager.getManager().getSession(+` +`+                sessionName, MyServerSession.class.getClassLoader());+` +`+Session clientSession = (Session) server.acquireClientSession();+` ++ +For more information, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[Acquiring +and Using Sessions at Run Time]. +. Use the `+Session+` object to perform read operations (for more +information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Introduction to +EclipseLink Queries] and +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions]). ++ +\{| class="`Note oac_no_warn`" width="`80%`" border="`1`" +frame="`hsides`" rules="`groups`" cellpadding="`3`" frame="`hsides`" +rules="`groups`" | align="`left`" | *Note*: We recommend that you do not +use the server session object directly to read objects from the +database. |} + +==== Providing Write Access + +Because the client session disables all database modification methods, a +client session cannot create, change, or delete objects directly. +Instead, the client must obtain a unit of work from the client session +to perform database modification methods. + +To write to the database, the client acquires a client session from the +server session and then acquires a unit of work within that client +session. The unit of work acts as an exclusive transactional object +space, and also ensures that any changes that are committed to the +database also occur in the session cache. + +[width="100%",cols="<100%",] +|=== +|*Note*: Although client sessions are thread-safe, do not use them to +write across multiple threads. Multithread write operations from the +same client session can result in errors and a loss of data. For more +information, see link:#Concurrency[Concurrency]. +|=== + +This figure illustrates how to write to the database using a client +session acquired from a server session. + +[#Figure 83-5]## *_Writing with Client Sessions and Server Sessions_* + +.Writing with Client Sessions and Server Sessions +image::uowwrite.gif[Writing with Client Sessions and Server +Sessions,title="Writing with Client Sessions and Server Sessions"] + +To write to the database using a unit of work, use this procedure: + +[arabic] +. Acquire a session from the server session: ++ +`+Server server = (Server)SessionManager.getManager().getSession(+` +`+                sessionName, MyServerSession.class.getClassLoader());+` +`+Session clientSession = (Session) server.acquireClientSession();+` ++ +For more information, see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)[Acquiring +and Using Sessions at Run Time]. +. Acquire a `+UnitOfWork+` object from the `+Session+` object. ++ +`+UnitOfWork uow = clientSession.acquireUnitOfWork();+` ++ +For more information, see link:#Unit_of_Work_Sessions[Unit of Work +Sessions]. +. Use the unit of work to perform the required updates and then commit +the `+UnitOfWork+`. ++ +For more information, see the following: +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#CACJAFJD[Introduction +to EclipseLink Queries] +* link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions] +* link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions] + +==== Security and User Privileges + +You can define several different server sessions in your application to +support users with different data access rights. For example, your +application may serve a group called "`Managers,`" who has access rights +to salary information, and a group called "`Employees,`" who do not. +Because each session you define in the `+sessions.xml+` file has its own +login information, you can create multiple sessions, each with its own +login credentials, to meet the needs of both of these groups. + +When you use internal EclipseLink connection pools (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[Connection +Pools]), each server session provides a read connection pool and a write +connection pool. All read queries use connections from the read +connection pool and all queries that write changes to the data store use +connections from the write connection pool. This ensures that +connections for one session are kept separate from the connections used +in another. + +To further isolate users from one another, you can use an isolated +session: a special type of client session that provides its own session +cache isolated from the shared object cache of its parent server session +to provide improved user-based security, or to avoid caching highly +volatile data. For more information, see +link:#Isolated_Client_Sessions[Isolated Client Sessions]. + +==== Concurrency + +The server session supports concurrent clients by providing each client +with a dedicated thread of execution. Dedicated threads enable clients +to operate asynchronously–that is, client processes execute as they are +called and do not wait for other client processes to complete. + +EclipseLink safeguards thread safety with a concurrency manager. The +concurrency manager ensures that no two threads interfere with each +other when performing operations such as creating new objects, executing +a transaction on the database, or accessing value holders. + +For more information about handling concurrency issues, see +link:Introduction%20to%20Cache%20(ELUG)#Handling_Stale_Data[Handling +Stale Data]. + +==== Connection Allocation + +When you instantiate the server session, it creates a pool of data +source connections. The session then manages the connection pool based +on your session configuration, and shares the connections among its +client sessions. When the client session releases the connection, the +server session recovers the connection and makes it available to other +client processes. Reusing connections reduces the number of connections +required by the application and allows a server session to support a +larger number of clients. + +The server session provides connections to client sessions as needed. By +default, the server session does not allocate a data source connection +for a client session until a transaction starts (a lazy data source +connection). Alternatively, you can acquire a client session that +allocates a connection immediately (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Does_Not_Use_Lazy_Connection_Allocation[How +to Acquire a Client Session that Does Not Use Lazy Connection +Allocation]). + +The server session allocates read connections from its read connection +pool to all client sessions. If your application requires multiple read +security levels then you must use multiple server sessions or +EclipseLink isolated sessions (see +link:#Isolated_Client_Sessions[Isolated Client Sessions]). + +The server session also supports multiple write connection pools and +nonpooled connections. Be default, all client sessions use the default +write connection pool. However, if your application requires multiple +security levels or user logins for write access, then you can use +multiple write connection pools. You can configure a client session to +use a specific write connection pool or nonpooled connection when it is +acquired (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_a_Named_Connection_Pool[How +to Acquire a Client Session that Uses a Named Connection Pool]). This +connection is only used for writes, not reads (reads still go through +the server session read connection pool). + +For more information, see the following: + +* link:Introduction%20to%20Data%20Access%20(ELUG)#Internal_Connection_Pools[Internal +Connection Pools] +* link:Introduction%20to%20Data%20Access%20(ELUG)#External_Connection_Pools[External +Connection Pools] + +== Unit of Work Sessions + +The unit of work ensures that the client edits objects in a separate +object transaction space. This feature lets clients perform object +transactions in parallel. When transactions are committed, the unit of +work makes any required changes in the database, and then merges the +changes into the shared EclipseLink session cache. The modified objects +are then available to all other users. + +For information on creating, configuring, and using a unit of work, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. + +== Isolated Client Sessions + +An isolated client session is a special type of client session that +provides its own session cache. This session cache is isolated from the +shared session cache of its parent server session. + +If in your EclipseLink project you configure all classes as isolated +(see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Cache_Isolation_at_the_Project_Level[Configuring +Cache Isolation at the Project Level]), or one or more classes as +isolated (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]), then all client sessions that +you acquire from a parent server session will be isolated client +sessions. + +This figure illustrates the relationship between a parent server +session’s shared session cache and its child isolated client sessions. + +[#Figure 83-6]## *_Isolated Client Sessions_* + +.Isolated Client Sessions +image::isolses.gif[Isolated Client +Sessions,title="Isolated Client Sessions"] + +Each isolated client session owns an initially empty cache and identity +maps used exclusively for isolated objects that the isolated client +session accesses while it is active. The isolated client session’s +isolated session cache is discarded when the isolated client session is +released. + +When you use an isolated client session to read an isolated class, the +client session reads the isolated object directly from the database and +stores it in that client session’s isolated session cache. When you use +the client session to read a shared class, the client session reads the +shared object from the parent server session’s shared session cache. If +the shared object is not in the parent server session’s shared session +cache, it will read it from the database and store it in the parent +server session’s shared session cache. + +Isolated objects in an isolated client session’s isolated session cache +may reference shared objects in the parent server session’s shared +session cache, but shared objects in the parent server session’s shared +session cache cannot reference isolated objects in an isolated client +session’s isolated session cache. + +[width="100%",cols="<100%",] +|=== +|*Note*: You cannot define mappings from shared classes to isolated +classes. +|=== + +Client sessions can access the data source using a connection pool, or +an exclusive connection. To use an exclusive connection, acquire the +isolated client session using a `+ConnectionPolicy+` (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_Exclusive_Connections[How +to Acquire a Client Session that Uses Exclusive Connections]). Using an +exclusive connection provides improved user-based security for reads and +writes. Named queries can also use an exclusive connection (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Advanced_Options[Configuring +Named Query Advanced Options]). + +[width="100%",cols="<100%",] +|=== +|*Note*: If an isolated session contains an exclusive connection, you +must release the session when you are finished using it. We do not +recommend relying on the finalizer to release the connection when the +session is garbage-collected. If you are using an active unit of work in +a JTA transaction, you do not need to release the client session–-the +unit of work will release it after the JTA transaction completes. +|=== + +Use isolated client sessions to do the following: + +* avoid caching highly volatile data in the shared session cache; +* achieve serializable transaction isolation (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Isolated_Client_Session_Cache[Isolated +Client Session Cache]); +* use the Oracle Virtual Private Database (VPD) feature in your +EclipseLink-enabled application (see +link:#Isolated_Client_Sessions_and_Oracle_Virtual_Private_Database_(VPD)[Isolated +Client Sessions and Oracle Virtual Private Database (VPD)]). + +For more information, see the following: + +* link:#Isolated_Client_Session_Limitations[Isolated Client Session +Limitations] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_an_Isolated_Client_Session[How +to Acquire an Isolated Client Session] +* link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)[Configuring +Exclusive Isolated Client Sessions for Virtual Private Database] + +=== Isolated Client Sessions and Oracle Virtual Private Database (VPD) + +Oracle9__i__ Database Server (and later) provides a server-enforced, +fine-grained access control mechanism called Virtual Private Database +(VPD). VPD ties a security policy to a table by dynamically appending +SQL statements with a predicate to limit data access at the row level. +You can create your own security policies, or use Oracle’s custom +implementation of VPD called Oracle Label Security (OLS). For more +information on VPD and OLS, see the following: + +http://www.oracle.com/technology/deploy/security/index.html[`+http://www.oracle.com/technology/deploy/security/index.html+`]. + +To use the Oracle Database VPD feature in your EclipseLink-enabled +application, use isolated client sessions. + +Any class that maps to a table that uses VPD must have the descriptor +configured as isolated (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]). + +When you use isolated client sessions with VPD, you typically use +exclusive connections (see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_Exclusive_Connections[How +to Acquire a Client Session that Uses Exclusive Connections]). + +To support VPD, you are responsible for implementing session event +handlers that the EclipseLink runtime invokes during the isolated client +session life cycle (see +link:#Isolated_Client_Session_Life_Cycle[Isolated Client Session Life +Cycle]). The session event handler you must implement depends on whether +or not you are using Oracle Database proxy authentication (see +link:#VPD_with_Oracle_Database_Proxy_Authentication[VPD with Oracle +Database Proxy Authentication] and +link:#VPD_Without_Oracle_Database_Proxy_Authentication[VPD Without +Oracle Database Proxy Authentication]). + +For information, see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)[Configuring +Exclusive Isolated Client Sessions for Virtual Private Database]. + +==== VPD with Oracle Database Proxy Authentication + +If you are using Oracle Database proxy authentication ( +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database Proxy Authentication]), you must implement a session event +handler for the following session events: + +* `+noRowsModifiedSessionEvent+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_NoRowsModifiedSessionEvent_Event_Handler[Using +NoRowsModifiedSessionEvent Event Handler]) + +By using Oracle Database proxy authentication, you can set up VPD +support entirely in the database. That is, rather than making the +isolated client session execute SQL (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PostAcquireExclusiveConnection_Event_Handler[Using +PostAcquireExclusiveConnection Event Handler] and +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PreReleaseExclusiveConnection_Event_Handler[Using +PreReleaseExclusiveConnection Event Handler]), the database performs the +required setup in an after login trigger using the proxy +`+session_user+`. + +==== VPD Without Oracle Database Proxy Authentication + +If you are not using Oracle Database proxy authentication, you must +implement session event handlers for the following session events: + +* `+postAcquireExclusiveConnection+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PostAcquireExclusiveConnection_Event_Handler[Using +PostAcquireExclusiveConnection Event Handler]): used to perform VPD +setup at the time EclipseLink allocates a dedicated connection to an +isolated session and before the isolated session user uses the +connection to interact with the database. +* `+preReleaseExclusiveConnection+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PreReleaseExclusiveConnection_Event_Handler[Using +PreReleaseExclusiveConnection Event Handler]): used to perform VPD +cleanup at the time the isolated session is released and after the user +is finished interacting with the database. +* `+noRowsModifiedSessionEvent+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_NoRowsModifiedSessionEvent_Event_Handler[Using +NoRowsModifiedSessionEvent Event Handler]) + +In your implementation of these handlers, you obtain the required user +credentials from the `+ConnectionPolicy+` associated with the session +(see +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How_to_Acquire_a_Client_Session_that_Uses_Connection_Properties[How +to Acquire a Client Session that Uses Connection Properties]). + +==== Isolated Client Session Life Cycle + +This section provides an overview of the key phases in the life cycle of +an isolated session, including the following: + +* Setup required before using an isolated session +* Interaction among isolated session objects +* Clean-up required after using an isolated session + +To enable the life cycle of an isolated session, use this procedure: + +[arabic] +. Prepare VPD configuration in the database. +. Configure your project and session: +* Designate descriptors as isolated (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Isolation_at_the_Descriptor_Level[Configuring +Cache Isolation at the Descriptor Level]). +* Configure your server session to allocate exclusive connections (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Connection_Policy[onfiguring +Connection Policy]). +* Implement session event listeners for the required connection events: +** If you are using +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database proxy authentication], see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_NoRowsModifiedSessionEvent_Event_Handler[Using +NoRowsModifiedSessionEvent Event Handler]. +** If you are not using Oracle Database proxy authentication, see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PostAcquireExclusiveConnection_Event_Handler[Using +PostAcquireExclusiveConnection Event Handler], +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_PreReleaseExclusiveConnection_Event_Handler[Using +PreReleaseExclusiveConnection Event Handler], and +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_NoRowsModifiedSessionEvent_Event_Handler[Using +NoRowsModifiedSessionEvent Event Handler] ++ ++ ++ ++ +*Note:* You must add these session event listeners to the server session +from which you acquire your isolated client session. You cannot add them +to the isolated client session itself. For more information, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_Session_Event_Listeners[Configuring +Session Event Listeners] ++ ++ ++ +* Implement exception handlers for the appropriate exceptions (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using_ValidationException_Handler[Using +ValidationException Handler]). +. Acquire an isolated session: +* If you are using +link:Introduction%20to%20Data%20Access%20(ELUG)#Oracle_Database_Proxy_Authentication[Oracle +Database proxy authentication]: ++ +`+Session myIsolatedClientSession = +` +`+server.acquireClientSession();+` ++ +Because you configured one or more descriptors as isolated, +`+myIsolatedClientSession+` is an isolated session with an exclusive +connection. +* If you are not using Oracle Database proxy authentication: ++ +`+ConnectionPolicy myConnPolicy = (ConnectionPolicy)server.getDefaultConnectionPolicy().clone();+` +`+myConnectionPolicy.setProperty("credentials", myUserCredentials);+` +`+Session myIsolatedClientSession = server.acquireClientSession(myConnectionPolicy);+` ++ +Set the user’s credentials as appropriate properties on +`+myConnectionPolicy+`. Because you configured one or more descriptors +as isolated, `+myIsolatedClientSession+` is an isolated session with an +exclusive connection. The EclipseLink runtime raises a +`+SessionEvent.PostAcquireExclusiveConnection+` event handled by your +`+SessionEventListener+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHJFGFD[Using +PostAcquireExclusiveConnection Event Handler]). +. Use `+myIsolatedClientSession+` to interact with the database. If the +EclipseLink runtime raises a `+SessionEvent.NoRowsModified+` event, it +is handled by your `+SessionEventListener+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHHJCDG[Using +NoRowsModifiedSessionEvent Event Handler]). +. When you are finished using `+myIsolatedClientSession+`, release the +isolated session: ++ +`+myIsolatedClientSession.release();+` ++ +The EclipseLink runtime prepares to destroy the isolated cache and to +close the exclusive connection associated with this isolated session. +The EclipseLink runtime raises a +`+SessionEvent.PreReleaseExclusiveConnection+` event handled by your +`+SessionEventListener+` (see +link:Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHEEIEF[Using +PreReleaseExclusiveConnection Event Handler]). +. Repeat steps #3 to #5 (as required) until the application exits. + +=== Isolated Client Session Limitations + +For the purposes of security as well as efficiency, observe the +limitations described in the following section, when you use isolated +client sessions in your EclipseLink three-tier application: + +* link:#Mapping[Mapping] +* link:#Inheritance[Inheritance] +* link:#Caching_and_Cache_Coordination[Caching and Cache Coordination] +* link:#Sequencing[Sequencing] +* link:#Transactions_and_JTA[Transactions and JTA] + +==== *Mapping* + +Consider the following mapping and relationship restrictions when using +isolated sessions with your relational model: + +* Isolated objects may be related to shared objects, but shared objects +cannot have any relationships with isolated objects. +* If a table has a VPD security policy associated with it, then the +class mapped to that table must be isolated. +* If one of the tables in a multiple table mapping is isolated, then the +main class must also be isolated. + +The EclipseLink runtime enforces these restrictions during descriptor +initialization. + +==== *Inheritance* + +Aggregates and aggregate mappings inherit the isolated configuration of +their parents. + +If a class is isolated, then all inheriting classes should be isolated. +Otherwise, if you relate a shared class to a shared superclass with +isolated subclasses, it is possible that some of the isolated subclasses +will lose object identity when the isolated session is released. + +To give you the flexibility to mix shared and isolated classes, the +EclipseLink runtime does not enforce these restrictions during +descriptor initialization. If you wish to mix shared and isolated +classes in your inheritance hierarchy, then you must be prepared to deal +with this possible loss of object identity. + +==== *Caching and Cache Coordination* + +Isolated classes are never loaded into the shared cache of a parent +server session. Isolated classes cannot be used with cache coordination. + +==== *Sequencing* + +We recommend that you do not configure a sequencing object or sequence +table using VPD security. EclipseLink does not access sequencing objects +using the isolated session’s dedicated connection, and so VPD restricted +sequence values are not available to the isolated session. Sequence +objects not using VPD security are fine. + +==== *Transactions and JTA* + +We recommend that you explicitly release an isolated session when you +are finished using it, rather than wait for the Java garbage collector +to invoke the finalizer. The finalizer is provided as a last resort: +waiting for the garbage collector may cause errors when dealing with a +JTA transaction. + +== Historical Sessions + +By default, a session represents a view of the most current version of +objects, and when you execute a query in that session, it returns the +most current version of selected objects. + +If your data source maintains past versions of objects, you can +configure EclipseLink to access this historical data so that you can +express read queries conditional on how your objects are changing over +time. You can also do the following: + +* Make series of queries relative to any point in time–not just the time +of the first query. +* Provide read consistency so that a series of read operations or report +queries all execute as if at the same time. +* Use the `+mergeClone+` method to provide deep recovery of an object by +passing in a past version of it. + +In addition, you can express query selection criteria as either of the +following: + +* A condition at a past time: for example, "`employees who used to…`". +* A change over time: for example, "`employees who recently…`". + +For more information, see the following: + +* link:#Historical_Session_Limitations[Historical Session Limitation] +* link:Configuring%20Historical%20Sessions%20(ELUG)#CIHCCEFA[Configuring +Historical Sessions] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Historical_Session[Acquiring +a Historical Session] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Historical_Queries[Historical +Queries]. + +=== Historical Session Limitations + +The `+HistoryPolicy+` provides a very flexible means of accommodating a +wide variety of historical schemas. However, be aware of the following +restrictions: + +* You cannot use the `+HistoryPolicy+`, if your design combines both +current and historical data in a single schema. +* EclipseLink assumes that the current version of an object corresponds +to the row in the historical table whose row end field is `+NULL+`. +* You cannot directly map the start and end fields of a history table +because they do not exist in the regular schema. +* You cannot query on ranges of historical objects, only as of a +specific point in time. + +== Session Broker and Client Sessions + +The *EclipseLink session broker* is a mechanism that enables client +applications to transparently access multiple databases through a single +EclipseLink session. + +The EclipseLink session broker enables client applications to access two +or more databases through a single session. If your application stores +objects in multiple databases, the session broker, which provides +seamless communication for client applications, enables the client to +view multiple databases as if they were a single database. + +When a three-tier session broker application uses server sessions to +communicate with the database, clients require a client session to +access the database. Similarly, when you implement a session broker, the +client requires a _client session broker_ to access the database. + +A *client session broker* is a collection of client sessions, one from +each server session associated with the session broker. When a client +acquires a client session broker, the session broker collects one client +session from each associated server session, and wraps the client +sessions so that they appear to be a single client session to the client +application. + +As this illustrates, a session broker connects to the databases through +two or more server sessions or database sessions. + +[#Figure 83-7]## *_EclipseLink Session Broker with Server Session +Architecture_* + +.EclipseLink Session Broker with Server Session Architecture +image::sesbrokfig.gif[EclipseLink Session Broker with Server Session +Architecture,title="EclipseLink Session Broker with Server Session Architecture"] + +This section explains the following: + +* link:#Session_Broker_Architecture[Session Broker Architecture] +* link:#Committing_a_Transaction_with_a_Session_Broker[Committing a +Transaction with a Session Broker] +* link:#Session_Broker_Session_Limitations[Session Broker Session +Limitations] +* link:#Session_Broker_Alternatives[Session Broker Alternatives] + +For information, see the following: + +* link:Creating%20a%20Session%20(ELUG)#Creating_Session_Broker_and_Client_Sessions[Creating +Session Broker and Client Sessions] +* link:Configuring%20Session%20Broker%20and%20Client%20Sessions%20(ELUG)#CHDEDEDA[Configuring +Session Broker and Client Sessions] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#i1121932[Acquiring +a Session from the Session Manager] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#CFAJJJGB[Acquiring +a Client Session] + +=== Session Broker Architecture + +As the link:#Figure_83-7[EclipseLink Session Broker with Server Session +Architecture] figure illustrates, a session broker contains a broker +object that acts as an intermediary between the application and the +multiple sessions added to the session broker. + +To construct a session broker, use Workbench to modify your +`+sessions.xml+` file as follows: + +[arabic] +. Define two or more sessions (of the same type, either server sessions +or database sessions). +. Define a session broker. +. Add the sessions to the session broker. + +When you use `+SessionManager+` method `+getSession(sessionBrokerName)+` +where `+sessionBrokerName+` is the name of the session broker you +defined, the session manager returns the corresponding session broker +session (call it `+mySessionBroker+`) that contains an instance of each +of the sessions you added to it. When you use `+mySessionBroker+` method +`+login+`, it logs into each defined session. Thereafter, you use +`+mySessionBroker+` as you would any other session: EclipseLink +transparently handles access to the multiple databases. + +In the case of a three-tier architecture where the session broker +contains two or more server sessions, you use session broker method +`+acquireClientSessionBroker+` to acquire a single client session that +lets you query across all the data sources managed by the various server +sessions. You use this client session as you would any other client +session. + +=== Committing a Transaction with a Session Broker + +By default, when you commit a transaction with a session broker session, +a two-stage commit is performed. + +Ideally, you should incorporate a JTA external transaction controller in +order to benefit from its two-phase commit. + +==== Committing a Session with a JTA Driver: Two-Phase Commits + +If you use a session broker, incorporate a JTA external transaction +controller wherever possible. The external transaction controller +provides a _two-phase commit_, which passes the SQL statements that are +required to commit the transaction to the JTA driver. The JTA driver +handles the entire commit process. + +JTA guarantees that the transaction commits or rolls back completely, +even if the transaction involves more than one database. If the commit +operation to any one database fails, then all database transactions roll +back. The two-phase commit operation is the safest method available to +commit a transaction to the database. + +Two-phase commit support requires integration with a compliant JTA +driver. + +==== Committing a Session Without a JTA Driver: Two-Stage Commits + +If there is no JTA driver available, then the session broker provides a +_two-stage commit_ algorithm. A two-stage commit differs from a +two-phase commit in that it guarantees data integrity only up to the +point of the final commit of the transaction. If the SQL script executes +successfully on all databases, but the commit operation then fails on +one database, only the database that experiences the commit failure +rolls back. + +Although unlikely, this scenario is possible. As a result, if your +system does not include a JTA driver and you use a two-stage commit, +build a mechanism into your application to deal with this type of +potential problem. + +=== Session Broker Session Limitations + +Although the session broker is a powerful tool that lets you use data +that is distributed across multiple databases from a single application, +it has some limitations including the following: + +* It may not meet the needs of your particular distributed data +application (see link:#Session_Broker_Alternatives[Session Broker +Alternatives]). +* You cannot split multiple table descriptors across databases. +* Each class must reside on only one database. +* You cannot use joins through expressions across databases. +* Many-to-many join tables must reside on the same database as the +target object (See +link:#Many-to-Many_Join_Tables_and_Direct_Collection_Table[Many-to-Many +Join Tables and Direct Collection Tables] for a work-around for this +limitation). + +==== Many-to-Many Join Tables and Direct Collection Tables + +By default, EclipseLink assumes that many-to-many and direct collection +tables are on the same database as the source object. If they are on a +different database, then you must configure the mapping’s session name +using `+ManyToManyMapping+` or `+DirectCollectionMapping+` method +`+setSessionName+`, as this example illustrates. Note that a +many-to-many join table must still reside on the same database as the +target object. + +[#Example 83-4]## *_Using Mapping setSessionName in a Descriptor +Amendment Method_* + +[source,java] +---- + public void addToDescriptor(ClassDescriptor descriptor) { + descriptor.getMappingForAttributeName("projects").setSessionName("branch-database"); + } +---- + +To work around this problem for data-level queries, use the +`+DatabaseQuery+` method `+setSessionName+`. + +=== Session Broker Alternatives + +When evaluating whether or not to use a session broker in your +application, consider the following alternatives: + +* link:#Database_Linking[Database Linking] +* link:#Multiple_Sessions[Multiple Sessions] + +==== Database Linking + +Most enterprise databases, such as the Oracle Database, support linking +other databases on the database server. This allows querying and +two-phase commit across linked databases. Using the session broker is +not the same as linking databases. If your database allows linking, we +recommend that you use that functionality to provide multiple database +access instead of using a session broker. + +==== Multiple Sessions + +An alternative to the session broker is to use multiple sessions to work +with multiple databases, as follows: + +* If the data on each database is unrelated to data on the other +databases, and relationships do not cross database boundaries, then you +can create a separate session for each database. For example, you might +have individual databases and associated sessions dedicated to each +department. This arrangement requires that you to manage each session +manually and ensure that the class descriptors for your project reside +in the correct session. +* You can use additional sessions to house a standard batch job. In this +case, you can create two or more sessions on the same database. In +addition to the main session that supports client queries, you create +other sessions that support batch inserts at low-traffic times in your +system. This lets you maintain the client cache. + +== Database Sessions + +A *database session* provides a client application with a single data +source connection, for simple, standalone applications in which a single +connection services all data source requests for one user. + +[#Figure 83-8]## *_EclipseLink Database Session Architecture_* + +.EclipseLink Database Session Architecture +image::Dbsess.gif[EclipseLink Database Session +Architecture,title="EclipseLink Database Session Architecture"] + +A database session is the simplest session EclipseLink offers. It +provides both client and server communications and supports only a +single client and a single database connection. It is suitable for +simple applications or 2-tier applications. + +[width="100%",cols="<100%",] +|=== +|*Note*:We do not recommend using this session type in a 3-tier +application because it is not as flexible or scalable as a server and +client session. We recommend that you use server sessions and client +sessions (see link:#Server_and_Client_Sessions[Server and Client +Sessions]). Applications that are built using database sessions may be +difficult to migrate to a scalable architecture in the future. +|=== + +A database session contains and manages the following information: + +* An instance of `+Project+` and `+DatabaseLogin+`, which store database +login and configuration information +* The JDBC connection and the database access +* The descriptors for each of the application persistent classes +* Identity maps that maintain object identity and act as a cache + +For more information, see the following: + +* link:Creating%20a%20Session%20(ELUG)#Creating_Database_Sessions[Creating +Database Sessions] +* link:Configuring%20Database%20Sessions%20(ELUG)#CHDGHACC[Configuring +Database Sessions] +* link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_a_Session_from_the_Session_Manager[Acquiring +a Session from the Session Manager] + +== Remote Sessions + +A *remote session* is a client-side session that communicates over RMI +with a corresponding client session and server session on the +server-side. Remote sessions handle object identity and marshalling and +unmarshalling between client-side and server-side. + +A remote session resides on the client rather than the EclipseLink +server. The remote session does not replace the client session; rather, +a remote session requires a client session to communicate with the +server session. + +[#Figure 83-9]## *_Typical EclipseLink Server Session with Remote +Session Architecture_* + +.Typical EclipseLink Server Session with Remote Session Architecture +image::Remtsess.gif[Typical EclipseLink Server Session with Remote +Session +Architecture,title="Typical EclipseLink Server Session with Remote Session Architecture"] + +The remote session provides a full EclipseLink session, complete with a +session cache, on the client system. EclipseLink manages the remote +session cache and enables client applications to execute operations on +the server. + +A remote session offers database access to clients that do not reside on +the server. The remote session resides on the client and connects by way +of RMI to a corresponding client session, which, in turn, connects to +its server session on the server. + +This section describes the following: + +* link:#Architectural_Overview[Architectural Overview] +* link:#Remote_Session_Concepts[Remote Session Concepts] + +For more information, see +link:Creating%20a%20Session%20(ELUG)#Creating_Remote_Sessions[Creating +Remote Sessions]. + +=== Architectural Overview + +As the link:#Figure_83-10[An Architectural Overview of the Remote +Session] figure illustrates, the remote session model consists of the +following layers: + +* The application layer–a client-side application talking to a remote +session +* The transport layer–a communication layer, RMI or RMI-IIOP +* The server layer–an EclipseLink session communicating with a database + +The request from the client application to the server travels down +through the layers of a distributed system. A client that makes a +request to the server session uses the remote session as a conduit to +the server session. The client references the remote session, and the +remote session forwards a request to the server session through the +transport layer. + +At run time, the remote session builds its knowledge base by reading +descriptors and mappings from the server side as they are needed. These +descriptors and mappings are lightweight, because not all information is +passed on to the remote session. The information needed to traverse an +object tree and to extract primary keys from the given object is passed +with the mappings and descriptors. + +[#Figure 83-10]## *_An Architectural Overview of the Remote Session_* + +.An Architectural Overview of the Remote Session +image::remarch.gif[An Architectural Overview of the Remote +Session,title="An Architectural Overview of the Remote Session"] + +==== Application Layer + +The application layer includes the application client and the remote +session. The remote session is a subclass of `+Session+` and maintains +all the public protocols of the session, giving the appearance of +working with the corresponding client session. + +The remote session maintains its own identity map and a project of all +the descriptors read from the server. If the remote session can handle a +request by itself, the request is not passed to the server. For example, +a request for an object that is in the remote session cache is processed +by the remote session. However, if the object is not in the remote +session cache, the request passes to the server session. + +==== Transport Layer + +The transport layer is responsible for carrying the semantics of the +invocation. It is a layer that hides all the protocol dependencies from +the application and server layers. + +The transport layer includes a remote connection that is an abstract +entity, through which all requests to the server are forwarded. Each +remote session maintains a single remote connection that marshals and +unmarshals all requests and responses on the client side. + +The remote session supports communications over RMI. + +==== Server Layer + +The server layer includes a remote session controller dispatcher and an +EclipseLink sessions: link:#Figure_83-10[An Architectural Overview of +the Remote Session] illustrates a three-tier server and its client +sessions. The remote session controller dispatcher is an interface +between the session and transport layers: it marshals and unmarshals all +responses and requests between the sessions on the server and their +corresponding remote sessions on the client. + +=== Remote Session Concepts + +When using remote sessions, consider the following: + +* link:#Securing_Remote_Session_Access[Securing Remote Session Access] +* link:#Queries[Queries] +* link:#Refreshing[Refreshing] +* link:#Indirection[Indirection] +* link:#Cursored_Streams[Cursored Streams] +* link:#Unit_of_Work[Unit of Work] + +==== Securing Remote Session Access + +The remote session represents a potential security risk because it +requires you to register a remote session controller dispatcher as a +service that anyone can access. This can expose the entire database to +nonprivileged access. + +To reduce this threat, run a server manager as a service to hold the +remote session controller dispatcher. All the clients must then +communicate through the server manager, which implements the security +model for accessing the remote session controller dispatcher. + +On the client side, the user requests the remote session controller +dispatcher. The manager returns a remote session controller dispatcher +only if the user has access rights according to the security model built +into the server manager. + +To access the system, the remote session controller dispatcher on the +client side creates a remote connection, and acquires a remote session +from the remote connection. The API for the remote session is the same +as for the session, and there is no user-visible difference between +working on a session or a remote session. + +==== Queries + +Read queries are publicly available on the client side, but queries that +modify objects must be performed using the unit of work. + +==== Refreshing + +Calling refresh methods on the remote session causes database read +operations, and may also cause cache updates if the data being refreshed +is modified in the database. This can lead to poor performance. + +To improve performance, configure refresh methods to run against the +server session cache, by configuring the descriptor to always remotely +refresh the objects in the cache on all queries. This technique ensures +that all queries against the remote session refresh the objects from the +server session cache, without the database access. + +Cache hits on remote sessions still occur on read object queries based +on the primary keys. To avoid this, disable the remote session cache +hits on read object queries based on the primary key. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Refreshing[Configuring +Cache Refreshing]. + +==== Indirection + +The remote session supports indirection (lazily loaded) objects. An +indirection object is a value holder that can be invoked remotely on the +client side. When invoked, the value holder first checks to see if the +requested object exists on the remote session. If not, then the +associated value holder on the server is instantiated to get the value +that is then passed back to the client. Remote value holders are used +automatically; the application’s code does not change. + +==== Cursored Streams + +A remote session supports both cursored streams and scrollable cursors. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Stream_and_Cursor_Query_Results[Stream +and Cursor Query Results]. + +==== Unit of Work + +Use a unit of work acquired from the remote session to modify objects on +the database. A unit of work acquired from the remote session offers the +user the same functionality as a unit of work acquired from the client +session or the database session. + +== Sessions and the Cache + +Server, database, isolated, and historical sessions include an identity +map that maintains object identity, and acts as a cache. + +This section explains how the cache differs between the following +sessions: + +* link:#Server_and_Database_Session_Cache[Server and Database Session +Cache] +* link:#Isolated_Session_Cache[Isolated Session Cache] +* link:#Historical_Session_Cache[Historical Session Cache] + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)#CHEJAEBH[Introduction to Cache]. + +=== Server and Database Session Cache + +When a server or database session reads objects from the database, it +instantiates them and stores them in its identity map (cache). When the +application subsequently queries for the same object, EclipseLink +returns the object in the cache, rather than read the object from the +database again. + +This cache plays an important role in the performance of your +application. + +In the case of a server session, all client sessions acquired from it +share the server session’s cache. + +To define how the cache manages objects, specify a strategy for cache +management in Workbench. + +=== Isolated Session Cache + +When an isolated session reads an object, whose descriptor is configured +as isolated, that object is instantiated and stored in the isolated +session’s cache only–it is not stored in the parent server session’s +shared object cache. Objects in the isolated session’s cache may +reference objects in the parent server session’s shared object cache, +but objects in the parent server session’s shared object cache can never +reference objects in the isolated session’s cache. + +=== Historical Session Cache + +When a historical session reads objects, it does so only from its +static, read-only cache, which is populated with all objects as of a +specified time. + +== Session API + +The session API is defined by the following interfaces: + +* `+org.eclipse.persistence.sessions.Session+` +* `+org.eclipse.persistence.sessions.DatabaseSession+` +* `+org.eclipse.persistence.sessions.UnitOfWork+` +* `+org.eclipse.persistence.sessions.server.Server+` + +These APIs are used at run time to access objects and the data source. +Always use the session public interfaces, not the corresponding +implementation classes. + +You should use the `+Session+` interface when reading and querying with +any of client sessions, session brokers, isolated client sessions, +historical sessions, remote sessions, and database sessions. + +You should use the `+UnitOfWork+` interface for all units of work +acquired from any type of session. + +You should use the `+Server+` interface to configure and acquire a +client session from a `+Server+` session. + +The `+DatabaseSession+` interface can be used for a database +session.Typically, you define server sessions, database sessions, and +session broker sessions in a `+sessions.xml+` file and acquire them at +run time using the `+SessionManager+`. You can also acquire a server +session or database session from a `+Project+`. The only session that +should ever be instantiated directly is the `+SessionBroker+`, and only +when not using the `+SessionManager+`. + +You acquire a client session from a server session. + +You can also acquire a client session broker from a session broker +composed of server sessions. + +You acquire a unit of work from any session instance, client session +broker, or session broker which contains `+DatabaseSession+` instances. + +This example illustrates the session interfaces that derive from +`+org.eclipse.persistence.sessions.Session+` interface. + +[#Example 83-5]## *_Session Interface Inheritance Hierarchy_* + +`+org.eclipse.persistence.sessions.Session+` +`+    org.eclipse.persistence.sessions.DatabaseSession+` +`+        org.eclipse.persistence.sessions.server.Server+` +`+    org.eclipse.persistence.sessions.UnitOfWork+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Support_for_Oracle_Spatial_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Support_for_Oracle_Spatial_(ELUG).adoc new file mode 100644 index 00000000000..be5f79f37a3 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Support_for_Oracle_Spatial_(ELUG).adoc @@ -0,0 +1,217 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Support_for_Oracle_Spatial_(ELUG)[Related +Topics] + +This section provides an overview of the EclipseLink support for Oracle +Spatial, as well as demonstrates the ways to extend EclipseLink to +support the mapping and querying of Oracle Spatial columns +(`+MDSYS.SDO_GEOMETRY+`). + +For more information about Oracle Spatial, see +http://www.oracle.com/technology/products/spatial/index.html[`+http://www.oracle.com/technology/products/spatial/index.html+`] + +== EclipseLink Support for Oracle Spatial + +EclipseLink provides support for direct mappings of database columns of +type `+MDSYS.SDO_GEOMETRY+` to attributes of the +`+oracle.spatial.geometry.JGeometry+` data type. + +EclipseLink also provides support for spatial operators (see +link:#How_to_Perform_Queries_Using_Spatial_Operator_Expressions[How to +Perform Queries Using Spatial Operator Expressions]) through the +EclipseLink expression framework (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Introduction_to_EclipseLink_Expressions[Introduction +to EclipseLink Expressions]), as well as for custom object types that +wrap `+SDO_GEOMETRY+`. + +For information on using EclipseLink structure converter with +application servers (for example, Oracle WebLogic Server, JBoss, or +SunAS), see the relevant server documentation. + +== Using Structure Converters + +In EclipseLink, a +`+org.eclipse.persistence.platform.database.DatabasePlatform+` (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms]) stores a list of structure converters. + +To create a custom converter, implement the +`+org.eclipse.persistence.platform.database.converters.StructConverter+` +interface and register it on your direct-to-field mapping (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping]). + +To use the `+StructConverter+`, do the following: + +[arabic] +. Configure the database platform (see +link:#How_to_Configure_the_Database_Platform_to_Use_Structure_Convertes[How +to Configure the Database Platform to Use Structure Convertes]). +. Set up a mapping (see +link:#How_to_Set_Up_Mappings_Using_Structure_Converters[How to Set Up +Mappings Using Structure Converters]). + +=== How to Configure the Database Platform to Use Structure Converters + +EclipseLink uses a database platform (see +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms]) to control the usage of database vendor-specific and +version-specific operations such as SQL dialect, stored procedure calls, +sequencing, as well as platform-specific type handling. You need to +configure the platform to allow EclipseLink to use the advanced features +of the database. + +To add your structure converter to the `+DatabasePlatform+`, call +`+addStructConverter(StructConverter converter)+` method of the +`+DatabasePlatform+`. Call this method within your EclipseLink session +(server or database) prior to the session login (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Login[Configuring +a Session Login]). + +=== How to Set Up Mappings Using Structure Converters + +Use direct-to-field mappings (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping]) to map your `+STRUCT+` types. For each mapping that maps to +the type defined by the structure converter, set its field type to the +`+STRUCT+` data type, as follows: + +`+mapping.setFieldType(java.sql.Types.STRUCT);+` + +== Using JGeometry + +To use the `+oracle.spatial.geometry.JGeometry+`, do the following: + +[arabic] +. Configure the database platform (see +link:#How_to_Configure_the_Database_Platform_to_Use_JGeometry[How to +Configure the Database Platform to Use JGeometry]). +. Set up a mapping (see link:#How_to_Map_JGeometry_Attributes[How to Map +JGeometry Attributes]). + +You can query your mapped entities with expressions that use Spatial +operators. For more information, see +link:#How_to_Perform_Queries_Using_Spatial_Operator_Expressions[How to +Perform Queries Using Spatial Operator Expressions]. + +=== How to Configure the Database Platform to Use JGeometry + +To configure the database platform, add a structure converter in a form +of the +`+org.eclipse.persistence.platform.database.oracle.converters.JGeometryConverter+` +as follows: + +`+databasePlatform.addStructConverter(new JGeometryConverter());+` + +You must configure this platform within your EclipseLink session prior +to the session login (see +link:Configuring%20a%20Session%20(ELUG)[Configuring a Session Login]). + +=== How to Map JGeometry Attributes + +Use direct-to-field mappings (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping]) to map your `+STRUCT+` types. For each mapping that maps to +the type defined by the structure converter (`+JGeometry+`), set its +field type to the `+STRUCT+` data type, as follows: + +`+mapping.setFieldType(java.sql.Types.STRUCT);+` + +=== How to Perform Queries Using Spatial Operator Expressions + +With the configured database platform, you can read and write persistent +entities with `+JGeometry+` attributes mapped to `+SDO_GEOMETRY+` +columns. With this support, you can query for these mapped entities with +native SQL queries using Oracle Spatial operators. + +Spatial operators are special SQL functions supported by the Oracle +Database to enable querying and comparison of columns containing +geometry types. The spatial operators take the following format: + +`+(geometry1, geometry2, parameters) = 'TRUE' +` + +For more information on spatial operators, see _Oracle Spatial API +Documentation_ at +http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28401/toc.htm[`+http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28401/toc.htm+`]. + +EclipseLink provides the expression support for the following Spatial +operators: + +* `+SDO_WITHIN_DISTANCE+` +* `+SDO_RELATE+` +* `+SDO_FILTER+` +* `+SDO_NN+` + +Use the following methods of the +`+org.eclipse.persistence.expressions.spatial.SpatialExpressionFactory+` +class to build expressions that use Spatial operators: + +* `+withinDistance+` +* `+relate+` +* `+filter+` +* `+nearestNeighbor+` + +All these methods have the following common set of parameters: + +[arabic] +. an expression (`+org.eclipse.persistence.expressions.Expression+`) +that points to `+JGeometry+`; +. `+JGeometry+` object or an `+Expression+`; +. an `+org.eclipse.persistence.expressions.spatial.SpatialParameters+` +object that defines the parameters to the function call. + +The `+SpatialParameters+` class provides convenience methods that let +you set the parameters representing the following: + +* minimum resolution; +* maximum resolution; +* units; +* distance; +* query type; +* masks; +* `+String+` of parameters. + +The following example demonstrates how to construct a Spatial operator +expression, and then relate it to an existing `+JGeometry+` with +`+SpatialParameters+` created using a `+String+`. [#Example 108-1]## + +*_Relating an Expression Using String of Spatial Parameters_* + +`+SpatialParameters parameters = new SpatialParameters("MASK=ANYINTERACT QUERYTYPE=WINDOW");+` +`+Expression selectionCriteria = SpatialExpressionFactory.relate(expressionBuilder.get("geometry"),+` +`+                                                               rectangle,+` +`+                                                               parameters);+` + +The following example demonstrates how to relate two expressions with +`+SpatialParameters+` constructed using convenience methods. +[#Example 108-2]## + +*_Relating Two Expressions_* + +`+SpatialParameters parameters = new SpatialParameters();+` +`+parameters.setQueryType(SpatialParameters.QueryType.WINDOW.setMask(Mask.ANYINTERACT);+` +`+Expression selectionCriteria = SpatialExpressionFactory.relate(expressionBuilder1.get("geometry"),+` +`+                                                               expressionBuilder2.get("geometry"),+` +`+                                                               parameters);+` + +[#Example 108-3]## + +*_Using Nearest Neighbor_* + +`+SpatialParameters parameters = new SpatialParameters();+` +`+parameters.setParams("sdo_num_res=10");+` +`+Expression expression = SpatialExpressionFactory.nearestNeighbor(expressionBuilder.get("geometry"), geom, parameters);+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Transactions_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Transactions_(ELUG).adoc new file mode 100644 index 00000000000..71fb478cb68 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_EclipseLink_Transactions_(ELUG).adoc @@ -0,0 +1,783 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_Transactions_(ELUG)[Related +Topics] + +This section explains how transactions are implemented in EclipseLink. + +== Unit of Work Architecture + +A database *transaction* is a set of operations (create, read, update, +or delete) that either succeed or fail as a single operation. The +database discards, or _rolls back_, unsuccessful transactions, leaving +the database in its original state. Transactions may be _internal_ (that +is, provided by EclipseLink) or _external_ (that is, provided by a +source external to the application, such as an application server). + +In EclipseLink, transactions are contained in the unit of work object. +You +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Acquiring_a_Unit_of_Work[acquire +a unit of work from a session] and using its API, you can control +transactions directly or through a Java 2 Enterprise Edition (Java EE) +application server transaction controller such as the Java Transaction +API (JTA). + +Transactions execute in their own context, or logical space, isolated +from other transactions and database operations. + +The transaction context is demarcated; that is, it has a defined +structure that includes the following: + +* A *begin* point, where the operations within the transaction begin. At +this point, the transaction begins to execute its operations. +* A *commit* point, where the operations are complete and the +transaction attempts to formalize changes on the database. + +The degree to which concurrent (parallel) transactions on the same data +are allowed to interact is determined by the level of _transaction +isolation_ configured. ANSI/SQL defines four levels of database +transaction isolation, as shown in link:#Table_109-1[Transaction +Isolation Levels]. Each offers a trade-off between performance and +resistance from the following unwanted actions: + +* Dirty read: a transaction reads uncommitted data written by a +concurrent transaction. +* Nonrepeatable read: a transaction rereads data and finds it has been +modified by some other transaction that was committed after the initial +read operation. +* Phantom read: a transaction reexecutes a query and the returned data +has changed due to some other transaction that was committed after the +initial read operation. + +[#Table 109-1]## *_Transaction Isolation Levels_* + +[width="100%",cols="<38%,<17%,<26%,<19%",options="header",] +|=== +|*Transaction Isolation Level* |*Dirty Read* |*Nonrepeatable Read* +|*Phantom Read* +|Read Uncommitted |Yes |Yes |Yes + +|Read Committed |No |Yes |Yes + +|Repeatable Read |No |No |Yes + +|Serializable |No |No |No +|=== + +As a transaction is committed, the database maintains a log of all +changes to the data. If all operations in the transaction succeed, the +database allows the changes; if any part of the transaction fails, the +database uses the log to roll back the changes. + +Like any transaction, a unit of work transaction provides the following: + +* link:#Unit_of_Work_Transaction_Context[Unit of Work Transaction +Context] +* link:#Unit_of_Work_Transaction_Demarcation[Unit of Work Transaction +Demarcation] +* link:#Unit_of_Work_Transaction_Isolation[Unit of Work Transaction +Isolation] + +=== Unit of Work Transaction Context + +Unit of work operations occur within a unit of work _context_, in which +writes are isolated from the database until commit time. The unit of +work executes changes on copies, or _clones_, of objects in its own +internal cache, and if successful, applies changes to objects in the +database and the session cache. + +=== Unit of Work Transaction Demarcation + +In a standalone EclipseLink application, your application demarcates +transactions using the unit of work. + +If your application includes a Java EE container that provides +container-managed transactions, your application server demarcates +transactions using its own transaction service. You configure +EclipseLink to integrate with the container’s transaction service by +specifying an EclipseLink external transaction controller. + +An EclipseLink external transaction controller class integrates the unit +of work with an application server’s transaction service. Using an +external transaction controller, your application can participate in +transactions that span multiple data sources and that are managed by the +application server. The external transaction controller coordinates +messages and callbacks between the application server’s transaction +service and the unit of work. + +When you configure your application to use an external transaction +controller (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]), the unit of work executes as part of an external +transaction. The unit of work still manages its own internal operations, +but it waits for the external transaction to tell it to write changes +back to the database and to the session cache. + +Note that because the transaction happens outside of the unit of work +context and is controlled by the application server’s transaction +service, errors can be more difficult to diagnose and fix because +exceptions may occur outside of your application code, for example, +during application server initiated call-backs. + +You can integrate the unit of work with the following: + +* link:#JTA_Controlled_Transactions[JTA Controlled Transactions] +* link:#OTS_Controlled_Transactions[OTS Controlled Transactions] + +==== JTA Controlled Transactions + +The Java Transaction API (JTA) is the application programming interface +you use to interact with a transaction manager. + +Using JTA, your application can participate in a distributed +transaction. A transaction manager that implements JTA provides +transaction management and connection pooling and enables your +application to interact with multiple data sources transparently by +using JTA. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +==== OTS Controlled Transactions + +The CORBA Object Transaction Service (OTS) specification is part of the +Common Object Request Brokers Architecture (CORBA) Object Services model +and is the standard for Object Request Broker (ORB) implementations. +Some servers implement the Java APIs for the OTS rather than for JTA +(see link:#JTA_Controlled_Transactions[JTA Controlled Transactions]). + +Use EclipseLink OTS support with the unit of work to directly access the +Java OTS interfaces of servers that do not support JTA. + +To integrate your application with an OTS transaction service, you must +configure your application to use a custom server platform (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== Unit of Work Transaction Isolation + +The unit of work does not directly participate in database transaction +isolation. Because the unit of work may execute queries outside the +database transaction (and, by interacting with the cache, outside the +database itself), the database does not have control over this data and +its visibility. + +However, by default, EclipseLink provides a degree of transaction +isolation regardless of what database transaction isolation has been +configured on the underlying database. + +Each unit of work instance operates on its own copy (clone) of +registered objects (see link:#Clones_and_the_Unit_of_Work[Clones and the +Unit of Work]). In this case, because the unit of work provides an API +that allows querying to be done on object changes within a unit of work +(see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Conforming_Queries_and_Descriptors[Using +Conforming Queries and Descriptors]), the unit of work provides read +committed operations. + +Optimistic locking, optimistic read locking, or pessimistic locking can +be used to further manage concurrency (see +link:#Locking_and_the_Unit_of_Work[Locking and the Unit of Work]). + +Changes are committed to the database only when the unit of work +`+commit+` method is called (either directly or by way of an external +transaction controller). + +For detailed information on configuring and using EclipseLink to achieve +a particular level of transaction isolation and transaction isolation +level limitations, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Database_Transaction_Isolation_Levels[Database +Transaction Isolation Levels]. + +== Unit of Work Concepts + +This section introduces transaction concepts unique to EclipseLink, +including the following: + +* link:#Unit_of_Work_Benefits[Unit of Work Benefits] +* link:#Unit_of_Work_Life_Cycle[Unit of Work Life Cycle] +* link:#Unit_of_Work_and_Change_Policy[Unit of Work and Change Policy] +* link:#Clones_and_the_Unit_of_Work[Clones and the Unit of Work] +* link:#Nested_and_Parallel_Units_of_Work[Nested and Parallel Units of +Work] +* link:#Commit_and_Rollback_Transactions[Commit and Rollback +Transactions] +* link:#Primary_Keys[Primary Keys] +* link:#Unit_of_Work_Optimization[Unit of Work Optimization] + +=== Unit of Work Benefits + +The EclipseLink unit of work simplifies transactions and improves +transactional performance. It is the preferred method of writing to a +database in EclipseLink because it performs the following: + +* Sends a minimal amount of SQL to the database during the commit by +updating only the exact changes down to the field level +* Reduces database traffic by isolating transaction operations in their +own memory space +* Optimizes cache coordination, in applications that use multiple +caches, by passing change sets (rather than objects) between caches +* Isolates object modifications in their own transaction space to allow +parallel transactions on the same objects +* Ensures referential integrity and minimizes deadlocks by automatically +maintaining SQL ordering +* Orders database insert, update, and delete operations to maintain +referential integrity for mapped objects +* Resolves bidirectional references automatically +* Frees the application from tracking or recording its changes +* Simplifies persistence with _persistence by reachability_ (see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Associating_a_New_Source_to_an_Existing_Target_Object[Associating +a New Source to an Existing Target Object]) + +=== Unit of Work Life Cycle + +EclipseLink uses the unit of work as follows: + +[arabic] +. The client application acquires a unit of work from a session object. +. The client application queries EclipseLink to obtain a cache object it +wants to modify, and then registers the cache object with the unit of +work. +. The unit of work registers the object according to the object’s change +policy. For more information about how change policy affects +registration, see link:#Unit_of_Work_and_Change_Policy[Unit of Work and +Change Policy]. By default, as each object is registered, the unit of +work accesses the object from the session cache or database and creates +a backup clone and working clone (see +link:#Clones_and_the_Unit_of_Work[Clones and the Unit of Work]). The +unit of work returns the working clone to the client application. If +change tracking is used, the unit of work does not create backup clones +and intercepts the changes through weaving (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Using_Weaving[Optimizing +Using Weaving]). +. The client application modifies the working object returned by the +unit of work. +. The client application (or external transaction controller) commits +the transaction. +. The unit of work calculates the change set for each registered object +according to the object’s change policy. For more information about how +change policy affects change set calculation, see +link:#Unit_of_Work_and_Change_Policy[Unit of Work and Change Policy]. By +default, at commit time, the unit of work compares the working clones to +the backup clones and calculates the change set (that is, determines the +minimum changes required). The comparison is done with a backup clone so +that concurrent changes to the same objects will not result in incorrect +changes being identified. The unit of work then attempts to commit any +new or changed objects to the database. If the commit transaction +succeeds, the unit of work merges changes into the shared session cache. +Otherwise, no changes are made to the objects in the shared cache. For +more details, see link:#Commit_and_Rollback_Transactions[Commit and +Rollback Transactions]. If there are no changes, the unit of work does +not start a new transaction. + +[#Figure 109-1]## *_The Life Cycle of a Unit of Work_* + +.The Life Cycle of a Unit of Work +image::uow.gif[The Life Cycle of a Unit of +Work,title="The Life Cycle of a Unit of Work"] + +The following example shows the default life cycle in code. + +[#Example 109-1]## *_Unit of Work Life Cycle_* + +*`+//\'\' \'\'The\'\' \'\'application\'\' \'\'reads\'\' \'\'a\'\' \'\'set\'\' \'\'of\'\' \'\'objects\'\' \'\'from\'\' \'\'the\'\' \'\'database+`* + +`+List employees = session.readAllObjects(Employee.class);+` + +*`+//\'\' \'\'The\'\' \'\'application\'\' \'\'specifies\'\' \'\'an\'\' \'\'employee\'\' \'\'to\'\' \'\'edit+`* +`+. . .+` `+Employee employee = (Employee) employees.get(index);+` + +`+try {+` +`+    +`*`+//\'\' \'\'Acquire\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work\'\' \'\'from\'\' \'\'the\'\' \'\'session+`* +`+    UnitOfWork uow = session.acquireUnitOfWork();+` +`+    +`*`+//\'\' \'\'Register\'\' \'\'the\'\' \'\'object\'\' \'\'that\'\' \'\'is\'\' \'\'to\'\' \'\'be\'\' \'\'changed.\'\' \'\'Unit\'\' \'\'of\'\' \'\'work\'\' \'\'returns\'\' \'\'a\'\' \'\'clone+`* +`+    +`*`+//\'\' \'\'of\'\' \'\'the\'\' \'\'object\'\' \'\'and\'\' \'\'makes\'\' \'\'a\'\' \'\'backup\'\' \'\'copy\'\' \'\'of\'\' \'\'the\'\' \'\'original\'\' \'\'employee+`* +`+    Employee employeeClone = (Employee)uow.registerObject(employee);+` +`+    +`*`+//\'\' \'\'Make\'\' \'\'changes\'\' \'\'to\'\' \'\'the\'\' \'\'employee\'\' \'\'clone\'\' \'\'by\'\' \'\'adding\'\' \'\'a\'\' \'\'new\'\' \'\'phoneNumber.+`* + +`+    +`*`+//\'\' \'\'If\'\' \'\'a\'\' \'\'new\'\' \'\'object\'\' \'\'is\'\' \'\'referred\'\' \'\'to\'\' \'\'by\'\' \'\'a\'\' \'\'clone,\'\' \'\'it\'\' \'\'does\'\' \'\'not\'\' \'\'have\'\' \'\'to\'\' \'\'be+`* +`+    +`*`+//\'\' \'\'registered.\'\' \'\'Unit\'\' \'\'of\'\' \'\'work\'\' \'\'determines\'\' \'\'it\'\' \'\'is\'\' \'\'a\'\' \'\'new\'\' \'\'object\'\' \'\'at\'\' \'\'commit\'\' \'\'time+`* +`+    PhoneNumber newPhoneNumber = new PhoneNumber("cell","212","765-9002");+` +`+    employeeClone.addPhoneNumber(newPhoneNumber);+` +`+    +`*`+//\'\' \'\'Commit\'\' \'\'the\'\' \'\'transaction:\'\' \'\'unit\'\' \'\'of\'\' \'\'work\'\' \'\'compares\'\' \'\'the\'\' \'\'employeeClone\'\' \'\'with+`* +`+    +`*`+//\'\' \'\'the\'\' \'\'backup\'\' \'\'copy\'\' \'\'of\'\' \'\'the\'\' \'\'employee,\'\' \'\'begins\'\' \'\'a\'\' \'\'transaction,\'\' \'\'and\'\' \'\'updates\'\' \'\'the+`* +`+    +`*`+//\'\' \'\'database\'\' \'\'with\'\' \'\'the\'\' \'\'changes.\'\' \'\'If\'\' \'\'successful,\'\' \'\'the\'\' \'\'transaction\'\' \'\'is\'\' \'\'committed+`* +`+    +`*`+//\'\' \'\'and\'\' \'\'the\'\' \'\'changes\'\' \'\'in\'\' \'\'employeeClone\'\' \'\'are\'\' \'\'merged\'\' \'\'into\'\' \'\'employee.\'\' \'\'If\'\' \'\'there\'\' \'\'is+`* +`+    +`*`+//\'\' \'\'an\'\' \'\'error\'\' \'\'updating\'\' \'\'the\'\' \'\'database,\'\' \'\'the\'\' \'\'transaction\'\' \'\'is\'\' \'\'rolled\'\' \'\'back\'\' \'\'and\'\' \'\'the+`* +`+    +`*`+//\'\' \'\'changes\'\' \'\'are\'\' \'\'not\'\' \'\'merged\'\' \'\'into\'\' \'\'the\'\' \'\'original\'\' \'\'employee\'\' \'\'object+`* +`+    uow.commit();+` `+} +` `+catch (DatabaseException ex) {+` +`+    +`*`+//\'\' \'\'If\'\' \'\'the\'\' \'\'commit\'\' \'\'fails,\'\' \'\'the\'\' \'\'database\'\' \'\'is\'\' \'\'not\'\' \'\'changed.\'\' \'\'The\'\' \'\'unit\'\' \'\'of\'\' \'\'work\'\' \'\'should+`* +`+    +`*`+//\'\' \'\'be\'\' \'\'thrown\'\' \'\'away\'\' \'\'and\'\' \'\'application-specific\'\' \'\'action\'\' \'\'taken+`* +`+}+` +*`+//\'\' \'\'After\'\' \'\'the\'\' \'\'commit,\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work\'\' \'\'is\'\' \'\'no\'\' \'\'longer\'\' \'\'valid.\'\' \'\'Do\'\' \'\'not\'\' \'\'use\'\' \'\'further+`* + +=== Unit of Work and Change Policy + +The unit of work tracks changes for a registered object based on the +change policy you configure for the object’s descriptor. If there are no +changes, the unit of work will not start a database transaction. This +table lists the change policies that EclipseLink provides. + +[#Table 109-2]## *_EclipseLink Change Policies_* + +Change Policy + +Applicable to… + +Deferred Change Detection Policy + +Wide range of object change characteristics.The default change policy. + +Object-Level Change Tracking Policy + +Objects with few attributes or with many attributes and many changed +attributes. + +Attribute Change Tracking Policy + +Objects with many attributes and few changed attributes. + +The most efficient change policy. + +The default change policy for JPA. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[Configuring +Change Policy]. + +==== Deferred Change Detection Policy + +The `+DeferredChangeDetectionPolicy+` is the change policy that all +persistent objects use by default. + +This option provides good unit of work commit performance for a wide +range of object change characteristics. + +When you register in a unit of work an object whose descriptor is +configured with a `+DeferredChangeDetectionPolicy+` (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Deferred_Change_Detection_Policy[Configuring +Deferred Change Detection Policy]), a backup clone is made of the object +(see link:#Clones_and_the_Unit_of_Work[Clones and the Unit of Work]) and +at commit time, the unit of work computes changes by making an +attribute-by-attribute comparison between the backup clone and the +original object. + +This change policy is applicable to all mapping types. + +==== Object-Level Change Tracking Policy + +The `+ObjectChangeTrackingPolicy+` optimizes the unit of work commit +transaction by including objects in the change set calculation only if +at least one attribute has changed. + +This option provides improved unit of work commit performance for +objects with few attributes, or with many attributes and many changed +attributes. + +When you register in a unit of work an object whose descriptor is +configured with `+ObjectChangeTracking+` change policy, a backup clone +is made of the object and at commit time, the unit of work computes +changes by comparing the backup to the current object if and only if at +least one attribute is changed (if the object’s `+hasChanges+` method +returns `+true+`). If a registered object has no changes, the unit of +work does not compare it to the backup clone. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you modify an object’s field through reflection, EclipseLink +will not detect the change. However, if you disable change tracking, +EclipseLink _will_ detect the change. +|=== + +This change policy is applicable to a subset of mapping types (see +link:#Change_Policy_Mapping_Support[Change Policy Mapping Support]). + +For JPA applications, when you configure a descriptor for an entity with +an ObjectChangeTrackingPolicy, EclipseLink code generates a concrete +subclass to implement the EclipseLink ChangeTracker interface at deploy +time (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Object_Change_Tracking_Policy[Configuring +Object Change Tracking Policy]). + +==== Attribute Change Tracking Policy + +The `+AttributeChangeTrackingPolicy+` optimizes the unit of work commit +transaction by tracking all object changes at the attribute level. This +eliminates two unit of work operations: backup clone creation and change +detection through comparison. + +This option provides improved unit of work commit performance for +objects with many attributes, and few changed attributes. Generally, +this is the most efficient change policy. + +This change policy is applicable to a subset of mapping types (see +link:#Change_Policy_Mapping_Support[Change Policy Mapping Support]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use the `+AttributeChangeTrackingPolicy+` if you are +using any instance of `+FieldsLockingPolicy+` (see +link:Introduction%20to%20Descriptors%20(ELUG)#Optimistic_Field_Locking_Policies[Optimistic +Field Locking Policies]). +|=== + +EclipseLink provides different levels of support for this change policy: + +===== Support for JPA Entities + +For JPA entities, you can configure EclipseLink to automatically weave +attribute level change tracking. + +EclipseLink only supports change tracking with lazy collection +relationships, not with eager collection relationship. + +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_Weaving_JPA_Entities[What +You May Need to Know About Weaving JPA Entities]. + +===== Support for Plain Old Java Object (POJO) Classes + +For POJO classes, you can configure EclipseLink to automatically weave +attribute level change tracking. + +EclipseLink can weave both transparent indirect container indirection +(lazy loading) and change tracking for collection mappings. If you +manually configure a collection mapping with non-transparent indirection +(either value holder indirection or proxy indirection), EclipseLink does +not automatically weave change tracking. + +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#What_You_May_Need_to_Know_About_Weaving_and_POJO_Classes[What +You May Need to Know About Weaving and POJO Classes]. + +==== Change Policy Mapping Support + +EclipseLink supports alternative change tracking policies (policies +other than `+DeferredChangeDetectionPolicy+`) for attributes that use +any of the following mapping types: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field_Mapping[Direct-to-Field +Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping] (immutable mappings only) +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-One +Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Variable_One-to-One_Mapping[Variable +One-to-One Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-Many +Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-Many +Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Collection_Mapping[Direct +Collection Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct_Map_Mapping[Direct +Map Mapping] +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate_Object_Mapping[Aggregate +Object Mapping] +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Transformation_Mapping[EIS +Transformation Mapping] (immutable mappings only) + +EclipseLink uses the `+DeferredChangeDetectionPolicy+` (see +link:#Deferred_Change_Detection_Policy[Deferred Change Detection +Policy]) for attributes that use any other type of mapping. + +If a transformation mapping maps a mutable value, EclipseLink must clone +and compare the value in a unit of work (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Configuring +Copy Policy]). + +By default, EclipseLink assumes that all transformation mappings are +mutable. If the mapping maps a simple immutable value, you can improve +unit of work performance by configuring the *IsMutable* option to +`+false+`. + +Mutable basic mappings affect the overhead of change tracking. +EclipseLink can only weave an attribute change tracking policy for +immutable mappings. + +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Mutability[Mutability]. + +=== Clones and the Unit of Work + +When using the `+DefrerredChangeDetectionPolicy+` or the +`+ObjectLevelChangeTrackingPolicy+` (see +link:#Deferred_Change_Detection_Policy[Deferred Change Detection +Policy]), the unit of work maintains the following two copies of the +original objects registered with it: + +* working clones; +* backup clones. + +After you change the working clones and the transaction is committed, +the unit of work compares the working clones to the backup clones, and +writes any changes to the database. The unit of work uses clones to +allow parallel units of work (see +link:#Nested_and_Parallel_Units_of_Work[Nested and Parallel Units of +Work]) to exist, a requirement in multiuser three-tier applications. + +The EclipseLink cloning process is efficient in that it clones only the +mapped attributes of registered objects, and stops at indirection +(lazily loaded) objects unless you trigger the indirection. For more +information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Configuring +Indirection (Lazy Loading)]. + +You can customize the cloning process using the descriptor’s copy +policy. For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Configuring +Copy Policy]. + +You should discontinue the use of the unit of work clones after the +transaction has been committed, as it is beyond the scope of a server +request. If you choose to continue using the clones, be aware that these +objects may include a reference to the unit of work and not let the +garbage collection to proceed until they are released. For more +information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Resuming a Unit +of Work After Commit]. + +=== Nested and Parallel Units of Work + +You can use EclipseLink to create the following: + +* link:#Nested_Unit_of_Work[Nested Unit of Work] +* link:#Parallel_Unit_of_Work[Parallel Unit of Work] + +For additional information and examples on using nested and parallel +units of work, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_a_Nested_or_Parallel_Unit_of_Work[Using +a Nested or Parallel Unit of Work]. + +==== Nested Unit of Work + +You can nest a unit of work (the _child_) within another unit of work +(the _parent_). A nested unit of work does not commit changes to the +database. Instead, it passes its changes to the parent unit of work, and +the parent attempts to commit the changes at commit time. Nesting units +of work lets you break a large transaction into smaller isolated +transactions, and ensures that: + +* Changes from each nested unit of work commit or fail as a group. +* Failure of a nested unit of work does not affect the commit or +rollback transaction of other operations in the parent unit of work. +* Changes are presented to the database as a single transaction. + +==== Parallel Unit of Work + +You can modify the same objects in multiple unit of work instances in +parallel because the unit of work manipulates copies of objects. +EclipseLink resolves any concurrency issues when the Units of Work +commits the changes. + +=== Commit and Rollback Transactions + +When a unit of work transaction is committed, it either succeeds, or +fails and rolls back. A commit transaction can be initiated by your +application or by a Java EE container. + +==== Commit Transactions + +At commit time, the unit of work compares the working clones and backup +clones to calculate the change set (that is, to determine the minimum +changes required). Changes include updates to or deletion of existing +objects, and the creation of new objects. The unit of work then begins a +database transaction, and attempts to write the changes to the database. +If all changes commit successfully on the database, the unit of work +merges the changed objects into the session cache. If any one of the +changes fail on the database, the unit of work rolls back any changes on +the database, and does not merge changes into the session cache. + +The unit of work calculates commit order using foreign key information +from one-to-one and one-to-many mappings. If you encounter constraint +problems during a commit transaction, verify your mapping definitions. +The order in which you register objects with the `+registerObject+` +method does not affect the commit order. + +===== Commit and JTA + +When your application uses JTA, the unit of work commit transaction acts +differently than in a non-JTA application. In most cases, the unit of +work attaches itself to an external transaction. If no transaction +exists, the unit of work creates a transaction. This distinction affects +commit activity as follows: + +* _If the unit of work attaches to an existing transaction_, the unit of +work ignores the `+commit+` call. The transaction commits the unit of +work when the entire external transaction is complete. +* _If the unit of work starts the external transaction_, the transaction +treats the unit of work `+commit+` call as a request to commit the +external transaction. The external transaction then calls its own commit +code on the database. + +In either case, only the external transaction can call `+commit+` on the +database because it owns the database connection. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +==== Rollback Transactions + +A unit of work commit transaction must succeed or fail as a unit. +Failure in writing changes to the database causes the unit of work to +roll back the database to its previous state. Nothing changes in the +database, and the unit of work does not merge changes into the session +cache. + +===== Rollback and JTA + +In a JTA environment, the unit of work does not own the database +connection. In this case, the unit of work sends the rollback call to +the external transaction rather than the database, and the external +transaction treats the rollback call as a request to roll the +transaction back. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating_the_Unit_of_Work_with_an_External_Transaction_Service[Integrating +the Unit of Work with an External Transaction Service]. + +=== Primary Keys + +You cannot modify the primary key attribute of an object in a unit of +work. This is an unsupported operation and doing so will result in +unexpected behavior (exceptions or database corruption). + +To replace one instance of an object with unique constraints with +another, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_the_setShouldPerformDeletesFirst_Method_of_the_Unit_of_Work[How +to Use the setShouldPerformDeletesFirst Method of the Unit of Work]. + +=== Unit of Work Optimization + +By default, the unit of work performs change set calculation efficiently +for a wide range of object change characteristics. However, there are +various ways you can use the unit of work to enhance application +performance. + +One way to improve performance is to consider using an alternative +change policy (see link:#Unit_of_Work_and_Change_Policy[Unit of Work and +Change Policy]). + +For more performance options, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_the_Unit_of_Work[Optimizing +the Unit of Work]. + +== Unit of Work API + +You do not instantiate an instance of +`+org.eclipse.persistence.sessions.UnitOfWork+`. Rather, you acquire a +unit of work from an instance of +`+org.eclipse.persistence.sessions.Session+` or from another unit of +work. + +For more information on creating sessions, see +link:Creating%20a%20Session%20(ELUG)#Creating_a_Session[Creating a +Session]. + +For more information on acquiring a unit of work, see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Acquiring_a_Unit_of_Work[Acquiring +a Unit of Work]. + +For more information on using the basic API of the unit of work, see +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)[Using Basic Unit of +Work API]. + +For more information on using the advanced API of the unit of work, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Using Advanced +Unit of Work API]. + +=== Unit of Work as Session + +The unit of work extends the interface +`+org.eclipse.persistence.sessions.Session+`, and implements all the +usual session API. When using session API from a unit of work, you +should consider the following: + +* link:#Reading_and_Querying_Objects_with_the_Unit_of_Work[Reading and +Querying Objects with the Unit of Work] +* link:#Locking_and_the_Unit_of_Work[Locking and the Unit of Work] + +==== Reading and Querying Objects with the Unit of Work + +A unit of work offers the same set of database access methods as a +regular session. + +When called from a unit of work, these methods access the objects in the +unit of work, register the selected objects automatically, and return +clones. + +Although this makes it unnecessary for you to call the +`+registerObject+` and `+registerAllObjects+` methods, be aware of the +restrictions on registering objects described in +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Creating_an_Object[Creating +an Object] and +link:Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Associating_a_New_Source_to_an_Existing_Target_Object[Associating +a New Source to an Existing Target Object]. + +===== Reading Objects with the Unit of Work + +As with regular sessions, you use the `+readObject+` and +`+readAllObjects+` methods to read objects from the database. + +===== Querying Objects with the Unit of Work + +You can execute queries in a unit of work with the `+executeQuery+` +method. + +[width="100%",cols="<100%",] +|=== +|*Note*: Because a unit of work manages changes to existing objects and +the creation of new objects, modifying queries such as +`+InsertObjectQuery+` or `+UpdateObjectQuery+` are not necessary and +therefore are not supported by the unit of work. +|=== + +==== Locking and the Unit of Work + +For information on locking API generic to all sessions, see the +following: + +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Locking[Locking] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy] + +For information on locking API specific to a unit of work, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Optimistic_Read_Locking_with_the_forceUpdateToVersionField_Method[Using +Optimistic Read Locking with the forceUpdateToVersionField Method]. + +== Example Model Object and Schema + +Throughout the chapters in this part, the following object model and +schema are used in the examples provided. The example object model +appears in the link:#Figure_109-2[Example Object Model] figure, and the +example entity-relationship (data model) diagram appears in the +link:#Figure_109-3[Example Data Model] figure. + +[#Figure 109-2]## *_Example Object Model_* + +.Example Object Model +image::xobjmod.gif[Example Object Model,title="Example Object Model"] + +[#Figure 109-3]## *_Example Data Model_* + +.Example Data Model +image::xdatmod.gif[Example Data Model,title="Example Data Model"] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Java_Persistence_API_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Java_Persistence_API_(ELUG).adoc new file mode 100644 index 00000000000..d636ed6cc87 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Java_Persistence_API_(ELUG).adoc @@ -0,0 +1,347 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_Java_Persistence_API_(ELUG)[Related +Topics] + +This section introduces concepts of Java Persistence API and provides +general information on it. + +== What Is Java Persistence API? + +The Java Persistence API (JPA) is a lightweight framework for Java +persistence (see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Persisting_Objects[Persisting +Objects]) based on Plain Old Java Object (POJO). JPA is a part of EJB +3.0 and 3.1 specifications. JPA provides an object relational mapping +approach that lets you declaratively define how to map Java objects to +relational database tables in a standard, portable way. You can use this +API to create, remove and query across lightweight Java objects within +both an EJB 3.0/3.1-compliant container and a standard Java SE 5/6 +environment. + +For more information, see the following: + +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Considering_JPA_Entity_Architecture[Considering +JPA Entity Architecture] +* http://jcp.org/en/jsr/detail?id=220[JSR 220 EJB 3.0 with JPA 1.0 +specifications] +* http://jcp.org/en/jsr/detail?id=317[JSR 317 EJB 3.1 with JPA 2.0 +specifications] + +== What Do You Need to Develop with JPA + +To start developing with JPA, you need the following: + +* link:#Relational_Database[Relational Database] +* link:#Domain_Model_Classes[Domain Model Classes] +* link:#persistence.xml_File[persistence.xml File] +* link:#Object_Relational_Mapping_Metadata[Object Relational Mapping +Metadata] +* link:#Persistence_Provider[Persistence Provider] +* link:#Persistence_Application_Code[Persistence Application Code] + +=== Relational Database + +To develop your applications with JPA, you can use any relational +database. + +=== Domain Model Classes + +Your domain model should consist of classes representing +entities–lightweight persistent domain objects. The easiest way to +define an entity class is by using the `+@Entity+` annotation (see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Using_Metadata_Annotations[Using +Metadata Annotations]), as the following example shows: + +[source,java] +---- + @Entity + public class Employee implements Serializable { + private static final long serialVersionUID = -8865917134914502125L; + ... + } +---- + +For more information on entities, see the following: + +* Section 2.1 "`Requirements on the Entity Class`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 8.1 "`Entity`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Considering_JPA_Entity_Architecture[Considering +JPA Entity Architecture] +* link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Configuring_an_Entity[Configuring +an Entity] + +=== persistence.xml File + +Use the `+persistence.xml+` file to package your entities. + +For more information and examples, see the following: + +* Section 6.2.1 "`persistence.xml file`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using_EclipseLink_JPA_Extensions_(ELUG)#What_You_May_Need_to_Know_About_Using_EclipseLink_JPA_Persistence_Unit_Properties[What +You May Need to Know About Using EclipseLink JPA Persistence Unit +Properties] + +=== Object Relational Mapping Metadata + +Object relational mapping metadata specifies the mapping of your domain +model classes to the database. + +You can express this metadata in the form of annotations and/or XML. + +==== Metadata Annotations and ORM.xml File + +A metadata annotation represents a Java language feature that lets you +attach structured and typed metadata to the source code. Annotations +alone are sufficient for the metadata specification–you do not need to +use XML. Annotations for object relational mapping are in the +`+javax.persistence+` package. For more information and examples, see +Chapter 8 "`Metadata Annotations`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] + +An object relational mapping XML file is optional. If you choose to +provide one, then it should contain mapping information for the classes +listed in it. The persistence provider loads an `+orm.xml+` file (or +other mapping file) as a resource. If you provide a mapping file, the +classes and mapping information specified in the mapping file will be +used. For more information and examples, see the following: + +* link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Using_XML[Using +XML] +* Section 6.2.1.6 "`mapping-file, jar-file, class, +exclude-unlisted-classes`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] + +==== Overriding Annotations with XML + +XML mapping metadata may combine with and override annotation metadata. +For more information and examples, see the following: + +* Section 10.1 "`XML Overriding Rules`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Overriding_Annotations_with_XML[Overriding +Annotations with XML] + +===== Advantages and Disadvantages of Using Annotations + +Metadata annotations are relatively simple to use and understand. They +provide in-line metadata located with the code that this metadata is +describing–you do not need to replicate the source code context of where +the metadata applies. + +On the other hand, annotations unnecessarily couple the metadata to the +code. Thus, changes to metadata require changing the source code. + +===== Advantages and Disadvantages of Using XML + +The following are advantages of using XML: + +* no coupling between the metadata and the source code; +* compliance with the existing, pre-EJB 3.0 development process; +* support in IDEs and source control systems; + +The main disadvantages of mapping with XML are the complexity and the +need for replication of the code context. + +=== Persistence Provider + +The persistence provider supplies the implementation of the JPA +specification. + +The persistence provider handles the object relational mapping of the +relationships, including their loading and storing to the database (as +specified in the metadata of the entity class), and the referential +integrity of the relationships (as specified in the database). + +For example, the EclipseLink persistence provider ensures that +relational descriptors are created for annotated objects, as well as +mappings are created based on annotations. + +=== Persistence Application Code + +To manage entities (see link:#Domain_Model_Classes[Domain Model +Classes]) in your persistence application, you need to obtain an entity +manager from an `+EntityManagerFactory+`. How you get the entity manager +and its factory largely depends on the Java environment in which you are +developing your application. + +==== Container-Managed Entity Manager + +In the Java EE environment, you acquire an entity manager by injecting +it using the `+@PersistenceContext+` annotation (dependency injection), +as the link:#Example_17-1[Obtaining an Entity Manager Through Dependency +Injection] example shows, or using a direct lookup of the entity manager +in the JNDI namespace, as the link:#Example_17-2[Performing JNDI Lookup +of an Entity Manager] example shows. + +===== Example 17-1 + +[#'Example 17-1]## *_Obtaining an Entity Manager Through Dependency +Injection_* + +[source,java] +---- + @PersistenceContext + public EntityManager em; +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You can only use the `+@PersistenceContext+` annotation +injection on session beans, servlets and JSP. +|=== + +===== Example 17-2 + +[#Example 17-2]## *_Performing JNDI Lookup of an Entity Manager_* + +[source,java] +---- + @Stateless + @PersistenceContext(name="ProjectEM", unitName="Project") + public class ProjectSessionBean implements Project { + @Resource + SessionContext ctx; + + public void makeCurrent() { + try { + EntityManager em = (EntityManager)ctx.lookup("ProjectEM"); + ... + } + } +---- + +See the following +http://dev.eclipse.org/mhonarc/lists/eclipselink-users/msg04632.html[EclipseLink +post] for concurrency issues when using an EntityManager directly on a +servlet outside of a function local variable instead of a Statelss +session bean. + +The container would manage the life cycle of this entity manager–your +application does not have to create it or close it. + +For more information and examples, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 3.1 "`EntityManager`" +* Section 5.2.1 "`Obtaining an Entity Manager in the Java EE +Environment`" +* Section 5.3.1 "`Obtaining an Entity Manager Factory in a Java EE +Container`" + +==== Application-Managed Entity Manager + +In the Java SE environment, not the container but the application +manages the life cycle of an entity manager. You would create this +entity manager using the `+EntityManagerFactory+`’s method +`+createEntityManager+`. You have to use the +`+javax.persistence.Persistence+` class to bootstrap an +`+EntityManagerFactory+` instance, as this example shows: + +[#Example 17-3]## *_Application-Managed Entity Manager in the Java SE +Environment_* + +[source,java] +---- + public class Employee { + + public static void main(String[] args) { + EntityManagerFactory emf = + Persistence.createEntityManagerFactory("EmpService"); + EntityManager em = emf.createEntityManager(); + ... + em.close(); + emf.close(); + } +---- + +Notice that you need to explicitly close the entity manager and the +factory. + +In the Java EE environment, you can use the application-managed entity +managers as well. You would create it using the `+@PersistenceUnit+` +annotation to declare a reference to the `+EntityManagerFactory+` for a +persistence unit, as the following example shows: + +[source,java] +---- + @PersistenceUnit + EntityManagerFactory emf; +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You can only use the `+@PersistenceContext+` annotation +injection on session beans, servlets and JSP. +|=== + +For more information and examples, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 5.2.2 "`Obtaining an Application-managed Entity Manager`" +* Section 5.3.2 "`Obtaining an Entity Manager Factory in a Java SE +Environment`" + +==== Transaction Management + +Transactions define when new, changed or removed entities are +synchronized to the database. + +JPA supports the following two types of transaction management: + +* link:#JTA_Transaction_Management[JTA Transaction Management] +* link:#Resource-Local_Transactions[Resource-Local Transactions] + +Container-managed entity managers always use JTA transactions. +Application-managed entity managers may use JTA or resource-local +transactions. The default transaction type for Java EE application is +JTA. + +You define the transaction type for a persistence unit and configure it +using the `+persistence.xml+` file (see +link:#persistence.xml_File[persistence.xml File]). + +For more information, see Section 5.5 "`Controlling Transactions`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +===== JTA Transaction Management + +JTA transactions are the transactions of the Java EE server. + +As section 5.5.1 "`JTA Entity Managers`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] defines, "`An +entity manager whose transactions are controlled through JTA is a JTA +entity manager. A JTA entity manager participates in the current JTA +transaction, which is begun and committed external to the entity manager +and propagated to the underlying resource manager.`" + +===== Resource-Local Transactions + +Resource-local transactions are the native transactions of the JDBC +drivers that are referenced by a persistence unit. Your application +explicitly controls these transactions. Your application interacts with +the resource-local transactions by acquiring an implementation of the +`+EntityTransaction+` interface from the entity manager. + +For more information and examples, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +* Section 5.5.2 "`Resource-local Entity Managers`" +* Section 5.5.2.1 "`The EntityTransaction Interface`" + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_JPA[Category: JPA] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..3d713e4bb40 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Mappings_(ELUG).adoc @@ -0,0 +1,1494 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_Mappings_(ELUG)[Related +Topics] + +EclipseLink can transform data between an object representation and a +representation specific to a data source. This transformation is called +mapping and it is the core of an EclipseLink project. + +A mapping corresponds to a single data member of a domain object. It +associates the object data member with its data source representation +and defines the means of performing the two-way conversion between +object and data source. + +== Mapping Types + +This table describes the mapping types that EclipseLink supports. + +[#Table 16-1]## + +Type + +Description + +EclipseLink Workbench + +Java + +Relational + +Mappings that transform any object data member type to a corresponding +relational database (SQL) data source representation in any supported +relational database. Relational mappings allow you to map an object +model into a relational data model. + +Object-relational data type + +Mappings that transform certain object data member types to structured +data source representations optimized for storage in specialized +object-relational data type databases such as Oracle Database. +Object-relational data type mappings let you map an object model into an +object-relational data type data model. + +EIS + +Mappings that transform object data members to the EIS record format +defined by the object’s descriptor. + +XML + +Mappings that transform object data members to the XML elements of an +XML document whose structure is defined by an XML schema document (XSD). + +For more information, see the following: + +* link:Creating%20a%20Mapping%20(ELUG)#CBBHHHJC[Creating a Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)#CEGFEFJG[Configuring a +Mapping] + +== Mapping Concepts + +This section describes concepts unique to EclipseLink mappings, +including the following: + +* link:#Mapping_Architecture[Mapping Architecture] (applicable to +relational and nonrelational mappings) +* link:#Example_Mapping[Example Mapping] (applicable to relational and +nonrelational mappings) +* link:#Automatic_Mappings[Automatic Mappings] +** link:#JPA_Automapping[JPA Automapping] (applicable to relational +mappings) +** link:#Automapping_with_Workbench_at_Development_Time[Automapping with +Workbench at Development Time] (applicable to relational and +nonrelational mappings) +** link:#JAXB_Project_Generation_at_Development_Time[JAXB Project +Generation at Development Time] (applicable to XML mappings) +* link:#Indirection_(Lazy_Loading)[Indirection (Lazy Loading)] +(applicable to relational mappings) +** link:#Value_Holder_Indirection[Value Holder Indirection] +** link:#Transparent_Indirect_Container_Indirection[Transparent Indirect +Container Indirection] +** link:#Proxy_Indirection[Proxy Indirection] +** link:#Weaved_IndirectionW[eaved Indirection] +** link:#Indirection_and_JPA[Indirection and JPA] +** link:#Indirection,_Serialization,_and_Detachment[Indirection, +Serialization, and Detachment] +* link:#Method_Accessors_and_Attribute_Accessors[Method Accessors and +Attribute Accessors] (applicable to relational and nonrelational +mappings) +* link:#Mapping_Converters_and_Transformers[Mapping Converters and +Transformers] +** link:#Serialized_Object_Converter[Serialized Object Converter] +(applicable to relational and nonrelational mappings) +** link:#Type_Conversion_Converter[Type Conversion Converter] +(applicable to relational and nonrelational mappings) +** link:#Object_Type_Converter[Object Type Converter] (applicable to XML +mappings) +** link:#Simple_Type_Translator[Simple Type Translator] (applicable to +XML mappings) +** link:#Transformation_Mappings[Transformation Mappings] (applicable to +relational and nonrelational mappings) +* link:#Mappings_and_XPath[Mappings and XPath] (applicable to XML +mappings) +* #Mappings_and_xsd:list_and_xsd:union_Types[Mappings and xsd:list and +xsd:union Types] (applicable to XML mappings) +* #Mappings_and_the_jaxb:class_Customization[Mappings and the jaxb:class +Customization] (applicable to XML mappings) +* link:#Mappings_and_JAXB_Typesafe_Enumerations[Mappings and JAXB +Typesafe Enumerations] (applicable to XML mappings) + +=== Mapping Architecture + +To define a mapping, you draw upon the following components: + +* The data representation specific to the data source (such as a +relational database table or schema-defined XML element) in which you +store the object’s data. +* A descriptor for a particular object class. +* An object class to map. + +[width="100%",cols="<100%",] +|=== +|*Note:* A mapping is the same regardless of whether your project is +persistent or nonpersistent. +|=== + +For an example of a typical EclipseLink mapping, see +link:#Example_Mapping[Example Mapping]. + +The type of data source you define in your EclipseLink project +determines the type of mappings you can use and how you configure them. +In a persistent project, you use mappings to persist to a data source. +In a nonpersistent project, you use mappings simply to transform between +the object format and some other data representation (such as XML). For +more information about data source and project types, see +link:Introduction%20to%20Projects_(ELUG)[EclipseLink Project Types]. + +A descriptor represents a particular domain object: it describes the +object’s class. It owns mappings: one mapping for each of the class data +members that you intend to persist or transform in memory. + +[cols="<",] +|=== +|*Note:* Persistence is applicable at the descriptor level. +|=== + +For more information about descriptors, see +link:Introduction%20to%20Descriptors%20(ELUG)#CHECEAAE[Introduction to +Descriptors]. + +EclipseLink provides mappings to handle a wide variety of data types and +data representations. For more information, see +link:#Mapping_Types[Mapping Types]. + +All mappings are subclasses of the +`+org.eclipse.persistence.mappings.DatabaseMapping+` class. For more +information about the mapping API, see link:#Mapping_API[Mapping API]. + +=== Example Mapping + +Although EclipseLink supports more complex mappings, most EclipseLink +classes map to a single database table or XML element that defines the +type of information available in the class. Each object instance of a +given class maps to a single row comprising the object’s attributes, +plus an identifier (the primary key) that uniquely identifies the +object. + +The link:#Figure_16-1[How Classes and Objects Map to a Database Table] +figure illustrates the simplest database mapping case in which: + +* *Table_X* in the database represents *Class_X*. +* *Object_X1* and *Object_X2* are instances of *Class_X*. +* Individual rows in *Table_X* represent *Object_X1* and *Object_X2*, as +well as any other instances of *Class_X*. + +[#Figure 16-1]## *_How Classes and Objects Map to a Database Table_* + +.How Classes and Objects Map to a Database Table +image::example_map1.gif[How Classes and Objects Map to a Database +Table,title="How Classes and Objects Map to a Database Table"] + +EclipseLink provides you with the tools to build these mappings, from +the simple mappings illustrated in the link:#Figure_16-1[How Classes and +Objects Map to a Database Tabl] figure, to complex mappings. + +For an additional example of a relational mapping, see the +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure_31-1[Direct-to-Field +Mapping] figure. + +For an example of a nonrelational mapping, see the +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Figure_58-34[XML +Transformation Mappings] figure. + +=== Automatic Mappings + +Typically, you use the Workbench to define mappings on a class-by-class +and data member-by-data-member basis manually (see +link:Creating%20a%20Mapping%20(ELUG)#Creating_Mappings_Manually_During_Development[Creating +Mappings Manually During Development]). + +Alternatively, you can take advantage of the following: + +* link:#JPA_Automapping[JPA Automapping] +* link:#Automapping_with_Workbench_at_Development_Time[Automapping with +Workbench at Development Time] +* link:#JAXB_Project_Generation_at_Development_Time[JAXB Project +Generation at Development Time] + +==== JPA Automapping + +To configure automapping in a JPA project, you just need to annotate +your persistence classes with `+@Entity+` and define their primary key +with `+@Id+` (or define the list of entities and their primary key +fields in your `+orm.xml+`) and the EclipseLink JPA persistence provider +will automatically map all unmapped properties. You can also configure +`+persistence.xml+` properties to automatically create or replace the +corresponding database tables. For more information, see +link:Introduction_to_EclipseLink_JPA_(ELUG)[EclipseLink JPA Overview]. + +==== Automapping with Workbench at Development Time + +You can use Workbench *Automap* feature to automatically define default +mappings for every class and data member in your project (see +link:Creating%20a%20Mapping%20(ELUG)#Creating_Mappings_Automatically_During_Development[Creating +Mappings Automatically During Development]). + +Workbench automapping is available for all project types and assumes +that both the object model and database schema are already defined. + +==== JAXB Project Generation at Development Time + +JAXB provides an API and a tool that allow automatic two-way mapping +between XML documents and Java objects. The JAXB compiler generates all +the Java classes and mappings based on the provided Document Type +Definition (DTD) and a schema definition. + +For more information on JAXB, see _Architecture for XML Binding (JAXB): +A Primer_ at +http://java.sun.com/developer/technicalArticles/xml/jaxb/indexl[`+http://java.sun.com/developer/technicalArticles/xml/jaxb/indexl+`] + +For more information on XML mappings, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Introduction_to_XML_Mappings[Introduction +to XML Mappings]. + +=== Indirection (Lazy Loading) + +By default, when EclipseLink retrieves a persistent object, it retrieves +all of the dependent objects to which it refers. When you configure +indirection (also known as lazy reading, lazy loading, and just-in-time +reading) for an attribute mapped with a relationship mapping, +EclipseLink uses an indirection object as a place holder for the +referenced object: EclipseLink defers reading the dependent object until +you access that specific attribute. This can result in a significant +performance improvement, especially if the application is interested +only in the contents of the retrieved object, rather than the objects to +which it is related. + +We strongly recommend using indirection for all relationship mappings. +Not only does this lets you optimize data source access, but it also +allows EclipseLink to optimize the unit of work processing, cache +access, and concurrency. + +[width="100%",cols="<100%",] +|=== +|*Note:* The use of indirection is especially important for providing a +proper maintenance of bidirectional relationships. In this case, you +must use indirection. If you are operating with collections, you must +use transparent indirection (see +link:#Transparent_Indirect_Container_Indirection[Transparent Indirect +Container Indirection]). +|=== + +The link:#Figure_16-2[EclipseLink Indirection] figure shows an +indirection example. Without indirection, reading the `+Order+` object +also reads the dependent collection of `+LineItem+` objects. With +indirection, reading the `+Order+` object does not read the dependent +collection of `+LineItem+` objects: the `+lineItems+` attribute refers +to an indirection object. You can access other attributes (such as +`+customerId+`), but EclipseLink reads the dependent `+LineItem+` +objects only if and when you access the `+lineItems+` attribute. + +[#Figure 16-2]## *_EclipseLink Indirection_* + +.EclipseLink Indirection +image::indirctn.gif[EclipseLink +Indirection,title="EclipseLink Indirection"] + +EclipseLink supports the following types of indirection: + +* link:#Value_Holder_Indirection[Value Holder Indirection] +* link:#Transparent_Indirect_Container_Indirection[Transparent Indirect +Container Indirection] +* link:#Proxy_Indirection[Proxy Indirection] + +When using indirection with an object that your application serializes, +you must consider the effect of any untriggered indirection objects at +deserialization time (see +link:#Indirection,_Serialization,_and_Detachment[Indirection, +Serialization, and Detachment]). + +For information on configuring indirection, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Configuring +Indirection (Lazy Loading)]. + +==== Value Holder Indirection + +Persistent classes that use indirection must replace relationship +attributes with value holder attributes. A value holder is an instance +of a class that implements the `+ValueHolderInterface+` interface, such +as `+ValueHolder+`. This object stores the information necessary to +retrieve the object it is replacing from the database. If the +application does not access the value holder, the replaced object is +never read from the database. + +To obtain the object that the value holder replaces, use the +`+getValue+` and `+setValue+` methods of the `+ValueHolderInterface+`. A +convenient way of using these methods is to hide the `+getValue+` and +`+setValue+` methods of the `+ValueHolderInterface+` inside `+get+` and +`+set+` methods, as shown in the following illustrations. + +The link:#Figure_16-3[Address Object Not Read] figure shows the +`+Employee+` object being read from the database. The `+Address+` object +is not read and will not be created unless it is accessed. + +[#Figure 16-3]## *_Address Object Not Read_* + +.Address Object Not Read +image::vhstep1.gif[Address Object Not +Read,title="Address Object Not Read"] + +The first time the address is accessed, as in the +link:#Figure_16-4[Initial Request] figure, the `+ValueHolder+` reads and +returns the `+Address+` object. + +[#Figure 16-4]## *_Initial Request_* + +.Initial Request +image::vhstep2.gif[Initial Request,title="Initial Request"] + +Subsequent requests for the address do not access the database, as shown +in the link:#Figure_16-5[Subsequent Requests] figure. + +[#Figure 16-5]## *_Subsequent Requests_* + +.Subsequent Requests +image::vhstep3.gif[Subsequent Requests,title="Subsequent Requests"] + +If you are using method access ( +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]), the get and set +methods specified in the mapping must access the instance of +`+ValueHolderInterface+`, rather than the object referenced by the value +holder. The application should not use these getter and setter, but use +the getter and setter that hide the usage of value holders. For more +information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_ValueHolder_Indirection_With_Method_Accessing[Configuring +ValueHolder Indirection With Method Accessing]. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many or many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading nor value holder indirection). + +==== Transparent Indirect Container Indirection + +Transparent indirect container (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy]) indirection lets you declare any relationship +attribute of a persistent class that holds a collection of related +objects as any of the following: + +* `+java.util.Collection+` +* `+java.util.Hastable+` +* `+java.util.List+` +* `+java.util.Map+` +* `+java.util.Set+` +* `+java.util.Vector+` + +EclipseLink will use an indirection object that implements the +appropriate interface and also performs just-in-time reading of the +related objects. When using transparent indirection, you do not have to +declare the attributes as `+ValueHolderInterface+`. + +Newly created collection mappings use transparent indirection by default +if their attribute _is not_ a `+ValueHolderInterface+`. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many or many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading nor value holder indirection). + +You can configure EclipseLink to automatically weave transparent +indirect container indirection for JPA entities and Plain Old Java +Object (POJO) classes. For more information, see the following: + +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Weaving[Using +EclipseLink JPA Weaving] + +==== Proxy Indirection + +Introduced in JDK 1.3, the Java class `+Proxy+` lets you use dynamic +proxy objects as place-holders for a defined interface. Certain +EclipseLink mappings (see the +link:Configuring%20a%20Mapping%20(ELUG)#Table_117-4[Mapping Support for +Indirection] table) can be configured to use proxy indirection, which +gives you the benefits of EclipseLink indirection without the need to +include EclipseLink classes in your domain model. Proxy indirection is +to one-to-one relationship mappings as indirect containers are to +collection mappings. + +To use proxy indirection, your domain model must satisfy all of the +following criteria: + +* The target class of the one-to-one relationship must implement a +public interface. +* The one-to-one attribute on the source class must be of the +`+interface+` type. +* If you employ method accessing ( +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]), then the getter +and setter methods must use the interface. + +Before using proxy indirection, be aware of the restrictions it places +on how you use the unit of work (see +link:#Proxy_Indirection_Restrictions[Proxy Indirection Restrictions]). + +To configure proxy indirection, you can use the Workbench (see +link:Configuring%20a%20Mapping%20(ELUG)#How_to_Configure_Indirection_Using_Workbench[How +to Configure Indirection Using Workbench]) or Java in an amendment +method (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Proxy_Indirection[Configuring +Proxy Indirection]). + +===== Proxy Indirection Restrictions + +Proxy objects in Java are only able to intercept messages sent. If a +primitive operation such as `+==+`, `+instanceof+`, or `+getClass+` is +used on a proxy, it will not be intercepted. This limitation can require +the application to be somewhat aware of the usage of proxy objects. + +You cannot register the target of a proxy indirection implementation +with a unit of work. Instead, first register the source object with the +unit of work. This lets you retrieve a target object clone with a call +to a getter on the source object clone. + +For example: + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Employee emp = (Employee)session.readObject(Employee.class);+` `+ +` +*`+//\'\' \'\'Register\'\' \'\'the\'\' \'\'source\'\' \'\'object+`* +`+Employee empClone = (Employee)uow.registerObject(emp); +` `+ +` +*`+//\'\' \'\'All\'\' \'\'of\'\' \'\'source\'\' \'\'object's\'\' \'\'relationships\'\' \'\'are\'\' \'\'cloned\'\' \'\'when\'\' \'\'source\'\' \'\'object\'\' \'\'is\'\' \'\'cloned+`* +`+Address addressClone = empClone.getAddress();+` +`+addressClone.setCity("Toronto"); +` + +For more information about clones and the unit of work, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#CIHEGFDA[Introduction +to EclipseLink Transactions]. + +==== Weaved Indirection + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many or many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading nor value holder indirection). + +For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving]. + +==== Indirection and JPA + +When you set mapping annotation attribute `+fetch+` to `+lazy+`, the +EclipseLink JPA persistence provider uses indirection. + +By default, one-to-many and many-to-many relationships are lazy and use +transparent indirection, while one-to-one and many-to-one relationships +are not lazy. + +If you set one-to-one or many-to-one relationships to lazy, and you +enable weaving, the EclipseLink JPA persistence provider will use +weaving to enable value holder indirection for these relationships. + +For more information, see the following: + +* link:#Weaved_Indirection[Weaved Indirection] +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] + +==== Indirection, Serialization, and Detachment + +When using indirection (lazy loading), it is likely that a graph of +persistent objects will contain untriggered indirection objects. Because +indirection objects are transient and do not survive serialization +between one JVM and another, untriggered indirection objects will +trigger an error if the relationship is accessed after deserialization. + +The application must ensure that any indirect relationships that will be +required after deserialization have been instantiated before +serialization. This can be done through accessing the get method for any +relationship using `+ValueHolder+` or weaved indirection, and by sending +the `+size()+` method to any relationship using transparent indirection. +If the application desired the relationships to be always instantiated +on serialization, the serialization `+writeObject()+` method could be +overwritten in the persistent class to first instantiate the desired +relationships. Caution should be used for objects with many or deep +relationships to avoid serializing large object graphs: ideally, only +the relationships required by the client should be instantiated. + +When serializing JPA entities, any lazy relationships that have not been +instantiated prior to serialization will trigger errors if they are +accessed. If weaving is used on the server, and the entities are +serialized to a client, the same weaved classes must exist on the +client, either through static weaving of the jar, or through launching +the client JVM using EclipseLink. + +For more information, see the following: + +* link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Using_Weaving[Using +Weaving] +* link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Merging_Changes_in_Working_Copy_Clones[Merging +Changes in Working Copy Clones] + +=== Method Accessors and Attribute Accessors + +By default, EclipseLink uses direct access to access public attributes. +Using EclipseLink, you can configure field access at the project level +(see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Configuring +Method or Direct Field Access at the Project Level]) and at the mapping +level +(link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]). + +=== Mapping Converters and Transformers + +If existing EclipseLink mappings do not meet your needs, you can create +custom mappings using mapping extensions. These extensions include the +following: + +* link:#Serialized_Object_Converter[Serialized Object Converter] +* link:#Type_Conversion_Converter[Type Conversion Converter] +* link:#Object_Type_Converter[Object Type Converter] +* link:#Simple_Type_Translator[Simple Type Translator] +* link:#Transformation_Mappings[Transformation Mappings] + +[width="100%",cols="<100%",] +|=== +|*Note:* You can use the mapping converters and transformers regardless +of whether your data source is relational or nonrelational. +|=== + +==== Serialized Object Converter + +The serialized object converter is an extension of direct and direct +collection mappings that lets you map complex objects into binary fields +through Java object serialization. Serialized objects are normally +stored in `+RAW+` or Binary Large Object (`+BLOB)+` fields in the +database, or `+HEX+` or `+BASE64+` elements in an XML document. + +The link:#Figure_16-6[Serialized Object Converter] figure shows an +example of a direct-to-field mappings that uses a serialized object +converter. The attribute `+jobDescription+` contains a formatted text +document that is stored in the JOB_DESC field of the database. + +[#Figure 16-6]## *_Serialized Object Converter (relational)_* + +.Serialized Object Converter (relational) +image::serobjfg.gif[Serialized Object Converter +(relational),title="Serialized Object Converter (relational)"] + +The link:#Figure_16-7[Serialized Object Converter (nonrelational)] +figure demonstrates an example of a nonrelational mapping that uses a +serialized object converter. The attribute `+jobDescription+` contains a +formatted text document that EclipseLink stores in the +`+JOB DESCRIPTION+` element of an XML schema. + +[#Figure 16-7]## *_Serialized Object Converter (nonrelational)_* + +.Serialized Object Converter (nonrelational) +image::serobjxml.gif[Serialized Object Converter +(nonrelational),title="Serialized Object Converter (nonrelational)"] + +The serialized object converter relies on the Java serializer. Before +you map a domain object with the serialized object converter, ensure +that the domain object implements the `+java.io.Serializable+` interface +(or inherits that implementation) and marks all nonserializable fields +transient. + +For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Serialized_Object_Converter[Configuring +a Serialized Object Converter]. + +==== Type Conversion Converter + +The type conversion converter is an extension of direct and direct +collection mappings that lets you explicitly map a data source type to a +Java type. For example, a `+Number+` in the data source can be mapped to +a `+String+` in Java, or a `+java.util.Date+` in Java can be mapped to a +`+java.sql.Date+` in the data source. + +The link:#Figure_16-8[Type Conversion Mapping (relational)] figure +illustrates a type conversion mapping (relational). Because the +`+java.util.Date+` class is stored by default as a `+Timestamp+` in the +database, it must first be converted to an explicit database type such +as `+java.sql.Date+` (required only for DB2–most other databases have a +single date data type that can store any date or time). + +[#Figure 16-8]## *_Type Conversion Mapping (relational)_* + +.Type Conversion Mapping (relational) +image::tcmapfig.gif[Type Conversion Mapping +(relational),title="Type Conversion Mapping (relational)"] + +The link:#Figure_16-9[Type Conversion Mapping (nonrelational)] figure +illustrates a type conversion mapping (nonrelational). +`+java.util.Date+` object is mapped to a String in a XML schema. + +[#Figure 16-9]## *_Type Conversion Mapping (nonrelational)_* + +.Type Conversion Mapping (nonrelational) +image::tcmapxml.gif[Type Conversion Mapping +(nonrelational),title="Type Conversion Mapping (nonrelational)"] + +You can use a type conversion converter to specify the specific database +type when that type must be handled specially for the database. This +includes support for the special Oracle JDBC binding options required +for `+NCHAR+`, `+NVARCHAR2+`, and `+NCLOB+` fields as well as the +special Oracle Thin JDBC insert and update requirements for handling +`+BLOB+` and `+CLOB+` fields greater than 5K. + +EclipseLink uses the `+NCharacter+`, `+NClob+` and `+NString+` types in +the `+org.eclipse.persistence.platform.database.oracle+` package as the +converter data type to support the `+NCHAR+`, `+NCLOB+` and +`+NVARCHAR2+` types. EclipseLink uses the `+java.sql.Blob+` and `+Clob+` +types as the converter data type to support `+BLOB+` and `+CLOB+` values +greater than 5K. + +You can configure a type conversion converter to map a data source time +type (such as `+TIMESTAMP+`) to a `+java.lang.String+` provided that the +String value conforms to the following formats: + +* `+YYYY/MM/DD HH:MM:SS+` +* `+YY/MM/DD HH:MM:SS+` +* `+YYYY-MM-DD HH:MM:SS+` +* `+YY-MM-DD HH:MM:SS+` + +For more complex `+String+` to `+TIMESTAMP+` type conversion, consider a +transformation mapping (see link:#Transformation_Mappings[Transformation +Mappings]). + +For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Type_Conversion_Converter[Configuring +a Type Conversion Converter]. + +==== Object Type Converter + +The object type converter is an extension of direct and direct +collection mappings that lets you match a fixed number of XML values to +Java objects. Use this converter when the values in the schema differ +from those in Java. + +The link:#Figure_16-10[Object Type XML Converter] figure illustrates an +object type conversion between the `+Employee+` attribute `+gender+` and +the XML element `+gender+`. If the value of the Java object attribute is +`+Female+`, EclipseLink stores it in the XML element as `+F+`. + +[#Figure 16-10]## *_Object Type XML Converter_* + +.Object Type XML Converter +image::obxmlfig.gif[Object Type XML +Converter,title="Object Type XML Converter"] + +For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_an_Object_Type_Converter[Configuring +an Object Type Converter]. + +==== Simple Type Translator + +The simple type translator is an extension of direct and direct +collection mappings that lets you automatically translate an XML element +value to an appropriate Java type based on the element’s attribute as +defined in your XML schema. + +You can use a simple type translator only when the mapping’s XPath goes +to a text node. You cannot use a simple type translator if the mapping’s +XPath goes to an attribute. + +Using a simple type translator, you can make the XML document preserve +type information. This is useful when your object model specifies +generic object attributes such as `+java.lang.Object+` and +`+java.io.Serializable+`, since they do not trigger specific type +conversions in EclipseLink as do specific object attributes such as +`+java.lang.Integer+` or `+java.util.Calendar+`. + +The link:#Figure_16-11[Simple Type Translator] figure illustrates a type +translation XML mapping for the `+number+` attribute of the +`+PhoneNumber+` class. Notice that the Java attribute is not specific +enough to preserve the typing. The simple type translator adds the type +information to the resulting document to preserve the typing. + +[#Figure 16-11]## *_Simple Type Translator_* + +.Simple Type Translator +image::tcxmlfig.gif[Simple Type +Translator,title="Simple Type Translator"] + +By default, EclipseLink uses built-in read and write conversion pairs +(see link:#Default_Read_Conversions[Default Read Conversions] and +link:#Default_Write_Conversions[Default Write Conversions]). + +You can override this behavior by specifying and configuring your own +simple type translator, for example, to write XML binary data as +`+Base64+`. + +For more information, see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Simple_Type_Translator[Configuring +a Simple Type Translator]. + +===== Default Read Conversions + +The link:#Table_16-2[Simple Type Translator Read Conversions] table +lists the built-in conversion pairs for reading XML elements. When the +schema attribute is specified and the simple type translator is enabled, +the value read is converted to the corresponding Java type. + +[#Table 16-2]## *_Simple Type Translator Read Conversions_* + +[cols="<,<",options="header",] +|=== +|*Schema Type* |*Java Type* +|base64Binary |Byte[] +|boolean |Boolean +|byte |Byte +|date |Calendar +|dateTime |Calendar +|double |Double +|float |Float +|hexBinary |Byte[] +|int |int +|integer |BigInteger +|long |Long +|short |Short +|string |String +|time |Calendar +|unsignedByte |Short +|unsignedInt |Long +|unsignedShort |Integer +|=== + +===== Default Write Conversions + +The link:#Table_16-3[Simple Type Translator Write Conversions] tabel +lists the built-in conversion pairs for writing XML. When a Java class +attribute is of a type in the following table and the simple type +translator is enabled, the corresponding schema type is specified on the +element written. + +[#Table 16-3]## *_Simple Type Translator Write Conversions_* + +[cols="<,<",options="header",] +|=== +|*Java Type* |*Schema Type* +|Byte[] |hexBinary +|BigInteger |integer +|Boolean |boolean +|Byte |byte +|Calendar |dateTime +|Gregorian_Calendar |dateTime +|Double |double +|Float |float +|Integer |int +|Long |long +|int |int +|short |short +|String |string +|=== + +=== Transformation Mappings + +In some special circumstances, existing mapping types and their default +Java to data source type handling may be insufficient. In these special +cases, you can consider using a transformation mapping to perform +specialized translations between how a value is represented in Java and +in the data source. + +A transformation mapping is made up of the following two components: + +* attribute transformer (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Attribute_Transformer[Configuring +Attribute Transformer]): performs the object attribute transformation at +read (unmarshall) time; +* field transformer (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Field_Transformer_Associations[Configuring +Field Transformer Associations]): performs the object attribute-to-field +transformation at write (marshal) time; + +You can implement a transformer as either a separate class or as a +method on your domain object. + +Within your implementation of the attribute and field transformer, you +can take whatever actions are necessary to transform your application +data to suit your data source, and vise versa. + +For more information, see the following: + +* link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping] +* link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Transformation_Mapping[EIS +Transformation Mapping] +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Transformation_Mapping[XML +Transformation Mapping] + +=== Mappings and XPath + +EclipseLink uses XPath statements to efficiently map the attributes of a +Java object in EIS mappings to XML records and in XML mappings to XML +documents. When you create such a mapping, you can specify the +following: + +* link:#XPath_by_Position[XPath by Position] +* link:#XPath_by_Path_and_Name[XPath by Path and Name] +* link:#XPath_by_Name[XPath by Name] +* link:#Self_XPath[Self XPath] + +==== XPath by Position + +In a relational database table, columns are uniquely identified by name. +In an XML document, elements are uniquely identified by name and +position. The link:#Figure_16-12[Mapping to an XML Document by Position] +figure illustrates mapping to an XML document in which the first +instance of the `+street+` element stores apartment information and the +second instance of the `+street+` element stores street information. The +link:#Figure_16-12[Mapping to an XML Document by Position] figure shows +that EclipseLink XML mappings preserve the order in which mappings are +persisted and allow you to map Java object attributes to XML elements by +position using an XPath like `+street[2]/text()+`. + +Other XML technologies only recognize the name of XML elements (not +their position) and force you to store the simple values from elements +with the same name in a collection. + +[#Figure 16-12]## *_Mapping to an XML Document by Position_* + +.Mapping to an XML Document by Position +image::xpposit.gif[Mapping to an XML Document by +Position,title="Mapping to an XML Document by Position"] + +==== XPath by Path and Name + +In an XML document, attributes and elements are uniquely identified by a +combination of name and path. The link:#Figure_16-13[Mapping to an XML +Document by Path and Name] figure illustrates that EclipseLink XML +mappings can uniquely identify an XML element by name and path using an +XPath such as `+item/name/text()+`. EclipseLink does not require a +formal object relationship between XML elements `+lines+` and `+item+`. + +Other XML technologies force you to provide an object relationship for +every level of nesting, resulting in the inclusion of many XML elements +and classes simply to organize the data to satisfy this restriction. +This produces an unnecessarily large object model that does not properly +reflect the domain space. + +[#Figure 16-13]## *_Mapping to an XML Document by Path and Name_* + +.Mapping to an XML Document by Path and Name +image::xpnampat.gif[Mapping to an XML Document by Path and +Name,title="Mapping to an XML Document by Path and Name"] + +==== XPath by Name + +For simple XML documents, EclipseLink XML mappings can correctly place +data in an XML document given an XPath of only an attribute or element +name. + +The link:#Figure_16-14[Mapping to a Simple XML Document by Name] figure +illustrates mapping to a simple XML document by name. You can map Java +object attribute `+name+` to XML attribute `+name+` by specifying an +XPath of only `+@NAME+`. Similarly, you can map Java object attribute +`+age+` to XML text node `+AGE+` by specifying an XPath of only `+AGE+`. + +[#Figure 16-14]## *_Mapping to a Simple XML Document by Name_* + +.Mapping to a Simple XML Document by Name +image::xpname.gif[Mapping to a Simple XML Document by +Name,title="Mapping to a Simple XML Document by Name"] + +Specifying an XPath by name provides the worst performance of the XPath +mapping options. We recommend that you use XPath by position (see +link:#XPath_by_Position[XPath by Position]) or XPath by path and name +(see link:#XPath_by_Path_and_Name[XPath by Path and Name]) instead. + +==== Self XPath + +For composite relationships, EclipseLink XML mappings can place data in +the parent’s element rather than an element nested within it given the +self XPath (`+"."+`). + +This figure illustrates mapping to an XML document using the self XPath. + +[#Figure 16-15]## *_Mapping to a XML Document Using Self XPath_* + +.Mapping to a XML Document Using Self XPath +image::xpnameaddress.gif[Mapping to a XML Document Using Self +XPath,title="Mapping to a XML Document Using Self XPath"] + +Note that in the preceding example represented by the +link:#Figure_16-15[Mapping to a XML Document Using Self XPath] figure, +`+name+` attribute of the `+Employee+` class is mapped using the +`+@name+` annotation. + +Using the self XPath, you can make EclipseLink perform all read and +write operations in the parent’s element and not an element nested +within it (see #Mappings_and_the_jaxb:class_Customization[Mappings and +the jaxb:class Customization]). + +=== Mappings and xsd:list and xsd:union Types + +EclipseLink supports mapping to `+xsd:list+` and `+xsd:union+` types in +EIS mappings to XML records and XML mappings to XML documents, as this +table shows. + +[#Table 16-4]## *_EclipseLink Support for xsd:list and xsd:union Types_* + +XSD + +EIS Direct Mapping XML Direct Mapping + +EIS Composite Direct Collection Mapping XML Composite Direct Collection +Mapping + +Mapping an xsd:union Type + +Mapping an xsd:list Type + +Mapping a List of Unions + +Mapping a Union of Lists + +Mapping a Union of Unions + +==== Mapping an xsd:union Type + +Use an `+EISDirectMapping+` (with XML records), an `+XMLDirectMapping+` +or their subclasses to map a Java attribute to an `+xsd:union+` type, +such as the following: + +`+    +` `+        +` + +`+    +` + +When EclipseLink marshalls (writes) an object to XML, it uses its +default conversion pairs to convert from the Java type to the +appropriate `+xsd+` type. + +In the case where the `+memberTypes+` map to the same Java type, +EclipseLink marshalls using the first `+memberType+` in the union which +allows a successful conversion. For example, if you map a Java type of +`+byte[]+` to an `+xsd:union+` with `+memberTypes+` of `+hexBinary+` and +`+base64Binary+`, then EclipseLink marshalls using the first +`+memberType+`: `+hexBinary+`. + +You can customize the default conversion pairs to control the Java type +to `+xsd+` type conversion using `+XMLField+` method `+addConversion+` +and configuring your mapping with that `+XMLField+` using +`+EISDirectMapping+` or `+XMLDirectMapping+` method `+setField+`. For +example, if the `+memberTypes+` were `+xsd:date+` and `+xsd:time+` and +the Java attribute was of type `+java.util.Date+` instead of the JAXB +1.0 standard `+java.util.Calendar+`, you can modify the conversion pair +for `+xsd:date+` to be `+java.util.Date+`. + +When EclipseLink unmarshalls (reads) XML into an object, it tries each +`+memberType+` in the order specified in the XSD until the first +successful conversion is made. + +If your XML document specifies the `+xsi:type+` attribute on an element, +then EclipseLink converts according to the `+xsi:type+` instead of +trying the `+memberTypes+`. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Union_Field_with_an_XML_Direct_Mapping[Mapping +to a Union Field with an XML Direct Mapping]. The same applies to an +`+EISDirectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Direct_Mapping[EIS +Direct Mapping]). + +==== Mapping an xsd:list Type + +You can map a Java attribute to an `+xsd:list+` type, such as: + +`+    +` + +If you represent the `+xsd:list+` in your object model as a Java +`+List+` type, use an `+EISCompositeDirectCollectionMapping+` (with XML +records), an `+XMLCompositeDirectCollectionMapping+` or their subclasses +and use the mapping method `+useCollectionClass+` to specify the +`+List+` type of the Java attribute. + +If you represent the list in your object model as a `+String+` of white +space delimited tokens (for example, `+"aaa bbb ccc"+`), use an +`+EISDirectMapping+` (with XML records), an `+XMLDirectMapping+` or +their subclasses to map this Java attribute to an `+xsd:list+` (for +example, `+aaa bbb ccc+`). + +In either case, you can configure whether or not the mapping unmarshalls +(writes) the list to a single node, like `+aaa bbb ccc+`, or to multiple +nodes, such as the following: + +`+aaa+` `+bbb+` `+ccc+` + +For more information on mapping to an `+xsd:list+` type using an +`+XMLCompositeDirectCollectionMapping+` or its subclasses, see the +following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Single_Text_Node_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Single Text Node with an XML Composite Direct Collection Mapping] +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Single_Attribute_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Single Attribute with an XML Composite Direct Collection Mapping] +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#Specifying_the_Content_Type_of_a_Collection_with_an_XML_Composite_Direct_Collection_Mapping[Specifying +the Content Type of a Collection with an XML Composite Direct Collection +Mapping] + +The same applies to an `+EISCompositeDirectCollectionMapping+` (with XML +records). + +For more information about mapping to an `+xsd:list+` type using an +`+XMLDirectMapping+` or its subclasses, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_List_Field_with_an_XML_Direct_Mapping[Mapping +to a List Field with an XML Direct Mapping]. The same applies to an +`+EISDirectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Direct_Mapping[EIS +Direct Mapping]). + +==== Mapping a List of Unions + +Use an `+EISCompositeDirectCollectionMapping+` (with XML records), an +`+XMLCompositeDirectCollectionMapping+` or their subclasses to map a +Java attribute to an `+xsd:list+` that contains `+xsd:union+` types, +such as: + +`+    +` `+        +` `+            +` `+                +` +`+            +` + +`+        +` `+    +` + +When EclipseLink marshalls (writes) an object to XML, it does not rely +on a single `+xsd:list+` `+itemType+`. Instead, for each item in the +list, EclipseLink tries each `+memberType+` until the first successful +conversion. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_List_of_Unions_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a List of Unions with an XML Composite Direct Collection Mapping]. +The same applies to an `+EISCompositeDirectCollectionMapping+` with XML +records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Direct_Collection_Mapping[EIS +Composite Direct Collection Mapping]). + +==== Mapping a Union of Lists + +You can map a Java attribute to an `+xsd:union+` type whose +`+memberTypes+` are `+xsd:list+` types where each `+xsd:list+` contains +items of a single type, such as: + +`+    +` `+        +` `+            +` `+                +` +`+            +` + +`+            +` `+                +` `+            +` `+        +` +`+    +` + +Note that in this example, valid XML documents contain either all +`+xsd:double+`, all `+xsd:date+`, or all `+xsd:integer+` values. + +If you represent the list in your object model as a `+String+` of white +space delimited tokens (for example, `+"aaa bbb ccc"+`), use an +`+EISDirectMapping+` (with XML records) or an `+XMLDirectMappng+` to map +this Java attribute to an `+xsd:list+` (for example, `+aaa bbb ccc+`). + +If you represent the list in your object model as a Java `+List+` type, +use an `+EISCompositeDirectCollectionMapping+` (with XML records), an +`+XMLCompositeDirectCollectionMapping+` or their subclasses. + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Union_of_Lists_with_an_XML_Direct_Mapping[Mapping +to a Union of Lists with an XML Direct Mapping]. The same applies to an +`+EISDirectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Direct_Mapping[EIS +Direct Mapping]). +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Union_of_Lists_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Union of Lists with an XML Composite Direct Collection Mapping]. +The same applies to an `+EISCompositeDirectCollectionMapping+` with XML +records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Direct_Collection_Mapping[EIS +Composite Direct Collection Mapping]). + +==== Mapping a Union of Unions + +Use an `+EISDirectMapping+` (with XML records), an `+XMLDirectMapping+` +or their subclasses to map a Java attribute to an `+xsd:union+` that +contains `+xsd:union+` types, such as: + +`+    +` `+        +` `+            +` `+              +` +`+                +` `+              +` + +`+              +` `+                +` `+              +` +`+              +` `+      +` `+      +` + +`+            +` `+              +` `+                +` +`+              +` `+              +` `+                +` + +`+              +` `+              +` `+      +` `+    +` + +Note that in this example, valid XML documents may contain any of +`+xsd:date+`, `+xsd:integer+`, `+xsd:string+`, or `+xsd:float+`. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Mapping_to_a_Union_of_Unions_with_an_XML_Direct_Mapping[Mapping +to a Union of Unions with an XML Direct Mapping]. The same applies to an +`+EISDirectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Direct_Mapping[EIS +Direct Mapping]). + +=== Mappings and the jaxb:class Customization + +Using the `+jaxb:class+` customization, you can declaratively specify an +application-specific subclass of a schema-derived implementation class. +This lets you write your own classes that extend JAXB’s generated +implementation classes. The JAXB runtime binding framework can then +access your subclasses. + +When you create an EIS composite object mapping to XML records or an XML +composite object mapping to XML documents, you can configure the +mapping’s XPath ( +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_XPath[Configuring +XPath]) to accommodate `+jaxb:class+` customizations with the following +XSD structures: + +* link:#all,_choice,_or_sequence_Structure[all, choice, or +sequence Structure] +* link:#group_Structure[group Structure] +* link:#sequence_or_choice_Structure_Containing_a_group[sequence or +choice Structure Containing a group] +* link:#group_Structure_Containing_a_sequence_or_choice[group Structure +Containing a sequence or choice] +* link:#group_Structure_Containing_a_group[group Structure Containing a +group] + +When mapping to `+jaxb:class+` customized structures, consider the +limitations of EclipseLink support for this customization (see +#Limitations_of_jaxb:class_Customization_Support[Limitations of +jaxb:class Customization Support]). + +==== all, choice, or sequence Structure + +You can use the `+jaxb:class+` customization with an `+all+`, +`+choice+`, or `+sequence+` structure. The link:#Example_16-1[jaxb:class +Customization of an all Structure] example shows a `+jaxb:class+` +customization of an `+all+` structure. + +[#Example 16-1]## *_jaxb:class Customization of an all Structure_* + +`+    +` `+        +` `+            +` `+                +` + +`+                    +` `+                +` `+            +` +`+            +` `+            +` `+        +` + +`+    +` + +This directs the JAXB compiler to create an inner class named `+Period+` +in the owning element’s class for the `+all+` structure. Use an +`+EISCompositeObjectMapping+` (with XML records) or an +`+XMLCompositeObjectMapping+` to map a Java attribute to this inner +class. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The same applies to an +`+EISCompositeObjectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping]). + +==== group Structure + +You can use the `+jaxb:class+` customization with a `+group+` structure, +as this example shows. + +[#Example 16-2]## *_jaxb:class Customization of a group Structure_* + +`+    +` `+        +` `+            +` `+        +` + +`+    +` `+    +` `+        +` `+        +` `+    +` + +`+    +` `+        +` `+    +` + +This directs the JAXB compiler to create an external wrapper class named +`+Period+` for the `+group+` structure. Use an +`+EISCompositeObjectMapping+` (with XML records) or an +`+XMLCompositeObjectMapping+` to map a Java attribute to this external +wrapper class. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The same applies to an +`+EISCompositeObjectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping]). + +==== sequence or choice Structure Containing a group + +You can use the `+jaxb:class+` customization with a `+sequence+` or +`+choice+` structure that contains a `+group+`. The +link:#Example_16-3[jaxb:class Customization of a sequence Structure +Containing a group] example shows a `+jaxb:class+` customization of a +`+sequence+` structure containing a `+group+` structure. + +[#Example 16-3]## *_jaxb:class Customization of a sequence Structure +Containing a group_* + +`+    +` `+        +` `+            +` `+                +` + +`+                    +` `+                +` `+            +` +`+            +` `+            +` `+        +` + +`+    +` + +`+    +` `+        +` `+            +` + +`+        +` `+    +` `+    +` `+        +` `+        +` `+    +` + +This directs the JAXB compiler to create an inner class named +`+EmploymentInfo+` in the owning element’s class for the `+sequence+` +structure and an external wrapper class named `+Period+` for the +`+group+` structure. The inner class references the external wrapper +class. Use an `+EISCompositeObjectMapping+` (with XML records) or an +`+XMLCompositeObjectMapping+` to map a Java attribute to this inner +class. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The same applies to an +`+EISCompositeObjectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping]). + +==== group Structure Containing a sequence or choice + +You can use the `+jaxb:class+` customization with a `+group+` structure +that contains a `+sequence+` or `+choice+`. The +link:#Example_16-4[jaxb:class Customization of a group Structure +Containing a sequence] example shows a `+jaxb:class+` customization of a +`+group+` structure containing a `+sequence+` structure. + +[#Example 16-4]## *_jaxb:class Customization of a group Structure +Containing a sequence_* + +`+    +` `+        +` `+            +` `+        +` + +`+    +` `+    +` `+        +` `+            +` `+                +` +`+            +` + +`+        +` `+        +` `+        +` `+    +` + +`+    +` `+        +` `+            +` `+            +` +`+        +``+      +` `+    +` + +This directs the JAXB compiler to create an external wrapper class named +`+EmploymentInfo+` for the `+group+` structure and an inner class named +`+Period+` in the external wrapper class for the `+sequence+` structure. +The owning element references the external wrapper class. Use an +`+EISCompositeObjectMapping+` (with XML records) or an +`+XMLCompositeObjectMapping+` to map a Java attribute to this external +wrapper class. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The same applies to an +`+EISCompositeObjectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping]). + +==== group Structure Containing a group + +You can use the `+jaxb:class+` customization with a `+group+` structure +that contains another `+group+` structure, as the +link:#Example_16-5[jaxb:class Customization of a group Structure +Containing a group] example shows. + +[#Example 16-5]## *_jaxb:class Customization of a group Structure +Containing a group_* + +`+    +` `+        +` `+            +` `+        +` + +`+    +` `+    +` `+        +` `+        +` `+    +` + +`+    +` `+        +` `+            +` `+        +` `+    +` + +`+    +` `+        +` `+        +` `+    +` + +`+    +` `+        +` `+    +` + +This directs the JAXB compiler to create a wrapper class named +`+EmploymentInfo+` for the `+group+` structure that the owning element’s +class references and another wrapper class named `+Period+` for the +`+group+` structure that the `+EmploymentInfo+` class references. Use an +`+EISCompositeObjectMapping+` (with XML records) or an +`+XMLCompositeObjectMapping+` to map a Java attribute to these wrapper +classes. + +For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping]. The same applies to an +`+EISCompositeObjectMapping+` with XML records (see +link:Introduction%20to%20EIS%20Mappings%20(ELUG)#EIS_Composite_Object_Mapping[EIS +Composite Object Mapping]). + +==== Limitations of jaxb:class Customization Support + +When mapping to jaxb:class customized structures, consider the following +limitations: + +* Unbounded structures are not supported. +* Partial validation is not supported. +* When mapping sequence elements to a composite object, the XML schema +must order the elements so that the elements you map to the composite +object are kept together. The `+sequence+` structure forces all elements +to occur in the order in which they are specified in the XML schema. +Consider the XML schema shown in the link:#Example_16-6[XML Schema With +Unsupported Sequence Element Order] example. A valid XML instance must +contain the sequence elements in the specified order: `+street+`, +`+customerName+`, `+city+` In this example, you want to map the +`+customerName+` attribute with a direct mapping and you want to map the +`+street+` and `+city+` attributes to a composite `+Address+` object. +Depending on the order in which you define the mappings, EclipseLink +will marshall invalid XML document instances in the order +`+customerName+`, `+street+`, `+city+` or `+street+`, `+city+`, +`+customerName+`. + +[#Example 16-6]## *_XML Schema With Unsupported Sequence Element Order_* + +`+    +` `+        +` `+            +` `+            +` `+            +` + +`+        +` `+    +` + +To correct this problem, modify the XML schema to keep the elements you +want to map to the composite object together (see the +link:#Example_16-7[XML Schema With Supported Sequence Element Order] +example) and define the mappings in the order specified by the XML +schema. + +[#Example 16-7]## *_XML Schema With Supported Sequence Element Order_* + +`+    +` `+        +` `+            +` `+            +` `+            +` + +`+        +` `+    +` + +=== Mappings and JAXB Typesafe Enumerations + +JAXB binds a typesafe enumeration class to a named simple type +definition with a `+basetype+` that derives from `+xsd:NCName+` and has +`+enumeration+` facets (see this example). + +[#Example 16-8]## *_Schema Fragment with Typesafe Enumeration +Declaration_* + +`+    +` `+        +` `+        +` `+    +` + +You can map a Java attribute to such an enumeration using the +`+JAXBTypesafeEnumConverter+` with an `+EISDirectMapping+` or +`+EISCompositeDirectCollectionMapping+` with XML records, or with an +`+XMLDirectMapping+`, `+XMLCompositeDirectCollectionMapping+` or their +subclasses with XML documents. + +The Workbench does not support the `+JAXBTypesafeEnumConverter+` +directly: to configure a mapping with this converter, you must use a +descriptor amendment method (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_JAXB_Typesafe_Enumeration_Converter[Configuring +a JAXB Typesafe Enumeration Converter]). + +If you create a project and object model using the EclipseLink JAXB +compiler (see +link:Creating%20an%20XML%20Project%20(ELUG)#Creating_an_XML_Project_from_an_XML_Schema[Creating +an XML Project from an XML Schema]), the compiler will create the type +safe enumeration class and a class with descriptor amendment methods and +register the required amendment methods automatically (see +link:Introduction%20to%20XML%20Projects%20(ELUG)#Typesafe_Enumeration_Converter_Amendment_Method_DescriptorAfterLoads_Class[Typesafe +Enumeration Converter Amendment Method DescriptorAfterLoads Class]). + +== Mapping API + +All the mapping classes are derived from the `+DatabaseMapping+` class. + +[#Table 16-5]## *_Platform and Mapping Package Compatibility_* + +Platform + +Mapping Package + +DatabasePlatform For relational projects + +org.eclipse.persistence.mappings org.eclipse.persistence.mappings.xdb +org.eclipse.persistence.mappings.structures + +EISPlatform For EIS projects + +org.eclipse.persistence.eis.mappings + +XMLPlatform For XML projects + +org.eclipse.persistence.ox.mappings + +== Relational Mappings + +A relational mapping transforms any object data member type to a +corresponding relational database (SQL) data source representation in +any supported relational database. Relational mappings allow you to map +an object model into a relational data-model. + +Relational mappings can also transform object data members that +reference other domain objects that are stored in other tables in the +database and are related through foreign keys. + +Use relational mappings in relational projects. For more information, +see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Building_Relational_Projects[Building +Relational Projects]. + +For more information about relational mappings, see +link:Relational_Mappings_(ELUG)[Relational Mappings (ELUG)] + +== Object-Relational Data Type Mappings + +An object-relational data type mapping transforms certain object data +member types to structured data source representations optimized for +storage in specialized object-relational data type databases such as +Oracle Database. Object-relational data type mappings allow you to map +an object model into an object-relational data type data-model. + +Use object-relational data type mappings in relational projects. For +more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Building_Relational_Projects[Building +Relational Projects]. + +For more information about object-relational data type mappings, see +link:Object-Relational_Data_Type_Mappings_(ELUG)[Object-Relational Data +Type Mappings (ELUG)]. + +== XML Mappings + +An XML mapping transforms object data members to the XML elements of an +XML file whose structure is defined by an XML schema document (XSD). + +Use XML mappings in XML projects. For more information, see +link:Introduction%20to%20XML%20Projects%20(ELUG)#XML_Project_Concepts[XML +Project Concepts]. + +For more information about XML mappings, see +link:XML_Mappings_(ELUG)[XML Mappings (ELUG)]. + +== EIS Mappings + +An EIS mapping transforms object data members to the EIS record format +defined by the object’s descriptor. + +Use EIS mappings in EIS projects. For more information, see +link:Introduction%20to%20EIS%20Projects%20(ELUG)#EIS_Project_Concepts[EIS +Project Concepts]. + +For more information about EIS mappings, see +link:EIS_Mappings_(ELUG)[EIS Mappings (ELUG)]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Concept[Category: Concept] Category:_Release_1[Category: +Release 1] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..9d9745b9fdb --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Descriptors_(ELUG).adoc @@ -0,0 +1,46 @@ +*TOC* +Special:Whatlinkshere_Introduction_to_Object-Relational_Data_Type_Descriptors_(ELUG)[Related +Topics] + +This section provides an overview of object-relational data type +descriptors. + +For information on descriptor concepts and features common to more than +one type of EclipseLink descriptors, see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors]. + +The object-relational data type paradigm extends traditional relational +databases to include object-oriented functions. Oracle, IBM DB2, +Informix, and other DBMS databases allow users to store, access, and use +complex data in more sophisticated ways.The object-relational data type +standard is an evolving standard concerned mainly with extending the +database data structures and SQL (SQL 3). + +Object-relational data type descriptors describe Java objects that you +map to special relational database types that correspond more closely to +object types. Using these special object-relational data type database +types can simplify mapping objects to relational database tables. Not +all relational databases support these special object-relational data +type database types. + +Using object-relational data type descriptors in a relational project, +you can configure object-relational data type mappings to these special +object-relational data type database data types (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational_Data_Type_Mapping_Types[Object-Relational +Data Type Mapping Types]). + +For more information, see the following: + +* link:Creating%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)[Creating +an Object-Relational Data Type Descriptor] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)[Configuring +an Object-Relational Data Type Descriptor] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..0fcd8878310 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Object-Relational_Data_Type_Mappings_(ELUG).adoc @@ -0,0 +1,188 @@ +*TOC* +Special:Whatlinkshere_Introduction_to_Object-Relational_Data_Type_Mappings_(ELUG)[Related +Topics] + +An object-relational data type mapping transforms certain object data +member types to structured data source representations optimized for +storage in specialized object-relational data type databases (such as +Oracle Database). Object-relational data type mappings let you map an +object model into an object-relational data type data model. + +Do not confuse object-relational data type mappings with relational +mappings (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation_Mapping[Transformation +Mapping]). A relational mapping transforms any object data member type +to a corresponding relational database (SQL) data source representation +in any supported relational database. Relational mappings let you map an +object model into a relational data model. In general, you can use +relational mappings with any supported relational database. You can only +use object-relational data type mappings with specialized +object-relational data type databases optimized to support +object-relational data type data source representations. + +For information on mapping concepts and features common to more than one +type of EclipseLink mappings, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings]. + +EclipseLink supports the following object-relational data type mappings. +These mappings allow for an object model to persist in an +object-relational data type data model. The Workbench does not support +object-relational data type mappings–they must be defined in code or +through amendment methods. + +[#Table 45-1]## + +[width="100%",cols="<34%,<43%,<12%,<11%",options="header",] +|=== +|*Type of Mapping* |*Description* |*EclipseLink Workbench* |*Java* +|link:#Object-Relational_Data_Type_Structure_Mapping[Object-relational +data type structure mapping] |Map to object-relational data type +aggregate structures (the `+Struct+` type in JDBC and the `+OBJECT+` +type in Oracle Database__i__) +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Object-Relational_Data_Type_Reference_Mapping[Object-relational +data type reference mapping] |Map to object-relational data type +references (the `+Ref+` type in JDBC and the `+REF+` type in Oracle +Database) |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Object-Relational_Data_Type_Array_Mapping[Object-relational data +type array mapping] |Map a collection of primitive data to +object-relational data type array data types (the `+Array+` type in JDBC +and the `+VARRAY+` type in Oracle Database). +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Object-Relational_Data_Type_Object_Array_Mapping[Object-relational +data type object array mapping] |Map to object-relational data type +array data types (the `+Array+` type in JDBC and the `+VARRAY+` type in +Oracle Database). |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Object-Relational_Data_Type_Nested_Table_Mapping[Object-relational +data type nested table mapping] |Map to object-relational data type +nested tables (the `+Array+` type in JDBC and the `+NESTED+` `+TABLE+` +type in Oracle Database) +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Object-Relational Data Type Structure Mapping + +In an object-relational data type data model, *structures* are +user-defined data types or object types. This is similar to a Java +class–it defines attributes or fields in which each attribute is one of +the following: + +* A primitive data type. +* Another structure. +* Reference to another structure. + +EclipseLink maps nested structures with the `+StructureMapping+` class. +The structure mapping supports null values and shared aggregates without +requiring additional settings (because of the object-relational data +type support of the database). + +See +link:Configuring%20an%20Object-Relational%20Data%20Type%20Structure%20Mapping%20(ELUG)[Configuring +an Object-Relational Data Type Structure Mapping] for more information. + +== Object-Relational Data Type Reference Mapping + +In an object-relational data type data model, structures reference each +other through *refs*–not through foreign keys (as in a traditional data +model). Refs are based on the target structure’s `+ObjectID+`. They +represent an object reference in Java. + +EclipseLink maps refs with the `+ReferenceMapping+` class. The reference +mapping does not require foreign key information (because of the +object-relational data type support of the database). + +See +link:Configuring%20an%20Object-Relational%20Data%20Type%20Reference%20Mapping%20(ELUG)[Configuring +an Object-Relational Data Type Reference Mapping] for more information. + +== Object-Relational Data Type Array Mapping + +In an object-relational data type data model, structures can contain +*arrays* (collections of other data types). These arrays can contain +primitive data types or collections of other structures. + +EclipseLink maps arrays of primitive data types with the +`+ArrayMapping+` class. An array mapping maps to object-relational data +type array data types (the `+Array+` type in JDBC and the `+VARRAY+` +type in Oracle Database). To map a collection of aggregate structures, +use an object array mapping (see +link:#Object-Relational_Data_Type_Object_Array_Mapping[Object-Relational +Data Type Object Array Mapping]). + +The object-relational data type database stores the arrays with their +parent structure in the same table. To store information in a separate +table from the parent structure’s table, use a nested table mapping (see +link:#Object-Relational_Data_Type_Nested_Table_Mapping[Object-Relational +Data Type Nested Table Mapping]). + +All elements in the array must be the same data type. The number of +elements in an array controls the size of the array. An Oracle Database +allows arrays of variable sizes (the `+VARRAY+` type). + +See +link:Configuring%20an%20Object-Relational%20Data%20Type%20Array%20Mapping%20(ELUG)[Configuring +an Object-Relational Data Type Array Mapping] for more information. + +== Object-Relational Data Type Object Array Mapping + +In an object-relational data type data model, structures can contain +_arrays_ (collections of other data types). These arrays can contain +primitive data types or collections of other structures. + +EclipseLink maps arrays of structures with the `+ObjectArrayMapping+` +class. An object array mapping defines a collection-aggregated +relationship, in which the target objects share the same row as the +source object. + +You must associate this mapping to an attribute in the parent class. + +See +link:Configuring%20an%20Object-Relational%20Data%20Type%20Object%20Array%20Mapping%20(ELUG)[Configuring +an Object-Relational Data Type Object Array Mapping] for more +information. + +== Object-Relational Data Type Nested Table Mapping + +*Nested table* types model an unordered set of elements. These elements +may be built-in or user-defined types. You can view a nested table as a +single-column table or, if the nested table is an object type, as a +multicolumn table (with a column for each attribute of the object type). + +EclipseLink maps nested tables with the `+NestedTableMapping+` class. It +represents a collection of object references in Java. Because of the +object-relational data type support of the database, nested table +mapping does not require foreign key information (as with a one-to-many +mapping) or a relational table (as with a many-to-many mapping). + +Typically, nested tables represent a one-to-many or many-to-many +relationship of references to another independent structure. They +support querying and joining better than the `+VARRAY+` types that are +in-lined to the parent table. EclipseLink supports mapping a nested +table of `+REF+` types only. EclipseLink does not support nested tables +of basic or other structured data types–use array (see +link:#Object-Relational_Data_Type_Array_Mapping[Object-Relational Data +Type Array Mapping]) or object array (see +link:#Object-Relational_Data_Type_Object_Array_Mapping[Object-Relational +Data Type Object Array Mapping]) mappings instead. + +See +link:Configuring%20an%20Object-Relational%20Data%20Type%20Nested%20Table%20Mapping%20(ELUG)[Configuring +an Object-Relational Data Type Nested Table Mapping] for more +information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Persistence_Layer_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Persistence_Layer_(ELUG).adoc new file mode 100644 index 00000000000..ae1b63564ce --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Persistence_Layer_(ELUG).adoc @@ -0,0 +1,153 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_Persistence_Layer_(ELUG)[Related +Topics] + +This section provides the conceptual overview of the persistence layer +of an EclipseLink application. + +[#Persistence Layer Concepts]## The purpose of your application’s +persistence layer is to use link:#transactions-sessions[a session] at +run time to associate +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Mapping_Metatdata[mapping +metadata] and a link:#transactions-data-access[data source] in order to +create, read, update, and delete persistent objects using the +link:#transactions-cache[EclipseLink cache], +link:#transactions-queries-and-expressions[queries and expressions], as +well as link:#transactions-transactions[transactions]. + +This section introduces the following persistence layer concepts: + +* link:#transactions-sessions[Sessions] +* link:#transactions-data-access[Data Access] +* link:#transactions-cache[Cache] +* link:#transactions-queries-and-expressions[Queries and Expressions] +* link:#transactions-transactions[Transactions] + +== [#transactions-sessions]#Sessions# + +A session is the primary interface between the client application and +the EclipseLink runtime, and represents the connection to the underlying +data source. + +For POJO projects, EclipseLink offers several different +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[session types], +each optimized for different design requirements and architectures. The +most commonly used session is the server session–a session that clients +access on the server through a client session. The server session +provides a shared cache and shared connection resources. + +In JPA projects, sessions are used internally as follows: + +* an `+EntityManagerFactory+` wraps an +`+org.eclipse.persistence.threetier.ServerSession+`; +* an `+EntityManager+` wraps an +`+org.eclipse.persistence.sessions.UnitOfWork+` and an +`+org.eclipse.persistence.threetier.ClientSession+`. + +== [#transactions-data-access]#Data Access# + +The login (if any) associated with a session 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 (an instance of `+Login+` interface) owns a data source platform. + +A platform includes options, such as binding, use of native SQL, use of +batch writing, and sequencing, that are specific to a particular data +source. For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types]. + +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. + +For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)[Introduction to Data +Access] + +== [#transactions-cache]#Cache# + +By default, an EclipseLink session provides an object level cache that +guarantees object identity and enhances performance by reducing the +number of times the application needs to access the data source. +EclipseLink provides a variety of cache options, including locking, +refresh, invalidation, isolation, and coordination. Using cache +coordination, you can configure EclipseLink to synchronize changes with +other instances of the deployed application. You configure most cache +options at the session level. You can also configure cache options on a +per-query basis, or on a descriptor to apply to all queries on the +reference class. + +For more information, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +== [#transactions-queries-and-expressions]#Queries and Expressions# + +EclipseLink provides several object and data query types, and offers +flexible options for query selection criteria, including the following: + +* EclipseLink expressions +* JP QL +* SQL +* Stored procedures +* Query by example + +With these options, you can build any type of query. We recommend using +predefined queries to define application queries. Predefined queries are +held in the project metadata and referenced by name. This simplifies +application development and encapsulates the queries to reduce +maintenance costs. + +Regardless of the architecture or persistent entity type, you are free +to use any of the query options. The Workbench provides the simplest way +to define queries. Alternatively, you can build queries in code, using +the EclipseLink API. + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Introduction +to EclipseLink Queries] +* link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Introduction +to EclipseLink Expressions] + +== [#transactions-transactions]#Transactions# + +EclipseLink provides the ability to write transactional code isolated +from the underlying database and schema by using a *unit of work*. + +The unit of work isolates changes in a transaction from other threads +until it successfully commits the changes to the database. Unlike other +transaction mechanisms, the unit of work automatically manages changes +to the objects in the transaction, the order of the changes, and changes +that might invalidate other EclipseLink caches. The unit of work manages +these issues by calculating a minimal change set, ordering the database +calls to comply with referential integrity rules and deadlock avoidance, +and merging changed objects into the shared cache. In a clustered +environment, the unit of work also synchronizes changes with the other +servers in the coordinated cache. + +If an application uses EJB entity beans, you do not access the unit of +work API directly, but you still benefit from its features: the +integration between the EclipseLink runtime and the Java EE container +automatically uses the unit of work. + +For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Projects_(ELUG).adoc new file mode 100644 index 00000000000..58c6f5ef0da --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Projects_(ELUG).adoc @@ -0,0 +1,654 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_Projects_(ELUG)[Related +Topics] + +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. + +[#Table 13-1]## + +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. + +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. + +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. + +For more information, see the following: + +* link:Creating%20a%20Project%20(ELUG)[Creating a Project] +* link:Configuring%20a%20Project%20(ELUG)[Configuring a Project] +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Introduction +to EclipseLink Sessions] + +== Project Concepts + +This section describes concepts unique to EclipseLink projects, +including: + +* link:#Project_Architecture[Project Architecture] +* link:#Relational_and_Nonrelational_Projects[Relational and +Nonrelational Projects] +* link:#Persistent_and_Nonpersistent_Project[Persistent and +Nonpersistent Projects] +* link:#Projects_and_Login[Projects and Login] +* link:#Projects_and_Platforms[Projects and Platforms] +* link:#Projects_and_Sequencing[Projects and Sequencing] +* link:#XML_Namespaces[XML Namespaces] + +=== 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. + +[#Table 13-2]## *_Project, Descriptor, and Mapping Support_* + +[width="100%",cols="<17%,<42%,<41%",options="header",] +|=== +|*Project* |*Descriptor* |*Mapping* +|link:Introduction%20to%20Relational%20Projects%20(ELUG)[Relational +Projects] +|link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Relational +Descriptors] and +link:Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)[Object-Relational +Data Type Descriptors] +|link:Introduction%20to%20Mappings%20(ELUG)#Relational_Mappings[Relational +Mappings] and +link:Introduction%20to%20Mappings%20(ELUG)#Object-Relational_Data_Type_Mappings[Object-Relational +Data Type Mappings] + +|link:Introduction%20to%20EIS%20Projects%20(ELUG)[EIS Projects] +|link:Introduction%20to%20EIS%20Descriptors%20(ELUG)[EIS Descriptor +Concepts] |link:Introduction%20to%20Mappings%20(ELUG)#EIS_Mappings[EIS +Mappings] + +|link:Introduction%20to%20XML%20Projects%20(ELUG)[XML Projects] +|link:Introduction%20to%20XML%20Descriptors%20(ELUG)[XML Descriptor +Concepts] |link:Introduction%20to%20Mappings%20(ELUG)#XML_Mappings[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 +link:#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. + +=== 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 +link:#Projects_and_Platforms[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: + +* link:#POJO_Session_Role[POJO Session Role] +* link:#Development_Role[Development Role] + +==== 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 +link:Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring_and_Using_Sessions_at_Run_Time[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 link:#Development_Role[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 +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Login_Types[Data +Source Login Types]. + +For information on configuring a session login, see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Session_Login[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 +link:#POJO_Session_Role[POJO Session Role]) or the `+project.xml+` file. + +For more information on creating a development login, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Development_and_Deployment_Logins[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 +link:#Projects_and_Login[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 +link:Introduction%20to%20Data%20Access%20(ELUG)#Data_Source_Platform_Types[Data +Source Platform Types]. + +=== Projects and Sequencing + +An essential part of +link: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: + +* For relational projects, you typically obtain object identifier values +from a separate sequence table (or database object) dedicated to +managing object identifier values (see +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Sequencing in +Relational Projects]). +* For EIS projects, you typically +link: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. + +To configure sequencing, you must configure the following: + +* link:#Configuring_How_to_Obtain_Sequence_Values[how to obtain sequence +values], and +* link:#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 +link:Introduction%20to%20Data%20Access%20(ELUG)#Sequence_Connection_Pools[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 +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[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 +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[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: +link:Creating%20an%20EIS%20Project%20(ELUG)#Creating_an_EIS_Project_with_XML_Records[EIS +projects that use XML records] and +link:Introduction%20to%20XML%20Projects%20(ELUG)#XML_Project_Concepts[XML +projects]. + +For more information, see link:#XML_Namespaces_Overview[XML Namespaces +Overview]]. + +== Project API + +This section describes the following: + +* link:#Project_Inheritance_Hierarchy[Project Inheritance Hierarchy] + +=== 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: +link:Creating%20an%20EIS%20Project%20(ELUG)#Creating_an_EIS_Project_with_XML_Records[EIS +projects that use XML records] and +link:Introduction%20to%20XML%20Projects%20(ELUG)#XML_Project_Concepts[XML +projects]. + +This section describes the following: + +* link:#Workbench_Namespace_Resolution[Workbench Namespace Resolution] +* link:#Element_and_Attribute_Form_Options[Element and Attribute Form +Options] +* link:#EclipseLink_Runtime_Namespace_Resolution[EclipseLink Runtime +Namespace Resolution] + +=== Workbench Namespace Resolution + +Using Workbench, you can configure the XML schema namespace for your +project. For more information, see +link:Using%20Workbench%20(ELUG)#How_to_Configure_XML_Schema_Namespace[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: + +* link:#Element_Form_Default_Qualified_and_Attribute_Form_Default_Unqualified[Element +Form Default Qualified and Attribute Form Default Unqualified] +* link:#Element_and_Attribute_Form_Default_Unqualified[Element and +Attribute Form Default Unqualified] +* link:#Element_and_Attribute_Form_Default_Qualified[Element and +Attribute Form Default Qualified] + +==== Element Form Default Qualified and Attribute Form Default Unqualified + +The link:#Example_13-1[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. + +[#Example 13-1]## *_XML Schema with Element Form Default Qualified and +Attribute Form Default Unqualified_* + +[source,xml] +---- + + elementFormDefault="qualified"''' + '''attributeFormDefault="unqualified"''' + ns="urn:namespace-example" + targetNamespace="urn:namespace-example"> + + + + + + + + + + + + +---- + +This example shows an XML document that conforms to this XML schema. + +[#Example 13-2]## *_XML Document_* + +[source,xml] +---- + + <'''ns:'''customer xmlns:ns="urn:namespace-example" id="1"> + <'''ns:'''name>Jane Doens:'''name> + <'''ns:'''date-of-birth>1975-02-21ns:'''date-of-birth> + + ns:'''customer> +---- + +The link:#Example_13-3[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 +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_an_XML_Descriptor[Configuring +an XML Descriptor] and +link:Configuring%20an%20XML%20Mapping%20(ELUG)#Configuring_an_XML_Mapping[Configuring +an XML Mapping]). + +[#Example 13-3]## *_XML Descriptors and Mappings_* + +[source,java] +---- + 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); +---- + +==== Element and Attribute Form Default Unqualified + +The link:#Example_13-4[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. + +[#Example 13-4]## *_XML Schema with Element and Attribute Form Default +Unqualified_* + +[source,xml] +---- + + + elementFormDefault="unqualified"''' + '''attributeFormDefault="unqualified"''' + ns="urn:namespace-example" + targetNamespace="urn:namespace-example"> + + + + + + + + + + + + +---- + +This example shows an XML document that conforms to this XML schema. + +[#Example 13-5]## *_XML Document_* + +[source,xml] +---- + + <'''ns:'''customer xmlns:ns="urn:namespace-example" id="1"> + + Jane Doe + <'''ns:'''date-of-birth>1975-02-21ns:'''date-of-birth> + ns:'''customer> +---- + +The link:#Example_13-6[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 +link:Configuring%20an%20XML%20Descriptor%20(ELUG)[Configuring an XML +Descriptor] and +link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping]). + +[#'Example 13-6]## *_XML Descriptors and Mappings_* + +[source,java] +---- + + 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); +---- + +==== Element and Attribute Form Default Qualified + +The link:#Example_13-7[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. + +[#Example 13-7]## *_XML Schema with Element and Attribute Form Default +Qualified_* + +[source,xml] +---- + + elementFormDefault="qualified"''' + '''attributeFormDefault="qualified"''' + ns="urn:namespace-example" + targetNamespace="urn:namespace-example"> + + + + + + + + + + + + +---- + +This example shows an XML document that conforms to this XML schema. + +[#Example 13-8]## *_XML Document_* + +[source,xml] +---- + + <'''ns:'''customer xmlns:ns="urn:namespace-example" '''ns:'''id="1"> + <'''ns:'''name>Jane Doens:'''name> + <'''ns:'''date-of-birth>1975-02-21ns:'''date-of-birth> + + ns:'''customer> +---- + +The link:#Example_13-9[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 +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_an_XML_Descriptor[Configuring +an XML Descriptor] and +link:Configuring%20an%20XML%20Mapping%20(ELUG)#Configuring_an_XML_Mapping[Configuring +an XML Mapping]). + +[#Example 13-9]## *_XML Descriptors and Mappings_* + +[source,java] +---- + 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); +---- + +=== 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 link:#Example_13-9[XML Descriptors +and Mappings] example shows, EclipseLink will use the namespace prefixes +specified in the mapping when creating new documents. + +[#Figure 13-1]## *_Namespaces in EclipseLink_* + +.Namespaces in EclipseLink +image::namesp.gif[Namespaces in +EclipseLink,title="Namespaces in EclipseLink"] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..08be077b5e2 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Descriptors_(ELUG).adoc @@ -0,0 +1,298 @@ +*TOC* +Special:Whatlinkshere_Introduction_to_Relational_Descriptors_(ELUG)[Related +Topics] + +This section provides an overview of relational descriptors, as well as +explains the role of inheritance and various types of descriptors in +relational projects. + +For information on descriptor concepts and features common to more than +one type of EclipseLink descriptors, see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors]. + +Relational descriptors describe Java objects that you map to tables in a +relational database. You use them in +link:Introduction%20to%20Relational%20Projects%20(ELUG)[relational +projects]. + +Using relational descriptors in a relational project, you can configure +link:Introduction%20to%20Relational%20Mappings%20(ELUG)[relational +mappings]. + +For more information, see the following: + +* link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating a +Relational Descriptor] +* link:Configuring%20a%20Relational%20Descriptor%20(ELUG)[Configuring a +Relational Descriptor] + +== Aggregate and Composite Descriptors in Relational Projects + +In a relational project, you can designate the descriptor +link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Aggregate_Descriptors[as +an aggregate]. + +This lets you configure +link:Configuring%20a%20Relational%20Aggregate%20Object%20Mapping_(ELUG)[an +aggregate mapping] to associate data members in the target object with +fields in the source object’s underlying database tables. + +When you designate a relational descriptor as an aggregate, EclipseLink +lets you specify a mapping type for each field in the target class, but +defers associating the field with a database table until you configure +the aggregate object mapping in the source descriptor. In other words, +the target class descriptor defines _how_ each target class field is +mapped, but the source class descriptor defines _where_ each target +class field is mapped. This lets you share an aggregate object among +many parent descriptors mapped to different tables. + +When you designate a relational descriptor as an aggregate, you tell +EclipseLink that the class will be a target of an aggregate object +mapping, and this ensures that the EclipseLink runtime handles the +target class as follows: + +* It inserts, updates, and deletes the target class in parallel with its +source class. +* It does not cache the target class on its own; instead, it caches the +target class as part of its source class. +* It does not allow the target class to be read, written, deleted, or +registered in a unit of work. + +When working with aggregate relational descriptors, consider the +following: + +* link:#Relational_Aggregates_and_Nesting[Relational Aggregates and +Nesting] +* link:#Relational_Aggregates_and_Inheritance[Relational Aggregates and +Inheritance] + +For more information, see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Configuring +a Relational Descriptor as a Class or Aggregate Type]. + +=== Relational Aggregates and Nesting + +EclipseLink supports nested aggregates. In the link:#Figure_26-1[Nested +Aggregates] figure, source class `+HockeyPlayer+` is a normal +nonaggregate class descriptor. It owns target class `+Info+` which is +designated as an aggregate. The `+Info+` class itself owns target +classes `+PersonalInfo+` and `+TeamInfo+` which are each designated as +aggregates. + +[#Figure 26-1]## *_Nested Aggregates_* + +.Nested Aggregates +image::nestagg.gif[Nested Aggregates,title="Nested Aggregates"] + +In EJB 3.0, an aggregate is known as an embeddable. In the EJB 3.0 +specification, an embeddable may not contain another embeddable (that +is, the EJB 3.0 specification does not support nested aggregates). + +However, if you deploy an EclipseLink-enabled EJB 3.0 application with +persistence to OC4J, you can take advantage of an EclipseLink extension +of the EJB 3.0 specification to configure nested embeddables. Note that +if you do so, your application will not be strictly EJB 3.0-compliant. +The link:#Example_26-1[Nested Embeddables] example shows the classes +from the link:#Figure_26-1[Nested Aggregates] figure, using EJB 3.0 +annotations to take advantage of the EclipseLink extension of the EJB +3.0 specification to allow `+Info+` (an embeddable) to own embeddables +`+TeamInfo+` and `+PersonalInfo+`. + +[#Example 26-1]## *_Nested Embeddables_* + +[source,java] +---- + public class HockeyPlayer implements Serializable { + private int playerId; + private Info Info; + private String lastName; + private String firstName; + ... + @Embedded + public Info getInfo() { + return Info; + } + } + + @Embeddable + public class Info implements Serializable { + TeamInfo teamInfo; // EclipseLink extension of EJB 3.0 allows Embeddable with Embeddable + PersonalInfo personalInfo; + + public Info() {} + + @Embedded + public PersonalInfo getPersonalInfo() { + return personalInfo; + } + + public void setPersonalInfo(PersonalInfo personalInfo) { + this.personalInfo = personalInfo; + } + + @Embedded + public TeamInfo getTeamInfo() { + return teamInfo; + } + + public void setTeamInfo(TeamInfo teamInfo) { + this.teamInfo = teamInfo; + } + } + + @Embeddable + public class PersonalInfo implements Serializable { + private int age; + private double weight; + private double height; + ... + } + + @Embeddable + public class TeamInfo implements Serializable { + private String position; + private int jerseyNumber; + private HockeyTeam hockeyTeam; + ... + } +---- + +=== Relational Aggregates and Inheritance + +You can configure inheritance for a relational descriptor designated as +an aggregate (see +link:Introduction%20to%20Descriptors%20(ELUG)[Descriptors and +Inheritance]), however, in this case, _all_ the descriptors in the +inheritance tree must be aggregates. Aggregate and class descriptors +cannot exist in the same inheritance tree. + +== Descriptors and Inheritance in Relational Projects + +Inheritance describes how a derived class inherits the characteristics +of its superclass. You can use descriptors to describe the inheritance +relationships between classes in your relational projects. + +This section includes information on the following topics: + +* link:#Inheritance_and_Primary_Keys_in_Relational_Projects[Inheritance +and Primary Keys in Relational Projects] +* link:#Single-_and_Multi-Table_Inheritance_in_Relational_Projects[Single- +and Multi-Table Inheritance in Relational Projects] + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)[Descriptors and +Inheritance]. + +=== Inheritance and Primary Keys in Relational Projects + +For relational projects, EclipseLink assumes that all of the classes in +an inheritance hierarchy have the same primary key, as set in the root +descriptor. Child descriptors associated with data source +representations that have different primary keys must define the mapping +between the root primary key and the local one. + +For more information, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Primary Keys]. + +=== Single- and Multi-Table Inheritance in Relational Projects + +In a relational project, you can map your inheritance hierarchy to +link:#Single-Table_Inheritance[a single table] or to +link:#Multi-Table_Inheritance[multiple tables]. Use these options to +achieve the balance between storage efficiency and access efficiency +that is appropriate for your application. + +==== Single-Table Inheritance + +In this example, you store classes with multiple levels of inheritance +in a single table to optimize database access speeds. + +The entire inheritance hierarchy shown in the link:#Figure_26-1[Nested +Aggregates] figure can share the same table, as in the +link:#Figure_26-2[Inheritance Using a Superclass Table with Optional +Fields] figure. The `+FueledVehicle+` and `+NonFueledVehicle+` +subclasses can share the same table even though `+FueledVehicle+` has +some attributes that `+NonFueledVehicle+` does not. The +`+NonFueledVehicle+` instances waste database resources because the +database must still allocate space for the unused portion of its row. +However, this approach saves on accessing time because there is no need +to join to another table to get the additional `+FueledVehicle+` +information. + +As this figure shows, this approach uses a class indicator field. For +more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#How_to_Specify_a_Class_Indicator[How +to Specify a Class Indicator]. + +[#'Figure 26-2]## *_Inheritance Using a Superclass Table with Optional +Fields_* + +.Inheritance Using a Superclass Table with Optional Fields +image::inhtable.gif[Inheritance Using a Superclass Table with Optional +Fields,title="Inheritance Using a Superclass Table with Optional Fields"] + +==== Multi-Table Inheritance + +In this example, you store classes with multiple levels of inheritance +in multiple tables to optimize database storage space. + +In the inheritance hierarchy shown in the link:#Figure_26-1[Nested +Aggregates] figure, for subclasses that require additional attributes, +you use multiple tables instead of a single superclass table. This +optimizes storage space because there are no unused fields in the +database. However, this may affect performance because EclipseLink must +read from more than one table before it can instantiate the object. +EclipseLink first looks at +link:Introduction%20to%20Descriptors%20(ELUG)#How_to_Specify_a_Class_Indicator[the +class indicator field] to determine the class of object to create, then +uses the descriptor for that class to read from the subclass tables. + +The link:#Figure_26-3[Inheritance Using Separate Tables for Each +Subclass] figure illustrates the EclipseLink implementation of the +`+FUELEDVHCL+`, `+CAR+`, and `+BICYCLE+` tables. All objects are stored +in the `+VEHICLE+` table. `+FueledVehicle+`, `+Car+`, and `+Bicycle+` +information are also stored in secondary tables. Note that because the +`+NonFueledVehicle+` class does not hold any attributes or +relationships, it does not need a secondary table. + +[#Figure 26-3]## *_Inheritance Using Separate Tables for Each Subclass_* + +.Inheritance Using Separate Tables for Each Subclass +image::inhsepar.gif[Inheritance Using Separate Tables for Each +Subclass,title="Inheritance Using Separate Tables for Each Subclass"] + +[width="100%",cols="<100%",] +|=== +|*_Note_*: In general, using multitable inheritance is inefficient +because it can require excessive joins and multiple table fetching. +|=== + +===== Inheritance Outer-Joins + +If a root or branch inheritance descriptor has subclasses that span +multiple tables, you can configure a database view to optimize the +performance of queries against the parent descriptor by outer-joining +all of the subclass tables. This allows EclipseLink to fetch all of the +subclass instances in one query, instead of multiple queries. It also +allows queries for the parent class that use cursors or ordering. + +By default, EclipseLink executes multiple queries to read in a multiple +table inheritance hierarchy, which, in some cases, is the most efficient +way to query. In addition, EclipseLink supports querying the inheritance +hierarchy using +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Reading_Subclasses_on_Queries[a +single outer-join query]. + +You can also set a database view on the descriptor that outer-joins or +unions all of the tables. For more information, see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Multitable_Information[Configuring +Multitable Information]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..fde5ddb02df --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Mappings_(ELUG).adoc @@ -0,0 +1,812 @@ +*TOC* +Special:Whatlinkshere_Introduction_to_Relational_Mappings_(ELUG)[Related +Topics] + +A relational mapping transforms any object data member type to a +corresponding relational database (SQL) data source representation in +any supported relational database. Relational mappings let you map an +object model into a relational data model. + +Relational mappings transform object data members to relational database +fields. Use them to map simple data types including primitives (such as +`+int+`), JDK classes (such as `+String+`), and large object (LOB) +values. You can also use them to transform object data members that +reference other domain objects by way of association where data source +representations require object identity maintenance (such as sequencing +and back references) and possess various types of multiplicity and +navigability. The appropriate mapping class is chosen primarily by the +cardinality of the relationship. + +Do not confuse relational mappings with object-relational data type +mappings (see +link:Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)[Introduction +to Object-Relational Data Type Mappings]). An object-relational data +type mapping transforms certain object data member types to structured +data source representations optimized for storage in specialized +object-relational data type databases such as Oracle9__i__ Database +Server. Object-relational data type mappings let you map an object model +into an object-relational data type data model. In general, you can use +relational mappings with any supported relational database. You can only +use object-relational data type mappings with specialized +object-relational data type databases optimized to support +object-relational data type data source representations. + +For information on mapping concepts and features common to more than one +type of EclipseLink mappings, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings]. + +== Relational Mapping Types + +EclipseLink supports the relational mappings listed in the following +table. + +[#Table 32-1]## + +[width="100%",cols="<24%,<42%,<17%,<17%",options="header",] +|=== +|*Type of Mapping* |*Description* |*EclipseLink Workbench* |*Java* +|link:#Direct-to-Field_Mapping[Direct-to-field] |Map a Java attribute +directly to a database field. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Direct-to-XMLType_Mapping[Direct-to-XMLType] |Map Java attributes +to an `+XMLType+` column in an Oracle Database (introduced in version +9.2.0.1). |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#One-to-One_Mapping[One-to-one] |Map a reference to another +persistent Java object to the database. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#One-to-One_Mapping[Variable one-to-one] |Map a reference to an +interface to the database. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#One-to-Many_Mapping[One-to-many] |Map Java collections of +persistent objects to the database. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Many-to-Many_Mapping[Many-to-many] |Use an association table to +map Java collections of persistent objects to the database. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Collection_Mapping[Aggregate collection] |Map Java collections of +persistent objects to the database. +|image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Direct_Collection_Mapping[Direct collection] |Map Java +collections of objects that do not have descriptors. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Direct_Map_Mapping[Direct map] |Direct map mappings store +instances that implement `+java.util.Map+`. +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Aggregate_Object_Mapping[Aggregate object] |Create strict +one-to-one mappings that require both objects to exist in the same +database row. |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:#Transformation_Mapping[Transformation] |Create custom mappings +where one or more fields can be used to create the object to be stored +in the attribute. |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +== Relational Mapping Concepts + +This section introduces direct mapping concepts unique to EclipseLink, +including the following: + +* link:#Directionality[Directionality] +* link:#Converters_and_Transformers[Converters and Transformers] + +=== Directionality + +The direction of a relationship may be either unidirectional or +bidirectional. In a unidirectional relationship, only one entity bean +has a relationship field that refers to the other. All EclipseLink +relational mappings are unidirectional, from the class being described +(the _source_ class) to the class with which it is associated (the +_target_ class). The target class does not have a reference to the +source class in a unidirectional relationship. + +In a bidirectional relationship, each entity bean has a relationship +field that refers to the other bean. Through the relationship field, an +entity bean’s code can access its related object. To implement a +bidirectional relationship (classes that reference each other), use two +unidirectional mappings with the sources and targets reversed. + +Note: Maintenance of bidirectional relationships presents a number of +technical challenges. + +For more information, see the following: + +Configuring Bidirectional Relationship + +Indirection (Lazy Loading) + +=== Converters and Transformers + +You can store object attributes directly in a database table as follows: + +* link:#Using_a_Direct_Mapping[Direct mapping] +* link:#Using_a_Converter_Mapping[Converter Mapping] +* link:#Using_a_Transformation_Mapping[Transformation mapping] + +==== Using a Direct Mapping + +If the attribute type is comparable to a database type, the information +can be stored directly simply by using a +link:#Direct-to-Field_Mapping[Direct-to-Field Mapping]. + +==== Using a Converter Mapping + +If the attribute type is comparable to a database type but requires +conversion, the information can be stored directly by using a +link:#Direct-to-Field_Mapping[Direct-to-Field Mapping] and an +appropriate `+Converter+` instance. + +If the application’s objects contain attributes that cannot be +represented as direct-to-field with an existing converter, use a +direct-to-field mapping with a custom converter. + +==== Using a Transformation Mapping + +If there is no database primitive type that is logically comparable to +the attribute’s type, or, if an attribute requires data from multiple +fields, it must be transformed on its way to and from the database. + +In this case, use a link:#Transformation_Mapping[transformation +mapping]. + +== Direct-to-Field Mapping + +Use direct-to-field mappings to map primitive object attributes, or non +persistent regular objects, such as the JDK classes. For example, use a +direct-to-field mapping to store a `+String+` attribute in a `+VARCHAR+` +field. + +[#Example 32-1]## *_Direct-to-Field Mapping Example_* + +The link:#Figure_32-1[Direct-to-Field Mapping] figure illustrates a +direct-to-field mapping between the Java attribute `+city+` and the +relational database column `+CITY+`. Similarly, direct-to-field mappings +could be defined from `+country+` to `+COUNTRY+`, `+id+` to +`+ADDRESS_ID+`, `+established+` to `+EST_DATE+`, and `+province+` to +`+PROVINCE+`. + +[#Figure 32-1]## *_Direct-to-Field Mapping_* + +.Direct-to-Field Mapping +image::dtfmpfig.gif[Direct-to-Field +Mapping,title="Direct-to-Field Mapping"] + +You can use a direct-to-field mapping with any of the following +`+Converter+` instances: + +* link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#[Type Conversion Converter] + +You can use a direct-to-field mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]. + +See +link:Configuring%20a%20Relational%20Direct-to-Field%20Mapping_(ELUG)[Configuring +a Relational Direct-to-Field Mapping] for more information. + +== Direct-to-XMLType Mapping + +Using a direct-to-`+XMLType+` mapping, you can map XML data in the form +of a `+String+` or an org`+.w3c.dom.Document+` object to an *XMLType* +column in an Oracle Database (introduced in version 9.2.0.1). + +If you plan to use direct-to-`+XMLType+` mappings in Workbench and the +EclipseLink runtime, you must include the Oracle Database `+xdb.jar+` +file in the Workbench classpath (see +link:Using%20Workbench%20(ELUG)#Configuring_the_Workbench_Environment[Configuring +the Workbench Environment]). + +The EclipseLink query framework provides a number of expression +operators you can use to create queries based on the content of that XML +data (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#XMLType_Functions[XMLType +Functions]). + +See +link:Configuring%20a%20Relational%20Direct-to-XMLType%20Mapping_(ELUG)[Configuring +a Relational Direct-to-XMLType Mapping] for more information. + +== One-to-One Mapping + +One-to-one mappings represent simple pointer references between two Java +objects. In Java, a single pointer stored in an attribute represents the +mapping between the source and target objects. Relational database +tables implement these mappings using foreign keys. + +The link:#Figure_32-2[One-to-One Mappings] figure illustrates a +one-to-one relationship from the `+address+` attribute of an +`+Employee+` object to an `+Address+` object. To store this relationship +in the database, create a one-to-one mapping between the `+address+` +attribute and the `+Address+` class. This mapping stores the `+id+` of +the `+Address+` instance in the `+EMPLOYEE+` table when the `+Employee+` +instance is written. It also links the `+Employee+` instance to the +`+Address+` instance when the `+Employee+` is read from the database. +Because an `+Address+` does not have any references to the `+Employee+`, +it does not have to provide a mapping to `+Employee+`. + +For one-to-one mappings, the source table normally contains a foreign +key reference to a record in the target table. In the +link:#Figure_32-2[One-to-One Mappings] figure, the `+ADDR_ID+` field of +the `+EMPLOYEE+` table is a foreign key. + +[#Figure 32-2]## *_One-to-One Mappings_* + +.One-to-One Mappings +image::onetoone_map_fig.gif[One-to-One +Mappings,title="One-to-One Mappings"] + +You can also implement a one-to-one mapping where the target table +contains a foreign key reference to the source table. In the +link:#Figure_32-2[One-to-One Mappings] figure, the database design would +change such that the `+ADDRESS+` row would contain the `+EMP_ID+` to +identify the `+Employee+` to which it belonged. In this case, the target +must also have a relationship mapping to the source. + +The update, insert and delete operations, which are normally done for +the target before the source for privately owned one-to-one +relationships, are performed in the opposite order when the target owns +the foreign key. Target foreign keys normally occur in bidirectional +one-to-one mappings (see link:#Directionality[Directionality]), because +one side has a foreign key and the other shares the same foreign key in +the other’s table. + +Target foreign keys can also occur when large cascaded composite primary +keys exist (that is, one object’s primary key is composed of the primary +key of many other objects). In this case it is possible to have a +one-to-one mapping that contains both foreign keys and target foreign +keys. + +In a foreign key, EclipseLink automatically updates the foreign key +value in the object’s row. In a target foreign key, it does not. In +EclipseLink, use the *Target Foreign Key* option when a target foreign +key relationship is defined. + +When mapping a relationship, you must understand these differences +between a foreign key and a target foreign key, to ensure that the +relationship is defined correctly. + +In a bidirectional relationship where the two classes in the +relationship reference each other, only one of the mappings should have +a foreign key. The other mapping should have a target foreign key. If +one of the mappings in a bidirectional relationship is a one-to-many +mapping, see +link:Configuring%20a%20Relational%20Variable%20One-to-One%20Mapping%20(ELUG)[Configuring +a Relational Variable One-to-One Mapping] for details. + +You can use a one-to-one mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]. + +See +link:Configuring%20a%20Relational%20One-to-One%20Mapping%20(ELUG)[Configuring +a Relational One-to-One Mapping] for more information. + +== Variable One-to-One Mapping + +Variable class relationships are similar to polymorphic relationships, +except that in this case the target classes are not related through +inheritance (and thus not good candidates for an abstract table), but +through an interface. + +To define variable class relationships in Workbench, use the variable +one-to-one mapping selection, but choose the interface as the reference +class. This makes the mapping a variable one-to-one. When defining +mappings in Java code, use the `+VariableOneToOneMapping+` class. + +EclipseLink supports variable relationships only in one-to-one mappings. +It handles this relationship in two ways: + +* Through the class indicator field (see +link:Configuring%20a%20Relational%20Variable%20One-to-One%20Mapping%20(ELUG)#Configuring_Class_Indicator[Configuring +Class Indicator]). +* Through unique primary key values among target classes implementing +the interface (see +link:Configuring%20a%20Relational%20Variable%20One-to-One%20Mapping%20(ELUG)#Configuring_Unique_Primary_Key[Configuring +Unique Primary Key]). + +[#Figure 32-3]## *_Variable One-to-One Mappings with Class Indicator_* + +.Variable One-to-One Mappings with Class Indicator +image::v11mapfig.gif[Variable One-to-One Mappings with Class +Indicator,title="Variable One-to-One Mappings with Class Indicator"] + +See +link:Configuring%20a%20Relational%20Variable%20One-to-One%20Mapping%20(ELUG)[Configuring +a Relational Variable One-to-One Mapping] for more information. + +== One-to-Many Mapping + +One-to-many mappings are used to represent the relationship between a +single source object and a collection of target objects. They are a good +example of something that is simple to implement in Java using a +`+Collection+` (or other collection types) of target objects, but +difficult to implement using relational databases. + +In a Java `+Collection+`, the owner references its parts. In a +relational database, the parts reference their owner. Relational +databases use this implementation to make querying more efficient. + +The purpose of creating this one-to-one mapping in the target is so that +the foreign key information can be written when the target object is +saved. Alternatives to the one-to-one mapping back reference include the +following: + +* Use a direct-to-field mapping to map the foreign key and maintain its +value in the application. Here the object model does not require a back +reference, but the data model still requires a foreign key in the target +table. +* Use a many-to-many mapping to implement a logical one-to-many. This +has the advantage of not requiring a back reference in the object model +and not requiring a foreign key in the data model. In this model the +many-to-many relation table stores the collection. It is possible to put +a constraint on the join table to enforce that the relation is a logical +one-to-many relationship. + +[#Figure 32-4]## *_One-to-Many Relationships_* + +.One-to-Many Relationships +image::onetomany_map_fig.gif[One-to-Many +Relationships,title="One-to-Many Relationships"] + +[width="100%",cols="<100%",] +|=== +|*_Note_*: The `+phone+` attribute shown in the +link:#Figure_32-4[One-to-Many Relationships] is of type `+Vector+`. You +can use a `+Collection+` interface (or any class that implements the +`+Collection+` interface) for declaring the collection attribute. See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] for details. +|=== + +You can use a many-to-many mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]. + +See +link:Configuring%20a%20Relational%20One-to-Many%20Mapping_(ELUG)[Configuring +a Relational One-to-Many Mapping] for more information. + +== Many-to-Many Mapping + +Many-to-many mappings represent the relationships between a collection +of source objects and a collection of target objects. They require the +creation of an intermediate table for managing the associations between +the source and target records. + +This figure illustrates a many-to-many mapping in Java and in relational +database tables. + +[#Figure 32-5]## *_Many-to-many Relationships_* + +.Many-to-many Relationships +image::mmmapfig.gif[Many-to-many +Relationships,title="Many-to-many Relationships"] + +[width="100%",cols="<100%",] +|=== +|*_Note_*: The `+projects+` attribute shown in the +link:#Figure_32-5[Many-to-many Relationships] figure is of type +`+Vector+`. You can use a `+Collection+` interface (or any class that +implements the `+Collection+` interface) for declaring the collection +attribute. See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] for details. +|=== + +Many-to-many mappings are implemented using a relation table. This table +contains columns for the primary keys of the source and target tables. +Composite primary keys require a column for each field of the composite +key. The intermediate table must be created in the database before using +the many-to-many mapping. + +The target class does not have to implement any behavior for the +many-to-many mappings. If the target class also creates a many-to-many +mapping back to its source, then it can use the same relation table, but +one of the mappings must be set to read-only. If both mappings write to +the table, they can cause collisions. + +Indirection (lazy loading) is enabled by default in a many-to-many +mapping, which requires that the attribute have the +`+ValueHolderInterface+` type or transparent collections. For more +information on indirection, see +link:Introduction%20to%20Mappings%20(ELUG)#Indirection_(Lazy_Loading)[Indirection +(Lazy Loading)]. + +You can use a many-to-many mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]). + +See +link:Configuring%20a%20Relational%20Many-to-Many%20Mapping_(ELUG)#Configuring_Change_Policy[Configuring +a Relational Many-to-Many Mapping] for more information. + +== Aggregate Collection Mapping + +Aggregate collection mappings are used to represent the aggregate +relationship between a single-source object and a collection of target +objects. Unlike the EclipseLink one-to-many mappings, in which there +should be a one-to-one back reference mapping from the target objects to +the source object, there is no back reference required for the aggregate +collection mappings, because the foreign key relationship is resolved by +the aggregation. + +[width="100%",cols="<100%",] +|=== +|*Note*: To use aggregate collections with Workbench, you must use an +amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]), or manually edit the project source to add the +mapping. +|=== + +Although aggregate collection mappings are similar to one-to-many +mappings, they are not replacements for one-to-many mappings. Use +aggregate collections only in situations where the target collections +are of a reasonable size and if having a many-to-one back mapping is +difficult. + +Because one-to-many relationships offer better performance and are more +robust and scalable, consider using a one-to-many relationship rather +than an aggregate collection. In addition, aggregate collections are +privately owned by the source of the relationship and must not be shared +or referenced by other objects. + +This section describes the following: + +* link:#Aggregate_Collection_Mappings_and_Inheritance[Aggregate +Collection Mappings and Inheritance] +* link:#Aggregate_Collection_Mappings_and_EJB[Aggregate Collection +Mappings and EJB] +* link:#How_to_Implement_Aggregate_Collection_Mapping[How to Implement +Aggregate Collection Mappings] + +See +link:Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)[Configuring +a Relational Aggregate Collection Mapping] for more information. + +=== Aggregate Collection Mappings and Inheritance + +Aggregate collection descriptors can use inheritance. You must also +declare subclasses as aggregate collection. The subclasses can have +their own mapped tables, or share the table with their parent class. See +link:Introduction%20to%20Descriptors%20(ELUG)[Descriptors and +Inheritance] for more information on inheritance. + +=== Aggregate Collection Mappings and EJB + +You can use aggregate collection mappings with entity beans if the +source of the relationship is an entity bean or Java object, and the +mapping targets are regular Java objects. Entity beans cannot be the +target of an aggregate object mapping. + +=== How to Implement Aggregate Collection Mappings + +In a Java `+Collection+`, the owner references its parts. In a +relational database, the parts reference their owners. Relational +databases use this implementation to make querying more efficient. + +Aggregate collection mappings require a target table for the target +objects. + +To implement an aggregate collection mapping, the following must take +place: + +* The descriptor of the target class must declare itself to be an +aggregate collection object. Unlike the aggregate object mapping, in +which the target descriptor does not have a specific table to associate +with, there must be a target table for the target object. +* The descriptor of the source class must add an aggregate collection +mapping that specifies the target class. + +== Direct Collection Mapping + +Direct collection mappings store collections of Java objects that are +not EclipseLink-enabled. The object type stored in the direct collection +is typically a Java type, such as `+String+`. + +It is also possible to use direct collection mappings to map a +collection of non-`+String+` objects. For example, it is possible to +have an attribute that contains a collection of `+Integer+` or `+Date+` +instances. The instances stored in the collection can be any type +supported by the database and has a corresponding wrapper class in Java. + +Support for primitive data types such as `+int+` is not provided, +because Java `+Collection+` holds only objects. + +The link:#Figure_32-6[Direct Collection Mappings] figure illustrates how +a direct collection is stored in a separate table with two fields. The +first field is the reference key field, which contains a reference to +the primary key of the instance owning the collection. The second field +contains an object in the collection and is called the direct field. +There is one record in the table for each object in the collection. + +[#Figure 32-6]## *_Direct Collection Mappings_* + +.Direct Collection Mappings +image::dcmapfig.gif[Direct Collection +Mappings,title="Direct Collection Mappings"] + +[width="100%",cols="<100%",] +|=== +|*_Note_*: The `+responsibilities+` attribute shown in the +link:#Figure_32-6[Direct Collection Mappings] figure is of type +`+Vector+`. You can use a `+Collection+` interface (or any class that +implements the `+Collection+` interface) for declaring the collection +attribute. See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[Configuring +Container Policy] for details. +|=== + +Maps are not supported for direct collection because there is no key +value. + +You can use a direct collection mapping with any of the following +`+Converter+` instances: + +* link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Type_Conversion_Converter[Type +Conversion Converter] + +You can use a direct collection mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]). + +See +link:Configuring%20a%20Relational%20Direct%20Collection%20Mapping_(ELUG)[Configuring +a Relational Direct Collection Mapping] for more information. + +== Direct Map Mapping + +Direct map mappings store instances that implement `+java.util.Map+`. +Unlike one-to-many or many-to-many mappings, the keys and values of the +map in this type of mapping are Java objects that do not have +descriptors. The object type stored in the key and the value of direct +map are Java primitive wrapper types such as `+String+` objects. + +The link:#Figure_32-7[Direct Map Mappings] figure illustrates how a +direct map is stored in a separate table with three fields. The first +field (`+EMPID+`) is the reference key field, which contains a reference +to the primary key of the instance owning the collection. The second +field (`+ADDRESS+`) contains an object in the collection and is called +the direct value field. The third field (`+TYPE+`) contains the direct +key field. In this example, the direct map uses a object type converter +for the direct key field, converting the single character *W* in the +database to the full string *Work* in the object (and *H* to *Home*). + +[#Figure 32-7]## *_Direct Map Mappings_* + +.Direct Map Mappings +image::dmmapfig.gif[Direct Map Mappings,title="Direct Map Mappings"] + +You can use a direct collection mapping with any of the following +`+Converter+` instances: + +* link:Introduction%20to%20Mappings%20(ELUG)#Object_Type_Converter[Object +Type Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#Serialized_Object_Converter[Serialized +Object Converter] +* link:Introduction%20to%20Mappings%20(ELUG)#[Type Conversion Converter] + +You can use a direct map mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]). + +See +link:Configuring%20a%20Relational%20Direct%20Map%20Mapping%20(ELUG)[Configuring +a Relational Direct Map Mapping] for more information. + +== Aggregate Object Mapping + +Two objects–a source (parent or owning) object and a target (child or +owned) object–are related by aggregation if there is a strict one-to-one +relationship between them and all the attributes of the target object +can be retrieved from the same table(s) as the source object. This means +that if the source object exists, then the target object must also exist +and if the source object is destroyed, then the target object is also +destroyed. + +An aggregate mapping allows you to associate data members in the target +object with fields in the source object’s underlying database tables. + +You configure the aggregate mapping in the source object’s descriptor. +However, before doing so, you must designate the target object’s +descriptor as an aggregate (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_a_Relational_Descriptor_as_a_Class_or_Aggregate_Type[Configuring +a Relational Descriptor as a Class or Aggregate Type]). + +Aggregate objects are privately owned and should not be shared or +referenced by other objects. + +You cannot configure one-to-one, one-to-many, or many-to-many mappings +from a nonaggregate object to an aggregate target object. + +You can configure such mappings from an aggregate target object to +another nonaggregate object. If you configure a one-to-many mapping from +an aggregate target object to another nonaggregate object, you must +configure a one-to-one mapping from the other object back to the source +object that owns the aggregate (instead of to the aggregate target +object itself). This is because the source object contains the table and +primary key information of the aggregate target. + +You can configure inheritance for a descriptor designated as an +aggregate (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]), however, in this case, _all_ the descriptors in the +inheritance tree must be aggregates. Aggregate and class descriptors +cannot exist in the same inheritance tree. + +This section describes the following: + +* link:#Aggregate_Object_Mappings_with_a_Single_Source_Object[Aggregate +Object Mappings with a Single Source Object] +* link:#Aggregate_Object_Mappings_with_Multiple_Source_Objects[Aggregate +Object Mappings with Multiple Source Objects] +* link:#How_to_Implement_an_Aggregate_Object_Relationship_Mapping[How to +Implement an Aggregate Object Relationship Mapping] + +You can use an aggregate object mapping with a +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[change +policy]. + +For more information on configuring an aggregate object relationship +mapping, see +link:Configuring%20a%20Relational%20Aggregate%20Object%20Mapping_(ELUG)[Configuring +a Relational Aggregate Object Mapping]. + +=== Aggregate Object Mappings with a Single Source Object + +The link:#Figure_32-8[Aggregate Object Mapping with a Single Source +Object] figure shows an example aggregate object mapping between source +object `+Employee+` and target object `+Period+`. In this example, the +target object is not shared by other types of source object. + +[#Figure 32-8]## *_Aggregate Object Mapping with a Single Source +Object_* + +.Aggregate Object Mapping with a Single Source Object +image::agmapfig.gif[Aggregate Object Mapping with a Single Source +Object,title="Aggregate Object Mapping with a Single Source Object"] + +Aggregate target classes not shared among multiple source classes can +have any type of mapping, including other aggregate object mappings. + +=== Aggregate Object Mappings with Multiple Source Objects + +The link:#Figure_32-9[Aggregate Object Mapping with Multiple Source +Objects] figure shows an example aggregate object mapping in which +different source objects–`+Employee+` and `+Project+`–map instances of +the same type of target object, `+Period+`. + +[#Figure 32-9]## *_Aggregate Object Mapping with Multiple Source +Objects_* + +.Aggregate Object Mapping with Multiple Source Objects +image::agmultiple.gif[Aggregate Object Mapping with Multiple Source +Objects,title="Aggregate Object Mapping with Multiple Source Objects"] + +When you configure the aggregate object mapping in the source object, +you choose the source object table for that particular mapping. This +allows different source types to store the same target information +within their tables. Each source object’s table may use different field +names. EclipseLink automatically manages the case where multiple source +object tables use different field names. + +For example, in the link:#Figure_32-9[Aggregate Object Mapping with +Multiple Source Objects] figure, The `+Employee+` attribute +`+employPeriod+` is mapped by an aggregate object mapping to target +object `+Period+`. This mapping associates `+Period+` attribute +`+startDate+` with `+EMPLOYEE+` table field `+START_DATE+`. The +`+Project+` attribute `+projectPeriod+` is also mapped by an aggregate +object mapping to target object `+Period+`. This mapping associates +`+Period+` attribute `+startDate+` with `+PROJECT+` table field +`+S_DATE+`. + +Aggregate target classes shared with multiple source classes cannot have +one-to-many or many-to-many mappings. + +=== How to Implement an Aggregate Object Relationship Mapping + +You must ensure that the following takes place: + +* The descriptor of the target class declares itself to be an aggregate +object. Because all its information comes from its parent’s table(s), +the target descriptor does not have a specific table associated with it. +You must, however, choose one or more candidate table(s) from which you +can use fields in mapping the target.In the example above, you could +choose the `+EMPLOYEE+` table so that the `+START_DATE+` and +`+END_DATE+` fields are available during mapping. +* The descriptor of the source class adds an aggregate object mapping +that specifies the target class. In the example above, the `+Employee+` +class has an attribute called `+employPeriod+` that would be mapped as +an aggregate object mapping with `+Period+` as the reference class. The +source class must ensure that its table has fields that correspond to +the field names registered with the target class. +* If a source object has a `+null+` target reference, EclipseLink writes +`+null+` values to the aggregate database fields (see +link:Configuring%20a%20Relational%20Aggregate%20Object%20Mapping_(ELUG)#Configuring_Allowing_Null_Values[Configuring +Allowing Null Values]). When the source is read from the database, it +can handle this `+null+` target in one of two ways: +** Create an instance of the object with all its attributes equal to +`+null+`. +** Put a `+null+` reference in the source object without instantiating a +target. (This is the default method of handling `+null+` targets.) + +== Transformation Mapping + +Use transformation mappings for specialized translations for how a value +is represented in Java and how it is represented in the database. + +[width="100%",cols="<100%",] +|=== +|*Tip*: Use transformation mappings only when mapping multiple fields +into a single attribute. Because of the complexity of transformation +mappings, it is often easier to perform the transformation with a +converter or getter and setter methods of a direct-to-field mapping. See +link:Configuring%20a%20Relational%20Direct-to-Field%20Mapping_(ELUG)[Configuring +a Relational Direct-to-Field Mapping] for more information. +|=== + +The link:#Figure_32-10[Transformation Mappings] figure illustrates a +transformation mapping. The values from the `+B_DATE+` and `+B_TIME+` +fields are used to create a `+java.util.Date+` to be stored in the +`+birthDate+` attribute. + +[#'Figure 32-10]## *_Transformation Mappings_* + +.Transformation Mappings +image::trmapfig.gif[Transformation +Mappings,title="Transformation Mappings"] + +Often, a transformation mapping is appropriate when values from multiple +fields are used to create an object. This type of mapping requires that +you provide an _attribute transformation_ that is invoked when reading +the object from the database. This must have at least one parameter that +is an instance of `+Record+`. In your attribute transformation, you can +use `+Record+` method `+get+` to retrieve the value in a specific +column. Your attribute transformation can specify a second parameter, +when it is an instance of `+Session+`. The `+Session+` performs queries +on the database to get additional values needed in the transformation. +The transformation should _return_ the value to be stored in the +attribute. + +Transformation mappings also require a _field transformation_ for each +field, to be written to the database when the object is saved. The +transformation returns the value to be stored in that field. + +See +link:Configuring%20a%20Relational%20Transformation%20Mapping%20(ELUG)[Configuring +a Relational Transformation Mapping] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Projects_(ELUG).adoc new file mode 100644 index 00000000000..b30ec37f633 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Introduction_to_Relational_Projects_(ELUG).adoc @@ -0,0 +1,571 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_Relational_Projects_(ELUG)[Related +Topics] + +This section provides an overview of relational projects and focuses on +building these projects for relational and object-relational data type +databases. + +For information on project concepts and features common to more than one +type of EclipseLink projects, see +link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects]. + +== Building Relational Projects + +Use a relational project for transactional persistence of Java objects +to a conventional _relational_ database or to an _object-relational data +type_ database that supports data types specialized for object storage, +both accessed using JDBC. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are using Workbench, you must add your JDBC driver to +the Workbench classpath. For more information, see +link:Using%20Workbench%20(ELUG)#Configuring_the_Workbench_Environment[Configuring +the Workbench Environment]. +|=== + +In a relational project, you can make full use of EclipseLink queries +and expressions (see +link:EclipseLink_UserGuide_Queries_%28ELUG%29[Queries]). + +=== How to Build Relational Projects for a Relational Database + +The Workbench provides complete support for creating relational projects +that map Java objects to a conventional relational database accessed +using JDBC. + +[[Table 23-1]] + +*_Components of a Relational Project for a Relational Database_* + +[width="100%",cols="<10%,<90%",options="header",] +|=== +|*Component* |*Supported Types* +|Data Source +|link:Introduction%20to%20Data%20Access%20(ELUG)[DatabaseLogin] or +link:Introduction%20to%20Data%20Access%20(ELUG)[Database Platforms] + +|Descriptors +|link:Introduction%20to%20Relational%20Descriptors%20(ELUG)[Relational +Descriptors] + +|Mappings |link:Relational_Mappings_(ELUG)[Relational Mappings] +|=== + +For more information, see +link:Creating%20a%20Relational%20Project%20(ELUG)#Creating_a_Relational_Project[Creating +a Relational Project]. + +=== How to Build Relational Projects for an Object-Relational Data Type Database + +The Workbench does not currently support relational projects for an +object-relational data type database. You must create such a relational +project in Java. + +Using Java, you can create a relational project for transactional +persistence of Java objects to an object-relational data type database +that supports data types specialized for object storage (such as Oracle +Database) accessed using JDBC. + +When using EclipseLink to build a relational project for an +object-relational data type database, consider the following: + +* You must create a Java class and an EclipseLink +`+ObjectRelationalDescriptor+` for each structured type +(`+Struct/object-type+`). +* EclipseLink supports only arrays (`+Varrays+`) of basic types or +arrays on structured types (`+Struct/object-type+`). EclipseLink does +not support arrays of `+Refs+` or arrays of nested tables. +* EclipseLink supports only nested tables of `+Refs+`. EclipseLink does +not support nested tables of basic types, structured types, or array +types. + +The general development process for building a relational project for an +object-relational data type database is as follows: + +[arabic] +. Define structured object-types in the database. +. Define tables of the structured object-types in the database. +. Define the Java classes that will map to the structured object-types. +. link:Creating%20a%20Project%20(ELUG)[Create a relational project]. +. link:Creating%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)[Create +an object-relational data type descriptor for each Java class]. +. Create object-relational data type mappings from each persistent field +of each Java class to the corresponding object-types and object-type +tables. For more information, see the following: +* link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping] +* link:Configuring%20an%20Object-Relational%20Data%20Type%20Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] + +[[Table 23-2]] + +*_Components of a Relational Project for an Object-Relational Data Type +Database_* + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*Component* |*Supported Types* +|Data Source +|link:Introduction%20to%20Data%20Access%20(ELUG)#DatabaseLogin[DatabaseLogin] +or +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms] + +|Descriptors +|link:Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)[Object-Relational +Data Type Descriptors] + +|Mappings +|link:Object-Relational_Data_Type_Mappings_(ELUG)[Object-Relational Data +Type Mappings] +|=== + +For more information, see +link:Creating%20a%20Relational%20Project%20(ELUG)#Creating_a_Relational_Project[Creating +a Relational Project]. + +== Sequencing in Relational Projects + +In an relational project, you store persistent objects for your +application in database tables that represent the class of instantiated +object. As the link:#Figure_23-1[Sequencing Elements in a Class Database +Table] figure shows, each row of the VEHICLE_POOL table represents an +instantiated object from that class, and the VEH_ID column holds the +primary key for each object. + +[#Figure 23-1]## *_Sequencing Elements in a Class Database Table_* + +.Sequencing Elements in a Class Database Table +image::seqtable.gif[Sequencing Elements in a Class Database +Table,title="Sequencing Elements in a Class Database Table"] + +You configure EclipseLink sequencing at the +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[Project +Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Session +Level] to tell EclipseLink how to obtain values for the primary key +column: that is, whatlink:#Sequencing_Types[type of sequencing to use]. + +You configure EclipseLink +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[configure +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. + +[width="100%",cols="<100%",] +|=== +|*Note:* When choosing a column type for a primary key value, ensure +that the type provides a suitable precision. For example, if you use a +`+TIMESTAMP+` type but your database platform’s `+TIMESTAMP+` is defined +only to the second, then identical values may be returned for objects +created within the same second. +|=== + +This section describes the following: + +* link:#Sequencing_Configuration_Options[Sequencing Configuration +Options] +* link:#Sequencing_Types[Sequencing Types] +* link:#Sequencing_and_Preallocation_Size[Sequencing and Preallocation +Size] + +=== Sequencing Configuration Options + +You can configure sequencing using either the Workbench or Java (but not +both). + +Using the Workbench, create one sequence with a single preallocation +size that applies to all descriptors that require sequencing. You can +configure link:#Table_Sequencing[Table Sequencing] or native sequencing +(see link:#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform]). If you choose table +sequencing, you can either use default table and column names or specify +your own (see link:#Default_Versus_Custom_Sequence_Table[Default Versus +Custom Sequence Table]). + +Using Java, you can configure any sequence type that EclipseLink +supports (see link:#Sequencing_Types[Sequencing Types]). You can create +any number and combination of sequences per project. You can create a +sequence object explicitly or use the platform +link:#Default_Sequencing[Default Sequencing]. You can associate the same +sequence with more than one descriptor or associate different sequences +(and different sequence types) to various descriptors. You can configure +a separate preallocation size for each descriptor’s sequence. For more +information, see +link:Configuring%20a%20Database%20Login%20(ELUG)#How_to_Configure_Sequencing_at_the_Session_Level_Using_Java[How +to Configure Sequencing at the Session Level Using Java]. + +=== Sequencing Types + +EclipseLink supports the following sequence types: + +* link:#Table_Sequencing[Table Sequencing] +* link:#Unary_Table_Sequencing[Unary Table Sequencing] +* link:#Query_Sequencing[Query Sequencing] +* link:#Default_Sequencing[Default Sequencing] +* link:#Native_Sequencing_with_an_Oracle_Database_Platform[Native +Sequencing with an Oracle Database Platform] +* link:#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform] + +==== Table Sequencing + +With table sequencing, you create a single database table that includes +sequencing information for one or more sequenced objects in the project. +EclipseLink maintains this table to track sequence numbers for these +object types. + +As the link:#Figure_23-2[EclipseLink Table Sequence Table] figure shows, +the table may contain sequencing information for more than one class +that uses sequencing. The default table is called `+SEQUENCE+` and +contains two columns: + +* `+SEQ_NAME+`, which specifies the class type to which the selected row +refers +* `+SEQ_COUNT+`, which specifies the highest sequence number currently +allocated for the object represented in the selected row + +[#Figure 23-2]## *_EclipseLink Table Sequence Table_* + +.EclipseLink Table Sequence Table +image::seqtblmn.gif[EclipseLink Table Sequence +Table,title="EclipseLink Table Sequence Table"] + +The rows of the `+SEQUENCE+` table represent each sequence object: one +for each class that participates in sequencing or a single sequence +object across several classes so that they can benefit from the same +preallocation pool. When you configure +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Sequencing +at the Descriptor Level], you specify the `+SEQ_NAME+` for the class. +Add a row with that name to the `+SEQUENCE+` table and initialize the +`+SEQ_COUNT+` column to the value . + +Each time a new instance of a class is created, EclipseLink obtains the +required sequence value. For efficiency, EclipseLink uses preallocation +to reduce the number of table accesses required to obtain sequence +values (see link:#Sequencing_and_Preallocation_Size[Sequencing and +Preallocation Size]). + +You can create the `+SEQUENCE+` table on the database in one of two +ways: + +* Use the Workbench to create the table. See +link:Using%20Workbench%20(ELUG)#Generating_Tables_on_the_Database[Generating +Tables on the Database] for more information. +* Use the EclipseLink table creator to create and update the table +manually. See +link:Using%20Workbench%20(ELUG)#Generating_SQL_Creation_Scripts[Generating +SQL Creation Scripts] for more information. + +You can configure table sequencing using the Workbench or Java. For more +information about configuring table sequencing, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]. + +===== Default Versus Custom Sequence Table + +In most cases, you implement table sequencing using the default table +and column names. However, you may want to specify your own table and +column names if the following holds true: + +* You want to use an existing sequence table for sequencing. +* You do not want to use the default naming convention for the table and +its columns. + +==== Unary Table Sequencing + +Although similar to link:#Table_Sequencing[Table Sequencing], with unary +table sequencing, you create a separate sequence table for each +sequenced object in the project. + +As this figure shows, sequencing information appears in the table for a +single class that uses sequencing. You can name the table anything you +want but it must contain only one column named (by default) +`+SEQUENCE+`. + +[#Figure 23-3]## *_EclipseLink Unary Table Sequence Table_* + +.EclipseLink Unary Table Sequence Table +image::seqtblun.gif[EclipseLink Unary Table Sequence +Table,title="EclipseLink Unary Table Sequence Table"] + +When you configure sequencing at the descriptor level, you specify the +sequence name for the class: this is the name of the unary table +sequence table. The link:#Figure_23-3[EclipseLink Unary Table Sequence +Table] figure shows a unary table sequence for the `+Employee+` class. +The `+Employee+` class descriptor is configured (see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_Sequencing_at_the_Descriptor_Level[Configuring +Sequencing at the Descriptor Level]) with a sequence name of `+EMP_SEQ+` +to match the unary table sequence table name. EclipseLink adds a row to +this table and initializes the `+SEQUENCE+` column to the value `+1+`. + +Each time a new class is created, EclipseLink obtains the required +sequence value from the single row of the unary sequence table +corresponding to the class. For efficiency, EclipseLink uses +preallocation to reduce the number of table accesses required to obtain +sequence values (see link:#Sequencing_and_Preallocation_Size[Sequencing +and Preallocation Size]). + +You can create the unary table sequence table on the database in one of +two ways: + +* Use the Workbench to create the table. See +link:Using%20Workbench%20(ELUG)#Generating_Tables_on_the_Database[Generating +Tables on the Database] for more information. +* Use the EclipseLink table creator to create and update the table +manually. See +link:Using%20Workbench%20(ELUG)#Generating_SQL_Creation_Scripts[Generating +SQL Creation Scripts] for more information. + +Currently, you can only configure unary table sequencing in Java using +the `+UnaryTableSequence+` class (for more information, see +link:Configuring%20a%20Database%20Login%20(ELUG)#How_to_Configure_Sequencing_at_the_Session_Level_Using_Java[How +to Configure Sequencing at the Session Level Using Java] "`wikilink`")). + +==== Query Sequencing + +With query sequencing, you can access a sequence resource using custom +read (`+ValueReadQuery+`) and update (`+DataModifyQuery+`) queries and a +preallocation size that you specify. This allows you to perform +sequencing using stored procedures and allows you to access sequence +resources that are not supported by the other sequencing types that +EclipseLink provides. + +Currently, you can only configure query sequencing in Java using the +`+QuerySequence+` class (for more information, see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Query_Sequencing[Configuring +Query Sequencing]). + +==== Default Sequencing + +The platform owned by a login is responsible for providing a default +sequence instance appropriate for the platform type. For example, by +default, a `+DatabasePlatform+` provides a table sequence using the +default table and column names (see link:#Table_Sequencing[Table +Sequencing]). + +You can access this default sequence directly using `+DatasourceLogin+` +method `+getDefaultSequence+`, or indirectly by using the +`+DefaultSequence+` class, a wrapper for the platform default sequence. + +If you associate a descriptor with a nonexistent sequence, the +EclipseLink runtime will create an instance of `+DefaultSequence+` to +provide sequencing for that descriptor. For more information, see +link:Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring_the_Platform_Default_Sequence[Configuring +the Platform Default Sequence]. + +The main purpose of the `+DefaultSequence+` is to allow a sequence to +use a different pre-allocation size than the project default. + +Currently, you can only make use of default sequencing in Java (for more +information, see +link:Configuring%20a%20Database%20Login%20(ELUG)#Using_the_Platform_Default_Sequence[Using +the Platform Default Sequence]). + +==== Native Sequencing with an Oracle Database Platform + +EclipseLink support for native sequencing with Oracle Databases is +similar to table sequencing (see link:#Table_Sequencing[Table +Sequencing]), except that EclipseLink does not maintain a table in the +database. Instead, the database contains a sequence object that stores +the current maximum number and preallocation size for sequenced objects. +The sequence name configured at the descriptor level identifies the +sequence object responsible for providing sequencing values for the +descriptor’s reference class. + +You can configure native sequencing using Workbench or Java. For more +information about configuring table sequencing, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]. + +===== Understanding the Oracle SEQUENCE Object + +The Oracle `+SEQUENCE+` object implements a strategy that closely +resembles EclipseLink sequencing: it implements an `+INCREMENT+` +construct that parallels the EclipseLink preallocation size, and a +`+sequence.nextval+` construct that parallels the `+SEQ_COUNT+` field in +the EclipseLink `+SEQUENCE+` table in table sequencing. This +implementation enables EclipseLink to use the Oracle `+SEQUENCE+` object +as if it were an EclipseLink `+SEQUENCE+` table, but eliminates the need +for EclipseLink to create and maintain the table. + +As with table sequencing, EclipseLink creates a pool of available +numbers by requesting that the Oracle `+SEQUENCE+` object increment the +`+sequence.nextval+` and return the result. Oracle adds the value, +`+INCREMENT+`, to the `+sequence.nextval+`, and EclipseLink uses the +result to build the sequencing pool. + +The key difference between this process and the process involved in +table sequencing is that EclipseLink is unaware of the `+INCREMENT+` +construct on the `+SEQUENCE+` object. EclipseLink sequencing and the +Oracle `+SEQUENCE+` object operate in isolation. To avoid sequencing +errors in the application, set the EclipseLink preallocation size and +the Oracle `+SEQUENCE+` object `+INCREMENT+` to the same value. Note +that the Oracle sequence object must have a starting value equal to the +preallocation size because when EclipseLink gets the next sequence +value, it assume it has the previous preallocation size of values. + +===== Using SEQUENCE Objects + +Your database administrator (DBA) must create a `+SEQUENCE+` object on +the database for every sequencing series your application requires. If +every class in your application requires its own sequence, the DBA +creates a `+SEQUENCE+` object for every class; if you design several +classes to share a sequence, the DBA need create only one `+SEQUENCE+` +object for those classes. + +For example, in the link:#Figure_23-4[Example of Database Tables–Racquet +Information] figure, consider the case of a sporting goods manufacturer +that manufactures three styles of tennis racquet. The data for these +styles of racquet are stored in the database as follows: + +* Each style of racquet has its own class table. +* Each manufactured racquet is an object represented by a line in the +class table. +* The system assigns serial numbers to the racquets that use sequencing. + +[#Figure 23-4]## *_Example of Database Tables–Racquet Information_* + +.Example of Database Tables–Racquet Information +image::orseqa.gif[Example of Database Tables–Racquet +Information,title="Example of Database Tables–Racquet Information"] + +The manufacturer can do either of the following: + +* _Use separate sequencing for each racquet style._ The DBA builds three +separate `+SEQUENCE+` objects, perhaps called `+ATTACK_SEQ+`, +`+VOLLEY_SEQ+`, and `+PROX_SEQ+`. Each different racquet line has its +own serial number series, and there may be duplication of serial numbers +between the lines (for example: all three styles may include a racquet +with serial number 1234). +* _Use a single sequencing series for all racquets._ The DBA builds a +single `+SEQUENCE+` object (perhaps called `+RACQUET_SEQ+`). The +manufacturer assigns serial numbers to racquets as they are produced, +without regard for the style of racquet. + +==== Native Sequencing with a Non-Oracle Database Platform + +Several databases support a type of native sequencing in which the +database management system generates the sequence numbers. + +When you create a database table for a class that uses native +sequencing, include a primary key column, and set the column type as +follows: + +* For Sybase and Microsoft SQL Server databases, set the primary key +field to the type `+IDENTITY+`. +* For IBM Informix databases, set the primary key field to the type +`+SERIAL+`. +* For IBM DB2 databases, set the primary key field to the type +`+IDENTITY+`. + +When you insert a new object into the table, EclipseLink populates the +object before insertion into the table, but does not include the +sequence number. As the database inserts the object into its table, the +database automatically populates the primary key field with a value +equal to the primary key of the previous object plus `+1+`. + +At this point, and before the transaction closes, EclipseLink reads back +the primary key for the new object so that the object has an identity in +the EclipseLink cache. + +[width="100%",cols="<100%",] +|=== +|*Note:* This type of sequencing does not support preallocation, so the +preallocation size must be set to 1. To take advantage of sequence +preallocation, we recommend that you use table sequencing on these +databases instead of native sequencing. +|=== + +If your database provides native sequencing, but EclipseLink does not +directly support it, you may be able to access the native sequence +object using a query sequence and stored procedures. For more +information, see link:#Query_Sequencing[Query Sequencing]. + +You can configure native sequencing using Workbench or Java. We +recommend that you use the Workbench. For more information about +configuring table sequencing, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]. + +=== Sequencing and Preallocation Size + +To improve sequencing efficiency, EclipseLink lets you preallocate +sequence numbers. Preallocation enables EclipseLink to build a pool of +available sequence numbers that are assigned to new objects as they are +created and inserted into the database. EclipseLink assigns numbers from +the sequence pool until the pool is empty. + +The preallocation size specifies the size of the pool of available +numbers. Preallocation improves sequencing efficiency by substantially +reducing the number of database accesses required by sequencing. By +default, EclipseLink sets preallocation size to `+50+`. You can specify +preallocation size either in the Workbench or as part of the session +login. + +Preallocation size configuration applies to table sequencing and Oracle +native sequencing. In Oracle native sequencing, the sequence +preallocation size must match the Oracle sequence object increment size. +Preallocation is not available for native sequencing in other databases +as they use an auto-assigned sequence column. We recommend that you use +table sequencing in non-Oracle databases to allow preallocation. + +For table sequencing, EclipseLink maintains a pool of preallocated +values for each sequenced class. When EclipseLink exhausts this pool of +values, it acquires a new pool of values, as follows: + +[arabic] +. EclipseLink accesses the database, requesting that the `+SEQ_COUNT+` +for the given class (identified by the `+SEQ_NAME+`) be incremented by +the preallocation size and the result returned. For example, consider +the `+SEQUENCE+` table in the link:#Figure_23-2[EclipseLink Table +Sequence Table] figure. If you create a new purchase order and +EclipseLink has exhausted its pool of sequence numbers, then EclipseLink +executes a SQL statement to increment `+SEQ_COUNT+` for +`+SEQ_PURCH_ORDER+` by the preallocation size (in this case, the +EclipseLink default of `+50+`). The database increments `+SEQ_COUNT+` +for `+SEQ_PURCH_ORDER+` to `+1600+` and returns this number to +EclipseLink. +. EclipseLink calculates a maximum and a minimum value for the new +sequence number pool, and creates the pool of values. +. EclipseLink populates the object sequence attribute with the first +number in the pool and writes the object to the class table. + +As you add new objects to the class table, EclipseLink continues to +assign values from the pool until it exhausts the pool. When the pool is +exhausted, EclipseLink again requests new values from the table. + +Using the Workbench, you specify a preallocation size when you choose a +sequencing type at the project or session level. That preallocation size +applies to all descriptors. + +Using Java, you can specify a different preallocation size for each +sequence that you create. + +For more information about configuring preallocation size, see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Sequencing_at_the_Project_Level[Configuring +Sequencing at the Project Level] or +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Sequencing_at_the_Session_Level[Configuring +Sequencing at the Session Level]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..d9b4441c563 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Descriptors_(ELUG).adoc @@ -0,0 +1,32 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +== Object-Relational Data Type Descriptors + +The following sections contain general information about +object-relational data type descriptors, as well as detailed information +on how to create and configure these descriptors: + +* link:Introduction_to_Object-Relational_Data_Type_Descriptors_(ELUG)[Introduction +to Object-Relational Data Type Descriptors] + +* link:Creating_an_Object-Relational_Data_Type_Descriptor_(ELUG)[Creating +an Object-Relational Data Type Descriptor] + +* link:Configuring_an_Object-Relational_Data_Type_Descriptor_(ELUG)[Configuring +an Object-Relational Data Type Descriptor] – explains how to configure +descriptor options specific to an object-relational data type +descriptor. + +*Special:Whatlinkshere_Object-Relational_Data_Type_Descriptors_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..cfe07283dbe --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Object-Relational_Data_Type_Mappings_(ELUG).adoc @@ -0,0 +1,35 @@ +== Object-Relational Data Type Mappings + +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +An object-relational data type mapping taransforms certain object data +member types to structured data source representations optimized for +storage in specialized object-relational data type databases (such as +Oracle Database). Object-relational data type mappings let you map an +object model into an object-relational data type data model. + +Consider the following sections: + +* link:Introduction_to_Object-Relational_Data_Type_Mappings_(ELUG)[Introduction +to Object-Relational Data Type Mappings] – describes each of the +different EclipseLink object-relational data type mapping types and +important object-relational data type mapping concepts. + +* link:Configuring_an_Object-Relational_Data_Type_Mapping_(ELUG)[Configuring +an Object-Relational Data Type Mapping] – explains how to configure +EclipseLink object-relational data type mapping options common to two or +more object-relational data type mapping types. + +*Special:Whatlinkshere_Object-Relational_Data_Type_Mappings_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Optimizing_the_EclipseLink_Application_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Optimizing_the_EclipseLink_Application_(ELUG).adoc new file mode 100644 index 00000000000..3a714c8f859 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Optimizing_the_EclipseLink_Application_(ELUG).adoc @@ -0,0 +1,2618 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Optimizing_the_EclipseLink_Application_(ELUG)[Related +Topics] + +EclipseLink provides a diverse set of features to measure and optimize +application performance. You can enable or disable most features in the +descriptors or session, making any resulting performance gains global. + +== Introduction to Optimization + +Performance considerations are present at every step of the development +cycle. Although this implies an awareness of performance issues in your +design and implementation, it does not mean that you should expect to +achieve the best possible performance in your first pass. + +For example, if optimization complicates the design, leave it until the +final development phase. You should still plan for these optimizations +from your first iteration, to make them easier to integrate later. + +The most important concept associated with tuning your EclipseLink +application is the idea of an iterative approach. The most effective way +to tune your application is to do the following: + +[arabic] +. link:#Measuring_EclipseLink_Performance_with_the_EclipseLink_Profiler[Measure +EclipseLink Performance with the EclipseLink Profiler]. +. link:#Identifying_Sources_of_Application_Performance_Problems[Identify +sources of application performance problems] and modify application +components; +. Measure performance again. + +To identify the changes that improve your application performance, +modify only one or two components at a time. You should also tune your +application in a nonproduction environment before you deploy the +application. + +== Identifying Sources of Application Performance Problems + +For various parts of an EclipseLink-enabled application, this section +describes the performance problems most commonly encountered and +provides suggestions for improving performance. Areas of the application +where performance problems could occur include the following: + +* link:#Identifying_General_Performance_Optimization[Identifying General +Performance Optimization] +* link:#Optimizing_Schema[Schema] +* link:#Optimizing_Mappings_and_Descriptors[Mappings and Descriptors] +* link:#Optimizing_Sessions[Sessions] +* link:#Optimizing_Cache[Cache] +* link:#Optimizing_Data_Access[Data Access] +* link:#Optimizing_Queries[Queries] +* link:#Optimizing_the_Unit_of_Work[Unit of Work] +* link:#Optimizing_the_Application_Server_and_Database_Optimization[Application +Server and Database Optimization] + +== Measuring EclipseLink Performance with the EclipseLink Profiler + +The most important challenge to performance tuning is knowing what to +optimize. To improve the performance of your application, identify the +areas of your application that do not operate at peak efficiency. The +EclipseLink performance profiler helps you identify performance problems +by logging performance statistics for every executed query in a given +session. + +[width="100%",cols="<100%",] +|=== +|*Note*: You should also consider using general performance profilers +such as JDeveloper or JProbe to analyze performance problems. These +tools can provide more detail that may be required to properly diagnose +a problem. +|=== + +The EclipseLink performance profiler logs the following information to +the EclipseLink log file (for general information about EclipseLink +logging, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging[Logging]): + +* query class; +* domain class; +* total time, total execution time of the query, including any nested +queries (in milliseconds); +* local time, execution time of the query, excluding any nested queries +(in milliseconds); +* number of objects, the total number of objects affected; +* number of objects handled per second; +* logging, the amount of time spent printing logging messages (in +milliseconds); +* SQL prepare, the amount of time spent preparing the SQL script (in +milliseconds); +* SQL execute, the amount of time spent executing the SQL script (in +milliseconds); +* row fetch, the amount of time spent fetching rows from the database +(in milliseconds); +* cache, the amount of time spent searching or updating the object cache +(in milliseconds); +* object build, the amount of time spent building the domain object (in +milliseconds); +* query prepare, the amount of time spent to prepare the query prior to +execution (in milliseconds); +* SQL generation, the amount of time spent to generate the SQL script +before it is sent to the database (in milliseconds). + +Note: Use the EclipseLink profiler to profile single-threaded finite use +cases to determine the bottle neck. + +Do not use the EclipseLink profiler to enable monitoring of a +long-running multi-threaded server. + +This section includes information on the following topics: + +* link:#How_to_Configure_the_EclipseLink_Performance_Profiler[How to +Configure the EclipseLink Performance Profiler] +* link:#How_to_Access_the_EclipseLink_Profiler_Results[How to Access the +EclipseLink Profiler Results] + +=== How to Configure the EclipseLink Performance Profiler + +To enable the EclipseLink performance profiler, select the *EclipseLink* +profiler option when configuring your session (see +link:Configuring%20a%20Session%20(ELUG)#Configuring_a_Performance_Profiler[Configuring +a Performance Profiler]). + +When using JPA the profiler can be set in your `+persistence.xml+` +through the persistence property `+"eclipselink.profiler"+` to +`+"PerformanceProfiler"+`. See the `+ProfilerType+` in the `+config+` +package for other profiling options. + +The EclipseLink performance profiler is an instance of +`+org.eclipse.persistence.tools.profiler.PerformanceProfiler+` class. It +provides the following public API: + +* `+logProfile+` – enables the profiler; +* `+dontLogProfile+` – disables the profiler; +* `+logProfileSummary+` – organizes the profiler log into a summary of +all the individual operation profiles including operation statistics +like the shortest time of all the operations that were profiled, the +total time of all the operations, the number of objects returned by +profiled queries, and the total time that was spent in each kind of +operation that was profiled; +* `+logProfileSummaryByQuery+` – organizes the profiler log into a +summary of all the individual operation profiles by query; +* `+logProfileSummaryByClass+` – organizes the profiler log into a +summary of all the individual operation profiles by class. + +=== How to Access the EclipseLink Profiler Results + +The simplest way to view EclipseLink profiler results is to read the +EclipseLink log files with a text editor. For general information about +EclipseLink logging, such as logging file location, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging[Logging]. + +This example shows an example of the EclipseLink profiler output. + +[#Example 11-1]## *_Performance Profiler Output_* + +[source,text] +---- +Begin Profile of{ +ReadAllQuery(com.demos.employee.domain.Employee) +Profile(ReadAllQuery,# of obj=12, time=1399,sql execute=217, +prepare=495, row fetch=390, time/obj=116,obj/sec=8) +} End Profile +---- + +The second line of the profile contains the following information about +a query: + +* *Vote for enhancement bug# http://bugs.eclipse.org/310820[310820] if +you would like to see nanosecond (10^6 ms) resolution* +* `+ReadAllQuery(com.demos.employee.domain.Employee)+`: specific query +profiled, and its arguments. +* `+Profile(ReadAllQuery+`: start of the profile and the type of query. +* `+# of obj=12+`: number of objects involved in the query. +* `+time=1399+`: total execution time of the query (in milliseconds). +* `+sql execute=217+`: total time spent executing the SQL statement. +* `+prepare=495+`: total time spent preparing the SQL statement. +* `+row fetch=390+`: total time spent fetching rows from the database. +* `+time/obj=116+`: number of milliseconds spent on each object. +* `+obj/sec=8+`: number of objects handled per second. + +== Identifying General Performance Optimization + +In general, avoid overriding EclipseLink default behavior unless your +application requires it. Some EclipseLink defaults are suitable for a +development environment; you should change these defaults to suit your +production environment (see +link:#Optimizing_for_a_Production_Environment[Optimizing for a +Production Environment]). + +Use the Workbench rather than manual coding. These tools are not only +easy to use: the default configuration they export to deployment XML +(and the code it generates, if required) represents best practices +optimized for most applications. + +== Optimizing for a Production Environment + +Some EclipseLink defaults are suitable for a development environment but +we recommend that you change these to suit your production environment +for optimal performance. These defaults include: + +* Batch writing: enable. For more information, see +link:#How_to_Use_Batch_Writing_for_Optimization[How to Use Batch Writing +for Optimization]. +* Statement caching: enable either in EclipseLink when using an internal +connection pool or in the data source when using an external connection +pool and choose a statement cache size appropriate for your application. +For more information, see +link:#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. +* Read and write connection pool size: increase to the desired number of +concurrent threads (for example, 50). For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[Connection +Pools]. +* Session cache size: increase to the desired number of objects to be +cached in memory (for example, 1000). Note that you can configure +session cache size for each class individually. For more information, +see +link:Introduction%20to%20Cache%20(ELUG)#Guidelines_for_Configuring_the_Cache_and_Identity_Maps[Guidelines +for Configuring the Cache and Identity Maps]. + +== Optimizing Schema + +Optimization is an important consideration when you design your database +schema and object model. Most performance issues occur when the object +model or database schema is too complex, which can make the database +slow and difficult to query. This is most likely to happen if you derive +your database schema directly from a complex object model. + +To optimize performance, design the object model and database schema +together. However, allow each model to be designed optimally: do not +require a direct one-to-one correlation between the two. + +This section includes the following schema optimization examples: + +* #Schema_Case_1:_Aggregation_of_Two_Tables_Into_One[Schema Case 1: +Aggregation of Two Tables Into One] +* #Schema_Case_2:_Splitting_One_Table_Into_Many[Schema Case 2: Splitting +One Table Into Many] +* #Schema_Case_3:_Collapsed_Hierarchy[Schema Case 3: Collapsed +Hierarchy] +* #Schema_Case_4:_Choosing_One_Out_of_Many[Schema Case 4: Choosing One +Out of Many] + +=== Schema Case 1: Aggregation of Two Tables Into One + +A common schema optimization technique is to aggregate two tables into a +single table. This improves read and write performance by requiring only +one database operation instead of two. + +The link:#Table_11-1[Original Schema (Aggregation of Two Tables Case)] +and link:#Table_11-2[Optimized Schema (Aggregation of Two Tables Case)] +tables illustrate the table aggregation technique. + +[#Table 11-1]## *_Original Schema (Aggregation of Two Tables Case)_* + +[cols="<,<",options="header",] +|=== +|*Elements* |*Details* +|Title |ACME Member Location Tracking System +|Classes |Member, Address +|Tables |MEMBER, ADDRESS +|Relationships |address - OneToOne - Address +|=== + +The nature of this application dictates that you always look up +employees and addresses together. As a result, querying a member based +on address information requires a database join, and reading a member +and its address requires two read statements. Writing a member requires +two write statements. This adds unnecessary complexity to the system, +and results in poor performance. + +A better solution is to combine the MEMBER and ADDRESS tables into a +single table, and change the one-to-one relationship to an aggregate +relationship. This lets you read all information with a single +operation, and doubles the update and insert speed, because only a +single row in one table requires modifications. + +[#Table 11-2]## *_Optimized Schema (Aggregation of Two Tables Case)_* + +[cols="<,<",options="header",] +|=== +|*Elements* |*Details* +|Classes |Member, Address +|Tables |MEMBER +|Relationships |address - Embedded (aggregate) - Address +|=== + +=== Schema Case 2: Splitting One Table Into Many + +To improve overall performance of the system, split large tables into +two or more smaller tables. This significantly reduces the amount of +data traffic required to query the database. + +For example, the system illustrated in the link:#Table_11-3[Original +Schema (Splitting One Table into Many Case)] table assigns employees to +projects within an organization. The most common operation reads a set +of employees and projects, assigns employees to projects, and update the +employees. The employee’s address or job classification is also +occasionally used to determine the project on which the employee is +placed. + +[#Table 11-3]## *_Original Schema (Splitting One Table into Many Case)_* + +Elements + +Details + +Instance Variable + +Mapping + +Target + +Title + +ACME Employee Workflow System + +Classes + +Employee, Address, PhoneNumber, EmailAddress, JobClassification, Project + +Tables + +EMPLOYEE, PROJECT, PROJ_EMP + +Relationships + +Employee + +address + +Embedded (aggregate) + +Address + +Employee + +phoneNumber + +Embedded (aggregate) + +EmailAddress + +Employee + +emailAddress + +Embedded (aggregate) + +EmailAddress + +Employee + +job + +Embedded (aggregate) + +JobClassification + +Employee + +projects + +ManyToMany + +Project + +When you read a large volume of employee records from the database, you +must also read their aggregate parts. Because of this, the system +suffers from general read performance issues. To resolve this, break the +EMPLOYEE table into the EMPLOYEE, ADDRESS, PHONE, EMAIL, and JOB tables, +as illustrated in the link:#Table_11-4[Optimized Schema (Splitting One +Table into Many Case)] table. + +Because you usually read only the employee information, splitting the +table reduces the amount of data transferred from the database to the +client. This improves your read performance by reducing the amount of +data traffic by 25 percent. + +[#Table 11-4]## *_Optimized Schema (Splitting One Table into Many +Case)_* + +Elements + +Details + +Instance Variable + +Mapping + +Target + +Title + +ACME Employee Workflow System + +Classes + +Employee, Address, PhoneNumber, EmailAddress, JobClassification, Project + +Tables + +EMPLOYEE, ADDRESS, PHONE, EMAIL, JOB, PROJECT, PROJ_EMP + +Relationships + +Employee + +address + +OneToOne + +Address + +Employee + +phoneNumber + +OneToOne + +EmailAddress + +Employee + +emailAddress + +OneToOne + +EmailAddress + +Employee + +job + +OneToOne + +JobClassification + +Employee + +projects + +ManyToMany + +Project + +=== Schema Case 3: Collapsed Hierarchy + +A common mistake when you transform an object-oriented design into a +relational model, is to build a large hierarchy of tables on the +database. This makes querying difficult, because queries against this +type of design can require a large number of joins. It is usually a good +idea to collapse some of the levels in your inheritance hierarchy into a +single table. + +The link:#Table_11-5[Original Schema (Collapsed Hierarchy Case)] table +represents a system that assigns clients to a company’s sales +representatives. The managers also track the sales representatives that +report to them. + +[#Table 11-5]## *_Original Schema (Collapsed Hierarchy Case)_* + +[cols="<,<",options="header",] +|=== +|*Elements* |*Details* +|Title |ACME Sales Force System +|Classes |Tables +|Person |PERSON +|Employee |PERSON, EMPLOYEE +|SalesRep |PERSON, EMPLOYEE, REP +|Staff |PERSON, EMPLOYEE, STAFF +|Client |PERSON, CLIENT +|Contact |PERSON, CONTACT +|=== + +The system suffers from complexity issues that hinder system development +and performance. Nearly all queries against the database require large, +resource-intensive joins. If you collapse the three-level table +hierarchy into a single table, as illustrated in the +link:#Table_11-6[Optimized Schema (Collapsed Hierarchy Case)] table, you +substantially reduce system complexity. You eliminate joins from the +system, and simplify queries. + +[#Table 11-6]## *_Optimized Schema (Collapsed Hierarchy Case)_* + +[cols="<,<",options="header",] +|=== +|*Elements* |*Details* +|Classes |Tables +|Person |none +|Employee |EMPLOYEE +|SalesRep |EMPLOYEE +|Staff |EMPLOYEE +|Client |CLIENT +|Contact |CLIENT +|=== + +=== Schema Case 4: Choosing One Out of Many + +In a one-to-many relationship, a single source object has a collection +of other objects. In some cases, the source object frequently requires +one particular object in the collection, but requires the other objects +only infrequently. You can reduce the size of the returned result set in +this type of case by adding an instance variable for the frequently +required object. This lets you access the object without instantiating +the other objects in the collection. + +The link:#Table_11-7[Original Schema (Choosing One out of Many Case)] +table represents a system by which an international shipping company +tracks the location of packages in transit. When a package moves from +one location to another, the system creates a new a location entry for +the package in the database. The most common query against any given +package is for its current location. + +[#Table 11-7]## *_Original Schema (Choosing One out of Many Case)_* + +Elements + +Details + +Instance Variable + +Mapping + +Target + +Title + +ACME Shipping Package Location Tracking system + +Classes + +Package, Location + +Tables + +PACKAGE, LOCATION + +Relationships + +Package + +locations + +OneToMany + +Location + +A package in this system can accumulate several location values in its +LOCATION collection as it travels to its destination. Reading all +locations from the database is resource intensive, especially when the +only location of interest is the current location. + +To resolve this type of problem, add a specific instance variable that +represents the current location. You then add a one-to-one mapping for +the instance variable, and use the instance variable to query for the +current location. As illustrated in the link:#Table_11-7[Original Schema +(Choosing One out of Many Case)] table, because you can now query for +the current location without reading all locations associated with the +package, this dramatically improves the performance of the system. + +[#Table 11-8|Optimized Schema (Choosing One out of Many Case)]## +*_Optimized Schema (Choosing One out of Many Case)_* + +Elements + +Details + +Instance Variable + +Mapping + +Target + +Classes + +Package, Location + +Tables + +PACKAGE, LOCATION + +Relationships + +Package + +locations + +OneToMany + +Location + +Package + +currentLocation + +OneToOne + +Location + +== Optimizing Mappings and Descriptors + +Always use indirection (lazy loading). It is not only critical in +optimizing database access, but also allows EclipseLink to make several +other optimizations including optimizing its cache access and unit of +work processing. See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Indirection_(Lazy_Loading)[Configuring +Indirection (Lazy Loading)]. + +Avoid using the existence checking option `+checkCacheThenDatabase+` on +descriptors (see +link:Configuring%20a%20Descriptor%20(ELUG)#BCGIIBFA[Configuring Cache +Existence Checking at the Descriptor Level]), unless required by the +application. The default existence checking behavior offers better +performance. + +Avoid expensive initialization in the default constructor that +EclipseLink uses to instantiate objects. Instead, use lazy +initialization or use an EclipseLink instantiation policy (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Instantiation_Policy[Configuring +Instantiation Policy]) to configure the descriptor to use a different +constructor. + +Avoid using method access in your EclipseLink mappings (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Method_or_Direct_Field_Accessing_at_the_Mapping_Level[Configuring +Method or Direct Field Accessing at the Mapping Level]), especially if +you have expensive or potentially dangerous side-effect code in your get +or set methods; use the default direct attribute access instead. + +== Optimizing Sessions + +Use a Server session in a server environment, not a `+DatabaseSession+`. + +Use the EclipseLink client session instead of remote session. A client +session is appropriate for most multiuser Java EE application server +environments. + +Do not pool client sessions. Pooling sessions offers no performance +gains. + +We recommend you increase the size of your session read and write +connection pools to the desired number of concurrent threads (for +example, 50). You configure this in EclipseLink when using an internal +connection pool or in the data source when using an external connection +pool. + +For more information, see the following: + +* link:#Optimizing_for_a_Production_Environment[Optimizing for a +Production Environment] +* link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#CServer_and_Client_Sessions[Server +and Client Sessions] +* link:Introduction%20to%20Data%20Access%20(ELUG)#Connection_Pools[Connection +Pools] + +== Optimizing Cache + +Cache coordination (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination]) is one way to allow multiple, possibly distributed, +instances of a session to broadcast object changes among each other so +that each session’s cache can be kept up-to-date. + +However, cache coordination is best suited to applications with specific +characteristics (see +link:Introduction%20to%20Cache%20(ELUG)#hen_to_Use_Cache_CoordinationI[When +to Use Cache Coordination]). Before implementing cache coordination, +tune the EclipseLink cache for each class using alternatives such as +object identity type (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Type_and_Size_at_the_Descriptor_Level[Configuring +Cache Type and Size at the Descriptor Level]), cache invalidation (see +link:Introduction%20to%20Cache%20(ELUG)#CCache_InvalidationI[Cache +Invalidation]), or cache isolation (see +link:Introduction%20to%20Cache%20(ELUG)#Cache_Isolation[Cache +Isolation]). Doing so lets you configure the optimal cache configuration +for each type of class (see the link:#Table_11-9[Identity Map and Cache +Configuration by Class Type] table) and may eliminate the need for +distributed cache coordination altogether. + +[#Table 11-9]## *_Identity Map and Cache Configuration by Class Type_* + +Class Type + +Identity Map Options + +Cache Options + +read-only + +soft, hard, or full 1 + +read-mostly + +soft or hard + +cache invalidation or cache coordination + +write-mostly + +weak + +cache invalidation + +1If the number of instances is finite. + +If you do use cache coordination, use JMS for cache coordination rather +than RMI. JMS is more robust, easier to configure, and runs +asynchronously. If you require synchronous cache coordination, use RMI. + +You can configure a descriptor to control when the EclipseLink runtime +will refresh the session cache when an instance of this object type is +queried (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Cache_Refreshing[Configuring +Cache Refreshing]). We do not recommend the use of *Always Refresh* or +*Disable Cache Hits*. + +Using *Always Refresh* may result in refreshing the cache on queries +when not required or desired. As an alternative, consider configuring +cache refresh on a query by query basis (see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How_to_Refresh_the_Cache[How +to Refresh the Cache]). + +Using *Disable Cache Hits* instructs EclipseLink to bypass the cache for +object read queries based on primary key. This results in a database +round trip every time an object read query based on primary key is +executed on this object type, negating the performance advantage of the +cache. When used in conjunction with *Always Refresh*, this option +ensures that all queries go to the database. This can have a significant +impact on performance. These options should only be used in specialized +circumstances. + +== Optimizing Data Access + +Depending on the type of data source your application accesses, +EclipseLink offers a variety of `+Login+` options that you can use to +tune the performance of low level data reads and writes. + +You can use several techniques to improve data access performance for +your application. This section discusses some of the more common +approaches, including the following: + +* link:#How_to_Optimize_JDBC_Driver_Properties[How to Optimize JDBC +Driver Properties] +* link:#How_to_Optimize_Data_Format[How to Optimize Data Format] +* link:#How_to_Use_Batch_Writing_for_Optimization[How to Use Batch +Writing for Optimization] +* link:#How_to_Use_Outer-Join_Reading_with_Inherited_Subclasses[How to +Use Outer-Join Reading with Inherited Subclasses] +* link:#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization] + +=== How to Optimize JDBC Driver Properties + +Consider the default behavior of the JDBC driver you choose for your +application. Some JDBC driver options can affect data access +performance. + +Some important JDBC driver properties can be configured directly using +the Workbench or EclipseLink API (for example, see +link:#How_to_Use_JDBC_Fetch_Size_for_Optimization[How to Use JDBC Fetch +Size for Optimization]). + +JDBC driver properties that are not supported directly by Workbench or +EclipseLink API can still be configured as generic JDBC properties that +EclipseLink passes to the JDBC driver. + +For example, some JDBC drivers, such as Sybase JConnect, perform a +database round trip to test whether or not a connection is closed: that +is, calling the JDBC driver method `+isClosed+` results in a stored +procedure call or SQL select. This database round-trip can cause a +significant performance reduction. To avoid this, you can disable this +behavior: for Sybase JConnect, you can set property name `+CLOSED_TEST+` +to value `+INTERNAL+`. + +For more information about configuring general JDBC driver properties +from within your EclipseLink application, see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_Properties[Configuring +Properties]. + +=== How to Optimize Data Format + +By default, EclipseLink optimizes data access by accessing the data from +JDBC in the format the application requires. For example, EclipseLink +retrieves `+long+` data types from JDBC instead of having the driver +return a `+BigDecimal+` that EclipseLink would then have to convert into +a `+long+`. + +Some older JDBC drivers do not perform data conversion correctly and +conflict with this optimization. In this case, you can disable this +optimization (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Advanced_Options[Configuring +Advanced Options]). + +=== How to Use Batch Writing for Optimization + +Batch writing can improve database performance by sending groups of +`+INSERT+`, `+UPDATE+`, and `+DELETE+` statements to the database in a +single transaction, rather than individually. + +When used without parameterized SQL, this is known as dynamic batch +writing. + +When used with parameterized SQL (see +link:#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]), this is known as parameterized batch +writing. This allows a repeatedly executed statement, such as a group of +inserts of the same type, to be executed as a single statement and a set +of bind parameters. This can provide a large performance benefit as the +database does not have to parse the batch. + +When using batch writing, you can tune the maximum batch writing size. + +In JPA applications, you can use persistence unit property +`+eclipselink.jdbc.batch-writing+` (see +link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_EclipseLink_JPA_Extensions_for_JDBC_Connection_Communication[EclipseLink +JPA Persistence Unit Properties for JDBC Connection Communication]). + +In POJO applications, you can use `+setMaxBatchWritingSize+` method of +the `+Login+` interface. The meaning of this value depends on whether or +not you are using parameterized SQL: + +* If you are using parameterized SQL (you configure your `+Login+` by +calling its `+bindAllParameters+` method), the maximum batch writing +size is the number of statements to batch with 100 being the default. +* If you are using dynamic SQL, the maximum batch writing size is the +size of the SQL string buffer in characters with 32000 being the +default. + +By default, EclipseLink does not enable batch writing because not all +databases and JDBC drivers support it. We recommend that you enable +batch writing for selected databases and JDBC drivers that support this +option. If your JDBC driver does not support batch writing, use the +batch writing capabilities of EclipseLink, known as native batch writing +(see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_JDBC_Options[Configuring +JDBC Options]). + +For a more detailed example of using batch writing to optimize write +queries, see link:#Batch_Writing_and_Parameterized_SQL[Batch Writing and +Parameterized SQL]. + +=== How to Use Outer-Join Reading with Inherited Subclasses + +You can configure an object-level read query to allow inherited +subclasses to be outer-joined to avoid the cost of a single query per +class, as the following exampple shows. + +[#Example 11-2|Configuring an ObjectLevelReadQuery to Outer-Join Inherited Subclasses]## +*_Configuring an ObjectLevelReadQuery to Outer-Join Inherited +Subclasses_* + +[source,java] +---- +objectLevelReadQuery.setShouldOuterJoinSubclasses(true); +---- + +You can configure a descriptor’s `+InheritancePolicy+` to allow the same +thing, as the link:#Example_11-3[Configuring a Descriptor to Allow +Inherited Subclasses to be Outer-Joined] example shows. By configuring +the `+InheritancePolicy+`, this option applies to all queries on the +descriptor’s class. + +[#Example 11-3]## *_Configuring a Descriptor to Allow Inherited +Subclasses to be Outer-Joined_* + +[source,java] +---- +descriptor.getInheritancePolicy().setShouldOuterJoinSubclasses(true); +---- + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Reading_Subclasses_on_Queries[Configuring +Reading Subclasses on Queries] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Join_Reading_and_Object-Level_Read_Queries[Join +Reading and Object-Level Read Queries] + +=== How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization + +Using parameterized SQL, you can keep the overall length of an SQL query +from exceeding the statement length limit that your JDBC driver or +database server imposes. + +Using parameterized SQL and prepared statement caching, you can improve +performance by reducing the number of times the database SQL engine +parses and prepares SQL for a frequently called query. + +By default, EclipseLink enables parameterized SQL but not prepared +statement caching. We recommend that you enable statement caching either +in EclipseLink when using an internal connection pool or in the data +source when using an external connection pool and choose a statement +cache size appropriate for your application. + +*Note*: When parameter binding is enabled, querying a database field +with a fixed CHAR length may result in no results returned. This is +because the white space may not be trimmed. Instead, you can: + +[arabic] +. Use a Variable length column type (for example, VARCHAR). +. Force the proper padding manually (either in your application or in a +converter). +. Not use parameter binding. + +Not all JDBC drivers support all JDBC binding options (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_JDBC_Options[Configuring +JDBC Options]). Selecting a combination of options may result in +different behavior from one driver to another. Before selecting JDBC +options, consult your JDBC driver documentation. When choosing binding +options, consider the following approach: + +[arabic] +. Try binding all parameters with all other binding options disabled. +. If this fails to bind some large parameters, consider enabling one of +the following options, depending on the parameter’s data type and the +binding options that your JDBC driver supports: +[arabic] +.. To bind large `+String+` parameters, try enabling string binding.If +large `+String+` parameters still fail to bind, consider adjusting the +maximum `+String+` size. EclipseLink sets the maximum `+String+` size to +32000 characters by default. +.. To bind large `+Byte+` array parameters, try enabling byte array +binding. +. If this fails to bind some large parameters, try enabling streams for +binding. Typically, configuring string or byte array binding will invoke +streams for binding. If not, explicitly configuring streams for binding +may help. + +For Java EE applications that use EclipseLink external connection pools, +you must configure parameterized SQL in EclipseLink, but you cannot +configure prepared statement caching in EclipseLink. In this case, you +must configure prepared statement caching in the application server +connection pool. For example, in OC4J, if you configure your +`+data-source.xml+` file with a managed `+data-source+` (where +`+connection-driver+` is `+oracle.jdbc.OracleDriver+`, and `+class+` is +`+oracle.j2ee.sql.DriverManagerDataSource+`), you can configure a +non-zero `+num-cached-statements+` that enables JDBC statement caching +and defines the maximum number of statements cached. + +For applications that use EclipseLink internal connection pools, you can +configure parameterized SQL and prepared statement caching. + +You can configure parameterized SQL and prepared statement caching at +the following levels: + +* session database login level–applies to all queries and provides +additional parameter binding API to alleviate the limit imposed by some +drivers on SQL statement size. We recommend that you use this approach. +For more information, see the following: +** JPA applications: see persistence unit properties +`+eclipselink.jdbc.bind-parameters+` and +`+eclipselink.jdbc.cache-statements+` in +link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_EclipseLink_JPA_Extensions_for_JDBC_Connection_Communication[EclipseLink +JPA Persistence Unit Properties for JDBC Connection Communication]. +** POJO applications: see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_JDBC_Options[Configuring +JDBC Options] +* project level–applies to all named queries (see +link:Configuring%20a%20Relational%20Project%20(ELUG)#Configuring_Named_Query_Parameterized_SQL_and_Statement_Caching_at_the_Project_Level[Configuring +Named Query Parameterized SQL and Statement Caching at the Project +Level]); +* descriptor level–applies on a per-named-query basis (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Options[Configuring +Named Query Options]); +* query level–applies on a per-query basis (see +link:Using%20Basic%20Query%20API%20(ELUG)#How_to_Use_Parameterized_SQL_and_Statement_Caching_in_a_DatabaseQuery[How +to Use Parameterized SQL and Statement Caching in a DatabaseQuery]). + +== Optimizing Queries + +EclipseLink provides an extensive query API for reading, writing, and +updating data. This section describes ways of optimizing query +performance in various circumstances. + +Before optimizing queries, consider the optimization suggestions in +link:#Optimizing_Data_Access[Optimizing Data Access]. + +This section includes information on the following: + +* link:#How_to_Use_Parameterized_SQL_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL and Prepared Statement Caching for +Optimization] +* link:#How_to_Use_Named_Queries_for_Optimization[How to Use Named +Queries for Optimization] +* link:#How_to_Use_Batch_and_Join_Reading_for_Optimization[How to Use +Batch and Join Reading for Optimization] +* link:#How_to_Use_Partial_Object_Queries_and_Fetch_Groups_for_Optimization[How +to Use Partial Object Queries and Fetch Groups for Optimization] +* link:#How_to_Use_Read-Only_Queries_for_Optimization[How to Use +Read-Only Queries for Optimization] +* link:#How_to_Use_JDBC_Fetch_Size_for_Optimization[How to Use JDBC +Fetch Size for Optimization] +* link:#How_to_Use_Cursored_Streams_and_Scrollable_Cursors_for_Optimization[How +to Use Cursored Streams and Scrollable Cursors for Optimization] +* link:#How_to_Use_Result_Set_Pagination_for_Optimization[How to Use +Result Set Pagination for Optimization] +* link:#Read_Optimization_Examples[Read Optimization Examples] +* link:#Write_Optimization_Examples[Write Optimization Examples] + +=== How to Use Parameterized SQL and Prepared Statement Caching for Optimization + +These features let you cache and reuse a query’s preparsed database +statement when the query is reexecuted. + +For more information, see +link:#How_to_Use_Parameterized_SQL_(Parameter_Binding)_and_Prepared_Statement_Caching_for_Optimization[How +to Use Parameterized SQL (Parameter Binding) and Prepared Statement +Caching for Optimization]. + +=== How to Use Named Queries for Optimization + +Whenever possible, use named queries in your application. Named queries +help you avoid duplication, are easy to maintain and reuse, and easily +add complex query behavior to the application. Using named queries also +allows for the query to be prepared once, and for the SQL generation to +be cached. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries]. + +=== How to Use Batch and Join Reading for Optimization + +To optimize database read operations, EclipseLink supports both batch +and join reading. When you use these techniques, you dramatically +decrease the number of times you access the database during a read +operation, especially when your result set contains a large number of +objects. + +For more information, see the following: + +* For JPA applications, see the following: +** link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@JoinFetch_Annotation[How +to Use the @JoinFetch Annotation] +** link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#Join_Fetch[Join +Fetch Query Hint] +** link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#Batch[Batch Query +Hint] +* For POJO applications, see the following: +** link:Introduction_to_EclipseLink_Queries_%28ELUG%29#Join_Reading_and_Object-Level_Read_Queries[Join +Reading and Object-Level Read Queries] +** link:Using%20Basic%20Query%20API%20(ELUG)#Using_Batch_Reading[Using +Batch Reading] + +=== How to Use Partial Object Queries and Fetch Groups for Optimization + +Partial object queries let you retrieve partially populated objects from +the database rather than complete objects. + +When using weaving with JPA or POJO applications, you can use fetch +groups to accomplish the same performance optimization. + +For more information about partial object reading, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Partial_Object_Queries[Partial +Object Queries]. + +For more information about fetch groups, see +link:Introduction%20to%20Descriptors%20(ELUG)#Fetch_Groups[Fetch +Groups]. + +=== How to Use Read-Only Queries for Optimization + +You can configure an object-level read query as read-only, as this +shows. When you execute such a query in the context of a `+UnitOfWork+` +(or EclipseLink JPA persistence provider), EclipseLink returns a +read-only, non-registered object. You can improve performance by +querying read-only data in this way because the read-only objects need +not be registered or checked for changes. + +*_Configuring an ObjectLevelReadQuery as Read-Only_* + +[source,java] +---- +objectLevelReadQuery.setIsReadOnly(true); +---- + +For more information, see the following: + +* For JPA applications, see the following: +** link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#Read_Only[Read Only +Query Hint] +** link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_.40ReadOnly_Annotation[How +to Use the ReadOnly Annotation] +* For POJO applications, see the following: +** link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Read-Only_Descriptors[Configuring +Read-Only Descriptors] +** link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Read-Only_Query[Read-Only +Query] + +=== How to Use JDBC Fetch Size for Optimization + +The JDBC fetch size gives the JDBC driver a hint as to the number of +rows that should be fetched from the database when more rows are needed. + +For large queries that return a large number of objects you can +configure the row fetch size used in the query to improve performance by +reducing the number database hits required to satisfy the selection +criteria. + +Most JDBC drivers default to a fetch size of 10, so if you are reading +1000 objects, increasing the fetch size to 256 can significantly reduce +the time required to fetch the query’s results. The optimal fetch size +is not always obvious. Usually, a fetch size of one half or one quarter +of the total expected result size is optimal. Note that if you are +unsure of the result set size, incorrectly setting a fetch size too +large or too small can decrease performance. + +Set the query fetch size with `+ReadQuery+` method `+setFetchSize+`, as +the link:#Example_11-5[JDBC Driver Fetch Size] example shows. +Alternatively, you can use `+ReadQuery+` method `+setMaxRows+` to set +the limit for the maximum number of rows that any `+ResultSet+` can +contain. + +[#Example 11-5]## *_JDBC Driver Fetch Size_* + +[source,java] +---- +// Create query and set Employee as its reference class +ReadAllQuery query = new ReadAllQuery(Employee.class); +ExpressionBuilder builder = query.getExpressionBuilder(); +query.setSelectionCriteria(builder.get("id").greaterThan(100)); + +// Set the JDBC fetch size +query.setFetchSize(50); + +// Configure the query to return results as a ScrollableCursor +query.useScrollableCursor(); + +// Execute the query +ScrollableCursor cursor = (ScrollableCursor) session.executeQuery(query); + +// Iterate over the results + +while (cursor.hasNext()) { + System.out.println(cursor.next().toString()); +} +cursor.close(); +---- + +In this example, when you execute the query, the JDBC driver retrieves +the first 50 rows from the database (or all rows if less than 50 rows +satisfy the selection criteria). As you iterate over the first 50 rows, +each time you call `+cursor.next()+`, the JDBC driver returns a row from +local memory–it does not need to retrieve the row from the database. +When you try to access the fifty first row (assuming there are more than +50 rows that satisfy the selection criteria), the JDBC driver again goes +to the database and retrieves another 50 rows. In this way, 100 rows are +returned with only two database hits. + +If you specify a value of zero (default; means the fetch size is not +set), then the hint is ignored and the JDBC driver’s default is used. + +For more information see the following: + +* link:Using_EclipseLink_JPA_Extensions_%28ELUG%29#Fetch_Size[Fetch Size +Query Hint] + +=== How to Use Cursored Streams and Scrollable Cursors for Optimization + +You can configure a query to retrieve data from the database using a +cursored Java stream or scrollable cursor. This lets you view a result +set in manageable increments rather than as a complete collection. This +is useful when you have a large result set. You can further tune +performance by configuring the JDBC driver fetch size used (see +link:#How_to_Use_JDBC_Fetch_Size_for_Optimization[How to Use JDBC Fetch +Size for Optimization]). + +For more information about scrollable cursors, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Handling_Cursor_and_Stream_Query_Results[Handling +Cursor and Stream Query Results]. + +=== How to Use Result Set Pagination for Optimization + +As this figure shows, using `+ReadQuery+` methods +`+setMaxRows(maxRows)+` and `+setFirstResult(firstResult)+`, you can +configure a query to retrieve a result set in pages, that is, a partial +result as a `+List+` of `+pageSize+` (or less) results. + +[#Figure 11-1]## *_Using Result Set Pagination_* + +.Using Result Set Pagination +image::page.gif[Using Result Set +Pagination,title="Using Result Set Pagination"] + +In this example, for the first query invocation, `+pageSize=3+`, +`+maxRows=pageSize+`, and `+firstResult=0+`. This returns a List of +results `+00+` through `+02+`. + +For each subsequent query invocation, you increment +`+maxRows=maxRows+pageSize+` and `+firstResult=firstResult+pageSize+`. +This returns a new `+List+` for each page of results `+03+` through +`+05+`, `+06+` through `+08+`, and so on. + +Typically, you use this approach when you do not necessarily need to +process the entire result set. For example, when a user wishes to scan +the result set a page at a time looking for a particular result and may +abandon the query after the desired record is found. + +The advantage of this approach over cursors is that it does not require +any state or live connection on the server; you only need to store the +`+firstResult+` index on the client. This makes it useful for paging +through a Web result. + +For more information, see the following: + +* link:Using%20Advanced%20Query%20API%20(ELUG)#Handling_Query_Results_Using_Pagination[Handling +Query Results Using Pagination] +* link:#How_to_Use_Cursored_Streams_and_Scrollable_Cursors_for_Optimization[How +to Use Cursored Streams and Scrollable Cursors for Optimization] + +=== Read Optimization Examples + +EclipseLink provides the read optimization features listed in the +link:#Table_11-10[Read Optimization Features] table. + +This section includes the following read optimization examples: + +* #Reading_Case_1:_Displaying_Names_in_a_List[Reading Case 1: Displaying +Names in a List] +* #Reading_Case_2:_Batch_Reading_Objects[Reading Case 2: Batch Reading +Objects] +* #Reading_Case_3:_Using_Complex_Custom_SQL_Queries[Reading Case 3: +Using Complex Custom SQL Queries] +* #Reading_Case_4:_Using_View_Objects[Reading Case 4: Using View +Objects] +* #Reading_Case_5:_Inheritance_Subclass_Outer-Joining[Reading Case 5: +Inheritance Subclass Outer-Joining] + +[#Table 11-10]## *_Read Optimization Features_* + +Feature + +Function + +Performance Technique + +Unit of work + +Tracks object changes within the unit of work. + +To minimize the amount of tracking required, registers only those +objects that will change. For more information, see Introduction to +EclipseLink Transactions. + +Indirection (lazy loading) + +Uses indirection objects to defer the loading and processing of +relationships. + +Provides a major performance benefit. It allows database access to be +optimized and allows EclipseLink to internally make several +optimizations in caching and unit of work. + +Soft cache, weak identity map + +Offers client-side caching for objects read from database, and drops +objects from the cache when memory becomes low. + +Reduces database calls and improves memory performance. For more +information, see Cache Type and Object Identity. + +Weak identity map + +Offers client-side caching for objects. + +Reduces database access and maintains a cache of all referenced objects. +For more information, see Cache Type and Object Identity. + +Batch reading and joining + +Reduces database access by batching many queries into a single query +that reads more data. + +Dramatically reduces the number of database accesses required to perform +a read query. For more information, see Using Batch Reading and Using +Join Reading with ObjectLevelReadQuery. + +Partial object reading and fetch groups. + +Allows reading of a subset of a result set of the object’s attributes. + +Reduces the amount of data read from the database. For more information, +see Partial Object Queries. For more information about fetch groups, see +Fetch Groups. + +Report query + +Similar to partial object reading, but returns only the data instead of +the objects. + +Supports complex reporting functions such as aggregation and group-by +functions. Also lets you compute complex results on the database, +instead of reading the objects into the application and computing the +results locally. For more information, see Report Query. + +Read-only query + +EclipseLink returns a read-only, non-registered object. + +The read-only objects need not be registered or checked for changes. For +more information, see How to Use Read-Only Queries for Optimization + +JDBC fetch size and ReadQuery first result maximum rows + +Reduces the number of database hits required to return all the rows that +satisfy selection criteria. + +For more information, see How to Use JDBC Fetch Size for Optimization. + +Cursors + +Lets you view a large result set in manageable increments rather than as +a complete collection + +For more information, see How to Use Cursored Streams and Scrollable +Cursors for Optimization + +Inheritance subclass outer joins + +Allows queries against an inheritance superclass that can read all of +its subclasses in a single query, instead of multiple queries, with or +without a view. + +For more information, see Reading Case 5: Inheritance Subclass +Outer-Joining. + +Soft identity map + +Similar to the weak identity map, except that the map uses soft +references instead of weak references. This method allows full garbage +collection and provides full caching and guaranteed identity + +Allows for optimal caching of the objects without the overhead of a +sub-cache, while still allowing the JVM to garbage collect the objects +if memory is low. For more information, see Soft Identity Map. + +==== Reading Case 1: Displaying Names in a List + +An application may ask the user to choose an element from a list. +Because the list displays only a subset of the information contained in +the objects, it is not necessary to query for all information for +objects from the database. + +EclipseLink features that optimize these types of operations include the +following: + +* link:#Partial_Object_Reading[Partial Object Reading] +* link:#Report_Query[Report Query] +* link:#Fetch_Groups[Fetch Groups] + +These features let you query only the information required to display +the list. The user can then select an object from the list. + +[#Example 11-6]## *_No Optimization_* + +JPA + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* This must read in all the information for all the employees */ +ListBox list; + +// Fetch data from database and add to list box +List employees = entityManager.createQuery("Select e from Employee e").getResultList(); +list.addAll(employees); + +// Display list box +.... + +// Get selected employee from list +Employee selectedEmployee = (Employee) list.getSelectedItem(); + +return selectedEmployee; +---- + +Native API + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* This must read in all the information for all the employees */ +ListBox list; + +// Fetch data from database and add to list box +List employees = session.readAllObjects(Employee.class); +list.addAll(employees); + +// Display list box +.... + +// Get selected employee from list +Employee selectedEmployee = (Employee) list.getSelectedItem(); + +return selectedEmployee; +---- + +===== Partial Object Reading + +Partial object reading is a query designed to extract only the required +information from a selected record in a database, rather than all the +information the record contains. Because partial object reading does not +fully populate objects, you can neither cache nor edit partially read +objects. + +For more information about partial object queries, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Partial_Object_Queries[Partial +Object Queries]. + +In this example, the query builds complete employee objects, even though +the list displays only employee last names. With no optimization, the +query reads all the employee data. + +The link:#Example_11-7[Optimization Through Partial Object Reading] +example demonstrates the use of partial object reading. It reads only +the last name and primary key for the employee data. This reduces the +amount of data read from the database. + +[#Example 11-7]## *_Optimization Through Partial Object Reading_* + +JPA + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* This uses partial object reading to read just the last names of the employees. */ +ListBox list; + +// Fetch data from database and add to list box +List employees = entityManager.createQuery("Select new Employee(e.id, e.lastName) from Employee e").getResultList(); +list.addAll(employees); + +// Display list box +.... + +// Get selected employee from list +Employee selectedEmployee = (Employee)entityManager.find(Employee.class, ((Employee)list.getSelectedItem()).getId()); +return selectedEmployee; +---- + +Native API + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* This uses partial object reading to read just the last names of the employees. */ +/* Since EclipseLink automatically includes the primary key of the object, the full object can easily be read for editing */ +ListBox list; + +// Fetch data from database and add to list box +ReadAllQuery query = new ReadAllQuery(Employee.class); +query.addPartialAttribute("lastName"); + +// The next line avoids a query exception +query.dontMaintainCache(); +List employees = session.executeQuery(query); +list.addAll(employees); + +// Display list box +.... + +// Get selected employee from list +Employee selectedEmployee = (Employee)session.readObject(list.getSelectedItem()); +return selectedEmployee; +---- + +===== Report Query + +Report query lets you retrieve data from a set of objects and their +related objects. Report query supports database reporting functions and +features. + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report_Query_Results[Report +Query Results]. + +The link:#Example_11-8[Optimization Through Report Query] example +demonstrates the use of report query to read only the last name of the +employees. This reduces the amount of data read from the database +compared to the code in the link:#Example_11-6[No Optimization] example, +and avoids instantiating employee instances. + +[#Example 11-8]## *_Optimization Through Report Query_* + +JPA + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* This uses a report query to read just the last names of the employees. */ +ListBox list; + +// Fetch data from database and add to list box +// This query returns a List of Object[] data values +List rows = entityManager.createQuery("Select e.id, e.lastName from Employee e").getResultList(); +list.addAll(rows); + +// Display list box +.... + +// Get selected employee from list +Object selectedItem[] = (Object[])list.getSelectedItem(); +Employee selectedEmployee = (Employee)entityManager.find(Employee.class, selectedItem[0]); +return selectedEmployee; +---- + +Native API + +[source,java] +---- +/* Read all the employees from the database, ask the user to choose one and return it. */ +/* The report query is used to read just the last name of the employees. */ +/* Then the primary key stored in the report query result to read the real object */ +ListBox list; + +// Fetch data from database and add to list box +ExpressionBuilder builder = new ExpressionBuilder(); +ReportQuery query = new ReportQuery (Employee.class, builder); +query.addAttribute("lastName"); +query.retrievePrimaryKeys(); +List reportRows = (List) session.executeQuery(query); +list.addAll(reportRows); + +// Display list box +.... + +// Get selected employee from list +ReportQueryResult result = (ReportQueryResult) list.getSelectedItem(); +Employee selectedEmployee = (Employee)result.readobject(Employee.Class, session); +---- + +Although the differences between the unoptimized example +(link:#Example_11-6[No Optimization]) and the report query optimization +in the link:#Example_11-8[Optimization Through Report Query] example +appear to be minor, report queries offer a substantial performance +improvement. + +===== Fetch Groups + +Fetch groups are similar to partial object reading, but does allow +caching of the objects read. For objects with many attributes or +reference attributes to complex graphs (or both), you can define a fetch +group that determines what attributes are returned when an object is +read. Because EclipseLink will automatically execute additional queries +when the `+get+` method is called for attributes not in the fetch group, +ensure that the unfetched data is not required: refetching data can +become a performance issue. + +For more information about querying with fetch groups, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Using_Queries_with_Fetch_Groups[Using +Queries with Fetch Groups]. + +The link:#Example_11-9[Configuring a Query with a FetchGroup Using the +FetchGroupManager] example demonstrates the use of a static fetch group. + +*_Configuring a Query with a FetchGroup Using the FetchGroupManager_* + +JPA + +[source,java] +---- +// Use fetch group at query level +ReadAllQuery query = new ReadAllQuery(Employee.class); +FetchGroup group = new FetchGroup("nameOnly"); +group.addAttribute("firstName"); +group.addAttribute("lastName"); +query.setFetchGroup(group); + +JpaQuery jpaQuery = (JpaQuery)entityManager.createQuery("Select e from Employee e"); +jpaQuery.setDatabaseQuery(query); + +List employees = jpaQuery.getResultList(); + + +/* Only Employee attributes firstName and lastName are fetched. + If you call the Employee get method for any other attribute, EclipseLink executes + another query to retrieve all unfetched attribute values. Thereafter, + calling that get method will return the value directly from the object */ +---- + +Native API + +[source,java] +---- +// Use fetch group at query level +ReadAllQuery query = new ReadAllQuery(Employee.class); +FetchGroup group = new FetchGroup("nameOnly"); +group.addAttribute("firstName"); +group.addAttribute("lastName"); +query.setFetchGroup(group); + +List employees = session.executeQuery(query); + +/* Only Employee attributes firstName and lastName are fetched. + If you call the Employee get method for any other attribute, EclipseLink executes + another query to retrieve all unfetched attribute values. Thereafter, + calling that get method will return the value directly from the object */ +---- + +==== Reading Case 2: Batch Reading Objects + +The way your application reads data from the database affects +performance. For example, reading a collection of rows from the database +is significantly faster than reading each row individually. + +A common performance challenge is to read a collection of objects that +have a one-to-one reference to another object. This typically requires +one read operation to read in the source rows, and one call for each +target row in the one-to-one relationship. + +To reduce the number of read operations required, use join and batch +reading. The link:#Example_11-10[No Optimization] example illustrates +the unoptimized code required to retrieve a collection of objects with a +one-to-one reference to another object. The +link:#Example_11-11[Optimization Through Joining] and +link:#Example_11-12[Optimization Through Batch Reading] examples +illustrate the use of joins and batch reading to improve efficiency. + +[#Example 11-10]## *_No Optimization_* + +JPA + +[source,java] +---- +// Read all the employees, and collect their address' cities. This takes N + 1 queries if not optimized +// Read all the employees from the database. This requires 1 SQL call +List employees = entityManager.createQuery("Select e from Employee e where e.lastName = 'Smith'").getResultList(); +//SQL: Select * from Employee where l_name = 'Smith + +// Iterate over employees and get their addresses. +// This requires N SQL calls +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while(iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); +} +//SQL: Select * from Address where address_id = 123, etc (* n) +---- + +Native API + +[source,java] +---- +// Read all the employees, and collect their address' cities. This takes N + 1 queries if not optimized +// Read all the employees from the database. This requires 1 SQL call +List employees = session.readAllObjects(Employee.class, + new ExpressionBuilder().get("lastName").equal("Smith")); + +//SQL: Select * from Employee where l_name = 'Smith + +// Iterate over employees and get their addresses. +// This requires N SQL calls +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while(iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); +} +//SQL: Select * from Address where address_id = 123, etc (* n) +---- + +[#Example 11-11]## *_Optimization Through Joining_* + +JPA + +[source,java] +---- +// Read all the employees; collect their address' cities. Although the code +// is almost identical because joining optimization is used it takes only 1 query + +// Read all the employees from the database using joining. +// This requires 1 SQL call +List employees = entityManager.createQuery("Select e from Employee e join fetch e.address where e.lastName = 'Smith'").getResultList(); +/// SQL: Select E.*, A.* from Employee E, Address A where E.l_name = 'Smith' and E.address_id = A.address_id + +// Iterate over employees and get their addresses. +// The previous SQL already read all the addresses, so no SQL is required + +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while (iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); +} +---- + +Native API + +[source,java] +---- +// Read all the employees; collect their address' cities. Although the code +// is almost identical because joining optimization is used it takes only 1 query + +// Read all the employees from the database using joining. +// This requires 1 SQL call +ReadAllQuery query = new ReadAllQuery(Employee.class); +ExpressionBuilder builder = query.getExpressionBuilder(); +query.setSelectionCriteria(builder.get("lastName").equal("Smith")); +query.addJoinedAttribute("address"); +List employees = session.executeQuery(query); +/// SQL: Select E.*, A.* from Employee E, Address A where E.l_name = 'Smith' and E.address_id = A.address_id + +// Iterate over employees and get their addresses. +// The previous SQL already read all the addresses, so no SQL is required +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while (iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); +} +---- + +[#Example 11-12]## *_Optimization Through Batch Reading_* + +JPA + +[source,java] +---- +// Read all the employees; collect their address' cities. Although the code +// is almost identical because batch reading optimization is used it takes only 2 queries + +// Read all the employees from the database, using batch reading. + +// This requires 1 SQL call, note that only the employees are read +Query query = entityManager.createQuery("Select e from Employee e where e.lastName = 'Smith'"); +query.setHint("eclipselink.batch", "e.address"); +List employees = query.getResultList(); +// SQL: Select * from Employee where l_name = 'Smith + +// Iterate over employees and get their addresses. +// The first address accessed will cause all the addresses to be read in a single SQL call +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while (iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); + // SQL: Select distinct A.* from Employee E, Address A + // where E.l_name = 'Smith' and E.address_id = A.address_i +} +---- + +Native API + +[source,java] +---- +// Read all the employees; collect their address' cities. Although the code +// is almost identical because batch reading optimization is used it takes only 2 queries + +// Read all the employees from the database, using batch reading. + +// This requires 1 SQL call, note that only the employees are read +ReadAllQuery query = new ReadAllQuery(Employee.class); +ExpressionBuilder builder = query.getExpressionBuilder(); +query.setSelectionCriteria(bulder.get("lastName").equal("Smith")); +query.addBatchReadAttribute("address"); +List employees = (List)session.executeQuery(query); +// SQL: Select * from Employee where l_name = 'Smith + +// Iterate over employees and get their addresses. +// The first address accessed will cause all the addresses to be read in a single SQL call +Iterator iterator = employees.iterator(); +List cities = new ArrayList(); +while (iterator.hasNext()) { + Employee employee = (Employee) iterator.next(); + cities.add(employee.getAddress().getCity()); + // SQL: Select distinct A.* from Employee E, Address A + // where E.l_name = 'Smith' and E.address_id = A.address_i +} +---- + +Because the two-phase approach to the query (the +link:#Example_11-11[Optimization Through Joining] and +link:#Example_11-12[Optimization Through Batch Reading] examples) +accesses the database only twice, it is significantly faster than the +approach illustrated in the link:#Example_11-10[No Optimization] +example. + +Joins offer a significant performance increase under most circumstances. +Batch reading offers a further performance advantage in that it allows +for delayed loading through value holders, and has much better +performance where the target objects are shared. + +For example, if employees in the link:#Example_11-10[No Optimization], +link:#Example_11-11[Optimization Through Joining], and +link:#Example_11-12[Optimization Through Batch Reading] examples are at +the same address, batch reading reads much less data than joining, +because batch reading uses a SQL `+DISTINCT+` call to filter duplicate +data. + +Batch reading and joining are available for one-to-one, one-to-many, +many-to-many, direct collection, direct map and aggregate collection +mappings. Note that one-to-many joining will return a large amount of +duplicate data and so is normally less efficient than batch reading. + +==== Reading Case 3: Using Complex Custom SQL Queries + +EclipseLink provides a high-level query mechanism. However, if your +application requires a complex query, a direct SQL or stored procedure +call may be the best solution. + +For more information about executing SQL calls, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#SQLCall[SQLCall]. + +==== Reading Case 4: Using View Objects + +Some application operations require information from several objects +rather than from just one. This can be difficult to implement, and +resource-intensive. The link:#Example_11-13[No Optimization] example +illustrates unoptimized code that reads information from several +objects. + +[#Example 11-13]## *_No Optimization_* + +JPA + +[source,java] +---- +/* Gather the information to report on an employee and return the summary of the + information. In this situation, a hash table is used to hold the report + information. Notice that this reads a lot of objects from the database, but + uses very little of the information contained in the objects. This may take 5 + queries and read in a large number of objects */ + +public Map reportOnEmployee(String employeeName) { + List projects, associations; + Map report = new HashMap(); + // Retrieve employee from database + Query query = entityManager.createQuery("Select e from Employee e where e.lastName = :name"); + query.setParameter("name", employeeName); + Employee employee = (Employee)query.getSingleResult(); + + // Get all the projects affiliated with the employee + projects = entityManager.createNativeQuery("SELECT P.* FROM PROJECT P," + + "EMPLOYEE E WHERE P.MEMBER_ID = E.EMP_ID AND E.L_NAME = " + + employeeName, Project.class).getResultList(); + + // Get all the associations affiliated with the employee + associations = entityManager.createNativeQuery("SELECT A.* " + + "FROM ASSOC A, EMPLOYEE E WHERE A.MEMBER_ID = E.EMP_ID AND E.L_NAME = " + + employeeName, Association.class).getResultList(); + + report.put("firstName", employee.getFirstName()); + report.put("lastName", employee.getLastName()); + report.put("manager", employee.getManager()); + report.put("city", employee.getAddress().getCity()); + report.put("projects", projects); + report.put("associations", associations); + return report; +} +---- + +Native API + +[source,java] +---- +/* Gather the information to report on an employee and return the summary of the + information. In this situation, a hash table is used to hold the report + information. Notice that this reads a lot of objects from the database, but + uses very little of the information contained in the objects. This may take 5 + queries and read in a large number of objects */ + +public Map reportOnEmployee(String employeeName) { + List projects, associations; + Map report = new HashMap(); + // Retrieve employee from database + Employee employee = session.readObject(Employee.class, + new ExpressionBuilder.get("lastName").equal(employeeName)); + + // Get all the projects affiliated with the employee + projects = session.readAllObjects(Project.class, + "SELECT P.* FROM PROJECT P," + + "EMPLOYEE E WHERE P.MEMBER_ID = E.EMP_ID AND E.L_NAME = " + + employeeName); + + // Get all the associations affiliated with the employee + associations = session.readAllObjects(Association.class, "SELECT A.* " + + "FROM ASSOC A, EMPLOYEE E WHERE A.MEMBER_ID = E.EMP_ID AND E.L_NAME = " + + employeeName); + + report.put("firstName", employee.getFirstName()); + report.put("lastName", employee.getLastName()); + report.put("manager", employee.getManager()); + report.put("city", employee.getAddress().getCity()); + report.put("projects", projects); + report.put("associations", associations); + return report; +} +---- + +To improve application performance in these situations, define a new +read-only object to encapsulate this information, and map it to a view +on the database. To set the object to be read-only, configure its +descriptor as read-only (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Read-Only_Descriptors[Configuring +Read-Only Descriptors]). + +[#Example 11-14]## *_Optimization Through View Object_* + +[source,sql] +---- +CREATE VIEW NAMED EMPLOYEE_VIEW AS (SELECT F_NAME = E.F_NAME, L_NAME = E.L_NAME,EMP_ID = E.EMP_ID, MANAGER_NAME = E.NAME, CITY = A.CITY, NAME = E.NAME + FROM EMPLOYEE E, EMPLOYEE M, ADDRESS A + WHERE E.MANAGER_ID = M.EMP_ID + AND E.ADDRESS_ID = A.ADDRESS_ID) +---- + +Define a descriptor for the `+EmployeeReport+` class as follows: + +* Define the descriptor as usual, but specify the `+tableName+` as +`+EMPLOYEE_VIEW+`. +* Map only the attributes required for the report. In the case of the +`+numberOfProjects+` and associations, use a transformation mapping to +retrieve the required data. + +You can now query the report from the database in the same way as any +other object enabled by EclipseLink. + +[#Example 11-15]## *_View the Report from +link:#Example_11-14[Optimization Through View Object]_* + +[source,java] +---- +// Return the report for the employee +public EmployeeReport reportOnEmployee(String employeeName) { + EmployeeReport report; + report = (EmployeeReport) session.readObject(EmployeeReport.class, + new ExpressionBuilder.get("lastName").equal(employeeName)); + return report; +} +---- + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +(for example: `+readAllObjects(Class class, String sql)+` and +`+readObject(Class class, String sql)+` method) makes your application +vulnerable to SQL injection attacks.’’’ +|=== + +==== Reading Case 5: Inheritance Subclass Outer-Joining + +If you have an inheritance hierarchy that spans multiple tables and +frequently query for the root class, consider using outer joining. This +allows an outer-joining to be used for queries against an inheritance +superclass that can read all of its subclasses in a single query instead +of multiple queries. + +Note that on some databases, the outer joins may be less efficient than +the default multiple queries mechanism. + +For more information about inheritance, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]. + +For more information about querying on inheritance, see +link:Using%20Advanced%20Query%20API%20(ELUG)#Querying_on_an_Inheritance_Hierarchy[Querying +on an Inheritance Hierarchy]. + +=== Write Optimization Examples + +EclipseLink provides the write optimization features listed in the +link:#Table_11-11[Write Optimization Features] table. + +This section includes the following write optimization examples: + +* #Writing_Case:_Batch_Writes[Writing Case: Batch Writes] + +[#Table 11-11]## *_Write Optimization Features_* + +Feature + +Effect on Performance + +Unit of work + +Improves performance by updating only the changed fields and objects. + +Minimizes the amount of tracking required (which can be expensive) by +registering only those objects that will change. + +For more information, see Introduction to EclipseLink Transactions). + +Note: The unit of work supports marking classes as read-only (see +Configuring Read-Only Descriptors and Declaring Read-Only Classes). This +avoids tracking of objects that do not change. + +Batch writing + +Lets you group all insert, update, and delete commands from a +transaction into a single database call. This dramatically reduces the +number of calls to the database (see Batch Writing and Parameterized +SQL). + +Parameterized SQL + +Improves performance for frequently executed SQL statements (see How to +Use Parameterized SQL and Prepared Statement Caching for Optimization). + +Sequence number preallocation + +Dramatically improves insert performance (see Sequence Number +Preallocation). + +Multiprocessing + +Splitting a batch job across threads lets you synchronize reads from a +cursored stream and use parallel units of work for performance +improvements even on a single machine (see Multiprocessing). + +Does exist alternatives + +The does exist call on write object can be avoided in certain situations +by checking the cache for does exist, or assuming the existence of the +object (see Configuring Existence Checking at the Project Level or +Configuring Cache Existence Checking at the Descriptor Level and How to +Use Registration and Existence Checking). + +Change Tracking + +Improves writing and transactional read performance (see Unit of Work +and Change Policy and Configuring Change Policy). + +Isolated Client Sessions + +For write-only, or non-cached (isolated) objects, the unit of work +isolation level should be set to isolated-always to avoid caching +overhead when not caching (see Cache Isolation). + +==== Writing Case: Batch Writes + +The most common write performance problem occurs when a batch job +inserts a large volume of data into the database. For example, consider +a batch job that loads a large amount of data from one database, and +then migrates the data into another. The following objects are involved: + +* Simple individual objects with no relationships. +* Objects that use generated sequence numbers as their primary key. +* Objects that have an address that also uses a sequence number. + +The batch job loads 10,000 employee records from the first database and +inserts them into the target database. With no optimization, the batch +job reads all the records from the source database, acquires a unit of +work from the target database, registers all objects, and commits the +unit of work. + +[#Example 11-16]## *_No Optimization_* + +JPA + +[source,java] +---- +// Read all the employees from source entity manager + +// Read all the employees from the database. This requires 1 SQL call, +// but will be very memory intensive as 10,000 objects will be read +List employees = (List)sourceEntityManager.createQuery("Select e from Employee e").getResultList(); + +//SQL: Select * from Employee + +// Acquire a unit of work and register the employees +targetEntityManager.getTransaction().begin(); +for (Employee employee : employees) { + targetEntityManager.persist(employee); +} +targetEntityManager.getTransaction().commit(); +---- + +Native API + +[source,java] +---- +// Read all the employees, acquire a unit of work, and register them + +// Read all the employees from the database. This requires 1 SQL call, +// but will be very memory intensive as 10,000 objects will be read +List employees = sourceSession.readAllObjects(Employee.class); + +//SQL: Select * from Employee + +// Acquire a unit of work and register the employees +UnitOfWork uow = targetSession.acquireUnitOfWork(); +uow.registerAllObjects(employees); +uow.commit(); +---- + +SQL + +[source,sql] +---- +BEGIN +Update Sequence set count = count + 1 where name = 'EMP' +Select count from Sequence +// ... repeat this 10,000 times + 10,000 times for the addresses ... +COMMIT +BEGIN +Insert into Address (...) values (...) +// ... repeat this 10,000 times +Insert into Employee (...) values (...) +// ... repeat this 10,000 times +COMMIT +---- + +This batch job performs poorly, because it requires 60,000 SQL +executions. It also reads huge amounts of data into memory, which can +raise memory performance issues. EclipseLink offers several optimization +features to improve the performance of this batch job. + +To improve this operation, do the following: + +* Use EclipseLink batch read operations and cursor support (see +link:#Cursors[Cursors]). +* Use batch writing or parameterized batch writing to write to the +database (see link:#Batch_Writing_and_Parameterized_SQL[Batch Writing +and Parameterized SQL]). If your database does not support batch +writing, use parameterized SQL to implement the write query. +* Implement sequence number preallocation (see +link:#Sequence_Number_Preallocation[Sequence Number Preallocation]). +* Implement multiprocessing (see +link:#Multiprocessing[Multiprocessing]). + +===== Cursors + +To optimize the query in the link:#Example_11-16[No Optimization] +example, use a cursored stream to read the Employees from the source +database. You can also employ a weak identity map instead of a hard or +soft cache identity map in both the source and target databases. + +To address the potential for memory problems, use the +`+releasePrevious+` method after each read to stream the cursor in +groups of 100. Register each batch of 100 employees in a new unit of +work and commit them. + +Although this does not reduce the amount of executed SQL, it does +address potential out-of-memory issues. When your system runs out of +memory, the result is performance degradation that increases over time, +and excessive disk activity caused by memory swapping on disk. + +For more information, see +link:#How_to_Use_Cursored_Streams_and_Scrollable_Cursors_for_Optimization[How +to Use Cursored Streams and Scrollable Cursors for Optimization]. + +===== Batch Writing and Parameterized SQL + +Batch writing lets you combine a group of SQL statements into a single +statement and send it to the database as a single database execution. +This feature reduces the communication time between the application and +the server, and substantially improves performance. + +You can enable batch writing alone (dynamic batch writing) using +`+Login+` method `+useBatchWriting+`. If you add batch writing to the +link:#Example_11-16[No Optimization] example, you execute each batch of +100 employees as a single SQL execution. This reduces the number of SQL +executions from 20,200 to 300. + +You can also enable batch writing and parameterized SQL (parameterized +batch writing) and prepared statement caching. Parameterized SQL avoids +the prepare component of SQL execution. This improves write performance +because it avoids the prepare cost of an SQL execution. For +parameterized batch writing you would get one statement per Employee, +and one for Address: this reduces the number of SQL executions from +20,200 to 400. Although this is more than dynamic batch writing alone, +parameterized batch writing also avoids all parsing, so it is much more +efficient overall. + +Although parameterized SQL avoids the prepare component of SQL +execution, it does not reduce the number of executions. Because of this, +parameterized SQL alone may not offer as big of a gain as batch writing. +However, if your database does not support batch writing, parameterized +SQL will improve performance. If you add parameterized SQL in the +link:#Example_11-16[No Optimization] example, you must still execute +20,200 SQL executions, but parameterized SQL reduces the number of SQL +PREPAREs to 4. + +For more information, see +link:#How_to_Use_Batch_Writing_for_Optimization[How to Use Batch Writing +for Optimization]. + +===== Sequence Number Preallocation + +SQL select calls are more resource-intensive than SQL modify calls, so +you can realize large performance gains by reducing the number of select +calls you issue. The code in the link:#Example_11-16[No Optimization] +example uses the select calls to acquire sequence numbers. You can +substantially improve performance if you use sequence number +preallocation. + +In EclipseLink, you can configure the sequence preallocation size on the +login object (the default size is 50). The link:#Example_11-16[No +Optimization] example uses a preallocation size of 1 to demonstrate this +point. If you stream the data in batches of 100 as suggested in +link:#Cursors[Cursors], set the sequence preallocation size to 100. +Because employees and addresses in the example both use sequence +numbering, you further improve performance by letting them share the +same sequence. If you set the preallocation size to 200, this reduces +the number of SQL execution from 60,000 to 20,200. + +For more information about sequencing preallocation, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_and_Preallocation_Size[Sequencing +and Preallocation Size]. + +===== Multiprocessing + +You can use multiple processes or multiple machines to split the batch +job into several smaller jobs. In this example, splitting the batch job +across threads enables you to synchronize reads from the cursored +stream, and use parallel Units of Work on a single machine. + +This leads to a performance increase, even if the machine has only a +single processor, because it takes advantage of the wait times inherent +in SQL execution. While one thread waits for a response from the server, +another thread uses the waiting cycles to process its own database +operation. + +The following example illustrates the optimized code for this example. +Note that it does not illustrate multiprocessing. + +[#Example 11-17]## *_Fully Optimized_* + +JPA + +[source,java] +---- +// Read each batch of employees, begin a transaction, and persist them +Map properties = new HashMap(); +properties.put("eclipselink.jdbc.batch-writing", "JDBC"); +properties.put("eclipselink.jdbc.cache-statements", "true"); +EntityManagerFactory factory = Persistence.createEntityManagerFactory("my-batch-app", properties); +EntityManager targetEntityManager = factory.createEntityManager(); + +// Read all the page of employees from the database. +// This requires 1 SQL call for each page, but fewer rows. +Query query = sourceEntityManager.createQuery("Select e from Employee e"); +int start = 0; +boolean done = false; +while (!done) { + query.setFirstResult(start); + query.setMaxRows(start + 100); + List page = query.getResultList(); + start = start + 100; + if (page.size() < 100) { + done = true; + } + //SQL: Select * from Employee. Process each batch + targetEntityManager.getTransaction().begin(); + for (Employee employee : employees) { + targetEntityManager.persist(employee); + } + targetEntityManager.getTransaction().commit(); +} +---- + +Native API + +[source,java] +---- +// Read each batch of employees, acquire a unit of work, and register them +targetSession.getLogin().useBatchWriting(); +targetSession.getLogin().setSequencePreallocationSize(200); +targetSession.getLogin().bindAllParameters(); +targetSession.getLogin().cacheAllStatements(); +targetSession.getLogin().setMaxBatchWritingSize(200); +... + +// Read all the employees from the database into a stream. +// This requires 1 SQL call, but none of the rows will be fetched. +ReadAllQuery query = new ReadAllQuery(Employee.class); +query.useCursoredStream(); +CursoredStream stream; +stream = (CursoredStream) sourceSession.executeQuery(query); +//SQL: Select * from Employee. Process each batch +while (! stream.atEnd()) { + List employees = stream.read(100); + // Acquire a unit of work to register the employees + UnitOfWork uow = targetSession.acquireUnitOfWork(); + uow.registerAllObjects(employees); + uow.commit(); +} +---- + +SQL + +[source,sql] +---- +BEGIN +Update Sequence set count = count + 200 where name = 'SEQ' +Select count from Sequence where name = 'SEQ' +COMMIT +BEGIN +BEGIN BATCH +Insert into Address (...) values (...) +//... repeat this 100 times +Insert into Employee (...) values (...) +//... repeat this 100 times +END BATCH +COMMIT +---- + +== Optimizing the Unit of Work + +For best performance when using a unit of work, consider the following +tips: + +* Register objects with a unit of work only if objects are eligible for +change. If you register objects that will not change, the unit of work +needlessly clones and processes those objects. +* Avoid the cost of existence checking when you are registering a new or +existing object (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Use_Registration_and_Existence_Checking[How +to Use Registration and Existence Checking]). +* Avoid the cost of change set calculation on a class you know will not +change by telling the unit of work that the class is read-only (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Declaring_Read-Only_Classes[Declaring +Read-Only Classes]). +* Avoid the cost of change set calculation on an object read by a +`+ReadAllQuery+` in a unit of work that you do not intend to change by +unregistering the object (see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How_to_Unregister_Working_Clones[How +to Unregister Working Clones]). +* Before using conforming queries, be sure that it is necessary. For +alternatives, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using_Conforming_Queries_and_Descriptors[Using +Conforming Queries and Descriptors]. +* Enable weaving and change tracking to greatly improve transactional +performance. For more information, see +link:#Optimizing_Using_Weaving[Optimizing Using Weaving]. + +If your performance measurements show that you have a performance +problem during unit of work commit, consider using object level or +attribute level change tracking, depending on the type of objects +involved and how they typically change. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)#Unit_of_Work_and_Change_Policy[Unit +of Work and Change Policy]. + +== Optimizing Using Weaving + +We recommend that you enable weaving to improve performance. + +In addition to using weaving to transparently configure lazy loading +(indirection) and change tracking, EclipseLink uses weaving to make +numerous internal optimizations. + +We recommend that you enable weaving. Transactional performance can be +greatly improved through using weaving and change tracking. + +For more information, see +link:Introduction_to_EclipseLink_Application_Development_(ELUG)#Using_Weaving[Using +Weaving]. + +== Optimizing the Application Server and Database Optimization + +Configuring your application server and database correctly can have a +big impact on performance and scalabilty. Ensure that you correctly +optimize these key components of your application in addition to your +EclipseLink application and persistence. + +For your application or Java EE server, ensure your memory, thread pool +and connection pool sizes are sufficient for your server’s expected +load, and that your JVM has been configured optimally. + +Ensure that your database has been configured correctly for optimal +performance and its expected load. + +== Optimizing Storage and Retrieval of Binary Data in XML + +When working with Java API for XML Web Services (JAX-WS), you can use +XML binary attachments to optimize the storage and retrieval of binary +data in XML. Rather than storing the data as a base64 BLOB, you can +optimize it by sending the data as a Multipurpose Internet Mail +Extensions (MIME) attachment in order to retrieve it on the other end. + +To make the use of XML binary attachments, register an instance of the +`+org.eclipselink.persistence.ox.attachment.XMLAttachmentMarshaller+` or +`+XMLAttachmentUnmarshaller+` interface with the binding framework. +During a marshal operation, binary data will be handed into the +`+XMLAttachmentMarshaller+`, which will be required to provide an ID +that you can use at a later time to retrieve the data. + +EclipseLink runtime supports MtOM and SwaRef-style attachments. + +EclipseLink provides support for the following Java types as +attachments: + +* `+java.awt.Image+` +* `+javax.activation.DataHandler+` +* `+javax.mail.internet.MimeMultipart+` +* `+javax.xml.transform.Source+` +* `+byte[]+` +* `+Byte[]+` + +You can generate schema and mappings based on JAXB classes for these +types. + +You can configure which mappings will be treated as attachments and set +the MIME types of those attachments. You perform configurations using +the following JAXB annotations: + +* `+XmlAttachmentRef+`–Used on a `+DataHandler+` to indicate that this +should be mapped to a `+swaRef+` in the XML schema. This means it should +be treated as a SwaRef attachment. +* `+XmlMimeType+`–Specifies the expected MIME type of the mapping. When +used on a byte array, this value should be passed into the +`+XMLAttachmentMarshaller+` during a marshal operation. During schema +generation, this will result in an `+expectedContentType+` attribute +being added to the related element. +* `+XmlInlineBinaryData+`–Indicates that this binary field should always +be written inline as `+base64Binary+` and never treated as an +attachment. + +For information on JAXB annotations, see Chapter 8 of the specification +at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html + +Additionally, you have to set the schema type on a mapping going to +binary if it is to be considered an attachment: it is either +`+base64Binary+` or `+swaRef+`. + +[width="100%",cols="<100%",] +|=== +|*Note*: EclipseLink lets you override treating an object as an +attachment on a per-mapping basis. +|=== + +Consider the following examples. + +[#Example 11-44]## *_Using SwaRef_* + +[source,java] +---- + public class Employee { + + @XmlAttachmentRef + public DataHandler photo; + ... + } +---- + +The preceding code yeilds the following XML schema type: + +[source,xml] +---- + + + + + +---- + +The XML would look as follows: + +[source,xml] +---- + + attachment_id + +---- + +[#Example 11-45]## *_Using MtOM Without MimeType_* + +[source,java] +---- + public class Employee { + + public java.awt.Image photo; + ... + } +---- + +The preceding code generates the following XML schema type: + +[source,xml] +---- + + + + + + + +The XML would look as follows: + + + + + + +---- + +[#Example 11-46]## *_Using MtOM with MimeType_* + +[source,java] +---- + public class Employee { + + @XmlMimeType("image/jpeg") + public java.awt.Image photo; + ... + } +---- + +The preceding code generates the following XML schema type: + +[source,xml] +---- + + + + + +---- + +The XML would look as follows: + +[source,xml] +---- + + + + + +---- + +[#Example 11-47]## *_Using Binary Object with Forced Inline_* + +[source,java] +---- + public class Employee { + + @XmlInlineBinaryData + public java.awt.Image photo; + ... + } +---- + +The preceding code generates the following XML schema type: + +[source,xml] +---- + + + + + +---- + +The XML would look as follows: + +[source,xml] +---- + + ASWIUHFD1323423OIJEUFHEIUFWE134DFO3IR3298RY== + +---- + +If you are not using JAXB, use the +`+org.eclipselink.persistence.ox.mappings.XMLBinaryDataMapping+` and +`+XMLBinaryDataCollectionMapping+` API to handle binary data. For more +information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Binary_Data_Mapping[XML +Binary Data Mapping] and +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Binary_Data_Collection_Mapping[XML +Binary Data Collection Mapping]. + +=== How to Use an Attachment Marshaller and Unmarshaller + +You implement EclipseLink `+XMLAttachmentMarshaller+` and +`+XMLAttachmentUnmarshaller+` interfaces to add and retrieve various +types of XML attachments. An `+XMLMarshaller+` holds an instance of an +`+XMLAttachmentMarshaller+`, and `+XMLUnmarshaller+`–an instance of an +`+XMLAttachmentUnmarshaller+`. + +You set and obtain an attachment marshaller and unmarshaller using the +following corresponding `+XMLMarshaller+` and `+XMLUnmarshaller+` +methods: `+setAttachmentMarshaller(XMLAttachmentMarshaller am)+` +`+getAttachmentMarshaller()+` +`+setAttachmentUnmarshaller(XMLAttachmentUnmarshaller au)+` +`+getAttachmentUnmarshaller()+` + +The following example shows how to use an attachment marshaller in your +application. + +[#Example 11-48]## *_Using an Attachment Marshaller_* + +[source,java] +---- + ... + XMLMarshaller marshaller = context.createMarshaller(); + XMLAttachmentMarshaller am = new EmployeeAttachmentMarshaller(); + marshaller.setAttachmentMarshaller(am); + ... +---- + +For the preceding example to be valid, the XML schema type should be set +to `+swaRef+`. + +For more information, see +link:Introduction_to_XML_Projects_(ELUG)#How_to_Use_EclipseLink_XMLContext[How +to Use EclipseLink XMLContext]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Relational_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Relational_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..fc000d499f6 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Relational_Descriptors_(ELUG).adoc @@ -0,0 +1,30 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +== Relational Descriptors + +The following sections describe how to create and configure relational +descriptors: + +* link:Introduction_to_Relational_Descriptors_(ELUG)[Introduction to +Relational Descriptors] + +* link:Creating_a_Relational_Descriptor_(ELUG)[Creating a Relational +Descriptor] + +* link:Configuring_a_Relational_Descriptor_(ELUG)[Configuring a +Relational Descriptor] – explains how to configure descriptor options +specific to a relational descriptor. + +*Special:Whatlinkshere_Relational_Descriptors_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_ORM[Category: ORM] diff --git a/docs/docs.ug/src/main/asciidoc/core/Relational_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Relational_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..d4a827021f2 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Relational_Mappings_(ELUG).adoc @@ -0,0 +1,29 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +A relational mapping transforms any object data member type to a +corresponding relational database (SQL) data source representation in +any supported relational database. Relational mappings let you map an +object model into a relational data model. + +Consider the following sections: + +* link:Introduction_to_Relational_Mappings_(ELUG)[Introduction to +Relational Mappings] – describes each of the different EclipseLink +relational mapping types and important relational mapping concepts. + +* link:Configuring_a_Relational_Mapping_(ELUG)[Configuring a Relational +Mapping] – explains how to configure EclipseLink relational mapping +options common to two or more relational mapping types. + +*Special:Whatlinkshere_Relational_Mappings_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Troubleshooting_an_EclipseLink_Application_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Troubleshooting_an_EclipseLink_Application_(ELUG).adoc new file mode 100644 index 00000000000..90140555b57 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Troubleshooting_an_EclipseLink_Application_(ELUG).adoc @@ -0,0 +1,18 @@ +Consider the following sections: + +* link:EclipseLink_Exception_Error_Reference_(ELUG)[EclipseLink +Exception Error Reference] – lists exceptions that may occur at time of +deployment of an EclipseLink application, as well as at run time. + +* link:EclipseLink_Workbench_Error_Reference_(ELUG)[EclipseLink +Workbench Error Reference] – describes common problems and their +solutions when using EclipseLink Workbench. + +*Special:Whatlinkshere_Troubleshooting_an_EclipseLink_Application_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_Advanced_Query_API_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_Advanced_Query_API_(ELUG).adoc new file mode 100644 index 00000000000..ab4d189a0ea --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_Advanced_Query_API_(ELUG).adoc @@ -0,0 +1,744 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Using_Advanced_Query_API_(ELUG)[Related +Topics] + +For more information about the available query API, see _EclipseLink API +Reference_. + +== Using Redirect Queries + +A redirect query is a named query that delegates query execution control +to your application. redirect queried allow you to define the query +implementation in code as a static method. + +To perform complex operations, you can combine query redirectors with +the EclipseLink query framework. + +=== How to Create a Redirect Query + +To perform complex operations, you can combine query redirectors with +the EclipseLink query framework. To create a redirector, implement the +`+org.eclipse.persistence.queries.QueryRedirector+` interface. The query +mechanism executes the +`+Object invokeQuery(DatabaseQuery query, Record arguments, Session session)+` +method and waits for the results. + +EclipseLink provides one preimplemented redirector, the +`+MethodBasedQueryRedirector+` method. To use this redirector, create a +static invoke method on a class, and use the `+setMethodName(String)+` +call to specify the method to invoke. + +[#Example 107-1]## *_Redirect Query_* + +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+query.setName("findEmployeeByAnEmployee");+` +`+query.addArgument("employee");+` + +`+MethodBaseQueryRedirector redirector = new+` +`+     MethodBaseQueryRedirector(QueryRedirectorTest.class, "findEmployeeByAnEmployee");+` +`+query.setRedirector(redirector);+` +`+Descriptor descriptor = getSession().getDescriptor(query.getReferenceClass());+` +`+descriptor.getQueryManager().addQuery(query.getName(), query);+` + +`+List args = new ArrayList();+` `+args.addElement(employee);+` +`+objectFromDatabase = +` +`+    getSession().executeQuery("findEmployeeByAnEmployee", Employee.class, args);+` + +`+public class QueryRedirectorTest {+` + +`+    public static Object findEmployeeByAnEmployee(+` +`+                                 DatabaseQuery query,+` +`+                                 org.eclipse.peristence.sessions.Record arguments,+` +`+                                 org.eclipse.peristence.sessions.Session+` +`+                                 session) {+` +`+        ((ReadObjectQuery) query).setSelectionObject(arguments.get("employee"));+` +`+        return session.executeQuery(query);+` `+    }+` `+}+` + +== Using Historical Queries + +To make a query time-aware, you specify an `+AsOfClause+` that +EclipseLink appends to the query. Use the `+AsOfClause+` class if your +historical schema is based on time stamps or the `+AsOfSCNClause+` class +if your historical schema is based on database system change numbers. +You can specify an `+AsOfClause+` at the time you acquire a historical +session so that EclipseLink appends the same clause to all queries, or +you can specify an `+AsOfClause+` on a query-by-query basis. + +The following example shows how to create a query that uses a particular +`+AsOfClause+`. This query will read all `+Employee+` objects as of the +time specified by `+timestamp+` using the appropriate history tables +described by the `+HistoryPolicy+` set on the `+Employee+` descriptor. + +[#Example 107-2]## *_Using a Historical Session_* + +`+ReadAllQuery historicalQuery = new ReadAllQuery(Employee.class);+` +`+AsOfClause asOfClause = new AsOfClause(timestamp);+` +`+historicalQuery.setAsOfClause(asOfClause);+` +`+historicalQuery.dontMaintainCache();+` +`+List pastEmployees = (List)historicalSession.executeQuery(historicalQuery);+` + +== Using Queries with Fetch Groups + +You can use a fetch group with a `+ReadObjectQuery+` or +`+ReadAllQuery+`. When you execute the query, EclipseLink retrieves only +the attributes in the fetch group. EclipseLink automatically executes a +query to fetch all the attributes excluded from this subset when and if +you call a getter method on any one of the excluded attributes. + +[width="100%",cols="<100%",] +|=== +|*Note:* When you use fetch groups outside of CMP, use weaving (see +link:Introduction%20to%20EclipseLink%20Application%20Development%20(ELUG)[Using +Weaving]). +|=== + +This section describes the following: + +* link:#How_to_Configure_Default_Fetch_Group_Behavior[How to Configure +Default Fetch Group Behavior] +* link:#How_to_Query_with_a_Static_Fetch_Group[How to Query with a +Static Fetch Group] +* link:#How_to_Query_with_a_Dynamic_Fetch_Group[How to Query with a +Dynamic Fetch Group] + +For more information about fetch groups, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Fetch_Groups_and_Object-Level_Read_Queries[Fetch +Groups and Object-Level Read Queries]. + +=== How to Configure Default Fetch Group Behavior + +You can optionally designate at most one fetch group as the default +fetch group for a descriptor’s reference class. + +If you execute a `+ReadObjectQuery+` or `+ReadAllQuery+` without +specifying a fetch group, EclipseLink will use the default fetch group +unless you configure the query otherwise, as this example shows. + +[#Example 107-3]## *_Configuring Default Fetch Group Behavior_* + +*`+//\'\' \'\'at\'\' \'\'the\'\' \'\'descriptor\'\' \'\'level+`* +`+FetchGroup group = new FetchGroup("nameOnly");+` +`+group.addAttribute("firstName");+` `+group.addAttribute("lastName");+` +`+employeeDescriptor.getFetchGroupManager().addFetchGroup(group);+` +*`+//\'\' \'\'set\'\' \'\'the\'\' \'\'default\'\' \'\'fetch\'\' \'\'group+`* +`+employeeDescriptor.getFetchGroupManager().setDefaultFetchGroup(group);+` + +*`+//\'\' \'\'when\'\' \'\'query1\'\' \'\'is\'\' \'\'executed,\'\' \'\'the\'\' \'\'default\'\' \'\'fetch\'\' \'\'group\'\' \'\'applies+`* +`+ReadAllQuery query1 = new ReadAllQuery(Employee.class);+` + +*`+//\'\' \'\'when\'\' \'\'query2\'\' \'\'is\'\' \'\'executed,\'\' \'\'the\'\' \'\'default\'\' \'\'fetch\'\' \'\'group\'\' \'\'does\'\' \'\'not\'\' \'\'apply+`* +`+ReadAllQuery query2 = new ReadAllQuery(Employee.class);+` +`+query2.setShouldUsedefaultFetchGroup(false);+` + +=== How to Query with a Static Fetch Group + +link:#Example_107-4[Configuring a Query with a FetchGroup Using the +FetchGroupManager] shows how to configure a `+ReadObjectQuery+` for the +`+Employee+` class with a `+FetchGroup+` named `+nameOnly+` previously +stored in the `+FetchGroupManager+` owned by the `+Employee+` class’s +descriptor. + +[#'Example 107-4]## *’ Configuring a Query with a FetchGroup Using the +FetchGroupManager*’’ + +In this example, only the `+Employee+` attributes `+firstName+` and +`+lastName+` are fetched. If you call the `+Employee+` method `+get+` +for any other attribute, EclipseLink executes another query to retrieve +all unfetched attribute values. Thereafter, calling that `+get+` method +will return the value directly from the object. + +*`+//\'\' \'\'create\'\' \'\'static\'\' \'\'fetch\'\' \'\'group\'\' \'\'at\'\' \'\'the\'\' \'\'descriptor\'\' \'\'level+`* +`+FetchGroup group = new FetchGroup("nameOnly");+` +`+group.addAttribute("firstName");+` `+group.addAttribute("lastName");+` +`+descriptor.getFetchGroupManager().addFetchGroup(group);+` + +*`+//\'\' \'\'use\'\' \'\'static\'\' \'\'fetch\'\' \'\'group\'\' \'\'at\'\' \'\'query\'\' \'\'level+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setFetchGroupName("nameOnly");+` + +=== How to Query with a Dynamic Fetch Group + +link:#Example_107-5[Configuring a Query with a FetchGroup Dynamically] +shows how to create a `+FetchGroup+` instance dynamically, at the time +you create and execute a query, and configure the query with that +`+FetchGroup+` directly. + +In this example, only the `+firstName+`, `+lastName+`, and `+salary+` +attributes are fetched. If you call the `+Employee+` method `+get+` for +any other attribute, EclipseLink executes another query to retrieve all +unfetched attribute values. Thereafter, calling that `+get+` method will +return the value directly from the object. + +[#Example 107-5]## *_Configuring a Query with a FetchGroup Dynamically_* + +*`+//\'\' \'\'dynamic\'\' \'\'fetch\'\' \'\'group\'\' \'\'query+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+FetchGroup group = new FetchGroup("nameAndSalary");+` +`+group.addAttribute("firstName");+` `+group.addAttribute("lastName");+` +`+group.addAttribute("salary");+` `+query. setFetchGroup(group);+` + +== Using Read-Only Queries + +This example shows how to create an object-level read query to return +data that you know is read-only. Using such a query for read-only data +can improve performance. + +[#Example 107-6]## *_Configuring an ObjectLevelReadQuery as Read-Only_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setIsReadOnly(true);+` + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Read-Only +Query] +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[How to Use +Read-Only Queries for Optimization] + +== Querying on Interfaces + +When you define descriptors for an interface to enable querying, +EclipseLink supports querying on an interface, as follows: + +* If there is only a single implementor of the interface, the query +returns an instance of the concrete class. +* If there are multiple implementors of the interfaces, the query +returns instances of all implementing classes. + +== Querying on an Inheritance Hierarchy + +When you query on a class that is part of an inheritance hierarchy, the +session checks the descriptor to determine the type of the class, as +follows: + +* If you configure the descriptor to read subclasses (the default +configuration), the query returns instances of the class and its +subclasses. +* If you configure the descriptor not to read subclasses, the query +returns only instances of the queried class, but no instances of the +subclasses. +* If you configure the descriptor to outer-join subclasses, the query +returns instances of the class and its subclasses. +* If neither of these conditions applies, the class is a leaf class and +does not have any subclasses. The query returns instances of the queried +class. + +== Appending Additional Join Expressions + +You can set the query manager to automatically append an expression to +every query it performs on a class. For example, you can add an +expression that filters the database for the valid instances of a given +class. + +Use this to do the following: + +* Filter logically deleted objects +* Enable two independent classes to share a single table without +inheritance +* Filter historical versions of objects + +=== How to Append Additional Join Expressions Using Java + +Using Java, configure a descriptor with additional join expressions by +creating an amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Amendment +Methods]), and then using the `+DescriptorQueryManager+` methods +`+setAdditionalJoinExpression+` or `+setMultipleTableJoinExpression+`, +as this example shows. + +[#Example 107-7]## *_Registering a Query That Includes a Join +Expression_* + +In this exmaple, the `+join+` expression filters invalid instances of +`+employee+` from the query. + +`+public static void addToDescriptor(Descriptor descriptor) {+` +`+    ExpressionBuilder builder = new ExpressionBuilder();+` +`+    descriptor.getQueryManager().setAdditionalJoinExpression(+` +`+        (builder.getField("EMP.STATUS").notEqual("DELETED")).and(+` +`+             builder.getField("EMP.STATUS").notEqual("HISTORICAL"))+` +`+    );+` `+}+` + +== Using Queries on Variable One-to-One Mappings + +EclipseLink does not provide a method to directly query against variable +one-to-one mappings. To query against this type of mapping, combine +EclipseLink `+DirectQueryKeys+` and EclipseLink `+ReportQueries+` to +create query selection criteria for classes that implement the +interface, as follows: + +[arabic] +. Create two `+DirectQueryKeys+` to query for the possible implementors +of the interface: +* The first `+DirectQueryKey+` is for the class indicator field for the +variable one-to-one mapping. +* The second `+DirectQueryKey+` is for the foreign key to the class or +table that implements the interface. +. Create a `+subSelect+` statement for each concrete class that +implements the interface included in the query selection criteria. +. Implement a `+ReportQuery+`. + +[#Example 107-8]## *_Creating DirectQueryKeys_* + +*`+//\'\' \'\'The\'\' \'\'DirectQueryKeys\'\' \'\'as\'\' \'\'generated\'\' \'\'in\'\' \'\'the\'\' \'\'EclipseLink\'\' \'\'project\'\' \'\'Java+`* +`+// source code from Workbench +` `+…+` +`+descriptor.addDirectQueryKey("locationTypeCode","DEALLOCATION.DEALLOCATIONOBJECTTYPE");+` +`+descriptor.addDirectQueryKey("locationTypeId","DEALLOCATION.DEALLOCATIONOBJECTID");     +` + +== Using Oracle Database Features + +If you are using Oracle Database, you can take advantage of EclipseLink +support for the following Oracle Database features: + +* Oracle Hints (see link:#How_to_Use_Oracle_Hints[How to Use Oracle +Hints]) +* Hierarchical Queries (see link:#How_to_Use_Hierarchical_Queries[How to +Use Hierarchical Queries]) + +=== How to Use Oracle Hints + +Oracle Hints is an Oracle Database feature through which you can make +decisions usually reserved for the optimizer. You use hints to specify +things such as join order for a join statement, or the optimization +approach of an SQL call. + +The EclipseLink query framework supports Oracle Hints with the following +API: + +`+setHintString("/*+`_`+[hints\'\' \'\'or\'\' \'\'comments]+`_`+*/");+` +`+ +` + +EclipseLink adds the hint to the SQL string as a comment immediately +following a `+SELECT+`, `+UPDATE+`, `+INSERT+`, or `+DELETE+` statement. + +Add hints to a read query as follows: + +[arabic] +. Create a `+ReadObjectQuery+` or a `+ReadAllQuery+` +. Set the selection criteria. +. Add hints as needed. + +For example, the following code uses the `+FULL+` hint (which explicitly +chooses a full table scan for the specified table): + +*`+//\'\' \'\'Create\'\' \'\'the\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +*`+//\'\' \'\'Retrieve\'\' \'\'ExpressionBuilder\'\' \'\'from\'\' \'\'the\'\' \'\'query+`* +`+ExpressionBuilder builder = query.getExpressionBuilder();+` +`+query.setSelectionCritera(builder.get("id").equal(new Integer(1));+` +*`+//\'\' \'\'Add\'\' \'\'the\'\' \'\'hint+`* +`+query.setHintString("/*+ FULL */" ); +` + +This code generates the following SQL: + +`+SELECT /*+ FULL */ FROM EMPLOYEE WHERE ID=1+` + +To add hints to `+WRITE+`, `+INSERT+`, `+UPDATE+`, and `+DELETE+`, +create custom queries for these operations in the EclipseLink query +framework, then specify hints as required. For more information, see the +following: + +* link:Configuring%20a%20Relational%20Descriptor%20(ELUG)[Configuring +Custom SQL Queries for Basic Persistence Operations] +* link:Configuring%20an%20EIS%20Descriptor%20(ELUG)[Configuring Custom +EIS Interactions for Basic Persistence Operations] + +For more information about the available hints, see the Oracle Database +documentation. + +=== How to Use Hierarchical Queries + +Hierarchical Queries is an Oracle Database mechanism that lets you +select database rows based on hierarchical order. For example, you can +design a query that reads the row of a given employee, followed by the +rows of people this employee manages, followed by their managed +employees, and so on. + +To create a hierarchical query, use the `+setHierarchicalQueryClause+` +method. This method takes three parameters, as follows: + +`+setHierarchicalQueryClause(startWith, connectBy, orderSibling)+` + +This expression requires all three parameters, as described in the +subsequent text. + +==== Using startWith Parameter + +The `+startWith+` parameter in the expression specifies the first object +in the hierarchy. This parameter mirrors the Oracle Database +`+START WITH+` clause. + +To include a `+startWith+` parameter, build an expression to specify the +appropriate object, and pass it as a parameter in the +`+setHierarchicalQueryClause+` method. If you do not specify the root +object for the hierarchy, set this value to `+null+`. + +==== Using connectBy Parameter + +The `+connectBy+` parameter specifies the relationship that creates the +hierarchy. This parameter mirrors the Oracle Database `+CONNECT BY+` +clause. + +Build an expression to specify the `+connectBy+` parameter, and pass it +as a parameter in the `+setHierarchicalQueryClause+` method. Because +this parameter defines the nature of the hierarchy, it is required for +the `+setHierarchicalQueryClause+` implementation. + +==== Using orderSibling Parameter + +The `+orderSibling+` parameter in the expression specifies the order in +which the query returns sibling objects in the hierarchy. This parameter +mirrors the Oracle Database `+ORDER SIBLINGS+` clause. + +To include an `+orderSibling+` parameter, define a vector, and to +include the order criteria, use the `+addElement+` method. Pass the +vector as the third parameter in the `+setHierarchicalQueryClause+` +method. If you do not specify an order, set this value to `+null+`. + +[#Example 107-9]## *_Hierarchical Query_* + +`+ReadAllQuery raq = new ReadAllQuery(Employee.class);+` +*`+//\'\' \'\'Specifies\'\' \'\'a\'\' \'\'START\'\' \'\'WITH\'\' \'\'expression+`* +`+Expression startExpr = expressionBuilder.get("id").equal(new Integer(1));+` +*`+//\'\' \'\'Specifies\'\' \'\'a\'\' \'\'CONNECT\'\' \'\'BY\'\' \'\'expression+`* +`+Expression connectBy = expressionBuilder.get("managedEmployees");+` +*`+//\'\' \'\'Specifies\'\' \'\'an\'\' \'\'ORDER\'\' \'\'SIBLINGS\'\' \'\'BY\'\' \'\'vector+`* +`+Vector order = new Vector();+` +`+order.addElement(expressionBuilder.get("lastName"));+` +`+order.addElement(expressionBuilder.get("firstName"));+` +`+raq.setHierarchicalQueryClause(startExpr, connectBy, order);+` +`+Vector employees = uow.executeQuery(raq);+` + +This code generates the following SQL: + +`+SELECT * FROM EMPLOYEE START WITH ID=1 CONNECT BY PRIOR ID=MANAGER_ID ORDER SIBLINGS BY LAST_NAME, FIRST_NAME+` + +== Handling Cursor and Stream Query Results + +Cursors and streams are related mechanisms that let you work with large +result sets efficiently. See +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Stream_and_Cursor_Query_Results[Stream +and Cursor Query Results] for more information. + +link:#Table_107-1[Stream and Cursor Query Result Options] table lists +the methods that EclipseLink provides for all subclasses of +`+DataReadQuery+` and `+ReadAllQuery+` that you can use to make your +query return its results as a cursor or stream. + +[#Table 107-1]## *_Stream and Cursor Query Result Options_* + +[width="100%",cols="<14%,<11%,<75%",options="header",] +|=== +|*Method* |*Query Returns* |*Description* +|`+useScrollableCursor+` |`+ScrollableCursor+` |Allows you access a +database result set cursor, allowing you to move forward and backward +through the result set. + +|`+useCursoredStream+` |`+CursoredStream+` |Allows you to access results +one at a time in sequence, as results become available to the underlying +database result set cursor. +|=== + +Using a `+ScrollableCursor+` or `+CursoredStream+` combines the features +of an EclipseLink with the ability of the database to cursor data, and +breaks up the result set into smaller, more manageable pieces. + +The behavior of a query that uses a `+ScrollableCursor+` or +`+CursoredStream+` differs from other queries in that the elements +requested by the client are sent to the client. + +This section describes the following: + +* link:#How_to_Handle_Cursors_and_Java_Iterators[How to Handle Cursors +and Java Iterators] +* link:#How_to_Handle_Java_Streams[How to Handle Java Streams] +* link:#How_to_Optimize_Streams[How to Optimize Streams] + +=== How to Handle Cursors and Java Iterators + +The EclipseLink scrollable cursor lets you scroll through a result set +from the database without reading the whole result set in a single +database read operation. The `+ScrollableCursor+` class implements the +Java `+ListIterator+` interface to allow for direct and relative access +within the stream. Scrollable cursors also let you scroll forward and +backward through the stream. + +==== Traversing Data with Scrollable Cursors + +The following methods let you navigate data with a scrollable cursor: + +* `+relative(int i)+`: advances the row number in relation to the +current row by one row +* `+absolute(int i)+`: places the cursor at an absolute row position, 1 +being the first row + +Several strategies are available for traversing data with cursors. For +example, to start at the end of the data set and work toward the first +record, do the following: + +[arabic] +. Call the `+afterLast+` method to place the cursor after the last row +in the result set. +. Use the `+hasPrevious+` method to determine whether there is a record +above the current record. This method returns `+false+` when you reach +the final record in the data set. +. If the `+hasPrevious+` method returns `+true+`, call the `+previous+` +method to move the cursor to the row prior to the current row and read +that object. + +These are common methods for data traversal, but they are not the only +available methods. For more information about the available methods, see +_EclipseLink API Reference_. + +To use the `+ScrollableCursor+` object, the JDBC driver must be +compatible with the JDBC 2.0 specifications. + +[#107-10]## *_Example Traversing with a Scrollable Cursor_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.useScrollableCursor();+` +`+ScrollableCursor cursor = (ScrollableCursor) session.executeQuery(query);+` + +`+while (cursor.hasNext()) {+` +`+    System.out.println(cursor.next().toString());+` `+}+` +`+cursor.close();+` + +=== How to Handle Java Streams + +Java streams let you retrieve query results as individual records or +groups of records, which can result in a performance increase. You can +use streams to build efficient EclipseLink queries, especially when the +queries are likely to generate large result sets. + +==== Using Cursored Stream Support + +Cursored streams provide the ability to read back a query result set +from the database in manageable subsets, and to scroll through the +result set stream. + +The `+useCursoredStream+` method of the `+ReadAllQuery+` class provides +cursored stream support. + +[#Example 107-11]## *_Cursored Streams_* + +`+CursoredStream stream;+` +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.useCursoredStream();+` +`+stream = (CursoredStream) session.executeQuery(query);+` + +The query returns an instance of `+CursoredStream+` rather than a +`+List+`, which can be a more efficient approach. For example, consider +the following two code examples. The link:#Example_107-12[Using a List] +example returns a `+List+` that contains all employee objects. If ACME +has 10,000 employees, the `+List+` contains references to 10,000 +`+Employee+` objects. + +[#Example 107-12]## *_Using a List_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+Enumeration employeeEnumeration;+` + +`+List employees = (List) session.executeQuery(query);+` +`+employeeEnumeration = employee.elements();+` + +`+while (employeeEnumeration.hasMoreElements()) {+` +`+    Employee employee = (Employee) employeeEnumeration.nextElement();+` +`+    employee.doSomeWork();+` `+}+` + +The following example returns a `+CursoredStream+` instance rather than +a `+List+`. The `+CursoredStream+` collection appears to contain all +10,000 objects, but initially contains a reference to only the first 10 +`+Employee+` objects. It retrieves the remaining objects in the +collection as they are needed. In many cases, the application never +needs to read all the objects: + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.useCursoredStream();+` + +`+CursoredStream stream = (CursoredStream) session.executeQuery(query);+` +`+while (! stream.atEnd()) {+` +`+    Employee employee = (Employee) stream.read();+` +`+    employee.doSomeWork();+` `+    stream.releasePrevious();+` `+}+` +`+stream.close();+` + +[width="100%",cols="<100%",] +|=== +|*Note*: The `+releasePrevious+` message is optional. This releases any +previously read objects and frees system memory. Even though released +objects are removed from the cursored stream storage, they may remain in +the identity map. +|=== + +=== How to Optimize Streams + +To optimize `+CursoredStream+` performance, provide a _threshold_ and +_page size_ to the `+useCursoredStream(Threshold, PageSize)+` method, as +follows: + +* The threshold specifies the number of objects to read into the stream +initially. The default threshold is 10. +* The page size specifies the number of objects to read into the stream +after the initial group of objects. This occurs after the threshold +number of objects is read. Although larger page sizes result in faster +overall performance, they introduce delays into the application when +EclipseLink loads each page. The default page size is 5. + +When you execute a batch-type operation, use the `+dontMaintainCache+` +method with a cursored stream. A batch operation performs simple +operations on large numbers of objects and then discards the objects. +Cursored streams create the required objects only as needed, and the +`+dontMaintainCache+` ensures that these transient objects are not +cached. + +== Handling Query Results Using Pagination + +You can configure a query to retrieve a result set in pages, that is, a +partial result as a List of pageSize (or less) results. The following +example demonstrates paging through the result set of a query using +`+ReadQuery+` methods `+setMaxRows+` and `+setFirstResult+`. + +For more information, see the following: + +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_Result_Set_Pagination_for_Optimization[How +to Use Result Set Pagination for Optimization] +* link:Optimizing_the_EclipseLink_Application_%28ELUG%29#How_to_Use_JDBC_Fetch_Size_for_Optimization[How +to Use JDBC Fetch Size for Optimization] + +[#Example 107-13]## *_Using setMaxRows and setFirstResult to Page +Through a Result Set_* + +`+...+` `+int pageSize = 100;+` `+int firstResult = 0;+` +`+int maxRows = pageSize;+` `+boolean hasNext = true;+` +`+List page = null;+` + +`+while (hasNext) {+` `+    query.setFirstResult(firstResult);+` +`+    query.setMaxRows(maxRows);+` +`+    page = (List)sesssion.executeQuery(query);+` +`+    +`*`+//\'\' \'\'process\'\' \'\'this\'\' \'\'page\'\' \'\'of\'\' \'\'results+`* +`+    if (page.size() == 0) {+` `+        hasNext = false;+` +`+    } else {+` `+        firstResult = firstResult + pageSize;+` +`+        maxRows = maxRows + pageSize;+` `+    }+` `+}+` `+...+` + +== Using Queries and the Cache + +This section describes how to use caching options in EclipseLink +queries, including the following: + +* link:#How_to_Cache_Results_in_a_ReadQuery[How to Cache Results in a +ReadQuery] +* link:#How_to_Configure_Cache_Expiration_at_the_Query_Level[How to +Configure Cache Expiration at the Query Level] + +=== How to Cache Results in a ReadQuery + +By default, each time you execute a `+ReadQuery+`, EclipseLink applies +the current query configuration to the read operation. In doing so, +EclipseLink will access the session cache, the data source, or both. + +Some queries are known to return the same result set (for example, the +number of units sold last year by the current sales person). After the +first query execution, there is no need to actually execute the query if +it is invoked again. + +For these types of queries, you can use any EclipseLink `+ReadQuery+` +and configure it to store its query results in an internal query cache. + +After its first execution for a set of query parameters, the query will +return its cached result set each time it is invoked with the same query +parameters. This improves query performance for frequently executed +queries. By default a query will cache the results sets for the last 100 +queries of specific parameters. You can configure this query cache as +part of the `+QueryResultsCachePolicy+`. + +Enable this feature using `+ReadQuery+` method `+cacheQueryResults+` or +by calling the `+ReadQuery+` method `+setQueryResultsCachePolicy+` with +an instance of `+QueryResultsCachePolicy+`, and disable it using +`+ReadQuery+` method `+doNotCacheQueryResults+`. + +Before using this feature, consider the restrictions in +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Internal Query +Cache Restrictions]. For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[How to Cache +Query Results in the Query Cache]. + +You can apply a cache invalidation policy to the query’s internal cache +(see link:#How_to_Configure_Cache_Expiration_at_the_Query_Level[How to +Configure Cache Expiration at the Query Level]). For more information, +see link:Introduction%20to%20Cache%20(ELUG)#Cache_Invalidation[Cache +Invalidation]. + +This example shows how to configure a `+ReadQuery+` to cache its +results. + +[#Example 107-14]## *_Configuring a ReadQuery to Cache Its Query +Results_* + +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` + +*`+//\'\' \'\'Instruct\'\' \'\'the\'\' \'\'ReadQuery\'\' \'\'to\'\' \'\'cache\'\' \'\'its\'\' \'\'query\'\' \'\'results+`* +`+query.cacheQueryResults();+` + +*`+//\'\' \'\'The\'\' \'\'first\'\' \'\'time\'\' \'\'you\'\' \'\'invoke\'\' \'\'it,\'\' \'\'the\'\' \'\'ReadQuery\'\' \'\'reads\'\' \'\'from\'\' \'\'the\'\' \'\'database,\'\' \'\'session+`* +*`+//\'\' \'\'cache,\'\' \'\'or\'\' \'\'both\'\' \'\'and\'\' \'\'stores\'\' \'\'the\'\' \'\'result\'\' \'\'set\'\' \'\'in\'\' \'\'its\'\' \'\'internal\'\' \'\'query\'\' \'\'cache+`* +`+Employee employeeFirst = (Employee) session.executeQuery(query);+` + +The following example shows how to configure the `+ReadQuery+` to stop +caching its results. The next time the query is executed, EclipseLink +does not use the query cache. Instead, the query accesses the data +source. + +[#Example 107-15]## *_Configuring a ReadQuery to Stop Caching Its Query +Results_* + +*`+//\'\' \'\'Disable\'\' \'\'query\'\' \'\'caching+`* +`+query.doNotCacheQueryResults();+` + +*`+//\'\' \'\'The\'\' \'\'ReadQuery\'\' \'\'does\'\' \'\'not\'\' \'\'use\'\' \'\'the\'\' \'\'query\'\' \'\'cahce\'\' \'\'and\'\' \'\'instead\'\' \'\'accesses\'\' \'\'the\'\' \'\'database+`* +`+Employee employee = (Employee) session.executeQuery(query);+` + +Alternatively, you can clear the query’s internal cache using +`+ReadQuery+` method `+clearQueryResults+` passing in your session. This +clears the currently cached results and ensures that the next query +execution reads from the database. + +=== How to Configure Cache Expiration at the Query Level + +You can configure a `+ReadQuery+` with a `+CacheInvalidationPolicy+`. + +If you configure a query to cache results in its own internal cache (see +link:#How_to_Cache_Results_in_a_ReadQuery[How to Cache Results in a +ReadQuery]), the cache invalidation policy allows the cached query +result set to expire, based on a time-to-live or daily-expiry. This +invalidation time is calculated from the time of the query execution +that cached the query result set for the specific set of query +parameters. + +The following example shows how to configure a `+ReadQuery+` so that a +`+TimeToLiveCacheInvalidationPolicy+` is applied to all the objects +returned by the query and cached in the query’s internal cache. + +[#Example 107-16]## *_Configuring a CacheInvalidationPolicy on a +ReadQuery for the Query’s Internal Cache_* + +*`+//\'\' \'\'The\'\' \'\'TimeToLiveCacheInvalidationPolicy\'\' \'\'applies\'\' \'\'to\'\' \'\'all\'\' \'\'objects\'\' \'\'returned\'\' \'\'by\'\' \'\'the\'\' \'\'query\'\' \'\'and+`* +*`+//\'\' \'\'cached\'\' \'\'in\'\' \'\'the\'\' \'\'query's\'\' \'\'internal\'\' \'\'cache+`*`+ +` + +`+readQuery.setQueryResultsCachePolicy(+` +`+    new QueryResultsCachePolicy(new TimeToLiveCacheInvalidationPolicy(1000))+` +`+);+` + +For more information, see link:Introduction%20to%20Cache%20(ELUG)[Cache +Invalidation]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Query_API_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Query_API_(ELUG).adoc new file mode 100644 index 00000000000..10ba61df624 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Query_API_(ELUG).adoc @@ -0,0 +1,2009 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* + +For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)[Using Advanced Query API]. + +== Using Session Queries + +[width="100%",cols="<100%",] +|=== +|*Note* We recommend that you perform all data source operations using a +unit of work: doing so is the most efficient way to manage transactions, +concurrency, and referential constraints. For more information, see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]. +|=== + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Session_Queries[Session +Queries]. + +=== How to Read Objects with a Session Query + +Using the session query API, you can perform the following read +operations: + +* link:#Reading_an_Object_with_a_Session_Query[Reading an Object with a +Session Query] +* link:#Reading_All_Objects_with_a_Session_Query[Reading All Objects +with a Session Query] +* link:#Refreshing_an_Object_with_a_Session_Query[Refreshing an Object +with a Session Query] + +==== Reading an Object with a Session Query + +The `+readObject+` method retrieves a single object from the database. +The application must specify the class of object to read. If no object +matches the criteria, a null value is returned. + +For example, the basic read operation is: + +`+session.readObject(MyDomainObject.class);+` + +The following example returns the first instance of `+MyDomainObject+` +found in the table used for `+MyDomainObject+`. EclipseLink provides the +`+Expression+` class to specify querying parameters for a specific +object. + +When you search for a single, specific object using a primary key, the +`+readObject+` method is more efficient than the `+readAllObjects+` +method, because `+readObject+` can find an instance in the cache without +accessing database. Because a `+readAllObjects+` method does not know +how many objects match the criteria, it always searches the database to +find matching objects, even if it finds matching objects in the cache. + +[#Example 105-1]## *_readObject Using an Expression_* + +`+import org.eclipse.persistence.sessions.*;+` +`+import org.eclipse.persistence.expressions.*;+` `+...+` + +*`+//\'\' \'\'Use\'\' \'\'an\'\' \'\'expression\'\' \'\'to\'\' \'\'read\'\' \'\'in\'\' \'\'the\'\' \'\'employee\'\' \'\'whose\'\' \'\'last\'\' \'\'name\'\' \'\'is\'\' \'\'Smith.+`* +*`+//\'\' \'\'Create\'\' \'\'an\'\' \'\'expression\'\' \'\'using\'\' \'\'the\'\' \'\'Expression\'\' \'\'Builder\'\' \'\'and\'\' \'\'use\'\' \'\'it\'\' \'\'as\'\' \'\'the\'\' \'\'selection\'\' \'\'criterion\'\' \'\'of\'\' \'\'the\'\' \'\'search+`* +`+Employee employee = (Employee) session.readObject(Employee.class, new ExpressionBuilder().get("lastName").equal("Smith"));+` + +==== Reading All Objects with a Session Query + +The `+readAllObjects+` method retrieves a `+List+` of objects from the +database and does not put the returned objects in order. If the query +does not find any matching objects, it returns an empty `+List+`. + +Specify the class for the query. You can also include an expression to +define more complex search criteria, as illustrated in the following +example. + +[#Example 105-2]## *_readAllObjects Using an Expression_* + +*`+//\'\' \'\'Returns\'\' \'\'a\'\' \'\'List\'\' \'\'of\'\' \'\'employees\'\' \'\'whose\'\' \'\'employee\'\' \'\'salary\'\' \'\'is\'\' \'\'greater\'\' \'\'than\'\' \'\'10000+`* +`+List employees = session.readAllObjects(Employee.class,new ExpressionBuilder.get("salary").greaterThan(10000));+` + +==== Refreshing an Object with a Session Query + +The `+refreshObject+` method causes EclipseLink to update the object in +memory using data from the database. This operation refreshes any +privately owned objects as well. + +[width="100%",cols="<100%",] +|=== +|*Note*: A privately owned object is one that cannot exist without its +parent, or source object. +|=== + +=== How to Create, Update, and Delete Objects with a Session Query + +Using the session query API, you can perform the following create, +update, and delete operations: + +* link:#Writing_a_Single_Object_to_the_Database_with_a_Session_Query[Writing +a Single Object to the Database with a Session Query] +* link:#Writing_All_Objects_to_the_Database_with_a_Session_Query[Writing +All Objects to the Database with a Session Query] +* link:#Adding_New_Objects_to_the_Database_with_a_Session_Query[Adding +New Objects to the Database with a Session Query] +* link:#Modifying_Existing_Objects_in_the_Database_with_a_Session_Query[Modifying +Existing Objects in the Database with a Session Query] +* link:#Deleting_Objects_in_the_Database_with_a_Session_Query[Deleting +Objects in the Database with a Session Query] + +==== Writing a Single Object to the Database with a Session Query + +When you invoke the `+writeObject+` method, the method performs a +_does-exist_ check to determine whether or not an object exists. If the +object exists, `+writeObject+` updates the object; if it does not exist, +`+writeObject+` inserts a new object. + +The `+writeObject+` method writes privately owned objects in the correct +order to maintain referential integrity. + +Call the `+writeObject+` method when you cannot verify that an object +exists in the database. + +[#Example 105-3]## *_Writing a Single Object Using writeObject_* + +*`+//\'\' \'\'Create\'\' \'\'an\'\' \'\'instance\'\' \'\'of\'\' \'\'the\'\' \'\'employee\'\' \'\'and\'\' \'\'write\'\' \'\'it\'\' \'\'to\'\' \'\'the\'\' \'\'database+`* +`+Employee susan = new Employee();+` `+susan.setName("Susan");+` `+...+` +*`+//\'\' \'\'Initialize\'\' \'\'the\'\' \'\'susan\'\' \'\'object\'\' \'\'with\'\' \'\'all\'\' \'\'other\'\' \'\'instance\'\' \'\'variables+`* +`+session.writeObject(susan); +` + +==== Writing All Objects to the Database with a Session Query + +You can call the `+writeAllObjects+` method to write multiple objects to +the database. The `+writeAllObjects+` method performs the same +_does-exist_ check as the `+writeObject+` method and then performs the +appropriate insert or update operations. + +\'\' \'\'100+`* + +*`+//\'\' \'\'Initialize\'\' \'\'the\'\' \'\'DatabaseQuery\'\' \'\'by\'\' \'\'specifying\'\' \'\'the\'\' \'\'query\'\' \'\'type+`* +*`+//\'\' \'\'and\'\' \'\'set\'\' \'\'the\'\' \'\'reference\'\' \'\'class\'\' \'\'for\'\' \'\'the\'\' \'\'query+`* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` + +*`+//\'\' \'\'Retrieve\'\' \'\'ExpressionBuilder\'\' \'\'from\'\' \'\'the\'\' \'\'query+`* +`+ExpressionBuilder builder = query.getExpressionBuilder();+` + +*`+//\'\' \'\'Configure\'\' \'\'the\'\' \'\'query\'\' \'\'execution.\'\' \'\'Because\'\' \'\'this\'\' \'\'example\'\' \'\'uses+`*`+ +` +*`+//\'\' \'\'an\'\' \'\'expression,\'\' \'\'it\'\' \'\'uses\'\' \'\'the\'\' \'\'setSelectionCriteria\'\' \'\'method+`* +`+query.setSelectionCriteria(builder.get("id").greaterThan(100)); +` + +*`+//\'\' \'\'Execute\'\' \'\'the\'\' \'\'query+`* +`+List employees = (List) session.executeQuery(query);+` + +The following example illustrates a complex `+readObject+` query that +uses all available configuration options. + +[#Example 105-6]## *_Named Read Query with Two Arguments_* + +*`+//\'\' \'\'Initialize\'\' \'\'the\'\' \'\'DatabaseQuery\'\' \'\'by\'\' \'\'specifying\'\' \'\'the\'\' \'\'query\'\' \'\'type+`* +*`+//\'\' \'\'and\'\' \'\'set\'\' \'\'the\'\' \'\'reference\'\' \'\'class\'\' \'\'for\'\' \'\'the\'\' \'\'query+`* +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +*`+//\'\' \'\'Retrieve\'\' \'\'ExpressionBuilder\'\' \'\'from\'\' \'\'the\'\' \'\'query+`* +`+ExpressionBuilder builder = query.getExpressionBuilder();+` +*`+//\'\' \'\'Define\'\' \'\'two\'\' \'\'expressions\'\' \'\'that\'\' \'\'map\'\' \'\'to\'\' \'\'the\'\' \'\'first\'\' \'\'and\'\' \'\'last\'\' \'\'names\'\' \'\'of\'\' \'\'the\'\' \'\'employee+`* +`+Expression firstNameExpression = builder.get("firstName").equal(emp.getParameter("firstName"));+` +`+Expression lastNameExpression = builder.get("lastName").equal(emp.getParameter("lastName"));+` + +*`+//\'\' \'\'Configure\'\' \'\'the\'\' \'\'query\'\' \'\'execution.\'\' \'\'Because\'\' \'\'this\'\' \'\'example\'\' \'\'uses\'\' \'\'an\'\' \'\'expression,+`*`+ +` +*`+//\'\' \'\'it\'\' \'\'uses\'\' \'\'the\'\' \'\'setSelectionCriteria\'\' \'\'method+`* +`+query.setSelectionCriteria(firstNameExpression.and(lastNameExpression)); +` +*`+//\'\' \'\'Specify\'\' \'\'the\'\' \'\'required\'\' \'\'arguments\'\' \'\'for\'\' \'\'the\'\' \'\'query+`* +`+query.addArgument("firstName");+` `+query.addArgument("lastName");+` + +*`+//\'\' \'\'Add\'\' \'\'the\'\' \'\'query\'\' \'\'to\'\' \'\'the\'\' \'\'session+`* +`+session.addQuery("getEmployeeWithName", query);+` + +*`+//\'\' \'\'Execute\'\' \'\'the\'\' \'\'query\'\' \'\'by\'\' \'\'referencing\'\' \'\'its\'\' \'\'name\'\' \'\'and\'\' \'\'providing\'\' \'\'values\'\' \'\'for\'\' \'\'the\'\' \'\'specified\'\' \'\'arguments+`* +`+Employee employee = (Employee) session.executeQuery("getEmployeeWithName","Bob","Smith");+` + +==== Reading Objects Using Partial Object Queries + +The following example demonstrates the use of partial object reading. It +reads only the last name and primary key for the employees. This reduces +the amount of data read from the database. + +[#Example 105-7]## *_Using Partial Object Reading_* + +*`+//\'\' \'\'Read\'\' \'\'all\'\' \'\'the\'\' \'\'employees\'\' \'\'from\'\' \'\'the\'\' \'\'database,\'\' \'\'ask\'\' \'\'the\'\' \'\'user\'\' \'\'to\'\' \'\'choose\'\' \'\'one\'\' \'\'and\'\' \'\'return\'\' \'\'it.+`*`+ +` +*`+//\'\' \'\'This\'\' \'\'uses\'\' \'\'partial\'\' \'\'object\'\' \'\'reading\'\' \'\'to\'\' \'\'read\'\' \'\'just\'\' \'\'the\'\' \'\'last\'\' \'\'name\'\' \'\'of\'\' \'\'the\'\' \'\'employees.\'\' \'\'Since+`*`+  +` +`+'''// EclipseLink automatically includes the primary key of the object, the full object +` +*`+//\'\' \'\'can\'\' \'\'easily\'\' \'\'be\'\' \'\'read\'\' \'\'for\'\' \'\'editing+`* +`+List list;+` +*`+//\'\' \'\'Fetch\'\' \'\'data\'\' \'\'from\'\' \'\'database\'\' \'\'and\'\' \'\'add\'\' \'\'to\'\' \'\'list\'\' \'\'box+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.addPartialAttribute("lastName");+` + +*`+//\'\' \'\'The\'\' \'\'next\'\' \'\'line\'\' \'\'avoids\'\' \'\'a\'\' \'\'query\'\' \'\'exception+`* +`+query.dontMaintainCache();+` +`+List employees = (List) session.executeQuery(query);+` +`+list.addAll(employees);+` + +*`+//\'\' \'\'Display\'\' \'\'list\'\' \'\'box+`* `+...+` +*`+//\'\' \'\'Get\'\' \'\'selected\'\' \'\'employee\'\' \'\'from\'\' \'\'list+`* +`+Employee selectedEmployee = (Employee)session.readObject(list.getSelectedItem());+` +`+return selectedEmployee;+` + +==== Reading Objects Using Report Queries + +The following example reports the total and average salaries for +Canadian employees grouped by their city. + +[#Example 105-8]## *_Querying Reporting Information on Employees_* + +`+ExpressionBuilder emp = new ExpressionBuilder();+` +`+ReportQuery query = new ReportQuery(Employee.class, emp);+` +`+query.addMaximum("max-salary", emp.get("salary"));+` +`+query.addAverage("average-salary", emp.get("salary"));+` +`+query.addAttribute("city", emp.get("address").get("city"));+` + +`+query.setSelectionCriteria(emp.get("address").get("country").equal("Canada"));+` +`+query.addOrdering(emp.get("address").get("city"));+` +`+query.addGrouping(emp.get("address").get("city"));+` +`+List reports = (List) session.executeQuery(query);+` + +The `+Report\'\'Q\'\'uery+` class provides an extensive reporting API, +including methods for computing average, maximum, minimum, sum, standard +deviation, variance, and count of attributes. For more information about +the available methods for the `+Report\'\'Q\'\'uery+`, see the +_EclipseLink API Reference_. + +[width="100%",cols="<100%",] +|=== +|*Note*: Because `+ReportQuery+` inherits from `+ReadAllQuery+`, it also +supports most `+ReadAllQuery+` properties. +|=== + +==== Reading Objects Using Query-By-Example + +Query-by-example enables you to specify query selection criteria in the +form of a sample object instance that you populate with only the +attributes you want to use for the query. + +To define a query-by-example, provide a `+ReadObjectQuery+` or a +`+ReadAllQuery+` with a sample persistent object instance and an +optional query-by-example policy. The sample instance contains the data +to query, and, optionally, a `+QueryByExamplePolicy+` (see +link:#Defining_a_QueryByExamplePolicy[Defining a QueryByExamplePolicy]) +that specifies configuration settings, such as the operators to use and +the attribute values to ignore. You can also combine a query-by-example +with an expression (see +link:#Combining_Query-by-Example_and_Expressions[Combining +Query-by-Example and Expressions]). + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Query-by-Example]. + +The following example queries the employee Bob Smith. + +[#Example 105-9]## *_Using Query-by-Example to Query an Employee_* + +`+Employee employee = new Employee();+` +`+employee.setFirstName("Bob");+` `+employee.setLastName("Smith");+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+query.setExampleObject(employee);+` + +`+Employee result = (Employee) session.executeQuery(query);+` + +The following example queries across the employee’s address. + +[#Example 105-10 ]## *_Using Query-by-Example to Query an Employee’s +Address_* + +`+Employee employee = new Employee();+` +`+Address address = new Address();+` `+address.setCity("Ottawa");+` +`+employee.setAddress(address);+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadAllQuery query = new ReadAllQuery (Employee.class);+` +`+query.setExampleObject(employee);+` + +`+List results = (List) session.executeQuery(query);+` + +*Defining a QueryByExamplePolicy* + +EclipseLink support for query-by-example includes a query-by-example +policy. You can edit the policy to modify query-by-example default +behavior. You can modify the policy to do the following: + +* Use `+LIKE+` or other operations to compare attributes. By default, +query-by-example allows only `+EQUALS+`. +* Modify the set of values query-by-example ignores (the `+IGNORE+` +set). The default ignored values are zero (0), empty strings, and +`+FALSE+`. +* Force query-by-example to consider attribute values, even if the value +is in the `+IGNORE+` set. +* Use `+isNull+` or `+notNull+` for attribute values. + +To specify a query-by-example policy, include an instance of +`+QueryByExamplePolicy+` with the query. + +The following example uses `+like+` operator for strings and includes +only objects whose salary is greater than zero. + +[#Example 105-11]## *_Query-by-Example Policy Using like Operator_* + +`+Employee employee = new Employee();+` `+employee.setFirstName("B%");+` +`+employee.setLastName("S%");+` `+employee.setSalary(0);+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setExampleObject(employee);+` +*`+//\'\' \'\'Query\'\' \'\'by\'\' \'\'example\'\' \'\'policy\'\' \'\'section\'\' \'\'adds\'\' \'\'like\'\' \'\'and\'\' \'\'greaterThan+`* +`+QueryByExamplePolicy policy = new QueryByExamplePolicy();+` +`+policy.addSpecialOperation(String.class, "like");+` +`+policy.addSpecialOperation(Integer.class, "greaterThan");+` +`+policy.alwaysIncludeAttribute(Employee.class, "salary");+` +`+query.setQueryByExamplePolicy(policy);+` +`+List results = (List) session.executeQuery(query);+` + +This example uses keywords for strings and ignores the value -1. + +[#Example 105-12]## *_Query-by-Example Policy Using Keywords_* + +`+Employee employee = new Employee();+` +`+employee.setFirstName("bob joe fred");+` +`+employee.setLastName("smith mc mac");+` `+employee.setSalary(-1);+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setExampleObject(employee);+` +*`+//\'\' \'\'Query\'\' \'\'by\'\' \'\'example\'\' \'\'policy\'\' \'\'section+`* +`+QueryByExamplePolicy policy = new QueryByExamplePolicy();+` +`+policy.addSpecialOperation(String.class, "containsAnyKeyWords");+` +`+policy.excludeValue(-1);+` `+query.setQueryByExamplePolicy(policy);+` +`+List results = (List) session.executeQuery(query);+` + +*Combining Query-by-Example and Expressions* + +To create more complex query-by-example queries, combine +query-by-example with EclipseLink expressions, as shown in the following +example. + +[#Example 105-13]## *_Combining Query-by-Example with Expressions_* + +`+Employee employee = new Employee();+` +`+employee.setFirstName("Bob");+` `+employee.setLastName("Smith");+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'Employee\'\' \'\'as\'\' \'\'its\'\' \'\'reference\'\' \'\'class+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` + +`+query.setExampleObject(employee);+` + +*`+//\'\' \'\'Specify\'\' \'\'expression+`* +`+ExpressionBuilder builder = query.getExpressionBuilder();+` +`+query.setSelectionCriteria(builder.get("salary").between(100000,200000);+` +`+List results = (List) session.executeQuery(query);+` + +==== Specifying Read Ordering + +Ordering is a common `+DatabaseQuery+` option. You can order a +collection of objects returned from a `+ReadAllQuery+` using the +`+addOrdering+`, `+addAscendingOrdering+`, or `+addDescendingOrdering+` +methods. You can apply order based on attribute names or query keys and +expressions. + +[#Example 105-14]## *_A Query with Simple Ordering_* + +*`+//\'\' \'\'Retrieves\'\' \'\'objects\'\' \'\'ordered\'\' \'\'by\'\' \'\'last\'\' \'\'name\'\' \'\'then\'\' \'\'first\'\' \'\'name\'\' \'\'in\'\' \'\'ascending\'\' \'\'order+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.addAscendingOrdering ("lastName");+` +`+query.addAscendingOrdering ("firstName");+` +`+List employees = (List) session.executeQuery(query);+` + +[#'Example 105-15]## *_A Query with Complex Ordering_* + +*`+//\'\' \'\'Retrieves\'\' \'\'objects\'\' \'\'ordered\'\' \'\'by\'\' \'\'street\'\' \'\'address,\'\' \'\'descending\'\' \'\'case-insensitive+`*`+ +` +*`+//\'\' \'\'order\'\' \'\'of\'\' \'\'cities,\'\' \'\'and\'\' \'\'manager's\'\' \'\'last\'\' \'\'name+`* +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+ExpressionBuilder emp = query.getExpressionBuilder();+` +`+query.addOrdering (emp.getAllowingNull("address").get("street"));+` +`+query.addOrdering(emp.getAllowingNull("address").get("city").toUpperCase().descending());+` +`+query.addOrdering(emp.getAllowingNull("manager").get("lastName"));+` +`+List employees = (List) session.executeQuery(query);+` + +Note the use of `+getAllowingNull+`, which creates an outer join for the +address and manager relationships. This ensures that employees without +an address or manager still appear in the list. + +For more information about configuring read ordering, see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Read All Query +Order]. + +==== Specifying a Collection Class + +By default, a `+ReadAllQuery+` returns its result objects in a list. You +can configure the query to return the results in any collection class +that implements the `+Collection+` or `+Map+` interface, as shown in the +following example. + +[#Example 105-16]## *_Specifying the Collection Class for a Collection_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.useCollectionClass(LinkedList.class);+` +`+LinkedList employees = (LinkedList) getSession().executeQuery(query);+` + +[#Example 105-17]## *_Specifying the Collection Class for a Map_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.useMapClass(HashMap.class, "getFirstName");+` +`+HashMap employees = (HashMap) getSession().executeQuery(query);+` + +==== Specifying the Maximum Rows Returned + +You can limit a query to a specified maximum number of rows. Use this +feature to avoid queries that can return an excessive number of objects. + +To specify a maximum number of rows, use the `+setMaxRows+` method, and +pass an integer that represents the maximum number of rows for the +query, as shown in the following example. + +[#Example 105-18]## *_Setting the Maximum Returned Object Size_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setMaxRows(5);+` +`+List employees = (List) session.executeQuery(query);+` + +The `+setMaxRows+` method limits the number of rows the query returns, +but does not let you acquire more records after the initial result set. + +If you want to browse the result set in fixed increments, use either +cursors or cursored streams. For more information, see +link:Using%20Advanced%20Query%20API%20(ELUG)[Handling Cursor and Stream +Query Results]. + +==== Configuring Query Timeout at the Query Level + +You can set the maximum amount of time that EclipseLink waits for +results from a query. This forces a hung or lengthy query to abort after +the specified time has elapsed. EclipseLink throws a +`+DatabaseException+` after the timeout interval. + +To specify a timeout interval on a per-query basis, use +`+DatabaseQuery+` method `+setQueryTimeout+` and pass the timeout +interval as an integer representing the number of seconds before the +timeout interval should occur, as the following example shows. + +[#Example 105-19]## *_DatabaseQuery Timeout_* + +`+ +`*`+//\'\' \'\'Create\'\' \'\'the\'\' \'\'appropriate\'\' \'\'query\'\' \'\'and\'\' \'\'set\'\' \'\'timeout\'\' \'\'limits+`* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.setQueryTimeout(2);+` `+try {+` +`+    List employees = (List) session.executeQuery(query);+` `+} +` +`+catch (DatabaseException ex) {+` +`+    +`*`+//\'\' \'\'timeout\'\' \'\'occurs+`* `+}+` + +To specify a timeout interval for all queries on a particular object +type, configure a query timeout interval at the descriptor level (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Query Timeout at +the Descriptor Level]). + +==== Using Batch Reading + +Batch reading propagates query selection criteria through an object’s +relationship attribute mappings. You can also nest batch read operations +down through complex object graphs. This significantly reduces the +number of required SQL select statements and improves database access +efficiency. + +Consider the following guidelines when you implement batch reading: + +* Use batch reading for processes that read in objects and all their +related objects. +* Do not enable batch reading for both sides of a bidirectional +relationship. +* Avoid nested batch read operations, because they result in multiple +joins on the database, slowing query execution. + +For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[Reading Case +2: Batch Reading Objects]. + +For example, in reading _n_ employees and their related projects, +EclipseLink may require _n + 1_ select operations. All employees are +read at once, but the projects of each are read individually. With batch +reading, all related projects can also be read with one select operation +by using the original selection criteria, for a total of only two select +operations. + +To implement batch reading, add the batch read attribute to a query, use +the `+query.addBatchReadAttribute(Expression anExpression)+` API, as the +following example shows: + +`+…+` `+ReadAllQuery raq = new ReadAllQuery(Trade.class);+` +`+ExpressionBuilder tradeBuilder = raq.getBuilder();+` `+…+` +`+Expression batchReadProduct = tradeBuilder.get("product");+` +`+readAllQuery.addBatchReadAttribute(batchReadProduct); +` +`+Expression batchReadPricingDetails = batchReadProduct.get("pricingDetails");+` +`+readAllQuery.addBatchReadAttribute(batchReadPricingDetails); +` `+…+` + +Alternatively, you can add batch reading at the mapping level for a +descriptor. For more information, see +link:Configuring%20a%20Relational%20Mapping%20(ELUG)[Configuring Batch +Reading]. + +You can combine batch reading and indirection (lazy loading) to provide +controlled reading of object attributes. For example, if you have +one-to-one back pointer relationship attributes, you can defer back +pointer instantiation until the end of the query, when all parent and +owning objects are instantiated. This prevents unnecessary database +access and optimizes EclipseLink cache use. + +==== Using Join Reading with ObjectLevelReadQuery + +Use join reading with `+ObjectLevelReadQuery+` to configure a query for +a class to return the data to build an instance of that class and its +related objects. For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Join Reading and +Object-Level Read Queries]. + +To use join reading with an `+ObjectLevelReadQuery+`, you can use +Workbench (see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring +Named Query Optimization]))or Java. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use Workbench to create an `+ObjectLevelReadQuery+` +with a join expression on a one-to-many mapped attribute: you must use +Java. +|=== + +===== Using Java + +You can use `+ObjectLevelReadQuery+` API to add joined attributes for +mappings. + +You can use any of the following API: + +* Use the `+ObjectLevelReadQuery+` method `+addJoinedAttribute+` with a +join expression or attribute name for one-to-one or one-to-many mapped +attributes. Using this method, you can add multiple joined attributes, +including nested joins. The source and target can be the same class +type. On a one-to-one mapped attribute, use this method to get the class +of the `+ObjectLevelReadQuery+` and the target of the one-to-one mapped +attribute of that class with a single database hit. On a one-to-many +mapped attribute, use this method to get the class of the +`+ObjectLevelReadQuery+` and the target collection of the one-to-many +mapped attribute of that class with a single database hit. +* Use the `+ObjectLevelReadQuery+` method `+setShouldFilterDuplicates+` +with a join expression on a one-to-many mapped attribute to filter +duplicate rows. Default is *true*, unless using a JPA query. +* Use the `+ObjectLevelReadQuery+` method +`+setShouldOuterJoinSubclasses+` to configure an object-level read query +to allow inherited subclasses to be outer-joined to avoid the cost of a +single query per class. + +Use a join expression to configure nested batch reads and inner or outer +joins (see +link:Introduction%20to%20EclipseLink%20Expressions%20(ELUG)[Expressions +for Joining and Complex Relationships]). You can also specify inner or +outer joins using the mapping methods `+useInnerJoinFetch+` or +`+useOuterJoinFetch+`. + +The link:#Example_105-20[Join Reading Multiple Attributes] example is +based on the EclipseLink `+ThreeTierEmployee+` example project. It shows +a `+ReadAllQuery+` configured to join-read multiple attributes. + +[#Example 105-20]## *_Join Reading Multiple Attributes_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` + +`+Expression managedEmployees = query.getExpressionBuilder().anyOfAllowingNone("managedEmployees");+` +`+query.addJoinedAttribute(managedEmployees);+` +`+query.addJoinedAttribute(managedEmployees.get("address"));+` +`+query.addJoinedAttribute(managedEmployees.anyOf("phoneNumbers"));+` + +`+List employees = (List) getSession().executeQuery(query);+` + +Use the `+ObjectLevelReadQuery+` method +`+addJoinedAttribute(java.lang.String attributeName)+` to configure the +query to join-read a single attribute, as the following shows. + +[#Example 105-22]## *_Join Reading a Single Attribute_* + +`+ReadAllQuery query = new ReadAllQuery(Employee.class);+` +`+query.addJoinedAttribute("address");+` +`+List employees = (List)getSession().executeQuery(query);+` + +=== How to Create, Update, and Delete Objects with a DatabaseQuery + +You can create, update or delete object with a `+DatabaseQuery+` using a +`+DatabaseSession+`. For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Session +Queries]. + +This section describes the following: + +* link:#Using_Write_Query[Using Write Query] +* link:#Performing_Noncascading_Write_Queries[Noncascading Write +Queries] +* link:#Disabling_the_Identity_Map_Cache_During_a_Write_Query[Disabling +the Identity Map Cache During a Write Query] + +==== Using Write Query + +To execute a write query, use a `+WriteObjectQuery+` instance instead of +using the `+writeObject+` method of the session. Likewise, substitute +`+DeleteObjectQuery+`, `+UpdateObjectQuery+`, and `+InsertObjectQuery+` +objects for their respective `+Session+` methods. + +[#Example 105-24]## *_Using a WriteObjectQuery_* + +`+WriteObjectQuery writeQuery = new WriteObjectQuery();+` +`+writeQuery.setObject(domainObject);+` +`+session.executeQuery(writeQuery);+` + +[#Example 105-25]## *_Using InsertObjectQuery, UpdateObjectQuery, and +DeleteObjectQuery_* + +`+InsertObjectQuery insertQuery= new InsertObjectQuery();+` +`+insertQuery.setObject(domainObject);+` +`+session.executeQuery(insertQuery);+` + +*`+//\'\' \'\'When\'\' \'\'you\'\' \'\'use\'\' \'\'UpdateObjectQuery\'\' \'\'without\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work,+`* +*`+//\'\' \'\'UpdateObjectQuery\'\' \'\'writes\'\' \'\'all\'\' \'\'direct\'\' \'\'attributes\'\' \'\'to\'\' \'\'the\'\' \'\'database+`* +`+UpdateObjectQuery updateQuery= new UpdateObjectQuery();+` +`+updateQuery.setObject(domainObject2);+` +`+session.executeQuery(updateQuery);+` + +`+DeleteObjectQuery deleteQuery = new DeleteObjectQuery();+` +`+deleteQuery.setObject(domainObject2);+` +`+session.executeQuery(deleteQuery);+` + +==== Performing Noncascading Write Queries + +When you execute a write query, it writes both the object and its +privately owned parts to the database by default. To build write queries +that do not update privately owned parts, include the +`+dontCascadeParts+` method in your query definition. + +Use this method to do the following: + +* Increase performance when you know that only the object’s direct +attributes have changed. +* Resolve referential integrity dependencies when you write large groups +of new, independent objects. + +[width="100%",cols="<100%",] +|=== +|*Note*: Because the unit of work resolves referential integrity +internally, this method is not required if you use the unit of work to +write to the database. +|=== + +[#Example 105-27]## *_Performing a Noncascading Write Query_* + +*`+//\'\' \'\'the\'\' \'\'Employee\'\' \'\'is\'\' \'\'an\'\' \'\'existing\'\' \'\'employee\'\' \'\'read\'\' \'\'from\'\' \'\'the\'\' \'\'database+`* +`+Employee.setFirstName("Bob");+` +`+UpdateObjectQuery query = new UpdateObjectQuery();+` +`+query.setObject(Employee);+` `+query.dontCascadeParts();+` +`+session.executeQuery(query);+` + +==== Disabling the Identity Map Cache During a Write Query + +When you write objects to the database, EclipseLink copies them to the +session cache by default. To disable this within a query, call the +`+dontMaintainCache+` method within the query. This improves query +performance when you insert objects into the database, but must be used +only on objects that will not be required later by the application. + +The following example reads all the objects from a flat file and writes +new copies of the objects into a table. + +[#Example 105-28]## *_Disabling the Identity Map Cache During a Write +Query_* + +*`+//\'\' \'\'Reads\'\' \'\'objects\'\' \'\'from\'\' \'\'an\'\' \'\'employee\'\' \'\'file\'\' \'\'and\'\' \'\'writes\'\' \'\'them\'\' \'\'to\'\' \'\'the\'\' \'\'employee\'\' \'\'table+`* +`+void createEmployeeTable(String filename, Session session) {+` +`+   Iterator iterator;+` `+   Employee employee;+` + +`+   +`*`+//\'\' \'\'Read\'\' \'\'the\'\' \'\'employee\'\' \'\'data\'\' \'\'file+`* +`+   List employees = Employee.parseFromFile(filename);+` +`+   Iterator iterator = employees.iterator();+` +`+   while (iterator.hasNext()) {+` +`+      Employee employee = (Employee) iterator.next();+` +`+      InsertObjectQuery query = new InsertObjectQuery();+` +`+      query.setObject(employee);+` +`+      query.dontMaintainCache();+` +`+      session.executeQuery(query);+` `+   }+` `+}+` + +[width="100%",cols="<100%",] +|=== +|*Note*: Disable the identity map only when object identity is +unimportant in subsequent operations. +|=== + +=== How to Update and Delete Multiple Objects with a DatabaseQuery + +Using the unit of work, you can perform update and delete operations on +multiple objects. + +This section describes the following: + +* link:#Using_UpdateAll_Queries[Using UpdateAll Queries] +* link:#Using_DeleteAll_Queries[Using DeleteAll Queries] + +==== Using UpdateAll Queries + +Use an `+UpdateAllQuery+` to update a large number of objects at once. +With this query, you can update a large number of objects with a single +SQL statement instead of reading the objects into memory and updating +them individually. The following example shows an `+UpdateAllQuery+` to +give all full-time employees a raise. + +[#Example 105-26]## *_Using UpdateAllQuery_* + +*`+//\'\' \'\'Give\'\' \'\'all\'\' \'\'full\'\' \'\'time\'\' \'\'employees\'\' \'\'a\'\' \'\'10%\'\' \'\'raise+`* +`+UpdateAllQuery updateQuery = new UpdateAllQuery(Employee.class);+` +`+ExpressionBuilder employee = updateQuery.getExpressionBuilder();+` +`+updateQuery.setSelectionCriteria(employee.get("status").equal("FULL_TIME"));+` +`+updateQuery.addUpdateExpression(employee.get("salary"), +` +`+            ExpressionMath.multiply(employee.get("salary"), new Float(1.10)));+` + +`+UpdateAllQuery+` takes the cache into consideration and ensures that +the cache is kept up to date. You can configure the `+UpdateAllQuery+` +to invalidate cache (see link:Introduction%20to%20Cache%20(ELUG)[Cache +Invalidation]) by setting the cache usage to `+INVALIDATE_CACHE+` +(default), or to not use the cache by specifying `+NO_CACHE+` option. +You can manipulate these settings through the `+setCacheUsage+` method. +You can only update the cache for expressions that can conform. For more +information on cache, see +link:Introduction%20to%20Cache%20(ELUG)[Introduction to Cache]. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can set an attribute within an aggregate only, but not an +entire aggregate. +|=== + +You can use an `+UpdateAllQuery+` with optimistic locking (see +link:Introduction%20to%20Descriptors%20(ELUG)[Descriptors and Locking]) +at the level of updating a row in a database–there should be no updates +in the cache. You will update the locking field on the database. There +is also support for version and timestamp locking, as well as indirect +support for field locking. + +==== Using DeleteAll Queries + +The following example shows a `+DeleteAllQuery+` to eliminate all +part-time employee positions. + +[#Example 105-27]## *_Using DeleteAllQuery_* + +*`+//\'\' \'\'Delete\'\' \'\'all\'\' \'\'part-time\'\' \'\'employees+`* +`+DeleteAllQuery deleteQuery = new DeleteAllQuery(Employee.class);+` +`+ExpressionBuilder employee = deleteQuery.getExpressionBuilder();+` +`+deleteQuery.setSelectionCriteria(employee.get("status").equal("PART_TIME"));+` +`+deleteQuery.setObjects(domainObjects);+` +`+session.executeQuery(deleteQuery);+` + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[DeleteAllQuery] + +=== How to Read Data with a DatabaseQuery + +This section describes the following: + +* link:#Using_a_DataReadQuery[Using a DataReadQuery] +* link:#Using_a_DirectReadQuery[Using a DirectReadQuery] +* link:#Using_a_ValueReadQuery[Using a ValueReadQuery] + +==== Using a DataReadQuery + +You can use a `+DataReadQuery+` to execute a selecting SQL string that +returns a `+Collection+` of the `+Record+` objects representing the +result set, as the following example shows. + +[#Example 105-29]## *_Using a DataReadQuery_* + +`+DataReadQuery dataReadQuery = new DataReadQuery();+` +`+dataReadQuery.setSQLString("Select * from EMPLOYEE"); +` + +*`+//\'\' \'\'queryResults\'\' \'\'is\'\' \'\'a\'\' \'\'List\'\' \'\'of\'\' \'\'DatabaseRow\'\' \'\'objects+`* +`+List queryResults = (List)session.executeQuery(dataReadQuery);+` + +==== Using a DirectReadQuery + +You can use a `+DirectReadQuery+` to read a single column of data (that +is, one field) that returns a `+Collection+` of the `+Record+` objects +representing the result set, as this example shows. + +[#Example 105-30]## *_Using a DirectReadQuery_* + +`+DirectReadQuery directReadQuery = new DirectReadQuery();+` +`+directReadQuery.setSQLString("Select * from EMPLOYEE"); +` + +*`+//\'\' \'\'queryResults\'\' \'\'is\'\' \'\'a\'\' \'\'List\'\' \'\'of\'\' \'\'Record\'\' \'\'objects+`* +`+List queryResults = (List)session.executeQuery(directReadQuery);+` + +==== Using a ValueReadQuery + +You can use a `+ValueReadQuery+` to read a single data value (that is, +one field). A single data value is returned, or null if no rows are +returned, as this example shows. + +[#Example 105-31]## *_Using a ValueReadQuery_* + +`+ValueReadQuery valueReadQuery = new ValueReadQuery();+` +`+valueReadQuery.setSQLString("SELECT DISTINCT CURRENT TIMESTAMP FROM SYSTABLES");+` + +*`+//\'\' \'\'result\'\' \'\'is\'\' \'\'a\'\' \'\'single\'\' \'\'Object\'\' \'\'value+`* +`+Object result = session.executeQuery(valueReadQuery);+` + +\{| class="`NoteWarn oac_no_warn`" width="`80%`" border="`1`" +frame="`hsides`" rules="`groups`" cellpadding="`3`" frame="`hsides`" +rules="`groups`" | align="`left`" | *WARNING:* Allowing an unverified +SQL string to be passed into methods (for example: `+setSQLString+` +method) makes your application vulnerable to SQL injection attacks. |} + +=== How to Update Data with a DatabaseQuery + +You can use a `+DataModifyQuery+` to execute a nonselecting SQL +statement (directly or as an `+SQLCall+`), as the +link:#Example_105-32[Using a DataModifyQuery] example shows. This is +equivalent to `+Session+` method `+executeNonSelectingCall+` (see +link:#Using_a_SQLCall[Using a SQLCall]). + +[#Example 105-32]## *_Using a DataModifyQuery_* + +`+DataModifyQuery query = new DataModifyQuery(new SQLCall("Delete from Employee"));+` +`+session.executeQuery(query);+` + +=== How to Specify a Custom SQL String in a DatabaseQuery + +All `+DatabaseQuery+` objects provide a `+setSQLString+` method that you +can use to define a custom SQL string. + +For more information about using custom SQL in queries, see +link:#Using_a_SQLCall[Using a SQLCall]. + +The following example uses SQL to read all employee IDs. + +[#Example 105-33]## *_A Direct Read Query with SQL_* + +`+DirectReadQuery query = new DirectReadQuery();+` +`+query.setSQLString("SELECT EMP_ID FROM EMPLOYEE");+` +`+List ids = (List) session.executeQuery(query);+` + +The following example uses SQL to switch to a different database. + +[#Example 105-34]## *_A Data Modify Query with SQL_* + +`+DataModifyQuery query = new DataModifyQuery();+` +`+query.setSQLString("USE SALESDATABASE");+` +`+session.executeQuery(query);+` + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +(for example: `+setSQLString+` method) makes your application vulnerable +to SQL injection attacks. +|=== + +=== How to Specify a Custom JPQL String in a DatabaseQuery + +Information pending + +=== How to Use Parameterized SQL and Statement Caching in a DatabaseQuery + +By default, EclipseLink enables parameterized SQL (parameter binding) +and statement caching. This causes EclipseLink to use a prepared +statement, binding all SQL parameters and caching the prepared +statement. When you reexecute this query, you avoid the SQL preparation, +which improves performance. + +To disable parameterized SQL and statement caching on individual +queries, use `+DatabaseQuery+` methods `+setShouldBindAllParameters+` +and `+setShouldCacheStatement+`, passing in an argument of `+false+`. To +re-enable this feature, pass in an argument of `+true+`. + +[#Example 105-35]## *_A Simple ReadObjectQuery with Parameterized SQL_* + +`+ReadObjectQuery query = new ReadObjectQuery(Employee.class);+` +`+query.setShouldBindAllParameters(true);+` +`+query.setShouldCacheStatement(true);+` + +Alternatively, you can configure parameterized SQL and binding at any of +the following levels: + +* project level–applies to all named queries (see +link:Configuring%20a%20Relational%20Project%20(ELUG)[Configuring Named +Query Parameterized SQL and Statement Caching at the Project Level]); +* descriptor level–applies on a per-named-query basis (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Named Query +Options]); +* session database login level–applies to all queries (see +link:Configuring%20a%20Database%20Login%20(ELUG)[Configuring JDBC +Options]) and provides additional parameter binding API to alleviate the +limit imposed by some drivers on SQL statement size; + +For more information about using parameterized SQL and binding for data +access optimization, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)[How to Use +Parameterized SQL (Parameter Binding) and Prepared Statement Caching for +Optimization]. + +[width="100%",cols="<100%",] +|=== +|*Note*: For applications using a Java EE data source or external +connection pool, you must configure statement caching in the Java EE +server’s data source–not in EclipseLink. +|=== + +== Using Named Queries + +Named queries improve application performance because they are prepared +once and they (and all their associated supporting objects) can be +efficiently reused thereafter making them well suited for frequently +executed operations. + +You can configure named queries at the session (see +link:Configuring%20a%20Session%20(ELUG)[Configuring Named Queries at the +Session Level]) or descriptor (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Named Queries at +the Descriptor Level]) level. + +For a session-level named query, you can execute the query using any of +the following `+Session+` API methods: + +* `+executeQuery(String queryName)+` +* `+executeQuery(String queryName, arg1)+` +* `+executeQuery(String queryName, arg1, arg2)+` +* `+executeQuery(String queryName, arg1, arg2, arg3)+` +* `+executeQuery(String queryName, List args)+` + +[#Example 105-36]## *_Executing a Session-Level Named Query_* + +`+List args = new ArrayList();+` `+args.add("Sarah");+` +`+Employee sarah = (Employee)session.executeQuery("employeeReadByFirstName", args);+` + +For a descriptor-level named query, you can execute the query using any +of the following `+Session+` API calls, as the +link:#Example_105-37[Executing a Descriptor Level Named Query] example +shows: + +* `+executeQuery(String queryName, Class domainClass)+` +* `+executeQuery(String queryName, Class domainClass, arg1)+` +* `+executeQuery(String queryName, Class domainClass, arg1, arg2)+` +* `+executeQuery(String queryName, Class domainClass, arg1, arg2, arg3)+` +* `+executeQuery(String queryName, Class domainClass, List args)+` + +[#Example 105-37]## *_Executing a Descriptor Level Named Query_* + +`+List args = new ArrayList();+` `+args.add("Sarah");+` +`+Employee sarah = (Employee)session.executeQuery("ReadByFirstName", Employee.class, args);+` + +For more information, see +link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)[Named Queries] + +== Using a SQLCall + +The EclipseLink expression framework enables you to define complex +queries at the object level. If your application requires a more complex +query or one that accesses data directly, you can specify a custom SQL +string in an `+SQLCall+` object and execute the SQL string in the +context of a `+DatabaseQuery+` or using Session API for executing +`+Call+` objects. + +You can provide an `+SQLCall+` object to any query instead of an +expression, but the SQL string contained in the `+SQLCall+` must return +all data required to build an instance of the queried class. + +The SQL string can be a complex SQL query that includes input, output, +and input/output arguments using JDBC data types. + +[width="100%",cols="<100%",] +|=== +|*WARNING:* Allowing an unverified SQL string to be passed into methods +makes your application vulnerable to SQL injection attacks. +|=== + +=== How to Configure a SQLCall Without Arguments + +You can configure a `+SQLCall+` without arguments and execute it +directly using `+Session+` API. Use this approach when you want to +execute a SQL string without arguments (or with hard-coded argument +values). + +*To configure a SQLCall input without arguments:* + +[arabic] +. Instantiate a `+SQLCall+` object. +. Pass the SQL string into the constructor, as the +link:#Example_105-38[Executing a SQLCall Without Arguments] example +shows. Alternatively, you can use `+SQLCall+` method `+setSQLString+`. +. Execute the `+SQLCall+` using the appropriate `+Session+` API, as the +link:#Example_105-38[Executing a SQLCall Without Arguments] example +shows. You can use any of the following `+Session+` methods, depending +on the type of SQL string you define: +* `+executeSelectingCall+`: returns a `+List+` of `+Record+` objects, +each representing a database row. +* `+executeNonSelectingCall+`: returns `+void+`. + +[#Example 105-38]## *_Executing a SQLCall Without Arguments_* + +`+List result = session.executeSelectingCall(new SQLCall("SELECT * FROM EMPLOYEE WHERE DEPT_ID =44"));+` + +=== How to Configure a SQLCall with Arguments Using JDBC Data Types + +You can configure a `+SQLCall+` that takes any combination of input, +output, or input/output arguments. Use this approach when you want to +bind argument values to the `+SQLCall+` at runtime, receive output +values from the `+SQLCall+` at execution time, or both. + +*To configure a SQLCall with arguments using JDBC data types:* + +[arabic] +. Instantiate a `+SQLCall+` object. +. Create the SQL string and designate arguments as input, output, or +input/output. EclipseLink assumes that a token in the custom SQL string +of an `+SQLCall+` is an argument if it is prefixed with one or more +number signs (`+#+` ), as follows: +* Input parameter prefix:`+#+` (see link:#Example_105-39[Example 1]). +* Output parameter prefix:`+###+` (see link:#Example_105-40[Example 2]). +* Input/output parameter prefix:`+####+` (see +link:#Example_105-41[Example 3]). +. Pass the SQL string into the constructor, as +link:#Example_105-39[Example 1], link:#Example_105-40[Example 2], and +link:#Example_105-41[Example 3] show. Alternatively, you can use +`+SQLCall+` method `+setSQLString+`. +. For each output argument, use the appropriate `+SQLCall+` method +`+setCustomSQLArgumentType+` to specify the Java data type EclipseLink +uses to return the output value, as link:#Example_105-40[Example 2] +shows. For an input argument, EclipseLink automatically converts the +Java data type to the appropriate JDBC data type. For an input/output +argument, the type of the input value determines the type of the output +value. As link:#Example_105-41[Example 3] shows, the data type of the +argument value passed into `+in_out+` is `+String+` ("`MacDonald`") so +EclipseLink returns the output value (for `+EMP_ID+`) as a `+String+`. +. Instantiate a `+DatabaseQuery+` appropriate for your SQL string. +. Configure the `+DatabaseQuery+` with your `+SQLCall+` using +`+DatabaseQuery+` method `+setCall+`, as link:#Example_105-39[Example +1], link:#Example_105-40[Example 2], and link:#Example_105-41[Example 3] +show. +. Specify the names for all input and input/output arguments using +`+DatabaseQuery+` method `+addArgument+`, as +link:#Example_105-39[Example 1], link:#Example_105-40[Example 2], and +link:#Example_105-41[Example 3] show. +. Create a `+Vector+` of argument values in the same order as you +specified argument names in step 7, as link:#Example_105-39[Example 1], +link:#Example_105-40[Example 2], and link:#Example_105-41[Example 3] +show. +. Bind values to the arguments and execute the `+DatabaseQuery+` using +`+Session+` method `+executeQuery(DatabaseQuery, java.util.Vector)+`, +passing in your `+DatabaseQuery+` and `+Vector+` of argument values, as +link:#Example_105-39[Example 1], link:#Example_105-40[Example 2], and +link:#Example_105-41[Example 3] show. + +[#Example 105-39]## *_Example 1: Specifying an SQLCall with an Input +Argument Using the # Prefix: JDBC Data Types_* + +`+SQLCall sqlCall = new SQLCall("INSERT INTO EMPLOYEE (L_NAME) VALUES (#last_name)");+` + +`+DataModifyQuery query = new DataModifyQuery();+` +`+query.setCall(sqlCall);+` +`+query.addArgument("last_name");   +`*`+//\'\' \'\'input+`* + +`+List args = new ArrayList();+` `+args.add("MacDonald"); +` +`+session.executeQuery(query, args);+` + +[#Example 105-40]## *_Example 2: Specifying a SQLCall with an Output +Argument Using the ### Prefix: JDBC Data Types_* + +`+SQLCall sqlCall = new SQLCall("BEGIN INSERT INTO EMPLOYEE (L_NAME) VALUES (#last_name) RETURNING EMP_ID INTO ###employee_id; END;");+` +`+sqlCall.setCustomSQLArgumentType("employee_id", Integer.class); +`*`+// specify output value type+`* + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(sqlCall);+` +`+query.addArgument("last_name");   +`*`+//\'\' \'\'input+`* + +`+List args = new ArrayList();+` `+args.add("MacDonald");+` + +`+Integer employeeID = (Integer) getSession().executeQuery(query, args);+` + +[#Example 105-41]## *_Example 3: Specifying a SQLCall with an +Input/Output Argument Using the #### Prefix: JDBC Data Types_* + +`+SQLCall sqlCall = new SQLCall("BEGIN INSERT INTO EMPLOYEE (L_NAME) VALUES (####in_out) RETURNING EMP_ID INTO ####in_out; END;");+` + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(sqlCall);+` +`+query.addArgument("in_out");   +`*`+//\'\' \'\'input\'\' \'\'and\'\' \'\'outpu+`* +`+ +` `+List args = new ArrayList();+` +`+args.add("MacDonald");         +`*`+// type of input argument determines type of output value+`* + +`+String lastName = (String) getSession().executeQuery(query, args);+` + +=== What You May Need to Know About Using a SQLCall + +When using SQL calls, you can use a `+ReturningPolicy+` to control +whether or not EclipseLink writes a parameter out or retrieves a value +generated by the database. + +If you want to invoke a stored procedure or stored function, use a +`+StoredProcedureCall+` or `+StoredFunctionCall+`. + +Alternatively, you can specify a simple SQL string directly on +`+DatabaseQuery+`. You can use this approach to avoid the overhead of +creating a `+SQLCall+` object when your SQL string is simple, uses +hard-coded arguments (or no arguments), and you do not require the +additional API that `+SQLCall+` provides. + +For more information, see the following: + +* link:#How_to_Specify_a_Custom_SQL_String_in_a_DatabaseQuery[How to +Specify a Custom SQL String in a DatabaseQuery] +* link:Configuring%20a%20Descriptor%20(ELUG)[Configuring Returning +Policy] +* link:#Using_a_StoredProcedureCall[Using a StoredProcedureCall] +* link:#Using_a_StoredFunctionCall[Using a StoredFunctionCall] + +== Using a StoredProcedureCall + +The EclipseLink expression framework enables you to define complex +queries at the object level. If your application requires a more complex +query or one that invokes an existing stored procedure that your +database provides, you can define a `+StoredProcedureCall+` object using +both JDBC and PL/SQL data types and invoke the stored procedure in the +context of a `+DatabaseQuery+`. + +If you are using an Oracle Database, you can pass in both JDBC and +PL/SQL (non-JDBC) data types. + +If you are using a non-Oracle database, you may pass in only JDBC data +types. + +link:EclipseLink_Examples_JPA_nonJDBCArgsToStoredProcedures[This +example] contains additional samples on on using stored procedures. + +=== How to Configure a StoredProcedureCall Without Arguments + +You can configure a `+StoredProcedureCall+` without arguments and +execute it directly using `+Session+` API. Use this approach when you +want to execute a stored procedure that does not take arguments or +return values. + +*To configure a StoredProcedureCall without arguments using JDBC data +types:* + +[arabic] +. Instantiate a `+StoredProcedureCall+` object. +. Set the name of the stored procedure to execute using +`+StoredProcedureCall+` method `+setProcedureName+`, as the +link:#Example_105-42[Executing a SQLCall Without Arguments] example +shows. +. Execute the `+StoredProcedureCall+` using the appropriate `+Session+` +API, as the link:#Example_105-42[Executing a SQLCall Without Arguments] +example shows. You can use any of the following `+Session+` methods, +depending on the type of stored procedure you are executing: +* `+executeSelectingCall+`: returns a `+List+` of `+Record+` objects, +each representing a database row. +* `+executeNonSelectingCall+`: returns `+void+`. + +[#Example 105-42]## *_Executing a SQLCall Without Arguments_* + +`+StoredProcedureCall spcall = new StoredProcedureCall();+` +`+spcall.setProcedureName("Read_All_Employees");+` +`+spcall.useNamedCursorOutputAsResultSet("RESULT_SET");+` + +`+List employees = (List) getSession().executeSelectingCall(spcall);+` + +=== How to Configure a StoredProcedureCall with Arguments Using JDBC Data Types + +You can configure a `+StoredProcedureCall+` that takes any combination +of input, output, or input/output arguments. Use this approach when you +want to bind argument values to the `+StoredProcedureCall+` at runtime, +receive output values from the `+StoredProcedureCall+` at execution +time, or both. + +[width="100%",cols="<100%",] +|=== +|*Note:* Use this procedure when all input, output, and input/output +arguments are JDBC data types. If one or more arguments are PL/SQL +(non-JDBC) data types, see +link:#How_to_Configure_a_PLSQLStoredProcedureCall_with_PL_SQL_Data_Type_Arguments[How +to Configure a PLSQLStoredProcedureCall with PL/SQL Data Type +Arguments]. +|=== + +*To configure a StoredProcedureCall with arguments using JDBC data +types:* + +[arabic] +. Instantiate a `+StoredProcedureCall+` object. +. Specify the name of the stored procedure to call using +`+StoredProcedureCall+` method `+setProcedureName+`, as +link:#Example_105-43[Example 1], link:#Example_105-44[Example 2], and +link:#Example_105-45[Example 3] show. +. For each argument, use the appropriate `+StoredProcedureCall+` methods +to specify whether arguments are input, output, or input/output +arguments: +* Input argument: `+addNamedArgument+` (see link:#Example_105-43[Example +1]). +* Output argument: `+addNamedOutputArgument+` (see +link:#Example_105-44[Example 2]). +* Input/output argument: `+addNamedInOutputArgument+` (see +link:#Example_105-45[Example 3]). In general, you should always specify +the return Java data type for all output and input/output arguments, as +link:#Example_105-44[Example 2] and link:#Example_105-45[Example 3] +show. If you do not specify a return Java data type, the default is +`+java.lang.String+`. Typically, you specify arguments using the stored +procedure argument name as is. However, you may associate a stored +procedure argument name with an alternate name that you use in the +`+DatabaseQuery+`, as link:#Example_105-43[Example 1] shows. Use this +approach to specify a more meaningful argument name if the stored +procedure argument name is cryptic. +. Instantiate a `+DatabaseQuery+` appropriate for your stored procedure. +. Configure the `+DatabaseQuery+` with your `+StoredProcedureCall+` +using `+DatabaseQuery+` method `+setCall+`, as +link:#Example_105-43[Example 1], link:#Example_105-44[Example 2], and +link:#Example_105-45[Example 3] show. +. Specify the names for all input and input/output arguments using +`+DatabaseQuery+` method `+addArgument+`, as +link:#Example_105-43[Example 1], link:#Example_105-44[Example 2], and +link:#Example_105-45[Example 3] show. If you associated stored procedure +argument names with more meaningful alternate names in step +[[#3],_use_the_alternate_names_in_the_DatabaseQuery<_tt>__method__addArgument<_tt>,_as_link:#Example_105-43[Example +1] shows. +. Create a `+Vector+` of argument values in the same order as you +specified argument names in step [[#6],_as_link:#Example_105-43[Example +1], link:#Example_105-44[Example 2], and link:#Example_105-45[Example 3] +show. +. Bind values to the arguments and execute the `+DatabaseQuery+` using +`+Session+` method `+executeQuery(DatabaseQuery, java.util.Vector)+`, +passing in your `+DatabaseQuery+` and `+Vector+` of argument values, as +link:#Example_105-43[Example 1], link:#Example_105-44[Example 2], and +link:#Example_105-45[Example 3] show. + +[#Example 105-43]## *_Example 1: Specifying a StoredProcedureCall with +an Input Argument: JDBC Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'INSERT_EMPLOYEE(L_NAME\'\' \'\'IN\'\' \'\'VARCHAR)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'last\'\' \'\'name.+`* +*`+//\'\' \'\'END;+`* + +`+StoredProcedureCall spcall = new StoredProcedureCall();+` +`+spcall.setProcedureName("INSERT_EMPLOYEE");+` +`+spcall.addNamedArgument("L_NAME", "last_name");+` + +`+DataModifyQuery query = new DataModifyQuery();+` +`+query.setCall(spcall);+` +`+query.addArgument("last_name");   +`*`+//\'\' \'\'input+`* + +`+Vector arguments = new Vector();+` `+arguments.add("MacDonald");+` +`+session.executeQuery(query, arguments);+` + +[#Example 105-44]## *_Example 2: Specifying a StoredProcedureCall with +an Output Argument: JDBC Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'GET_EMP_ID(L_NAME\'\' \'\'IN\'\' \'\'VARCHAR,\'\' \'\'EMP_ID\'\' \'\'OUT\'\' \'\'INTEGER)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'last\'\' \'\'name\'\' \'\'and\'\' \'\'return\'\' \'\'the\'\' \'\'EMP_ID\'\' \'\'for\'\' \'\'this\'\' \'\'record.+`* +*`+//\'\' \'\'END;+`* + +`+StoredProcedureCall spcall = new StoredProcedureCall();+` +`+spcall.setProcedureName("GET_EMP_ID");+` +`+spcall.addNamedArgument("L_NAME");+` +`+spcall.addNamedOutputArgument(+` +`+    "EMP_ID",      +`*`+//\'\' \'\'procedure\'\' \'\'parameter\'\' \'\'name+`* +`+    "EMP_ID",      +`*`+//\'\' \'\'out\'\' \'\'argument\'\' \'\'field\'\' \'\'name+`* +`+    Integer.class  +`*`+//\'\' \'\'Java\'\' \'\'type\'\' \'\'corresponding\'\' \'\'to\'\' \'\'type\'\' \'\'returned\'\' \'\'by\'\' \'\'procedure+`* +`+);+` + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(spcall);+` +`+query.addArgument("L_NAME");   +`*`+//\'\' \'\'input+`* + +`+List args = new ArrayList();+` `+args.add("MacDonald");+` + +`+Integer employeeID = (Integer) getSession().executeQuery(query, args);+` + +[#Example 105-45]## *_Example 3: Specifying a StoredProcedureCall with +an Input/Output Argument: JDBC Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'INSERT_EMPLOYEE(IN_OUT\'\' \'\'INOUT\'\' \'\'VARCHAR)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'last\'\' \'\'name\'\' \'\'and\'\' \'\'return\'\' \'\'the\'\' \'\'EMP_CODE_NAME\'\' \'\'for\'\' \'\'this\'\' \'\'record.+`* +*`+//\'\' \'\'END;+`* + +`+StoredProcedureCall spcall = new StoredProcedureCall();+` +`+spcall.setProcedureName("INSERT_EMP"); +`*`+//\'\' \'\'returns\'\' \'\'EMP_CODE_NAME\'\' \'\'after\'\' \'\'insert+`* +`+spcall.addNamedInOutputArgument(+` +`+    "IN_OUT",       +`*`+//\'\' \'\'procedure\'\' \'\'parameter\'\' \'\'name+`* +`+    "IN_OUT",       +`*`+//\'\' \'\'out\'\' \'\'argument\'\' \'\'field\'\' \'\'name+`* +`+    String.class    +`*`+//\'\' \'\'Java\'\' \'\'type\'\' \'\'corresponding\'\' \'\'to\'\' \'\'type\'\' \'\'returned\'\' \'\'by\'\' \'\'procedure+`* +`+);+` + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(sqlCall);+` +`+query.addArgument("INOUT");   +`*`+//\'\' \'\'input\'\' \'\'and\'\' \'\'outpu+`* +`+ +` `+List args = new ArrayList();+` +`+args.add("MacDonald");         +`*`+// type of input argument determines type of output value+`* +`+ +` +`+String employeeCode = (String)getSession().executeQuery(query, args));+` + +=== How to Configure a PLSQLStoredProcedureCall with PL/SQL Data Type Arguments + +You must use the +`+org.eclipse.persistence.platform.database.oracle.PLSQLStoredProcedureCall+` +class if *any* combination of input, output, or input/output arguments +are PL/SQL (non-JDBC) data types. Use this approach when you want to +bind argument values to the `+PLSQLStoredProcedureCall+` at run time, +receive output values from the `+PLSQLStoredProcedureCall+` at execution +time, or both. + +[width="100%",cols="<100%",] +|=== +|*Note:* If all arguments are JDBC (not PL/SQL data types), see +link:#How_to_Configure_a_StoredProcedureCall_with_Arguments_Using_JDBC_Data_Types[How +to Configure a StoredProcedureCall with Arguments Using JDBC Data +Types]. +|=== + +*To configure a PLSQLStoredProcedureCall with arguments using JDBC and +PL/SQL data types:* + +[arabic] +. Instantiate a `+PLSQLStoredProcedureCall+` object. +. Specify the name of the stored procedure to call using +`+PLSQLStoredProcedureCall+` method `+setProcedureName+`, as +link:#Example_105-46[Example 1], link:#Example_105-47[Example 2], and +link:#Example_105-48[Example 3] show. +. For each argument, use the appropriate `+PLSQLStoredProcedureCall+` +methods to specify whether arguments are input, output, or input/output +arguments: +* Input argument: `+addNamedArgument+` (see link:#Example_105-46[Example +1]). +* Output argument: `+addNamedOutputArgument+` (see +link:#Example_105-47[Example 2]). +* Input/output argument: `+addNamedInOutputArgument+` (see +link:#Example_105-48[Example 3]). You must specify the data type for all +arguments: input, output, and input/output. You use +`+org.eclipse.persistence.platform.database.jdbc.JDBCTypes+` to specify +JDBC types and +`+org.eclipse.persistence.platform.database.oracle.OraclePLSQLTypes+` to +specify PL/SQL types. For JDBC and PL/SQL input arguments (and the in +value of input/output arguments), you may use any Java type with +sufficient size and precision for the argument. For JDBC output +arguments (and the out value of input/output arguments) EclipseLink +converts the JDBC data types to Java types as before. For PL/SQL output +arguments (and the out value of input/output arguments), EclipseLink +converts PL/SQL data types to the Java data types that +link:#Table_105-1[Table 105-1] lists. Typically, you specify the +arguments using the stored procedure argument name as is. However, you +may associate a stored procedure argument name with an alternate name +that you use in the `+DatabaseQuery+`, as link:#Example_105-48[Example +3] shows. Use this approach to specify a more meaningful argument name +if the stored procedure argument name is cryptic. +. Instantiate a `+DatabaseQuery+` appropriate for your stored procedure. +. Configure the `+DatabaseQuery+` with your `+PLSQLStoredProcedureCall+` +using `+DatabaseQuery+` method `+setCall+`, as +link:#Example_105-46[Example 1], link:#Example_105-47[Example 2], and +link:#Example_105-48[Example 3] show. +. Specify the names for all input and input/output arguments using +`+DatabaseQuery+` method `+addArgument+`, as +link:#Example_105-46[Example 1], link:#Example_105-47[Example 2], and +link:#Example_105-48[Example 3] show. If you associated stored procedure +argument names with more meaningful alternate names in step 3, use the +alternate names in the `+DatabaseQuery+` method `+addArgument+`, as +link:#Example_105-48[Example 3] shows. +. Create a `+Vector+` of argument values in the same order as you +specified argument names in step #6, as link:#Example_105-46[Example 1], +link:#Example_105-47[Example 2], and link:#Example_105-48[Example 3] +show. +. Bind values to the arguments and execute the `+DatabaseQuery+` using +`+Session+` method `+executeQuery(DatabaseQuery, java.util.Vector)+`, +passing in your `+DatabaseQuery+` and `+Vector+` of argument values, as +link:#Example_105-46[Example 1], link:#Example_105-47[Example 2], and +link:#Example_105-48[Example 3] show. + +[#Example 105-46]## *_Example 1: Specifying a PLSQLStoredProcedureCall +with an Input Argument: JDBC and PL/SQL Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'INSERT_EMPLOYEE(L_NAME\'\' \'\'IN\'\' \'\'VARCHAR,\'\' \'\'MANAGER\'\' \'\'IN\'\' \'\'BOOLEAN)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'last\'\' \'\'name\'\' \'\'and\'\' \'\'whether\'\' \'\'or\'\' \'\'not\'\' \'\'the\'\' \'\'employee\'\' \'\'is\'\' \'\'a\'\' \'\'manager.+`* +*`+//\'\' \'\'END;+`* + +`+PLSQLStoredProcedureCall plsqlcall = new PLSQLStoredProcedureCall();+` +`+plsqlcall.setProcedureName("INSERT_EMPLOYEE");+` +`+plsqlcall.addNamedArgument("L_NAME", JDBCTypes.VARCHAR_TYPE, 40); // must specify a length+` +`+plsqlcall.addNamedArgument("MANAGER", OraclePLSQLTypes.PLSQLBoolean);+` + +`+DataModifyQuery query = new DataModifyQuery();+` +`+query.setCall(plsqlcall);+` +`+query.addArgument("L_NAME");    +`*`+//\'\' \'\'input+`* +`+query.addArgument("MANAGER");   +`*`+//\'\' \'\'input+`* + +`+Vector arguments = new Vector();+` `+arguments.add("MacDonald");+` +`+arguments.add(Integer.valueOf(1));+` +`+session.executeQuery(query, arguments);+` + +[#Example 105-47]## *_Example 2: Specifying a PLSQLStoredProcedureCall +with an Output Argument: JDBC and PL/SQL Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'GET_EMP_ID(L_NAME\'\' \'\'IN\'\' \'\'VARCHAR,\'\' \'\'EMP_ID\'\' \'\'OUT\'\' \'\'PLS_INTEGER)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'last\'\' \'\'name\'\' \'\'and\'\' \'\'return\'\' \'\'EMP_ID\'\' \'\'for\'\' \'\'this\'\' \'\'row.+`* +*`+//\'\' \'\'END;+`* + +`+PLSQLStoredProcedureCall plsqlcall= new PLSQLStoredProcedureCall();+` +`+plsqlcall.setProcedureName("GET_EMP_ID");+` +`+plsqlcall.addNamedArgument("L_NAME", JDBCTypes.VARCHAR_TYPE, 25);+` +`+plsqlcall.addNamedOutputArgument("EMP_ID", OraclePLSQLTypes.PLSQLInteger);+` + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(plsqlcall);+` +`+query.addArgument("L_NAME");   +`*`+//\'\' \'\'input+`* + +`+List args = new ArrayList();+` `+args.add("MacDonald");+` + +`+Number employeeID = (Number) getSession().executeQuery(query, args);+` + +[#Example 105-48]## *_Example 3: Specifying a PLSQLStoredProcedureCall +with an Input/Output Argument: JDBC and PL/SQL Data Types_* + +*`+//\'\' \'\'CREATE\'\' \'\'PROCEDURE\'\' \'\'INSERT_EMP(IN_OUT\'\' \'\'INOUT\'\' \'\'PLS_INTEGER)\'\' \'\'AS+`* +*`+//\'\' \'\'BEGIN+`* +*`+//\'\' \'\'Insert\'\' \'\'an\'\' \'\'EMP\'\' \'\'record\'\' \'\'initialized\'\' \'\'with\'\' \'\'department\'\' \'\'id\'\' \'\'and\'\' \'\'return+`*`+ +` +*`+//\'\' \'\'the\'\' \'\'EMP_ID\'\' \'\'for\'\' \'\'this\'\' \'\'record.+`* +*`+//\'\' \'\'END;+`* + +`+PLSQLStoredProcedureCall plsqlcall= new PLSQLStoredProcedureCall();+` +`+plsqlcall.setProcedureName("INSERT_EMP");+` +`+plsqlcall.addNamedInOutputArgument("IN_OUT", OraclePLSQLTypes.PLSQLInteger);+` + +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(plsqlcall);+` +`+query.addArgument("IN_OUT");       +`*`+//\'\' \'\'input\'\' \'\'and\'\' \'\'outpu+`* + +`+List args = new ArrayList();+` +`+args.add(Integer.valueOf(1234));   +`*`+// department id+`* + +`+Integer employeeID = new Integer(BigDecimal.intValue(getSession().executeQuery(query, args)));+` + +=== How to Specify a Simple Optimistic Version Locking Value with a StoredProcedureCall Using JDBC Data Types + +When using optimistic version locking, you typically delegate the +responsibility for updating the version field to EclipseLink. + +Alternatively, you may choose to use stored procedures to manually +update the version field for all of create, read, update, and delete +operations. + +When using optimistic locking and stored procedure calls, you may only +use a simple, sequential numeric value that the stored procedure can +generate independently of EclipseLink. To use a complex value, such as a +timestamp, you must delegate the responsibility for updating the version +field to EclipseLink. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)[Optimistic Version Locking +Policies]. + +*To specify a simple optimistic version locking value with a +StoredProcedureCall using JDBC data types:* + +[arabic] +. Create stored procedures for create, read, update, and delete +operations. Each stored procedure is responsible for checking and +updating the optimistic lock field: a simple sequential numeric value in +your database. The following example shows a typical stored procedure +for the update operation. [#Example 105-49]## *_Stored Procedure for +Update Operation Using Simple Optimistic Version Locking_* ++ +`+PROCEDURE Update_Employee (+` `+    P_EMP_ID NUMBER,+` +`+    P_SALARY NUMBER,+` `+    P_END_DATE DATE,+` +`+    P_MANAGER_ID NUMBER,+` `+    P_START_DATE DATE,+` +`+    P_F_NAME VARCHAR2,+` `+    P_L_NAME VARCHAR2,+` +`+    P_GENDER VARCHAR2,+` `+    P_ADDR_ID NUMBER,+` +`+    P_VERSION NUMBER,+` `+    P_START_TIME DATE,+` +`+    P_END_TIME DATE,+` `+    O_ERROR_CODE OUT NUMBER) AS+` `+BEGIN +` +`+Update SALARY set SALARY = P_SALARY WHERE (EMP_ID = P_EMP_ID); +` +`+Update EMPLOYEE set END_DATE = P_END_DATE, MANAGER_ID = P_MANAGER_ID, VERSION = P_VERSION + 1, START_DATE = P_START_DATE, F_NAME = P_F_NAME, L_NAME = P_L_NAME, GENDER = P_GENDER, ADDR_ID = P_ADDR_ID where ((EMP_ID = P_EMP_ID) and (VERSION = P_VERSION)); +` +`+O_ERROR_CODE := SQL%ROWCOUNT; +` `+END;+` +. Create a `+StoredProcedureCall+` for each of your custom create, read, +update, and delete stored procedures. The following example shows the +`+StoredProcedureCall+` for the update stored procedure in the +link:#Example_105-49[Stored Procedure for Update Operation Using Simple +Optimistic Version Locking]. [#Example 105-50]## example. ++ +*_StoredProcedureCall for Update Stored Procedure_* ++ +`+UpdateObjectQuery updateQuery = new UpdateObjectQuery();+` +`+call = new StoredProcedureCall();+` `+call.setUsesBinding(true);+` +`+call.setProcedureName("Update_Employee");+` +`+call.addNamedArgument("P_EMP_ID", "EMP_ID");+` +`+call.addNamedArgument("P_SALARY", "SALARY");+` +`+call.addNamedArgument("P_END_DATE", "END_DATE");+` +`+call.addNamedArgument("P_MANAGER_ID", "MANAGER_ID");+` +`+call.addNamedArgument("P_START_DATE", "START_DATE");+` +`+call.addNamedArgument("P_F_NAME", "F_NAME");+` +`+call.addNamedArgument("P_L_NAME", "L_NAME");+` +`+call.addNamedArgument("P_GENDER", "GENDER");+` +`+call.addNamedArgument("P_ADDR_ID", "ADDR_ID");+` +`+call.addNamedArgument("P_VERSION", "VERSION");+` +`+call.addNamedArgument("P_START_TIME", "START_TIME");+` +`+call.addNamedArgument("P_END_TIME", "END_TIME");+` +`+call.addNamedOutputArgument("O_ERROR_CODE", "O_ERROR_CODE", Long.class);+` +`+updateQuery.setCall(call);+` ++ +For more information, see the following: +* link:#How_to_Configure_a_StoredProcedureCall_Without_Arguments[How to +Configure a StoredProcedureCall Without Arguments] +* link:#How_to_Configure_a_StoredProcedureCall_with_Arguments_Using_JDBC_Data_Types[How +to Configure a StoredProcedureCall with Arguments Using JDBC Data Types] +* link:#How_to_Configure_a_StoredProcedureCall_with_Arguments_Using_JDBC_and_PL_SQL_Data_Types[How +to Configure a StoredProcedureCall with Arguments Using JDBC and PL/SQL +Data Types] +. Configure the EclipseLink descriptor query manager to use your +`+StoredProcedureCall+` objects for create, read, update, and delete +operations. The following example shows how to use a descriptor +customizer class to update the EclipseLink descriptor query manager with +the update `+StoredProcedureCall+` from the +link:#Example_105-50[StoredProcedureCall for Update Stored Procedure] +example. [#Example 105-51]## *_Configuring the EclipseLink Descriptor +Query Manager with a StoredProcedureCall_* ++ +`+import org.eclipse.persistence.sessions.factories.DescriptorCustomizer;+` +`+import org.eclipse.persistence.descriptors.ClassDescriptor;+` + +`+public class EmployeeDescriptorCustomizer implements DescriptorCustomizer {+` + +`+    public void customize(ClassDescriptor descriptor) {+` +`+        descriptor.getQueryManager().setUpdateQuery(updateQuery);+` +`+    }+` `+}+` ++ +For more information, see the following: +* link:Configuring%20a%20Relational%20Descriptor%20(ELUG)[Configuring +Custom SQL Queries for Basic Persistence Operations] +* link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor +Customizer Class] +. Define a `+StoredProcedureCall+` output parameter event to handle any +errors. ++ +In the Oracle database, the rowcount is not maintained when calling a +stored procedure. You must ensure that the rowcount is returned using an +output parameter. Use the `+Session+` event `+outputParametersDetected+` +to check the rowcount and raise an error. Alternatively, the stored +procedure could check the rowcount and throw an exception. ++ +For more information, see +link:#How_to_Configure_a_StoredProcedureCall_Output_Parameter_Event_Using_JDBC_or_PL_SQL_Data_Types[How +to Configure a StoredProcedureCall Output Parameter Event Using JDBC or +PL/SQL Data Types] + +=== How to Configure a StoredProcedureCall Output Parameter Event Using JDBC or PL/SQL Data Types + +EclipseLink manages output parameter events for databases that support +them. For example, if a stored procedure returns an error code that +indicates that the application wants to check for an error condition, +EclipseLink raises the session event `+outputParametersDetected+` to +allow the application to process the output parameters. + +*To configure a StoredProcedureCall output parameter event using JDBC or +PL/SQL data types:* + +[arabic] +. Create a `+StoredProcedureCall+` using JDBC arguments, PL/SQL +arguments, or both. The link:#Example_105-55[Stored Procedure] example +shows a `+StoredProcedureCall+` using JDBC arguments. For more +information, see the following: +* link:#How_to_Configure_a_StoredProcedureCall_with_Arguments_Using_JDBC_Data_Types[How +to Configure a StoredProcedureCall with Arguments Using JDBC Data Types] +* link:#How_to_Configure_a_StoredProcedureCall_with_Arguments_Using_JDBC_and_PL_SQL_Data_Types[How +to Configure a StoredProcedureCall with Arguments Using JDBC and PL/SQL +Data Types] ++ +[#Example 105-52]## ++ +*_Stored Procedure_* ++ +`+PROCEDURE Update_Employee (+` `+    P_EMP_ID NUMBER,+` +`+    P_SALARY NUMBER,+` `+    P_END_DATE DATE,+` +`+    P_MANAGER_ID NUMBER,+` `+    P_START_DATE DATE,+` +`+    P_F_NAME VARCHAR2,+` `+    P_L_NAME VARCHAR2,+` +`+    P_GENDER VARCHAR2,+` `+    P_ADDR_ID NUMBER,+` +`+    P_VERSION NUMBER,+` `+    P_START_TIME DATE,+` +`+    P_END_TIME DATE,+` `+    O_ERROR_CODE OUT NUMBER) AS+` `+BEGIN +` +`+Update SALARY set SALARY = P_SALARY WHERE (EMP_ID = P_EMP_ID); +` +`+Update EMPLOYEE set END_DATE = P_END_DATE, MANAGER_ID = P_MANAGER_ID, VERSION = P_VERSION + 1, START_DATE = P_START_DATE, F_NAME = P_F_NAME, L_NAME = P_L_NAME, GENDER = P_GENDER, ADDR_ID = P_ADDR_ID where ((EMP_ID = P_EMP_ID) and (VERSION = P_VERSION)); +` +`+O_ERROR_CODE := SQL%ROWCOUNT; +` `+END;+` +. Create a `+SessionEventListener+` that handles the +`+outputParametersDetected+` event, as the +link:#Example_105-53[SessionEventListener for outputParametersDetected +Event] example shows. Subclassing the +`+org.eclipse.persistence.sessions.SessionEventAdapter+` is an easy way +to create a `+SessionEventListener+`: you only need to override the +specific `+SessionEventListener+` methods you are interested in. In the +link:#Example_105-53[SessionEventListener for outputParametersDetected +Event] example, `+SessionEvent+` method `+getProperty+` uses an argument +value of `+ERROR_CODE+`. This property name and its data type is defined +in the `+StoredProcedureCall+` method `+addNamedOutputArgument+`. ++ +[#Example 105-53]## ++ +*_SessionEventListener for outputParametersDetected Event_* ++ +`+import org.eclipse.persistence.sessions.SessionEventAdapter;+` +`+importorg.eclipse.persistence.sessions.SessionEvent;+` + +`+public class OptimisticLockListener extends SessionEventAdapter {+` + +`+    public OptimisticLockListener() {}+` `+ +` +`+    public void outputParametersDetected(SessionEvent event) {+` +`+        DatabaseQuery query = event.getQuery();+` +`+        if ((query != null) && query.isObjectLevelModifyQuery()) {+` +`+            Number rowcount = new Integer(1);+` +`+            if (event.getResult() instanceof Map) {+` +`+                rowcount = (Number)((Map)event.getResult()).get("O_ERROR_CODE");+` +`+            }+` `+            if (rowcount.longValue() <= 0) {+` +`+                if (query.isDeleteObjectQuery()) {+` +`+                    DeleteObjectQuery deleteQuery = (DeleteObjectQuery)query;+` +`+                    throw OptimisticLockException.objectChangedSinceLastReadWhenDeleting+` +`+                                                  (deleteQuery.getObject(), deleteQuery);+` +`+                } +` +`+                else if (query.isWriteObjectQuery()) {+` +`+                    WriteObjectQuery updateQuery = (WriteObjectQuery)query;+` +`+                    throw OptimisticLockException.objectChangedSinceLastReadWhenUpdating+` +`+                                                  (updateQuery.getObject(), updateQuery);+` +`+                }+` `+            }+` `+        }+` `+    }+` `+}+` +. Add your `+SessionEventListener+` instance to the session event +manager, as the link:#Example_105-54[Adding SessionEventListener to the +Session Event Manager] example shows. You must do this step before +executing your stored procedure. For more information, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Managing +Session Events with the Session Event Manager] [#Example 105-54]## +*_Adding SessionEventListener to the Session Event Manager_* ++ +`+getSession().getEventManager().addListener(new OptimisticLockListener());+` +. Execute the query. If there is an error and a `+SessionEvent+` of type +`+outputParametersDetected+` is raised, EclipseLink will notify your +`+SessionEventListener+`. ++ + +=== What You May Need to Know About Using a StoredProcedureCall + +EclipseLink automatically converts PL/SQL data types into the Java data +types that the following table lists for out arguments (and the out +value of input/output arguments). + +[#Table 105-1]## *_EclipseLink PL/SQL to Java Data Type Conversion: Out +Arguments and Out Value of Input/Output Arguments_* + +[width="100%",cols="<32%,<36%,<32%",options="header",] +|=== +|*PL/SQL Data Type* |*OraclePLSQLTypes Enum* |*Java Type* +|`+BINARY_INTEGER+` |`+BinaryInteger+` |`+java.math.BigDecimal+` +|`+BOOLEAN+` |`+PLSQLBoolean+` |`+java.lang.Integer+` +|`+DEC+` |`+Dec+` |`+java.math.BigDecimal+` +|`+INT+` |`+Int+` |`+java.math.BigDecimal+` +|`+NATURAL+` |`+Natural+` |`+java.math.BigDecimal+` +|`+NATURALN+` |`+NaturalN+` |`+java.math.BigDecimal+` +|`+PLS_INTEGER+` |`+PLSQLInteger+` |`+java.math.BigDecimal+` +|`+POSITIVE+` |`+Positive+` |`+java.math.BigDecimal+` +|`+POSITIVEN+` |`+PositiveN+` |`+java.math.BigDecimal+` +|`+SIGNTYPE+` |`+SignType+` |`+java.lang.Integer+` +|=== + +You may use the value from any Java type for a PL/SQL in argument (or in +value of an input/output argument) as long as the size and precision of +the Java type is appropriate for the PL/SQL type. + +[width="100%",cols="<100%",] +|=== +|*Note:* You no longer need to use `+DatabaseQuery+` method +`+bindAllParameters+` when using a `+StoredProcedureCall+` with `+OUT+` +or `+INOUT+` parameters. However, you should always specify the Java +type for all `+OUT+` and `+INOUT+` parameters. If you do not, be aware +of the fact that they default to type `+String+`. +|=== + +== Using a StoredFunctionCall + +The EclipseLink expression framework enables you to define complex +queries at the object level. If your application requires a more complex +query or one that invokes an existing stored function that your database +provides, you can define a `+StoredFunctionCall+` object using both JDBC +and PL/SQL data types and invoke the stored function in the context of a +`+DatabaseQuery+`. + +Note that not all databases provide stored functions. + +In the link:#Example_105-56[Creating a StoredFunctionCall] example, note +that the name of the stored function is set using `+StoredFunctionCall+` +method `+setProcedureName+`. + +[#Example 105-56]## *_Creating a StoredFunctionCall_* + +`+StoredFunctionCall functionCall = new StoredFunctionCall();+` +`+functionCall.setProcedureName("CHECK_VALID_EMPLOYEE");+` +`+functionCall.addNamedArgument("EMP_ID");+` +`+functionCall.setResult("FUNCTION_RESULT", String.class);+` +`+ValueReadQuery query = new ValueReadQuery();+` +`+query.setCall(functionCall);+` `+query.addArgument("EMP_ID");+` +`+List args = new ArrayList();+` `+args.addElement(new Integer(44));+` +`+String valid = (String) session.executeQuery(query, args);+` + +=== What You May Need to Know About Using a StoredFunctionCall + +In general, both stored procedures and stored functions let you specify +input parameters, output parameters, and input and output parameters. +For more information, see link:#Using_a_StoredProcedureCall[Using a +StoredProcedureCall]. However, stored procedures need not return values, +while stored functions always return a single value. + +The `+StoredFunctionCall+` class extends `+StoredProcedureCall+` to add +one new method - `+setResult+`. Use this method to specify the name (and +alternatively both the name and type) under which EclipseLink stores the +return value of the stored function. + +When EclipseLink prepares a `+StoredFunctionCall+`, it validates its SQL +and throws a `+ValidationException+` under the following circumstances: + +* If your current platform does not support stored functions. Stored +functions are supported only for Oracle. +* If you fail to specify the return type. + +== Using Java Persistence Query Language (JPQL) Calls + +Information pending + +== Using EIS Interactions + +For an EIS root descriptor, you can define EIS interactions to invoke +methods on an EIS. + +EclipseLink represents EIS interactions using instances of +`+org.eclipse.persistence.eis.interactions.EISInteraction+`. These +classes implement the `+Call+` interface and can be used wherever a +`+Call+` can be used. + +This table lists the type of EIS interactions that EclipseLink supports. + +[#Table 105-2]## + +[width="100%",cols="<8%,<92%",options="header",] +|=== +|*EIS Interaction Type* |*Description* +|`+IndexedInteraction+` |Defines the specification for a call to a JCA +interaction that uses indexed records. Builds the input and output +records from the arguments by position. + +|`+MappedInteraction+` |Defines the specification for a call to a JCA +interaction that uses mapped records. Builds the input and output +records from the arguments by name. + +|`+XMLInteraction+` |Specifies an instance of `+MappedInteraction+` that +defines the specification for a call to a JCA interaction that uses XML +records defined by the XML schema document (XSD) associated with the EIS +project (for more information, see link:Using%20Workbench%20(ELUG)[How +to Import an XML Schema]). + +|`+QueryStringInteraction+` |Specifies an instance of +`+MappedInteraction+` that defines the specification for a call to a JCA +interaction that uses a query string. Prefix arguments in the query +string with a number sign ( `+#+` ) character. + +|`+XQueryInteraction+` |Specifies an instance of `+XMLInteraction+` that +defines the specification for a call to a JCA interaction that uses +XQuery. Translates the XQuery from the query arguments. +|=== + +You can use EclipseLink to define an interaction for each basic +persistence operation (`+insert+`, `+update+`, `+delete+`, +`+read object+`, `+read all+`, or `+does exist+`) so that when you query +and modify your EIS-mapped objects, the EclipseLink runtime will use the +appropriate EIS interaction. For more information, see +link:Configuring%20an%20EIS%20Descriptor%20(ELUG)[Configuring Custom EIS +Interactions for Basic Persistence Operations]. + +You can also use EclipseLink to define an interaction as a named query +for read object and read-all object queries. These queries are not +called for basic persistence operations; you can call these additional +queries by name in your application for special purposes. For more +information, see link:Configuring%20a%20Descriptor%20(ELUG)[Creating an +EIS Interaction for a Named Query]. + +== Handling Exceptions + +Most exceptions in queries are database exceptions, resulting from a +failure in the database operation. Write operations can also throw an +`+OptimisticLockException+` on a write, update, or delete operation in +applications that use optimistic locking. To catch these exceptions, +execute all database operations within a `+try+`-`+catch+` block: + +`+    try {+` +`+        List employees = session.readAllObjects(Employee.class); +` +`+    } +` `+    catch (DatabaseException exception) {+` +`+        +`*`+//\'\' \'\'handle\'\' \'\'exception+`*`+ +` `+    }+` + +See +link:EclipseLink%20Exception%20Error%20Reference%20(ELUG)%20[EclipseLink +Exception Error Reference] for more information about exceptions in an +EclipseLink application. + +== Handling Collection Query Results + +EclipseLink provides a `+useCollectionClass+` method to all subclasses +of `+DataReadQuery+` and `+ReadAllQuery+`, that you can use to configure +a query to return results as any concrete instance of `+Collection+` or +`+Map+`. + +Do not confuse collection query result configuration with a mapping +container policy (see +link:Configuring%20a%20Mapping%20(ELUG)[Configuring Container Policy]): +there is no relationship between the two. Collection query result +configuration determines how EclipseLink returns multiobject results +from a particular query. A mapping container policy tells EclipseLink +how your domain object implements a data member that contains a +collection. + +For example, consider a class `+Employee+` with a data member +`+phoneNumbers+`. In your implementation of `+Employee+`, the +`+getPhoneNumbers+` method returns a `+Vector+`. Using Workbench, you +map the `+phoneNumbers+` data member as a one-to-many mapping. You +configure the mapping container policy so that the mapping contains its +value (many `+PhoneNumber+` objects) in a `+Vector+`. This corresponds +to your implementation of `+Employee+`. + +You define a `+ReadAllQuery+` named `+localPhoneNumbers+` on the +`+DescriptorQueryManager+` of the `+PhoneNumber+`. The +`+localPhoneNumbers+` query takes one argument, the ID of an +`+Employee+` object, and returns all the phone numbers from its +`+phoneNumbers+` data member whose area code is 613. + +You get this query by name from the `+DescriptorQueryManager+` for +`+PhoneNumber+`. You call the `+useCollectionClass+` method on this +`+ReadAllQuery+`, passing in the `+ArrayList+` class. You execute the +query, passing in the ID of an `+Employee+`. The query returns all the +`+PhoneNumber+` objects from the `+Employee+` object’s `+phoneNumbers+` +data member whose area code is 613. The query returns these results as +an `+ArrayList+`. + +== Handling Report Query Results + +The following table lists the `+ReportQuery+` methods you can use to +configure how a `+ReportQuery+` returns its results. + +By default, the `+ReportQuery+` returns a `+Collection+` of +`+ReportQueryResult+` objects. + +[#Table 105-3]## *_Report Query Result Options_* + +Method + +Query Returns + +Description + +setShouldReturnSingleAttribute + +Collection + +Returns a single attribute (not wrapped in a ReportQueryResult). + +Use this option if you know that the ReportQuery returns only one +attribute. + +setShouldReturnSingleResult + +ReportQueryResult + +Returns only the first ReportQueryResult object (not wrapped in a +Collection or Map). + +Use this option if you know that the ReportQuery returns only one row. + +setShouldReturnSingleValue + +Object + +Returns only a single value. + +Use this option if you know that the ReportQuery returns only one row +that contains only one attribute. + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report_Query[Report +Query] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report_Query_Results[Report +Query Results] +* link:#Reading_Objects_Using_Report_Queries[Reading Objects Using +Report Queries] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Named_Query_Attributes[Configuring +Named Query Attributes] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Unit_of_Work_API_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Unit_of_Work_API_(ELUG).adoc new file mode 100644 index 00000000000..22ed436b13e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_Basic_Unit_of_Work_API_(ELUG).adoc @@ -0,0 +1,822 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Using_Basic_Unit_of_Work_API_(ELUG)[Related +Topics] + +This section explains the essential unit of work API calls that you are +most likely to use throughout the development cycle. For more +information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Using Advanced +Unit of Work API]. + +== Acquiring a Unit of Work + +This example shows how to acquire a unit of work from a client session +object. + +`+Server server = (Server) SessionManager.getManager().getSession(+` +`+                sessionName, MyServerSession.class.getClassLoader());+` +`+Session session = (Session) server.acquireClientSession();+` +`+UnitOfWork uow = session.acquireUnitOfWork();+` + +You can acquire a unit of work from any session type. For more +information about acquiring sessions at run time, see +link:Introduction%20to%20EclipseLink%20Sessions%20(ELUG)[Acquiring a +Session at Run Time with the Session Manager]. + +Note that you do not need to create a new session and log in before +every transaction. The recommended pattern is to acquire a client +session per client access (or thread), and then acquire the necessary +unit of work from this client session. + +The unit of work is valid until the `+commit+` or `+release+` method is +called. After a commit or release transaction, a unit of work is not +valid even if the transaction fails and is rolled back. + +A unit of work remains valid after the `+commitAndResume+` method is +called, as described in +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Resuming a Unit +of Work After Commit]. + +When using a unit of work with JTA, you should also use the advanced API +`+getActiveUnitOfWork+` method, as described in +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Integrating the +Unit of Work with an External Transaction Service]. + +== Creating an Object + +When you create new objects in the unit of work, use the +`+registerObject+` method to ensure that the unit of work writes the +objects to the database at commit time. + +The unit of work calculates commit order using foreign key information +from one-to-one and one-to-many mappings. If you encounter constraint +problems during a commit transaction, verify your mapping definitions. +The order in which you register objects with the `+registerObject+` +method does not affect the commit order. + +link:#Example_110-1[Creating an Object: Preferred Method] and +link:#Example_110-2[Creating an Object: Alternative Method] examples +show how to create and persist a simple object (without relationships) +using the clone returned by the unit of work `+registerObject+` method. + +[#Example 110-1]## *_Creating an Object: Preferred Method_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet pet = new Pet();+` +`+Pet petClone = (Pet)uow.registerObject(pet);+` +`+petClone.setId(100);+` `+petClone.setName("Fluffy");+` +`+petClone.setType("Cat");+` `+uow.commit();+` + +This example shows a common alternative. + +[#Example 110-2]## *_Creating an Object: Alternative Method_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet pet = new Pet();+` `+pet.setId(100);+` `+pet.setName("Fluffy");+` +`+pet.setType("Cat");+` `+uow.registerObject(pet); +` `+uow.commit();+` + +Both approaches produce the following SQL: + +`+INSERT INTO PET (ID, NAME, TYPE, PET_OWN_ID) VALUES (100, 'Fluffy', 'Cat', NULL)+` + +You should follow the link:#Example_110-1[Creating an Object: Preferred +Method] example: it gets you into the pattern of working with clones and +provides the most flexibility for future code changes. Working with +combinations of new objects and clones can lead to confusion and +unwanted results. + +== Modifying an Object + +In the link:#Example_110-3[Modifying an Object] example, a `+Pet+` is +read prior to a unit of work: the variable `+pet+` is the cache copy +clone for that `+Pet+`. Inside the unit of work, register the cache copy +to get a working copy clone, then modify the working copy clone and +commit the unit of work. + +[#Example 110-3]## *_Modifying an Object_* + +*`+//\'\' \'\'Read\'\' \'\'in\'\' \'\'any\'\' \'\'pet+`* +`+Pet pet = (Pet)session.readObject(Pet.class);+` +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet petClone = (Pet) uow.registerObject(pet);+` +`+petClone.setName("Furry");+` `+uow.commit();+` + +link:#Example_110-4[Modifying an Object: Skipping the Registration Step] +example shows how to take advantage of the fact that you can query +through a unit of work and get back clones, saving the registration +step. However, the drawback is that you do not have a handle to the +cache copy clone. + +If you wanted to do something with the updated `+Pet+` after the commit +transaction, you would have to query the session to get it (remember +that after a unit of work is committed, its clones are invalid and +should not be used). + +[#Example 110-4]## *_Modifying an Object: Skipping the Registration +Step_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet petClone = (Pet) uow.readObject(Pet.class);+` +`+petClone.setName("Furry");+` `+uow.commit();+` + +Both approaches produce the following SQL: + +`+UPDATE PET SET NAME = 'Furry' WHERE (ID = 100)+` + +Take care when querying through a unit of work. All objects read in the +query are registered in the unit of work and therefore will be checked +for changes at commit time. Rather than do a `+ReadAllQuery+` through a +unit of work, it is better for performance to design your application to +do the `+ReadAllQuery+` through a session, and then register in a unit +of work only the objects that need to be changed. + +== Associating a New Target to an Existing Source Object + +Consider the following options: + +* #How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Unidirectional_Relationship:_Reference_to_the_New_Cache_Object_After_Commit_not_Required[How +to Associate a New Target to an Existing Source Object in a +Unidirectional Relationship: Reference to the New Cache Object After +Commit not Required] +* #How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Unidirectional_Relationship:_Reference_to_the_New_Cache_Object_After_Commit_Required[How +to Associate a New Target to an Existing Source Object in a +Unidirectional Relationship: Reference to the New Cache Object After +Commit Required] +* #How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Bidirectional_Relationship:_Query_for_Target_Before_Commit_not_Required[How +to Associate a New Target to an Existing Source Object in a +Bidirectional Relationship: Query for Target Before Commit not Required] +* #How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Bidirectional_Relationship:_Query_for_Target_Object_Before_Commit_Required[How +to Associate a New Target to an Existing Source Object in a +Bidirectional Relationship: Query for Target Object Before Commit +Required] + +Deciding which approach to use depends on whether or not your code +requires a reference to the cache copy clone of the new object after the +unit of work is committed, and on how adaptable to change you want your +code to be. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a `+ValidationException+` +or other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +=== How to Associate a New Target to an Existing Source Object in a Unidirectional Relationship: Reference to the New Cache Object After Commit not Required + +link:#Example_110-5[Associating Without Reference to the Cache Object] +example shows how to associate a new target with an existing source in a +unidirectional relationship without retaining a reference to the cache +object. + +When the `+Pet+` object is read using the unit of work, EclipseLink +automatically registers it. Because there is a unidirectional +relationship between the `+Pet+` object and the new `+PetOwner+` and +`+VetVisit+` objects, you do not need to register the new `+PetOwner+` +or `+VetVisit+` objects. EclipseLink can reach these new objects through +the registered `+Pet+` object and automatically detect that they are new +objects. + +[#Example 110-5]## *_Associating Without Reference to the Cache Object_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet petClone = (Pet)uow.readObject(Pet.class);+` + +`+PetOwner petOwner = new PetOwner();+` `+petOwner.setId(400);+` +`+petOwner.setName("Donald Smith");+` +`+petOwner.setPhoneNumber("555-1212");+` + +`+VetVisit vetVisit = new VetVisit();+` `+vetVisit.setId(500);+` +`+vetVisit.setNotes("Pet was shedding a lot.");+` +`+vetVisit.setSymptoms("Pet in good health.");+` +`+vetVisit.setPet(petClone);+` + +`+petClone.setPetOwner(petOwner);+` +`+petClone.getVetVisits().add(vetVisit); +` `+uow.commit();+` + +This executes the following proper SQL: + +`+INSERT INTO PETOWNER (ID, NAME, PHN_NBR) VALUES (400, 'Donald Smith', '555-1212')+` +`+UPDATE PET SET PET_OWN_ID = 400 WHERE (ID = 100)+` +`+INSERT INTO VETVISIT (ID, NOTES, SYMPTOMS, PET_ID) VALUES (500, 'Pet was shedding a lot.', 'Pet in good health.', 100)+` + +When associating new objects to existing objects, the unit of work +treats the new object as if it were a clone. That is, after the commit +transaction: + +`+petOwner != session.readObject(petOwner)+` + +Therefore, after the unit of work commit transaction, the variables +`+vetVisit+` and `+petOwner+` no longer point to their respective cache +objects; they point at working copy clones. + +If you need the cache object after the unit of work commit transaction, +you must query for it or create the association with a reference to the +cache object (as described in +#How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Unidirectional_Relationship:_Reference_to_the_New_Cache_Object_After_Commit_Required[How +to Associate a New Target to an Existing Source Object in a +Unidirectional Relationship: Reference to the New Cache Object After +Commit Required]). + +If there was a bidirectional relationship between the source and target +objects, you must take more care when registering them (see +#How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Bidirectional_Relationship:_Query_for_Target_Before_Commit_not_Required[How +to Associate a New Target to an Existing Source Object in a +Bidirectional Relationship: Query for Target Before Commit not +Required]). + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Registering and +Unregistering Objects]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a `+ValidationException+` +or other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +=== How to Associate a New Target to an Existing Source Object in a Unidirectional Relationship: Reference to the New Cache Object After Commit Required + +link:#Example_110-6[Associating With Reference to the Cache Object] +example shows how to associate a new target with an existing source in a +unidirectional relationship and retain a reference to the cache object. + +When the `+Pet+` object is read using the unit of work, EclipseLink +automatically registers it. Because there is a unidirectional +relationship between the `+Pet+` object and the new `+PetOwner+` and +`+VetVisit+` objects, you do not need to register the new `+PetOwner+` +or `+VetVisit+` objects. EclipseLink can reach these new objects through +the registered `+Pet+` object and automatically detect that they are new +objects. + +However, by using `+UnitOfWork+` method `+registerObject+`, you can +retain a handle to the post-commit cache objects in case your code needs +to continue using them after commit: for example, to display their new +contents in a GUI. + +If there was a bidirectional relationship between the source and target +objects, you must take more care when registering them (see +#How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Bidirectional_Relationship:_Query_for_Target_Object_Before_Commit_Required[How +to Associate a New Target to an Existing Source Object in a +Bidirectional Relationship: Query for Target Object Before Commit +Required]). + +[#Example 110-6]## *_Associating With Reference to the Cache Object_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet petClone = (Pet)uow.readObject(Pet.class);+` + +`+PetOwner petOwner = new PetOwner();+` +`+PetOwner petOwnerClone = (PetOwner)uow.registerObject(petOwner);+` +`+petOwnerClone.setId(400);+` `+petOwnerClone.setName("Donald Smith");+` +`+petOwnerClone.setPhoneNumber("555-1212");+` + +`+VetVisit vetVisit = new VetVisit();+` +`+VetVisit vetVisitClone = (VetVisit)uow.registerObject(vetVisit);+` +`+vetVisitClone.setId(500);+` +`+vetVisitClone.setNotes("Pet was shedding a lot.");+` +`+vetVisitClone.setSymptoms("Pet in good health.");+` +`+vetVisitClone.setPet(petClone);+` + +`+petClone.setPetOwner(petOwnerClone);+` +`+petClone.getVetVisits().addElement(vetVisitClone); +` +`+uow.commit();+` + +Now, after the unit of work commit transaction: + +`+petOwner == session.readObject(petOwner)+` + +This means that we have a handle to the cache copy after the commit +transaction, rather than a clone. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Registering and +Unregistering Objects]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a ValidationException or +other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +=== How to Associate a New Target to an Existing Source Object in a Bidirectional Relationship: Query for Target Before Commit not Required + +Consider an `+Employee+` class implemented, as +link:#Example_110-7[Employee Class] example shows. Note that the +`+setManager+` method modifies the `+Employee+` instance you pass into +it. + +[#Example 110-7]## *_Employee Class_* + +`+public class Employee {+` + +`+    private Collection managedEmployees = new ArrayList();+` +`+    private Emplyoee myManager;+` + +`+    ...+` + +`+    public setManager(Employee manager) {+` +`+        myManager = manager;+` +`+        manager.addManagedEmployee(this);+` `+    }+` + +`+    public addManagedEmployee(Employee employee) {+` +`+        managedEmployees.add(employee);+` `+    }+` + +`+    ...+` + +`+}+` + +link:#Example_110-8[Resolving Issues When Adding New Objects] example +shows how to register a new object when a bidirectional relationship +exists such as that between manager and employee. + +Because `+Employee+` method `+setManager+` modifies the `+Employee+` you +pass in (as link:#Example_110-7[Employee Class] example shows), you must +pass in `+managerClone+` that `+registerObject+` returns. + +After you call `+setManager+`, you establish the bidirectional +relationship between `+newEmployee+` and `+managerClone+`. Because +`+newEmployee+` is reachable from the `+manager+` object already +registered with the unit of work, EclipseLink can automatically detect +that it is a new object. Consequently, you do not need to register +`+newEmployee+` at all and it is, in fact, an error to call +`+registerObject+` on `+newEmployee+` in this case. + +If your code must be able to query for the new child object prior to +commit, see +#How_to_Associate_a_New_Target_to_an_Existing_Source_Object_in_a_Bidirectional_Relationship:_Query_for_Target_Object_Before_Commit_Required[How +to Associate a New Target to an Existing Source Object in a +Bidirectional Relationship: Query for Target Object Before Commit +Required]. + +If you need the cache object after the unit of work commit transaction, +in this case, you must query for it. + +[#Example 110-8]## *_Resolving Issues When Adding New Objects_* + +*`+//\'\' \'\'Get\'\' \'\'an\'\' \'\'employee\'\' \'\'read\'\' \'\'from\'\' \'\'the\'\' \'\'parent\'\' \'\'session\'\' \'\'of\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+Employee manager = (Employee)session.readObject(Employee.class);+` + +*`+//\'\' \'\'Acquire\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+UnitOfWork uow = session.acquireUnitOfWork();+` + +*`+//\'\' \'\'Register\'\' \'\'the\'\' \'\'manager\'\' \'\'to\'\' \'\'get\'\' \'\'its\'\' \'\'clone+`* + +`+Employee managerClone = (Employee)uow.registerObject(manager);+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'new\'\' \'\'employee+`* +`+Employee newEmployee = new Employee();+` +`+newEmployee.setFirstName("Spike");+` +`+newEmployee.setLastName("Robertson");+` + +*`+//\'\' \'\'INCORRECT:\'\' \'\'Do\'\' \'\'not\'\' \'\'associate\'\' \'\'the\'\' \'\'new\'\' \'\'employee\'\' \'\'with\'\' \'\'the\'\' \'\'original\'\' \'\'manager.+`*`+ +` +*`+//\'\' \'\'This\'\' \'\'will\'\' \'\'cause\'\' \'\'a\'\' \'\'QueryException\'\' \'\'when\'\' \'\'EclipseLink\'\' \'\'detects\'\' \'\'this\'\' \'\'error\'\' \'\'during\'\' \'\'commit+`* +*`+//newEmployee.setManager(manager);+`* + +*`+//\'\' \'\'CORRECT:\'\' \'\'Associate\'\' \'\'the\'\' \'\'new\'\' \'\'object\'\' \'\'with\'\' \'\'the\'\' \'\'clone.\'\' \'\'Note\'\' \'\'that\'\' \'\'in\'\' \'\'this\'\' \'\'example,+`* +*`+//\'\' \'\'the\'\' \'\'setManager\'\' \'\'method\'\' \'\'is\'\' \'\'maintaining\'\' \'\'the\'\' \'\'bidirectional\'\' \'\'managedEmployees+`*`+ +` +*`+//\'\' \'\'relationship\'\' \'\'and\'\' \'\'adding\'\' \'\'the\'\' \'\'new\'\' \'\'employee\'\' \'\'to\'\' \'\'its\'\' \'\'managedEmployees.+`*`+ +` +`+'''// At commit time, the unit of work will detect that this is a new object +` +*`+//\'\' \'\'and\'\' \'\'will\'\' \'\'take\'\' \'\'the\'\' \'\'appropriate\'\' \'\'action+`* +`+newEmployee.setManager(managerClone);+` + +*`+//\'\' \'\'INCORRECT:\'\' \'\'Do\'\' \'\'not\'\' \'\'register\'\' \'\'the\'\' \'\'newEmployee:\'\' \'\'this\'\' \'\'will\'\' \'\'create+`*`+ +` +`+'''// two copies and cause a QueryException when EclipseLink detects +` +*`+//\'\' \'\'this\'\' \'\'error\'\' \'\'during\'\' \'\'commit+`* +*`+//uow.registerObject(newEmployee);+`* + +*`+//\'\' \'\'Commit\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+uow.commit();+` + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Registering and +Unregistering Objects]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a ValidationException or +other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +=== How to Associate a New Target to an Existing Source Object in a Bidirectional Relationship: Query for Target Object Before Commit Required + +Consider an `+Employee+` class implemented, as +link:#Example_110-9[Employee Class] example shows. Note that the +`+setManager+` method modifies the `+Employee+` instance you pass into +it. + +[#Example 110-9]## *_Employee Class_* + +`+public class Employee+` `+{+` +`+    private Collection managedEmployees = new ArrayList();+` +`+    private Emplyoee myManager;+` + +`+    ...+` + +`+    public setManager(Employee manager)+` `+    {+` +`+        myManager = manager;+` +`+        manager.addManagedEmployee(this);+` `+    }+` + +`+    public addManagedEmployee(Employee employee)+` `+    {+` +`+        managedEmployees.add(employee);+` `+    }+` + +`+    ...+` + +`+}+` + +link:#Example_110-10[Resolving Issues When Adding New Objects] example +shows how to register a new object when a bidirectional relationship +exists such as that between manager and employee. + +[#Example 110-10]## *_Resolving Issues When Adding New Objects_* + +*`+//\'\' \'\'Get\'\' \'\'an\'\' \'\'employee\'\' \'\'read\'\' \'\'from\'\' \'\'the\'\' \'\'parent\'\' \'\'session\'\' \'\'of\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* + +`+Employee manager = (Employee)session.readObject(Employee.class);+` + +*`+//\'\' \'\'Acquire\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+UnitOfWork uow = session.acquireUnitOfWork();+` + +*`+//\'\' \'\'Register\'\' \'\'the\'\' \'\'manager\'\' \'\'to\'\' \'\'get\'\' \'\'its\'\' \'\'clone+`* +`+Employee managerClone = (Employee)uow.registerObject(manager);+` + +*`+//\'\' \'\'Create\'\' \'\'a\'\' \'\'new\'\' \'\'employee+`* +`+Employee newEmployee = new Employee();+` +`+newEmployee.setFirstName("Spike");+` +`+newEmployee.setLastName("Robertson");+` + +*`+//\'\' \'\'INCORRECT:\'\' \'\'Do\'\' \'\'not\'\' \'\'associate\'\' \'\'the\'\' \'\'new\'\' \'\'employee\'\' \'\'with\'\' \'\'the\'\' \'\'original\'\' \'\'manager.+`*`+ +` +*`+//\'\' \'\'This\'\' \'\'will\'\' \'\'cause\'\' \'\'a\'\' \'\'QueryException\'\' \'\'when\'\' \'\'EclipseLink\'\' \'\'detects\'\' \'\'this\'\' \'\'error\'\' \'\'during\'\' \'\'commit+`* +*`+//newEmployee.setManager(manager);+`* + +*`+//\'\' \'\'CORRECT:\'\' \'\'Associate\'\' \'\'the\'\' \'\'new\'\' \'\'object\'\' \'\'with\'\' \'\'the\'\' \'\'clone.\'\' \'\'Note\'\' \'\'that\'\' \'\'in\'\' \'\'this\'\' \'\'example,+`* +*`+//\'\' \'\'the\'\' \'\'setManager\'\' \'\'method\'\' \'\'is\'\' \'\'maintaining\'\' \'\'the\'\' \'\'bidirectional\'\' \'\'managedEmployees+`*`+ +` +*`+//\'\' \'\'relationship\'\' \'\'and\'\' \'\'adding\'\' \'\'the\'\' \'\'new\'\' \'\'employee\'\' \'\'to\'\' \'\'its\'\' \'\'managedEmployees.+`*`+ +` +`+'''// At commit time, the unit of work will detect that this is a new object +` +*`+//\'\' \'\'and\'\' \'\'will\'\' \'\'take\'\' \'\'the\'\' \'\'appropriate\'\' \'\'action+`* +`+newEmployee.setManager(managerClone);+` + +`+'''// INCORRECT: Do not register the newEmployee: this will create two copies and+` +*`+//\'\' \'\'cause\'\' \'\'a\'\' \'\'QueryException\'\' \'\'when\'\' \'\'EclipseLink\'\' \'\'detects\'\' \'\'this\'\' \'\'error\'\' \'\'during\'\' \'\'commit+`* +*`+//uow.registerObject(newEmployee);+`* + +*`+//\'\' \'\'CORRECT:\'\' \'\'In\'\' \'\'the\'\' \'\'above\'\' \'\'setManager\'\' \'\'call,\'\' \'\'if\'\' \'\'the\'\' \'\'managerClone's+`* +`+'''// managedEmployees was not maintained by the setManager method, then you +` +`+'''// should call registerObject before the new employee is related to the manager. +` +`+'''// If in doubt, you could use the  registerNewObject method to ensure that +` +`+'''// the newEmployee is registered in the unit of work. The registerNewObject +` +*`+//\'\' \'\'method\'\' \'\'registers\'\' \'\'the\'\' \'\'object,\'\' \'\'but\'\' \'\'does\'\' \'\'not\'\' \'\'make\'\' \'\'a\'\' \'\'clone+`* +`+uow.registerNewObject(newEmployee);+` + +*`+//\'\' \'\'Commit\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+uow.commit();+` + +Because `+Employee+` method `+setManager+` modifies the `+Employee+` you +pass in (as link:#Example_110-10[Resolving Issues When Adding New +Objects] example), you must pass in `+managerClone+` that +`+registerObject+` returns. + +After you call `+setManager+`, you establish the bidirectional +relationship between `+newEmployee+` and `+managerClone+`. Because +`+newEmployee+` is reachable from the `+manager+` object already +registered with the unit of work, EclipseLink can automatically detect +that it is a new object. Consequently, you do not need to register +`+newEmployee+` at all and it is, in fact, an error to call +`+registerObject+` on `+newEmployee+` in this case. + +If your code must be able to query for the new child object prior to +commit, register the new object using `+UnitOfWork+` method +`+registerNewObject+`. Unlike `+registerObject+`, this method does not +create a clone. + +Another difference between `+registerNewObject+` and `+registerObject+` +is that `+registerNewObject+` does not cascade registration to child +objects. If you call `+registerNewObject+` on a parent object, you must +also call `+registerNewObject+` on new child instances if your code must +be able to query for the new child object prior to commit and you prefer +not to use conforming queries. + +If you need the cache object after the unit of work commit transaction, +you must query for it. + +For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Registering and +Unregistering Objects]). + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a ValidationException or +other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +== Associating a New Source to an Existing Target Object + +This section describes how to associate a new source object with an +existing target object with one-to-many and one-to-one relationships. + +EclipseLink follows all relationships of all registered objects (deeply) +in a unit of work to calculate what is new and what has changed. This is +known as _persistence by reachablity_. In +link:#Associating_a_New_Target_to_an_Existing_Source_Object[Associating +a New Target to an Existing Source Object] example, you saw that when +you associate a new target with an existing source, you can choose to +register the object or not. If you do not register the new object, it is +still reachable from the source object (which is a clone, hence it is +registered). However, when you need to associate a new source object +with an existing target, you must register the new object. If you do not +register the new object, then it is not reachable in the unit of work, +and EclipseLink will not write it to the database. + +link:#Example_110-11[Associating a New Source to an Existing Target +Object] example shows how to create a new `+Pet+` and associate it with +an existing `+PetOwner+`. + +[#Example 110-11]## *_Associating a New Source to an Existing Target +Object_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+PetOwner existingPetOwnerClone =+` +`+        (PetOwner)uow.readObject(PetOwner.class);+` + +`+Pet newPet = new Pet();+` +`+Pet newPetClone = (Pet)uow.registerObject(newPet);+` +`+newPetClone.setId(900);+` `+newPetClone.setType("Lizzard");+` +`+newPetClone.setName("Larry");+` +`+newPetClone.setPetOwner(existingPetOwnerClone);+` `+uow.commit();+` + +This generates the following proper SQL: + +`+INSERT INTO PET (ID, NAME, TYPE, PET_OWN_ID) VALUES (900, 'Larry', 'Lizzard', 400)+` + +In this situation, you should register the new object and work with the +working copy of the new object. If you associate the new object with the +`+PetOwner+` clone without registering, it will not be written to the +database. + +[width="100%",cols="<100%",] +|=== +|*Note:* You cannot use `+UnitOfWork+` methods `+registerObject+`, +`+registerNewObject+`, or `+registerExistingObject+` with an aggregate +object (see +link:Creating%20a%20Relational%20Descriptor%20(ELUG)[Creating Relational +Aggregate Descriptors]). Doing so will raise a ValidationException or +other errors at commit time. For more information, see +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[How to Work with +Aggregates]. +|=== + +If you fail to register the clone and accidentally associate the cache +version of the existing object with the new object, then EclipseLink +will generate an error which states that you have associated the cache +version of an object ("`from a parent session`") with a clone from this +unit of work. You must work with working copies in units of work. + +For more information, see the following: + +* link:#Associating_a_New_Target_to_an_Existing_Source_Object[Associating +a New Target to an Existing Source Object] +* link:#Associating_an_Existing_Source_to_an_Existing_Target_Object[Associating +an Existing Source to an Existing Target Object] + +== Associating an Existing Source to an Existing Target Object + +This section explains how to associate an existing source object with an +existing target object with one-to-many and one-to-one relationships. + +As shown in link:#Example_110-12[Associating an Existing Source to +Existing Target Object] example, associating existing objects with each +other in a unit of work is as simple as associating objects in Java. +Just remember to only work with working copies of the objects. + +[#Example 110-12]## *_Associating an Existing Source to Existing Target +Object_* + +*`+//\'\' \'\'Associate\'\' \'\'all\'\' \'\'VetVisits\'\' \'\'in\'\' \'\'the\'\' \'\'database\'\' \'\'to\'\' \'\'a\'\' \'\'Pet\'\' \'\'from\'\' \'\'the\'\' \'\'database+`* +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet existingPetClone = (Pet)uow.readObject(Pet.class);+` +`+List allVetVisitClones;+` +`+allVetVisitClones = uow.readAllObjects(VetVisit.class);+` +`+Iterator iter = allVetVisitClones.elements();+` +`+while(iter.hasNext()) {+` +`+    VetVisit vetVisitClone =(VetVisit)iter.next();+` +`+    existingPetClone.getVetVisits().add(vetVisitClone);+` +`+    vetVisitClone.setPet(existingPetClone);+` `+};+` `+uow.commit();+` + +The most common error when associating existing objects is failing to +work with the working copies. If you accidentally associate a cache +version of an object with a working copy you will get an error at commit +time indicating that you associated an object from a parent session (the +cache version) with a clone from this unit of work. + +link:#Example_110-13[Associating Existing Objects] example shows another +example of associating an existing source to an existing target object. + +[#Example 110-13]## *_Associating Existing Objects_* + +*`+//\'\' \'\'Get\'\' \'\'an\'\' \'\'employee\'\' \'\'read\'\' \'\'from\'\' \'\'the\'\' \'\'parent\'\' \'\'session\'\' \'\'of\'\' \'\'the\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* + +`+Employee employee = (Employee)session.readObject(Employee.class)+` + +*`+//\'\' \'\'Acquire\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Project project = (Project) uow.readObject(Project.class);+` + +*`+//\'\' \'\'When\'\' \'\'associating\'\' \'\'an\'\' \'\'existing\'\' \'\'object\'\' \'\'(read\'\' \'\'from\'\' \'\'the\'\' \'\'session)\'\' \'\'with\'\' \'\'a\'\' \'\'clone,+`*`+ +` +*`+//\'\' \'\'make\'\' \'\'sure\'\' \'\'you\'\' \'\'register\'\' \'\'the\'\' \'\'existing\'\' \'\'object\'\' \'\'and\'\' \'\'assign\'\' \'\'its\'\' \'\'clone\'\' \'\'into\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work+`* + +*`+//\'\' \'\'INCORRECT:\'\' \'\'Cannot\'\' \'\'associate\'\' \'\'an\'\' \'\'existing\'\' \'\'object\'\' \'\'with\'\' \'\'a\'\' \'\'unit\'\' \'\'of\'\' \'\'work\'\' \'\'clone.+`* +*`+//\'\' \'\'A\'\' \'\'QueryException\'\' \'\'will\'\' \'\'be\'\' \'\'thrown+`* +*`+//project.setTeamLeader(employee);+`* + +*`+//\'\' \'\'CORRECT:\'\' \'\'Instead\'\' \'\'register\'\' \'\'the\'\' \'\'existing\'\' \'\'object\'\' \'\'then\'\' \'\'associate\'\' \'\'the\'\' \'\'clone+`* +`+Employee employeeClone = (Employee)uow.registerObject(employee);+` +`+project.setTeamLeader(employeeClone);+` `+uow.commit();+` + +For more information, see the following: + +* link:#Associating_a_New_Target_to_an_Existing_Source_Object[Associating +a New Target to an Existing Source Object] +* link:#Associating_a_New_Source_to_an_Existing_Target_Object[Associating +a New Target to an Existing Source Object] + +== Deleting Objects + +To delete objects in a unit of work, use the `+deleteObject+` or +`+deleteAllObjects+` method. When you delete an object that is not +already registered in the unit of work, the unit of work registers the +object automatically. + +When you delete an object, EclipseLink deletes the object’s privately +owned child parts, because those parts cannot exist without the owning +(parent) object. At commit time, the unit of work generates SQL to +delete the objects, taking database constraints into account. + +When you delete an object, you must take your object model into account. +You may need to set references to the deleted object to null (for an +example, see link:#How_to_Use_the_privateOwnedRelationship_Attribute[How +to Use the privateOwnedRelationship Attribute]). + +This section explains how to delete objects within a unit of work, +including the following: + +* link:#How_to_Use_the_privateOwnedRelationship_Attribute[How to Use the +privateOwnedRelationship Attribute] +* link:#How_to_Explicitly_Delete_from_the_Database[How to Explicitly +Delete from the Database] +* link:#What_You_May_Need_to_Know_About_the_Order_in_which_Objects_Are_Deleted[What +You May Need to Know About the Order in which Objects Are Deleted] + +=== How to Use the privateOwnedRelationship Attribute + +Relational databases do not have garbage collection like a Java Virtual +Machine (JVM) does. To delete an object in Java you just remove the +reference to the object. To delete a row in a relational database, you +must explicitly delete it. Rather than tediously manage when to delete +data in the relational database, use the mapping attribute +`+privateOwnedRelationship+` to have EclipseLink manage the garbage +collection in the relational database for you. + +As shown in the link:#Example_110-14[Specifying a Mapping as Privately +Owned] example, when you create a mapping using Java, use its +`+privateOwnedRelationship+` method to tell EclipseLink that the +referenced object is privately owned: that is, the referenced child +object cannot exist without the parent object. + +[#Example 110-14]## *_Specifying a Mapping as Privately Owned_* + +`+OneToOneMapping petOwnerMapping = new OneToOneMapping();+` +`+petOwnerMapping.setAttributeName("petOwner");+` +`+petOwnerMapping.setReferenceClass(com.top.uowprimer.model.PetOwner.class);+` +`+petOwnerMapping.privateOwnedRelationship();+` +`+petOwnerMapping.addForeignKeyFieldName("PET.PET_OWN_ID", "PETOWNER.ID");+` +`+descriptor.addMapping(petOwnerMapping);+` + +When you create a mapping using Workbench, you can select the *Private +Owned* check box under the *General* tab. + +When you tell EclipseLink that a relationship is privately owned, you +are specifying the following: + +* If the source of a privately owned relationship is deleted, then +delete the target. +* If you remove the reference to a target from a source, then delete the +target. + +Do not configure privately owned relationships to objects that might be +shared. An object should not be the target in more than one relationship +if it is the target in a privately owned relationship. + +The exception to this rule is the case when you have a many-to-many +relationship in which a relation object is mapped to a relation table +and is referenced through a one-to-many relationship by both the source +and the target. In this case, if the one-to-many mapping is configured +as privately owned, then when you delete the source, all the association +objects will be deleted. + +Consider the link:#Example_110-15[Privately Owned Relationships] +example. + +[#Example 110-15]## *_Privately Owned Relationships_* + +*`+//\'\' \'\'If\'\' \'\'the\'\' \'\'Pet-PetOwner\'\' \'\'relationship\'\' \'\'is\'\' \'\'privateOwned+`* +*`+//\'\' \'\'then\'\' \'\'the\'\' \'\'PetOwner\'\' \'\'will\'\' \'\'be\'\' \'\'deleted\'\' \'\'at\'\' \'\'uow.commit()+`* +*`+//\'\' \'\'otherwise,\'\' \'\'just\'\' \'\'the\'\' \'\'foreign\'\' \'\'key\'\' \'\'from\'\' \'\'PET\'\' \'\'to\'\' \'\'PETOWNER\'\' \'\'will+`* +*`+//\'\' \'\'be\'\' \'\'set\'\' \'\'to\'\' \'\'null.\'\' \'\'The\'\' \'\'same\'\' \'\'is\'\' \'\'true\'\' \'\'for\'\' \'\'VetVisit+`* +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+Pet petClone = (Pet)uow.readObject(Pet.class);+` +`+petClone.setPetOwner(null);+` +`+VetVisit vvClone = (VetVisit)petClone.getVetVisits().get(0);+` +`+vvClone.setPet(null);+` `+petClone.getVetVisits().remove(vvClone);+` +`+uow.commit();+` + +If the relationships from `+Pet+` to `+PetOwner+` and from `+Pet+` to +`+VetVisit+` are not privately owned, this code produces the following +SQL: + +`+UPDATE PET SET PET_OWN_ID = NULL WHERE (ID = 150)+` +`+UPDATE VETVISIT SET PET_ID = NULL WHERE (ID = 350)+` + +If the relationships are privately owned, this code produces the +following SQL: + +`+UPDATE PET SET PET_OWN_ID = NULL WHERE (ID = 150)+` +`+UPDATE VETVISIT SET PET_ID = NULL WHERE (ID = 350)+` +`+DELETE FROM VETVISIT WHERE (ID = 350)+` +`+DELETE FROM PETOWNER WHERE (ID = 250)+` + +=== How to Explicitly Delete from the Database + +If there are cases where you have objects that will not be garbage +collected through privately owned relationships (especially root objects +in your object model), then you can explicitly tell EclipseLink to +delete the row representing the object using the `+deleteObject+` API, +as shown in the link:#Example_110-16[Explicitly Deleting] example. + +[#Example 110-16]## *_Explicitly Deleting_* + +`+UnitOfWork uow = session.acquireUnitOfWork();+` +`+pet petClone = (Pet)uow.readObject(Pet.class);+` +`+uow.deleteObject(petClone);+` `+uow.commit();+` + +The preceding code generates the following SQL: + +`+DELETE FROM PET WHERE (ID = 100)+` + +=== What You May Need to Know About the Order in which Objects Are Deleted + +The unit of work does not track changes or the order of operations. It +is intended to insulate you from having to modify your objects in the +order the database requires. + +By default, at commit time, the unit of work correctly puts in order all +insert and update operations using the constraints defined by your +schema. After all insert and update operations are done, the unit of +work will issue the necessary delete operations. + +Constraints are inferred from one-to-one and one-to-many mappings. If +you have no such mappings, you can add additional constraint knowledge +to EclipseLink as described in +link:Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)[Controlling the +Order of Delete Operations]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_Workbench_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_Workbench_(ELUG).adoc new file mode 100644 index 00000000000..0d4c2c933d2 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_Workbench_(ELUG).adoc @@ -0,0 +1,3018 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Using_Workbench_(ELUG)[Related Topics] + +This section provides information about understanding, using, and +customizing the EclipseLink Workbench. + +For information on using Workbench to configure sessions XML, refer to +link:EclipseLink_UserGuide_Using_EclipseLink_Sessions_(ELUG)[EclipseLink +Sessions]. + +== Introduction to the Workbench + +Workbench is a separate component from the EclipseLink runtime – it lets +you graphically configure descriptors and map your project. Workbench +can verify the descriptor options, access the data source (either a +database or an XML schema), and create the database schema. Using +Workbench, you can define EclipseLink descriptors and configurations +_without using code_. + +The Workbench is primarily for developing when using the native +EclipseLink API, MOXy, or EIS. When using JPA, other development tools +such as Eclipse Dali, or Oracle JDeveloper can be used. + +You can use Workbench during the _development_ phase of the +link:Introduction_to_EclipseLink_Application_Development_(ELUG)[development +process]. Typically, this phase includes the following: + +[arabic] +. Defining an object model (a set of Java classes) to describe and solve +your problem. +. Creating a Workbench project, importing your Java classes and data +sources, and using descriptors to describe how the Java classes map to +your data source model. +. Creating an EclipseLink session and registering your descriptors. In +your application, use the session to retrieve and store objects from and +to the data source. + +Workbench creates a __`+.mwp+` file to store all EclipseLink project +information, including object model, descriptor, and session +information. + +The __`+.mwp+` file is used only by Workbench. Typically, the only time +you need to modify the __`+.mwp+` file is to merge changes during +application development by a team of developers +(link:Using%20an%20Integrated%20Development%20Environment%20(ELUG)#How_to_Merge_Files[How +to Merge Files]). + +Using Workbench, you export this information into a `+project.xml+` file +that your EclipseLink enabled application reads at run time. + +For more information on using Workbench as the development environment, +see +link:Introduction%20to%20EclipseLink%20Development%20Tools%20(ELUG)[Introduction +to EclipseLink Development Tools]. + +== Configuring the Workbench Environment + +Workbench reads its environment variables from the `+setenv+` script in +the __`+/bin+` directory. + +Before you launch Workbench, you must configure its environment as +follows: + +[arabic] +. Use a text editor to open the __`+/bin/setenv+` script. +* For Windows, open the `+setenv.cmd+` file. +* For UNIX, open the `+setenv.sh+` file. +. Ensure that the `+JAVA_HOME+` environment variable is set: +* For Windows: `+set JAVA_HOME=C:/j2sdk1.5.0_04+` +* For UNIX: `+JAVA_HOME=/usr/local/packages/java; export JAVA_HOME+` +*Note*: If you have already set JAVA_HOME as a system environment +variable, you can skip this step. +. Update the `+DRIVER_CLASSPATH+` environment variable to add the +location of the following (if necessary): *Note*: Do not include any +Java classes for your persistent business objects in the +`+DRIVER_CLASSPATH+` variable. Instead, add these persistent business +objects in your +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Workbench +project classpath]. +* JDBC drivers – if you are using +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Building_Relational_Projects[building +Relational Projects]. +* Java EE Connector Architecture (JCA) adapters – if you are +link:Introduction%20to%20EIS%20Projects%20(ELUG)#EIS_Project_Concepts[Building +EIS projects]. +* JCA `+connector.jar+` file – if you are using +link:Introduction%20to%20EIS%20Projects%20(ELUG)#EIS_Project_Concepts[EIS +Projects]. The `+connector.jar+` file contains `+javax.resource.cci+` +and `+javax.resource.spi+` interfaces that EclipseLink EIS uses. Edit +the `+workbench.cmd+` or `+workbench.sh+` file in +`+<+`_`+ECLIPSELINK_HOME+`_`+>/utils/workbench/bin+` to change the path +to this file. At run time, this `+connector.jar+` file (or its +equivalent) must be on your application or application server classpath. +* Oracle Database `+ORACLE_HOME/rdbms/jlib/xdb.jar+` file – if you are +using +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mappings] with an Oracle9i or later database. +* Custom `+Collection+` class that you use to override the default +`+Collection+` class that EclipseLink uses with a +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Container_Policy[mapping +container policy]. The following examples shows how to set the +`+DRIVER_CLASSPATH+` variable for Windows system and for UNIX. ++ +*’’Example: Setting DRIVER_CLASSPATH on Windows*’’ +`+set DRIVER_CLASSPATH=C:\OraHome\jdbc\lib\ojdbc14.jar;C:\Attunity\Connect\Java\lib\attunityResourceAdapter.jar;C:\OraHome\rdbms\jlib\xdb.jar+` +*Note*: If the path to your driver(s) contains spaces, you must enclose +the path in double-quotes in the `+setenv.cmd+` file. For example: +`+set DRIVER_CLASSPATH="C:\Program Files\some directory\driver.jar"+` ++ +*_Example: Setting DRIVER_CLASSPATH on UNIX_* +`+DRIVER_CLASSPATH=/OraHome/jdbc/lib/ojdbc14.jar;/attunity/connect/java/lib/attunityResourceAdapter.jar;/OraHome/rdbms/jlib/xdb.jar; export JDBC_CLASSPATH+` +. Save and close the `+setenv+` script. +. Start the Workbench by launching the +__`+\utils\workbench\bin\workbench.cmd+` or `+workbench.sh+` file. + +== Using Workbench + +The following figure shows the primary parts of the Workbench window. + +[#Figure 4-1]## *_Workbench Window_* + +.Workbench Window +image::mw_.gif[Workbench Window,title="Workbench Window"] + +The numbered callouts in the previous figure identify the following user +interface components: + +[arabic] +. Menu bar: The menu bar contains menus for each Workbench function. +Some objects also contain context-sensitive menus. See +link:#How_to_Use_Menus[How to Use Menus] for more information. +. Toolbars: The toolbars contain shortcuts to specific functions. See +link:#How_to_Use_Toolbars[How to Use Toolbars] for more information. +. Navigator window section: The Navigator window section shows the +project navigation tree for all open projects (see +link:#How_to_Use_the_Navigator[How to Use the Navigator]). Click the +plus (*+* ) or minus ( *–*) sign next to an object (or double-click the +object) to expand or collapse the tree. When you select an object in the +*Navigator* window section, its properties appear in the *Editor* +window. +. Editor window section: The *Editor* window section contains specific +property sheets and option tabs for the currently selected object. See +link:#How_to_Use_the_Editor[How to Use the Editor] for more information. +. Problems window section: The *Problems* window section shows messages +and errors for the currently selected object in the Navigator window +section (see link:#How_to_Use_the_Problems_Window[How to Use the +Problems Window]). +link:EclipseLink_Workbench_Error_Reference_(ELUG)[EclipseLink Workbench +Error Reference (ELUG)] contains detailed information on each error +message. + +=== How to Use Menus + +Workbench contains the following two types of menus: + +* Menu bar menus (see link:#Using_Menu_Bar_Menus[Using Menu Bar Menus]) +* Context menus (see link:#Using_Context_Menus[Using Context Menus]) + +==== Using Menu Bar Menus + +The menu bar, located at the top of the Workbench window, provides menus +for each Workbench function. Some menus (such as *Selected*) are +context-sensitive; the available options may vary, depending on the +currently selected object. + +[#Figure 4-2]## *_Sample Menu Bar Menu_* + +.Sample Menu Bar Menu +image::menubar.gif[Sample Menu Bar Menu,title="Sample Menu Bar Menu"] + +==== Using Context Menus + +When you right-click objects in the *Navigator* window, a context menu +appears with functions specific to the selected object. + +[#Figure 4-3]## *_Sample Context Menu_* + +.Sample Context Menu +image::popup.gif[Sample Context Menu,title="Sample Context Menu"] + +=== How to Use Toolbars + +Workbench contains the following toolbars at the top of the window: + +* link:#Using_Standard_Toolbar[Standard Toolbar] +* link:#Using_Context_Toolbar[Context Toolbar] + +Toolbars provide tool tips: each toolbar button provides a brief +description when you position the mouse pointer over it. + +==== Using Standard Toolbar + +The standard toolbar furnishes quick access to the standard menu options +(*File*, *Edit*, *Selected*, and so on). + +[#Table 4-1]## *_Standard Toolbar Buttons_* + +Button + +Description + +Available for… + +New + +All + +Open + +All + +Save + +All + +Save as + +All + +Save all + +All + +Close + +All + +Close all + +All + +Export deployment XML for the selected projects + +Projects + +Refreshes selected classes + +Projects + +Add or refresh classes + +Projects + +Create new class + +Projects + +==== Using Context Toolbar + +The context toolbar provides quick access to functions for the currently +selected object in the *link:#How_to_Use_the_Navigator[Navigator]*. The +available buttons will vary, depending on which item you have selected. + +You can also right-click the item and choose the appropriate option from +the context menu. + +[#Table 4-2]## *_Context Toolbar Buttons_* + +Button + +Description + +Available for… + +Login to database + +Databases + +Logout of database + +Databases + +Add new table + +Databases + +Add or update existing tables from database + +Databases + +Refresh from database + +Database tables + +Remove table or selected item + +Database tables + +Rename table or selected item + +Database tables + +Import schema + +Schemas + +Relational aggregate descriptor + +Descriptors + +Relational class descriptor + +Descriptors + +EIS composite descriptor + +Descriptors + +EIS root descriptor + +Descriptors + +XML descriptor + +Descriptors + +Direct-to-field mapping + +Attributes in relational descriptors + +Direct-to-XMLType mapping + +Attributes in relational descriptors + +Direct collection mapping + +Attributes in relational descriptors + +Direct map mapping + +Attributes in relational descriptors + +Aggregate mapping + +Attributes in relational descriptors + +One-to-one mapping + +Attributes in relational descriptors + +Variable one-to-one mapping + +Attributes in relational descriptors + +One-to-many mapping + +Attributes in relational descriptors + +Many-to-many mapping + +Attributes in relational descriptors + +Direct mapping + +Attributes in EIS descriptors + +Direct collection mapping + +Attributes in EIS descriptors + +Composite object mapping + +Attributes in EIS descriptors + +Composite collection mapping + +Attributes in EIS descriptors + +One-to-one mapping + +Attributes in EIS descriptors + +One-to-many mapping + +Attributes in EIS descriptors + +Direct-to-XML mapping + +Attributes in XML descriptors + +Direct collection mapping + +Attributes in XML descriptors + +Composite object mapping + +Attributes in XML descriptors + +Composite collection mapping + +Attributes in XML descriptors + +Any object mapping + +Attributes in XML descriptors + +Any collection mapping + +Attributes in XML descriptors + +Transformation mapping + +Attributes in all descriptors + +Unmap + +Attributes in all descriptors + +Session + +Sessions configurations + +Session Broker + +Sessions configurations + +Named connection pool + +Server sessions + +Sequence connection pool + +Server sessions + +Write connection pool + +Server sessions + +Rename + +Database sessions, session brokers + +Delete session + +Database sessions, session brokers + +=== How to Use the Navigator + +EclipseLink displays the items included in each project (descriptors, +mappings, data source, and so on) in the *Navigator* on the left side of +the Workbench window, as this figure shows. + +[#Figure 4-4]## *_Sample Navigator_* + +.Sample Navigator +image::city.gif[Sample Navigator,title="Sample Navigator"] + +The numbered callouts on this figure identify the following user +interface components: + +[arabic] +. Project (relational project) +. Package +. EclipseLink Descriptor (relational descriptor) +. Attribute/mapping (direct to field mapping) +. Unsaved/changed item +. Database +. Database table + +Click the plus (*+*) or minus (*–*) sign next to the item, or +double-click the item name to expand or collapse the item. + +Workbench identifies items that have been changed but not yet saved by +adding an asterisk (***) in front of the item name. + +When you select an item in the *Navigator*, its properties appear in the +*Editor* (see link:#How_to_Use_the_Editor[How to Use the Editor]). + +To perform specific functions for an item, select the item in the +*Navigator* and do one of the following: + +* Right-click on the object and select the function from the context +menu (see link:#Using_Context_Menus[Using Context Menus]). +* Choose a function from the *Selected* menu (see +link:#Using_Menu_Bar_Menus[Using Menu Bar Menus]). + +For information on using the Navigator with a database in relational +projects, see +link:#How_to_Use_Database_Tables_in_the_Navigator_Window[How to Use +Database Tables in the Navigator Window]. + +For information on using the Navigator with an XML schema in EIS +projects (using XML records) and XML projects, see +link:#How_to_Use_XML_Schemas_in_the_Navigator[How to Use XML Schemas in +the Navigator]. + +*Active and Inactive Descriptors* + +Inactive descriptors appear dimmed in the *Navigator*. Inactive +descriptors are not registered with the session when the project is +loaded into Java. This feature lets you define and test subsets of +descriptors. To activate or deactivate a descriptor, right-click the +descriptor and select *Activate/Deactivate Descriptor* from the context +menu. + +[#Figure 4-5]## *_Sample Active and Inactive Descriptors_* + +.Sample Active and Inactive Descriptors +image::inactive.gif[Sample Active and Inactive +Descriptors,title="Sample Active and Inactive Descriptors"] + +The numbered callouts show the following user interface components: + +[arabic] +. Inactive descriptor +. Active descriptor + +*Errors and Missing Information* + +image:catnicon.gif[Caution / Warning +icon,title="Caution / Warning icon"] If an element in the project (such +as a descriptor or mapping) contains an error or some deficiency +(sometimes called _neediness_), a warning icon appears beside the +element icon in the *Navigator*, and Workbench displays a message in the +link:#How_to_Use_the_Problems_Window[Problems window]. + +link:EclipseLink_Workbench_Error_Reference_(ELUG)[EclipseLink Workbench +Error Reference (ELUG)] contains more information on each Workbench +error message. + +=== How to Use the Editor + +The *Editor*, on the right side of the Workbench window, displays the +property sheet associated with the currently selected item in the +*Navigator*, as this figure shows. + +[#Figure 4-6]## *_Sample Editor_* + +.Sample Editor +image::edpane.gif[Sample Editor,title="Sample Editor"] + +The numbered callouts identify the following user interface components: + +[arabic] +. Selected element (from the *Navigator*) +. Editor property tabs + +=== How to Use the Problems Window + +image:catnicon.gif[Caution / Warning +icon,title="Caution / Warning icon"] If an element in the project (such +as a descriptor or mapping) contains an error or some deficiency +(sometimes called _neediness_), the Workbench displays a caution icon +(represented by a yellow triangle with a black exclamation point in the +middle) to the left of the deficient element in the *Navigator* (see +link:#How_to_Use_the_Navigator[How to Use the Navigator]) and displays a +message in the Problems window as link:#Figure_4-7[the Sample Deficient +Mapping figure] shows. + +If you select the error, then Workbench displays the complete error +message in the *Problems* window. +link:EclipseLink_Workbench_Error_Reference_(ELUG)[EclipseLink Workbench +Error Reference (ELUG)] contains detailed information on each error +message. + +[#Figure 4-7]## *_Sample Deficient Mapping_* + +.Sample Deficient Mapping +image::desmaper.gif[Sample Deficient +Mapping,title="Sample Deficient Mapping"] + +Double-click any error message in the *Problems* window to automatically +highlight the specific node in the *Navigator*. To display or hide the +*Problems* window, select *Window > Show Problems* from the menu. + +You can also +link:Creating%20a%20Project%20(ELUG)#How_to_Generate_the_Project_Status_Report[create +a status report] that includes all errors in a selected project. + +== Using Workbench Preferences + +To customize Workbench, select *Tools > Preferences* from the menu. The +*Preferences* dialog box appears. + +[#Figure 4-8]## *_Preferences Dialog Box_* + +.Preferences Dialog Box +image::pref_gen.gif[Preferences Dialog +Box,title="Preferences Dialog Box"] + +Workbench provides the following preferences: + +* link:#How_to_Use_General_Preferences[General Preferences] +** link:#How_to_Use_Help_Preferences[Help Preferences] +* link:#How_to_Use_Mappings_Preferences[Mappings Preferences] +** link:#How_to_Use_Class_Preferences[Class Preferences] +** link:#How_to_Use_Database_Preferences[Database Preferences] +* link:#How_to_Use_Sessions_Configuration_Preferences[Sessions +Configuration Preferences] +** link:#How_to_Use_New_Names_Preferences[New Names Preferences] +** link:#How_to_Use_Session_Platform_Preferences[Session Platform +Preferences] +* link:#How_to_Use_Platforms_Preferences[Platforms Preferences] + +Use this dialog box to configure Workbench preferences. After changing +preferences, you must restart Workbench. + +To import your preferences from an existing file, click *Import* and +select the file. + +To export your preferences, click *Export* and select a directory +location and filename. + +=== How to Use General Preferences + +Use the General preferences to customize the look and feel (the +graphical user interface) of Workbench as well as to specify any proxy +information required to access the Internet (for example, to allow +EclipseLink to access XML schemas hosted on Internet sites). Follow +these steps to customize the General preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Select *General* in the *Category* window. +[#Figure 4-9]##*_Preferences – General Dialog Box_* +image:pref_gen.gif[Preferences – General Dialog +Box,title="Preferences – General Dialog Box"] +. Complete each field on the *Preferences – General* dialog box and +click *OK*. + +Use the following information to enter data in each field of the dialog +box: + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Field* |*Description* +|*Display Splash Screen* |Specify if Workbench should show the graphical +splash screen when starting. + +|*Look and Feel* |Select the look and feel to use for Workbench. + +|*Size of recently opened files list* |Select the number of projects to +maintain in the *File* > *Reopen* option. See +link:Creating%20a%20Project%20(ELUG)#How_to_Open_Existing_Projects[How +to Open Existing Projects] for more information. + +|*HTTP Proxy Host* |Specify if your PC requires a proxy server to access +the internet. + +|*HTTP Proxy Port* |Specify the port used by your proxy host. + +|*Network Connect Timeout* |Specify the timeout (in seconds) to +establish a network or internet connection. + +|*Network Read Timeout* |Specify the timeout (in seconds) when accessing +data from a network or internet connection. + +|*Reopen Projects on Startup* |Select to reopen the projects that were +open the last time you exited the Workbench. +|=== + +You must restart Workbench to apply the changes. + +=== How to Use Help Preferences + +The EclipseLink Workbench online help is web-based. Use the Help +preferences to define the location of your web browser. + +Follow these steps to customize the Help preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Select *General > Help* in the *Category* window. The *Help* dialog +box appears. *_Preferences – Help Dialog Box_* +image:pref_help.gif[Preferences – Help Dialog +Box,title="Preferences – Help Dialog Box"] +. Click *Browse* and select your HTML web browser. +. Click *OK*. + +*Note*: If your location requires a proxy to browse external web pages, +be sure to complete the *Proxy* fields on the +link:#How_to_Use_General_Preferences[General Preferences] page. + +=== How to Use Mappings Preferences + +Use the Mappings preferences to specify general mapping preferences. +Follow these steps to set the Mapping preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Select *Mappings* in the *Category* window. The *Mappings* dialog box +appears. *_Preferences – Mappings Dialog Box_* +image:pref_map.gif[Preferences – Mappings Dialog +Box,title="Preferences – Mappings Dialog Box"] +. Complete each field on the *Preferences - Mappings* dialog box and +click *OK*. + +Use the following information to enter data in each field: + +[width="100%",cols="<17%,<83%",options="header",] +|=== +|*Field* |*Description* +|*Allow changing query type* |Configure whether or not Workbench always +allows, never allows, or prompts before allowing you to change the query +type associated with a descriptor. + +|*Allow changing query format* |Configure whether or not Workbench +always allows, never allows, or prompts before allowing you to change +the configuration of a query associated with a descriptor. +|=== + +=== How to Use Class Preferences + +Use the Class preferences to specify how Workbench maintains classes +when renaming or editing a zero-argument constructor. Follow these steps +to set the Class preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Expand *Mappings* in the *Category* window and select *Class*. +[#Figure 4-11]##*_Preferences – Mappings – Class Dialog Box_* +image:pref_map_class.gif[Preferences – Mappings – Class Dialog +Box,title="Preferences – Mappings – Class Dialog Box"] +. On the *Preferences* – *Mappings* – *Class* dialog box, specify how +Workbench maintains classes when renaming or editing a zero-argument +constructor. + +=== How to Use Database Preferences + +Use the Database preferences to specify custom database divers and +connection URLs for Workbench. These drivers and URLs can then be used +when defining database logins. Follow these steps to set the Database +preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Expand *Mappings* in the *Category* window and select *Database*. +[#Figure 4-12]##*_Preferences – Mappings – Database Preferences Dialog +Box_* image:pref_map_db.gif[Preferences – Mappings – Database +Preferences Dialog +Box,title="Preferences – Mappings – Database Preferences Dialog Box"] +. Enter data in each field on the *Preferences – Mappings – Database* +dialog box and click *OK*. + +Use the following information to enter data in each field: + +[cols="<,<",options="header",] +|=== +|*Field* |*Description* +|*Database Driver* |Enter the custom database driver class name. +|*Connection URL* |Enter the custom database connection URL. +|=== + +=== How to Use Sessions Configuration Preferences + +Use the Sessions preferences to specify default classpaths to be added +to each newly created EclipseLink sessions configuration for features +that require an external Java class (for example, session event +listeners). The entries added here will automatically appear on the +link:Creating%20a%20Session%20(ELUG)#Configuring_a_Sessions_Configuration[Sessions +Configuration property sheet]. Follow these steps to set the Sessions +Configuration preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Select *Sessions Configuration* in the *Category* window. +[#Figure 4-13]##*_Preferences – Sessions Configuration Dialog Box_* +image:pref_ses.gif[Preferences – Sessions Configuration Dialog +Box,title="Preferences – Sessions Configuration Dialog Box"] + +To add a JAR or ZIP file, click *Add Entry* or *Browse* and add the JAR +or ZIP files that contain the default compiled Java classes for this +sessions configuration. + +To remove a JAR or ZIP file, select the file and click *Remove*. + +To change the order in which EclipseLink searches these JAR or ZIP +files, select a file and click *Up* to move it up, or click *Down* to +move it down in the list. + +=== How to Use New Names Preferences + +Use the New Names preferences to specify the default values and names of +newly created sessions, session brokers, and connection pools. Follow +these steps to set the New Names preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Expand *Sessions Configuration* in the *Category* window and select +*New Names*. [#Figure 4-14]##*_Preferences – Sessions Configuration – +New Names Dialog Box_* image:pref_ses_new.gif[Preferences – Sessions +Configuration – New Names Dialog +Box,title="Preferences – Sessions Configuration – New Names Dialog Box"] +. Complete each field on the *Preferences – Sessions Configuration – New +Names dialog box* and click *OK*. + +Use the following information to enter data in each field: + +[width="100%",cols="<10%,<90%",options="header",] +|=== +|*Field* |*Description* +|*Sessions Configuration* |Specify the default name for newly created +sessions configuration files (default, `+sessions.xml+`). See +link:Creating%20a%20Session%20(ELUG)#Creating_a_Sessions_Configuration[Creating +a Sessions Configuration] for more information. + +|*Session* |Specify the default name for newly created sessions +(default, `+Session+`). See +link:Creating%20a%20Session%20(ELUG)#Introduction_to_the_Session_Creation[Introduction +to the Session Creation] for more information. + +|*Broker* |Specify the default name for newly created session brokers +(default, `+SessionBroker+`). See +link:Creating%20a%20Session%20(ELUG)#Creating_Session_Broker_and_Client_Sessions[Creating +Session Broker and Client Sessions] for more information. + +|*Connection Pool* |Specify the default name for newly created +connection pools (default, `+ConnectionPool+`). See +link:Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Creating_an_Internal_Connection_Pool[Creating +an Internal Connection Pool] for more information. +|=== + +=== How to Use Session Platform Preferences + +Use the Platform preferences to specify the default data source type for +newly created sessions. The type selected here will automatically appear +on the Create New Session dialog box. Follow these steps to set the +Platform preferences: + +[arabic] +. Select *Tools > Preferences* from the menu. The *Preferences* dialog +box appears. +. Expand *Sessions Configuration* in the *Category* window and select +*Platform*. [#Figure 4-15]##*_Preferences – Sessions Configuration – +Platform Preferences Dialog Box_* image:pref_ses_plat.gif[Preferences – +Sessions Configuration – Platform Preferences Dialog +Box,title="Preferences – Sessions Configuration – Platform Preferences Dialog Box"] +. Complete each field on the *Preferences – Sessions Configuration – +Platform dialog box* and click *OK*. + +Use the following information to enter data in each field: + +[width="100%",cols="<11%,<89%",options="header",] +|=== +|*Field* |*Description* +|*Use Server Platform* |Specify the default application server platform +for newly created sessions configuration files (default, +`+sessions.xml+`). See +link:Creating%20a%20Session%20(ELUG)#Creating_a_Sessions_Configuration[Creating +a Sessions Configuration] for more information. + +|*Default Data Source Type* |Select the default data source type +(*Database*, *EIS*, or *XML*) and platform for newly created sessions. +See +link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform] for more information. +|=== + +== Using Databases + +In relational projects, when you expand the database object in the +*Navigator*, Workbench displays the database tables associated with the +project. You can associate tables by importing them from the database, +or by creating them within Workbench. + +[#Figure 4-17]## *_Sample Database Tables_* + +.Sample Database Tables +image::dbtable.gif[Sample Database +Tables,title="Sample Database Tables"] + +The following numbered callouts identify the following database icons. + +[arabic] +. Project +. Database +. Database table + +Each database table property sheet contains the following tabs in the +*Editor*: + +* *Columns* – Add or modify the table’s fields, and specify each field’s +properties. +* *References* – Specify references between tables. + +This section includes information on the following topics: + +* link:#How_to_Use_Database_Tables_in_the_Navigator_Window[How to Use +Database Tables in the Navigator Window] +* link:#How_to_Use_Database_Tables_in_the_Editor_Window[How to Use +Database Tables in the Editor Window] +* link:#How_to_Generate_Data_from_Database_Tables[How to Generate Data +from Database Tables] + +=== How to Use Database Tables in the Navigator Window + +This section describes the following options: + +* link:#Logging_In_and_Out_of_a_Database[Logging In and Out of a +Database] +* link:#Creating_New_Tables[Creating New Tables] +* link:#Importing_Tables_from_a_Database[Importing Tables from a +Database] +* link:#Removing_Tables[Removing Tables] +* link:#Renaming_Tables[Renaming Tables] +* link:#Refreshing_Tables_from_the_Database[Refreshing Tables from the +Database] + +See link:#How_to_Use_Database_Tables_in_the_Editor_Window[How to Use +Database Tables in the Editor Window] for more information. + +==== Logging In and Out of a Database + +To log in or out of a relational database, do the following: + +[arabic] +. Create a database login (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Introduction_to_Database_Login_Configuration[Introduction +to Database Login Configuration]). +. To log in to a relational database, right-click the database object in +the *Navigator*, and choose *Log In to Database* from the context menu +or choose *Selected* > *Log In to Database* from the menu. +. To log out of a relational database, right-click the database object +in the *Navigator* and choose *Log Out of Database* from the context +menu or choose *Selected* > *Log Out of Database* from the menu. + +==== Creating New Tables + +To create a new database table within Workbench, use the following +procedure: + +[arabic] +. Select the database object in the *Navigator* window and click *Add +New Table* image:addtable.gif[Add a New Table +button,title="Add a New Table button"]. The *New Table* dialog box +appears. You can also right-click the database object and choose *Add +New Table* from the context menu, or choose *Selected* > *Add New Table* +from the menu. [#Figure4-18]##*_New Table Dialog Box_* +image:newtble.gif[New Table Dialog Box,title="New Table Dialog Box"] +. Complete each field on the *New Table* dialog box and click *OK*. + +Use the following information to enter data in each field: + +[width="100%",cols="<12%,<88%",options="header",] +|=== +|*Field* |*Description* +|*Catalog* |Use to identify specific database information for the table. +Consult your database administrator for more information. + +|*Schema* |Use to identify specific database information for the table. +Consult your database administrator for more information. + +|*Table Name* |Specify the name of this database table. +|=== + +Workbench adds the database table to the project. + +Although the database table has been added to the project, it has not +been written to the actual database. See +link:#Generating_Tables_on_the_Database[Generating Tables on the +Database] for more information on creating the table in the database. + +Continue with link:#How_to_Use_Database_Tables_in_the_Editor_Window[How +to Use Database Tables in the Editor Window] to use these tables in your +project. + +==== Importing Tables from a Database + +Workbench can automatically read the schema for a relational database +and import the table data into the project as long as your JDBC driver +supports the following JDBC methods: + +* `+getTables+` +* `+getTableTypes+` +* `+getImportedKeys+` +* `+getCatalogs+` +* `+getPrimaryKeys+` + +The JDBC driver must be on the Workbench classpath (see +link:#Configuring_the_Workbench_Environment[Configuring the Workbench +Environment]). + +To import tables from the database, use the following procedure: + +[arabic] +. Select the database object in the *Navigator,* and click *Add or +Update Existing Tables from Database* image:addtbldb.gif[Add/Update +Existing Tables from +Database,title="Add/Update Existing Tables from Database"]. The *Import +Tables from Database* dialog box appears. You can also right-click on +the database object in the *Navigator* and choose *Add or Update +Existing Tables from Database* from the context menu or choose +*Selected* > *Add/Update Existing Tables from Database* from the menu. +[#Figure 4-19]##*_Import Tables from Database Dialog Box_* +image:importdb.gif[Import Tables from Database Dialog +Box,title="Import Tables from Database Dialog Box"] ++ +The following numbered callouts identify the following user interface +components: +[arabic] +.. Filters +.. Database tables that match the filters +. Complete each field on the *Import Tables from Database* dialog box +and click *OK*. + +Use the following information to enter data in each field of the dialog +box: + +[width="100%",cols="<13%,<87%",options="header",] +|=== +|*Field* |*Description* +|*Table Name Pattern* |Specify the name of database table(s) to import. +Use percent character (*%*) as a wildcard. Tables that match the *Table +Name Pattern* can be imported. + +|*Catalog* |Specify the catalog of database table(s) to import. + +|*Schema Pattern* |Specify the schema of database table(s) to import. + +|*Table Type* |Specify the type of database table(s) to import. + +|*Available Tables* |Click *Get Table Names* to make EclipseLink display +tables that match *Table Name Pattern*, *Catalog*, *Schema Pattern*, and +*Table Type* settings. + +|*Selected Tables* |Select the tables in the *Available Tables* area to +import, and click the right-arrow button. EclipseLink adds the table to +the *Selected Tables* field. Click *OK* to import the tables from the +database into the Workbench project. + +|*Import Fully Qualified Names* |Specify whether or not the tables’ +names are fully qualified against the schema and catalog. +|=== + +Examine each table’s properties to verify that the imported tables +contain the correct information. See +link:#How_to_Use_Database_Tables_in_the_Editor_Window[How to Use +Database Tables in the Editor Window] for more information. + +==== Removing Tables + +To remove a database table from the project, use the following +procedure: + +[arabic] +. Select a database table in the *Navigator,* and click *Remove Selected +Item* image:remtable.gif[Remove Table +button,title="Remove Table button"] on the toolbar. Workbench prompts +for confirmation. You can also right-click on the database object and +choose *Remove* from the context menu or choose *Selected* > *Remove* +from the menu. +. Click *OK*. Workbench removes the table from the project. + +[width="100%",cols="<100%",] +|=== +|*Note*: Although you have removed the table from the Workbench project, +the table remains in the database. +|=== + +==== Renaming Tables + +To rename a database table in the Workbench project, use the following +procedure: + +[arabic] +. Select a database table in the *Navigator,* and click *Rename* on the +toolbar. The Rename dialog box appears. You can also right-click on the +table and choose *Rename* from the context menu or choose *Selected* > +*Rename* from the menu. +. Enter a new name and click *OK*. Workbench renames the table. + +[width="100%",cols="<100%",] +|=== +|*Note*: Although you have renamed the table in the Workbench project, +the original table name remains in the database. +|=== + +==== Refreshing Tables from the Database + +To refresh (that is, reload) the database tables in the Workbench +project, use the following procedure: + +[arabic] +. Select the database table in the *Navigator,* and click *Refresh from +Database* on the toolbar. You can also right-click on the database table +and choose *Refresh from Database* from the context menu or choose +*Selected* > *Refresh from Database* from the menu. Workbench reloads +the database table. +. When refreshing tables from the database, if there are multiple +database tables with similar names, the *Duplicate Tables* dialog box +appears. [#Figure 4-20]## *_Duplicate Table Dialog Box_* +image:duptable.gif[Duplicate Table Dialog +Box,title="Duplicate Table Dialog Box"] +. Select the specific database table to update, and then click *OK*. + +=== How to Use Database Tables in the Editor Window + +When you select a database table in the *Navigator*, its properties +appear in the *Editor*. Each database table contains the following +property tabs: + +* *Columns* – Add or modify the table fields, and specify each field +properties. +* *References* – Specify references between tables. + +This section describes how to use these tabs to configure the following: + +* link:#Working_with_Column_Properties[Working with Column Properties] +* link:#Setting_a_Primary_Key_for_Database_Tables[Setting a Primary Key +for Database Tables] +* link:#Creating_Table_References[Creating Table References] +* link:#Creating_Field_Associations[Creating Field Associations] + +==== Working with Column Properties + +Use the database table’s *Column* tab to specify properties for the +database table’s fields. + +To specify a table’s column properties, use this procedure: + +[arabic] +. Select a database table in the *Navigator*. The table’s property sheet +displays in the *Editor*. +. Click the Columns tab. [#Figure 4-21]##*_Fields Properties_* +image:fields.gif[Fields Properties,title="Fields Properties"] +. Enter data in each field on the Columns tab. Use the scroll bar to +display the additional field. + +Use the following information to fill each column on the Columns tab: + +[width="100%",cols="<9%,<91%",options="header",] +|=== +|*Field* |*Description* +|*Name* |Specify the name of the field. + +|*Type* |Use the drop-down list to select the field’s type. Note: The +valid values will vary, depending on the database. + +|*Size* |Specify the size of the field. + +|*Sub-Size* |Specify the sub-size of the field. + +|*Allows Null* |Specify if this field can be null. + +|*Unique* |Specify whether the value must be unique within the table. + +|*Primary Key* |Specify whether or not this field is a primary key for +the table (see link:#Setting_a_Primary_Key_for_Database_Tables[Setting a +Primary Key for Database Tables]). + +|*Identity* |Use to indicate a Sybase, SQL Server or Informix identity +field. +|=== + +[width="100%",cols="<100%",] +|=== +|*Note*: Some properties may be unavailable, depending on your database +type. +|=== + +To add a new field, click *Add*. + +To remove a field, select the field and click *Remove*. + +To rename a field, select the field and click *Rename*. + +==== Setting a Primary Key for Database Tables + +To set a primary key(s) for a database table, use this procedure: + +[width="100%",cols="<100%",] +|=== +|*Note*: Workbench can automatically import primary key information if +supported by the JDBC driver. +|=== + +[arabic] +. Select a database table in the *Navigator*. Its property sheet appears +in the *Editor*. +. Click the *Columns* tab.Click the *Columns* tab. *_Setting Primary Key +for a Database Table [#Figure 4-22]##_* image:fieldspk.gif[Setting +Primary Key for a Database +Table,title="Setting Primary Key for a Database Table"] +. Select the *Primary Key* field(s) for the table. + +==== Creating Table References + +References are table properties that contain the foreign key; they may +or may not correspond to an actual constraint that exists on the +database. Workbench uses these references when you define relationship +mappings and multiple table associations. + +When importing tables from the database, Workbench can automatically +create references (if the driver supports this), or you can define +references from the workbench. See +link:#Importing_Tables_from_a_Database[Importing Tables from a +Database]. + +To create a new table reference, use this procedure: + +[arabic] +. Select a database table in the *Navigator*. The table’s properties +display in the *Editor*. +. Click the *References* tab. [#Figure 4-23]##*_References Tab_* +image:reftab.gif[Description of Figure 4-23 +follows,title="Description of Figure 4-23 follows"] The following +numbered callouts identify the following user interface components: +[arabic] +.. Table References area +.. Key Pairs area +. In the *References* area, click *Add*. The *New Reference* dialog box +appears. [#Figure 4-24]##*_New Reference Dialog Box_* +image:newref.gif[New Reference Dialog +Box,title="New Reference Dialog Box"] +. Complete each field on the new Reference dialog box and click *OK.* + +Use the following information to enter data in each field of the dialog +box: + +[width="100%",cols="<18%,<82%",options="header",] +|=== +|*Field* |*Description* +|*Enter Name of New Reference* |Specify the name of the reference table. +If you leave this field blank, Workbench automatically creates a name +based on the format: SOURCETABLE_TARGETTABLE. + +|*Select the Source Table* |Specify the name of the source database +table (the currently selected table in the Navigator). + +|*Select the Target Table* |Use the list to specify the target table for +this reference. + +|*On Database* |Specify if you want to create the reference on the +database when you create the table. Not all database drivers support +this option. +|=== + +Continue with link:#Creating_Field_Associations[Creating Field +Associations]. + +==== Creating Field Associations + +For each table reference, you can specify one or more field associations +that define how fields in the source table relate to fields in the +target table. See link:#Creating_Table_References[Creating Table +References]. + +To create new field references, use this procedure: + +[arabic] +. Select a database table in the Navigator. The table’s properties +display in the *Editor*. +. Click the *References* tab. [#Figure 4-25]##*_References Tab_* +image:reftab.gif[References Tab,title="References Tab"] ++ +The following numbered callouts identify the following user interface +components: +[arabic] +.. Table references area +.. Key pairs area +. Select a table reference from the references area. +. To create a new key pair, click *Add* in the key pairs area and +complete each field in the key pairs area using the following +information: + +Field + +Description + +Table References Area + +Name + +Specify the name of this table reference + +Target Table + +Specify the database table that is the target of this reference. + +On Database + +Specify if the reference exists on the database. + +Key Pairs Area + +Source Column + +Select the database field from the source table. + +Target Column + +Select the database field from the target table. + +=== How to Generate Data from Database Tables + +Workbench can automatically generate a variety of information from the +database tables. This section describes the following: + +* link:#Generating_SQL_Creation_Scripts[Generating SQL Creation Scripts] +* link:#Generating_Classes_and_Descriptors_from_Database_Tables[Generating +Classes and Descriptors from Database Tables] +* link:#Generating_Tables_on_the_Database[Generating Tables on the +Database] + +==== Generating SQL Creation Scripts + +Using the Workbench, you can generate SQL scripts that you can use to +create tables in a relational database. + +To automatically generate SQL scripts to create the tables in a project, +use this procedure: + +[arabic] +. Select the database table(s) in the *Navigator*. +. Right-click the table(s) and choose *Generate Creation Script for* > +*Selected Tables* or *All Tables* from the context menu. The SQL +Creation Script dialog box appears. You can also choose *Selected* > +*Generate Creation Script for* > *Selected Tables* or *All Tables* from +the menu. [#Figure 4-26]##*_SQL Creation Script Dialog Box_* +image:sqlscrip.gif[Creation Script Dialog +Box,title="Creation Script Dialog Box"] + +Copy the script and paste it into a file. You may need to edit the file +to include additional SQL information that Workbench could not generate. +If the database table or column name is an SQL reserved word, you must +edit the SQL script and enclose the database table or column in quotes. + +[width="100%",cols="<100%",] +|=== +|*Note*: If EclipseLink cannot determine how a particular table feature +should be implemented in SQL, it generates a descriptive message in the +script. +|=== + +==== Generating Classes and Descriptors from Database Tables + +Workbench can automatically generate Java class definitions, descriptor +definitions, and associated mappings from the information in database +tables. You can later edit the generated information if necessary. + +For each table, Workbench does the following: + +* Creates a class definition and a descriptor definition. +* Adds attributes to the class for each column in the table. +* Automatically generates access methods, if specified. +* Creates direct-to-field mappings for all direct (nonforeign key) +fields in the table. +* Creates relationship mappings (one-to-one and one-to-many) if there is +sufficient foreign key information. You may be required to determine the +exact mapping type. + +[width="100%",cols="<100%",] +|=== +|*Note*: Class and attribute names are generated based on the table and +column names. You can edit the class properties to change their names. +|=== + +*To generate classes and descriptors from database tables, use the +following procedure:* + +[arabic] +. Select the database table(s) in the *Navigator*. +. Right-click the table(s) and choose *Generate Classes and Descriptors +from* > *Selected Tables* or *All Tables* from the context menu. +Workbench prompts you to save your project. You can also choose +*Selected* > *Generate Classes and Descriptors from* > *Selected Tables* +or *All Tables* from the menu. +. Click *Yes*. The Generate Classes and Descriptors dialog box appears. +*’’Generate Classes and Descriptors Dialog Box*’’ +image:generateclasses.gif[Generate Classes and Descriptors Dialog +Box,title="Generate Classes and Descriptors Dialog Box"] ++ +Complete each field on the Generate Classes and Descriptors dialog box +and click *OK*. Use the following information to enter data in each +field: | *Field* | *Description* | +|:——————————-|:————————————————————————————————–| | *Package Name* | +Specify the name of package to generate. The package name must comply +with Java naming standards. | | *Generate Accessing Methods* | Specify +if Workbench generates accessing methods for each class and descriptor. +| +. If the table contains foreign key fields that may represent +relationship mappings, then the Choose Relationships to Generate dialog +box appears. [#Figure 4-28]## *_Choose Relationships to Generate Dialog +Box_* image:choose.gif[Choose Relationships to Generate Dialog +Box,title="Choose Relationships to Generate Dialog Box"] +. Select an entry from *Potential Relationships* and click the *1:1 +Mapping* image:onetoone_map_btn.gif[One to One mapping +button,title="One to One mapping button"] or *1:M Mapping* +image:onetomany_map_btn.gif[One to Many mapping +button,title="One to Many mapping button"] button, located between the +Potential Relationships and Selected Relationships windows. See +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#CHDCBEDB[Introduction +to Relational Mappings] for more information on mappings. You can also +specify whether the relationships are bidirectional. See +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_Bidirectional_Relationship[Configuring +Bidirectional Relationship] for more information. +. Click *OK* to automatically create the relationships. + +The newly created descriptors appear in the *Navigator* of Workbench. + +==== Generating Tables on the Database + +To create a table in the database, based on the information in +Workbench, use this procedure: + +[width="100%",cols="<100%",] +|=== +|*Note*: You must log in the database before creating tables. See +link:Configuring%20a%20Relational%20Project%20(ELUG)#Logging_In_to_the_Database[Logging +In to the Database] for more information. +|=== + +[arabic] +. Select the database table(s) in the *Navigator*. +. Right-click the table(s) and choose *Create on Database* > *Selected +Tables* or *All Tables* from the context menu. You can also create +tables by selecting *Selected* > *Create on Database* > *Selected +Tables* or *All Tables* from the menu. + +Workbench creates the tables on the database. + +Alternatively, you can generate tables at run time by exporting the +information in Workbench to a `+TableCreator+` class (see +link:Using%20the%20Schema%20Manager%20(ELUG)#Introduction_to_the_Schema_Manager[Introduction +to the Schema Manager]). + +== Using XML Schemas + +For XML and EIS projects, Workbench maps each EclipseLink descriptor to +your XML schema. + +This section includes information on the following topics: + +* link:#How_to_Use_XML_Schemas_in_the_Navigator[How to Use XML Schemas +in the Navigator] +* link:#How_to_Use_an_XML_Schema_Structure[How to Use an XML Schema +Structure] +* link:#How_to_Import_an_XML_Schema[How to Import an XML Schema] +* link:#How_to_Configure_an_XML_Schema_Reference[How to Configure an XML +Schema Reference] +* link:#How_to_Configure_XML_Schema_Namespace[How to Configure XML +Schema Namespace] + +=== How to Use XML Schemas in the Navigator + +After you import one or more XML schemas into your project (see +link:#How_to_Import_an_XML_Schema[How to Import an XML Schema]) and you +expand the schema object in the *Navigator*, Workbench displays the +schemas associated with the project. + +[#Figure 4-29]## *_Sample XML Schemas_* + +.Sample XML Schemas +image::navschem.gif[Sample XML Schemas,title="Sample XML Schemas"] + +The following numbered callouts identify the following schema icons: + +[arabic] +. Project +. Schemas object +. Specific schema + +For more information, see the following: + +* link:#How_to_Use_an_XML_Schema_Structure[How to Use an XML Schema +Structure] +* link:#How_to_Configure_an_XML_Schema_Reference[How to Configure an XML +Schema Reference] +* link:#How_to_Configure_XML_Schema_Namespace[How to Configure XML +Schema Namespace] + +=== How to Use an XML Schema Structure + +When you select a specific XML schema in the *Navigator*, you can +display the structure and details of the schema using the Schema +Structure tab. + +To display the structure and details of a schema, use this procedure: + +[arabic] +. Select a schema element in the *Navigator*. Its properties appear in +the *Editor*. +. Click the *Schema Structure* tab. The Schema Structure tab appears. +. Select an element in the schema. The element’s details appear. +[#Figure 4-30]##*_Schema Structure Tab_* image:schstruc.gif[Schema +Structure Tab,title="Schema Structure Tab"] +. Review the fields on the *Schema Structure* tab. + +Use the following information to verify data in each field in the Schema +Document Info tab: + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Field* |*Description* +|*Schema Structure* |Displays the elements of the schema, listed in +alphabetical order, in an expandable or collapsible tree structure. + +|*Details* |Displays detailed information (such as name and type) for +the currently selected element in the *Schema Structure* area. +|=== + +These fields are for display only and cannot be changed in Workbench. + +=== How to Import an XML Schema + +The first step in configuring an EIS project (using XML records) or XML +project is importing the XML schema(s) that your project uses. + +When you import a schema, you define a schema reference that gives +EclipseLink the information it needs to locate the schema itself. +Anytime after you import an XML schema, you can update the schema +reference (see link:#How_to_Configure_an_XML_Schema_Reference[How to +Configure an XML Schema Reference]) if necessary. + +After importing an XML schema, you can configure XML schema namespaces +(see link:#How_to_Configure_XML_Schema_Namespace[How to Configure XML +Schema Namespace]). + +To import an XML schema into an EIS project (using XML records) or an +EIS project, use this procedure: + +[arabic] +. Right-click the schemas element in the *Navigator* and select *Import +Schema* from the context menu. The Import Schema dialog box appears.*_ +[#Figure 4-31]## Import Schema Dialog Box_* image:schema.gif[Import +Schema Dialog Box,title="Import Schema Dialog Box"] +. Fill the Import Schema dialog box with data, and then click *OK*. +Workbench will add the schema to the project. + +Use the following information to enter data in each field in the Import +Schema dialog box: + +Field + +Description + +Name + +Specify the name of this schema. This is the display name that Workbench +uses. It can be different than the name you specify when you configure +Source. + +Source + +Select how Workbench should import the schema. + +File + +Specify that Workbench should import the schema from a file. Enter the +fully qualified directory path and filename of the schema file. + +URL + +Specify that Workbench should import the schema using a URL. Enter the +complete URL of the schema file. + +Note: When importing schemas by URL, ensure you have set your proxy +information correctly. + +See How to Use General Preferences for more information. + +Classpath + +Specify that Workbench should import the schema from the project +classpath. + +Resource Name + +Enter the fully qualified name of the XML schema file including the name +of the package of which it is a part. For example, if your XML schema +mySchema.xsd is in C: and you add this directory to your project +classpath (see Project Support for Project Classpath), specify a +resource name of project.config.mySchema.xsd. + +To reimport _a specific schema_, right-click on the specific schema in +the *Navigator* and select *Reimport Schema* from the context menu. + +To reimport _all schemas in a project_, right-click on *Schemas* in the +*Navigator* and select *Reimport All Schemas* from the context menu. + +To change a schema’s source, right-click on the specific schema in the +Navigator window and select *Properties* from the context menu. The +Schema Properties dialog appears. + +=== How to Configure an XML Schema Reference + +After you import an XML schema (see +link:#How_to_Import_an_XML_Schema[How to Import an XML Schema]), you can +update its source by configuring the schema reference. + +==== How to Configure an XML Schema Reference Using Workbench + +To specify the source of a schema, use this procedure: + +[arabic] +. Select a schema element in the *Navigator*. Its properties appear in +the *Editor*. +. Click the *Schema Document Info* tab. The Schema Document Info tab +appears. [#Figure 4-32]##*_Schema Document Info Tab – Source Field_* +image:schsrc.gif[Schema Document Info Tab – Source +Field,title="Schema Document Info Tab – Source Field"] +. Click *Edit* to select a new source for the selected schema. The +Schema Properties dialog box appears. [#Figure 4-33]##*_Schema +Properties Dialog Box_* image:schemapr.gif[Schema Properties Dialog +Box,title="Schema Properties Dialog Box"] + +Complete the *Schema Properties* dialog box and click *OK*. Workbench +adds the schema to the project. + +Use the following information to complete each field in the Schema +Properties dialog box: + +Field + +Description + +Name + +Specify the name of this schema. This is the display name that Workbench +uses. It can be different than the name you specify when you configure +Source. + +Source + +Select how Workbench should import the schema. + +File + +Specify that Workbench should import the schema from a file. Enter the +fully qualified directory path and filename of the schema file. + +URL + +Specify that Workbench should import the schema using a URL. + +Enter the complete URL of the schema file. + +Note: When importing schemas by URL, ensure you have set your proxy +information correctly. See How to Use General Preferences for more +information. + +Classpath + +Specify that Workbench should import the schema from the project +classpath. + +Resource Name + +Enter the fully qualified name of the XML schema file including the name +of the package of which it is a part. For example, if your XML schema +mySchema.xsd is in C: and you add this directory to your project +classpath (see Configuring Project Classpath, specify a resource name of +project.config.mySchema.xsd. + +==== How to Configure an XML Schema Reference Using Java + +Use Java to configure schema reference. Create a descriptor amendment +method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]) that instantiates the appropriate type of +`+XMLSchemaReference+` (`+XMLSchemaClassPathReference+`, +`+XMLSchemaFileReference+`, or `+XMLSchemaURLReference+`) and configures +the descriptor with it, as follows: + +* If you are using `+EISDescriptors+`, the EclipseLink runtime does not +use the schema reference; no further configuration is required. +* If you are using `+XMLDescriptors+`, configure the descriptor with the +`+XMLSchemaReference+` using `+XMLDescriptor+` method +`+setSchemaReference+`. + +=== How to Configure XML Schema Namespace + +As defined in +http://www.w3.org/TR/REC-xml-names/[`+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. + +When you import an XML schema (see link:#How_to_Import_an_XML_Schema[How +to Import an XML Schema]) such as the one that the link:#Example_4-3[XML +Schema with Namespace Options example] shows, Workbench organizes the +various namespaces that the XML schema identifies, as +link:#Table_4-3[the Workbench XML Schema Categories table] shows. + +[#Example 4-3]## *_XML Schema with Namespace Options_* + +`++` +`+    targetNamespace="+``+"            +` + +`+    elementFormDefault="qualified"+` +`+    attributeFormDefault="unqualified"+` `+    version="10.1.3">+` +`+    +` +`+        namespace="+`http://xmlns.oracle.com/ias/xsds/opm[`+http://xmlns.oracle.com/ias/xsds/opm+`]`+"+` +`+        schemaLocation="object-persistence_1_0.xsd"+` `+    />+` +`+...+` + +[#Table 4-3]## *_Workbench XML Schema Categories_* + +[width="100%",cols="<6%,<6%,<38%,<50%",options="header",] +|=== +|*Workbench Category* |*Defined By* |*Purpose* |*When Needed* +|Built-in |`+xmlns:+``+="+``+"+` |Provides access to types defined in +other XML schemas for use as is. |If your project uses more than one XML +schema or if you want to use `+xsi+` or `+xsd+` types. + +|Target |`+targetNamespace="+``+"+` |The namespace you use to qualify +the types you define for your application. If set, all XML documents +that use these types must use this namespace qualifier. |You may need to +specify a target namespace depending on how element and attribute form +options are set (see +link:Introduction%20to%20Projects_(ELUG)#Element_and_Attribute_Form_Options[Element +and Attribute Form Options]). + +|Imported |`+xsd:import+` |Provides access to types defined in the +corresponding built-in XML schema so that you can extend the built-in +types. Extended types must be qualified by the target namespace. |If +your project uses more than one XML schema and you want to extend one or +more built-in types. +|=== + +For more information, see +link:Introduction%20to%20Projects_(ELUG)#XML_Namespaces_Overview[XML +Namespaces Overview]. + +==== How to Configure XML Schema Namespace Using Workbench + +To specify the namespaces of a schema, use this procedure: + +[arabic] +. Select a schema element in the *Navigator*. Its properties appear in +the *Editor*. +. Click the *Schema Document Info* tab. The Schema Document Info tab +appears. [#Figure 4-34]##*_Schema Document Info Tab – Namespaces Field_* +image:schnmsp.gif[Schema Document Info Tab – Namespaces +Field,title="Schema Document Info Tab – Namespaces Field"] +. Complete the Namespaces fields on the Schema Document Info tab. + +Use the following information to complete each Namespaces field in the +tab: + +Field + +Description + +Built-in Namespaces + +All namespaces defined by xmlns:="``". + +Note that when a schema is imported to the Workbench (see How to Import +an XML Schema), none of the built-in namespaces’ URLs are selected. If +you are using inheritance, declare the built-in namespace with xsi +prefix. Otherwise, EclipseLink will throw exceptions. + +Target Namespaces + +All namespaces defined by targetNamespace="``". + +Imported Namespaces + +All namespaces defined by xsd:import. + +Prefix + +Double-click in the Prefix field to specify the prefix that corresponds +to the given namespace. + +When the EclipseLink runtime marshalls (writes) an object to an XML +document, it uses the namespace prefixes you specify here. + +When the EclipseLink runtime unmarshalls (reads) an XML document, the +document may use any prefix value as long as it corresponds to the +appropriate namespace. For more information, see EclipseLink Runtime +Namespace Resolution. + +Declare + +When selected, XML documents must use the corresponding URI qualifier +when referring to types from this namespace. XML documents may use a +different prefix value as long as that value is associated with the +appropriate namespace URI. For more information, see EclipseLink Runtime +Namespace Resolution. + +==== How to Configure XML Schema Namespace Using Java + +Using Java, to configure XML schema namespaces for an EIS descriptor +(with XML records) or an XML descriptor, create a descriptor amendment +method (see +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Amendment_Methods[Configuring +Amendment Methods]) that uses `+EISDescriptor+` or `+XMLDescriptor+` +method `+getNamespaceResolver+` to configure the descriptor’s +`+NamespaceResolver+` accordingly, as this example shows. + +[#Example 4-4]## *_Configuring Namespaces_* + +`+public void addToDescriptor(ClassDescriptor descriptor) {+` +`+    descriptor.getNamespaceResolver.put(+` `+        prefix,+` +`+        namespaceURI+` `+    );+` `+}+` + +== Using Classes + +Using Workbench, you can create Java classes and packages. This section +includes information on the following: + +* link:#How_to_Create_Classes[How to Create Classes] +* link:#How_to_Configure_Classes[How to Configure Classes] +* link:#How_to_Import_and_Update_Classes[How to Import and Update +Classes] +* link:#How_to_Manage_Nondescriptor_Classes[How to Manage Nondescriptor +Classes] +* link:#How_to_Rename_Packages[How to Rename Packages] + +=== How to Create Classes + +We recommend that you develop your Java classes using an IDE such as +Eclipse and import these existing classes into Workbench (see +link:#How_to_Import_and_Update_Classes[How to Import and Update +Classes]) + +However, it is sometimes convenient to create and configure classes in +Workbench: for example, when generating an object model from a database +schema. + +This section includes information on using Workbench to create Java +classes. + +For more information on using Workbench to edit classes, see +link:#How_to_Create_Classes[How to Create Classes]. + +==== How to Create Classes Using Workbench + +To create new classes and packages from within Workbench, use this +procedure: + +[arabic] +. Select the project in the *Navigator* and click *Create New Class* +image:creatcls.gif[Create New Class +button,title="Create New Class button"]. You can also right-click the +project in the *Navigator* and choose *Create New Class* from the +context menu or choose *Selected* > *Create New Class* from the menu. +[#Figure 4-35]##*_Add Class Dialog Box_* image:addclass.gif[Add Class +Dialog Box,title="Add Class Dialog Box"] +. Enter data in each field on the Add Class dialog box and click *OK*. +Workbench will add the new class to the project in the *Navigator*. + +Use the following information to enter data in each field on the Add +Class dialog box: + +[width="100%",cols="<16%,<84%",options="header",] +|=== +|*Field* |*Description* +|*Package Name* |Choose an existing package or enter a new package name. +If blank, Workbench uses the default package name. + +|*New Class Name* |Enter a class name. The *New Class Name* must be +unique within the package. +|=== + +For more information on using Workbench to edit classes, see +link:#How_to_Configure_Classes[How to Configure Classes]. + +=== How to Configure Classes + +We recommend that you develop your Java classes using an IDE such as +Eclipse and import these existing classes into Workbench (see +link:#How_to_Import_and_Update_Classes[How to Import and Update +Classes]) + +However, it is sometimes convenient to create (see +link:#How_to_Create_Classes[How to Create Classes]) and configure +classes in Workbench: for example, when generating an object model from +a database schema. + +This section describes using Workbench to edit classes, including the +following: + +* link:#Configuring_Class_Information[Configuring Class Information] +* link:#Configuring_Class_Modifiers[Configuring Class Modifiers] +* link:#Configuring_Class_Interfaces[Configuring Class Interfaces] +* link:#Adding_Attributes[Adding Attributes] +* link:#Configuring_Attribute_Modifiers[Configuring Attribute Modifiers] +* link:#Configuring_Attribute_Type_Declaration[Configuring Attribute +Type Declaration] +* link:#Configuring_Attribute_Accessing_Methods[Configuring Attribute +Accessing Methods] +* link:#Adding_Methods[Adding Methods] +* link:#Configuring_Method_Modifiers[Configuring Method Modifiers] +* link:#Configuring_Method_Return_Type[Configuring Method Return Type] +* link:#Configuring_Method_Parameters[Configuring Method Parameters] + +==== Configuring Class Information + +This section includes information on using the workbench to configure +class information. + +===== Using Workbench + +To configure class and superclass information, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Class* tab. [#Figure 4-36]##*_Class Tab, Class Information +Fields_* image:classinfo.gif[Class Tab, Class Information +Fields,title="Class Tab, Class Information Fields"] +. Complete the class information fields on the Class Info tab. + +Use the following information to enter data in each field on the tab: + +[width="100%",cols="<14%,<86%",options="header",] +|=== +|*Field* |*Description* +|*Name* |The name of the class. This field is for display only. + +|*Superclass* |Click *Browse* and select a class and package that +contains the class (that is, the superclass). +|=== + +==== Configuring Class Modifiers + +This section includes information on using the workbench to configure +class modifiers. + +===== Using Workbench + +To configure class modifiers, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Class* tab.[#Figure 4-37]## *_Class Tab, Class Modifiers +Fields_* image:clclmodi.gif[Class Tab, Class Modifiers +Fields,title="Class Tab, Class Modifiers Fields"] +. Complete the Modifiers fields on the Class tab. + +Use the following information to enter data in each field on the tab: + +[width="100%",cols="<13%,<87%",options="header",] +|=== +|*Field* |*Description* +|*Access Modifiers* |Use to specify whether the class is accessible +publicly or not. Only public classes are visible to the Workbench. + +|*Other Modifiers* |Specify if the class is *Final* or *Abstract*, or +both. Final classes are not included in the superclass selection lists +for other classes to extend. +|=== + +==== Configuring Class Interfaces + +This section includes information on using the workbnech to specify the +interfaces implemented by a class. You can choose any interface in the +Workbench classpath (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]). + +Although you may add interfaces to a project directly (see +link:#How_to_Import_and_Update_Classes[How to Import and Update +Classes]), you do not need to do so in order to configure a class to +implement an interface. + +===== Using Workbench + +To implement interfaces, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Class* tab. [#Figure 4-38]##*_Class Tab, Interfaces +Implemented Fields_* image:clclintr.gif[Class Tab, Interfaces +Implemented Fields,title="Class Tab, Interfaces Implemented Fields"] +. Complete the Iterfaces Implemented field on the tab. + +Use the following information to enter data in the Interfaces +Implemented field on the Class tab: + +[width="100%",cols="<13%,<87%",options="header",] +|=== +|*Field* |*Description* +|*Interfaces Implemented* |To add an interface, click *Add*. The Choose +Class dialog box appears. In the dialog box, select the interface and +package. To remove an interface, select the interface and click +*Remove*. +|=== + +==== Adding Attributes + +This section includes information on using the workbench to add an +attribute to a class. + +===== Using Workbench + +* To add a new attribute (field) to the descriptor, click *Add.* +* To delete an existing attribute, select the attribute and click +*Remove*. +* To rename an existing attribute, select the attribute and click +*Rename*. + +The *Attributes* tab contains the following tabs: + +* General +* Accessors + +==== Configuring Attribute Modifiers + +This section includes information on using the workbench to configure +attribute modifiers. + +===== Using Workbench + +To specify access modifiers, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Attributes* tab. The Attributes tab contains two sub-tabs. +. Click the *General* tab. [#Figure 4-39]##*_Attributes Tab, Modifiers +Fields_* image:clatgenmod.gif[Attributes Tab, Modifiers +Fields,title="Attributes Tab, Modifiers Fields"] +. Complete the Modifiers fields on the Attributes tab. + +Use the following information to enter data in the Modifiers fields on +the Attributes tab: + +Field + +Description + +Access Modifiers + +Specify how the attribute is accessible: + +Public + +Protected –only visible within its own package and subclasses. + +Private – not visible for subclasses + +Default – only visible within its own package + +Other Modifiers + +Specify whether the attribute is Final, Static, Transient, or Volatile. + +Note: Selecting some modifiers may disable others. + +==== Configuring Attribute Type Declaration + +This section includes information on using the workbench to configure +attribute type declaration. + +===== Using Workbench + +To specify attribute type declaration, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Attributes* tab. The Attributes tab contains two sub-tabs. +. Click the *General* tab. [#Figure 4-40]##*_Attributes Tab, Type +Declaration Fields_* image:clatgentyp.gif[Attributes Tab, Type +Declaration Fields,title="Attributes Tab, Type Declaration Fields"] +. Complete the Type Declaration fields on the Attributes tab. + +Use the following information to enter data in Type Declaration fields +on the Attributes tab: + +[width="100%",cols="<14%,<86%",options="header",] +|=== +|*Field* |*Description* +|*Type* |Click *Browse* and select a class and package for the +attribute. + +|*Dimensionality* |Specify the length of an array. This field applies +only if *Type* is an array. + +|*Value Type* |Click *Browse* and select a class and package for the +attribute. This field applies for `+ValueHolderInterface+` types only. + +|*Map Key Type* |Click *Browse* and select a class and package for the +attribute. This field applies for `+Map+` types only. + +|*Map Value Type* |Click *Browse* and select a class and package for the +attribute. This field applies for `+Map+` types only. + +|*Element Type* |Click *Browse* and select a class and package for the +attribute. This field applies for `+List+` types only. +|=== + +==== Configuring Attribute Accessing Methods + +This section includes information on using the workbench to configure +attribute accessing methods. If you change an attribute and regenerate +the accessing methods, EclipseLink _does not_ remove any previously +generated methods. + +===== Using Workbench + +To specify attribute accessing methods, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Attributes* tab. The Attributes tab contains two sub-tabs. +. Click the *Accessors* tab. [#Figure 4-41]##*_Attributes Tab, Accessors +Fields_* image:clataccs.gif[Attributes Tab, Accessors +Fields,title="Attributes Tab, Accessors Fields"] +. Complete the Accessors fields on the Attributes tab. Click *Generate +Methods* to automatically create the required method. + +Use the following information to complete the Accessors fields on the +Attributes tab: + +[width="100%",cols="<19%,<81%",options="header",] +|=== +|*Field* |*Description* +|*Get Method* |Choose the `+get+` method for the attribute. This field +applies for non-`+Collection+` types only. + +|*Set Method* |Choose the `+set+` method for the attribute. This field +applies for non-`+Collection+` types only. + +|*Add Method* |Choose the `+add+` method for the attribute. This field +applies for `+List+` and `+Map+` types only. + +|*Remove Method* |Choose the `+remove+` method for the attribute. This +field applies for `+List+` and `+Map+` types only. + +|*Value Holder Get Method* |Choose the method used to return the +`+ValueHolderInterface+` type. This field applies for +`+ValueHolderInterface+` types only. + +|*Value Holder Set Method* |Choose the method used to set the +`+ValueHolderInterface+` type. This field applies for +`+ValueHolderInterface+` types only. + +|*Value Get Method* |Choose the method used to return the actual value. +This field applies for `+ValueHolderInterface+` types only. + +|*Value Set Method* |Choose the method used to set the actual value. +This field applies for `+ValueHolderInterface+` types only. +|=== + +==== Adding Methods + +This section includes information on the workbench to add a method to a +class. + +===== Using Workbench + +To add or remove methods, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Methods* tab.[#Figure 4-42]## *_Class Info – Methods Tab_* +image:clmethod.gif[Class Info – Methods +Tab,title="Class Info – Methods Tab"] + +To add a new method to the descriptor, click *Add.* + +To delete an existing method, select the method and click *Remove*. + +To rename an existing method, select the method and click *Rename*. + +==== Configuring Method Modifiers + +This section includes information on using the workbench to configure +method modifiers. + +===== Using Workbench + +To specify access modifiers, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Methods* tab. [#Figure 4-43]##*_Methods Tab, Modifiers +Fields_* image:clmemod.gif[DMethods Tab, Modifiers +Fields,title="DMethods Tab, Modifiers Fields"] +. Complete the Modifiers fields on the Methods tab. + +Use the following information to enter data in Modifiers fields on the +Methods tab: + +Field + +Description + +Access Modifiers + +Specify how the method can be accessed: + +Public + +Protected – only visible within its own package and subclasses. + +Private – not visible for subclasses. + +Default – only visible within its own package. + +Other Modifiers + +Specify whether the method is Abstract, Final, Synchronized, Static, or +Native. + +Note: Selecting some modifiers may disable others. + +==== Configuring Method Return Type + +This section includes information on using the workbench to configure +method return type. + +===== Using Workbench + +To specify method return type, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Methods* tab. [#Figure 4-44]##*_Methods Tab, Return Type +Fields_* image:clmetyp.gif[Methods Tab, Return Type +Fields,title="Methods Tab, Return Type Fields"] +. Complete the Return Type fields on the Methods tab. + +Use the following information to enter data in Return Type fields on the +Methods tab: + +[width="100%",cols="<20%,<80%",options="header",] +|=== +|*Field* |*Description* +|*Type* |Click *Browse* and select a class and package for the method. + +|*Dimensionality* |Specify the length of an array. This field applies +only if *Type* is an array. +|=== + +==== Configuring Method Parameters + +This section includes information on using the workbench to configure +method parameters. + +===== Using Workbench + +To specify additional method parameters, use this procedure: + +[arabic] +. Select a class in the *Navigator*. Its properties appear in the +*Editor*. +. Click the *Class Info* tab in the *Editor*. +. Click the *Methods* tab. [#Figure 4-45]##*_Methods Tab, Method +Parameters Fields_* image:clmeparm.gif[Methods Tab, Method Parameters +Fields,title="Methods Tab, Method Parameters Fields"] +. Complete the Parameters fields on the Methods tab. + +Use the following information to enter data in Parameters fields on the +Methods tab: + +[width="100%",cols="<20%,<80%",options="header",] +|=== +|*Field* |*Description* +|*Type* |Click *Browse* and select a class and package for the method. + +|*Dimensionality* |Specify the length of an array. This field applies +only if *Type* is an array. +|=== + +=== How to Import and Update Classes + +This section includes information on +link:#Importing_and_Updating_Classes_Using_Workbench[Importing and +Updating Classes Using Workbench] to import and update Java classes. + +You can import Java classes and interfaces created in any IDE. + +[cols="<",] +|=== +|*Note*: You can import interfaces only in relational projects. +|=== + +You can import any class on the system classpath or project classpath. + +If a class exists on both the system classpath and the project +classpath, Workbench will update the class from the system classpath. To +update or refresh from the project classpath, remove the class from the +system classpath and restart Workbench. + +For more information, see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]. + +==== Importing and Updating Classes Using Workbench + +Use this procedure to update or refresh the classes in the Workbench +project. + +[arabic] +. Define the available classes and packages for the project on the +*General* tab. See +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath] for information on classes and packages. +. Click *Add or Refresh Class* image:creatcls.gif[Add or Refresh Class +button,title="Add or Refresh Class button"]. The Select Classes dialog +box appears. You can also update the classes by choosing *Selected* > +*Add or Refresh Classes* from the menu. [#Figure 4-46]##*_Select Classes +Dialog Box_* image:select.gif[Select Classes Dialog +Box,title="Select Classes Dialog Box"] + +Select the packages or classes (or both) to import into the project and +click *OK*. Workbench adds the new classes to your project in the +*Navigator*. + +By default, Workbench creates the following descriptor types for each +package and class (depending on your project type): + +* link:Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating_Relational_Class_Descriptors[Relational +projects – Relational class descriptors] +* link:Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS_Composite_Descriptors[EIS +projects – EIS composite descriptors] +* link:Introduction%20to%20XML%20Descriptors%20(ELUG)#Composite_Descriptors_in_XML_Projects[XML +projects – XML descriptors] + +See +link:Creating%20a%20Descriptor%20(ELUG)#Creating_a_Descriptor[Creating a +Descriptor] for more information. + +[width="100%",cols="<100%",] +|=== +|*Note*: If the class exists on both the system classpath and the +project classpath, Workbench will update the class from the system +classpath. To update or refresh from the project classpath, remove the +class from the system classpath and restart Workbench. +|=== + +*To Remove a Class from a Project, do the following:* + +Select the descriptor and click *Remove* image:remclass.gif[Remove Class +button,title="Remove Class button"], or choose *Selected* > *Remove* +from the menu. + +=== How to Manage Nondescriptor Classes + +Some of the mappings in your EclipseLink project may reference classes +that do not have EclipseLink descriptors or are not included in the +project. + +To add, remove, or refresh Java classes that do not have EclipseLink +descriptors, use this procedure: + +From the menu, select *Workbench > Manage Non-Descriptor Classes*. The +Manage Non-Descriptor Classes dialog box appears. + +You can access the dialog box by right-clicking the EclipseLink project +icon in the *Navigator* and selecting *Manage Non-Descriptor Classes* +from the context menu. + +[#Figure 4-47]## *_Manage Non-Descriptor Classes Dialog Box_* + +.Manage Non-Descriptor Classes Dialog Box +image::nondescriptor.gif[Manage Non-Descriptor Classes Dialog +Box,title="Manage Non-Descriptor Classes Dialog Box"] + +Select one of the following options: + +* To add new classes, click *Add*. The Select Classes dialog box appears +(see link:#Figure_4-46[the Select Classes Dialog Box]). Only classes +that have been added to the +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[project’s +classpath] can be added as nondescriptor classes. +* To delete an existing class, select the class and click *Remove*. +* To refresh the classes (for example, if you edited the classes in an +IDE), click *Refresh*. + +=== How to Rename Packages + +When you add classes to a project, Workbench shows the classes contained +in the package to which they belong (see +link:#How_to_Use_the_Navigator[How to Use the Navigator]). + +You can use Workbench to change the package statements in all the Java +classes of a selected package (to move the all the classes contained by +the selected package to a new package). This is useful if you are +refactoring an existing Workbench project. + +Note: The Workbench package rename feature is not intended for migrating +projects to this release of EclipseLink: for this, you must still use +the EclipseLink Package Renamer. The Package Renamer updates import +statements for EclipseLink classes – it does not change the package +statements in user application classes. + +For information on the EclipseLink Package Renamer, see "`Running the +Package Renamer`" in the Migration Guide. + +For more information on using Workbench to edit classes, see +link:#How_to_Configure_Classes[How to Configure Classes]. + +==== Renaming Packages Using Workbench + +To change the package of an existing class in Workbench, use this +procedure: + +[arabic] +. Right-click the package in the *Navigator* and select *Rename*. You +can also select the package and choose *Selected* > *Rename* from the +menu.* *_Rename Package Dialog Box_’’’ +[#Figure 4-48]##image:changpkg.gif[Rename Package Dialog +Box,title="Rename Package Dialog Box"] +. Enter the package name on the Rename Package dialog box and click +*OK*. Workbench will change the name of the package in the Navigator. + +Enter the package name and click *OK*. Workbench changes the name of the +package in the Navigator window. + +For more information on using Workbench to edit classes, see +link:#How_to_Configure_Classes[How to Configure Classes]. + +== Integrating Workbench with Apache Ant + +If you use the Apache Ant Java-based build tool, you can use the Ant +task and type definitions that EclipseLink provides to invoke certain +Workbench functions from an Ant build file. Using these tasks, you can +integrate Workbench into your automated build process. + +This section describes the following: + +* link:#How_to_Configure_Ant_to_Use_Workbench_Tasks[How to Configure Ant +to Use Workbench Tasks] +* link:#What_You_May_Need_to_Know_About_Workbench_Ant_Task_API[What You +May Need to Know About Workbench Ant Task API] +* link:#How_to_Create_Workbench_Ant_Tasks[How to Create Workbench Ant +Tasks] + +For more information about Ant, see +http://ant.apache.org/manual/[`+http://ant.apache.org/manual/+`]. + +=== How to Configure Ant to Use Workbench Tasks + +Before you can use Workbench tasks in your Ant build files, you must +consider their library dependencies (see +link:#Creating_Library_Dependencies[Creating Library Dependencies]). + +To declare Workbench tasks in your Ant `+build.xml+` file, declare them +directly (see link:#Declaring_Workbench_Tasks[Declaring Workbench +Tasks]). + +==== Creating Library Dependencies + +In addition to the Ant library dependencies (see +http://ant.apache.org/manual/installl#librarydependencies[`+http://ant.apache.org/manual/installl#librarydependencies+`]), +the following table lists the EclipseLink-specific JAR files that must +be in your Ant classpath. + +[#table_4_4]##[#Table 4-4]## *_Workbench Ant Task Library Dependencies_* + +[width="100%",cols="<20%,<37%,<43%",options="header",] +|=== +|*JAR Name* |*Needed For…* |*Available At…* +|`+eclipselinkmw.jar+` |Workbench Ant task and type definitions. +|`+<+`_`+ECLIPSELINK_HOME+`_`+>/utils/workbench/jlib+` +|=== + +==== Declaring Workbench Tasks + +After you declare the Workbench task definitions (see +link:#table_4_6[the Workbench Ant Type Definitions]) table and data +definitions (see link:#table_4_4[the Workbench Ant Task Library +Dependencies]) table in the `+eclipselink-ant-lib.xml+` file (see +link:#example_4_5[Declaring Workbench Ant Task and Data Types in an +eclipselink-ant-lib.xml File]) example, you can use a Workbench task in +a `+build.xml+` file, as the link:#example_4_6[Specifying the +eclipselink-ant-lib.xml File in the build.xml File] example shows: + +[#example4_5]## *_Declaring Workbench Ant Task and Data Types in an +eclipselink-ant-lib.xml File_* + +`+    +` + +`+    +` + +`+    +` + +`+ +` `+    +` + +`+    +` + +`+    +` + +[#example_4_6]## *_Specifying the eclipselink-ant-lib.xml File in the +build.xml File_* + +`+   +` `+   ...+` + +=== What You May Need to Know About Workbench Ant Task API + +The following lists the Workbench Ant task definitions that EclipseLink +provides. + +[#Table 4-5]## *_Workbench Ant Task Definitions_* + +Task Name + +EclipseLink Class + +mappings.validate Task + +org.eclipse.persistence.tools.workbench.ant.taskdefs.MappingsValidateTask + +session.validate Task + +org.eclipse.persistence.tools.workbench.ant.taskdefs.SessionValidateTask + +mappings.export Task + +org.eclipse.persistence.tools.workbench.ant.taskdefs.ExportDeploymentXMLTask + +The following lists the Workbench Ant type definitions that EclipseLink +provides. + +[#Table 4-6]## *_Workbench Ant Type Definitions_* + +Type Name + +EclipseLink Class + +ignoreerror Task + +org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreError + +ignoreerrorset Task + +org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreErrorSet + +loginspec Task + +org.eclipse.persistence.tools.workbench.ant.typedefs.LoginSpec + +=== How to Create Workbench Ant Tasks + +The following shows a typical Ant `+build.+`xml file that declares and +uses the Workbench Ant task and type definitions. + +[#Example 4-7]## *_Example Ant Build File with Workbench Ant Tasks_* + +`+    +` +`+    +` + +`+    +` +`+    +` `+        +` + +`+        +` `+        +` `+        +` + +`+        +` `+            +` `+            +` `+        +` `+        +` +`+            +` `+            +` `+        +` `+        +` +`+            +` + +`+            +` `+        +` `+        +` `+            +` `+        +` + +`+        +` + +`+    +` +`+    +` +`+    +` +`+    +` +`+    +` `+        +` + +`+        +` `+        +` + +`+        +` `+    +` +`+    +` +`+    +` + +`+    +` +`+    +` + +`+        +` + +`+            +` `+            +` + +`+            +` + +`+        +` `+    +` +`+    +` +`+    +` + +`+    +` +`+    +` + +`+        +` + +`+            +` `+            +` + +`+            +` `+            +` +`+        +` `+    +` +`+    +` +`+    +` + +`+    +` +`+    +` + +`+        +` + +`+            +` `+            +` + +`+            +` `+        +` `+    +` + +=== How to Create the mappings.validate Task + +The `+mapings.validate+` task is a testing task that you use to list of +all the problems in a Workbench project (`+.mwp+`) file. + +This task lets you do the following: + +* log all the problems to a file in text orL format; +* set an Ant property to indicate that the Workbench project is valid +(has no errors). + +==== Using Parameters + +[#Table 4-7]## *_mappings.validate Task Parameters_* + +[width="100%",cols="<15%,<61%,<24%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|projectfile |Fully qualified Workbench projects file name (.mwp). |Yes + +|reportfile |Fully qualified file name to which to write the output. |No + +|reportformat |The format of the generated output. Must be `+codel+` or +`+text+`. |No – default to `+text+`. + +|classpath |Project classpath. |No + +|classpathref |Reference to a path defined elsewhere. |No + +|property |The name of the property to set (true if there is no +problem). |No +|=== + +==== Specifying Parameters Specified as Nested Elements + +You can specify the following parameters as nested elements of this +task: + +* classpath +* link:#How_to_Create_the_ignoreerror_Task[ignoreerror] +* link:#How_to_Create_the_ignoreerrorset_Task[ignorerrorset] + +==== Examples + +The following shows a typical `+mappings.validate+` task. + +[#Example 4-8]## *_A mappings.validate Task_* + +`++` + +`+    +` `+    +` + +`+    +` `+    +` + +`++` + +=== How to Create the session.validate Task + +The `+session.validate+` task is a testing task that you use to test +your EclipseLink deployment XML by running EclipseLink. + +This task provides the ability to do the following: + +* specify the test type using a nested element; +* set an Ant property to indicate that the Workbench project is valid +(has no errors). + +==== Using Parameters + +[#Table 4-8]## *_session.validate Task Parameters_* + +[width="100%",cols="<14%,<43%,<43%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|sessionsfile |Fully qualified `+sessions.xml+` file. |No – default to +`+sessions.xml+` and to classpath. + +|sessionname |Name of the session to test. |Yes + +|classpath |Project classpath. |No + +|classpathref |Reference to a path defined elsewhere. |No + +|property |The name of the property to set (true if valid). |No +|=== + +==== Specifying Parameters Specified as Nested Elements + +You can specify the following parameters as nested elements of this +task: + +* classpath; +* link:#How_to_Create_the_loginspec_Task[loginspec]. + +==== Examples + +The following shows a typical `+session.validate+` task. + +[#Example 4-9]## *_A session.validate Task_* + +`++` + +`+    +` `+    +` + +`+    +` + +`++` + +=== How to Create the mappings.export Task + +The `+mappings.export+` task is a generation task that you use to +generate an EclipseLink deployment XML file for a given Workbench +project (`+.mwp+`). The `+mappings.export+` task executes a +link:#How_to_Create_the_mappings.validate_Task[H`+mappings.validate+` +task] before executing. A `+BuildException+` is thrown if validation +fails. + +This task provides the ability to override the Workbench project +database login information. + +==== Using Parameters + +[#Table 4-9]## *_mappings.export Task Parameters_* + +[width="100%",cols="<9%,<51%,<40%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|projectfile |Fully qualified Workbench projects file name (`+.mwp+`). +|Yes + +|deploymentfile |Fully qualified EclipseLink project deployment file +name (`+.xml+`). |No – default to the name specified in the Workbench +project (`+.mwp+`). + +|ejbjarxmldir |The directory that contains the `+ejb-jar.xml+` file +(only applicable to Java EE project). |No – default to the directory +specified in the Workbench project (`+.mwp+`). + +|classpath |Project classpath. |No + +|classpathref |Reference to a path defined elsewhere. |No + +|failonerror |Indicates whether the build will continue even if there +are export errors; defaults to `+true+`. |No + +|property |The name of the property to set (`+true+` if export completed +successfully). |No +|=== + +==== Specifying Parameters Specified as Nested Elements + +You can specify the following parameters as nested elements of this +task: + +* classpath; +* link:#How_to_Create_the_loginspec_Task[loginspec]; +* link:#How_to_Create_the_ignoreerrorTask[ignorerror]; +* link:#How_to_Create_the_ignoreerrorset_Task[ignorerrorset]. + +==== Examples + +The following example shows a typical `+mappings.export+` task. + +[#Example 4-10]## *_A mappings.export Task_* + +`++` + +`+    +` + +`+    +` + +`+    +` `+    +` `+    +` `++` + +=== How to Create the classpath Task + +Use the classpath element to define the Java classpath necessary to run +a task. For more information, see +http://ant.apache.org/manual/usingl#path[`+http://ant.apache.org/manual/usingl#path+`]. + +==== Using Parameters + +[#Table 4-10]## *_classpath Element Parameters_* + +[width="100%",cols="<12%,<78%,<10%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|location |Specifies a single file or directory relative to the +project’s base directory (or an absolute filename). |No + +|path |Specifies one or multiple files or directories separated by a +colon or semicolon. |No + +|refid |Reference to a path defined elsewhere. |No +|=== + +==== Specifying Parameters Specified as Nested Elements + +You can specify the following parameters as nested elements of this +task: + +* pathelement +* fileset +* dirset +* filelist + +==== Examples + +The following example shows a typical `+classpath+` element. + +*_A classpath Element_* + +`+   +` `+       +` `+           +` `+       +` `+   +` `+       +` +`+           +` `+           +` `+       +` `+   +` + +=== How to Create the ignoreerror Task + +Use the `+ignoreerror+` element to instruct an EclipseLink Ant task to +ignore a specific EclipseLink Foundation Library or Workbench (see +link:Troubleshooting_an_EclipseLink_Application_(ELUG)[Troubleshooting +an EclipseLink Application (ELUG)]) run-time error code. + +To instruct an EclipseLink Ant task to ignore multiple error codes, +consider using an +link:#How_to_Create_the_ignoreerrorset_Task[`+ignoreerrorset+` element]. + +==== Using Parameters + +[#Table 4-11]## *_ignoreerror Element Parameters_* + +[cols="<,<,<",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|code |Error code of the problem to ignore. |Yes +|=== + +==== Specifying Parameters Specified as Nested Elements + +You cannot specify parameters as nested elements of this element. + +==== Examples + +The following example shows a typical `+ignoreerror+` element. This +element instructs a `+mappings.export+` task to ignore Workbench error +code 0545. + +*_An ignoreerror Element_* + +`++` `+   +` `+   +` `+   +` +`++` + +=== How to Create the ignoreerrorset Task + +Use the `+ignoreerrorset+` element to instruct an EclipseLink Ant task +to ignore any of multiple EclipseLink Foundation Library or Workbench +run-time error codes. + +==== Using Parameters + +[#Table 4-12]## *_ignoreerrorset Element Parameters_* + +[width="100%",cols="<14%,<75%,<11%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|id |Unique identifier for this type instance, can be used to reference +this type in scripts. |No + +|refid |Reference to a ignoreerrorset defined elsewhere. |No +|=== + +==== Specifying Parameters Specified as Nested Elements + +You can specify the following parameter as nested elements of this +element: + +* link:#How_to_Create_the_ignoreerror_Task[ignorerror] + +==== Examples + +The following example shows a typical `+ignoreerrorset+` element. This +element instructs a `+mappings.export+` task to ignore all of Workbench +error codes 0402 and 0570. Note that the `+mappings.export+` task also +uses an explicitly `+ignoreerror+` element: this means that the +`+mappings.export+` task will ignore all of error codes 0402, 0570, and +0545. + +[#Example 4-13]## *_An ignoreerrorset Element_* + +`+   +` `+   +` `+   ...+` `+   +` `+   +` `+   +` `+   +` +`+   +` `++` + +=== How to Create the loginspec Task + +Use the `+loginspec+` element to instruct an EclipseLink Ant task to +override the project database login information in a Workbench project. +For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)[Introduction to Data +Access]. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can only use this element with +link:Introduction%20to%20Relational%20Projects%20(ELUG)[Relational +Projects]. You cannot use this element with a Java EE project. +|=== + +==== Using Parameters + +[#Table 4-13]## *_loginspec Element Parameters_* + +[width="100%",cols="<6%,<72%,<22%",options="header",] +|=== +|*Attribute* |*Description* |*Required* +|id |Unique identifier for this type instance, can be used to reference +this type in scripts. |No + +|refid |Reference to a loginspec defined elsewhere. |No + +|driverclass |Fully qualified class of the data source driver (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Database_Login_Connection_Options[Configuring +Database Login Connection Options]). |No – default to the class that the +Workbench project specifies. + +|url |URL of the driver (see +link:Configuring%20a%20Database%20Login%20(ELUG)#Configuring_Database_Login_Connection_Options[Configuring +Database Login Connection Options]). |Yes + +|user |Login user name (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_User_Name_and_Password[Configuring +User Name and Password]). |No – default to the value that the Workbench +project specifies + +|password |Login password (see +link:Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring_User_Name_and_Password[Configuring +User Name and Password]). |No – default to the value that the Workbench +project specifies +|=== + +==== Specifying Parameters Specified as Nested Elements + +You cannot specify parameters as nested elements of this element. + +==== Examples + +The following example shows a typical `+loginspec+` element. + +[#Example 4-14]## *_A loginspec Element_* + +`++` + +`+    +` `+    +` + +`+    +` + +`++` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_an_Integrated_Development_Environment_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_an_Integrated_Development_Environment_(ELUG).adoc new file mode 100644 index 00000000000..b2e93b542ac --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_an_Integrated_Development_Environment_(ELUG).adoc @@ -0,0 +1,232 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Using_an_Integrated_Development_Environment_(ELUG)[Related +Topics] + +In addition to the development environment described in this section, +you can use EclipseLink with _any_ Java EE development environment and +process. + +== Configuring Workbench with Source Control Management Software + +You can use Workbench with a source control management (SCM) system to +facilitate enterprise-level team development (see +link:#How_to_Use_a_Source_Control_Management_System[How to Use a Source +Control Management System]). If you have a small development team, you +can manage the changes from within XML files (see +link:#How_to_Share_Project_Objects[How to Share Project Objects]). + +When using a Workbench project in a team environment, you must +synchronize your changes with other developers. See +link:#How_to_Merge_Files[How to Merge Files] for more information. + +=== How to Use a Source Control Management System + +If you use an enterprise, file-based source control management system to +manage your Java source files, you can use the same system with your +Workbench project files. These project files are maintained by Workbench +and written out in XML file format. + +The _check in_ and _check out_ mechanism for the source control system +defines how to manage the source (the XML source and Workbench project +file) in a multiuser environment. + +*Checking Out and Checking In Workbench Project Files* + +Although your actual development process will vary depending on your SCM +tool, a typical process involves the following steps: + +[arabic] +. Determine (based on your SCM system) which files to retrieve from the +source management system. +. Edit the project using Workbench. +. Save the edited project. If Workbench displays the Read-Only Files +dialog box, make a note of these files, they must be unlocked and +possibly merged. See link:#How_to_Work_with_Locked_Files[How to Work +with Locked Files] for more information. +. Merge the required project files. See link:#How_to_Merge_Files[How to +Merge Files] for details. +. Check in the modified files, then retrieve from the repository any +files that have been added or modified for this Workbench project. + +=== How to Merge Files + +The most difficult aspect of application development is merging changes +from two (or more) development team members that have simultaneously +edited the same file. If you check in your changes, a _merge_ condition +exists. Use a file comparison tool to determine the merged aspects of +the project. The files to edit will vary, depending on the type of +merge, as follows: + +* link:#Project_Files[Project Files] +* link:#Merging_Table,_Descriptor,_and_Class_Files[Merging Table, +Descriptor, and Class Files] + +link:#example_merging_projects[Merging Projects] and +link:#example_merging_files[Merging Files] examples demonstrate a _merge +out_ merging technique. + +==== Merging Project Files + +Project files contain references to the objects in the project. +Generally, your project __`+.mwp+` contains the following elements: + +* Database information: +** Database tables: +* Descriptors: +* Repository: +** Classes: + +Changes in these parts of the `+.mwp+` file are usually caused by +adding, deleting, or renaming project elements. + +To merge project files, you will generally need to merge a project file +if another developer has added or removed a descriptor, table, or class, +and checked in the project while you were adding or removing +descriptors, tables, or classes from the same project. To merge the +project’s `+.mwp+` file, use this procedure: + +[arabic] +. Perform a file comparison between the __.`+mwp+` file in the +repository and your local copy. The file comparison shows the addition +or removal of a project element inside the owner (that is, , , or ). +. Insert the XML script to, or delete from your local __.`+mwp+` file +(inside the _corresponding owner element_). This brings your local code +up-to-date to the current code in the code repository. +. Retrieve any updated files, as indicated by your source control +system. + +Your local source now matches the repository. + +[#example_merging_projects]## *’’Example: Merging Projects*’’ Another +developer has added and checked in a new *Employee* class descriptor to +the `+com.demo+` package while you were working with the same Workbench +project. To merge your work with the newly changed project, follow these +steps: + +[arabic] +. Perform a file comparison on the __.`+mwp+` file to determine the +differences between your local file and the file in the repository. Your +SCM system may show the file in _merge_ status. The file comparison +shows the addition of the tag and a element inside that tag: ++ +`+   +``+com.demo.Employee.ClassDescriptor+` +. Insert this XML into your __.`+mwp+` file (inside the element) to +bring it up to date with the current files in the source repository. +. Retrieve any new or updated files from your source control system. +This includes the newly added *Employee* class descriptor. +. Check in files that you have modified. + +==== Merging Table, Descriptor, and Class Files + +Developers who concurrently modify the same existing table, descriptor, +or class file will create a merge condition for the following files: + +* Table: __`+`+.xml+` (one for each table) +* Descriptor: _`++`_`+.xml+` (one for each +descriptor) +* Class: __`+.xml+` (one for each class) + +Workbench changes these files when saving a project if you have changed +any of the contents within them (such as adding a mapping to a +descriptor, adding an attribute to a class, or a changing a field +reference in a table). + +If another developer has changed an attribute in a table, descriptor, or +class, while you were changing a different mapping on that same +descriptor, you will need to merge your project. To merge your project, +use this procedure: + +[arabic] +. Perform a file comparison on the specific `+.xml+` files in merge +status (that is, table, descriptor, or class). The file comparison shows +the addition or removal of an XML element. +. Insert the XML script to, or remove from your local `+.xml+` file to +bring it up to date with the current files in the source repository. + +[#example_merging_files]## *’’Example: Merging Files*’’ Another +developer has added and checked in the *firstName* mapping to the +*Employee* class descriptor while you were changing a different mapping +on that same descriptor. To merge your work with the newly changed +project, use this procedure: + +[arabic] +. Perform a file comparison on the +`+com.demo.Employee.ClassDescriptor.xml+` file located in +__`+/Descriptor/+` directory that is in merge status. The file +comparison shows the addition of the tag and the elements inside that +tag: ++ +[source,java] +---- + + false + false + false + firstName + + direct field= + + + + EMPLOYEE
+ F_NAME + + + MWDirectToFieldMapping + +---- +. Insert this XML block into your local +`+com.demo.Employee.ClassDescriptor.xml+` file (inside the existing +element) to bring it up to date to the current files in the source +repository. +. Retrieve any new files noted as missing by your source control system. +This includes any tables or descriptors that may be referenced by the +new mapping. +. Check in files that you have modified. + +=== How to Share Project Objects + +You can also share project objects by copying the table or descriptor +files into the appropriate directories in the target project. + +After copying the files, insert a reference to the table, descriptor, or +class in the appropriate place in the __`+.mwp+` file. All references +contained within the project file must refer to an existing object in +the project. + +=== How to Work with Locked Files + +When working in a team environment, your source control system may lock +files when you retrieve them from the repository. If Workbench attempts +to save a locked file, the Version Control Assistance dialog box +appears, showing the locked files.’’’’’ + +[#Figure 6-1]## *_Version Control Assistance Dialog Box_* + +.Version Control Assistance Dialog Box +image::readonly.gif[Version Control Assistance Dialog +Box,title="Version Control Assistance Dialog Box"] + +Select one of the following methods to save your project: + +* Use your source control system to unlock the files, and then click +*Save*. +* Click *Save As* to save the project to a new location. + +See link:Creating%20a%20Project%20(ELUG)#How_to_Save_Projects[How to +Save Projects] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] diff --git a/docs/docs.ug/src/main/asciidoc/core/Using_the_Schema_Manager_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/core/Using_the_Schema_Manager_(ELUG).adoc new file mode 100644 index 00000000000..dd2988cfde1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/core/Using_the_Schema_Manager_(ELUG).adoc @@ -0,0 +1,341 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Using_the_Schema_Manager_(ELUG)[Related +Topics] + +The `+SchemaManager+` and its related classes provide API that you can +use from a Java application to specify database tables in a generic +format, and then create and modify them in a specific relational +database. This decouples your EclipseLink project from a particular +database schema while giving you a programmatic means of creating a +database schema based on your EclipseLink project. For example, you can +use the schema manager to recreate a production database in a +nonproduction environment. This lets you build models of your existing +databases, and modify and test them during development. + +[width="100%",cols="<100%",] +|=== +|*Note:* You can also create database tables manually during development +using the Workbench (see +link:Using%20Workbench%20(ELUG)#Creating_New_Tables[Creating New Tables] +and +link:Using%20Workbench%20(ELUG)#Generating_Tables_on_the_Database[Generating +Tables on the Database]). +|=== + +== Introduction to the Schema Manager + +The following figure summarizes the important `+SchemaManager+` classes +and the primary means of using them. + +[#Figure 5-1]## *_SchemaManager Usage_* + +.SchemaManager Usage +image::scheman.gif[SchemaManager Usage,title="SchemaManager Usage"] + +Although you can use the `+SchemaManager+` API directly, we recommend +that you create a `+TableCreator+` class and use its API (which, in +turn, uses the `+SchemaManager+`). + +You can automatically generate a `+TableCreator+` using the following: + +* link:#How_to_Use_Workbench_During_Development[Workbench during +development] +* link:#How_to_Use_the_Default_Table_Generator_at_Run_Time[`+DefaultTableGenerator+` +at run time] + +The `+TableCreator+` class owns one or more `+TableDefinition+` classes +(one for each database table) and the `+TableDefinition+` class owns one +or more `+FieldDefinition+` classes (one for each field). + +The `+TableDefinition+` class lets you specify a database table schema +in a generic format. At run time, EclipseLink uses the session +associated with your EclipseLink project to determine the specific +database type, and uses the generic schema to create the appropriate +tables and fields for that database. + +After creating a `+TableCreator+` class, you can use its API to create +and drop tables (see link:#Creating_Tables_with_a_Table_Creator[Creating +Tables with a Table Creator]). You can also configure EclipseLink to do +this automatically (see +link:#Creating_Database_Tables_Automatically[Creating Database Tables +Automatically]). + +Because the schema manager uses Java types rather than database types, +it is database-independent. However, because it does not account for +database-specific optimizations, it is best-suited for development +purposes rather than production. For more information on how the schema +manager maps Java types to database types, see +link:#How_to_Use_Schema_Manager_Java_and_Database_Type_Conversion[How to +Use Schema Manager Java and Database Type Conversion]. + +Although the schema manager can handle the sequencing configuration that +you specify in your EclipseLink project, there are some sequencing +restrictions you should be aware of (see link:#How_to_Use_Sequencing[How +to Use Sequencing]). + +=== How to Use Schema Manager Java and Database Type Conversion + +The following table lists the Java type to database type conversions +that the schema manager supports depending on the database platform your +EclipseLink project uses. This list is specific to the schema manager +and does not apply to mappings. EclipseLink automatically performs +conversions between any database types within mappings. + +[#Table 5-1]## *_Java and Database Field Type Conversion_* + +[width="99%",cols="<30%,<13%,<12%,<16%,<13%,<16%",options="header",] +|=== +|*Java Type* |*Oracle* |*DB2* |*Sybase* |*MySQL* |*MS Access* +|`+java.lang.Boolean+` |NUMBER |SMALLINT |BIT default 0 |TINYINT(1) +|SHORT + +|`+java.lang.Byte+` |NUMBER |SMALLINT |SMALLINT |TINYINT |SHORT + +|`+java.lang.Byte\'\'[]+` |LONG RAW |BLOB |IMAGE |BLOB |LONGBINARY + +|`+java.lang.Character+` |CHAR |CHAR |CHAR |CHAR |TEXT + +|`+java.lang.Character[]+` |LONG |CLOB |TEXT |TEXT |LONGTEXT + +|`+java.lang.Double+` |NUMBER |FLOAT |FLOAT(32) |DOUBLE |DOUBLE + +|`+java.lang.Float+` |NUMBER |FLOAT |FLOAT(16) |FLOAT |DOUBLE + +|`+java.lang.Integer+` |NUMBER |INTEGER |INTEGER |INTEGER |LONG + +|`+java.lang.Long+` |NUMBER |INTEGER |NUMERIC |BIGINT |DOUBLE + +|`+java.lang.Short+` |NUMBER |SMALLINT |SMALLINT |SMALLINT |SHORT + +|`+java.lang.String+` |VARCHAR2 |VARCHAR |VARCHAR |VARCHAR |TEXT + +|`+java.math.BigDecimal+` |NUMBER |DECIMAL |NUMERIC |DECIMAL |DOUBLE + +|`+java.math.BigInteger+` |NUMBER |DECIMAL |NUMERIC |BIGINT |DOUBLE + +|`+java.sql.Date+` |DATE |DATE |DATETIME |DATE |DATETIME + +|`+java.sql.Time+` |DATE |TIME |DATETIME |TIME |DATETIME + +|`+java.sql.Timestamp+` |DATE |TIMESTAMP |DATETIME |DATETIME |DATETIME +|=== + +For more information about database platforms that EclipseLink supports, +see +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms]. + +=== How to Use Sequencing + +If you generate a `+TableCreator+` class +link:#How_to_Use_Workbench_During_Development[using the Workbench] or +link:#How_to_Use_the_Default_Table_Generator_at_Run_Time[`+DefaultTableGenerator+`], +then sequencing configuration is included in your `+TableCreator+` +according to your EclipseLink project configuration. In this case, when +you use `+TableCreator+` method `+createTables+`, it does the following: + +* Creates the sequence table as defined in the session +`+DatabaseLogin+`. +* Creates or inserts sequences for each sequence name for all registered +descriptors in the session. +* Creates the Oracle sequence object if you use Oracle native +sequencing. + +You can use advanced API to handle special cases like Sybase or +Microsoft SQL Server native sequencing (see +link:#How_to_Use_Java_to_Create_a_Table_Creator[How to Use Java to +Create a Table Creator]). + +For more information about sequencing, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing_in_Relational_Projects[Sequencing +in Relational Projects]. + +== Creating a Table Creator + +You can automatically generate a `+TableCreator+` using: + +* link:#How_to_Use_Workbench_During_Development2[Workbench during +development] +* link:#How_to_Use_the_Default_Table_Generator_at_Run_Time2[`+DefaultTableGenerator+` +at run time] + +After creating a `+TableCreator+` class, you can use its API to create +and drop tables (see link:#Creating_Tables_with_a_Table_Creator[Creating +Tables with a Table Creator]). + +[#How to Use Workbench During Development2]## + +=== How to Use Workbench During Development + +To create a `+TableCreator+` class that you can use in a Java +application to recreate a database schema using the `+SchemaManager+`, +use this procedure: + +[arabic] +. Right-click the project in the *Navigator* and choose *Export > Table +Creator Java Source* from the context menu. The Table Creator dialog box +appears. You can also select the table and choose *Selected* > *Export > +Table Creator Java Source* from the menu. +. Enter a name for the table creator class and click *OK*. The Save As +dialog box appears. +. Choose a location for your table creator class and click *OK*. +Workbench exports the table creator Java class to the location you +specify. + +[#How to Use the Default Table Generator at Run Time2]## + +=== How to Use the Default Table Generator at Run Time + +To create a `+TableCreator+` class in Java using the +`+DefaultTableGenerator+`, use this procedure: + +[arabic] +. Create an instance of `+DefaultTableGenerator+`, passing in an +instance of your EclipseLink project: +`+DefaultTableGenerator myDefTblGen = new DefaultTableGenerator(eclipselinkProject);+` +. Create a `+TableCreator+` instance: +* If you want a `+TableCreator+` that can support any session, use: +`+TableCreator myTblCre = myDefTblGen.generateDefaultTableCreator();+` +* If you want a `+TableCreator+` customized for a specific EclipseLink +session, use: +`+TableCreator myTblCre = myDefTblGen.generateFilteredDefaultTableCreator(eclipselinkSession);+` + +You can also configure EclipseLink to use the `+DefaultTableGenerator+` +to automatically generate and execute a `+TableCreator+` at run time +(see link:#Creating_Database_Tables_Automatically[Creating Database +Tables Automatically]). + +=== How to Use Java to Create a Table Creator + +This section describes how to create a `+TableCreator+` class in Java, +including the following: + +* link:#Creating_a_TableCreator_Class[Creating a TableCreator Class] +* link:#Creating_a_TableDefinition_Class[Creating a TableDefinition +Class] +* link:#Adding_Fields_to_a_TableDefinition[Adding Fields to a +TableDefinition] +* link:#Defining_Sybase_and_Microsoft_SQL_Server_Native_Sequencing[Defining +Sybase and Microsoft SQL Server Native Sequencing] + +==== Creating a TableCreator Class + +To create your own `+TableCreator+` instance, you should extend +`+TableCreator+`, as the following example shows: + +[#Example 5-1]## *_Creating a TableCreator Class_* + +[source,java] +---- + public class MyTableCreator extends org.eclipse.persistence.schemaframework.TableCreator { + + public M7TableCreator() { + setName("MyTableCreator"); + addTableDefinition(buildADDRESSTable()); + ... + } + + public TableDefinition buildADDRESSTable() { + TableDefinition table = new TableDefinition(); + ... + return table; + } + ... + } +---- + +==== Creating a TableDefinition Class + +The `+TableDefinition+` class includes all the information required to +create a new table, including the names and properties of a table and +all its fields. + +The `+TableDefinition+` class has the following methods: + +* `+setName+` +* `+addField+` +* `+addPrimaryKeyField+` +* `+addIdentityField+` +* `+addForeignKeyConstraint+` + +All table definitions must call the `+setName+` method to set the name +of the table that is described by the `+TableDefinition+`. + +==== Adding Fields to a TableDefinition + +Use the `+addField+` method to add fields to the `+TableDefinition+`. To +add the primary key field to the table, use the `+addPrimaryKeyField+` +method rather than the `+addField+` method. + +To maintain compatibility among different databases, the type parameter +requires a Java class rather than a database field type. EclipseLink +translates the Java class to the appropriate database field type at run +time. For example, the `+String+` class translates to the `+CHAR+` type +for dBase databases. However, if you are connecting to Sybase, the +`+String+` class translates to `+VARCHAR+`. For more information, see +link:#How_to_Use_Schema_Manager_Java_and_Database_Type_Conversion[How to +Use Schema Manager Java and Database Type Conversion]. + +The `+addField+` method can also be called with the `+fieldSize+` or +`+fieldSubSize+` parameters for column types that require size and +subsize to be specified. + +Some databases require a subsize, but others do not. EclipseLink +automatically provides the required information, as necessary. + +==== Defining Sybase and Microsoft SQL Server Native Sequencing + +Use `+FieldDefinition+` method `+addIdentityField+` to add fields +representing a generated sequence number from Sybase or Microsoft SQL +Server native sequencing. See +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Native_Sequencing_with_a_Non-Oracle_Database_Platform[Native +Sequencing with a Non-Oracle Database Platform] for detailed information +on using sequencing. + +== Creating Tables with a Table Creator + +After creating a `+TableCreator+` class (see +link:#Creating_a_Table_Creator[Creating a Table Creator]), you can use +its API to create and drop tables. The important `+TableCreator+` +methods are the following (each method takes an instance of +`+DatabaseSession+`): + +* `+createTables+`–this method creates tables, adds constraints, and +creates sequence tables and sequences (if sequence tables already exist, +this method drops them and recreates them). +* `+dropTables+`–his method drops all constraints and drops all tables +(except sequence tables) that the `+TableCreator+` defines. +* `+createConstraints+`–this method creates constraints on all +pre-existing tables that the `+TableCreator+` defines. +* `+dropConstraints+`–this method drops constraints on all pre-existing +tables that the `+TableCreator+` defines. +* `+replaceTables+`–this method drops and then creates all tables that +the `+TableCreator+` defines. + +== Creating Database Tables Automatically + +You can configure EclipseLink to create database tables automatically in +JPA projects. + +=== Creating Database Tables Automatically in JPA Projects + +Using EclipseLink JPA persistence unit properties that you can define in +a `+persistence.xml+` file, you can configure schema generation + +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Extensions_for_Schema_Generation[Using +EclipseLink JPA Extensions for Schema Generation]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_Task[Category: Task] diff --git a/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWSBuilder_File_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWSBuilder_File_(ELUG).adoc new file mode 100644 index 00000000000..ca9e40a8323 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWSBuilder_File_(ELUG).adoc @@ -0,0 +1,6 @@ +For EclipseLink DBWS documentation,including JAX-WS and JAX-RS, see +http://www.eclipse.org/eclipselink/dbws.php + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.1[Category: Release 1.1] Category:_DBWS[Category: +DBWS] diff --git a/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWS_Service_Descriptor_File_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWS_Service_Descriptor_File_(ELUG).adoc new file mode 100644 index 00000000000..ca9e40a8323 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/dbws/EclipseLink_UserGuide_DBWS_Overview_EclipseLink_DBWS_Service_Descriptor_File_(ELUG).adoc @@ -0,0 +1,6 @@ +For EclipseLink DBWS documentation,including JAX-WS and JAX-RS, see +http://www.eclipse.org/eclipselink/dbws.php + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.1[Category: Release 1.1] Category:_DBWS[Category: +DBWS] diff --git a/docs/docs.ug/src/main/asciidoc/jpa/Developing_Applications_Using_EclipseLink_JPA_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/jpa/Developing_Applications_Using_EclipseLink_JPA_(ELUG).adoc new file mode 100644 index 00000000000..f3a34949d36 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/Developing_Applications_Using_EclipseLink_JPA_(ELUG).adoc @@ -0,0 +1,962 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Developing_Applications_Using_EclipseLink_JPA_(ELUG)[Related +Topics] + +== Using Application Components + +When developing an application with EclipseLink JPA, you need to know +how to use the following application components: + +* link:#How_to_Obtain_an_Entity_Manager_Factory[Entity manager factory] +* link:#How_to_Obtain_an_Entity_Manager[Entity manager] +* link:#How_to_Use_a_Persistence_Context[Persistence context] + +=== How to Obtain an Entity Manager Factory + +How you obtain the entity manager factory depends on the Java +environment in which you are developing your application: + +* link:#Obtaining_an_Entity_Manager_Factory_in_Java_EE_Application_Server_Environment[Obtaining +an Entity Manager Factory in Java EE Application Server Environment] +* link:#Obtaining_an_Entity_Manager_Factory_in_Java_SE_Environment[Obtaining +an Entity Manager Factory in Java SE Environment] + +==== Obtaining an Entity Manager Factory in Java EE Application Server Environment + +You can inject an entity manager factory using the `+@PersistenceUnit+` +annotation, as the following example shows, or you can obtain it through +JNDI lookup. You may choose to specify the `+unitName+` element to +designate the persistence unit whose factory you are using. + +`+@PersistenceUnit+` `+EntityManagerFactory emf;+` + +For more information, see the following: + +* Section 8.4.2 "`PersistenceUnit Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 5.3.1 "`Obtaining an Entity Manager Factory in a Java EE +Container`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification] +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Container-Managed_Entity_Manager[Container-Managed +Entity Manager] + +==== Obtaining an Entity Manager Factory in Java SE Environment + +In Java SE environment, use the `+javax.persistence.Persistence+` +bootstrap class to get access to an entity manager factory. In your +application, create an entity manager factory by calling the +`+javax.persistence.Persistence+` class’ `+createEntityManagerFactory+` +method (see Section 7.2.1 "`javax.persistence.Persistence Class`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), as the +following example shows: + +[source,java] +---- + EntityManagerFactory emf = javax.persistence.Persistence.createEntityManagerFactory("Order"); + EntityManager em = emf.createEntityManager(); +---- + +For more information, see the following: + +* Section 7.2.1 "`javax.persistence.Persistence Class`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 5.3.2 "`Obtaining an Entity Manager Factory in a Java SE +Container`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification] +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Application-Managed_Entity_Manager[Application-Managed +Entity Manager] + +=== How to Obtain an Entity Manager + +All entity managers come from factories of type +`+EntityManagerFactory+`. The configuration for an entity manager is +bound to the `+EntityManagerFactory+` that created it, but it is defined +separately as a persistence unit. A persistence unit dictates either +implicitly or explicitly the settings and entity classes used by all +entity managers obtained from the unique `+EntityManagerFactory+` +instance bound to that persistence unit. There is, therefore, a +one-to-one correspondence between a persistence unit and its concrete +`+EntityManagerFactory+`.Persistence units are named to allow +differentiation of one `+EntityManagerFactory+` from another. This gives +the application control over which configuration or persistence unit is +to be used for operating on a particular entity. + +How you obtain the entity manager and its factory depends on the Java +environment in which you are developing your application: + +* link:#Obtaining_an_Entity_Manager_in_Java_EE_Application_Server_Environment[Obtaining +an Entity Manager in Java EE Application Server Environment] +* link:#Obtaining_an_Entity_Manager_in_Java_SE_Environment[Obtaining an +Entity Manager in Java SE Environment] + +==== Obtaining an Entity Manager in Java EE Application Server Environment + +In the Java EE environment, you can inject an entity manager using the +`+@PersistenceContext+` annotation, as the following example shows, or +you can obtain it through a direct JNDI lookup. You may choose to +specify the `+unitName+` element of the `+@PersistenceContext+` +annotation to designate the persistence unit whose factory the container +is using (see Section 8.4.2 "`PersistenceUnit Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]). You can also +specify the `+type+` element to indicate whether a transaction-scoped +(default) or extended persistence context is to be used (see Section 5.6 +"`Container-managed Persistence Contexts`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]). + +[source,java] +---- + @PersistenceContext + EntityManager em; + + @PersistenceContext(type=PersistenceContextType.EXTENDED) + EntityManager orderEM; +---- + +The container manages the life cycle of the persistence context, as well +as the creation and closing of the entity manager–your application does +not have to be involved in this process. + +For more information, see the following: + +* Section 8.4.2 "`PersistenceUnit Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 5.6 "`Container-managed Persistence Contexts`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 5.2.1 "`Obtaining an Entity Manager in a Java EE Container`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Container-Managed_Entity_Manage[Container-Managed +Entity Manager] + +==== Obtaining an Entity Manager in Java SE Environment + +You obtain an application-managed entity manager from an entity manager +factory. + +For more information and examples, see the following: + +* Section 5.2.2 "`Obtaining an Entity Manager in a Java SE Container`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:#How_to_Obtain_an_Entity_Manager_Factory[How to Obtain an Entity +Manager Factory] +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Application-Managed_Entity_Manager[Application-Managed +Entity Manager] + +=== What You May Need to Know About Entity Managers and Their Factories + +An entity manager persists and manages specific types of objects, +enables reading from and writing to a given database. You have to +configure the entity manager to do so. You are also responsible for +configuring the entity manager to be implemented by a particular +persistence provider, such as EclipseLink. The provider supplies the +backing implementation engine for the entire Java Persistence API, which +includes an entity manager, a `+Query+` implementation, and SQL +generation. + +An entity manager implements the API enabling operations on entities. It +is encapsulated almost entirely within a single interface called +`+EntityManager+`. Until you use an entity manager to create, read, or +write an entity, the entity is nothing more than a regular nonpersistent +Java object. + +For more information, see Chapter 5 "`Entity Managers and Persistence +Contexts`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +Applications use the `+EntityManagerFactory+` interface for creating an +application-managed entity manager (see +link:#Obtaining_an_Entity_Manager_in_Java_SE_Environment[Obtaining an +Entity Manager in Java SE Environment]). + +Each entity manager factory provides entity manager instances that are +all configured in the same manner (for example, configured to connect to +the same database or use the same initial settings as defined by the +implementation). + +=== How to Use a Persistence Context + +Information pending + +==== Using an Extended Persistence Context + +Information pending + +=== What You May Need to Know About Persistence Contexts and Persistence Units + +When an entity manager (see +link:#What_You_May_Need_to_Know_About_Entity_Managers_and_Their_Factories[What +You May Need to Know About Entity Managers and Their Factories]) obtains +a reference to an entity (either by having it explicitly passed in or +because it was read from the database) that object becomes managed by +the entity manager. The set of managed entity instances within an entity +manager at any given time is called this entity manager’s persistence +context. Only one Java instance with the same persistent identity may +exist in a persistence context at any time. For example, if an Employee +with a persistent identity (or id) of 158 exists in the persistence +context, then no other object with its id set to 158 may exist within +that same persistence context. + +An `+EntityManager+` instance is associated with a persistence context. +A persistence context is a set of entity instances in which for any +persistent entity identity there is a unique entity instance. The entity +instances and their life cycle are managed within the persistence +context. The `+EntityManager+` interface defines the methods for +interacting with the persistence context. The `+EntityManager+` API is +used to create and remove persistent entity instances, to find entities +by their primary key, and to query over entities. + +For more information, see Section 5.1 "`Persistence Contexts`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +==== Persistence Unit + +The set of entities that a given `+EntityManager+` instance manages is +defined by a persistence unit. A persistence unit defines the set of all +classes that are related or grouped by your application, and which must +be collocated in their mapping to a single database. + +A persistence unit includes the following: + +* An entity manager factory and its entity managers, together with their +configuration information. +* The set of classes managed by the entity managers. +* Mapping metadata (in the form of metadata annotations and/or XML +metadata) that specifies the mapping of the classes to the database. + +== Querying for an Entity + +=== How to Use the Entity Manager find Method + +Information pending + +=== What You May Need to Know About Querying with Java Persistence Query Language + +You can use the Java Persistence query language (JP QL) to define +queries over entities and their persistent state. + +JP QL is an extension of EJB QL, and adds the following features: + +* Single and multiple value result types; +* Aggregate functions with sorting and grouping clauses; +* A more natural jon syntax, including support for both inner and outer +joins; +* Conditional expressions involving subqueries; +* Update and delete queries for bulk data changes; +* Result projection into nonpersistent classes. + +JP QL supports the use of dynamic queries and the use of named +parameters. You can use it to define queries over the persistent +entities, as well as their persistent state and relationships + +You may define queries in metadata annotations or the XML descriptor. + +A JP QL statement may be either a select statement, an update statement, +or a delete statement. All statement types may have parameters. Any +statement may be constructed dynamically or may be statically defined in +a metadata annotation or XML descriptor element. + +This example demonstrates how to create a simple query that finds all +orders using JP QL. + +[#Example 21-1]## *_Simple Query to Find All Objects_* + +[source,sql] +---- + SELECT order + FROM Order order +---- + +This example demonstrates how to create a simple query that finds all +orders to ship to California using JP QL. + +[#Example 21-2]## *_Simple Query to Find Some Objects_* + +[source,sql] +---- + SELECT order + FROM Order order + WHERE order.shippingAddress.state = 'CA' +---- + +For more information and examples, see the following: + +* Chapter 4 "`Query Language`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 3.6 "`Query API`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:#What_You_May_Need_to_Know_About_Named_and_Dynamic_Queries[What +You May Need to Know About Named and Dynamic Queries] +* link:#What_You_May_Need_to_Know_About_Persisting_with_JP_QL[What You +May Need to Know About Persisting with JP QL] + +=== What You May Need to Know About Named and Dynamic Queries + +You can use the `+Query+` API to define both named and dynamic queries. + +Named queries are static and expressed in metadata. You can define named +queries using JP QL or SQL, scoping their names to the persistence unit. + +[width="100%",cols="<100%",] +|=== +|*Note:* The query name must be unique within the scope of the +persistence unit. +|=== + +These queries are efficient to execute as the persistence provider can +translate JP QL to SQL once, when you application starts, as opposed to +every time the query is executed. You define a named query using the +`+@NamedQuery+` annotation (see Section 8.3.1 "`NamedQuery Annotation`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]), which +you may place on the class definition for any entity. The annotation +defines the name of the query, as well as the query text, as this +example shows: + +[#Example 21-3]## *_Defining a Named Query_* + +[source,java] +---- + @NamedQuery(name="findSalaryForNameAndDepartment", + query="SELECT e.salary " + + "FROM Employee.e " + + "WHERE e.department.name = :deptName AND " + + " e.name = :empName") +---- + +Place your named query on the entity class that most directly +corresponds to the query result. In the preceding example, that would be +the `+Employee+` entity. + +If you need to define more than one named query for a class, place them +inside of a `+@NamedQueries+` annotation (see Section 8.3.1 "`NamedQuery +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) that accepts an array of `+@NamedQuery+` annotations, as +this example shows: + +[#Example 21-4]## *_Defining Multiple Named Queries for an Entity_* + +[source,java] +---- + @NamedQueries({ + @NamedQuery(name="Employee.findAll", + query="SELECT e FROM Employee.e"), + @NamedQuery(name="Employee.findByPrimaryKey", + query="SELECT e FROM Employee.e WHERE e.id = :id"), + @NamedQuery(name="Employee.findByName", + query="SELECT e FROM Employee.e WHERE e.name = :name"), + }) +---- + +Because the query string is defined in the annotation, your application +cannot alter it at run time. If you need to specify additional criteria, +you must do it using query parameters. This example shows how you can +use the `+createNamedQuery+` method of the `+EntityManager+` to create a +named query that requires a query parameter. + +[#Example 21-5]## + +[source,java] +---- +''''' Creating a Named Query with Parameters''''' + @PersistenceContext + public EntityManager em; + ... + customers = em.createNamedQuery("findAllCustomersWithName") + .setParameter("custName", "Smith").getResultList(); +---- + +You may choose to define named queries in an XML mapping file (see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Using_XML[Using +XML]) using the `+named-query+` element. A `+named-query+` element in +the mapping file may also override an existing query of the same name +that was defined as an annotation. A `+named-query+` element may appear +as a subelement of `+entity-mapping+` or `+entity+` elements. Regardless +of where you defined it, it will be keyed by its name in the persistence +unit query namespace. You may provide +link:#What_You_May_Need_to_Know_About_Query_Hints[query hints] as +`+hint+` subelements. + +This example shows the definition a named query in an XML mapping file. +This query uses `+eclipselink.cache-usage+` hint to bypass the cache. + +[#Example 21-6]## *_Defining a Named Query in an XML Mapping File_* + +[source,xml] +---- + + ... + + + SELECT e FROM Employee e WHERE e.name LIKE :empName + + + ... + +---- + +[cols="<",] +|=== +|*Note:* We recommend using named queries with query parameters. +|=== + +Dynamic queries are strings. You generate these queries at run time by +passing the JP QL query string to the `+createQuery+` method of the +`+EntityManager+`. There are no restrictions on the query definition; +all JP QL query types are supported, as well as the use of parameters. + +You may consider using dynamic queries in your application, if there +might be a need to specify complex criteria and the exact shape of the +query cannot be known in advance. However, note that if your application +issues many queries, the use of dynamic queries will have a negative +impact on performance. + +For more information and examples, see the following: + +* Section 3.6.4 "`Named Queries`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 3.6 "`Query API`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Query_Customization_Extensions[Using +EclipseLink JPA Query Customization Extensions] +* link:EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG)#Cache[Cache] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries] +* link:#What_You_May_Need_to_Know_About_Query_Hints[What You May Need to +Know About Query Hints] + +== Persisting Domain Model Changes + +=== How to Use JTA + +Information pending + +=== How to Use RESOURCE_LOCAL + +Information pending + +=== How to Configure Flushing and Set Flush Modes + +Information pending + +=== How to Manage a Life Cycle of an Entity + +Information pending + +==== Merging Detached Entity State + +Information pending + +==== Using Detached Entities and Lazy Loading + +Information pending + +For more information, see the following: + +* Section 3.2.4.2 "`Detached Entities and Lazy Loading`" of JPA +specification +* link:Introduction%20to%20Mappings%20(ELUG)[Indirection, +Serialization, and Detachment] + +=== What You May Need to Know About Persisting with JP QL + +You may define queries in metadata annotations or the XML descriptor. + +You can use update and delete queries to persist your changes with JP +QL. + +You can perform bulk update of entities with the `+UPDATE+` statement. +This statement operates on a single entity type and sets one or more +single-valued properties of the entity subject to the condition in the +`+WHERE+` clause. Update queries provide an equivalent to the +`+SQL UPDATE+` statement, but with JP QL conditional expressions. + +This example demonstrates how to use an update query to give employees a +raise. The `+WHERE+` clause contains the conditional expression. + +[#Example 21-7]## *_Update Query_* + +[source,sql] +---- + UPDATE Employee e + SET e.salary = 60000 + WHERE e.salary = 50000 +---- + +You can perform bulk removal of entities with the `+DELETE+` statement. +Delete queries provide an equivalent to the `+SQL DELETE+` statement, +but with JP QL conditional expressions. + +This example demonstrates how to use a delete query to remove all +employees who are not assigned to a department. The `+WHERE+` clause +contains the conditional expression. + +[#Example 21-8]## *_Delete Query_* + +[source,sql] +---- + DELETE FROM Employee e + WHERE e.department IS NULL +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* Delete queries are polymorphic: any entity subclass instances +that meet the criteria of the delete query will be deleted. However, +delete queries do not honor cascade rules: no entities other than the +type referenced in the query and its subclasses will be removed, even if +the entity has relationships to other entities with cascade removes +enabled. +|=== + +The persistence context is not updated to reflect results of update and +delete operations. If you use a transaction-scoped persistence context, +you should either execute the bulk operation in a transaction all by +itself, or be the first operation in the transaction (see +link:Introduction%20to%20EclipseLink%20Transactions_(ELUG)[Introduction +to EclipseLink Transactions]). That is because any entity actively +managed by the persistence context will remain unaware of the actual +changes occurring at the database level. + +For more information and examples, see the following: + +* Section 4.10 "`Bulk Update and Delete Operations`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Chapter 4 "`Query Language`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:#What_You_May_Need_to_Know_About_Querying_with_Java_Persistence_Query_Language[What +You May Need to Know About Querying with Java Persistence Query +Language] +* link:EclipseLink_UserGuide_Queries_(ELUG)[Queries] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries] + +=== What You May Need to Know About Persisting Results of Named and Dynamic Queries + +Expressions listed in the `+SELECT+` clause of a query determine the +result type of the query. The following are some of the type that may +result from JP QL queries: + +* Basic types: `+String+`, primitive types, JDBC types +* Entity types +* An array of `+Object+` instances +* User-defined types created from a constructor-expressions + +The collection or single result corresponds directly to the result type +of the query. + +The `+Query+` interface provides three different ways to execute a +query, depending on whether or not the query returns results and how +many results are expected. For queries that return values, you can call +either the following methods: + +* `+getResultList+`–use this method if you expect the query to return +more than one result. This method returns a collection (`+List+`) +containing query results. If there are no results to return, this method +returns an empty collection. +* `+getSingleResult+`–use this method if you expect the query to return +a single result. In case of unexpected results, such as there are no +results to return or multiple results are available, this method throws +an exception. + +Use the `+executeUpdate+` method of the `+Query+` interface to invoke +bulk update and delete queries (see +link:#What_You_May_Need_to_Know_About_Persisting_with_JP_QL[What You May +Need to Know About Persisting with JP QL]). + +The active persistence context manages a returned entity instance. If +that entity instance is modified and the persistence context is part of +a transaction, then the changes will be persisted to the database. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you use a transaction-scoped entity manager outside of a +transaction, then the executed query will return detached entity +instances instead of managed entity instances. To make changes to these +detached entities, you must merge them into a persistence context before +synchronizing with the database. +|=== + +You can reuse `+Query+` objects as often as you need so long as the same +persistence context that you used to create the query is active. For +transaction-scoped entity managers, this limits the lifetime of the +`+Query+` object to the life of the transaction. Other entity manager +types may reuse `+Query+` objects until you close or remove the entity +manager. + +For more information, see the following: + +* Section 3.6 "`Query API`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 3.6.4 "`Named Queries`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Query_Customization_Extensions[Using +EclipseLink JPA Query Customization Extensions] +* link:EclipseLink_UserGuide_Queries_(ELUG)[Queries] +* link:Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named_Queries[Named +Queries] +* Section 5.6.4.1 "`Container-managed Transaction-scoped Persistence +Context`" of the http://jcp.org/en/jsr/detail?id=220[JPA Specification] + +== Using EclipseLink JPA Extensions in Your Application Development + +This section describes the following: + +* link:#How_to_Use_Extensions_for_Query[How to Use Extensions for Query] +* link:#How_to_Configure_Lazy_Loading[How to Configure Lazy Loading] +* link:#How_to_Configure_Change_Tracking[How to Configure Change +Tracking] +* link:#How_to_Configure_Fetch_Groups[How to Configure Fetch Groups] +* link:#How_to_Use_Extensions_for_Caching[What You May Need to Know +About EclipseLink Caching] +* link:#What_You_May_Need_to_Know_About_EclipseLink_Caching[What You May +Need to Know About EclipseLink Caching] +* link:#What_You_May_Need_to_Know_About_Cache_Coordination[What You May +Need to Know About Cache Coordination] +* link:#How_to_Configure_Cascading[How to Configure Cascading] +* link:#What_You_May_Need_to_Know_About_Cascading_Entity_Manager_Operations[What +You May Need to Know About Cascading Entity Manager Operations] +* link:#How_to_Use_EclipseLink_Metadata[How to Use EclipseLink Metadata] +* link:#How_to_Use_Events_and_Listeners[How to Use Events and Listeners] +* link:#What_You_May_Need_to_Know_About_Database_Platforms[What You May +Need to Know About Database Platforms] +* link:#What_You_May_Need_to_Know_About_Server_Platforms[What You May +Need to Know About Server Platforms] +* link:#How_to_Optimize_a_JPA_Application[How to Optimize a JPA +Application] +* link:#How_to_Perform_Diagnostics[How to Perform Diagnostics] + +=== How to Use Extensions for Query + +Information pending + +==== Using Query Hints + +Information pending + +==== What You May Need to Know About Query Hints + +Query hints are the JPA extension point for vendor-specific query +features. Hints are the only feature in the query API that are not a +standard usage: a hint is a string name and object value. + +You may associate your queries with hints by either setting them in the +persistence unit metadata as part of the `+@NamedQuery+` annotation (see +Section 8.3.1 "`NamedQuery Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), or by using the +`+setHint+` method of the `+Query+`. + +The link:#Example_21-9[Using Query Hints] example shows how to use the +`+eclipselink.cache-usage+` hint to indicate that the cache should not +be checked when reading an `+Employee+` for the database. + +[width="100%",cols="<100%",] +|=== +|*Note:* Unlike the `+refresh+` method of the `+EntityManager+`, the +`+eclipselink.cache-usage+` hint will not cause the query result to +override the current cached value. +|=== + +[#Example 21-9]## *_Using Query Hints_* + +[source,java] +---- + public Employee findEmployeeNoCache(int empId) { + Query q = em.createQuery("SELECT e FROM Employee e WHERE e.id = ?1"); + // force read from database + q.setHint("eclipselink.cache-usage", "DoNotCheckCache"); + q.setParameter(1, empId); + try { + return (Employee)q.getSingleResult(); + } + catch(NoResultException e) { + return null; + } + } +---- + +If you need execute this query frequently, you should use a named query. +The following named query definition incorporates the cache hint from +the link:#Example_21-9[Using Query Hints] example. + +`+@NamedQuery(name="findEmployeeNoCache",+` +`+            query="SELECT e FROM Employee e WHERE e.id = :empId",+` +`+            hints={@QueryHint(name="eclipselink.cache-usage", +` +`+                              value="DoNotCheckCache")})+` + +The `+hints+` element accepts an array of `+@QueryHint+` annotations +(see Section 8.3 "`Annotations for Queries`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), allowing you to +set any number of hints for a query. + +For more information, see the following: + +* Section 3.6 "`Query API`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Query_Customization_Extensions[Using +EclipseLink JPA Query Customization Extensions] +* link:EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG)#Cache[Cache] +* link:Using%20Advanced%20Query%20API%20(ELUG)#How_to_Use_Oracle_Hints[How +to Use Oracle Hints] + +==== Using the Expression API + +Information pending + +=== How to Configure Lazy Loading + +By default, the EclipseLink persistence provider will use dynamic +weaving to configure all applicable mappings with lazy loading +(indirection). + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many and many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading, nor value holder indirection). + +For more information, see the following: + +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions for Customization and Optimization] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[What You May Need +to Know About EclipseLink JPA Lazy Loading] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Weaving] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring Indirection (Lazy +Loading)] + +=== How to Configure Change Tracking + +By default, the EclipseLink persistence provider will use dynamic +weaving to configure all applicable mappings with attribute level change +tracking. + +For JPA entities or POJO classes that you configure for weaving, +EclipseLink weaves value holder indirection for one-to-one mappings. If +you want EclipseLink to weave change tracking and your application +includes collection mappings (one-to-many and many-to-many), then you +must configure all collection mappings to use transparent indirect +container indirection only (you may not configure your collection +mappings to use eager loading, nor value holder indirection). + +For more information, see the following: + +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Extensions_for_Tracking_Changes[Using +EclipseLink JPA Extensions for Tracking Changes] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Weaving[Using +EclipseLink JPA Weaving] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Change_Policy[Configuring +Change Policy] + +=== How to Configure Fetch Groups + +By default, the EclipseLink persistence provider will use dynamic +weaving to configure all applicable mappings to use fetch groups. + +For more information, see the following: + +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions for Customization and Optimization] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Weaving] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Fetch_Groups[Configuring +Fetch Groups] + +=== How to Use Extensions for Caching + +Information pending + +=== What You May Need to Know About EclipseLink Caching + +The EclipseLink cache is an in-memory repository that stores recently +read or written objects based on class and primary key values. +EclipseLink uses the cache to do the following: + +* Improve performance by holding recently read or written objects and +accessing them in-memory to minimize database access. +* Manage locking and isolation level. +* Manage object identity. + +EclipseLink uses the following two types of cache: + +* the session cache maintains objects retrieved from and written to the +data source; +* the unit of work cache holds objects while they participate in +transactions. + +When a unit of work successfully commits to the data source, EclipseLink +updates the session cache accordingly. + +For more information, see +link:EclipseLink_UserGuide_Caching_with_EclipseLink_(ELUG)[Cache]. + +=== What You May Need to Know About Cache Coordination + +EclipseLink provides a distributed cache coordination feature that +ensures data in distributed applications remains current. + +For more information, see the following: + +* link:Introduction%20to%20Cache%20(ELUG)#Cache_Coordination[Cache +Coordination] +* link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Locking_Policy[Configuring +Locking Policy] "`wikilink`") +* link:Introduction%20to%20Cache%20(ELUG)#Querying_and_the_Cache[Querying +and the Cache] +* link:EclipseLink_UserGuide_Queries_(ELUG)[Cache] + +=== How to Configure Cascading + +Information pending + +For more information, see the following: + +* link:#What_You_May_Need_to_Know_About_Cascading_Entity_Manager_Operations[What +You May Need to Know About Cascading Entity Manager Operations] +* link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)[Mapping +Relationships] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions for Optimistic Locking] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[How to Use the +@PrivateOwned Annotation] + +=== What You May Need to Know About Cascading Entity Manager Operations + +Typically, you use cascading in parent-child relationships. + +By default, every entity manager operation applies only to the entity +that you supplied as an argument to the operation. The operation will +not cascade to other entities that have a relationship with the entity +under operation. For some operations, such as `+remove+`, this is +usually the desired behavior. For other operations, such as `+persist+`, +it is not: in most cases, if you have a new entity that has a +relationship to another new entity, you would want to persist both +entities together. + +Using the `+cascade+` element of relationship annotations (see +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Mapping_Relationships[Mapping +Relationships]), you can define whether or not to cascade operations +across relationships. + +When listed as a part of the `+cascade+` element, you can identify the +entity manager operations with the following constant values using the +`+javax.persitence.CascadeType+` enumerated type: + +* `+PERSIST+`–corresponds to the entity manager `+persist+` operation; +* `+REFRESH+`–corresponds to the entity manager `+refresh+` operation; +* `+REMOVE+`–corresponds to the entity manager `+remove+` operation; +* `+MERGE+`–corresponds to the entity manager `+merge+` operation; +* `+ALL+`–indicates that all four operations should be cascaded. + +[width="100%",cols="<100%",] +|=== +|*Note:* Cascade sessions are unidirectional: you must set them on both +sides of a relationship if you plan for the same behavior for both +situations. +|=== + +For more information, see the following: + +* link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Mapping_Relationships[Mapping +Relationships] +* link:#How_to_Configure_Cascading[How to Configure Cascading] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@OptimisticLocking_Annotation[How +to Use the @OptimisticLocking Annotation] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How_to_Use_the_@PrivateOwned_Annotation[How +to Use the @PrivateOwned Annotation] + +=== How to Use EclipseLink Metadata + +Information pending + +==== Using EclipseLink Project + +Information pending + +==== Using sessions.xml File + +Information pending + +=== How to Use Events and Listeners + +Information pending + + + + + +==== Using Session Events + +Information pending + +==== Using an Exception Handler + +Information pending + +=== What You May Need to Know About Database Platforms + +EclipseLink interacts with databases using SQL. The type of database +platform you choose determines the specific means by which the +EclipseLink runtime accesses the database. + +For more information, see +link:Introduction%20to%20Data%20Access%20(ELUG)#Database_Platforms[Database +Platforms]. + +=== What You May Need to Know About Server Platforms + +You deploy your application to a specific Java EE application server. + +EclipseLink supports most versions of WebLogic, OC4J, SunAS, and +WebSphere application servers. + +For more information, see the following: + +* link:Configuring%20a%20Session%20(ELUG)#Configuring_the_Server_Platform[Configuring +the Server Platform] +* link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)[Integrating +EclipseLink with an Application Server] + +=== How to Optimize a JPA Application + +Information pending + +==== Using Statement Caching + +Information pending + +==== Using Batch Reading and Writing + +Information pending + +=== How to Perform Diagnostics + +Information pending + +==== Using Logging + +Information pending + +==== Using Profiling + +Information pending + +==== Using JMX + +Information pending + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_JPA[Category: JPA] diff --git a/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_Developing_JPA_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_Developing_JPA_Projects_(ELUG).adoc new file mode 100644 index 00000000000..c330a864f92 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_Developing_JPA_Projects_(ELUG).adoc @@ -0,0 +1,76 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*NOTOC* + +== Step 1 + +Define your persistence units in `+persistence.xml+`. + +* link:Introduction_to_Java_Persistence_API_(ELUG)#persistence.xml_File[About +the persistence.xml file] +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)#How_to_Specify_the_Persistence_Unit_Name[Specifying +the persistence unit] + +== Step 2 + +Annotate classes with @Entity, @Embeddable, and @MappedSuperClass and/or +define classes in your mapping file (orm.xml). + +* link:Introduction_to_EclipseLink_JPA_%28ELUG%29#Configuring_an_Entity[Configuring +an entity] +* link:Using_EclipseLink_JPA_Extensions_%28ELUG%29[EclipseLink +extensions] + +== Step 3 + +Configure your application with: + +* javax.persistence.transactionType +* javax.persistence.jtaDataSource +* javax.persistence.nonJtaDataSource + +* link:Developing_Applications_Using_EclipseLink_JPA_%28ELUG%29[Application +development] +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29[Packaging +and deployment] + +== EclipseLink User’s Guide + +The following sections describe the Java Persistence API, including the +EclipseLink implementation: + +* link:Introduction_to_Java_Persistence_API_(ELUG)[Introduction to Java +Persistence API] + +* link:Introduction_to_EclipseLink_JPA_(ELUG)[Introduction to +EclipseLink JPA] + +* link:Using_EclipseLink_JPA_Extensions_(ELUG)[Using EclipseLink JPA +Extensions] + +* link:Configuring_a_EclipseLink_JPA_Application_(ELUG)[Configuring a +EclipseLink JPA Application] – contains information on how to configure +the EclipseLink persistence project, as well as set up the application +configuration and packaging. + +* link:Developing_Applications_Using_EclipseLink_JPA_(ELUG)[Developing +Applications Using EclipseLink JPA] – describes the actual steps you +have to perform to develop your EclipseLink JPA application. + +* link:Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Packaging +and Deploying EclipseLink JPA Applications] + +*Special:Whatlinkshere_EclipseLink_UserGuide_Developing_JPA_Projects_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_JPA[Category: JPA] diff --git a/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_JPA_Print_Version.adoc b/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_JPA_Print_Version.adoc new file mode 100644 index 00000000000..1141994d289 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/EclipseLink_UserGuide_JPA_Print_Version.adoc @@ -0,0 +1,13 @@ +*TOC* *NOEDITSECTION* + +== Introduction to Java Persistence API + +== Introduction to EclipseLink JPA + +== Using EclipseLink JPA Extensions + +== Configuring a EclipseLink JPA Application + +== Developing Applications Using EclipseLink JPA + +== Packaging and Deploying EclipseLink JPA Applications diff --git a/docs/docs.ug/src/main/asciidoc/jpa/Introduction_to_EclipseLink_JPA_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/jpa/Introduction_to_EclipseLink_JPA_(ELUG).adoc new file mode 100644 index 00000000000..c9eb2354596 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/Introduction_to_EclipseLink_JPA_(ELUG).adoc @@ -0,0 +1,3278 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_EclipseLink_JPA_(ELUG)[Related +Topics] + +This section introduces EclipseLink implementation of Java Persistence +API. + +As a specification, JPA needs to be implemented by vendors or open +source projects. + +EclipseLink provides a complete, EJB 3.0-compliant JPA implementation. +It provides complete compliance for all of the mandatory features, many +of the optional features, and some additional features. The additional +nonmandatory functionality includes the following: + +* object-level cache; +* distributed cache coordination; +* extensive performance tuning options; +* enhanced Oracle Database support; +* advanced mappings; +* optimistic and pessimistic locking options; +* extended annotations and query hints. + +EclipseLink offers support for deployment within an EJB 3.0 container. +This includes Web containers and other non-EJB 3.0 Java EE containers. +For more information, see +link:Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#Deploying_an_EclipseLink_JPA_Application[Deploying +an EclipseLink JPA Application]. + +Through its pluggable persistence capabilities EclipseLink can function +as the persistence provider in a compliant EJB 3.0 container. + +For more information, see +link:Introduction%20to%20EclipseLink%20(ELUG)[Introduction to +EclipseLink]. + +You can perform object-relational mapping with EclipseLink JPA by the +means of doing the following: + +* link:#Using_Metadata_Annotations[Using Metadata Annotations] +* link:#Using_XML[Using XML] +* link:#Overriding_and_Merging_XML[Overriding and Merging XML] +* link:#Defaulting_Properties[Defaulting Properties] +* link:#Configuring_an_Entity[Configuring an Entity] +* link:#Declaring_Basic_Property_Mappings[Declaring Basic Property +Mappings] +* link:#Mapping_Relationships[Mapping Relationships] +* link:#Mapping_Inheritance[Mapping Inheritance] +* link:#Using_Embedded_Objects[Using Embedded Objects] + +== Using Metadata Annotations + +An annotation is a simple, expressive means of decorating Java source +code with metadata that is compiled into the corresponding Java class +files for interpretation at run time by a JPA persistence provider to +manage persistent behavior. + +You can use annotations to configure the persistent behavior of your +entities. For example, to designate a Java class as a JPA entity, use +the `+@Entity+` annotation (see Section 8.1 "`Entity`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) as follows: + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + } +---- + +You can apply annotations at three different levels: at the class, +method, and field levels. + +For more information and examples, see the following: + +* Chapter 8 "`Metadata annotations`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions] + +EclipseLink defines a set of proprietary annotations. You can find them +in the `+org.eclipselink.annotations+` package. + +EclipseLink annotations expose some features of EclipseLink that are +currently not available through the use of JPA metadata. + +== Using XML + +You can use XML mapping metadata on its own, or in combination with +annotation metadata, or you can use it to override the annotation +metadata. + +If you choose to include one or more mapping XML files in your +persistence unit, each file must conform and be valid against the +`+orm_1_0.xsd+` schema located at +http://java.sun.com/xml/ns/persistence/orm_1_0.xsd[`+http://java.sun.com/xml/ns/persistence/orm_1_0.xsd+`]. +This schema defines a namespace called +http://java.sun.com/xml/ns/persistence/orm[`+http://java.sun.com/xml/ns/persistence/orm+`] +that includes all of the ORM elements that you can use in your mapping +file. + +This example shows a typical XML header for a mapping file: + +[#Example 18-1]## *_XML Header for Mapping File_* + +[source,xml] +---- + + +---- + +The root element of the mapping file is called `+entity-mappings+`. All +object relational XML metadata is contained within this element. The +subelements of `+entity-mappings+` can be categorized into four main +scoping and functional groups: persistence unit defaults, mapping file +defaults, queries and generators, and managed classes and mappings. +There is also a special setting that determines whether annotations +should be considered in the metadata for the persistence unit. + +For more information and examples, see Section 10.1 "`XML Overriding +Rules`" of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +EclipseLink provides a set of persistence unit properties that you can +specify in your `+persistence.xml+` file, or in a property map file +(`+eclipse.persistence.config.PersistenceUnitProperties+`). For more +information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_Using_EclipseLink_JPA_Persistence_Unit_Properties[What +You May Need to Know About Using EclipseLink JPA Persistence Unit +Properties]. + +Similar to EclipseLink annotation extensions, EclipseLink persistence +unit properties expose some features of EclipseLink that are currently +not available through the use of JPA metadata. + +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions]. + +== Overriding and Merging XML + +You can use EclipseLink’s native metadata xml file, EclipseLink-ORM.XML, +to override mappings defined in JPA’s configuration file `+orm.xml+` and +provide EclipseLink with extended ORM features. For more information on +JPA extensions for mapping, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions]. + +The EclipseLink-ORM.XML file defines the object-relational mapping +metadata for EclipseLink. It is built from the existing `+orm.xml+` file +which makes it more intuitive, requires minimum configuration, and easy +to override. For more information, see Section 10.1 "`XML Overriding +Rules`" of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +To override `+orm.xml+` file’s mapping, you must define the +`+META-INF/eclipselink-orm.xml+` file in the project. When both +`+orm.xml+` and `+eclipselink-orm.xml+` are specified, the contents of +`+eclipselink-orm.xml+` override `+orm.xml+` and any other JPA mapping +file specified in the persistence unit. If there are overlapping +specifications in multiple ORM files, the files are merged if they are +no conflicting entities. + +*Note:* The order of files defined in `+persistence.xml+` does not +define the order of their processing. The files are processed, merged +and overidden as required. For more information, see +link:#Overriding_and_Merging_Examples[Overriding and Merging Examples]. + +The EclipseLink-ORM.XML file can be referenced for inclusion in a +persistence unit’s metadata through any of the following files or +methods: + +[width="100%",cols="42%,58%",options="header",] +|=== +|File/Method |Description +|`+META-INF/eclipselink-orm.xml+` |Provides mapping overriding +capabilities. + +|`+META-INF/orm.xml+` |The default ORM file provided with JPA. + +|Referenced as persistence unit mapping file in `+persistence.xml+` +|Does not provide mapping overriding capability, but can be used for +merging mapping files. +|=== + +=== Overriding and Merging Examples + +*_Example 1_* + +* `+META-INF/orm.xml+` - defines Entity A with the mappings b and c. +* `+META-INF/eclipselink-orm.xml+` - defines Entity A with the mappings +for c and d. +* Result - Entity A will contain the mapping b (from `+orm.xml+`), +mapping c and d (from `+eclipselink-orm.xml+`) + +*_Example 2_* + +* `+META-INF/orm.xml+` - defines Entity A with the mappings b and c +* `+META-INF/some-other-mapping-file.xml+` - defines Entity B with +mappings a and b +* `+META-INF/eclipselink-orm.xml+` - defines Entity A with the mappings +for c and d and Entity B with the mapping b and c +* Result +** Entity A will contain the mapping b (from `+orm.xml+`), mapping c and +d (from `+eclipselink-orm.xml+`) +** Entity B will contain the mapping a (from +`+some-other-mapping-file+`), mappings b and c (from +`+eclipselink-orm.xml+`) + +*_Example 3_* + +* `+META-INF/orm.xml+` - defines Entity A with the mappings b and c. +* `+META-INF/eclipse-orm.xml+` - defines Entity A with the mappings c +and d. +* `+META-INF/some-other-mapping-file.xml+` - defines Entity A with the +mapping x. +* Result - Entity A will contain the mapping b (from `+orm.xml+`), +mapping c and d (from `+eclipselink-orm.xml+`) and mapping x (from +some-other-mapping-file) + +*_Example 4_* + +* `+META-INF/orm.xml+` - defines Entity A with the mappings b and c. +* `+META-INF/extensions/eclipselink-orm.xml+` - defines defines Entity A +with the mappings c and d. *Note:* This file is added through a tag in +the `+persistence.xml+` +* Result - Exception generated for conficting specifications for mapping +c. + +*_Example 5_* + +* `+META-INF/orm.xml+` - defines Entity A with the mappings b and c. +* `+META-INF/jpa-mapping-file.xml+` - defines Entity A with the mappings +a and d. +* `+META-INF/extensions/eclipse-mapping-file.xml+` - defines defines +Entity A with the mappings c and d. +* Result - Exception generated for conficting specifications for mapping +c or d (which ever is processed first). + +=== Overriding and Merging Rules + +The following sections outlines elements defined in `+orm.xml+` and +their specific overriding in greater detail. + +==== Persistence Unit Metadata + +In EclipseLink-ORM.XML, a persistence-unit-metadata specification merges +or overrides the values of existing persistence-unit-metadata +specification. + +[width="100%",cols="33%,5%,62%",options="header",] +|=== +|entity-mappings/persistence-unit-metadata |Rule |Description +|xml-mapping-metadata-complete |Full override |If specified, the +complete set of mapping metadata for the persistence unit is contained +in the XML mapping files for the persistence unit. + +|persistence-unit-defaults/schema |Full override |If a schema setting +exists, then the EclipseLink-ORM.XML’s schema setting overrides the +existing setting, or creates a new schema setting. + +|persistence-unit-defaults/catalog |Full override |If a catalog setting +exists, then the EclipseLink-ORM.XML’s catalog setting overrides the +existing setting, or creates a new catalog setting + +|persistence-unit-defaults/access |Full override |If an access setting +exists, then the EclipseLink-ORM.XML’s access setting overrides the +existing setting, or creates a new access setting. + +|entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist +|Full override |If a cascade-persist setting exists, then the +EclipseLink-ORM.XML’s cascade-persist setting overrides the existing +setting, or creates a new cascade-persist setting. + +|entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners +|Merge |If an entity-listeners exists, then the EclipseLink-ORM.XML’s +entity-listeners will be merged with the list of all entity-listeners +from the persistence unit. +|=== + +==== Entity Mappings + +Entities, embeddables and mapped superclasses are defined within +entity-mappings. EclipseLink-ORM.XML’s entities, embeddables and mapped +superclasses are added to the persistence unit. The following table +describes the top-level elements of the entity-mappings sections: + +[width="100%",cols="7%,3%,90%",options="header",] +|=== +|entity-mappings/ |Rule |Description +|package |None |The package element specifies the package of the classes +listed within the subelements and attributes of the same mapping file +only. It is only applicable to those entities that are fully defined +within the EclipseLink-ORM.XML file, else its usage remains local and is +same as described in the JPA specification. + +|catalog |None |The catalog element applies only to the subelements and +attributes listed within the EclipseLink-ORM.XML file that are not an +extension to another mapping file. Otherwise, the use of the catalog +element within the EclipseLink-ORM.XML file remains local and is same as +described in the JPA specification. + +|schema |None |The schema element applies only to the subelements and +attributes listed within the EclipseLink-ORM.XML file that are not an +extension to another mapping file. Otherwise, the use of the schema +element within the EclipseLink-ORM.XML file remains local and is same as +described in the JPA specification. + +|access |None |The access element applies only to the subelements and +attributes listed within the EclipseLink-ORM.XML file that are not an +extension to another mapping file. Otherwise, the use of the access +element within the EclipseLink-ORM.XML file remains local and is same as +described in the JPA specification. + +|sequence-generator |Full override |A sequence-generator is unique by +name. The sequence-generator defined in the EclipseLink-ORM.XML will +override a sequence-generator of the same name defined in another +mapping file. Outside of the overriding case, an exception is thrown if +two or more sequence-generators with the same name are defined in one or +across multiple mapping files. + +|table-generator |Full override |A table-generator is unique by name. +The table-generator defined in the EclipseLink-ORM.XML will override a +table-generator of the same name defined in another mapping file. +Outside of the overriding case, an exception is thrown if two or more +table-generators with the same name are defined in one or across +multiple mapping files. + +|named-query |Full override |A named-query is unique by name. The +named-query defined in the EclipseLink-ORM.XML will override a +named-query of the same name defined in other mapping files. Outside of +the overriding case, an exception is thrown if two or more named-querys +with the same name are defined in one or across multiple mapping file. + +|named-native-query |Full override |A named-native-query is unique by +name. The named-native-query defined in the EclipseLink-ORM.XML will +override a named-native-query of the same name defined in other mapping +files. Outside of the overriding case, an exception is thrown if two or +more named-native-querys with the same name are defined in one or across +multiple mapping files. + +|sql-result-set-mapping |Full override |A sql-result-set-mapping is +unique by name. The sql-result-set-mapping defined in the +EclipseLink-ORM.XML will override a sql-result-set-mapping of the same +name defined in other mapping files. Outside of the overriding case, an +exception is thrown if two or more sql-result-set-mapping entities with +the same name are defined in one or across multiple mapping files. +|=== + +==== Mapped Superclass + +A mapped-superclass can be defined completely, or with specific elements +to provide extensions to a mapped-superclass from another mapping file. +The following table lists individual override and merging rules: + +entity-mappings/mapped-superclass + +Rule + +Description + +id-class + +Full override + +If an id-class setting exists, then the EclipseLink-ORM.XML’s id-class +setting overrides the existing setting, or creates a new id-class +setting. + +exclude-default-listeners + +Full override + +If an exclude-default-listeners setting exists, then the +EclipseLink-ORM.XML’s exclude-default-listeners setting will be applied. +If the exclude-default-listeners setting is not specified, it will not +override an existing setting, that is essentially turning it off. + +exclude-superclass-listeners + +Full override + +If an exclude-superclass-listeners setting exists, then the +EclipseLink-ORM.XML’s exclude-superclass-listeners setting will be +applied. If exclude-superclass-listeners setting is not specified, it +will not override an existing setting, that is essentially turning it +off. + +entity-listeners + +Merge and full override + +If an entity-listeners setting exists, then the EclipseLink-ORM.XML’s +entity-listeners setting will override and merge with an existing +setting, or creates a new entity-listeners setting all together. Note: +An entity listener override must be complete. All lifecycle methods of +that listener must be specified and no merging of individual lifecycle +methods of an entity listener is allowed. The class name of the listener +is the key to identify the override. + +pre-persist + +Full override + +If a pre-persist setting exists, then the EclipseLink-ORM.XML’s +pre-persist setting overrides the existing setting, or creates a new +pre-persist setting. + +post-persist + +Full override + +If a post-persist setting exists, then the EclipseLink-ORM.XML’s +post-persist setting overrides the existing setting, or creates a new +post-persist setting. + +pre-remove + +Full override + +If a pre-remove setting exists, then the EclipseLink-ORM.XML’s +pre-remove setting overrides the existing setting, or creates a new +pre-remove setting. + +post-remove + +Full override + +If a post-remove setting exists, then the EclipseLink-ORM.XML’s +post-remove setting overrides the existing setting, or creates a new +post-remove setting. + +pre-update + +Full override + +If a pre-update setting exists, then the EclipseLink-ORM.XML’s +pre-update setting overrides the existing setting, or creates a new +pre-update setting. + +post-update + +Full override + +If a post-update setting exists, then the EclipseLink-ORM.XML’s +post-update setting overrides the existing setting, or creates a new +post-update setting. + +post-load + +Full override + +If a post-load setting exists, then the EclipseLink-ORM.XML’s post-load +setting overrides the existing setting, or creates a new post-load +setting. + +attributes + +Merge and mapping level override + +If the attribute settings (id, embedded-id, basic, version, many-to-one, +one-to-many, one-to-one, many-to-many, embedded, transient) exist at the +mapping level, then the EclipseLink-ORM.XML’s attributes merges or +overrides the existing settings, else creates new attributes. + +class + +None + +access + +Full override + +If an access setting exists, then the EclipseLink-ORM.XML’s access +setting overrides the existing setting, or creates a new access setting. +It also overrides the default class setting. + +metadata-complete + +Full override + +If a metadata-complete setting exists, then the EclipseLink-ORM.XML’s +metadata-complete setting will be applied. If metadata-complete setting +is not specified, it will not override an existing setting, that is +essentially turning it off. + +==== Entity override and merging rules + +An entity can be defined completely, or with specific elements to +provide extensions to an entity from another mapping file. The following +table lists individual override and merging rules: + +entity-mappings/entity + +Rule + +Comments + +table + +Full override + +The table definition overrides any other table setting (with the same +name) for this entity. There is no merging of individual table values. + +secondary-table + +Full override + +The secondary-table definition overrides another secondary-table setting +(with the same name) for this entity. There is no merging of individual +secondary-table(s) values. + +primary-key-join-column + +Full override + +The primary-key-join-column(s) definition overrides any other +primary-key-join-column(s) setting for this entity. There is no merging +of the primary-key-join-column(s). The specification is assumed to be +complete and these primary-key-join-columns are the source of truth. + +id-class + +Full override + +If an id-class setting exists, then the EclipseLink-ORM.XML’s id-class +setting overrides the existing setting, or creates a new id-class +setting. + +inheritance + +Full override + +If an inheritance setting exists, then the EclipseLink-ORM.XML’s +inheritance setting overrides the existing setting, or creates a new +inheritance setting. + +discriminator-value + +Full override + +If a discriminator-value setting exists, then the EclipseLink-ORM.XML’s +discriminator-value setting overrides the existing setting, or creates a +new discriminator-value setting. + +discriminator-column + +Full override + +If a discriminator-column setting exists, then the EclipseLink-ORM.XML’s +discriminator-column setting overrides the existing setting, or creates +a new discriminator-column setting. + +sequence-generator + +Full override + +A sequence-generator is unique by name. The sequence-generator defined +in EclipseLink-ORM.XML overrides sequence-generator of the same name +defined in other mapping files. Outside of the overriding case, an +exception is thrown if two or more sequence-generators with the same +name are defined in one or across multiple mapping files. + +table-generator + +Full override + +A table-generator is unique by name. The table-generator defined in +EclipseLink-ORM.XML overrides table-generator of the same name defined +in other mapping files. Outside of the overriding case, an exception is +thrown if two or more table-generators with the same name are defined in +one or across multiple mapping files. + +named-query + +Merge and full override + +A named-query is unique by name. The named-query defined in +EclipseLink-ORM.XML overrides named-query of the same name defined in +other mapping files. Outside of the overriding case, an exception is +thrown if two or more named-query elements with the same name are +defined in one or across multiple mapping files. + +named-native-query + +Merge and full override + +A named-native-query is unique by name. The named-native-query defined +in EclipseLink-ORM.XML overrides named-native-query of the same name +defined in other mapping files. Outside of the overriding case, an +exception is thrown if two or more named-native-query elements with the +same name are defined in one or across multiple mapping files. + +sql-result-set-mapping + +Merge and full override + +A sql-result-set-mapping is unique by name. The sql-result-set-mapping +defined in EclipseLink-ORM.XML overrides sql-result-set-mapping of the +same name defined in other mapping files. Outside of the overriding +case, an exception is thrown if two or more sql-result-set-mapping +elements with the same name are defined in one or across multiple +mapping files. + +exclude-default-listeners + +Full override + +If an exclude-default-listeners setting exists, then the +EclipseLink-ORM.XML’s exclude-default-listeners setting will be applied. +If an exclude-default-listeners setting is not specified, it will not +override an existing setting, that is essentially turning it off. + +exclude-superclass-listeners + +Full override + +If an exclude-superclass-listeners setting exists, then the +EclipseLink-ORM.XML’s exclude-superclass-listeners setting will be +applied. If an exclude-superclass-listeners setting is not specified, it +will not override an existing setting, that is essentially turning it +off. + +entity-listeners + +Full override + +If an entity-listeners setting exists, then the EclipseLink-ORM.XML’s +entity-listeners setting will override and merge with an existing +setting, or creates a new entity-listeners setting all together. Note: +An entity listener override must be complete. All lifecycle methods of +that listener must be specified and no merging of individual lifecycle +methods of an entity listener is allowed. The class name of the listener +is the key to identify the override. + +pre-persist + +Full override + +If a pre-persist setting exists, then the EclipseLink-ORM.XML’s +pre-persist setting overrides the existing setting, or creates a new +pre-persist setting. + +post-persist + +Full override + +If a post-persist setting exists, then the EclipseLink-ORM.XML’s +post-persist setting overrides the existing setting, or creates a new +post-persist setting. + +pre-remove + +Full override + +If a pre-remove setting exists, then the EclipseLink-ORM.XML’s +pre-remove setting overrides the existing setting, or creates a new +pre-remove setting. + +post-remove + +Full override + +If a post-remove setting exists, then the EclipseLink-ORM.XML’s +post-remove setting overrides the existing setting, or creates a new +post-remove setting. + +pre-update + +Full override + +If a pre-update setting exists, then the EclipseLink-ORM.XML’s +pre-update setting overrides the existing setting, or creates a new +pre-update setting. + +post-update + +Full override + +If a post-update setting exists, then the EclipseLink-ORM.XML’s +post-update setting overrides the existing setting, or creates a new +post-update setting. + +post-load + +Full override + +If a post-load setting exists, then the EclipseLink-ORM.XML’s post-load +setting overrides the existing setting, or creates a new post-load +setting. + +attributes + +Merge and mapping level override + +If the attribute settings (id, embedded-id, basic, version, many-to-one, +one-to-many, one-to-one, many-to-many, embedded, transient) exist at the +mapping level, then the EclipseLink-ORM.XML’s attributes merges or +overrides the existing settings, else creates new attributes. + +association-override + +Merge and full override + +If an association-override setting exists, then the +EclipseLink-ORM.XML’s association-override setting overrides the +existing setting, or creates a new association-override setting. + +name + +Full override + +If a name setting exists, then the EclipseLink-ORM.XML’s name setting +overrides the existing setting, or creates a new name setting. + +class + +None + +access + +Full override + +If an access setting exists, then the EclipseLink-ORM.XML’s access +setting overrides the existing setting, or creates a new access setting. +It also overrides the default class setting. + +metadata-complete + +Full override + +If a metadata-complete setting exists, then the EclipseLink-ORM.XML’s +metadata-complete setting will be applied. If a metadata-complete +setting is not specified, it will not override an existing setting, that +is essentially turning it off. + +==== Embeddable + +An embeddable can be defined wholely or may be defined so as to provide +extensions to an embeddeable from another mapping file. Therefore, we +will allow the merging of that classes metadata. The individual override +rules for that metadata is tabled below. + +[width="100%",cols="9%,6%,85%",options="header",] +|=== +|entity-mappings/embeddable |Rule |Description +|attributes |Override and merge |If the attribute settings (id, +embedded-id, basic, version, many-to-one, one-to-many, one-to-one, +many-to-many, embedded, transient) exist at the mapping level, then the +EclipseLink-ORM.XML’s attributes merges or overrides the existing +settings, or creates new attributes. + +|class |None | + +|access |Full override |If an access setting exists, then the +EclipseLink-ORM.XML’s access setting overrides the existing setting, or +creates a new access setting. It also overrides the default class +setting. + +|metadata-complete |Full override |If a metadata-complete setting +exists, then the EclipseLink-ORM.XML’s metadata-complete setting will be +applied. If a metadata-complete setting is not specified, it will not +override an existing setting, that is essentially turning it off. +|=== + +== Defaulting Properties + +Each annotation has a default value (consult the JPA specification for +defaults). A persistence engine defines defaults that apply to the +majority of applications. You only need to supply values when you want +to override the default value. Therefore, having to supply a +configuration value is not a requirement, but the exception to the rule. +This is known as _configuration by exception_. + +[width="100%",cols="<100%",] +|=== +|*Note:* You should be familiar with the defaults to be able to change +the behavior when necessary. +|=== + +== Configuring an Entity + +You can configure your entity’s identity, as well as the locking +technique and sequence generation option for your entity. + +=== Configuring an Entity Identity + +Every entity must have a persistent identity, which is an equivalent of +a primary key in a database table that stores the entity state. + +By default, EclipseLink persistence provider assumes that each entity +has at least one field or property that serves as a primary key. + +You can generate and/or configure the identity of your entities by using +the following annotations: + +* link:#@Id[@Id] +* link:#@IdClass[@IdClass] +* link:#@EmbeddedId[@EmbeddedId] +* link:#@GeneratedValue[@GeneratedValue] +* link:#@TableGenerator[@TableGenerator] +* link:#@SequenceGenerator[@SequenceGenerator] + +You can also use these annotations to fine-tune how your database +maintains the identity of your entities. + +For more information on the EclipseLink artifacts configured by these +JPA metadata, refer to +link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Primary_Keys[Configuring +Primary Keys]. + +==== @Id + +Use the `+@Id+` annotation to designate one or more persistent fields or +properties as the entity’s primary key. + +For each entity, you must designate at least one of the following: + +* one `+@Id+` +* one link:#@EmbeddedId[`+@EmbeddedId+`] +* multiple `+@Id+` and an link:#@IdClass[`+@IdClass+`] + +[width="100%",cols="<100%",] +|=== +|*Note:* The last option in the preceding list – `+@Id+` and +`+@IdClass+` combination – is applicable to composite primary key +configuration. +|=== + +The `+@Id+` annotation does not have attributes. + +By default, EclipseLink persistence provider chooses the most +appropriate primary key generator (see +link:#@GeneratedValue[@GeneratedValue]) and is responsible for managing +primary key values: you do not need to take any further action if you +are satisfied with the persistence provider’s default key generation +mechanism. + +This example shows how to use this annotation to designate the +persistent field `+empID+` as the primary key of the `+Employee+` table. + +[#Example 18-2]## *_Usage of @Id Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + @Id + private int empID; + ... + } +---- + +The `+@Id+` annotation supports the use of EclipseLink converters (see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Converters[Using +EclipseLink JPA Converters]). + +For more information and examples, see Section 9.1.8 "`Id Annotation`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +==== @IdClass + +Use the `+@IdClass+` annotation to specify a composite primary key class +(usually made up of two or more primitive, JDK object types or Entity +types) for an entity or MappedSuperclass. + +[width="100%",cols="<100%",] +|=== +|*Note:* Composite primary keys typically arise during mapping from +legacy databases when the database key is comprised of several columns. +|=== + +A composite primary key class has the following characteristics: + +* It is a POJO class. +* It is a public class with a public no-argument constructor. +* If you use property-based access, the properties of the primary key +class are public or protected. +* It is serializable. +* It defines `+equals+` and `+hashCode+` methods. The semantics of value +equality for these methods must be consistent with the database equality +for the database types to which the key is mapped. +* Its fields or properties must correspond in type and name to the +entity primary key fields or properties annotated with link:#@Id[@Id]. + +Alternatively, you can make the composite primary key class an embedded +class owned by the entity (see link:#@EmbeddedId[@EmbeddedId]). + +The `+@IdClass+` annotation has a required attribute `+value+` that you +set to the class to specify this class as a composite primary key class +(see link:#@AttributeOverride[@AttributeOverride]). + +The link:#Example_18-3[Nonembedded Composite Primary Key Class] example +shows a nonembedded composite primary key class. In this class, fields +`+empName+` and `+birthDay+` must correspond in name and type to +properties in the entity class. The link:#Example_18-4[Usage of @IdClass +Annotation] example shows how to configure an entity with this +nonembedded composite primary key class using the `+@IdClass+` +annotation. Because entity class fields `+empName+` and `+birthDay+` are +used in the primary key, you must also annotate them using the `+@Id+` +annotation (see link:#@Id[@Id]). + +[#Example 18-3]## *_Nonembedded Composite Primary Key Class_* + +[source,java] +---- + public class EmployeePK implements Serializable { + + private String empName; + private Date birthDay; + + public EmployeePK() { + } + + public String getName() { + return this.empName; + } + + public void setName(String name) { + this.empName = name; + } + + public long getDateOfBirth() { + return this.birthDay; + } + + public void setDateOfBirth(Date date) { + this.birthDay = date; + } + + public int hashCode() { + return (int)this.empName.hashCode(); + } + + public boolean equals(Object obj) { + if (obj == this) return true; + if (!(obj instanceof EmployeePK)) return false; + if (obj == null) return false; + EmployeePK pk = (EmployeePK) obj; + return pk.birthDay = this.birthDay && pk.empName.equals(this.empName); + } + } +---- + +[#Example 18-4]## *_Usage of @IdClass Annotation_* + +[source,java] +---- + @IdClass (EmployeePK.class) + @Entity + public class Employee implements Serializable{ + + @Id String empName; + @Id Date birthDay; + ... + } +---- + +For more information and examples, see Section 9.1.15 "`IdClass +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +==== @EmbeddedId + +Use the `+@EmbeddedId+` annotation to specify an embeddable composite +primary key class (usually made up of two or more primitive or JDK +object types) owned by the entity. + +[width="100%",cols="<100%",] +|=== +|*Note:* Composite primary keys typically arise during mapping from +legacy databases when the database key is comprised of several columns. +|=== + +A composite primary key class has the following characteristics: + +* It is a POJO class. +* It is a public class with a public no-argument constructor. +* If you use property-based access, the properties of the primary key +class are public or protected. +* It is serializable. +* It defines `+equals+` and `+hashCode+` methods. The semantics of value +equality for these methods must be consistent with the database equality +for the database types to which the key is mapped. + +Alternatively, you can make the composite primary key class a +nonembedded class (see link:#@IdClass[@IdClass]). + +The `+@EmbeddedId+` annotation does not have attributes. + +This example shows a typical composite primary key class annotated with +link:#@Embeddable[`+@Embeddable+`]. The link:#Example_18-6[Usage of +@EmbeddedId Annotation] example shows how to configure an entity with +this embeddable composite primary key class using the `+@EmbeddedId+` +annotation. + +[#'Example 18-5]## *_Embeddable Composite Primary Key Class_* + +[source,java] +---- + @Embeddable + public class EmployeePK implements Serializable { + + private String empName; + private long empID; + + public EmployeePK() { + } + + public String getName() { + return this.empName; + } + + public void setName(String name) { + this.empName = name; + } + + public long getId() { + return this.empID; + } + + public void setId(long id) { + this.empID = id; + } + + public int hashCode() { + return (int)this.empName.hashCode()+ this.empID; + } + + public boolean equals(Object obj) { + if (obj == this) return true; + if (!(obj instanceof EmployeePK)) return false; + if (obj == null) return false; + EmployeePK pk = (EmployeePK) obj; + return pk.empID == this.empID && pk.empName.equals(this.empName); + } + } +---- + +[#Example 18-6]## *_Usage of @EmbeddedId Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable{ + + @EmbeddedId + EmployeePK primaryKey; + + public Employee { + } + + public EmployeePK getPrimaryKey() { + return primaryKey: + } + + public void setPrimaryKey(EmployeePK pk) { + primaryKey = pk; + } + + ... + } +---- + +For more information and examples, see Section 9.1.14 "`EmbeddedId +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +==== @GeneratedValue + +Use the `+@GeneratedValue+` annotation to enable EclipseLink persistence +provider to generate unique identifiers for entity primary keys (see +link:#@Id[@Id]). + +This annotation lets you do the following: + +* override the type of identity value generation selected by the +persistence provider for your database if you feel another generator +type is more appropriate for your database or application; +* override the primary key generator name selected by the persistence +provider if this name is awkward, a reserved word, incompatible with a +preexisting data model, or invalid as a primary key generator name in +your database. + +The `+@GeneratedValue+` annotation has the following attributes: + +* `+generator+` – The default value of this attribute is the name that +EclipseLink persistence provider assigns to the primary key generator it +selects. If the generator name is awkward, a reserved word, incompatible +with a preexisting data model, or invalid as a primary key generator +name in your database, set the value of this attribute to the `+String+` +generator name you want to use. ++ +You are not required to specify the value of this attribute. +* `+strategy+` – By default, EclipseLink persistence provider chooses +the type of primary key generator that is most appropriate for the +underlying database. If you feel that another generator type is more +appropriate for your database or application, set the value of this +attribute to one of the following enumerated values of the +`+GenerationType+` enumerated type: +** `+AUTO+` (default) – specify that EclipseLink persistence provider +should choose a primary key generator that is most appropriate for the +underlying database. ++ ++ ++ ++ +*Note:* By default, EclipseLink chooses the `+TABLE+` strategy using a +table named `+SEQ_GEN_TABLE+`, with `+SEQ_NAME+` and `+SEQ_COUNT+` +columns, with `+allocationSize+` of 50 and `+pkColumnValue+` of +`+SEQ_GEN+`. The default `+SEQUENCE+` used is database sequence +`+SEQ_GEN_SEQUENCE+` with `+allocationSize+` of 50. Note that the +database sequence increment must match the allocation size. ++ ++ ++ +** `+TABLE+` – specify that EclipseLink persistence provider assign +primary keys for the entity using an underlying database table to ensure +uniqueness (see link:#@TableGenerator[@TableGenerator]). +** `+SEQUENCE+` – specify that EclipseLink persistence provider use a +database sequence (see link:#@SequenceGenerator[@SequenceGenerator]). ++ ++ ++ ++ ++ ++ +** `+IDENTITY+` – specify that EclipseLink persistence provider use a +database identity column. Setting this value will indicate to the +persistence provider that it must reread the inserted row from the table +after an insert has occurred. This will allow it to obtain the newly +generated identifier from the database and put it into the in-memory +entity that was just persisted. The identity must be defined as part of +the database schema for the primary key column. Identity generation may +not be shared across multiple entity types. ++ ++ ++ + +*Note:* `+IDENTITY+` strategy is supported on DB2, SQL Server, MySQL, +Derby, JavaDB, Informix, and Postgres databases. + +\{| class="`Note oac_no_warn`" width="`80%`" border="`1`" +frame="`hsides`" rules="`groups`" cellpadding="`3`" frame="`hsides`" +rules="`groups`" | align="`left`" | *Note:* There is a difference +between using `+IDENTITY+` and other id generation strategies: the +identifier will not be accessible until after the insert has occurred – +it is the action of inserting that caused the identifier generation. Due +to the fact that insertion of entities is most often deferred until the +commit time, the identifier would not be available until after the +transaction has been committed. |} + +\{| class="`Note oac_no_warn`" width="`80%`" border="`1`" +frame="`hsides`" rules="`groups`" cellpadding="`3`" frame="`hsides`" +rules="`groups`" | align="`left`" | *Note:* We do not recommend using +the `+IDENTITY+` strategy for it does not support preallocation. |} You +are not required to specify the value of the `+strategy+` attribute. +This example shows how to use automatic id generation. This will cause +EclipseLink persistence provider to create an identifier value and +insert it into the `+id+` field of each `+Employee+` entity that gets +persisted. [#Example 18-7]## *_Using Automatic Id Generation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + + @Id + @GeneratedValue(strategy=GenerationType.AUTO) + private int id; + ... + } +---- + +\{| class="`Note oac_no_warn`" width="`80%`" border="`1`" +frame="`hsides`" rules="`groups`" cellpadding="`3`" frame="`hsides`" +rules="`groups`" | align="`left`" | *Caution:* Be careful when using the +automatic id generation: the persistence provider has to pick its own +strategy to store the identifiers, but it needs to have a persistent +resource, such as a table or a sequence, to do so. The persistence +provider cannot always rely upon the database connection that it obtains +from the server to have permissions to create a table in the database. +This is usually a privileged operation that is often restricted to the +DBA. There will need to be a creation phase or schema generation to +cause the resource to be created before the `+AUTO+` strategy can +function. |} + +For more information and examples, see Section 9.1.9 "`GeneratedValue +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== Configuring Sequence Generation + +Many databases support an internal mechanism for id generation called +sequences. You can use a database sequence to generate identifiers when +the underlying database supports them. + +For more information, see +link:Introduction%20to%20Relational%20Projects%20(ELUG)#Table_Sequencing[Table +Sequencing]. + +==== @SequenceGenerator + +If you use the link:#@GeneratedValue[@GeneratedValue annotation] to +specify a primary key generator of type `+SEQUENCE+`, then you can use +the `+@SequenceGenerator+` annotation to fine-tune this primary key +generator to do the following: + +* change the allocation size to match your application requirements or +database performance parameters; +* change the initial value to match an existing data model (for example, +if you are building on an existing data set for which a range of primary +key values has already been assigned or reserved); +* use a predefined sequence in an existing data model. + +The `+@SequenceGenerator+` annotation has the following attributes: + +* `+name+` – The name of the generator must match the name of a +`+GeneratedValue+` with its `+strategy+` attribute set to `+SEQUENCE+`. ++ +You are required to specify the value of this attribute. +* `+allocationSize+` – By default, EclipseLink persistence provider uses +an allocation size of 50. ++ +The value of this attribute must match the increment size on the +database sequence object. If this allocation size does not match your +application requirements or database performance parameters, set this +attribute to the `+int+` value you want. ++ +You are not required to specify the value of the `+allocationSize+` +attribute. +* `+initialValue+` – By default, EclipseLink persistence provider starts +all primary key values from 0. If this does not match an existing data +model, set this attribute to the `+int+` value you want. ++ +You are not required to specify the value of the `+initialValue+` +attribute. +* `+sequenceName+` – By default, EclipseLink persistence provider +assigns a sequence name of its own creation. ++ +The `+sequenceName+` defaults to the name of the `+SequenceGenerator+`. +If you prefer to use an existing or predefined sequence, set +`+sequenceName+` to the `+String+` name you want. ++ +You are not required to specify the value of the `+sequenceName+` +attribute. + +This example shows how to use this annotation to specify the allocation +size for the `+SEQUENCE+` primary key generator named `+Cust_Seq+`. + +[#Example 18-8]## *_Usage of @SequenceGenerator_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Id + @SequenceGenerator(name="Cust_Seq", allocationSize=25) + @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="Cust_Seq") + @Column(name="CUST_ID") + public Long getId() { + return id; + } + ... + } +---- + +For more information and examples, see Section 9.1.37 +"`SequenceGenerator Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +For more information on the EclipseLink artifacts configured by these +JPA metadata, refer to +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Sequencing[Descriptors +and Sequencing]. + +==== @TableGenerator + +If you use the link:#@GeneratedValue[`+@GeneratedValue+` annotation] to +specify a primary key generator of type `+TABLE+`, then you can use the +`+@TableGenerator+` annotation to fine-tune this primary key generator +to do the following: + +* change the name of the primary key generator’s table, because the name +is awkward, a reserved word, incompatible with a preexisting data model, +or invalid as a table name in your database; +* change the allocation size to match your application requirements or +database performance parameters; +* change the initial value to match an existing data model (for example, +if you are building on an existing data set, for which a range of +primary key values has already been assigned or reserved); +* configure the primary key generator’s table with a specific catalog or +schema; +* configure a unique constraint on one or more columns of the primary +key generator’s table; + +The `+@TableGenerator+` annotation has the following attributes: + +* `+name+` – The name of the generator must match the name of a +`+GeneratedValue+` with its `+strategy+` attribute set to `+TABLE+`. The +scope of the generator name is global to the persistence unit (across +all generator types). ++ +You are required to specify the value of this attribute. +* `+allocationSize+` – By default, EclipseLink persistence provider uses +an allocation size of 50. If this allocation size does not match your +application requirements or database performance parameters, set this +attribute to the `+int+` value you want. ++ +You are not required to specify the value of the `+allocationSize+` +attribute. +* `+catalog+` – By default, EclipseLink persistence provider uses +whatever the default catalog is for your database. If the default +catalog is inappropriate for your application, set the value of this +attribute to the `+String+` catalog name to use. ++ +You are not required to specify the value of the `+catalog+` attribute. +* `+initialValue+` – By default, EclipseLink persistence provider starts +all primary key values from 0. If this does not match an existing data +model, set this attribute to the `+int+` value you want. ++ +You are not required to specify the value of the `+initialValue+` +attribute. +* `+pkColumnName+` – By default, EclipseLink persistence provider +supplies a name for the primary key column in the generator table: +`+"SEQ_NAME"+`. If this name is inappropriate for your application, set +the value of this attribute to the `+String+` name you want. ++ +You are not required to specify the value of the `+pkColumnName+` +attribute. +* `+pkColumnValue+` – By default, EclipseLink persistence provider +supplies a suitable primary key value for the primary key column in the +generator table: `+TableGenereator.name+`. If this value is +inappropriate for your application, set the value of this attribute to +the `+String+` value you want. ++ +You are not required to specify the value of the `+pkColumnValue+` +attribute. +* `+schema+` – By default, EclipseLink persistence provider uses +whatever the default schema is for your database. If this value is +inappropriate for your application, set the value of this attribute to +the `+String+` schema name you choose. ++ +You are not required to specify the value of the `+schema+` attribute. +* `+table+` – By default, EclipseLink persistence provider supplies a +suitable name for the table that stores the generated id values: +`+"SEQUENCE"+`. If this value is inappropriate for your application, set +the value of this attribute to the `+String+` table name you want. ++ +You are not required to specify the value of the `+table+` attribute. +* `+uniqueConstraints+` – By default, EclipseLink persistence provider +assumes that none of the columns in the primary key generator table have +unique constraints. If unique constraints do apply to one or more +columns in this table, set the value of this attribute to an array of +one or more `+UniqueConstraint+` instances. For more information, see +Section 9.1.4 "`UniqueConstraint Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. ++ +You are not required to specify the value of the `+uniqueConstraints+` +attribute. +* `+valueColumnName+` – By default, EclipseLink persistence provider +supplies a suitable name for the column that stores the generated id +values: `+"SEQ_COUNT"+`. If the default column name is inappropriate for +your application, set the value of this attribute to the `+String+` +column name you want. ++ +You are not required to specify the value of the `+valueColumnName+` +attribute. + +The link:#Example_18-9[Usage of @TableGenerator] example shows how to +use this annotation to specify the allocation size for the `+TABLE+` +primary key generator named `+Emp_Gen+`. + +[#Example 18-9]## *_Usage of @TableGenerator_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Id + @TableGenerator(name="Emp_Gen", allocationSize=1) + @GeneratedValue(strategy=GenerationType.TABLE, generator="Emp_Gen") + @Column(name="CUST_ID") + public Long getId() { + return id; + } + ... + } +---- + +Every table that you use for id generation should have two columns – if +there are more columns, only two will be used. The first column is of a +string type and is used to identify the particular generator sequence. +It is the primary key for all of the generators in the table. The name +of this column is specified by the `+pkColumnName+` attribute. The +second column is of an integer type and stores the actual id sequence +that is being generated. The value stored in this column is the last +identifier that was allocated in the sequence. The name of this column +is specified by the `+valueColumnName+` attribute. + +Each defined generator represents a row in the table. The name of the +generator becomes the value stored in the `+pkColumnName+` column for +that row and is used by EclipseLink persistence provider to look up the +generator to obtain its last allocated value. + +For more information and examples, see Section 9.1.38 "`TableGenerator +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== Configuring Locking + +You have the choice between optimistic and pessimistic locking. We +recommend using EclipseLink +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Optimistic_Locking[optimistic +locking]. For more information, see +link:Introduction_to_EclipseLink%20Application%20Development%20(ELUG)#Locking[Locking]. + +By default, EclipseLink persistence provider assumes that the +application is responsible for data consistency. + +Use the `+@Version+` annotation to enable the JPA-managed optimistic +locking by specifying the version field or property of an entity class +that serves as its optimistic lock value (recommended). + +When choosing a version field or property, ensure that the following is +true: + +* there is only one version field or property per entity; +* you choose a property or field persisted to the primary table (see +Section 9.1.1 "`Table Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]); +* your application does not modify the version property or field. + +[width="100%",cols="<100%",] +|=== +|*Note:* The field or property type must either be a numeric type (such +as `+Number+`, `+long+`, `+int+`, `+BigDecimal+`, and so on), or a +`+java.sql.Timestamp+`. We recommend using a numeric type. +|=== + +The `+@Version+` annotation does not have attributes. + +The link:#Example_18-10[Usage of @Version Annotation] example shows how +to use this annotation to specify property `+getVersionNum+` as the +optimistic lock value. In this example, the column name for this +property is set to `+OPTLOCK+` (see Section 9.1.5 "`Column Annotation`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]) instead +of the default column name for the property. + +[#Example 18-10]## *_Usage of @Version Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Version + @Column(name="OPTLOCK") + protected int getVersionNum() { + return versionNum; + } + ... + } +---- + +The `+@Version+` annotation supports the use of EclipseLink converters +(see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Converters[Using +EclipseLink JPA Converters]). + +For more information, see the following: + +* Section 3.4 "`Optimistic Locking and Concurrency`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* Section 9.1.17 "`Version Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Extensions_for_Optimistic_Locking[Using +EclipseLink JPA Extensions for Optimistic Locking] + +For more information on the EclipseLink artifacts configured by these +JPA metadata, refer to +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Locking[Descriptors +and Locking]. + +== Declaring Basic Property Mappings + +Simple Java types are mapped as part of the immediate state of an entity +in its fields or properties. Mappings of simple Java types are called +_basic mappings_. + +By default, EclipseLink persistence provider automatically configures a +basic mapping for simple types. + +Use the following annotations to fine-tune how your database implements +these mappings: + +* link:#@Basic[@Basic] +* link:#@Enumerated[@Enumerated] +* link:#@Temporal[@Temporal] +* link:#@Lob[@Lob] +* link:#@Transient[@Transient] + +For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using_EclipseLink_JPA_Converters[Using +EclipseLink JPA Converters]. + +=== @Basic + +By default, EclipseLink persistence provider automatically configures +`+@Basic+` mapping for most Java primitive types, wrappers of the +primitive types, and enumerated types. + +EclipseLink uses the default column name format of or in uppercase +characters. + +You may explicitly place an optional `+@Basic+` annotation on a field or +property to explicitly mark it as persistent. + +[width="100%",cols="<100%",] +|=== +|*Note:* The `+@Basic+` annotation is mostly for documentation purposes +– it is not required for the field or property to be persistent. +|=== + +Use the `+@Basic+` annotation to do the following: + +* configure the fetch type to `+LAZY+`; +* configure the mapping to forbid null values (for nonprimitive types) +in case null values are inappropriate for your application. + +The `+@Basic+` annotation has the following attributes: + +* `+fetch+` – By default, EclipseLink persistence provider uses a fetch +type of `+javax.persitence.FetchType.EAGER+`: data must be eagerly +fetched.If the default is inappropriate for your application or a +particular persistent field, set `+fetch+` to `+FetchType.LAZY+`: this +is a hint to the persistence provider that data should be fetched lazily +when it is first accessed (if possible).You are not required to specify +the value of this attribute. For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Lazy_Loading[What +You May Need to Know About EclipseLink JPA Lazy Loading]. +* `+optional+` – By default, EclipseLink persistence provider assumes +that the value of all (nonprimitive) fields and properties may be +`+null+`. If the default is inappropriate for your application, set this +the value of this attribute to `+false+`. ++ +You are not required to specify the value of this attribute. + +This example shows how to use this annotation to specify a fetch type of +`+LAZY+` for a basic mapping. + +[#Example 18-11]## *_Usage of the @Basic Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Basic(fetch=LAZY) + protected String getName() { + return name; + } + ... + } +---- + +For more information and examples, see Section 9.1.18 "`Basic +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +For more information on EclipseLink direct mappings and relationship +mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +=== @Enumerated + +By default, EclipseLink persistence provider persists the ordinal values +of enumerated constants. + +Use the `+@Enumerated+` annotation to specify whether EclipseLink +persistence provider should persist ordinal or `+String+` values of +enumerated constants if the `+String+` value suits your application +requirements, or to match an existing database schema: + +You can use this annotation with the link:#@Basic[@Basic annotation]. + +The `+@Enumerated+` annotation has the following attributes: + +* `+value+` – By default, EclipseLink persistence provider assumes that +for a property or field mapped to an enumerated constant, the ordinal +value should be persisted. In the link:#Example_18-13[Usage of the +@Enumerated Annotation] example, the ordinal value of `+EmployeeStatus+` +is written to the database when `+Employee+` is persisted. If you want +the `+String+` value of the enumerated constant persisted, set value to +`+EnumType.STRING+`. ++ +You are not required to specify the value of this attribute. + +Given the enumerated constants in the link:#Example_18-12[Enumerated +Constants] example, the link:#Example_18-13[Usage of the @Enumerated +Annotation] example shows how to use the `+@Enumerated+` annotation to +specify that the `+String+` value of `+SalaryRate+` should be written to +the database when `+Employee+` is persisted. By default, the ordinal +value of `+EmployeeStatus+` is written to the database. + +[#Example 18-12]## *_Enumerated Constants_* + +[source,java] +---- + public enum EmployeeStatus {FULL_TIME, PART_TIME, CONTRACT} + public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE} +---- + +[#Example 18-13]## *_Usage of the @Enumerated Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable{ + ... + public EmployeeStatus getStatus() { + ... + } + + @Enumerated(STRING) + public SalaryRate getRate() { + ... + } + ... + } +---- + +For more information and examples, see Section 9.1.21 "`Enumerated +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @Temporal + +Use the `+@Temporal+` annotation to specify the database type that +EclipseLink persistence provider should persist for persistent fields or +properties of type `+java.util.Date+` and `+java.util.Calendar+` only. + +You can use this annotation with the link:#@Basic[`+@Basic+` +annotation]. + +The `+@Temporal+` annotation has the following attributes: + +* `+value+` – Set this attribute to the `+TemporalType+` that +corresponds to database type you want EclipseLink persistence provider +to use: +** `+DATE+` – equivalent of `+java.sql.Date+` +** `+TIME+` – equivalent of `+java.time.Date+` +** `+TIMESTAMP+` – equivalent of `+java.sql.Timestamp+` + +You are required to specify the value of this attribute. + +This example shows how to use this annotation to specify that +EclipseLink persistence provider should persist `+java.util.Date+` field +`+startDate+` as a `+DATE+` (`+java.sql.Date+`) database type. + +[#Example 18-14]## *_Usage of the @Temporal Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable{ + ... + @Temporal(DATE) + protected java.util.Date startDate; + ... + } +---- + +For more information and examples, see Section 9.1.20 "`Temporal +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @Lob + +By default, EclipseLink persistence provider assumes that all persistent +data can be represented as typical database data types. + +Use the `+@Lob+` annotation with the link:#@Basic[`+@Basic+` mapping] to +specify that a persistent property or field should be persisted as a +large object to a database-supported large object type. + +A `+Lob+` may be either a binary or character type. The persistence +provider infers the `+Lob+` type from the type of the persistent field +or property. + +For `+String+` and character-based types, the default is `+Clob+`. In +all other cases, the default is `+Blob+`. + +You can also use the `+@Column+` attribute `+columnDefinition+` (see +Section 9.1.5 "`Column Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) to further +refine the `+Lob+` type. + +The `+@Lob+` annotation does not have attributes. + +This example shows how to use this `+@Lob+` annotation to specify that +persistent field `+pic+` should be persisted as a `+Blob+`. + +[#Example 18-15]## *_Usage of the @Lob Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Lob + @Basic(fetch=LAZY) + @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL") + protected byte[] pic; + ... + } +---- + +For more information and examples, see Section 9.1.20 "`Temporal +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @Transient + +By default, EclipseLink persistence provider assumes that all the fields +of an entity are persistent. + +Use the `+@Transient+` annotation to specify a field or property of an +entity that is not persistent (for example, a field or property that is +used at run time, but that is not part of the entity’s state). + +EclipseLink persistence provider will not persist (or create database +schema) for a property or field annotated with `+@Transient+`. + +This annotation can be used with `+@Entity+` (see Section 8.1 "`Entity`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]), +link:#@MappedSuperclass[`+@MappedSuperclass+`]), and +link:#@Embeddable[`+@Embeddable+`]. + +The `+@Transient+` annotation does not have attributes. + +The link:#Example_18-16[Usage of the @Transient Annotation] example +shows how to use the `+@Transient+` annotation to specify `+Employee+` +field `+currentSession+` as not persistent. EclipseLink persistence +provider will not persist this field. + +[#Example 18-16]## *_Usage of the @Transient Annotation_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @Id + int id; + + @Transient + Session currentSession; + ... + } +---- + +For more information and examples, see Section 9.1.16 "`Transient +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +== Mapping Relationships + +EclipseLink persistence provider requires that you map relationships +explicitly. + +Use the following annotations to specify the type and characteristics of +entity relationships to fine-tune how your database implements these +relationships: + +* link:#@OneToOne[@OneToOne] +* link:#@ManyToOne[@ManyToOne] +* link:#@OneToMany[@OneToMany] +* link:#@ManyToMany[@ManyToMany] +* link:#@MapKey[@MapKey] +* link:#@MapKey[@MapKey] + +At end of relationships section should link to the EclipseLink +relationships mappings section and state that additional advanced +mapping and mapping options are available through EclipseLink’s +descriptor and mapping API through using a `+DescriptorCustomizer+`. + +For more information, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +You can access additional advanced mappings and mapping options through +EclipseLink descriptor and mapping API +link:Customizing%20the%20EclipseLink%20Application%20(ELUG)#Using_the_Descriptor_Customizer_Class[using +a DescriptorCustomizer Class]. + +=== @OneToOne + +By default, JPA automatically defines a `+OneToOne+` mapping for a +single-valued association to another entity that has one-to-one +multiplicity and infers the associated target entity from the type of +the object being referenced. + +Use the `+OneToOne+` annotation to do the following: + +* configure the fetch type to `+LAZY+`; +* configure the mapping to forbid null values (for nonprimitive types) +in case null values are inappropriate for your application; +* configure the associated target entity, if it cannot be inferred from +the type of the object being referenced; +* configure the operations that must be cascaded to the target of the +association (for example, if the owning entity is removed, ensure that +the target of the association is also removed). + +The `+@OneToOne+` annotation has the following attributes: + +* `+cascade+` – By default, JPA does not cascade any persistence +operations to the target of the association. Thus, the default value of +this attribute is an empty `+javax.persitence.CascadeType+` array. If +you want some or all persistence operations cascaded to the target of +the association, set the value of this attribute to one or more +`+CascadeType+` instances, including the following: +** `+ALL+` – Any persistence operation performed on the owning entity is +cascaded to the target of the association. +** `+MERGE+` – If the owning entity is merged, the merge is cascaded to +the target of the association. +** `+PERSIST+` – If the owning entity is persisted, the persist is +cascaded target of the association. +** `+REFRESH+` – If the owning entity is refreshed, the refresh is +cascaded target of the association. +** `+REMOVE+` – If the owning entity is removed, the target of the +association is also removed. ++ +You are not required to provide value for this attribute. +* `+fetch+` – By default, EclipseLink persistence provider uses a fetch +type of `+javax.persitence.FetchType.EAGER+`: this is a requirement on +the persistence provider runtime that data must be eagerly fetched.If +the default is inappropriate for your application or a particular +persistent field, set `+fetch+` to `+FetchType.LAZY+`: this is a hint to +the persistence provider that data should be fetched lazily when it is +first accessed (if possible). We recommend using the FetchType.LAZY on +all relationships. You are not required to provide value for this +attribute. For more information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Lazy_Loading[What +You May Need to Know About EclipseLink JPA Lazy Loading]. +* `+mappedBy+` – By default, EclipseLink persistence provider infers the +associated target entity from the type of the object being referenced. +Use the `+mappedBy+` attribute if the relationship is bidirectional and +the target entity has an inverse one-to-one relationship that has +already been mapped. You can only use `+mappedBy+` on the side of the +relationship that does not define the foreign key in its table. This is +the only way in JPA to define a target foreign key relationship. For +example, if the foreign key for the one-to-one is in the target entity’s +table, you must define the one-to-one mapping on both sides of the +relationship and use the `+mappedBy+` on the target foreign key side. +For more information on target foreign keys, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-One +Mapping]. ++ +You are not required to specify the value of this attribute. +* `+optional+` – By default, EclipseLink persistence provider assumes +that the value of all (nonprimitive) fields and properties may be +`+null+`. ++ +The default value of this attribute is `+true+`. If the default is +inappropriate for your application, set value of this attribute to +`+false+`. ++ +You are not required to specify the value of this attribute. +* `+targetEntity+` – By default, EclipseLink persistence provider infers +the associated target entity from the type of the object being +referenced. If the persistence provider cannot infer the type of the +target entity, then set the `+targetEntity+` element on owning side of +the association to the `+Class+` of the entity that is the target of the +relationship. ++ +You are not required to specify the value of this attribute. + +The link:#Example_18-17[Usage of @OneToOne Annotation - Customer Class] +and link:#Example_18-18[Usage of @OneToOne Annotation - CustomerRecord +Class] examples show how to use this annotation to configure a +one-to-one mapping between `+Customer+` (the owning side) and +`+CustomerRecord+` (the owned side). + +[#Example 18-17]## *_Usage of @OneToOne Annotation - Customer Class_* + +[source,java] +---- + @Entity + public class Customer implements Serializable { + ... + @OneToOne(optional=false) + @JoinColumn(name="CUSTREC_ID", unique=true, nullable=false, updatable=false) + public CustomerRecord getCustomerRecord() { + return customerRecord; + } + ... + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You have to provide a `+@JoinColumn+` (see Section 9.1.6 +"`JoinColumn Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) for a `+@OneToOne+` defining the foreign key. Otherwise, +the foreign key will be assumed to be the `+_+` or `+_+`. +|=== + +Use either a `+@JoinColumn+` or a `+@JoinTable+` (see Section 9.1.25 +"`JoinTable Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) with the mapping; if you do not specify any of them, +EclipseLink will default to `+@JoinTable+` with the join table name +format of `+_+` in uppercase characters, and with columns format of +`+_+`, `+_+` (or _ ) in uppercase characters. + +[#Example 18-18]## *_Usage of @OneToOne Annotation - CustomerRecord +Class_* + +[source,java] +---- + @Entity + public class CustomerRecord implements Serializable { + ... + @OneToOne(optional=false, mappedBy="customerRecord") + public Customer getCustomer() { + return customer; + } + ... + } +---- + +For more information and examples, see Section 9.1.23 "`OneToOne +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +For more information on EclipseLink direct mappings and relationship +mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +For more information, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-One_Mapping[One-to-One +Mapping] and +link:Configuring_a_Relational_One-to-One_Mapping_(ELUG)[Configuring a +Relational One-to-One Mapping]. + +=== @ManyToOne + +By default, JPA automatically defines a `+ManyToOne+` mapping for a +single-valued association to another entity class that has many-to-one +multiplicity. + +Use the `+ManyToOne+` annotation to do the following: + +* configure the fetch type to `+LAZY+`; +* configure the mapping to forbid null values (for nonprimitive types) +in case null values are inappropriate for your application; +* configure the associated target entity, if it cannot be inferred from +the type of the object being referenced; +* configure the operations that must be cascaded to the target of the +association (for example, if the owning entity is removed, ensure that +the target of the association is also removed). + +The `+@ManyToOne+` annotation has the following attributes: + +* `+cascade+` – By default, JPA does not cascade any persistence +operations to the target of the association. Thus, the default value of +this attribute is an empty `+javax.persistence.CascadeType+` array. If +you want some or all persistence operations cascaded to the target of +the association, set the value of this attribute to one or more +`+CascadeType+` instances, including the following: +** `+ALL+` – Any persistence operation performed on the owning entity is +cascaded to the target of the association. +** `+MERGE+` – If the owning entity is merged, the merge is cascaded to +the target of the association. +** `+PERSIST+` – If the owning entity is persisted, the persist is +cascaded target of the association. +** `+REFRESH+` – If the owning entity is refreshed, the refresh is +cascaded target of the association. +** `+REMOVE+` – If the owning entity is removed, the target of the +association is also removed. ++ +You are not required to provide value for this attribute. +* `+fetch+` – By default, EclipseLink persistence provider uses a fetch +type of javax.persitence.`+FetchType.EAGER+`: this is a requirement on +the persistence provider runtime that data must be eagerly fetched. If +the default is inappropriate for your application or a particular +persistent field, set `+fetch+` to `+FetchType.LAZY+`: this is a hint to +the persistence provider that data should be fetched lazily when it is +first accessed (if possible). ++ +You are not required to provide value for this attribute. For more +information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Lazy_Loading[What +You May Need to Know About EclipseLink JPA Lazy Loading]. +* `+optional+` – By default, EclipseLink persistence provider assumes +that the value of all (nonprimitive) fields and properties may be +`+null+`. ++ +The default value of this attribute is `+true+`. If the default is +inappropriate for your application, set value of this attribute to +`+false+`. ++ +You are not required to specify the value of this attribute. +* `+targetEntity+` – By default, EclipseLink persistence provider infers +the associated target entity from the type of the object being +referenced. If the persistence provider cannot infer the type of the +target entity, then set the `+targetEntity+` element on owning side of +the association to the `+Class+` of the entity that is the target of the +relationship. ++ +You are not required to specify the value of this attribute. + +This example shows how to use this annotation to configure a many-to-one +mapping between `+Customer+` (the owned side) and `+Order+` (the owning +side) using generics. + +[#Example 18-19]## *_Usage of @ManyToOne Annotation_* + +[source,java] +---- + @Entity + public class Order implements Serializable { + ... + @ManyToOne(optional=false) + @JoinColumn(name="CUST_ID", nullable=false, updatable=false) + public Customer getCustomer() { + return customer; + } + ... + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* You have to provide a `+@JoinColumn+` (see Section 9.1.6 +"`JoinColumn Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) for a `+@ManyToOne+` defining the foreign key. +Otherwise, the foreign key will be assumed to be the `+_+` or _ . +|=== + +Use either a `+@JoinColumn+` or a `+@JoinTable+` (see Section 9.1.25 +"`JoinTable Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) with the mapping; if you do not specify any of them, +EclipseLink will default to `+@JoinTable+` with the join table name +format of `+_+` in uppercase characters, and with columns format of +`+_+`, `+_+` (or _ ) in uppercase characters. + +For more information and examples, see Section 9.1.22 "`ManyToOne +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +For more information on EclipseLink direct mappings and relationship +mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +=== @OneToMany + +By default, JPA automatically defines a `+OneToMany+` mapping for a +many-valued association with one-to-many multiplicity. + +Use the `+OneToMany+` annotation to do the following: + +* configure the fetch type to `+EAGER+`; +* configure the associated target entity, because the `+Collection+` +used is not defined using generics; +* configure the operations that must be cascaded to the target of the +association: for example, if the owning entity is removed, ensure that +the target of the association is also removed; +* configure the details of the join table used by the persistence +provider for unidirectional one-to-many relationships (see Section +9.1.25 "`JoinTable Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]). + +The `+@OneToMany+` annotation has the following attributes: + +* `+cascade+` – By default, JPA does not cascade any persistence +operations to the target of the association. Thus, the default value of +this attribute is an empty `+javax.persitence.CascadeType+` array. If +you want some or all persistence operations cascaded to the target of +the association, set the value of this attribute to one or more +`+CascadeType+` instances, including the following: +** `+ALL+` – Any persistence operation performed on the owning entity is +cascaded to the target of the association. +** `+MERGE+` – If the owning entity is merged, the merge is cascaded to +the target of the association. +** `+PERSIST+` – If the owning entity is persisted, the persist is +cascaded target of the association. +** `+REFRESH+` – If the owning entity is refreshed, the refresh is +cascaded target of the association. +** `+REMOVE+` – If the owning entity is removed, the target of the +association is also removed. ++ +You are not required to provide value for this attribute. +* `+fetch+` – By default, EclipseLink persistence provider uses a fetch +type of javax.persitence.`+FetchType.LAZY+`: this is a hint to the +persistence provider that data should be fetched lazily when it is first +accessed (if possible). If the default is inappropriate for your +application or a particular persistent field, set `+fetch+` to +`+FetchType.EAGER+`: this is a requirement on the persistence provider +runtime that data must be eagerly fetched. ++ +You are not required to provide value for this attribute. For more +information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Lazy_Loading[What +You May Need to Know About EclipseLink JPA Lazy Loading]. +* `+mappedBy+` – By default, if the relationship is unidirectional, +EclipseLink persistence provider determines the field that owns the +relationship. If the relationship is bidirectional, then set the +`+mappedBy+` element on the inverse (non-owning) side of the association +to the name of the field or property that owns the relationship, as the +link:#Example_18-21[Usage of @ManyToOne Annotation - Order Class with +Generics] example shows. ++ +You are not required to specify the value of this attribute. +* `+targetEntity+` – By default, if you are using a `+Collection+` +defined using generics, then the persistence provider infers the +associated target entity from the type of the object being referenced. +Thus, the default is the parameterized type of the `+Collection+` when +defined using generics. If your `+Collection+` does not use generics, +then you must specify the entity class that is the target of the +association: set the `+targetEntity+` element on owning side of the +association to the `+Class+` of the entity that is the target of the +relationship. ++ +You are not required to specify the value of this attribute. + +The link:#Example_18-20[Usage of @OneToMany Annotation - Customer Class +with Generics] and link:#Example_18-21[Usage of @ManyToOne Annotation - +Order Class with Generics] examples show how to use this annotation to +configure a one-to-many mapping between `+Customer+` (the owned side) +and `+Order+` (the owning side) using generics. + +[#Example 18-20]## *_Usage of @OneToMany Annotation - Customer Class +with Generics_* + +[source,java] +---- + @Entity + public class Customer implements Serializable { + ... + @OneToMany(cascade=ALL, mappedBy="customer") + public Set getOrders() { + return orders; + } + ... + } +---- + +[#Example 18-21]## *_Usage of @ManyToOne Annotation - Order Class with +Generics_* + +[source,java] +---- + @Entity + public class Order implements Serializable { + ... + @ManyToOne + @JoinColumn(name="CUST_ID", nullable=false) + public Customer getCustomer() { + return customer; + } + ... + } +---- + +For more information and examples, see Section 9.1.24 "`OneToMany +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +For more information on EclipseLink direct mappings and relationship +mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +For more information on EclipseLink one-to-one mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#One-to-Many_Mapping[One-to-Many +Mapping], and for information on how to configure these mappings, see +link:Configuring_a_Relational_One-to-Many_Mapping_(ELUG)[Configuring a +Relational One-to-Many Mapping]. + +=== @ManyToMany + +By default, JPA automatically defines a `+ManyToMany+` mapping for a +many-valued association with many-to-many multiplicity. + +Use the `+@ManyToMany+` annotation to do the following: + +* configure the fetch type to `+EAGER+`; +* configure the mapping to forbid null values (for nonprimitive types) +in case `+null+` values are inappropriate for your application; +* configure the associated target entity because the `+Collection+` used +is not defined using generics; +* configure the operations that must be cascaded to the target of the +association (for example, if the owning entity is removed, ensure that +the target of the association is also removed). + +The `+@ManyToMany+` annotation has the following attributes: + +* `+cascade+` – By default, JPA does not cascade any persistence +operations to the target of the association. Thus, the default value of +this attribute is an empty `+javax.persitence.CascadeType+` array. If +you want some or all persistence operations cascaded to the target of +the association, set the value of this attribute to one or more +`+CascadeType+` instances, including the following: +** `+ALL+` – Any persistence operation performed on the owning entity is +cascaded to the target of the association. +** `+MERGE+` – If the owning entity is merged, the merge is cascaded to +the target of the association. +** `+PERSIST+` – If the owning entity is persisted, the persist is +cascaded target of the association. +** `+REFRESH+` – If the owning entity is refreshed, the refresh is +cascaded target of the association. +** `+REMOVE+` – If the owning entity is removed, the target of the +association is also removed. ++ +You are not required to provide value for this attribute. +* `+fetch+` – By default, EclipseLink persistence provider uses a fetch +type of `+javax.persitence.FetchType.LAZY+`: this is a hint to the +persistence provider that data should be fetched lazily when it is first +accessed (if possible). If the default is inappropriate for your +application or a particular persistent field, set `+fetch+` to +`+FetchType.EAGER+`: this is a requirement on the persistence provider +runtime that data must be eagerly fetched. ++ +You are not required to provide value for this attribute. For more +information, see +link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_EclipseLink_JPA_Lazy_Loading[What +You May Need to Know About EclipseLink JPA Lazy Loading]. +* `+mappedBy+` – By default, if the relationship is unidirectional, +EclipseLink persistence provider determines the field that owns the +relationship. If the relationship is bidirectional, then set the +`+mappedBy+` element on the inverse (non-owning) side of the association +to the name of the field or property that owns the relationship, as the +link:#Example_18-23[Usage of @ManyToMany Annotation - Project Class with +Generics] example shows. ++ +You are not required to specify the value of this attribute. +* `+targetEntity+` – By default, if you are using a `+Collection+` +defined using generics, then the persistence provider infers the +associated target entity from the type of the object being referenced. +Thus, the default is the parameterized type of the `+Collection+` when +defined using generics. If your `+Collection+` does not use generics, +then you must specify the entity class that is the target of the +association: set the `+targetEntity+` element on owning side of the +association to the `+Class+` of the entity that is the target of the +relationship. ++ +You are not required to specify the value of this attribute. + +The link:#Example_18-22[Usage of @ManyToMany Annotation - Employee Class +with Generics] and link:#Example_18-23[Usage of @ManyToMany Annotation - +Project Class with Generics] examples show how to use this annotation to +configure a many-to-many mapping between `+Employee+` and `+Project+` +using generics. + +[#Example 18-22]## *_Usage of @ManyToMany Annotation - Employee Class +with Generics_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + @Id + private int id; + private String name; + @ManyToMany + @JoinTable(name="EMP_PROJ", + joinColumns= + @JoinColumn(name="EMP_ID"), + inverseJoinColumns= + @JoinColumn(name="PROJ_ID) + ) + private Collection projects; + ... + } +---- + +[width="100%",cols="<100%",] +|=== +|*Note:* Use a `+@JoinTable+` (see Section 9.1.25 "`JoinTable +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]) annotation to define a many-to-many join table; if you +do not specify this annotation, EclipseLink will default to +`+@JoinTable+` with the join table name format of `+_+` in uppercase +characters, and with columns format of `+_+`, `+_+` (or _ ) in uppercase +characters. +|=== + +[#Example 18-23]## *_Usage of @ManyToMany Annotation - Project Class +with Generics_* + +[source,java] +---- + @Entity + public class Project implements Serializable { + ... + @ManyToMany(mappedBy="projects") + public Set getEmployees() { + return employees; + } + ... + } +---- + +For more information and examples, see Section 9.1.26 "`ManyToMany +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +For more information on EclipseLink direct mappings and relationship +mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational_Mapping_Types[Relational +Mapping Types]. + +For more information on EclipseLink one-to-one mappings, see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many_Mapping[Many-to-Many +Mapping], and for information on how to configure these mappings, see +link:Configuring_a_Relational_Many-to-Many_Mapping_(ELUG)[Configuring a +Relational Many-to-Many Mapping]. + +=== @MapKey + +By default, EclipseLink persistence provider assumes that the primary +key of the associated entity is the map key for associations of type +`+java.util.Map+`. If the primary key is a noncomposite primary key +annotated with the link:#@Id[@Id annotation], an instance of this field +or property’s type is used as the map key. + +Use the `+@MapKey+` annotation to specify the following: + +* some other field or property as the map key if the primary key of the +associated entity is not appropriate for your application; +* an embedded composite primary key class (see +link:#@EmbeddedId[@EmbeddedId]). + +The field or property you specify must have a unique constraint (see +Section 9.1.4 "`UniqueConstraint Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]). + +The `+@MapKey+` annotation has the following attributes: + +* `+name+` – By default, EclipseLink persistence provider uses the +primary key of the associated entity as the `+Map+` key for a property +or field mapped to a `+java.util.Map+` for noncomposite primary keys, or +composite primary keys annotated with the `+@IdClass+` annotation (see +link:#@IdClass[@IdClass]). If you want to use some other field or +property as the map key, set name to the associated entity’s `+String+` +field or property name to use. ++ +You are not required to provide value for this attribute. + +In the link:#Example_18-24[Project Entity Using @MapKey Annotation] +example, `+Project+` owns a one-to-many relationship to instances of +`+Employee+` as a `+Map+`. The link:#Example_18-24[Project Entity Using +@MapKey Annotation] example shows how to use the `+@MapKey+` annotation +to specify that the key for this `+Map+` is `+Employee+` field +`+empPK+`, an embedded composite primary key (see the +link:#Example_18-25[Employee Entity] example) of type `+EmployeePK+` +(see the link:#Example_18-24[Project Entity Using @MapKey Annotation] +example). + +[#Example 18-24]## *_Project Entity Using @MapKey Annotation_* + +[source,java] +---- + @Entity + public class Project implements Serializable { + ... + @OneToMany(mappedBy="project") + @MapKey(name="empPK") + public Map getEmployees() { + ... + } + ... + } +---- + +[#Example 18-25]## *_Employee Entity_* + +[source,java] +---- + @Entity + public class Employee implements Serializable { + ... + @EmbeddedId + public EmployeePK getEmpPK() { + ... + } + + @ManyToOne + @JoinColumn(name="proj_id") + public Project getProject() { + ... + } + ... + } +---- + +[#Example 18-26]## *_EmployeePK Composite Primary Key Class_* + +[source,java] +---- + @Embeddable + public class EmployeePk { + + String name; + Date birthDate; + ... + } +---- + +For more information and examples, see Section 9.1.27 "`MapKey +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @OrderBy + +Use the `+@OrderBy+` annotation with `+@OneToMany+` and `+@ManyToMany+` +to specify the following: + +* one or more other field or property names to order by; +* different orders (ascending or descending) for each such field or +property names. + +The `+@OrderBy+` annotation has the following attributes: + +* `+value+` – By default, EclipseLink persistence provider retrieves the +members of an association in ascending order by primary key of the +associated entities. If you want to order by some other fields or +properties and specify different, set `+value+` to a comma-separated +list of the following elements: "``+property-or-field-name ASC|DESC+``" +(see Example 1-65). ++ +You are not required to provide value for this attribute. + +This example shows how to use the `+@OrderBy+` annotation to specify +that the `+Project+` method `+getEmployees+` should return a `+List+` of +`+Employee+` in ascending order by `+Employee+` field `+lastname+`, and +in descending order by `+Employee+` field `+seniority+`. + +[#Example 18-27]## *_Project Entity Using @OrderBy Annotation_* + +[source,java] +---- + @Entity + public class Project implements Serializable { + ... + @ManyToMany(mappedBy="project") + @OrderBy("lastname ASC, seniority DESC") + public List getEmployees() { + ... + } + ... + } +---- + +For more information and examples, see Section 9.1.28 "`OrderBy +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +== Mapping Inheritance + +By default, EclipseLink persistence provider assumes that all persistent +fields are defined by a single entity class. + +Use the following annotations if your entity class inherits some or all +persistent fields from one or more superclasses: + +* link:#@Inheritance[@Inheritance] +* link:#@MappedSuperclass[@MappedSuperclass] +* link:#@DiscriminatorColumn[@DiscriminatorColumn] +* link:#@DiscriminatorValue[@DiscriminatorValue] + +For more information, see Section 2.1.9 "`Inheritance`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +You can access advanced inheritance options through EclipseLink +descriptor API +link:Customizing%20the%20EclipseLink%20Application%20(ELUG)#Using_the_Descriptor_Customizer_Class[using +a DescriptorCustomizer class]. + +=== @Inheritance + +By default, the EclipseLink persistence provider automatically manages +the persistence of entities in an inheritance hierarchy. + +Use the `+@Inheritance+` annotation to customize the persistence +provider’s inheritance hierarchy support to improve application +performance or to match an existing data model. + +The `+@Inheritance+` annotation has the following attributes: + +* `+strategy+` – By default, the EclipseLink persistence provider +assumes that all the classes in a hierarchy are mapped to a single table +differentiated by the discriminator value (see +link:#@DiscriminatorValue[@DiscriminatorValue]) in the table’s +discriminator column (see +link:#@DiscriminatorColumn[@DiscriminatorColumn]): +`+InheritanceType.SINGLE_TABLE+`. If this is not appropriate for your +application or if you must match an existing data model, set +`+strategy+` to the desired `+InheritanceType+` enumerated type: +** `+SINGLE_TABLE+` – all the classes in a hierarchy are mapped to a +single table. The table has a discriminator column +(link:#@DiscriminatorColumn[@DiscriminatorColumn]) whose value +(link:#@DiscriminatorValue[@DiscriminatorValue]) identifies the specific +subclass to which the instance that is represented by the row belongs. ++ ++ ++ ++ +*Note:* This option provides the best support for both polymorphic +relationships between entities and queries that range over the class +hierarchy. The disadvantages of this option include the need to make +nullable columns that should be `+NOT NULL+`. ++ ++ ++ ++ +For more information, see Section 2.1.10.1 "`Single Table per Class +Hierarchy Strategy`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. +** `+TABLE_PER_CLASS+` – each class is mapped to a separate table. All +properties of the class, including inherited properties, are mapped to +columns of the table for the class. ++ ++ ++ ++ +*Note:* This option is available starting in EclipseLink Release 1.1. +For earlier versions, you can instead either map each entity subclass +independently, or use a link:#@MappedSuperclass[`+@MappedSuperclass+`]. ++ ++ ++ ++ +For more information, see Section 2.1.10.2 "`Table per Concrete Class +Strategy`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. +** `+JOINED+` – the root of the class hierarchy is represented by a +single table and each subclass is represented by a separate table. Each +subclass table contains only those fields that are specific to the +subclass (not inherited from its superclass) and primary key columns +that serve as foreign keys to the primary keys of the superclass table. +For more information, see Section 2.1.10.3 "`Joined Subclass Strategy`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. ++ +You are not required to specify the value of this attribute. + +This example shows how to use this annotation to specify that all +subclasses of `+Customer+` will use `+InheritanceType.JOINED+`. The +subclass in the link:#Example_18-29[@Inheritance - Subclass Using +JOINED] example will be mapped to its own table that contains a column +for each the persistent properties of `+ValuedCustomer+` and one foreign +key column that contains the primary key to the `+Customer+` table. + +[#Example 18-28]## *_@Inheritance - Root Class Using JOINED_* + +[source,java] +---- + import static javax.persistence.InheritanceType.JOINED; + @Entity + @Inheritance(strategy=JOINED) + public class Customer implements Serializable { + + @Id + private int customerId; + ... + } +---- + +[#Example 18-29]## *_@Inheritance - Subclass Using JOINED_* + +[source,java] +---- + @Entity + public class ValuedCustomer extends Customer { + ... + } +---- + +In the link:#Example_18-30[@Inheritance - Root Class Specifying its +Discriminator Column] example, by default, +`+InheritanceType.SINGLE_TABLE+` applies to `+Customer+` and all its +subclasses. In this example, the default discriminator table column +`+DTYPE+` (link:#@DiscriminatorColumn[@DiscriminatorColumn]) is +specified as having a discriminator type of `+INTEGER+` and the +`+@DiscriminatorValue+` for `+Customer+` is specified as 1. The +link:#Example_18-31[@Inheritance - Subclass Specifying its Discriminator +Value] example shows how to specify the discriminator value for subclass +`+ValuedCustomer+` as 2. In this example, all the persistent properties +of both `+Customer+` and `+ValuedCustomer+` will be mapped to a single +table. + +[#Example 18-30]## *_@Inheritance - Root Class Specifying its +Discriminator Column_* + +[source,java] +---- + @Entity + @DiscriminatorColumn(discriminatorType=DiscriminatorType.INTEGER) + @DiscriminatorValue(value="1") + public class Customer implements Serializable { + ... + } +---- + +[#Example 18-31]## *_@Inheritance - Subclass Specifying its +Discriminator Value_* + +[source,java] +---- + @Entity + @DiscriminatorValue(value="2") + public class ValuedCustomer extends Customer { + ... + } +---- + +For more information, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 2.1.9 "`Inheritance`" +* Section 2.1.10 "`Inheritance Mapping Strategies`" +* Section 9.1.29 "`Inheritance Annotation`" + +=== @MappedSuperclass + +By default, a EclipseLink persistence provider assumes that all the +persistent fields of an entity are defined in that entity. + +The `+@MappedSuperclass+` annotation lets you define mappings in a +nonpersistent abstract superclass and enable their inheritance by the +subclasses. You can use the link:#@AttributeOverride[@AttributeOverride] +and link:#@AssociationOverride[@AssociationOverride] annotations to +override the mapping information in these subclasses. + +Use the `+@MappedSuperclass+` annotation to designate a superclass from +which your entity class inherits persistent fields. This is a convenient +pattern when multiple entity classes share common persistent fields or +properties. + +You can annotate this superclass’ fields and properties with any of the +direct and relationship mapping annotations (such as +link:#@Basic[@Basic] and link:#@ManyToMany[@ManyToMany]) as you would +for an entity, but these mappings apply only to its subclasses since no +table exists for the superclass itself. The inherited persistent fields +or properties belong to the subclass’ table. + +The `+@MappedSuperclass+` annotation does not have any attributes. + +This example shows how to use the `+@MappedSuperclass+` annotation to +specify `+Employee+` as a mapped superclass. The +link:#Example_18-33[Extending a Mapped Superclass] example shows how to +extend this superclass in an entity and how to use the +`+@AttributeOverride+` annotation in the entity class to override +configuration made in the superclass. + +[#Example 18-32]## *_Usage of the @MappedSuperclass Annotation_* + +[source,java] +---- + @MappedSuperclass + public class Employee implements Serializable { + + @Id + protected Integer empId; + @Version + protected Integer version; + + @ManyToOne + @JoinColumn(name="ADDR") + protected Address address; + + ... + } +---- + +[#Example 18-33]## *_Extending a Mapped Superclass_* + +[source,java] +---- + @Entity + @AttributeOverride(name="address", column=@Column(name="ADDR_ID")) + public class PartTimeEmployee extends Employee { + @Column(name="WAGE") + protected Float hourlyWage; + + ... + } +---- + +For more information, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 9.1.36 "`MappedSuperclass Annotation`" +* Section 2.1.9.2 "`Mapped Superclasses`" +* Section 2.1.10 "`Inheritance Mapping Strategies`" + +=== @DiscriminatorColumn + +By default, when link:#@Inheritance[@Inheritance] attribute strategy is +`+InheritanceType.SINGLE_TABLE+` or `+JOINED+`, EclipseLink persistence +provider creates a discriminator column named `+DTYPE+` to differentiate +classes in an inheritance hierarchy. + +Use the `+@DiscriminatorColumn+` annotation to do the following: + +* specify a discriminator column name if the column name in your data +model is not the default column name `+DTYPE+`; +* specify a discriminator column length that is appropriate for your +application or a preexisting data model; +* fine-tune the characteristics of the discriminator column in your +database. + +The `+@DiscriminatorColumn+` annotation has the following attributes: + +* `+columnDefinition+` – By default, EclipseLink persistence provider +creates a database table column with minimal SQL: empty `+String+`. If +you want the column created with more specialized options, set the value +of this attribute to the SQL fragment that you want JPA to use when +generating the DDL for the column. ++ +You are not required to specify the value of this attribute. +* `+discriminatorType+` – By default, EclipseLink persistence provider +assumes that the discriminator type is a `+String+`: +`+DiscriminatorType.STRING+`. If you want to use a different type, set +the value of this attribute to `+DiscriminatorType.CHAR+` or +`+DiscriminatorType.INTEGER+`. ++ +Your link:#@DiscriminatorValue[@DiscriminatorValue] must conform to this +type. ++ +You are not required to specify the value of this attribute. +* `+length+` – By default, EclipseLink persistence provider assumes that +the discriminator column has a maximum length of 255 characters when +used to hold a `+String+` value. Default value of this attribute is +[arabic, start=31] +. If this column width is inappropriate for your application or +database, set the length to the int value appropriate for your database +column. ++ +Your link:#@DiscriminatorValue[@DiscriminatorValue] must conform to this +type. ++ +You are not required to specify the value of this attribute. +* `+name+` – By default, EclipseLink persistence provider assumes that +the discriminator column is named "``+DTYPE+``". ++ +To specify an alternative column name, set name to the `+String+` column +name you want. ++ +You are not required to specify the value of this attribute. + +The link:#Example_18-34[@DiscriminatorColumn and @DiscriminatorValue - +Root Class] example shows how to use this annotation to specify a +discriminator column named `+DISC+` of type `+STRING+` and length 20. In +this example, the link:#@DiscriminatorValue[@DiscriminatorValue] for +this class is specified as `+CUST+`. The subclass in the +link:#Example_18-35[@DiscriminatorValue - Subclass] example specifies +its own `+@DiscriminatorValue+` of `+VIP+`. In both `+Customer+` and +`+ValuedCustomer+`, the value for `+@DiscriminatorValue+` must be +convertible to the type specified by `+@DiscriminatorColumn+` attribute +`+discriminatorType+` and must conform to `+@DiscriminatorColumn+` +attribute `+length+`. + +[#Example 18-34]## *_@DiscriminatorColumn and @DiscriminatorValue - Root +Class_* + +[source,java] +---- + @Entity + @Table(name="CUST") + @Inheritance(strategy=SINGLE_TABLE) + @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) + @DiscriminatorValue(value="CUST") + public class Customer implements Serializable { + ... + } +---- + +[#Example 18-35]## *_@DiscriminatorValue - Subclass_* + +[source,java] +---- + @Entity + @DiscriminatorValue(value="VIP") + public class ValuedCustomer extends Customer { + ... + } +---- + +For more information, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 9.1.30 "`DiscriminatorColumn Annotation`" +* Section 9.1.31 "`DiscriminatorValue Annotation`" +* Section 2.1.10 "`Inheritance Mapping Strategies`" + +=== @DiscriminatorValue + +By default, when `+@Inheritance+` attribute strategy is +`+InheritanceType.SINGLE_TABLE+` or `+JOINED+`, EclipseLink persistence +provider uses a `+@DiscriminatorColumn+` to differentiate classes in the +inheritance hierarchy by entity name (see Section 8.1 "`Entity`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]). + +Use the `+@DiscriminatorValue+` annotation to specify the discriminator +value used to differentiate an entity in this inheritance hierarchy: + +* if the entity name is inappropriate for this application; +* to match an existing database schema; + +The `+@DiscriminatorValue+` annotation has the following attributes: + +* `+value+` – Set value to the `+String+` equivalent of a discriminator +value that conforms to the `+@DiscriminatorColumn+` attributes +`+discriminatorType+` and `+length+`. ++ +You are required to specify the value of this attribute. + +The link:#Example_18-36[@DiscriminatorColumn and @DiscriminatorValue - +Root Class] example shows how to use this annotation to specify a +discriminator column named `+DISC+` of type `+STRING+` and length 20. In +this example, the `+@DiscriminatorValue+` for this class is specified as +`+CUST+`. The subclass in the link:#Example_18-37[@DiscriminatorValue - +Subclass] example specifies its own `+@DiscriminatorValue+` of `+VIP+`. +In both `+Customer+` and `+ValuedCustomer+`, the value for +`+@DiscriminatorValue+` must be convertible to the type specified by +`+@DiscriminatorColumn+` attribute `+discriminatorType+` and must +conform to `+@DiscriminatorColumn+` attribute `+length+`. + +[#Example 18-36]## *_@DiscriminatorColumn and @DiscriminatorValue - Root +Class_* + +[source,java] +---- + @Entity + @Table(name="CUST") + @Inheritance(strategy=SINGLE_TABLE) + @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) + @DiscriminatorValue(value="CUST") + public class Customer implements Serializable { + ... + } +---- + +[#Example 18-37]## *_@DiscriminatorValue - Subclass_* + +[source,java] +---- + @Entity + @DiscriminatorValue(value="VIP") + public class ValuedCustomer extends Customer { + ... + } +---- + +For more information, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 9.1.30 "`DiscriminatorColumn Annotation`" +* Section 9.1.31 "`DiscriminatorValue Annotation`" +* Section 2.1.10 "`Inheritance Mapping Strategies`" + +== Using Embedded Objects + +An embedded object does not have its own persistent identity – it is +dependent upon an entity for its identity. For more information, see +Section 2.1.5 "`Embeddable Classes`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +By default, EclipseLink persistence provider assumes that every entity +is mapped to its own table. Use the following annotations to override +this behavior for entities that are owned by other entities: + +* link:#@Embeddable[@Embeddable] +* link:#@Embedded[@Embedded] +* link:#@AttributeOverride[@AttributeOverride] +* link:#@AttributeOverrides[@AttributeOverrides] +* link:#@AssociationOverride[@AssociationOverride] +* link:#@AssociationOverrides[@AssociationOverrides] + +For information on EclipseLink aggregate descriptors, refer to +link:Introduction%20to%20Relational%20Descriptors%20(ELUG)#Aggregate_and_Composite_Descriptors_in_Relational_Projects[Aggregate +and Composite Descriptors in Relational Projects]; for aggregates +advanced configuration options, refer to EclipseLink API. + +=== @Embeddable + +Use the `+@Embeddable+` annotation to specify a class whose instances +are stored as an intrinsic part of an owning entity and share the +identity of the entity. Each of the persistent properties or fields of +the embedded object is mapped to the database table for the entity. + +The `+@Embeddable+` annotation does not have attributes. + +The link:#Example_18-38[Usage of the @Embeddable Annotation] example +shows how to use this annotation to specify that class +`+EmploymentPeriod+` may be embedded in an entity when used as the type +for a persistent field annotated as `+@Embedded+` (see +thelink:#Example_18-39[Usage of the @Embedded Annotation] and +link:#@Embedded[@Embedded] examples). + +[#Example 18-38]## *_Usage of the @Embeddable Annotation_* + +[source,java] +---- + @Embeddable + public class EmploymentPeriod { + + java.util.Date startDate; + java.util.Date endDate; + ... + } +---- + +For more information, see Section 9.1.34 "`Embeddable Annotation`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +=== @Embedded + +Use the `+@Embedded+` annotation to specify a persistent field whose +link:#@Embeddable[@Embeddable] type can be stored as an intrinsic part +of the owning entity and share the identity of the entity. Each of the +persistent properties or fields of the embedded object is mapped to the +database table for the owning entity. + +You can use the `+@Embedded+` annotation in conjunction with +`+@Embeddable+` to model a strict ownership relationship so that if the +owning object is removed, the owned object is also removed. + +Embedded objects should not be mapped across more than one table. + +By default, column definitions (see Section 9.1.5 "`Column Annotation`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]) specified +in the `+@Embeddable+` class apply to the `+@Embedded+` class. If you +want to override these column definitions, use the +link:#@AttributeOverride[@AttributeOverride] annotation. + +The `+@Embedded+` annotation does not have attributes. + +The link:#Example_18-39[Usage of the @Embedded Annotation] example shows +how to use this annotation to specify that `+@Embeddable+` class +`+EmploymentPeriod+` (see the link:#Example_18-38[Usage of the +@Embeddable Annotation]) example may be embedded in the entity class +using the specified attribute overrides +(link:#@AttributeOverride[@AttributeOverride]). If you do not need +attribute overrides, you can omit the `+@Embedded+` annotation entirely: +EclipseLink persistence provider will infer that `+EmploymentPeriod+` is +embedded from its `+@Embeddable+` annotation. + +[#Example 18-39]## *_Usage of the @Embedded Annotation_* + +[source,java] +---- + @Embeddable + public class Employee implements Serializable { + ... + @Embedded + @AttributeOverrides({ + @AttributeOverride(name="startDate", column=@Column(name="EMP_START")), + @AttributeOverride(name="endDate", column=@Column(name="EMP_END"))}) + public EmploymentPeriod getEmploymentPeriod() { + ... + } + ... + } +---- + +For more information, see Section 9.1.35 "`Embedded Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +=== @AttributeOverride + +By default, EclipseLink persistence provider automatically assumes that +a subclass inherits both persistent properties and their basic mappings +from the superclass. + +Use the `+@AttributeOverride+` annotation to customize a basic mapping +inherited from a link:#@MappedSuperclass[@MappedSuperclass] or +link:#@Embeddable[@Embeddable] to change the `+@Column+` (see Section +9.1.5 "`Column Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) associated with +the field or property if the inherited column definition is incorrect +for your entity (for example, if the inherited column name is +incompatible with a preexisting data model, or invalid as a column name +in your database). + +If you have more than one `+@AttributeOverride+` change to make, you +must use the link:#@AttributeOverrides[@AttributeOverrides] annotation. + +To customize an association mapping to change its `+@JoinColumn+` (see +Section 9.1.6 "`JoinColumn Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), use the +link:#@AssociationOverride[@AssociationOverride] annotation. + +The `+@AttributeOverride+` annotation has the following attributes: + +* `+column+` – The `+@Column+` that is being mapped to the persistent +attribute. The mapping type will remain the same as is defined in the +embeddable class or mapped superclass. ++ +You are required to specify the value of this attribute. +* `+name+` – The name of the property in the embedded object that is +being mapped if property-based access is being used, or the name of the +field if field-based access is used. ++ +You are required to specify the value of this attribute. + +The link:#Example_18-40[Usage of the @MappedSuperclass Annotation] +example shows a `+@MappedSuperclass+` that the entity in the +link:#Example_18-41[Usage of the @AttributeOverride Annotation] example +extends. The link:#Example_18-41[Usage of the @AttributeOverride +Annotation] example shows how to use `+@AttributeOverride+` in the +entity subclass to override the `+@Column+` defined (by default) in the +`+@MappedSuperclass+` `+Employee+` for the basic mapping to `+Address+`. + +With the `+@AttributeOverride+`, the `+Employee+` table contains the +following columns: + +* `+ID+` +* `+VERSION+` +* `+ADDR_STRING+` +* `+WAGE+` + +Without the `+@AttributeOverride+`, the `+Employee+` table contains the +following columns: + +* `+ID+` +* `+VERSION+` +* `+ADDRESS+` +* `+WAGE+` + +[#Example 18-40]## *_Usage of the @MappedSuperclass Annotation_* + +[source,java] +---- + @MappedSuperclass + public class Employee { + + @Id + protected Integer id; + @Version + protected Integer version; + protected String address; + ... + } +---- + +[#Example 18-41]## *_Usage of the @AttributeOverride Annotation_* + +[source,java] +---- + @Entity + @AttributeOverride(name="address", column=@Column(name="ADDR_STRING")) + public class PartTimeEmployee extends Employee { + + @Column(name="WAGE") + protected Float hourlyWage; + ... + } +---- + +For more information, see Section 9.1.10 "`AttributeOverride +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @AttributeOverrides + +If you need to specify more than one +link:#@AttributeOverride[@AttributeOverride], you must specify all your +attribute overrides using a single `+@AttributeOverrides+` annotation. + +The `+@AttributeOverrides+` annotation has the following attributes: + +* `+value+` – To specify two or more attribute overrides, set `+value+` +to an array of `+AttributeOverride+` instances. ++ +You are required to specify the value of this attribute. + +This example shows how to use this annotation to specify two attribute +overrides. + +[#Example 18-42]## *_Usage of the @AttributeOverrides Annotation_* + +[source,java] +---- + @Entity + @AttributeOverrides({ + @AttributeOverride(name="address", column=@Column(name="ADDR_ID")), + @AttributeOverride(name="id", column=@Column(name="PTID")) + }) + public class PartTimeEmployee extends Employee { + + @Column(name="WAGE") + protected Float hourlyWage; + + public PartTimeEmployee() { + ... + } + + public Float getHourlyWage() { + ... + } + + public void setHourlyWage(Float wage) { + ... + } + } +---- + +For more information, see Section 9.1.11 "`AttributeOverrides +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @AssociationOverride + +By default, EclipseLink persistence provider automatically assumes that +a subclass inherits both persistent properties and their association +mappings from the superclass. + +Use the `+@AssociationOverride+` annotation to customize an +link:#@OneToOne[@OneToOne] or link:#@ManyToOne[@ManyToOne] mapping +inherited from a `+@MappedSuperclass+` (see +link:#@MappedSuperclass[@MappedSuperclass]) or +link:#@Embeddable[@Embeddable] to change the `+@JoinColumn+` (see +Section 9.1.6 "`JoinColumn Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) associated with +the field or property if the inherited column definition is incorrect +for your entity (for example, if the inherited column name is +incompatible with a preexisting data model, or invalid as a column name +in your database). + +If you have more than one `+@AssociationOverride+` change to make, you +must use the link:#@AssociationOverrides[@AssociationOverrides +annotation]. + +To customize an association mapping to change its `+@Column+` (see +Section 9.1.5 "`Column Annotation`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), use the +`+@AttributeOverride+` annotation. + +The `+@AssociationOverride+` annotation has the following attributes: + +* `+joinColumns+` – To specify the join columns that are being mapped to +the persistent attribute, set the `+joinColumns+` to an array of +`+JoinColumn+` instances (see Section 9.1.6 "`JoinColumn Annotation`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]). ++ +The mapping type will remain the same as is defined in the embeddable +class or mapped superclass. ++ +You are required to specify the value of this attribute. +* `+name+` – The name of the property in the embedded object that is +being mapped if property-based access is being used, or the name of the +field if field-based access is used. ++ +You are required to specify the value of this attribute. + +The link:#Example_18-43[Usage of the @MappedSuperclass Annotation] +example shows a link:#@MappedSuperclass[@MappedSuperclass] that the +entity in the link:#Example_18-44[Usage of the @AssociationOverride +Annotation] example extends. The link:#Example_18-44[Usage of the +@AssociationOverride Annotation] example shows how to use +`+@AssociationOverride+` in the entity subclass to override the +`+@JoinColumn+` defined (by default) in the `+@MappedSuperclass+` +`+Employee+` for the association to `+Address+`. + +With the `+@AssociationOverride+`, the `+Employee+` table contains the +following columns: + +* `+ID+` +* `+VERSION+` +* `+ADDR_ID+` +* `+WAGE+` + +Without the `+@AssociationOverride+`, the `+Employee+` table contains +the following columns: + +* `+ID+` +* `+VERSION+` +* `+ADDRESS+` +* `+WAGE+` + +[#Example 18-43]## *_Usage of the @MappedSuperclass Annotation_* + +[source,java] +---- + @MappedSuperclass + public class Employee { + + @Id + protected Integer id; + @Version + protected Integer version; + @ManyToOne + protected Address address; + ... + } +---- + +[#Example 18-44]## *_Usage of the @AssociationOverride Annotation_* + +[source,java] +---- + @Entity + @AssociationOverride(name="address", joinColumns=@JoinColumn(name="ADDR_ID")) + public class PartTimeEmployee extends Employee { + + @Column(name="WAGE") + protected Float hourlyWage; + ... + } +---- + +For more information, see Section 9.1.12 "`AssociationOverride +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +=== @AssociationOverrides + +If you need to specify more than one +link:#@AssociationOverride[@AssociationOverride], you must specify all +your association overrides using a single `+@AssociationOverrides+` +annotation. + +The `+@AssociationOverrides+` annotation has the following attributes: + +* `+value+` – To specify two or more association overrides, set this +attribute to an array of `+AssociationOverride+` instances. ++ +You are required to specify the value of this attribute. + +This example shows how to use this annotation to specify two association +overrides. + +[#Example 18-45]## *_Usage of the @AssociationOverrides Annotation_* + +[source,java] +---- + @Entity + @AssociationOverrides({ + @AssociationOverride(name="address", joinColumn=@JoinColumn(name="ADDR_ID")), + @AssociationOverride(name="phone", joinColumn=@JoinColumn(name="PHONE_NUM")) + }) + public class PartTimeEmployee extends Employee { + + @Column(name="WAGE") + protected Float hourlyWage; + ... + } +---- + +For more information, see Section 9.1.13 "`AssociationOverrides +Annotation`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_JPA[Category: JPA] diff --git a/docs/docs.ug/src/main/asciidoc/jpa/Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/jpa/Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG).adoc new file mode 100644 index 00000000000..2349ef7fd70 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG).adoc @@ -0,0 +1,433 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Packaging_and_Deploying_EclipseLink_JPA_Applications_(ELUG)[Related +Topics] + +== Packaging an EclipseLink JPA Application + +Packaging means assembling all parts of the application in a way that +can be correctly interpreted and used by the infrastructure when the +application is deployed into an application server or run in a +stand-alone JVM. + +Once you chose a packaging strategy, place the `+persistence.xml+` file +in the `+META-INF+` directory of the archive of your choice. + +In a Java EE environment, the most efficient way to package your +application is to use a tool, such as JDeveloper or Eclipse. Using OC4J, +it is possible to skip the packaging step and deploy from your working +directories using expanded deployment. + +To package your EclipseLink JPA application, you need to configure the +link:Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#Persistence_Unit[persistence +unit] during the creation of the +link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#persistence.xml_File[`+persistence.xml+` +file]. Define each persistence unit in a `+persistence-unit+` element in +the `+persistence.xml+` file. + +For more information, see the following: + +* Chapter 6 "`Entity Packaging`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Packaging%20a%20EclipseLink%20Application%20(ELUG)[Packaging an +EclipseLink Application] + +=== How to Specify the Persistence Unit Name + +If you are developing your application in a Java EE environment, ensure +that the persistence unit name is unique within each module. For +example, you can define only one persistence unit with the name +`+"EmployeeService"+` in an `+emp_ejb.jar+` file. The following example +shows how to define the name of the persistence unit: + +[source,xml] +---- + +---- + +For more information, see Section 6.2.1.1 "`name`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +=== How to Specify the Transaction Type, Persistence Provider and Data Source + +If you are developing your application in a Java EE environment, accept +the default transaction type (see Section 6.2.1.2 "`transaction-type`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification])–JTA (see +link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#JTA_Transaction_Management[JTA +Transaction Management]), and for the persistence provider setting, set +the persistence provider in a `+provider+` element (see Section 6.2.1.2 +"`provider`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]). Specify the data source in a `+jta-data-source+` +element, as the following example shows: + +[source,xml] +---- + + jdbc/EmployeeServiceDS + +---- + +Typically, you would use the JNDI access to the data source. Make this +data source available by configuring it in a server-specific +configuration file or management console. + +For more information, see the following sections of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]: + +* Section 6.2.1.2 "`transaction-type`" +* Section 6.2.1.4 "`provider`" +* Section 6.2.1.5 "`jta-data-source, non-jta-data-source`" + +=== How to Specify Mapping Files + +Apply the metadata to the persistence unit. This metadata is a union of +all the mapping files and the annotations (if there is no +`+xml-mapping-metadata-complete+` element). If you use one mapping +link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Metadata_Annotations_and_ORM.xml_File[`+orm.xml+` +file]) for your metadata, and place this file in a `+META-INF+` +directory on the classpath, then you do not need to explicitly list it, +because the EclipseLink persistence provider will automatically search +for this file and use it. If you named your mapping files differently or +placed them in a different location, then you must list them in the +`+mapping-file+` elements in the `+persistence.xml+` file, as the +following example shows: + +[source,xml] +---- + + jdbc/EmployeeServiceDS + META-INF/employee_service_queries.xml + +---- + +Note that the `+orm.xml+` file is not listed in the previous example, +because the persistence provider finds it by default. + +For more information, see the following: + +* Section 6.2.1.6 "`mapping-file, jar-file, class, +exclude-unlisted-classes`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] + +=== How to Specify Managed Classes + +Typically, you put all of the entities and other managed classes in a +single JAR file, along with the `+persistence.xml+` file in the +`+META-INF+` directory, and one or more mapping files (when you use XML +mapping). + +At the time EclipseLink persistence provider processes the persistence +unit, it determines which set of entities, mapped superclasses, and +embedded objects each particular persistence unit will manage. + +At deployment time, EclipseLink persistence provider may obtain managed +classes from any of the four sources. A managed class will be included +if it is one of the following: + +* Local classes: the classes annotated with `+@Entity+` (see Section 8.1 +"`Entity`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification]), +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass[`+@MappedSuperclass+`] +or +link:Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable[`+@Embeddable+`] +in the deployment unit in which its `+persistence.xml+` file was +packaged. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are deploying your application in the Java EE +environment, not EclipseLink persistence provider, but the application +server itself will discover local classes. In the Java SE environment, +you can use the `+exclude-unlisted-classes+` element (see Section +6.2.1.6 "`mapping-file, jar-file, class, exclude-unlisted-classes`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]) to enable +this functionality–EclipseLink persistence provider will attempt to find +local classes if you set this element to `+false+`. +|=== + +* Classes in mapping files: the classes that have mapping entries, such +as `+entity+` (see Section 10.1.2.10 "`entity`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), +`+mapped-superclass+` (see Section 10.1.2.11 "`mapped-superclass`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]) or +`+embeddable+` (see Section 10.1.2.12 "`embeddable`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]), in an XML +mapping file. If these classes are in the deployed component archive, +then they will already be on the classpath. If they are not, you must +explicitly include them in the classpath. + +* Explicitly listed classes: the classes that are listed as `+class+` +elements in the `+persistence.xml+` file. Consider listing classes +explicitly if one of the following applies: +** there are additional classes that are not local to the deployment +unit JAR. For example, there is an embedded object class in a different +JAR that you want to use in an entity in your persistence unit. You +would list the fully qualified class in the `+class+` element in the +`+persitence.xml+` file. You would also need to ensure that the JAR or +directory that contains the class is on the classpath of the deployed +component (by adding it to the manifest classpath of the deployment JAR, +for example); +** you want to exclude one or more classes that may be annotated as an +entity. Even though the class may be annotated with the `+@Entity+` +annotation, you do not want it treated as an entity in this particular +deployed context. For example, you may want to use this entity as a +transfer object and it needs to be part of the deployment unit. In this +case, in the Java EE environment, you have to use the +`+exclude-unlisted-classes+` element (see Section 6.2.1.6 +"`mapping-file, jar-file, class, exclude-unlisted-classes`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) of the +`+persistence.xml+` file–the use of the default setting of this element +prevents local classes from being added to the persistence unit; +** you plan to run your application in the Java SE environment, and you +list your classes explicitly because that is the only portable way to do +so in Java SE (see link:#How_to_Perform_an_Application_Bootstrapping[How +to Perform an Application Bootstrapping]). +* Additional JAR files of managed classes: the annotated classes in a +named JAR file listed in a `+jar-file+` element (see Section 6.2.1.6 +"`mapping-file, jar-file, class, exclude-unlisted-classes`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification]) in the +`+persistence.xml+` file. You have to ensure that any JAR file listed in +the `+jar-file+` element is on the classpath of the deployment unit. Do +so by manually adding the JAR file to the manifest classpath of the +deployment unit. Note that you must list the JAR file in the +`+jar-file+` element relative to the parent of the JAR file in which the +`+persistence.xml+` file is located. This matches what you would put in +the classpath entry in the manifest file. The following example shows +the structure of the `+emp.ear+` EAR file: + +`+emp.ear+` `+    emp-ejb.jar+` `+        META-INF/persistence.xml+` +`+    employee/emp-classes.jar+` +`+        examples/model/Empoyee.class+` + +The following example shows the contents of the `+persistence.xml+` +file, with the `+jar-file+` element containing +"`employee/emp-classes.jar`" to reference the `+emp-classes.jar+` in the +`+employee+` directory in the EAR file: + +[source,xml] +---- + + jdbc/EmployeeServiceDS + employee/emp-classes.jar + +---- + +You may choose to use any one or a combination of these mechanisms to +include your managed classes in the persistence unit. + +For more information, see +link:#How_to_Deploy_an_Application_to_Generic_Java_EE_5_Application_Servers[How +to Deploy an Application to Generic Java EE 5 Application Servers]. + +=== How to Add Vendor Properties + +The last section in the `+persistence.xml+` file is the properties +section. The `+properties+` element (see Section 6.2.1.7 "`properties`" +of the http://jcp.org/en/jsr/detail?id=220[JPA Specification]) gives you +the chance to supply EclipseLink persistence provider-specific settings +for the persistence unit. + +This example shows how to add EclipseLink-specific properties. + +[#Example 22-1]## *_Using EclipseLink Persistence Provider Properties_* + +[source,xml] +---- + + ... + + + + + + +---- + +For more information, see the following: + +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What_You_May_Need_to_Know_About_Using_EclipseLink_JPA_Persistence_Unit_Properties[What +You May Need to Know About Using EclipseLink JPA Persistence Unit +Properties] +* link:Using%20EclipseLink%20JPA%20Extensions%20(ELUG)[Using EclipseLink +JPA Extensions] + +=== How to Set Up the Deployment Classpath + +To be accessible to the EJB JAR, WAR, or EAR file, a class or a JAR file +must be on the deployment classpath. You can achieve this in one of the +following ways: + +* Put the JAR file in the manifest classpath of the EJB JAR or WAR file. +Do this by adding a classpath entry to the `+META-INF/MANIFEST.MF+` file +in the JAR or WAR file. You may specify one or more directories or JAR +files, separating them by spaces. The following example shows how the +manifest file classpath entry adds the `+employee/emp-classes.jar+` file +and the `+employee/classes+` directory to the classpath of the JAR file +that contains the manifest file: + +`+Class-Path: employee/emp-classes.jar employee/classes+` + +* Place the JAR file in the library directory of the EAR file–this will +make this JAR file available on the application classpath and accessible +by all of the modules deployed within the EAR file. By default, this +would be the `+lib+` directory of the EAR file, although you may +configure it to be any directory in the EAR file using the +`+library-directory+` element in the `+application.xml+` deployment +descriptor. The following example shows the `+application.xml+` file: + +`++` `+    ...+` `+    +``+myDir/jars+` + +=== What You May Need to Know About Persistence Unit Packaging Options + +Java EE allows for persistence support in a variety of packaging +configurations. You can deploy your application to the following module +types: + +* EJB modules: you can package your entities in an EJB JAR. When +defining a persistence unit in an EJB JAR, the `+persistence.xml+` file +is not optional–you must create and place it in the `+META-INF+` +directory of the JAR alongside the deployment descriptor, if it exists. +* Web modules: you can use WAR file to package your entities. In this +case, place the `+persistence.xml+` file in the +`+WEB-INF/classes/META-INF+` directory. Since the `+WEB-INF/classes+` +directory is automatically on the classpath of the WAR, specify the +mapping file relative to that directory. +* Persistence archives: a persistence archive is a JAR that contains a +`+persistence.xml+` file in its `+META-INF+` directory and the managed +classes for the persistence unit defined by the `+persistence.xml+` +file. Use a persistence archive if you want to allow multiple components +in different Java EE modules to share or access a persistence unit. The +following example shows how to package entities in a persistence +archive: + +`+emp.ear+` `+    emp-persitence.jar+` +`+        META-INF/persistence.xml+` `+        META-INF/orm.xml+` +`+        examples/model/Employee.class+` +`+        examples/model/Phone.class+` +`+        examples/model/Address.class+` +`+        examples/model/Department.class+` +`+        examples/model/Project.class+` + +Once you created a persistence archive, you can place it in either the +root or the application library directory of the EAR. Alternatively, you +can place the persistence archive in the `+WEB-INF/lib+` directory of a +WAR. This will make the persistence unit accessible only to the classes +inside the WAR, but it enables the decoupling of the definition of the +persistence unit from the web archive itself. + +For more information, see Section 6.2 "`Persistence Unit Packaging`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +=== What You May Need to Know About the Persistence Unit Scope + +You can define any number of persistence units in single +`+persistence.xml+` file. The following are the rules for using defined +and packaged persistence units: + +* Persistence units are accessible only within the scope of their +definition. +* Persistence units names must be unique within their scope. + +For more information, see Section 6.2.2 "`Persistence Unit Scope`" of +the http://jcp.org/en/jsr/detail?id=220[JPA Specification]. + +=== How to Perform an Application Bootstrapping + +Outside of a container, use the `+createEntityManagerFactory+` method of +the `+javax.persistence.Persistence+` class to create an entity manager +factory. This method accepts a `+Map+` of properties and the name of the +persistence unit. The properties that you pass to this method are +combined with those that you already specified in the +`+persistence.xml+` file. They may be additional properties or they may +override the value of a property that you specified previously. + +[width="100%",cols="<100%",] +|=== +|*Note:* This is a convenient way to set properties obtained from a +program input, such as the command line. +|=== + +This example shows how to take the user name and password properties +from the command line and pass them to the EclipseLink persistence +provider when creating the `+EntityManagerFactory+`. + +[#Example 22-2]## *_Using Command-Line Persistence Properties_* + +[source,java] +---- + public class EmployeeService { + + public static void main (String[] args) { + Map props = new HashMap(); + props.put("eclipselink.jdbc.user", args[0]); + props.put("eclipselink.jdbc.password", args[1]); + EntityManagerFactory emf = Persistence.createEntityManagerFactory("EmployeeService", props); + ... + emf.close(); + } + } +---- + +For more information, see the following: + +* Section 7.2 "`Bootstrapping in Java SE Environments`" of the +http://jcp.org/en/jsr/detail?id=220[JPA Specification] +* link:Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Application-Managed_Entity_Manager[Application-Managed +Entity Manager] + +[#Deploying an EclipseLink JPA Application]## + +== Deploying an EclipseLink JPA Application + +Deployment is the process of getting the application into an execution +environment and running it. + +For more information, see the following: + +* link:#Packaging_a_EclipseLink_JPA_Application[Packaging an EclipseLink +JPA Application] +* link:#How_to_Specify_Managed_Classes[How to Specify Managed Classes] +* link:Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)[Creating +EclipseLink Files for Deployment] +* link:Deploying%20a%20EclipseLink%20Application%20(ELUG)[Deploying an +EclipseLink Application] +* Chapter 7 "`Container and Provider Contracts for Deployment and +Bootstrapping`" of the http://jcp.org/en/jsr/detail?id=220[JPA +Specification] + +=== How to Deploy an Application to OC4J + +After packaging, you deploy your EclipseLink JPA application to OC4J to +execute it and make it available to end users. + +You can deploy from a Java EE development tool such as +link:EclipseLink_Examples_JPA#Integrating_EclipseLink_JPA_with_an_IDE[JDeveloper] +or link:EclipseLink_Examples_JPA_OC4J_Web_Tutorial[Eclipse]. + +=== How to Deploy an Application to Generic Java EE 5 Application Servers + +Each persistence unit deployed into a Java EE container consists of a +single `+persistence.xml+` file, any number of mapping files, and any +number of class files. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you are deploying to JBoss 4.2 server, refer to +link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)#How_to_Configure_JPA_Application_Deployment_to_JBoss_4.2_Application_Server[How +to Configure JPA Application Deployment to JBoss 4.2 Application +Server]. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_JPA[Category: JPA] diff --git a/docs/docs.ug/src/main/asciidoc/jpa/UserGuide_JPA_Using_the_Canonical_Model_Generator_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/jpa/UserGuide_JPA_Using_the_Canonical_Model_Generator_(ELUG).adoc new file mode 100644 index 00000000000..25f9806efa4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/jpa/UserGuide_JPA_Using_the_Canonical_Model_Generator_(ELUG).adoc @@ -0,0 +1,246 @@ +*TOC* +Special:Whatlinkshere_UserGuide_JPA_Using_the_Canonical_Model_Generator_(ELUG)[Related +Topics] + +== Canonical Model Generation + +With the new Criteria API from the JPA 2.0 spec, EclipseLink can now +produce static + +http://wiki.eclipse.org/EclipseLink/Development/JPA_2.0/metamodel_api[metamodel] +classes that correspond to the entities, mapped superclasses, and +embeddable classes in the persistence unit. A static metamodel class +models the persistent state and relationships of the corresponding +managed class. + +For portability, EclipseLink generates this canonical metamodel as +defined in section 6.2.1.1 of the specification. EclipseLink generates +the static metamodel classes by using the the annotation processor tool +(APT) in conjunction with its existing metadata processing of +annotations. + +For more information on APT, see: +http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html + +=== Metadata Processing + +The annotation processor tool directly ties into the regular deployment +metadata processing. Which means before generating the metamodel +classes, persistence units are processed as they normally would be +according to the spec giving you the following behavior: *Persistence +unit property processing + +* XML mapping file merging and override +* Full annotation and xml processing of Entities, Embeddables and +MappedSuperclasses. +* Full support of EclipseLink extensions, including annotations and +eclipelink-orm.xml + +=== Configuring and using within Eclipse Galileo + +Use the following procedure to configure the metamodel generation within +the Eclipse IDE. + +[arabic] +. Select your project in the *Package Explorer* and select *Project* > +*Properties*. The Properties dialog appears. +. Select *Java Compiler* and ensure you are using JDK 1.6 (or higher). +. Expand the *Java Compiler* element and select *Annotation Processing*. +. In the Annotation Processing area, enable the *Enable annotation +processing* option. +. In the *Generated source directory* field, enter the directory in +which to generate the metamodel classes. +. By default, *Processor options* are not needed. However, EclipseLink +provides you with custom generation options if you would like to +configure you metamodel classes differently then defined in the spec. +See the EclipseLink custom processor options section below for supported +processor options. +. Expand the *Annotation Processing* element and select *Factory Path*. +. Click *Add External JARs* and add the following libraries (JARs). +Refer to the the link:#library_names[1.2.0 RC4 Library names] for +details. + +* {blank} +** The EclipseLink JAR (eclipselik.jar) +** The Java persistence 2.0 preview JAR +** A JAR that contains the enabling services file that specifies the +name of the annotation processor tool. + +http://www.eclipse.org/downloads/download.php?file=/rt/eclipselink/releases/static/eclipselink-jpa-modelgen.jar[Service +Jar] + +[width="100%",cols="<100%",] +|=== +|*Note:* The annotation processor _does not_ log to the *Console* +window. Instead, messages are logged to the *Error Log* window. To +display this window, select *Window > Show View > Error Log* from the +Eclipse menu. +|=== + +=== Configuring and using within ANT/javac + +Use the following procedure to configure the metamodel generation within +ANT/javac: + +[arabic] +. Add *modelgen jar* to the javac classpath. +. Use the `+-processor+` option on javac command line. +. In the following examples, options are specified with using *-A* (for +example, +`+javac -Aeclipselink.persistencexml=META-INF/sub/persistence.xml+`) + +==== ANT example + +[source,xml] +---- + + + + + + + +---- + +[#processor_options]## + +=== EclipseLink custom processor options + +The following table describes the EclipseLink custom options: + +Option + +Description + +*eclipselink.persistencexml* + +The full resource name in which to look for the persistence XML files. +If not specified the default `+META-INF/persistence.xml+` will be used. + +*eclipselink.persistenceunits* + +A comma deliminated list of persistence unit names that will be used +when generating the canonical model. By default all persistence units +available in all persistence XML files will be used. Note: When +specifying multiple persistence units you cannot include a persistence +unit with a comma ( , ) in its name. + +*eclipselink.canonicalmodel.prefix* + +The prefix that will be added to the start of the class name of any +generated canonical model class. By default the prefix is not used. + +*eclipselink.canonicalmodel.suffix* + +The suffix that will be added to the end of the class name of any +generated canonical model class. The default suffix value is _ (an +underscore). If specified, this property value must be a non-empty +string that contains valid characters for use in a Java class name. + +*eclipselink.canonicalmodel.subpackage* + +A sub-package name that can be used to have the canonical model +generator generate its classes in a sub-package of the package where the +corresponding entity class is located. By default the canonical model +classes are generated into the same package as the entity classes. + +[#library_names]## + +=== EclipseLink 1.2.0 RC4 Library names + +Currently the target release of EclipseLink 1.2.0 is RC4 which uses the +following jar files names in the ZIP installer. Please note that the ZIP +installer is the only distribution of EclipseLink including the modelgen +JAR file. + +* Services file (enables the processor): +http://www.eclipse.org/downloads/download.php?file=/rt/eclipselink/releases/static/eclipselink-jpa-modelgen.jar[Service +Jar] +*_\eclipselink\jlib\jpa\eclipselink-jpa-modelgen_1.2.0.v20091016-r5565.jar_* + +* javax.persistence library: +*_\eclipselink\jlib\jpa\javax.persistence_2.0_preview.jar_* + +* EclipseLink jar: *_\eclipselink\jlib\eclipselink.jar_* + +=== Troubleshooting + +After following the configuration steps above if no classes are +generated, check the following: + +===== Do you have a persistence XML file? + +Verify that you have a Persistence XML file. By default, the file is +located in `+META-INF/persistence.xml+`. + +If you name your persistence XML differently, or place it in a different +directory, you must use the *eclipselink.persistencexml* processor +option. See link:#processor_options[EclipseLink Custom Processor +Options] for more information. + +===== Are you using an extended EclipseLink ORM mapping file? + +If you use an extended EclipseLink ORM mapping file that is not listed +in your Persistence XML file, EclipseLink will not automatically +discover the mapping file (similar to the `+orm.xml+` file). You must +explicitly specify the mapping file: + +[source,xml] +---- + + ... + eclipselink-orm.xml + ... + +---- + +Note: Future versions of EclipseLink will include the ability to +automatically discover the eclipselink-orm.xml file for the metamodel +class generation. In a regular deployment scenario the eclipselink-orm +discovery still applies. + +===== Are XML changes not being reflected in the generated model classes? + +After making an XML change within Eclipse, the the generated model +classes are not updated to reflect the change. Unlike changes to the +model class, XML changes _are not_ automatically reflected, since the +annotation processor is not aware of these changes. + +To reflect XML changes in your generated metamodel classes, clean the +project. Select *Project > Clean…* from the Eclipse menu. + +If you have made extensive XML changes (including the removal of mapping +files or deletion of entities), you must restart the annotation +processor tool: + +[arabic] +. Select *Project > Properties* from the Eclipse menu. +. Expand *Java Compiler* element and select *Annotation Processing*. +. In the Annotation Processing area of the Properties window, deselect +the *Enable annotation processing* option. +. Click *OK*. A window appears, indicating that you have changed the +annotation processing settings and Eclipse must rebuild the project. +. Click *Yes*. +. After Eclipse rebuilds the project, return to the Annotations +Processing area of the Properties page, and enable the *Enable +annotation processing* option. +. Click *OK*. Again, a window appears, indicating that you have changed +the annotation processing settings and Eclipse must rebuild the project. +. Click *Yes*. Eclipse rebuilds the project. The generated model classes +now reflect your latest XML changes. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.2[Category: Release 1.2] Category:_JPA[Category: +JPA] diff --git a/docs/docs.ug/src/main/asciidoc/main.adoc b/docs/docs.ug/src/main/asciidoc/main.adoc new file mode 100644 index 00000000000..dbf2195ad9d --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/main.adoc @@ -0,0 +1,5 @@ += EclipseLink User Guide +:toc: +:doctype: book + +include::sdo/sdo-main.adoc[] diff --git a/docs/docs.ug/src/main/asciidoc/sdo/BasicAPI.adoc b/docs/docs.ug/src/main/asciidoc/sdo/BasicAPI.adoc new file mode 100644 index 00000000000..90d0751b042 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/BasicAPI.adoc @@ -0,0 +1,240 @@ +[#sdo-example-basic] +=== Using the SDO API + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[#sdo-example-basic-helperctx] +==== HelperContext + +The helper context is the access point for all the SDO helpers and +factories. If a type is defined in the TypeHelper for a HelperContext, +then the DataFactory from that HelperContext can be used to create a +DataObject of that Type. + +===== Default HelperContext + +SDO provides a default helper context. The helpers and factories +obtained from the default helper context are the same ones available +from the static INSTANCE variables on each of the helpers and factory +classes. De-serialization is always performed in the scope of the +default HelperContext. + +[source,java] +---- +HelperContext helperContext = HelperProvider.getDefaultContext(); +---- + +===== Local HelperContext + +SDO also allows for HelperContexts other than the default + +[source,java] +---- +HelperContext helperContext = new SDOHelperContext(); +---- + +If you are using type safe DataObjects then you can provide the +ClassLoader that contains the generated interfaces. + +[source,java] +---- +HelperContext helperContext = new SDOHelperContext(aClassLoader); +---- + +[#sdo-example-basic-typehelper] +==== TypeHelper - Access Metadata + +TypeHelper provides a convenient means of handling SDO metadata. + +[source,java] +---- +TypeHelper typeHelper = helperContext.getTypeHelper(); +---- + +===== Get Types + +You can lookup the SDO type by name and uri. + +[source,java] +---- +typeHelper.getType("http://www.example.org/customer-example", "customer-type"); +---- + +You can also use the type safe interface classes to look up the +corresponding SDO type. + +[source,java] +---- +typeHelper.getType(Customer.class); +---- + +===== Get Open Content Properties + +You can lookup open content properties by name and uri. + +[source,java] +---- +typeHelper.getOpenContentProperty("http://www.example.org/customer-example", "phone-number"); +---- + +[#sdo-example-basic-xsdhelper] +==== XSDHelper - Access XML Schema Metadata + +XSDHelper provides a convenient means of handling XML Schema metadata. + +[source,java] +---- +XSDHelper xsdHelper = helperContext.getXSDHelper(); +---- + +===== Define + +The XSDHelper contains a number of define methods for generating SDO +types from an XML Schema. + +[source,java] +---- +URL xsdURL = new URL("http://www.example.org/customer-example/customer.xsd"); +List types = xsdHelper.define(xsdUrl.openStream(), xsdUrl.toExternalForm()); +---- + +===== Generate + +The XSDHelper contains a number of generate methods to generate an XML +Schema from SDO types. + +[source,java] +---- +String xmlSchema = xsdHelper.generate(types); +---- + +[#sdo-example-basic-datafactory] +==== DataFactory - Create DataObjects + +DataFactory provides a convenient means of creating SDO DataObjects. + +[source,java] +---- +DataFactory dataFactory = helperContext.getDataFactory(); +---- + +===== Create + +[#sdo-example-basic-datahelper] +==== DataHelper - Convert Simple Values + +DataHelper provides a convenient means of converting SDO data type +values. + +[source,java] +---- +DataHelper dataHelper = helperContext.getDataHelper(); +---- + +[#sdo-example-basic-xmlhelper] +==== XMLHelper - Handle XML Data as DataObjects + +XMLHelper provides a convenient means of handling XML data as +DataObjects. + +[source,java] +---- +XMLHelper xmlHelper = helperContext.getXMLHelper(); +---- + +===== Load + +Load methods are used to unmarshal XML into DataObjects. + +[source,java] +---- +FileInputStream xmlInputStream = new FileInputStream("customer.xml"); +XMLDocument xmlDocument = xmlHelper.load(xmlInputStream); +DataObject customerDO = xmlDocument.getRootObject; +---- + +===== Save + +Save methods are used to convert DataObjects to XML. + +[source,java] +---- +xmlHelper.save(customerDO, "http://www.example.org/customer-example", "customer", System.out); +---- + +The XML root information can also be encapsulated in an XMLDocument +object. + +[source,java] +---- +XMLDocument xmlDocument = + xmlHelper.createDocument(customerDO, "http://www.example.org/customer-example", "customer"); +xmlHelper.save(xmlDocument, System.out, null); +---- + +[#sdo-example-basic-copyhelper] +==== CopyHelper - Create Copies of DataObjects + +CopyHelper provides a convenient means of copying DataObjects. + +[source,java] +---- +CopyHelper copyHelper = helperContext.getCopyHelper(); +---- + +===== Shallow Copy + +Create a new DataObject containing the values of all dataType=true +properties (excluding the ChangeSummary property). + +[source,java] +---- +DataObject shallowCopy = copyHelper.copyShallow(dataObject); +---- + +===== Deep Copy + +Create a copy of the entire tree. + +[source,java] +---- +DataObject deepCopy = copyHelper.copy(dataObject); +---- + +[#sdo-example-basic-equalityhelper] +==== EqualityHelper - Compare DataObjects + +EqualityHelper provides a convenient means of comparing DataObjects. + +[source,java] +---- +EqualityHelper equalityHelper = helperContext.getEqualityHelper(); +---- + +===== Shallow Equal + +Two DataObjects are considered shallow equal if the data objects are of +the same type and all the values of all dataType=true properties +(excluding the ChangeSummary property) are equal. + +[source,java] +---- +boolean isShallowEqual = equalityHelper.equalShallow(dataObject1, dataObject2); +---- + +===== Deep Equal + +Two DataObjects are considered deep equal if the data objects and the +trees that they belong to are both equal. + +[source,java] +---- +boolean isDeepEqual = equalityHelper.equal(dataObject1, dataObject2); +---- diff --git a/docs/docs.ug/src/main/asciidoc/sdo/Compiler.adoc b/docs/docs.ug/src/main/asciidoc/sdo/Compiler.adoc new file mode 100644 index 00000000000..0c221f68a4b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/Compiler.adoc @@ -0,0 +1,49 @@ +[#sdo-example-compiler] +=== Running the SDO Compiler + +* <> +* <> +* <> + +[#sdo-example-compiler-overview] +==== Overview + +The following example will demonstrate how to use EclipseLink's SDO +functionality to: + +* Generate Java source files from an XML Schema using the SDO Compiler + +[#sdo-example-compiler-setup] +==== Setup + +. Ensure that you have EclipseLink correctly installed and configured +for your environment. Please see +link:/EclipseLink/Installing_and_Configuring_EclipseLink[EclipseLink/Installing +and Configuring EclipseLink] for more information. + +[#sdo-example-compiler-run] +==== Running the SDO Compiler + +The SDO compiler can be run to generate Static SDO Java files from an +XML Schema: + +[source,bash] +---- +/eclipselink/bin/sdo-compiler.sh [-options] +\eclipselink\bin\sdo-compiler.cmd [-options] + +Options: + -help Prints the help message text + -sourceFile The input schema file (required) + -targetDirectory The directory to generate Java source (optional) + -logLevel Specify the integer value of the logging level + (8=OFF,7=SEVERE,6=WARNING,5=INFO,4=CONFIG,3=FINE,2=FINER(default),1=FINEST,0=ALL) +Example: + sdo-compiler.sh -sourceFile config/Customer.xsd -targetDirectory sdo-compiler-output -logLevel 8 +---- + +For each complex type in the schema, the compiler will generate both an +interface (e.g. `+CustomerType.java+`), and a concrete implementation +which subclasses `+org.eclipse.persistence.sdo.SDODataObject+` (e.g. +`+CustomerTypeImpl.java+`). + diff --git a/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPI.adoc b/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPI.adoc new file mode 100644 index 00000000000..672b7a9511a --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPI.adoc @@ -0,0 +1,44 @@ +[#sdo-example-dynamicapi] +=== Using Dynamic DataObjects + +* <> +** <> +** <> +* <> + +[#sdo-example-dynamicapi-do] +==== Creating DataObjects + +[#sdo-example-dynamicapi-do-df] +===== Using DataFactory + +DataObjects can be created by Type using DataFactory: + +[source,java] +---- +Type customerType = TypeHelper.INSTANCE.getType("http://www.example.org/customer-example", "customer-type"); +DataObject customerDO = DataFactory.INSTANCE.create(customerType); +---- + +[#sdo-example-dynamicapi-do-do] +===== Using DataObject + +Once you have a DataObject you can use it to create child DataObjects +based on its properties: + +[source,java] +---- +DataObject contactInfoDO = customerDO.createDataObject("contact-info"); +DataObject billingAddressDO = contactInfoDO.createDataObject("billing-address"); +---- + +[#sdo-example-dynamicapi-props] +==== Getting/Setting Properties + +An SDO path (similar to XPath) can be used with the String based +accessors: + +[source,java] +---- +DataObject billingAddressDO = customerDO.getDataObject("contact-info/billing-address"); +---- diff --git a/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPIXML.adoc b/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPIXML.adoc new file mode 100644 index 00000000000..dbe01a01439 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/DynamicAPIXML.adoc @@ -0,0 +1,242 @@ +[#sdo-example-dynamicapixml] +=== Using Dynamic DataObjects to Manipulate XML + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[#sdo-example-dynamicapixml-overview] +==== Overview + +The following example will demonstrate how to use EclipseLink's SDO +functionality to: + +* Define a set of SDO Types from an XML Schema +* Load an XML file and modify its data +* Monitor changes made to the data +* Save the modified data to XML + +[#sdo-example-dynamicapixml-setup] +==== Setup + +. Ensure that you have EclipseLink correctly installed and configured +for your environment. Please see +link:/EclipseLink/Installing_and_Configuring_EclipseLink[EclipseLink/Installing +and Configuring EclipseLink] for more information. +. Ensure that you have ANT correctly installed and configured. +. Unzip the Example ZIP file to a new directory. +. Edit the `+env.properties+` file in the root directory of the example +and specify the path to your EclipseLink `+jlib+` directory: + +[source,properties] +---- +... +# Edit eclipselink.jlib to point to your EclipseLink jlib directory +eclipselink.jlib=C:/EclipseLink-1.0/eclipselink/jlib +... +---- + +You can compile and run the Example at any time by typing `+ant+` from +the Example directory. + +For Eclipse IDE users, a `+.project+` file is included in the Example +directory. To setup this project in Eclipse: + +. From the "File" menu, choose "Import..." +. In the Import dialog, choose "General > Existing Projects into +Workspace", and click "Next". +. Click "Browse" to select a root directory, and point to the folder +containing this example. After selecting the directory, you should see +the project name in the "Projects" list. Click "Finish". + +This project is configured to use a classpath variable, +`+ECLIPSELINK_JLIB+`, to point to the required JAR files. After the +project is imported, you should define a variable called +`+ECLIPSELINK_JLIB+` to point to your EclipseLink `+jlib+` directory. + +[#sdo-example-dynamicapixml-init] +==== Initializing the Types from XML Schema + +The first thing that needs to be done in an SDO application is to set up +the metadata for the Types and Properties. This is most commonly done by +loading an XML schema, although it may also be done programmatically. + +[source,java] +---- +FileInputStream xsdInputStream = new FileInputStream("Customer.xsd"); +XSDHelper.INSTANCE.define(xsdInputStream, null); +---- + +[#sdo-example-dynamicapixml-unmarshall] +==== Unmarshalling the XML Document + +With the SDO Types and Properties defined from the schema, we can now +load an XML document based on that schema, and then obtain a DataObject +and begin modifying its contents. + +[source,java] +---- +FileInputStream xmlInputStream = new FileInputStream("Customer-data.xml"); +XMLDocument xmlDocument = XMLHelper.INSTANCE.load(xmlInputStream); +DataObject customerDO = xmlDocument.getRootObject(); +---- + +[#sdo-example-dynamicapixml-track] +==== Tracking Object Modifications using Change Summary + +SDO's Change Summary provides access to change history information for +the DataObjects in a data graph. A change history covers any +modifications that have been made to a data graph starting from the +point when logging was activated. + +In order to use Change Summary, we have defined an element of type +"`+sdo:ChangeSummaryType+`" on our root complex type: + +[source,xml] +---- + + + ... + + + + +---- + +Before we start modifying our data, we must enable logging: + +[source,java] +---- +customerDO.getChangeSummary().beginLogging(); +---- + +From this point on, any modifications to the DataObject will be captured +in the Change Summary, until logging is deactivated: + +[source,java] +---- +customerDO.getChangeSummary().endLogging(); +---- + +[#sdo-example-dynamicapixml-modify] +==== Modifying the DataObjects + +Below are examples of manipulating the DataObjects using the dynamic +APIs. Note how the dynamic accessors take an XPath instead of just a +property name. + +Modifying the ShippingAddress ZipCode: + +[source,java] +---- +DataObject addressDO = customerDO.getDataObject("contact-info").getDataObject("shipping-address"); +addressDO.set("zip-code", "27601"); +---- + +Adding a new PhoneNumber: + +[source,java] +---- +DataObject newPhoneNumberDO = DataFactory.INSTANCE.create("urn:customer-example", "phone-number"); +newPhoneNumberDO.set("number-type", "home"); +newPhoneNumberDO.set("value", "(613) 555-3333"); +customerDO.getList("contact-info/phone-number").add(newPhoneNumberDO); +---- + +Removing all "cell" PhoneNumbers: + +[source,java] +---- +ArrayList phoneNumbersToRemove = new ArrayList(); +List phoneNumbers = customerDO.getDataObject("contact-info").getList("phone-number"); +Iterator it = phoneNumbers.iterator(); +while (it.hasNext()) { + DataObject phoneNumberDO = (DataObject) it.next(); + if (phoneNumberDO.get("number-type").equals("cell")) { + phoneNumbersToRemove.add(phoneNumberDO); + } +} +phoneNumbers.removeAll(phoneNumbersToRemove); +---- + +There are general accessors for properties, i.e., `+get()+` and +`+set()+`, as well as specific accessors for the primitive types and +commonly used data types like String, Date, List, BigInteger, and +BigDecimal. For more information see the +http://help.eclipse.org/help32/topic/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataObject.html[documentation +for DataObject]. + +[#sdo-example-dynamicapixml-marshall] +==== Marshalling the DataObjects + +The following code segment demonstrates how to marshal DataObjects +wrapped in a `+commonj.sdo.helper.XMLDocument+` back to XML. In this +example the stream we are saving to is `+System.out+`, so the XML text +will be printed to the console. + +[source,java] +---- +XMLHelper.INSTANCE.save(xmlDocument, System.out, null); +---- + +[#sdo-example-dynamicapixml-interpret] +==== Interpreting the Change Summary + +When the document is saved to `+System.out+`, we can see the change +summary information in the XML: + +[source,xml] +---- + + ... + + + + (613) 555-2222 + + + 12345 + + + +---- + +* For DataObjects with modified data type properties, the Change Summary +element contains a copy of the DataObject from the data graph, but +containing only the properties which have changed, and showing their old +values. In our example, we see a "`+shipping-address+`" element which +references "`+#/ns1:contact-info/shipping-address+`" (the element that +was modified), along with its old value, "`+12345+`". + +* DataObjects which are currently in the data graph, but were not +present when logging was started are indicated in the change summary +with a "`+create+`" attribute. If more than one DataObject had been +created, the attribute would contain a space-separated list of +references, one for each DataObject. In our example, we see a +"`+create+`" attribute indicating that +"`+#/ns1:contact-info/ns1:phone-number\[2\]+`" (the second phone number +in the XML) is the newly created one. + +* DataObjects deleted during logging are flagged with the "`+delete+`" +attribute. In this case the change summary also contains a deep copy of +the object which was deleted, as it no longer appears in the data graph. +Here, we see a "`+delete+`" attribute indicating that +"`+#/changeSummary/ns1:contact-info/ns1:phone-number\[2\]+`" (the second +phone number in the _Change Summary_) is the one that was deleted from +the XML. + +[#sdo-example-dynamicapixml-download] +==== Download + +Download the "Examples Zip" from the EclipseLink +http://www.eclipse.org/eclipselink/downloads/[Downloads] page. Code for +this example will be found in the +`+org.eclipse.persistence.example.sdo.dynamicapi.zip+` file. + diff --git a/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_EclipseLink_SDO_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_EclipseLink_SDO_(ELUG).adoc new file mode 100644 index 00000000000..0a030c75365 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_EclipseLink_SDO_(ELUG).adoc @@ -0,0 +1,278 @@ +This section introduces EclipseLink implementation of Service Data +Objects (SDO) specification, as well as provides information on how you +can use it in your application development. + +[#sdo-introel] +== Using SDO Metadata + +SDO metadata is represented as <> and +<> objects. You define the metadata at +run time either programmatically (<>), +or from an XML schema (<>). + +For more information, see <>. + +[#sdo-introel-type] +=== Using Type + +SDO `+Type+` acts similarly to a `+Class+` in Java, and provides much of +the same metadata as the Java Reflection API provides for Java classes. + +In EclipseLink, a +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOType.html[`+SDOType+`] +wraps an link:Introduction_to_XML_Descriptors_%28ELUG%29[object-XML +mapping (OXM) descriptor]. + +A `+Type+` can have supertypes, which corresponds to the EclipseLink +concept of inheritance policy (see +link:Introduction_to_Descriptors_%28ELUG%29#Descriptor_API[Inheritance +Policy in Descriptor API]). + +To create types programmatically, you populate a +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html[`+DataObject+`] +with them. + +To load types from an XML schema, use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XSDHelper.html[`+XSDHelper+`] +class, as the following example shows: + +[source,java] +---- +HelperContext ctx = HelperProvider.getDefaultContext(); +FileInputStream is = new FileInputStream("test.xsd"); +ctx.getXSDHelper().define(is, null); +---- + +For more information, see the default +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Type.html[`+Type+`] +API. + +==== What You May Need to Know About Sequenced Types + +You can define SDO types as sequenced (that is, `+isSequenced+` is +`+true+`). With sequenced DataObjects you can have fine grained control +over how the properties are ordered when they are saved to XML. For more +information see +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/Sequence.html[`+Sequence+`]. + +==== What You May Need to Know About Open Types + +You can define SDO types as open (that is, isOpen is true). Open +DataObjects will accept additional properties (the ones not specified by +their `+Type+`). + +[#sdo-introel-property] +=== Using Property + +A `+DataObject+` is made up of `+Property+` values. SDO `+Property+` +acts similarly to a property in Java and provides much of the same +metadata as the Java Reflection API provides for Java fields or methods. + +In EclipseLink, a +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOProperty.html[`+SDOProperty+`] +wraps an link:Introduction_to_XML_Mappings_%28ELUG%29[object-XML +mapping] in the following manner: + +* `+DataType=true + isMany=false+` - corresponds to EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Direct_Mapping[OXM +direct mappings] and +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Binary_Data_Mapping[OXM +binary mappings]. +* `+DataType=true + isMany=true+` - corresponds to EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Direct_Collection_Mapping[OXM +direct collection mappings] and +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Binary_Data_Collection_Mapping[OXM +binary collection mappings]. +* `+DataType=false + isMany=false + containment=true+` - corresponds to +EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Object_Mapping[OXM +composite object mappings]. +* `+DataType=false + isMany=true + containment=true+` - corresponds to +EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Collection_Mapping[OXM +composite collection mappings]. +* `+DataType=false + isMany=false + containment=false+` - corresponds to +EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Object_Reference_Mapping[OXM +reference mappings]. +* `+DataType=false + isMany=true + containment=false+` - corresponds to +EclipseLink +link:Introduction_to_XML_Mappings_%28ELUG%29#XML_Collection_Reference_Mapping[OXM +collection reference mappings]. + +For more information, see the +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Property.html[`+Property+`] +API. + +=== Defining Metadata + +You can use the following helper classes to define and access SDO +metadata: + +* <> +* <> + +[#sdo-introel-xsdhelper] +==== How to Define Metadata with XSDHelper + +You use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XSDHelper.html[`+XSDHelper+`] +to do the following: + +* Define SDO metadata, where SDO metadata is derived from XML schemas. +* Generate XML schemas from SDO types. + +You can obtain the default `+XSDHelper+` from the `+INSTANCE+` field or +from the `+getXSDHelper+` method of the default +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +You can customize metadata by using the following annotations that you +apply to the XML schema: + +* Standard annotations: +** Information pending +** {blank} +* EclipseLink annotations: +** Information pending +** {blank} + +You can also use various APIs to determine the XML representation about +the SDO metadata. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXSDHelper.html[`+SDOXSDHelper+`] +API +* <> + +[#sdo-introel-typehelper] +==== How to Define Metadata with TypeHelper + +You use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/TypeHelper.html[`+TypeHelper+`] +to do the following: + +* Look up SDO metadata. +* Programmatically define SDO metadata. + +You can obtain the default `+TypeHelper+` from the `+INSTANCE+` field or +from the `+getTypeHelper+` method of the default +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information on how to use the `+TypeHelper+` in your +application, see <>. + +For more information, see EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOTypeHelper.html[`+SDOTypeHelper+`] +API. + +== Using Data + +Use the following SDO classes to work with data: + +* <> +* <> + +[#sdo-introel-do] +=== Using DataObject + +A +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html[`+DataObject+`] +is the central concept in SDO. It represents business data and +corresponds to an `+Object+` in Java (POJO). To define +link:Introduction_to_XML_Mappings_%28ELUG%29[object-XML mappings], you +map the `+DataObject+` to XML. You can create your data object as either +dynamic (see +http://wiki.eclipse.org/EclipseLink/Examples/SDO/DynamicAPI[Dynamic +DataObject Examples]), or static by applying a type-safe interface to it +(see <>). + +The `+DataObject+` provides an XPath-like (see +link:Introduction_to_Mappings_%28ELUG%29#Mappings_and_XPath[Mappings and +XPath]) means of data access. For example, the following code is valid +in SDO: + +[source,java] +---- +customerDO.getDataObject("contact-info/phone-number[2]"); +---- + +The standard XML Binding, however, would require the following: + +[source,java] +---- +customer.getContactInfo().getPhoneNumbers().get(1); +---- + +Note that you can use the EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/extension/XPathHelper.html[`+XPathHelper+`] +to query data objects using an XPath expression. + +For more information, see EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDODataObject.html[`+SDODataObject+`] +API. + +==== What You May Need to Know About Serialization in SDO + +SDO DataObjects are serializable. When a DataObject is serialized, the +entire data graph is serialized with it. On the stream SDO DataObjects +are represented in a specification defined XML representation. + +[#sdo-introel-xmldoc] +=== Using XMLDocument + +When you marshall (save) a `+DataObject+` to XML, or unmarshall an XML +document into objects, the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLDocument.html[`+XMLDocument+`] +class contains information about the root of the XML document. + +The +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLHelper.html[`+XMLHelper+`] +creates and serializes `+XMLDocument+` objects. The `+XMLDocument+` does +not change the state of any input `+DataObject+` and ignores any +containers. + +For more information, see EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOXMLDocument.html[`+SDOXMLDocument+`] +API. + +=== What You May Need to Know About Sequence, ChangeSummary, and DataGraph + +The following SDO classes allow you to obtain additional information +about data objects: + +* http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Sequence.html[`+Sequence+`] +– provides a list of properties and their corresponding values. It +represents the order of all the XML elements in the `+DataObject+`. Each +entry in a Sequence has an index, with the order of settings being +preserved, even across different properties. The same properties that +appear in a `+Sequence+` are also available through a `+DataObject+`, +but without preserving the order across properties. You should use +sequences when dealing with semi-structured business data, for example, +mixed text XML elements. +* http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/ChangeSummary.html[`+ChangeSummary+`] +– records changes to data objects, therefore reducing the amount of data +that needs to be transmitted between collaborating SDO applications. The +`+ChangeSummary+` only tracks modifications that have been made to a +tree of data objects starting from the point when logging was activated. +If logging is no longer active, the log includes only changes that were +made up to the point when logging was deactivated. Otherwise, it +includes all changes up to the point at which the `+ChangeSummary+` is +being interrogated. Although change information is only gathered when +logging is on, you can query change information whether logging is on or +off. All of the information returned is read-only. Use the +`+ChangeSummary+`’s `+beginLogging+` method to clear the `+List+` of +changed `+DataObjects+` and start change logging; use the `+endLogging+` +method to stop change logging; use `+undoChanges+` to restore the tree +of data objects to its state when logging began. Note that +`+undoChanges+` also clears the log, but does not affect `+isLogging+`. + +Note that the +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataGraph.html[`+DataGraph+`] +class has been deprecated. + +For more information, see the following EclipseLink APIs: + +* http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOSequence.html[`+SDOSequence+`] +* http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOChangeSummary.html[`+SDOChangeSummary+`] diff --git a/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_SDO_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_SDO_(ELUG).adoc new file mode 100644 index 00000000000..3c2cd4675e0 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Introduction_to_SDO_(ELUG).adoc @@ -0,0 +1,123 @@ +This section introduces concepts of Service Data Objects (SDO) and +provides general information on it. + +[#sdo-intro] +== What Is SDO? + +SDO is designed to be a unified view of data, similarly to POJO in Java +EE. There are several programming languages (of which Java is one) that +support the SDO specification. + +You can use SDO to develop data-oriented applications. SDO includes an +architecture and an API. + +The following are possible expressions of SDO: + +* <> +* <> +* <> +* <> + +For more information, see http://jcp.org/en/jsr/detail?id=235[SDO Specification]. + +[#sdo-intro-dynamic] +=== Dynamic Object Model + +SDO metadata is represented as +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Type.html[`+Type+`] +and +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Property.html[`+Property+`] +objects. A `+Type+` is comparable to a Java class, and a `+Property+` – +to a Java field. You define this metadata at run time either +programmatically or from an XML schema, as follows: + +[source,java] +---- +Type customerType = TypeHelper.INSTANCE.getType("urn:example", "customer"); +Property firstNameProperty = customerType.getProperty("first-name"); + +Type addressType = TypeHelper.INSTANCE.getType("urn:example", "address"); +---- + +Data is represented as instances of `+Type+` called +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataObject.html[`+DataObject+`]. +The `+DataObject+` in SDO corresponds to a Java `+Object+` and have many +generic accessors that you can use to manipulate the data, as the +following example shows: + +[source,java] +---- +DataObject customerDO = DataFactory.INSTANCE.create(customerType); +customerDO.setString(firstNameProperty, "Jane"); + +DataObject addressDO = DataFactory.INSTANCE.create("urn:example", address); +addressDO.set("street", "123 Any Street"); +---- + +A `+DataObject+`’s properties can contain simple values, other data +objects, or ``+List+``s of simple values or ``+DataObject+``s. Data objects +can contain references to other data objects, or they can contain them. + +[#sdo-intro-typed] +=== Typed Object Model + +SDO as a dynamic object model is useful in certain frameworks based on +the fact that dynamic models let you add metadata without requiring a +redeployment of your application. However, in some cases a strongly +typed model is required that allows for code completion in an IDE. You +can perform a code generation step to produce typed interfaces complete +with bean-style accessors, as the following example shows: + +[source,java] +---- +Customer customerDO = (Customer) DataFactory.INSTANCE.create(customerType); +CustomerDO.setFirstName("Jane"); +---- +For more information, see the <> +and <> examples. + +[#sdo-intro-xml] +=== XML Representation + +SDO has a built-in support for handling XML. You can introspect the SDO +metadata to determine the corresponding XML representation, as the +following EclipseLink example shows: + +[source,java] +---- +XSDHelper.INSTANCE.isMixed(customerType); +XSDHelper.INSTANCE.isElement(firstNameProperty); +---- + +You can then convert the `+DataObject+` instances to and from XML, as +follows: + +[source,java] +---- +XMLHelper.INSTANCE.save(customerDO, "urn:example", "customer", System.out); +---- + +For more information, see the following: + +* <> +* <> + +[#sdo-intro-disconnected] +=== Disconnected Object + +SDO was designed to represent disconnected data in a Service Component +Architecture (SCA) environment. You can do so by using the +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataObject.html[`+ChangeSummary+`] +that tracks changes made to data objects over time. Note that this +applies to `+DataObject+` instances that have a `+ChangeSummary+` +property. Consider the following example: + +[source,java] +---- +List changed = customerDO.getChangeSummary().getChangedDataObjects(); +---- + +EclipseLink is focused on separating data from its messaging or +persisted representations. With SDO support this data can be a POJO or a +data object, which allows you to work with data in both Java EE and SCA +environments. diff --git a/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Using_EclipseLink_SDO_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Using_EclipseLink_SDO_(ELUG).adoc new file mode 100644 index 00000000000..91a015572ab --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/EclipseLink_UserGuide_SDO_Using_EclipseLink_SDO_(ELUG).adoc @@ -0,0 +1,311 @@ +This section explains where and how you use EclipseLink SDO to customize +your application to meet requirements. + +[#sdo-usage] +== Performing Actions on Data Objects at Run Time + +Use the following classes to perform actions on your +http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataObject.html[data +objects]: + +* <> +* <> +* <> +* <> +* <> +* <> + +For more information, see <>. + +[#sdo-usage-helperctx] +=== Using HelperContext + +SDO defines a +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`] +interface. You use it to access related SDO helper classes that let you +perform common operations such as reading and writing XML documents, +defining SDO types from XML Schema, and so on. + +To obtain a default context, call the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/impl/HelperProvider.html[`+HelperProvider+`] +`+getDefaultContext+` method. + +You can create the local context provided by EclipseLink as follows: + +[source,java] +---- +HelperContext helperContext = new SDOHelperContext(); +---- + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOHelperContext.html[`+SDOHelperContext+`] +API +* EclipseLink <> examples + +==== What You May Need to Know About Local and Global HelperContext + +All the helpers that you can retrieve from the INSTANCE fields are the +same ones as can be accessed from HelperProvider. + +[source,java] +---- +XSDHelper.INSTANCE == HelperProvider.getDefaultContext().getXSDHelper() +---- + +In terms of Java serialization, both global and local HelperContexts can +be used to serialize DataObjects, but the global HelperContext is always +used for deserialization. + +Using the EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOHelperContext.html[`+SDOHelperContext+`] +`+makeDefaultContext+` method, you can promote your local context to +become the global (default) one. + +[#sdo-usage-datafactory] +=== Using DataFactory + +You use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataFactory.html[`+DataFactory+`] +to create disconnected instances of a +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html[`+DataObject+`]. +That is, the newly created `+DataObject+` instances have no set +properties and no container. + +You can obtain the global `+DataFactory+` from the `+INSTANCE+` field or +a DataFactory corresponding to a HelperContext using the +`+getDataFactory+` method on +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataFactory.html[`+SDODataFactory+`] +API +* EclipseLink <> examples + +[#sdo-usage-xmlhelper] +=== Using XMLHelper + +You use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLHelper.html[`+XMLHelper+`] +to convert XML documents into data objects, and vice versa. The two main +operations of the `+XMLHelper+` are `+load+` and `+save+`. + +You can obtain the global `+XMLHelper+` from the `+INSTANCE+` field or a +XMLHelper corresponding to a HelperContext using the `+getXMLHelper+` +method on +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXMLHelper.html[`+SDOXMLHelper+`] +API +* EclipseLink <> examples + +[#sdo-usage-datahelper] +=== Using DataHelper + +The main purpose of the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataHelper.html[`+DataHelper+`] +is to enable conversion of values used with data objects between data +types. + +You can obtain the global `+DataHelper+` from the `+INSTANCE+` field or +a DataHelper corresponding to a HelperContext using the +`+getDataHelper+` method on +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataHelper.html[`+SDODataHelper+`] +API +* EclipseLink <> examples + +[#sdo-usage-copyhelper] +=== Using CopyHelper + +You use the +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/CopyHelper.html[`+CopyHelper+`] +to create the following types of copies of data objects: + +* a copy of a `+DataObject+`’s values with `+DataType+` properties; +* a copy of a tree of `+DataObject+` instances. + +You can obtain the global `+CopyHelper+` from the `+INSTANCE+` field or +a CopyHelper corresponding to a HelperContext using the +`+getCopyHelper+` method on +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOCopyHelper.html[`+SDOCopyHelper+`] +API +* EclipseLink <> examples + +[#sdo-usage-equalityhelper] +=== Using EqualityHelper + +An +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/EqualityHelper.html[`+EqualityHelper+`] +provides methods to compare data objects and let you determine the +following: + +* whether or not two `+DataObject+` instances have the same values for +their `+DataType+` properties; +* whether or not two trees of data objects are equal. + +You can obtain the global `+EqualityHelper+` from the `+INSTANCE+` field +or an EqualityHelper corresponding to a HelperContext using the +`+getEqualityHelper+` method on +http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html[`+HelperContext+`]. + +For more information, see the following: + +* EclipseLink +http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOEqualityHelper.html[`+SDOEqualityHelper+`] +API +* EclipseLink <> examples + +== Performing Integration + +You can integrate your SDO application with the following technologies: + +* <> +* <> + +The first step in this integration proccess is to create POJO/SDO +bridge. + +[#integration-xml] +=== Integrating SDO with Jakarta XML Binding + +For information and examples, see <>. + +[#integration-persistence] +=== Integrating SDO with Jakarta Persistence + +For information and examples, see <>. + +== Using SDO as a Web Service Binding Layer + +You can easily invoke a Web service and obtain results in the form of +data objects, as the following example shows: + +[source,java] +---- +DataObject resultEnvelope = + WebService.invoke(po, "http://werbservices.org/purchaseOrder", soap, "Envelope"); + +// Get the purchase order from the result envelope +DataObject resultPo = resultEnvelope.getDataObject("Body/purchaseOrder"); +---- + +You can also build a Web services client around the `+XMLHelper+`. For +example, in a simple Web service client, you could post an input +`+DataObject+` representing an XML document using the `+XMLHelper+`, and +then have the returning XML document returned to the caller as a +`+DataObject+`: + +[source,java] +---- +public static DataObject invoke(DataObject input, String serviceUri, + String rootElementURI, String rootElementName) + throws IOException { + URL address = new URL(serviceUri); + HttpURLConnection connection = (HttpURLConnection) address.openConnection(); + if (input != null) { + connection.setRequestMethod("POST"); + connection.setDoOutput(true); + connection.addRequestProperty("Content-Type", "text/xml; charset=utf-8"); + OutputStream os = connection.getOutputStream(); + // Add the XML document to the request + XMLHelper.INSTANCE.save(input, rootElementURI, rootElementName, os); + os.flush(); + } + // invoke the service + connection.connect(); + int code = connection.getResponseCode(); + if (code != HttpURLConnection.HTTP_OK) { + throw new IOException("HTTP " + code + " " + connection.getResponseMessage()); + } + InputStream is = connection.getInputStream(); + // Return the root DataObject from the web service response + DataObject output = XMLHelper.INSTANCE.load(is).getRootObject(); + return output; +} +---- + +=== How to Use Web Service Attachments + +Information pending + +== Executing XPath with XML + +Many of the accessor methods for data objects make use of a `+String+` +parameter that provides the path that identifies the property to which +the method applies. + +The XPath expression is an augmented subset of XPath with the additional +ability to access data using 0 as a base index. You specify the path +using the following syntax: + +---- +path ::= (scheme ':')? '/'? (step '/')* step +scheme ::= [^:]+ +step ::= '@'? property + | property '[' index_from_1 ']' + | property '.' index_from_0 + | reference '[' attribute '=' value ']' + | ".." +property ::= NCName ;; may be simple or complex type +attribute ::= NCName ;; must be simple type +reference :: NCName ;; must be DataObject type +index_from_0 ::= Digits +index_from_1 ::= NotZero (Digits)? +value ::= Literal + | Number + | Boolean +Literal ::= '"' [^"]* '"' + | "'" [^']* "'" +Number ::= Digits ('.' Digits?)? + | '.' Digits +Boolean ::= true + | false +NotZero ::= [1-9] +Digits ::= [0-9]+ +;; leading '/' begins at the root +;; ".." is the containing DataObject, using containment properties +;; Only the last step have an attribute as the property +---- + +Note that properties are always matched by name independent of their XML +representation. + +The following example shows how to construct an XPath that you can use +to access a `+DataObject+` contained in another `+DataObject+` is to +specify the index of the contained `+DataObject+` within the appropriate +property: + +[source,java] +---- +DataObject department = company.getDataObject("departments.0"); +---- + +Another way to access a contained `+DataObject+` is to identify that +object by specifying the value of one of the attributes of that object. +For example: + +[source,java] +---- +DataObject employee = department.getDataObject("employees[SN='E0002']"); +---- + +You can also use XPath expressions to set or unset values of properties, +including multivalued properties. Note that each step of the path before +the last must return a single `+DataObject+`. When the property is a +`+Sequence+`, the values returned are those of the `+getValue+` method. diff --git a/docs/docs.ug/src/main/asciidoc/sdo/JAXB.adoc b/docs/docs.ug/src/main/asciidoc/sdo/JAXB.adoc new file mode 100644 index 00000000000..506317c7b2b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/JAXB.adoc @@ -0,0 +1,223 @@ +[#sdo-example-xmlbinding] +=== SDO-XML Integration + +* <> +* <> +** <> +** <> +** <> +* <> +* <> +* <> +* <> +* <> +* <> + +[#sdo-example-xmlbinding-overview] +==== [#Overview .mw-headline]#Overview# + +The JAXBHelperContext is a bridge between POJOs and SDO DataObjects. +This bridge allows POJO data to be exposed as SDO DataObjects, this is +useful when using POJO data with SDO aware applications. The bridge is +based on their corresponding XML representations. + +[#sdo-example-xmlbinding-create] +==== [#Create_the_POJO.2FSDO_Bridge .mw-headline]#Create the POJO/SDO Bridge# + +JAXBHelperContext is the bridge between POJOs and DataObjects. This +bridge allows POJOs to be converted to/from SDO DataObjects. It also +provides a mechanism to determine the SDO type corresponding to a POJO +class. + +[#sdo-example-xmlbinding-define] +===== [#Define_an_XML_Representation_for_the_POJOs .mw-headline]#Define an XML Representation for the POJOs# + +This XML representation can be defined either by applying JAXB +annotations to the POJOs, or by using an existing XML schema and mapping +to it using EclipseLink MOXy. Programmatically this XML binding is +represented as a javax.xml.bind.JAXBContext. + +[source,java] +---- +JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer"); +---- + +For help on creating a JAXBContext see: + +* link:/EclipseLink/Examples/MOXy/JAXB#Creating_a_JAXBContext_using_jaxb.properties[Creating +a JAXBContext using jaxb.properties] +* link:/EclipseLink/Examples/MOXy/NativeOxmJaxbContext[Creating a Native +OXM aware JAXBContext] + +[#sdo-example-xmlbinding-instantiate] +===== Instantiate the JAXBHelperContext + +The JAXBHelperContext is instantiated using a JAXBContext. This +JAXBContext represents the object-to-XML mapping for the POJOs. If +static DataObjects are being used, a second constructor is offered that +takes a ClassLoader as a parameter. + +[source,java] +---- +JAXBHelperContext jaxbHelperContext = new JAXBHelperContext(jaxbContext); +---- + +[#sdo-example-xmlbinding-metadata] +===== Define the SDO Side of the Metadata + +An XML schema can be used to create the SDO metadata. This is the same +schema that the POJOs are mapped to. This step has been separated so +that SDO annotations could be added to the XML schema. + +[source,java] +---- +jaxbHelperContext.getXSDHelper().define(xmlSchema); +---- + +For help on creating an XML Schema from POJOs using JAXB see: + +* link:/EclipseLink/Examples/MOXy/JAXB#Using_JAXBContext_to_Generate_an_XML_Schema[Generating +an XSD using a JAXBContext] + +[#sdo-example-xmlbinding-get-type] +==== Get the SDO Type for a POJO + +From the JAXBHelperContext you can determine the SDO type from a POJO +class. This provides quick access to the necessary SDO metadata, to work +with the data as SDO DataObjects. + +[source,java] +---- +Type customerType = jaxbHelperContext.getType(Customer.class); +DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType); +---- + +[#sdo-example-xmlbinding-to-sdo] +==== Convert a POJO to a SDO DataObject + +POJOs corresponding to the types in the JAXBContext, can be converted to +SDO DataObjects using the "wrap" operation on JAXBHelperContext. This +operation should be called on the root POJO. + +[source,java] +---- +Customer customer = new Customer(); +Address address new Address(); +address.setStreet("123 Any Street"); +customer.set(address); + +DataObject customerDO = jaxbHelperContext.wrap(customer); +customerDO.getString("address/street"); // returns "123 Any Street" +---- + +Multiple calls to wrap for the same instance POJO return the same +instance of DataObject, in other words the following is always true: + +[source,java] +---- +jaxbHelperContext.wrap(customer123) == jaxbHelperContext.wrap(customer123) +jaxbHelperContext.wrap(customer123) != jaxbHelperContext.wrap(customer456) +---- + +The wrap operation may also be called on a collection POJOS. + +[source,java] +---- +List dataObjects = jaxbHelperContext.wrap(pojoCollection); +---- + +[#sdo-example-xmlbinding-to-pojo] +==== Convert a SDO DataObject to a POJO + +SDO DataObjects corresponding to POJOs with types in the JAXBContext, +can be converted to POJOs using the "unwrap" operation on +JAXBHelperContext. + +[source,java] +---- +Type customerType = jaxbHelperContext.getType(Customer.class); +DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType); +DataObject addressDO = customerDO.create("address"); +addressDO.set("street", "123 Any Street"); + +Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO); +customer.getAddress().getStreet(); // returns "123 Any Street" +---- + +Multiple calls to unwrap for the same DataObject must return the same +instance of Object, in other words the following is always true: + +[source,java] +---- +jaxbHelperContext.unwrap(customerDO123) == jaxbHelperContext.unwrap(customerDO123) +jaxbHelperContext.unwrap(customerDO123) != jaxbHelperContext.unwrap(customerDO456) +customer123 == jaxbHelperContext.unwrap(jaxbHelperContext.wrap(customer123)) +---- + +The unwrap operation may also be called on a collection of SDO +DataObjects. + +[source,java] +---- +List objects = jaxbHelperContext.unwrap(dataObjectCollection); +---- + +[#sdo-example-xmlbinding-unmarshall] +==== Unmarshalling from XML (SDO load) + +JAXBHelperContext can be used to unmarshal the POJOs from XML. + +[source,java] +---- +FileInputStream xml = new FileInputStream("customer.xml"); +XMLDocument xmlDocument = jaxbHelperContext.getXMLHelper().load(xml); +DataObject customerDO = xmlDocument.getRootObject(); +Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO); +---- + +[#sdo-example-xmlbinding-marshall] +==== Marshalling to XML (SDO save) + +JAXBHelperContext can be used to marshal the POJOs to XML. + +[source,java] +---- +DataObject customerDO = jaxbHelperContext.wrap(customer); +XMLDocument xmlDocument =jaxbHelperContext.getXMLHelper().createDocment(customerDO, "urn:customer", "root"); +jaxbHelperContext.getXMLHelper().save(xmlDocument, System.out, null); +---- + +[NOTE] +==== +With the exception of the ChangeSummary property (if any), the +output of the SDO save operation will be identical to the output +produced by JAXB marshalling the entities directly. +==== + +[#sdo-example-xmlbinding-limitations] +==== Limitations + +The following are known limitations of the current implementation. + +* All entities must be mapped to global XML elements or global complex +types. +* The schema context for a OXM descriptor can only be set to a global +element if that element has an anonymous complex type. Otherrwise the +schema context must be set to be the corresponding global complex type +instead. +* Path and position based MOXy mappings are currently not supported with +the SDO integration. The following are compatible "address" and +"name/text()", and the following are not currently compatible +"contact-info/address" and "phone-number[2]". +* Only the following MOXy mappings are supported (either through native +mapping or JAXB equivalents): +** XML Direct Mapping +** XML Direct Collection Mapping +** XML Composite Object Mapping +** XML Compoiste Collection Mapping +** XML Object Reference Mapping +** XML Collection Reference Mapping +* The current implementation does not support ChangeSummary +* The current implementation does not support open content properties +* The current implementation does not support inheritance + diff --git a/docs/docs.ug/src/main/asciidoc/sdo/JPA.adoc b/docs/docs.ug/src/main/asciidoc/sdo/JPA.adoc new file mode 100644 index 00000000000..1a6ed027605 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/JPA.adoc @@ -0,0 +1,168 @@ +[#sdo-example-persistence] +=== SDO-Persistence Integration + +* <> +* <> +* <> +* <> +* <> +* <> + +[#sdo-example-persistence-overview] +==== Overview + +In this use case a developer wishes to expose their JPA model as an SDO +DataObject model (static or dynamic). The JPA entities are mapped to a +XSD through JAXB mappings. + +* In this use case the developer defines the mapping from the JPA domain +model (POJOs) to an XML schema (XSD) using JAXB mappings (annotations or +EclipseLink native OXM). +* The XSD is then generated using the JAXB Java-XML Compiler (JXC), or +in the meet-in-the-middle case the schema from the previous step. +* The SDO Data Object model is now implicitly define through the use of +the generated XSD. If the service developer wishes to use a static +DataObject model they can optionally use the SDO compiler to generate +this model based on the XSD. + +[#sdo-example-persistence-bridge] +==== Create the POJO/SDO Bridge + +JAXBHelperContext is the bridge between POJOs and DataObjects. This +bridge allows POJOs to be converted to/from SDO DataObjects. + +[source,java] +---- +JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer"); +JAXBHelperContext jaxbHelperContext = new JAXBHelperContext(jaxbContext); +jaxbHelperContext.getXSDHelper().define(customerXSD); +---- + +When using JPA entities behind the SDO model the service developer will +need to express the XML schema represenation through JAXB mappings +(including MOXy extensions) on the JPA entities. + +For more informations see: + +* link:/EclipseLink/Examples/SDO/JAXB#Create_the_POJO.2FSDO_Bridge[Create +the POJO/SDO Bridge] + +[#sdo-example-persistence-query] +==== Querying + +When developing a service that will return SDO DataObject instances from +the relational database the developer will issue queries against the +database using JPA (PK Find, JP QL or Native ORM queries in JPA 1.0). +The resulting entity/entities will then be wrapped by SDO DataObjects +using the POJO/SDO bridge. + +[source,java] +---- +EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample"); +EntityManager em = emf.createEntityManager(); +MyEntity entity = em.createQuery("SELECT e FROM MyEntity e WHERE ...").getSingleResult(); + +DataObject dataObject = jaxbHelperContext.wrap(entity); +---- + +[source,java] +---- +EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample"); +EntityManager em = emf.createEntityManager(); +List entities = em.createQuery("SELECT e FROM MyEntity e WHERE ...").getResultList(); + +List dataObjects = jaxbHelperContext.wrap(entities); +---- + +[#sdo-example-persistence-persist] +==== Creating (JPA persist) + +Creating new entities in the database can be done by explicitly +requesting the new data to be persisted. If the DataObject being +persisted combines new objects with updates to existing objects then the +Updating scenario below will be used. + +[source,java] +---- +EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample"); +EntityManager em = emf.createEntityManager(); + +JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer"); +JAXBHelperContext jaxbHelperContext = new JAXBHelperConext(jaxbContext); +jaxbHelperContext.getXSDHelper().define(customerXSD); + +Type customerType = jaxbHelperContext.getType(Customer.class); +DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType); +customerDO.setString("first-name", "Jane"); +customerDO.setString("last-name", "Doe"); +DataObject addressDO customerDO.create("address"); +addressDO.setString("street", "123 Any Street"); +addressDO.setString("city", "Any Town"); + +em.getTransaction().begin(); +em.persist(jaxbHelperContext.unwrap(customerDO)); +em.getTransaction().commit(); +---- + +[NOTE] +==== +The cascade persist configuration on the underlying entity's +relationship mappings will define the scope of which new instances in +the graph will be persisted. +==== + +[#sdo-example-persistence-merge] +==== Updating (JPA merge) + +In the case of updates to existing entities as well as addition of new +entities through relationships the merge call on the helper will be +used. + +[source,java] +---- +EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample"); +EntityManager em = emf.createEntityManager(); + +JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer"); +JAXBHelperContext jaxbHelperContext = new JAXBHelperConext(jaxbContext); +jaxbHelperContext.getXSDHelper().define(customerXSD); + +em.getTransaction().begin(); +em.merge(jaxbHelperContext.unwrap(dataObject)); +// ... Other operations within the same TX +em.getTransaction().commit(); +---- + +[NOTE] +==== +The creation of new objects and the removal of existing objects +in the graph result in database operations based on the cascade and +private-owned configurations in the JPA model's relationship mappings. +==== + +[NOTE] +==== +getTransaction() may return different transactions so that in the +example above commit() may not affect the same transaction affected by +the call to begin(). +==== + +[#sdo-example-persistence-remove] +==== Deleting (JPA remove) + +Entities can be removed from the database using the helper's remove +call: + +[source,java] +---- +EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample"); +EntityManager em = emf.createEntityManager(); + +JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer"); +JAXBHelperContext jaxbHelperContext = new JAXBHelperConext(jaxbContext); +jaxbHelperContext.getXSDHelper().define(customerXSD); + +em.getTransaction().begin(); +em.remove(jaxbHelperContext.unwrap(dataObject)); +em.getTransaction().commit(); +---- diff --git a/docs/docs.ug/src/main/asciidoc/sdo/MetadataXMLSchema.adoc b/docs/docs.ug/src/main/asciidoc/sdo/MetadataXMLSchema.adoc new file mode 100644 index 00000000000..d9ee197d835 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/MetadataXMLSchema.adoc @@ -0,0 +1,152 @@ +[#sdo-example-metadata] +=== Convert an XML Schema to SDO Metadata + +* <> +* <> +* <> +** <> +** <> +** <> +* <> +** <> +** <> + +[#sdo-example-metadata-overview] +==== Overview + +The following example will demonstrate how to use EclipseLink's SDO +functionality to: + +* Define SDO Types and Properties from an XML Schema +* Lookup SDO Types and Properties +* Get XML Schema Information about SDO Types and Properties + +[#sdo-example-metadata-define] +==== Define SDO Types and Properties from XML Schema + +The first thing that needs to be done in a SDO application is to set up +the metadata for the Types and Properties. This is most commonly done by +loading an XML schema, although it may also be done programmatically. + +[source,java] +---- +FileInputStream xsdInputStream = new FileInputStream("Customer.xsd"); +XSDHelper.INSTANCE.define(xsdInputStream, null); +---- + +[#sdo-example-metadata-lookup] +==== Lookup SDO Types and Properties + +[#sdo-example-metadata-lookup-open] +===== Get a SDO Open Content Property corresponding to a Global Attribute/Element + +Once the XML schema has been processed the global attributes and +elements are available as open content properties. + +[source,java] +---- +Property phoneNumberProperty = + TypeHelper.INSTANCE.getOpenContentProperty("http://www.example.org/customer-example", "phone-number"); +---- + +You can also use XSDHelper to get the open content properties using XML +information. This is useful when you have a global element and attribute +in the same namspace with the same name. + +[source,java] +---- +Property phoneNumberProperty = + XSDHelper.INSTANCE.getGlobalProperty("http://www.example.org/customer-example", "phone-number", true); +---- + +[#sdo-example-metadata-lookup-ct] +===== Get a SDO Type corresponding to a Global Complex Type + +When the SDO Type corresponds to a global complex type like the +following: + +[source,xml] +---- + + + + + + + + +---- + +Then the corresponding SDO Type can be looked up as follows: + +[source,java] +---- +Type addressType = TypeHelper.INSTANCE.getType("http://www.example.org/customer-example", "address-type"); +---- + +[#sdo-example-metadata-lookup-gae] +===== Get a SDO Type corresponding to a Global Attribute/Element + +When the SDO Type corresponds to a global element like the following: + +[source,xml] +---- + + + + + + + + + +---- + +Then the corresponding SDO Type can be looked up as follows: + +[source,java] +---- +Property phoneNumberProperty = + TypeHelper.INSTANCE.getOpenContentProperty("http://www.example.org/customer-example", "phone-number"); +Type phoneNumberType = phoneNumberProperty.getType(); +---- + +[#sdo-example-metadata-info] +==== Get XML Schema Information about SDO Types and Properties + +[#sdo-example-metadata-info-prop] +===== SDO Property XML Schema Info + +You can determine if the SDO property corresponds to an XML attribute or +XML element: + +[source,java] +---- +XSDHelper.INSTANCE.isAttribute(phoneNumberProperty); +XSDHelper.INSTANCE.isElement(phoneNumberProperty); +---- + +You can get XML name/URI information: + +[source,java] +---- +XSDHelper.INSTANCE.getLocalName(phoneNumberProperty); +XSDHelper.INSTANCE.getNamespaceURI(phoneNumberProperty); +---- + +[#sdo-example-metadata-info-type] +===== SDO Type XML Schema Info + +You can get the XML name information: + +[source,java] +---- +XSDHelper.INSTANCE.getLocalName(addressType); +---- + +You can determine if the corresponding XML type is mixed: + +[source,java] +---- +XSDHelper.INSTANCE.isMixed(addressType); +---- diff --git a/docs/docs.ug/src/main/asciidoc/sdo/StaticAPI.adoc b/docs/docs.ug/src/main/asciidoc/sdo/StaticAPI.adoc new file mode 100644 index 00000000000..e927caeca31 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/StaticAPI.adoc @@ -0,0 +1,268 @@ +[#sdo-example-static] +=== Using Type Safe DataObjects to Manipulate XML + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[#sdo-example-static-overview] +==== Overview + +The following example will demonstrate how to use EclipseLink's SDO +functionality to: + +* Generate Java source files from an XML Schema using the SDO Compiler +* Define a set of SDO Types from an XML Schema +* Load an XML file and modify its data +* Monitor changes made to the data +* Save the modified data to XML + +[#sdo-example-static-setup] +==== Setup + +. Ensure that you have EclipseLink correctly installed and configured +for your environment. Please see +link:/EclipseLink/Installing_and_Configuring_EclipseLink[EclipseLink/Installing +and Configuring EclipseLink] for more information. +. Ensure that you have ANT correctly installed and configured. +. Unzip the Example ZIP file to a new directory. +. Edit the `+env.properties+` file in the root directory of the example +and specify the path to your EclipseLink `+jlib+` directory: + +[source,properties] +---- +... +# Edit eclipselink.jlib to point to your EclipseLink jlib directory +eclipselink.jlib=C:/EclipseLink-1.0/eclipselink/jlib +... +---- + +You can compile and run the Example at any time by typing `+ant+` from +the Example directory. + +For Eclipse IDE users, a `+.project+` file is included in the Example +directory. To setup this project in Eclipse: + +. From the "File" menu, choose "Import..." +. In the Import dialog, choose "General > Existing Projects into +Workspace", and click "Next". +. Click "Browse" to select a root directory, and point to the folder +containing this example. After selecting the directory, you should see +the project name in the "Projects" list. Click "Finish". + +This project is configured to use a classpath variable, +`+ECLIPSELINK_JLIB+`, to point to the required JAR files. After the +project is imported, you should define a variable called +`+ECLIPSELINK_JLIB+` to point to your EclipseLink `+jlib+` directory. + +[#sdo-example-static-run] +==== [#Running_the_SDO_Compiler .mw-headline]#Running the SDO Compiler# + +The SDO compiler can be run to generate Static SDO Java files from an +XML Schema: + +[source,bash] +---- +/eclipselink/bin/sdo-compiler.sh [-options] +\eclipselink\bin\sdo-compiler.cmd [-options] + +Options: + -help Prints the help message text + -sourceFile The input schema file (required) + -targetDirectory The directory to generate Java source (optional) + -logLevel Specify the integer value of the logging level + (8=OFF,7=SEVERE,6=WARNING,5=INFO,4=CONFIG,3=FINE,2=FINER(default),1=FINEST,0=ALL) +Example: + sdo-compiler.sh -sourceFile config/Customer.xsd -targetDirectory sdo-compiler-output -logLevel 8 +---- + +For each complex type in the schema, the compiler will generate both an +interface (e.g. `+CustomerType.java+`), and a concrete implementation +which subclasses `+org.eclipse.persistence.sdo.SDODataObject+` (e.g. +`+CustomerTypeImpl.java+`). For this example we will only deal with the +generated interfaces. + +In this example, the SDO Compiler is run from the "`+run.sdo.compiler+`" +task in the ANT build file. + +[#sdo-example-static-init] +==== Initializing the Types from XML Schema + +The first thing that needs to be done in an SDO application is to set up +the metadata for the Types and Properties. This is most commonly done by +loading an XML schema, although it may also be done programmatically. + +[source,java] +---- +FileInputStream xsdInputStream = new FileInputStream("Customer.xsd"); +XSDHelper.INSTANCE.define(xsdInputStream, null); +---- + +[#sdo-example-static-unmarshall] +==== Unmarshalling the XML Document + +With the SDO Types and Properties defined from the schema, we can now +load an XML document based on that schema, and then obtain a +CustomerType object and begin modifying its contents. + +.... +FileInputStream xmlInputStream = new FileInputStream("Customer-data.xml"); +XMLDocument xmlDocument = XMLHelper.INSTANCE.load(xmlInputStream); +CustomerType customer = (CustomerType) xmlDocument.getRootObject(); +.... + +[#sdo-example-static-track] +==== Tracking Object Modifications using Change Summary + +SDO's Change Summary provides access to change history information for +the DataObjects in a data graph. A change history covers any +modifications that have been made to a data graph starting from the +point when logging was activated. + +In order to use Change Summary, we have defined an element of type +"`+sdo:ChangeSummaryType+`" on our root complex type: + +[source,xml] +---- + + + ... + + + + +---- + +Before we start modifying our data, we must enable logging: + +[source,java] +---- +customer.getChangeSummary().beginLogging(); +---- + +From this point on, any modifications to the DataObject will be captured +in the Change Summary, until logging is deactivated: + +[source,java] +---- +customer.getChangeSummary().endLogging(); +---- + +[#sdo-example-static-modify] +==== Modifying the DataObjects + +Below are examples of manipulating the DataObjects using the static +classes. Note that there are JavaBean-type accessors on the static +interfaces. + +Modifying the ShippingAddress ZipCode: + +[source,java] +---- +AddressType address = customer.getContactInfo().getShippingAddress(); +address.setZipCode("27601"); +---- + +Adding a new PhoneNumber: + +[source,java] +---- +PhoneNumber phoneNumber = + (PhoneNumber) DataFactory.INSTANCE.create("urn:customer-example", "phone-number"); +phoneNumber.setNumberType("home"); +phoneNumber.setValue("(613) 555-3333"); +customer.getContactInfo().getPhoneNumber().add(phoneNumber); +---- + +Removing all "cell" PhoneNumbers: + +[source,java] +---- +ArrayList phoneNumbersToRemove = new ArrayList(); +List phoneNumbers = customer.getContactInfo().getPhoneNumber(); +Iterator it = phoneNumbers.iterator(); +while (it.hasNext()) { + PhoneNumber phoneNumber = (PhoneNumber) it.next(); + if (phoneNumber.getNumberType().equals("cell")) { + phoneNumbersToRemove.add(phoneNumber); + } +} +phoneNumbers.removeAll(phoneNumbersToRemove); +---- + +[#sdo-example-static-marshall] +==== Marshalling the DataObjects + +The following code segment demonstrates how to marshal DataObjects +wrapped in a `+commonj.sdo.helper.XMLDocument+` back to XML. In this +example the stream we are saving to is `+System.out+`, so the XML text +will be printed to the console. + +[source,java] +---- +XMLHelper.INSTANCE.save(xmlDocument, System.out, null); +---- + +[#sdo-example-static-interpret] +==== Interpreting the Change Summary + +When the document is saved to `+System.out+`, we can see the change +summary information in the XML: + +[source,xml] +---- + + ... + + + + (613) 555-2222 + + + 12345 + + + +---- + +* For DataObjects with modified data type properties, the Change Summary +element contains a copy of the DataObject from the data graph, but +containing only the properties which have changed, and showing their old +values. In our example, we see a "`+shipping-address+`" element which +references "`+#/ns1:contact-info/shipping-address+`" (the element that +was modified), along with its old value, "`+12345+`". + +* DataObjects which are currently in the data graph, but were not +present when logging was started are indicated in the change summary +with a "`+create+`" attribute. If more than one DataObject had been +created, the attribute would contain a space-separated list of +references, one for each DataObject. In our example, we see a +"`+create+`" attribute indicating that +"`+#/ns1:contact-info/ns1:phone-number\[2\]+`" (the second phone number +in the XML) is the newly created one. + +* DataObjects deleted during logging are flagged with the "`+delete+`" +attribute. In this case the change summary also contains a deep copy of +the object which was deleted, as it no longer appears in the data graph. +Here, we see a "`+delete+`" attribute indicating that +"`+#/changeSummary/ns1:contact-info/ns1:phone-number\[2\]+`" (the second +phone number in the _Change Summary_) is the one that was deleted from +the XML. + +[#sdo-example-static-download] +==== Download + +Download the "Examples Zip" from the EclipseLink +http://www.eclipse.org/eclipselink/downloads/[Downloads] page. Code for +this example will be found in the +`+org.eclipse.persistence.example.sdo.staticapi.zip+` file. + diff --git a/docs/docs.ug/src/main/asciidoc/sdo/sdo-examples.adoc b/docs/docs.ug/src/main/asciidoc/sdo/sdo-examples.adoc new file mode 100644 index 00000000000..d0a8d8eea79 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/sdo-examples.adoc @@ -0,0 +1,57 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2024 Oracle and/or its affiliates. All rights reserved. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +/////////////////////////////////////////////////////////////////////////////// + +== Examples + +The following examples are provided to assist developers with their adoption +and usage of EclipseLink's SDO functionality. + +* Getting started +** <> +** <> +// ** Customizing your XSD for SDO Usage +* Using Dynamic Data Objects +** <> +** <> +* Using Static Data Objects +** <> +** <> +* Data Access Service - These examples focus on the usage of SDO with alternative value stores. +** <> +** <> + +// Getting Started +include::BasicAPI.adoc[] + +include::MetadataXMLSchema.adoc[] + +// Using Dynamic Data Objects +include::DynamicAPI.adoc[] + +include::DynamicAPIXML.adoc[] + +// Using Static Data Objects +include::Compiler.adoc[] + +include::StaticAPI.adoc[] + +// Data Access Service +include::JAXB.adoc[] + +include::JPA.adoc[] + diff --git a/docs/docs.ug/src/main/asciidoc/sdo/sdo-main.adoc b/docs/docs.ug/src/main/asciidoc/sdo/sdo-main.adoc new file mode 100644 index 00000000000..c1adaa0b987 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/sdo/sdo-main.adoc @@ -0,0 +1,175 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2024 Oracle and/or its affiliates. All rights reserved. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +/////////////////////////////////////////////////////////////////////////////// + +// include::header.adoc[] + += Service Data Objects (SDO) + +// :nofooter: +// :description: EclipseLink +// :keywords: eclipselink, java, jpa, persistence, introduction, sdo +// :pdf-theme: ../../theme/jakartaee-theme.yml +// :authors: Jakarta Persistence Team, https://projects.eclipse.org/projects/ee4j.jpa +// :email: https://dev.eclipse.org/mailman/listinfo/sdo-example-persistence-dev +// :version-label!: +:doctype: book +// :license: Eclipse Foundation Specification License v1.0 +:source-highlighter: coderay +// :toc: left +:toc: +:toclevels: 4 +:sectnumlevels: 4 +// :sectanchors: +:xrefstyle: short + + + + + +// include::attributes.adoc[] + +// What Is SDO +include::EclipseLink_UserGuide_SDO_Introduction_to_SDO_(ELUG).adoc[] + +// Using SDO Metadata +include::EclipseLink_UserGuide_SDO_Introduction_to_EclipseLink_SDO_(ELUG).adoc[] + +// Using SDO actions +include::EclipseLink_UserGuide_SDO_Using_EclipseLink_SDO_(ELUG).adoc[] + +// //Title and Copyright Information + + + +include::sdo-examples.adoc[] + +//Preface +// [preface] +// include::Compiler.adoc[] +// +// //List of Examples +// // :sectnums!: +// include::DynamicAPI.adoc[] +// +// include::DynamicAPIXML.adoc[] +// +// include::JAXB.adoc[] +// +// include::JPA.adoc[] +// +// include::MetadataXMLSchema.adoc[] +// +// include::StaticAPI.adoc[] + +//Introduction +// :sectnums: +// :sectnumlevels: 1 +// include::{rootdir}/introduction.adoc[] +// +// //Annotation Extensions Reference +// include::{rootdir}/annotations_ref.adoc[] +// +// //Java Persistence Query Language Extensions +// include::{rootdir}/jpql.adoc[] +// +// //JPA Query Customization Extensions +// include::{rootdir}/queryhints.adoc[] +// +// //Persistence Property Extensions Reference +// include::{rootdir}/persistenceproperties_ref.adoc[] +// +// //eclipselink-orm.xml Schema Reference +// include::{rootdir}/schema.adoc[] +// +// include::copyright.adoc[] +// +// +// = Jakarta Persistence +// :pdf-theme: ../../theme/jakartaee-theme.yml +// :authors: Jakarta Persistence Team, https://projects.eclipse.org/projects/ee4j.jpa +// :email: https://dev.eclipse.org/mailman/listinfo/sdo-example-persistence-dev +// :version-label!: +// :doctype: book +// :license: Eclipse Foundation Specification License v1.0 +// :source-highlighter: coderay +// :toc: left +// :toclevels: 4 +// :sectnumlevels: 4 +// :sectanchors: +// :xrefstyle: short +// +// // == License +// :sectnums!: +// include::license-efsl.adoc[] +// +// // == Scope +// // :sectnums!: +// // include::scope.adoc[] +// +// // == The Introduction +// :sectnums: +// include::ch01-introduction.adoc[] +// +// // == Entities +// :sectnums: +// include::ch02-entities.adoc[] +// +// // == Entity Operations +// :sectnums: +// include::ch03-entity-operations.adoc[] +// +// // == Query Language +// :sectnums: +// include::ch04-query-language.adoc[] +// +// // == Metamodel API +// :sectnums: +// include::ch05-metamodel-api.adoc[] +// +// // == Criteria API +// :sectnums: +// include::ch06-criteria-api.adoc[] +// +// // == Entity Managers and Persistence Contexts +// :sectnums: +// include::ch07-entitymanagers-and-persistence-contexts.adoc[] +// +// // == Entity Packaging +// :sectnums: +// include::ch08-entity-packaging.adoc[] +// +// // == Container and Provider Contracts for Deployment and Bootstrapping +// :sectnums: +// include::ch09-container-provider-contracts.adoc[] +// +// // == Metadata Annotations +// :sectnums: +// include::ch10-sdo-example-metadata-annotations.adoc[] +// +// // == Metadata for Object/Relational Mapping +// :sectnums: +// include::ch11-sdo-example-metadata-for-or-mapping.adoc[] +// +// // == XML Object/Relational Mapping Descriptor +// :sectnums: +// include::ch12-xml-or-mapping-descriptor.adoc[] +// +// // == Related Documents +// :sectnums: +// include::related-documents.adoc[] +// diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Attribute_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Attribute_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..97cf355ebfa --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Attribute_Mapping_(ELUG).adoc @@ -0,0 +1,43 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Any_Attribute_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML any attribute +mapping. + +[#Table 170-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Method or direct field access + +Read-only + +Container policy + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Any_Attribute_Mapping[XML +Any Attribute Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..232c7c194d1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,48 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Any_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML any collection +mapping. + +[#Table 65-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring Maps to Wildcard + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Container Policy + +Configuring Mapping Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Any_Collection_Mapping[XML +Any Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* https://writeanypapers.com/[write my paper] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] +* http://www.custom-essays-lab.com/Essay-editing.html[Professional Essay +Editing] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Object_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Object_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..8c43bf3bbfd --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Any_Object_Mapping_(ELUG).adoc @@ -0,0 +1,42 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Any_Object_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML any object mapping. + +[#Table 64-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring Maps to Wildcard + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Any_Object_Mapping[XML +Any Object Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Task[Category: Task] Category:_Release_1[Category: Release 1] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..038cd8ae917 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,63 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Binary_Data_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML binary data +collection mapping. + +[#Table 165-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring a Simple Type Translator + +Configuring the Use of a Single Node + +Configuring the Use of CDATA + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Default Null Value at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +Configuring Container Policy + +Configuring the Use of Inline Binary Data + +Configuring the Use of SwaRef Type + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Binary_Data_Collection_Mapping[XML +Binary Data Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..c0988138cad --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Binary_Data_Mapping_(ELUG).adoc @@ -0,0 +1,61 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Binary_Data_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML binary data +mapping. + +[#Table 160-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring a Simple Type Translator + +Configuring the Use of a Single Node + +Configuring the Use of CDATA + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Default Null Value at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +Configuring the Use of Inline Binary Data + +Configuring the Use of SwaRef Type + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Binary_Data_Mapping[XML +Binary Data Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..c3c4697969a --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,45 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Choice_Collection_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML choice collection +mapping. + +[#Table 169-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Choice element + +Method or direct field access + +Read-only + +Container policy + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Choice_Collection_Mapping[XML +Choice Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Object_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Object_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..e9ab4d0265d --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Choice_Object_Mapping_(ELUG).adoc @@ -0,0 +1,41 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Choice_Object_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML choice object +mapping. + +[#Table 168-1]## + +Option to Configure + +Workbench + +Java + +Choice element + +Method or direct field access + +Read-only + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Choice_Object_Mapping[XML +Choice Object Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Collection_Reference_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Collection_Reference_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..298dcbac788 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Collection_Reference_Mapping_(ELUG).adoc @@ -0,0 +1,45 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Collection_Reference_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML collection +reference mapping. + +[#Table 163-1]## + +Option to Configure + +Workbench + +Java + +Source to target key field association + +Reference class + +Method or direct field access + +Container policy + +Read-only + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Object_Reference_Mapping[XML +Object Reference Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..3419be83b91 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,45 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Composite_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML composite +collection mapping. + +[#Table 63-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring Reference Descriptor + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Container Policy + +Configuring Mapping Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Collection_Mapping[XML +Composite Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Direct_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Direct_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..0bc96a228f4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Direct_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,57 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Composite_Direct_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML direct collection +mapping. + +[#Table 61-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring a Simple Type Translator + +Configuring the Use of a Single Node + +Configuring the Use of CDATA + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Container Policy + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Direct_Collection_Mapping[XML +Composite Direct Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Object_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Object_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..31b1f7f38b4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Composite_Object_Mapping_(ELUG).adoc @@ -0,0 +1,43 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Composite_Object_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML composite object +mapping. + +[#Table 62-1]## + +Option to Configure + +Workbench + +Java + +XPath + +Reference descriptor + +Method or direct field access + +Read-only + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Composite_Object_Mapping[XML +Composite Object Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..00b16f952ce --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Descriptor_(ELUG).adoc @@ -0,0 +1,320 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Configuring_an_XML_Descriptor_(ELUG)[Related +Topics] + +For information on how to create XML descriptors, see +link:Creating%20an%20XML%20Descriptor%20(ELUG)[Creating an XML +Descriptor]. + +This table lists the default configurable options for an XML descriptor. + +[#Table 57-1]## + +[width="100%",cols="<66%,<16%,<18%",options="header",] +|=== +|*Option to Configure* |*EclipseLink Workbench* |*Java* +|link:Using%20Workbench%20(ELUG)#How_to_Configure_XML_Schema_Namespace[XML +schema namespace] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Using%20Workbench%20(ELUG)#How_to_Configure_an_XML_Schema_Reference[XML +schema reference] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Schema_Context_for_an_XML_Descriptor[Schema context] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_for_Complex_Type_of_anyType[Complex type of anyType] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:#Configuring_Default_Root_Element[Default root element] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:#Configuring_Document_Preservation[Document preservation] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Descriptor_Comments[Comments] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Using%20Workbench%20(ELUG)#How_to_Configure_Classes[Classes] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Child_(Branch_or_Leaf)_Class_Descriptor[Inheritance +for a child class descriptor] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inheritance_for_a_Parent_(Root)_Descriptor[Inheritance +for a parent descriptor] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Inherited_Attribute_Mapping_in_a_Subclass[Inherited +attribute mapping in a subclass] +|image:support.gif[Supported.,title="Supported."] +|image:support.gif[Supported.,title="Supported."] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Instantiation_Policy[Instantiation +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_Copy_Policy[Copy +policy] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Descriptor%20(ELUG)#Configuring_a_Descriptor[Amendment +methods] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Mapping%20(ELUG)#Configuring_a_Mapping[Mapping] +|image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] +|=== + +For more information, see +link:Introduction%20to%20XML%20Descriptors%20(ELUG)[Introduction to XML +Descriptors]. + +== Configuring Schema Context for an XML Descriptor + +The Workbench uses the schema context to associate the XML descriptor +reference class with a simple or complex type in one of the schemas +associated with the XML project (see +link:Using%20Workbench%20(ELUG)#How_to_Configure_an_XML_Schema_Reference[How +to Configure an XML Schema Reference]). This allows the Workbench to +display the appropriate attributes available for mapping in that +context. + +You must configure the schema context for an XML descriptor regardless +of whether or not you are using the Workbench. + +The EclipseLink runtime uses the schema context to validate XML +fragments. + +=== How to Configure Schema Context for an XML Descriptor Using Workbench + +To associate an XML descriptor with a specific schema complex type, use +this procedure: + +[arabic] +. Select an XML descriptor in the *Navigator*. Its properties appear in +the Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +[#Figure 57-1]##*_Descriptor Info Tab, Schema Context Option_* +image:schmctx.gif[Descriptor Info Tab, Schema Context +Option,title="Descriptor Info Tab, Schema Context Option"] +. Complete the Schema Context field on the tab. +. Click *Browse* to select the schema element to associate with this +descriptor. For more information, see +link:#Choosing_a_Schema_Context[Choosing a Schema Context]. + +See Also: + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +==== Choosing a Schema Context + +[arabic] +. Use the Choose Schema Context dialog box to select a specific schema +element (such as when mapping an element). [#Figure 57-2]## *_Choose +Schema Context Dialog Box_* image:schcontx.gif[Choose Schema Context +Dialog Box,title="Choose Schema Context Dialog Box"] +. Select a schema element and click *OK*. + +=== How to Configure Schema Context for an XML Descriptor Using Java + +To configure an XML descriptor with a schema context using Java, create +a descriptor amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor]) +that uses `+XMLSchemaReference+` method `+setSchemaContext+`, as this +example shows. + +[#Example 57-1]## *_Configuring Schema Context_* + +[source,java] +---- + public void addToDescriptor(ClassDescriptor descriptor) { + descriptor.getSchemaReference().setSchemaContext(xPath); + } +---- + +== Configuring for Complex Type of anyType + +This attribute applies only to Workbench. Use this option to solve "`No +schema context is specified`" problems (see +link:Using%20Workbench%20(ELUG)#How_to_Use_the_Problems_Window[How to +Use the Problems Window]) for an XML descriptor that does not represent +an element in your XML schema. + +In general, Workbench assumes that every XML descriptor must have a +schema context (see +link:#Configuring_Schema_Context_for_an_XML_Descriptor[Configuring +Schema Context for an XML Descriptor]). However, if a class in your +project does not relate to an element in your schema, then it does not +have a schema context. + +Consider the schema that this exmaple shows: + +[#Example 57-2]## *_Schema Using xsd:anyType_* + +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + +---- + +Because element `+contact-method+` is of type `+xsd:anyType+`, your +project requires a class to represent that type, such as class +`+AnyTypeImpl+` shown in the link:#Figure_57-3[Class Representing +xsd:anyType] figure. Because this class does not relate to any complex +type in your schema, it has no schema context. In this example, you +would select this option for the `+AnyTypeImpl+` class. + +[#Figure 57-3]## *_Class Representing xsd:anyType_* + +.Class Representing xsd:anyType +image::cmplxtp.gif[Class Representing +xsd:anyType,title="Class Representing xsd:anyType"] + +For more information, see +Introduction%20to%20XML%20Mappings%20(ELUG)#xs:any_and_xs:anyType_Support[xs:any +and xs:anyType Support]. + +=== How to Configure Complex Type of anyType Using Workbench + +To specify that the descriptor represents a complex type of `+anyType+`, +use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Complex Type "`anyType`" Option +_*image:drcmplxa.gif[Descriptor Info Tab, Complex Type "`anyType`" +Option,title="Descriptor Info Tab, Complex Type "anyType" Option"] +. Select the *Descriptor Represents Complex Type "`anyType`"* option to +specify this descriptor as the root element. + +== Configuring Default Root Element + +The default root element is the name that EclipseLink uses for the root +element when marshalling objects for this descriptor to, and +unmarshalling from, an XML document. Descriptors used only in composite +relationship mappings do not require a default root element. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Default_Root_Element[Default +Root Element]. + +=== How to Configure Default Root Element Using Workbench + +To specify a schema element as the default root element for the +descriptor, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Default Root Option_* +image:docroot.gif[Descriptor Info Tab, Default Root +Option,title="Descriptor Info Tab, Default Root Option"] +. Select the *Default Root Element* option to specify this descriptor as +the root element. +. Click *Browse* to select the schema element to identify as the root +element for this descriptor. See link:#Choosing_a_Root_Element[Choosing +a Root Element] for more information. + +See Also: + +link:#Configuring_Default_Root_Element[Configuring Default Root Element] + +==== Choosing a Root Element + +Use the Choose Root Element dialog box to select a specific root +element. + +*_Choose Root Element Dialog Box_* + +.Choose Root Element Dialog Box +image::rootelem.gif[Choose Root Element Dialog +Box,title="Choose Root Element Dialog Box"] + +Select the root element and click *OK*. + +== Configuring Document Preservation + +EclipseLink lets you preserve any "`extra`" data in your XML source that +is not required to map to an object model (such as comments, processing +instructions, or unmapped elements). + +This permits round-tripping from XML to objects and back to XML without +losing any data. + +=== How to Configure Document Preservation Using Workbench + +To preserve the entire XML source document, use this procedure: + +[arabic] +. Select a descriptor in the *Navigator*. Its properties appear in the +Editor. +. Click the *Descriptor Info* tab. The Descriptor Info tab appears. +*_Descriptor Info Tab, Preserve Document Option_* +image:preserve.gif[Descriptor Info Tab, Preserve Document +Option,title="Descriptor Info Tab, Preserve Document Option"] +. Select the *Preserve Document* option to maintain any extra +information from the source XML document that EclipseLink does not +require (such as comments). + +See Also: + +link:#Configuring_Document_Preservation[Configuring Document +Preservation] + +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor] + +=== How to Configure Document Preservation Using Java + +To configure an XML descriptor to maintain any extra information from +the source XML document that EclipseLink does not require (such as +comments) using Java, create a descriptor amendment method (see +link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a Descriptor]) +that configures the descriptor using `+XMLDescriptor+` method +`+setShouldPreserveDocument+`. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Direct_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Direct_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..f29f2a50908 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Direct_Mapping_(ELUG).adoc @@ -0,0 +1,56 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Direct_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML direct mapping. + +[#Table 60-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring a Simple Type Translator + +Configuring the Use of a Single Node + +Configuring the Use of CDATA + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Default Null Value at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Direct_Mapping[XML +Direct Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Collection_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Collection_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..ff39769131e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Collection_Mapping_(ELUG).adoc @@ -0,0 +1,51 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Fragment_Collection_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML fragment collection +mapping. + +[#Table 167-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Default Null Value at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Fragment_Collection_Mapping[XML +Fragment Collection Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..b5a108f6710 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Fragment_Mapping_(ELUG).adoc @@ -0,0 +1,50 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Fragment_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML fragment mapping. + +[#Table 166-1]## + +Option to Configure + +Workbench + +Java + +Configuring XPath + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Default Null Value at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mapping Comments + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a JAXB Typesafe Enumeration Converter + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Fragment_Mapping[XML +Fragment Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..81e7eb04464 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Mapping_(ELUG).adoc @@ -0,0 +1,581 @@ +*TOC* Special:Whatlinkshere_Configuring_an_XML_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the types of XML mappings that you can configure and +provides a cross-reference to the type-specific chapter that lists the +configurable options supported by that type. + +[#Table 59-1]## + +Mapping Type + +See… + +XML Direct Mapping + +Configuring an XML Direct Mapping + +XML Composite Direct Collection Mapping + +Configuring an XML Composite Direct Collection Mapping + +XML Composite Object Mapping + +Configuring an XML Composite Object Mapping + +XML Composite Collection Mapping + +Configuring an XML Composite Collection Mapping + +XML Any Object Mapping + +Configuring an XML Any Object Mapping + +XML Any Collection Mapping + +Configuring an XML Any Collection Mapping + +XML Transformation Mapping + +Configuring an XML Transformation Mapping + +XML Object Reference Mapping + +Configuring an XML Object Reference Mapping + +XML Collection Reference Mapping + +Configuring an XML Collection Reference Mapping + +XML Binary Data Mapping + +Configuring an XML Binary Data Mapping + +XML Binary Data Collection Mapping + +Configuring an XML Binary Data Collection Mapping + +XML Fragment Mapping + +Configuring an XML Fragment Mapping + +XML Fragment Collection Mapping + +Configuring an XML Fragment Collection Mapping + +XML Choice Object Mapping + +Configuring an XML Choice Object Mapping + +XML Choice Collection Mapping + +Configuring an XML Choice Collection Mapping + +XML Any Attribute Mapping + +Configuring an XML Any Attribute Mapping + +For more information, see the following: + +* link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] +* link:Introduction%20to%20XML%20Mappings%20(ELUG)[Introduction to XML +Mappings] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +== Configuring Common XML Mapping Options + +This table lists the configurable options shared by two or more XML +mapping types. In addition to the configurable options described here, +you must also configure the options described for the specific +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Mapping_Types[XML +Mapping Types], as shown in this table: + +[#Table 59-2]## + +Option + +EclipseLink Workbench + +Java + +Configuring XPath + +Configuring Reference Descriptor + +Configuring Container Policy + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring a Mapping + +Configuring Maps to Wildcard + +Configuring a Serialized Object Converter + +Configuring a Type Conversion Converter + +Configuring an Object Type Converter + +Configuring a Simple Type Translator + +Configuring the Use of a Single Node + +Configuring the Use of CDATA + +Configuring Reference Class + +Configuring the Use of Inline Binary Data + +Configuring the Use of SwaRef Type + +Configuring Source to Target Key Field Association + +Configuring the Choice Element + +== Configuring Reference Descriptor + +For XML attributes that reference other descriptors (instead of a schema +element), you may select a specific reference descriptor. If you do not +specify a reference descriptor, EclipseLink uses the `+xsi:Type+` +attribute to determine the reference class object. + +This table summarizes which XML mappings support reference descriptor +configuration. + +[#Table 59-3]## *_XML Mapping Support for Reference Descriptor +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure a Reference Descriptor Using Workbench + +To specify a reference descriptor for an XML mapping that references +another descriptor (instead of a schema element), use this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. Click the *General* tab. The General tab appears.*_General Tab, +Reference Descriptor Field_* image:xmlrefd.gif[General Tab, Reference +Descriptor Field,title="General Tab, Reference Descriptor Field"] +. If this XML attribute refers to another descriptor (instead of a +schema element), use the *Reference Descriptor* field to select a +descriptor in the project. + +== Configuring Maps to Wildcard + +This attribute applies only to the Workbench. Use this option to solve +"`No XPath specified`" problems (see +link:Using%20Workbench%20(ELUG)#How_to_Use_the_Problems_Window[How to +Use the Problems Window]) for an XML mapping that does not need an XPath +(see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_XPath[Configuring +XPath]) for it maps to a wildcard. + +If the XML mapping is owned by an `+anyType+` descriptor (see +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_for_Complex_Type_of_anyType[Configuring +for Complex Type of anyType]), it cannot map to a wildcard, and you must +specify an XPath. + +This table summarizes which XML mappings support maps to wildcard +configuration. + +[#Table 59-4]## *_XML Mapping Support for Maps to Wildcard +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure Maps to Wildcard Using Workbench + +To specify a map a schema element using the `+xs:any+` declaration, use +this procedure. + +[arabic] +. Select the mapped attribute in the *Navigator*. Its properties appear +in the Editor. +. *_Mapping Tab, Maps to Wildcard Option_* image:wildcard.gif[Mapping +Tab, Maps to Wildcard +Option,title="Mapping Tab, Maps to Wildcard Option"] +. If the XML mapping is not owned by an `+anyType+` descriptor (see +link:Configuring%20an%20XML%20Descriptor%20(ELUG)#Configuring_for_Complex_Type_of_anyType[Configuring +for Complex Type of anyType]) and maps to a wildcard, then you do not +need to specify an XPath (see +link:Configuring%20a%20Mapping%20(ELUG)#Configuring_XPath[Configuring +XPath]). Select the *Maps to Wildcard (uses "`any`" tag)* option to +clear the missing XPath neediness message. +. If the XML mapping is owned by an `+anyType+` descriptor, it cannot +map to a wildcard and you must specify an XPath. Deselect the *Maps to +Wildcard (Uses "`any`" tag)* option and ensure that you specify an +XPath. + +== Configuring Source to Target Key Field Association + +This option is applicable to key on source-based mappings. Use this +option to add a source and target XPath pair to the map of such key +pairs. + +This table summarizes which XML mappings support source to target key +field association configuration. + +[#Table 59-5]## *_XML Mapping Support for Source to Target Key Field +Association Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure Source to Target Key Field Association Using Java + +To configure the source to target key field association for your +mapping, use the `+XMLObjectReferenceMapping+` method +`+addSourceToTargetKeyFieldAssociation+` to add a specified source and +target XPath pair to the map. + +== Configuring Reference Class + +This option is applicable to key on source-based mappings. + +Use this option to define the reference class, whose instances your XML +object reference mapping will store in the domain objects. + +This table summarizes which XML mappings support source to target key +field association configuration. + +[#Table 59-6]## *_XML Mapping Support for Reference Class +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure Reference Class Using Java + +To configure a reference class for your mapping, use the +`+AggregateMapping+` method `+setReferenceClass+`. + +== Configuring the Use of Inline Binary Data + +This option is applicable to binary data mappings. + +Use this option to define whether or not there should always be inline +binary data for this mapping. + +This table summarizes which XML mappings support the use of inline +binary data configuration. + +[#Table 59-7]## *_XML Mapping Support for the Use of Inline Binary Data +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure the Use of Inline Binary Data Using Java + +To configure the use of inline binary data for your mapping, use the +`+XMLBinaryDataMapping+` or `+XMLBinaryDataCollectionMapping+` method +`+setShouldInlineBinaryData+`. If you set it to `+true+`, you disable +consideration for attachment handling for this mapping and indicate that +you only want inline data. + +== Configuring the Use of SwaRef Type + +This option is applicable to binary data mappings. + +Use this option to specify that the target node of this mapping is of +type xs:swaref. + +This table summarizes which XML mappings support the use of SwaRef type +configuration. + +[#Table 59-8]## *_XML Mapping Support for the Use of SwaRef Type +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure the Use of SwaRef Type Using Java + +To configure the use of SwaRef type for your mapping, use the +`+XMLBinaryDataMapping+` or `+XMLBinaryDataCollectionMapping+` method +`+setSwaRef+`. If you set it to `+true+`, you indicate that the target +node of this mapping is of type `+xs:swaref+`. + +== Configuring the Choice Element + +This option is applicable to choice mappings. + +Use this option to specify an XPath and the type assocated with this +XPath. + +This table summarizes which XML mappings support the choice element +configuration. + +[#Table 59-9]## *_XML Mapping Support for the Choice Element +Configuration_* + +XML Mapping + +Using the Workbench + +Using Java + +XML direct mapping + +XML composite direct collection mapping + +XML composite object mapping + +XML composite collection mapping + +XML any object mapping + +XML any collection mapping + +XML transformation mapping + +XML object reference mapping + +XML object collection mapping + +XML binary data mapping + +XML binary data collection mapping + +XML fragment mapping + +XML fragment collection mapping + +XML choice object mapping + +XML choice collection mapping + +XML any attribute mapping + +=== How to Configure the Choice Element Using Java + +Use the following `+XMLChoiceObjectMapping+` or +`+XMLChoiceCollectionMapping+` methods to add choice element: + +* `+addChoiceElement(String xpath, Class elementType)+` +* `+addChoiceElement(String xpath, String elementTypeName)+` + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Object_Reference_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Object_Reference_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..3914a1bf602 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Object_Reference_Mapping_(ELUG).adoc @@ -0,0 +1,43 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Object_Reference_Mapping_%28ELUG%29[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for an XML object reference +mapping. + +[#Table 162-1]## + +Option to Configure + +Workbench + +Java + +Source to target key field association + +Reference class + +Method or direct field access + +Read-only + +Comments + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Object_Reference_Mapping[XML +Object Reference Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Project_(ELUG).adoc new file mode 100644 index 00000000000..252d1858f3b --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Project_(ELUG).adoc @@ -0,0 +1,67 @@ +*TOC* Special:Whatlinkshere_Configuring_an_XML_Project_(ELUG)[Related +Topics] + +For information on how to create XML projects, see +link:Creating%20an%20XML%20Project%20(ELUG)[Creating an XML Project]. + +This table lists the configurable options for XML projects. + +[#Table 54-1]## + +[width="100%",cols="<61%,<19%,<20%",options="header",] +|=== +|*Option to Configure* |*EclipseLink Workbench* |*Java* +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Save_Location[Project +save location] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Project +classpath] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Comments[Project +comments] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Method_or_Direct_Field_Access_at_the_Project_Level[Method +or direct field access] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Deployment_XML_Options[Project +deployment XML options] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)#Configuring_XML_Parser_Platform[XML +parser platform] |image:unsupport.gif[Unsupported,title="Unsupported"] +|image:support.gif[Supported,title="Supported"] + +|link:Using%20Workbench%20(ELUG)#How_to_Import_an_XML_Schema[Importing +an XML schema] |image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported.,title="Unsupported."] + +|link:Using%20Workbench%20(ELUG)#How_to_Configure_XML_Schema_Namespace[XML +schema namespace] |image:support.gif[Supported,title="Supported"] +|image:support.gif[Supported,title="Supported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Model_Java_Source_Code_Options[Model +Java source code options] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] + +|link:Configuring%20a%20Project%20(ELUG)#Configuring_Default_Descriptor_Advanced_Properties[Default +descriptor advanced properties] +|image:support.gif[Supported,title="Supported"] +|image:unsupport.gif[Unsupported,title="Unsupported"] +|=== + +For more information, see +link:Introduction%20to%20XML%20Projects%20(ELUG)[Introduction to XML +Projects]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Transformation_Mapping_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Transformation_Mapping_(ELUG).adoc new file mode 100644 index 00000000000..8b810158bb3 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Configuring_an_XML_Transformation_Mapping_(ELUG).adoc @@ -0,0 +1,47 @@ +*TOC* +Special:Whatlinkshere_Configuring_an_XML_Transformation_Mapping_(ELUG)[Related +Topics] + +For information on how to create EclipseLink mappings, see +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +This table lists the configurable options for a XML transformation +mapping. + +[#Table 66-1]## + +Option to Configure + +Workbench + +Java + +Configuring Attribute Transformer + +Configuring Field Transformer Associations + +Configuring Method or Direct Field Accessing at the Mapping Level + +Configuring Read-Only Mappings + +Configuring Mutable Mappings + +Configuring Mapping Comments + +Configuring Indirection (Lazy Loading) + +For more information, see the following: + +* link:Introduction%20to%20XML%20Mappings%20(ELUG)[XML Transformation +Mapping] +* link:Configuring%20an%20XML%20Mapping%20(ELUG)[Configuring an XML +Mapping] +* link:Configuring%20a%20Mapping%20(ELUG)[Configuring a Mapping] + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Descriptor_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Descriptor_(ELUG).adoc new file mode 100644 index 00000000000..6db3ffb4aac --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Descriptor_(ELUG).adoc @@ -0,0 +1,77 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Creating_an_XML_Descriptor_(ELUG)[Related +Topics] + +This section explains how to create descriptor options specific to an +XML descriptor. + +For information on how to create more than one type of descriptor, see +link:Creating%20a%20Descriptor%20(ELUG)[Creating a Descriptor]. + +After you create a descriptor, you must configure its various options +(see link:Configuring%20a%20Descriptor%20(ELUG)[Configuring a +Descriptor]) and use it to define mappings. + +For complete information on the various types of mapping that +EclipseLink supports, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings] and +link:Creating%20a%20Mapping%20(ELUG)[Creating a Mapping]. + +For complete information on the various types of descriptor that +EclipseLink supports, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptor_Types[Descriptor +Types]. + +For more information, see the following: + +* link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors] +* link:Introduction%20to%20XML%20Descriptors%20(ELUG)[Introduction to +XML Descriptors] + +== Creating an XML Descriptor + +You can create an XML descriptor using the +link:#How_to_Create_an_XML_Descriptor_Using_Workbench[Workbench] or +link:#How_to_Create_an_XML_Descriptor_Using_Java[Java code]. We +recommend that you use the Workbench to create and manage your XML +descriptors. + +=== How to Create an XML Descriptor Using Workbench + +image:xmldesin.gif[XML descriptor icon,title="XML descriptor icon"] When +you add a class to an XML project (see +link:Configuring%20a%20Project%20(ELUG)#Configuring_Project_Classpath[Configuring +Project Classpath]), Workbench creates an XML descriptor for the class. + +An XML descriptor is always a composite type. + +=== How to Create an XML Descriptor Using Java + +This example shows how to create an XML descriptor using Java code. + +[#Example 56-1]## *_Creating an XML Descriptor in Java_* + +`+XMLDescriptor descriptor = new XMLDescriptor();+` +`+descriptor.setJavaClass(YourClass.class);+` + +[width="100%",cols="<100%",] +|=== +|*Note:* Use the `+org.eclipse.persistence.ox.XMLDescriptor+` class. Do +not use the deprecated +`+org.eclipse.persistence.internal.xml\'\'.\'\'XMLDescriptor+` class. +|=== + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Task[Category: Task] +Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Project_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Project_(ELUG).adoc new file mode 100644 index 00000000000..b372716708e --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Creating_an_XML_Project_(ELUG).adoc @@ -0,0 +1,640 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Creating_an_XML_Project_(ELUG)[Related +Topics] + +This section describes the various components that you must configure in +order to create an XML project. + +For information on how to create more than one type of EclipseLink +projects, see link:Creating%20a%20Project%20(ELUG)[Creating a Project]. + +== Introduction to XML Project Creation + +You can create a project using the Workbench or Java code. + +We recommend using the Workbench to create projects and generate +deployment XML or Java source versions of the project for use at run +time. For more information on how to create a project using Workbench, +see +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[How +to Create a Project Using the Workbench]. For information on how to +create a project using Java, see +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_Java[How +to Create a Project Using Java]. + +You can use EclipseLink to create an XML project, if you have an XML +schema (XSD) document, but no object model yet (see +link:#Creating_an_XML_Project_from_an_XML_Schema[Creating an XML Project +from an XML Schema]). If you have both XSD and object model classes, you +can create an XML project using the procedure described in +link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[How +to Create a Project Using the Workbench] + +For more information, see +link:Introduction%20to%20XML%20Projects%20(ELUG)[Introduction to XML +Projects]. + +== Creating an XML Project from an XML Schema + +EclipseLink 1.x supports JAXB 2.0 and uses the JAXB 2.0 schema compiler. +You can use this JAXB compiler to generate POJO (Plain Old Java Objects) +annotated with JAXB 2.0 mapping metadata. You can define and edit this +JAXB metadata by embedding these annotations in your source code – not +the Eclipse Workbench. + +To use the Eclipse Workbench to define XPath based mappings: + +[arabic] +. link:Creating%20a%20Project%20(ELUG)#How_to_Create_a_Project_Using_the_Workbench[Create +an XML project]. +. link:Using_Workbench_(ELUG)#How_to_Import_an_XML_Schema[Import your +schema] and +link:Using_Workbench_(ELUG)#How_to_Import_and_Update_Classes[classes] +into the project. +. link:Configuring_an_XML_Mapping_%28ELUG%29[Define the mappings] +between your classes and schema. + +The EclipseLink JAXB compiler generates +link:Introduction%20to%20XML%20Projects%20(ELUG)#Working_with_JAXB-Specific_Generated_Files[JAXB-specific +files] and +link:Introduction%20to%20XML%20Projects%20(ELUG)#Working_with_EclipseLink-Specific_Generated_Files[EclipseLink-specific +files]. + +Optionally, open the generated +link:Introduction%20to%20XML%20Projects%20(ELUG)#Workbench_Project[workbench +project]), customize the generated mappings and descriptors, and +reexport the EclipseLink project XML. + +[width="100%",cols="<100%",] +|=== +|*Note:* Before you compile your generated classes, be sure to configure +your IDE classpath to include +`+<+`_`+ECLIPSELINK_HOME+`_`+>\jlib\moxy\javax.xml.bind_2.0.0.jar+`. For +example, see +link:Using%20an%20Integrated%20Development%20Environment%20(ELUG)[Using +an Integrated Development Environment]. +|=== + +=== How to Create an XML Project from an XML Schema Using the Command Line + +To create a new, mapped Workbench project from an XML schema using JAXB +from the command line, use the `+jaxb-compiler.cmd+` or +`+jaxb-compiler.sh+` file (located in the __`+/bin+` directory) as +follows: + +[arabic] +. Using a text editor, edit the `+jaxb-compiler.cmd+` or +`+jaxb-compiler.sh+` file to set proxy settings (if required). If you +are using a schema that imports another schema by URL and you are +operating behind a proxy, then you must uncomment the lines shown in the +link:#Example_53-1[Proxy Settings in jaxb-compiler.cmd] or +link:#Example_53-2[Proxy Settings in jaxb-compiler.sh] examples and edit +them to set your proxy host (name or IP address) and port: ++ +[#Example 53-1]## *_Proxy Settings in jaxb-compiler.cmd_* ++ +@REM set JVM_ARGS=%JVM_ARGS% -DproxySet=true -Dhttp.proxyHost= +-Dhttp.proxyPort= ++ +[#Example 53-2]## *_Proxy Settings in jaxb-compiler.sh_* ++ +JVM_ARGS="`$\{JVM_ARGS} -DproxySet=true -Dhttp.proxyHost= +-Dhttp.proxyPort=`" +. Execute the `+jaxb-compiler.cmd+` or `+jaxb-compiler.sh+` file +(located in the __`+/bin+` directory). The EclipseLink JAXB compiler +generates JAXB-specific files (see +link:Introduction%20to%20XML%20Projects%20(ELUG)[Working with +JAXB-Specific Generated Files]) and EclipseLink-specific files (see +link:Introduction%20to%20XML%20Projects%20(ELUG)[Working with +EclipseLink-Specific Generated Files]). The +link:#Example_53-3[Generating an Object Model from a Schema with +jaxb-compiler.cmd] example illustrates how to generate an object model +from a schema using the EclipseLink JAXB compiler. The +link:#Table_53-1[EclipseLink JAXB Binding Compiler Arguments] table +lists the compiler arguments. ++ +[#Example 53-3]## *_Generating an Object Model from a Schema with +jaxb-compiler.cmd_* ++ +jaxb-compiler.cmd [-options…] schemafile [-b bindingfile] ++ +[#Table 53-1]## *_EclipseLink JAXB Binding Compiler Arguments_* ++ ++ ++ ++ ++ ++ +Argument ++ ++ ++ ++ ++ +Description ++ ++ ++ ++ ++ +Optional? ++ ++ ++ ++ ++ ++ ++ ++ ++ +-help ++ ++ ++ ++ ++ +Prints the help and usage information. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-version ++ ++ ++ ++ ++ +Prints the release version of the EclipseLink JAXB compiler. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-verbose ++ ++ ++ ++ ++ +The interfaces and classes generated. This argument is optional. ++ ++ ++ +Default: not verbose. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-customize ++ ++ ++ ++ ++ +The fully qualified path and file name of a standard JAXB customization +file that you can use to override default JAXB compiler behavior. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-nv ++ ++ ++ ++ ++ +Do not preform strict validation of the input schemas. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-extension ++ ++ ++ ++ ++ +Allow vendor extensions. The compiler will not strictly follow the +Compatibility Rules and Appendix E.2 or the JAXB specification. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-b ++ ++ ++ ++ ++ +Specify external bindings files (or directories). -b file1 -b file2 -b +file3 ++ ++ ++ +If you include a directory, the compiler will search **/*.xjb. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-d ++ ++ ++ ++ ++ +The directory for the generated files. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-p ++ ++ ++ ++ ++ +The target package. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-httpproxy ++ ++ ++ ++ ++ +Set an HTTP/HTTPS proxy. ++ ++ ++ +-httpproxy [user[:password]@]proxyHost:proxy:Port ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-httpproxyfile ++ ++ ++ ++ ++ +Similar to -httpproxy, except that it takes a file (to protect the +password). ++ ++ ++ +-httpproxyfile file ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-classpath ++ ++ ++ ++ ++ +Specify the location of your class files ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-catalog ++ ++ ++ ++ ++ +Specify the catalog files to resolve external entity references. The +JAXB compiler supports TR9401, XCatalog, and OASIS XML catalog formats. ++ ++ ++ +-catalog filename ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-customize ++ ++ ++ ++ ++ +The fully qualified path and file name of a standard JAXB customization +file that you can use to override default JAXB compiler behavior. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-readonly ++ ++ ++ ++ ++ +The generated files will be in read-only mode. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-npa ++ ++ ++ ++ ++ +The package-level annotations '`will not`' be generated +(**/package-info.java). ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-no-header ++ ++ ++ ++ ++ +The file header with timestamp will not be generated. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-xmlschmea ++ ++ ++ ++ ++ +The input schema will be treated as W3C schema (default). ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-relaxng ++ ++ ++ ++ ++ +The input schema will be treated as RELAX NG ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-relaxng-compact ++ ++ ++ ++ ++ +The input schmea will be treated as RELAX NG (compact syntax). ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-wsdl ++ ++ ++ ++ ++ +The input schmea will be treated as WSDL and compile shemas inside of +it. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ ++ ++ +-dtd ++ ++ ++ ++ ++ +The input schmea will be trated as XML DTD. ++ ++ ++ ++ ++ +Yes ++ ++ ++ ++ ++ +. Optionally, open the generated +link:Introduction%20to%20XML%20Projects%20(ELUG)#Workbench_Project[Workbench +project] in Workbench, customize the generated mappings and descriptors, +and reexport the EclipseLink project XML. | | +|:—————————————————————————————————————————————————————————————————————————————————————————————————————-| +| *Note:* Before you compile your generated classes, be sure to +configure your IDE classpath to include +`+<+`_`+ECLIPSELINK_HOME+`_`+>\jlib\moxy\javax.xml.bind_2.0.0.jar+`. For +example, see +link:Using%20an%20Integrated%20Development%20Environment%20(ELUG)[Using +an Integrated Development Environment]. | + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1.1[Category: Release 1.1] Category:_Task[Category: +Task] Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/EclipseLink_UserGuide_Developing_XML_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/EclipseLink_UserGuide_Developing_XML_Projects_(ELUG).adoc new file mode 100644 index 00000000000..1e858344469 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/EclipseLink_UserGuide_Developing_XML_Projects_(ELUG).adoc @@ -0,0 +1,25 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +== XML Projects + +The following sections describe XML projects, descriptors and mappings: + +* link:XML_Projects_(ELUG)[Creating and Configuring XML Projects] + +* link:XML_Descriptors_(ELUG)[Creating and Configuring XML Descriptors] + +* link:XML_Mappings_(ELUG)[Creating and Configuring XML Mappings] + +*Special:Whatlinkshere_EclipseLink_UserGuide_Developing_XML_Projects_(ELUG)[Related +Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..e1fd88dc9a1 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Descriptors_(ELUG).adoc @@ -0,0 +1,70 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* +Special:Whatlinkshere_Introduction_to_XML_Descriptors_(ELUG)[Related +Topics] + +This section introduces options specific to an XML descriptor. + +For information on descriptor concepts and features common to more than +one type of EclipseLink descriptors, see +link:Introduction%20to%20Descriptors%20(ELUG)[Introduction to +Descriptors]. + +== XML Descriptor Concepts + +XML descriptors describe Java objects that you map to simple and complex +types defined by an XML schema document (XSD). + +Using XML descriptors in an XML project, you can configure XML mappings +(see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Mapping_Types[XML +Mapping Types]), in memory, to XML elements defined by an XSD. + +For more information, see the following: + +* link:Creating%20an%20XML%20Descriptor%20(ELUG)[Creating an XML +Descriptor] +* link:Configuring%20an%20XML%20Descriptor%20(ELUG)[Configuring an XML +Descriptor] + +=== XML Descriptors and Aggregation + +When working with descriptors for a parent (source) and a child (target) +objects, you have to accomplish the following: + +* if the source object exists, then you must ensure that the target +object also exists; +* if the source object is destroyed, then you must ensure that the +target object is also destroyed. + +For more information, see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Aggregation[Descriptors +and Aggregation]. + +In your XML project, designate the descriptors for the source and target +objects to reflect this relationship as +link:#Composite_Descriptors_in_XML_Projects[Composite Descriptors in XML +Projects]. + +==== Composite Descriptors in XML Projects + +In an XML project, descriptors are always composites. + +Because XML descriptors are always composites, you can configure +inheritance for an XML descriptor without considering its type (see +link:Introduction%20to%20Descriptors%20(ELUG)#Descriptors_and_Inheritance[Descriptors +and Inheritance]). + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..92eeb200005 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Mappings_(ELUG).adoc @@ -0,0 +1,2099 @@ +*TOC* Special:Whatlinkshere_Introduction_to_XML_Mappings_(ELUG)[Related +Topics] + +An XML mapping transforms object data members to the XML nodes of an XML +document whose structure is defined by an XML schema document (XSD). + +For information on mapping concepts and features common to more than one +type of EclipseLink mappings, see +link:Introduction%20to%20Mappings%20(ELUG)[Introduction to Mappings]. + +== XML Mapping Types + +EclipseLink supports the XML mappings listed in this table + +[#Table 58-1]## + +Mapping Type + +Description + +EclipseLink Workbench + +Java + +XML direct mapping + +Map a simple object attribute to an XML attribute or text node. + +XML composite direct collection mapping + +Map a collection of simple object attributes to XML attributes or text +nodes. + +XML composite object mapping + +Map any attribute that contains a single object to an XML element. The +EclipseLink runtime uses the descriptor for the referenced object to +populate the contents of that element. + +XML composite collection mapping + +Map an attribute that contains a homogenous collection of objects to +multiple XML elements. The EclipseLink runtime uses the descriptor for +the referenced object to populate the contents of those elements. + +XML any object mapping + +The any object XML mapping is similar to the composite object XML +mapping (see XML Composite Object Mapping), except that the reference +object may be of different types (including String), not necessarily +related to each other through inheritance or a common interface. + +XML any collection mapping + +The any collection XML mapping is similar to the composite collection +XML mapping (see XML Composite Collection Mapping) except that the +referenced objects may be of different types (including String), not +necessarily related to each other through inheritance or a common +interface. + +XML transformation mapping + +Create custom mappings where one or more XML nodes can be used to create +the object to be stored in a Java class’s attribute. + +XML object reference mapping + +Map a given element in an XML document to another element in that same +XML document using key(s). Use this mapping when several objects +reference the same instance of another object. + +XML collection reference mapping + +This mapping is similar to the XML object reference mapping (see XML +Object Reference mapping), except that it deals with collections instead +of single objects. Use this mapping when several objects reference the +same instance of another object. + +XML binary data mapping + +Handle binary data: this mapping maps binary data in the object model to +XML. Use this mapping to enable writing of binary data directly as +inline binary data (base64 BLOB), or passing through as a MtOM or SwaRef +attachment. + +XML binary data collection mapping + +This mapping is similar to the XML binary data mapping (see XML Binary +Data mapping), except that it maps a collection of binary data in the +object model to XML. + +XML fragment mapping + +Keep a part of an XML tree as a node. + +XML fragment collection mapping + +This mapping is similar to the XML fragment mapping (see XML Fragment +mapping), except that it allows you to keep a part of an XML tree as a +collection of nodes. + +XML choice object mapping + +Map a single attribute to a number of different elements in an XML +document. Use this mapping to map to single choices or substitution +groups in an XML schema. + +XML choice collection mapping + +This mapping is similar to the XML choice object mapping (see XML Choice +Object mapping), except that you use it to handle reading and writing of +XML documents containing a collection of choice or substitution group +elements. + +XML any attribute mapping + +Map to an attribute in an object to any XML attributes contained on a +specific element in the XML document. + +== XML Mapping Concepts + +You can map the attributes of a Java object to a combination of XML +simple and complex types using a wide variety of XML mapping types. + +EclipseLink stores XML mappings for each class in the class descriptor. +EclipseLink uses the descriptor to instantiate objects mapped from an +XML document and to store new or modified objects as an XML document. + +To configure XML mappings, we recommend that you use the Workbench to +set the descriptor properties and configure the mappings. + +This section describes concepts unique to EclipseLink XML mappings, +including the following: + +* link:#Mapping_to_Simple_and_Complex_Types[Mapping to Simple and +Complex Types] +* link:#Mapping_Order[Mapping Order] +* link:#XPath_Support[Path Support] +* #xsd:list_and_xsd:union_Support[xsd:list and xsd:union Support] +* #xs:any_and_xs:anyType_Support[xs:any and xs:anyType Support] +* #jaxb:class_Support[jaxb:class Support] +* link:#Typesafe_Enumeration_Support[Typesafe Enumeration Support] +* link:#Mapping_Extensions[Mapping Extensions] +* link:#Substitution_Groups[Substitution Groups] +* link:#Mixed_Content_Mapping[Mixed Content Mapping] +* link:#Key_On_Source-Based_Mapping_Support[Key On Source-Based Mapping +Support] +* link:#XML_Adapter[XML Adapter] + +=== Mapping to Simple and Complex Types + +Consider the XML document shown in this example: + +[#Example 58-1]## *_XML Document_* + +`+    +``+Jane Doe+` `+    +` + +`+        +``+123 Any St.+` `+        +``+MyCity+` `+    +` + +In general, using EclipseLink XML mappings, you can map a Java class to +a simple type (such as `+NAME+`) or to a complex type (such as +`+ADDRESS+`). + +Specifically, you can map a Java object’s simple attributes to XML +attributes (such as `+ID+`) and text nodes (such as `+NAME+`). You can +also map a Java object’s relationships to XML elements (such as +`+ADDRESS+`). + +This table summarizes the XML simple and complex types supported by each +EclipseLink XML mapping. + +[#Table 58-2]## *_XML Mapping Support for XML Simple and Complex Types_* + +Mapping + +XML Attribute + +XML Text Node + +XML Element + +XML direct + +XML composite direct collection + +XML composite object + +XML composite collection + +XML any object + +XML any collection + +XML transformation + +XML object reference + +XML collection reference + +XML binary data + +XML binary data collection + +XML fragment collection + +XML fragment collection + +XML choice collection + +XML choice collection + +XML any attribute + +=== Mapping Order + +Unlike relational database mappings, the order in which mappings are +persisted in XML is significant. + +The order in which you define XML mappings in EclipseLink (whether in +the Workbench or in Java code) including the order in which you define +mapping components such as `+Transformers+` (see +link:#XML_Transformation_Mapping[XML Transformation Mapping]) is +reflected in the order, in which EclipseLink persists data in an XML +document. + +=== XPath Support + +EclipseLink uses XPath statements to efficiently map the attributes of a +Java object to locations in an XML document. + +The following are main characteristics of XPath: + +* Each XPath statement is relative to the context node specified in the +descriptor. +* The XPath may contain node type, path, and positional information. +* The XPath is specified on a mapping using the setXPath method. + +For more information about using XPath with XML mappings, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_XPath[Mappings +and XPath]. + +=== xsd:list and xsd:union Support + +You can use XML direct (see link:#XML_Direct_Mapping[XML Direct +Mapping]) and composite direct collection (see +link:#XML_Composite_Direct_Collection_Mapping[XML Composite Direct +Collection Mapping]) mappings, as well as their subclasses, to map to +`+xsd:list+` and `+xsd:union+` types in an XML document. + +For more information, see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_xsd:list_and_xsd:union_Types[Mappings +and xsd:list and xsd:union Types]. + +=== xs:any and xs:anyType Support + +In an XML schema, you can define elements and complex types that +correspond to any data type using `+xs:any+` and `+xs:anyType+`. You can +map objects to such elements and complex types using XML mappings +`+XMLAnyObjectMapping+` and `+XMLAnyCollectionMapping+`. + +This table lists the XML mappings to use with common applications of +`+xs:any+` and `+xs:anyType+`. For more details, see the specified XML +mapping type. + +[#Table 58-3]## *_XML Mappings and XML Schema xs:any and xs:anyType_* + +Use XML Mapping… + +To Map XML Schema Definition… + +XML Any Object Mapping + +Element with a single 1 unnamed complex type specified as xs:any. + +XML Any Collection Mapping + +Element with an unnamed sequence 2 of complex types specified as xs:any. + +Element with a named sequence 2 of complex types of type xs:anyType.Root +element of type xs:anyType. + +1`+minOccurs+` and `+maxOccurs+` are both equal to 1. 2`+maxOccurs+` is +greater than 1. + +=== jaxb:class Support + +You can configure an XML composite object mapping (see +link:#XML_Composite_Object_Mapping[XML Composite Object Mapping]) and +its subclasses to accommodate `+jaxb:class+` customizations with the +following XSD structures: + +* `+all+` +* `+sequence+` +* `+choice+` +* `+group+` + +For more information, see +Introduction%20to%20Mappings%20(ELUG)#Mappings_and_the_jaxb:class_Customization[Mappings +and the jaxb:class Customization]. + +=== Typesafe Enumeration Support + +You can map a Java attribute to such a typesafe enumeration using the +`+JAXBTypesafeEnumConverter+` with an `+XMLDirectMapping+`, +`+XMLCompositeDirectCollectionMapping+` or their subclasses with XML +documents. + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Mappings_and_JAXB_Typesafe_Enumerations[Mappings +and JAXB Typesafe Enumerations] + +=== Mapping Extensions + +If existing EclipseLink XML mappings do not meet your needs, you can +create custom XML mappings using XML mapping extensions, including +object type, serialized object, type conversion converters, and a simple +type translator. For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Mapping_Converters_and_Transformers[Mapping +Converters and Transformers]. + +=== Key On Source-Based Mapping Support + +EclipseLink XML support for key on source-based mapping lets you use +one-to-one and one-to-many mappings to map a given element in an XML +document to another element in that same XML document using key(s). + +You use this mapping when several objects reference the same instance of +another object. + +Use the +link:#XML_Object_Reference_Mapping[`+org.eclipselink.persistence.ox.mappings.XMLObjectReferenceMapping+`] +and +link:#XML_Collection_Reference_Mapping[`+XMLCollectionReferenceMapping+`] +for the key on source. + +You configure this mappings using the deployment XML and a project +class. + +=== Substitution Groups + +Substitution groups is a mechanism provided by the XML schema. Using +substitution groups, you can substitute elements for other elements. For +more information, see _XML Schema Primer_ at +http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#SubsGroups. + +Use EclipseLink +link:#XML_Choice_Object_Mapping[`+XMLChoiceObjectMapping+`] and +link:#XML_Choice_Collection_Mapping[`+XMLChoiceCollectionMapping+`] to +handle substitution groups. + +JAXB handles substitution groups with the following annotations, for +which EclipseLink provides support: + +* `+XmlElementRef+` - the use of this annotation has a number of +constrains. For more information, see _JAXB 2.0 API Reference_ at +https://jaxb.dev.java.net/nonav/jaxb20-pfd/api/index.html +* `+XmlElementRefs+` - this annotation contains one of more +`+XmlElementRef+` annotations. + +Through the use of the +`+org.eclipse.persistence.oxm.mappings.converters.XMLRootConverter+`, +EclipseLink enables the +link:Introduction%20to%20XML%20Projects%20(ELUG)#How_to_Use_JAXBElement[`+JAXBElement+`] +and the `+org.eclipse.persistence.oxm.XMLRoot+` to act not only like +root-level elements, but child elements. + +=== Mixed Content Mapping + +To handle mixed content, such as reading in text nodes as strings, use +EclipseLink +link:#XML_Any_Collection_Mapping[`+XMLAnyCollectionMapping+`]. Enable +this functionality through the `+setMixedContent+` method. + +=== XML Adapter + +EclipseLink supports the use of the +`+javax.xml.bind.annotation.adapters.XmlAdapter+` +and its subclasses, which allow for arbitrary Java classes to be used +with JAXB. + +The `+XmlAdapter+` enables adaptation of a Java type for custom +marshaling through its `+marshal+` and `+unmarshal+` methods. + +For more information, refer to JAXB 2.0 Specification at +https://jaxb.dev.java.net/nonav/jaxb20-pfd/api/index.html + +== XML Direct Mapping + +XML direct mappings map a Java attribute directly to XML text nodes. You +can use an XML direct mapping in the following scenarios: + +* link:#Mapping_to_a_Text_Node[Mapping to a Text Node] +* link:#Mapping_to_an_Attribute[Mapping to an Attribute] +* link:#Mapping_to_a_Specified_Schema_Type[Mapping to a Specified Schema +Type] +* link:#Mapping_to_a_List_Field_with_an_XML_Direct_Mapping[Mapping to a +List Field with an XML Direct Mapping] +* link:#Mapping_to_a_Union_Field_with_an_XML_Direct_Mapping[Mapping to a +Union Field with an XML Direct Mapping] +* link:#Mapping_to_a_Union_of_Lists_with_an_XML_Direct_Mapping[Mapping +to a Union of Lists with an XML Direct Mapping] +* link:#Mapping_to_a_Union_of_Unions_with_an_XML_Direct_Mapping[Mapping +to a Union of Unions with an XML Direct Mapping] +* link:#Mapping_with_a_Simple_Type_Translator[Mapping with a Simple Type +Translator] + +See link:Configuring%20an%20XML%20Direct%20Mapping%20(ELUG)[Configuring +an XML Direct Mapping] for more information. + +[width="100%",cols="<100%",] +|=== +|*Note:* Do not confuse an XML direct mapping with a relational +direct-to-`+XMLType+` mapping (see +link:Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType_Mapping[Direct-to-XMLType +Mapping]). +|=== + +=== Mapping to a Text Node + +This section describes using an XML direct mapping when doing the +following: + +* link:#Mapping_to_a_Simple_Text_Node[Mapping to a Simple Text Node] +* link:#Mapping_to_a_Text_Node_in_a_Simple_Sequence[Mapping to a Text +Node in a Simple Sequence] +* link:#Mapping_to_a_Text_Node_in_a_Subelement[Mapping to a Text Node in +a Subelement] +* link:#Mapping_to_a_Text_Node_by_Position[Mapping to a Text Node by +Position] + +==== Mapping to a Simple Text Node + +Given the XML schema in the link:#Example_58-2[Schema for XML Direct +Mapping to Simple Text Node] example, the link:#Figure_58-1[XML Direct +Mapping to Simple Text Node] figure illustrates an XML direct mapping to +a simple text node in a corresponding XML document. The +link:#Example_58-3[Java for XML Direct Mapping to Simple Text Node] +example shows how to configure this mapping in Java. + +[#Example 58-2]## *_Schema for XML Direct Mapping to Simple Text Node_* + +`+    +` + +[#Figure 58-1]## *_XML Direct Mapping to Simple Text Node_* + +.XML Direct Mapping to Simple Text Node +image::dxmstn.gif[XML Direct Mapping to Simple Text +Node,title="XML Direct Mapping to Simple Text Node"] + +[#Example 58-3]## *_Java for XML Direct Mapping to Simple Text Node_* + +`+XMLDirectMapping numberMapping = new XMLDirectMapping();+` +`+numberMapping.setAttributeName("number");+` +`+numberMapping.setXPath("text()");+` + +==== Mapping to a Text Node in a Simple Sequence + +Given the XML schema in the link:#Example_58-4[Schema for XML Direct +Mapping to a Text Node in a Simple Sequence] example, the +link:#Figure_58-2[XML Direct Mapping to a Text Node in a Simple +Sequence] figure illustrates an XML direct mapping to individual text +nodes in a sequence in a corresponding XML document. The +link:#Example_58-5[Java for XML Direct Mapping to a Text Node in a +Simple Sequence] example shows how to configure this mapping in Java. + +[#''Example 58-4]## *Schema for XML Direct Mapping to a Text Node in a +Simple Sequence*’’ + +`+    +` `+    +` `+        +` `+            +` `+            +` +`+        +` + +`+    +` + +[#Figure 58-2]## *_XML Direct Mapping to a Text Node in a Simple +Sequence_* + +.XML Direct Mapping to a Text Node in a Simple Sequence +image::dxmss.gif[XML Direct Mapping to a Text Node in a Simple +Sequence,title="XML Direct Mapping to a Text Node in a Simple Sequence"] + +[#Example 58-5]## *_Java for XML Direct Mapping to a Text Node in a +Simple Sequence_* + +`+XMLDirectMapping firstNameMapping = new XMLDirectMapping();+` +`+firstNameMapping.setAttributeName("firstName");+` +`+firstNameMapping.setXPath("first-name/text()");+` + +`+XMLDirectMapping lastNameMapping = new XMLDirectMapping();+` +`+lastNameMapping.setAttributeName("lastName");+` +`+lastNameMapping.setXPath("last-name/text()");+` + +==== Mapping to a Text Node in a Subelement + +Given the XML schema in the link:#Example_58-6[Schema for XML Direct +Mapping to a Text Node in a Subelement] example, the +link:#Figure_58-3[XML Direct Mapping to a Text Node in a Subelement] +figure illustrates an XML direct mapping to a text node in a subelement +in a corresponding XML document. The link:#Example_58-7[Java for XML +Direct Mapping to a Text Node in a Subelemen] example shows how to +configure this mapping in Java. + +[#Example 58-6]## *_Schema for XML Direct Mapping to a Text Node in a +Subelement_* + +`+    +` `+    +` `+        +` + +`+            +` `+                +` `+                    +` +`+                        +` `+                        +` +`+                    +` + +`+                +` `+            +` `+        +` `+    +` + +[#Figure 58-3]## *_XML Direct Mapping to a Text Node in a Subelement_* + +.XML Direct Mapping to a Text Node in a Subelement +image::dxmse.gif[XML Direct Mapping to a Text Node in a +Subelement,title="XML Direct Mapping to a Text Node in a Subelement"] + +[#Example 58-7]## *_Java for XML Direct Mapping to a Text Node in a +Subelement_* + +`+XMLDirectMapping firstNameMapping = new XMLDirectMapping();+` +`+firstNameMapping.setAttributeName("firstName");+` +`+firstNameMapping.setXPath("personal-info/first-name/text()");+` + +`+XMLDirectMapping lastNameMapping = new XMLDirectMapping();+` +`+lastNameMapping.setAttributeName("lastName");+` +`+lastNameMapping.setXPath("personal-info/last-name/text()");+` + +==== Mapping to a Text Node by Position + +Given the XML schema in the link:#Example_58-8[Schema for XML Direct +Mapping to Text Node by Position] exampple, the link:#Figure_58-4[XML +Direct Mapping to Text Node by Position] figure illustrates an XML +direct mapping to a text node by position in a corresponding XML +document. The link:#Example_58-9[Java for XML Direct Mapping to Text +Node by Position] example shows how to configure this mapping in Java. + +[#Example 58-8]## *’ Schema for XML Direct Mapping to Text Node by +Position*’’ + +`+    +` `+    +` `+        +` `+            +` `+        +` + +`+    +` + +[#Figure 58-4]## *_XML Direct Mapping to Text Node by Position_* + +.XML Direct Mapping to Text Node by Position +image::dxmpos.gif[XML Direct Mapping to Text Node by +Position,title="XML Direct Mapping to Text Node by Position"] + +[#Example 58-9]## *’ Java for XML Direct Mapping to Text Node by +Position*’’ + +`+XMLDirectMapping firstNameMapping = new XMLDirectMapping();+` +`+firstNameMapping.setAttributeName("firstName");+` +`+firstNameMapping.setXPath("name[1]/text()");+` + +`+XMLDirectMapping lastNameMapping = new XMLDirectMapping();+` +`+lastNameMapping.setAttributeName("lastName");+` +`+lastNameMapping.setXPath("name[2]/text()");+` + +=== Mapping to an Attribute + +Given the XML schema in this example, the link:#Figure_58-5[XML Direct +Mapping to an Attribute] figure illustrates an XML direct mapping to a +text node by position in a corresponding XML document. The +link:#Example_58-11[Java for XML Direct Mapping to an Attribute] +exampple shows how to configure this mapping in Java. + +*_Schema for XML Direct Mapping to an Attribute_* + +`+    +` `+    +` `+        +` `+    +` + +[#Figure 58-5]## *_XML Direct Mapping to an Attribute_* + +.XML Direct Mapping to an Attribute +image::dxmatt.gif[XML Direct Mapping to an +Attribute,title="XML Direct Mapping to an Attribute"] + +[#Example 58-11]## *_Java for XML Direct Mapping to an Attribute_* + +`+XMLDirectMapping idMapping = new XMLDirectMapping();+` +`+idMapping.setAttributeName("id");+` `+idMapping.setXPath("@id");+` + +=== Mapping to a Specified Schema Type + +In most cases, EclipseLink can determine the target format in the XML +document. However, there are cases where you must specify which one of a +number of possible targets EclipseLink should use. For example, a +`+java.util.Calendar+` could be marshalled to a schema `+date+`, +`+time+`, or `+dateTime+` node, or a `+byte[]+` could be marshalled to a +schema `+hexBinary+` or `+base64Binary+` node. + +Given the XML schema in this exmaple, the link:#Figure_58-6[XML Direct +Mapping to a Specified Schema Type] figure illustrates an XML direct +mapping to a text node by position in a corresponding XML document. The +link:#Example_58-13[Java for XML Direct Mapping to a Specified Schema +Type] example shows how to configure this mapping in Java. + +[#Example 58-12]## *_Schema for XML Direct Mapping to a Specified Schema +Type_* + +`+    +` `+    +` `+        +` `+            +` `+            +` +`+        +` + +`+    +` + +[#Figure 58-6]## *_XML Direct Mapping to a Specified Schema Type_* + +.XML Direct Mapping to a Specified Schema Type +image::dxmscht.gif[XML Direct Mapping to a Specified Schema +Type,title="XML Direct Mapping to a Specified Schema Type"] + +[#Example 58-13]## *_Java for XML Direct Mapping to a Specified Schema +Type_* + +`+XMLDirectMapping pictureMapping = new XMLDirectMapping();+` +`+pictureMapping.setAttributeName("picture");+` +`+pictureMapping.setXPath("picture/text()");+` +`+XMLField pictureField = (XMLField) pictureMapping.getField();+` +`+pictureField.setSchemaType(XMLConstants.HEX_BINARY_QNAME);+` + +`+XMLDirectMapping resumeMapping = new XMLDirectMapping();+` +`+resumeMapping.setAttributeName("resume");+` +`+resumeMapping.setXPath("resume/text()");+` +`+XMLField resumeField = (XMLField) resumeMapping.getField();+` +`+resumeField.setSchemaType(XMLConstants.BASE_64_BINARY_QNAME);+` + +=== Mapping to a List Field with an XML Direct Mapping + +Given the XML schema in this exmaple, the link:#Figure_58-7[XMLDirect +Mapping to a List Field] figure illustrates an XML direct mapping to an +`+xsd:list+` type in a corresponding XML document when you represent the +list in your object model as a `+String+` of white space delimited +tokens. The link:#Example_58-15[Java for XML Direct Mapping to a List +Field Node] example shows how to configure this mapping in Java. + +[#Example 58-14]## *_Schema for XML Direct Mapping to a List Field_* + +`+    +` `+    +` `+        +` + +`+            +` `+        +` `+    +` `+    +` `+        +` `+    +` + +[#Figure 58-7]## *_XMLDirect Mapping to a List Field_* + +.XMLDirect Mapping to a List Field +image::dcxmstn.gif[XMLDirect Mapping to a List +Field,title="XMLDirect Mapping to a List Field"] + +[#Example 58-15]## *_Java for XML Direct Mapping to a List Field Node_* + +`+XMLDirectMapping tasksMapping = new XMLDirectMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+XMLField myField = new XMLField("tasks/text()"); +`*`+//\'\' \'\'pass\'\' \'\'in\'\' \'\'the\'\' \'\'XPath+`* + +`+myField.setUsesSingleNode(true);+` `+tasksMapping.setField(myField);+` + +=== Mapping to a Union Field with an XML Direct Mapping + +Given the XML schema in the link:#Example_58-16[Schema for XML Direct +Mapping to a Union Field] example, the link:#Figure_58-8[Java Class for +XML Direct Mapping to a Union Field] figure illustrates a Java class +that can be mapped to a corresponding XML document. Note the +`+shoeSize+` attribute in this class: when using a union field, the +corresponding attribute must be able to store all possible values. + +[#Example 58-16]## *_Schema for XML Direct Mapping to a Union Field_* + +`+    +` `+    +` `+        +` + +`+            +` `+        +` `+    +` `+    +` `+        +` `+    +` + +[#Figure 58-8]## *_Java Class for XML Direct Mapping to a Union Field_* + +.Java Class for XML Direct Mapping to a Union Field +image::dxmuc.gif[Java Class for XML Direct Mapping to a Union +Field,title="Java Class for XML Direct Mapping to a Union Field"] + +The link:#Figure_58-9[XML Direct Mapping to the First Valid Union Type] +figure illustrates an XML direct mapping to a union field in an XML +document that conforms to the schema in the link:#Example_58-16[Schema +for XML Direct Mapping to a Union Field] example. When EclipseLink +unmarshalls the XML document, it tries each of the union types until it +can make a successful conversion. The first schema type in the union is +`+xsd:decimal+`. Because "`10.5`" is a valid decimal, EclipseLink +converts the value to the appropriate type. If the `+Object+` attribute +is specific enough to trigger an appropriate value, EclipseLink will use +that type instead. Otherwise, EclipseLink uses a default (in this case +`+BigDecimal+`). You can override this behavior in Java code. + +[#Figure 58-9]## *_XML Direct Mapping to the First Valid Union Type_* + +.XML Direct Mapping to the First Valid Union Type +image::dxmuv.gif[XML Direct Mapping to the First Valid Union +Type,title="XML Direct Mapping to the First Valid Union Type"] + +The link:#Figure_58-10[XML Direct Mapping to Another Valid Union Type] +figure illustrates an XML direct mapping to union field in another XML +document that conforms to the schema in link:#Example_58-16[Schema for +XML Direct Mapping to a Union Field]. In this document, the value "`M`" +is not a valid `+xsd:decimal+` type so the next union type is tried. The +next union type is `+xsd:string+` and a conversion can be done. + +[#Figure 58-10]## *_XML Direct Mapping to Another Valid Union Type_* + +.XML Direct Mapping to Another Valid Union Type +image::dxmuvs.gif[XML Direct Mapping to Another Valid Union +Type,title="XML Direct Mapping to Another Valid Union Type"] + +This example shows how to configure this mapping in Java. + +[#Example 58-17]## *_Java for XML Direct Mapping to a Union Type_* + +`+XMLDirectMapping shoeSizeMapping = new XMLDirectMapping();+` +`+shoeSizeMapping.setAttributeName("shoeSize");+` +`+XMLUnionField shoeSizeField = new XMLUnionField();+` +`+shoeSizeField.setXPath("shoe-size/text()");+` +`+shoeSizeField.addSchemaType(XMLConstants.DECIMAL_QNAME);+` +`+shoeSizeField.addSchemaType(XMLConstants.STRING_QNAME);+` +`+shoeSizeMapping.setField(shoeSizeField);+` + +To override the default conversion, use the `+XMLUnionField+` method +`+addConversion+`: + +`+shoeSizeField.addConversion(XMLConstants.DECIMAL_QNAME, Float.class);+` + +=== Mapping to a Union of Lists with an XML Direct Mapping + +Given the XML schema in link:#Example_58-18[Schema for XML Direct +Mapping to Union of Lists], the link:#Figure_58-11[XML Direct Mapping to +Union of Lists] figure illustrates an XML direct mapping to a union of +lists in a corresponding XML document. The link:#Example_58-19[Java for +XML Direct Mapping to Union of Lists] example shows how to configure +this mapping in Java. + +[#Example 58-18]## *_Schema for XML Direct Mapping to Union of Lists_* + +`+    +` `+    +` `+        +` `+            +` `+                +` +`+            +` + +`+            +` `+                +` `+            +` `+        +` +`+    +` + +[#'Figure 58-11]## *_XML Direct Mapping to Union of Lists_* + +.XML Direct Mapping to Union of Lists +image::dxuofl.gif[XML Direct Mapping to Union of +Lists,title="XML Direct Mapping to Union of Lists"] + +Note that in this example, valid XML documents contain either all +`+xsd:double+`, all `+xsd:date+`, or all `+xsd:integer+` values. + +[#Example 58-19]## *_Java for XML Direct Mapping to Union of Lists_* + +`+XMLDirectMapping mapping = new XMLDirectMapping();+` +`+mapping.setAttributeName("vacation");+` +`+mapping.setXPath("UnionOfLists/text()");+` + +=== Mapping to a Union of Unions with an XML Direct Mapping + +Given the XML schema in the link:#Example_58-20[Schema for XML Direct +Mapping to a Union of Unions] example, the link:#Figure_58-12[Java Class +for XML Direct Mapping to a Union of Unions] figure illustrates a Java +class that can be mapped to a corresponding XML document. The +link:#Example_58-21[Java for XML Direct Mapping to a Union of Unions] +example shows how to configure this mapping in Java. + +[#Example 58-20]## *_Schema for XML Direct Mapping to a Union of +Unions_* + +`+    +` `+    +` `+        +` + +`+            +` `+                +` `+                    +` +`+                        +` `+                    +` +`+                    +` + +`+                        +` `+                    +` +`+                +` `+            +` `+            +` +`+                +` + +`+                    +` `+                        +` +`+                    +` `+                    +` +`+                        +` `+                    +` + +`+                +` `+            +` `+        +` `+    +` + +[#Figure 58-12]## *_Java Class for XML Direct Mapping to a Union of +Unions_* + +.Java Class for XML Direct Mapping to a Union of Unions +image::dxuofu.gif[Java Class for XML Direct Mapping to a Union of +Unions,title="Java Class for XML Direct Mapping to a Union of Unions"] + +[#Example 58-21]## *_Java for XML Direct Mapping to a Union of Unions_* + +`+XMLDirectMapping vacationMapping = new XMLDirectMapping();+` +`+vacationMapping.setAttributeName("vacation");+` +`+XMLUnionField vacationField = new XMLUnionField();+` +`+vacationField.setXPath("vacation/text()");+` +`+vacationField.addSchemaType(XMLConstants.DATE_QNAME);+` +`+vacationField.addSchemaType(XMLConstants.INTEGER_QNAME);+` +`+vacationField.addSchemaType(XMLConstants.STRING_QNAME);+` +`+vacationField.addSchemaType(XMLConstants.FLOAT_QNAME);+` +`+vacationMapping.setField(vacationField);+` + +=== Mapping with a Simple Type Translator + +If the type of a node is not defined in your XML schema, you can +configure an XML direct mapping to use the `+xsi:type+` attribute to +provide type information. + +Given the XML schema fragment in the link:#Example_58-22[Schema for XML +Direct Mapping with Simple Type Translator] example, the +link:#Figure_58-13[Java Class for XML Direct Mapping with Simple Type +Translator] figure illustrates a Java class that can be mapped to a +corresponding XML document. + +[#Example 58-22]## *_Schema for XML Direct Mapping with Simple Type +Translator_* + +`+...+` `+    +` `+    +` `+...+` + +[#Figure 58-13]## *_Java Class for XML Direct Mapping with Simple Type +Translator_* + +.Java Class for XML Direct Mapping with Simple Type Translator +image::dxmsttc.gif[Java Class for XML Direct Mapping with Simple Type +Translator,title="Java Class for XML Direct Mapping with Simple Type Translator"] + +The following figure illustrates an XML direct mapping with a simple +type translator in an XML document that conforms to the schema in the +link:#Example_58-22[Schema for XML Direct Mapping with Simple Type +Translator] example. + +[#Figure 58-14]## *_XML Direct Mapping with a Simple Type Translator_* + +.XML Direct Mapping with a Simple Type Translator +image::dxmsttm.gif[XML Direct Mapping with a Simple Type +Translator,title="XML Direct Mapping with a Simple Type Translator"] + +This example shows how to configure this mapping in Java. + +[#Example 58-23]## *_Java for XML Direct Mapping with Simple Type +Translator_* + +`+XMLDirectMapping numberMapping = new XMLDirectMapping();+` +`+numberMapping.setAttributeName("number");+` +`+numberMapping.setXPath("number/text()");+` +`+XMLField numberField = (XMLField) numberMapping.getField();+` +`+numberField.setIsTypedTextField(true);+` + +For more information, see +link:Introduction%20to%20Mappings%20(ELUG)#Simple_Type_Translator[Simple +Type Translator]. + +== XML Composite Direct Collection Mapping + +XML composite direct collection mappings map a Java collection of simple +object attributes to XML attributes and text nodes. Use multiplicity +settings to specify an element as a collection. The XML schema allows +you to define minimum and maximum occurrences. You can use a composite +direct collection XML mapping in the following scenarios: + +* link:#Mapping_to_Multiple_Text_Nodes[Mapping to Multiple Text Nodes] +* link:#Mapping_to_Multiple_Attributes[Mapping to Multiple Attributes] +* link:#Mapping_to_a_Single_Text_Node_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Single Text Node with an XML Composite Direct Collection Mapping] +* link:#Mapping_to_a_Single_Attribute_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Single Attribute with an XML Composite Direct Collection Mapping] +* link:#Mapping_to_a_List_of_Unions_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a List of Unions with an XML Composite Direct Collection Mapping] +* link:#Mapping_to_a_Union_of_Lists_with_an_XML_Composite_Direct_Collection_Mapping[Mapping +to a Union of Lists with an XML Composite Direct Collection Mapping] +* link:#Specifying_the_Content_Type_of_a_Collection_with_an_XML_Composite_Direct_Collection_Mapping[Specifying +the Content Type of a Collection with an XML Composite Direct Collection +Mapping] + +See +link:Configuring%20an%20XML%20Composite%20Direct%20Collection%20Mapping%20(ELUG)[Configuring +an XML Composite Direct Collection Mapping] for more information. + +=== Mapping to Multiple Text Nodes + +This section describes using a composite direct collection XML mapping +when: + +* link:#Mapping_to_a_Simple_Sequence[Mapping to a Simple Sequence] +* link:#Mapping_to_a_Sequence_in_a_Subelement[Mapping to a Sequence in a +Subelement] + +==== Mapping to a Simple Sequence + +Given the XML schema in the link:#Example_58-24[Schema for Composite +Direct Collection XML Mapping to a Simple Sequence] example, the +link:#Figure_58-15[Composite Direct Collection XML Mapping to a Simple +Sequence] figure illustrates a composite direct collection XML mapping +to a simple sequence of text nodes in a corresponding XML document. +link:#Example_58-25[Java for Composite Direct Collection XML Mapping to +a Simple Sequence] shows how to configure this mapping in Java. + +[#Example 58-24]## *_Schema for Composite Direct Collection XML Mapping +to a Simple Sequence_* + +`+    +` `+    +` `+        +` `+            +` `+        +` + +`+    +` + +[#Figure 58-15]## *_Composite Direct Collection XML Mapping to a Simple +Sequence_* + +.Composite Direct Collection XML Mapping to a Simple Sequence +image::dcxmss.gif[Composite Direct Collection XML Mapping to a Simple +Sequence,title="Composite Direct Collection XML Mapping to a Simple Sequence"] + +[#Example 58-25]## *_Java for Composite Direct Collection XML Mapping to +a Simple Sequence_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+tasksMapping.setXPath("task/text()");+` + +==== Mapping to a Sequence in a Subelement + +Given the XML schema in this example, the link:#Figure_58-16[Composite +Direct Collection XML Mapping to a Subelement Sequence] figure +illustrates a composite direct collection XML mapping to a sequence of +text nodes in a subelement in a corresponding XML document. The +link:#Example_58-27[Java for Composite Direct Collection XML Mapping to +a Subelement Sequence] shows how to configure this mapping in Java. + +[#Example 58-26]## *_Schema for Composite Direct Collection XML Mapping +to a Subelement Sequence_* + +`+    +` `+    +` `+        +` + +`+            +` `+                +` `+                    +` +`+                        +` `+                    +` +`+                +` + +`+            +` `+        +` `+    +` + +[#Figure 58-16]## *_Composite Direct Collection XML Mapping to a +Subelement Sequence_* + +.Composite Direct Collection XML Mapping to a Subelement Sequence +image::dcxmsub.gif[Composite Direct Collection XML Mapping to a +Subelement +Sequence,title="Composite Direct Collection XML Mapping to a Subelement Sequence"] + +[#Example 58-27]## *_Java for Composite Direct Collection XML Mapping to +a Subelement Sequence_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+tasksMapping.setXPath("tasks/task/text()");+` + +=== Mapping to Multiple Attributes + +Given the XML schema in the following example, the +link:#Figure_58-17[Composite Direct Collection XML Mapping to Multiple +Attributes] figure illustrates a composite direct collection XML mapping +to a sequence of text nodes in a subelement in a corresponding XML +document. The link:#Example_58-29[Java for Composite Direct Collection +XML Mapping to Multiple Attributes] exampleshows how to configure this +mapping in Java. + +[#Example 58-28]## *_Schema for Composite Direct Collection XML Mapping +to Multiple Attributes_* + +`+    +` `+    +` `+        +` `+            +` `+                +` +`+                    +` + +`+                +` `+            +` `+        +` `+    +` + +[#Figure 58-17]## *_Composite Direct Collection XML Mapping to Multiple +Attributes_* + +image:dcxmma.gif[Description of Figure 58-17 +follows,title="Description of Figure 58-17 follows"] +[img_text/dcxmma.htm Description of "`Figure 58-17 Composite Direct +Collection XML Mapping to Multiple Attributes`"] + +[#Example 58-29]## *_Java for Composite Direct Collection XML Mapping to +Multiple Attributes_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("tasks/@task");+` +`+tasksMapping.setXPath("task/text()");+` + +=== Mapping to a Single Text Node with an XML Composite Direct Collection Mapping + +When you map a collection to a single node, the contents of the node is +treated as a space-separated list. + +Given the XML schema in this example, the link:#Figure_58-18[XML +Composite Direct Collection Mapping to a Single Text Node] figur +eillustrates a composite direct collection XML mapping to a single text +node in a corresponding XML document. The link:#Example_58-31[Java for +XML Composite Direct Collection Mapping to a Single Text Node] example +shows how to configure this mapping in Java. + +[#Example 58-30]## *_Schema for XML Composite Direct Collection Mapping +to a Single Text Node_* + +`+    +` `+    +` `+        +` `+            +` + +`+        +` `+    +` `+    +` `+        +` `+    +` + +[#Figure 58-18]## *_XML Composite Direct Collection Mapping to a Single +Text Node_* + +.XML Composite Direct Collection Mapping to a Single Text Node +image::dcxmstn.gif[XML Composite Direct Collection Mapping to a Single +Text +Node,title="XML Composite Direct Collection Mapping to a Single Text Node"] + +[#Example 58-31]## *_Java for XML Composite Direct Collection Mapping to +a Single Text Node_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+tasksMapping.setXPath("tasks/text()");+` +`+tasksMapping.setUsesSingleNode(true);+` + +=== Mapping to a Single Attribute with an XML Composite Direct Collection Mapping + +Given the XML schema in this example, the link:#Figure_58-19[XML +Composite Direct Collection Mapping to a Single Attribute] figure +illustrates a composite direct collection XML mapping to a single +attribute in a corresponding XML document. The link:#Example_58-33[Java +for XML Composite Direct Collection Mapping to a Single Attribute] +example shows how to configure this mapping in Java. + +[#Example 58-32]## *_Schema for XML Composite Direct Collection Mapping +to a Single Attribute_* + +`+    +` `+    +` `+        +` `+    +` + +`+    +` `+        +` `+    +` + +[#Figure 58-19]## *_XML Composite Direct Collection Mapping to a Single +Attribute_* + +.XML Composite Direct Collection Mapping to a Single Attribute +image::dcxmsat.gif[XML Composite Direct Collection Mapping to a Single +Attribute,title="XML Composite Direct Collection Mapping to a Single Attribute"] + +[#Example 58-33]## *_Java for XML Composite Direct Collection Mapping to +a Single Attribute_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("tasks");+` +`+tasksMapping.setXPath("@tasks");+` +`+tasksMapping.setUsesSingleNode(true);+` + +=== Mapping to a List of Unions with an XML Composite Direct Collection Mapping + +Given the XML schema in this example, the link:#Figure_58-20[Composite +XML Direct Collection Mapping to List of Unions] figure illustrates a +composite direct collection XML mapping to a list of unions in a +corresponding XML document. The link:#Example_58-35[Java for XML +Composite Direct Collection Mapping to List of Unions] example shows how +to configure this mapping in Java. + +[#Example 58-34]## *_Schema for XML Composite Direct Collection Mapping +to List of Unions_* + +`+    +` `+    +` `+        +` + +`+            +` `+                +` `+            +` `+        +` +`+    +` + +[#Figure 58-20]## *_Composite XML Direct Collection Mapping to List of +Unions_* + +.Composite XML Direct Collection Mapping to List of Unions +image::cdxlofu.gif[Composite XML Direct Collection Mapping to List of +Unions,title="Composite XML Direct Collection Mapping to List of Unions"] + +[#Example 58-35]## *_Java for XML Composite Direct Collection Mapping to +List of Unions_* + +`+XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();+` +`+mapping.setAttributeName("myattribute");+` +`+XMLUnionField field = new XMLUnionField("listOfUnions/text()");+` +`+mapping.addSchemaType(new Qname(url,"int"));+` +`+mapping.addSchemaType(new Qname(url,"date"));+` +`+mapping.setField(field);+` `+mapping.useSingleElement(false);+` + +=== Mapping to a Union of Lists with an XML Composite Direct Collection Mapping + +Given the XML schema in this example, the link:#Figure_58-21[XML +Composite Direct Collection Mapping to a Union of Lists] figure +illustrates an XML composite direct collection mapping to a union of +lists in a corresponding XML document. The link:#Example_58-37[Java for +XML Composite Direct Collection Mapping to a Union of Lists] example +shows how to configure this mapping in Java. + +[#Example 58-36]## *_Schema for XML Composite Direct Collection Mapping +to a Union of Lists_* + +`+    +` `+    +` `+        +` `+            +` + +`+                +` `+            +` `+            +` +`+                +` `+            +` `+        +` + +`+    +` + +[#Figure 58-21]## *_XML Composite Direct Collection Mapping to a Union +of Lists_* + +.XML Composite Direct Collection Mapping to a Union of Lists +image::cdxuofl.gif[XML Composite Direct Collection Mapping to a Union of +Lists,title="XML Composite Direct Collection Mapping to a Union of Lists"] + +Note that in this example, valid XML documents contain either all +`+xsd:double+`, all `+xsd:date+`, or all `+xsd:integer+` values. + +[#Example 58-37]## *_Java for XML Composite Direct Collection Mapping to +a Union of Lists_* + +`+XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();+` +`+mapping.setAttributeName("myattribute");+` +`+mapping.useSingleElement(false);+` +`+XMLUnionField unionField = new XMLUnionField("UnionOfLists/text()");+` +`+field.addSchemaType(new Qname(url," integer"))+` +`+field.addSchemaType (new Qname(url," date"))+` +`+field.addSchemaType (new Qname(url," double"))+` +`+field.setUsesSingleNode(false);+` + +=== Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping + +By default, EclipseLink will treat the node values read by a composite +direct collection XML mapping as objects of type `+String+`. You can +override this behavior by specifying the type of the collection’s +contents. + +Given the XML schema in this example, the link:#Figure_58-22[XML +Composite Direct Collection Mapping with Specified Content Type] figure +illustrates an XML composite direct collection mapping to a simple +sequence in a corresponding XML document. The mapping is configured to +specify the content type of the collection as `+Calendar+`. The +link:#Example_58-39[Java for XML Composite Direct Collection Mapping +with Specified Content Type] example shows how to configure this mapping +in Java. + +[#Example 58-38]## *_Schema for XML Composite Direct Collection Mapping +with Specified Content Type_* + +`+    +` `+    +` `+        +` + +`+            +` `+        +` `+    +` + +[#Figure 58-22]## *_XML Composite Direct Collection Mapping with +Specified Content Type_* + +.XML Composite Direct Collection Mapping with Specified Content Type +image::dcxmct.gif[XML Composite Direct Collection Mapping with Specified +Content +Type,title="XML Composite Direct Collection Mapping with Specified Content Type"] + +[#Example 58-39]## *_Java for XML Composite Direct Collection Mapping +with Specified Content Type_* + +`+XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();+` +`+tasksMapping.setAttributeName("vacationDays");+` +`+tasksMapping.setXPath("vacation/text()");+` +`+tasksMapping.setAttributeElementClass(Calendar.class);+` + +== XML Composite Object Mapping + +XML composite object mappings represent a relationship between two +classes. In XML, the "`owned`" class may be nested with the element tag +representing the "`owning`" class. You can use a composite object XML +mapping in the following scenarios: + +* link:#Mapping_into_the_Parent_Record[Mapping into the Parent Record] +* link:#Mapping_to_an_Element[Mapping to an Element] +* link:#Mapping_to_Different_Elements_by_Element_Name[Mapping to +Different Elements by Element Name] +* link:#Mapping_to_Different_Elements_by_Element_Position[Mapping to +Different Elements by Element Position] + +See +link:Configuring%20an%20XML%20Composite%20Object%20Mapping%20(ELUG)[Configuring +an XML Composite Object Mapping] for more information. + +=== Mapping into the Parent Record + +The composite object may be mapped to the same record as the parent. + +[width="100%",cols="<100%",] +|=== +|*Note:* The nodes mapped to by the composite object must be sequential. +|=== + +Given the XML schema in this exmaple, the link:#Figure_58-23[XML +Composite Object Mapping into the Parent Record] figure illustrates an +XML composite object mapping into the parent record in a corresponding +XML document. The link:#Example_58-41[Java for XML Composite Object +Mapping into the Parent Record] example shows how to configure this +mapping in Java. + +[#Example 58-40]## *_Schema for XML Composite Object Mapping into the +Parent Record_* + +`+    +` `+    +` `+        +` + +`+            +` `+            +` `+            +` `+            +` +`+        +` `+    +` + +[#Figure 58-23]##*_XML Composite Object Mapping into the Parent Record_* + +.XML Composite Object Mapping into the Parent Record +image::coxmpr.gif[XML Composite Object Mapping into the Parent +Record,title="XML Composite Object Mapping into the Parent Record"] + +[#Example 58-41]## *_Java for XML Composite Object Mapping into the +Parent Record_* + +`+XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();+` +`+addressMapping.setAttributeName("address");+` +`+addressMapping.setXPath(".");+` +`+addressMapping.setReferenceClass(Address.class);+` + +=== Mapping to an Element + +Given the XML schema in this example, thelink:#Figure_58-24[XML +Composite Object Mapping to an Element] figure illustrates an XML +composite object mapping to an element in a corresponding XML document. +The link:#Example_58-43[Java for XML Composite Object Mapping to an +Element] example shows how to configure this mapping in Java. + +[#Example 58-42]## *_Schema for XML Composite Object Mapping to an +Element_* + +`+    +` `+    +` `+        +` + +`+            +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                        +` `+                    +` +`+                +` `+            +` `+        +` `+    +` + +[#Figure 58-24]## *_XML Composite Object Mapping to an Element_* + +.XML Composite Object Mapping to an Element +image::coxme.gif[XML Composite Object Mapping to an +Element,title="XML Composite Object Mapping to an Element"] + +[#Example 58-43]## *_Java for XML Composite Object Mapping to an +Element_* + +`+XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();+` +`+addressMapping.setAttributeName("address");+` +`+addressMapping.setXPath("address");+` +`+addressMapping.setReferenceClass(Address.class);+` + +=== Mapping to Different Elements by Element Name + +An object may have multiple composite object mappings to the same +reference class. Each composite object mapping must have a unique XPath. +This example uses unique XPaths by name. + +Given the XML schema in this example, the link:#Figure_58-25[XML +Composite Object Mapping to Elements by Name] figure illustrates an XML +composite object mapping to different elements by name in a +corresponding XML document. The link:#Example_58-45[Java for XML +Composite Object Mapping to Elements by Name] example shows how to +configure this mapping in Java. + +[#Example 58-44]## *_Schema for XML Composite Object Mapping to Elements +by Name_* + +`+    +` `+    +` `+        +` + +`+            +` `+            +` `+            +` `+            +` +`+        +` `+    +` + +`+    +` `+        +` `+            +` `+            +` `+        +` +`+    +` + +[#Figure 58-25]## *_XML Composite Object Mapping to Elements by Name_* + +.XML Composite Object Mapping to Elements by Name +image::coxmden.gif[XML Composite Object Mapping to Elements by +Name,title="XML Composite Object Mapping to Elements by Name"] + +[#Example 58-45]## *_Java for XML Composite Object Mapping to Elements +by Name_* + +`+XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();+` +`+billingAddressMapping.setAttributeName("billingAddress");+` +`+billingAddressMapping.setXPath("billing-address");+` +`+billingAddressMapping.setReferenceClass(Address.class);+` + +`+XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();+` +`+shippingAddressMapping.setAttributeName("shippingAddress");+` +`+shippingAddressMapping.setXPath("shipping-address");+` +`+shippingAddressMapping.setReferenceClass(Address.class);+` + +=== Mapping to Different Elements by Element Position + +An object may have multiple composite object mappings to the same +reference class. Each composite object mapping must have a unique XPath. +This example uses unique XPaths by position. + +Given the XML schema in this example, the link:#Figure_58-26[XML +Composite Object Mapping to Elements by Position] figure illustrates an +XML composite object mapping to different elements by position in a +corresponding XML document. The link:#Example_58-47[Java for XML +Composite Object Mapping to Elements by Position] example shows how to +configure this mapping in Java. + +[#Example 58-46]## *_Schema for XML Composite Object Mapping to Elements +by Position_* + +`+    +` `+    +` `+        +` + +`+            +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                        +` `+                    +` +`+                +` `+            +` `+        +` `+    +` + +[#Figure 58-26]## *_XML Composite Object Mapping to Elements by +Position_* + +.XML Composite Object Mapping to Elements by Position +image::coxmdep.gif[XML Composite Object Mapping to Elements by +Position,title="XML Composite Object Mapping to Elements by Position"] + +[#Example 58-47]## *_Java for XML Composite Object Mapping to Elements +by Position_* + +`+XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();+` +`+billinAddressMapping.setAttributeName("billingAddress");+` +`+billinAddressMapping.setXPath("address[1]");+` +`+billinAddressMapping.setReferenceClass(Address.class);+` + +`+XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();+` +`+shippingAddressMapping.setAttributeName("shippingAddress");+` +`+shippingAddressMapping.setXPath("address[2]");+` +`+shippingAddressMapping.setReferenceClass(Address.class);+` + +== XML Composite Collection Mapping + +Use XML composite collection mappings to represent one-to-many +relationships. Composite collection XML mappings can reference any class +that has an EclipseLink descriptor. The attribute in the object mapped +must implement either the Java `+Collection+` interface (for example, +`+Vector+` or `+HashSet+`) or `+Map+` interface (for example, +`+Hashtable+` or `+TreeMap+`). The `+CompositeCollectionMapping+` class +allows a reference to the mapped class and the indexing type for that +class. + +Given the XML schema in this example, link:#Figure_58-27[XML Composite +Collection Mapping] illustrates an XML composite collection mapping to +different elements by position in a corresponding XML document. +link:#Example_58-49[Java for XML Composite Collection Mapping for a +Collection Attribute] shows how to configure this mapping in Java for a +`+Collection+` attribute and link:#Example_58-50[Java for XML Composite +Collection Mapping for a Map Attribute] shows how to configure this +mapping in Java for a `+Map+` attribute. + +*_Schema for XML Composite Collection Mapping_* + +`+    +` `+    +` `+        +` + +`+            +` `+            +` `+            +` `+                +` +`+                    +` `+                        +` + +`+                    +` `+                    +` `+                +` +`+            +` `+        +` `+    +` + +[#Figure 58-27]## *_XML Composite Collection Mapping_* + +.XML Composite Collection Mapping +image::ccxm.gif[XML Composite Collection +Mapping,title="XML Composite Collection Mapping"] + +[#Example 58-49]## *_Java for XML Composite Collection Mapping for a +Collection Attribute_* + +`+XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();+` +`+phoneNumbersMapping.setAttributeName("phoneNumbers");+` +`+phoneNumbersMapping.setXPath("phone-number");+` +`+phoneNumbersMapping.setReferenceClass(PhoneNumber.class);+` + +[#Example 58-50]## *_Java for XML Composite Collection Mapping for a Map +Attribute_* + +`+XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();+` +`+phoneNumbersMapping.setAttributeName("phoneNumbers");           +` +`+phoneNumbersMapping.setXPath("phone-number");+` +`+phoneNumbersMapping.setReferenceClass(PhoneNumber.class);+` +`+phoneNumbersMapping.useMapClass(HashMap.class, "getType");+` + +See +link:Configuring%20an%20XML%20Composite%20Collection%20Mapping%20(ELUG)[Configuring +an XML Composite Collection Mapping] for more information. + +== XML Any Object Mapping + +The XML any object mapping is similar to the composite object XML +mapping (see link:#XML_Composite_Object_Mapping[XML Composite Object +Mapping]) except that the reference object may be of any type (including +`+String+`). This type does not need to be related to any other +particular type through inheritance or a common interface. + +The corresponding object attribute value can be an instance of any +object with a `+Descriptor+`, a `+java.lang.Object+`, a +`+java.lang.String+`, a primitive object (such as +`+java.lang.Integer+`), or a user defined type generic enough for all +possible application values. + +This mapping is useful with the following XML schema constructs: + +* any +* choice +* substitution groups + +Referenced objects can specify a default root element on their +descriptor (see +link:Introduction%20to%20Descriptors%20(ELUG)#Default_Root_Element[Default +Root Element]). + +[width="100%",cols="<100%",] +|=== +|*Note:* The undefined document root element of a referenced object is +ignored during marshalling with an any collection mapping and object +mapping. +|=== + +Given the XML schema in link:#Example_58-51[Schema for XML Any Object +Mapping], link:#Figure_58-28[Java Classes for XML Any Object Mapping] +illustrates the Java classes used in this example. A single XML any +object mapping is used to map `+Customer+` attribute `+contactMethod+`. +This attribute must be generic enough to reference all possible values: +in this example, instances of `+Address+`, `+PhoneNumber+`, and +`+String+`. + +[#Example 58-51]## *_Schema for XML Any Object Mapping_* + +`+    +` `+    +` `+        +` + +`+            +` `+        +` `+    +` `+    +` `+        +` +`+            +` + +`+                +` `+                +` `+            +` `+        +` +`+    +` `+    +` + +[#Figure 58-28]## *_Java Classes for XML Any Object Mapping_* + +.Java Classes for XML Any Object Mapping +image::aoxmc.gif[Java Classes for XML Any Object +Mapping,title="Java Classes for XML Any Object Mapping"] + +link:#Figure_58-29[XML Any Object Mapping to Address Type], +link:#Figure_58-30[XML Any Object Mapping to PhoneNumber Type], and +link:#Figure_58-31[XML Any Object Mapping to String Type] illustrate how +the XML any object mapping maps to an `+Address+`, `+PhoneNumber+`, and +`+String+` (respectively) in XML documents that conform to the schema in +link:#Example_58-51[Schema for XML Any Object Mapping]. + +[#Figure 58-29]## *_XML Any Object Mapping to Address Type_* + +.XML Any Object Mapping to Address Type +image::aoxmadd.gif[XML Any Object Mapping to Address +Type,title="XML Any Object Mapping to Address Type"] + +[#Figure 58-30]## *_XML Any Object Mapping to PhoneNumber Type_* + +.XML Any Object Mapping to PhoneNumber Type +image::aoxmpho.gif[XML Any Object Mapping to PhoneNumber +Type,title="XML Any Object Mapping to PhoneNumber Type"] + +[#Figure 58-31]## *_XML Any Object Mapping to String Type_* + +.XML Any Object Mapping to String Type +image::aoxmstr.gif[XML Any Object Mapping to String +Type,title="XML Any Object Mapping to String Type"] + +This example shows how to configure this mapping in Java. + +[#Example 58-52]## *_Java for XML Any Object Mapping_* + +`+XMLAnyObjectMapping contactMethodMapping = new XMLAnyObjectMapping();+` +`+contactMethodMapping.setAttributeName("contactMethod");+` +`+contactMethodMapping.setXPath("contact-method");+` + +For more information about EclipseLink XML mapping support for +`+xs:any+` and `+xs:anyType+`, see #xs:any_and_xs:anyType_Support[xs:any +and xs:anyType Support]. + +See +link:Configuring%20an%20XML%20Any%20Object%20Mapping%20(ELUG)[Configuring +an XML Any Object Mapping] for more information. + +== XML Any Collection Mapping + +The XML any collection mapping is similar to the composite collection +XML mapping (see link:#XML_Composite_Collection_Mapping[XML Composite +Collection Mapping]), except that the referenced objects may be of +different types (including `+String+`). These types need not be related +to each other through inheritance or a common interface. + +The corresponding object attribute value can be an instance of any +object with a `+Descriptor+`, a `+java.lang.Object+`, a +`+java.lang.String+`, a primitive object (such as +`+java.lang.Integer+`), or a user defined type generic enough for all +possible application values. + +This mapping is useful with the following XML schema constructs: + +* any +* choice +* substitution groups + +Each of the referenced objects (except `+String+`) must specify a +default root element on their descriptor (see +link:Introduction%20to%20Descriptors%20(ELUG)#Default_Root_Element[Default +Root Element]). + +Given the XML schema in link:#Example_58-53[Schema for XML Any +Collection Mapping], link:#Figure_58-32[Java Classes for XML Any +Collection Mapping] illustrates the Java classes used in this example. A +single XML any collection mapping is used to map `+Customer+` attribute +`+contactMethods+`. This attribute must be generic enough to reference +all possible values: in this example, instances of `+Address+`, +`+PhoneNumber+`, and `+String+`. + +[#Example 58-53]## *_Schema for XML Any Collection Mapping_* + +`+    +` `+    +` `+        +` + +`+            +` `+        +` `+    +` `+    +` `+        +` +`+            +` + +`+                +` `+                +` `+            +` `+        +` +`+    +` `+    +` + +[#Figure 58-32]## *_Java Classes for XML Any Collection Mapping_* + +.Java Classes for XML Any Collection Mapping +image::aoxmc.gif[Java Classes for XML Any Collection +Mapping,title="Java Classes for XML Any Collection Mapping"] + +link:#Figure_58-33[XML Any Collection Mapping] illustrate how the XML +any collection mapping maps to a collection of `+Address+`, +`+PhoneNumber+`, and `+String+` objects in an XML document that conforms +to the schema in link:#Example_58-53[Schema for XML Any Collection +Mapping]. + +[#Figure 58-33]## *_XML Any Collection Mapping_* + +.XML Any Collection Mapping +image::acxm.gif[XML Any Collection +Mapping,title="XML Any Collection Mapping"] + +This example shows how to configure this mapping in Java. + +[#Example 58-54]## *_Java for XML Any Collection Mapping_* + +`+XMLAnyCollectionMapping contactMethodsMapping = new XMLAnyCollectionMapping();+` +`+contactMethodsMapping.setAttributeName("contactMethods");+` +`+contactMethodsMapping.setXPath("contact-methods");+` + +For more information about EclipseLink XML mapping support for +`+xs:any+` and `+xs:anyType+`, see #xs:any_and_xs:anyType_Support[xs:any +and xs:anyType Support]. + +See +link:Configuring%20an%20XML%20Any%20Collection%20Mapping%20(ELUG)[Configuring +an XML Any Collection Mapping] for more information. + +== XML Transformation Mapping + +You can use an XML transformation mapping to create a custom mapping +where one or more XML nodes can be used to create the object to be +stored in a Java class’s attribute. To handle the custom requirements at +marshall (write) and unmarshall (read) time, a transformation mapping +takes instances of `+org.eclipse.persistence.mappings.transformers+` +(such as `+AttributeTransformer+` and `+FieldTransformer+`) that you +provide. This provides a nonintrusive solution that avoids the need for +your domain objects to implement special interfaces for this purpose. + +As link:#Figure_58-34[XML Transformation Mappings] illustrates, you +configure the transformation mapping with an +`+org.eclipse.persistence.mappings.transformers.AttributeTransformer+` +instance to perform the XML instance-to-Java attribute transformation at +unmarshall time. In this example, the `+AttributeTransformer+` combines +two XML text nodes into a single Java object. + +Similarly, you also configure the transformation mapping with one or +more `+org.eclipse.persistence.mappings.transformers.FieldTransformer+` +instances to perform the Java attribute-to-XML instance transformation +at marshall time. In this example, each `+FieldTransformer+` is +responsible for mapping one of the Java object values to an XML text +node. + +[#Figure 58-34]## *_XML Transformation Mappings_* + +.XML Transformation Mappings +image::transfig.gif[XML Transformation +Mappings,title="XML Transformation Mappings"] + +See +link:Configuring%20an%20XML%20Transformation%20Mapping_(ELUG)[Configuring +an XML Transformation Mapping] for more information. + +== XML Object Reference Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLObjectReferenceMapping+` is +a key on source-based aggregate mapping. It allows you to use one-to-one +mappings to map a given element in an XML document to another element in +that same XML document using one or more keys. + +Use this mapping when several objects reference the same instance of +another object. In this case, one and only one of the mappings is to be +a composite–the remaining mappings must be reference mappings. These +references will be created based on one or more key values. + +XML object reference mapping is fully supported in the deployment XML. + +With this mapping, EclipseLink provides support for composite keys, as +well as for foreign key grouping elements. + +[width="100%",cols="<100%",] +|=== +|*Note:* You should group together elements mapped to keys. Also, +EclipseLink supports grouping elements that wrap all of the keys (not +the ones that wrap each individual key). +|=== + +The `+XMLObjectReferenceMapping+` captures the following information: + +* Attribute name. +* Reference class. +* Map of source and target key pairs, such as XPath values (see +link:#XPath_Support[XPath Support]) in the following format: + +`+["project-id/text()","@id"]+` + +Use the `+addSourceToTargetKeyFieldAssociation+` method to add a source +and target Xpath pair to the map. + +* List of source keys to maintain order. + +For more information, see +link:Configuring%20an%20XML%20Object%20Reference%20Mapping%20(ELUG)[Configuring +an XML Object Reference Mapping]. + +=== Mapping Using a Single Key + +The following class diagram, as well as the following three examples, +demonstrate how to map one element to another using a single key. + +[#Figure 58-35]## *_Class Diagram_* + +.Class Diagram +image::xmlobrefmap.gif[Class Diagram,title="Class Diagram"] + +[#Example 58-55]## *_Using Single Key - Instance Document_* + +`+...+` `+    +``+Joe Brown+` `+    +`*`+99+`* +`++` `+    +``+Big Project+` +`+    +``+100,000+` `+...+` + +This example shows how to create an `+XMLObjectReferenceMapping+`, set a +single key on source, and then add the mapping to the descriptor. + +[#Example 58-56]## *_Using Single Key - Project Class - Employee +Descriptor_* + +`+...+` +`+XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();+` +`+emp.setAttributeName("project");+` +`+emp.setReferenceClass(Project.class);+` +*`+emp.addSourceToTargetKeyFieldAssociation("project-id/text()","@id");+`*`+   +` +`+empDescriptor.addMapping(emp);+` `+...+` + +This example shows how to define the primary key field on the +descriptor. + +[#Example 58-57]## *_Using Single Key - Project Class - Project +Descriptor_* + +`+...+` `+XMLDescriptor prjDescriptor = new XMLDescriptor();+` +`+prjDescriptor.setJavaClass(Project.class);+` +*`+prjDescriptor.addPrimaryKeyField("@id");+`* `+...+` + +=== Mapping Using a Composite Key + +The link:#Figure_58-35[Class Diagram] figure, as well as the following +three examples, demonstrate how to map one element to another using a +composite key. + +[#Example 58-58]## *_Using Composite Key - Instance Document_* + +`+...+` `+    +``+Joe Brown+` `+    +`*`+Big\'\' \'\'Project+`* +`+    +`*`+100,000+`* `+    +``+Big Project+` `+    +`*`+100,000+`* +`+...+` + +This example shows how to create an `+XMLObjectReferenceMapping+`, set a +composite key on source, and then add the mapping to the descriptor. + +[#Example 58-59]## *_Using Composite Key - Project Class - Employee +Descriptor_* + +`+...+` +`+XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();+` +`+emp.setAttributeName("project");+` +`+emp.setReferenceClass(Project.class);+` +*`+emp.addSourceToTargetKeyFieldAssociation("prj-name/text()","name/text()");+`* +*`+emp.addSourceToTargetKeyFieldAssociation("prj-budget/text()","budget/text()");+`* +`+empDescriptor.addMapping(emp);+` `+...+` + +The following example shows how to define a composite primary key field +on the descriptor. + +[#Example 58-60]## *_Using Composite Key - Project Class - Project +Descriptor_* + +`+...+` `+XMLDescriptor prjDescriptor = new XMLDescriptor();+` +`+prjDescriptor.setJavaClass(Project.class);+` +*`+prjDescriptor.addPrimaryKeyField("name");+`* +*`+prjDescriptor.addPrimaryKeyField("budget");+`* `+...+` + +=== Mapping Using JAXB + +The JAXB generator generates a deployment descriptor based on +annotations and default values. + +Note: The JAXB 2.0 specification states that for the @XmlID annotation, +the following restrictions apply: + +The field type must be String. + +The use of composite keys is not allowed. + +The link:#Figure_58-35[Class Diagram] figure, as well as the following +four examples, demonstrate how to map one XML element to another using +JAXB annotations. + +[#Example 58-61]## *_Using JAXB - Object Model_* + +`+public class Employee {+` + +`+    @XmlAttribute(name="id")+` `+    public String id;+` +`+    public String name;+` + +`+    +`*`+@XmlElement(name="project-id")+`* `+    +`*`+@XmlIDREF+`* +`+    +`*`+public\'\' \'\'Project\'\' \'\'project;+`* `+    ...+` `+}+` + +`+public class Project {+` + +`+    +`*`+@XmlElement(name="project-id")+`* `+    +`*`+@XmlID+`* +`+    +`*`+public\'\' \'\'String\'\' \'\'id;+`* + +`+    public String name;+` `+    public String budget;+` `+    ...+` +`+}+` + +[#Example 58-62]## *_Using JAXB - Instance Document_* + +`+...+` `+    +``+Joe Brown+` `+    +`*`+99+`* +`++` `+    +``+Big Project+` +`+    +``+100,000+` `+...+` + +The following example shows how to create an +`+XMLObjectReferenceMapping+`, set a key on source, and then add the +mapping to the descriptor. + +[#Example 58-63]## *_Using JAXB - Project Class - Employee Descriptor_* + +`+...+` +`+XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();+` +`+emp.setAttributeName("project");+` +`+emp.setReferenceClass(Project.class);+` +*`+emp.addSourceToTargetKeyFieldAssociation("project-id/text()","@pid");+`* +`+empDescriptor.addMapping(emp);+` `+...+` + +This example shows how to define the primary key field on the +descriptor. + +[#Example 58-64]## *_Using JAXB - Project Class - Project Descriptor_* + +`+...+` `+XMLDescriptor prjDescriptor = new XMLDescriptor();+` +`+prjDescriptor.setJavaClass(Project.class);+` +*`+prjDescriptor.addPrimaryKeyField("@pid");+`* `+...+` + +For more information, see the following: + +* JAXB 2.0 Specification at +http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html +* link:Introduction%20to%20XML%20Projects%20(ELUG)[Introduction to XML +Projects] + +== XML Collection Reference Mapping + +The +`+org.eclipse.persistence.ox.mappings.XMLCollectionReferenceMapping+` is +a key on source-based aggregate mapping. It allows you to use +one-to-many mappings to map a given element in an XML document to +another element in that same XML document using one or more keys. + +With this mapping, EclipseLink provides support for foreign key grouping +elements. + +[width="100%",cols="<100%",] +|=== +|*Note:* You should group together elements mapped to keys. Also, +EclipseLink supports grouping elements that wrap all of the keys (not +the ones that wrap each individual key). +|=== + +The `+XMLCollectionReferenceMapping+` captures the following +information: + +* Attribute name. +* Reference class. +* Map of source and target key pairs, such as XPath values (see +link:#XPath_Support[XPath Support]) in the following format: + +`+["project-id/text()","@id"]+` + +Use the `+addSourceToTargetKeyFieldAssociation+` method to add a source +and target XPath pair to the map. + +* List of source keys to maintain order. + +The following class diagram, as well as the following three examples, +demonstrate how to map one element to another using a single key. + +[#Figure 58-36]## *_Class Diagram_* + +.Class Diagram +image::xmlcollrefmap.gif[Class Diagram,title="Class Diagram"] + +[#Example 58-65]## *_Using a Single Key - Instance Document_* + +`+...+` `+    +``+Joe Brown+` `+    +`*`+99+`* `+    +`*`+199+`* +`++` `+    +``+Big Project+` +`+    +``+100,000+` `++` +`+    +``+Bigger Project+` `+    +``+100,000,000+` `+...+` + +This example shows how to create an `+XMLCollectionReferenceMapping+`, +set a single key on source, and then add the mapping to the descriptor. + +[#Example 58-66]## *_Using a Single Key - Project Class - Employee +Descriptor_* + +`+...+` +`+XMLCollectionReferenceMapping prj = new XMLCollectionReferenceMapping();+` +`+prj.useCollectionClass(ArrayList.class);+` +`+prj.setAttributeName("projects");+` +`+prj.setReferenceClass(Project.class);+` +*`+prj.addSourceToTargetKeyFieldAssociation("project-id/text()","@id");+`* +`+empDescriptor.addMapping(prj);+` `+...+` + +The following example shows how to define the primary key field on the +descriptor. + +[#Example 58-67]## *_Using a Single Key - Project Class - Project +Descriptor_* + +`+...+` `+XMLDescriptor prjDescriptor = new XMLDescriptor();+` +`+prjDescriptor.setJavaClass(Project.class);+` +*`+prjDescriptor.addPrimaryKeyField("@id");+`* `+...+` + +The link:#Figure_58-36[Class Diagram] figure, as well as the following +three examples, demonstrate how to map one element to another using a +single key as a space-separated list. + +[#Example 58-68]## *_Using a Single Key as Space-Separated List - +Instance Document_* + +`+...+` `++` +`+    +``+Joe Brown+` `++` +`+    +``+Big Project+` `+    +``+100,000+` +`++` `+    +``+Bigger Project+` +`+    +``+100,000,000+` `+...+` + +The following example shows how to create an +`+XMLCollectionReferenceMapping+`, set a single key on source as a +space-separated list, and then add the mapping to the descriptor. + +[#Example 58-69]## *_Using a Single Key as Space-Separated List - +Project Class - Employee Descriptor_* + +`+...+` +`+XMLCollectionReferenceMapping prj = new XMLCollectionReferenceMapping();+` +`+prj.useCollectionClass(ArrayList.class);+` +`+prj.setAttributeName("projects");+` +`+prj.setReferenceClass(Project.class);+` +*`+prj.addSourceToTargetKeyFieldAssociation("project-ids","@id");+`* +`+empDescriptor.addMapping(prj);+` `+...+` + +This example shows how to define the primary key field on the +descriptor. + +[#Example 58-70]## *_Using a Single Key as Space-Separated List - +Project Class - Project Descriptor_* + +`+...+` `+XMLDescriptor prjDescriptor = new XMLDescriptor();+` +`+prjDescriptor.setJavaClass(Project.class);+` +*`+prjDescriptor.addPrimaryKeyField("@id");+`* `+...+` + +For more information, see +link:Configuring%20an%20XML%20Collection%20Reference%20Mapping%20(ELUG)[Configuring +an XML Collection Reference Mapping]. + +== XML Binary Data Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLBinaryDataMapping+` is a +direct mapping (see link:#XML_Direct_Mapping[XML Direct Mapping]) that +you use for handling binary data: it maps binary data in the object +model to XML. This allows you to enable writing of binary data directly +as inline binary data (base64 BLOB), or passing through as a MtOM or +SwaRef attachment. For more information, see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Storage_and_Retrieval_of_Binary_Data_in_XML[Optimizing +Storage and Retrieval of Binary Data in XML]. + +The `+XMLBinaryDataMapping+` also lets you make callbacks to an +attachment marshaller and unmarshaller (see +link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How_to_Use_an_Attachment_Marshaller_and_Unmarshaller[How +to Use an Attachment Marshaller and Unmarshaller]), as well as set XPath +(see link:#XPath_Support[XPath Support]). + +The following example shows how to create an `+XMLBinaryDataMapping+`, +set some of its properties, and then add the mapping to a descriptor. + +`+XMLBinaryDataMapping addressMapping = new XMLBinaryDataMapping();+` +`+addressMapping.setXPath("address");+` +`+addressMapping.setShouldInlineBinaryData(true);+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Binary%20Data%20Mapping%20(ELUG)[Configuring +an XML Binary Data Mapping] for more information. + +== XML Binary Data Collection Mapping + +The +`+org.eclipse.persistence.ox.mappings.XMLBinaryDataCollectionMapping+` +is very similar to the `+XMLBinaryDataMapping+` (see +link:#XML_Binary_Data_Mapping[XML Binary Data Mapping]), except that it +maps a collection of binary data in the object model to XML. + +For more information, see the following: + +* link:Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing_Storage_and_Retrieval_of_Binary_Data_in_XML[Optimizing +Storage and Retrieval of Binary Data in XML] +* link:#XML_Binary_Data_Mapping[XML Binary Data Mapping] + +The following example shows how to create an +`+XMLBinaryDataCollectionMapping+`, set some of its properties, and then +add the mapping to a descriptor. + +`+XMLBinaryDataCollectionMapping addressMapping = new XMLBinaryDataCollectionMapping();+` +`+addressMapping.setCollectionContentType(type);+` +`+addressMapping.setXPath("address");+` +`+addressMapping.setShouldInlineBinaryData(true);+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +For more information, see the following: + +* link:Configuring%20an%20XML%20Binary%20Data%20Collection%20Mapping%20(ELUG)[Configuring +an XML Binary Data Collection Mapping] +* link:#XML_Composite_Direct_Collection_Mapping[XML Composite Direct +Collection Mapping] + +== XML Fragment Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLFragmentMapping+` is a +direct mapping (see link:#XML_Direct_Mapping[XML Direct Mapping]) that +provides you with a means to keep a part of an XML tree as a node. + +This mapping also lets you set the XPath (see link:#XPath_Support[XPath +Support]). + +The following example shows how to create an `+XMLFragmentMapping+`, set +some of its properties, and then add the mapping to a descriptor. + +`+XMLFragmentMapping addressMapping = new XMLFragmentMapping();+` +`+addressMapping.setXPath("address");+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Fragment%20Mapping%20(ELUG)[Configuring an +XML Fragment Mapping] for more information. + +== XML Fragment Collection Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLFragmentCollectionMapping+` +is similar to the XMLFragmentMapping (see link:#XML_Fragment_Mapping[XML +Fragment Mapping]), except that it allows you to keep a part of an XML +tree as a collection of nodes. + +The following example shows how to create an `+XMLFragmentMapping+`, set +the XPath (see link:#XPath_Support[XPath Support]), and then add the +mapping to a descriptor. + +`+XMLFragmentCollectionMapping addressMapping = new XMLFragmentCollectionMapping();+` +`+addressMapping.setXPath("address");+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Fragment%20Collection%20Mapping%20(ELUG)[Configuring +an XML Fragment Collection Mapping] for more information. + +== XML Choice Object Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLChoiceObjectMapping+` lets +you map a single attribute to a number of different elements in an XML +document. + +Unlike other EclipseLink XML mappings, instead of setting a single +XPath, you use the `+addChoiceElement+` method to specify an XPath (see +link:#XPath_Support[XPath Support]), as well as the type associated with +this XPath, as follows: + +* `+xmlChoiceObjectMapping.addChoiceElement("mystring/text()", String.class);+` +* `+xmlChoiceObjectMapping.addChoiceElement("myaddress", Address.class);+` + +When any of these elements are encountered in the XML document, they are +read in and set in the object as correct types. + +Use this mapping to map to single choices or +link:#Substitution_Groups[substitution groups] in an XML schema. + +The following example shows how to create an `+XMLChoiceObjectMapping+`, +set the XPath, and then add the mapping to a descriptor. + +`+XMLChoiceObjectMapping addressMapping = new XMLChoiceObjectMapping();+` +`+addressMapping.setXPath("address", Address.class);+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Choice%20Object%20Mapping%20(ELUG)[Configuring +an XML Choice Object Mapping] for more information. + +== XML Choice Collection Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLChoiceCollectionMapping+` +is similar to the `+XMLChoiceObjectMapping+` (see +link:#XML_Choice_Object_Mapping[XML Choice Object Mapping]), except that +you use it to handle reading and writing of XML documents containing a +collection of choice or link:#Substitution_Groups[substitution group] +elements. + +The following example shows how to create an +`+XMLChoiceCollectionMapping+`, set the XPath (see +link:#XPath_Support[XPath Support]), and then add the mapping to a +descriptor. + +`+XMLChoiceCollectionMapping addressMapping = new XMLChoiceCollectionMapping();+` +`+addressMapping.setXPath("address", Address.class);+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Choice%20Collection%20Mapping%20(ELUG)[Configuring +an XML Choice Collection Mapping] for more information. + +== XML Any Attribute Mapping + +The `+org.eclipse.persistence.ox.mappings.XMLAnyAttributeMapping+` is a +database mapping that you can use to map to an attribute in an object to +any XML attributes contained on a specific element in the XML document. +The attribute in the object will contain a map of attribute values keyed +on a qualified name (`+javax.xml.namespace.QName+`). If one or more of +the attributes found on the specified element is already mapped to +another attribute in the object, EclipseLink will ignored that attribute +during the unmarshall operation. + +The `+XMLAnyAttributeMapping+` lets you set the XPath (see +link:#XPath_Support[XPath Support]), however, this operation is optional +for this type of mapping: if you do not set the XPath, the mapping will +look for any attribute children directly owned by the current element. + +The following example shows how to create an `+XMLAnyAttributeMapping+`, +set the XPath, and then add the mapping to a descriptor. + +`+XMLAnyAttributeMapping addressMapping = new XMLAnyAttributeMapping();+` +`+addressMapping.setXPath("address", Address.class);+` +`+descriptor.addMapping(addressMapping);+` `+...+` + +See +link:Configuring%20an%20XML%20Any%20Attribute%20Mapping%20(ELUG)[Configuring +an XML Any Attribute Mapping] for more information. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Projects_(ELUG).adoc new file mode 100644 index 00000000000..bcdec289fa4 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/Introduction_to_XML_Projects_(ELUG).adoc @@ -0,0 +1,523 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +*TOC* Special:Whatlinkshere_Introduction_to_XML_Projects_(ELUG)[Related +Topics] + +This section provides an overview of XML projects and their components. + +For information on project concepts and features common to more than one +type of EclipseLink projects, see +link:Introduction%20to%20Projects_(ELUG)[Introduction to Projects]. + +== XML Project Concepts + +Use an XML project for nontransactional, nonpersistent (in-memory) +conversions between Java objects and XML documents using JAXB (see +link:#EclipseLink_Support_for_Java_Architecture_for_XML_Binding_(JAXB)[EclipseLink +Support for Java Architecture for XML Binding (JAXB)] and +link:#JAXB_Validation[JAXB Validation]). The Workbench provides complete +support for creating XML projects. + +The EclipseLink runtime performs XML data conversion based on one or +more XML schemas. In an XML project, Workbench directly references +schemas in the deployment XML, and exports mappings configured with +respect to the schemas you specify. For information on how to use +Workbench with XML schemas, see +link:Using%20Workbench%20(ELUG)#Using_XML_Schemas[Using XML Schemas]. +For information on how EclipseLink supports XML namespaces, see +link:Introduction%20to%20Projects_(ELUG)#XML_Namespaces_Overview[XML +Namespaces Overview]. + +[#Table 52-1]## *_XML Project Components_* + +[width="100%",cols="<11%,<89%",options="header",] +|=== +|*Component* |*Supported Types* +|Data Source |None + +|Descriptors |For more information, see +link:Introduction%20to%20XML%20Descriptors%20(ELUG)#Descriptor_Concepts[Descriptor +Concepts]. + +|Mappings |For more information, see link:XML_Mappings_(ELUG)[XML +Mappings]. +|=== + +In an XML project, you do not use EclipseLink queries and expressions. + +=== EclipseLink Support for Java Architecture for XML Binding (JAXB) + +JAXB defines annotations to control the mapping of Java objects to XML, +but it also defines a default set of mappings. Using the defaults, +EclipseLink can marshall a set of objects into XML, and unmarshall an +XML documennt into objects. JAXB provides a standard Java object-to-XML +API. For more information, see +http://java.sun.com/xml/jaxb/index%7Cl[`+http://java.sun.com/xml/jaxb/index|l+`]. + +EclipseLink provides an extra layer of functions on top of JAXB. It +allows for the creation and subsequent manipulation of mappings (in the +form of a Workbench project) from an existing object model, without +requiring the recompilation of the JAXB object model. + +An essential component of this function is the EclipseLink JAXB +compiler. Using the EclipseLink JAXB compiler, you can generate both an +EclipseLink XML project and JAXB-compliant object model classes from +your XML schema. + +The EclipseLink JAXB compiler simplifies JAXB application development +with EclipseLink by automatically generating (see +link:Creating%20an%20XML%20Project%20(ELUG)[Creating an XML Project from +an XML Schema]) the required JAXB files (see +link:#Working_with_JAXB-Specific_Generated_Files[Working with +JAXB-Specific Generated Files]) from your XML schema (XSD) document. + +For more information on using the JAXB and EclipseLink-specific run-time +classes, see +link:#Using_EclipseLink_JAXB_Compiler-Generated_Files_at_Run_Time[Using +EclipseLink JAXB Compiler-Generated Files at Run Time]. + +==== Generating EclipseLink Project and XML Schema Using JAXB Annotations + +The EclipseLink JAXB compiler generates a EclipseLink project and an XML +schema using the following JAXB annotations: + +* `+XmlRootElement+` - Indicates that a class should be mapped to a +root-level element in a schema. The element name and namespace are +specified in this annotation. This is a class-level annotation. +* `+XmlElement+` - Indicates that a particular attribute on a Java class +should be mapped to an XML element in the schema. The name and namespace +can be specified by this annotation. This is a field-level annotation. +* `+XmlElementRef+` - Indicates that a particular attribute on a Java +class should be mapped in the schema to an XML element derived from the +attribute’s type. The name and namespace can be specified by this +annotation. This is a field-level annotation. For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Substitution_Groups[Substitution +Groups]. +* `+XmlElementRefs+` - Contains a collection of `+XmlElementRef+` +annotations. This is a field-level annotation. For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#Substitution_Groups[Substitution +Groups]. +* `+XmlAttribute+` - Indicates that the Java attribute should map to an +XML attribute in the schema. Name and namespace should be provided. This +is a field-level annotation. +* `+XmlElementWrapper+` - Specifies a wrapper element around another +element or attribute. You can use this annotation to create a grouping +element around a collection. This is a field-level annotation. +* `+XmlList+` - Indicates that a collection property should map to a +space-separated list in XML. This is a field-level annotation. +* `+XmlType+` - Defines the complex-type for a class. Using this +annotation’s `+propOrder+` property, you can specify the order in which +to map elements. The `+propOrder+` property also determines if the +schema should contain a `+sequence+` or an `+all+`. Depending on the +structure of the class, it will either map to a `+ComplexType+`, a +`+SimpleType+`, or a `+ComplexType+` with `+SimpleContent+`. This is a +class-level annotation. +* `+XmlTransient+` - Indicates that a mapping should not be generated +for a particular field. This is a marker annotation. This is a +field-level annotation. +* `+XmlSchema+` - Specifies the target namespace for a schema. You can +also use this annotation to configure namespace prefix mappings with the +`+XmlNs+` annotation. This is a package-level annotation. +* `+XmlNs+` - Appears only in an `+XmlSchema+` annotation to specify +namespace-prefix mappings. This is a package-level annotation. +* `+XmlValue+` - Maps an attribute to a text node under the parent class +(for example, an Xpath of "`text( )`"). Also indicates that the owning +class should map to either a `+SimpleType+` or a `+ComplexType+` with +`+SimpleContent+`. This is a field-level annotation. +* `+XmlEnum+` - Indicates that a JDK 1.5 `+Enum+` type should map to a +simple type with enumeration facets in the schema. The base schema type +is specified on this annotation. This is a field-level annotation. +* `+XmlEnumValue+` - Lets you specify the enumeration facets to be used +in the schema, if they are to be different from the string values of the +`+Enum+` constants specified in Java. This is a field-level annotation. +* `+XmlAccessorType+` - Specifies how the classes’ attributes should be +processed. This is a package- or class-level annotation. The following +are valid values: +** `+FIELD+` – Process all the public and/or private fields of the +class. +** `+PROPERTY+` – Process all the public or private get and set method +pairs on the class. +** `+PUBLIC_MEMBER+` – Process all the public fields and public get and +set method pairs on the class. +** `+NONE+` – Only process members that are annotated with JAXB +annotations. +* `+XmlAccessorOrder+` - Specifies the order in which properties are to +be processed. This is a package- or class-level annotation. The +following are valid values: +** `+DEFAULT+` +** `+ALPHABETICAL+`. +* `+XmlSchemaType+` - If specified at a property level, indicates the +schema type that should be used in schema generation. If used as part of +an `+XmlSchemaTypes+` annotation, overrides default schema types at a +package level. This is a property- or a package-level annotation. +* `+XmlSchemaTypes+` - Contains a collection of `+XmlSchemaType+` +annotations. Each one specifies a Java class and a XML schema type pair +that should be used as a default for this package. This is a +package-level annotation. +* `+XmlAnyAttribute+` - Specifies that a Map property should be mapped +to an `+xs:any+` attribute in the schema. For more information, see +link:Introduction%20to%20XML%20Mappings%20(ELUG)#XML_Any_Attribute_Mapping[XML +Any Attribute Mapping]. This is a filed-level annotation. + +For more information, see Chapter 8 of JAXB Specification at +http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html + +Note: The EclipseLink project is generated from a collection of +annotated Java classes with support for relationships, collection-style +mappings, and JDK 1.5 enumerations. + +The schema is generated from a set of annotated Java classes with +support for relationships. + +==== Working with JAXB-Specific Generated Files + +The EclipseLink JAXB compiler generates the following JAXB-specific +files from your XSD: + +* link:#Implementation_Classes[Implementation Classes] + +The JAXB runtime uses these files as specified by the JAXB +specification. + +All JAXB-specific files are generated in the output directory you +define, and in the subdirectories implied by the target package name you +define. For more information about EclipseLink JAXB binding compiler +options, see +link:Creating%20an%20XML%20Project%20(ELUG)#Creating_an_XML_Project_from_an_XML_SchemaCreating_an_XML_Project_from_an_XML_Schema[Creating +an XML Project from an XML SchemaCreating an XML Project from an XML +Schema]. + +Before you compile your generated classes, be sure to configure your IDE +classpath to include `+<+`_`+ECLIPSELINK_HOME+`_`+>\lib\xml.jar+`. For +an example, see +link:Using%20an%20Integrated%20Development%20Environment%20(ELUG)[Using +an Integrated Development Environment]. + +===== Implementation Classes + +All implementation classes are named according to the content, element, +or implementation `+name+` attribute defined in the XSD. + +The generated implementation classes are simple domain classes, with +private attributes for each JAXB property, and public `+get+` and +`+set+` methods that return or set attribute values. + +==== Using EclipseLink JAXB Compiler-Generated Files at Run Time + +At run time, you can access the EclipseLink JAXB compiler-generated +files by doing the following: + +* Using EclipseLink `+XMLContext+` (see +link:#How_to_Use_EclipseLink_XMLContext[How to Use EclipseLink +XMLContext]) +* Using EclipseLink `+XMLBinder+` (see +link:#How_to_Use_EclipseLink_XMLBinder[How to Use EclipseLink +XMLBinder]) +* Using EclipseLink `+JAXBContext+` (see +link:#How_to_Use_JAXBContext[How to Use JAXBContext]) + +===== How to Use EclipseLink XMLContext + +EclipseLink provides an `+org.eclipse.persistence.ox.XMLContext+` class +with which you can create instances of EclipseLink `+XMLMarshaller+`, +`+XMLUnmarshaller+`, `+XMLBinder+` (see +link:#How_to_Use_EclipseLink_XMLBinder[How to Use EclipseLink +XMLBinder]), and `+XMLValidator+`. + +The `+XMLContext+` is thread-safe. For example, if multiple threads +accessing the same `+XMLContext+` object request an `+XMLMarshaller+`, +each will receive their own instance of `+XMLMarshaller+`, so any state +that the `+XMLMarshaller+` maintains will be unique to that process. By +using the `+XMLContext+`, you can use EclipseLink XML in multithreaded +architectures, such as the binding layer for Web services. Create the +`+XMLContext+` using its constructor method and by passing in the +session name defined in the `+sessions.xml+` file, as the following +example shows: + +`+XMLContext context = new XMLContext("mysession");+` + +You can also create the `+XMLContext+` from multiple sessions using a +colon separated list of session names, as the following example shows: + +`+XMLContext context = new XMLContext("session1:session2:session3");+` + +Use the `+XMLContext+` to create an EclipseLink `+XMLMarshaller+`, +`+XMLUnmarshaller+`, `+XMLBinder+`, and `+XMLValidator+`, as follows: + +`+XMLMarshaller marshaller = context.createMarshaller();+` +`+marshaller.marshal(myObject, outputStream);+` +`+marshaller.setFormattedOutput(true);+` + +`+XMLUnmarshaller unmarshaller = context.createUnmarshaller();+` +`+Employee emp = (Employee)unmarshaller.unmarshal(new File("employee.xml"));+` + +`+XMLBinder binder = context.createBinder();+` +`+Address add = (Address)binder.unmarshal(myElement);+` + +`+XMLValidator validator = context.createValidator();+` +`+boolean isValid = validator.validate(emp);+` + +Using the `+XMLContext+` `+getDocumentPreservationPolicy+` method, you +can retrieve this context’s document preservation policy in a form of +the `+DocumentPreservationPolicy+` object. This object’s API lets you +specify the position of newly added to the node elements, as well as +disable the addition of new elements. + +===== How to Use Marshal and Unmarshal Events + +You can provide EclipseLink `+XMLMarshaller+` and `+XMLUnmarshaller+` +with additional functionality at run time by registering them with a +listener to handle specific event callbacks. This allows for extra +processing on a business object either immediately before, or +immediately after an object is written to or read from XML. + +There are two types of event callbacks that you can handle in two +different ways: + +[arabic] +. To handle listener-based callbacks, set an event handler on an +instance of `+XMLMarshaller+` or `+XMLUnmarshaller+` that implements a +required interface, such as `+XMLMarshalListener+` or +`+XMLUnmarshalListener+`. The events are triggered on the marshaller or +unmarshaller’s listener for any classes being marshalled or +unmarshalled. +. To handle class-specific callbacks, you need to provide the required +callback methods on your business objects. + +[width="100%",cols="<100%",] +|=== +|*Note:* If you specify both the listener and the business object +callbacks, the class-specific method will be invoked before the listener +event. +|=== + +This example shows how to create your custom event listeners. + +[#Example 52-33]## *_Implementing the EclipseLink XMLMarhsalListener and +XMLUnmarhsalListener Interfaces_* + +`+public class EmployeeMarshalListener implements XMLMarshalListener {+` + +`+   public void beforeMarshal(Object target) {+` +`+       // do something+` `+   }+` + +`+   public void afterMarshal(Object target) {+` +`+       // do something+` `+   }+` `+)+` + +`+public class EmployeeUnmarshalListener implements XMLUnmarshalListener {+` + +`+   public void beforeUnmarshal(Object target, Object parent) {+` +`+       // do something+` `+   }+` + +`+   public void afterUnmarshal(Object target, Object parent) {+` +`+       // do something+` `+   }+` `+}+` + +The following examples show how to use the listeners in your +application. + +[#Example 52-34]## *_Using the Marshal Listener_* + +`+...+` `+XMLMarshaller marshaller = context.createMarshaller();+` +`+marshaller.setMarshalListener(new EmployeeMarshalListener());+` +`+marshaller.marshal(myObject, System.out);+` `+...+` + +[#Example 52-35]## *_Using the Unmarshal Listener_* + +`+...+` `+XMLUnmarshaller unmarshaller = context.createUnmarshaller();+` +`+unmarshaller.setUnmarshalListener(new EmployeeUnmarshalListener());+` +`+Object myObject = unmarshaller.unmarshal(myFile); +` `+...+` + +===== How to Use EclipseLink XMLBinder + +`+XMLBinder+` is a run-time class that allows you to preserve a document +that you have unmarshalled, as well as to resynchronize that document +with the unmarshalled objects at any time. + +[width="100%",cols="<100%",] +|=== +|*Note:* This functionality is based on the JAXB binder API +(`+javax.xml.bind.Binder+`). This is an addition to the design-time +method of document preservation. +|=== + +When the `+XMLBinder+` unmarshalls XML nodes into mapping objects, and +then performs an update operation, it preserves not only the order of +elements, but also the comments from an original XML document using the +cached value. This way, both the returned node and the cached node are +identical and reflect the preserved document. When adding new elements, +EclipseLink `+XMLBinder+` places them at the correct location (relative +to other mapped content) in the node. + +When unmarshalling a document that contains only unmapped content, +setting some values and then marshalling, the `+XMLBinder+` adds new +elements before existing unmapped data, such as comments and processing +instructions. + +This example demonstrates how you can unmarshall a document using an +instance of an `+XMLBinder+`. + +[#Example 52-2]## *_Unmarshalling a Document Using XMLBinder_* + +`+XMLContext conext = new XMLContext(myProject);+` +`+XMLBinder binder = context.createBinder();+` +`+Employee emp = (Employee) binder.unmarshal(myDocument);+` + +In the preceding example, `+emp+` is the root object that was +unmarshalled from the provided document. The binder maintains references +to the original XML document as well as objects generated during the +unmarshall operation. + +The following example demonstrates how you can make changes to the +object (`+Employee+`) and update the XML document using an instance of +an `+XMLBinder+`. + +[#''Example 52-3]## *Making Changes to an Object and to Updating XML +Using XMLBinder*’’ + +`+...+` `+emp.setPhoneNumber("123-4567");+` `+binder.updateXML(emp);+` + +In the preceding example, the `+updateXML+` method will update the +cached node in the binder. Note that the cached node preserves the +document, including comments, as the following example shows: + +`+   +` `+      +``+John Smith +` `+      +``+123-4567+` `+   +` + +The following example demonstrates how you can obtain an associated node +for a subobject (`+Address+`) of the `+Employee+` using an instance of +an `+XMLBinder+`. + +[#Example 52-4]## *_Obtaining an Associated Node Using XMLBinder_* + +`+...+` `+Address addr = emp.getAddress();+` +`+Node addressNode = binder.getXMLNode(addr);+` + +In the preceding example, the returned node (`+addressNode+`) is the XML +node in the original XML document that was used to build this employee’s +`+Address+` object. + +This example demonstrates how you can make changes to an XML node and +update objects (`+Address+`) of the `+Employee+` using an instance of an +`+XMLBinder+`. + +[#Example 52-5]## *_Making Changes to an XML Node and Updating Objects +Using XMLBinder_* + +`+...+` `+addressNode.setAttribute("apt-no", "1527");+` +`+Address updatedAddressNode = binder.updateObject(addressNode);+` + +In the preceding example, the address returned from the binder operation +is the original Address object created during the unmarshall operation, +but now it contains the updated apartment number information from the +XML document. + +===== How to Use JAXBContext + +You can create an instance of `+JAXBContext+` from a collection of +classes that are to be bound to XML. This will generate a EclipseLink +project from the classes dynamically at run time. + +Using the instance of `+JAXBContext+` you can obtain `+Marshaller+` and +`+Unmarshaller+` instances to operate on those classes, as the +link:#Example_52-6[Creating and Using JAXBContext] example shows. Note +that this example assumes that you configure your application classpath +to include your domain object class files. + +[#Example 52-6]## *_Creating and Using JAXBContext_* + +`+Class[] classes = {Employee.class, Address.class, Department.class};+` +`+JAXBContext jaxbContext = JAXBContext.newInstance(classes);+` +`+Marshaller marshaller = jaxbContext.createMarshaller();+` +`+marshaller.marshal(myEmployee, myOutput);+` + +[cols="<",] +|=== +|*Note:* The `+JAXBContext+` object is thread-safe. +|=== + +===== How to Use JAXBElement + +EclipseLink lets you marshal to and unmarshal from `+JAXBElement+` +types. The `+javax.xml.bind.JAXBElement+` class provides access to the +following basic properties of an XML element: + +* its qualified name, which is composed of `+{target namespace}+` and +`+{name}+` +* its value, which is an instance of the Java class binding of its +`+{type definition}+` +* whether or not the element’s content is `+{nillable}+` + +EclipseLink supports the following JAXB element marshal API defined in +the `+Marshaller+`: + +* `+marshal(java.lang.Object jaxbElement, java.io.Writer writer)+` +* `+marshal(java.lang.Object jaxbElement, java.io.OutputStream os)+` +* `+marshal(java.lang.Object jaxbElement, org.xml.sax.ContentHandler)+` +* `+marshal(java.lang.Object jaxbElement, javax.xml.transform.Result)+` +* `+marshal(java.lang.Object jaxbElement, org.w3c.dom.Node)+` +* `+marshal(java.lang.Object jaxbElement, javax.xml.stream.XMLStreamWriter writer)+` + +[width="100%",cols="<100%",] +|=== +|*Note:* If the first parameter is not a `+JAXBElement+` instance, the +marshal operation will throw an +`+org.eclipse.persistence.exceptions.XMLMarshalException.MARSHAL_EXCEPTION+`. +|=== + +EclipseLink provides implementation of the following JAXB element +unmarshal API defined in the `+Unarshaller+`: + +* `+JAXBElement+``+unmarshal(org.w3c.dom.Node node, Class+``+declaredType)+` +* `+JAXBElement+``+unmarshal(javax.xml.transform.Source source, Class+``+declaredType)+` +* `+JAXBElement+``+unmarshal(javax.xml.stream.XMLStreamReader streamReader, Class+``+declaredType)+` +* `+JAXBElement+``+unmarshal(javax.xml.stream.XMLEventReader eventReader, Class+``+declaredType)+` + +=== JAXB Validation + +EclipseLink can validate both complete object trees and subtrees against +the XML schema that was used to generate the implementation classes. In +addition, EclipseLink will validate both root objects (objects that +correspond to the root element of the XML document) and nonroot objects +against the schema used to generate the object’s implementation class. + +When validating an object tree, EclipseLink performs the following +checks (in order): + +[arabic] +. Check that element appears in the document at the specified location. +. If *maxOccurs* or *minOccurs* is specified, check number of elements. +. If *type* is specified, check that element value satisfies the type +constraints. +. If a *fixed value* is specified, check that the element value matches +it. +. If *restrictions* (length, patterns, enumerations, and so on) are +specified, check that the element value satisfies it. +. If an *ID* type is specified during a `+validateRoot+` operation, +check that the ID value is unique in the document. +. If an *IDREF* type is specified during a `+validateRoot+` operation, +check that the ID referenced exists in the document. + +If validation errors are encountered, EclipseLink stops validating the +object tree and creates a `+ValidationEvent+` object, according to the +JAXB specification. If an error occurs in a subobject, EclipseLink will +not validate further down that object’s subtree. + +For more information on using EclipseLink XML to perform validation, see +link:#Using_EclipseLink_JAXB_Compiler-Generated_Files_at_Run_Time[Using +EclipseLink JAXB Compiler-Generated Files at Run Time]. + +For additional information on JAXB and validation, refer to the JAXB +specification at +http://java.sun.com/xml/jaxb/[`+http://java.sun.com/xml/jaxb/+`]. + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] +Category:_Release_1[Category: Release 1] Category:_Concept[Category: +Concept] Category:_XML[Category: XML] diff --git a/docs/docs.ug/src/main/asciidoc/xml/XML_Descriptors_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/XML_Descriptors_(ELUG).adoc new file mode 100644 index 00000000000..33704d9cd72 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/XML_Descriptors_(ELUG).adoc @@ -0,0 +1,21 @@ +== Creating and Configuring XML Descriptors + +The following sections contain general information about XML +descriptors, as well as detailed information on how to create and +configure these descriptors: + +* link:Introduction_to_XML_Descriptors_(ELUG)[Introduction to XML +Descriptors] + +* link:Creating_an_XML_Descriptor_(ELUG)[Creating an XML Descriptor] + +* link:Configuring_an_XML_Descriptor_(ELUG)[Configuring an XML +Descriptor] + +*Special:Whatlinkshere_XML_Descriptors_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/xml/XML_Mappings_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/XML_Mappings_(ELUG).adoc new file mode 100644 index 00000000000..45b79d7e869 --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/XML_Mappings_(ELUG).adoc @@ -0,0 +1,22 @@ +== Creating and Configuring XML Mappings + +An XML mapping transforms object data members to the XML nodes of an XML +document, whose structure is defined by an XML schema document (XSD). + +Consider the following sections: + +* link:Introduction_to_XML_Mappings_(ELUG)[Introduction to XML Mappings] +– describes each of the different EclipseLink XML mapping types and +important XML mapping concepts. + +* link:Configuring_an_XML_Mapping_(ELUG)[Configuring an XML Mapping] – +explains how to configure EclipseLink XML mapping options common to two +or more XML mapping types. + +*Special:Whatlinkshere_XML_Mappings_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/docs.ug/src/main/asciidoc/xml/XML_Projects_(ELUG).adoc b/docs/docs.ug/src/main/asciidoc/xml/XML_Projects_(ELUG).adoc new file mode 100644 index 00000000000..c4c5fb25fde --- /dev/null +++ b/docs/docs.ug/src/main/asciidoc/xml/XML_Projects_(ELUG).adoc @@ -0,0 +1,26 @@ +image:Elug_draft_icon.png[Image:Elug draft +icon.png,title="Image:Elug draft icon.png"] *For the latest EclipseLink +documentation, please see +http://www.eclipse.org/eclipselink/documentation/* + +''''' + +== Creating and Configuring XML Projects + +The following sections contain general information about XML projects, +as well as detailed information on how to create and configure these +projects: + +* link:Introduction_to_XML_Projects_(ELUG)[Introduction to XML Projects] + +* link:Creating_an_XML_Project_(ELUG)[Creating an XML Project] + +* link:Configuring_an_XML_Project_(ELUG)[Configuring an XML Project] + +*Special:Whatlinkshere_XML_Projects_(ELUG)[Related Topics]* + +''''' + +_link:EclipseLink_User's_Guide_Copyright_Statement[Copyright Statement]_ + +Category:_EclipseLink_User's_Guide[Category: EclipseLink User’s Guide] diff --git a/docs/pom.xml b/docs/pom.xml index a7696917fd1..e1041c3b44e 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -48,6 +48,7 @@ docs.jpa docs.moxy docs.solutions + docs.ug