[jboss-cvs] JBossAS SVN: r95877 - projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Oct 30 22:36:36 EDT 2009
Author: laubai
Date: 2009-10-30 22:36:36 -0400 (Fri, 30 Oct 2009)
New Revision: 95877
Modified:
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Book_Info.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Revision_History.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/batch.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/configuration.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/entitymanagerapi.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/listeners.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_ejbql.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_native.xml
projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/transactions.xml
Log:
Added changes for JBPAPP-2966.
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Book_Info.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Book_Info.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -6,7 +6,7 @@
<title>Hibernate Entity Manager Reference Guide</title>
<subtitle>for Use with JBoss Enterprise Application Platform 5.0</subtitle>
<edition>1.0</edition>
- <pubsnumber>1</pubsnumber>
+ <pubsnumber>2</pubsnumber>
<productname>JBoss Enterprise Application Platform</productname>
<productnumber>5.0</productnumber>
<pubdate>, 2009</pubdate>
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Revision_History.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/Revision_History.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -1,9 +1,29 @@
<?xml version='1.0'?>
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<appendix id="appe-Publican-Revision_History">
<title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>1.1</revnumber>
+ <date>Tue Oct 27 2009</date>
+ <author>
+ <firstname>Laura</firstname>
+ <surname>Bailey</surname>
+ <email>lbailey at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Applied changes from
+JBPAPP-2966, JBPAPP-1723.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
<simpara>
<revhistory>
<revision>
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/batch.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/batch.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/batch.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -77,8 +77,8 @@
<programlisting>EntityManager entityManager = entityManagerFactory.createEntityManager();
entityManager.getTransaction().begin();
-String ejbqlUpdate = "update Customer set name = :newName where name = :oldName"
-int updatedEntities = entityManager.createQuery( hqlUpdate )
+String ejbqlUpdate = "update Customer set name = :newName where name = :oldName";
+int updatedEntities = entityManager.createQuery( ejbqlUpdate )
.setParameter( "newName", newName )
.setParameter( "oldName", oldName )
.executeUpdate();
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/configuration.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/configuration.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -147,7 +147,7 @@
load the mapping file located in the jar file at
<literal>META_INF/orm.xml</literal>. Of course any explicit
mapping file will be loaded too. As a matter of fact, you can
- provides any XML file in the mapping file element ie. either hbm
+ provide any XML file in the mapping file element ie. either hbm
files or EJB3 deployment descriptor.</para>
</listitem>
</varlistentry>
@@ -306,7 +306,7 @@
<tbody>
<row>
- <entry>hibernate.ejb.classcache.<classname></entry>
+ <entry>hibernate.ejb.classcache. <classname></entry>
<entry>class cache strategy [comma cache region] of the class
Default to no cache, and default region cache to
@@ -317,7 +317,7 @@
</row>
<row>
- <entry>hibernate.ejb.collectioncache.<collectionrole></entry>
+ <entry>hibernate.ejb.collectioncache. <collectionrole></entry>
<entry>collection cache strategy [comma cache region] of the
class Default to no cache, and default region cache to
@@ -335,7 +335,7 @@
</row>
<row>
- <entry>hibernate.archive.autodetection</entry>
+ <entry>hibernate.archive. autodetection</entry>
<entry>Determine which element is auto discovered by Hibernate
Entity Manager while parsing the .par archive. (default to
@@ -343,7 +343,7 @@
</row>
<row>
- <entry>hibernate.ejb.interceptor</entry>
+ <entry>hibernate.ejb. interceptor</entry>
<entry>An optional Hibernate interceptor. The interceptor
instance is shared by all <classname>Session</classname>
@@ -354,7 +354,7 @@
</row>
<row>
- <entry>hibernate.ejb.interceptor.session_scoped</entry>
+ <entry>hibernate.ejb.interceptor. session_scoped</entry>
<entry>An optional Hibernate interceptor. The interceptor
instance is specific to a given <classname>Session</classname>
@@ -375,7 +375,7 @@
</row>
<row>
- <entry>hibernate.ejb.event.<eventtype></entry>
+ <entry>hibernate.ejb.event. <eventtype></entry>
<entry>Event listener list for a given eventtype. The list of
event listeners is a comma separated fully qualified class name
@@ -384,14 +384,14 @@
</row>
<row>
- <entry>hibernate.ejb.use_class_enhancer</entry>
+ <entry>hibernate.ejb. use_class_enhancer</entry>
<entry>Whether or not use Application server class enhancement
at deployment time (default to false)</entry>
</row>
<row>
- <entry>hibernate.ejb.discard_pc_on_close</entry>
+ <entry>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
@@ -406,7 +406,7 @@
<para>Note that you can mix XML <literal><class></literal>
declaration and <literal>hibernate.ejb.cfgfile</literal> usage in the
- same configuration. Be aware of the potential clashed. The properties
+ same configuration. Be aware of the potential clashes. The properties
set in <filename>persistence.xml</filename> will override the one in the
defined <filename>hibernate.cfg.xml</filename>.</para>
@@ -461,8 +461,8 @@
.setInterceptor( myInterceptorImpl ) // set an interceptor
.addAnnotatedClass( MyAnnotatedClass.class ) //add a class to be mapped
.addClass( NonAnnotatedClass.class ) //add an hbm.xml file using the Hibernate convention
- .addRerousce( "mypath/MyOtherCLass.hbm.xml ) //add an hbm.xml file
- .addRerousce( "mypath/orm.xml ) //add an EJB3 deployment descriptor
+ .addResource( "mypath/MyOtherCLass.hbm.xml" ) //add an hbm.xml file
+ .addResource( "mypath/orm.xml" ) //add an EJB3 deployment descriptor
.configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml
.buildEntityManagerFactory(); //Create the entity manager factory</programlisting>
</section>
@@ -606,7 +606,7 @@
<para>You can configure the event listeners either through the properties
(see <xref linkend="setup-configuration" />) or through the
- <methodname>ejb3configuration.getEventListeners()</methodname> API.</para>
+ <methodname>Ejb3Configuration.getEventListeners()</methodname> API.</para>
</section>
<section>
@@ -620,7 +620,7 @@
entity manager factory.</para>
<programlisting>// Use persistence.xml configuration
-EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1")
+EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
EntityManager em = emf.createEntityManager(); // Retrieve an application managed entity manager
// Work with the EM
em.close();
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/entitymanagerapi.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/entitymanagerapi.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/entitymanagerapi.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -30,13 +30,13 @@
<section>
<title>Entity states</title>
- <para>Like in Hibernate (comparable terms in parantheses), an entity
+ <para>Like in Hibernate (comparable terms in parentheses), an entity
instance is in one of the following states:</para>
<itemizedlist>
<listitem>
<para>New (transient): an entity is new if it has just been
- instantiated using the new operator, and it is not associated with a
+ instantiated using the <literal>new</literal> operator, and it is not associated with a
persistence context. It has no persistent representation in the
database and no identifier value has been assigned.</para>
</listitem>
@@ -71,7 +71,7 @@
<title>Making objects persistent</title>
<para>Once you've created a new entity instance (using the common
- <literal>new</literal> operator) it is in <literal>new</literal> state.
+ <literal>new</literal> operator) it is in the <emphasis>new</emphasis> state.
You can make it persistent by associating it to an entity manager:</para>
<programlisting>DomesticCat fritz = new DomesticCat();
@@ -103,14 +103,14 @@
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");
Parent parent = em.getReference(Parent.class, parentId); //no query to the DB
child.setParent(parent);
em.persist(child);</programlisting>
- <para>You can reload an entity instance and it's collections at any time
+ <para>You can reload an entity instance and its collections at any time
using the <code>em.refresh()</code> operation. This is useful when
database triggers are used to initialize some of the properties of the
entity. Note that only the entity instance and its collections are
@@ -129,7 +129,7 @@
looking for, you need a query. The Hibernate EntityManager implementation
supports an easy-to-use but powerful object-oriented query language
(EJB3-QL) which has been inspired by HQL (and vice-versa). Both query
- languages are portable across databases, the use entity and property names
+ languages are portable across databases, they use entity and property names
as identifiers (instead of table and column names). You may also express
your query in the native SQL of your database, with optional support from
EJB3 for result set conversion into Java business objects.</para>
@@ -220,7 +220,7 @@
<literal>Query</literal> API offers several methods to bind arguments.
The EJB3 specification numbers positional parameters from one. Named
parameters are identifiers of the form <literal>:paramname</literal>
- in the query string. Named parameters should be prefered, they are
+ in the query string. Named parameters should be preferred, they are
more robust and easier to read and understand:</para>
<programlisting>// Named parameter (preferred)
@@ -308,7 +308,7 @@
<note>
<para>For more information about scalar support in named queries,
- please refers to the Hibenate Annotations documentation</para>
+ please refers to the Hibernate Annotations documentation</para>
</note>
</section>
@@ -658,7 +658,7 @@
<methodname>flush()</methodname> is called explicitly.</para>
<programlisting>em = emf.createEntityManager();
-Transaction tx = em.getTransaction().begin();
+em.getTransaction().begin();
em.setFlushMode(FlushModeType.COMMIT); // allow queries to return stale state
Cat izi = em.find(Cat.class, id);
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/listeners.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/listeners.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/listeners.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -46,11 +46,11 @@
annotation:</para>
<programlisting>@Entity
- at EntityListeners(class=Audit.class)
+ at EntityListeners(class=Audit.value)
public class Cat {
@Id private Integer id;
private String name;
- private Calendar dateOfBirth;
+ private Date dateOfBirth;
@Transient private int age;
private Date lastUpdate;
//getters and setters
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_ejbql.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_ejbql.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_ejbql.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -31,8 +31,8 @@
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.
+ use the same query API for EJB-QL and HQL queries. For an EJB3 application to
+ remain portable, it should use EJB-QL without vendor-specific extensions.
</para>
<sect1 id="queryhql-casesensitivity">
@@ -741,9 +741,7 @@
<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!</para>
+ now EJB-QL). This section includes examples of queries in Hibernate.</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
@@ -773,8 +771,7 @@
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:</para>
+ <para>To avoid using subqueries, you could write something like this:</para>
<programlisting>select order.id, sum(price.amount), count(item)
from Order as order
@@ -813,9 +810,8 @@
group by status.name, status.sortOrder
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.</para>
+ <para>If the <literal>statusChanges</literal> collection were mapped
+ as a list instead of a set, the query would be far simpler.</para>
<programlisting>select count(payment), status.name
from Payment as payment
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_native.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_native.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/query_native.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -31,14 +31,14 @@
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
+ 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>
<title>Expressing the resultset</title>
- <para>To use a SQL query, you need to describe the SQL resultset, this
+ <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
Modified: projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/transactions.xml
===================================================================
--- projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/transactions.xml 2009-10-31 01:24:39 UTC (rev 95876)
+++ projects/docs/enterprise/5.0/Hibernate/Hibernate_Entity_Manager/en-US/transactions.xml 2009-10-31 02:36:36 UTC (rev 95877)
@@ -793,7 +793,8 @@
t.begin();
int oldVersion = foo.getVersion();
Foo dbFoo = em.find( foo.getClass(), foo.getKey() ); // load the current state
-if ( dbFoo.getVersion()!=foo.getVersion ) throw new StaleObjectStateException();
+if ( dbFoo.getVersion()!=foo.getVersion() )
+ throw new StaleObjectStateException("Message", oldVersion);
dbFoo.setProperty("bar");
t.commit();
em.close();</programlisting>
@@ -849,7 +850,7 @@
non-managed environment:</para>
<programlisting>// foo is an instance loaded earlier by the extended entity manager
-em.getTransaction.begin(); // new connection to data store is obtained and tx started
+em.getTransaction().begin(); // new connection to data store is obtained and tx started
foo.setProperty("bar");
em.getTransaction().commit(); // End tx, flush and check version, disconnect</programlisting>
@@ -889,11 +890,12 @@
persistence context and then merges the changes using
<literal>EntityManager.merge()</literal>:</para>
+<!--#CLARIFY JBPAPP-2966-->
<programlisting>// foo is an instance loaded by a non-extended entity manager
foo.setProperty("bar");
entityManager = factory.createEntityManager();
entityManager.getTransaction().begin();
-managedFoo = session.merge(foo); // discard foo and from now on use managedFoo
+managedFoo = entityManager.merge(foo); // discard foo and from now on use managedFoo
entityManager.getTransaction().commit();
entityManager.close();</programlisting>
More information about the jboss-cvs-commits
mailing list