[jboss-cvs] JBossAS SVN: r85948 - in projects/docs/enterprise: 4.2.7/Hibernate/Entity_Manager_User_Guide/en-US and 15 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Mar 16 22:30:06 EDT 2009
Author: irooskov at redhat.com
Date: 2009-03-16 22:30:05 -0400 (Mon, 16 Mar 2009)
New Revision: 85948
Modified:
projects/docs/enterprise/4.2.7/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml
projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml
projects/docs/enterprise/4.2.7/Installation_Guide/en-US/Post_Installation.xml
projects/docs/enterprise/4.2.7/readme/en-US/Release_Notes_CP07.xml
projects/docs/enterprise/4.3.4/Getting_Started/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Hibernate/Annotations_Reference_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Hibernate/Entity_Manager_User_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Hibernate/Reference_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Installation_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/JDK6_Compatibility_Notes/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Seam/Reference_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/Server_Configuration_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3.4/readme/en-US/Revision_History.xml
projects/docs/enterprise/4.3.5/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml
projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml
projects/docs/enterprise/4.3.5/Installation_Guide/en-US/Post_Installation.xml
projects/docs/enterprise/4.3.5/readme/en-US/Release_Notes_CP05.xml
Log:
updated release notes with new JIRAs added and updated Revison History files with revision dates and updated Hibernate books with general JIRA fixes
Modified: projects/docs/enterprise/4.2.7/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -1543,10 +1543,11 @@
<para>
In the above example, the <literal>night&area</literal> named query use the <literal>joinMapping</literal> result set mapping. This mapping returns 2 entities, <literal>Night</literal> and <literal>Area</literal>, each property is declared and associated to a column name, actually the column name retrieved by the query. Let's now see an implicit declaration of the property / column.
</para>
-<programlisting>@Entity<emphasis role="bold"> @SqlResultSetMapping(name="implicit",</emphasis>
- <emphasis role="bold">entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class))</emphasis>
- <emphasis role="bold">@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",</emphasis>
- <emphasis role="bold">resultSetMapping="implicit")</emphasis>
+<programlisting>
+ at Entity
+<emphasis role="bold">@SqlResultSetMapping(name="implicit", entities=@EntityResult(entityClass=org.hibernate.test. \annotations.query.SpaceShip.class))</emphasis>
+<emphasis role="bold">@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",</emphasis>
+<emphasis role="bold">resultSetMapping="implicit")</emphasis>
public class SpaceShip {
private String name;
private String model;
@@ -1579,7 +1580,12 @@
}
}
</programlisting>
+<note>
<para>
+ The escape character <emphasis>\</emphasis> has been used to escape a space charater that has been inserted in the above example in order to maintain readability of the code on paper.
+ </para>
+</note>
+ <para>
In this example, we only describe the entity member of the result set mapping. The property / column mappings is done using the entity mapping values. In this case the <literal>model</literal> property is bound to the <literal>model_txt </literal>column. If the association to a related entity involve a composite primary key, a <literal>@FieldResult</literal> element should be used for each foreign key column. The <literal>@FieldResult</literal> name is composed of the property name for the relationship, followed by a dot ("."), followed by the name or the field or property of the primary key.
</para>
<programlisting>@Entity
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -81,7 +81,7 @@
<section id="EJB_container_environment-Container_managed_entity_manager">
<title>Container-managed entity manager</title>
<para>
- The most common and widely used entity manager in a Java EE environment is the container-managed entity manager. In this mode, the container is responsible for the opening and closing of the entity manager (this is transparent to the application). It is also responsible for transaction boundaries. A container-managed entity manager is obtained in an application through dependency injection or through JNDI lookup, A container-managed entity manger requires the use of a JTA transaction.
+ The most common and widely used entity manager in a Java EE environment is the container-managed entity manager. In this mode, the container is responsible for the opening and closing of the entity manager (this is transparent to the application). It is also responsible for transaction boundaries. A container-managed entity manager is obtained in an application through dependency injection or through JNDI lookup. A container-managed entity manger requires the use of a JTA transaction.
</para>
</section>
@@ -101,7 +101,7 @@
The most common case is to bind the persistence context scope to the current transaction scope. This is only doable when JTA transactions are used: the persistence context is associated with the JTA transaction life cycle. When a entity manager is invoked, the persistence context is also opened, if there is no persistence context associated with the current JTA transaction. Otherwise, the associated persistence context is used. The persistence context ends when the JTA transaction completes. This means that during the JTA transaction, an application will be able to work on managed entities of the same persistence context. In other words, you don't have to pass the entity manager's persistence context across your EJB method calls, but simply use dependency injection or lookup whenever you need an entity manager.
</para>
<para>
- You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed entity manager: the persistence context is created when an entity manager is retrieved from dependency injection or JNDI lookup , and is kept until the container closes it after the completion of the <literal>Remove</literal> stateful session bean method. This is a perfect mechanism for implementing a "long" unit of work pattern. For example, if you have to deal with multiple user interaction cycles as a single unit of work (e.g. a wizard dialog that has to be fully completed), you usually model this as a unit of work from the point of view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern. JBoss Seam is a framework tht link together JSF and EJB3 around the notion of conversation and unit of wo!
rk. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to be commited or rollbacked. For application-managed entity manager only support the exctended persistence context.
+ You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed entity manager: the persistence context is created when an entity manager is retrieved from dependency injection or JNDI lookup , and is kept until the container closes it after the completion of the <literal>Remove</literal> stateful session bean method. This is a perfect mechanism for implementing a "long" unit of work pattern. For example, if you have to deal with multiple user interaction cycles as a single unit of work (e.g. a wizard dialog that has to be fully completed), you usually model this as a unit of work from the point of view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern. JBoss Seam is a framework that link together JSF and EJB3 around the notion of conversation and unit of w!
ork. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to be commited or rollbacked. For application-managed entity manager only support the extended persistence context.
</para>
<para>
A resource-local entity manager or an entity manager created with <literal>EntityManagerFactory.createEntityManager()</literal> (application-managed) has a one-to-one relationship with a persistence context. In other situations <emphasis>persistence context propagation</emphasis> occurs.
@@ -127,7 +127,7 @@
</listitem>
<listitem>
<para>
- If a stateful session bean with an extended persistence context calls as stateless session bean or a stateful session bean with a transaction-scoped persistence context in the same JTA transaction, the persistence context is propagated.
+ If a stateful session bean with an extended persistence context calls a stateless session bean or a stateful session bean with a transaction-scoped persistence context in the same JTA transaction, the persistence context is propagated.
</para>
</listitem>
<listitem>
@@ -153,7 +153,7 @@
<section id="Architecture-Java_SE_environments" revision="1">
<title>Java SE environments</title>
<para>
- In a Java SE environment only extented context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence context propagation are not supported in Java SE (you will have to propagate the persistence context yourself, e.g. using the thread local session pattern popular in the Hibernate community).
+ In a Java SE environment only extended context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence context propagation are not supported in Java SE (you will have to propagate the persistence context yourself, e.g. using the thread local session pattern popular in the Hibernate community).
</para>
<para>
Extended context means that a persistence context is created when the entity manager is retrieved (using <literal>EntityManagerFactory.createEntityManager(...)</literal> ) and closed when the entity manager is closed. Many resource-local transaction share the same persistence context, in this case.
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -63,7 +63,7 @@
entityManager.close();
</programlisting>
<para>
- The <literal>int</literal> value returned by the <literal>Query.executeUpdate()</literal> method indicate the number of entities effected by the operation. This may or may not correlate with the number of rows effected in the database. An EJB-QL bulk operation might result in multiple actual SQL statements being executed, for joined-subclass, for example. The returned number indicates the number of actual entities affected by the statement. Going back to the example of joined-subclass, a delete against one of the subclasses may actually result in deletes against not just the table to which that subclass is mapped, but also the "root" table and potentially joined-subclass tables further down the inheritence hierarchy.
+ The <literal>int</literal> value returned by the <literal>Query.executeUpdate()</literal> method indicate the number of entities affected by the operation. This may or may not correlate with theffectede number of rows effected in the database. An EJB-QL bulk operation might result in multiple actual SQL statements being executed, for joined-subclass, for example. The returned number indicates the number of actual entities affected by the statement. Going back to the example of joined-subclass, a delete against one of the subclasses may actually result in deletes against not just the table to which that subclass is mapped, but also the "root" table and potentially joined-subclass tables further down the inheritence hierarchy.
</para>
</sect1>
</chapter>
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -116,7 +116,7 @@
<term><code>class</code></term>
<listitem>
<para>
- The class element specifies a fully qualified class name that you will map. By default all properly annotated classes and all hbm.xml files found inside the archive are added to the persistence unit configuration. You can add some external entity through the class element though. As an extension to the specification, you can add a package name in the <literal><class></literal> element (eg <code><class>org.hibernate.eg</class></code>). Caution, the package will include the metadata defined at the package level (ie in <filename>package-info.java</filename>), it will not include all the classes of a given package.
+ The class element specifies a fully qualified class name that you will map. By default all properly annotated classes and all hbm.xml files found inside the archive are added to the persistence unit configuration. You can add some external entity through the class element though. As an extension to the specification, you can add a package name in the <literal><class></literal> element (eg <code><class>org.hibernate.eg</class></code>). Caution, specifying the package in the class element will add only the annotated classes.
</para>
</listitem>
</varlistentry>
@@ -130,7 +130,7 @@
</varlistentry>
</variablelist>
<para>
- Be sure to define the grammar definition in the <literal>persistence</literal> element since the EJB3 specification requires the schema validation. If the systemId ends with <literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. No internet access will be processed.
+ Be sure to define the grammar definition in the <literal>persistence</literal> element since the EJB3 specification requires the schema validation. If the systemId ends with <literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. No internet access will be performed.
</para>
<programlisting><persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -178,7 +178,7 @@
</listitem>
</itemizedlist>
<para>
- When <code>Persistence.createEntityManagerFactory()</code> is called, the persistence implementation will search your classpath for any <code>META-INF/persistence.xml</code> files using the <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method. Actually the <classname>Persistence</classname> class will look at all the Persistence Providers available in the classpath and ask each of them if they are responsible for the creation of the entity manager factory <literal>manager1</literal>. Each provider, from this list of resources, it will try to find an entity manager that matches the name you specify in the command line with what is specified in the persistence.xml file (of course the provider <literal>element</literal> must match the current persistent provider). If no persistence.xml with the correct name are found or if the expected persistence provider is not found, a <classname>PersistenceException</classname> is raised.
+ When <code>Persistence.createEntityManagerFactory()</code> is called, the persistence implementation will search your classpath for any <code>META-INF/persistence.xml</code> files using the <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method. Actually the <classname>Persistence</classname> class will look at all the Persistence Providers available in the classpath and ask each of them if they are responsible for the creation of the entity manager factory <literal>manager1</literal>. Each provider, from this list of resources, will try to find an entity manager that matches the name you specify in the command line with what is specified in the persistence.xml file (of course the provider <literal>element</literal> must match the current persistent provider). If no persistence.xml with the correct name is found or if the expected persistence provider is not found, a <classname>PersistenceException</classname> is raised.
</para>
<para>
Apart from Hibernate system-level settings, all the properties available in Hibernate can be set in <code>properties</code> element of the persistence.xml file or as an override in the map you pass to <code>createEntityManagerFactory()</code>. Please refer to the Hibernate reference documentation for a complete listing. There are however a couple of properties available in the EJB3 provider only.
@@ -268,7 +268,7 @@
hibernate.ejb.discard_pc_on_close
</entry>
<entry>
- If true, the persistence context will be discarded (think clear() when the method is called. Otherwise the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be sy,chronized with the database (default to false, ie wait the transaction completion)
+ If true, the persistence context will be discarded (think clear() when the method is called. Otherwise the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be synchronized with the database (default to false, ie wait the transaction completion)
</entry>
</row>
</tbody>
@@ -315,9 +315,9 @@
<para>
To ease the programmatic configuration, Hibernate Entity Manager provide a proprietary API. This API is very similar to the <classname>Configuration</classname> API and share the same concepts: <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the Hibernate reference guide for more detailed informations on how to use it.
</para>
- <para>
+ <!-- <para>
TODO: me more descriptive on some APIs like setDatasource()
- </para>
+ </para> -->
<programlisting>Ejb3Configuration cfg = new Ejb3Configuration();
EntityManagerFactory emf =
cfg.configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml
@@ -515,14 +515,14 @@
emf.close(); //close at application end
</programlisting>
<para>
- An entity manager factory is typically create at application initialization time and closed at application end. It's creation is an expensive process. For those who are familiar with Hibernate, an entity manager factory is very much like a session factory. Actually, an entity manager factory is a wrapper on top of a session factory. Calls to the entityManagerFactory are thread safe.
+ An entity manager factory is typically created at application initialization time and closed at application end. It's creation is an expensive process. For those who are familiar with Hibernate, an entity manager factory is very much like a session factory. Actually, an entity manager factory is a wrapper on top of a session factory. Calls to the entityManagerFactory are thread safe.
</para>
<para>
Thanks to the EntityManagerFactory, you can retrieve an extended entity manager. The extended entity manager keep the same persistence context for the lifetime of the entity manager: in other words, the entities are still managed between two transactions (unless you call entityManager.clear() in between). You can see an entity manager as a small wrapper on top of an Hibernate session.
</para>
- <para>
+ <!-- <para>
TODO explains emf.createEntityManager(Map)
- </para>
+ </para> -->
</section>
<section id="Setup_and_configuration-Various">
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -63,7 +63,7 @@
em.find( Cat.class, new Long(catId) );
</programlisting>
<para>
- In some cases, you don't really want to load the object state, but just having a reference to it (ie a proxy). You can get this reference using the <literal>getReference()</literal> method. This is especially useful to link a child to its parent wo having to load the parent.
+ In some cases, you don't really want to load the object state, but just having a reference to it (ie a proxy). You can get this reference using the <literal>getReference()</literal> method. This is especially useful to link a child to its parent without having to load the parent.
</para>
<programlisting>child = new Child();
child.SetName("Henry");
@@ -89,7 +89,7 @@
<title>Executing queries</title>
<para>
EJB3QL and SQL queries are represented by an instance of <classname>javax.persistence.Query</classname>. This interface offers methods for parameter binding, result set handling, and for execution of the query. Queries are always created using the current entity manager:
- </para>
+ </para><!--
<programlisting>List cats = em.createQuery(
"select cat from Cat as cat where cat.birthdate < ?1")
.setParameter(1, date, TemporalType.DATE)
@@ -109,7 +109,7 @@
"select cat.mother from Cat as cat where cat = ?1")
.setParameter(1, izi)
.getSingleResult();
-</programlisting>
+</programlisting> -->
<para>
A query is usually executed by invoking <methodname>getResultList()</methodname>. This method loads the resulting instances of the query completly into memory. Entity instances retrieved by a query are in persistent state. The <methodname>getSingleResult() </methodname>method offers a shortcut if you know your query will only return a single object.
</para>
@@ -118,17 +118,12 @@
<para>
An EJB3QL query queries can return tuples of objects if projection is used. Each result tuple is returned as an object array:
</para>
-<programlisting>Iterator kittensAndMothers = sess.createQuery(
- "select kitten, mother from Cat kitten join kitten.mother mother")
- .getResultList()
- .iterator();
-
-while ( kittensAndMothers.hasNext() ) {
- Object[] tuple = (Object[]) kittensAndMothers.next();
- Cat kitten = tuple[0];
- Cat mother = tuple[1];
- ....
-}
+<programlisting>Iterator<Cat[]> kittensAndMothers = em.createQuery("select kitten, mother from Cat kitten join kitten.mother mother").getResultList().iterator();
+while (kittensAndMothers.hasNext()) {
+ Cat[] tuple = kittensAndMothers.next();
+ Cat kitten = tuple[0];
+ Cat mother = tuple[1];
+}
</programlisting>
</section>
@@ -137,7 +132,7 @@
<para>
Queries may specify a particular property of an entity in the select clause, instead of an entity alias. You may call SQL aggregate functions as well. Returned non-transactional objects or aggregation results are considered "scalar" results and are not entities in persistent state (in other words, they are considered "read only"):
</para>
-<programlisting>Iterator results = em.createQuery(
+<programlisting>Iterator<Object[]> results = em.createQuery(
"select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
"group by cat.color")
.getResultList()
@@ -174,7 +169,7 @@
names.add("Fritz");
Query q = em.createQuery("select cat from DomesticCat cat where cat.name in (:namesList)");
q.setParameter("namesList", names);
-List cats = q.list();
+List cats = q.getResultList();
</programlisting>
</section>
@@ -205,8 +200,8 @@
Parameters are bound programatically to the named query, before it is executed:
</para>
<programlisting>Query q = em.createNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
-q.setString(1, name);
-q.setInt(2, minWeight);
+q.setParameter(1, name);
+q.setParameter(2, minWeight);
List cats = q.getResultList();
</programlisting>
<para>
@@ -348,7 +343,7 @@
<section id="Working_with_objects-Modifying_persistent_objects">
<title>Modifying persistent objects</title>
<para>
- Transactional managed instances (ie. objects loaded, saved, created or queried by the entity manager) may be manipulated by the application and any changes to persistent state will be persisted when the Entity manager is flushed (discussed later in this chapter). There is no need to call a particular method to make your modifications persistent. A straightforward wayt to update the state of an entity instance is to <methodname>find()</methodname> it, and then manipulate it directly, while the persistence context is open:
+ Transactional managed instances (ie. objects loaded, saved, created or queried by the entity manager) may be manipulated by the application and any changes to persistent state will be persisted when the Entity manager is flushed (discussed later in this chapter). There is no need to call a particular method to make your modifications persistent. A straightforward way to update the state of an entity instance is to <methodname>find()</methodname> it, and then manipulate it directly, while the persistence context is open:
</para>
<programlisting>Cat cat = em.find( Cat.class, new Long(69) );
cat.setName("PK");
@@ -545,7 +540,7 @@
It is possible to change the default behavior so that flush occurs less frequently. The <classname>FlushModeType</classname> for an entity manager defines two different modes: only flush at commit time or flush automatically using the explained routine unless <methodname>flush()</methodname> is called explicitly.
</para>
<programlisting>em = emf.createEntityManager();
-Transaction tx = em.getTransaction().begin();
+EntityTransaction tx = em.getTransaction().begin();
em.setFlushMode(FlushModeType.COMMIT); // allow queries to return stale state
Cat izi = em.find(Cat.class, id);
@@ -559,7 +554,7 @@
em.getTransaction().commit(); // flush occurs
</programlisting>
<para>
- During flush, an exception might happen (e.g. if a DML operation violates a constraint). TODO: Add link to exception handling.
+ During flush, an exception might happen (e.g. if a DML operation violates a constraint). <!--TODO: Add link to exception handling. -->
</para>
<para>
Hibernate provides more flush modes than the one described in the EJB3 specification. Please refer to the Hibernate core reference documentation for more informations.
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -4,7 +4,7 @@
<chapter id="EJB_QL_The_Object_Query_Language">
<title>EJB-QL: The Object Query Language</title>
<para>
- EJB3-QL has been heavily inspired by HQL, the native Hibernate Query Language. Both are therefore very close to SQL, but portable and independent of the database schema. People familiar with HQL shouldn't have any problem using EJB-QL. Actually, you use the same query API for EJB-QL and HQL queries. Portable EJB3 applications however should stick to EJB-QL or similar vendor extensions are needed.
+ EJB3-QL has been heavily inspired by HQL, the native Hibernate Query Language. Both are therefore very close to SQL, but portable and independent of the database schema. People familiar with HQL shouldn't have any problem using EJB-QL. Actually, you use the same query API for EJB-QL and HQL queries. Portable EJB3 applications however should stick to EJB-QL or similar vendor extensions when needed in order to remain portable.
</para>
<sect1 id="EJB_QL_The_Object_Query_Language-Case_Sensitivity"><title>Case Sensitivity</title>
<para>
@@ -82,9 +82,9 @@
<para>
Note that the <literal>fetch</literal> construct may not be used in queries called using <literal>scroll()</literal> or <literal>iterate()</literal>. Nor should <literal>fetch</literal> be used together with <literal>setMaxResults()</literal> or <literal>setFirstResult()</literal>. It is possible to create a cartesian product by join fetching more than one collection in a query (as in the example above), be careful the result of this product isn't bigger than you expect. Join fetching multiple collection roles also sometimes gives unexpected results for bag mappings, so be careful about how you formulate your queries in this case.
</para>
- <para>
+<!-- <para>
TODO: The last statement is useless and typical developer thinking, please elaborate. The word "sometimes" should never appear in any technical documentation.
- </para>
+ </para> -->
<para>
If you are using property-level lazy fetching (with bytecode instrumentation), it is possible to force Hibernate to fetch the lazy properties immediately (in the first query) using <literal>fetch all properties</literal>. This is Hibernate specific option:
</para>
@@ -179,7 +179,7 @@
</listitem>
</itemizedlist>
<para>
- You may use arithmetic operators, concatenation, and recognized SQL functions in the select clause (dpending on configured dialect, HQL specific feature):
+ You may use arithmetic operators, concatenation, and recognized SQL functions in the select clause (depending on configured dialect, HQL specific feature):
</para>
<programlisting>select cat.weight + sum(kitten.weight)
from Cat cat
@@ -422,7 +422,7 @@
<programlisting>select cat from Player p where 3 > all elements(p.scores)</programlisting>
<programlisting>select cat from Show show where 'fizard' in indices(show.acts)</programlisting>
<para>
- Note that these constructs - <literal>size</literal>, <literal>elements</literal>, <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, <literal>minelement</literal>, <literal>maxelement</literal> - may only be used in the where clause in Hibernate3.
+ Note that these constructs - <literal>size</literal>, <literal>elements</literal>, <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, <literal>minelement</literal>, <literal>maxelement</literal> - may only be used in the where clause in Hibernate.
</para>
<para>
In HQL, elements of indexed collections (arrays, lists, maps) may be referred to by index (in a where clause only):
@@ -575,7 +575,7 @@
</para>
</sect1><sect1 id="EJB_QL_The_Object_Query_Language-EJB_QL_examples"><title>EJB-QL examples</title>
<para>
- Hibernate queries can be quite powerful and complex. In fact, the power of the query language is one of Hibernate's main selling points (and now EJB-QL). Here are some example queries very similar to queries that I used on a recent project. Note that most queries you will write are much simpler than these!
+ Hibernate queries can be quite powerful and complex. In fact, the power of the query language is one of Hibernate's main selling points (and now EJB-QL). Here are some example queries. Note that most queries you will write are much simpler than these.
</para>
<para>
The following query returns the order id, number of items and total value of the order for all unpaid orders for a particular customer and given minimum total value, ordering the results by total value. In determining the prices, it uses the current catalog. The resulting SQL query, against the <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</literal>, <literal>CATALOG</literal> and <literal>PRICE</literal> tables has four inner joins and an (uncorrelated) subselect.
@@ -589,18 +589,18 @@
where order.paid = false
and order.customer = :customer
and price.product = product
- and catalog.effectiveDate < sysdate
+ and catalog.effectiveDate < current_date()
and catalog.effectiveDate >= all (
select cat.effectiveDate
from Catalog as cat
- where cat.effectiveDate < sysdate
+ where cat.effectiveDate < current_date()
)
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc
</programlisting>
<para>
- What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was really more like this:
+ The above example can be condensed into code which is simpler to read and maintain:
</para>
<programlisting>select order.id, sum(price.amount), count(item)
from Order as order
@@ -636,7 +636,7 @@
order by status.sortOrder
</programlisting>
<para>
- If I would have mapped the <literal>statusChanges</literal> collection as a list, instead of a set, the query would have been much simpler to write.
+ If the <literal>statusChanges</literal> collection was mapped as a list, instead of a set, the query would have been much simpler to write.
</para>
<programlisting>select count(payment), status.name
from Payment as payment
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -4,51 +4,55 @@
<chapter id="Native_query">
<title>Native query</title>
<para>
- You may also express queries in the native SQL dialect of your database. This is useful if you want to utilize database specific features such as query hints or the CONNECT BY option in Oracle. It also provides a clean migration path from a direct SQL/JDBC based application to Hibernate. Note that Hibernate3 allows you to specify handwritten SQL (including stored procedures) for all create, update, delete, and load operations (please refer to the reference guide for more information.)
+ You may also express queries in the native SQL dialect of your database. This is useful if you want to utilize database specific features such as query hints or the CONNECT BY option in Oracle. It also provides a clean migration path from a direct SQL/JDBC based application to Hibernate. Note that Hibernate allows you to specify handwritten SQL (including stored procedures) for all create, update, delete, and load operations (please refer to the reference guide for more information.)
</para>
<sect1 id="Native_query-Expressing_the_resultset"><title>Expressing the resultset</title>
<para>
To use a SQL query, you need to describe the SQL resultset, this description will help the <literal>EntityManager</literal> to map your columns onto entity properties. This is done using the <literal>@SqlResultSetMapping</literal> annotation. Each <literal>@SqlResultSetMapping </literal>has a name wich is used when creating a SQL query on <literal>EntityManager</literal>.
</para>
-<programlisting>@SqlResultSetMapping(name="GetNightAndArea", entities={
- @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
- @FieldResult(name="id", column="nid"),
- @FieldResult(name="duration", column="night_duration"),
- @FieldResult(name="date", column="night_date"),
- @FieldResult(name="area", column="area_id")
- }),
- @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
- @FieldResult(name="id", column="aid"),
- @FieldResult(name="name", column="name")
- })
- }
+<programlisting>
+ at SqlResultSetMapping(name="GetNightAndArea", entities={
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Night.class, fields
+= {
+ at FieldResult(name="id", column="nid"),
+ at FieldResult(name="duration", column="night_duration"),
+ at FieldResult(name="date", column="night_date"),
+ at FieldResult(name="area", column="area_id")
+}),
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Area.class, fields
+= {
+ at FieldResult(name="id", column="aid"),
+ at FieldResult(name="name", column="name")
+})
+}
)
-
-//or
+
@SqlResultSetMapping(name="defaultSpaceShip",
- entities=@EntityResult(name="org.hibernate.test.annotations.query.SpaceShip"))
+entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class))
</programlisting>
<para>
You can also define scalar results and even mix entity results and scalar results
</para>
-<programlisting>@SqlResultSetMapping(name="ScalarAndEntities",
- entities={
- @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
- @FieldResult(name="id", column="nid"),
- @FieldResult(name="duration", column="night_duration"),
- @FieldResult(name="date", column="night_date"),
- @FieldResult(name="area", column="area_id")
- }),
- @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
- @FieldResult(name="id", column="aid"),
- @FieldResult(name="name", column="name")
- })
- },
- columns={
- @ColumnResult(name="durationInSec")
- }
-)
-</programlisting>
+<programlisting>
+ at SqlResultSetMapping(name="ScalarAndEntities",
+entities={
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Night.class,
+fields = {
+ at FieldResult(name="id", column="nid"),
+ at FieldResult(name="duration", column="night_duration"),
+ at FieldResult(name="date", column="night_date"),
+ at FieldResult(name="area", column="area_id")
+}),
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Area.class,
+fields = {
+ at FieldResult(name="id", column="aid"),
+ at FieldResult(name="name", column="name")
+})
+},
+columns={
+ at ColumnResult(name="durationInSec")
+}
+) </programlisting>
<para>
The SQL query will then have to return a column alias <literal>durationInSec</literal>.
</para>
@@ -56,9 +60,9 @@
Please refer to the Hibernate Annotations reference guide for more information about <literal>@SqlResultSetMapping.</literal>
</para>
</sect1><sect1 id="Native_query-Using_native_SQL_Queries"><title>Using native SQL Queries</title>
- <para>
+<!-- <para>
TODO: This sounds like a dupe...
- </para>
+ </para> -->
<para>
Now that the result set is described, we are capable of executing the native SQL query. <literal>EntityManager</literal> provides all the needed APIs. The first method is to use a SQL resultset name to do the binding, the second one uses the entity default mapping (the column returned has to have the same names as the one used in the mapping). A third one (not yet supported by Hibernate entity manager), returns pure scalar results.
</para>
Modified: projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -7,7 +7,7 @@
The most important point about Hibernate Entity Manager and concurrency control is that it is very easy to understand. Hibernate Entity Manager directly uses JDBC connections and JTA resources without adding any additional locking behavior. We highly recommend you spend some time with the JDBC, ANSI, and transaction isolation specification of your database management system. Hibernate Entity Manager only adds automatic versioning but does not lock objects in memory or change the isolation level of your database transactions. Basically, use Hibernate Entity Manager like you would use direct JDBC (or JTA/CMT) with your database resources.
</para>
<para>
- We start the discussion of concurrency control in Hibernate with the granularity of <literal>EntityManagerFactory</literal>, and <literal>EntityManager</literal>, as well as database transactions and long units of work..
+ We start the discussion of concurrency control in Hibernate with the granularity of <literal>EntityManagerFactory</literal>, and <literal>EntityManager</literal>, as well as database transactions and long units of work.
</para>
<para>
In this chapter, and unless explicitly expressed, we will mix and match the concept of entity manager and persistence context. One is an API and programming object, the other a definition of scope. However, keep in mind the essential difference. A persistence context is usually bound to a JTA transaction in Java EE, and a persistence context starts and ends at transaction boundaries (transaction-scoped) unless you use an extended entity manager. Please refer to <xref linkend="EJB_container_environment-Persistence_context_scope" /> for more information.
@@ -83,9 +83,9 @@
<para>
Both <emphasis>entitymanager-per-request-with-detached-objects</emphasis> and <emphasis>entitymanager-per-application-transaction</emphasis> have advantages and disadvantages, we discuss them later in this chapter in the context of optimistic concurrency control.
</para>
- <para>
+<!-- <para>
TODO: This note should probably come later.
- </para>
+ </para> -->
</sect2><sect2 id="Entity_manager_and_transaction_scopes-Considering_object_identity"><title>Considering object identity</title>
<para>
An application may concurrently access the same persistent state in two different persistence contexts. However, an instance of a managed class is never shared between two persistence contexts. Hence there are two different notions of identity:
@@ -257,9 +257,9 @@
<para>
In other words, all you have to do in a managed environment is to inject the <literal>EntityManager</literal>, do your data access work, and leave the rest to the container. Transaction boundaries are set declaratively in the annotations or deployment descriptors of your session beans. The lifecycle of the entity manager and persistence context is completely managed by the container.
</para>
- <para>
+<!-- <para>
TODO: The following paragraph is very confusing, especially the beginning...
- </para>
+ </para> -->
<para>
When using particular Hibernate native APIs, one caveat has to be remembered: <literal>after_statement</literal> connection release mode. Due to a silly limitation of the JTA spec, it is not possible for Hibernate to automatically clean up any unclosed <literal>ScrollableResults</literal> or <literal>Iterator</literal> instances returned by <literal>scroll()</literal> or <literal>iterate()</literal>. You <emphasis>must</emphasis> release the underlying database cursor by calling <literal>ScrollableResults.close()</literal> or <literal>Hibernate.close(Iterator)</literal> explicity from a <literal>finally</literal> block. (Of course, most applications can easily avoid using <literal>scroll()</literal> or <literal>iterate()</literal> at all from the CMT code.)
</para>
@@ -273,7 +273,7 @@
<itemizedlist>
<listitem>
<para>
- IllegalArgumentException: something wrong happen
+ IllegalArgumentException: Some argument/parameter/property is not permitted, unrecognized, or in the wrong format.
</para>
</listitem>
<listitem>
@@ -296,7 +296,7 @@
The <literal>HibernateException</literal>, which wraps most of the errors that can occur in a Hibernate persistence layer, is an unchecked exception. Note that Hibernate might also throw other unchecked exceptions which are not a <literal>HibernateException</literal>. These are, again, not recoverable and appropriate action should be taken.
</para>
<para>
- Hibernate wraps <literal>SQLException</literal>s thrown while interacting with the database in a <literal>JDBCException</literal>. In fact, Hibernate will attempt to convert the eexception into a more meningful subclass of <literal>JDBCException</literal>. The underlying <literal>SQLException</literal> is always available via <literal>JDBCException.getCause()</literal>. Hibernate converts the <literal>SQLException</literal> into an appropriate <literal>JDBCException</literal> subclass using the <literal>SQLExceptionConverter</literal> attached to the <literal>SessionFactory</literal>. By default, the <literal>SQLExceptionConverter</literal> is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the <literal>SQLExceptionConverterFactory</literal> class for details). The standard <literal>JDBCException</literal> subtypes are:
+ Hibernate wraps <literal>SQLException</literal>s thrown while interacting with the database in a <literal>JDBCException</literal>. In fact, Hibernate will attempt to convert the exception into a more meningful subclass of <literal>JDBCException</literal>. The underlying <literal>SQLException</literal> is always available via <literal>JDBCException.getCause()</literal>. Hibernate converts the <literal>SQLException</literal> into an appropriate <literal>JDBCException</literal> subclass using the <literal>SQLExceptionConverter</literal> attached to the <literal>SessionFactory</literal>. By default, the <literal>SQLExceptionConverter</literal> is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the <literal>SQLExceptionConverterFactory</literal> class for details). The standard <literal>JDBCException</literal> subtypes are:
</para>
<itemizedlist spacing="compact">
<listitem>
Modified: projects/docs/enterprise/4.2.7/Installation_Guide/en-US/Post_Installation.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Installation_Guide/en-US/Post_Installation.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/Installation_Guide/en-US/Post_Installation.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -41,6 +41,11 @@
-Xms1303m -Xmx1303m -XX:PermSize=256m -XX:MaxPermSize=256m
</programlisting>
</para>
+ <important>
+ <para>
+ If you are running the JBoss Enterprise Application Platform on a Windows operating system then you will need to update the <filename>run.bat</filename> file with the above values instead.
+ </para>
+ </important>
</section>
<section id="Post-Installation">
<title>
Modified: projects/docs/enterprise/4.2.7/readme/en-US/Release_Notes_CP07.xml
===================================================================
--- projects/docs/enterprise/4.2.7/readme/en-US/Release_Notes_CP07.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.2.7/readme/en-US/Release_Notes_CP07.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -461,9 +461,24 @@
<itemizedlist>
<listitem>
<para>
-
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1782">JBPAPP-1782</ulink>: Chapter 7.2 named <emphasis>Adjusting memory settings</emphasis> within the <filename>Installation Guide</filename>, stated that a user should modify the <filename>run.conf</filename> file in order to increase the avaliable memory to the program. This however is incorrect when running the JBoss Enterprise Application Platform on a Windows operating system. In this case the <filename>run.bat</filename> file should be modified and the documentation now reflects this difference.
</para>
</listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1768">JBPAPP-1768</ulink>: On page 37 of the PDF for the <filename>Hibernate Annotations Reference Guide</filename> book an example would overflow the allowed area because of the way in which the software to build the PDF deals with names that contain full stops without spaces. In order to rectify the overflow problem without invalidating the code that a user could copy and paste into a command line window, the file name has been broken with the escape character <code>\</code> used to escape a hard return.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1689">JBPAPP-1689</ulink>: The <filename>Server Configuration Guide</filename>, section 16.5 contained an error reguarding the name of the directory where JBoss Web is deployed. Instead of the path to the <filename>jboss-service.xml</filename> file being <filename>JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml</filename> it should be <filename>JBOSS_HOME/server/all/deploy/jboss-web.deployer/META-INF/jboss-service.xml</filename>. For this CP release, the file path has been corrected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1584">JBPAPP-1584</ulink>: Information about the <classname>LdapExtLoginModule</classname> was missing from the documentation on login modules within the <filename>Server Configuration Guide</filename>. The information about this module has now been added to the <emphasis>Using JBoss Login Modules</emphasis> section of the guide.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</formalpara>
Modified: projects/docs/enterprise/4.3.4/Getting_Started/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Getting_Started/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Getting_Started/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/Hibernate/Annotations_Reference_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Hibernate/Annotations_Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Hibernate/Annotations_Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/Hibernate/Entity_Manager_User_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Hibernate/Entity_Manager_User_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Hibernate/Entity_Manager_User_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/Hibernate/Reference_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Hibernate/Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Hibernate/Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/Installation_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Installation_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Installation_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/JDK6_Compatibility_Notes/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/JDK6_Compatibility_Notes/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/JDK6_Compatibility_Notes/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,11 +8,11 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date>10th of October 2008</date>
+ <date>Fri Oct 10 2008</date>
<author>
<firstname>Isaac</firstname>
<surname>Rooskov</surname>
- <email>irooskov at redhat.com</email>
+ <email>irooskov at redhat.com</email>
</author>
<revdescription>
<simplelist>
@@ -23,4 +23,3 @@
</revhistory>
</simpara>
</appendix>
-
Modified: projects/docs/enterprise/4.3.4/Seam/Reference_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Seam/Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Seam/Reference_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/Server_Configuration_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/Server_Configuration_Guide/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/Server_Configuration_Guide/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.4/readme/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3.4/readme/en-US/Revision_History.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.4/readme/en-US/Revision_History.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -8,7 +8,7 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
- <date></date>
+ <date>Fri Feb 27 2009</date>
<author>
<firstname></firstname>
<surname></surname>
Modified: projects/docs/enterprise/4.3.5/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Annotations_Reference_Guide/en-US/Entity.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -1543,10 +1543,11 @@
<para>
In the above example, the <literal>night&area</literal> named query use the <literal>joinMapping</literal> result set mapping. This mapping returns 2 entities, <literal>Night</literal> and <literal>Area</literal>, each property is declared and associated to a column name, actually the column name retrieved by the query. Let's now see an implicit declaration of the property / column.
</para>
-<programlisting>@Entity<emphasis role="bold"> @SqlResultSetMapping(name="implicit",</emphasis>
- <emphasis role="bold">entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class))</emphasis>
- <emphasis role="bold">@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",</emphasis>
- <emphasis role="bold">resultSetMapping="implicit")</emphasis>
+<programlisting>
+ at Entity
+<emphasis role="bold">@SqlResultSetMapping(name="implicit", entities=@EntityResult(entityClass=org.hibernate.test. \annotations.query.SpaceShip.class))</emphasis>
+<emphasis role="bold">@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",</emphasis>
+<emphasis role="bold">resultSetMapping="implicit")</emphasis>
public class SpaceShip {
private String name;
private String model;
@@ -1579,7 +1580,12 @@
}
}
</programlisting>
+<note>
<para>
+ The escape character <emphasis>\</emphasis> has been used to escape a space charater that has been inserted in the above example in order to maintain readability of the code on paper.
+ </para>
+</note>
+ <para>
In this example, we only describe the entity member of the result set mapping. The property / column mappings is done using the entity mapping values. In this case the <literal>model</literal> property is bound to the <literal>model_txt </literal>column. If the association to a related entity involve a composite primary key, a <literal>@FieldResult</literal> element should be used for each foreign key column. The <literal>@FieldResult</literal> name is composed of the property name for the relationship, followed by a dot ("."), followed by the name or the field or property of the primary key.
</para>
<programlisting>@Entity
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Architecture.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -81,7 +81,7 @@
<section id="EJB_container_environment-Container_managed_entity_manager">
<title>Container-managed entity manager</title>
<para>
- The most common and widely used entity manager in a Java EE environment is the container-managed entity manager. In this mode, the container is responsible for the opening and closing of the entity manager (this is transparent to the application). It is also responsible for transaction boundaries. A container-managed entity manager is obtained in an application through dependency injection or through JNDI lookup, A container-managed entity manger requires the use of a JTA transaction.
+ The most common and widely used entity manager in a Java EE environment is the container-managed entity manager. In this mode, the container is responsible for the opening and closing of the entity manager (this is transparent to the application). It is also responsible for transaction boundaries. A container-managed entity manager is obtained in an application through dependency injection or through JNDI lookup. A container-managed entity manger requires the use of a JTA transaction.
</para>
</section>
@@ -101,7 +101,7 @@
The most common case is to bind the persistence context scope to the current transaction scope. This is only doable when JTA transactions are used: the persistence context is associated with the JTA transaction life cycle. When a entity manager is invoked, the persistence context is also opened, if there is no persistence context associated with the current JTA transaction. Otherwise, the associated persistence context is used. The persistence context ends when the JTA transaction completes. This means that during the JTA transaction, an application will be able to work on managed entities of the same persistence context. In other words, you don't have to pass the entity manager's persistence context across your EJB method calls, but simply use dependency injection or lookup whenever you need an entity manager.
</para>
<para>
- You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed entity manager: the persistence context is created when an entity manager is retrieved from dependency injection or JNDI lookup , and is kept until the container closes it after the completion of the <literal>Remove</literal> stateful session bean method. This is a perfect mechanism for implementing a "long" unit of work pattern. For example, if you have to deal with multiple user interaction cycles as a single unit of work (e.g. a wizard dialog that has to be fully completed), you usually model this as a unit of work from the point of view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern. JBoss Seam is a framework tht link together JSF and EJB3 around the notion of conversation and unit of wo!
rk. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to be commited or rollbacked. For application-managed entity manager only support the exctended persistence context.
+ You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed entity manager: the persistence context is created when an entity manager is retrieved from dependency injection or JNDI lookup , and is kept until the container closes it after the completion of the <literal>Remove</literal> stateful session bean method. This is a perfect mechanism for implementing a "long" unit of work pattern. For example, if you have to deal with multiple user interaction cycles as a single unit of work (e.g. a wizard dialog that has to be fully completed), you usually model this as a unit of work from the point of view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern. JBoss Seam is a framework that link together JSF and EJB3 around the notion of conversation and unit of w!
ork. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to be commited or rollbacked. For application-managed entity manager only support the extended persistence context.
</para>
<para>
A resource-local entity manager or an entity manager created with <literal>EntityManagerFactory.createEntityManager()</literal> (application-managed) has a one-to-one relationship with a persistence context. In other situations <emphasis>persistence context propagation</emphasis> occurs.
@@ -127,7 +127,7 @@
</listitem>
<listitem>
<para>
- If a stateful session bean with an extended persistence context calls as stateless session bean or a stateful session bean with a transaction-scoped persistence context in the same JTA transaction, the persistence context is propagated.
+ If a stateful session bean with an extended persistence context calls a stateless session bean or a stateful session bean with a transaction-scoped persistence context in the same JTA transaction, the persistence context is propagated.
</para>
</listitem>
<listitem>
@@ -153,7 +153,7 @@
<section id="Architecture-Java_SE_environments" revision="1">
<title>Java SE environments</title>
<para>
- In a Java SE environment only extented context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence context propagation are not supported in Java SE (you will have to propagate the persistence context yourself, e.g. using the thread local session pattern popular in the Hibernate community).
+ In a Java SE environment only extended context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence context propagation are not supported in Java SE (you will have to propagate the persistence context yourself, e.g. using the thread local session pattern popular in the Hibernate community).
</para>
<para>
Extended context means that a persistence context is created when the entity manager is retrieved (using <literal>EntityManagerFactory.createEntityManager(...)</literal> ) and closed when the entity manager is closed. Many resource-local transaction share the same persistence context, in this case.
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Batch.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -63,7 +63,7 @@
entityManager.close();
</programlisting>
<para>
- The <literal>int</literal> value returned by the <literal>Query.executeUpdate()</literal> method indicate the number of entities effected by the operation. This may or may not correlate with the number of rows effected in the database. An EJB-QL bulk operation might result in multiple actual SQL statements being executed, for joined-subclass, for example. The returned number indicates the number of actual entities affected by the statement. Going back to the example of joined-subclass, a delete against one of the subclasses may actually result in deletes against not just the table to which that subclass is mapped, but also the "root" table and potentially joined-subclass tables further down the inheritence hierarchy.
+ The <literal>int</literal> value returned by the <literal>Query.executeUpdate()</literal> method indicate the number of entities affected by the operation. This may or may not correlate with theffectede number of rows effected in the database. An EJB-QL bulk operation might result in multiple actual SQL statements being executed, for joined-subclass, for example. The returned number indicates the number of actual entities affected by the statement. Going back to the example of joined-subclass, a delete against one of the subclasses may actually result in deletes against not just the table to which that subclass is mapped, but also the "root" table and potentially joined-subclass tables further down the inheritence hierarchy.
</para>
</sect1>
</chapter>
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Configuration.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -116,7 +116,7 @@
<term><code>class</code></term>
<listitem>
<para>
- The class element specifies a fully qualified class name that you will map. By default all properly annotated classes and all hbm.xml files found inside the archive are added to the persistence unit configuration. You can add some external entity through the class element though. As an extension to the specification, you can add a package name in the <literal><class></literal> element (eg <code><class>org.hibernate.eg</class></code>). Caution, the package will include the metadata defined at the package level (ie in <filename>package-info.java</filename>), it will not include all the classes of a given package.
+ The class element specifies a fully qualified class name that you will map. By default all properly annotated classes and all hbm.xml files found inside the archive are added to the persistence unit configuration. You can add some external entity through the class element though. As an extension to the specification, you can add a package name in the <literal><class></literal> element (eg <code><class>org.hibernate.eg</class></code>). Caution, specifying the package in the class element will add only the annotated classes.
</para>
</listitem>
</varlistentry>
@@ -130,7 +130,7 @@
</varlistentry>
</variablelist>
<para>
- Be sure to define the grammar definition in the <literal>persistence</literal> element since the EJB3 specification requires the schema validation. If the systemId ends with <literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. No internet access will be processed.
+ Be sure to define the grammar definition in the <literal>persistence</literal> element since the EJB3 specification requires the schema validation. If the systemId ends with <literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. No internet access will be performed.
</para>
<programlisting><persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -178,7 +178,7 @@
</listitem>
</itemizedlist>
<para>
- When <code>Persistence.createEntityManagerFactory()</code> is called, the persistence implementation will search your classpath for any <code>META-INF/persistence.xml</code> files using the <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method. Actually the <classname>Persistence</classname> class will look at all the Persistence Providers available in the classpath and ask each of them if they are responsible for the creation of the entity manager factory <literal>manager1</literal>. Each provider, from this list of resources, it will try to find an entity manager that matches the name you specify in the command line with what is specified in the persistence.xml file (of course the provider <literal>element</literal> must match the current persistent provider). If no persistence.xml with the correct name are found or if the expected persistence provider is not found, a <classname>PersistenceException</classname> is raised.
+ When <code>Persistence.createEntityManagerFactory()</code> is called, the persistence implementation will search your classpath for any <code>META-INF/persistence.xml</code> files using the <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method. Actually the <classname>Persistence</classname> class will look at all the Persistence Providers available in the classpath and ask each of them if they are responsible for the creation of the entity manager factory <literal>manager1</literal>. Each provider, from this list of resources, will try to find an entity manager that matches the name you specify in the command line with what is specified in the persistence.xml file (of course the provider <literal>element</literal> must match the current persistent provider). If no persistence.xml with the correct name is found or if the expected persistence provider is not found, a <classname>PersistenceException</classname> is raised.
</para>
<para>
Apart from Hibernate system-level settings, all the properties available in Hibernate can be set in <code>properties</code> element of the persistence.xml file or as an override in the map you pass to <code>createEntityManagerFactory()</code>. Please refer to the Hibernate reference documentation for a complete listing. There are however a couple of properties available in the EJB3 provider only.
@@ -268,7 +268,7 @@
hibernate.ejb.discard_pc_on_close
</entry>
<entry>
- If true, the persistence context will be discarded (think clear() when the method is called. Otherwise the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be sy,chronized with the database (default to false, ie wait the transaction completion)
+ If true, the persistence context will be discarded (think clear() when the method is called. Otherwise the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be synchronized with the database (default to false, ie wait the transaction completion)
</entry>
</row>
</tbody>
@@ -315,9 +315,9 @@
<para>
To ease the programmatic configuration, Hibernate Entity Manager provide a proprietary API. This API is very similar to the <classname>Configuration</classname> API and share the same concepts: <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the Hibernate reference guide for more detailed informations on how to use it.
</para>
- <para>
+ <!-- <para>
TODO: me more descriptive on some APIs like setDatasource()
- </para>
+ </para> -->
<programlisting>Ejb3Configuration cfg = new Ejb3Configuration();
EntityManagerFactory emf =
cfg.configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml
@@ -515,14 +515,14 @@
emf.close(); //close at application end
</programlisting>
<para>
- An entity manager factory is typically create at application initialization time and closed at application end. It's creation is an expensive process. For those who are familiar with Hibernate, an entity manager factory is very much like a session factory. Actually, an entity manager factory is a wrapper on top of a session factory. Calls to the entityManagerFactory are thread safe.
+ An entity manager factory is typically created at application initialization time and closed at application end. It's creation is an expensive process. For those who are familiar with Hibernate, an entity manager factory is very much like a session factory. Actually, an entity manager factory is a wrapper on top of a session factory. Calls to the entityManagerFactory are thread safe.
</para>
<para>
Thanks to the EntityManagerFactory, you can retrieve an extended entity manager. The extended entity manager keep the same persistence context for the lifetime of the entity manager: in other words, the entities are still managed between two transactions (unless you call entityManager.clear() in between). You can see an entity manager as a small wrapper on top of an Hibernate session.
</para>
- <para>
+ <!-- <para>
TODO explains emf.createEntityManager(Map)
- </para>
+ </para> -->
</section>
<section id="Setup_and_configuration-Various">
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Entitymanagerapi.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -63,7 +63,7 @@
em.find( Cat.class, new Long(catId) );
</programlisting>
<para>
- In some cases, you don't really want to load the object state, but just having a reference to it (ie a proxy). You can get this reference using the <literal>getReference()</literal> method. This is especially useful to link a child to its parent wo having to load the parent.
+ In some cases, you don't really want to load the object state, but just having a reference to it (ie a proxy). You can get this reference using the <literal>getReference()</literal> method. This is especially useful to link a child to its parent without having to load the parent.
</para>
<programlisting>child = new Child();
child.SetName("Henry");
@@ -89,7 +89,7 @@
<title>Executing queries</title>
<para>
EJB3QL and SQL queries are represented by an instance of <classname>javax.persistence.Query</classname>. This interface offers methods for parameter binding, result set handling, and for execution of the query. Queries are always created using the current entity manager:
- </para>
+ </para><!--
<programlisting>List cats = em.createQuery(
"select cat from Cat as cat where cat.birthdate < ?1")
.setParameter(1, date, TemporalType.DATE)
@@ -109,7 +109,7 @@
"select cat.mother from Cat as cat where cat = ?1")
.setParameter(1, izi)
.getSingleResult();
-</programlisting>
+</programlisting> -->
<para>
A query is usually executed by invoking <methodname>getResultList()</methodname>. This method loads the resulting instances of the query completly into memory. Entity instances retrieved by a query are in persistent state. The <methodname>getSingleResult() </methodname>method offers a shortcut if you know your query will only return a single object.
</para>
@@ -118,17 +118,12 @@
<para>
An EJB3QL query queries can return tuples of objects if projection is used. Each result tuple is returned as an object array:
</para>
-<programlisting>Iterator kittensAndMothers = sess.createQuery(
- "select kitten, mother from Cat kitten join kitten.mother mother")
- .getResultList()
- .iterator();
-
-while ( kittensAndMothers.hasNext() ) {
- Object[] tuple = (Object[]) kittensAndMothers.next();
- Cat kitten = tuple[0];
- Cat mother = tuple[1];
- ....
-}
+<programlisting>Iterator<Cat[]> kittensAndMothers = em.createQuery("select kitten, mother from Cat kitten join kitten.mother mother").getResultList().iterator();
+while (kittensAndMothers.hasNext()) {
+ Cat[] tuple = kittensAndMothers.next();
+ Cat kitten = tuple[0];
+ Cat mother = tuple[1];
+}
</programlisting>
</section>
@@ -137,7 +132,7 @@
<para>
Queries may specify a particular property of an entity in the select clause, instead of an entity alias. You may call SQL aggregate functions as well. Returned non-transactional objects or aggregation results are considered "scalar" results and are not entities in persistent state (in other words, they are considered "read only"):
</para>
-<programlisting>Iterator results = em.createQuery(
+<programlisting>Iterator<Object[]> results = em.createQuery(
"select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
"group by cat.color")
.getResultList()
@@ -174,7 +169,7 @@
names.add("Fritz");
Query q = em.createQuery("select cat from DomesticCat cat where cat.name in (:namesList)");
q.setParameter("namesList", names);
-List cats = q.list();
+List cats = q.getResultList();
</programlisting>
</section>
@@ -205,8 +200,8 @@
Parameters are bound programatically to the named query, before it is executed:
</para>
<programlisting>Query q = em.createNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
-q.setString(1, name);
-q.setInt(2, minWeight);
+q.setParameter(1, name);
+q.setParameter(2, minWeight);
List cats = q.getResultList();
</programlisting>
<para>
@@ -348,7 +343,7 @@
<section id="Working_with_objects-Modifying_persistent_objects">
<title>Modifying persistent objects</title>
<para>
- Transactional managed instances (ie. objects loaded, saved, created or queried by the entity manager) may be manipulated by the application and any changes to persistent state will be persisted when the Entity manager is flushed (discussed later in this chapter). There is no need to call a particular method to make your modifications persistent. A straightforward wayt to update the state of an entity instance is to <methodname>find()</methodname> it, and then manipulate it directly, while the persistence context is open:
+ Transactional managed instances (ie. objects loaded, saved, created or queried by the entity manager) may be manipulated by the application and any changes to persistent state will be persisted when the Entity manager is flushed (discussed later in this chapter). There is no need to call a particular method to make your modifications persistent. A straightforward way to update the state of an entity instance is to <methodname>find()</methodname> it, and then manipulate it directly, while the persistence context is open:
</para>
<programlisting>Cat cat = em.find( Cat.class, new Long(69) );
cat.setName("PK");
@@ -545,7 +540,7 @@
It is possible to change the default behavior so that flush occurs less frequently. The <classname>FlushModeType</classname> for an entity manager defines two different modes: only flush at commit time or flush automatically using the explained routine unless <methodname>flush()</methodname> is called explicitly.
</para>
<programlisting>em = emf.createEntityManager();
-Transaction tx = em.getTransaction().begin();
+EntityTransaction tx = em.getTransaction().begin();
em.setFlushMode(FlushModeType.COMMIT); // allow queries to return stale state
Cat izi = em.find(Cat.class, id);
@@ -559,7 +554,7 @@
em.getTransaction().commit(); // flush occurs
</programlisting>
<para>
- During flush, an exception might happen (e.g. if a DML operation violates a constraint). TODO: Add link to exception handling.
+ During flush, an exception might happen (e.g. if a DML operation violates a constraint). <!--TODO: Add link to exception handling. -->
</para>
<para>
Hibernate provides more flush modes than the one described in the EJB3 specification. Please refer to the Hibernate core reference documentation for more informations.
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_ejbql.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -4,7 +4,7 @@
<chapter id="EJB_QL_The_Object_Query_Language">
<title>EJB-QL: The Object Query Language</title>
<para>
- EJB3-QL has been heavily inspired by HQL, the native Hibernate Query Language. Both are therefore very close to SQL, but portable and independent of the database schema. People familiar with HQL shouldn't have any problem using EJB-QL. Actually, you use the same query API for EJB-QL and HQL queries. Portable EJB3 applications however should stick to EJB-QL or similar vendor extensions are needed.
+ EJB3-QL has been heavily inspired by HQL, the native Hibernate Query Language. Both are therefore very close to SQL, but portable and independent of the database schema. People familiar with HQL shouldn't have any problem using EJB-QL. Actually, you use the same query API for EJB-QL and HQL queries. Portable EJB3 applications however should stick to EJB-QL or similar vendor extensions when needed in order to remain portable.
</para>
<sect1 id="EJB_QL_The_Object_Query_Language-Case_Sensitivity"><title>Case Sensitivity</title>
<para>
@@ -82,9 +82,9 @@
<para>
Note that the <literal>fetch</literal> construct may not be used in queries called using <literal>scroll()</literal> or <literal>iterate()</literal>. Nor should <literal>fetch</literal> be used together with <literal>setMaxResults()</literal> or <literal>setFirstResult()</literal>. It is possible to create a cartesian product by join fetching more than one collection in a query (as in the example above), be careful the result of this product isn't bigger than you expect. Join fetching multiple collection roles also sometimes gives unexpected results for bag mappings, so be careful about how you formulate your queries in this case.
</para>
- <para>
+<!-- <para>
TODO: The last statement is useless and typical developer thinking, please elaborate. The word "sometimes" should never appear in any technical documentation.
- </para>
+ </para> -->
<para>
If you are using property-level lazy fetching (with bytecode instrumentation), it is possible to force Hibernate to fetch the lazy properties immediately (in the first query) using <literal>fetch all properties</literal>. This is Hibernate specific option:
</para>
@@ -179,7 +179,7 @@
</listitem>
</itemizedlist>
<para>
- You may use arithmetic operators, concatenation, and recognized SQL functions in the select clause (dpending on configured dialect, HQL specific feature):
+ You may use arithmetic operators, concatenation, and recognized SQL functions in the select clause (depending on configured dialect, HQL specific feature):
</para>
<programlisting>select cat.weight + sum(kitten.weight)
from Cat cat
@@ -422,7 +422,7 @@
<programlisting>select cat from Player p where 3 > all elements(p.scores)</programlisting>
<programlisting>select cat from Show show where 'fizard' in indices(show.acts)</programlisting>
<para>
- Note that these constructs - <literal>size</literal>, <literal>elements</literal>, <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, <literal>minelement</literal>, <literal>maxelement</literal> - may only be used in the where clause in Hibernate3.
+ Note that these constructs - <literal>size</literal>, <literal>elements</literal>, <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, <literal>minelement</literal>, <literal>maxelement</literal> - may only be used in the where clause in Hibernate.
</para>
<para>
In HQL, elements of indexed collections (arrays, lists, maps) may be referred to by index (in a where clause only):
@@ -575,7 +575,7 @@
</para>
</sect1><sect1 id="EJB_QL_The_Object_Query_Language-EJB_QL_examples"><title>EJB-QL examples</title>
<para>
- Hibernate queries can be quite powerful and complex. In fact, the power of the query language is one of Hibernate's main selling points (and now EJB-QL). Here are some example queries very similar to queries that I used on a recent project. Note that most queries you will write are much simpler than these!
+ Hibernate queries can be quite powerful and complex. In fact, the power of the query language is one of Hibernate's main selling points (and now EJB-QL). Here are some example queries. Note that most queries you will write are much simpler than these.
</para>
<para>
The following query returns the order id, number of items and total value of the order for all unpaid orders for a particular customer and given minimum total value, ordering the results by total value. In determining the prices, it uses the current catalog. The resulting SQL query, against the <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</literal>, <literal>CATALOG</literal> and <literal>PRICE</literal> tables has four inner joins and an (uncorrelated) subselect.
@@ -589,18 +589,18 @@
where order.paid = false
and order.customer = :customer
and price.product = product
- and catalog.effectiveDate < sysdate
+ and catalog.effectiveDate < current_date()
and catalog.effectiveDate >= all (
select cat.effectiveDate
from Catalog as cat
- where cat.effectiveDate < sysdate
+ where cat.effectiveDate < current_date()
)
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc
</programlisting>
<para>
- What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was really more like this:
+ The above example can be condensed into code which is simpler to read and maintain:
</para>
<programlisting>select order.id, sum(price.amount), count(item)
from Order as order
@@ -636,7 +636,7 @@
order by status.sortOrder
</programlisting>
<para>
- If I would have mapped the <literal>statusChanges</literal> collection as a list, instead of a set, the query would have been much simpler to write.
+ If the <literal>statusChanges</literal> collection was mapped as a list, instead of a set, the query would have been much simpler to write.
</para>
<programlisting>select count(payment), status.name
from Payment as payment
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Query_native.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -4,51 +4,55 @@
<chapter id="Native_query">
<title>Native query</title>
<para>
- You may also express queries in the native SQL dialect of your database. This is useful if you want to utilize database specific features such as query hints or the CONNECT BY option in Oracle. It also provides a clean migration path from a direct SQL/JDBC based application to Hibernate. Note that Hibernate3 allows you to specify handwritten SQL (including stored procedures) for all create, update, delete, and load operations (please refer to the reference guide for more information.)
+ You may also express queries in the native SQL dialect of your database. This is useful if you want to utilize database specific features such as query hints or the CONNECT BY option in Oracle. It also provides a clean migration path from a direct SQL/JDBC based application to Hibernate. Note that Hibernate allows you to specify handwritten SQL (including stored procedures) for all create, update, delete, and load operations (please refer to the reference guide for more information.)
</para>
<sect1 id="Native_query-Expressing_the_resultset"><title>Expressing the resultset</title>
<para>
To use a SQL query, you need to describe the SQL resultset, this description will help the <literal>EntityManager</literal> to map your columns onto entity properties. This is done using the <literal>@SqlResultSetMapping</literal> annotation. Each <literal>@SqlResultSetMapping </literal>has a name wich is used when creating a SQL query on <literal>EntityManager</literal>.
</para>
-<programlisting>@SqlResultSetMapping(name="GetNightAndArea", entities={
- @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
- @FieldResult(name="id", column="nid"),
- @FieldResult(name="duration", column="night_duration"),
- @FieldResult(name="date", column="night_date"),
- @FieldResult(name="area", column="area_id")
- }),
- @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
- @FieldResult(name="id", column="aid"),
- @FieldResult(name="name", column="name")
- })
- }
+<programlisting>
+ at SqlResultSetMapping(name="GetNightAndArea", entities={
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Night.class, fields
+= {
+ at FieldResult(name="id", column="nid"),
+ at FieldResult(name="duration", column="night_duration"),
+ at FieldResult(name="date", column="night_date"),
+ at FieldResult(name="area", column="area_id")
+}),
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Area.class, fields
+= {
+ at FieldResult(name="id", column="aid"),
+ at FieldResult(name="name", column="name")
+})
+}
)
-
-//or
+
@SqlResultSetMapping(name="defaultSpaceShip",
- entities=@EntityResult(name="org.hibernate.test.annotations.query.SpaceShip"))
+entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class))
</programlisting>
<para>
You can also define scalar results and even mix entity results and scalar results
</para>
-<programlisting>@SqlResultSetMapping(name="ScalarAndEntities",
- entities={
- @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
- @FieldResult(name="id", column="nid"),
- @FieldResult(name="duration", column="night_duration"),
- @FieldResult(name="date", column="night_date"),
- @FieldResult(name="area", column="area_id")
- }),
- @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
- @FieldResult(name="id", column="aid"),
- @FieldResult(name="name", column="name")
- })
- },
- columns={
- @ColumnResult(name="durationInSec")
- }
-)
-</programlisting>
+<programlisting>
+ at SqlResultSetMapping(name="ScalarAndEntities",
+entities={
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Night.class,
+fields = {
+ at FieldResult(name="id", column="nid"),
+ at FieldResult(name="duration", column="night_duration"),
+ at FieldResult(name="date", column="night_date"),
+ at FieldResult(name="area", column="area_id")
+}),
+ at EntityResult(entityClass=org.hibernate.test.annotations.query.Area.class,
+fields = {
+ at FieldResult(name="id", column="aid"),
+ at FieldResult(name="name", column="name")
+})
+},
+columns={
+ at ColumnResult(name="durationInSec")
+}
+) </programlisting>
<para>
The SQL query will then have to return a column alias <literal>durationInSec</literal>.
</para>
@@ -56,9 +60,9 @@
Please refer to the Hibernate Annotations reference guide for more information about <literal>@SqlResultSetMapping.</literal>
</para>
</sect1><sect1 id="Native_query-Using_native_SQL_Queries"><title>Using native SQL Queries</title>
- <para>
+<!-- <para>
TODO: This sounds like a dupe...
- </para>
+ </para> -->
<para>
Now that the result set is described, we are capable of executing the native SQL query. <literal>EntityManager</literal> provides all the needed APIs. The first method is to use a SQL resultset name to do the binding, the second one uses the entity default mapping (the column returned has to have the same names as the one used in the mapping). A third one (not yet supported by Hibernate entity manager), returns pure scalar results.
</para>
Modified: projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Hibernate/Entity_Manager_User_Guide/en-US/Transactions.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -7,7 +7,7 @@
The most important point about Hibernate Entity Manager and concurrency control is that it is very easy to understand. Hibernate Entity Manager directly uses JDBC connections and JTA resources without adding any additional locking behavior. We highly recommend you spend some time with the JDBC, ANSI, and transaction isolation specification of your database management system. Hibernate Entity Manager only adds automatic versioning but does not lock objects in memory or change the isolation level of your database transactions. Basically, use Hibernate Entity Manager like you would use direct JDBC (or JTA/CMT) with your database resources.
</para>
<para>
- We start the discussion of concurrency control in Hibernate with the granularity of <literal>EntityManagerFactory</literal>, and <literal>EntityManager</literal>, as well as database transactions and long units of work..
+ We start the discussion of concurrency control in Hibernate with the granularity of <literal>EntityManagerFactory</literal>, and <literal>EntityManager</literal>, as well as database transactions and long units of work.
</para>
<para>
In this chapter, and unless explicitly expressed, we will mix and match the concept of entity manager and persistence context. One is an API and programming object, the other a definition of scope. However, keep in mind the essential difference. A persistence context is usually bound to a JTA transaction in Java EE, and a persistence context starts and ends at transaction boundaries (transaction-scoped) unless you use an extended entity manager. Please refer to <xref linkend="EJB_container_environment-Persistence_context_scope" /> for more information.
@@ -83,9 +83,9 @@
<para>
Both <emphasis>entitymanager-per-request-with-detached-objects</emphasis> and <emphasis>entitymanager-per-application-transaction</emphasis> have advantages and disadvantages, we discuss them later in this chapter in the context of optimistic concurrency control.
</para>
- <para>
+<!-- <para>
TODO: This note should probably come later.
- </para>
+ </para> -->
</sect2><sect2 id="Entity_manager_and_transaction_scopes-Considering_object_identity"><title>Considering object identity</title>
<para>
An application may concurrently access the same persistent state in two different persistence contexts. However, an instance of a managed class is never shared between two persistence contexts. Hence there are two different notions of identity:
@@ -257,9 +257,9 @@
<para>
In other words, all you have to do in a managed environment is to inject the <literal>EntityManager</literal>, do your data access work, and leave the rest to the container. Transaction boundaries are set declaratively in the annotations or deployment descriptors of your session beans. The lifecycle of the entity manager and persistence context is completely managed by the container.
</para>
- <para>
+<!-- <para>
TODO: The following paragraph is very confusing, especially the beginning...
- </para>
+ </para> -->
<para>
When using particular Hibernate native APIs, one caveat has to be remembered: <literal>after_statement</literal> connection release mode. Due to a silly limitation of the JTA spec, it is not possible for Hibernate to automatically clean up any unclosed <literal>ScrollableResults</literal> or <literal>Iterator</literal> instances returned by <literal>scroll()</literal> or <literal>iterate()</literal>. You <emphasis>must</emphasis> release the underlying database cursor by calling <literal>ScrollableResults.close()</literal> or <literal>Hibernate.close(Iterator)</literal> explicity from a <literal>finally</literal> block. (Of course, most applications can easily avoid using <literal>scroll()</literal> or <literal>iterate()</literal> at all from the CMT code.)
</para>
@@ -273,7 +273,7 @@
<itemizedlist>
<listitem>
<para>
- IllegalArgumentException: something wrong happen
+ IllegalArgumentException: Some argument/parameter/property is not permitted, unrecognized, or in the wrong format.
</para>
</listitem>
<listitem>
@@ -296,7 +296,7 @@
The <literal>HibernateException</literal>, which wraps most of the errors that can occur in a Hibernate persistence layer, is an unchecked exception. Note that Hibernate might also throw other unchecked exceptions which are not a <literal>HibernateException</literal>. These are, again, not recoverable and appropriate action should be taken.
</para>
<para>
- Hibernate wraps <literal>SQLException</literal>s thrown while interacting with the database in a <literal>JDBCException</literal>. In fact, Hibernate will attempt to convert the eexception into a more meningful subclass of <literal>JDBCException</literal>. The underlying <literal>SQLException</literal> is always available via <literal>JDBCException.getCause()</literal>. Hibernate converts the <literal>SQLException</literal> into an appropriate <literal>JDBCException</literal> subclass using the <literal>SQLExceptionConverter</literal> attached to the <literal>SessionFactory</literal>. By default, the <literal>SQLExceptionConverter</literal> is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the <literal>SQLExceptionConverterFactory</literal> class for details). The standard <literal>JDBCException</literal> subtypes are:
+ Hibernate wraps <literal>SQLException</literal>s thrown while interacting with the database in a <literal>JDBCException</literal>. In fact, Hibernate will attempt to convert the exception into a more meningful subclass of <literal>JDBCException</literal>. The underlying <literal>SQLException</literal> is always available via <literal>JDBCException.getCause()</literal>. Hibernate converts the <literal>SQLException</literal> into an appropriate <literal>JDBCException</literal> subclass using the <literal>SQLExceptionConverter</literal> attached to the <literal>SessionFactory</literal>. By default, the <literal>SQLExceptionConverter</literal> is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the <literal>SQLExceptionConverterFactory</literal> class for details). The standard <literal>JDBCException</literal> subtypes are:
</para>
<itemizedlist spacing="compact">
<listitem>
Modified: projects/docs/enterprise/4.3.5/Installation_Guide/en-US/Post_Installation.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Installation_Guide/en-US/Post_Installation.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/Installation_Guide/en-US/Post_Installation.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -41,6 +41,11 @@
-Xms1303m -Xmx1303m -XX:PermSize=256m -XX:MaxPermSize=256m
</programlisting>
</para>
+ <important>
+ <para>
+ If you are running the JBoss Enterprise Application Platform on a Windows operating system then you will need to update the <filename>run.bat</filename> file with the above values instead.
+ </para>
+ </important>
</section>
<section id="Post-Installation">
<title>
Modified: projects/docs/enterprise/4.3.5/readme/en-US/Release_Notes_CP05.xml
===================================================================
--- projects/docs/enterprise/4.3.5/readme/en-US/Release_Notes_CP05.xml 2009-03-17 02:28:57 UTC (rev 85947)
+++ projects/docs/enterprise/4.3.5/readme/en-US/Release_Notes_CP05.xml 2009-03-17 02:30:05 UTC (rev 85948)
@@ -502,9 +502,24 @@
<itemizedlist>
<listitem>
<para>
-
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1782">JBPAPP-1782</ulink>: Chapter 7.2 named <emphasis>Adjusting memory settings</emphasis> within the <filename>Installation Guide</filename>, stated that a user should modify the <filename>run.conf</filename> file in order to increase the avaliable memory to the program. This however is incorrect when running the JBoss Enterprise Application Platform on a Windows operating system. In this case the <filename>run.bat</filename> file should be modified and the documentation now reflects this difference.
</para>
</listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1768">JBPAPP-1768</ulink>: On page 37 of the PDF for the <filename>Hibernate Annotations Reference Guide</filename> book an example would overflow the allowed area because of the way in which the software to build the PDF deals with names that contain full stops without spaces. In order to rectify the overflow problem without invalidating the code that a user could copy and paste into a command line window, the file name has been broken with the escape character <code>\</code> used to escape a hard return.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1689">JBPAPP-1689</ulink>: The <filename>Server Configuration Guide</filename>, section 16.5 contained an error reguarding the name of the directory where JBoss Web is deployed. Instead of the path to the <filename>jboss-service.xml</filename> file being <filename>JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml</filename> it should be <filename>JBOSS_HOME/server/all/deploy/jboss-web.deployer/META-INF/jboss-service.xml</filename>. For this CP release, the file path has been corrected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://jira.jboss.com/jira/browse/JBPAPP-1584">JBPAPP-1584</ulink>: Information about the <classname>LdapExtLoginModule</classname> was missing from the documentation on login modules within the <filename>Server Configuration Guide</filename>. The information about this module has now been added to the <emphasis>Using JBoss Login Modules</emphasis> section of the guide.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</formalpara>
More information about the jboss-cvs-commits
mailing list