[jboss-cvs] JBossAS SVN: r96390 - in projects/docs/enterprise: 4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US and 10 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Nov 15 21:05:20 EST 2009
Author: laubai
Date: 2009-11-15 21:05:20 -0500 (Sun, 15 Nov 2009)
New Revision: 96390
Added:
projects/docs/enterprise/4.2.8/Getting_Started/en-US/Logging.xml
projects/docs/enterprise/4.3.7/Getting_Started/en-US/Logging.xml
Modified:
projects/docs/enterprise/4.2.8/Getting_Started/en-US/Getting_Started_Guide_CP07.xml
projects/docs/enterprise/4.2.8/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP07.ent
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml
projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP07.ent
projects/docs/enterprise/4.2.8/Installation_Guide/publican.cfg
projects/docs/enterprise/4.3.7/Getting_Started/en-US/Getting_Started_Guide_CP06.xml
projects/docs/enterprise/4.3.7/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP06.ent
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml
projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP06.ent
projects/docs/enterprise/4.3.7/Installation_Guide/publican.cfg
Log:
Added Logging chapter to 4.3.7 and 4.2.8 documentation.
Modified: projects/docs/enterprise/4.2.8/Getting_Started/en-US/Getting_Started_Guide_CP07.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Getting_Started/en-US/Getting_Started_Guide_CP07.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Getting_Started/en-US/Getting_Started_Guide_CP07.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -7,7 +7,8 @@
<xi:include href="Preface_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="The_JBoss_Server___A_Quick_Tour.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="EJB3_Caveats.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="EJB3_Caveats.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="About_the_Example_Applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Sample_JSF_EJB3_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Using_Seam.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Added: projects/docs/enterprise/4.2.8/Getting_Started/en-US/Logging.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Getting_Started/en-US/Logging.xml (rev 0)
+++ projects/docs/enterprise/4.2.8/Getting_Started/en-US/Logging.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -0,0 +1,667 @@
+?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis$
+]>
+
+<chapter id="logging">
+ <title>Logging Conventions</title>
+ <para>
+ Persisted diagnostic logs can be very helpful when it comes to debugging software issues. The logging service used in JBoss Enterprise Application Platform is <literal>log4j</literal>.
+ </para>
+ <para>
+ <literal>log4j</literal> is controlled from a central <filename>conf/log4j.xml</filename> file. This file defines a set of appenders that specify the name of the log files, the category of message that should be stored in each log file, the message format, and the level of filtering. By default, JBoss Application server produces output for both the console and a log file (<filename>server.log</filename> in the <filename>log</filename> directory).
+ </para>
+ <para>
+ This chapter teaches you some of the conventions that should be observed when configuring diagnostic logging.
+ </para>
+
+
+ <!--Section of uncertain necessity... #modify?-->
+ <section id="logging.get">
+ <title>Obtaining a Logger</title>
+ <para>
+ You can obtain a logger with the following code:
+ </para>
+ <programlisting role="JAVA">package org.jboss.X.Y;
+import org.jboss.logging.Logger;
+
+public class TestABCWrapper
+{
+ private static final Logger log = Logger.getLogger(TestABCWrapper.class.getName());
+
+ // Hereafter, the logger may be used with whatever priority level as appropriate.
+}</programlisting>
+ </section>
+
+
+ <section id="logging.levels">
+ <title>Logging Levels</title>
+ <para>
+ There are six basic levels of logging: <literal>FATAL</literal>, <literal>ERROR</literal>, <literal>WARN</literal>, <literal>INFO</literal>, <literal>DEBUG</literal>, and <literal>TRACE</literal>. This section describes some of the situations in which each level should be used.
+ </para>
+ <formalpara>
+ <title><literal>FATAL</literal></title>
+ <para>
+ Use the <literal>FATAL</literal> priority level for events that indicate a critical service failure. If a service issues a <literal>FATAL</literal> error, it is completely unable to service requests of any kind.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>ERROR</literal></title>
+ <para>
+ Use the <literal>ERROR</literal> priority level for events that indicate a disruption in the request, or in the ability to service a request. A service should have some capacity to continue to service requests in the presence of an <literal>ERROR</literal>.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>WARN</literal></title>
+ <para>
+ Use the <literal>WARN</literal> priority level for events that may indicate a non-critical service error, such as a resumable error or a minor breach in a request exception. The difference between the <literal>WARN</literal> priority and the <literal>ERROR</literal> priority can be difficult to discern, and is left to the developer's judgement. The simplest criterion is to ask whether a failure would result in a user calling support. If yes, we recommend using <literal>ERROR</literal>. If not, <literal>WARN</literal> is recommended.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>INFO</literal></title>
+ <para>
+ Use the <literal>INFO</literal> priority level for service life-cycle events and other crucial related information. The <literal>INFO</literal> log messages for a particular service category should accurately represent the state of the service.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>DEBUG</literal></title>
+ <para>
+ Use the <literal>DEBUG</literal> priority level to log messages that convey additional information regarding life-cycle events. This priority level is concerned with developer or in-depth information required for support. When <literal>DEBUG</literal> priority is enabled, the JBoss server log should not grow proportionally with the number of server requests. The <literal>DEBUG</literal> and <literal>INFO</literal> log messages for a particular service category should accurately represent the state of the service, and the server resources being used: ports, interfaces, log files, etc.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>TRACE</literal></title>
+ <para>
+ Use the <literal>TRACE</literal> priority level for log messages that are directly associated with activities that correspond to requests. These messages should not be submitted to a <classname>Logger</classname> unless the <classname>Logger</classname> category priority threshold indicates that the message will be rendered. Use the <classname>Logger.isTraceEnabled()</classname> method to determine whether the category priority threshold is enabled. The <literal>TRACE</literal> priority allows deep probing of JBoss server behavior where required. When <literal>TRACE</literal> is enabled, the number of messages in the JBoss server log is expected to grow at least <literal>a x N</literal>, where <literal>N</literal> is the number of requests received by the server, and <literal>a</literal> is some constant. The server log may grow as a power of <literal>N</literal>, depending on the request-handling layer being traced.
+ </para>
+ </formalpara>
+ </section>
+
+
+ <section id="logging.log4jconf">
+ <title>Log4j Configuration</title>
+ <para>
+ The <literal>log4j</literal> configuration is loaded from the <filename>conf/log4j.xml</filename> file. You can edit this file to add or change the default appenders and logging thresholds.
+ </para>
+ <section id="logging.log4j.applogs">
+ <title>Separating Application Logs</title>
+ <para>
+ You can divide or segment logging output by assigning <literal>log4j</literal> categories to specific appenders in the <filename>conf/log4j.xml</filename> configuration file, like so:
+ </para>
+ <programlisting><![CDATA[
+ <appender name="App1Log" class="org.apache.log4j.FileAppender">
+ <errorHandler
+ class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Append" value="false"/>
+ <param name="File"
+ value="${jboss.server.home.dir}/log/app1.log"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
+ </layout>
+ </appender>
+
+...
+
+ <category name="com.app1">
+ <appender-ref ref="App1Log"/>
+ </category>
+ <category name="com.util">
+ <appender-ref ref="App1Log"/>
+ </category>
+
+...
+
+ <root>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+ <appender-ref ref="App1Log"/>
+ </root>
+]]>
+ </programlisting>
+ </section>
+
+ <section id="logging.log4j.appsfilters">
+ <title>Specifying appenders and filters</title>
+ <para>
+ If you have multiple applications that make use of shared classes or categories, or you want to include JBoss categories in your application logs, the previous approach will not work. The <classname>TCLFilter</classname>, a new appender filter, was created to assist in these situations.
+ </para>
+ <para>
+ You can specify a filter by adding a <code><filter></code> element to your <code><appender></code> element in <filename>conf/log4j.xml</filename>. For example, if your <literal>app1</literal> deployment was <filename>app1.ear</filename>, you would use the following additions to the <filename>conf/log4j.xml</filename>:
+ </para>
+ <programlisting><![CDATA[
+<appender name="App1Log" class="org.apache.log4j.FileAppender">
+ <errorHandler
+ class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Append" value="false"/>
+ <param name="File"
+ value="${jboss.server.home.dir}/log/app1.log"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
+ </layout>
+ <filter class="org.jboss.logging.filter.TCLFilter">
+ <param name="AcceptOnMatch" value="true"/>
+ <param name="DeployURL" value="app1.ear"/>
+ </filter>
+ </appender>
+
+...
+
+ <root>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+ <appender-ref ref="App1Log"/>
+ </root>
+
+]]> </programlisting>
+ </section>
+
+ <section id="logging.log4j.server">
+ <title>Logging to a Separate Server</title>
+ <para>
+ The <literal>log4j</literal> framework has a number of appenders that let you send log messages to an external server. Common appenders include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.JMSAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SMTPAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SocketAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SyslogAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.TelnetAppender</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can find more information about configuring these appenders at <ulink url="http://logging.apache.org/">Apache Logging Services</ulink>.
+ </para>
+ <section id="logging.log4j.server.setup">
+ <title>Setting up and using the <classname>Log4jSocketServer</classname> service</title>
+ <para>
+ The <classname>org.jboss.logging.Log4jSocketServer</classname> is an MBean service that allows one to collect output from multiple <literal>log4j</literal> clients (including JBoss servers) that use the <classname>org.apache.log4j.net.SocketAppender</classname>.
+ </para>
+ <para>
+ The <classname>Log4jSocketServer</classname> creates a server socket to accept <classname>SocketAppender</classname> connections, and logs incoming messages based on the local <filename>log4j.xml</filename> configuration.
+ </para>
+ <para>
+ You can create a minimal JBoss configuration that includes a <classname>Log4jSocketServer</classname> to act as your log server.
+ </para>
+ </section>
+ <section id="logging.log4j.server.conf">
+ <title>A <classname>Log4jSocketServer</classname> mbean configuration</title>
+ <para>
+ You can add the following MBean configuration to your <filename>conf/jboss-service.xml</filename>
+ </para>
+ <programlisting role="XML"><![CDATA[
+ <mbean code="org.jboss.logging.Log4jSocketServer"
+ name="jboss.system:type=Log4jService,service=SocketServer">
+ <attribute name="Port">12345</attribute>
+ <attribute name="BindAddress">${jboss.bind.address}</attribute>
+ </mbean>
+ ]]>
+ </programlisting>
+ <para>
+ The <classname>Log4jSocketServer</classname> adds an MDC entry under the key 'host' which includes the client socket <literal>InetAddress.getHostName</literal> value on every client connection. This allows you to differentiate logging output based on the client hostname using the MDC pattern.
+ </para>
+ </section>
+ <section id="logging.log4j.server.hostname">
+ <title>Augmenting the log server console output with the logging client socket hostname</title>
+ <programlisting role="XML"><![CDATA[
+<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
+ <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Target" value="System.out"/>
+ <param name="Threshold" value="INFO"/>
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1},%X{host}] %m%n"/>
+ </layout>
+</appender>
+]]>
+ </programlisting>
+ <para>
+ All other JBoss servers that should send log messages to the log server would add an appender configuration that uses the SocketAppender.
+ </para>
+ </section>
+ <section id="logging.log4j.server.xml">
+ <title><filename>log4j.xml</filename> appender for the <classname>Log4jSocketServer</classname></title>
+ <programlisting role="XML"><![CDATA[
+<appender name="SOCKET" class="org.apache.log4j.net.SocketAppender">
+ <param name="Port" value="12345"/>
+ <param name="RemoteHost" value="loghost"/>
+ <param name="ReconnectionDelay" value="60000"/>
+ <param name="Threshold" value="INFO"/>
+</appender>
+]]>
+ </programlisting>
+ </section>
+ </section>
+
+
+ <section id="logging.log4j.subsys">
+ <title>Key JBoss Subsystem Categories</title>
+ <para>
+ Some of the key subsystem category names are given in the following table. These are just the top level category names. Generally you can specify much more specific category names to enable very targeted logging.
+ </para>
+ <table><title>JBoss Subsystem Categories</title>
+ <tgroup cols='2' align='center' colsep='1' rowsep='1'>
+ <colspec colname='Subsystem'>
+ <colspec colname='Category'>
+ <thead>
+ <row>
+ <entry>Subsystem</entry>
+ <entry>Category</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry><classname></classname></entry>
+ </row>
+ <row>
+ <entry>CMP</entry>
+ <entry><classname>org.jboss.ejb. plugins.cmp</classname></entry>
+ </row>
+ <row>
+ <entry>Core Service</entry>
+ <entry><classname>org.jboss.system</classname></entry>
+ </row>
+ <row>
+ <entry>Cluster</entry>
+ <entry><classname>org.jboss.ha</classname></entry>
+ </row>
+ <row>
+ <entry>EJB</entry>
+ <entry><classname>org.jboss.ejb</classname></entry>
+ </row>
+ <row>
+ <entry>JCA</entry>
+ <entry><classname>org.jboss.resource</classname></entry>
+ </row>
+ <row>
+ <entry>JMX</entry>
+ <entry><classname>org.jboss.mx</classname></entry>
+ </row>
+ <row>
+ <entry>JMS</entry>
+ <entry><classname>org.jboss.mq</classname></entry>
+ </row>
+ <row>
+ <entry>JTA</entry>
+ <entry><classname>org.jboss.tm</classname></entry>
+ </row>
+ <row>
+ <entry>MDB</entry>
+ <entry><classname>org.jboss.ejb.plugins</classname>, <classname>org.jboss.jms</classname></entry>
+ </row>
+ <row>
+ <entry>Security</entry>
+ <entry><classname>org.jboss.security</classname></entry>
+ </row>
+ <row>
+ <entry>Tomcat</entry>
+ <entry><classname>org.jboss.web</classname>, <classname>org.jboss.catalina</classname></entry>
+ </row>
+ <row>
+ <entry>Apache</entry>
+ <entry><classname>org.apache</classname></entry>
+ </row>
+ <row>
+ <entry>JGroups</entry>
+ <entry><classname>org.jgroups</classname></entry>
+ </row>
+ </tbody>
+ </table>
+ </section>
+
+ <section id="logging.log4j.redir">
+ <title>Redirecting Category Output</title>
+ <para>
+ When you increase the level of logging for one or more categories, it is often useful to redirect the output to a seperate file for easier investigation. To do this you add an <varname>appender-ref</varname> to the <classname>category</classname> as shown here:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<appender name="JSR77" class="org.apache.log4j.FileAppender">
+ <param name="File"
+ value="${jboss.server.home.dir}/log/jsr77.log"/>
+...
+</appender>
+
+<!-- Limit the JSR77 categories -->
+<category name="org.jboss.management" additivity="false">
+ <priority value="DEBUG"/>
+ <appender-ref ref="JSR77"/>
+</category>
+ ]]>
+ </programlisting>
+ <para>
+ This sends <classname>allorg.jboss.management</classname> output to the <filename>jsr77.log</filename> file. The <varname>additivity</varname> attribute controls whether output continues to go to the root category appender. If <literal>false</literal>, output only goes to the appenders referred to by the category.
+ </para>
+ </section>
+ </section>
+
+ <section id="logging.log4j.properties">
+ <title>Using your own log4j.properties file - class loader scoping</title>
+ <para>
+ To use your own <filename>log4j.xml</filename> file you must initialize <literal>log4j</literal> in your application. If you use the default singleton initialization method where the first use of <literal>log4j</literal> triggers a search for the <literal>log4j</literal> initialization files, you must configure a ClassLoader to use scoped class loading with overrides for JBoss classes. You also have to include the <filename>log4j.jar</filename> in your application so that new <literal>log4j</literal> singletons are created in your application's scope.
+ </para>
+ <note>
+ <para>
+ You cannot use a <filename>log4j.properties</filename> file using this approach, at least using log4j-1.2.8 because it preferentially searches for a <filename>log4j.xml</filename> resource and will find the <filename>conf/log4j.xml</filename> ahead of the application <filename>log4j.properties</filename> file. You could rename the <filename>conf/log4j.xml</filename> to something like <filename>conf/jboss-log4j.xml</filename> and then change the <varname>ConfigurationURL</varname> attribute of the <classname>Log4jService</classname> in the <filename>conf/jboss-service.xml</filename> to get around this.
+ </para>
+ </note>
+ </section>
+
+ <section id="logging.log4j.scoping">
+ <title>Using your own <filename>log4j.properties</filename> file - class loader scoping</title>
+ <para>
+ To use a <filename>log4j.properties</filename> file, you have to make the following change in <filename>conf/jboss-service.xml</filename>, for the reasons mentioned in the previous section.
+ </para>
+ <programlisting role="XML"><![CDATA[
+<!--================================================================-->
+<!-- Log4j Initialization -->
+<!-=================================================================-->
+
+<mbean code="org.jboss.logging.Log4jService"
+ name="jboss.system:type=Log4jService,service=Logging">
+ <attribute name="ConfigurationURL">
+ resource:jboss-log4j.xml</attribute>
+ <!-- Set the org.apache.log4j.helpers.LogLog.setQuiteMode.
+ As of log4j1.2.8 this needs to be set to avoid a possible deadlock
+ on exception at the appender level. See bug#696819.
+ -->
+ <attribute name="Log4jQuietMode">true</attribute>
+ <!-- How frequently in seconds the ConfigurationURL is checked for changes -->
+ <attribute name="RefreshPeriod">60</attribute>
+</mbean>
+ ]]>
+ </programlisting>
+ <para>
+ This changes the <literal>log4j</literal> resource file that JBoss Application Server looks for. After making the change in <filename>jboss-service.xml</filename> make sure you rename the <filename>conf/log4j.xml</filename> to match the name of the resource you specified in <filename>jboss-service.xml</filename> (in this case <filename>jboss-log4j.xml</filename>).
+ </para>
+ <para>
+ Include <filename>log4j.jar</filename> in your <filename>myapp.war/WEB-INF</filename> directory. Make the change in <filename>jboss-web.xml</filename> for class loading, as shown in the section above. In this case, <filename>myapp.war/WEB-INF/jboss-web.xml</filename> looks like this:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<jboss-web>
+ <class-loading java2ClassLoadingCompliance="false">
+ <loader-repository>
+ myapp:loader=myapp.war
+ <loader-repository-config>java2ParentDelegation=false
+ </loader-repository-config>
+ </loader-repository>
+ </class-loading>
+</jboss-web>
+ ]]>
+ </programlisting>
+ <para>
+ Now, create a <filename>log4j.properties</filename> file in your <filename>deploy/myapp.war/WEB-INF/classes</filename> directory.
+ </para>
+ <section id="logging.log4j.scoping.example">
+ <title>Sample <filename>log4j.properties</filename></title>
+ <programlisting><![CDATA[
+# Debug log4j
+log4j.debug=true
+log4j.rootLogger=debug, myapp
+
+log4j.appender.myapp=org.apache.log4j.FileAppender
+log4j.appender.myapp.layout=org.apache.log4j.HTMLLayout
+log4j.appender.myapp.layout.LocationInfo=true
+log4j.appender.myapp.layout.Title='All' Log
+log4j.appender.myapp.File=${jboss.server.home.dir}/deploy/myapp.war/WEB-INF/logs/myapp.html
+log4j.appender.myapp.ImmediateFlush=true
+log4j.appender.myapp.Append=false
+ ]]>
+ </programlisting>
+ <para>
+ This property file sets the <literal>log4j</literal> debug system to <literal>true</literal>, which enables the display of <literal>log4j</literal> messages in your JBoss log. You can use this to discover any errors in your properties file. It then produces a HTML log file and places it in your application's <filename>WEB-INF/logs</filename> directory. In your application, you can call this logger with the following syntax:
+ </para>
+ <programlisting>
+...
+private static Logger log = Logger.getLogger("myapp");
+...
+log.debug("############## A debug message from myapp logger #########");
+...
+ </programlisting>
+ <para>
+ You should then see the message in <filename>myapp.html</filename>.
+ </para>
+ <para>
+ After JBoss Application Server has reloaded <filename>conf/jboss-service.xml</filename> (you may need to restart JBoss AS), touch <filename>myapp.war/WEB-INF/web.xml</filename> so that JBoss reloads the configuration for your application. As the application loads, you should see <literal>log4j</literal> debug messages, which confirms that JBoss AS is reading your <filename>log4j.properties</filename> file. This lets you have your own logging system independent of the JBoss AS log.
+ </para>
+ </section>
+ </section>
+
+ <section id="logging.log4j.reposelect">
+ <title>Using your own <filename>log4j.xml</filename> file - Log4j <classname>RepositorySelector</classname></title>
+ <para>
+ Another way to achieve this is to write a custom <classname>RepositorySelector</classname> that changes how the LogManager gets a logger. Using this technique, <classname>Logger.getLogger()</classname> will return a different logger based on the context class loader. Each context class loader has its own configuration set up with its own <filename>log4j.xml</filename> file.
+ </para>
+ <programlisting role="JAVA">
+ /*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2005, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.repositoryselectorexample;
+
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.Map;
+import javax.servlet.ServletConfig;
+import javax.servlet.ServletException;
+import javax.xml.parsers.DocumentBuilderFactory;
+import org.apache.log4j.Hierarchy;
+import org.apache.log4j.Level;
+import org.apache.log4j.LogManager;
+import org.apache.log4j.spi.LoggerRepository;
+import org.apache.log4j.spi.RepositorySelector;
+import org.apache.log4j.spi.RootCategory;
+import org.apache.log4j.xml.DOMConfigurator;
+import org.w3c.dom.Document;
+
+/**
+ * This RepositorySelector is for use with web applications.
+ * It assumes that your log4j.xml file is in the WEB-INF directory.
+ * @author Stan Silvert
+ */
+public class MyRepositorySelector implements RepositorySelector
+{
+ private static boolean initialized = false;
+
+ // This object is used for the guard because it doesn't get
+ // recycled when the application is redeployed.
+ private static Object guard = LogManager.getRootLogger();
+
+ private static Map repositories = new HashMap();
+ private static LoggerRepository defaultRepository;
+
+ /**
+ * Register your web-app with this repository selector.
+ */
+ public static synchronized void init(ServletConfig config)
+ throws ServletException {
+ if( !initialized ) // set the global RepositorySelector
+ {
+ defaultRepository = LogManager.getLoggerRepository();
+ RepositorySelector theSelector = new MyRepositorySelector();
+ LogManager.setRepositorySelector(theSelector, guard);
+ initialized = true;
+ }
+
+ Hierarchy hierarchy = new Hierarchy(new
+ RootCategory(Level.DEBUG));
+ loadLog4JConfig(config, hierarchy);
+ ClassLoader loader =
+ Thread.currentThread().getContextClassLoader();
+ repositories.put(loader, hierarchy);
+ }
+
+ // load log4j.xml from WEB-INF
+ private static void loadLog4JConfig(ServletConfig config,
+ Hierarchy hierarchy)
+ throws ServletException {
+ try {
+ String log4jFile = "/WEB-INF/log4j.xml";
+ InputStream log4JConfig =
+
+ config.getServletContext().getResourceAsStream(log4jFile);
+ Document doc = DocumentBuilderFactory.newInstance()
+ .newDocumentBuilder()
+ .parse(log4JConfig);
+ DOMConfigurator conf = new DOMConfigurator();
+ conf.doConfigure(doc.getDocumentElement(), hierarchy);
+ } catch (Exception e) {
+ throw new ServletException(e);
+ }
+ }
+
+ private MyRepositorySelector() {
+ }
+
+ public LoggerRepository getLoggerRepository() {
+ ClassLoader loader =
+ Thread.currentThread().getContextClassLoader();
+ LoggerRepository repository =
+ (LoggerRepository)repositories.get(loader);
+
+ if (repository == null) {
+ return defaultRepository;
+ } else {
+ return repository;
+ }
+ }
+}
+ </programlisting>
+ </section>
+
+ <section id="logging.jdk">
+ <title>JDK java.util.logging</title>
+ <para>
+ The choice of the actual logging implementation is determined by the <varname>org.jboss.logging.Logger.pluginClass</varname> system property. This property specifies the class name of an implementation of the <classname>org.jboss.logging.LoggerPlugin</classname> interface. The default value for this is the <classname>org.jboss.logging.Log4jLoggerPlugin</classname> class.
+ </para>
+ <para>
+ If you want to use the JDK 1.4+ <classname>java.util.logging</classname> framework instead of <literal>log4j</literal>, you can create your own <classname>Log4jLoggerPlugin</classname> to do this. The attached <filename>JDK14LoggerPlugin.java</filename> file shows an example implementation.
+ </para>
+ <para>
+ To use this, you must specify the following system properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ To specify the custom JDK1.4 plugin:
+ </para>
+ <programlisting>
+org.jboss.logging.Logger.pluginClass = logging.JDK14LoggerPlugin
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ To specify the JDK1.4 logging configuration file:
+ </para>
+ <programlisting>
+java.util.logging.config.file = logging.properties
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can specify these properties using the <literal>JAVA_OPTS</literal> environment variable, like so:
+ </para>
+ <programlisting>
+JAVA_OPTS=
+ "-Dorg.jboss.logging.Logger.pluginClass=logging.JDK14LoggerPlugin
+ -Djava.util.logging.config.file=logging.properties"
+ </programlisting>
+ <para>
+ You need to make your custom <classname>Log4jLoggerPlugin</classname> available to JBoss by placing it in a JAR in the <filename>JBOSS_DIST/lib</filename> directory, and then telling JBoss to load this as part of the bootstrap libraries by passing in <code>-L $JARNAME</code> on the command line as follows:
+ </para>
+ <programlisting>
+[user at host bin] $ run.sh -c minimal -L logger.jar
+ </programlisting>
+ </section>
+
+
+ <section>
+ <title>Debugging with server.log</title>
+ <para>
+ The logging threshold on the console is set to <literal>INFO</literal>, which means that you will see informative messages, warning messages and error messages on the console, but not general debug messages. However, there is no threshold set for the <filename>server.log</filename> file, so all messages generated will be logged there.
+ </para>
+ <para>
+ If you are experiencing difficulties and the console is not displaying useful information, always check the <filename>server.log</filename> file for debug messages that might help to solve the problem. However, keep in mind that not all of your components will produce detailed debug information for the log file. You must also boost the logging limits set for individual categories.
+ </para>
+ <para>
+ The following category limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided.
+ </para>
+<programlisting><!-- Limit JBoss categories to INFO -->
+<category name="org.jboss">
+<priority value="<emphasis role="bold">INFO</emphasis>"/>
+</category>
+</programlisting>
+ <para>
+ If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output.
+ </para>
+ <para>
+ As an example, say you want to set the output from the container-managed persistence engine to <literal>DEBUG</literal> level and to redirect it to a separate file, <filename>cmp.log</filename>, in order to analyze the generated SQL commands. You would add the following code to the <filename>log4j.xml</filename> file:
+ </para>
+<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
+<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+<param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
+<param name="Append" value="false"/>
+<param name="MaxFileSize" value="500KB"/>
+<param name="MaxBackupIndex" value="1"/>
+
+<layout class="org.apache.log4j.PatternLayout">
+<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
+</layout>
+</appender>
+
+<category name="org.jboss.ejb.plugins.cmp">
+<priority value="DEBUG" />
+<appender-ref ref="CMP"/>
+</category>
+</programlisting>
+ <para>
+ This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
+ </para>
+ <para>
+ The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is <filename>cmp.log</filename>. Older files have the date they were written added to the name. You will notice that the <filename class="directory">log</filename> directory also contains HTTP request logs which are produced by the web container.
+ </para>
+ <warning>
+ <para>
+ If you edit the <filename>jboss-log4j.xml</filename> file, be aware that the <literal>log4j</literal> configuration will be reloaded as if the server was restarted. Before editing the file, be aware that if the file appender is not configured to append to an existing log file, then the process will delete the current log and create a new file in its place.
+ </para>
+ </warning>
+</section>
+
+</chapter>
\ No newline at end of file
Modified: projects/docs/enterprise/4.2.8/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -98,50 +98,8 @@
Logging is controlled from a central <filename>conf/log4j.xml</filename> file. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, JBoss produces output to both the console and a log file (<filename>server.log</filename> in the <filename class="directory">log</filename> directory).
</para>
<para>
- There are 5 basic log levels used: <literal>DEBUG</literal>, <literal>INFO</literal>, <literal>WARN</literal>, <literal>ERROR</literal> and <literal>FATAL</literal>. The logging threshold on the console is <literal>INFO</literal>, which means that you will see informational messages, warning messages and error messages on the console but not general debug messages. In contrast, there is no threshold set for the <filename>server.log</filename> file, so all generated logging messages will be logged there.
- </para>
- <para>
- If things are going wrong and there doesn’t seem to be any useful information in the console, always check the <filename>server.log</filename> file to see if there are any debug messages which might help you to track down the problem. However, be aware that just because the logging threshold allows debug messages to be displayed, that doesn't mean that all of JBoss will produce detailed debug information for the log file. You will also have to boost the logging limits set for individual categories. Take the following category for example.
- </para>
-<programlisting><!-- Limit JBoss categories to INFO -->
-<category name="org.jboss">
- <priority value="<emphasis role="bold">INFO</emphasis>"/>
-</category>
-</programlisting>
- <para>
- This limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided. If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output.
- </para>
- <para>
- As another example, let’s say you wanted to set the output from the container-managed persistence engine to <literal>DEBUG</literal> level and to redirect it to a separate file, <filename>cmp.log</filename>, in order to analyze the generated SQL commands. You would add the following code to the <filename>log4j.xml</filename> file:
- </para>
-<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
- <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
- <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
- <param name="Append" value="false"/>
- <param name="MaxFileSize" value="500KB"/>
- <param name="MaxBackupIndex" value="1"/>
-
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
- </layout>
-</appender>
-
-<category name="org.jboss.ejb.plugins.cmp">
- <priority value="DEBUG" />
- <appender-ref ref="CMP"/>
-</category>
-</programlisting>
- <para>
- This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
- </para>
- <para>
- The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is <filename>cmp.log</filename>. Older files have the date they were written added to the name. You will notice that the <filename class="directory">log</filename> directory also contains HTTP request logs which are produced by the web container.
- </para>
- <warning>
- <para>
- If you edit the <filename>jboss-log4j.xml</filename> file, be aware that the log4j configuration will be reloaded as if the server was restarted. Before editing the file, be aware that if the file appender is not configured to append to an existing log file, then the process will delete the current log and create a new file in its place.
- </para>
- </warning>
+ For more information, see <xref linkend="logging" />.
+ </para>
</section>
<section id="Basic_Configuration_Issues-Security_Service">
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -28,7 +28,7 @@
Every bound persistent POJO class is an entity bean and is declared using the <literal>@Entity</literal> annotation (at the class level):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@Entity</literal> declares the class as an entity bean (i.e. a persistent POJO class), <literal>@Id</literal> declares the identifier property of this entity bean. The other mapping declarations are implicit. This "configuration by exception" concept is central to the new EJB3 specification and a major improvement. The class Flight is mapped to the Flight table, using the column id as its primary key column.
</para>
@@ -41,12 +41,12 @@
<literal>@Table</literal> is set at the class level. It allows you to define the table, catalog, and schema names for your entity bean mapping. If no <literal>@Table</literal> is defined the default values are used: the unqualified class name of the entity.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>@Table</literal> element also contains <literal>schema</literal> and a <literal>catalog</literal> attributes, if they need to be defined. You can also define unique constraints to the table using the <literal>@UniqueConstraint</literal> annotation in conjunction with <literal>@Table</literal> (for a unique constraint bound to a single column, refer to <literal>@Column</literal>).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A unique constraint is applied to the tuple month, day. Note that the <literal>columnNames</literal> array refers to the logical column names.
</para>
@@ -59,7 +59,7 @@
You can add optimistic locking capability to an entity bean using the <literal>@Version</literal> annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The version property will be mapped to the <literal>OPTLOCK</literal> column, and the entity manager will use it to detect conflicting updates (preventing lost updates you might otherwise see with the last-commit-wins strategy).
</para>
@@ -81,7 +81,7 @@
Every non-static non-transient property (field or method) of an entity bean is considered persistent, unless you annotate it as <literal>@Transient</literal>. Not having an annotation for your property is equivalent to the appropriate <literal>@Basic</literal> annotation. The <literal>@Basic</literal> annotation allows you to declare the fetching strategy for a property:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>counter</literal>, a transient field, and <literal>lengthInMeter</literal>, a method annotated as <literal>@Transient</literal>, and will be ignored by the entity manager. <literal>name</literal>, <literal>length</literal>, and <literal>firstname</literal> properties are mapped persistent and eagerly fetched (the default for simple properties). The <literal>detailedComment</literal> property value will be lazily fetched from the database once a lazy property of the entity is accessed for the first time. Usually you don't need to lazy simple properties (not to be confused with lazy association fetching).
</para>
@@ -103,7 +103,7 @@
<literal>@Lob</literal> indicates that the property should be persisted in a Blob or a Clob depending on the property type: <classname>java.sql.Clob</classname>, <classname>Character[]</classname>, <classname>char[]</classname> and java.lang.<classname>String</classname> will be persisted in a Clob. <classname>java.sql.Blob</classname>, <classname>Byte[]</classname>, <classname>byte[] </classname>and serializable type will be persisted in a Blob.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If the property type implements <classname>java.io.Serializable</classname> and is not a basic type, and if the property is not annotated with <literal>@Lob</literal>, then the Hibernate <literal>serializable</literal> type is used.
</para>
@@ -147,7 +147,7 @@
</listitem>
</itemizedlist>
- <programlisting language="java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>name</literal> property is mapped to the <literal>flight_name</literal> column, which is not nullable, has a length of 50 and is not updatable (making the property immutable).
</para>
@@ -156,7 +156,7 @@
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -219,11 +219,11 @@
It is possible to declare an embedded component inside an entity and even override its column mapping. Component classes have to be annotated at the class level with the <literal>@Embeddable</literal> annotation. It is possible to override the column mapping of an embedded object for a particular entity using the <literal>@Embedded</literal> and <literal>@AttributeOverride</literal> annotation in the associated property:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A embeddable object inherits the access type of its owning entity (note that you can override that using the Hibernate-specific <literal>@AccessType</literal> annotations (see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Entity_Beans-Hibernate_Annotation_Extensions" />).
</para>
@@ -232,7 +232,7 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Hibernate Annotations supports one more feature that is not explicitly supported by the EJB3 specification: you can annotate a embedded object with the <literal>@MappedSuperclass</literal> annotation to make the superclass properties persistent (see <literal>@MappedSuperclass</literal> for more information).
</para>
<para>
@@ -296,17 +296,17 @@
The following example shows a sequence generator using the <literal>SEQ_STORE</literal> configuration (see below)
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The next example uses the identity generator:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>AUTO</literal> generator is the preferred type for portable applications (across several DB vendors). The identifier generation configuration can be shared for several <literal>@Id</literal> mappings with the generator attribute. There are several configurations available through <literal>@SequenceGenerator</literal> and <literal>@TableGenerator</literal>. The scope of a generator can be the application or the class. Class-defined generators are not visible outside the class and can override application level generators. Application-level generators are defined at XML level (see <xref linkend="chap-Hibernate_Annotations_Reference_Guide-Overriding_metadata_through_XML" />):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If JPA XML (like <filename>META-INF/orm.xml</filename>) is used to define the generators, <literal>EMP_GEN</literal> and <literal>SEQ_GEN</literal> are application level generators. <literal>EMP_GEN</literal> defines a table based id generator using the hilo algorithm with a <literal>max_lo</literal> of 20. The hi value is kept in a <literal>table</literal> "<literal>GENERATOR_TABLE</literal>". The information is kept in a row where <literal>pkColumnName</literal> "key" is equals to <literal>pkColumnValue</literal> "<literal>EMP</literal>" and column <literal>valueColumnName</literal> "<literal>hi</literal>" contains the the next high value used.
</para>
@@ -322,7 +322,7 @@
The next example shows the definition of a sequence generator in a class scope:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This class will use a sequence named my_sequence and the SEQ_STORE generator is not visible in other classes. Note that you can check the Hibernate Annotations tests in the <package>org.hibernate.test.annotations.id</package> package for more examples.
</para>
@@ -344,7 +344,7 @@
While quite common to the EJB2 developer, <literal>@IdClass</literal> is likely new for Hibernate users. The composite primary key class corresponds to multiple fields or properties of the entity class, and the names of primary key fields or properties in the primary key class and those of the entity class must match and their types must be the same. Let's look at an example:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
As you may have seen, <literal>@IdClass</literal> points to the corresponding primary key class.
</para>
@@ -352,7 +352,7 @@
While not supported by the EJB3 specification, Hibernate allows you to define associations inside a composite identifier. Simply use the regular annotations for that.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Mapping_with_EJB3JPA_Annotations-Mapping_inheritance">
@@ -385,7 +385,7 @@
This strategy has many drawbacks (esp. with polymorphic queries and associations) explained in the EJB3 spec, the Hibernate reference documentation, <citetitle>Hibernate in Action</citetitle>, and many other places. Hibernate works around most of them implementing this strategy using <literal>SQL UNION</literal> queries. It is commonly used for the top level of an inheritance hierarchy:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21a.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21a.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This strategy supports one-to-many associations provided that they are bidirectional. This strategy does not support the <literal>IDENTITY</literal> generator strategy: the id has to be shared across several tables. Consequently, when using this strategy, you should not use <literal>AUTO </literal>nor <literal>IDENTITY</literal>.
</para>
@@ -397,7 +397,7 @@
All properties of all super- and subclasses are mapped into the same table, instances are distinguished by a special discriminator column:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Plane</classname> is the superclass, it defines the inheritance strategy <literal>InheritanceType.SINGLE_TABLE</literal>. It also defines the discriminator column through the <literal>@DiscriminatorColumn</literal> annotation. A discriminator column can also define the discriminator type. Finally, the <literal>@DiscriminatorValue</literal> annotation defines the value used to differentiate a class in the hierarchy. All of these attributes have sensible default values. The default name of the discriminator column is <literal>DTYPE</literal>. The default discriminator value is the entity name (as defined in <literal>@Entity.name</literal>) for DiscriminatorType.STRING. <classname>A320</classname> is a subclass; you only have to define discriminator value if you don't want to use the default value. The strategy and the discriminator type are implicit.
</para>
@@ -412,7 +412,7 @@
The<literal> @PrimaryKeyJoinColumn</literal> and <literal>@PrimaryKeyJoinColumns</literal> annotations define the primary key(s) of the joined subclass table:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
All of the above entities use the <literal>JOINED</literal> strategy, the <literal>Ferry</literal> table is joined with the <literal>Boat</literal> table using the same primary key names. The <literal>AmericaCupClass</literal> table is joined with <literal>Boat</literal> using the join condition <code>Boat.id = AmericaCupClass.BOAT_ID</code>.
</para>
@@ -424,7 +424,7 @@
This is sometimes useful to share common properties through a technical or a business superclass without including it as a regular mapped entity (ie no specific table for this entity). For that purpose you can map them as <literal>@MappedSuperclass</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In database, this hierarchy will be represented as an <literal>Order</literal> table having the <literal>id</literal>, <literal>lastUpdate</literal> and <literal>lastUpdater</literal> columns. The embedded superclass property mappings are copied into their entity subclasses. Remember that the embeddable superclass is not the root of the hierarchy though.
</para>
@@ -457,7 +457,7 @@
You can override columns defined in entity superclasses at the root entity level using the <literal>@AttributeOverride</literal> annotation.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>altitude</literal> property will be persisted in an <literal>fld_altitude</literal> column of table <literal>Plane</literal> and the propulsion association will be materialized in a <literal>fld_propulsion_fk</literal> foreign key column.
</para>
@@ -479,9 +479,9 @@
First, we map a real one-to-one association using shared primary keys:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The one-to-one is marked as true by using the <literal>@PrimaryKeyJoinColumn</literal> annotation.
</para>
@@ -489,7 +489,7 @@
In the following example, the associated entities are linked through a foreign key column:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <classname>Customer</classname> is linked to a <classname>Passport</classname>, with a foreign key column named <literal>passport_fk</literal> in the <literal>Customer</literal> table. The join column is declared with the <literal>@JoinColumn</literal> annotation which looks like the <literal>@Column</literal> annotation. It has one more parameters named <literal>referencedColumnName</literal>. This parameter declares the column in the targeted entity that will be used to the join. Note that when using <literal><literal>referencedColumnName</literal></literal> to a non primary key column, the associated class has to be <classname>Serializable</classname>. Also note that the <literal><literal>referencedColumnName</literal></literal> to a non primary key column has to be mapped to a property having a single column (other cases might not work).
</para>
@@ -503,7 +503,7 @@
The third possibility (using an association table) is very exotic.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <classname>Customer</classname> is linked to a <classname>Passport</classname> through a association table named <literal>CustomerPassports</literal> ; this association table has a foreign key column named <literal>passport_fk</literal> pointing to the <literal>Passport</literal> table (materialized by the <literal>inverseJoinColumn</literal> and a foreign key column named <literal>customer_fk</literal> pointing to the <literal>Customer</literal> table materialized by the <literal>joinColumns</literal> attribute.
</para>
@@ -518,7 +518,7 @@
Many-to-one associations are declared at the property level with the annotation <literal>@ManyToOne</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>@JoinColumn</literal> attribute is optional, the default value(s) is like in one-to-one, the concatenation of the name of the relationship in the owner side, <keycap>_</keycap> (underscore), and the name of the primary key column in the owned side. In this example <literal>company_id</literal> because the property name is <literal>company</literal> and the column id of Company is <literal>id</literal>.
</para>
@@ -526,12 +526,12 @@
<literal>@ManyToOne</literal> has a parameter named <literal>targetEntity</literal> which describes the target entity name. You usually don't need this parameter since the default value (the type of the property that stores the association) is good in almost all cases. However this is useful when you want to use interfaces as the return type instead of the regular entity.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also map a many-to-one association through an association table. This association table described by the <literal>@JoinTable</literal> annotation will contains a foreign key referencing back the entity table (through <literal>@JoinTable.joinColumns</literal>) and a foreign key referencing the target entity table (through <literal>@JoinTable.inverseJoinColumns</literal>).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Mapping_entity_bean_associationsrelationships-Collections" revision="1">
@@ -627,7 +627,7 @@
Collection of primitive, core type or embedded objects is not supported by the EJB3 specification. Hibernate Annotations allows them however (see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Entity_Beans-Hibernate_Annotation_Extensions" />).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_33.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_33.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
So <literal>City</literal> has a collection of <literal>Street</literal>s that are ordered by <literal>streetName</literal> (of <literal>Street</literal>) when the collection is loaded. <literal>Software</literal> has a map of <literal>Version</literal>s which key is the <literal>Version</literal> <literal>codeName</literal>.
</para>
@@ -647,7 +647,7 @@
Since many-to-one are (almost) always the owner side of a bidirectional relationship in the EJB3 spec, the one-to-many association is annotated by <literal>@OneToMany( mappedBy=... )</literal>
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Troop</classname> has a bidirectional one-to-many relationship with <literal>Soldier</literal> through the <literal>troop</literal> property. You must not define any physical mapping in the <literal>mappedBy</literal> side.
</para>
@@ -655,7 +655,7 @@
To map a bidirectional one-to-many, with the one-to-many side as the owning side, you have to remove the <literal>mappedBy</literal> element and set the many-to-one <literal>@JoinColumn</literal> as insertable and updatable to false. This solution is obviously not optimized and will produce some additional UPDATE statements.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-One_to_many-Unidirectional">
@@ -664,7 +664,7 @@
A unidirectional one-to-many using a foreign key column in the owned entity is not that common and not really recommended. We strongly advise you to use a join table for this kind of association (as explained in the next section). This kind of association is described through a <literal>@JoinColumn</literal>
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_36.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_36.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>Customer</literal> describes a unidirectional relationship with <literal>Ticket</literal> using the join column <literal>CUST_ID</literal>.
</para>
@@ -676,7 +676,7 @@
A unidirectional one-to-many with join table is much preferred. This association is described through an <literal>@JoinTable</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_37.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_37.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>Trainer</literal> describes a unidirectional relationship with <classname>Monkey</classname> using the join table <classname>TrainedMonkeys</classname>, with a foreign key <literal>trainer_id</literal> to <literal>Trainer</literal> (<literal>joinColumns</literal>) and a foreign key <literal>monkey_id</literal> to <literal>Monkey</literal> (<literal>inversejoinColumns</literal>).
</para>
@@ -688,7 +688,7 @@
Without describing any physical mapping, a unidirectional one-to-many with join table is used. The table name is the concatenation of the owner table name, <keycap>_</keycap>, and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table, <keycap>_</keycap>, and the owner primary key column(s) name. The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s) name. A unique constraint is added to the foreign key referencing the other side table to reflect the one-to-many.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_38.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_38.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Trainer</classname> describes a unidirectional relationship with <classname>Tiger</classname> using the join table <literal>Trainer_Tiger</literal>, with a foreign key <literal>trainer_id</literal> to <literal>Trainer</literal> (table name, <keycap>_</keycap>, trainer id) and a foreign key <literal>trainedTigers_id</literal> to <literal>Monkey</literal> (property name, <keycap>_</keycap>, Tiger primary column).
</para>
@@ -704,9 +704,9 @@
A many-to-many association is defined logically using the <literal>@ManyToMany</literal> annotation. You also have to describe the association table and the join conditions using the <literal>@JoinTable</literal> annotation. If the association is bidirectional, one side has to be the owner and one side has to be the inverse end (ie. it will be ignored when updating the relationship values in the association table):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_39.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_39.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_40.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_40.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
We've already shown the many declarations and the detailed attributes for associations. We'll go deeper in the <literal>@JoinTable</literal> description, it defines a <literal>name</literal>, an array of join columns (an array in annotation is defined using { A, B, C }), and an array of inverse join columns. The latter ones are the columns of the association table which refer to the <classname>Employee</classname> primary key (the "other side").
</para>
@@ -721,7 +721,7 @@
As any other annotations, most values are guessed in a many-to-many relationship. Without describing any physical mapping in a unidirectional many-to-many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_</keycap> and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table name, <keycap>_</keycap> and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s). These are the same rules used for a unidirectional one-to-many relationship.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_41.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_41.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <literal>Store_City</literal> is used as the join table. The <literal>Store_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>implantedIn_id</literal> column is a foreign key to the <literal>City</literal> table.
</para>
@@ -729,7 +729,7 @@
Without describing any physical mapping in a bidirectional many-to-many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_</keycap> and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the other side property name, <keycap>_</keycap>, and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s). These are the same rules used for a unidirectional one-to-many relationship.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_42.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_42.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <literal>Store_Customer</literal> is used as the join table. The <literal>stores_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>customers_id</literal> column is a foreign key to the <literal>Customer</literal> table.
</para>
@@ -789,21 +789,21 @@
Composite primary keys use a embedded class as the primary key representation, so you'd use the <literal>@Id</literal> and <literal>@Embeddable</literal> annotations. Alternatively, you can use the <literal>@EmbeddedId</literal> annotation. Note that the dependent class has to be serializable and implements <methodname>equals()</methodname>/<methodname>hashCode()</methodname>. You can also use <literal>@IdClass</literal> as described in <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Mapping_with_EJB3JPA_Annotations-Mapping_identifier_properties" />.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_43.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_43.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
or alternatively
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_44.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_44.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@Embeddable</literal> inherits the access type of its owning entity unless the Hibernate-specific annotation <literal>@AccessType</literal> is used. Composite foreign keys (if not using the default sensitive values) are defined on associations using the <literal>@JoinColumns</literal> element, which is basically an array of <literal>@JoinColumn</literal>. It is considered a good practice to express <literal>referencedColumnNames</literal> explicitly. Otherwise, Hibernate will suppose that you use the same order of columns as in the primary key declaration.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_45.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_45.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_46.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_46.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_47.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_47.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note the explicit usage of the <literal>referencedColumnName</literal>.
</para>
@@ -815,7 +815,7 @@
You can map a single entity bean to several tables using the <literal>@SecondaryTable</literal> or <literal>@SecondaryTables</literal> class level annotations. To express that a column is in a particular table, use the <literal>table</literal> parameter of <literal>@Column</literal> or <literal>@JoinColumn</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_48.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_48.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this example, <literal>name</literal> will be in <literal>MainCat</literal>. <literal>storyPart1</literal> will be in <literal>Cat1</literal> and <literal>storyPart2</literal> will be in <literal>Cat2</literal>. <literal>Cat1</literal> will be joined to <literal>MainCat</literal> using the <literal>cat_id</literal> as a foreign key, and <literal>Cat2</literal> using <literal>id</literal> (ie the same column name, the <literal>MainCat</literal> id column has). Plus a unique constraint on <literal>storyPart2</literal> has been set.
</para>
@@ -834,7 +834,7 @@
You can map EJBQL/HQL queries using annotations. <literal>@NamedQuery</literal> and <literal>@NamedQueries</literal> can be defined at the class level or in a JPA XML file. However their definitions are global to the session factory/entity manager factory scope. A named query is defined by its name and the actual query string.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_49.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_49.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also provide some hints to a query through an array of <literal>QueryHint</literal> through a <literal>hints</literal> attribute.
</para>
@@ -936,18 +936,18 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_50.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_50.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<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 language="java"><xi:include href="extras/Code_Example_51.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_51.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this example, we only describe the entity member of the result set mapping. The property / column mapping 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 involves 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 language="java"><xi:include href="extras/Code_Example_52.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_52.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
If you look at the dimension property, you'll see that although EJB3 implementations do not have to support the dotted notation for embedded objects, Hobernate does. You can even have nested embedded objects.
@@ -957,12 +957,12 @@
If you retrieve a single entity and if you use the default mapping, you can use the <literal>resultClass</literal> attribute instead of <literal>resultSetMapping</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_53.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_53.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In some of your native queries, you'll have to return scalar values, for example when building report queries. You can map them in the <literal>@SqlResultsetMapping</literal> through <literal>@ColumnResult</literal>. You actually can even mix entities and scalar returns in the same native query (this is probably not common though).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_54.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_54.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Another query hint specific to native queries has been introduced: <literal>org.hibernate.callable</literal> which can be true or false depending on whether the query is a stored procedure or not.
</para>
@@ -1049,9 +1049,9 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_55.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_55.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_56.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_56.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
</section>
@@ -1067,7 +1067,7 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_57.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_57.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
<literal>strategy</literal> is the short name of a Hibernate3 generator strategy or the fully qualified class name of an <classname>IdentifierGenerator</classname> implementation. You can add some parameters through the <literal>parameters</literal> attribute.
@@ -1076,7 +1076,7 @@
Contrary to their standard counterpart, <literal>@GenericGenerator</literal> and <literal>@GenericGenerators</literal> can be used in package-level annotations, making them application-level generators (just like if they were in a JPA XML file).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_58.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_58.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Identifier-NaturalId">
@@ -1085,7 +1085,7 @@
While not used as identifier property, some (groups of) properties represent the natural identifier of an entity. This is especially true when the schema uses the recommended approach of using surrogate primary key even if a natural business key exists. Hibernate allows to map such natural properties and reuse them in a <classname>Criteria</classname> query. The natural identifier is composed of all the properties marked <classname>@NaturalId</classname>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_60.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_60.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that the group of properties representing the natural identifier have to be unique (Hibernate will generate a unique constraint if the database schema is generated).
</para>
@@ -1153,7 +1153,7 @@
If a superclass or an embeddable object is not annotated, the root entity access type is used (even if an access type has been define on an intermediate superclass or embeddable object). The "Matryoshka doll principle" does not apply.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_61.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_61.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Formula">
@@ -1162,7 +1162,7 @@
Sometimes, you want the Database to do some computation for you rather than in the JVM, you might also create some kind of virtual column. You can use a SQL fragment (aka formula) instead of mapping a property into a column. This kind of property is read only (its value is calculated by your formula fragment).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_62.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_62.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The SQL fragment can be as complex as you want and even include subselects.
</para>
@@ -1177,12 +1177,12 @@
<literal>@org.hibernate.annotations.TypeDef</literal> and <literal>@org.hibernate.annotations.TypeDefs</literal> allows you to declare type definitions. These annotations are placed at the class or package level. Note that these definitions will be global for the session factory (even at the class level) and that type definition has to be defined before any usage.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_63.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_63.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
When using composite user type, you will have to express column definitions. The <literal>@Columns</literal> has been introduced for that purpose.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_64.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_64.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Index">
@@ -1191,7 +1191,7 @@
You can define an index on a particular column using the <literal>@Index</literal> annotation on a one column property, the columnNames attribute will then be ignored
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_65.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_65.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Parent">
@@ -1200,7 +1200,7 @@
When inside an embeddable object, you can define one of the properties as a pointer back to the owner element.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_66.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_66.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Generated_properties">
@@ -1209,7 +1209,7 @@
Some properties are generated at insert or update time by your database. Hibernate can deal with such properties and triggers a subsequent select to read these properties.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_67.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_67.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Annotate your property as <literal>@Generated</literal>. You have to make sure your insertability or updatability does not conflict with the generation strategy you have chosen. When <literal>GenerationTime.INSERT</literal> is chosen, the property must not contains insertable columns, when <literal>GenerationTime.ALWAYS</literal> is chosen, the property must not contains insertable nor updatable columns.
</para>
@@ -1224,7 +1224,7 @@
Sometimes, the type guessed by reflection is not the one you want Hibernate to use. This is especially true of components when an interface is used. You can use <literal>@Target</literal> to bypass the reflection guessing mechanism (very much like the <literal>targetEntity</literal> attribute available on associations.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_68.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_68.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Optimistic_lock">
@@ -1245,7 +1245,7 @@
<literal>SINGLE_TABLE</literal> is a very powerful strategy but sometimes, and especially for legacy systems, you cannot add an additional discriminator column. For that purpose, Hibernate has introduced the notion of discriminator formula: <literal>@DiscriminatorFormula</literal> is a replacement of <literal>@DiscriminatorColumn</literal> and use a SQL fragment as a formula for discriminator resolution (no need to have a dedicated column).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_69.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_69.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
By default, when querying the top entities, Hibernate does not put a restriction clause on the discriminator column. This can be inconvenient if this column contains values not mapped in your hierarchy (through <literal>@DiscriminatorValue</literal>). To work around that you can use <literal>@ForceDiscriminator</literal> (at the class level, next to <literal>@DiscriminatorColumn</literal>). Hibernate will then list the available values when loading the entities.
</para>
@@ -1253,7 +1253,7 @@
You can define the foreign key name generated by Hibernate for subclass tables in the JOINED inheritance strategy.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_70.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_70.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The foreign key from the <literal>Document</literal> table to the <literal>File</literal> table will be named <literal>FK_DOCU_FILE</literal>.
</para>
@@ -1265,12 +1265,12 @@
By default, when Hibernate cannot resolve the association because the expected associated element is not in database (wrong id on the association column), an exception is raised by Hibernate. This might be inconvenient for legacy and badly maintained schemas. You can ask Hibernate to ignore such elements instead of raising an exception using the <literal>@NotFound</literal> annotation. This annotation can be used on a <literal>@OneToOne</literal> (with FK), <literal>@ManyToOne</literal>, <literal>@OneToMany</literal> or <literal>@ManyToMany</literal> association.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_71.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_71.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Sometimes you want to delegate to your database the deletion of cascade when a given entity is deleted.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_72.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_72.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this case Hibernate generates a cascade delete constraint at the database level.
</para>
@@ -1278,7 +1278,7 @@
Foreign key constraints, when generated by Hibernate, have a fairly unreadable name. You can override the constraint name by using <literal>@ForeignKey</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_73.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_73.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<section id="sect-Hibernate_Annotations_Reference_Guide-Single_Association_related_annotations-Lazy_options_and_fetching_modes">
<title>Lazy options and fetching modes</title>
<para>
@@ -1370,7 +1370,7 @@
The @Any annotation describes the column holding the metadata information. To link the value of the metadata information and an actual entity type, The <classname>@AnyDef</classname> and <classname>@AnyDefs</classname> annotations are used.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_74.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_74.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<methodname>idType</methodname> represents the target entities identifier property type and <methodname>metaType</methodname> the metadata type (usually String).
</para>
@@ -1378,7 +1378,7 @@
Note that <classname>@AnyDef</classname> can be mutualized and reused. It is recommended to place it as a package metadata in this case.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_75.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_75.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
@@ -1419,7 +1419,7 @@
You can also declare a sort comparator. Use the <literal>@Sort</literal> annotation. Expressing the comparator type you want between unsorted, natural or custom comparator. If you want to use your own comparator implementation, you'll also have to express the implementation class using the <literal>comparator</literal> attribute. Note that you need to use either a <classname>SortedSet</classname> or a <classname>SortedMap</classname> interface.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_76.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_76.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Please refer to the previous descriptions of these annotations for more information.
</para>
@@ -1427,7 +1427,7 @@
Foreign key constraints, while generated by Hibernate, have a fairly unreadable name. You can override the constraint name by use <literal>@ForeignKey</literal>. Note that this annotation has to be placed on the owning side of the relationship, <literal>inverseName</literal> referencing to the other side constraint.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_77.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_77.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Collection_related_annotations-Extra_collection_types" revision="1">
@@ -1438,7 +1438,7 @@
Beyond EJB3, Hibernate Annotations supports true <classname>List</classname> and <classname>Array</classname>. Map your collection the same way as usual and add the @<literal>IndexColumn</literal>. This annotation allows you to describe the column that will hold the index. You can also declare the index value in DB that represent the first element (aka as base index). The usual value is <literal>0</literal> or <literal>1</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_78.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_78.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
If you forgot to set <literal>@IndexColumn</literal>, the bag semantic is applied. If you want the bag semantic without the limitations of it, consider using <literal>@CollectionId</literal>.
@@ -1455,7 +1455,7 @@
Both <literal>@org.hibernate.annotations.MapKey</literal> and <literal>@org.hibernate.annotations.MapKeyManyToMany</literal> allow you to override the target element to be used. This is especially useful if your collection does not use generics (or if you use interfaces).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_79.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_79.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Extra_collection_types-Bidirectional_association_with_indexed_collections" revision="2">
@@ -1464,12 +1464,12 @@
A bidirectional association where one end is an indexed collection (that is, represented as a <literal>@IndexColumn</literal>, <literal>@org.hibernate.annotations.MapKey</literal> or <classname>@org.hibernate.annotations.MapKeyManyToMany</classname>) requires special consideration. If a property on the associated class explicitly maps the indexed value, the use of <methodname>mappedBy</methodname> is permitted:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_80.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_80.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
But, if there is no such property on the child class, we can't think of the association as truly bidirectional (there is information available at one end of the association that is not available at the other end: the index). In this case, we can't map the collection as <literal>mappedBy</literal>. Instead, we could use the following mapping:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_81.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_81.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that in this mapping, the collection-valued end of the association is responsible for updating the foreign key.
</para>
@@ -1481,7 +1481,7 @@
Another interesting feature is the ability to define a surrogate primary key to a bag collection. This removes pretty much all of the drawbacks of bags: update and removal are efficient, more than one <literal>EAGER</literal> bag per query or per entity. This primary key will be contained in an additional column of your collection table but will not be visible to the Java application. @CollectionId is used to mark a collection as id bag, it also allow to override the primary key column(s), the primary key type and the generator strategy. The strategy can be <literal>identity</literal>, or any defined generator name of your application.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_82.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_82.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Extra_collection_types-Collection_of_element_or_composite_elements">
@@ -1493,7 +1493,7 @@
A collection of elements has to be annotated as <literal>@CollectionOfElements</literal> (as a replacement of <literal>@OneToMany</literal>) To define the collection table, the <literal>@JoinTable</literal> annotation is used on the association property, <literal>joinColumns</literal> defines the join columns between the entity primary table and the collection table (inverseJoincolumn is useless and should be left empty). For collection of core types or array of primitive types, you can override the element column definition using a <literal>@Column</literal> on the association property. You can also override the columns of a collection of embeddable object using <literal>@AttributeOverride</literal>. To reach the collection element, you need to append "element" to the attribute override name (eg "element" for core types, or "element.serial" for the serial property of an embeddable element). To reach the index/key of a collection, append "key" instead.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_83.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_83.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
On a collection of embeddable objects, the embeddable object can have a property annotated with <literal>@Parent</literal>. This property will then point back to the entity containing the collection.
</para>
@@ -1510,7 +1510,7 @@
<classname>@ManyToAny</classname> allows polymorphic associations to classes from multiple tables. This type of mapping always requires more than one column. The first column holds the type of the associated entity. The remaining columns hold the identifier. It is impossible to specify a foreign key constraint for this kind of association, so this is most certainly not meant as the usual way of mapping (polymorphic) associations. You should use this only in very special cases (eg. audit logs, user session data, etc).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_84.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_84.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Like <classname>@Any</classname>, <classname>@ManyToAny</classname> can use named <classname>@AnyDef</classname>s, see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Single_Association_related_annotations-Any" /> for more information.
</para>
@@ -1581,7 +1581,7 @@
This is especially useful for <literal>SAVE_UPDATE</literal> (which is the operation cascaded at flush time if you use plain Hibernate Annotations - Hibernate EntityManager cascade <literal>PERSIST</literal> at flush time as per the specification). <literal>DELETE_ORPHAN</literal> applies only to <literal>@OneToMany</literal> associations, and indicates that the <methodname>delete()/remove()</methodname> operation should be applied to any child object that is removed from the association. In other words, if a child is dereferenced by a persistent parent and if <literal>DELETE_ORPHAN</literal> is used, the "orphaned" child is deleted.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_85.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_85.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
It is recommended to use @Cascade to compliment @*To*(cascade=...) as shown in the previous example.
</para>
@@ -1596,11 +1596,11 @@
<literal>@org.hibernate.annotations.Cache</literal> defines the caching strategy and region of a given second level cache. This annotation can be applied on the root entity (not the sub entities), and on the collections.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_86.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_86.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_87.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_87.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_88.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_88.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes:</title>
<listitem>
<para>
@@ -1635,13 +1635,13 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_89.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_89.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
When the collection uses an association table as a relational representation, you might want to apply the filter condition to the association table itself or to the target entity table. To apply the constraint on the target entity, use the regular <literal>@Filter</literal> annotation. However, if you want to target the association table, use the <literal>@FilterJoinTable</literal> annotation.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_90.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_90.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Hibernate_Annotation_Extensions-Queries">
@@ -1680,7 +1680,7 @@
Hibernate gives you the ability to override every single SQL statement generated. We have seen native SQL query usage already, but you can also override the SQL statement used to load or change the state of entities.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_91.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_91.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@SQLInsert</literal>, <literal>@SQLUpdate</literal>, <literal>@SQLDelete</literal>, <literal>@SQLDeleteAll</literal> respectively override the <literal>INSERT</literal> statement, <literal>UPDATE</literal> statement, <literal>DELETE</literal> statement, <literal>DELETE</literal> statement to remove all entities.
</para>
@@ -1708,7 +1708,7 @@
You can use the exact same set of annotations to override the collection related statements.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_92.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_92.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The order of the parameters is important and is defined by the order Hibernate handles properties. You can see the expected order by enabling debug logging for the <literal>org.hibernate.persister.entity</literal> level. With this, level-enabled Hibernate will print out the static SQL that is used to create, update, delete etc. entities. (To see the expected sequence, remember not to include your custom SQL through annotations as that will override the Hibernate-generated static sql.)
</para>
@@ -1716,7 +1716,7 @@
Overriding SQL statements for secondary tables is also possible using <literal>@org.hibernate.annotations.Table</literal> and either (or all) attributes <literal>sqlInsert</literal>, <literal>sqlUpdate</literal>, <literal>sqlDelete</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_93.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_93.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The previous example also show that you can give a comment to a given table (primary or secondary): This comment will be used for DDL generation.
</para>
@@ -1731,7 +1731,7 @@
To define tuplixer in annotations, simply use the <literal>@Tuplizer</literal> annotation on the according element
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_94.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_94.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -24,7 +24,7 @@
You can define global level metadata available for all XML files. You must not define these metadata more than once per deployment.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_95.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_95.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>xml-mapping-metadata-complete</literal> means that all entity, mapped-superclasses and embeddable metadata should be picked up from XML (that is, ignore annotations).
</para>
@@ -42,7 +42,7 @@
You can either define or override metadata information on a given entity.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_96.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_96.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -112,7 +112,7 @@
</orderedlist>
- <programlisting language="xml"><xi:include href="extras/Code_Example_97.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_97.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -153,7 +153,7 @@
You can of course define XML overriding for properties. If metadata complete is defined, then additional properties (ie at the Java level) will be ignored. Otherwise, once you start overriding a property, all annotations on the given property are ignored. All property level metadata resides in <literal>entity/attributes</literal>, <literal>mapped-superclass/attributes</literal> or <literal>embeddable/attributes</literal>.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_98.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_98.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override a property through <literal>id</literal>, <literal>embedded-id</literal>, <literal>version</literal>, <literal>embedded</literal> and <literal>basic</literal>. Each of these elements can have sub-elements accordingly: <literal>lob</literal>, <literal>temporal</literal>, <literal>enumerated</literal>, <literal>column</literal>.
</para>
@@ -165,7 +165,7 @@
You can define XML overriding for associations. All association level metadata behave in <literal>entity/attributes</literal>, <literal>mapped-superclass/attributes</literal> or <literal>embeddable/attributes</literal>.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_99.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_99.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override an association through <literal>one-to-many</literal>, <literal>one-to-one</literal>, <literal>many-to-one</literal>, and <literal>many-to-many</literal>. Each of these elements can have sub-elements accordingly: <literal>join-table</literal> (which can have <literal>join-column</literal>s and <literal>inverse-join-column</literal>s), <literal><literal>join-column</literal>s</literal>, <literal>map-key</literal>, and <literal>order-by</literal>. <literal>mapped-by</literal> and <literal>target-entity</literal> can be defined as attributes when it makes sense. Once again the structure is reflects the annotations structure. You can find all semantic information in <xref linkend="chap-Hibernate_Annotations_Reference_Guide-Entity_Beans" />.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -55,13 +55,13 @@
</para>
<para>
We also recommend a small wrapper class to startup Hibernate in a static initializer block, known as <classname>HibernateUtil</classname>. You might have seen this class in various forms in other areas of the Hibernate documentation. For Annotation support you have to enhance this helper class as follows:
- <programlisting language="java"><xi:include href="extras/Code_Example_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
Interesting here is the use of <classname>AnnotationConfiguration</classname>. The packages and annotated classes are declared in your regular XML configuration file (usually <filename>hibernate.cfg.xml</filename>). Here is the equivalent of the above declaration:
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that you can mix the hbm.xml use and the new annotation one. The resource element can be either an hbm file or an EJB3 XML deployment descriptor. The distinction is transparent for your configuration process.
</para>
@@ -69,7 +69,7 @@
Alternatively, you can define the annotated classes and packages using the programmatic API
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also use the Hibernate EntityManager which has its own configuration mechanism. Please refer to this project documentation for more details.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -40,12 +40,12 @@
<para>
As an example, to execute an EJB-QL <literal>UPDATE</literal>, use the <literal>Query.executeUpdate()</literal> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
To execute an EJB-QL <literal>DELETE</literal>, use the same <literal>Query.executeUpdate()</literal> method (the method is named for those familiar with JDBC's <literal>PreparedStatement.executeUpdate()</literal>):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></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 inheritance hierarchy.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -13,7 +13,7 @@
A method of the entity may be designated as a callback method to receive notification of a particular entity life cycle event. Callbacks methods are annotated by a callback annotation. You can also define an entity listener class to be used instead of the callback methods defined directly inside the entity class. An entity listener is a stateless class with a no-arg constructor. An entity listener is defined by annotating the entity class with the <literal>@EntityListeners</literal> annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The same callback method or entity listener method can be annotated with more than one callback annotation. For a given entity, you cannot have two methods being annotated by the same callback annotation whether it is a callback method or an entity listener method. A callback method is a no-arg method with no return type and any arbitrary name. An entity listener has the signature <code>void <METHOD>(Object)</code> where Object is of the actual entity type (note that Hibernate Entity Manager relaxed this constraint and allows <literal>Object</literal> of <literal>java.lang.Object</literal> type (allowing sharing of listeners across several entities.)
</para>
@@ -145,7 +145,7 @@
<para>
The EJB3 specification allows annotation overriding through EJB3 deployment descriptor. There is also an additional feature that can be useful: default event listeners.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_33.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_33.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override entity listeners on a given entity. An entity listener correspond to a given class and one or several event fire a given method call. You can also define event on the entity itself to describe the callbacks.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -13,12 +13,12 @@
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 which is used when creating a SQL query on <literal>EntityManager</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also define scalar results and even mix entity results and scalar results
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The SQL query will then have to return a column alias <literal>durationInSec</literal>.
</para>
@@ -33,11 +33,11 @@
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>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This native query returns nights and area based on the <literal>GetNightAndArea</literal> result set.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The second version is useful when your SQL query returns one entity reusing the same columns as the ones mapped in metadata.
</para>
@@ -48,7 +48,7 @@
<para>
Native named queries share the same calling API than EJB-QL named queries. Your code doesn't need to know the difference between the two. This is very useful for migration from SQL to EJB-QL:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</chapter>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -19,12 +19,12 @@
The configuration for entity managers both inside an application server and in a standalone application reside in a persistence archive. A persistence archive is a JAR file which must define a <literal>persistence.xml</literal> file that resides in the <filename>META-INF</filename> folder. All properly annotated classes included in the archive (ie having an <literal>@Entity</literal> annotation), all annotated packages and all Hibernate <filename>hbm.xml</filename> files included in the archive will be added to the persistence unit configuration, so by default, your <filename>persistence.xml</filename> will be quite minimalist:
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Here's a more complete example of a <filename><literal>persistence.xml</literal></filename> file
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<variablelist spacing="compact">
<varlistentry>
<term><code>name</code></term>
@@ -73,7 +73,7 @@
The jar-file elements specifies a jar to analyze. All properly annotated classes, annotated packages and all hbm.xml files part of this jar file will be added to the persistence unit configuration. This element is mainly used in Java EE environment. Use of this one in Java SE should be considered as non portable, in this case a absolute url is needed. You can alternatively point to a directory (This is especially useful when in your test environment, the persistence.xml file is not under the same root directory or jar than your domain model).
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
</varlistentry>
<varlistentry>
@@ -105,7 +105,7 @@
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 language="xml"><xi:include href="extras/Code_Example_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Configuration_and_bootstrapping-Bootstrapping" revision="1">
@@ -114,7 +114,7 @@
The EJB3 specification defines a bootstrap procedure to access the <classname>EntityManagerFactory</classname> and the <classname>EntityManager</classname>. The bootstrap class is <classname>javax.persistence.Persistence</classname>, for example:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The first version is equivalent to the second with an empty map. The map version is a set of overrides that will take precedence over any properties defined in your persistence.xml files. There are a couple of EJB3 properties usable in the map:
</para>
@@ -257,13 +257,13 @@
Here is a typical configuration in a J2SE environment
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
To ease the programmatic configuration, Hibernate Entity Manager provides a proprietary API. This API is very similar to the <classname>Configuration</classname> API and shares the same concepts: <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the Hibernate reference guide for more detailed information on how to use it.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -189,7 +189,7 @@
If an EJB3 persistence layer runs in a non-managed environment, database connections are usually handled by Hibernate's pooling mechanism behind the scenes. The common entity manager and transaction handling idiom looks like this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You don't have to <literal>flush()</literal> the <literal>EntityManager</literal> explicitly - the call to <literal>commit()</literal> automatically triggers the synchronization.
</para>
@@ -223,7 +223,7 @@
If you use bean-managed transactions (BMT), the code will look like this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
With Container Managed Transactions (CMT) in an EJB3 container, transaction demarcation is done in session bean annotations or deployment descriptors, not programatically. The <literal>EntityManager</literal> will automatically be flushed on transaction completion (and if you have injected or lookup the <literal>EntityManager</literal>, it will be also closed automatically). If an exception occurs during the <literal>EntityManager</literal> use, transaction rollback occurs automatically if you don't catch the exception. Since <literal>EntityManager</literal> exceptions are <literal>RuntimeException</literal>s they will rollback the transaction as per the EJB specification (system exception vs. application exception).
</para>
@@ -237,7 +237,7 @@
Our entity manager/transaction management idiom for CMT and EJB3 container-use is reduced to this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<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>
@@ -364,7 +364,7 @@
In an implementation without much help from the persistence mechanism, each interaction with the database occurs in a new <literal>EntityManager</literal> and the developer is responsible for reloading all persistent instances from the database before manipulating them. This approach forces the application to carry out its own version checking to ensure application transaction isolation. This approach is the least efficient in terms of database access. It is the approach most similar to EJB2 entities:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>version</literal> property is mapped using <literal>@Version</literal>, and the entity manager will automatically increment it during flush if the entity is dirty.
</para>
@@ -388,7 +388,7 @@
The <literal>Entity Manager</literal> is disconnected from any underlying JDBC connection when waiting for user interaction. In an application-managed extended entity manager, this occurs automatically at transaction completion. In a stateful session bean holding a container-managed extended entity manager (i.e. a SFSB annotated with <literal>@PersistenceContext(EXTENDED)</literal>), this occurs transparently as well. This approach is the most efficient in terms of database access. The application need not concern itself with version checking or with merging detached instances, nor does it have to reload instances in every database transaction. For those who might be concerned by the number of connections opened and closed, remember that the connection provider should be a connection pool, so there is no performance impact. The following examples show the idiom in a non-managed environment:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>foo</literal> object still knows which <literal>persistence context</literal> it was loaded in. With <literal>getTransaction.begin();</literal> the entity manager obtains a new connection and resumes the persistence context. The method <literal>getTransaction().commit()</literal> will not only flush and check versions, but also disconnects the entity manager from the JDBC connection and return the connection to the pool.
</para>
@@ -405,7 +405,7 @@
<para>
With this paradigm, each interaction with the data store occurs in a new persistence context. However, the same persistent instances are reused for each interaction with the database. The application manipulates the state of detached instances originally loaded in another persistence context and then merges the changes using <literal>EntityManager.merge()</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Again, the entity manager will check instance versions during flush, throwing an exception if conflicting updates occurred.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -30,7 +30,7 @@
Once you've created a new entity instance (using the common <literal>new</literal> operator) it is in the <literal>new</literal> state. You can make it persistent by associating it to an entity manager:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If the <literal>DomesticCat</literal> entity type has a generated identifier, the value is associated to the instance when <code>persist()</code> is called. If the identifier is not automatically generated, the application-assigned (usually natural) key value has to be set on the instance before <code>persist()</code> is called.
</para>
@@ -42,17 +42,17 @@
Load an entity instance by its identifier value with the entity manager's <code>find()</code> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In some cases, you don't really want to load the object state, but just have a reference to it (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 language="java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<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 refreshed unless you specify <literal>REFRESH</literal> as a cascade style of any associations:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Querying_objects">
@@ -66,7 +66,7 @@
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>
-<!-- <programlisting language="java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>-->
+<!-- <programlisting language="Java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>-->
<para>
A query is usually executed by invoking <methodname>getResultList()</methodname>. This method loads the resulting instances of the query completely 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>
@@ -76,7 +76,7 @@
An EJB3QL query queries can return tuples of objects if projection is used. Each result tuple is returned as an object array:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Scalar_results">
@@ -85,7 +85,7 @@
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 language="java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Bind_parameters">
@@ -94,7 +94,7 @@
Both named and positional query parameters are supported. The <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 preferred, they are more robust and easier to read and understand:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Pagination">
@@ -103,7 +103,7 @@
If you need to specify bounds upon your result set (the maximum number of rows you want to retrieve and/or the first row you want to retrieve), use the following methods:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Hibernate knows how to translate this limit query into the native SQL of your DBMS.
</para>
@@ -115,12 +115,12 @@
You may also define named queries through annotations:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Parameters are bound programatically to the named query, before it is executed:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that the actual program code is independent of the query language that is used. You may also define native SQL queries in metadata, or use Hibernate's native facilities by placing them in XML mapping files.
</para>
@@ -132,7 +132,7 @@
You may express a query in SQL, using <methodname>createNativeQuery()</methodname> and let Hibernate take care mapping from JDBC result sets to business objects. Use the <literal>@SqlResultSetMapping</literal> (please see the Hibernate Annotations reference documentation on how to map a SQL resultset mapping) or the entity mapping (if the column names of the query result are the same as the names declared in the entity mapping. Remember that all entity columns have to be returned for this mechanism to work):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
For more information about scalar support in named queries, please refers to the Hibernate Annotations documentation
@@ -251,7 +251,7 @@
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 in <xref linkend="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Flush_the_persistence_context" />). 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 language="java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Sometimes this programming model is inefficient since it would require both an SQL SELECT (to load an object) and an SQL UPDATE (to persist its updated state) in the same session. Therefore Hibernate offers an alternate approach, using detached instances.
</para>
@@ -266,7 +266,7 @@
The EJB3 specifications supports this development model by providing for persistence of modifications made to detached instances using the <methodname>EntityManager.merge()</methodname> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>merge()</literal> method merges modifications made to the detached instance into the corresponding managed instance, if any, without consideration of the state of the persistence context. In other words, the merged objects state overrides the persistent entity state in the persistence context, if one is already present. The application should individually <methodname>merge()</methodname> detached instances reachable from the given detached instance if and only if it wants their state also to be persistent. This can be cascaded to associated entities and collections, using transitive persistence, see <xref linkend="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Transitive_persistence" />.
</para>
@@ -278,7 +278,7 @@
The merge operation is clever enough to automatically detect whether the merging of the detached instance has to result in an insert or update. In other words, you don't have to worry about passing a new instance (and not a detached instance) to <literal>merge()</literal>, the entity manager will figure this out for you:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The usage and semantics of <literal>merge()</literal> seem to be confusing for new users. Remember that as long as you are not trying to use an object state loaded in one entity manager in another new entity manager, you should not need to use <methodname>merge()</methodname> at all. Some whole applications will never use this method.
</para>
@@ -424,7 +424,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 language="java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
During flush, an exception might happen (e.g. if a DML operation violates a constraint).
</para>
@@ -457,12 +457,12 @@
For each basic operation of the entity manager - including <methodname>persist()</methodname>, <methodname>merge()</methodname>, <methodname>remove()</methodname>, <methodname>refresh()</methodname> - there is a corresponding cascade style. Respectively, the cascade styles are named PERSIST, MERGE, REMOVE, REFRESH. If you want an operation to be cascaded to associated entity (or collection of entities), you must indicate that in the association annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Cascading options can be combined:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You may even use CascadeType.ALL to specify that all operations should be cascaded for a particular association. Remember that by default, no operation is cascaded.
</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP07.ent
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP07.ent 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP07.ent 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,3 +1,4 @@
+<!ENTITY HOLDER "Red Hat, Inc">
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "Hibernate_Search">
<!ENTITY YEAR "2009">
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -66,7 +66,7 @@
Core, use the following configuration in
<literal>hibernate.cfg.xml</literal>:</para>
- <programlisting language="xml"><xi:include href="extras/hibernate_config.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/hibernate_config.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="Hibernate_Validator-Checkconstraints-orm-jpaevent">
@@ -85,7 +85,7 @@
<para>Here is how to make a class validatable:</para>
- <programlisting language="java"><xi:include href="extras/class_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/class_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para><note>
<para>Compared to the Hibernate event, the Java Persistence listener
@@ -102,7 +102,7 @@
<para>Hibernate Validator can be applied anywhere in your application
code.</para>
- <programlisting language="java"><xi:include href="extras/app_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/app_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The first two lines prepare the Hibernate Validator for class
checking. The first one relies upon the error messages embedded in
@@ -116,7 +116,7 @@
<para>You can also check a particular property instead of the whole bean.
This might be useful for property per property user interaction</para>
- <programlisting language="java"><xi:include href="extras/check_property.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/check_property.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="Hibernate_Validator-Checkconstraints-presentationlayer">
@@ -128,7 +128,7 @@
<literal><s:validateAll/></literal>, letting the constraints be
expressed on the model, and the violations presented in the view.</para>
- <programlisting language="java"><xi:include href="extras/pres_validation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/pres_validation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>Going even further, and adding <productname>Ajax4JSF</productname>
to the loop will bring client side validation with just a couple of
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -278,7 +278,7 @@
<emphasis>validator</emphasis> (the implementation class). Here is a
simple user-defined descriptor:</para>
- <programlisting language="java"><xi:include href="extras/define_descriptor.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/define_descriptor.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para><literal>type</literal> is a parameter describing how the property
should to be capitalized. This is a user parameter fully dependant on the
@@ -295,7 +295,7 @@
good practice. See <xref linkend="Hibernate_Validator-Defineconstraints-error" />
.</para>
- <programlisting language="java"><xi:include href="extras/validator_capitalized.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/validator_capitalized.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>As you can see the {} notation is recursive.</para>
@@ -311,7 +311,7 @@
database level (by implementing
<literal>PersistentClassConstraint</literal> )</para>
- <programlisting language="java"><xi:include href="extras/validator_implementation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/validator_implementation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The <literal>isValid()</literal> method should return false if the
constraint has been violated. For more examples, refer to the built-in
@@ -327,7 +327,7 @@
parameters) on the same property or type, you can use the following
annotation form:</para>
- <programlisting language="java"><xi:include href="extras/constraint_annotation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/constraint_annotation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>Basically an annotation containing the value attribute as an array
of validator annotations.</para>
@@ -339,18 +339,18 @@
<para>Since you are already familiar with annotations now, the syntax
should be very familiar.</para>
- <programlisting language="java"><xi:include href="extras/annotation_syntax.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotation_syntax.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>While the example only shows public property validation, you can
also annotate fields of any kind of visibility.</para>
- <programlisting language="java"><xi:include href="extras/annotate_constraint.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotate_constraint.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>You can also annotate interfaces. Hibernate Validator will check all
superclasses and interfaces extended or implemented by a given bean to
read the appropriate validator annotations.</para>
- <programlisting language="java"><xi:include href="extras/annotate_interface.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotate_interface.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The name property will be checked for nullity when the Dog bean is
validated.</para>
Modified: projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP07.ent
===================================================================
--- projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP07.ent 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP07.ent 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,3 +1,4 @@
+<!ENTITY HOLDER "Red Hat, Inc">
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "Hibernate_Validator">
<!ENTITY YEAR "2009">
Modified: projects/docs/enterprise/4.2.8/Installation_Guide/publican.cfg
===================================================================
--- projects/docs/enterprise/4.2.8/Installation_Guide/publican.cfg 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.2.8/Installation_Guide/publican.cfg 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,5 +1,5 @@
# Config::Simple 4.59
-# Fri Nov 6 12:45:46 2009
+# Mon Nov 9 07:59:00 2009
debug: 1
xml_lang: en-US
Modified: projects/docs/enterprise/4.3.7/Getting_Started/en-US/Getting_Started_Guide_CP06.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Getting_Started/en-US/Getting_Started_Guide_CP06.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Getting_Started/en-US/Getting_Started_Guide_CP06.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -7,6 +7,7 @@
<xi:include href="Preface_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="The_JBoss_Server___A_Quick_Tour.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="EJB3_Caveats.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="About_the_Example_Applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Sample_JSF_EJB3_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Added: projects/docs/enterprise/4.3.7/Getting_Started/en-US/Logging.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Getting_Started/en-US/Logging.xml (rev 0)
+++ projects/docs/enterprise/4.3.7/Getting_Started/en-US/Logging.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -0,0 +1,667 @@
+?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis$
+]>
+
+<chapter id="logging">
+ <title>Logging Conventions</title>
+ <para>
+ Persisted diagnostic logs can be very helpful when it comes to debugging software issues. The logging service used in JBoss Enterprise Application Platform is <literal>log4j</literal>.
+ </para>
+ <para>
+ <literal>log4j</literal> is controlled from a central <filename>conf/log4j.xml</filename> file. This file defines a set of appenders that specify the name of the log files, the category of message that should be stored in each log file, the message format, and the level of filtering. By default, JBoss Application server produces output for both the console and a log file (<filename>server.log</filename> in the <filename>log</filename> directory).
+ </para>
+ <para>
+ This chapter teaches you some of the conventions that should be observed when configuring diagnostic logging.
+ </para>
+
+
+ <!--Section of uncertain necessity... #modify?-->
+ <section id="logging.get">
+ <title>Obtaining a Logger</title>
+ <para>
+ You can obtain a logger with the following code:
+ </para>
+ <programlisting role="JAVA">package org.jboss.X.Y;
+import org.jboss.logging.Logger;
+
+public class TestABCWrapper
+{
+ private static final Logger log = Logger.getLogger(TestABCWrapper.class.getName());
+
+ // Hereafter, the logger may be used with whatever priority level as appropriate.
+}</programlisting>
+ </section>
+
+
+ <section id="logging.levels">
+ <title>Logging Levels</title>
+ <para>
+ There are six basic levels of logging: <literal>FATAL</literal>, <literal>ERROR</literal>, <literal>WARN</literal>, <literal>INFO</literal>, <literal>DEBUG</literal>, and <literal>TRACE</literal>. This section describes some of the situations in which each level should be used.
+ </para>
+ <formalpara>
+ <title><literal>FATAL</literal></title>
+ <para>
+ Use the <literal>FATAL</literal> priority level for events that indicate a critical service failure. If a service issues a <literal>FATAL</literal> error, it is completely unable to service requests of any kind.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>ERROR</literal></title>
+ <para>
+ Use the <literal>ERROR</literal> priority level for events that indicate a disruption in the request, or in the ability to service a request. A service should have some capacity to continue to service requests in the presence of an <literal>ERROR</literal>.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>WARN</literal></title>
+ <para>
+ Use the <literal>WARN</literal> priority level for events that may indicate a non-critical service error, such as a resumable error or a minor breach in a request exception. The difference between the <literal>WARN</literal> priority and the <literal>ERROR</literal> priority can be difficult to discern, and is left to the developer's judgement. The simplest criterion is to ask whether a failure would result in a user calling support. If yes, we recommend using <literal>ERROR</literal>. If not, <literal>WARN</literal> is recommended.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>INFO</literal></title>
+ <para>
+ Use the <literal>INFO</literal> priority level for service life-cycle events and other crucial related information. The <literal>INFO</literal> log messages for a particular service category should accurately represent the state of the service.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>DEBUG</literal></title>
+ <para>
+ Use the <literal>DEBUG</literal> priority level to log messages that convey additional information regarding life-cycle events. This priority level is concerned with developer or in-depth information required for support. When <literal>DEBUG</literal> priority is enabled, the JBoss server log should not grow proportionally with the number of server requests. The <literal>DEBUG</literal> and <literal>INFO</literal> log messages for a particular service category should accurately represent the state of the service, and the server resources being used: ports, interfaces, log files, etc.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title><literal>TRACE</literal></title>
+ <para>
+ Use the <literal>TRACE</literal> priority level for log messages that are directly associated with activities that correspond to requests. These messages should not be submitted to a <classname>Logger</classname> unless the <classname>Logger</classname> category priority threshold indicates that the message will be rendered. Use the <classname>Logger.isTraceEnabled()</classname> method to determine whether the category priority threshold is enabled. The <literal>TRACE</literal> priority allows deep probing of JBoss server behavior where required. When <literal>TRACE</literal> is enabled, the number of messages in the JBoss server log is expected to grow at least <literal>a x N</literal>, where <literal>N</literal> is the number of requests received by the server, and <literal>a</literal> is some constant. The server log may grow as a power of <literal>N</literal>, depending on the request-handling layer being traced.
+ </para>
+ </formalpara>
+ </section>
+
+
+ <section id="logging.log4jconf">
+ <title>Log4j Configuration</title>
+ <para>
+ The <literal>log4j</literal> configuration is loaded from the <filename>conf/log4j.xml</filename> file. You can edit this file to add or change the default appenders and logging thresholds.
+ </para>
+ <section id="logging.log4j.applogs">
+ <title>Separating Application Logs</title>
+ <para>
+ You can divide or segment logging output by assigning <literal>log4j</literal> categories to specific appenders in the <filename>conf/log4j.xml</filename> configuration file, like so:
+ </para>
+ <programlisting><![CDATA[
+ <appender name="App1Log" class="org.apache.log4j.FileAppender">
+ <errorHandler
+ class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Append" value="false"/>
+ <param name="File"
+ value="${jboss.server.home.dir}/log/app1.log"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
+ </layout>
+ </appender>
+
+...
+
+ <category name="com.app1">
+ <appender-ref ref="App1Log"/>
+ </category>
+ <category name="com.util">
+ <appender-ref ref="App1Log"/>
+ </category>
+
+...
+
+ <root>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+ <appender-ref ref="App1Log"/>
+ </root>
+]]>
+ </programlisting>
+ </section>
+
+ <section id="logging.log4j.appsfilters">
+ <title>Specifying appenders and filters</title>
+ <para>
+ If you have multiple applications that make use of shared classes or categories, or you want to include JBoss categories in your application logs, the previous approach will not work. The <classname>TCLFilter</classname>, a new appender filter, was created to assist in these situations.
+ </para>
+ <para>
+ You can specify a filter by adding a <code><filter></code> element to your <code><appender></code> element in <filename>conf/log4j.xml</filename>. For example, if your <literal>app1</literal> deployment was <filename>app1.ear</filename>, you would use the following additions to the <filename>conf/log4j.xml</filename>:
+ </para>
+ <programlisting><![CDATA[
+<appender name="App1Log" class="org.apache.log4j.FileAppender">
+ <errorHandler
+ class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Append" value="false"/>
+ <param name="File"
+ value="${jboss.server.home.dir}/log/app1.log"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
+ </layout>
+ <filter class="org.jboss.logging.filter.TCLFilter">
+ <param name="AcceptOnMatch" value="true"/>
+ <param name="DeployURL" value="app1.ear"/>
+ </filter>
+ </appender>
+
+...
+
+ <root>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+ <appender-ref ref="App1Log"/>
+ </root>
+
+]]> </programlisting>
+ </section>
+
+ <section id="logging.log4j.server">
+ <title>Logging to a Separate Server</title>
+ <para>
+ The <literal>log4j</literal> framework has a number of appenders that let you send log messages to an external server. Common appenders include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.JMSAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SMTPAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SocketAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.SyslogAppender</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.apache.log4j.net.TelnetAppender</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can find more information about configuring these appenders at <ulink url="http://logging.apache.org/">Apache Logging Services</ulink>.
+ </para>
+ <section id="logging.log4j.server.setup">
+ <title>Setting up and using the <classname>Log4jSocketServer</classname> service</title>
+ <para>
+ The <classname>org.jboss.logging.Log4jSocketServer</classname> is an MBean service that allows one to collect output from multiple <literal>log4j</literal> clients (including JBoss servers) that use the <classname>org.apache.log4j.net.SocketAppender</classname>.
+ </para>
+ <para>
+ The <classname>Log4jSocketServer</classname> creates a server socket to accept <classname>SocketAppender</classname> connections, and logs incoming messages based on the local <filename>log4j.xml</filename> configuration.
+ </para>
+ <para>
+ You can create a minimal JBoss configuration that includes a <classname>Log4jSocketServer</classname> to act as your log server.
+ </para>
+ </section>
+ <section id="logging.log4j.server.conf">
+ <title>A <classname>Log4jSocketServer</classname> mbean configuration</title>
+ <para>
+ You can add the following MBean configuration to your <filename>conf/jboss-service.xml</filename>
+ </para>
+ <programlisting role="XML"><![CDATA[
+ <mbean code="org.jboss.logging.Log4jSocketServer"
+ name="jboss.system:type=Log4jService,service=SocketServer">
+ <attribute name="Port">12345</attribute>
+ <attribute name="BindAddress">${jboss.bind.address}</attribute>
+ </mbean>
+ ]]>
+ </programlisting>
+ <para>
+ The <classname>Log4jSocketServer</classname> adds an MDC entry under the key 'host' which includes the client socket <literal>InetAddress.getHostName</literal> value on every client connection. This allows you to differentiate logging output based on the client hostname using the MDC pattern.
+ </para>
+ </section>
+ <section id="logging.log4j.server.hostname">
+ <title>Augmenting the log server console output with the logging client socket hostname</title>
+ <programlisting role="XML"><![CDATA[
+<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
+ <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="Target" value="System.out"/>
+ <param name="Threshold" value="INFO"/>
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d{ABSOLUTE} %-5p [%c{1},%X{host}] %m%n"/>
+ </layout>
+</appender>
+]]>
+ </programlisting>
+ <para>
+ All other JBoss servers that should send log messages to the log server would add an appender configuration that uses the SocketAppender.
+ </para>
+ </section>
+ <section id="logging.log4j.server.xml">
+ <title><filename>log4j.xml</filename> appender for the <classname>Log4jSocketServer</classname></title>
+ <programlisting role="XML"><![CDATA[
+<appender name="SOCKET" class="org.apache.log4j.net.SocketAppender">
+ <param name="Port" value="12345"/>
+ <param name="RemoteHost" value="loghost"/>
+ <param name="ReconnectionDelay" value="60000"/>
+ <param name="Threshold" value="INFO"/>
+</appender>
+]]>
+ </programlisting>
+ </section>
+ </section>
+
+
+ <section id="logging.log4j.subsys">
+ <title>Key JBoss Subsystem Categories</title>
+ <para>
+ Some of the key subsystem category names are given in the following table. These are just the top level category names. Generally you can specify much more specific category names to enable very targeted logging.
+ </para>
+ <table><title>JBoss Subsystem Categories</title>
+ <tgroup cols='2' align='center' colsep='1' rowsep='1'>
+ <colspec colname='Subsystem'>
+ <colspec colname='Category'>
+ <thead>
+ <row>
+ <entry>Subsystem</entry>
+ <entry>Category</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry><classname></classname></entry>
+ </row>
+ <row>
+ <entry>CMP</entry>
+ <entry><classname>org.jboss.ejb. plugins.cmp</classname></entry>
+ </row>
+ <row>
+ <entry>Core Service</entry>
+ <entry><classname>org.jboss.system</classname></entry>
+ </row>
+ <row>
+ <entry>Cluster</entry>
+ <entry><classname>org.jboss.ha</classname></entry>
+ </row>
+ <row>
+ <entry>EJB</entry>
+ <entry><classname>org.jboss.ejb</classname></entry>
+ </row>
+ <row>
+ <entry>JCA</entry>
+ <entry><classname>org.jboss.resource</classname></entry>
+ </row>
+ <row>
+ <entry>JMX</entry>
+ <entry><classname>org.jboss.mx</classname></entry>
+ </row>
+ <row>
+ <entry>JMS</entry>
+ <entry><classname>org.jboss.mq</classname></entry>
+ </row>
+ <row>
+ <entry>JTA</entry>
+ <entry><classname>org.jboss.tm</classname></entry>
+ </row>
+ <row>
+ <entry>MDB</entry>
+ <entry><classname>org.jboss.ejb.plugins</classname>, <classname>org.jboss.jms</classname></entry>
+ </row>
+ <row>
+ <entry>Security</entry>
+ <entry><classname>org.jboss.security</classname></entry>
+ </row>
+ <row>
+ <entry>Tomcat</entry>
+ <entry><classname>org.jboss.web</classname>, <classname>org.jboss.catalina</classname></entry>
+ </row>
+ <row>
+ <entry>Apache</entry>
+ <entry><classname>org.apache</classname></entry>
+ </row>
+ <row>
+ <entry>JGroups</entry>
+ <entry><classname>org.jgroups</classname></entry>
+ </row>
+ </tbody>
+ </table>
+ </section>
+
+ <section id="logging.log4j.redir">
+ <title>Redirecting Category Output</title>
+ <para>
+ When you increase the level of logging for one or more categories, it is often useful to redirect the output to a seperate file for easier investigation. To do this you add an <varname>appender-ref</varname> to the <classname>category</classname> as shown here:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<appender name="JSR77" class="org.apache.log4j.FileAppender">
+ <param name="File"
+ value="${jboss.server.home.dir}/log/jsr77.log"/>
+...
+</appender>
+
+<!-- Limit the JSR77 categories -->
+<category name="org.jboss.management" additivity="false">
+ <priority value="DEBUG"/>
+ <appender-ref ref="JSR77"/>
+</category>
+ ]]>
+ </programlisting>
+ <para>
+ This sends <classname>allorg.jboss.management</classname> output to the <filename>jsr77.log</filename> file. The <varname>additivity</varname> attribute controls whether output continues to go to the root category appender. If <literal>false</literal>, output only goes to the appenders referred to by the category.
+ </para>
+ </section>
+ </section>
+
+ <section id="logging.log4j.properties">
+ <title>Using your own log4j.properties file - class loader scoping</title>
+ <para>
+ To use your own <filename>log4j.xml</filename> file you must initialize <literal>log4j</literal> in your application. If you use the default singleton initialization method where the first use of <literal>log4j</literal> triggers a search for the <literal>log4j</literal> initialization files, you must configure a ClassLoader to use scoped class loading with overrides for JBoss classes. You also have to include the <filename>log4j.jar</filename> in your application so that new <literal>log4j</literal> singletons are created in your application's scope.
+ </para>
+ <note>
+ <para>
+ You cannot use a <filename>log4j.properties</filename> file using this approach, at least using log4j-1.2.8 because it preferentially searches for a <filename>log4j.xml</filename> resource and will find the <filename>conf/log4j.xml</filename> ahead of the application <filename>log4j.properties</filename> file. You could rename the <filename>conf/log4j.xml</filename> to something like <filename>conf/jboss-log4j.xml</filename> and then change the <varname>ConfigurationURL</varname> attribute of the <classname>Log4jService</classname> in the <filename>conf/jboss-service.xml</filename> to get around this.
+ </para>
+ </note>
+ </section>
+
+ <section id="logging.log4j.scoping">
+ <title>Using your own <filename>log4j.properties</filename> file - class loader scoping</title>
+ <para>
+ To use a <filename>log4j.properties</filename> file, you have to make the following change in <filename>conf/jboss-service.xml</filename>, for the reasons mentioned in the previous section.
+ </para>
+ <programlisting role="XML"><![CDATA[
+<!--================================================================-->
+<!-- Log4j Initialization -->
+<!-=================================================================-->
+
+<mbean code="org.jboss.logging.Log4jService"
+ name="jboss.system:type=Log4jService,service=Logging">
+ <attribute name="ConfigurationURL">
+ resource:jboss-log4j.xml</attribute>
+ <!-- Set the org.apache.log4j.helpers.LogLog.setQuiteMode.
+ As of log4j1.2.8 this needs to be set to avoid a possible deadlock
+ on exception at the appender level. See bug#696819.
+ -->
+ <attribute name="Log4jQuietMode">true</attribute>
+ <!-- How frequently in seconds the ConfigurationURL is checked for changes -->
+ <attribute name="RefreshPeriod">60</attribute>
+</mbean>
+ ]]>
+ </programlisting>
+ <para>
+ This changes the <literal>log4j</literal> resource file that JBoss Application Server looks for. After making the change in <filename>jboss-service.xml</filename> make sure you rename the <filename>conf/log4j.xml</filename> to match the name of the resource you specified in <filename>jboss-service.xml</filename> (in this case <filename>jboss-log4j.xml</filename>).
+ </para>
+ <para>
+ Include <filename>log4j.jar</filename> in your <filename>myapp.war/WEB-INF</filename> directory. Make the change in <filename>jboss-web.xml</filename> for class loading, as shown in the section above. In this case, <filename>myapp.war/WEB-INF/jboss-web.xml</filename> looks like this:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<jboss-web>
+ <class-loading java2ClassLoadingCompliance="false">
+ <loader-repository>
+ myapp:loader=myapp.war
+ <loader-repository-config>java2ParentDelegation=false
+ </loader-repository-config>
+ </loader-repository>
+ </class-loading>
+</jboss-web>
+ ]]>
+ </programlisting>
+ <para>
+ Now, create a <filename>log4j.properties</filename> file in your <filename>deploy/myapp.war/WEB-INF/classes</filename> directory.
+ </para>
+ <section id="logging.log4j.scoping.example">
+ <title>Sample <filename>log4j.properties</filename></title>
+ <programlisting><![CDATA[
+# Debug log4j
+log4j.debug=true
+log4j.rootLogger=debug, myapp
+
+log4j.appender.myapp=org.apache.log4j.FileAppender
+log4j.appender.myapp.layout=org.apache.log4j.HTMLLayout
+log4j.appender.myapp.layout.LocationInfo=true
+log4j.appender.myapp.layout.Title='All' Log
+log4j.appender.myapp.File=${jboss.server.home.dir}/deploy/myapp.war/WEB-INF/logs/myapp.html
+log4j.appender.myapp.ImmediateFlush=true
+log4j.appender.myapp.Append=false
+ ]]>
+ </programlisting>
+ <para>
+ This property file sets the <literal>log4j</literal> debug system to <literal>true</literal>, which enables the display of <literal>log4j</literal> messages in your JBoss log. You can use this to discover any errors in your properties file. It then produces a HTML log file and places it in your application's <filename>WEB-INF/logs</filename> directory. In your application, you can call this logger with the following syntax:
+ </para>
+ <programlisting>
+...
+private static Logger log = Logger.getLogger("myapp");
+...
+log.debug("############## A debug message from myapp logger #########");
+...
+ </programlisting>
+ <para>
+ You should then see the message in <filename>myapp.html</filename>.
+ </para>
+ <para>
+ After JBoss Application Server has reloaded <filename>conf/jboss-service.xml</filename> (you may need to restart JBoss AS), touch <filename>myapp.war/WEB-INF/web.xml</filename> so that JBoss reloads the configuration for your application. As the application loads, you should see <literal>log4j</literal> debug messages, which confirms that JBoss AS is reading your <filename>log4j.properties</filename> file. This lets you have your own logging system independent of the JBoss AS log.
+ </para>
+ </section>
+ </section>
+
+ <section id="logging.log4j.reposelect">
+ <title>Using your own <filename>log4j.xml</filename> file - Log4j <classname>RepositorySelector</classname></title>
+ <para>
+ Another way to achieve this is to write a custom <classname>RepositorySelector</classname> that changes how the LogManager gets a logger. Using this technique, <classname>Logger.getLogger()</classname> will return a different logger based on the context class loader. Each context class loader has its own configuration set up with its own <filename>log4j.xml</filename> file.
+ </para>
+ <programlisting role="JAVA">
+ /*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2005, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.repositoryselectorexample;
+
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.Map;
+import javax.servlet.ServletConfig;
+import javax.servlet.ServletException;
+import javax.xml.parsers.DocumentBuilderFactory;
+import org.apache.log4j.Hierarchy;
+import org.apache.log4j.Level;
+import org.apache.log4j.LogManager;
+import org.apache.log4j.spi.LoggerRepository;
+import org.apache.log4j.spi.RepositorySelector;
+import org.apache.log4j.spi.RootCategory;
+import org.apache.log4j.xml.DOMConfigurator;
+import org.w3c.dom.Document;
+
+/**
+ * This RepositorySelector is for use with web applications.
+ * It assumes that your log4j.xml file is in the WEB-INF directory.
+ * @author Stan Silvert
+ */
+public class MyRepositorySelector implements RepositorySelector
+{
+ private static boolean initialized = false;
+
+ // This object is used for the guard because it doesn't get
+ // recycled when the application is redeployed.
+ private static Object guard = LogManager.getRootLogger();
+
+ private static Map repositories = new HashMap();
+ private static LoggerRepository defaultRepository;
+
+ /**
+ * Register your web-app with this repository selector.
+ */
+ public static synchronized void init(ServletConfig config)
+ throws ServletException {
+ if( !initialized ) // set the global RepositorySelector
+ {
+ defaultRepository = LogManager.getLoggerRepository();
+ RepositorySelector theSelector = new MyRepositorySelector();
+ LogManager.setRepositorySelector(theSelector, guard);
+ initialized = true;
+ }
+
+ Hierarchy hierarchy = new Hierarchy(new
+ RootCategory(Level.DEBUG));
+ loadLog4JConfig(config, hierarchy);
+ ClassLoader loader =
+ Thread.currentThread().getContextClassLoader();
+ repositories.put(loader, hierarchy);
+ }
+
+ // load log4j.xml from WEB-INF
+ private static void loadLog4JConfig(ServletConfig config,
+ Hierarchy hierarchy)
+ throws ServletException {
+ try {
+ String log4jFile = "/WEB-INF/log4j.xml";
+ InputStream log4JConfig =
+
+ config.getServletContext().getResourceAsStream(log4jFile);
+ Document doc = DocumentBuilderFactory.newInstance()
+ .newDocumentBuilder()
+ .parse(log4JConfig);
+ DOMConfigurator conf = new DOMConfigurator();
+ conf.doConfigure(doc.getDocumentElement(), hierarchy);
+ } catch (Exception e) {
+ throw new ServletException(e);
+ }
+ }
+
+ private MyRepositorySelector() {
+ }
+
+ public LoggerRepository getLoggerRepository() {
+ ClassLoader loader =
+ Thread.currentThread().getContextClassLoader();
+ LoggerRepository repository =
+ (LoggerRepository)repositories.get(loader);
+
+ if (repository == null) {
+ return defaultRepository;
+ } else {
+ return repository;
+ }
+ }
+}
+ </programlisting>
+ </section>
+
+ <section id="logging.jdk">
+ <title>JDK java.util.logging</title>
+ <para>
+ The choice of the actual logging implementation is determined by the <varname>org.jboss.logging.Logger.pluginClass</varname> system property. This property specifies the class name of an implementation of the <classname>org.jboss.logging.LoggerPlugin</classname> interface. The default value for this is the <classname>org.jboss.logging.Log4jLoggerPlugin</classname> class.
+ </para>
+ <para>
+ If you want to use the JDK 1.4+ <classname>java.util.logging</classname> framework instead of <literal>log4j</literal>, you can create your own <classname>Log4jLoggerPlugin</classname> to do this. The attached <filename>JDK14LoggerPlugin.java</filename> file shows an example implementation.
+ </para>
+ <para>
+ To use this, you must specify the following system properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ To specify the custom JDK1.4 plugin:
+ </para>
+ <programlisting>
+org.jboss.logging.Logger.pluginClass = logging.JDK14LoggerPlugin
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ To specify the JDK1.4 logging configuration file:
+ </para>
+ <programlisting>
+java.util.logging.config.file = logging.properties
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can specify these properties using the <literal>JAVA_OPTS</literal> environment variable, like so:
+ </para>
+ <programlisting>
+JAVA_OPTS=
+ "-Dorg.jboss.logging.Logger.pluginClass=logging.JDK14LoggerPlugin
+ -Djava.util.logging.config.file=logging.properties"
+ </programlisting>
+ <para>
+ You need to make your custom <classname>Log4jLoggerPlugin</classname> available to JBoss by placing it in a JAR in the <filename>JBOSS_DIST/lib</filename> directory, and then telling JBoss to load this as part of the bootstrap libraries by passing in <code>-L $JARNAME</code> on the command line as follows:
+ </para>
+ <programlisting>
+[user at host bin] $ run.sh -c minimal -L logger.jar
+ </programlisting>
+ </section>
+
+
+ <section>
+ <title>Debugging with server.log</title>
+ <para>
+ The logging threshold on the console is set to <literal>INFO</literal>, which means that you will see informative messages, warning messages and error messages on the console, but not general debug messages. However, there is no threshold set for the <filename>server.log</filename> file, so all messages generated will be logged there.
+ </para>
+ <para>
+ If you are experiencing difficulties and the console is not displaying useful information, always check the <filename>server.log</filename> file for debug messages that might help to solve the problem. However, keep in mind that not all of your components will produce detailed debug information for the log file. You must also boost the logging limits set for individual categories.
+ </para>
+ <para>
+ The following category limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided.
+ </para>
+<programlisting><!-- Limit JBoss categories to INFO -->
+<category name="org.jboss">
+<priority value="<emphasis role="bold">INFO</emphasis>"/>
+</category>
+</programlisting>
+ <para>
+ If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output.
+ </para>
+ <para>
+ As an example, say you want to set the output from the container-managed persistence engine to <literal>DEBUG</literal> level and to redirect it to a separate file, <filename>cmp.log</filename>, in order to analyze the generated SQL commands. You would add the following code to the <filename>log4j.xml</filename> file:
+ </para>
+<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
+<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+<param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
+<param name="Append" value="false"/>
+<param name="MaxFileSize" value="500KB"/>
+<param name="MaxBackupIndex" value="1"/>
+
+<layout class="org.apache.log4j.PatternLayout">
+<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
+</layout>
+</appender>
+
+<category name="org.jboss.ejb.plugins.cmp">
+<priority value="DEBUG" />
+<appender-ref ref="CMP"/>
+</category>
+</programlisting>
+ <para>
+ This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
+ </para>
+ <para>
+ The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is <filename>cmp.log</filename>. Older files have the date they were written added to the name. You will notice that the <filename class="directory">log</filename> directory also contains HTTP request logs which are produced by the web container.
+ </para>
+ <warning>
+ <para>
+ If you edit the <filename>jboss-log4j.xml</filename> file, be aware that the <literal>log4j</literal> configuration will be reloaded as if the server was restarted. Before editing the file, be aware that if the file appender is not configured to append to an existing log file, then the process will delete the current log and create a new file in its place.
+ </para>
+ </warning>
+</section>
+
+</chapter>
\ No newline at end of file
Modified: projects/docs/enterprise/4.3.7/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Getting_Started/en-US/The_JBoss_Server___A_Quick_Tour.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -94,54 +94,9 @@
<para>
In JBoss, <literal>log4j</literal> is used for logging. If you are not familiar with the <literal>log4j</literal> package and would like to use it in your applications, you can read more about it at the Jakarta web site (<ulink url="http://jakarta.apache.org/log4j/"></ulink>).
</para>
- <para>
- Logging is controlled from a central <filename>conf/log4j.xml</filename> file. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, JBoss produces output to both the console and a log file (<filename>server.log</filename> in the <filename class="directory">log</filename> directory).
- </para>
- <para>
- There are 5 basic log levels used: <literal>DEBUG</literal>, <literal>INFO</literal>, <literal>WARN</literal>, <literal>ERROR</literal> and <literal>FATAL</literal>. The logging threshold on the console is <literal>INFO</literal>, which means that you will see informational messages, warning messages and error messages on the console but not general debug messages. In contrast, there is no threshold set for the <filename>server.log</filename> file, so all generated logging messages will be logged there.
- </para>
- <para>
- If things are going wrong and there doesn’t seem to be any useful information in the console, always check the <filename>server.log</filename> file to see if there are any debug messages which might help you to track down the problem. However, be aware that just because the logging threshold allows debug messages to be displayed, that doesn't mean that all of JBoss will produce detailed debug information for the log file. You will also have to boost the logging limits set for individual categories. Take the following category for example.
- </para>
-<programlisting><!-- Limit JBoss categories to INFO -->
-<category name="org.jboss">
- <priority value="<emphasis role="bold">INFO</emphasis>"/>
-</category>
-</programlisting>
- <para>
- This limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided. If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output.
- </para>
- <para>
- As another example, let’s say you wanted to set the output from the container-managed persistence engine to <literal>DEBUG</literal> level and to redirect it to a separate file, <filename>cmp.log</filename>, in order to analyze the generated SQL commands. You would add the following code to the <filename>log4j.xml</filename> file:
- </para>
-<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
- <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
- <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
- <param name="Append" value="false"/>
- <param name="MaxFileSize" value="500KB"/>
- <param name="MaxBackupIndex" value="1"/>
-
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
- </layout>
-</appender>
-
-<category name="org.jboss.ejb.plugins.cmp">
- <priority value="DEBUG" />
- <appender-ref ref="CMP"/>
-</category>
-</programlisting>
- <para>
- This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
- </para>
- <para>
- The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is <filename>cmp.log</filename>. Older files have the date they were written added to the name. You will notice that the <filename class="directory">log</filename> directory also contains HTTP request logs which are produced by the web container.
- </para>
- <warning>
- <para>
- If you edit the <filename>jboss-log4j.xml</filename> file, be aware that the log4j configuration will be reloaded as if the server was restarted. Before editing the file, be aware that if the file appender is not configured to append to an existing log file, then the process will delete the current log and create a new file in its place.
- </para>
- </warning>
+ <para>
+ For more information, see <xref linkend="logging" />.
+ </para>
</section>
<section id="Basic_Configuration_Issues-Security_Service">
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Entity_Beans.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -28,7 +28,7 @@
Every bound persistent POJO class is an entity bean and is declared using the <literal>@Entity</literal> annotation (at the class level):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@Entity</literal> declares the class as an entity bean (i.e. a persistent POJO class), <literal>@Id</literal> declares the identifier property of this entity bean. The other mapping declarations are implicit. This "configuration by exception" concept is central to the new EJB3 specification and a major improvement. The class Flight is mapped to the Flight table, using the column id as its primary key column.
</para>
@@ -41,12 +41,12 @@
<literal>@Table</literal> is set at the class level. It allows you to define the table, catalog, and schema names for your entity bean mapping. If no <literal>@Table</literal> is defined the default values are used: the unqualified class name of the entity.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>@Table</literal> element also contains <literal>schema</literal> and a <literal>catalog</literal> attributes, if they need to be defined. You can also define unique constraints to the table using the <literal>@UniqueConstraint</literal> annotation in conjunction with <literal>@Table</literal> (for a unique constraint bound to a single column, refer to <literal>@Column</literal>).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A unique constraint is applied to the tuple month, day. Note that the <literal>columnNames</literal> array refers to the logical column names.
</para>
@@ -59,7 +59,7 @@
You can add optimistic locking capability to an entity bean using the <literal>@Version</literal> annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The version property will be mapped to the <literal>OPTLOCK</literal> column, and the entity manager will use it to detect conflicting updates (preventing lost updates you might otherwise see with the last-commit-wins strategy).
</para>
@@ -81,7 +81,7 @@
Every non-static non-transient property (field or method) of an entity bean is considered persistent, unless you annotate it as <literal>@Transient</literal>. Not having an annotation for your property is equivalent to the appropriate <literal>@Basic</literal> annotation. The <literal>@Basic</literal> annotation allows you to declare the fetching strategy for a property:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>counter</literal>, a transient field, and <literal>lengthInMeter</literal>, a method annotated as <literal>@Transient</literal>, and will be ignored by the entity manager. <literal>name</literal>, <literal>length</literal>, and <literal>firstname</literal> properties are mapped persistent and eagerly fetched (the default for simple properties). The <literal>detailedComment</literal> property value will be lazily fetched from the database once a lazy property of the entity is accessed for the first time. Usually you don't need to lazy simple properties (not to be confused with lazy association fetching).
</para>
@@ -103,7 +103,7 @@
<literal>@Lob</literal> indicates that the property should be persisted in a Blob or a Clob depending on the property type: <classname>java.sql.Clob</classname>, <classname>Character[]</classname>, <classname>char[]</classname> and java.lang.<classname>String</classname> will be persisted in a Clob. <classname>java.sql.Blob</classname>, <classname>Byte[]</classname>, <classname>byte[] </classname>and serializable type will be persisted in a Blob.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If the property type implements <classname>java.io.Serializable</classname> and is not a basic type, and if the property is not annotated with <literal>@Lob</literal>, then the Hibernate <literal>serializable</literal> type is used.
</para>
@@ -147,7 +147,7 @@
</listitem>
</itemizedlist>
- <programlisting language="java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>name</literal> property is mapped to the <literal>flight_name</literal> column, which is not nullable, has a length of 50 and is not updatable (making the property immutable).
</para>
@@ -156,7 +156,7 @@
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -219,11 +219,11 @@
It is possible to declare an embedded component inside an entity and even override its column mapping. Component classes have to be annotated at the class level with the <literal>@Embeddable</literal> annotation. It is possible to override the column mapping of an embedded object for a particular entity using the <literal>@Embedded</literal> and <literal>@AttributeOverride</literal> annotation in the associated property:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A embeddable object inherits the access type of its owning entity (note that you can override that using the Hibernate-specific <literal>@AccessType</literal> annotations (see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Entity_Beans-Hibernate_Annotation_Extensions" />).
</para>
@@ -232,7 +232,7 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Hibernate Annotations supports one more feature that is not explicitly supported by the EJB3 specification: you can annotate a embedded object with the <literal>@MappedSuperclass</literal> annotation to make the superclass properties persistent (see <literal>@MappedSuperclass</literal> for more information).
</para>
<para>
@@ -296,17 +296,17 @@
The following example shows a sequence generator using the <literal>SEQ_STORE</literal> configuration (see below)
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The next example uses the identity generator:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>AUTO</literal> generator is the preferred type for portable applications (across several DB vendors). The identifier generation configuration can be shared for several <literal>@Id</literal> mappings with the generator attribute. There are several configurations available through <literal>@SequenceGenerator</literal> and <literal>@TableGenerator</literal>. The scope of a generator can be the application or the class. Class-defined generators are not visible outside the class and can override application level generators. Application-level generators are defined at XML level (see <xref linkend="chap-Hibernate_Annotations_Reference_Guide-Overriding_metadata_through_XML" />):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If JPA XML (like <filename>META-INF/orm.xml</filename>) is used to define the generators, <literal>EMP_GEN</literal> and <literal>SEQ_GEN</literal> are application level generators. <literal>EMP_GEN</literal> defines a table based id generator using the hilo algorithm with a <literal>max_lo</literal> of 20. The hi value is kept in a <literal>table</literal> "<literal>GENERATOR_TABLE</literal>". The information is kept in a row where <literal>pkColumnName</literal> "key" is equals to <literal>pkColumnValue</literal> "<literal>EMP</literal>" and column <literal>valueColumnName</literal> "<literal>hi</literal>" contains the the next high value used.
</para>
@@ -322,7 +322,7 @@
The next example shows the definition of a sequence generator in a class scope:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This class will use a sequence named my_sequence and the SEQ_STORE generator is not visible in other classes. Note that you can check the Hibernate Annotations tests in the <package>org.hibernate.test.annotations.id</package> package for more examples.
</para>
@@ -344,7 +344,7 @@
While quite common to the EJB2 developer, <literal>@IdClass</literal> is likely new for Hibernate users. The composite primary key class corresponds to multiple fields or properties of the entity class, and the names of primary key fields or properties in the primary key class and those of the entity class must match and their types must be the same. Let's look at an example:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
As you may have seen, <literal>@IdClass</literal> points to the corresponding primary key class.
</para>
@@ -352,7 +352,7 @@
While not supported by the EJB3 specification, Hibernate allows you to define associations inside a composite identifier. Simply use the regular annotations for that.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Mapping_with_EJB3JPA_Annotations-Mapping_inheritance">
@@ -385,7 +385,7 @@
This strategy has many drawbacks (esp. with polymorphic queries and associations) explained in the EJB3 spec, the Hibernate reference documentation, <citetitle>Hibernate in Action</citetitle>, and many other places. Hibernate works around most of them implementing this strategy using <literal>SQL UNION</literal> queries. It is commonly used for the top level of an inheritance hierarchy:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21a.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21a.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This strategy supports one-to-many associations provided that they are bidirectional. This strategy does not support the <literal>IDENTITY</literal> generator strategy: the id has to be shared across several tables. Consequently, when using this strategy, you should not use <literal>AUTO </literal>nor <literal>IDENTITY</literal>.
</para>
@@ -397,7 +397,7 @@
All properties of all super- and subclasses are mapped into the same table, instances are distinguished by a special discriminator column:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Plane</classname> is the superclass, it defines the inheritance strategy <literal>InheritanceType.SINGLE_TABLE</literal>. It also defines the discriminator column through the <literal>@DiscriminatorColumn</literal> annotation. A discriminator column can also define the discriminator type. Finally, the <literal>@DiscriminatorValue</literal> annotation defines the value used to differentiate a class in the hierarchy. All of these attributes have sensible default values. The default name of the discriminator column is <literal>DTYPE</literal>. The default discriminator value is the entity name (as defined in <literal>@Entity.name</literal>) for DiscriminatorType.STRING. <classname>A320</classname> is a subclass; you only have to define discriminator value if you don't want to use the default value. The strategy and the discriminator type are implicit.
</para>
@@ -412,7 +412,7 @@
The<literal> @PrimaryKeyJoinColumn</literal> and <literal>@PrimaryKeyJoinColumns</literal> annotations define the primary key(s) of the joined subclass table:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
All of the above entities use the <literal>JOINED</literal> strategy, the <literal>Ferry</literal> table is joined with the <literal>Boat</literal> table using the same primary key names. The <literal>AmericaCupClass</literal> table is joined with <literal>Boat</literal> using the join condition <code>Boat.id = AmericaCupClass.BOAT_ID</code>.
</para>
@@ -424,7 +424,7 @@
This is sometimes useful to share common properties through a technical or a business superclass without including it as a regular mapped entity (ie no specific table for this entity). For that purpose you can map them as <literal>@MappedSuperclass</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In database, this hierarchy will be represented as an <literal>Order</literal> table having the <literal>id</literal>, <literal>lastUpdate</literal> and <literal>lastUpdater</literal> columns. The embedded superclass property mappings are copied into their entity subclasses. Remember that the embeddable superclass is not the root of the hierarchy though.
</para>
@@ -457,7 +457,7 @@
You can override columns defined in entity superclasses at the root entity level using the <literal>@AttributeOverride</literal> annotation.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>altitude</literal> property will be persisted in an <literal>fld_altitude</literal> column of table <literal>Plane</literal> and the propulsion association will be materialized in a <literal>fld_propulsion_fk</literal> foreign key column.
</para>
@@ -479,9 +479,9 @@
First, we map a real one-to-one association using shared primary keys:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The one-to-one is marked as true by using the <literal>@PrimaryKeyJoinColumn</literal> annotation.
</para>
@@ -489,7 +489,7 @@
In the following example, the associated entities are linked through a foreign key column:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <classname>Customer</classname> is linked to a <classname>Passport</classname>, with a foreign key column named <literal>passport_fk</literal> in the <literal>Customer</literal> table. The join column is declared with the <literal>@JoinColumn</literal> annotation which looks like the <literal>@Column</literal> annotation. It has one more parameters named <literal>referencedColumnName</literal>. This parameter declares the column in the targeted entity that will be used to the join. Note that when using <literal><literal>referencedColumnName</literal></literal> to a non primary key column, the associated class has to be <classname>Serializable</classname>. Also note that the <literal><literal>referencedColumnName</literal></literal> to a non primary key column has to be mapped to a property having a single column (other cases might not work).
</para>
@@ -503,7 +503,7 @@
The third possibility (using an association table) is very exotic.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <classname>Customer</classname> is linked to a <classname>Passport</classname> through a association table named <literal>CustomerPassports</literal> ; this association table has a foreign key column named <literal>passport_fk</literal> pointing to the <literal>Passport</literal> table (materialized by the <literal>inverseJoinColumn</literal> and a foreign key column named <literal>customer_fk</literal> pointing to the <literal>Customer</literal> table materialized by the <literal>joinColumns</literal> attribute.
</para>
@@ -518,7 +518,7 @@
Many-to-one associations are declared at the property level with the annotation <literal>@ManyToOne</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>@JoinColumn</literal> attribute is optional, the default value(s) is like in one-to-one, the concatenation of the name of the relationship in the owner side, <keycap>_</keycap> (underscore), and the name of the primary key column in the owned side. In this example <literal>company_id</literal> because the property name is <literal>company</literal> and the column id of Company is <literal>id</literal>.
</para>
@@ -526,12 +526,12 @@
<literal>@ManyToOne</literal> has a parameter named <literal>targetEntity</literal> which describes the target entity name. You usually don't need this parameter since the default value (the type of the property that stores the association) is good in almost all cases. However this is useful when you want to use interfaces as the return type instead of the regular entity.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also map a many-to-one association through an association table. This association table described by the <literal>@JoinTable</literal> annotation will contains a foreign key referencing back the entity table (through <literal>@JoinTable.joinColumns</literal>) and a foreign key referencing the target entity table (through <literal>@JoinTable.inverseJoinColumns</literal>).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Mapping_entity_bean_associationsrelationships-Collections" revision="1">
@@ -627,7 +627,7 @@
Collection of primitive, core type or embedded objects is not supported by the EJB3 specification. Hibernate Annotations allows them however (see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Entity_Beans-Hibernate_Annotation_Extensions" />).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_33.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_33.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
So <literal>City</literal> has a collection of <literal>Street</literal>s that are ordered by <literal>streetName</literal> (of <literal>Street</literal>) when the collection is loaded. <literal>Software</literal> has a map of <literal>Version</literal>s which key is the <literal>Version</literal> <literal>codeName</literal>.
</para>
@@ -647,7 +647,7 @@
Since many-to-one are (almost) always the owner side of a bidirectional relationship in the EJB3 spec, the one-to-many association is annotated by <literal>@OneToMany( mappedBy=... )</literal>
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Troop</classname> has a bidirectional one-to-many relationship with <literal>Soldier</literal> through the <literal>troop</literal> property. You must not define any physical mapping in the <literal>mappedBy</literal> side.
</para>
@@ -655,7 +655,7 @@
To map a bidirectional one-to-many, with the one-to-many side as the owning side, you have to remove the <literal>mappedBy</literal> element and set the many-to-one <literal>@JoinColumn</literal> as insertable and updatable to false. This solution is obviously not optimized and will produce some additional UPDATE statements.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-One_to_many-Unidirectional">
@@ -664,7 +664,7 @@
A unidirectional one-to-many using a foreign key column in the owned entity is not that common and not really recommended. We strongly advise you to use a join table for this kind of association (as explained in the next section). This kind of association is described through a <literal>@JoinColumn</literal>
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_36.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_36.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>Customer</literal> describes a unidirectional relationship with <literal>Ticket</literal> using the join column <literal>CUST_ID</literal>.
</para>
@@ -676,7 +676,7 @@
A unidirectional one-to-many with join table is much preferred. This association is described through an <literal>@JoinTable</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_37.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_37.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>Trainer</literal> describes a unidirectional relationship with <classname>Monkey</classname> using the join table <classname>TrainedMonkeys</classname>, with a foreign key <literal>trainer_id</literal> to <literal>Trainer</literal> (<literal>joinColumns</literal>) and a foreign key <literal>monkey_id</literal> to <literal>Monkey</literal> (<literal>inversejoinColumns</literal>).
</para>
@@ -688,7 +688,7 @@
Without describing any physical mapping, a unidirectional one-to-many with join table is used. The table name is the concatenation of the owner table name, <keycap>_</keycap>, and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table, <keycap>_</keycap>, and the owner primary key column(s) name. The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s) name. A unique constraint is added to the foreign key referencing the other side table to reflect the one-to-many.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_38.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_38.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<classname>Trainer</classname> describes a unidirectional relationship with <classname>Tiger</classname> using the join table <literal>Trainer_Tiger</literal>, with a foreign key <literal>trainer_id</literal> to <literal>Trainer</literal> (table name, <keycap>_</keycap>, trainer id) and a foreign key <literal>trainedTigers_id</literal> to <literal>Monkey</literal> (property name, <keycap>_</keycap>, Tiger primary column).
</para>
@@ -704,9 +704,9 @@
A many-to-many association is defined logically using the <literal>@ManyToMany</literal> annotation. You also have to describe the association table and the join conditions using the <literal>@JoinTable</literal> annotation. If the association is bidirectional, one side has to be the owner and one side has to be the inverse end (ie. it will be ignored when updating the relationship values in the association table):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_39.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_39.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_40.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_40.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
We've already shown the many declarations and the detailed attributes for associations. We'll go deeper in the <literal>@JoinTable</literal> description, it defines a <literal>name</literal>, an array of join columns (an array in annotation is defined using { A, B, C }), and an array of inverse join columns. The latter ones are the columns of the association table which refer to the <classname>Employee</classname> primary key (the "other side").
</para>
@@ -721,7 +721,7 @@
As any other annotations, most values are guessed in a many-to-many relationship. Without describing any physical mapping in a unidirectional many-to-many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_</keycap> and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table name, <keycap>_</keycap> and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s). These are the same rules used for a unidirectional one-to-many relationship.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_41.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_41.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <literal>Store_City</literal> is used as the join table. The <literal>Store_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>implantedIn_id</literal> column is a foreign key to the <literal>City</literal> table.
</para>
@@ -729,7 +729,7 @@
Without describing any physical mapping in a bidirectional many-to-many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_</keycap> and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the other side property name, <keycap>_</keycap>, and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, <keycap>_</keycap>, and the other side primary key column(s). These are the same rules used for a unidirectional one-to-many relationship.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_42.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_42.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
A <literal>Store_Customer</literal> is used as the join table. The <literal>stores_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>customers_id</literal> column is a foreign key to the <literal>Customer</literal> table.
</para>
@@ -789,21 +789,21 @@
Composite primary keys use a embedded class as the primary key representation, so you'd use the <literal>@Id</literal> and <literal>@Embeddable</literal> annotations. Alternatively, you can use the <literal>@EmbeddedId</literal> annotation. Note that the dependent class has to be serializable and implements <methodname>equals()</methodname>/<methodname>hashCode()</methodname>. You can also use <literal>@IdClass</literal> as described in <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Mapping_with_EJB3JPA_Annotations-Mapping_identifier_properties" />.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_43.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_43.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
or alternatively
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_44.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_44.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@Embeddable</literal> inherits the access type of its owning entity unless the Hibernate-specific annotation <literal>@AccessType</literal> is used. Composite foreign keys (if not using the default sensitive values) are defined on associations using the <literal>@JoinColumns</literal> element, which is basically an array of <literal>@JoinColumn</literal>. It is considered a good practice to express <literal>referencedColumnNames</literal> explicitly. Otherwise, Hibernate will suppose that you use the same order of columns as in the primary key declaration.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_45.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_45.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_46.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_46.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_47.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_47.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note the explicit usage of the <literal>referencedColumnName</literal>.
</para>
@@ -815,7 +815,7 @@
You can map a single entity bean to several tables using the <literal>@SecondaryTable</literal> or <literal>@SecondaryTables</literal> class level annotations. To express that a column is in a particular table, use the <literal>table</literal> parameter of <literal>@Column</literal> or <literal>@JoinColumn</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_48.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_48.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this example, <literal>name</literal> will be in <literal>MainCat</literal>. <literal>storyPart1</literal> will be in <literal>Cat1</literal> and <literal>storyPart2</literal> will be in <literal>Cat2</literal>. <literal>Cat1</literal> will be joined to <literal>MainCat</literal> using the <literal>cat_id</literal> as a foreign key, and <literal>Cat2</literal> using <literal>id</literal> (ie the same column name, the <literal>MainCat</literal> id column has). Plus a unique constraint on <literal>storyPart2</literal> has been set.
</para>
@@ -834,7 +834,7 @@
You can map EJBQL/HQL queries using annotations. <literal>@NamedQuery</literal> and <literal>@NamedQueries</literal> can be defined at the class level or in a JPA XML file. However their definitions are global to the session factory/entity manager factory scope. A named query is defined by its name and the actual query string.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_49.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_49.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also provide some hints to a query through an array of <literal>QueryHint</literal> through a <literal>hints</literal> attribute.
</para>
@@ -936,18 +936,18 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_50.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_50.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<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 language="java"><xi:include href="extras/Code_Example_51.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_51.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this example, we only describe the entity member of the result set mapping. The property / column mapping 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 involves 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 language="java"><xi:include href="extras/Code_Example_52.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_52.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
If you look at the dimension property, you'll see that although EJB3 implementations do not have to support the dotted notation for embedded objects, Hobernate does. You can even have nested embedded objects.
@@ -957,12 +957,12 @@
If you retrieve a single entity and if you use the default mapping, you can use the <literal>resultClass</literal> attribute instead of <literal>resultSetMapping</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_53.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_53.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In some of your native queries, you'll have to return scalar values, for example when building report queries. You can map them in the <literal>@SqlResultsetMapping</literal> through <literal>@ColumnResult</literal>. You actually can even mix entities and scalar returns in the same native query (this is probably not common though).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_54.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_54.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Another query hint specific to native queries has been introduced: <literal>org.hibernate.callable</literal> which can be true or false depending on whether the query is a stored procedure or not.
</para>
@@ -1049,9 +1049,9 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_55.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_55.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_56.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_56.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
</section>
@@ -1067,7 +1067,7 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_57.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_57.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
<literal>strategy</literal> is the short name of a Hibernate3 generator strategy or the fully qualified class name of an <classname>IdentifierGenerator</classname> implementation. You can add some parameters through the <literal>parameters</literal> attribute.
@@ -1076,7 +1076,7 @@
Contrary to their standard counterpart, <literal>@GenericGenerator</literal> and <literal>@GenericGenerators</literal> can be used in package-level annotations, making them application-level generators (just like if they were in a JPA XML file).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_58.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_58.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Identifier-NaturalId">
@@ -1085,7 +1085,7 @@
While not used as identifier property, some (groups of) properties represent the natural identifier of an entity. This is especially true when the schema uses the recommended approach of using surrogate primary key even if a natural business key exists. Hibernate allows to map such natural properties and reuse them in a <classname>Criteria</classname> query. The natural identifier is composed of all the properties marked <classname>@NaturalId</classname>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_60.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_60.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that the group of properties representing the natural identifier have to be unique (Hibernate will generate a unique constraint if the database schema is generated).
</para>
@@ -1153,7 +1153,7 @@
If a superclass or an embeddable object is not annotated, the root entity access type is used (even if an access type has been define on an intermediate superclass or embeddable object). The "Matryoshka doll principle" does not apply.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_61.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_61.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Formula">
@@ -1162,7 +1162,7 @@
Sometimes, you want the Database to do some computation for you rather than in the JVM, you might also create some kind of virtual column. You can use a SQL fragment (aka formula) instead of mapping a property into a column. This kind of property is read only (its value is calculated by your formula fragment).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_62.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_62.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The SQL fragment can be as complex as you want and even include subselects.
</para>
@@ -1177,12 +1177,12 @@
<literal>@org.hibernate.annotations.TypeDef</literal> and <literal>@org.hibernate.annotations.TypeDefs</literal> allows you to declare type definitions. These annotations are placed at the class or package level. Note that these definitions will be global for the session factory (even at the class level) and that type definition has to be defined before any usage.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_63.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_63.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
When using composite user type, you will have to express column definitions. The <literal>@Columns</literal> has been introduced for that purpose.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_64.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_64.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Index">
@@ -1191,7 +1191,7 @@
You can define an index on a particular column using the <literal>@Index</literal> annotation on a one column property, the columnNames attribute will then be ignored
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_65.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_65.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Parent">
@@ -1200,7 +1200,7 @@
When inside an embeddable object, you can define one of the properties as a pointer back to the owner element.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_66.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_66.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Generated_properties">
@@ -1209,7 +1209,7 @@
Some properties are generated at insert or update time by your database. Hibernate can deal with such properties and triggers a subsequent select to read these properties.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_67.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_67.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Annotate your property as <literal>@Generated</literal>. You have to make sure your insertability or updatability does not conflict with the generation strategy you have chosen. When <literal>GenerationTime.INSERT</literal> is chosen, the property must not contains insertable columns, when <literal>GenerationTime.ALWAYS</literal> is chosen, the property must not contains insertable nor updatable columns.
</para>
@@ -1224,7 +1224,7 @@
Sometimes, the type guessed by reflection is not the one you want Hibernate to use. This is especially true of components when an interface is used. You can use <literal>@Target</literal> to bypass the reflection guessing mechanism (very much like the <literal>targetEntity</literal> attribute available on associations.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_68.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_68.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Property-Optimistic_lock">
@@ -1245,7 +1245,7 @@
<literal>SINGLE_TABLE</literal> is a very powerful strategy but sometimes, and especially for legacy systems, you cannot add an additional discriminator column. For that purpose, Hibernate has introduced the notion of discriminator formula: <literal>@DiscriminatorFormula</literal> is a replacement of <literal>@DiscriminatorColumn</literal> and use a SQL fragment as a formula for discriminator resolution (no need to have a dedicated column).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_69.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_69.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
By default, when querying the top entities, Hibernate does not put a restriction clause on the discriminator column. This can be inconvenient if this column contains values not mapped in your hierarchy (through <literal>@DiscriminatorValue</literal>). To work around that you can use <literal>@ForceDiscriminator</literal> (at the class level, next to <literal>@DiscriminatorColumn</literal>). Hibernate will then list the available values when loading the entities.
</para>
@@ -1253,7 +1253,7 @@
You can define the foreign key name generated by Hibernate for subclass tables in the JOINED inheritance strategy.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_70.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_70.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The foreign key from the <literal>Document</literal> table to the <literal>File</literal> table will be named <literal>FK_DOCU_FILE</literal>.
</para>
@@ -1265,12 +1265,12 @@
By default, when Hibernate cannot resolve the association because the expected associated element is not in database (wrong id on the association column), an exception is raised by Hibernate. This might be inconvenient for legacy and badly maintained schemas. You can ask Hibernate to ignore such elements instead of raising an exception using the <literal>@NotFound</literal> annotation. This annotation can be used on a <literal>@OneToOne</literal> (with FK), <literal>@ManyToOne</literal>, <literal>@OneToMany</literal> or <literal>@ManyToMany</literal> association.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_71.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_71.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Sometimes you want to delegate to your database the deletion of cascade when a given entity is deleted.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_72.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_72.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In this case Hibernate generates a cascade delete constraint at the database level.
</para>
@@ -1278,7 +1278,7 @@
Foreign key constraints, when generated by Hibernate, have a fairly unreadable name. You can override the constraint name by using <literal>@ForeignKey</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_73.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_73.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<section id="sect-Hibernate_Annotations_Reference_Guide-Single_Association_related_annotations-Lazy_options_and_fetching_modes">
<title>Lazy options and fetching modes</title>
<para>
@@ -1370,7 +1370,7 @@
The @Any annotation describes the column holding the metadata information. To link the value of the metadata information and an actual entity type, The <classname>@AnyDef</classname> and <classname>@AnyDefs</classname> annotations are used.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_74.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_74.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<methodname>idType</methodname> represents the target entities identifier property type and <methodname>metaType</methodname> the metadata type (usually String).
</para>
@@ -1378,7 +1378,7 @@
Note that <classname>@AnyDef</classname> can be mutualized and reused. It is recommended to place it as a package metadata in this case.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_75.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_75.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
@@ -1419,7 +1419,7 @@
You can also declare a sort comparator. Use the <literal>@Sort</literal> annotation. Expressing the comparator type you want between unsorted, natural or custom comparator. If you want to use your own comparator implementation, you'll also have to express the implementation class using the <literal>comparator</literal> attribute. Note that you need to use either a <classname>SortedSet</classname> or a <classname>SortedMap</classname> interface.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_76.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_76.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Please refer to the previous descriptions of these annotations for more information.
</para>
@@ -1427,7 +1427,7 @@
Foreign key constraints, while generated by Hibernate, have a fairly unreadable name. You can override the constraint name by use <literal>@ForeignKey</literal>. Note that this annotation has to be placed on the owning side of the relationship, <literal>inverseName</literal> referencing to the other side constraint.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_77.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_77.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Collection_related_annotations-Extra_collection_types" revision="1">
@@ -1438,7 +1438,7 @@
Beyond EJB3, Hibernate Annotations supports true <classname>List</classname> and <classname>Array</classname>. Map your collection the same way as usual and add the @<literal>IndexColumn</literal>. This annotation allows you to describe the column that will hold the index. You can also declare the index value in DB that represent the first element (aka as base index). The usual value is <literal>0</literal> or <literal>1</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_78.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_78.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
If you forgot to set <literal>@IndexColumn</literal>, the bag semantic is applied. If you want the bag semantic without the limitations of it, consider using <literal>@CollectionId</literal>.
@@ -1455,7 +1455,7 @@
Both <literal>@org.hibernate.annotations.MapKey</literal> and <literal>@org.hibernate.annotations.MapKeyManyToMany</literal> allow you to override the target element to be used. This is especially useful if your collection does not use generics (or if you use interfaces).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_79.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_79.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Extra_collection_types-Bidirectional_association_with_indexed_collections" revision="2">
@@ -1464,12 +1464,12 @@
A bidirectional association where one end is an indexed collection (that is, represented as a <literal>@IndexColumn</literal>, <literal>@org.hibernate.annotations.MapKey</literal> or <classname>@org.hibernate.annotations.MapKeyManyToMany</classname>) requires special consideration. If a property on the associated class explicitly maps the indexed value, the use of <methodname>mappedBy</methodname> is permitted:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_80.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_80.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
But, if there is no such property on the child class, we can't think of the association as truly bidirectional (there is information available at one end of the association that is not available at the other end: the index). In this case, we can't map the collection as <literal>mappedBy</literal>. Instead, we could use the following mapping:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_81.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_81.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that in this mapping, the collection-valued end of the association is responsible for updating the foreign key.
</para>
@@ -1481,7 +1481,7 @@
Another interesting feature is the ability to define a surrogate primary key to a bag collection. This removes pretty much all of the drawbacks of bags: update and removal are efficient, more than one <literal>EAGER</literal> bag per query or per entity. This primary key will be contained in an additional column of your collection table but will not be visible to the Java application. @CollectionId is used to mark a collection as id bag, it also allow to override the primary key column(s), the primary key type and the generator strategy. The strategy can be <literal>identity</literal>, or any defined generator name of your application.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_82.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_82.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Extra_collection_types-Collection_of_element_or_composite_elements">
@@ -1493,7 +1493,7 @@
A collection of elements has to be annotated as <literal>@CollectionOfElements</literal> (as a replacement of <literal>@OneToMany</literal>) To define the collection table, the <literal>@JoinTable</literal> annotation is used on the association property, <literal>joinColumns</literal> defines the join columns between the entity primary table and the collection table (inverseJoincolumn is useless and should be left empty). For collection of core types or array of primitive types, you can override the element column definition using a <literal>@Column</literal> on the association property. You can also override the columns of a collection of embeddable object using <literal>@AttributeOverride</literal>. To reach the collection element, you need to append "element" to the attribute override name (eg "element" for core types, or "element.serial" for the serial property of an embeddable element). To reach the index/key of a collection, append "key" instead.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_83.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_83.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
On a collection of embeddable objects, the embeddable object can have a property annotated with <literal>@Parent</literal>. This property will then point back to the entity containing the collection.
</para>
@@ -1510,7 +1510,7 @@
<classname>@ManyToAny</classname> allows polymorphic associations to classes from multiple tables. This type of mapping always requires more than one column. The first column holds the type of the associated entity. The remaining columns hold the identifier. It is impossible to specify a foreign key constraint for this kind of association, so this is most certainly not meant as the usual way of mapping (polymorphic) associations. You should use this only in very special cases (eg. audit logs, user session data, etc).
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_84.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_84.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Like <classname>@Any</classname>, <classname>@ManyToAny</classname> can use named <classname>@AnyDef</classname>s, see <xref linkend="sect-Hibernate_Annotations_Reference_Guide-Single_Association_related_annotations-Any" /> for more information.
</para>
@@ -1581,7 +1581,7 @@
This is especially useful for <literal>SAVE_UPDATE</literal> (which is the operation cascaded at flush time if you use plain Hibernate Annotations - Hibernate EntityManager cascade <literal>PERSIST</literal> at flush time as per the specification). <literal>DELETE_ORPHAN</literal> applies only to <literal>@OneToMany</literal> associations, and indicates that the <methodname>delete()/remove()</methodname> operation should be applied to any child object that is removed from the association. In other words, if a child is dereferenced by a persistent parent and if <literal>DELETE_ORPHAN</literal> is used, the "orphaned" child is deleted.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_85.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_85.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
It is recommended to use @Cascade to compliment @*To*(cascade=...) as shown in the previous example.
</para>
@@ -1596,11 +1596,11 @@
<literal>@org.hibernate.annotations.Cache</literal> defines the caching strategy and region of a given second level cache. This annotation can be applied on the root entity (not the sub entities), and on the collections.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_86.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_86.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_87.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_87.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="java"><xi:include href="extras/Code_Example_88.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_88.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes:</title>
<listitem>
<para>
@@ -1635,13 +1635,13 @@
</para>
<para>
- <programlisting language="java"><xi:include href="extras/Code_Example_89.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_89.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
When the collection uses an association table as a relational representation, you might want to apply the filter condition to the association table itself or to the target entity table. To apply the constraint on the target entity, use the regular <literal>@Filter</literal> annotation. However, if you want to target the association table, use the <literal>@FilterJoinTable</literal> annotation.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_90.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_90.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_Annotations_Reference_Guide-Hibernate_Annotation_Extensions-Queries">
@@ -1680,7 +1680,7 @@
Hibernate gives you the ability to override every single SQL statement generated. We have seen native SQL query usage already, but you can also override the SQL statement used to load or change the state of entities.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_91.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_91.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>@SQLInsert</literal>, <literal>@SQLUpdate</literal>, <literal>@SQLDelete</literal>, <literal>@SQLDeleteAll</literal> respectively override the <literal>INSERT</literal> statement, <literal>UPDATE</literal> statement, <literal>DELETE</literal> statement, <literal>DELETE</literal> statement to remove all entities.
</para>
@@ -1708,7 +1708,7 @@
You can use the exact same set of annotations to override the collection related statements.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_92.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_92.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The order of the parameters is important and is defined by the order Hibernate handles properties. You can see the expected order by enabling debug logging for the <literal>org.hibernate.persister.entity</literal> level. With this, level-enabled Hibernate will print out the static SQL that is used to create, update, delete etc. entities. (To see the expected sequence, remember not to include your custom SQL through annotations as that will override the Hibernate-generated static sql.)
</para>
@@ -1716,7 +1716,7 @@
Overriding SQL statements for secondary tables is also possible using <literal>@org.hibernate.annotations.Table</literal> and either (or all) attributes <literal>sqlInsert</literal>, <literal>sqlUpdate</literal>, <literal>sqlDelete</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_93.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_93.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The previous example also show that you can give a comment to a given table (primary or secondary): This comment will be used for DDL generation.
</para>
@@ -1731,7 +1731,7 @@
To define tuplixer in annotations, simply use the <literal>@Tuplizer</literal> annotation on the according element
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_94.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_94.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Overriding_metadata_through_XML.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -24,7 +24,7 @@
You can define global level metadata available for all XML files. You must not define these metadata more than once per deployment.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_95.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_95.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
<literal>xml-mapping-metadata-complete</literal> means that all entity, mapped-superclasses and embeddable metadata should be picked up from XML (that is, ignore annotations).
</para>
@@ -42,7 +42,7 @@
You can either define or override metadata information on a given entity.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_96.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_96.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -112,7 +112,7 @@
</orderedlist>
- <programlisting language="xml"><xi:include href="extras/Code_Example_97.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_97.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<orderedlist><title>Notes</title>
<listitem>
<para>
@@ -153,7 +153,7 @@
You can of course define XML overriding for properties. If metadata complete is defined, then additional properties (ie at the Java level) will be ignored. Otherwise, once you start overriding a property, all annotations on the given property are ignored. All property level metadata resides in <literal>entity/attributes</literal>, <literal>mapped-superclass/attributes</literal> or <literal>embeddable/attributes</literal>.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_98.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_98.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override a property through <literal>id</literal>, <literal>embedded-id</literal>, <literal>version</literal>, <literal>embedded</literal> and <literal>basic</literal>. Each of these elements can have sub-elements accordingly: <literal>lob</literal>, <literal>temporal</literal>, <literal>enumerated</literal>, <literal>column</literal>.
</para>
@@ -165,7 +165,7 @@
You can define XML overriding for associations. All association level metadata behave in <literal>entity/attributes</literal>, <literal>mapped-superclass/attributes</literal> or <literal>embeddable/attributes</literal>.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_99.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_99.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override an association through <literal>one-to-many</literal>, <literal>one-to-one</literal>, <literal>many-to-one</literal>, and <literal>many-to-many</literal>. Each of these elements can have sub-elements accordingly: <literal>join-table</literal> (which can have <literal>join-column</literal>s and <literal>inverse-join-column</literal>s), <literal><literal>join-column</literal>s</literal>, <literal>map-key</literal>, and <literal>order-by</literal>. <literal>mapped-by</literal> and <literal>target-entity</literal> can be defined as attributes when it makes sense. Once again the structure is reflects the annotations structure. You can find all semantic information in <xref linkend="chap-Hibernate_Annotations_Reference_Guide-Entity_Beans" />.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Annotations_Reference_Guide/en-US/Setting_up_an_annotations_project.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -55,13 +55,13 @@
</para>
<para>
We also recommend a small wrapper class to startup Hibernate in a static initializer block, known as <classname>HibernateUtil</classname>. You might have seen this class in various forms in other areas of the Hibernate documentation. For Annotation support you have to enhance this helper class as follows:
- <programlisting language="java"><xi:include href="extras/Code_Example_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</para>
<para>
Interesting here is the use of <classname>AnnotationConfiguration</classname>. The packages and annotated classes are declared in your regular XML configuration file (usually <filename>hibernate.cfg.xml</filename>). Here is the equivalent of the above declaration:
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that you can mix the hbm.xml use and the new annotation one. The resource element can be either an hbm file or an EJB3 XML deployment descriptor. The distinction is transparent for your configuration process.
</para>
@@ -69,7 +69,7 @@
Alternatively, you can define the annotated classes and packages using the programmatic API
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also use the Hibernate EntityManager which has its own configuration mechanism. Please refer to this project documentation for more details.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Batch_processing.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -40,12 +40,12 @@
<para>
As an example, to execute an EJB-QL <literal>UPDATE</literal>, use the <literal>Query.executeUpdate()</literal> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_34.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
To execute an EJB-QL <literal>DELETE</literal>, use the same <literal>Query.executeUpdate()</literal> method (the method is named for those familiar with JDBC's <literal>PreparedStatement.executeUpdate()</literal>):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_35.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></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 inheritance hierarchy.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Entity_listeners_and_Callback_methods.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -13,7 +13,7 @@
A method of the entity may be designated as a callback method to receive notification of a particular entity life cycle event. Callbacks methods are annotated by a callback annotation. You can also define an entity listener class to be used instead of the callback methods defined directly inside the entity class. An entity listener is a stateless class with a no-arg constructor. An entity listener is defined by annotating the entity class with the <literal>@EntityListeners</literal> annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_32.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The same callback method or entity listener method can be annotated with more than one callback annotation. For a given entity, you cannot have two methods being annotated by the same callback annotation whether it is a callback method or an entity listener method. A callback method is a no-arg method with no return type and any arbitrary name. An entity listener has the signature <code>void <METHOD>(Object)</code> where Object is of the actual entity type (note that Hibernate Entity Manager relaxed this constraint and allows <literal>Object</literal> of <literal>java.lang.Object</literal> type (allowing sharing of listeners across several entities.)
</para>
@@ -145,7 +145,7 @@
<para>
The EJB3 specification allows annotation overriding through EJB3 deployment descriptor. There is also an additional feature that can be useful: default event listeners.
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_33.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_33.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can override entity listeners on a given entity. An entity listener correspond to a given class and one or several event fire a given method call. You can also define event on the entity itself to describe the callbacks.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Native_query.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -13,12 +13,12 @@
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 which is used when creating a SQL query on <literal>EntityManager</literal>.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You can also define scalar results and even mix entity results and scalar results
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The SQL query will then have to return a column alias <literal>durationInSec</literal>.
</para>
@@ -33,11 +33,11 @@
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>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This native query returns nights and area based on the <literal>GetNightAndArea</literal> result set.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The second version is useful when your SQL query returns one entity reusing the same columns as the ones mapped in metadata.
</para>
@@ -48,7 +48,7 @@
<para>
Native named queries share the same calling API than EJB-QL named queries. Your code doesn't need to know the difference between the two. This is very useful for migration from SQL to EJB-QL:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8-5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8-5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</chapter>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Setup_and_configuration.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -19,12 +19,12 @@
The configuration for entity managers both inside an application server and in a standalone application reside in a persistence archive. A persistence archive is a JAR file which must define a <literal>persistence.xml</literal> file that resides in the <filename>META-INF</filename> folder. All properly annotated classes included in the archive (ie having an <literal>@Entity</literal> annotation), all annotated packages and all Hibernate <filename>hbm.xml</filename> files included in the archive will be added to the persistence unit configuration, so by default, your <filename>persistence.xml</filename> will be quite minimalist:
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Here's a more complete example of a <filename><literal>persistence.xml</literal></filename> file
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<variablelist spacing="compact">
<varlistentry>
<term><code>name</code></term>
@@ -73,7 +73,7 @@
The jar-file elements specifies a jar to analyze. All properly annotated classes, annotated packages and all hbm.xml files part of this jar file will be added to the persistence unit configuration. This element is mainly used in Java EE environment. Use of this one in Java SE should be considered as non portable, in this case a absolute url is needed. You can alternatively point to a directory (This is especially useful when in your test environment, the persistence.xml file is not under the same root directory or jar than your domain model).
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
</varlistentry>
<varlistentry>
@@ -105,7 +105,7 @@
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 language="xml"><xi:include href="extras/Code_Example_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Configuration_and_bootstrapping-Bootstrapping" revision="1">
@@ -114,7 +114,7 @@
The EJB3 specification defines a bootstrap procedure to access the <classname>EntityManagerFactory</classname> and the <classname>EntityManager</classname>. The bootstrap class is <classname>javax.persistence.Persistence</classname>, for example:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The first version is equivalent to the second with an empty map. The map version is a set of overrides that will take precedence over any properties defined in your persistence.xml files. There are a couple of EJB3 properties usable in the map:
</para>
@@ -257,13 +257,13 @@
Here is a typical configuration in a J2SE environment
</para>
- <programlisting language="xml"><xi:include href="extras/Code_Example_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/Code_Example_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
To ease the programmatic configuration, Hibernate Entity Manager provides a proprietary API. This API is very similar to the <classname>Configuration</classname> API and shares the same concepts: <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the Hibernate reference guide for more detailed information on how to use it.
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
</section>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Transactions_and_concurrency.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -189,7 +189,7 @@
If an EJB3 persistence layer runs in a non-managed environment, database connections are usually handled by Hibernate's pooling mechanism behind the scenes. The common entity manager and transaction handling idiom looks like this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_26.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You don't have to <literal>flush()</literal> the <literal>EntityManager</literal> explicitly - the call to <literal>commit()</literal> automatically triggers the synchronization.
</para>
@@ -223,7 +223,7 @@
If you use bean-managed transactions (BMT), the code will look like this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_27.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
With Container Managed Transactions (CMT) in an EJB3 container, transaction demarcation is done in session bean annotations or deployment descriptors, not programatically. The <literal>EntityManager</literal> will automatically be flushed on transaction completion (and if you have injected or lookup the <literal>EntityManager</literal>, it will be also closed automatically). If an exception occurs during the <literal>EntityManager</literal> use, transaction rollback occurs automatically if you don't catch the exception. Since <literal>EntityManager</literal> exceptions are <literal>RuntimeException</literal>s they will rollback the transaction as per the EJB specification (system exception vs. application exception).
</para>
@@ -237,7 +237,7 @@
Our entity manager/transaction management idiom for CMT and EJB3 container-use is reduced to this:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_28.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<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>
@@ -364,7 +364,7 @@
In an implementation without much help from the persistence mechanism, each interaction with the database occurs in a new <literal>EntityManager</literal> and the developer is responsible for reloading all persistent instances from the database before manipulating them. This approach forces the application to carry out its own version checking to ensure application transaction isolation. This approach is the least efficient in terms of database access. It is the approach most similar to EJB2 entities:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_29.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>version</literal> property is mapped using <literal>@Version</literal>, and the entity manager will automatically increment it during flush if the entity is dirty.
</para>
@@ -388,7 +388,7 @@
The <literal>Entity Manager</literal> is disconnected from any underlying JDBC connection when waiting for user interaction. In an application-managed extended entity manager, this occurs automatically at transaction completion. In a stateful session bean holding a container-managed extended entity manager (i.e. a SFSB annotated with <literal>@PersistenceContext(EXTENDED)</literal>), this occurs transparently as well. This approach is the most efficient in terms of database access. The application need not concern itself with version checking or with merging detached instances, nor does it have to reload instances in every database transaction. For those who might be concerned by the number of connections opened and closed, remember that the connection provider should be a connection pool, so there is no performance impact. The following examples show the idiom in a non-managed environment:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_30.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>foo</literal> object still knows which <literal>persistence context</literal> it was loaded in. With <literal>getTransaction.begin();</literal> the entity manager obtains a new connection and resumes the persistence context. The method <literal>getTransaction().commit()</literal> will not only flush and check versions, but also disconnects the entity manager from the JDBC connection and return the connection to the pool.
</para>
@@ -405,7 +405,7 @@
<para>
With this paradigm, each interaction with the data store occurs in a new persistence context. However, the same persistent instances are reused for each interaction with the database. The application manipulates the state of detached instances originally loaded in another persistence context and then merges the changes using <literal>EntityManager.merge()</literal>:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_31.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Again, the entity manager will check instance versions during flush, throwing an exception if conflicting updates occurred.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_EntityManager_User_Guide/en-US/Working_with_objects.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -30,7 +30,7 @@
Once you've created a new entity instance (using the common <literal>new</literal> operator) it is in the <literal>new</literal> state. You can make it persistent by associating it to an entity manager:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_8.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
If the <literal>DomesticCat</literal> entity type has a generated identifier, the value is associated to the instance when <code>persist()</code> is called. If the identifier is not automatically generated, the application-assigned (usually natural) key value has to be set on the instance before <code>persist()</code> is called.
</para>
@@ -42,17 +42,17 @@
Load an entity instance by its identifier value with the entity manager's <code>find()</code> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
In some cases, you don't really want to load the object state, but just have a reference to it (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 language="java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<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 refreshed unless you specify <literal>REFRESH</literal> as a cascade style of any associations:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_11.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Querying_objects">
@@ -66,7 +66,7 @@
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>
- <!--<programlisting language="java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>-->
+ <!--<programlisting language="Java"><xi:include href="extras/Code_Example_12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>-->
<para>
A query is usually executed by invoking <methodname>getResultList()</methodname>. This method loads the resulting instances of the query completely 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>
@@ -76,7 +76,7 @@
An EJB3QL query queries can return tuples of objects if projection is used. Each result tuple is returned as an object array:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Scalar_results">
@@ -85,7 +85,7 @@
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 language="java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Bind_parameters">
@@ -94,7 +94,7 @@
Both named and positional query parameters are supported. The <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 preferred, they are more robust and easier to read and understand:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_15.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="sect-Hibernate_EntityManager_User_Guide-Executing_queries-Pagination">
@@ -103,7 +103,7 @@
If you need to specify bounds upon your result set (the maximum number of rows you want to retrieve and/or the first row you want to retrieve), use the following methods:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_16.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Hibernate knows how to translate this limit query into the native SQL of your DBMS.
</para>
@@ -115,12 +115,12 @@
You may also define named queries through annotations:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_17.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Parameters are bound programatically to the named query, before it is executed:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_18.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Note that the actual program code is independent of the query language that is used. You may also define native SQL queries in metadata, or use Hibernate's native facilities by placing them in XML mapping files.
</para>
@@ -132,7 +132,7 @@
You may express a query in SQL, using <methodname>createNativeQuery()</methodname> and let Hibernate take care mapping from JDBC result sets to business objects. Use the <literal>@SqlResultSetMapping</literal> (please see the Hibernate Annotations reference documentation on how to map a SQL resultset mapping) or the entity mapping (if the column names of the query result are the same as the names declared in the entity mapping. Remember that all entity columns have to be returned for this mechanism to work):
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_19.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
For more information about scalar support in named queries, please refers to the Hibernate Annotations documentation
@@ -251,7 +251,7 @@
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 in <xref linkend="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Flush_the_persistence_context" />). 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 language="java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_20.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Sometimes this programming model is inefficient since it would require both an SQL SELECT (to load an object) and an SQL UPDATE (to persist its updated state) in the same session. Therefore Hibernate offers an alternate approach, using detached instances.
</para>
@@ -266,7 +266,7 @@
The EJB3 specifications supports this development model by providing for persistence of modifications made to detached instances using the <methodname>EntityManager.merge()</methodname> method:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_21.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The <literal>merge()</literal> method merges modifications made to the detached instance into the corresponding managed instance, if any, without consideration of the state of the persistence context. In other words, the merged objects state overrides the persistent entity state in the persistence context, if one is already present. The application should individually <methodname>merge()</methodname> detached instances reachable from the given detached instance if and only if it wants their state also to be persistent. This can be cascaded to associated entities and collections, using transitive persistence, see <xref linkend="sect-Hibernate_EntityManager_User_Guide-Working_with_objects-Transitive_persistence" />.
</para>
@@ -278,7 +278,7 @@
The merge operation is clever enough to automatically detect whether the merging of the detached instance has to result in an insert or update. In other words, you don't have to worry about passing a new instance (and not a detached instance) to <literal>merge()</literal>, the entity manager will figure this out for you:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_22.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
The usage and semantics of <literal>merge()</literal> seem to be confusing for new users. Remember that as long as you are not trying to use an object state loaded in one entity manager in another new entity manager, you should not need to use <methodname>merge()</methodname> at all. Some whole applications will never use this method.
</para>
@@ -424,7 +424,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 language="java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_23.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
During flush, an exception might happen (e.g. if a DML operation violates a constraint).
</para>
@@ -457,12 +457,12 @@
For each basic operation of the entity manager - including <methodname>persist()</methodname>, <methodname>merge()</methodname>, <methodname>remove()</methodname>, <methodname>refresh()</methodname> - there is a corresponding cascade style. Respectively, the cascade styles are named PERSIST, MERGE, REMOVE, REFRESH. If you want an operation to be cascaded to associated entity (or collection of entities), you must indicate that in the association annotation:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_24.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
Cascading options can be combined:
</para>
- <programlisting language="java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/Code_Example_25.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
You may even use CascadeType.ALL to specify that all operations should be cascaded for a particular association. Remember that by default, no operation is cascaded.
</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP06.ent
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP06.ent 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Search/en-US/Hibernate_Search_Reference_Guide_CP06.ent 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,3 +1,4 @@
+<!ENTITY HOLDER "Red Hat, Inc">
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "Hibernate_Search">
<!ENTITY YEAR "2009">
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Checkconstraints.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -66,7 +66,7 @@
Core, use the following configuration in
<literal>hibernate.cfg.xml</literal>:</para>
- <programlisting language="xml"><xi:include href="extras/hibernate_config.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/hibernate_config.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="Hibernate_Validator-Checkconstraints-orm-jpaevent">
@@ -85,7 +85,7 @@
<para>Here is how to make a class validatable:</para>
- <programlisting language="java"><xi:include href="extras/class_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/class_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para><note>
<para>Compared to the Hibernate event, the Java Persistence listener
@@ -102,7 +102,7 @@
<para>Hibernate Validator can be applied anywhere in your application
code.</para>
- <programlisting language="java"><xi:include href="extras/app_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/app_validate.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The first two lines prepare the Hibernate Validator for class
checking. The first one relies upon the error messages embedded in
@@ -116,7 +116,7 @@
<para>You can also check a particular property instead of the whole bean.
This might be useful for property per property user interaction</para>
- <programlisting language="java"><xi:include href="extras/check_property.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/check_property.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
<section id="Hibernate_Validator-Checkconstraints-presentationlayer">
@@ -128,7 +128,7 @@
<literal><s:validateAll/></literal>, letting the constraints be
expressed on the model, and the violations presented in the view.</para>
- <programlisting language="java"><xi:include href="extras/pres_validation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/pres_validation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>Going even further, and adding <productname>Ajax4JSF</productname>
to the loop will bring client side validation with just a couple of
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Defineconstraints.xml 2009-11-16 02:05:20 UTC (rev 96390)
@@ -278,7 +278,7 @@
<emphasis>validator</emphasis> (the implementation class). Here is a
simple user-defined descriptor:</para>
- <programlisting language="java"><xi:include href="extras/define_descriptor.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/define_descriptor.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para><literal>type</literal> is a parameter describing how the property
should to be capitalized. This is a user parameter fully dependant on the
@@ -295,7 +295,7 @@
good practice. See <xref linkend="Hibernate_Validator-Defineconstraints-error" />
.</para>
- <programlisting language="java"><xi:include href="extras/validator_capitalized.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/validator_capitalized.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>As you can see the {} notation is recursive.</para>
@@ -311,7 +311,7 @@
database level (by implementing
<literal>PersistentClassConstraint</literal> )</para>
- <programlisting language="java"><xi:include href="extras/validator_implementation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/validator_implementation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The <literal>isValid()</literal> method should return false if the
constraint has been violated. For more examples, refer to the built-in
@@ -327,7 +327,7 @@
parameters) on the same property or type, you can use the following
annotation form:</para>
- <programlisting language="java"><xi:include href="extras/constraint_annotation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/constraint_annotation.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>Basically an annotation containing the value attribute as an array
of validator annotations.</para>
@@ -339,18 +339,18 @@
<para>Since you are already familiar with annotations now, the syntax
should be very familiar.</para>
- <programlisting language="java"><xi:include href="extras/annotation_syntax.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotation_syntax.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>While the example only shows public property validation, you can
also annotate fields of any kind of visibility.</para>
- <programlisting language="java"><xi:include href="extras/annotate_constraint.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotate_constraint.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>You can also annotate interfaces. Hibernate Validator will check all
superclasses and interfaces extended or implemented by a given bean to
read the appropriate validator annotations.</para>
- <programlisting language="java"><xi:include href="extras/annotate_interface.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/annotate_interface.javat" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>The name property will be checked for nullity when the Dog bean is
validated.</para>
Modified: projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP06.ent
===================================================================
--- projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP06.ent 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Hibernate/Hibernate_Validator/en-US/Hibernate_Validator_Reference_Guide_CP06.ent 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,3 +1,4 @@
+<!ENTITY HOLDER "Red Hat, Inc">
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "Hibernate_Validator">
<!ENTITY YEAR "2009">
Modified: projects/docs/enterprise/4.3.7/Installation_Guide/publican.cfg
===================================================================
--- projects/docs/enterprise/4.3.7/Installation_Guide/publican.cfg 2009-11-16 01:41:43 UTC (rev 96389)
+++ projects/docs/enterprise/4.3.7/Installation_Guide/publican.cfg 2009-11-16 02:05:20 UTC (rev 96390)
@@ -1,5 +1,5 @@
# Config::Simple 4.59
-# Fri Nov 6 12:52:03 2009
+# Mon Nov 9 08:16:41 2009
debug: 1
xml_lang: en-US
More information about the jboss-cvs-commits
mailing list