Author: steve.ebersole(a)jboss.com Date: 2010-06-04 20:54:54 -0400 (Fri, 04 Jun 2010) New Revision: 19694 Added: core/branches/gradle2/hibernate-release/ core/branches/gradle2/hibernate-release/hibernate-release.gradle core/branches/gradle2/hibernate-release/src/ core/branches/gradle2/hibernate-release/src/main/ core/branches/gradle2/hibernate-release/src/main/docbook/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/Book_Info.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/author_group.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/architecture.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/association_mapping.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/basic_mapping.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/batch.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/best_practices.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/bibliography.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/collection_mapping.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/component_mapping.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/configuration.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/events.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_mappings.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_parentchild.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_weblog.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/filters.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/inheritance_mapping.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/performance.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/persistent_classes.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/portability.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/preface.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_criteria.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_hql.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_sql.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/readonly.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/session_api.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/toolset_guide.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/transactions.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/tutorial.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/type.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/xml.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/extras/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/extras/namespacing.xml_sample core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Conventions.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Feedback.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Legal_Notice.xml core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.zargo core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.zargo core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.zargo core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.svg core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/hibernate_logo_a.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.svg core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.png core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.svg core/branches/gradle2/hibernate-release/src/main/docbook/en-US/legal_notice.xml core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Book_Info.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Hibernate_Reference.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/author_group.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/architecture.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/association_mapping.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/basic_mapping.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/batch.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/best_practices.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/bibliography.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/collection_mapping.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/component_mapping.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/configuration.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/events.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_mappings.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_parentchild.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_weblog.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/filters.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/inheritance_mapping.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/performance.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/persistent_classes.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/portability.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/preface.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_criteria.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_hql.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_sql.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/quickstart.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/readonly.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/session_api.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/toolset_guide.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/transactions.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/tutorial.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/xml.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Conventions.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Feedback.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Legal_Notice.po core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/legal_notice.po Modified: core/branches/gradle2/settings.gradle Log: initial swag at applying gradle-jdocbook Added: core/branches/gradle2/hibernate-release/hibernate-release.gradle =================================================================== --- core/branches/gradle2/hibernate-release/hibernate-release.gradle (rev 0) +++ core/branches/gradle2/hibernate-release/hibernate-release.gradle 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,41 @@ +buildscript { + repositories { + mavenRepo name: "jboss", urls: "https://repository.jboss.org/nexus/content/groups/public/" + mavenRepo name: "mavenCache", urls: "file://" + System.getProperty('user.home') + "/.m2/repository/" + } + dependencies { + classpath "org.jboss.jdocbook:gradle-jdocbook:1.0.0-SNAPSHOT" + } +} + +apply plugin: 'base' // for clean +apply plugin: 'jdocbook' + +dependencies { + jdocbookStyles( + "org.hibernate:hibernate-jdocbook-style:2.0.1" + ) +} + +jdocbook { + masterSourceDocumentName = 'HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml' + translation 'fr-FR' + profiling { + enabled = true + } + format { + name = 'html_single' + finalName = 'index.html' + stylesheet = 'classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml-single.xsl' + } +// format { +// name 'html' +// finalName 'index.html' +// stylesheet 'classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml.xsl' +// } +// format { +// name 'pdf' +// stylesheet 'classpath:/xslt/org/hibernate/jdocbook/xslt/pdf.xsl' +// } + +} \ No newline at end of file Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/Book_Info.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/Book_Info.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/Book_Info.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,52 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; +]> + +<bookinfo id="HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java"> + <title>HIBERNATE - Relational Persistence for Idiomatic Java</title> + <subtitle>Hibernate Reference Documentation</subtitle> + <releaseinfo>&version;</releaseinfo> + <edition>1.0</edition> + <pubsnumber>1</pubsnumber> + <productname>JBoss Hibernate Core</productname> + <productnumber>&version;</productnumber> + <pubdate>&today;</pubdate> + <issuenum>1</issuenum> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/hibernate_logo_a.png" align="center" /> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="author_group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <!-- Insert relevant fallback material here. Legal_Notice and Author Group is a relevant placement BookInfo.xml--> + + <!-- No legal Notice in Community docs so commenting out --> + <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="Common_Content/Legal_Notice.xml"> + LEGAL NOTICE INCLUSION FOR JDOCBOOK: + <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="fallback_content/Legal_Notice.xml" + xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> + </xi:fallback> + </xi:include> --> + + <!-- + FOR PUBLICAN + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> + FOR JDOCBOOK + <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"/> + </xi:include> + --> + +</bookinfo> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,5 @@ +<!ENTITY version "WORKING"> +<!ENTITY today "TODAY"> +<!ENTITY copyrightYear "2004"> +<!ENTITY copyrightHolder "Red Hat, Inc."> +<!ENTITY semi ";"> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,108 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; +]> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!-- old DTD and entity declaration +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY versionNumber "WORKING"> + <!ENTITY today "TODAY"> + <!ENTITY copyrightYear "2004"> + <!ENTITY copyrightHolder "Red Hat Middleware, LLC."> +]> +--> +<book> +<!-- + <bookinfo> + <title>HIBERNATE - Relational Persistence for Idiomatic Java</title> + <subtitle>Hibernate Reference Documentation</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <pubdate>&today;</pubdate> + <issuenum>1</issuenum> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/hibernate_logo_a.png" align="center" /> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="author_group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + + <toc/> +--> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/persistent_classes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/basic_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/collection_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/association_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/component_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/inheritance_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/session_api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/readonly.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/batch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/query_hql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/query_criteria.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/query_sql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/filters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/toolset_guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/example_parentchild.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/example_weblog.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/example_mappings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/best_practices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/portability.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/bibliography.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</book> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/author_group.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/author_group.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/author_group.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,189 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2009, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<authorgroup> + <author> + <firstname>Gavin</firstname> + <surname>King</surname> + </author> + <author> + <firstname>Christian</firstname> + <surname>Bauer</surname> + </author> + <author> + <firstname>Max</firstname> + <othername>Rydahl</othername> + <surname>Andersen</surname> + </author> + <author> + <firstname>Emmanuel</firstname> + <surname>Bernard</surname> + </author> + <author> + <firstname>Steve</firstname> + <surname>Ebersole</surname> + </author> + + <othercredit> + <firstname>James</firstname> + <surname>Cobb</surname> + <affiliation> + <shortaffil>Graphic Design</shortaffil> + </affiliation> + </othercredit> + <othercredit> + <firstname>Cheyenne</firstname> + <surname>Weaver</surname> + <affiliation> + <shortaffil>Graphic Design</shortaffil> + </affiliation> + </othercredit> + + <!-- + ####################################################################### + # Spanish + ####################################################################### + --> + <othercredit class="translator" lang="es-ES"> + <othername><![CDATA[Bernardo Antonio Buffa Colom&#x00e9]]></othername> + <email&gt;kreimer(a)bbs.frc.utn.edu.ar&lt;/email&gt; + </othercredit> + + <!-- + ####################################################################### + # French + ####################################################################### + --> + <othercredit class="translator" lang="fr-FR"> + <firstname>Vincent</firstname> + <surname>Ricard</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Sebastien</firstname> + <surname>Cesbron</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Michael</firstname> + <surname>Courcy</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Vincent</firstname> + <surname>Giguère</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Baptiste</firstname> + <surname>Mathus</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Emmanuel</firstname> + <surname>Bernard</surname> + </othercredit> + <othercredit class="translator" lang="fr-FR"> + <firstname>Anthony</firstname> + <surname>Patricio</surname> + </othercredit> + + <!-- + ####################################################################### + # Portugese + ####################################################################### + --> + <othercredit class="translator" lang="pt-BR"> + <firstname>Alvaro</firstname> + <surname>Netto</surname> + <email&gt;alvaronetto(a)cetip.com.br&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Anderson</firstname> + <surname>Braulio</surname> + <email&gt;andersonbraulio(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Daniel Vieira</firstname> + <surname>Costa</surname> + <email&gt;danielvc(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Francisco</firstname> + <surname>gamarra</surname> + <email&gt;francisco.gamarra(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Gamarra</firstname> + <email&gt;mauricio.gamarra(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Luiz Carlos</firstname> + <surname>Rodrigues</surname> + <email&gt;luizcarlos_rodrigues(a)yahoo.com.br&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Marcel</firstname> + <surname>Castelo</surname> + <email&gt;marcel.castelo(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Paulo</firstname> + <surname>César</surname> + <email&gt;paulocol(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Pablo L.</firstname> + <surname>de Miranda</surname> + <email&gt;pablolmiranda(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Renato</firstname> + <surname>Deggau</surname> + <email&gt;rdeggau(a)gmail.com&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Rogério</firstname> + <surname>Araújo</surname> + <email&gt;rgildoaraujo(a)yahoo.com.br&lt;/email&gt; + </othercredit> + <othercredit class="translator" lang="pt-BR"> + <firstname>Wanderson</firstname> + <surname>Siqueira</surname> + <email&gt;wandersonxs(a)gmail.com&lt;/email&gt; + </othercredit> + + <!-- + ####################################################################### + # Chinese + ####################################################################### + --> + <othercredit class="translator" lang="zh-CN"> + <firstname>Cao</firstname> + <surname>Xiaogang</surname> + <affiliation> + <orgname>RedSaga</orgname> + </affiliation> + <contrib>Translation Lead</contrib> + <email&gt;caoxg(a)yahoo.com&lt;/email&gt; + </othercredit> + +</authorgroup> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/architecture.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/architecture.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/architecture.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,389 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="architecture"> + + <title>Architecture</title> + + <section id="architecture-overview" revision="1"> + <title>Overview</title> + + <para> + The diagram below provides a high-level view of the Hibernate architecture: + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/overview.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/overview.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + We do not have the scope in this document to provide a more detailed view of all the runtime architectures available; + Hibernate is flexible and supports several different approaches. We will, however, + show the two extremes: "minimal" architecture and "comprehensive" architecture. + </para> + + <para> + This next diagram illustrates how Hibernate utilizes database and configuration data to + provide persistence services, and persistent objects, to the application. + </para> + + <para> + The "minimal" architecture has the application + provide its own JDBC connections and manage its own transactions. This approach + uses a minimal subset of Hibernate's APIs: + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/lite.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/lite.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + The "comprehensive" architecture abstracts the application away from the + underlying JDBC/JTA APIs and allows Hibernate to manage the details. + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/full_cream.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/full_cream.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + Here are some definitions of the objects depicted in the diagrams: + + <variablelist spacing="compact"> + <varlistentry> + <term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term> + <listitem> + <para> + A threadsafe, immutable cache of compiled mappings for a single database. + A factory for <literal>Session</literal> and a client of + <literal>ConnectionProvider</literal>, <literal>SessionFactory</literal> can hold an optional (second-level) + cache of data that is reusable between transactions at a + process, or cluster, level. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Session (<literal>org.hibernate.Session</literal>)</term> + <listitem> + <para> + A single-threaded, short-lived object representing a conversation between + the application and the persistent store. It wraps a JDBC connection and is a factory + for <literal>Transaction</literal>. <literal>Session</literal> holds a mandatory first-level cache + of persistent objects that are used when navigating the object graph or looking up + objects by identifier. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Persistent objects and collections</term> + <listitem> + <para> + Short-lived, single threaded objects containing persistent state and business + function. These can be ordinary JavaBeans/POJOs. They are associated with exactly one + <literal>Session</literal>. Once the <literal>Session</literal> is closed, + they will be detached and free to use in any application layer (for example, directly + as data transfer objects to and from presentation). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Transient and detached objects and collections</term> + <listitem> + <para> + Instances of persistent classes that are not currently associated with a + <literal>Session</literal>. They may have been instantiated by + the application and not yet persisted, or they may have been instantiated by a + closed <literal>Session</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Transaction (<literal>org.hibernate.Transaction</literal>)</term> + <listitem> + <para> + (Optional) A single-threaded, short-lived object used by the application to + specify atomic units of work. It abstracts the application from the underlying JDBC, + JTA or CORBA transaction. A <literal>Session</literal> might span several + <literal>Transaction</literal>s in some cases. However, transaction demarcation, + either using the underlying API or <literal>Transaction</literal>, is never + optional. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term> + <listitem> + <para> + (Optional) A factory for, and pool of, JDBC connections. It abstracts the application from + underlying <literal>Datasource</literal> or <literal>DriverManager</literal>. + It is not exposed to application, but it can be extended and/or implemented by the developer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term> + <listitem> + <para> + (Optional) A factory for <literal>Transaction</literal> instances. It is not exposed to the + application, but it can be extended and/or implemented by the developer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Extension Interfaces</emphasis></term> + <listitem> + <para> + Hibernate offers a range of optional extension interfaces you can implement to customize + the behavior of your persistence layer. See the API documentation for details. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Given a "minimal" architecture, the application bypasses the + <literal>Transaction</literal>/<literal>TransactionFactory</literal> and/or + <literal>ConnectionProvider</literal> APIs to communicate with JTA or JDBC directly. + </para> + </section> + + <section id="architecture-states" revision="1"> + <title>Instance states</title> + <para> + An instance of a persistent class can be in one of three different states. These states are + defined in relation to a <emphasis>persistence context</emphasis>. + The Hibernate <literal>Session</literal> object is the persistence context. The three different states are as follows: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term>transient</term> + <listitem> + <para> + The instance is not associated with + any persistence context. It has no persistent identity or + primary key value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>persistent</term> + <listitem> + <para> + The instance is currently associated with a persistence + context. It has a persistent identity (primary key value) + and can have a corresponding row in the database. For a + particular persistence context, Hibernate + <emphasis>guarantees</emphasis> that persistent identity + is equivalent to Java identity in relation to the in-memory location of the + object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>detached</term> + <listitem> + <para> + The instance was once associated with a persistence + context, but that context was closed, or the instance + was serialized to another process. It has a persistent + identity and can have a corresponding row in the database. + For detached instances, Hibernate does not guarantee + the relationship between persistent identity and + Java identity. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="architecture-jmx" revision="1"> + <title>JMX Integration</title> + + <para> + JMX is the J2EE standard for the management of Java components. Hibernate can be managed via + a JMX standard service. AN MBean implementation is provided in the distribution: + <literal>org.hibernate.jmx.HibernateService</literal>. + </para> + + <para> + For an example of how to deploy Hibernate as a JMX service on the JBoss Application Server, + please see the JBoss User Guide. JBoss AS also provides these benefits if you deploy + using JMX: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Session Management</emphasis>: the Hibernate <literal>Session</literal>'s life cycle + can be automatically bound to the scope of a JTA transaction. This means that you no + longer have to manually open and close the <literal>Session</literal>; this + becomes the job of a JBoss EJB interceptor. You also do not have to worry about + transaction demarcation in your code (if you would like to write a portable + persistence layer use the optional Hibernate <literal>Transaction</literal> + API for this). You call the <literal>HibernateContext</literal> to access a + <literal>Session</literal>. + </para> + </listitem> + <listitem> + <para> + <emphasis>HAR deployment</emphasis>: the Hibernate JMX service is deployed using a JBoss + service deployment descriptor in an EAR and/or SAR file, as it supports all the usual + configuration options of a Hibernate <literal>SessionFactory</literal>. However, you still + need to name all your mapping files in the deployment descriptor. If you use + the optional HAR deployment, JBoss will automatically detect all mapping files in your + HAR file. + </para> + </listitem> + </itemizedlist> + + <para> + Consult the JBoss AS user guide for more information about these options. + </para> + + <para> + Another feature available as a JMX service is runtime Hibernate statistics. See + <xref linkend="configuration-optional-statistics"/> for more information. + </para> + </section> + + <section id="architecture-jca" revision="1"> + <title>JCA Support</title> + <para> + Hibernate can also be configured as a JCA connector. Please see the website for more + information. Please note, however, that at this stage Hibernate JCA support is under development. + </para> + </section> + + <section id="architecture-current-session" revision="2"> + <title>Contextual sessions</title> + <para> + Most applications using Hibernate need some form of "contextual" session, where a given + session is in effect throughout the scope of a given context. However, across applications + the definition of what constitutes a context is typically different; different contexts + define different scopes to the notion of current. Applications using Hibernate prior + to version 3.0 tended to utilize either home-grown <literal>ThreadLocal</literal>-based + contextual sessions, helper classes such as <literal>HibernateUtil</literal>, or utilized + third-party frameworks, such as Spring or Pico, which provided proxy/interception-based contextual sessions. + </para> + <para> + Starting with version 3.0.1, Hibernate added the <literal>SessionFactory.getCurrentSession()</literal> + method. Initially, this assumed usage of <literal>JTA</literal> transactions, where the + <literal>JTA</literal> transaction defined both the scope and context of a current session. + Given the maturity of the numerous stand-alone + <literal>JTA TransactionManager</literal> implementations, most, if not all, + applications should be using <literal>JTA</literal> transaction management, whether or not + they are deployed into a <literal>J2EE</literal> container. Based on that, the + <literal>JTA</literal>-based contextual sessions are all you need to use. + </para> + <para> + However, as of version 3.1, the processing behind + <literal>SessionFactory.getCurrentSession()</literal> is now pluggable. To that + end, a new extension interface, <literal>org.hibernate.context.CurrentSessionContext</literal>, + and a new configuration parameter, <literal>hibernate.current_session_context_class</literal>, + have been added to allow pluggability of the scope and context of defining current sessions. + </para> + <para> + See the Javadocs for the <literal>org.hibernate.context.CurrentSessionContext</literal> + interface for a detailed discussion of its contract. It defines a single method, + <literal>currentSession()</literal>, by which the implementation is responsible for + tracking the current contextual session. Out-of-the-box, Hibernate comes with three + implementations of this interface: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>org.hibernate.context.JTASessionContext</literal>: current sessions + are tracked and scoped by a <literal>JTA</literal> transaction. The processing + here is exactly the same as in the older JTA-only approach. See the Javadocs + for details. + </para> + </listitem> + <listitem> + <para> + <literal>org.hibernate.context.ThreadLocalSessionContext</literal>:current + sessions are tracked by thread of execution. See the Javadocs for details. + </para> + </listitem> + <listitem> + <para> + <literal>org.hibernate.context.ManagedSessionContext</literal>: current + sessions are tracked by thread of execution. However, you are responsible to + bind and unbind a <literal>Session</literal> instance with static methods + on this class: it does not open, flush, or close a <literal>Session</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + The first two implementations provide a "one session - one database transaction" programming + model. This is also known and used as <emphasis>session-per-request</emphasis>. The beginning + and end of a Hibernate session is defined by the duration of a database transaction. + If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to + use the Hibernate <literal>Transaction</literal> API to hide the underlying transaction system + from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you + execute in an EJB container that supports CMT, transaction boundaries are defined declaratively + and you do not need any transaction or session demarcation operations in your code. + Refer to <xref linkend="transactions"/> for more information and code examples. + </para> + + <para> + The <literal>hibernate.current_session_context_class</literal> configuration parameter + defines which <literal>org.hibernate.context.CurrentSessionContext</literal> implementation + should be used. For backwards compatibility, if this configuration parameter is not set + but a <literal>org.hibernate.transaction.TransactionManagerLookup</literal> is configured, + Hibernate will use the <literal>org.hibernate.context.JTASessionContext</literal>. + Typically, the value of this parameter would just name the implementation class to + use. For the three out-of-the-box implementations, however, there are three corresponding + short names: "jta", "thread", and "managed". + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/association_mapping.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/association_mapping.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/association_mapping.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,654 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="associations"> + + <title>Association Mappings</title> + + <section id="assoc-intro" revision="1"> + <title>Introduction</title> + + <para> + Association mappings are often the most difficult thing to implement correctly. In + this section we examine some canonical cases one by one, starting + with unidirectional mappings and then bidirectional cases. + We will use <literal>Person</literal> and <literal>Address</literal> in all + the examples. + </para> + + <para> + Associations will be classified by multiplicity and whether or not they map to an intervening + join table. + </para> + + <para> + Nullable foreign keys are not considered to be good practice in traditional data + modelling, so our examples do not use nullable foreign keys. This is not a + requirement of Hibernate, and the mappings will work if you drop the + nullability constraints. + </para> + + </section> + + <section id="assoc-unidirectional" revision="1"> + <title>Unidirectional associations</title> + + <section id="assoc-unidirectional-m21"> + <title>Many-to-one</title> + + <para> + A <emphasis>unidirectional many-to-one association</emphasis> is the most + common kind of unidirectional association. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-unidirectional-121"> + <title>One-to-one</title> + + <para> + A <emphasis>unidirectional one-to-one association on a foreign key</emphasis> + is almost identical. The only difference is the column unique constraint. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + unique="true" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + A <emphasis>unidirectional one-to-one association on a primary key</emphasis> + usually uses a special id generator In this example, however, we have reversed the direction + of the association: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> +</class> + +<class name="Address"> + <id name="id" column="personId"> + <generator class="foreign"> + <param name="property">person</param> + </generator> + </id> + <one-to-one name="person" constrained="true"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( personId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-unidirectional-12m"> + <title>One-to-many</title> + + <para> + A <emphasis>unidirectional one-to-many association on a foreign key</emphasis> + is an unusual case, and is not recommended. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses"> + <key column="personId" + not-null="true"/> + <one-to-many class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( addressId bigint not null primary key, personId bigint not null ) + ]]></programlisting> + + <para> + You should instead use a join table for this kind of association. + </para> + + </section> + + </section> + + <section id="assoc-unidirectional-join" revision="1"> + <title>Unidirectional associations with join tables</title> + + <section id="assoc-unidirectional-join-12m"> + <title>One-to-many</title> + + <para> + A <emphasis>unidirectional one-to-many association on a join table</emphasis> + is the preferred option. Specifying <literal>unique="true"</literal>, + changes the multiplicity from many-to-many to one-to-many. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + unique="true" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId not null, addressId bigint not null primary key ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-unidirectional-join-m21"> + <title>Many-to-one</title> + + <para> + A <emphasis>unidirectional many-to-one association on a join table</emphasis> + is common when the association is optional. For example: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-unidirectional-join-121"> + <title>One-to-one</title> + + <para> + A <emphasis>unidirectional one-to-one association on a join table</emphasis> is possible, + but extremely unusual. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" + unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true" + unique="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-unidirectional-join-m2m"> + <title>Many-to-many</title> + + <para> + Finally, here is an example of a <emphasis>unidirectional many-to-many association</emphasis>. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + </section> + + <section id="assoc-bidirectional" revision="1"> + <title>Bidirectional associations</title> + + <section id="assoc-bidirectional-m21" revision="2"> + <title>one-to-many / many-to-one</title> + + <para> + A <emphasis>bidirectional many-to-one association</emphasis> is the + most common kind of association. The following example illustrates the standard parent/child + relationship. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <set name="people" inverse="true"> + <key column="addressId"/> + <one-to-many class="Person"/> + </set> +</class>]]></programlisting> + + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + If you use a <literal>List</literal>, or other indexed collection, + set the <literal>key</literal> column of the foreign key to <literal>not null</literal>. + Hibernate will manage the association from the collections side to maintain the index + of each element, making the other side virtually inverse by setting + <literal>update="false"</literal> and <literal>insert="false"</literal>: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id"/> + ... + <many-to-one name="address" + column="addressId" + not-null="true" + insert="false" + update="false"/> +</class> + +<class name="Address"> + <id name="id"/> + ... + <list name="people"> + <key column="addressId" not-null="true"/> + <list-index column="peopleIdx"/> + <one-to-many class="Person"/> + </list> +</class>]]></programlisting> + + <para> + If the underlying foreign key column is <literal>NOT NULL</literal>, it + is important that you define <literal>not-null="true"</literal> on the + <literal>&lt;key&gt;</literal> element of the collection mapping. + Do not only + declare <literal>not-null="true"</literal> on a possible nested + <literal>&lt;column&gt;</literal> element, but on the <literal>&lt;key&gt;</literal> + element. + </para> + + </section> + + <section id="assoc-bidirectional-121"> + <title>One-to-one</title> + + <para> + A <emphasis>bidirectional one-to-one association on a foreign key</emphasis> + is common: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + unique="true" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <one-to-one name="person" + property-ref="address"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + A <emphasis>bidirectional one-to-one association on a primary key</emphasis> + uses the special id generator: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <one-to-one name="address"/> +</class> + +<class name="Address"> + <id name="id" column="personId"> + <generator class="foreign"> + <param name="property">person</param> + </generator> + </id> + <one-to-one name="person" + constrained="true"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( personId bigint not null primary key ) + ]]></programlisting> + + </section> + + </section> + + <section id="assoc-bidirectional-join" revision="1"> + <title>Bidirectional associations with join tables</title> + + <section id="assoc-bidirectional-join-12m"> + <title>one-to-many / many-to-one</title> + + <para> + The following is an example of a <emphasis>bidirectional one-to-many association on a join table</emphasis>. + The <literal>inverse="true"</literal> can go on either end of the + association, on the collection, or on the join. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" + table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + unique="true" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + inverse="true" + optional="true"> + <key column="addressId"/> + <many-to-one name="person" + column="personId" + not-null="true"/> + </join> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null primary key ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-bidirectional-join-121"> + <title>one to one</title> + + <para> + A <emphasis>bidirectional one-to-one association on a join table</emphasis> is possible, + but extremely unusual. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" + unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true" + unique="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true" + inverse="true"> + <key column="addressId" + unique="true"/> + <many-to-one name="person" + column="personId" + not-null="true" + unique="true"/> + </join> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + <section id="assoc-bidirectional-join-m2m" revision="1"> + <title>Many-to-many</title> + + <para> + Here is an example of a <emphasis>bidirectional many-to-many association</emphasis>. + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <set name="people" inverse="true" table="PersonAddress"> + <key column="addressId"/> + <many-to-many column="personId" + class="Person"/> + </set> +</class>]]></programlisting> + + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </section> + + </section> + + <section id="assoc-complex"> + <title>More complex association mappings</title> + + <para> + More complex association joins are <emphasis>extremely</emphasis> rare. + Hibernate handles more complex situations by using + SQL fragments embedded in the mapping document. For example, if a table + with historical account information data defines + <literal>accountNumber</literal>, <literal>effectiveEndDate</literal> + and <literal>effectiveStartDate</literal>columns, it would be mapped as follows: + </para> + + <programlisting role="XML"><![CDATA[<properties name="currentAccountKey"> + <property name="accountNumber" type="string" not-null="true"/> + <property name="currentAccount" type="boolean"> + <formula>case when effectiveEndDate is null then 1 else 0 end</formula> + </property> +</properties> +<property name="effectiveEndDate" type="date"/> +<property name="effectiveStateDate" type="date" not-null="true"/>]]></programlisting> + + <para> + You can then map an association to the <emphasis>current</emphasis> instance, + the one with null <literal>effectiveEndDate</literal>, by using: + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="currentAccountInfo" + property-ref="currentAccountKey" + class="AccountInfo"> + <column name="accountNumber"/> + <formula>'1'</formula> +</many-to-one>]]></programlisting> + + <para> + In a more complex example, imagine that the association between + <literal>Employee</literal> and <literal>Organization</literal> is maintained + in an <literal>Employment</literal> table full of historical employment data. + An association to the employee's <emphasis>most recent</emphasis> employer, + the one with the most recent <literal>startDate</literal>, could be mapped in the following way: + </para> + + <programlisting role="XML"><![CDATA[<join> + <key column="employeeId"/> + <subselect> + select employeeId, orgId + from Employments + group by orgId + having startDate = max(startDate) + </subselect> + <many-to-one name="mostRecentEmployer" + class="Organization" + column="orgId"/> +</join>]]></programlisting> + + <para> + This functionality allows a degree of creativity and flexibility, but it is more practical + to handle these kinds of cases using HQL or a criteria query. + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/basic_mapping.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/basic_mapping.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/basic_mapping.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,5601 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; +]> +<chapter id="mapping"> + <title>Basic O/R Mapping</title> + + <section id="mapping-declaration" revision="2"> + <title>Mapping declaration</title> + + <para>Object/relational mappings can be defined in three + approaches:</para> + + <itemizedlist> + <listitem> + <para>using Java 5 annotations (via the Java Persistence 2 + annotations)</para> + </listitem> + + <listitem> + <para>using JPA 2 XML deployment descriptors (described in chapter + XXX)</para> + </listitem> + + <listitem> + <para>using the Hibernate legacy XML files approach known as + hbm.xml</para> + </listitem> + </itemizedlist> + + <para>Annotations are split in two categories, the logical mapping + annotations (describing the object model, the association between two + entities etc.) and the physical mapping annotations (describing the + physical schema, tables, columns, indexes, etc). We will mix annotations + from both categories in the following code examples.</para> + + <para>JPA annotations are in the <literal>javax.persistence.*</literal> + package. Hibernate specific extensions are in + <literal>org.hibernate.annotations.*</literal>. You favorite IDE can + auto-complete annotations and their attributes for you (even without a + specific "JPA" plugin, since JPA annotations are plain Java 5 + annotations).</para> + + <para>Here is an example of mapping</para> + + <programlisting role="JAVA">package eg; + +@Entity +@Table(name="cats") @Inheritance(strategy=SINGLE_TABLE) +@DiscriminatorValue("C") @DiscriminatorColumn(name="subclass", discriminatorType=CHAR) +public class Cat { + + @Id @GeneratedValue + public Integer getId() { return id; } + public void setId(Integer id) { this.id = id; } + private Integer id; + + public BigDecimal getWeight() { return weight; } + public void setWeight(BigDecimal weight) { this.weight = weight; } + private BigDecimal weight; + + @Temporal(DATE) @NotNull @Column(updatable=false) + public Date getBirthdate() { return birthdate; } + public void setBirthdate(Date birthdate) { this.birthdate = birthdate; } + private Date birthdate; + + @org.hibernate.annotations.Type(type="eg.types.ColorUserType") + @NotNull @Column(updatable=false) + public ColorType getColor() { return color; } + public void setColor(ColorType color) { this.color = color; } + private ColorType color; + + @NotNull @Column(updatable=false) + public String getSex() { return sex; } + public void setSex(String sex) { this.sex = sex; } + private String sex; + + @NotNull @Column(updatable=false) + public Integer getLitterId() { return litterId; } + public void setLitterId(Integer litterId) { this.litterId = litterId; } + private Integer litterId; + + @ManyToOne @JoinColumn(name="mother_id", updatable=false) + public Cat getMother() { return mother; } + public void setMother(Cat mother) { this.mother = mother; } + private Cat mother; + + @OneToMany(mappedBy="mother") @OrderBy("litterId") + public Set&lt;Cat&gt; getKittens() { return kittens; } + public void setKittens(Set&lt;Cat&gt; kittens) { this.kittens = kittens; } + private Set&lt;Cat&gt; kittens = new HashSet&lt;Cat&gt;(); +} + +@Entity @DiscriminatorValue("D") +public class DomesticCat extends Cat { + + public String getName() { return name; } + public void setName(String name) { this.name = name } + private String name; +} + +@Entity +public class Dog { ... }</programlisting> + + <para>The legacy hbm.xml approach uses an XML schema designed to be + readable and hand-editable. The mapping language is Java-centric, meaning + that mappings are constructed around persistent class declarations and not + table declarations.</para> + + <para>Please note that even though many Hibernate users choose to write + the XML by hand, a number of tools exist to generate the mapping document. + These include XDoclet, Middlegen and AndroMDA.</para> + + <para>Here is an example mapping:</para> + + <programlisting role="XML">&lt;?xml version="1.0"?&gt; +&lt;!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"&gt; + +&lt;hibernate-mapping package="eg"&gt; + + &lt;class name="Cat" + table="cats" + discriminator-value="C"&gt; + + &lt;id name="id"&gt; + &lt;generator class="native"/&gt; + &lt;/id&gt; + + &lt;discriminator column="subclass" + type="character"/&gt; + + &lt;property name="weight"/&gt; + + &lt;property name="birthdate" + type="date" + not-null="true" + update="false"/&gt; + + &lt;property name="color" + type="eg.types.ColorUserType" + not-null="true" + update="false"/&gt; + + &lt;property name="sex" + not-null="true" + update="false"/&gt; + + &lt;property name="litterId" + column="litterId" + update="false"/&gt; + + &lt;many-to-one name="mother" + column="mother_id" + update="false"/&gt; + + &lt;set name="kittens" + inverse="true" + order-by="litter_id"&gt; + &lt;key column="mother_id"/&gt; + &lt;one-to-many class="Cat"/&gt; + &lt;/set&gt; + + &lt;subclass name="DomesticCat" + discriminator-value="D"&gt; + + &lt;property name="name" + type="string"/&gt; + + &lt;/subclass&gt; + + &lt;/class&gt; + + &lt;class name="Dog"&gt; + &lt;!-- mapping for Dog could go here --&gt; + &lt;/class&gt; + +&lt;/hibernate-mapping&gt;</programlisting> + + <para>We will now discuss the concepts of the mapping documents (both + annotations and XML). We will only describe, however, the document + elements and attributes that are used by Hibernate at runtime. The mapping + document also contains some extra optional attributes and elements that + affect the database schemas exported by the schema export tool (for + example, the <literal> not-null</literal> attribute).</para> + + <section> + <title>Some hbm.xml specificities</title> + + <para>The hbm.xml structure has some specificities naturally not present + when using annotations, let's describe them briefly.</para> + + <section id="mapping-declaration-doctype" revision="3"> + <title>Doctype</title> + + <para>All XML mappings should declare the doctype shown. The actual + DTD can be found at the URL above, in the directory + <literal>hibernate-x.x.x/src/org/hibernate </literal>, or in + <literal>hibernate3.jar</literal>. Hibernate will always look for the + DTD in its classpath first. If you experience lookups of the DTD using + an Internet connection, check the DTD declaration against the contents + of your classpath.</para> + + <section id="mapping-declaration-entity-resolution"> + <title>EntityResolver</title> + + <para>Hibernate will first attempt to resolve DTDs in its classpath. + It does this is by registering a custom + <literal>org.xml.sax.EntityResolver</literal> implementation with + the SAXReader it uses to read in the xml files. This custom + <literal>EntityResolver</literal> recognizes two different systemId + namespaces:</para> + + <itemizedlist> + <listitem> + <para>a <literal>hibernate namespace</literal> is recognized + whenever the resolver encounters a systemId starting with + <literal>http://hibernate.sourceforge.net/</literal>;. The + resolver attempts to resolve these entities via the classloader + which loaded the Hibernate classes.</para> + </listitem> + + <listitem> + <para>a <literal>user namespace</literal> is recognized whenever + the resolver encounters a systemId using a + <literal>classpath://</literal> URL protocol. The resolver will + attempt to resolve these entities via (1) the current thread + context classloader and (2) the classloader which loaded the + Hibernate classes.</para> + </listitem> + </itemizedlist> + + <para>The following is an example of utilizing user + namespacing:</para> + + <programlisting language="XML" role="XML"> +<xi:include href="../extras/namespacing.xml_sample" parse="text" + xmlns:xi="http://www.w3.org/2001/XInclude" /> +</programlisting> + + <para>Where <literal>types.xml</literal> is a resource in the + <literal>your.domain</literal> package and contains a custom <link + linkend="mapping-types-custom">typedef</link>.</para> + </section> + </section> + + <section id="mapping-declaration-mapping" revision="3"> + <title>Hibernate-mapping</title> + + <para>This element has several optional attributes. The + <literal>schema</literal> and <literal>catalog</literal> attributes + specify that tables referred to in this mapping belong to the named + schema and/or catalog. If they are specified, tablenames will be + qualified by the given schema and catalog names. If they are missing, + tablenames will be unqualified. The <literal>default-cascade</literal> + attribute specifies what cascade style should be assumed for + properties and collections that do not specify a + <literal>cascade</literal> attribute. By default, the + <literal>auto-import</literal> attribute allows you to use unqualified + class names in the query language.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="hm1" /> + + <area coords="3" id="hm2" /> + + <area coords="4" id="hm3" /> + + <area coords="5" id="hm4" /> + + <area coords="6" id="hm5" /> + + <area coords="7" id="hm6" /> + + <area coords="8" id="hm7" /> + </areaspec> + + <programlisting>&lt;hibernate-mapping + schema="schemaName" + catalog="catalogName" + default-cascade="cascade_style" + default-access="field|property|ClassName" + default-lazy="true|false" + auto-import="true|false" + package="package.name" + /&gt;</programlisting> + + <calloutlist> + <callout arearefs="hm1"> + <para><literal>schema</literal> (optional): the name of a + database schema.</para> + </callout> + + <callout arearefs="hm2"> + <para><literal>catalog</literal> (optional): the name of a + database catalog.</para> + </callout> + + <callout arearefs="hm3"> + <para><literal>default-cascade</literal> (optional - defaults to + <literal>none</literal>): a default cascade style.</para> + </callout> + + <callout arearefs="hm4"> + <para><literal>default-access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate should use + for accessing all properties. It can be a custom implementation + of <literal>PropertyAccessor</literal>.</para> + </callout> + + <callout arearefs="hm5"> + <para><literal>default-lazy</literal> (optional - defaults to + <literal>true</literal>): the default value for unspecified + <literal>lazy</literal> attributes of class and collection + mappings.</para> + </callout> + + <callout arearefs="hm6"> + <para><literal>auto-import</literal> (optional - defaults to + <literal>true</literal>): specifies whether we can use + unqualified class names of classes in this mapping in the query + language.</para> + </callout> + + <callout arearefs="hm7"> + <para><literal>package</literal> (optional): specifies a package + prefix to use for unqualified class names in the mapping + document.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>If you have two persistent classes with the same unqualified + name, you should set <literal>auto-import="false"</literal>. An + exception will result if you attempt to assign two classes to the same + "imported" name.</para> + + <para>The <literal>hibernate-mapping</literal> element allows you to + nest several persistent <literal>&lt;class&gt;</literal> mappings, as + shown above. It is, however, good practice (and expected by some + tools) to map only a single persistent class, or a single class + hierarchy, in one mapping file and name it after the persistent + superclass. For example, <literal>Cat.hbm.xml</literal>, + <literal>Dog.hbm.xml</literal>, or if using inheritance, + <literal>Animal.hbm.xml</literal>.</para> + </section> + + <section id="mapping-declaration-key"> + <title>Key</title> + + <para>The <literal>&lt;key&gt;</literal> element is featured a few + times within this guide. It appears anywhere the parent mapping + element defines a join to a new table that references the primary key + of the original table. It also defines the foreign key in the joined + table:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="key1" /> + + <area coords="3" id="key2" /> + + <area coords="4" id="key3" /> + + <area coords="5" id="key4" /> + + <area coords="6" id="key5" /> + + <area coords="7" id="key6" /> + </areaspec> + + <programlisting>&lt;key + column="columnname" + on-delete="noaction|cascade" + property-ref="propertyName" + not-null="true|false" + update="true|false" + unique="true|false" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="key1"> + <para><literal>column</literal> (optional): the name of the + foreign key column. This can also be specified by nested + <literal>&lt;column&gt;</literal> element(s).</para> + </callout> + + <callout arearefs="key2"> + <para><literal>on-delete</literal> (optional - defaults to + <literal>noaction</literal>): specifies whether the foreign key + constraint has database-level cascade delete enabled.</para> + </callout> + + <callout arearefs="key3"> + <para><literal>property-ref</literal> (optional): specifies that + the foreign key refers to columns that are not the primary key + of the original table. It is provided for legacy data.</para> + </callout> + + <callout arearefs="key4"> + <para><literal>not-null</literal> (optional): specifies that the + foreign key columns are not nullable. This is implied whenever + the foreign key is also part of the primary key.</para> + </callout> + + <callout arearefs="key5"> + <para><literal>update</literal> (optional): specifies that the + foreign key should never be updated. This is implied whenever + the foreign key is also part of the primary key.</para> + </callout> + + <callout arearefs="key6"> + <para><literal>unique</literal> (optional): specifies that the + foreign key should have a unique constraint. This is implied + whenever the foreign key is also the primary key.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>For systems where delete performance is important, we recommend + that all keys should be defined + <literal>on-delete="cascade"</literal>. Hibernate uses a + database-level <literal>ON CASCADE DELETE</literal> constraint, + instead of many individual <literal>DELETE</literal> statements. Be + aware that this feature bypasses Hibernate's usual optimistic locking + strategy for versioned data.</para> + + <para>The <literal>not-null</literal> and <literal>update</literal> + attributes are useful when mapping a unidirectional one-to-many + association. If you map a unidirectional one-to-many association to a + non-nullable foreign key, you <emphasis>must</emphasis> declare the + key column using <literal>&lt;key + not-null="true"&gt;</literal>.</para> + </section> + + <section id="mapping-declaration-import"> + <title>Import</title> + + <para>If your application has two persistent classes with the same + name, and you do not want to specify the fully qualified package name + in Hibernate queries, classes can be "imported" explicitly, rather + than relying upon <literal>auto-import="true"</literal>. You can also + import classes and interfaces that are not explicitly mapped:</para> + + <programlisting role="XML">&lt;import class="java.lang.Object" rename="Universe"/&gt;</programlisting> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="import1" /> + + <area coords="3" id="import2" /> + </areaspec> + + <programlisting>&lt;import + class="ClassName" + rename="ShortName" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="import1"> + <para><literal>class</literal>: the fully qualified class name + of any Java class.</para> + </callout> + + <callout arearefs="import2"> + <para><literal>rename</literal> (optional - defaults to the + unqualified class name): a name that can be used in the query + language.</para> + </callout> + </calloutlist> + </programlistingco> + + <note> + <para>This feature is unique to hbm.xml and is not supported in + annotations.</para> + </note> + </section> + + <section id="mapping-column" revision="5"> + <title>Column and formula elements</title> + + <para>Mapping elements which accept a <literal>column</literal> + attribute will alternatively accept a + <literal>&lt;column&gt;</literal> subelement. Likewise, + <literal>&lt;formula&gt;</literal> is an alternative to the + <literal>formula</literal> attribute. For example:</para> + + <programlisting role="XML">&lt;column + name="column_name" + length="N" + precision="N" + scale="N" + not-null="true|false" + unique="true|false" + unique-key="multicolumn_unique_key_name" + index="index_name" + sql-type="sql_type_name" + check="SQL expression" + default="SQL expression" + read="SQL expression" + write="SQL expression"/&gt;</programlisting> + + <programlisting role="XML">&lt;formula&gt;SQL expression&lt;/formula&gt;</programlisting> + + <para>Most of the attributes on <literal>column</literal> provide a + means of tailoring the DDL during automatic schema generation. The + <literal>read</literal> and <literal>write</literal> attributes allow + you to specify custom SQL that Hibernate will use to access the + column's value. For more on this, see the discussion of <link + linkend="mapping-column-read-and-write">column read and write + expressions</link>.</para> + + <para>The <literal>column</literal> and <literal>formula</literal> + elements can even be combined within the same property or association + mapping to express, for example, exotic join conditions.</para> + + <programlisting role="XML">&lt;many-to-one name="homeAddress" class="Address" + insert="false" update="false"&gt; + &lt;column name="person_id" not-null="true" length="10"/&gt; + &lt;formula&gt;'MAILING'&lt;/formula&gt; +&lt;/many-to-one&gt;</programlisting> + </section> + </section> + + <section id="mapping-declaration-class" revision="3"> + <title>Entity</title> + + <para>An entity is a regular Java object (aka POJO) which will be + persisted by Hibernate.</para> + + <para>To mark an object as an entity in annotations, use the + <classname>@Entity</classname> annotation.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +public class Flight implements Serializable { + Long id; + + @Id + public Long getId() { return id; } + + public void setId(Long id) { this.id = id; } +} </programlisting> + + <para>That's pretty much it, the rest is optional. There are however any + options to tweak your entity mapping, let's explore them.</para> + + <para><classname>@Table</classname> lets you define the table the entity + will be persisted into. If undefined, the table name is the unqualified + class name of the entity. You can also optionally define the catalog, + the schema as well as unique constraints on the table.</para> + + <programlisting role="JAVA">@Entity +@Table(name="TBL_FLIGHT", + schema="AIR_COMMAND", + uniqueConstraints= + @UniqueConstraint( + name="flight_number", + columnNames={"comp_prefix", "flight_number"} ) ) +public class Flight implements Serializable { + @Column(name="comp_prefix") + public String getCompagnyPrefix() { return companyPrefix; } + + @Column(name="flight_number") + public String getNumber() { return number; } +}</programlisting> + + <para>The constraint name is optional (generated if left undefined). The + column names composing the constraint correspond to the column names as + defined before the Hibernate <classname>NamingStrategy</classname> is + applied.</para> + + <para&gt;&lt;literal&gt;(a)Entity.name&lt;/literal&gt; lets you define the shortcut name + of the entity you can used in JP-QL and HQL queries. It defaults to the + unqualified class name of the class.</para> + + <para>Hibernate goes beyond the JPA specification and provide additional + configurations. Some of them are hosted on + <classname>@org.hibernate.annotations.Entity</classname>:</para> + + <itemizedlist> + <listitem> + <para><literal>dynamicInsert</literal> / + <literal>dynamicUpdate</literal> (defaults to false): specifies that + <literal>INSERT</literal> / <literal>UPDATE</literal> SQL should be + generated at runtime and contain only the columns whose values are + not null. The <literal>dynamic-update</literal> and + <literal>dynamic-insert</literal> settings are not inherited by + subclasses. Although these settings can increase performance in some + cases, they can actually decrease performance in others.</para> + </listitem> + + <listitem> + <para><literal>selectBeforeUpdate</literal> (defaults to false): + specifies that Hibernate should <emphasis>never</emphasis> perform + an SQL <literal>UPDATE</literal> unless it is certain that an object + is actually modified. Only when a transient object has been + associated with a new session using <literal>update()</literal>, + will Hibernate perform an extra SQL <literal>SELECT</literal> to + determine if an <literal>UPDATE</literal> is actually required. Use + of <literal>select-before-update</literal> will usually decrease + performance. It is useful to prevent a database update trigger being + called unnecessarily if you reattach a graph of detached instances + to a <literal>Session</literal>.</para> + </listitem> + + <listitem> + <para><literal>polymorphisms</literal> (defaults to + <literal>IMPLICIT</literal>): determines whether implicit or + explicit query polymorphisms is used. <emphasis>Implicit</emphasis> + polymorphisms means that instances of the class will be returned by + a query that names any superclass or implemented interface or class, + and that instances of any subclass of the class will be returned by + a query that names the class itself. <emphasis>Explicit</emphasis> + polymorphisms means that class instances will be returned only by + queries that explicitly name that class. Queries that name the class + will return only instances of subclasses mapped. For most purposes, + the default <literal>polymorphisms=IMPLICIT</literal> is + appropriate. Explicit polymorphisms is useful when two different + classes are mapped to the same table This allows a "lightweight" + class that contains a subset of the table columns.</para> + </listitem> + + <listitem> + <para><literal>persister</literal>: specifies a custom + <literal>ClassPersister</literal>. The <literal>persister</literal> + attribute lets you customize the persistence strategy used for the + class. You can, for example, specify your own subclass of + <literal>org.hibernate.persister.EntityPersister</literal>, or you + can even provide a completely new implementation of the interface + <literal>org.hibernate.persister.ClassPersister</literal> that + implements, for example, persistence via stored procedure calls, + serialization to flat files or LDAP. See + <literal>org.hibernate.test.CustomPersister</literal> for a simple + example of "persistence" to a <literal>Hashtable</literal>.</para> + </listitem> + + <listitem> + <para><literal>optimisticLock</literal> (defaults to + <literal>VERSION</literal>): determines the optimistic locking + strategy. If you enable <literal>dynamicUpdate</literal>, you will + have a choice of optimistic locking strategies:</para> + + <itemizedlist> + <listitem> + <para><literal>version</literal>: check the version/timestamp + columns</para> + </listitem> + + <listitem> + <para><literal>all</literal>: check all columns</para> + </listitem> + + <listitem> + <para><literal>dirty</literal>: check the changed columns, + allowing some concurrent updates</para> + </listitem> + + <listitem> + <para><literal>none</literal>: do not use optimistic + locking</para> + </listitem> + </itemizedlist> + + <para>It is <emphasis>strongly</emphasis> recommended that you use + version/timestamp columns for optimistic locking with Hibernate. + This strategy optimizes performance and correctly handles + modifications made to detached instances (i.e. when + <literal>Session.merge()</literal> is used).</para> + </listitem> + </itemizedlist> + + <tip> + <para>Be sure to import + <classname&gt;(a)javax.persistence.Entity&lt;/classname&gt; to mark a class as an + entity. It's a common mistake to import + <classname&gt;(a)org.hibernate.annotations.Entity&lt;/classname&gt; by + accident.</para> + </tip> + + <para>Some entities are not mutable. They cannot be updated or deleted + by the application. This allows Hibernate to make some minor performance + optimizations.. Use the <classname>@Immutable</classname> + annotation.</para> + + <para>You can also alter how Hibernate deals with lazy initialization + for this class. On <classname>@Proxy</classname>, use + <literal>lazy</literal>=false to disable lazy fetching (not + recommended). You can also specify an interface to use for lazy + initializing proxies (defaults to the class itself): use + <literal>proxyClass</literal> on <classname>@Proxy</classname>. + Hibernate will initially return proxies (Javassist or CGLIB) that + implement the named interface. The persistent object will load when a + method of the proxy is invoked. See "Initializing collections and + proxies" below.</para> + + <para><classname>@BatchSize</classname> specifies a "batch size" for + fetching instances of this class by identifier. Not yet loaded instances + are loaded batch-size at a time (default 1).</para> + + <para>You can specific an arbitrary SQL WHERE condition to be used when + retrieving objects of this class. Use <classname>@Where</classname> for + that.</para> + + <para>In the same vein, <classname>@Check</classname> lets you define an + SQL expression used to generate a multi-row <emphasis>check</emphasis> + constraint for automatic schema generation.</para> + + <para>There is no difference between a view and a base table for a + Hibernate mapping. This is transparent at the database level, although + some DBMS do not support views properly, especially with updates. + Sometimes you want to use a view, but you cannot create one in the + database (i.e. with a legacy schema). In this case, you can map an + immutable and read-only entity to a given SQL subselect expression using + <classname>@org.hibernate.annotations.Subselect</classname>:</para> + + <programlisting role="JAVA">@Entity +@Subselect("select item.name, max(bid.amount), count(*) " + + "from item " + + "join bid on bid.item_id = item.id " + + "group by item.name") +@Synchronize( {"item", "bid"} ) //tables impacted +public class Summary { + @Id + public String getId() { return id; } + ... +}</programlisting> + + <para>Declare the tables to synchronize this entity with, ensuring that + auto-flush happens correctly and that queries against the derived entity + do not return stale data. The <literal>&lt;subselect&gt;</literal> is + available both as an attribute and a nested mapping element.</para> + + <para>We will now explore the same options using the hbm.xml structure. + You can declare a persistent class using the <literal>class</literal> + element. For example:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="class1" /> + + <area coords="3" id="class2" /> + + <area coords="4" id="class3" /> + + <area coords="5" id="class4" /> + + <area coords="6" id="class5" /> + + <area coords="7" id="class6" /> + + <area coords="8" id="class7" /> + + <area coords="9" id="class8" /> + + <area coords="10" id="class9" /> + + <area coords="11" id="class10" /> + + <area coords="12" id="class11" /> + + <area coords="13" id="class12" /> + + <area coords="14" id="class13" /> + + <area coords="15" id="class14" /> + + <area coords="16" id="class15" /> + + <area coords="17" id="class16" /> + + <area coords="18" id="class17" /> + + <area coords="19" id="class18" /> + + <area coords="20" id="class19" /> + + <area coords="21" id="class20" /> + + <area coords="22" id="class21" /> + </areaspec> + + <programlisting>&lt;class + name="ClassName" + table="tableName" + discriminator-value="discriminator_value" + mutable="true|false" + schema="owner" + catalog="catalog" + proxy="ProxyInterface" + dynamic-update="true|false" + dynamic-insert="true|false" + select-before-update="true|false" + polymorphism="implicit|explicit" + where="arbitrary sql where condition" + persister="PersisterClass" + batch-size="N" + optimistic-lock="none|version|dirty|all" + lazy="true|false" + entity-name="EntityName" + check="arbitrary sql check condition" + rowid="rowid" + subselect="SQL expression" + abstract="true|false" + node="element-name" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="class1"> + <para><literal>name</literal> (optional): the fully qualified Java + class name of the persistent class or interface. If this attribute + is missing, it is assumed that the mapping is for a non-POJO + entity.</para> + </callout> + + <callout arearefs="class2"> + <para><literal>table</literal> (optional - defaults to the + unqualified class name): the name of its database table.</para> + </callout> + + <callout arearefs="class3"> + <para><literal>discriminator-value</literal> (optional - defaults + to the class name): a value that distinguishes individual + subclasses that is used for polymorphic behavior. Acceptable + values include <literal>null</literal> and <literal>not + null</literal>.</para> + </callout> + + <callout arearefs="class4"> + <para><literal>mutable</literal> (optional - defaults to + <literal>true</literal>): specifies that instances of the class + are (not) mutable.</para> + </callout> + + <callout arearefs="class5"> + <para><literal>schema</literal> (optional): overrides the schema + name specified by the root + <literal>&lt;hibernate-mapping&gt;</literal> element.</para> + </callout> + + <callout arearefs="class6"> + <para><literal>catalog</literal> (optional): overrides the catalog + name specified by the root + <literal>&lt;hibernate-mapping&gt;</literal> element.</para> + </callout> + + <callout arearefs="class7"> + <para><literal>proxy</literal> (optional): specifies an interface + to use for lazy initializing proxies. You can specify the name of + the class itself.</para> + </callout> + + <callout arearefs="class8"> + <para><literal>dynamic-update</literal> (optional - defaults to + <literal>false</literal>): specifies that + <literal>UPDATE</literal> SQL should be generated at runtime and + can contain only those columns whose values have changed.</para> + </callout> + + <callout arearefs="class9"> + <para><literal>dynamic-insert</literal> (optional - defaults to + <literal>false</literal>): specifies that + <literal>INSERT</literal> SQL should be generated at runtime and + contain only the columns whose values are not null.</para> + </callout> + + <callout arearefs="class10"> + <para><literal>select-before-update</literal> (optional - defaults + to <literal>false</literal>): specifies that Hibernate should + <emphasis>never</emphasis> perform an SQL + <literal>UPDATE</literal> unless it is certain that an object is + actually modified. Only when a transient object has been + associated with a new session using <literal>update()</literal>, + will Hibernate perform an extra SQL <literal>SELECT</literal> to + determine if an <literal>UPDATE</literal> is actually + required.</para> + </callout> + + <callout arearefs="class11"> + <para><literal>polymorphisms</literal> (optional - defaults to + <literal>implicit</literal>): determines whether implicit or + explicit query polymorphisms is used.</para> + </callout> + + <callout arearefs="class12"> + <para><literal>where</literal> (optional): specifies an arbitrary + SQL <literal>WHERE</literal> condition to be used when retrieving + objects of this class.</para> + </callout> + + <callout arearefs="class13"> + <para><literal>persister</literal> (optional): specifies a custom + <literal>ClassPersister</literal>.</para> + </callout> + + <callout arearefs="class14"> + <para><literal>batch-size</literal> (optional - defaults to + <literal>1</literal>): specifies a "batch size" for fetching + instances of this class by identifier.</para> + </callout> + + <callout arearefs="class15"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>version</literal>): determines the optimistic locking + strategy.</para> + </callout> + + <callout arearefs="class16"> + <para><literal>lazy</literal> (optional): lazy fetching can be + disabled by setting <literal>lazy="false"</literal>.</para> + </callout> + + <callout arearefs="class17"> + <para><literal>entity-name</literal> (optional - defaults to the + class name): Hibernate3 allows a class to be mapped multiple + times, potentially to different tables. It also allows entity + mappings that are represented by Maps or XML at the Java level. In + these cases, you should provide an explicit arbitrary name for the + entity. See <xref linkend="persistent-classes-dynamicmodels" /> + and <xref linkend="xml" /> for more information.</para> + </callout> + + <callout arearefs="class18"> + <para><literal>check</literal> (optional): an SQL expression used + to generate a multi-row <emphasis>check</emphasis> constraint for + automatic schema generation.</para> + </callout> + + <callout arearefs="class19"> + <para><literal>rowid</literal> (optional): Hibernate can use + ROWIDs on databases. On Oracle, for example, Hibernate can use the + <literal>rowid</literal> extra column for fast updates once this + option has been set to <literal>rowid</literal>. A ROWID is an + implementation detail and represents the physical location of a + stored tuple.</para> + </callout> + + <callout arearefs="class20"> + <para><literal>subselect</literal> (optional): maps an immutable + and read-only entity to a database subselect. This is useful if + you want to have a view instead of a base table. See below for + more information.</para> + </callout> + + <callout arearefs="class21"> + <para><literal>abstract</literal> (optional): is used to mark + abstract superclasses in <literal>&lt;union-subclass&gt;</literal> + hierarchies.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>It is acceptable for the named persistent class to be an + interface. You can declare implementing classes of that interface using + the <literal>&lt;subclass&gt;</literal> element. You can persist any + <emphasis>static</emphasis> inner class. Specify the class name using + the standard form i.e. <literal>e.g.Foo$Bar</literal>.</para> + + <para>Here is how to do a virtual view (subselect) in XML:</para> + + <programlisting role="XML">&lt;class name="Summary"&gt; + &lt;subselect&gt; + select item.name, max(bid.amount), count(*) + from item + join bid on bid.item_id = item.id + group by item.name + &lt;/subselect&gt; + &lt;synchronize table="item"/&gt; + &lt;synchronize table="bid"/&gt; + &lt;id name="name"/&gt; + ... +&lt;/class&gt;</programlisting> + + <para>The <literal>&lt;subselect&gt;</literal> is available both as an + attribute and a nested mapping element.</para> + </section> + + <section id="mapping-declaration-id" revision="4"> + <title>Identifiers</title> + + <para>Mapped classes <emphasis>must</emphasis> declare the primary key + column of the database table. Most classes will also have a + JavaBeans-style property holding the unique identifier of an + instance.</para> + + <para>Mark the identifier property with + <classname&gt;(a)Id&lt;/classname&gt;.&lt;/para&gt; + + <programlisting role="JAVA">@Entity +public class Person { + @Id Integer getId() { ... } + ... +}</programlisting> + + <para>In hbm.xml, use the <literal>&lt;id&gt;</literal> element which + defines the mapping from that property to the primary key column.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="id1" /> + + <area coords="3" id="id2" /> + + <area coords="4" id="id3" /> + + <area coords="5" id="id4" /> + + <area coords="6" id="id5" /> + </areaspec> + + <programlisting>&lt;id + name="propertyName" + type="typename" + column="column_name" + unsaved-value="null|any|none|undefined|id_value" + access="field|property|ClassName"&gt; + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + + &lt;generator class="generatorClass"/&gt; +&lt;/id&gt;</programlisting> + + <calloutlist> + <callout arearefs="id1"> + <para><literal>name</literal> (optional): the name of the + identifier property.</para> + </callout> + + <callout arearefs="id2"> + <para><literal>type</literal> (optional): a name that indicates + the Hibernate type.</para> + </callout> + + <callout arearefs="id3"> + <para><literal>column</literal> (optional - defaults to the + property name): the name of the primary key column.</para> + </callout> + + <callout arearefs="id4"> + <para><literal>unsaved-value</literal> (optional - defaults to a + "sensible" value): an identifier property value that indicates an + instance is newly instantiated (unsaved), distinguishing it from + detached instances that were saved or loaded in a previous + session.</para> + </callout> + + <callout arearefs="id5"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate should use + for accessing the property value.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>If the <literal>name</literal> attribute is missing, it is assumed + that the class has no identifier property.</para> + + <para>The <literal>unsaved-value</literal> attribute is almost never + needed in Hibernate3 and indeed has no corresponding element in + annotations.</para> + + <para>You can also declare the identifier as a composite identifier. + This allows access to legacy data with composite keys. Its use is + strongly discouraged for anything else.</para> + + <section> + <title>Composite identifier</title> + + <para>You can define a composite primary key through several + syntaxes:</para> + + <itemizedlist> + <listitem> + <para>use a component type to represent the identifier and map it + as a property in the entity: you then annotated the property as + <classname>@EmbeddedId</classname>. The component type has to be + <classname>Serializable</classname>.</para> + </listitem> + + <listitem> + <para>map multiple properties as <classname>@Id</classname> + properties: the identifier type is then the entity class itself + and needs to be <classname>Serializable</classname>. This approach + is unfortunately not standard and only supported by + Hibernate.</para> + </listitem> + + <listitem> + <para>map multiple properties as <classname>@Id</classname> + properties and declare an external class to be the identifier + type. This class, which needs to be + <classname>Serializable</classname>, is declared on the entity via + the <classname>@IdClass</classname> annotation. The identifier + type must contain the same properties as the identifier properties + of the entity: each property name must be the same, its type must + be the same as well if the entity property is of a basic type, its + type must be the type of the primary key of the associated entity + if the entity property is an association (either a + <classname>@OneToOne</classname> or a + <classname&gt;(a)ManyToOne&lt;/classname&gt;).&lt;/para&gt; + </listitem> + </itemizedlist> + + <para>As you can see the last case is far from obvious. It has been + inherited from the dark ages of EJB 2 for backward compatibilities and + we recommend you not to use it (for simplicity sake).</para> + + <para>Let's explore all three cases using examples.</para> + + <section> + <title>id as a property using a component type</title> + + <para>Here is a simple example of + <classname&gt;(a)EmbeddedId&lt;/classname&gt;.&lt;/para&gt; + + <programlisting language="JAVA" role="JAVA">@Entity +class User { + @EmbeddedId + @AttributeOverride(name="firstName", column=@Column(name="fld_firstname") + UserId id; + + Integer age; +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; +}</programlisting> + + <para>You can notice that the <classname>UserId</classname> class is + serializable. To override the column mapping, use + <classname&gt;(a)AttributeOverride&lt;/classname&gt;.&lt;/para&gt; + + <para>An embedded id can itself contains the primary key of an + associated entity.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +class Customer { + @EmbeddedId CustomerId id; + boolean preferredCustomer; + + @MapsId("userId") + @JoinColumns({ + @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"), + @JoinColumn(name="userlastname_fk", referencedColumnName="lastName") + }) + @OneToOne User user; +} + +@Embeddable +class CustomerId implements Serializable { + UserId userId; + String customerNumber; + + //implements equals and hashCode +} + +@Entity +class User { + @EmbeddedId UserId id; + Integer age; +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; + + //implements equals and hashCode +}</programlisting> + + <para>In the embedded id object, the association is represented as + the identifier of the associated entity. But you can link its value + to a regular association in the entity via the + <classname>@MapsId</classname> annotation. The + <classname>@MapsId</classname> value correspond to the property name + of the embedded id object containing the associated entity's + identifier. In the database, it means that the + <literal>Customer.user</literal> and the + <literal>CustomerId.userId</literal> properties share the same + underlying column (<literal>user_fk</literal> in this case).</para> + + <tip> + <para>The component type used as identifier must implement + <methodname>equals()</methodname> and + <methodname>hashCode()</methodname>.</para> + </tip> + + <para>In practice, your code only sets the + <literal>Customer.user</literal> property and the user id value is + copied by Hibernate into the <literal>CustomerId.userId</literal> + property.</para> + + <warning> + <para>The id value can be copied as late as flush time, don't rely + on it until after flush time.</para> + </warning> + + <para>While not supported in JPA, Hibernate lets you place your + association directly in the embedded id component (instead of having + to use the <classname>@MapsId</classname> annotation).</para> + + <programlisting language="JAVA" role="JAVA">@Entity +class Customer { + @EmbeddedId CustomerId id; + boolean preferredCustomer; +} + +@Embeddable +class CustomerId implements Serializable { + @OneToOne + @JoinColumns({ + @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"), + @JoinColumn(name="userlastname_fk", referencedColumnName="lastName") + }) + User user; + String customerNumber; + + //implements equals and hashCode +} + +@Entity +class User { + @EmbeddedId UserId id; + Integer age; +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; + + + //implements equals and hashCode +}</programlisting> + + <para>Let's now rewrite these examples using the hbm.xml + syntax.</para> + + <programlisting role="XML">&lt;composite-id + name="propertyName" + class="ClassName" + mapped="true|false" + access="field|property|ClassName"&gt; + node="element-name|." + + &lt;key-property name="propertyName" type="typename" column="column_name"/&gt; + &lt;key-many-to-one name="propertyName class="ClassName" column="column_name"/&gt; + ...... +&lt;/composite-id&gt;</programlisting> + + <para>First a simple example:</para> + + <programlisting role="XML">&lt;class name="User"&gt; + &lt;composite-id name="id" class="UserId"&gt; + &lt;key-property name="firstName" column="fld_firstname"/&gt; + &lt;key-property name="lastName"/&gt; + &lt;/composite-id&gt; +&lt;/class&gt;</programlisting> + + <para>Then an example showing how an association can be + mapped.</para> + + <programlisting role="XML">&lt;class name="Customer"&gt; + &lt;composite-id name="id" class="CustomerId"&gt; + &lt;key-property name="firstName" column="userfirstname_fk"/&gt; + &lt;key-property name="lastName" column="userfirstname_fk"/&gt; + &lt;key-property name="customerNumber"/&gt; + &lt;/composite-id&gt; + + &lt;property name="preferredCustomer"/&gt; + + &lt;many-to-one name="user"&gt; + &lt;column name="userfirstname_fk" updatable="false" insertable="false"/&gt; + &lt;column name="userlastname_fk" updatable="false" insertable="false"/&gt; + &lt;/many-to-one&gt; +&lt;/class&gt; + +&lt;class name="User"&gt; + &lt;composite-id name="id" class="UserId"&gt; + &lt;key-property name="firstName"/&gt; + &lt;key-property name="lastName"/&gt; + &lt;/composite-id&gt; + + &lt;property name="age"/&gt; +&lt;/class&gt;</programlisting> + + <para>Notice a few things in the previous example:</para> + + <itemizedlist> + <listitem> + <para>the order of the properties (and column) matters. It must + be the same between the association and the primary key of the + associated entity</para> + </listitem> + + <listitem> + <para>the many to one uses the same columns as the primary key + and thus must be marked as read only + (<literal>insertable</literal> and <literal>updatable</literal> + to false).</para> + </listitem> + + <listitem> + <para>unlike with <classname>@MapsId</classname>, the id value + of the associated entity is not transparently copied, check the + <literal>foreign</literal> id generator for more + information.</para> + </listitem> + </itemizedlist> + + <para>The last example shows how to map association directly in the + embedded id component.</para> + + <programlisting role="XML">&lt;class name="Customer"&gt; + &lt;composite-id name="id" class="CustomerId"&gt; + &lt;key-many-to-one name="user"&gt; + &lt;column name="userfirstname_fk"/&gt; + &lt;column name="userlastname_fk"/&gt; + &lt;/key-many-to-one&gt; + &lt;key-property name="customerNumber"/&gt; + &lt;/composite-id&gt; + + &lt;property name="preferredCustomer"/&gt; +&lt;/class&gt; + +&lt;class name="User"&gt; + &lt;composite-id name="id" class="UserId"&gt; + &lt;key-property name="firstName"/&gt; + &lt;key-property name="lastName"/&gt; + &lt;/composite-id&gt; + + &lt;property name="age"/&gt; +&lt;/class&gt;</programlisting> + + <para>This is the recommended approach to map composite identifier. + The following options should not be considered unless some + constraint are present.</para> + </section> + + <section> + <title>Multiple id properties without identifier type</title> + + <para>Another, arguably more natural, approach is to place + <classname>@Id</classname> on multiple properties of your entity. + This approach is only supported by Hibernate (not JPA compliant) but + does not require an extra embeddable component.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +class Customer implements Serializable { + @Id @OneToOne + @JoinColumns({ + @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"), + @JoinColumn(name="userlastname_fk", referencedColumnName="lastName") + }) + User user; + + @Id String customerNumber; + + boolean preferredCustomer; + + //implements equals and hashCode +} + +@Entity +class User { + @EmbeddedId UserId id; + Integer age; +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; + + //implements equals and hashCode +}</programlisting> + + <para>In this case <classname>Customer</classname> is its own + identifier representation: it must implement + <classname>Serializable</classname> and must implement + <methodname>equals()</methodname> and + <methodname>hashCode()</methodname>.</para> + + <para>In hbm.xml, the same mapping is:</para> + + <programlisting role="XML">&lt;class name="Customer"&gt; + &lt;composite-id&gt; + &lt;key-many-to-one name="user"&gt; + &lt;column name="userfirstname_fk"/&gt; + &lt;column name="userlastname_fk"/&gt; + &lt;/key-many-to-one&gt; + &lt;key-property name="customerNumber"/&gt; + &lt;/composite-id&gt; + + &lt;property name="preferredCustomer"/&gt; +&lt;/class&gt; + +&lt;class name="User"&gt; + &lt;composite-id name="id" class="UserId"&gt; + &lt;key-property name="firstName"/&gt; + &lt;key-property name="lastName"/&gt; + &lt;/composite-id&gt; + + &lt;property name="age"/&gt; +&lt;/class&gt;</programlisting> + </section> + + <section> + <title>Multiple id properties with with a dedicated identifier + type</title> + + <para><classname>@IdClass</classname> on an entity points to the + class (component) representing the identifier of the class. The + properties marked <classname>@Id</classname> on the entity must have + their corresponding property on the <classname>@IdClass</classname>. + The return type of search twin property must be either identical for + basic properties or must correspond to the identifier class of the + associated entity for an association.</para> + + <warning> + <para>This approach is inherited from the EJB 2 days and we + recommend against its use. But, after all it's your application + and Hibernate supports it.</para> + </warning> + + <programlisting language="JAVA" role="JAVA">@Entity +(a)IdClass(CustomerId.class) +class Customer implements Serializable { + @Id @OneToOne + @JoinColumns({ + @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"), + @JoinColumn(name="userlastname_fk", referencedColumnName="lastName") + }) + User user; + + @Id String customerNumber; + + boolean preferredCustomer; +} + +class CustomerId implements Serializable { + UserId user; + String customerNumber; + + //implements equals and hashCode +} + +@Entity +class User { + @EmbeddedId UserId id; + Integer age; + + //implements equals and hashCode +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; + + //implements equals and hashCode +}</programlisting> + + <para><classname>Customer</classname> and + <classname>CustomerId</classname> do have the same properties + <literal>customerNumber</literal> as well as + <literal>user</literal>. <classname>CustomerId</classname> must be + <classname>Serializable</classname> and implement + <classname>equals()</classname> and + <classname>hashCode()</classname>.</para> + + <para>While not JPA standard, Hibernate let's you declare the + vanilla associated property in the + <classname&gt;(a)IdClass&lt;/classname&gt;.&lt;/para&gt; + + <programlisting language="JAVA" role="JAVA">@Entity +(a)IdClass(CustomerId.class) +class Customer implements Serializable { + @Id @OneToOne + @JoinColumns({ + @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"), + @JoinColumn(name="userlastname_fk", referencedColumnName="lastName") + }) + User user; + + @Id String customerNumber; + + boolean preferredCustomer; +} + +class CustomerId implements Serializable { + @OneToOne User user; + String customerNumber; + + //implements equals and hashCode +} + +@Entity +class User { + @EmbeddedId UserId id; + Integer age; + + //implements equals and hashCode +} + +@Embeddable +class UserId implements Serializable { + String firstName; + String lastName; +}</programlisting> + + <para>This feature is of limited interest though as you are likely + to have chosen the <classname>@IdClass</classname> approach to stay + JPA compliant or you have a quite twisted mind.</para> + + <para>Here are the equivalent on hbm.xml files:</para> + + <programlisting role="XML">&lt;class name="Customer"&gt; + &lt;composite-id class="CustomerId" mapped="true"&gt; + &lt;key-many-to-one name="user"&gt; + &lt;column name="userfirstname_fk"/&gt; + &lt;column name="userlastname_fk"/&gt; + &lt;/key-many-to-one&gt; + &lt;key-property name="customerNumber"/&gt; + &lt;/composite-id&gt; + + &lt;property name="preferredCustomer"/&gt; +&lt;/class&gt; + +&lt;class name="User"&gt; + &lt;composite-id name="id" class="UserId"&gt; + &lt;key-property name="firstName"/&gt; + &lt;key-property name="lastName"/&gt; + &lt;/composite-id&gt; + + &lt;property name="age"/&gt; +&lt;/class&gt;</programlisting> + </section> + </section> + + <section id="mapping-declaration-id-generator" revision="2"> + <title>Identifier generator</title> + + <para>Hibernate can generate and populate identifier values for you + automatically. This is the recommended approach over "business" or + "natural" id (especially composite ids).</para> + + <para>Hibernate offers various generation strategies, let's explore + the most common ones first that happens to be standardized by + JPA:</para> + + <itemizedlist> + <listitem> + <para>IDENTITY: supports identity columns in DB2, MySQL, MS SQL + Server, Sybase and HypersonicSQL. The returned identifier is of + type <literal>long</literal>, <literal>short</literal> or + <literal>int</literal>.</para> + </listitem> + + <listitem> + <para>SEQUENCE (called <literal>seqhilo</literal> in Hibernate): + uses a hi/lo algorithm to efficiently generate identifiers of type + <literal>long</literal>, <literal>short</literal> or + <literal>int</literal>, given a named database sequence.</para> + </listitem> + + <listitem> + <para>TABLE (called + <classname>MultipleHiLoPerTableGenerator</classname> in Hibernate) + : uses a hi/lo algorithm to efficiently generate identifiers of + type <literal>long</literal>, <literal>short</literal> or + <literal>int</literal>, given a table and column as a source of hi + values. The hi/lo algorithm generates identifiers that are unique + only for a particular database.</para> + </listitem> + + <listitem> + <para>AUTO: selects <literal>IDENTITY</literal>, + <literal>SEQUENCE</literal> or <literal>TABLE</literal> depending + upon the capabilities of the underlying database.</para> + </listitem> + </itemizedlist> + + <important> + <para>We recommend all new projects to use the new enhanced + identifier generators. They are deactivated by default for entities + using annotations but can be activated using + <code>hibernate.id.new_generator_mappings=true</code>. These new + generators are more efficient and closer to the JPA 2 specification + semantic.</para> + + <para>However they are not backward compatible with existing + Hibernate based application (if a sequence or a table is used for id + generation). See XXXXXXX <xref linkend="ann-setup-properties" /> for + more information on how to activate them.</para> + </important> + + <para>To mark an id property as generated, use the + <classname>@GeneratedValue</classname> annotation. You can specify the + strategy used (default to <literal>AUTO</literal>) by setting + <literal>strategy</literal>.</para> + + <programlisting role="JAVA">@Entity +public class Customer { + @Id @GeneratedValue + Integer getId() { ... }; +} + +@Entity +public class Invoice { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) + Integer getId() { ... }; +}</programlisting> + + <para><literal>SEQUENCE</literal> and <literal>TABLE</literal> require + additional configurations that you can set using + <classname>@SequenceGenerator</classname> and + <classname>@TableGenerator</classname>:</para> + + <itemizedlist> + <listitem> + <para><literal>name</literal>: name of the generator</para> + </listitem> + + <listitem> + <para><literal>table</literal> / <literal>sequenceName</literal>: + name of the table or the sequence (defaulting respectively to + <literal>hibernate_sequences</literal> and + <literal>hibernate_sequence</literal>)</para> + </listitem> + + <listitem> + <para><literal>catalog</literal> / + <literal>schema</literal>:</para> + </listitem> + + <listitem> + <para><literal>initialValue</literal>: the value from which the id + is to start generating</para> + </listitem> + + <listitem> + <para><literal>allocationSize</literal>: the amount to increment + by when allocating id numbers from the generator</para> + </listitem> + </itemizedlist> + + <para>In addition, the <classname>TABLE</classname> strategy also let + you customize:</para> + + <itemizedlist> + <listitem> + <para><literal>pkColumnName</literal>: the column name containing + the entity identifier</para> + </listitem> + + <listitem> + <para><literal>valueColumnName</literal>: the column name + containing the identifier value</para> + </listitem> + + <listitem> + <para><literal>pkColumnValue</literal>: the entity + identifier</para> + </listitem> + + <listitem> + <para><literal>uniqueConstraints</literal>: any potential column + constraint on the table containing the ids</para> + </listitem> + </itemizedlist> + + <para>To link a table or sequence generator definition with an actual + generated property, use the same name in both the definition + <literal>name</literal> and the generator value + <literal>generator</literal> as shown below.</para> + + <programlisting language="JAVA" role="JAVA">@Id +@GeneratedValue( + strategy=GenerationType.SEQUENCE, + generator="SEQ_GEN") +(a)javax.persistence.SequenceGenerator( + name="SEQ_GEN", + sequenceName="my_sequence", + allocationSize=20 +) +public Integer getId() { ... } </programlisting> + + <para>The scope of a generator definition 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 in JPA's XML deployment descriptors (see XXXXXX + <xref linkend="xml-overriding" />):</para> + + <programlisting language="JAVA" role="JAVA">&lt;table-generator name="EMP_GEN" + table="GENERATOR_TABLE" + pk-column-name="key" + value-column-name="hi" + pk-column-value="EMP" + allocation-size="20"/&gt; + +//and the annotation equivalent + +(a)javax.persistence.TableGenerator( + name="EMP_GEN", + table="GENERATOR_TABLE", + pkColumnName = "key", + valueColumnName = "hi" + pkColumnValue="EMP", + allocationSize=20 +) + +&lt;sequence-generator name="SEQ_GEN" + sequence-name="my_sequence" + allocation-size="20"/&gt; + +//and the annotation equivalent + +(a)javax.persistence.SequenceGenerator( + name="SEQ_GEN", + sequenceName="my_sequence", + allocationSize=20 +) + </programlisting> + + <para>If a JPA XML descriptor (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.</para> + + <note> + <para>Package level definition is not supported by the JPA + specification. However, you can use the + <literal>@GenericGenerator</literal> at the package level (see <xref + linkend="entity-hibspec-identifier" />).</para> + </note> + + <para>These are the four standard JPA generators. Hibernate goes + beyond that and provide additional generators or additional options as + we will see below. You can also write your own custom identifier + generator by implementing + <classname>org.hibernate.id.IdentifierGenerator</classname>.</para> + + <para>To define a custom generator, use the + <classname>@GenericGenerator</classname> annotation (and its plural + counter part <classname>@GenericGenerators</classname>) that describes + the class of the identifier generator or its short cut name (as + described below) and a list of key/value parameters. When using + <classname>@GenericGenerator</classname> and assigning it via + <classname&gt;(a)GeneratedValue.generator&lt;/classname&gt;, the + <classname&gt;(a)GeneratedValue.strategy&lt;/classname&gt; is ignored: leave it + blank.</para> + + <programlisting language="JAVA" role="JAVA">@Id @GeneratedValue(generator="system-uuid") +@GenericGenerator(name="system-uuid", strategy = "uuid") +public String getId() { + +@Id @GeneratedValue(generator="trigger-generated") +@GenericGenerator( + name="trigger-generated", + strategy = "select", + parameters = @Parameter(name="key", value = "socialSecurityNumber") +) +public String getId() {</programlisting> + + <para>The hbm.xml approach uses the optional + <literal>&lt;generator&gt;</literal> child element inside + <literal>&lt;id&gt;</literal>. If any parameters are required to + configure or initialize the generator instance, they are passed using + the <literal>&lt;param&gt;</literal> element.</para> + + <programlisting role="XML">&lt;id name="id" type="long" column="cat_id"&gt; + &lt;generator class="org.hibernate.id.TableHiLoGenerator"&gt; + &lt;param name="table"&gt;uid_table&lt;/param&gt; + &lt;param name="column"&gt;next_hi_value_column&lt;/param&gt; + &lt;/generator&gt; +&lt;/id&gt;</programlisting> + + <section> + <title>Various additional generators</title> + + <para>All generators implement the interface + <literal>org.hibernate.id.IdentifierGenerator</literal>. This is a + very simple interface. Some applications can choose to provide their + own specialized implementations, however, Hibernate provides a range + of built-in implementations. The shortcut names for the built-in + generators are as follows: <variablelist> + <varlistentry> + <term><literal>increment</literal></term> + + <listitem> + <para>generates identifiers of type <literal>long</literal>, + <literal>short</literal> or <literal>int</literal> that are + unique only when no other process is inserting data into the + same table. <emphasis>Do not use in a + cluster.</emphasis></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>identity</literal></term> + + <listitem> + <para>supports identity columns in DB2, MySQL, MS SQL + Server, Sybase and HypersonicSQL. The returned identifier is + of type <literal>long</literal>, <literal>short</literal> or + <literal>int</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sequence</literal></term> + + <listitem> + <para>uses a sequence in DB2, PostgreSQL, Oracle, SAP DB, + McKoi or a generator in Interbase. The returned identifier + is of type <literal>long</literal>, <literal>short</literal> + or <literal>int</literal></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>hilo</literal></term> + + <listitem> + <para id="mapping-declaration-id-hilodescription" + revision="1">uses a hi/lo algorithm to efficiently generate + identifiers of type <literal>long</literal>, + <literal>short</literal> or <literal>int</literal>, given a + table and column (by default + <literal>hibernate_unique_key</literal> and + <literal>next_hi</literal> respectively) as a source of hi + values. The hi/lo algorithm generates identifiers that are + unique only for a particular database.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>seqhilo</literal></term> + + <listitem> + <para>uses a hi/lo algorithm to efficiently generate + identifiers of type <literal>long</literal>, + <literal>short</literal> or <literal>int</literal>, given a + named database sequence.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>uuid</literal></term> + + <listitem> + <para>Generates a 128-bit UUID based on a custom algorithm. + The value generated is represented as a string of 32 + hexidecimal digits. Users can also configure it to use a + separator (config parameter "separator") which separates the + hexidecimal digits into 8{sep}8{sep}4{sep}8{sep}4. Note + specifically that this is different than the IETF RFC 4122 + representation of 8-4-4-4-12. If you need RFC 4122 compliant + UUIDs, consider using "uuid2" generator discussed + below.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>uuid2</literal></term> + + <listitem> + <para>Generates a IETF RFC 4122 compliant (variant 2) + 128-bit UUID. The exact "version" (the RFC term) generated + depends on the pluggable "generation strategy" used (see + below). Capable of generating values as + <classname>java.util.UUID</classname>, + <classname>java.lang.String</classname> or as a byte array + of length 16 (<literal>byte[16]</literal>). The "generation + strategy" is defined by the interface + <interfacename>org.hibernate.id.UUIDGenerationStrategy</interfacename>. + The generator defines 2 configuration parameters for + defining which generation strategy to use: <variablelist> + <varlistentry> + <term><literal>uuid_gen_strategy_class</literal></term> + + <listitem> + <para>Names the UUIDGenerationStrategy class to + use</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>uuid_gen_strategy</literal></term> + + <listitem> + <para>Names the UUIDGenerationStrategy instance to + use</para> + </listitem> + </varlistentry> + </variablelist></para> + + <para>Out of the box, comes with the following strategies: + <itemizedlist> + <listitem> + <para><classname>org.hibernate.id.uuid.StandardRandomStrategy</classname> + (the default) - generates "version 3" (aka, "random") + UUID values via the + <methodname>randomUUID</methodname> method of + <classname>java.util.UUID</classname></para> + </listitem> + + <listitem> + <para><classname>org.hibernate.id.uuid.CustomVersionOneStrategy</classname> + - generates "version 1" UUID values, using IP address + since mac address not available. If you need mac + address to be used, consider leveraging one of the + existing third party UUID generators which sniff out + mac address and integrating it via the + <interfacename>org.hibernate.id.UUIDGenerationStrategy</interfacename> + contract. Two such libraries known at time of this + writing include <ulink + url="http://johannburkard.de/software/uuid/">http://johannburkard.de/software/uuid/</ulink> + and <ulink + url="http://commons.apache.org/sandbox/id/uuid.html">http://... + </listitem> + </itemizedlist></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>guid</literal></term> + + <listitem> + <para>uses a database-generated GUID string on MS SQL Server + and MySQL.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>native</literal></term> + + <listitem> + <para>selects <literal>identity</literal>, + <literal>sequence</literal> or <literal>hilo</literal> + depending upon the capabilities of the underlying + database.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>assigned</literal></term> + + <listitem> + <para>lets the application assign an identifier to the + object before <literal>save()</literal> is called. This is + the default strategy if no + <literal>&lt;generator&gt;</literal> element is + specified.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>select</literal></term> + + <listitem> + <para>retrieves a primary key, assigned by a database + trigger, by selecting the row by some unique key and + retrieving the primary key value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>foreign</literal></term> + + <listitem> + <para>uses the identifier of another associated object. It + is usually used in conjunction with a + <literal>&lt;one-to-one&gt;</literal> primary key + association.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sequence-identity</literal></term> + + <listitem> + <para>a specialized sequence generation strategy that + utilizes a database sequence for the actual value + generation, but combines this with JDBC3 getGeneratedKeys to + return the generated identifier value as part of the insert + statement execution. This strategy is only supported on + Oracle 10g drivers targeted for JDK 1.4. Comments on these + insert statements are disabled due to a bug in the Oracle + drivers.</para> + </listitem> + </varlistentry> + </variablelist></para> + </section> + + <section id="mapping-declaration-id-hilo" revision="1"> + <title>Hi/lo algorithm</title> + + <para>The <literal>hilo</literal> and <literal>seqhilo</literal> + generators provide two alternate implementations of the hi/lo + algorithm. The first implementation requires a "special" database + table to hold the next available "hi" value. Where supported, the + second uses an Oracle-style sequence.</para> + + <programlisting role="XML">&lt;id name="id" type="long" column="cat_id"&gt; + &lt;generator class="hilo"&gt; + &lt;param name="table"&gt;hi_value&lt;/param&gt; + &lt;param name="column"&gt;next_value&lt;/param&gt; + &lt;param name="max_lo"&gt;100&lt;/param&gt; + &lt;/generator&gt; +&lt;/id&gt;</programlisting> + + <programlisting role="XML">&lt;id name="id" type="long" column="cat_id"&gt; + &lt;generator class="seqhilo"&gt; + &lt;param name="sequence"&gt;hi_value&lt;/param&gt; + &lt;param name="max_lo"&gt;100&lt;/param&gt; + &lt;/generator&gt; +&lt;/id&gt;</programlisting> + + <para>Unfortunately, you cannot use <literal>hilo</literal> when + supplying your own <literal>Connection</literal> to Hibernate. When + Hibernate uses an application server datasource to obtain + connections enlisted with JTA, you must configure the + <literal>hibernate.transaction.manager_lookup_class</literal>.</para> + </section> + + <section id="mapping-declaration-id-uuid"> + <title>UUID algorithm</title> + + <para>The UUID contains: IP address, startup time of the JVM that is + accurate to a quarter second, system time and a counter value that + is unique within the JVM. It is not possible to obtain a MAC address + or memory address from Java code, so this is the best option without + using JNI.</para> + </section> + + <section id="mapping-declaration-id-sequences"> + <title>Identity columns and sequences</title> + + <para>For databases that support identity columns (DB2, MySQL, + Sybase, MS SQL), you can use <literal>identity</literal> key + generation. For databases that support sequences (DB2, Oracle, + PostgreSQL, Interbase, McKoi, SAP DB) you can use + <literal>sequence</literal> style key generation. Both of these + strategies require two SQL queries to insert a new object. For + example:</para> + + <programlisting role="XML">&lt;id name="id" type="long" column="person_id"&gt; + &lt;generator class="sequence"&gt; + &lt;param name="sequence"&gt;person_id_sequence&lt;/param&gt; + &lt;/generator&gt; +&lt;/id&gt;</programlisting> + + <programlisting role="XML">&lt;id name="id" type="long" column="person_id" unsaved-value="0"&gt; + &lt;generator class="identity"/&gt; +&lt;/id&gt;</programlisting> + + <para>For cross-platform development, the <literal>native</literal> + strategy will, depending on the capabilities of the underlying + database, choose from the <literal>identity</literal>, + <literal>sequence</literal> and <literal>hilo</literal> + strategies.</para> + </section> + + <section id="mapping-declaration-id-assigned"> + <title>Assigned identifiers</title> + + <para>If you want the application to assign identifiers, as opposed + to having Hibernate generate them, you can use the + <literal>assigned</literal> generator. This special generator uses + the identifier value already assigned to the object's identifier + property. The generator is used when the primary key is a natural + key instead of a surrogate key. This is the default behavior if you + do not specify <classname>@GeneratedValue</classname> nor + <literal>&lt;generator&gt;</literal> elements.</para> + + <para>The <literal>assigned</literal> generator makes Hibernate use + <literal>unsaved-value="undefined"</literal>. This forces Hibernate + to go to the database to determine if an instance is transient or + detached, unless there is a version or timestamp property, or you + define <literal>Interceptor.isUnsaved()</literal>.</para> + </section> + + <section id="mapping-declaration-id-select"> + <title>Primary keys assigned by triggers</title> + + <para>Hibernate does not generate DDL with triggers. It is for + legacy schemas only.</para> + + <programlisting role="XML">&lt;id name="id" type="long" column="person_id"&gt; + &lt;generator class="select"&gt; + &lt;param name="key"&gt;socialSecurityNumber&lt;/param&gt; + &lt;/generator&gt; +&lt;/id&gt;</programlisting> + + <para>In the above example, there is a unique valued property named + <literal>socialSecurityNumber</literal>. It is defined by the class, + as a natural key and a surrogate key named + <literal>person_id</literal>, whose value is generated by a + trigger.</para> + </section> + + <section> + <title>Identity copy (foreign generator)</title> + + <para>Finally, you can ask Hibernate to copy the identifier from + another associated entity. In the Hibernate jargon, it is known as a + foreign generator but the JPA mapping reads better and is + encouraged.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +class MedicalHistory implements Serializable { + @Id @OneToOne + @JoinColumn(name = "person_id") + Person patient; +} + +@Entity +public class Person implements Serializable { + @Id @GeneratedValue Integer id; +}</programlisting> + + <para>Or alternatively</para> + + <programlisting language="JAVA" role="JAVA">@Entity +class MedicalHistory implements Serializable { + @Id Integer id; + + @MapsId @OneToOne + @JoinColumn(name = "patient_id") + Person patient; +} + +@Entity +class Person { + @Id @GeneratedValue Integer id; +}</programlisting> + + <para>In hbm.xml use the following approach:</para> + + <programlisting role="XML">&lt;class name="MedicalHistory"&gt; + &lt;id name="id"&gt; + &lt;generator class="foreign"&gt; + &lt;param name="property"&gt;patient&lt;/param&gt; + &lt;/generator&gt; + &lt;/id&gt; + &lt;one-to-one name="patient" class="Person" constrained="true"/&gt; +&lt;/class&gt;</programlisting> + </section> + </section> + + <section id="mapping-declaration-id-enhanced"> + <title>Enhanced identifier generators</title> + + <para>Starting with release 3.2.3, there are 2 new generators which + represent a re-thinking of 2 different aspects of identifier + generation. The first aspect is database portability; the second is + optimization Optimization means that you do not have to query the + database for every request for a new identifier value. These two new + generators are intended to take the place of some of the named + generators described above, starting in 3.3.x. However, they are + included in the current releases and can be referenced by FQN.</para> + + <para>The first of these new generators is + <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal> + which is intended, firstly, as a replacement for the + <literal>sequence</literal> generator and, secondly, as a better + portability generator than <literal>native</literal>. This is because + <literal>native</literal> generally chooses between + <literal>identity</literal> and <literal>sequence</literal> which have + largely different semantics that can cause subtle issues in + applications eyeing portability. + <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal>, + however, achieves portability in a different manner. It chooses + between a table or a sequence in the database to store its + incrementing values, depending on the capabilities of the dialect + being used. The difference between this and <literal>native</literal> + is that table-based and sequence-based storage have the same exact + semantic. In fact, sequences are exactly what Hibernate tries to + emulate with its table-based generators. This generator has a number + of configuration parameters: <itemizedlist spacing="compact"> + <listitem> + <para><literal>sequence_name</literal> (optional, defaults to + <literal>hibernate_sequence</literal>): the name of the sequence + or table to be used.</para> + </listitem> + + <listitem> + <para><literal>initial_value</literal> (optional, defaults to + <literal>1</literal>): the initial value to be retrieved from + the sequence/table. In sequence creation terms, this is + analogous to the clause typically named "STARTS WITH".</para> + </listitem> + + <listitem> + <para><literal>increment_size</literal> (optional - defaults to + <literal>1</literal>): the value by which subsequent calls to + the sequence/table should differ. In sequence creation terms, + this is analogous to the clause typically named "INCREMENT + BY".</para> + </listitem> + + <listitem> + <para><literal>force_table_use</literal> (optional - defaults to + <literal>false</literal>): should we force the use of a table as + the backing structure even though the dialect might support + sequence?</para> + </listitem> + + <listitem> + <para><literal>value_column</literal> (optional - defaults to + <literal>next_val</literal>): only relevant for table + structures, it is the name of the column on the table which is + used to hold the value.</para> + </listitem> + + <listitem> + <para><literal>optimizer</literal> (optional - defaults to + <literal>none</literal>): See <xref + linkend="mapping-declaration-id-enhanced-optimizers" /></para> + </listitem> + </itemizedlist></para> + + <para>The second of these new generators is + <literal>org.hibernate.id.enhanced.TableGenerator</literal>, which is + intended, firstly, as a replacement for the <literal>table</literal> + generator, even though it actually functions much more like + <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal>, and + secondly, as a re-implementation of + <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal> that + utilizes the notion of pluggable optimizers. Essentially this + generator defines a table capable of holding a number of different + increment values simultaneously by using multiple distinctly keyed + rows. This generator has a number of configuration parameters: + <itemizedlist spacing="compact"> + <listitem> + <para><literal>table_name</literal> (optional - defaults to + <literal>hibernate_sequences</literal>): the name of the table + to be used.</para> + </listitem> + + <listitem> + <para><literal>value_column_name</literal> (optional - defaults + to <literal>next_val</literal>): the name of the column on the + table that is used to hold the value.</para> + </listitem> + + <listitem> + <para><literal>segment_column_name</literal> (optional - + defaults to <literal>sequence_name</literal>): the name of the + column on the table that is used to hold the "segment key". This + is the value which identifies which increment value to + use.</para> + </listitem> + + <listitem> + <para><literal>segment_value</literal> (optional - defaults to + <literal>default</literal>): The "segment key" value for the + segment from which we want to pull increment values for this + generator.</para> + </listitem> + + <listitem> + <para><literal>segment_value_length</literal> (optional - + defaults to <literal>255</literal>): Used for schema generation; + the column size to create this segment key column.</para> + </listitem> + + <listitem> + <para><literal>initial_value</literal> (optional - defaults to + <literal>1</literal>): The initial value to be retrieved from + the table.</para> + </listitem> + + <listitem> + <para><literal>increment_size</literal> (optional - defaults to + <literal>1</literal>): The value by which subsequent calls to + the table should differ.</para> + </listitem> + + <listitem> + <para><literal>optimizer</literal> (optional - defaults to + <literal></literal>): See <xref + linkend="mapping-declaration-id-enhanced-optimizers" /></para> + </listitem> + </itemizedlist></para> + + <section id="mapping-declaration-id-enhanced-optimizers"> + <title>Identifier generator optimization</title> + + <para>For identifier generators that store values in the database, + it is inefficient for them to hit the database on each and every + call to generate a new identifier value. Instead, you can group a + bunch of them in memory and only hit the database when you have + exhausted your in-memory value group. This is the role of the + pluggable optimizers. Currently only the two enhanced generators + (<xref linkend="mapping-declaration-id-enhanced" /> support this + operation. <itemizedlist spacing="compact"> + <listitem> + <para><literal>none</literal> (generally this is the default + if no optimizer was specified): this will not perform any + optimizations and hit the database for each and every + request.</para> + </listitem> + + <listitem> + <para><literal>hilo</literal>: applies a hi/lo algorithm + around the database retrieved values. The values from the + database for this optimizer are expected to be sequential. The + values retrieved from the database structure for this + optimizer indicates the "group number". The + <literal>increment_size</literal> is multiplied by that value + in memory to define a group "hi value".</para> + </listitem> + + <listitem> + <para><literal>pooled</literal>: as with the case of + <literal>hilo</literal>, this optimizer attempts to minimize + the number of hits to the database. Here, however, we simply + store the starting value for the "next group" into the + database structure rather than a sequential value in + combination with an in-memory grouping algorithm. Here, + <literal>increment_size</literal> refers to the values coming + from the database.</para> + </listitem> + </itemizedlist></para> + </section> + </section> + + <section> + <title>Partial identifier generation</title> + + <para>Hibernate supports the automatic generation of some of the + identifier properties. Simply use the + <classname>@GeneratedValue</classname> annotation on one or several id + properties.</para> + + <warning> + <para>The Hibernate team has always felt such a construct as + fundamentally wrong. Try hard to fix your data model before using + this feature.</para> + </warning> + + <programlisting language="JAVA" role="JAVA">@Entity +public class CustomerInventory implements Serializable { + @Id + @TableGenerator(name = "inventory", + table = "U_SEQUENCES", + pkColumnName = "S_ID", + valueColumnName = "S_NEXTNUM", + pkColumnValue = "inventory", + allocationSize = 1000) + @GeneratedValue(strategy = GenerationType.TABLE, generator = "inventory") + Integer id; + + + @Id @ManyToOne(cascade = CascadeType.MERGE) + Customer customer; +} + +@Entity +public class Customer implements Serializable { + @Id + private int id; +}</programlisting> + + <para>You can also generate properties inside an + <classname>@EmbeddedId</classname> class.</para> + </section> + </section> + + <section> + <title>Inheritance strategy</title> + + <para>Java is a language supporting polymorphism: a class can inherit + from another. Several strategies are possible to persist a class + hierarchy:</para> + + <itemizedlist> + <listitem> + <para>Single table per class hierarchy strategy: a single table + hosts all the instances of a class hierarchy</para> + </listitem> + + <listitem> + <para>Joined subclass strategy: one table per class and subclass is + present and each table persist the properties specific to a given + subclass. The state of the entity is then stored in its + corresponding class table and all its superclasses</para> + </listitem> + + <listitem> + <para>Table per class strategy: one table per concrete class and + subclass is present and each table persist the properties of the + class and its superclasses. The state of the entity is then stored + entirely in the dedicated table for its class.</para> + </listitem> + </itemizedlist> + + <section id="mapping-declaration-subclass" revision="4"> + <title>Single table per class hierarchy strategy</title> + + <para>With this approach the properties of all the subclasses in a + given mapped class hierarchy are stored in a single table.</para> + + <para>Each subclass declares its own persistent properties and + subclasses. Version and id properties are assumed to be inherited from + the root class. Each subclass in a hierarchy must define a unique + discriminator value. If this is not specified, the fully qualified + Java class name is used.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +(a)Inheritance(strategy=InheritanceType.SINGLE_TABLE) +@DiscriminatorColumn( + name="planetype", + discriminatorType=DiscriminatorType.STRING +) +@DiscriminatorValue("Plane") +public class Plane { ... } + +@Entity +@DiscriminatorValue("A320") +public class A320 extends Plane { ... } </programlisting> + + <para>In hbm.xml, for the table-per-class-hierarchy mapping strategy, + the <literal>&lt;subclass&gt;</literal> declaration is used. For + example:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="subclass1" /> + + <area coords="3" id="subclass2" /> + + <area coords="4" id="subclass3" /> + + <area coords="5" id="subclass4" /> + </areaspec> + + <programlisting>&lt;subclass + name="ClassName" + discriminator-value="discriminator_value" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + entity-name="EntityName" + node="element-name" + extends="SuperclassName"&gt; + + &lt;property .... /&gt; + ..... +&lt;/subclass&gt;</programlisting> + + <calloutlist> + <callout arearefs="subclass1"> + <para><literal>name</literal>: the fully qualified class name of + the subclass.</para> + </callout> + + <callout arearefs="subclass2"> + <para><literal>discriminator-value</literal> (optional - + defaults to the class name): a value that distinguishes + individual subclasses.</para> + </callout> + + <callout arearefs="subclass3"> + <para><literal>proxy</literal> (optional): specifies a class or + interface used for lazy initializing proxies.</para> + </callout> + + <callout arearefs="subclass4"> + <para><literal>lazy</literal> (optional - defaults to + <literal>true</literal>): setting + <literal>lazy="false"</literal> disables the use of lazy + fetching.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>For information about inheritance mappings see <xref + linkend="inheritance" />.</para> + + <section id="mapping-declaration-discriminator" revision="3"> + <title>Discriminator</title> + + <para>Discriminators are required for polymorphic persistence using + the table-per-class-hierarchy mapping strategy. It declares a + discriminator column of the table. The discriminator column contains + marker values that tell the persistence layer what subclass to + instantiate for a particular row. A restricted set of types can be + used: <literal>string</literal>, <literal>character</literal>, + <literal>integer</literal>, <literal>byte</literal>, + <literal>short</literal>, <literal>boolean</literal>, + <literal>yes_no</literal>, <literal>true_false</literal>.</para> + + <para>Use the <classname>@DiscriminatorColumn</classname> to define + the discriminator column as well as the discriminator type. + Alternatively, you can also use + <classname>@DiscriminatorFormula</classname> to express in SQL what + would be in a virtual discriminator column. This is particularly + handy when the discriminator value can be extracted from one or more + columns of the table. Both + <classname>@DiscriminatorColumn</classname> and + <classname>@DiscriminatorFormula</classname> are to be set on the + root entity (once per persisted hierarchy).</para> + + <para>Finally, use <classname>@DiscriminatorValue</classname> on + each class of the hierarchy to specify the value stored in the + discriminator column for a given entity. If you do not set + <classname>@DiscriminatorValue</classname> on a class, the fully + qualified class name is used.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +(a)Inheritance(strategy=InheritanceType.SINGLE_TABLE) +@DiscriminatorColumn( + name="planetype", + discriminatorType=DiscriminatorType.STRING +) +@DiscriminatorValue("Plane") +public class Plane { ... } + +@Entity +@DiscriminatorValue("A320") +public class A320 extends Plane { ... } </programlisting> + + <para>In hbm.xml, the <literal>&lt;discriminator&gt;</literal> + element is used to define the discriminator column or + formula:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="discriminator1" /> + + <area coords="3" id="discriminator2" /> + + <area coords="4" id="discriminator3" /> + + <area coords="5" id="discriminator4" /> + + <area coords="6" id="discriminator5" /> + </areaspec> + + <programlisting>&lt;discriminator + column="discriminator_column" + type="discriminator_type" + force="true|false" + insert="true|false" + formula="arbitrary sql expression" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="discriminator1"> + <para><literal>column</literal> (optional - defaults to + <literal>class</literal>): the name of the discriminator + column.</para> + </callout> + + <callout arearefs="discriminator2"> + <para><literal>type</literal> (optional - defaults to + <literal>string</literal>): a name that indicates the + Hibernate type</para> + </callout> + + <callout arearefs="discriminator3"> + <para><literal>force</literal> (optional - defaults to + <literal>false</literal>): "forces" Hibernate to specify the + allowed discriminator values, even when retrieving all + instances of the root class.</para> + </callout> + + <callout arearefs="discriminator4"> + <para><literal>insert</literal> (optional - defaults to + <literal>true</literal>): set this to <literal>false</literal> + if your discriminator column is also part of a mapped + composite identifier. It tells Hibernate not to include the + column in SQL <literal>INSERTs</literal>.</para> + </callout> + + <callout arearefs="discriminator5"> + <para><literal>formula</literal> (optional): an arbitrary SQL + expression that is executed when a type has to be evaluated. + It allows content-based discrimination.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>Actual values of the discriminator column are specified by the + <literal>discriminator-value</literal> attribute of the + <literal>&lt;class&gt;</literal> and + <literal>&lt;subclass&gt;</literal> elements.</para> + + <para>The <literal>force</literal> attribute is only useful if the + table contains rows with "extra" discriminator values that are not + mapped to a persistent class. This will not usually be the + case.</para> + + <para>The <literal>formula</literal> attribute allows you to declare + an arbitrary SQL expression that will be used to evaluate the type + of a row. For example:</para> + + <programlisting role="XML">&lt;discriminator + formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end" + type="integer"/&gt;</programlisting> + </section> + </section> + + <section id="mapping-declaration-joinedsubclass" revision="3"> + <title>Joined subclass strategy</title> + + <para>Each subclass can also be mapped to its own table. This is + called the table-per-subclass mapping strategy. An inherited state is + retrieved by joining with the table of the superclass. A discriminator + column is not required for this mapping strategy. Each subclass must, + however, declare a table column holding the object identifier. The + primary key of this table is also a foreign key to the superclass + table and described by the + <classname>@PrimaryKeyJoinColumn</classname>s or the + <literal>&lt;key&gt;</literal> element.</para> + + <programlisting language="JAVA" role="JAVA">@Entity @Table(name="CATS") +(a)Inheritance(strategy=InheritanceType.JOINED) +public class Cat implements Serializable { + @Id @GeneratedValue(generator="cat-uuid") + @GenericGenerator(name="cat-uuid", strategy="uuid") + String getId() { return id; } + + ... +} + +@Entity @Table(name="DOMESTIC_CATS") +@PrimaryKeyJoinColumn(name="CAT") +public class DomesticCat extends Cat { + public String getName() { return name; } +} </programlisting> + + <note> + <para>The table name still defaults to the non qualified class name. + Also if <classname>@PrimaryKeyJoinColumn</classname> is not set, the + primary key / foreign key columns are assumed to have the same names + as the primary key columns of the primary table of the + superclass.</para> + </note> + + <para>In hbm.xml, use the <literal>&lt;joined-subclass&gt;</literal> + element. For example:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="joinedsubclass1" /> + + <area coords="3" id="joinedsubclass2" /> + + <area coords="4" id="joinedsubclass3" /> + + <area coords="5" id="joinedsubclass4" /> + </areaspec> + + <programlisting>&lt;joined-subclass + name="ClassName" + table="tablename" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + schema="schema" + catalog="catalog" + extends="SuperclassName" + persister="ClassName" + subselect="SQL expression" + entity-name="EntityName" + node="element-name"&gt; + + &lt;key .... &gt; + + &lt;property .... /&gt; + ..... +&lt;/joined-subclass&gt;</programlisting> + + <calloutlist> + <callout arearefs="joinedsubclass1"> + <para><literal>name</literal>: the fully qualified class name of + the subclass.</para> + </callout> + + <callout arearefs="joinedsubclass2"> + <para><literal>table</literal>: the name of the subclass + table.</para> + </callout> + + <callout arearefs="joinedsubclass3"> + <para><literal>proxy</literal> (optional): specifies a class or + interface to use for lazy initializing proxies.</para> + </callout> + + <callout arearefs="joinedsubclass4"> + <para><literal>lazy</literal> (optional, defaults to + <literal>true</literal>): setting + <literal>lazy="false"</literal> disables the use of lazy + fetching.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>Use the <literal>&lt;key&gt;</literal> element to declare the + primary key / foreign key column. The mapping at the start of the + chapter would then be re-written as:</para> + + <programlisting role="XML">&lt;?xml version="1.0"?&gt; +&lt;!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"&gt; + +&lt;hibernate-mapping package="eg"&gt; + + &lt;class name="Cat" table="CATS"&gt; + &lt;id name="id" column="uid" type="long"&gt; + &lt;generator class="hilo"/&gt; + &lt;/id&gt; + &lt;property name="birthdate" type="date"/&gt; + &lt;property name="color" not-null="true"/&gt; + &lt;property name="sex" not-null="true"/&gt; + &lt;property name="weight"/&gt; + &lt;many-to-one name="mate"/&gt; + &lt;set name="kittens"&gt; + &lt;key column="MOTHER"/&gt; + &lt;one-to-many class="Cat"/&gt; + &lt;/set&gt; + &lt;joined-subclass name="DomesticCat" table="DOMESTIC_CATS"&gt; + &lt;key column="CAT"/&gt; + &lt;property name="name" type="string"/&gt; + &lt;/joined-subclass&gt; + &lt;/class&gt; + + &lt;class name="eg.Dog"&gt; + &lt;!-- mapping for Dog could go here --&gt; + &lt;/class&gt; + +&lt;/hibernate-mapping&gt;</programlisting> + + <para>For information about inheritance mappings see <xref + linkend="inheritance" />.</para> + </section> + + <section id="mapping-declaration-unionsubclass" revision="2"> + <title>Table per class strategy</title> + + <para>A third option is to map only the concrete classes of an + inheritance hierarchy to tables. This is called the + table-per-concrete-class strategy. Each table defines all persistent + states of the class, including the inherited state. In Hibernate, it + is not necessary to explicitly map such inheritance hierarchies. You + can map each class as a separate entity root. However, if you wish use + polymorphic associations (e.g. an association to the superclass of + your hierarchy), you need to use the union subclass mapping.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS) +public class Flight implements Serializable { ... } </programlisting> + + <para>Or in hbm.xml:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="unionsubclass1" /> + + <area coords="3" id="unionsubclass2" /> + + <area coords="4" id="unionsubclass3" /> + + <area coords="5" id="unionsubclass4" /> + </areaspec> + + <programlisting>&lt;union-subclass + name="ClassName" + table="tablename" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + schema="schema" + catalog="catalog" + extends="SuperclassName" + abstract="true|false" + persister="ClassName" + subselect="SQL expression" + entity-name="EntityName" + node="element-name"&gt; + + &lt;property .... /&gt; + ..... +&lt;/union-subclass&gt;</programlisting> + + <calloutlist> + <callout arearefs="unionsubclass1"> + <para><literal>name</literal>: the fully qualified class name of + the subclass.</para> + </callout> + + <callout arearefs="unionsubclass2"> + <para><literal>table</literal>: the name of the subclass + table.</para> + </callout> + + <callout arearefs="unionsubclass3"> + <para><literal>proxy</literal> (optional): specifies a class or + interface to use for lazy initializing proxies.</para> + </callout> + + <callout arearefs="unionsubclass4"> + <para><literal>lazy</literal> (optional, defaults to + <literal>true</literal>): setting + <literal>lazy="false"</literal> disables the use of lazy + fetching.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>No discriminator column or key column is required for this + mapping strategy.</para> + + <para>For information about inheritance mappings see <xref + linkend="inheritance" />.</para> + </section> + + <section> + <title>Inherit properties from superclasses</title> + + <para>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&gt;(a)MappedSuperclass&lt;/literal&gt;.&lt;/para&gt; + + <programlisting language="JAVA" role="JAVA">@MappedSuperclass +public class BaseEntity { + @Basic + @Temporal(TemporalType.TIMESTAMP) + public Date getLastUpdate() { ... } + public String getLastUpdater() { ... } + ... +} + +@Entity class Order extends BaseEntity { + @Id public Integer getId() { ... } + ... +}</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> + + <note> + <para>Properties from superclasses not mapped as + <literal>@MappedSuperclass</literal> are ignored.</para> + </note> + + <note> + <para>The default access type (field or methods) is used, unless you + use the <literal>@Access</literal> annotation.</para> + </note> + + <note> + <para>The same notion can be applied to + <literal>@Embeddable</literal> objects to persist properties from + their superclasses. You also need to use + <literal>@MappedSuperclass</literal> to do that (this should not be + considered as a standard EJB3 feature though)</para> + </note> + + <note> + <para>It is allowed to mark a class as + <literal>@MappedSuperclass</literal> in the middle of the mapped + inheritance hierarchy.</para> + </note> + + <note> + <para>Any class in the hierarchy non annotated with + <literal>@MappedSuperclass</literal> nor <literal>@Entity</literal> + will be ignored.</para> + </note> + + <para>You can override columns defined in entity superclasses at the + root entity level using the <literal>@AttributeOverride</literal> + annotation.</para> + + <programlisting language="JAVA" role="JAVA">@MappedSuperclass +public class FlyingObject implements Serializable { + + public int getAltitude() { + return altitude; + } + + @Transient + public int getMetricAltitude() { + return metricAltitude; + } + + @ManyToOne + public PropulsionType getPropulsion() { + return metricAltitude; + } + ... +} + +@Entity +@AttributeOverride( name="altitude", column = @Column(name="fld_altitude") ) +@AssociationOverride( + name="propulsion", + joinColumns = @JoinColumn(name="fld_propulsion_fk") +) +public class Plane extends FlyingObject { + ... +}</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> + + <para>You can define <literal>@AttributeOverride</literal>(s) and + <literal>@AssociationOverride</literal>(s) on + <literal>@Entity</literal> classes, + <literal>@MappedSuperclass</literal> classes and properties pointing + to an <literal>@Embeddable</literal> object.</para> + + <para>In hbm.xml, simply map the properties of the superclass in the + <literal>&lt;class&gt;</literal> element of the entity that needs to + inherit them.</para> + </section> + + <section id="mapping-declaration-join" revision="3"> + <title>Mapping one entity to several tables</title> + + <para>While not recommended for a fresh schema, some legacy databases + force your to map a single entity on several tables.</para> + + <para>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&gt;(a)JoinColumn&lt;/literal&gt;.&lt;/para&gt; + + <programlisting language="JAVA" role="JAVA">@Entity +@Table(name="MainCat") +@SecondaryTables({ + @SecondaryTable(name="Cat1", pkJoinColumns={ + @PrimaryKeyJoinColumn(name="cat_id", referencedColumnName="id") + ), + @SecondaryTable(name="Cat2", uniqueConstraints={@UniqueConstraint(columnNames={"storyPart2"})}) +}) +public class Cat implements Serializable { + + private Integer id; + private String name; + private String storyPart1; + private String storyPart2; + + @Id @GeneratedValue + public Integer getId() { + return id; + } + + public String getName() { + return name; + } + + @Column(table="Cat1") + public String getStoryPart1() { + return storyPart1; + } + + @Column(table="Cat2") + public String getStoryPart2() { + return storyPart2; + } +}</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> + + <para>There is also additional tuning accessible via the + <classname&gt;(a)org.hibernate.annotations.Table&lt;/classname&gt; + annotation:</para> + + <itemizedlist> + <listitem> + <para><literal>fetch</literal>: If set to JOIN, the default, + Hibernate will use an inner join to retrieve a secondary table + defined by a class or its superclasses and an outer join for a + secondary table defined by a subclass. If set to + <classname>SELECT</classname> then Hibernate will use a sequential + select for a secondary table defined on a subclass, which will be + issued only if a row turns out to represent an instance of the + subclass. Inner joins will still be used to retrieve a secondary + defined by the class and its superclasses.</para> + </listitem> + + <listitem> + <para><literal>inverse</literal>: If true, Hibernate will not try + to insert or update the properties defined by this join. Default + to false.</para> + </listitem> + + <listitem> + <para><literal>optional</literal>: If enabled (the default), + Hibernate will insert a row only if the properties defined by this + join are non-null and will always use an outer join to retrieve + the properties.</para> + </listitem> + + <listitem> + <para><literal>foreignKey</literal>: defines the Foreign Key name + of a secondary table pointing back to the primary table.</para> + </listitem> + </itemizedlist> + + <para>Make sure to use the secondary table name in the + <methodname>appliesto</methodname> property</para> + + <programlisting language="JAVA" role="JAVA">@Entity +@Table(name="MainCat") +@SecondaryTable(name="Cat1") +(a)org.hibernate.annotations.Table( + appliesTo="Cat1", + fetch=FetchMode.SELECT, + optional=true) +public class Cat implements Serializable { + + private Integer id; + private String name; + private String storyPart1; + private String storyPart2; + + @Id @GeneratedValue + public Integer getId() { + return id; + } + + public String getName() { + return name; + } + + @Column(table="Cat1") + public String getStoryPart1() { + return storyPart1; + } + + @Column(table="Cat2") + public String getStoryPart2() { + return storyPart2; + } +}</programlisting> + + <para>In hbm.xml, use the <literal>&lt;join&gt;</literal> + element.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="join1" /> + + <area coords="3" id="join2" /> + + <area coords="4" id="join3" /> + + <area coords="5" id="join4" /> + + <area coords="6" id="join5" /> + + <area coords="7" id="join6" /> + </areaspec> + + <programlisting>&lt;join + table="tablename" + schema="owner" + catalog="catalog" + fetch="join|select" + inverse="true|false" + optional="true|false"&gt; + + &lt;key ... /&gt; + + &lt;property ... /&gt; + ... +&lt;/join&gt;</programlisting> + + <calloutlist> + <callout arearefs="join1"> + <para><literal>table</literal>: the name of the joined + table.</para> + </callout> + + <callout arearefs="join2"> + <para><literal>schema</literal> (optional): overrides the schema + name specified by the root + <literal>&lt;hibernate-mapping&gt;</literal> element.</para> + </callout> + + <callout arearefs="join3"> + <para><literal>catalog</literal> (optional): overrides the + catalog name specified by the root + <literal>&lt;hibernate-mapping&gt;</literal> element.</para> + </callout> + + <callout arearefs="join4"> + <para><literal>fetch</literal> (optional - defaults to + <literal>join</literal>): if set to <literal>join</literal>, the + default, Hibernate will use an inner join to retrieve a + <literal>&lt;join&gt;</literal> defined by a class or its + superclasses. It will use an outer join for a + <literal>&lt;join&gt;</literal> defined by a subclass. If set to + <literal>select</literal> then Hibernate will use a sequential + select for a <literal>&lt;join&gt;</literal> defined on a + subclass. This will be issued only if a row represents an + instance of the subclass. Inner joins will still be used to + retrieve a <literal>&lt;join&gt;</literal> defined by the class + and its superclasses.</para> + </callout> + + <callout arearefs="join5"> + <para><literal>inverse</literal> (optional - defaults to + <literal>false</literal>): if enabled, Hibernate will not insert + or update the properties defined by this join.</para> + </callout> + + <callout arearefs="join6"> + <para><literal>optional</literal> (optional - defaults to + <literal>false</literal>): if enabled, Hibernate will insert a + row only if the properties defined by this join are non-null. It + will always use an outer join to retrieve the properties.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>For example, address information for a person can be mapped to a + separate table while preserving value type semantics for all + properties:</para> + + <programlisting role="XML">&lt;class name="Person" + table="PERSON"&gt; + + &lt;id name="id" column="PERSON_ID"&gt;...&lt;/id&gt; + + &lt;join table="ADDRESS"&gt; + &lt;key column="ADDRESS_ID"/&gt; + &lt;property name="address"/&gt; + &lt;property name="zip"/&gt; + &lt;property name="country"/&gt; + &lt;/join&gt; + ...</programlisting> + + <para>This feature is often only useful for legacy data models. We + recommend fewer tables than classes and a fine-grained domain model. + However, it is useful for switching between inheritance mapping + strategies in a single hierarchy, as explained later.</para> + </section> + </section> + + <section> + <title>Optimistic locking properties (optional)</title> + + <para>When using long transactions or conversations that span several + database transactions, it is useful to store versioning data to ensure + that if the same entity is updated by two conversations, the last to + commit changes will be informed and not override the other + conversation's work. It guarantees some isolation while still allowing + for good scalability and works particularly well in read-often + write-sometimes situations.</para> + + <para>You can use two approaches: a dedicated version number or a + timestamp.</para> + + <para>A version or timestamp property should never be null for a + detached instance. Hibernate will detect any instance with a null + version or timestamp as transient, irrespective of what other + <literal>unsaved-value</literal> strategies are specified. + <emphasis>Declaring a nullable version or timestamp property is an easy + way to avoid problems with transitive reattachment in Hibernate. It is + especially useful for people using assigned identifiers or composite + keys</emphasis>.</para> + + <section id="entity-mapping-entity-version"> + <title>Version number</title> + + <para>You can add optimistic locking capability to an entity using the + <literal>@Version</literal> annotation:</para> + + <programlisting language="JAVA" role="JAVA">@Entity +public class Flight implements Serializable { +... + @Version + @Column(name="OPTLOCK") + public Integer getVersion() { ... } +} </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> + + <para>The version column may be a numeric. Hibernate supports any kind + of type provided that you define and implement the appropriate + <classname>UserVersionType</classname>.</para> + + <para>The application must not alter the version number set up by + Hibernate in any way. To artificially increase the version number, + check in Hibernate Entity Manager's reference documentation + <literal>LockModeType.OPTIMISTIC_FORCE_INCREMENT</literal> or + <literal>LockModeType.PESSIMISTIC_FORCE_INCREMENT</literal>.</para> + + <para>If the version number is generated by the database (via a + trigger for example), make sure to use + <code&gt;(a)org.hibernate.annotations.Generated(GenerationTime.ALWAYS).&lt;/code&gt;&lt;/para&gt; + + <para>To declare a version property in hbm.xml, use:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="version1" /> + + <area coords="3" id="version2" /> + + <area coords="4" id="version3" /> + + <area coords="5" id="version4" /> + + <area coords="6" id="version5" /> + + <area coords="7" id="version6" /> + + <area coords="8" id="version7" /> + </areaspec> + + <programlisting>&lt;version + column="version_column" + name="propertyName" + type="typename" + access="field|property|ClassName" + unsaved-value="null|negative|undefined" + generated="never|always" + insert="true|false" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="version1"> + <para><literal>column</literal> (optional - defaults to the + property name): the name of the column holding the version + number.</para> + </callout> + + <callout arearefs="version2"> + <para><literal>name</literal>: the name of a property of the + persistent class.</para> + </callout> + + <callout arearefs="version3"> + <para><literal>type</literal> (optional - defaults to + <literal>integer</literal>): the type of the version + number.</para> + </callout> + + <callout arearefs="version4"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses to + access the property value.</para> + </callout> + + <callout arearefs="version5"> + <para><literal>unsaved-value</literal> (optional - defaults to + <literal>undefined</literal>): a version property value that + indicates that an instance is newly instantiated (unsaved), + distinguishing it from detached instances that were saved or + loaded in a previous session. <literal>Undefined</literal> + specifies that the identifier property value should be + used.</para> + </callout> + + <callout arearefs="version6"> + <para><literal>generated</literal> (optional - defaults to + <literal>never</literal>): specifies that this version property + value is generated by the database. See the discussion of <link + linkend="mapping-generated">generated properties</link> for more + information.</para> + </callout> + + <callout arearefs="version7"> + <para><literal>insert</literal> (optional - defaults to + <literal>true</literal>): specifies whether the version column + should be included in SQL insert statements. It can be set to + <literal>false</literal> if the database column is defined with + a default value of <literal>0</literal>.</para> + </callout> + </calloutlist> + </programlistingco> + </section> + + <section id="mapping-declaration-timestamp" revision="4"> + <title>Timestamp</title> + + <para>Alternatively, you can use a timestamp. Timestamps are a less + safe implementation of optimistic locking. However, sometimes the + application might use the timestamps in other ways.</para> + + <para>Simply mark a property of type <classname>Date</classname> or + <classname>Calendar</classname> as + <classname&gt;(a)Version&lt;/classname&gt;.&lt;/para&gt; + + <programlisting language="JAVA" role="JAVA">@Entity +public class Flight implements Serializable { +... + @Version + public Date getLastUpdate() { ... } +} </programlisting> + + <para>Like version numbers, the timestamp can be generated by the + database instead of Hibernate. To do that, use + <code&gt;(a)org.hibernate.annotations.Generated(GenerationTime.ALWAYS).&lt;/code&gt;&lt;/para&gt; + + <para>In hbm.xml, use the <literal>&lt;timestamp&gt;</literal> + element:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="timestamp1" /> + + <area coords="3" id="timestamp2" /> + + <area coords="4" id="timestamp3" /> + + <area coords="5" id="timestamp4" /> + + <area coords="6" id="timestamp5" /> + + <area coords="7" id="timestamp6" /> + </areaspec> + + <programlisting>&lt;timestamp + column="timestamp_column" + name="propertyName" + access="field|property|ClassName" + unsaved-value="null|undefined" + source="vm|db" + generated="never|always" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="timestamp1"> + <para><literal>column</literal> (optional - defaults to the + property name): the name of a column holding the + timestamp.</para> + </callout> + + <callout arearefs="timestamp2"> + <para><literal>name</literal>: the name of a JavaBeans style + property of Java type <literal>Date</literal> or + <literal>Timestamp</literal> of the persistent class.</para> + </callout> + + <callout arearefs="timestamp3"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="timestamp4"> + <para><literal>unsaved-value</literal> (optional - defaults to + <literal>null</literal>): a version property value that + indicates that an instance is newly instantiated (unsaved), + distinguishing it from detached instances that were saved or + loaded in a previous session. <literal>Undefined</literal> + specifies that the identifier property value should be + used.</para> + </callout> + + <callout arearefs="timestamp5"> + <para><literal>source</literal> (optional - defaults to + <literal>vm</literal>): Where should Hibernate retrieve the + timestamp value from? From the database, or from the current + JVM? Database-based timestamps incur an overhead because + Hibernate must hit the database in order to determine the "next + value". It is safer to use in clustered environments. Not all + <literal>Dialects</literal> are known to support the retrieval + of the database's current timestamp. Others may also be unsafe + for usage in locking due to lack of precision (Oracle 8, for + example).</para> + </callout> + + <callout arearefs="timestamp6"> + <para><literal>generated</literal> (optional - defaults to + <literal>never</literal>): specifies that this timestamp + property value is actually generated by the database. See the + discussion of <link linkend="mapping-generated">generated + properties</link> for more information.</para> + </callout> + </calloutlist> + </programlistingco> + + <note> + <title>Note</title> + + <para><literal>&lt;Timestamp&gt;</literal> is equivalent to + <literal>&lt;version type="timestamp"&gt;</literal>. And + <literal>&lt;timestamp source="db"&gt;</literal> is equivalent to + <literal>&lt;version type="dbtimestamp"&gt;</literal></para> + </note> + </section> + </section> + + <section id="mapping-declaration-property" revision="4"> + <title>Property</title> + + <para>You need to decide which property needs to be made persistent in a + given entity. This differs slightly between the annotation driven + metadata and the hbm.xml files.</para> + + <section> + <title>Property mapping with annotations</title> + + <para>In the annotations world, every non static non transient + property (field or method depending on the access type) of an entity + 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.</para> + + <para>The <literal>@Basic</literal> annotation allows you to declare + the fetching strategy for a property. If set to + <literal>LAZY</literal>, specifies that this property should be + fetched lazily when the instance variable is first accessed. It + requires build-time bytecode instrumentation, if your classes are not + instrumented, property level lazy loading is silently ignored. The + default is <literal>EAGER</literal>. You can also mark a property as + not optional thanks to the <classname&gt;(a)Basic.optional&lt;/classname&gt; + attribute. This will ensure that the underlying column are not + nullable (if possible). Note that a better approach is to use the + <classname>@NotNull</classname> annotation of the Bean Validation + specification.</para> + + <para>Let's look at a few examples:</para> + + <programlisting language="JAVA" role="JAVA">public transient int counter; //transient property + +private String firstname; //persistent property + +@Transient +String getLengthInMeter() { ... } //transient property + +String getName() {... } // persistent property + +@Basic +int getLength() { ... } // persistent property + +@Basic(fetch = FetchType.LAZY) +String getDetailedComment() { ... } // persistent property + +(a)Temporal(TemporalType.TIME) +java.util.Date getDepartureTime() { ... } // persistent property + +(a)Enumerated(EnumType.STRING) +Starred getNote() { ... } //enum persisted as String in database</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 Hibernate. + <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). The + recommended alternative is to use the projection capability of JP-QL + (Java Persistence Query Language) or Criteria queries.</para> + + <para>JPA support property mapping of all basic types supported by + Hibernate (all basic Java types , their respective wrappers and + serializable classes). Hibernate Annotations supports out of the box + enum type mapping either into a ordinal column (saving the enum + ordinal) or a string based column (saving the enum string + representation): the persistence representation, defaulted to ordinal, + can be overridden through the <literal>@Enumerated</literal> + annotation as shown in the <literal>note</literal> property + example.</para> + + <para></para> + + <para>In plain Java APIs, the temporal precision of time is not + defined. When dealing with temporal data you might want to describe + the expected precision in database. Temporal data can have + <literal>DATE</literal>, <literal>TIME</literal>, or + <literal>TIMESTAMP</literal> precision (ie the actual date, only the + time, or both). Use the <literal>@Temporal</literal> annotation to + fine tune that.</para> + + <para><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 <classname>Serializable</classname> + type will be persisted in a Blob.</para> + + <programlisting language="JAVA" role="JAVA">@Lob +public String getFullText() { + return fullText; +} + +@Lob +public byte[] getFullCode() { + return fullCode; +}</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> + + <section> + <title>Type</title> + + <para>You can also manually specify a type using the + <literal&gt;(a)org.hibernate.annotations.Type&lt;/literal&gt; and some + parameters if needed. <classname&gt;(a)Type.type&lt;/classname&gt; could + be:</para> + + <orderedlist spacing="compact"> + <listitem> + <para>The name of a Hibernate basic type: <literal>integer, + string, character, date, timestamp, float, binary, serializable, + object, blob</literal> etc.</para> + </listitem> + + <listitem> + <para>The name of a Java class with a default basic type: + <literal>int, float, char, java.lang.String, java.util.Date, + java.lang.Integer, java.sql.Clob</literal> etc.</para> + </listitem> + + <listitem> + <para>The name of a serializable Java class.</para> + </listitem> + + <listitem> + <para>The class name of a custom type: + <literal>com.illflow.type.MyCustomType</literal> etc.</para> + </listitem> + </orderedlist> + + <para>If you do not specify a type, Hibernate will use reflection + upon the named property and guess the correct Hibernate type. + Hibernate will attempt to interpret the name of the return class of + the property getter using, in order, rules 2, 3, and 4.</para> + + <para&gt;&lt;literal&gt;(a)org.hibernate.annotations.TypeDef&lt;/literal&gt; and + <literal&gt;(a)org.hibernate.annotations.TypeDefs&lt;/literal&gt; allows you to + declare type definitions. These annotations can be placed at the + class or package level. Note that these definitions are global for + the session factory (even when defined at the class level). If the + type is used on a single entity, you can place the definition on the + entity itself. Otherwise, it is recommended to place the definition + at the package level. In the example below, when Hibernate + encounters a property of class <literal>PhoneNumer</literal>, it + delegates the persistence strategy to the custom mapping type + <literal>PhoneNumberType</literal>. However, properties belonging to + other classes, too, can delegate their persistence strategy to + <literal>PhoneNumberType</literal>, by explicitly using the + <literal>@Type</literal> annotation.</para> + + <note> + <para>Package level annotations are placed in a file named + <filename>package-info.java</filename> in the appropriate package. + Place your annotations before the package declaration.</para> + </note> + + <programlisting language="JAVA" role="JAVA">@TypeDef( + name = "phoneNumber", + defaultForType = PhoneNumber.class, + typeClass = PhoneNumberType.class +) + +@Entity +public class ContactDetails { + [...] + private PhoneNumber localPhoneNumber; + @Type(type="phoneNumber") + private OverseasPhoneNumber overseasPhoneNumber; + [...] +}</programlisting> + + <para>The following example shows the usage of the + <literal>parameters</literal> attribute to customize the + TypeDef.</para> + + <programlisting language="JAVA" role="JAVA">//in org/hibernate/test/annotations/entity/package-info.java +@TypeDefs( + { + @TypeDef( + name="caster", + typeClass = CasterStringType.class, + parameters = { + @Parameter(name="cast", value="lower") + } + ) + } +) +package org.hibernate.test.annotations.entity; + +//in org/hibernate/test/annotations/entity/Forest.java +public class Forest { + @Type(type="caster") + public String getSmallText() { + ... +} </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" role=&quot;JAVA&quot;&gt;(a)Type(type=&quot;org.hibernate.test.annotations.entity.MonetaryAmountUserType&quot;) +@Columns(columns = { + @Column(name="r_amount"), + @Column(name="r_currency") +}) +public MonetaryAmount getAmount() { + return amount; +} + + +public class MonetaryAmount implements Serializable { + private BigDecimal amount; + private Currency currency; + ... +}</programlisting> + </section> + + <section> + <title>Access type</title> + + <para>By default the access type of a class hierarchy is defined by + the position of the <classname>@Id</classname> or + <classname>@EmbeddedId</classname> annotations. If these annotations + are on a field, then only fields are considered for persistence and + the state is accessed via the field. If there annotations are on a + getter, then only the getters are considered for persistence and the + state is accessed via the getter/setter. That works well in practice + and is the recommended approach.<note> + <para>The placement of annotations within a class hierarchy has + to be consistent (either field or on property) to be able to + determine the default access type. It is recommended to stick to + one single annotation placement strategy throughout your whole + application.</para> + </note></para> + + <para>However in some situations, you need to:</para> + + <itemizedlist> + <listitem> + <para>force the access type of the entity hierarchy</para> + </listitem> + + <listitem> + <para>override the access type of a specific entity in the class + hierarchy</para> + </listitem> + + <listitem> + <para>override the access type of an embeddable type</para> + </listitem> + </itemizedlist> + + <para>The best use case is an embeddable class used by several + entities that might not use the same access type. In this case it is + better to force the access type at the embeddable class + level.</para> + + <para>To force the access type on a given class, use the + <classname>@Access</classname> annotation as showed below:</para> + + <programlisting language="JAVA" role="JAVA">@Entity +public class Order { + @Id private Long id; + public Long getId() { return id; } + public void setId(Long id) { this.id = id; } + + @Embedded private Address address; + public Address getAddress() { return address; } + public void setAddress() { this.address = address; } +} + +@Entity +public class User { + private Long id; + @Id public Long getId() { return id; } + public void setId(Long id) { this.id = id; } + + private Address address; + @Embedded public Address getAddress() { return address; } + public void setAddress() { this.address = address; } +} + +@Embeddable +(a)Access(AcessType.PROPERTY) +public class Address { + private String street1; + public String getStreet1() { return street1; } + public void setStreet1() { this.street1 = street1; } + + private hashCode; //not persistent +}</programlisting> + + <para>You can also override the access type of a single property + while keeping the other properties standard.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +public class Order { + @Id private Long id; + public Long getId() { return id; } + public void setId(Long id) { this.id = id; } + @Transient private String userId; + @Transient private String orderId; + + @Access(AccessType.PROPERTY) + public String getOrderNumber() { return userId + ":" + orderId; } + public void setOrderNumber() { this.userId = ...; this.orderId = ...; } +}</programlisting> + + <para>In this example, the default access type is + <classname>FIELD</classname> except for the + <literal>orderNumber</literal> property. Note that the corresponding + field, if any must be marked as <classname>@Transient</classname> or + <code>transient</code>.</para> + + <note> + <title&gt;(a)org.hibernate.annotations.AccessType&lt;/title&gt; + + <para>The annotation + <classname&gt;(a)org.hibernate.annotations.AccessType&lt;/classname&gt; + should be considered deprecated for FIELD and PROPERTY access. It + is still useful however if you need to use a custom access + type.</para> + </note> + </section> + + <section> + <title>Optimistic lock</title> + + <para>It is sometimes useful to avoid increasing the version number + even if a given property is dirty (particularly collections). You + can do that by annotating the property (or collection) with + <literal&gt;(a)OptimisticLock(excluded=true)&lt;/literal&gt;.&lt;/para&gt; + + <para>More formally, specifies that updates to this property do not + require acquisition of the optimistic lock.</para> + </section> + + <section id="entity-mapping-property-column"> + <title>Declaring column attributes</title> + + <para>The column(s) used for a property mapping can be defined using + the <literal>@Column</literal> annotation. Use it to override + default values (see the JPA specification for more information on + the defaults). You can use this annotation at the property level for + properties that are:</para> + + <itemizedlist> + <listitem> + <para>not annotated at all</para> + </listitem> + + <listitem> + <para>annotated with <literal>@Basic</literal></para> + </listitem> + + <listitem> + <para>annotated with <literal>@Version</literal></para> + </listitem> + + <listitem> + <para>annotated with <literal>@Lob</literal></para> + </listitem> + + <listitem> + <para>annotated with <literal>@Temporal</literal></para> + </listitem> + </itemizedlist> + + <programlisting language="JAVA" role="JAVA"> +@Entity +public class Flight implements Serializable { +... +@Column(updatable = false, name = "flight_name", nullable = false, length=50) +public String getName() { ... } + </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> + + <para>This annotation can be applied to regular properties as well + as <literal>@Id</literal> or <literal>@Version</literal> + properties.</para> + + <programlistingco> + <areaspec> + <area coords="2" id="hm1" /> + + <area coords="3" id="hm2" /> + + <area coords="4" id="hm3" /> + + <area coords="5" id="hm4" /> + + <area coords="6" id="hm5" /> + + <area coords="7" id="hm6" /> + + <area coords="8" id="hm7" /> + + <area coords="9" id="hm8" /> + + <area coords="10" id="hm9" /> + + <area coords="11" id="hm10" /> + </areaspec> + + <programlisting>@Column( + name="columnName"; + boolean unique() default false; + boolean nullable() default true; + boolean insertable() default true; + boolean updatable() default true; + String columnDefinition() default ""; + String table() default ""; + int length() default 255; + int precision() default 0; // decimal precision + int scale() default 0; // decimal scale</programlisting> + + <calloutlist> + <callout arearefs="hm1"> + <para><literal>name</literal> (optional): the column name + (default to the property name)</para> + </callout> + + <callout arearefs="hm2"> + <para><literal>unique</literal> (optional): set a unique + constraint on this column or not (default false)</para> + </callout> + + <callout arearefs="hm3"> + <para><literal>nullable</literal> (optional): set the column + as nullable (default true).</para> + </callout> + + <callout arearefs="hm4"> + <para><literal>insertable</literal> (optional): whether or not + the column will be part of the insert statement (default + true)</para> + </callout> + + <callout arearefs="hm5"> + <para><literal>updatable</literal> (optional): whether or not + the column will be part of the update statement (default + true)</para> + </callout> + + <callout arearefs="hm6"> + <para><literal>columnDefinition</literal> (optional): override + the sql DDL fragment for this particular column (non + portable)</para> + </callout> + + <callout arearefs="hm7"> + <para><literal>table</literal> (optional): define the targeted + table (default primary table)</para> + </callout> + + <callout arearefs="hm8"> + <para><literal><literal>length</literal></literal> (optional): + column length (default 255)</para> + </callout> + + <callout arearefs="hm8"> + <para><literal><literal>precision</literal></literal> + (optional): column decimal precision (default 0)</para> + </callout> + + <callout arearefs="hm10"> + <para><literal><literal>scale</literal></literal> (optional): + column decimal scale if useful (default 0)</para> + </callout> + </calloutlist> + </programlistingco> + </section> + + <section> + <title>Formula</title> + + <para>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" role="JAVA">@Formula("obj_length * obj_height * obj_width") +public long getObjectVolume()</programlisting> + + <para>The SQL fragment can be as complex as you want and even + include subselects.</para> + </section> + + <section> + <title>Non-annotated property defaults</title> + + <para>If a property is not annotated, the following rules + apply:<itemizedlist> + <listitem> + <para>If the property is of a single type, it is mapped as + @Basic</para> + </listitem> + + <listitem> + <para>Otherwise, if the type of the property is annotated as + @Embeddable, it is mapped as @Embedded</para> + </listitem> + + <listitem> + <para>Otherwise, if the type of the property is + <classname>Serializable</classname>, it is mapped as + <classname>@Basic</classname> in a column holding the object + in its serialized version</para> + </listitem> + + <listitem> + <para>Otherwise, if the type of the property is + <classname>java.sql.Clob</classname> or + <classname>java.sql.Blob</classname>, it is mapped as + <classname>@Lob</classname> with the appropriate + <classname>LobType</classname></para> + </listitem> + </itemizedlist></para> + </section> + </section> + + <section> + <title>Property mapping with hbm.xml</title> + + <para>The <literal>&lt;property&gt;</literal> element declares a + persistent JavaBean style property of the class.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="property1" /> + + <area coords="3" id="property2" /> + + <area coords="4" id="property3" /> + + <areaset coords="" id="property4-5"> + <area coords="5" id="property4" /> + + <area coords="6" id="property5" /> + </areaset> + + <area coords="7" id="property6" /> + + <area coords="8" id="property7" /> + + <area coords="9" id="property8" /> + + <area coords="10" id="property9" /> + + <area coords="11" id="property10" /> + + <area coords="12" id="property11" /> + + <area coords="13" id="property12" /> + </areaspec> + + <programlisting>&lt;property + name="propertyName" + column="column_name" + type="typename" + update="true|false" + insert="true|false" + formula="arbitrary SQL expression" + access="field|property|ClassName" + lazy="true|false" + unique="true|false" + not-null="true|false" + optimistic-lock="true|false" + generated="never|insert|always" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + index="index_name" + unique_key="unique_key_id" + length="L" + precision="P" + scale="S" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="property1"> + <para><literal>name</literal>: the name of the property, with an + initial lowercase letter.</para> + </callout> + + <callout arearefs="property2"> + <para><literal>column</literal> (optional - defaults to the + property name): the name of the mapped database table column. + This can also be specified by nested + <literal>&lt;column&gt;</literal> element(s).</para> + </callout> + + <callout arearefs="property3"> + <para><literal>type</literal> (optional): a name that indicates + the Hibernate type.</para> + </callout> + + <callout arearefs="property4-5"> + <para><literal>update, insert</literal> (optional - defaults to + <literal>true</literal>): specifies that the mapped columns + should be included in SQL <literal>UPDATE</literal> and/or + <literal>INSERT</literal> statements. Setting both to + <literal>false</literal> allows a pure "derived" property whose + value is initialized from some other property that maps to the + same column(s), or by a trigger or other application.</para> + </callout> + + <callout arearefs="property6"> + <para><literal>formula</literal> (optional): an SQL expression + that defines the value for a <emphasis>computed</emphasis> + property. Computed properties do not have a column mapping of + their own.</para> + </callout> + + <callout arearefs="property7"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="property8"> + <para><literal>lazy</literal> (optional - defaults to + <literal>false</literal>): specifies that this property should + be fetched lazily when the instance variable is first accessed. + It requires build-time bytecode instrumentation.</para> + </callout> + + <callout arearefs="property9"> + <para><literal>unique</literal> (optional): enables the DDL + generation of a unique constraint for the columns. Also, allow + this to be the target of a + <literal>property-ref</literal>.</para> + </callout> + + <callout arearefs="property10"> + <para><literal>not-null</literal> (optional): enables the DDL + generation of a nullability constraint for the columns.</para> + </callout> + + <callout arearefs="property11"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>true</literal>): specifies that updates to this + property do or do not require acquisition of the optimistic + lock. In other words, it determines if a version increment + should occur when this property is dirty.</para> + </callout> + + <callout arearefs="property12"> + <para><literal>generated</literal> (optional - defaults to + <literal>never</literal>): specifies that this property value is + actually generated by the database. See the discussion of <link + linkend="mapping-generated">generated properties</link> for more + information.</para> + </callout> + </calloutlist> + </programlistingco> + + <para><emphasis>typename</emphasis> could be:</para> + + <orderedlist spacing="compact"> + <listitem> + <para>The name of a Hibernate basic type: <literal>integer, + string, character, date, timestamp, float, binary, serializable, + object, blob</literal> etc.</para> + </listitem> + + <listitem> + <para>The name of a Java class with a default basic type: + <literal>int, float, char, java.lang.String, java.util.Date, + java.lang.Integer, java.sql.Clob</literal> etc.</para> + </listitem> + + <listitem> + <para>The name of a serializable Java class.</para> + </listitem> + + <listitem> + <para>The class name of a custom type: + <literal>com.illflow.type.MyCustomType</literal> etc.</para> + </listitem> + </orderedlist> + + <para>If you do not specify a type, Hibernate will use reflection upon + the named property and guess the correct Hibernate type. Hibernate + will attempt to interpret the name of the return class of the property + getter using, in order, rules 2, 3, and 4. In certain cases you will + need the <literal>type</literal> attribute. For example, to + distinguish between <literal>Hibernate.DATE</literal> and + <literal>Hibernate.TIMESTAMP</literal>, or to specify a custom + type.</para> + + <para>The <literal>access</literal> attribute allows you to control + how Hibernate accesses the property at runtime. By default, Hibernate + will call the property get/set pair. If you specify + <literal>access="field"</literal>, Hibernate will bypass the get/set + pair and access the field directly using reflection. You can specify + your own strategy for property access by naming a class that + implements the interface + <literal>org.hibernate.property.PropertyAccessor</literal>.</para> + + <para>A powerful feature is derived properties. These properties are + by definition read-only. The property value is computed at load time. + You declare the computation as an SQL expression. This then translates + to a <literal>SELECT</literal> clause subquery in the SQL query that + loads an instance:</para> + + <programlisting role="XML"> +&lt;property name="totalPrice" + formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p + WHERE li.productId = p.productId + AND li.customerId = customerId + AND li.orderNumber = orderNumber )"/&gt;</programlisting> + + <para>You can reference the entity table by not declaring an alias on + a particular column. This would be <literal>customerId</literal> in + the given example. You can also use the nested + <literal>&lt;formula&gt;</literal> mapping element if you do not want + to use the attribute.</para> + </section> + </section> + + <section id="mapping-declaration-manytoone" revision="5"> + <title>Many-to-one</title> + + <para>An ordinary association to another persistent class is declared + using a <literal>many-to-one</literal> element. The relational model is + a many-to-one association; a foreign key in one table is referencing the + primary key column(s) of the target table.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="manytoone1" /> + + <area coords="3" id="manytoone2" /> + + <area coords="4" id="manytoone3" /> + + <area coords="5" id="manytoone4" /> + + <area coords="6" id="manytoone5" /> + + <areaset coords="" id="manytoone6-7"> + <area coords="7" id="manytoone6" /> + + <area coords="8" id="manytoone7" /> + </areaset> + + <area coords="9" id="manytoone8" /> + + <area coords="10" id="manytoone9" /> + + <area coords="11" id="manytoone10" /> + + <area coords="12" id="manytoone11" /> + + <area coords="13" id="manytoone12" /> + + <area coords="14" id="manytoone13" /> + + <area coords="15" id="manytoone14" /> + + <area coords="16" id="manytoone15" /> + + <area coords="17" id="manytoone16" /> + </areaspec> + + <programlisting>&lt;many-to-one + name="propertyName" + column="column_name" + class="ClassName" + cascade="cascade_style" + fetch="join|select" + update="true|false" + insert="true|false" + property-ref="propertyNameFromAssociatedClass" + access="field|property|ClassName" + unique="true|false" + not-null="true|false" + optimistic-lock="true|false" + lazy="proxy|no-proxy|false" + not-found="ignore|exception" + entity-name="EntityName" + formula="arbitrary SQL expression" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + embed-xml="true|false" + index="index_name" + unique_key="unique_key_id" + foreign-key="foreign_key_name" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="manytoone1"> + <para><literal>name</literal>: the name of the property.</para> + </callout> + + <callout arearefs="manytoone2"> + <para><literal>column</literal> (optional): the name of the + foreign key column. This can also be specified by nested + <literal>&lt;column&gt;</literal> element(s).</para> + </callout> + + <callout arearefs="manytoone3"> + <para><literal>class</literal> (optional - defaults to the + property type determined by reflection): the name of the + associated class.</para> + </callout> + + <callout arearefs="manytoone4"> + <para><literal>cascade</literal> (optional): specifies which + operations should be cascaded from the parent object to the + associated object.</para> + </callout> + + <callout arearefs="manytoone5"> + <para><literal>fetch</literal> (optional - defaults to + <literal>select</literal>): chooses between outer-join fetching or + sequential select fetching.</para> + </callout> + + <callout arearefs="manytoone6-7"> + <para><literal>update, insert</literal> (optional - defaults to + <literal>true</literal>): specifies that the mapped columns should + be included in SQL <literal>UPDATE</literal> and/or + <literal>INSERT</literal> statements. Setting both to + <literal>false</literal> allows a pure "derived" association whose + value is initialized from another property that maps to the same + column(s), or by a trigger or other application.</para> + </callout> + + <callout arearefs="manytoone8"> + <para><literal>property-ref</literal> (optional): the name of a + property of the associated class that is joined to this foreign + key. If not specified, the primary key of the associated class is + used.</para> + </callout> + + <callout arearefs="manytoone9"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="manytoone10"> + <para><literal>unique</literal> (optional): enables the DDL + generation of a unique constraint for the foreign-key column. By + allowing this to be the target of a + <literal>property-ref</literal>, you can make the association + multiplicity one-to-one.</para> + </callout> + + <callout arearefs="manytoone11"> + <para><literal>not-null</literal> (optional): enables the DDL + generation of a nullability constraint for the foreign key + columns.</para> + </callout> + + <callout arearefs="manytoone12"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>true</literal>): specifies that updates to this property + do or do not require acquisition of the optimistic lock. In other + words, it determines if a version increment should occur when this + property is dirty.</para> + </callout> + + <callout arearefs="manytoone13"> + <para><literal>lazy</literal> (optional - defaults to + <literal>proxy</literal>): by default, single point associations + are proxied. <literal>lazy="no-proxy"</literal> specifies that the + property should be fetched lazily when the instance variable is + first accessed. This requires build-time bytecode instrumentation. + <literal>lazy="false"</literal> specifies that the association + will always be eagerly fetched.</para> + </callout> + + <callout arearefs="manytoone14"> + <para><literal>not-found</literal> (optional - defaults to + <literal>exception</literal>): specifies how foreign keys that + reference missing rows will be handled. <literal>ignore</literal> + will treat a missing row as a null association.</para> + </callout> + + <callout arearefs="manytoone15"> + <para><literal>entity-name</literal> (optional): the entity name + of the associated class.</para> + </callout> + + <callout arearefs="manytoone16"> + <para><literal>formula</literal> (optional): an SQL expression + that defines the value for a <emphasis>computed</emphasis> foreign + key.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>Setting a value of the <literal>cascade</literal> attribute to any + meaningful value other than <literal>none</literal> will propagate + certain operations to the associated object. The meaningful values are + divided into three categories. First, basic operations, which include: + <literal>persist, merge, delete, save-update, evict, replicate, lock and + refresh</literal>; second, special values: + <literal>delete-orphan</literal>; and third,<literal>all</literal> + comma-separated combinations of operation names: + <literal>cascade="persist,merge,evict"</literal> or + <literal>cascade="all,delete-orphan"</literal>. See <xref + linkend="objectstate-transitive" /> for a full explanation. Note that + single valued, many-to-one and one-to-one, associations do not support + orphan delete.</para> + + <para>Here is an example of a typical <literal>many-to-one</literal> + declaration:</para> + + <programlisting role="XML">&lt;many-to-one name="product" class="Product" column="PRODUCT_ID"/&gt;</programlisting> + + <para>The <literal>property-ref</literal> attribute should only be used + for mapping legacy data where a foreign key refers to a unique key of + the associated table other than the primary key. This is a complicated + and confusing relational model. For example, if the + <literal>Product</literal> class had a unique serial number that is not + the primary key. The <literal>unique</literal> attribute controls + Hibernate's DDL generation with the SchemaExport tool.</para> + + <programlisting role="XML">&lt;property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/&gt;</programlisting> + + <para>Then the mapping for <literal>OrderItem</literal> might + use:</para> + + <programlisting role="XML">&lt;many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/&gt;</programlisting> + + <para>This is not encouraged, however.</para> + + <para>If the referenced unique key comprises multiple properties of the + associated entity, you should map the referenced properties inside a + named <literal>&lt;properties&gt;</literal> element.</para> + + <para>If the referenced unique key is the property of a component, you + can specify a property path:</para> + + <programlisting role="XML">&lt;many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/&gt;</programlisting> + </section> + + <section id="mapping-declaration-onetoone" revision="3"> + <title>One-to-one</title> + + <para>A one-to-one association to another persistent class is declared + using a <literal>one-to-one</literal> element.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="onetoone1" /> + + <area coords="3" id="onetoone2" /> + + <area coords="4" id="onetoone3" /> + + <area coords="5" id="onetoone4" /> + + <area coords="6" id="onetoone5" /> + + <area coords="7" id="onetoone6" /> + + <area coords="8" id="onetoone7" /> + + <area coords="9" id="onetoone8" /> + + <area coords="10" id="onetoone9" /> + + <area coords="11" id="onetoone10" /> + </areaspec> + + <programlisting>&lt;one-to-one + name="propertyName" + class="ClassName" + cascade="cascade_style" + constrained="true|false" + fetch="join|select" + property-ref="propertyNameFromAssociatedClass" + access="field|property|ClassName" + formula="any SQL expression" + lazy="proxy|no-proxy|false" + entity-name="EntityName" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + embed-xml="true|false" + foreign-key="foreign_key_name" +/&gt;</programlisting> + + <calloutlist> + <callout arearefs="onetoone1"> + <para><literal>name</literal>: the name of the property.</para> + </callout> + + <callout arearefs="onetoone2"> + <para><literal>class</literal> (optional - defaults to the + property type determined by reflection): the name of the + associated class.</para> + </callout> + + <callout arearefs="onetoone3"> + <para><literal>cascade</literal> (optional): specifies which + operations should be cascaded from the parent object to the + associated object.</para> + </callout> + + <callout arearefs="onetoone4"> + <para><literal>constrained</literal> (optional): specifies that a + foreign key constraint on the primary key of the mapped table and + references the table of the associated class. This option affects + the order in which <literal>save()</literal> and + <literal>delete()</literal> are cascaded, and determines whether + the association can be proxied. It is also used by the schema + export tool.</para> + </callout> + + <callout arearefs="onetoone5"> + <para><literal>fetch</literal> (optional - defaults to + <literal>select</literal>): chooses between outer-join fetching or + sequential select fetching.</para> + </callout> + + <callout arearefs="onetoone6"> + <para><literal>property-ref</literal> (optional): the name of a + property of the associated class that is joined to the primary key + of this class. If not specified, the primary key of the associated + class is used.</para> + </callout> + + <callout arearefs="onetoone7"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="onetoone8"> + <para><literal>formula</literal> (optional): almost all one-to-one + associations map to the primary key of the owning entity. If this + is not the case, you can specify another column, columns or + expression to join on using an SQL formula. See + <literal>org.hibernate.test.onetooneformula</literal> for an + example.</para> + </callout> + + <callout arearefs="onetoone9"> + <para><literal>lazy</literal> (optional - defaults to + <literal>proxy</literal>): by default, single point associations + are proxied. <literal>lazy="no-proxy"</literal> specifies that the + property should be fetched lazily when the instance variable is + first accessed. It requires build-time bytecode instrumentation. + <literal>lazy="false"</literal> specifies that the association + will always be eagerly fetched. <emphasis>Note that if + <literal>constrained="false"</literal>, proxying is impossible and + Hibernate will eagerly fetch the association</emphasis>.</para> + </callout> + + <callout arearefs="onetoone10"> + <para><literal>entity-name</literal> (optional): the entity name + of the associated class.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>There are two varieties of one-to-one associations:</para> + + <itemizedlist> + <listitem> + <para>primary key associations</para> + </listitem> + + <listitem> + <para>unique foreign key associations</para> + </listitem> + </itemizedlist> + + <para>Primary key associations do not need an extra table column. If two + rows are related by the association, then the two table rows share the + same primary key value. To relate two objects by a primary key + association, ensure that they are assigned the same identifier + value.</para> + + <para>For a primary key association, add the following mappings to + <literal>Employee</literal> and <literal>Person</literal> + respectively:</para> + + <programlisting role="XML">&lt;one-to-one name="person" class="Person"/&gt;</programlisting> + + <programlisting role="XML">&lt;one-to-one name="employee" class="Employee" constrained="true"/&gt;</programlisting> + + <para>Ensure that the primary keys of the related rows in the PERSON and + EMPLOYEE tables are equal. You use a special Hibernate identifier + generation strategy called <literal>foreign</literal>:</para> + + <programlisting role="XML">&lt;class name="person" table="PERSON"&gt; + &lt;id name="id" column="PERSON_ID"&gt; + &lt;generator class="foreign"&gt; + &lt;param name="property"&gt;employee&lt;/param&gt; + &lt;/generator&gt; + &lt;/id&gt; + ... + &lt;one-to-one name="employee" + class="Employee" + constrained="true"/&gt; +&lt;/class&gt;</programlisting> + + <para>A newly saved instance of <literal>Person</literal> is assigned + the same primary key value as the <literal>Employee</literal> instance + referred with the <literal>employee</literal> property of that + <literal>Person</literal>.</para> + + <para>Alternatively, a foreign key with a unique constraint, from + <literal>Employee</literal> to <literal>Person</literal>, can be + expressed as:</para> + + <programlisting role="XML">&lt;many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/&gt;</programlisting> + + <para>This association can be made bidirectional by adding the following + to the <literal>Person</literal> mapping:</para> + + <programlisting role="XML">&lt;one-to-one name="employee" class="Employee" property-ref="person"/&gt;</programlisting> + </section> + + <section id="mapping-declaration-naturalid"> + <title>Natural-id</title> + + <para>Although we recommend the use of surrogate keys as primary keys, + you should try to identify natural keys for all entities. A natural key + is a property or combination of properties that is unique and non-null. + It is also immutable. Map the properties of the natural key as + <classname>@NaturalId</classname> or map them inside the + <literal>&lt;natural-id&gt;</literal> element. Hibernate will generate + the necessary unique key and nullability constraints and, as a result, + your mapping will be more self-documenting.</para> + + <programlisting language="JAVA" role="JAVA">@Entity +public class Citizen { + @Id + @GeneratedValue + private Integer id; + private String firstname; + private String lastname; + + @NaturalId + @ManyToOne + private State state; + + @NaturalId + private String ssn; + ... +} + + + +//and later on query +List results = s.createCriteria( Citizen.class ) + .add( Restrictions.naturalId().set( "ssn", "1234" ).set( "state", ste ) ) + .list();</programlisting> + + <para>Or in XML,</para> + + <programlisting role="XML">&lt;natural-id mutable="true|false"/&gt; + &lt;property ... /&gt; + &lt;many-to-one ... /&gt; + ...... +&lt;/natural-id&gt;</programlisting> + + <para>It is recommended that you implement <literal>equals()</literal> + and <literal>hashCode()</literal> to compare the natural key properties + of the entity.</para> + + <para>This mapping is not intended for use with entities that have + natural primary keys.</para> + + <itemizedlist spacing="compact"> + <listitem> + <para><literal>mutable</literal> (optional - defaults to + <literal>false</literal>): by default, natural identifier properties + are assumed to be immutable (constant).</para> + </listitem> + </itemizedlist> + </section> + + <section id="mapping-declaration-component"> + <title>Embedded objects (aka components)</title> + + <para>Embeddable objects (or components) are objects whose properties + are mapped to the same table as the owning entity's table. Components + can, in turn, declare their own properties, components or + collections</para> + + <para>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" role="JAVA">@Entity +public class Person implements Serializable { + + // Persistent component using defaults + Address homeAddress; + + @Embedded + @AttributeOverrides( { + @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ), + @AttributeOverride(name="name", column = @Column(name="bornCountryName") ) + } ) + Country bornIn; + ... +} </programlisting> + + <programlisting language="JAVA" role="JAVA">@Embeddable +public class Address implements Serializable { + String city; + Country nationality; //no overriding here +} </programlisting> + + <programlisting language="JAVA" role="JAVA">@Embeddable +public class Country implements Serializable { + private String iso2; + @Column(name="countryName") private String name; + + public String getIso2() { return iso2; } + public void setIso2(String iso2) { this.iso2 = iso2; } + + + public String getName() { return name; } + public void setName(String name) { this.name = name; } + ... +} </programlisting> + + <para>An embeddable object inherits the access type of its owning entity + (note that you can override that using the <literal>@Access</literal> + annotation).</para> + + <para>The <literal>Person</literal> entity has two component properties, + <literal>homeAddress</literal> and <literal>bornIn</literal>. + <literal>homeAddress</literal> property has not been annotated, but + Hibernate will guess that it is a persistent component by looking for + the <literal>@Embeddable</literal> annotation in the Address class. We + also override the mapping of a column name (to + <literal>bornCountryName</literal>) with the + <literal>@Embedded</literal> and <literal>@AttributeOverride + </literal>annotations for each mapped attribute of + <literal>Country</literal>. As you can see, <literal>Country + </literal>is also a nested component of <literal>Address</literal>, + again using auto-detection by Hibernate and JPA defaults. Overriding + columns of embedded objects of embedded objects is through dotted + expressions.</para> + + <programlisting language="JAVA" role="JAVA"> @Embedded + @AttributeOverrides( { + @AttributeOverride(name="city", column = @Column(name="fld_city") ), + @AttributeOverride(name="nationality.iso2", column = @Column(name="nat_Iso2") ), + @AttributeOverride(name="nationality.name", column = @Column(name="nat_CountryName") ) + //nationality columns in homeAddress are overridden + } ) + Address homeAddress;</programlisting> + + <para>Hibernate Annotations supports something that is not explicitly + supported by the JPA 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 informations).</para> + + <para>You can also use association annotations in an embeddable object + (ie <literal>@OneToOne</literal>, <classname>@ManyToOne</classname>, + <classname>@OneToMany</classname> or <literal>@ManyToMany</literal>). To + override the association columns you can use + <literal&gt;(a)AssociationOverride&lt;/literal&gt;.&lt;/para&gt; + + <para>If you want to have the same embeddable object type twice in the + same entity, the column name defaulting will not work as several + embedded objects would share the same set of columns. In plain JPA, you + need to override at least one set of columns. Hibernate, however, allows + you to enhance the default naming mechanism through the + <classname>NamingStrategy</classname> interface. You can write a + strategy that prevent name clashing in such a situation. + <classname>DefaultComponentSafeNamingStrategy</classname> is an example + of this.</para> + + <para>If a property of the embedded object points back to the owning + entity, annotate it with the <classname>@Parent</classname> annotation. + Hibernate will make sure this property is properly loaded with the + entity reference.</para> + + <para>In XML, use the <literal>&lt;component&gt;</literal> + element.</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="component1" /> + + <area coords="3" id="component2" /> + + <area coords="4" id="component3" /> + + <area coords="5" id="component4" /> + + <area coords="6" id="component5" /> + + <area coords="7" id="component6" /> + + <area coords="8" id="component7" /> + + <area coords="9" id="component8" /> + </areaspec> + + <programlisting>&lt;component + name="propertyName" + class="className" + insert="true|false" + update="true|false" + access="field|property|ClassName" + lazy="true|false" + optimistic-lock="true|false" + unique="true|false" + node="element-name|." +&gt; + + &lt;property ...../&gt; + &lt;many-to-one .... /&gt; + ........ +&lt;/component&gt;</programlisting> + + <calloutlist> + <callout arearefs="component1"> + <para><literal>name</literal>: the name of the property.</para> + </callout> + + <callout arearefs="component2"> + <para><literal>class</literal> (optional - defaults to the + property type determined by reflection): the name of the component + (child) class.</para> + </callout> + + <callout arearefs="component3"> + <para><literal>insert</literal>: do the mapped columns appear in + SQL <literal>INSERTs</literal>?</para> + </callout> + + <callout arearefs="component4"> + <para><literal>update</literal>: do the mapped columns appear in + SQL <literal>UPDATEs</literal>?</para> + </callout> + + <callout arearefs="component5"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="component6"> + <para><literal>lazy</literal> (optional - defaults to + <literal>false</literal>): specifies that this component should be + fetched lazily when the instance variable is first accessed. It + requires build-time bytecode instrumentation.</para> + </callout> + + <callout arearefs="component7"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>true</literal>): specifies that updates to this component + either do or do not require acquisition of the optimistic lock. It + determines if a version increment should occur when this property + is dirty.</para> + </callout> + + <callout arearefs="component8"> + <para><literal>unique</literal> (optional - defaults to + <literal>false</literal>): specifies that a unique constraint + exists upon all mapped columns of the component.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>The child <literal>&lt;property&gt;</literal> tags map properties + of the child class to table columns.</para> + + <para>The <literal>&lt;component&gt;</literal> element allows a + <literal>&lt;parent&gt;</literal> subelement that maps a property of the + component class as a reference back to the containing entity.</para> + + <para>The <literal>&lt;dynamic-component&gt;</literal> element allows a + <literal>Map</literal> to be mapped as a component, where the property + names refer to keys of the map. See <xref + linkend="components-dynamic" /> for more information. This feature is + not supported in annotations.</para> + </section> + + <section id="mapping-declaration-properties" revision="2"> + <title>Properties</title> + + <para>The <literal>&lt;properties&gt;</literal> element allows the + definition of a named, logical grouping of the properties of a class. + The most important use of the construct is that it allows a combination + of properties to be the target of a <literal>property-ref</literal>. It + is also a convenient way to define a multi-column unique constraint. For + example:</para> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="properties1" /> + + <area coords="3" id="properties2" /> + + <area coords="4" id="properties3" /> + + <area coords="5" id="properties4" /> + + <area coords="6" id="properties5" /> + </areaspec> + + <programlisting>&lt;properties + name="logicalName" + insert="true|false" + update="true|false" + optimistic-lock="true|false" + unique="true|false" +&gt; + + &lt;property ...../&gt; + &lt;many-to-one .... /&gt; + ........ +&lt;/properties&gt;</programlisting> + + <calloutlist> + <callout arearefs="properties1"> + <para><literal>name</literal>: the logical name of the grouping. + It is <emphasis>not</emphasis> an actual property name.</para> + </callout> + + <callout arearefs="properties2"> + <para><literal>insert</literal>: do the mapped columns appear in + SQL <literal>INSERTs</literal>?</para> + </callout> + + <callout arearefs="properties3"> + <para><literal>update</literal>: do the mapped columns appear in + SQL <literal>UPDATEs</literal>?</para> + </callout> + + <callout arearefs="properties4"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>true</literal>): specifies that updates to these + properties either do or do not require acquisition of the + optimistic lock. It determines if a version increment should occur + when these properties are dirty.</para> + </callout> + + <callout arearefs="properties5"> + <para><literal>unique</literal> (optional - defaults to + <literal>false</literal>): specifies that a unique constraint + exists upon all mapped columns of the component.</para> + </callout> + </calloutlist> + </programlistingco> + + <para>For example, if we have the following + <literal>&lt;properties&gt;</literal> mapping:</para> + + <programlisting role="XML">&lt;class name="Person"&gt; + &lt;id name="personNumber"/&gt; + + ... + &lt;properties name="name" + unique="true" update="false"&gt; + &lt;property name="firstName"/&gt; + &lt;property name="initial"/&gt; + &lt;property name="lastName"/&gt; + &lt;/properties&gt; +&lt;/class&gt;</programlisting> + + <para>You might have some legacy data association that refers to this + unique key of the <literal>Person</literal> table, instead of to the + primary key:</para> + + <programlisting role="XML">&lt;many-to-one name="owner" + class="Person" property-ref="name"&gt; + &lt;column name="firstName"/&gt; + &lt;column name="initial"/&gt; + &lt;column name="lastName"/&gt; +&lt;/many-to-one&gt;</programlisting> + + <note> + <para>When using annotations as a mapping strategy, such construct is + not necessary as the binding between a column and its related column + on the associated table is done directly</para> + + <programlisting>@Entity +class Person { + @Id Integer personNumber; + String firstName; + @Column(name="I") + String initial; + String lastName; +} + +@Entity +class Home { + @ManyToOne + @JoinColumns({ + @JoinColumn(name="first_name", referencedColumnName="firstName"), + @JoinColumn(name="init", referencedColumnName="I"), + @JoinColumn(name="last_name", referencedColumnName="lastName"), + }) + Person owner +}</programlisting> + </note> + + <para>The use of this outside the context of mapping legacy data is not + recommended.</para> + </section> + + <section id="mapping-types-anymapping" revision="2"> + <title>Any</title> + + <para>There is one more type of property mapping. The + <classname>@Any</classname> mapping defines a polymorphic association to + classes from multiple tables. This type of mapping requires more than + one column. The first column contains the type of the associated entity. + The remaining columns contain the identifier. It is impossible to + specify a foreign key constraint for this kind of association. This is + not the usual way of mapping polymorphic associations and you should use + this only in special cases. For example, for audit logs, user session + data, etc.</para> + + <para>The <classname>@Any</classname> 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. The <literal>metaType</literal> attribute allows + the application to specify a custom type that maps database column + values to persistent classes that have identifier properties of the type + specified by <literal>idType</literal>. You must specify the mapping + from values of the <literal>metaType</literal> to class names.</para> + + <programlisting language="JAVA" role="JAVA">@Any( metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER ) +@AnyMetaDef( + idType = "integer", + metaType = "string", + metaValues = { + @MetaValue( value = "S", targetEntity = StringProperty.class ), + @MetaValue( value = "I", targetEntity = IntegerProperty.class ) + } ) +@JoinColumn( name = "property_id" ) +public Property getMainProperty() { + return mainProperty; +}</programlisting> + + <para>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" role="JAVA">//on a package +@AnyMetaDef( name="property" + idType = "integer", + metaType = "string", + metaValues = { + @MetaValue( value = "S", targetEntity = StringProperty.class ), + @MetaValue( value = "I", targetEntity = IntegerProperty.class ) + } ) +package org.hibernate.test.annotations.any; + + +//in a class + @Any( metaDef="property", metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER ) + @JoinColumn( name = "property_id" ) + public Property getMainProperty() { + return mainProperty; + }</programlisting> + + <para>The hbm.xml equivalent is:</para> + + <programlisting role="XML">&lt;any name="being" id-type="long" meta-type="string"&gt; + &lt;meta-value value="TBL_ANIMAL" class="Animal"/&gt; + &lt;meta-value value="TBL_HUMAN" class="Human"/&gt; + &lt;meta-value value="TBL_ALIEN" class="Alien"/&gt; + &lt;column name="table_name"/&gt; + &lt;column name="id"/&gt; +&lt;/any&gt;</programlisting> + + <note> + <para>You cannot mutualize the metadata in hbm.xml as you can in + annotations.</para> + </note> + + <programlistingco role="XML"> + <areaspec> + <area coords="2" id="any1" /> + + <area coords="3" id="any2" /> + + <area coords="4" id="any3" /> + + <area coords="5" id="any4" /> + + <area coords="6" id="any5" /> + + <area coords="7" id="any6" /> + </areaspec> + + <programlisting>&lt;any + name="propertyName" + id-type="idtypename" + meta-type="metatypename" + cascade="cascade_style" + access="field|property|ClassName" + optimistic-lock="true|false" +&gt; + &lt;meta-value ... /&gt; + &lt;meta-value ... /&gt; + ..... + &lt;column .... /&gt; + &lt;column .... /&gt; + ..... +&lt;/any&gt;</programlisting> + + <calloutlist> + <callout arearefs="any1"> + <para><literal>name</literal>: the property name.</para> + </callout> + + <callout arearefs="any2"> + <para><literal>id-type</literal>: the identifier type.</para> + </callout> + + <callout arearefs="any3"> + <para><literal>meta-type</literal> (optional - defaults to + <literal>string</literal>): any type that is allowed for a + discriminator mapping.</para> + </callout> + + <callout arearefs="any4"> + <para><literal>cascade</literal> (optional- defaults to + <literal>none</literal>): the cascade style.</para> + </callout> + + <callout arearefs="any5"> + <para><literal>access</literal> (optional - defaults to + <literal>property</literal>): the strategy Hibernate uses for + accessing the property value.</para> + </callout> + + <callout arearefs="any6"> + <para><literal>optimistic-lock</literal> (optional - defaults to + <literal>true</literal>): specifies that updates to this property + either do or do not require acquisition of the optimistic lock. It + defines whether a version increment should occur if this property + is dirty.</para> + </callout> + </calloutlist> + </programlistingco> + </section> + </section> + + <section id="mapping-types"> + <title>Hibernate types</title> + + <section id="mapping-types-entitiesvalues" revision="1"> + <title>Entities and values</title> + + <para>In relation to the persistence service, Java language-level + objects are classified into two groups:</para> + + <para>An <emphasis>entity</emphasis> exists independently of any other + objects holding references to the entity. Contrast this with the usual + Java model, where an unreferenced object is garbage collected. Entities + must be explicitly saved and deleted. Saves and deletions, however, can + be <emphasis>cascaded</emphasis> from a parent entity to its children. + This is different from the ODMG model of object persistence by + reachability and corresponds more closely to how application objects are + usually used in large systems. Entities support circular and shared + references. They can also be versioned.</para> + + <para>An entity's persistent state consists of references to other + entities and instances of <emphasis>value</emphasis> types. Values are + primitives: collections (not what is inside a collection), components + and certain immutable objects. Unlike entities, values in particular + collections and components, <emphasis>are</emphasis> persisted and + deleted by reachability. Since value objects and primitives are + persisted and deleted along with their containing entity, they cannot be + independently versioned. Values have no independent identity, so they + cannot be shared by two entities or collections.</para> + + <para>Until now, we have been using the term "persistent class" to refer + to entities. We will continue to do that. Not all user-defined classes + with a persistent state, however, are entities. A + <emphasis>component</emphasis> is a user-defined class with value + semantics. A Java property of type <literal>java.lang.String</literal> + also has value semantics. Given this definition, all types (classes) + provided by the JDK have value type semantics in Java, while + user-defined types can be mapped with entity or value type semantics. + This decision is up to the application developer. An entity class in a + domain model will normally have shared references to a single instance + of that class, while composition or aggregation usually translates to a + value type.</para> + + <para>We will revisit both concepts throughout this reference + guide.</para> + + <para>The challenge is to map the Java type system, and the developers' + definition of entities and value types, to the SQL/database type system. + The bridge between both systems is provided by Hibernate. For entities, + <literal>&lt;class&gt;</literal>, <literal>&lt;subclass&gt;</literal> + and so on are used. For value types we use + <literal>&lt;property&gt;</literal>, + <literal>&lt;component&gt;</literal>etc., that usually have a + <literal>type</literal> attribute. The value of this attribute is the + name of a Hibernate <emphasis>mapping type</emphasis>. Hibernate + provides a range of mappings for standard JDK value types out of the + box. You can write your own mapping types and implement your own custom + conversion strategies.</para> + + <para>With the exception of collections, all built-in Hibernate types + support null semantics.</para> + </section> + + <section id="mapping-types-basictypes" revision="3"> + <title>Basic value types</title> + + <para>The built-in <emphasis>basic mapping types</emphasis> can be + roughly categorized into the following: <variablelist> + <varlistentry> + <term><literal>integer, long, short, float, double, character, + byte, boolean, yes_no, true_false</literal></term> + + <listitem> + <para>Type mappings from Java primitives or wrapper classes to + appropriate (vendor-specific) SQL column types. + <literal>boolean, yes_no</literal> and + <literal>true_false</literal> are all alternative encodings for + a Java <literal>boolean</literal> or + <literal>java.lang.Boolean</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>string</literal></term> + + <listitem> + <para>A type mapping from <literal>java.lang.String</literal> to + <literal>VARCHAR</literal> (or Oracle + <literal>VARCHAR2</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>date, time, timestamp</literal></term> + + <listitem> + <para>Type mappings from <literal>java.util.Date</literal> and + its subclasses to SQL types <literal>DATE</literal>, + <literal>TIME</literal> and <literal>TIMESTAMP</literal> (or + equivalent).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>calendar, calendar_date</literal></term> + + <listitem> + <para>Type mappings from <literal>java.util.Calendar</literal> + to SQL types <literal>TIMESTAMP</literal> and + <literal>DATE</literal> (or equivalent).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>big_decimal, big_integer</literal></term> + + <listitem> + <para>Type mappings from <literal>java.math.BigDecimal</literal> + and <literal>java.math.BigInteger</literal> to + <literal>NUMERIC</literal> (or Oracle + <literal>NUMBER</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>locale, timezone, currency</literal></term> + + <listitem> + <para>Type mappings from <literal>java.util.Locale</literal>, + <literal>java.util.TimeZone</literal> and + <literal>java.util.Currency</literal> to + <literal>VARCHAR</literal> (or Oracle + <literal>VARCHAR2</literal>). Instances of + <literal>Locale</literal> and <literal>Currency</literal> are + mapped to their ISO codes. Instances of + <literal>TimeZone</literal> are mapped to their + <literal>ID</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class</literal></term> + + <listitem> + <para>A type mapping from <literal>java.lang.Class</literal> to + <literal>VARCHAR</literal> (or Oracle + <literal>VARCHAR2</literal>). A <literal>Class</literal> is + mapped to its fully qualified name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>binary</literal></term> + + <listitem> + <para>Maps byte arrays to an appropriate SQL binary type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>text</literal></term> + + <listitem> + <para>Maps long Java strings to a SQL <literal>CLOB</literal> or + <literal>TEXT</literal> type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>serializable</literal></term> + + <listitem> + <para>Maps serializable Java types to an appropriate SQL binary + type. You can also indicate the Hibernate type + <literal>serializable</literal> with the name of a serializable + Java class or interface that does not default to a basic + type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>clob, blob</literal></term> + + <listitem> + <para>Type mappings for the JDBC classes + <literal>java.sql.Clob</literal> and + <literal>java.sql.Blob</literal>. These types can be + inconvenient for some applications, since the blob or clob + object cannot be reused outside of a transaction. Driver support + is patchy and inconsistent.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>imm_date, imm_time, imm_timestamp, imm_calendar, + imm_calendar_date, imm_serializable, imm_binary</literal></term> + + <listitem> + <para>Type mappings for what are considered mutable Java types. + This is where Hibernate makes certain optimizations appropriate + only for immutable Java types, and the application treats the + object as immutable. For example, you should not call + <literal>Date.setTime()</literal> for an instance mapped as + <literal>imm_timestamp</literal>. To change the value of the + property, and have that change made persistent, the application + must assign a new, nonidentical, object to the property.</para> + </listitem> + </varlistentry> + </variablelist></para> + + <para>Unique identifiers of entities and collections can be of any basic + type except <literal>binary</literal>, <literal>blob</literal> and + <literal>clob</literal>. Composite identifiers are also allowed. See + below for more information.</para> + + <para>The basic value types have corresponding <literal>Type</literal> + constants defined on <literal>org.hibernate.Hibernate</literal>. For + example, <literal>Hibernate.STRING</literal> represents the + <literal>string</literal> type.</para> + </section> + + <section id="mapping-types-custom" revision="2"> + <title>Custom value types</title> + + <para>It is relatively easy for developers to create their own value + types. For example, you might want to persist properties of type + <literal>java.lang.BigInteger</literal> to <literal>VARCHAR</literal> + columns. Hibernate does not provide a built-in type for this. Custom + types are not limited to mapping a property, or collection element, to a + single table column. So, for example, you might have a Java property + <literal>getName()</literal>/<literal>setName()</literal> of type + <literal>java.lang.String</literal> that is persisted to the columns + <literal>FIRST_NAME</literal>, <literal>INITIAL</literal>, + <literal>SURNAME</literal>.</para> + + <para>To implement a custom type, implement either + <literal>org.hibernate.UserType</literal> or + <literal>org.hibernate.CompositeUserType</literal> and declare + properties using the fully qualified classname of the type. View + <literal>org.hibernate.test.DoubleStringType</literal> to see the kind + of things that are possible.</para> + + <programlisting role="XML">&lt;property name="twoStrings" type="org.hibernate.test.DoubleStringType"&gt; + &lt;column name="first_string"/&gt; + &lt;column name="second_string"/&gt; +&lt;/property&gt;</programlisting> + + <para>Notice the use of <literal>&lt;column&gt;</literal> tags to map a + property to multiple columns.</para> + + <para>The <literal>CompositeUserType</literal>, + <literal>EnhancedUserType</literal>, + <literal>UserCollectionType</literal>, and + <literal>UserVersionType</literal> interfaces provide support for more + specialized uses.</para> + + <para>You can even supply parameters to a <literal>UserType</literal> in + the mapping file. To do this, your <literal>UserType</literal> must + implement the + <literal>org.hibernate.usertype.ParameterizedType</literal> interface. + To supply parameters to your custom type, you can use the + <literal>&lt;type&gt;</literal> element in your mapping files.</para> + + <programlisting role="XML">&lt;property name="priority"&gt; + &lt;type name="com.mycompany.usertypes.DefaultValueIntegerType"&gt; + &lt;param name="default"&gt;0&lt;/param&gt; + &lt;/type&gt; +&lt;/property&gt;</programlisting> + + <para>The <literal>UserType</literal> can now retrieve the value for the + parameter named <literal>default</literal> from the + <literal>Properties</literal> object passed to it.</para> + + <para>If you regularly use a certain <literal>UserType</literal>, it is + useful to define a shorter name for it. You can do this using the + <literal>&lt;typedef&gt;</literal> element. Typedefs assign a name to a + custom type, and can also contain a list of default parameter values if + the type is parameterized.</para> + + <programlisting role="XML">&lt;typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero"&gt; + &lt;param name="default"&gt;0&lt;/param&gt; +&lt;/typedef&gt;</programlisting> + + <programlisting role="XML">&lt;property name="priority" type="default_zero"/&gt;</programlisting> + + <para>It is also possible to override the parameters supplied in a + typedef on a case-by-case basis by using type parameters on the property + mapping.</para> + + <para>Even though Hibernate's rich range of built-in types and support + for components means you will rarely need to use a custom type, it is + considered good practice to use custom types for non-entity classes that + occur frequently in your application. For example, a + <literal>MonetaryAmount</literal> class is a good candidate for a + <literal>CompositeUserType</literal>, even though it could be mapped as + a component. One reason for this is abstraction. With a custom type, + your mapping documents would be protected against changes to the way + monetary values are represented.</para> + </section> + </section> + + <section id="mapping-entityname"> + <title>Mapping a class more than once</title> + + <para>It is possible to provide more than one mapping for a particular + persistent class. In this case, you must specify an <emphasis>entity + name</emphasis> to disambiguate between instances of the two mapped + entities. By default, the entity name is the same as the class name. + Hibernate lets you specify the entity name when working with persistent + objects, when writing queries, or when mapping associations to the named + entity.</para> + + <programlisting>&lt;class name="Contract" table="Contracts" + entity-name="CurrentContract"&gt; + ... + &lt;set name="history" inverse="true" + order-by="effectiveEndDate desc"&gt; + &lt;key column="currentContractId"/&gt; + &lt;one-to-many entity-name="HistoricalContract"/&gt; + &lt;/set&gt; +&lt;/class&gt; + +&lt;class name="Contract" table="ContractHistory" + entity-name="HistoricalContract"&gt; + ... + &lt;many-to-one name="currentContract" + column="currentContractId" + entity-name="CurrentContract"/&gt; +&lt;/class&gt;</programlisting> + + <para>Associations are now specified using <literal>entity-name</literal> + instead of <literal>class</literal>.</para> + + <note> + <para>This feature is not supported in Annotations</para> + </note> + </section> + + <section id="mapping-quotedidentifiers"> + <title>SQL quoted identifiers</title> + + <para>You can force Hibernate to quote an identifier in the generated SQL + by enclosing the table or column name in backticks in the mapping + document. Hibernate will use the correct quotation style for the SQL + <literal>Dialect</literal>. This is usually double quotes, but the SQL + Server uses brackets and MySQL uses backticks.</para> + + <programlisting role="XML">@Entity @Table(name="`Line Item`") +class LineItem { + @id @Column(name="`Item Id`") Integer id; + @Column(name="`Item #`") int itemNumber +} + +&lt;class name="LineItem" table="`Line Item`"&gt; + &lt;id name="id" column="`Item Id`"/&gt;&lt;generator class="assigned"/&gt;&lt;/id&gt; + &lt;property name="itemNumber" column="`Item #`"/&gt; + ... +&lt;/class&gt;</programlisting> + </section> + + <section id="mapping-generated" revision="1"> + <title>Generated properties</title> + + <para>Generated properties are properties that have their values generated + by the database. Typically, Hibernate applications needed to + <literal>refresh</literal> objects that contain any properties for which + the database was generating values. Marking properties as generated, + however, lets the application delegate this responsibility to Hibernate. + When Hibernate issues an SQL INSERT or UPDATE for an entity that has + defined generated properties, it immediately issues a select afterwards to + retrieve the generated values.</para> + + <para>Properties marked as generated must additionally be non-insertable + and non-updateable. Only <link + linkend="mapping-declaration-version">versions</link>, <link + linkend="mapping-declaration-timestamp">timestamps</link>, and <link + linkend="mapping-declaration-property">simple properties</link>, can be + marked as generated.</para> + + <para><literal>never</literal> (the default): the given property value is + not generated within the database.</para> + + <para><literal>insert</literal>: the given property value is generated on + insert, but is not regenerated on subsequent updates. Properties like + created-date fall into this category. Even though <link + linkend="mapping-declaration-version">version</link> and <link + linkend="mapping-declaration-timestamp">timestamp</link> properties can be + marked as generated, this option is not available.</para> + + <para><literal>always</literal>: the property value is generated both on + insert and on update.</para> + + <para>To mark a property as generated, use + <classname&gt;(a)Generated&lt;/classname&gt;.&lt;/para&gt; + </section> + + <section id="mapping-column-read-and-write" revision="1"> + <title>Column read and write expressions</title> + + <para>Hibernate allows you to customize the SQL it uses to read and write + the values of columns mapped to <link + linkend="mapping-declaration-property">simple properties</link>. For + example, if your database provides a set of data encryption functions, you + can invoke them for individual columns like this: <programlisting + role="XML">&lt;property name="creditCardNumber"&gt; + &lt;column + name="credit_card_num" + read="decrypt(credit_card_num)" + write="encrypt(?)"/&gt; +&lt;/property&gt;</programlisting></para> + + <para>Hibernate applies the custom expressions automatically whenever the + property is referenced in a query. This functionality is similar to a + derived-property <literal>formula</literal> with two differences: + <itemizedlist spacing="compact"> + <listitem> + <para>The property is backed by one or more columns that are + exported as part of automatic schema generation.</para> + </listitem> + + <listitem> + <para>The property is read-write, not read-only.</para> + </listitem> + </itemizedlist></para> + + <para>The <literal>write</literal> expression, if specified, must contain + exactly one '?' placeholder for the value.</para> + + <note> + <para>This feature is not supported in Annotations</para> + </note> + </section> + + <section id="mapping-database-object"> + <title>Auxiliary database objects</title> + + <para>Auxiliary database objects allow for the CREATE and DROP of + arbitrary database objects. In conjunction with Hibernate's schema + evolution tools, they have the ability to fully define a user schema + within the Hibernate mapping files. Although designed specifically for + creating and dropping things like triggers or stored procedures, any SQL + command that can be run via a + <literal>java.sql.Statement.execute()</literal> method is valid (for + example, ALTERs, INSERTS, etc.). There are essentially two modes for + defining auxiliary database objects:</para> + + <para>The first mode is to explicitly list the CREATE and DROP commands in + the mapping file:</para> + + <programlisting role="XML">&lt;hibernate-mapping&gt; + ... + &lt;database-object&gt; + &lt;create&gt;CREATE TRIGGER my_trigger ...&lt;/create&gt; + &lt;drop&gt;DROP TRIGGER my_trigger&lt;/drop&gt; + &lt;/database-object&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <para>The second mode is to supply a custom class that constructs the + CREATE and DROP commands. This custom class must implement the + <literal>org.hibernate.mapping.AuxiliaryDatabaseObject</literal> + interface.</para> + + <programlisting role="XML">&lt;hibernate-mapping&gt; + ... + &lt;database-object&gt; + &lt;definition class="MyTriggerDefinition"/&gt; + &lt;/database-object&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <para>Additionally, these database objects can be optionally scoped so + that they only apply when certain dialects are used.</para> + + <programlisting role="XML">&lt;hibernate-mapping&gt; + ... + &lt;database-object&gt; + &lt;definition class="MyTriggerDefinition"/&gt; + &lt;dialect-scope name="org.hibernate.dialect.Oracle9iDialect"/&gt; + &lt;dialect-scope name="org.hibernate.dialect.Oracle10gDialect"/&gt; + &lt;/database-object&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <note> + <para>This feature is not supported in Annotations</para> + </note> + </section> +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/batch.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/batch.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/batch.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,381 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="batch"> + <title>Batch processing</title> + + <para> + A naive approach to inserting 100,000 rows in the database using Hibernate might + look like this: + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); +for ( int i=0; i<100000; i++ ) { + Customer customer = new Customer(.....); + session.save(customer); +} +tx.commit(); +session.close();]]></programlisting> + + <para> + This would fall over with an <literal>OutOfMemoryException</literal> somewhere + around the 50,000th row. That is because Hibernate caches all the newly inserted + <literal>Customer</literal> instances in the session-level cache. In this chapter + we will show you how to avoid this problem. + </para> + + <para> + + If you are undertaking batch processing you will need to enable the use of + JDBC batching. This is absolutely essential if you want to achieve optimal performance. + Set the JDBC batch size to a reasonable number (10-50, for example): + </para> + +<programlisting><![CDATA[hibernate.jdbc.batch_size 20]]></programlisting> + + <para id="disablebatching" revision="1"> + Hibernate disables insert batching at the JDBC level transparently if you + use an <literal>identity</literal> identifier generator. + </para> + + <para> + You can also do this kind of work in a process where interaction with + the second-level cache is completely disabled: + </para> + +<programlisting><![CDATA[hibernate.cache.use_second_level_cache false]]></programlisting> + + <para> + However, this is not absolutely necessary, since we can explicitly set the + <literal>CacheMode</literal> to disable interaction with the second-level cache. + </para> + + <section id="batch-inserts"> + <title>Batch inserts</title> + + <para> + When making new objects persistent <literal>flush()</literal> and + then <literal>clear()</literal> the session regularly in order to control the size of + the first-level cache. + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +for ( int i=0; i<100000; i++ ) { + Customer customer = new Customer(.....); + session.save(customer); + if ( i % 20 == 0 ) { //20, same as the JDBC batch size + //flush a batch of inserts and release memory: + session.flush(); + session.clear(); + } +} + +tx.commit(); +session.close();]]></programlisting> + + </section> + + <section id="batch-update" > + <title>Batch updates</title> + + <para> + For retrieving and updating data, the same ideas apply. In addition, you need to + use <literal>scroll()</literal> to take advantage of server-side cursors for + queries that return many rows of data. + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +ScrollableResults customers = session.getNamedQuery("GetCustomers") + .setCacheMode(CacheMode.IGNORE) + .scroll(ScrollMode.FORWARD_ONLY); +int count=0; +while ( customers.next() ) { + Customer customer = (Customer) customers.get(0); + customer.updateStuff(...); + if ( ++count % 20 == 0 ) { + //flush a batch of updates and release memory: + session.flush(); + session.clear(); + } +} + +tx.commit(); +session.close();]]></programlisting> + + </section> + + <section id="batch-statelesssession"> + <title>The StatelessSession interface</title> + <para> + Alternatively, Hibernate provides a command-oriented API that can be used for + streaming data to and from the database in the form of detached objects. A + <literal>StatelessSession</literal> has no persistence context associated + with it and does not provide many of the higher-level life cycle semantics. + In particular, a stateless session does not implement a first-level cache nor + interact with any second-level or query cache. It does not implement + transactional write-behind or automatic dirty checking. Operations performed + using a stateless session never cascade to associated instances. Collections + are ignored by a stateless session. Operations performed via a stateless session + bypass Hibernate's event model and interceptors. Due to the lack of a first-level cache, + Stateless sessions are vulnerable to data aliasing effects. A stateless + session is a lower-level abstraction that is much closer to the underlying JDBC. + </para> + +<programlisting role="JAVA"><![CDATA[StatelessSession session = sessionFactory.openStatelessSession(); +Transaction tx = session.beginTransaction(); + +ScrollableResults customers = session.getNamedQuery("GetCustomers") + .scroll(ScrollMode.FORWARD_ONLY); +while ( customers.next() ) { + Customer customer = (Customer) customers.get(0); + customer.updateStuff(...); + session.update(customer); +} + +tx.commit(); +session.close();]]></programlisting> + + <para> + In this code example, the <literal>Customer</literal> instances returned + by the query are immediately detached. They are never associated with any persistence + context. + </para> + + <para> + The <literal>insert(), update()</literal> and <literal>delete()</literal> operations + defined by the <literal>StatelessSession</literal> interface are considered to be + direct database row-level operations. They result in the immediate execution of a SQL + <literal>INSERT, UPDATE</literal> or <literal>DELETE</literal> respectively. + They have different semantics to the <literal>save(), saveOrUpdate()</literal> + and <literal>delete()</literal> operations defined by the <literal>Session</literal> + interface. + </para> + + </section> + + <section id="batch-direct" revision="3"> + <title>DML-style operations</title> + + <para> + As already discussed, automatic and transparent object/relational mapping is concerned + with the management of the object state. The object state is available in memory. This means that manipulating data directly in the database (using the SQL <literal>Data Manipulation Language</literal> + (DML) the statements: <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>) + will not affect in-memory state. However, Hibernate provides methods + for bulk SQL-style DML statement execution that is performed through the + Hibernate Query Language (<link linkend="queryhql">HQL</link>). + </para> + + <para> + The pseudo-syntax for <literal>UPDATE</literal> and <literal>DELETE</literal> statements + is: <literal>( UPDATE | DELETE ) FROM? EntityName (WHERE where_conditions)?</literal>. + </para> + + <para> + Some points to note: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + In the from-clause, the FROM keyword is optional + </para> + </listitem> + <listitem> + <para> + There can only be a single entity named in the from-clause. It can, however, be + aliased. If the entity name is aliased, then any property references must + be qualified using that alias. If the entity name is not aliased, then it is + illegal for any property references to be qualified. + </para> + </listitem> + <listitem> + <para> + No <link linkend="queryhql-joins-forms">joins</link>, either implicit or explicit, + can be specified in a bulk HQL query. Sub-queries can be used in the where-clause, where + the subqueries themselves may contain joins. + </para> + </listitem> + <listitem> + <para> + The where-clause is also optional. + </para> + </listitem> + </itemizedlist> + + <para> + As an example, to execute an HQL <literal>UPDATE</literal>, use the + <literal>Query.executeUpdate()</literal> method. The method is named for + those familiar with JDBC's <literal>PreparedStatement.executeUpdate()</literal>: + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlUpdate = "update Customer c set c.name = :newName where c.name = :oldName"; +// or String hqlUpdate = "update Customer set name = :newName where name = :oldName"; +int updatedEntities = s.createQuery( hqlUpdate ) + .setString( "newName", newName ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + In keeping with the EJB3 specification, HQL <literal>UPDATE</literal> statements, by default, do not effect the + <link linkend="mapping-declaration-version">version</link> + or the <link linkend="mapping-declaration-timestamp">timestamp</link> property values + for the affected entities. However, + you can force Hibernate to reset the <literal>version</literal> or + <literal>timestamp</literal> property values through the use of a <literal>versioned update</literal>. + This is achieved by adding the <literal>VERSIONED</literal> keyword after the <literal>UPDATE</literal> + keyword. + </para> +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); +String hqlVersionedUpdate = "update versioned Customer set name = :newName where name = :oldName"; +int updatedEntities = s.createQuery( hqlUpdate ) + .setString( "newName", newName ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + Custom version types, <literal>org.hibernate.usertype.UserVersionType</literal>, + are not allowed in conjunction with a <literal>update versioned</literal> statement. + </para> + + <para> + To execute an HQL <literal>DELETE</literal>, use the same <literal>Query.executeUpdate()</literal> + method: + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlDelete = "delete Customer c where c.name = :oldName"; +// or String hqlDelete = "delete Customer where name = :oldName"; +int deletedEntities = s.createQuery( hqlDelete ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + The <literal>int</literal> value returned by the <literal>Query.executeUpdate()</literal> + method indicates the number of entities effected by the operation. This may or may not + correlate to the number of rows effected in the database. An HQL 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> + + <para> + The pseudo-syntax for <literal>INSERT</literal> statements is: + <literal>INSERT INTO EntityName properties_list select_statement</literal>. Some + points to note: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Only the INSERT INTO ... SELECT ... form is supported; not the INSERT INTO ... VALUES ... form. + </para> + <para> + The properties_list is analogous to the <literal>column specification</literal> + in the SQL <literal>INSERT</literal> statement. For entities involved in mapped + inheritance, only properties directly defined on that given class-level can be + used in the properties_list. Superclass properties are not allowed and subclass + properties do not make sense. In other words, <literal>INSERT</literal> + statements are inherently non-polymorphic. + </para> + </listitem> + <listitem> + <para> + select_statement can be any valid HQL select query, with the caveat that the return types + must match the types expected by the insert. Currently, this is checked during query + compilation rather than allowing the check to relegate to the database. + This might, however, cause problems between Hibernate <literal>Type</literal>s which are + <emphasis>equivalent</emphasis> as opposed to <emphasis>equal</emphasis>. This might cause + issues with mismatches between a property defined as a <literal>org.hibernate.type.DateType</literal> + and a property defined as a <literal>org.hibernate.type.TimestampType</literal>, even though the + database might not make a distinction or might be able to handle the conversion. + </para> + </listitem> + <listitem> + <para> + For the id property, the insert statement gives you two options. You can either + explicitly specify the id property in the properties_list, in which case its value + is taken from the corresponding select expression, or omit it from the properties_list, + in which case a generated value is used. This latter option is only available when + using id generators that operate in the database; attempting to use this option with + any "in memory" type generators will cause an exception during parsing. + For the purposes of this discussion, in-database generators are considered to be + <literal>org.hibernate.id.SequenceGenerator</literal> (and its subclasses) and + any implementers of <literal>org.hibernate.id.PostInsertIdentifierGenerator</literal>. + The most notable exception here is <literal>org.hibernate.id.TableHiLoGenerator</literal>, + which cannot be used because it does not expose a selectable way to get its values. + </para> + </listitem> + <listitem> + <para> + For properties mapped as either <literal>version</literal> or <literal>timestamp</literal>, + the insert statement gives you two options. You can either specify the property in the + properties_list, in which case its value is taken from the corresponding select expressions, + or omit it from the properties_list, in which case the <literal>seed value</literal> defined + by the <literal>org.hibernate.type.VersionType</literal> is used. + </para> + </listitem> + </itemizedlist> + + <para> + The following is an example of an HQL <literal>INSERT</literal> statement execution: + </para> + +<programlisting role="JAVA"><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ..."; +int createdEntities = s.createQuery( hqlInsert ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/best_practices.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/best_practices.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/best_practices.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,254 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="best-practices" revision="3"> + <title>Best Practices</title> + + <variablelist spacing="compact"> + <varlistentry> + <term>Write fine-grained classes and map them using <literal>&lt;component&gt;</literal>:</term> + <listitem> + <para> + Use an <literal>Address</literal> class to encapsulate <literal>street</literal>, + <literal>suburb</literal>, <literal>state</literal>, <literal>postcode</literal>. + This encourages code reuse and simplifies refactoring. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Declare identifier properties on persistent classes:</term> + <listitem> + <para> + Hibernate makes identifier properties optional. There are a range of reasons why + you should use them. We recommend that identifiers be 'synthetic', that is, generated with + no business meaning. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Identify natural keys:</term> + <listitem> + <para> + Identify natural keys for all entities, and map them using + <literal>&lt;natural-id&gt;</literal>. Implement <literal>equals()</literal> and + <literal>hashCode()</literal> to compare the properties that make up the natural key. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Place each class mapping in its own file:</term> + <listitem> + <para> + Do not use a single monolithic mapping document. Map <literal>com.eg.Foo</literal> in + the file <literal>com/eg/Foo.hbm.xml</literal>. This makes sense, particularly in + a team environment. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Load mappings as resources:</term> + <listitem> + <para> + Deploy the mappings along with the classes they map. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Consider externalizing query strings:</term> + <listitem> + <para> + This is recommended if your queries call non-ANSI-standard SQL functions. + Externalizing the query strings to mapping files will make the application more + portable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Use bind variables.</term> + <listitem> + <para> + As in JDBC, always replace non-constant values by "?". Do not use string manipulation to + bind a non-constant value in a query. You should also consider using named parameters in + queries. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Do not manage your own JDBC connections:</term> + <listitem> + <para> + Hibernate allows the application to manage JDBC connections, but his approach should be considered + a last-resort. If you cannot use the built-in connection providers, consider providing your + own implementation of <literal>org.hibernate.connection.ConnectionProvider</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Consider using a custom type:</term> + <listitem> + <para> + Suppose you have a Java type from a library that needs to be persisted but does not + provide the accessors needed to map it as a component. You should consider implementing + <literal>org.hibernate.UserType</literal>. This approach frees the application + code from implementing transformations to/from a Hibernate type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Use hand-coded JDBC in bottlenecks:</term> + <listitem> + <para> + In performance-critical areas of the system, some kinds of operations might benefit from + direct JDBC. Do not assume, however, that JDBC is necessarily faster. Please wait until you <emphasis>know</emphasis> something is a bottleneck. + If you need to use direct JDBC, + you can open a Hibernate <literal>Session</literal>, wrap your JDBC operation as a <literal>org.hibernate.jdbc.Work</literal> object and using that JDBC connection. This + way you can still use the same transaction strategy and underlying connection provider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Understand <literal>Session</literal> flushing:</term> + <listitem> + <para> + Sometimes the Session synchronizes its persistent state with the database. Performance will + be affected if this process occurs too often. You can sometimes minimize unnecessary flushing by + disabling automatic flushing, or even by changing the order of queries and other operations within a + particular transaction. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>In a three tiered architecture, consider using detached objects:</term> + <listitem> + <para> + When using a servlet/session bean architecture, you can pass persistent objects loaded in + the session bean to and from the servlet/JSP layer. Use a new session to service each request. + Use <literal>Session.merge()</literal> or <literal>Session.saveOrUpdate()</literal> to + synchronize objects with the database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>In a two tiered architecture, consider using long persistence contexts:</term> + <listitem> + <para> + Database Transactions have to be as short as possible for best scalability. However, it is often + necessary to implement long running <emphasis>application transactions</emphasis>, a single + unit-of-work from the point of view of a user. An application transaction might span several + client request/response cycles. It is common to use detached objects to implement application + transactions. An appropriate alternative in a two tiered architecture, is to maintain + a single open persistence contact session for the whole life cycle of the application transaction. Then + simply disconnect from the JDBC connection at the end of each request and reconnect at the + beginning of the subsequent request. Never share a single session across more than one application + transaction or you will be working with stale data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Do not treat exceptions as recoverable:</term> + <listitem> + <para> + This is more of a necessary practice than a "best" practice. When an exception occurs, roll back + the <literal>Transaction</literal> and close the <literal>Session</literal>. If you do not do this, Hibernate + cannot guarantee that in-memory state accurately represents the persistent state. For example, + do not use <literal>Session.load()</literal> to determine if an instance with the given identifier + exists on the database; use <literal>Session.get()</literal> or a query instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Prefer lazy fetching for associations:</term> + <listitem> + <para> + Use eager fetching sparingly. Use proxies and lazy collections for most associations to classes that + are not likely to be completely held in the second-level cache. For associations to cached classes, + where there is an a extremely high probability of a cache hit, explicitly disable eager fetching using + <literal>lazy="false"</literal>. When join fetching is appropriate to a particular use + case, use a query with a <literal>left join fetch</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Use the <emphasis>open session in view</emphasis> pattern, or a disciplined + <emphasis>assembly phase</emphasis> to avoid problems with unfetched data: + </term> + <listitem> + <para> + Hibernate frees the developer from writing tedious <emphasis>Data Transfer Objects</emphasis> (DTO). + In a traditional EJB architecture, DTOs serve dual purposes: first, they work around the problem + that entity beans are not serializable; second, they implicitly define an assembly phase where + all data to be used by the view is fetched and marshalled into the DTOs before returning control + to the presentation tier. Hibernate eliminates the first purpose. Unless you are prepared to hold the + persistence context (the session) open across the view rendering process, you will still need + an assembly phase. Think of your business methods as having a strict contract with the presentation + tier about what data is available in the detached objects. This is not a limitation + of Hibernate. It is a fundamental requirement of safe transactional data access. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Consider abstracting your business logic from Hibernate:</term> + <listitem> + <para> + Hide Hibernate data-access code behind an interface. Combine the <emphasis>DAO</emphasis> and + <emphasis>Thread Local Session</emphasis> patterns. You can even have some classes persisted by + handcoded JDBC associated to Hibernate via a <literal>UserType</literal>. This advice is, however, + intended for "sufficiently large" applications. It is not appropriate for an application with + five tables. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Do not use exotic association mappings:</term> + <listitem> + <para> + Practical test cases for real many-to-many associations are rare. Most of the time you need + additional information stored in the "link table". In this case, it is much better to + use two one-to-many associations to an intermediate link class. In fact, + most associations are one-to-many and many-to-one. For this reason, you should proceed cautiously when using any + other association style. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Prefer bidirectional associations:</term> + <listitem> + <para> + Unidirectional associations are more difficult to query. In a large application, almost + all associations must be navigable in both directions in queries. + </para> + </listitem> + </varlistentry> + </variablelist> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/bibliography.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/bibliography.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/bibliography.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,80 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2009, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<bibliography> + <title>References</title> + + <biblioentry id="biblio-PoEAA"> + <abbrev>PoEAA</abbrev> + <title>Patterns of Enterprise Application Architecture</title> + <isbn>0-321-12742-0</isbn> + <authorgroup> + <author> + <firstname>Martin</firstname> + <surname>Fowler</surname> + </author> + </authorgroup> + <copyright> + <year>2003</year> + <holder>Pearson Education, Inc.</holder> + </copyright> + <publisher> + <publishername>Addison-Wesley Publishing Company</publishername> + </publisher> + </biblioentry> + + <biblioentry id="biblio-JPwH"> + <abbrev>JPwH</abbrev> + <title>Java Persistence with Hibernate</title> + <subtitle>Second Edition of Hibernate in Action</subtitle> + <isbn>1-932394-88-5</isbn> + <bibliomisc> + <ulink url="http://www.manning.com/bauer2"/> + </bibliomisc> + <authorgroup> + <author> + <firstname>Christian</firstname> + <surname>Bauer</surname> + </author> + <author> + <firstname>Gavin</firstname> + <surname>King</surname> + </author> + </authorgroup> + <copyright> + <year>2007</year> + <holder>Manning Publications Co.</holder> + </copyright> + <publisher> + <publishername>Manning Publications Co.</publishername> + </publisher> + </biblioentry> + +</bibliography> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/collection_mapping.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/collection_mapping.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/collection_mapping.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1273 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="collections"> + <title>Collection mapping</title> + + <section id="collections-persistent" revision="3"> + <title>Persistent collections</title> + + <para> + Hibernate requires that persistent collection-valued fields be declared + as an interface type. For example: + </para> + + <programlisting role="JAVA"><![CDATA[public class Product { + private String serialNumber; + private Set parts = new HashSet(); + + public Set getParts() { return parts; } + void setParts(Set parts) { this.parts = parts; } + public String getSerialNumber() { return serialNumber; } + void setSerialNumber(String sn) { serialNumber = sn; } +}]]></programlisting> + + <para> + The actual interface might be <literal>java.util.Set</literal>, + <literal>java.util.Collection</literal>, <literal>java.util.List</literal>, + <literal>java.util.Map</literal>, <literal>java.util.SortedSet</literal>, + <literal>java.util.SortedMap</literal> or anything you like + ("anything you like" means you will have to write an implementation of + <literal>org.hibernate.usertype.UserCollectionType</literal>.) + </para> + + <para> + Notice how the instance variable was initialized with an instance of + <literal>HashSet</literal>. This is the best way to initialize collection + valued properties of newly instantiated (non-persistent) instances. When + you make the instance persistent, by calling <literal>persist()</literal> + for example, Hibernate will actually replace the <literal>HashSet</literal> + with an instance of Hibernate's own implementation of <literal>Set</literal>. + Be aware of the following errors: + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = new DomesticCat(); +Cat kitten = new DomesticCat(); +.... +Set kittens = new HashSet(); +kittens.add(kitten); +cat.setKittens(kittens); +session.persist(cat); +kittens = cat.getKittens(); // Okay, kittens collection is a Set +(HashSet) cat.getKittens(); // Error!]]></programlisting> + + <para> + The persistent collections injected by Hibernate behave like + <literal>HashMap</literal>, <literal>HashSet</literal>, + <literal>TreeMap</literal>, <literal>TreeSet</literal> or + <literal>ArrayList</literal>, depending on the interface type. + </para> + + <para> + Collections instances have the usual behavior of value types. They are + automatically persisted when referenced by a persistent object and + are automatically deleted when unreferenced. If a collection is passed from one + persistent object to another, its elements might be moved from one table to + another. Two entities cannot share a reference to the same collection + instance. Due to the underlying relational model, collection-valued properties + do not support null value semantics. Hibernate does not distinguish between + a null collection reference and an empty collection. + </para> + + <para> + Use persistent collections + the same way you use ordinary Java collections. However, please ensure you understand + the semantics of bidirectional associations (these are discussed later). + </para> + + </section> + + <section id="collections-mapping" revision="4"> + <title>Collection mappings</title> + + <tip> + <para> + There are quite a range of mappings that can be generated for collections that cover + many common relational models. We suggest you experiment with the schema generation tool + so that you understand how various mapping declarations translate to database tables. + </para> + </tip> + + <para> + The Hibernate mapping element used for mapping a collection depends upon + the type of interface. For example, a <literal>&lt;set&gt;</literal> + element is used for mapping properties of type <literal>Set</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[<class name="Product"> + <id name="serialNumber" column="productSerialNumber"/> + <set name="parts"> + <key column="productSerialNumber" not-null="true"/> + <one-to-many class="Part"/> + </set> +</class>]]></programlisting> + + <para> + Apart from <literal>&lt;set&gt;</literal>, there is also + <literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</literal>, + <literal>&lt;bag&gt;</literal>, <literal>&lt;array&gt;</literal> and + <literal>&lt;primitive-array&gt;</literal> mapping elements. The + <literal>&lt;map&gt;</literal> element is representative: + </para> + + <programlistingco role="XML"> + <areaspec> + <area id="mappingcollection1" coords="2"/> + <area id="mappingcollection2" coords="3"/> + <area id="mappingcollection3" coords="4"/> + <area id="mappingcollection4" coords="5"/> + <area id="mappingcollection5" coords="6"/> + <area id="mappingcollection6" coords="7"/> + <area id="mappingcollection7" coords="8"/> + <area id="mappingcollection8" coords="9"/> + <area id="mappingcollection9" coords="10"/> + <area id="mappingcollection10" coords="11"/> + <area id="mappingcollection11" coords="12"/> + <area id="mappingcollection12" coords="13"/> + <area id="mappingcollection13" coords="14"/> + <area id="mappingcollection14" coords="15"/> + </areaspec> + <programlisting><![CDATA[<map + name="propertyName" + table="table_name" + schema="schema_name" + lazy="true|extra|false" + inverse="true|false" + cascade="all|none|save-update|delete|all-delete-orphan|delete-orphan" + sort="unsorted|natural|comparatorClass" + order-by="column_name asc|desc" + where="arbitrary sql where condition" + fetch="join|select|subselect" + batch-size="N" + access="field|property|ClassName" + optimistic-lock="true|false" + mutable="true|false" + node="element-name|." + embed-xml="true|false" +> + + <key .... /> + <map-key .... /> + <element .... /> +</map>]]></programlisting> + <calloutlist> + <callout arearefs="mappingcollection1"> + <para> + <literal>name</literal>: the collection property name + </para> + </callout> + <callout arearefs="mappingcollection2"> + <para> + <literal>table</literal> (optional - defaults to property name): the + name of the collection table. It is not used for one-to-many associations. + </para> + </callout> + <callout arearefs="mappingcollection3"> + <para> + <literal>schema</literal> (optional): the name of a table schema to + override the schema declared on the root element + </para> + </callout> + <callout arearefs="mappingcollection4"> + <para> + <literal>lazy</literal> (optional - defaults to <literal>true</literal>): + disables lazy fetching and specifies that the association is + always eagerly fetched. It can also be used to enable "extra-lazy" fetching where most + operations do not initialize the collection. This is suitable for large + collections. + </para> + </callout> + <callout arearefs="mappingcollection5"> + <para> + <literal>inverse</literal> (optional - defaults to <literal>false</literal>): + marks this collection as the "inverse" end of a bidirectional association. + </para> + </callout> + <callout arearefs="mappingcollection6"> + <para> + <literal>cascade</literal> (optional - defaults to <literal>none</literal>): + enables operations to cascade to child entities. + </para> + </callout> + <callout arearefs="mappingcollection7"> + <para> + <literal>sort</literal> (optional): specifies a sorted collection with + <literal>natural</literal> sort order or a given comparator class. + </para> + </callout> + <callout arearefs="mappingcollection8"> + <para> + <literal>order-by</literal> (optional, JDK1.4 only): specifies a table column or columns + that define the iteration order of the <literal>Map</literal>, <literal>Set</literal> + or bag, together with an optional <literal>asc</literal> or <literal>desc</literal>. + </para> + </callout> + <callout arearefs="mappingcollection9"> + <para> + <literal>where</literal> (optional): specifies an arbitrary SQL <literal>WHERE</literal> + condition that is used when retrieving or removing the collection. This is useful if the + collection needs to contain only a subset of the available data. + </para> + </callout> + <callout arearefs="mappingcollection10"> + <para> + <literal>fetch</literal> (optional, defaults to <literal>select</literal>): chooses + between outer-join fetching, fetching by sequential select, and fetching by sequential + subselect. + </para> + </callout> + <callout arearefs="mappingcollection11"> + <para> + <literal>batch-size</literal> (optional, defaults to <literal>1</literal>): specifies a + "batch size" for lazily fetching instances of this collection. + </para> + </callout> + <callout arearefs="mappingcollection12"> + <para> + <literal>access</literal> (optional - defaults to <literal>property</literal>): the + strategy Hibernate uses for accessing the collection property value. + </para> + </callout> + <callout arearefs="mappingcollection13"> + <para> + <literal>optimistic-lock</literal> (optional - defaults to <literal>true</literal>): + specifies that changes to the state of the collection results in increments of the + owning entity's version. For one-to-many associations you may want to + disable this setting. + </para> + </callout> + <callout arearefs="mappingcollection14"> + <para> + <literal>mutable</literal> (optional - defaults to <literal>true</literal>): + a value of <literal>false</literal> specifies that the elements of the + collection never change. This allows for minor performance optimization in some cases. + </para> + </callout> + </calloutlist> + </programlistingco> + + <section id="collections-foreignkeys" > + <title>Collection foreign keys</title> + + <para> + Collection instances are distinguished in the database by the foreign key of + the entity that owns the collection. This foreign key is referred to as the + <emphasis>collection key column</emphasis>, or columns, of the collection + table. The collection key column is mapped by the <literal>&lt;key&gt;</literal> + element. + </para> + + <para> + There can be a nullability constraint on the foreign key column. For most + collections, this is implied. For unidirectional one-to-many associations, + the foreign key column is nullable by default, so you may need to specify + <literal>not-null="true"</literal>. + </para> + + <programlisting role="XML"><![CDATA[<key column="productSerialNumber" not-null="true"/>]]></programlisting> + + <para> + The foreign key constraint can use <literal>ON DELETE CASCADE</literal>. + </para> + + <programlisting role="XML"><![CDATA[<key column="productSerialNumber" on-delete="cascade"/>]]></programlisting> + + <para> + See the previous chapter for a full definition of the <literal>&lt;key&gt;</literal> + element. + </para> + + </section> + + <section id="collections-elements" > + <title>Collection elements</title> + + <para> + Collections can contain almost any other Hibernate type, including: basic types, + custom types, components and references to other entities. This is an + important distinction. An object in a collection might be handled with "value" + semantics (its life cycle fully depends on the collection owner), or it might be a + reference to another entity with its own life cycle. In the latter case, only the + "link" between the two objects is considered to be a state held by the collection. + </para> + + <para> + The contained type is referred to as the <emphasis>collection element type</emphasis>. + Collection elements are mapped by <literal>&lt;element&gt;</literal> or + <literal>&lt;composite-element&gt;</literal>, or in the case of entity references, + with <literal>&lt;one-to-many&gt;</literal> or <literal>&lt;many-to-many&gt;</literal>. + The first two map elements with value semantics, the next two are used to map entity + associations. + </para> + + </section> + + <section id="collections-indexed"> + <title>Indexed collections</title> + + <para> + All collection mappings, except those with set and bag semantics, need an + <emphasis>index column</emphasis> in the collection table. An index column is a column that maps to an + array index, or <literal>List</literal> index, or <literal>Map</literal> key. The + index of a <literal>Map</literal> may be of any basic type, mapped with + <literal>&lt;map-key&gt;</literal>. It can be an entity reference mapped with + <literal>&lt;map-key-many-to-many&gt;</literal>, or it can be a composite type + mapped with <literal>&lt;composite-map-key&gt;</literal>. The index of an array or + list is always of type <literal>integer</literal> and is mapped using the + <literal>&lt;list-index&gt;</literal> element. The mapped column contains + sequential integers that are numbered from zero by default. + </para> + + <programlistingco role="XML"> + <areaspec> + <area id="index1" coords="2"/> + <area id="index2" coords="3"/> + </areaspec> + <programlisting><![CDATA[<list-index + column="column_name" + base="0|1|..."/>]]></programlisting> + <calloutlist> + <callout arearefs="index1"> + <para> + <literal>column_name</literal> (required): the name of the column holding the + collection index values. + </para> + </callout> + <callout arearefs="index1"> + <para> + <literal>base</literal> (optional - defaults to <literal>0</literal>): the value + of the index column that corresponds to the first element of the list or array. + </para> + </callout> + </calloutlist> + </programlistingco> + + <programlistingco role="XML"> + <areaspec> + <area id="mapkey1" coords="2"/> + <area id="mapkey2" coords="3"/> + <area id="mapkey3" coords="4"/> + </areaspec> + <programlisting><![CDATA[<map-key + column="column_name" + formula="any SQL expression" + type="type_name" + node="@attribute-name" + length="N"/>]]></programlisting> + <calloutlist> + <callout arearefs="mapkey1"> + <para> + <literal>column</literal> (optional): the name of the column holding the + collection index values. + </para> + </callout> + <callout arearefs="mapkey2"> + <para> + <literal>formula</literal> (optional): a SQL formula used to evaluate the + key of the map. + </para> + </callout> + <callout arearefs="mapkey3"> + <para> + <literal>type</literal> (required): the type of the map keys. + </para> + </callout> + </calloutlist> + </programlistingco> + + <programlistingco role="XML"> + <areaspec> + <area id="indexmanytomany1" coords="2"/> + <area id="indexmanytomany2" coords="3"/> + <area id="indexmanytomany3" coords="3"/> + </areaspec> + <programlisting><![CDATA[<map-key-many-to-many + column="column_name" + formula="any SQL expression" + class="ClassName" +/>]]></programlisting> + <calloutlist> + <callout arearefs="indexmanytomany1"> + <para> + <literal>column</literal> (optional): the name of the foreign key + column for the collection index values. + </para> + </callout> + <callout arearefs="indexmanytomany2"> + <para> + <literal>formula</literal> (optional): a SQ formula used to evaluate the + foreign key of the map key. + </para> + </callout> + <callout arearefs="indexmanytomany3"> + <para> + <literal>class</literal> (required): the entity class used as the map key. + </para> + </callout> + </calloutlist> + </programlistingco> + + + <para> + If your table does not have an index column, and you still wish to use <literal>List</literal> + as the property type, you can map the property as a Hibernate <emphasis>&lt;bag&gt;</emphasis>. + A bag does not retain its order when it is retrieved from the database, but it can be + optionally sorted or ordered. + </para> + + </section> + + <section id="collections-ofvalues" revision="2"> + <title>Collections of values and many-to-many associations</title> + + <para> + Any collection of values or many-to-many associations requires a dedicated + <emphasis>collection table</emphasis> with a foreign key column or columns, + <emphasis>collection element column</emphasis> or columns, and possibly + an index column or columns. + </para> + + <para> + For a collection of values use the <literal>&lt;element&gt;</literal> tag. For example: + </para> + + <programlistingco role="XML"> + <areaspec> + <area id="element1b" coords="2"/> + <area id="element2b" coords="3"/> + <area id="element3b" coords="4"/> + </areaspec> + <programlisting><![CDATA[<element + column="column_name" + formula="any SQL expression" + type="typename" + length="L" + precision="P" + scale="S" + not-null="true|false" + unique="true|false" + node="element-name" +/>]]></programlisting> + <calloutlist> + <callout arearefs="element1b"> + <para> + <literal>column</literal> (optional): the name of the column holding the + collection element values. + </para> + </callout> + <callout arearefs="element2b"> + <para> + <literal>formula</literal> (optional): an SQL formula used to evaluate the + element. + </para> + </callout> + <callout arearefs="element3b"> + <para> + <literal>type</literal> (required): the type of the collection element. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + A <emphasis>many-to-many association</emphasis> is specified using the + <literal>&lt;many-to-many&gt;</literal> element. + </para> + + <programlistingco role="XML"> + <areaspec> + <area id="manytomany1" coords="2"/> + <area id="manytomany2" coords="3"/> + <area id="manytomany3" coords="4"/> + <area id="manytomany4" coords="5"/> + <area id="manytomany5" coords="6"/> + <area id="manytomany6" coords="7"/> + <area id="manytomany7" coords="8"/> + <area id="manytomany8" coords="9"/> + </areaspec> + <programlisting><![CDATA[<many-to-many + column="column_name" + formula="any SQL expression" + class="ClassName" + fetch="select|join" + unique="true|false" + not-found="ignore|exception" + entity-name="EntityName" + property-ref="propertyNameFromAssociatedClass" + node="element-name" + embed-xml="true|false" + />]]></programlisting> + <calloutlist> + <callout arearefs="manytomany1"> + <para> + <literal>column</literal> (optional): the name of the element foreign key column. + </para> + </callout> + <callout arearefs="manytomany2"> + <para> + <literal>formula</literal> (optional): an SQL formula used to evaluate the element + foreign key value. + </para> + </callout> + <callout arearefs="manytomany3"> + <para> + <literal>class</literal> (required): the name of the associated class. + </para> + </callout> + <callout arearefs="manytomany4"> + <para> + <literal>fetch</literal> (optional - defaults to <literal>join</literal>): + enables outer-join or sequential select fetching for this association. This + is a special case; for full eager fetching in a single <literal>SELECT</literal> + of an entity and its many-to-many relationships to other entities, you would + enable <literal>join</literal> fetching,not only of the collection itself, + but also with this attribute on the <literal>&lt;many-to-many&gt;</literal> + nested element. + </para> + </callout> + <callout arearefs="manytomany5"> + <para> + <literal>unique</literal> (optional): enables the DDL generation of a unique + constraint for the foreign-key column. This makes the association multiplicity + effectively one-to-many. + </para> + </callout> + <callout arearefs="manytomany6"> + <para> + <literal>not-found</literal> (optional - defaults to <literal>exception</literal>): + specifies how foreign keys that reference missing rows will be handled: + <literal>ignore</literal> will treat a missing row as a null association. + </para> + </callout> + <callout arearefs="manytomany7"> + <para> + <literal>entity-name</literal> (optional): the entity name of the associated class, + as an alternative to <literal>class</literal>. + </para> + </callout> + <callout arearefs="manytomany8"> + <para> + <literal>property-ref</literal> (optional): the name of a property of the associated + class that is joined to this foreign key. If not specified, the primary key of + the associated class is used. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Here are some examples. + </para> + <para> + A set of strings: + </para> + + <programlisting role="XML"><![CDATA[<set name="names" table="person_names"> + <key column="person_id"/> + <element column="person_name" type="string"/> +</set>]]></programlisting> + + <para> + A bag containing integers with an iteration order determined by the + <literal>order-by</literal> attribute: + </para> + + <programlisting role="XML"><![CDATA[<bag name="sizes" + table="item_sizes" + order-by="size asc"> + <key column="item_id"/> + <element column="size" type="integer"/> +</bag>]]></programlisting> + + <para> + An array of entities, in this case, a many-to-many association: + </para> + + <programlisting role="XML"><![CDATA[<array name="addresses" + table="PersonAddress" + cascade="persist"> + <key column="personId"/> + <list-index column="sortOrder"/> + <many-to-many column="addressId" class="Address"/> +</array>]]></programlisting> + + <para> + A map from string indices to dates: + </para> + + <programlisting role="XML"><![CDATA[<map name="holidays" + table="holidays" + schema="dbo" + order-by="hol_name asc"> + <key column="id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date" type="date"/> +</map>]]></programlisting> + + <para> + A list of components (this is discussed in the next chapter): + </para> + + <programlisting role="XML"><![CDATA[<list name="carComponents" + table="CarComponents"> + <key column="carId"/> + <list-index column="sortOrder"/> + <composite-element class="CarComponent"> + <property name="price"/> + <property name="type"/> + <property name="serialNumber" column="serialNum"/> + </composite-element> +</list>]]></programlisting> + + </section> + + <section id="collections-onetomany"> + <title>One-to-many associations</title> + + <para> + A <emphasis>one-to-many association</emphasis> links the tables of two classes + via a foreign key with no intervening collection table. This mapping loses + certain semantics of normal Java collections: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + An instance of the contained entity class cannot belong to more than + one instance of the collection. + </para> + </listitem> + <listitem> + <para> + An instance of the contained entity class cannot appear at more than + one value of the collection index. + </para> + </listitem> + </itemizedlist> + + <para> + An association from <literal>Product</literal> to <literal>Part</literal> requires + the existence of a foreign key column and possibly an index column to the <literal>Part</literal> + table. A <literal>&lt;one-to-many&gt;</literal> tag indicates that this is a one-to-many + association. + </para> + + <programlistingco role="XML"> + <areaspec> + <area id="onetomany1" coords="2"/> + <area id="onetomany2" coords="3"/> + <area id="onetomany3" coords="4"/> + </areaspec> + <programlisting><![CDATA[<one-to-many + class="ClassName" + not-found="ignore|exception" + entity-name="EntityName" + node="element-name" + embed-xml="true|false" + />]]></programlisting> + <calloutlist> + <callout arearefs="onetomany1"> + <para> + <literal>class</literal> (required): the name of the associated class. + </para> + </callout> + <callout arearefs="onetomany2"> + <para> + <literal>not-found</literal> (optional - defaults to <literal>exception</literal>): + specifies how cached identifiers that reference missing rows will be handled. + <literal>ignore</literal> will treat a missing row as a null association. + </para> + </callout> + <callout arearefs="onetomany3"> + <para> + <literal>entity-name</literal> (optional): the entity name of the associated class, + as an alternative to <literal>class</literal>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + The <literal>&lt;one-to-many&gt;</literal> element does not need to + declare any columns. Nor is it necessary to specify the <literal>table</literal> + name anywhere. + </para> + + <warning> + <para> + If the foreign key column of a + <literal>&lt;one-to-many&gt;</literal> association is declared <literal>NOT NULL</literal>, + you must declare the <literal>&lt;key&gt;</literal> mapping + <literal>not-null="true"</literal> or <emphasis>use a bidirectional association</emphasis> + with the collection mapping marked <literal>inverse="true"</literal>. See the discussion + of bidirectional associations later in this chapter for more information. + </para> + </warning> + + <para> + The following example shows a map of <literal>Part</literal> entities by name, where + <literal>partName</literal> is a persistent property of <literal>Part</literal>. + Notice the use of a formula-based index: + </para> + + <programlisting role="XML"><![CDATA[<map name="parts" + cascade="all"> + <key column="productId" not-null="true"/> + <map-key formula="partName"/> + <one-to-many class="Part"/> +</map>]]></programlisting> + </section> + + </section> + + <section id="collections-advancedmappings"> + <title>Advanced collection mappings</title> + + <section id="collections-sorted" revision="2"> + <title>Sorted collections</title> + + <para> + Hibernate supports collections implementing <literal>java.util.SortedMap</literal> and + <literal>java.util.SortedSet</literal>. You must specify a comparator in the mapping file: + </para> + + <programlisting role="XML"><![CDATA[<set name="aliases" + table="person_aliases" + sort="natural"> + <key column="person"/> + <element column="name" type="string"/> +</set> + +<map name="holidays" sort="my.custom.HolidayComparator"> + <key column="year_id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date" type="date"/> +</map>]]></programlisting> + + <para> + Allowed values of the <literal>sort</literal> attribute are <literal>unsorted</literal>, + <literal>natural</literal> and the name of a class implementing + <literal>java.util.Comparator</literal>. + </para> + + <para> + Sorted collections actually behave like <literal>java.util.TreeSet</literal> or + <literal>java.util.TreeMap</literal>. + </para> + + <para> + If you want the database itself to order the collection elements, use the + <literal>order-by</literal> attribute of <literal>set</literal>, <literal>bag</literal> + or <literal>map</literal> mappings. This solution is only available under + JDK 1.4 or higher and is implemented using <literal>LinkedHashSet</literal> or + <literal>LinkedHashMap</literal>. This performs the ordering in the SQL query and + not in the memory. + </para> + + <programlisting role="XML"><![CDATA[<set name="aliases" table="person_aliases" order-by="lower(name) asc"> + <key column="person"/> + <element column="name" type="string"/> +</set> + +<map name="holidays" order-by="hol_date, hol_name"> + <key column="year_id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date type="date"/> +</map>]]></programlisting> + + <note> + <title>Note</title> + <para> + The value of the <literal>order-by</literal> attribute is an SQL ordering, not + an HQL ordering. + </para> + </note> + + <para> + Associations can even be sorted by arbitrary criteria at runtime using a collection + <literal>filter()</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();]]></programlisting> + + </section> + + <section id="collections-bidirectional" revision="1"> + <title>Bidirectional associations</title> + + <para> + A <emphasis>bidirectional association</emphasis> allows navigation from both + "ends" of the association. Two kinds of bidirectional association are + supported: + + <variablelist> + <varlistentry> + <term>one-to-many</term> + <listitem> + <para> + set or bag valued at one end and single-valued at the other + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>many-to-many</term> + <listitem> + <para> + set or bag valued at both ends + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + + <para> + You can specify a bidirectional many-to-many association by mapping two + many-to-many associations to the same database table and declaring one end as + <emphasis>inverse</emphasis>. You cannot select an + indexed collection. + </para> + + <para> + Here is an example of a bidirectional many-to-many association that illustrates how each category can + have many items and each item can be in many categories: + </para> + + <programlisting role="XML"><![CDATA[<class name="Category"> + <id name="id" column="CATEGORY_ID"/> + ... + <bag name="items" table="CATEGORY_ITEM"> + <key column="CATEGORY_ID"/> + <many-to-many class="Item" column="ITEM_ID"/> + </bag> +</class> + +<class name="Item"> + <id name="id" column="ITEM_ID"/> + ... + + <!-- inverse end --> + <bag name="categories" table="CATEGORY_ITEM" inverse="true"> + <key column="ITEM_ID"/> + <many-to-many class="Category" column="CATEGORY_ID"/> + </bag> +</class>]]></programlisting> + + <para> + Changes made only to the inverse end of the association are <emphasis>not</emphasis> + persisted. This means that Hibernate has two representations in memory for every + bidirectional association: one link from A to B and another link from B to A. This + is easier to understand if you think about the Java object model and how + a many-to-many relationship in Javais created: + </para> + + <programlisting role="JAVA"><![CDATA[ +category.getItems().add(item); // The category now "knows" about the relationship +item.getCategories().add(category); // The item now "knows" about the relationship + +session.persist(item); // The relationship won't be saved! +session.persist(category); // The relationship will be saved]]></programlisting> + + <para> + The non-inverse side is used to save the in-memory representation to the database. + </para> + + <para> + You can define a bidirectional one-to-many association by mapping a one-to-many association + to the same table column(s) as a many-to-one association and declaring the many-valued + end <literal>inverse="true"</literal>. + </para> + + <programlisting role="XML"><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <many-to-one name="parent" + class="Parent" + column="parent_id" + not-null="true"/> +</class>]]></programlisting> + + <para> + Mapping one end of an association with <literal>inverse="true"</literal> does not + affect the operation of cascades as these are orthogonal concepts. + </para> + + </section> + + <section id="collections-indexedbidirectional"> + <title>Bidirectional associations with indexed collections</title> + <para> + A bidirectional association where one end is represented as a <literal>&lt;list&gt;</literal> + or <literal>&lt;map&gt;</literal>, requires special consideration. If there is a property of + the child class that maps to the index column you can use + <literal>inverse="true"</literal> on the collection mapping: + </para> + + <programlisting role="XML"><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <map name="children" inverse="true"> + <key column="parent_id"/> + <map-key column="name" + type="string"/> + <one-to-many class="Child"/> + </map> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <property name="name" + not-null="true"/> + <many-to-one name="parent" + class="Parent" + column="parent_id" + not-null="true"/> +</class>]]></programlisting> + + <para> + If there is no such property on the child class, the association cannot be considered + truly bidirectional. That is, there is information available at one end of the association that is + not available at the other end. In this case, you cannot map the collection + <literal>inverse="true"</literal>. Instead, you could use the following mapping: + </para> + + <programlisting role="XML"><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <map name="children"> + <key column="parent_id" + not-null="true"/> + <map-key column="name" + type="string"/> + <one-to-many class="Child"/> + </map> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <many-to-one name="parent" + class="Parent" + column="parent_id" + insert="false" + update="false" + not-null="true"/> +</class>]]></programlisting> + + <para> + Note that in this mapping, the collection-valued end of the association is responsible for + updates to the foreign key. <!--TODO: Does this really result in some unnecessary update statements?--> + </para> + + </section> + + <section id="collections-ternary"> + <title>Ternary associations</title> + + <para> + There are three possible approaches to mapping a ternary association. One approach is to use a + <literal>Map</literal> with an association as its index: + </para> + + <programlisting role="XML"><![CDATA[<map name="contracts"> + <key column="employer_id" not-null="true"/> + <map-key-many-to-many column="employee_id" class="Employee"/> + <one-to-many class="Contract"/> +</map>]]></programlisting> + + <programlisting role="XML"><![CDATA[<map name="connections"> + <key column="incoming_node_id"/> + <map-key-many-to-many column="outgoing_node_id" class="Node"/> + <many-to-many column="connection_id" class="Connection"/> +</map>]]></programlisting> + + <para> + A second approach is to remodel the association as an entity class. This + is the most common approach. + </para> + + <para> + A final alternative is to use composite elements, which will be discussed later. + </para> + + </section> + + <section id="collections-idbag" revision="1"> + <title><literal>Using an &lt;idbag&gt;</literal></title> + + <para> + The majority of the many-to-many associations and collections of values + shown previously all map to tables with composite keys, even though it has been have suggested + that entities should have synthetic identifiers (surrogate keys). A + pure association table does not seem to benefit much from + a surrogate key, although a collection of composite values <emphasis>might</emphasis>. + It is for this reason that Hibernate provides a feature that allows you to map many-to-many + associations and collections of values to a table with a surrogate key. + </para> + + <para> + The <literal>&lt;idbag&gt;</literal> element lets you map a <literal>List</literal> + (or <literal>Collection</literal>) with bag semantics. For example: + </para> + +<programlisting role="XML"><![CDATA[<idbag name="lovers" table="LOVERS"> + <collection-id column="ID" type="long"> + <generator class="sequence"/> + </collection-id> + <key column="PERSON1"/> + <many-to-many column="PERSON2" class="Person" fetch="join"/> +</idbag>]]></programlisting> + + <para> + An <literal>&lt;idbag&gt;</literal> has a synthetic id generator, + just like an entity class. A different surrogate key is assigned to each collection + row. Hibernate does not, however, provide any mechanism for discovering the surrogate key value + of a particular row. + </para> + + <para> + The update performance of an <literal>&lt;idbag&gt;</literal> supersedes a regular <literal>&lt;bag&gt;</literal>. + Hibernate can locate individual rows efficiently and update or delete them + individually, similar to a list, map or set. + </para> + + <para> + In the current implementation, the <literal>native</literal> identifier generation + strategy is not supported for <literal>&lt;idbag&gt;</literal> collection identifiers. + </para> + + </section> + + </section> + + <!--undocumenting this stuff --> + + <!--section id="collections-heterogeneous"> + <title>Heterogeneous Associations</title> + + <para> + The <literal>&lt;many-to-any&gt;</literal> and <literal>&lt;index-many-to-any&gt;</literal> + elements provide for true heterogeneous associations. These mapping elements work in the + same way as the <literal>&lt;any&gt;</literal> element - and should also be used + rarely, if ever. + </para> + + </section--> + + <section id="collections-example" revision="1"> + <title>Collection examples</title> + + <para> + This section covers collection examples. + </para> + + <para> + The following class has a collection of <literal>Child</literal> instances: + </para> + + <programlisting role="JAVA"><![CDATA[package eg; +import java.util.Set; + +public class Parent { + private long id; + private Set children; + + public long getId() { return id; } + private void setId(long id) { this.id=id; } + + private Set getChildren() { return children; } + private void setChildren(Set children) { this.children=children; } + + .... + .... +}]]></programlisting> + + <para> + If each child has, at most, one parent, the most natural mapping is a + one-to-many association: + + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + This maps to the following table definitions: + </para> + + <programlisting role="XML"><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null primary key, name varchar(255), parent_id bigint ) +alter table child add constraint childfk0 (parent_id) references parent]]></programlisting> + + <para> + If the parent is <emphasis>required</emphasis>, use a bidirectional one-to-many + association: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + <many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Notice the <literal>NOT NULL</literal> constraint: + </para> + + <programlisting role="XML"><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null + primary key, + name varchar(255), + parent_id bigint not null ) +alter table child add constraint childfk0 (parent_id) references parent]]></programlisting> + + <para> + Alternatively, if this association must be unidirectional + you can declare the <literal>NOT NULL</literal> constraint on the <literal>&lt;key&gt;</literal> + mapping: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children"> + <key column="parent_id" not-null="true"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + On the other hand, if a child has multiple parents, a many-to-many + association is appropriate: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children" table="childset"> + <key column="parent_id"/> + <many-to-many class="Child" column="child_id"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Table definitions: + </para> + + <programlisting><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null primary key, name varchar(255) ) +create table childset ( parent_id bigint not null, + child_id bigint not null, + primary key ( parent_id, child_id ) ) +alter table childset add constraint childsetfk0 (parent_id) references parent +alter table childset add constraint childsetfk1 (child_id) references child]]></programlisting> + + <para> + For more examples and a complete explanation of a parent/child relationship mapping, + see <xref linkend="example-parentchild"/> for more information. + </para> + + <para> + Even more complex association mappings are covered + in the next chapter. + </para> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/component_mapping.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/component_mapping.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/component_mapping.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,442 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="components"> + <title>Component Mapping</title> + + <para> + The notion of a <emphasis>component</emphasis> is re-used in several different contexts and purposes + throughout Hibernate. + </para> + + <section id="components-dependentobjects" revision="2" > + <title>Dependent objects</title> + + <para> + A component is a contained object that is persisted as a value type and not an entity + reference. The term "component" refers to the object-oriented notion of composition + and not to architecture-level components. For example, you can model a person like this: + </para> + + <programlisting role="JAVA"><![CDATA[public class Person { + private java.util.Date birthday; + private Name name; + private String key; + public String getKey() { + return key; + } + private void setKey(String key) { + this.key=key; + } + public java.util.Date getBirthday() { + return birthday; + } + public void setBirthday(java.util.Date birthday) { + this.birthday = birthday; + } + public Name getName() { + return name; + } + public void setName(Name name) { + this.name = name; + } + ...... + ...... +}]]></programlisting> + +<programlisting role="JAVA"><![CDATA[public class Name { + char initial; + String first; + String last; + public String getFirst() { + return first; + } + void setFirst(String first) { + this.first = first; + } + public String getLast() { + return last; + } + void setLast(String last) { + this.last = last; + } + public char getInitial() { + return initial; + } + void setInitial(char initial) { + this.initial = initial; + } +}]]></programlisting> + + <para> + Now <literal>Name</literal> can be persisted as a component of + <literal>Person</literal>. <literal>Name</literal> defines getter + and setter methods for its persistent properties, but it does not need to declare + any interfaces or identifier properties. + </para> + + <para> + Our Hibernate mapping would look like this: + </para> + + <programlisting role="XML"><![CDATA[<class name="eg.Person" table="person"> + <id name="Key" column="pid" type="string"> + <generator class="uuid"/> + </id> + <property name="birthday" type="date"/> + <component name="Name" class="eg.Name"> <!-- class attribute optional --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </component> +</class>]]></programlisting> + + <para> + The person table would have the columns <literal>pid</literal>, + <literal>birthday</literal>, + <literal>initial</literal>, + <literal>first</literal> and + <literal>last</literal>. + </para> + + <para> + Like value types, components do not support shared references. In other words, two + persons could have the same name, but the two person objects would contain two independent + name objects that were only "the same" by value. The null value semantics of a component are + <emphasis>ad hoc</emphasis>. When reloading the containing object, Hibernate will assume + that if all component columns are null, then the entire component is null. This is suitable for most purposes. + </para> + + <para> + The properties of a component can be of any Hibernate type (collections, many-to-one + associations, other components, etc). Nested components should <emphasis>not</emphasis> + be considered an exotic usage. Hibernate is intended to support a fine-grained + object model. + </para> + + <para> + The <literal>&lt;component&gt;</literal> element allows a <literal>&lt;parent&gt;</literal> + subelement that maps a property of the component class as a reference back to the + containing entity. + </para> + + <programlisting role="XML"><![CDATA[<class name="eg.Person" table="person"> + <id name="Key" column="pid" type="string"> + <generator class="uuid"/> + </id> + <property name="birthday" type="date"/> + <component name="Name" class="eg.Name" unique="true"> + <parent name="namedPerson"/> <!-- reference back to the Person --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </component> +</class>]]></programlisting> + + </section> + + <section id="components-incollections" revision="1"> + <title>Collections of dependent objects</title> + + <para> + Collections of components are supported (e.g. an array of type + <literal>Name</literal>). Declare your component collection by + replacing the <literal>&lt;element&gt;</literal> tag with a + <literal>&lt;composite-element&gt;</literal> tag: + </para> + + <programlisting role="XML"><![CDATA[<set name="someNames" table="some_names" lazy="true"> + <key column="id"/> + <composite-element class="eg.Name"> <!-- class attribute required --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </composite-element> +</set>]]></programlisting> + + <important> + <para> + If you define a <literal>Set</literal> of composite elements, it is + important to implement <literal>equals()</literal> and + <literal>hashCode()</literal> correctly. + </para> + </important> + + <para> + Composite elements can contain components but not collections. If your + composite element contains + components, use the <literal>&lt;nested-composite-element&gt;</literal> + tag. This case is a collection of components which + themselves have components. You may want to consider if + a one-to-many association is more appropriate. Remodel the + composite element as an entity, but be aware that even though the Java model + is the same, the relational model and persistence semantics are still + slightly different. + </para> + + <para> + A composite element mapping does not support null-able properties + if you are using a <literal>&lt;set&gt;</literal>. There is no separate primary key column + in the composite element table. Hibernate + uses each column's value to identify a record when deleting objects, + which is not possible with null values. You have to either use only + not-null properties in a composite-element or choose a + <literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</literal>, + <literal>&lt;bag&gt;</literal> or <literal>&lt;idbag&gt;</literal>. + </para> + + <para> + A special case of a composite element is a composite element with a nested + <literal>&lt;many-to-one&gt;</literal> element. This mapping allows + you to map extra columns of a many-to-many association table to the + composite element class. The following is a many-to-many association + from <literal>Order</literal> to <literal>Item</literal>, where + <literal>purchaseDate</literal>, <literal>price</literal> and + <literal>quantity</literal> are properties of the association: + </para> + + <programlisting role="XML"><![CDATA[<class name="eg.Order" .... > + .... + <set name="purchasedItems" table="purchase_items" lazy="true"> + <key column="order_id"> + <composite-element class="eg.Purchase"> + <property name="purchaseDate"/> + <property name="price"/> + <property name="quantity"/> + <many-to-one name="item" class="eg.Item"/> <!-- class attribute is optional --> + </composite-element> + </set> +</class>]]></programlisting> + + <para> + There cannot be a reference to the purchase on the other side for + bidirectional association navigation. Components are value types and + do not allow shared references. A single <literal>Purchase</literal> can be in the + set of an <literal>Order</literal>, but it cannot be referenced by the <literal>Item</literal> + at the same time. + </para> + + <para>Even ternary (or quaternary, etc) associations are possible:</para> + + <programlisting role="XML"><![CDATA[<class name="eg.Order" .... > + .... + <set name="purchasedItems" table="purchase_items" lazy="true"> + <key column="order_id"> + <composite-element class="eg.OrderLine"> + <many-to-one name="purchaseDetails class="eg.Purchase"/> + <many-to-one name="item" class="eg.Item"/> + </composite-element> + </set> +</class>]]></programlisting> + + <para> + Composite elements can appear in queries using the same syntax as + associations to other entities. + </para> + + </section> + + <section id="components-asmapindex"> + <title>Components as Map indices</title> + + <para> + The <literal>&lt;composite-map-key&gt;</literal> element allows you to map a + component class as the key of a <literal>Map</literal>. Ensure that you override + <literal>hashCode()</literal> and <literal>equals()</literal> correctly on + the component class. + </para> + </section> + + <section id="components-compositeid" revision="1"> + <title>Components as composite identifiers</title> + + <para> + You can use a component as an identifier of an entity class. Your component + class must satisfy certain requirements: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + It must implement <literal>java.io.Serializable</literal>. + </para> + </listitem> + <listitem> + <para> + It must re-implement <literal>equals()</literal> and + <literal>hashCode()</literal> consistently with the database's + notion of composite key equality. + </para> + </listitem> + </itemizedlist> + + <note> + <title>Note</title> + <para> + In Hibernate3, although the second requirement is not an absolutely hard + requirement of Hibernate, it is recommended. + </para> + </note> + + <para> + You cannot use an <literal>IdentifierGenerator</literal> to generate composite keys. + Instead the application must assign its own identifiers. + </para> + + <para> + Use the <literal>&lt;composite-id&gt;</literal> tag, with nested + <literal>&lt;key-property&gt;</literal> elements, in place of the usual + <literal>&lt;id&gt;</literal> declaration. For example, the + <literal>OrderLine</literal> class has a primary key that depends upon + the (composite) primary key of <literal>Order</literal>. + </para> + + <programlisting role="XML"><![CDATA[<class name="OrderLine"> + + <composite-id name="id" class="OrderLineId"> + <key-property name="lineId"/> + <key-property name="orderId"/> + <key-property name="customerId"/> + </composite-id> + + <property name="name"/> + + <many-to-one name="order" class="Order" + insert="false" update="false"> + <column name="orderId"/> + <column name="customerId"/> + </many-to-one> + .... + +</class>]]></programlisting> + + <para> + Any foreign keys referencing the <literal>OrderLine</literal> table are now + composite. Declare this in your mappings for other classes. An association + to <literal>OrderLine</literal> is mapped like this: + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="orderLine" class="OrderLine"> +<!-- the "class" attribute is optional, as usual --> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> +</many-to-one>]]></programlisting> + + <tip> + <para> + The <literal>column</literal> element is an alternative to the + <literal>column</literal> attribute everywhere. Using the + <literal>column</literal> element just gives more declaration + options, which are mostly useful when utilizing + <literal>hbm2ddl</literal> + </para> + </tip> + + <para> + A <literal>many-to-many</literal> association to <literal>OrderLine</literal> also + uses the composite foreign key: + </para> + + <programlisting role="XML"><![CDATA[<set name="undeliveredOrderLines"> + <key column name="warehouseId"/> + <many-to-many class="OrderLine"> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> + </many-to-many> +</set>]]></programlisting> + + <para> + The collection of <literal>OrderLine</literal>s in <literal>Order</literal> would + use: + </para> + + <programlisting role="XML"><![CDATA[<set name="orderLines" inverse="true"> + <key> + <column name="orderId"/> + <column name="customerId"/> + </key> + <one-to-many class="OrderLine"/> +</set>]]></programlisting> + + <para> + The <literal>&lt;one-to-many&gt;</literal> element declares no columns. + </para> + + <para> + If <literal>OrderLine</literal> itself owns a collection, it also has a composite + foreign key. + </para> + + <programlisting role="XML"><![CDATA[<class name="OrderLine"> + .... + .... + <list name="deliveryAttempts"> + <key> <!-- a collection inherits the composite key type --> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> + </key> + <list-index column="attemptId" base="1"/> + <composite-element class="DeliveryAttempt"> + ... + </composite-element> + </set> +</class>]]></programlisting> + + </section> + + <section id="components-dynamic" revision="1"> + <title>Dynamic components</title> + + <para> + You can also map a property of type <literal>Map</literal>: + </para> + + <programlisting role="XML"><![CDATA[<dynamic-component name="userAttributes"> + <property name="foo" column="FOO" type="string"/> + <property name="bar" column="BAR" type="integer"/> + <many-to-one name="baz" class="Baz" column="BAZ_ID"/> +</dynamic-component>]]></programlisting> + + <para> + The semantics of a <literal>&lt;dynamic-component&gt;</literal> mapping are identical + to <literal>&lt;component&gt;</literal>. The advantage of this kind of mapping is + the ability to determine the actual properties of the bean at deployment time just + by editing the mapping document. Runtime manipulation of the mapping document is + also possible, using a DOM parser. You can also access, and change, Hibernate's + configuration-time metamodel via the <literal>Configuration</literal> object. + </para> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/configuration.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/configuration.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/configuration.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1767 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="session-configuration" revision="1"> + <title>Configuration</title> + + <para> + Hibernate is designed to operate in many different environments and, as such, there + is a broad range of configuration parameters. Fortunately, most have sensible + default values and Hibernate is distributed with an example + <literal>hibernate.properties</literal> file in <literal>etc/</literal> that displays + the various options. Simply put the example file in your classpath and customize it to suit your needs. + </para> + + <section id="configuration-programmatic" revision="1"> + <title>Programmatic configuration</title> + + <para> + An instance of <classname>org.hibernate.cfg.Configuration</classname> represents an entire set of mappings + of an application's Java types to an SQL database. The <classname>org.hibernate.cfg.Configuration</classname> + is used to build an immutable <interfacename>org.hibernate.SessionFactory</interfacename>. The mappings + are compiled from various XML mapping files. + </para> + + <para> + You can obtain a <classname>org.hibernate.cfg.Configuration</classname> instance by instantiating + it directly and specifying XML mapping documents. If the mapping files are in the classpath, + use <literal>addResource()</literal>. For example: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = new Configuration() + .addResource("Item.hbm.xml") + .addResource("Bid.hbm.xml");]]></programlisting> + + <para> + An alternative way is to specify the mapped class and + allow Hibernate to find the mapping document for you: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = new Configuration() + .addClass(org.hibernate.auction.Item.class) + .addClass(org.hibernate.auction.Bid.class);]]></programlisting> + + <para> + Hibernate will then search for mapping files named <filename>/org/hibernate/auction/Item.hbm.xml</filename> + and <filename>/org/hibernate/auction/Bid.hbm.xml</filename> in the classpath. This approach eliminates any + hardcoded filenames. + </para> + + <para> + A <classname>org.hibernate.cfg.Configuration</classname> also allows you to specify configuration + properties. For example: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = new Configuration() + .addClass(org.hibernate.auction.Item.class) + .addClass(org.hibernate.auction.Bid.class) + .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect") + .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test") + .setProperty("hibernate.order_updates", "true");]]></programlisting> + + <para> + This is not the only way to pass configuration properties to Hibernate. + Some alternative options include: + </para> + + <orderedlist spacing="compact"> + <listitem> + <para> + Pass an instance of <classname>java.util.Properties</classname> to + <literal>Configuration.setProperties()</literal>. + </para> + </listitem> + <listitem> + <para> + Place a file named <filename>hibernate.properties</filename> in a root directory of the classpath. + </para> + </listitem> + <listitem> + <para> + Set <literal>System</literal> properties using <literal>java -Dproperty=value</literal>. + </para> + </listitem> + <listitem> + <para> + Include <literal>&lt;property&gt;</literal> elements in + <literal>hibernate.cfg.xml</literal> (this is discussed later). + </para> + </listitem> + </orderedlist> + + <para> + If you want to get started quickly<filename>hibernate.properties</filename> is the easiest approach. + </para> + + <para> + The <classname>org.hibernate.cfg.Configuration</classname> is intended as a startup-time object that will + be discarded once a <literal>SessionFactory</literal> is created. + </para> + + </section> + + <section id="configuration-sessionfactory"> + <title>Obtaining a SessionFactory</title> + + <para> + When all mappings have been parsed by the <classname>org.hibernate.cfg.Configuration</classname>, + the application must obtain a factory for <interfacename>org.hibernate.Session</interfacename> instances. + This factory is intended to be shared by all application threads: + </para> + + <programlisting role="JAVA"><![CDATA[SessionFactory sessions = cfg.buildSessionFactory();]]></programlisting> + + <para> + Hibernate does allow your application to instantiate more than one + <interfacename>org.hibernate.SessionFactory</interfacename>. This is useful if you are using more than + one database. + </para> + + </section> + + <section id="configuration-hibernatejdbc" revision="1"> + <title>JDBC connections</title> + + <para> + It is advisable to have the <interfacename>org.hibernate.SessionFactory</interfacename> create and pool + JDBC connections for you. If you take this approach, opening a <interfacename>org.hibernate.Session</interfacename> + is as simple as: + </para> + + <programlisting role="JAVA"><![CDATA[Session session = sessions.openSession(); // open a new Session]]></programlisting> + + <para> + Once you start a task that requires access to the database, a JDBC connection will be obtained from + the pool. + </para> + + <para> + Before you can do this, you first need to pass some JDBC connection properties to Hibernate. All Hibernate property + names and semantics are defined on the class <classname>org.hibernate.cfg.Environment</classname>. + The most important settings for JDBC connection configuration are outlined below. + </para> + + <para> + Hibernate will obtain and pool connections using <classname>java.sql.DriverManager</classname> + if you set the following properties: + </para> + + <table frame="topbot"> + <title>Hibernate JDBC Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <property>hibernate.connection.driver_class</property> + </entry> + <entry> + <emphasis>JDBC driver class</emphasis> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.url</property> + </entry> + <entry> + <emphasis>JDBC URL</emphasis> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.username</property> + </entry> + <entry> + <emphasis>database user</emphasis> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.password</property> + </entry> + <entry> + <emphasis>database user password</emphasis> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.pool_size</property> + </entry> + <entry> + <emphasis>maximum number of pooled connections</emphasis> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Hibernate's own connection pooling algorithm is, however, quite rudimentary. + It is intended to help you get started and is <emphasis>not intended for use + in a production system</emphasis>, or even for performance testing. You should + use a third party pool for best performance and stability. Just replace the + <property>hibernate.connection.pool_size</property> property with connection + pool specific settings. This will turn off Hibernate's internal pool. For + example, you might like to use c3p0. + </para> + + <para> + C3P0 is an open source JDBC connection pool distributed along with Hibernate in the <filename>lib</filename> + directory. Hibernate will use its <classname>org.hibernate.connection.C3P0ConnectionProvider</classname> + for connection pooling if you set <property>hibernate.c3p0.*</property> properties. If you would like to use Proxool, + refer to the packaged <filename>hibernate.properties</filename> and the Hibernate web site for more + information. + </para> + + <para> + The following is an example <filename>hibernate.properties</filename> file for c3p0: + </para> + + + <programlisting><![CDATA[hibernate.connection.driver_class = org.postgresql.Driver +hibernate.connection.url = jdbc:postgresql://localhost/mydatabase +hibernate.connection.username = myuser +hibernate.connection.password = secret +hibernate.c3p0.min_size=5 +hibernate.c3p0.max_size=20 +hibernate.c3p0.timeout=1800 +hibernate.c3p0.max_statements=50 +hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting> + + <para> + For use inside an application server, you should almost always configure Hibernate to obtain connections + from an application server <interfacename>javax.sql.Datasource</interfacename> registered in JNDI. You will + need to set at least one of the following properties: + </para> + + <table frame="topbot"> + <title>Hibernate Datasource Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <property>hibernate.connection.datasource</property> + </entry> + <entry> + <emphasis>datasource JNDI name</emphasis> + </entry> + </row> + <row> + <entry> + <property>hibernate.jndi.url</property> + </entry> + <entry> + <emphasis>URL of the JNDI provider</emphasis> (optional) + </entry> + </row> + <row> + <entry> + <property>hibernate.jndi.class</property> + </entry> + <entry> + <emphasis>class of the JNDI <literal>InitialContextFactory</literal></emphasis> (optional) + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.username</property> + </entry> + <entry> + <emphasis>database user</emphasis> (optional) + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.password</property> + </entry> + <entry> + <emphasis>database user password</emphasis> (optional) + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Here is an example <filename>hibernate.properties</filename> file for an application server provided JNDI + datasource: + </para> + + <programlisting><![CDATA[hibernate.connection.datasource = java:/comp/env/jdbc/test +hibernate.transaction.factory_class = \ + org.hibernate.transaction.JTATransactionFactory +hibernate.transaction.manager_lookup_class = \ + org.hibernate.transaction.JBossTransactionManagerLookup +hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting> + + <para> + JDBC connections obtained from a JNDI datasource will automatically participate + in the container-managed transactions of the application server. + </para> + + <para> + Arbitrary connection properties can be given by prepending "<literal>hibernate.connection</literal>" to the + connection property name. For example, you can specify a <property>charSet</property> + connection property using <property>hibernate.connection.charSet</property>. + </para> + + <para> + You can define your own plugin strategy for obtaining JDBC connections by implementing the + interface <interfacename>org.hibernate.connection.ConnectionProvider</interfacename>, and specifying your + custom implementation via the <property>hibernate.connection.provider_class</property> property. + </para> + + </section> + + <section id="configuration-optional" revision="1"> + <title>Optional configuration properties</title> + + <para> + There are a number of other properties that control the behavior of Hibernate at runtime. All are optional + and have reasonable default values. + </para> + + <para> + <warning><para><emphasis>Some of these properties are "system-level" only.</emphasis> System-level properties can + be set only via <literal>java -Dproperty=value</literal> or <filename>hibernate.properties</filename>. They + <emphasis>cannot</emphasis> be set by the other techniques described above.</para></warning> + </para> + + <table frame="topbot" id="configuration-optional-properties" revision="8"> + <title>Hibernate Configuration Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <property>hibernate.dialect</property> + </entry> + <entry> + The classname of a Hibernate <classname>org.hibernate.dialect.Dialect</classname> which + allows Hibernate to generate SQL optimized for a particular relational database. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>full.classname.of.Dialect</literal> + </para> + <para> + In most cases Hibernate will actually be able to choose the correct + <classname>org.hibernate.dialect.Dialect</classname> implementation based on the + <literal>JDBC metadata</literal> returned by the JDBC driver. + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.show_sql</property> + </entry> + <entry> + Write all SQL statements to console. This is an alternative + to setting the log category <literal>org.hibernate.SQL</literal> + to <literal>debug</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.format_sql</property> + </entry> + <entry> + Pretty print the SQL in the log and console. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.default_schema</property> + </entry> + <entry> + Qualify unqualified table names with the given schema/tablespace + in generated SQL. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>SCHEMA_NAME</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.default_catalog</property> + </entry> + <entry> + Qualifies unqualified table names with the given catalog + in generated SQL. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>CATALOG_NAME</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.session_factory_name</property> + </entry> + <entry> + The <interfacename>org.hibernate.SessionFactory</interfacename> will be automatically + bound to this name in JNDI after it has been created. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>jndi/composite/name</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.max_fetch_depth</property> + </entry> + <entry> + Sets a maximum "depth" for the outer join fetch tree + for single-ended associations (one-to-one, many-to-one). + A <literal>0</literal> disables default outer join fetching. + <para> + <emphasis role="strong">e.g.</emphasis> + recommended values between <literal>0</literal> and + <literal>3</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.default_batch_fetch_size</property> + </entry> + <entry> + Sets a default size for Hibernate batch fetching of associations. + <para> + <emphasis role="strong">e.g.</emphasis> + recommended values <literal>4</literal>, <literal>8</literal>, + <literal>16</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.default_entity_mode</property> + </entry> + <entry> + Sets a default mode for entity representation for all sessions + opened from this <literal>SessionFactory</literal> + <para> + <literal>dynamic-map</literal>, <literal>dom4j</literal>, + <literal>pojo</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.order_updates</property> + </entry> + <entry> + Forces Hibernate to order SQL updates by the primary key value + of the items being updated. This will result in fewer transaction + deadlocks in highly concurrent systems. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.generate_statistics</property> + </entry> + <entry> + If enabled, Hibernate will collect statistics useful for + performance tuning. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.use_identifier_rollback</property> + </entry> + <entry> + If enabled, generated identifier properties will be + reset to default values when objects are deleted. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.use_sql_comments</property> + </entry> + <entry> + If turned on, Hibernate will generate comments inside the SQL, for + easier debugging, defaults to <literal>false</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-jdbc-properties" revision="8"> + <title>Hibernate JDBC and Connection Properties</title> + <tgroup cols="2"> +<!-- + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> +--> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <property>hibernate.jdbc.fetch_size</property> + </entry> + <entry> + A non-zero value determines the JDBC fetch size (calls + <literal>Statement.setFetchSize()</literal>). + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.batch_size</property> + </entry> + <entry> + A non-zero value enables use of JDBC2 batch updates by Hibernate. + <para> + <emphasis role="strong">e.g.</emphasis> + recommended values between <literal>5</literal> and <literal>30</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.batch_versioned_data</property> + </entry> + <entry> + Set this property to <literal>true</literal> if your JDBC driver returns + correct row counts from <literal>executeBatch()</literal>. Iit is usually + safe to turn this option on. Hibernate will then use batched DML for + automatically versioned data. Defaults to <literal>false</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.factory_class</property> + </entry> + <entry> + Select a custom <interfacename>org.hibernate.jdbc.Batcher</interfacename>. Most applications + will not need this configuration property. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.BatcherFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.use_scrollable_resultset</property> + </entry> + <entry> + Enables use of JDBC2 scrollable resultsets by Hibernate. + This property is only necessary when using user-supplied + JDBC connections. Hibernate uses connection metadata otherwise. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.use_streams_for_binary</property> + </entry> + <entry> + Use streams when writing/reading <literal>binary</literal> or <literal>serializable</literal> + types to/from JDBC. <emphasis>*system-level property*</emphasis> + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.jdbc.use_get_generated_keys</property> + </entry> + <entry> + Enables use of JDBC3 <literal>PreparedStatement.getGeneratedKeys()</literal> + to retrieve natively generated keys after insert. Requires JDBC3+ driver + and JRE1.4+, set to false if your driver has problems with the Hibernate + identifier generators. By default, it tries to determine the driver capabilities + using connection metadata. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.provider_class</property> + </entry> + <entry> + The classname of a custom <interfacename>org.hibernate.connection.ConnectionProvider</interfacename> + which provides JDBC connections to Hibernate. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.ConnectionProvider</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.isolation</property> + </entry> + <entry> + Sets the JDBC transaction isolation level. Check <interfacename>java.sql.Connection</interfacename> + for meaningful values, but note that most databases do not support all isolation levels and some + define additional, non-standard isolations. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>1, 2, 4, 8</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.autocommit</property> + </entry> + <entry> + Enables autocommit for JDBC pooled connections (it is not recommended). + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.release_mode</property> + </entry> + <entry> + Specifies when Hibernate should release JDBC connections. By default, + a JDBC connection is held until the session is explicitly closed or + disconnected. For an application server JTA datasource, use + <literal>after_statement</literal> to aggressively release connections + after every JDBC call. For a non-JTA connection, it often makes sense to + release the connection at the end of each transaction, by using + <literal>after_transaction</literal>. <literal>auto</literal> will + choose <literal>after_statement</literal> for the JTA and CMT transaction + strategies and <literal>after_transaction</literal> for the JDBC + transaction strategy. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>auto</literal> (default) | <literal>on_close</literal> | + <literal>after_transaction</literal> | <literal>after_statement</literal> + </para> + <para> + This setting only affects <literal>Session</literal>s returned from + <literal>SessionFactory.openSession</literal>. For <literal>Session</literal>s + obtained through <literal>SessionFactory.getCurrentSession</literal>, the + <literal>CurrentSessionContext</literal> implementation configured for use + controls the connection release mode for those <literal>Session</literal>s. + See <xref linkend="architecture-current-session"/> + </para> + </entry> + </row> + <row> + <entry> + <property>hibernate.connection.</property><emphasis>&lt;propertyName&gt;</emphasis> + </entry> + <entry> + Pass the JDBC property <emphasis>&lt;propertyName&gt;</emphasis> + to <literal>DriverManager.getConnection()</literal>. + </entry> + </row> + <row> + <entry> + <property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis> + </entry> + <entry> + Pass the property <emphasis>&lt;propertyName&gt;</emphasis> to + the JNDI <literal>InitialContextFactory</literal>. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-cache-properties" revision="7"> + <title>Hibernate Cache Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.cache.provider_class</literal> + </entry> + <entry> + The classname of a custom <literal>CacheProvider</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.CacheProvider</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_minimal_puts</literal> + </entry> + <entry> + Optimizes second-level cache operation to minimize writes, at the + cost of more frequent reads. This setting is most useful for + clustered caches and, in Hibernate3, is enabled by default for + clustered cache implementations. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_query_cache</literal> + </entry> + <entry> + Enables the query cache. Individual queries still have to be set cachable. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_second_level_cache</literal> + </entry> + <entry> + Can be used to completely disable the second level cache, which is enabled + by default for classes which specify a <literal>&lt;cache&gt;</literal> + mapping. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.query_cache_factory</literal> + </entry> + <entry> + The classname of a custom <literal>QueryCache</literal> interface, + defaults to the built-in <literal>StandardQueryCache</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.QueryCache</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.region_prefix</literal> + </entry> + <entry> + A prefix to use for second-level cache region names. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>prefix</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_structured_entries</literal> + </entry> + <entry> + Forces Hibernate to store data in the second-level cache + in a more human-friendly format. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-transaction-properties" revision="9"> + <title>Hibernate Transaction Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.transaction.factory_class</literal> + </entry> + <entry> + The classname of a <literal>TransactionFactory</literal> + to use with Hibernate <literal>Transaction</literal> API + (defaults to <literal>JDBCTransactionFactory</literal>). + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.TransactionFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>jta.UserTransaction</literal> + </entry> + <entry> + A JNDI name used by <literal>JTATransactionFactory</literal> to + obtain the JTA <literal>UserTransaction</literal> from the + application server. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>jndi/composite/name</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.manager_lookup_class</literal> + </entry> + <entry> + The classname of a <literal>TransactionManagerLookup</literal>. It is + required when JVM-level caching is enabled or when using hilo + generator in a JTA environment. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>classname.of.TransactionManagerLookup</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.flush_before_completion</literal> + </entry> + <entry> + If enabled, the session will be automatically flushed during the + before completion phase of the transaction. Built-in and + automatic session context management is preferred, see + <xref linkend="architecture-current-session"/>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.auto_close_session</literal> + </entry> + <entry> + If enabled, the session will be automatically closed during the + after completion phase of the transaction. Built-in and + automatic session context management is preferred, see + <xref linkend="architecture-current-session"/>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-misc-properties" revision="10"> + <title>Miscellaneous Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Property name</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.current_session_context_class</literal> + </entry> + <entry> + Supply a custom strategy for the scoping of the "current" + <literal>Session</literal>. See + <xref linkend="architecture-current-session"/> for more + information about the built-in strategies. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>jta</literal> | <literal>thread</literal> | + <literal>managed</literal> | <literal>custom.Class</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.query.factory_class</literal> + </entry> + <entry> + Chooses the HQL parser implementation. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>org.hibernate.hql.ast.ASTQueryTranslatorFactory</literal> or + <literal>org.hibernate.hql.classic.ClassicQueryTranslatorFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.query.substitutions</literal> + </entry> + <entry> + Is used to map from tokens in Hibernate queries to SQL tokens + (tokens might be function or literal names, for example). + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.hbm2ddl.auto</literal> + </entry> + <entry> + Automatically validates or exports schema DDL to the database + when the <literal>SessionFactory</literal> is created. With + <literal>create-drop</literal>, the database schema will be + dropped when the <literal>SessionFactory</literal> is closed + explicitly. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>validate</literal> | <literal>update</literal> | + <literal>create</literal> | <literal>create-drop</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cglib.use_reflection_optimizer</literal> + </entry> + <entry> + Enables the use of CGLIB instead of runtime reflection (System-level + property). Reflection can sometimes be useful when troubleshooting. + Hibernate always requires CGLIB even if you turn off the + optimizer. You cannot set this property in <literal>hibernate.cfg.xml</literal>. + <para> + <emphasis role="strong">e.g.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <section id="configuration-optional-dialects" revision="1"> + <title>SQL Dialects</title> + + <para> + Always set the <literal>hibernate.dialect</literal> property to the correct + <literal>org.hibernate.dialect.Dialect</literal> subclass for your database. If you + specify a dialect, Hibernate will use sensible defaults for some of the + other properties listed above. This means that you will not have to specify them manually. + </para> + + <table frame="topbot" id="sql-dialects" revision="3"> + <title>Hibernate SQL Dialects (<literal>hibernate.dialect</literal>)</title> + <tgroup cols="2"> +<!-- + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> +--> + <thead> + <row> + <entry>RDBMS</entry> + <entry>Dialect</entry> + </row> + </thead> + <tbody> + <row> + <entry>DB2</entry> <entry><literal>org.hibernate.dialect.DB2Dialect</literal></entry> + </row> + <row> + <entry>DB2 AS/400</entry> <entry><literal>org.hibernate.dialect.DB2400Dialect</literal></entry> + </row> + <row> + <entry>DB2 OS390</entry> <entry><literal>org.hibernate.dialect.DB2390Dialect</literal></entry> + </row> + <row> + <entry>PostgreSQL</entry> <entry><literal>org.hibernate.dialect.PostgreSQLDialect</literal></entry> + </row> + <row> + <entry>MySQL</entry> <entry><literal>org.hibernate.dialect.MySQLDialect</literal></entry> + </row> + <row> + <entry>MySQL with InnoDB</entry> <entry><literal>org.hibernate.dialect.MySQLInnoDBDialect</literal></entry> + </row> + <row> + <entry>MySQL with MyISAM</entry> <entry><literal>org.hibernate.dialect.MySQLMyISAMDialect</literal></entry> + </row> + <row> + <entry>Oracle (any version)</entry> <entry><literal>org.hibernate.dialect.OracleDialect</literal></entry> + </row> + <row> + <entry>Oracle 9i</entry> <entry><literal>org.hibernate.dialect.Oracle9iDialect</literal></entry> + </row> + <row> + <entry>Oracle 10g</entry> <entry><literal>org.hibernate.dialect.Oracle10gDialect</literal></entry> + </row> + <row> + <entry>Sybase</entry> <entry><literal>org.hibernate.dialect.SybaseDialect</literal></entry> + </row> + <row> + <entry>Sybase Anywhere</entry> <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry> + </row> + <row> + <entry>Microsoft SQL Server</entry> <entry><literal>org.hibernate.dialect.SQLServerDialect</literal></entry> + </row> + <row> + <entry>SAP DB</entry> <entry><literal>org.hibernate.dialect.SAPDBDialect</literal></entry> + </row> + <row> + <entry>Informix</entry> <entry><literal>org.hibernate.dialect.InformixDialect</literal></entry> + </row> + <row> + <entry>HypersonicSQL</entry> <entry><literal>org.hibernate.dialect.HSQLDialect</literal></entry> + </row> + <row> + <entry>Ingres</entry> <entry><literal>org.hibernate.dialect.IngresDialect</literal></entry> + </row> + <row> + <entry>Progress</entry> <entry><literal>org.hibernate.dialect.ProgressDialect</literal></entry> + </row> + <row> + <entry>Mckoi SQL</entry> <entry><literal>org.hibernate.dialect.MckoiDialect</literal></entry> + </row> + <row> + <entry>Interbase</entry> <entry><literal>org.hibernate.dialect.InterbaseDialect</literal></entry> + </row> + <row> + <entry>Pointbase</entry> <entry><literal>org.hibernate.dialect.PointbaseDialect</literal></entry> + </row> + <row> + <entry>FrontBase</entry> <entry><literal>org.hibernate.dialect.FrontbaseDialect</literal></entry> + </row> + <row> + <entry>Firebird</entry> <entry><literal>org.hibernate.dialect.FirebirdDialect</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="configuration-optional-outerjoin" revision="4"> + <title>Outer Join Fetching</title> + + <para> + If your database supports ANSI, Oracle or Sybase style outer joins, <emphasis>outer join + fetching</emphasis> will often increase performance by limiting the number of round + trips to and from the database. This is, however, at the cost of possibly more work performed by + the database itself. Outer join fetching allows a whole graph of objects connected + by many-to-one, one-to-many, many-to-many and one-to-one associations to be retrieved + in a single SQL <literal>SELECT</literal>. + </para> + + <para> + Outer join fetching can be disabled <emphasis>globally</emphasis> by setting + the property <literal>hibernate.max_fetch_depth</literal> to <literal>0</literal>. + A setting of <literal>1</literal> or higher enables outer join fetching for + one-to-one and many-to-one associations that have been mapped with + <literal>fetch="join"</literal>. + </para> + + <para> + See <xref linkend="performance-fetching"/> for more information. + </para> + + </section> + + <section id="configuration-optional-binarystreams" revision="1"> + <title>Binary Streams</title> + + <para> + Oracle limits the size of <literal>byte</literal> arrays that can + be passed to and/or from its JDBC driver. If you wish to use large instances of + <literal>binary</literal> or <literal>serializable</literal> type, you should + enable <literal>hibernate.jdbc.use_streams_for_binary</literal>. + <emphasis>This is a system-level setting only.</emphasis> + </para> + + </section> + + <section id="configuration-optional-cacheprovider" revision="2"> + <title>Second-level and query cache</title> + + <para> + The properties prefixed by <literal>hibernate.cache</literal> + allow you to use a process or cluster scoped second-level cache system + with Hibernate. See the <xref linkend="performance-cache"/> for + more information. + </para> + + </section> + + <section id="configuration-optional-querysubstitution"> + <title>Query Language Substitution</title> + + <para> + You can define new Hibernate query tokens using <literal>hibernate.query.substitutions</literal>. + For example: + </para> + + <programlisting>hibernate.query.substitutions true=1, false=0</programlisting> + + <para> + This would cause the tokens <literal>true</literal> and <literal>false</literal> to be translated to + integer literals in the generated SQL. + </para> + + <programlisting>hibernate.query.substitutions toLowercase=LOWER</programlisting> + + <para> + This would allow you to rename the SQL <literal>LOWER</literal> function. + </para> + + </section> + + <section id="configuration-optional-statistics" revision="2"> + <title>Hibernate statistics</title> + + <para> + If you enable <literal>hibernate.generate_statistics</literal>, Hibernate + exposes a number of metrics that are useful when tuning a running system via + <literal>SessionFactory.getStatistics()</literal>. Hibernate can even be configured + to expose these statistics via JMX. Read the Javadoc of the interfaces in + <literal>org.hibernate.stats</literal> for more information. + </para> + + </section> + </section> + + <section id="configuration-logging"> + <title>Logging</title> + + <para> + Hibernate utilizes <ulink url="http://www.slf4j.org/">Simple Logging Facade for Java</ulink> + (SLF4J) in order to log various system events. SLF4J can direct your logging output to + several logging frameworks (NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) depending on your + chosen binding. In order to setup logging you will need <filename>slf4j-api.jar</filename> in + your classpath together with the jar file for your preferred binding - <filename>slf4j-log4j12.jar</filename> + in the case of Log4J. See the SLF4J <ulink url="http://www.slf4j.org/manual.html">documentation</uli... for more detail. + To use Log4j you will also need to place a <filename>log4j.properties</filename> file in your classpath. + An example properties file is distributed with Hibernate in the <literal>src/</literal> directory. + </para> + + <para> + It is recommended that you familiarize yourself with Hibernate's log + messages. A lot of work has been put into making the Hibernate log as + detailed as possible, without making it unreadable. It is an essential + troubleshooting device. The most interesting log categories are the + following: + </para> + + <table frame="topbot" id="log-categories" revision="2"> + <title>Hibernate Log Categories</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> + <thead> + <row> + <entry>Category</entry> + <entry>Function</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>org.hibernate.SQL</literal></entry> + <entry>Log all SQL DML statements as they are executed</entry> + </row> + <row> + <entry><literal>org.hibernate.type</literal></entry> + <entry>Log all JDBC parameters</entry> + </row> + <row> + <entry><literal>org.hibernate.tool.hbm2ddl</literal></entry> + <entry>Log all SQL DDL statements as they are executed</entry> + </row> + <row> + <entry><literal>org.hibernate.pretty</literal></entry> + <entry> + Log the state of all entities (max 20 entities) associated + with the session at flush time + </entry> + </row> + <row> + <entry><literal>org.hibernate.cache</literal></entry> + <entry>Log all second-level cache activity</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction</literal></entry> + <entry>Log transaction related activity</entry> + </row> + <row> + <entry><literal>org.hibernate.jdbc</literal></entry> + <entry>Log all JDBC resource acquisition</entry> + </row> + <row> + <entry><literal>org.hibernate.hql.ast.AST</literal></entry> + <entry> + Log HQL and SQL ASTs during query parsing + </entry> + </row> + <row> + <entry><literal>org.hibernate.secure</literal></entry> + <entry>Log all JAAS authorization requests</entry> + </row> + <row> + <entry><literal>org.hibernate</literal></entry> + <entry> + Log everything. This is a lot of information but it is useful for + troubleshooting + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + When developing applications with Hibernate, you should almost always work with + <literal>debug</literal> enabled for the category <literal>org.hibernate.SQL</literal>, + or, alternatively, the property <literal>hibernate.show_sql</literal> enabled. + </para> + + + </section> + + <section id="configuration-namingstrategy"> + <title>Implementing a <literal>NamingStrategy</literal></title> + + <para> + The interface <literal>org.hibernate.cfg.NamingStrategy</literal> allows you + to specify a "naming standard" for database objects and schema elements. + </para> + + <para> + You can provide rules for automatically generating database identifiers from + Java identifiers or for processing "logical" column and table names given in + the mapping file into "physical" table and column names. This feature helps + reduce the verbosity of the mapping document, eliminating repetitive noise + (<literal>TBL_</literal> prefixes, for example). The default strategy used by + Hibernate is quite minimal. + </para> + + <para> + You can specify a different strategy by calling + <literal>Configuration.setNamingStrategy()</literal> before adding mappings: + </para> + + <programlisting role="JAVA"><![CDATA[SessionFactory sf = new Configuration() + .setNamingStrategy(ImprovedNamingStrategy.INSTANCE) + .addFile("Item.hbm.xml") + .addFile("Bid.hbm.xml") + .buildSessionFactory();]]></programlisting> + + <para> + <literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a built-in + strategy that might be a useful starting point for some applications. + </para> + + </section> + + <section id="configuration-xmlconfig" revision="2"> + <title>XML configuration file</title> + + <para> + An alternative approach to configuration is to specify a full configuration in + a file named <literal>hibernate.cfg.xml</literal>. This file can be used as a + replacement for the <literal>hibernate.properties</literal> file or, if both + are present, to override properties. + </para> + + <para> + The XML configuration file is by default expected to be in the root of + your <literal>CLASSPATH</literal>. Here is an example: + </para> + + <programlisting role="XML"><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> + +<hibernate-configuration> + + <!-- a SessionFactory instance listed as /jndi/name --> + <session-factory + name="java:hibernate/SessionFactory"> + + <!-- properties --> + <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property> + <property name="dialect">org.hibernate.dialect.MySQLDialect</property> + <property name="show_sql">false</property> + <property name="transaction.factory_class"> + org.hibernate.transaction.JTATransactionFactory + </property> + <property name="jta.UserTransaction">java:comp/UserTransaction</property> + + <!-- mapping files --> + <mapping resource="org/hibernate/auction/Item.hbm.xml"/> + <mapping resource="org/hibernate/auction/Bid.hbm.xml"/> + + <!-- cache settings --> + <class-cache class="org.hibernate.auction.Item" usage="read-write"/> + <class-cache class="org.hibernate.auction.Bid" usage="read-only"/> + <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/> + + </session-factory> + +</hibernate-configuration>]]></programlisting> + + <para> + The advantage of this approach is the externalization of the + mapping file names to configuration. The <literal>hibernate.cfg.xml</literal> + is also more convenient once you have to tune the Hibernate cache. It is + your choice to use either <literal>hibernate.properties</literal> or + <literal>hibernate.cfg.xml</literal>. Both are equivalent, except for the above + mentioned benefits of using the XML syntax. + </para> + + <para> + With the XML configuration, starting Hibernate is then as simple as: + </para> + + <programlisting role="JAVA"><![CDATA[SessionFactory sf = new Configuration().configure().buildSessionFactory();]]></programlisting> + + <para> + You can select a different XML configuration file using: + </para> + + <programlisting role="JAVA"><![CDATA[SessionFactory sf = new Configuration() + .configure("catdb.cfg.xml") + .buildSessionFactory();]]></programlisting> + + </section> + + <section id="configuration-j2ee" revision="1"> + <title>J2EE Application Server integration</title> + + <para> + Hibernate has the following integration points for J2EE infrastructure: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Container-managed datasources</emphasis>: Hibernate can use + JDBC connections managed by the container and provided through JNDI. Usually, + a JTA compatible <literal>TransactionManager</literal> and a + <literal>ResourceManager</literal> take care of transaction management (CMT), + especially distributed transaction handling across several datasources. You can + also demarcate transaction boundaries programmatically (BMT), or + you might want to use the optional Hibernate <literal>Transaction</literal> + API for this to keep your code portable. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>Automatic JNDI binding</emphasis>: Hibernate can bind its + <literal>SessionFactory</literal> to JNDI after startup. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>JTA Session binding:</emphasis> the Hibernate <literal>Session</literal> + can be automatically bound to the scope of JTA transactions. Simply + lookup the <literal>SessionFactory</literal> from JNDI and get the current + <literal>Session</literal>. Let Hibernate manage flushing and closing the + <literal>Session</literal> when your JTA transaction completes. Transaction + demarcation is either declarative (CMT) or programmatic (BMT/UserTransaction). + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>JMX deployment:</emphasis> if you have a JMX capable application server + (e.g. JBoss AS), you can choose to deploy Hibernate as a managed MBean. This saves + you the one line startup code to build your <literal>SessionFactory</literal> from + a <literal>Configuration</literal>. The container will startup your + <literal>HibernateService</literal> and also take care of service + dependencies (datasource has to be available before Hibernate starts, etc). + </para> + </listitem> + </itemizedlist> + + <para> + Depending on your environment, you might have to set the configuration option + <literal>hibernate.connection.aggressive_release</literal> to true if your + application server shows "connection containment" exceptions. + </para> + + <section id="configuration-optional-transactionstrategy" revision="3"> + <title>Transaction strategy configuration</title> + + <para> + The Hibernate <literal>Session</literal> API is independent of any transaction + demarcation system in your architecture. If you let Hibernate use JDBC directly + through a connection pool, you can begin and end your transactions by calling + the JDBC API. If you run in a J2EE application server, you might want to use bean-managed + transactions and call the JTA API and <literal>UserTransaction</literal> when needed. + </para> + + <para> + To keep your code portable between these two (and other) environments we recommend the optional + Hibernate <literal>Transaction</literal> API, which wraps and hides the underlying system. + You have to specify a factory class for <literal>Transaction</literal> instances by setting the + Hibernate configuration property <literal>hibernate.transaction.factory_class</literal>. + </para> + + <para> + There are three standard, or built-in, choices: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term><literal>org.hibernate.transaction.JDBCTransactionFactory</literal></term> + <listitem> + <para>delegates to database (JDBC) transactions (default)</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>org.hibernate.transaction.JTATransactionFactory</literal></term> + <listitem> + <para> + delegates to container-managed transactions if an existing transaction is + underway in this context (for example, EJB session bean method). Otherwise, + a new transaction is started and bean-managed transactions are used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>org.hibernate.transaction.CMTTransactionFactory</literal></term> + <listitem> + <para>delegates to container-managed JTA transactions</para> + </listitem> + </varlistentry> + </variablelist> + + <para> + You can also define your own transaction strategies (for a CORBA transaction service, + for example). + </para> + + <para> + Some features in Hibernate (i.e., the second level cache, Contextual Sessions with JTA, etc.) + require access to the JTA <literal>TransactionManager</literal> in a managed environment. + In an application server, since J2EE does not standardize a single mechanism, you have to specify how Hibernate should obtain a reference to the + <literal>TransactionManager</literal>: + </para> + + <table frame="topbot" id="jtamanagerlookup" revision="1"> + <title>JTA TransactionManagers</title> + <tgroup cols="2"> + <colspec colwidth="2.5*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Transaction Factory</entry> + <entry align="center">Application Server</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>org.hibernate.transaction.JBossTransactionManagerLookup</literal></entry> + <entry align="center">JBoss</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WeblogicTransactionManagerLookup</literal></entry> + <entry align="center">Weblogic</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WebSphereTransactionManagerLookup</literal></entry> + <entry align="center">WebSphere</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WebSphereExtendedJTATransactionLookup</literal></entry> + <entry align="center">WebSphere 6</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.OrionTransactionManagerLookup</literal></entry> + <entry align="center">Orion</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.ResinTransactionManagerLookup</literal></entry> + <entry align="center">Resin</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JOTMTransactionManagerLookup</literal></entry> + <entry align="center">JOTM</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JOnASTransactionManagerLookup</literal></entry> + <entry align="center">JOnAS</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JRun4TransactionManagerLookup</literal></entry> + <entry align="center">JRun4</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.BESTransactionManagerLookup</literal></entry> + <entry align="center">Borland ES</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="configuration-optional-jndi" revision="3"> + <title>JNDI-bound <literal>SessionFactory</literal></title> + + <para> + A JNDI-bound Hibernate <literal>SessionFactory</literal> can simplify the lookup + function of the factory and create new <literal>Session</literal>s. This + is not, however, related to a JNDI bound <literal>Datasource</literal>; both simply use the + same registry. + </para> + + <para> + If you wish to have the <literal>SessionFactory</literal> bound to a JNDI namespace, specify + a name (e.g. <literal>java:hibernate/SessionFactory</literal>) using the property + <literal>hibernate.session_factory_name</literal>. If this property is omitted, the + <literal>SessionFactory</literal> will not be bound to JNDI. This is especially useful in + environments with a read-only JNDI default implementation (in Tomcat, for example). + </para> + + <para> + When binding the <literal>SessionFactory</literal> to JNDI, Hibernate will use the values of + <literal>hibernate.jndi.url</literal>, <literal>hibernate.jndi.class</literal> to instantiate + an initial context. If they are not specified, the default <literal>InitialContext</literal> + will be used. + </para> + + <para> + Hibernate will automatically place the <literal>SessionFactory</literal> in JNDI after + you call <literal>cfg.buildSessionFactory()</literal>. This means you will have + this call in some startup code, or utility class in your application, unless you use + JMX deployment with the <literal>HibernateService</literal> (this is discussed later in greater detail). + </para> + + <para> + If you use a JNDI <literal>SessionFactory</literal>, an EJB or any other class, you can + obtain the <literal>SessionFactory</literal> using a JNDI lookup. + </para> + + <para> + It is recommended that you bind the <literal>SessionFactory</literal> to JNDI in + a managed environment and use a <literal>static</literal> singleton otherwise. + To shield your application code from these details, we also recommend to hide the + actual lookup code for a <literal>SessionFactory</literal> in a helper class, + such as <literal>HibernateUtil.getSessionFactory()</literal>. Note that such a + class is also a convenient way to startup Hibernate&mdash;see chapter 1. + </para> + + </section> + + <section id="configuration-j2ee-currentsession" revision="4"> + <title>Current Session context management with JTA</title> + + <para> + The easiest way to handle <literal>Sessions</literal> and transactions is + Hibernate's automatic "current" <literal>Session</literal> management. + For a discussion of contextual sessions see <xref linkend="architecture-current-session"/>. + Using the <literal>"jta"</literal> session context, if there is no Hibernate + <literal>Session</literal> associated with the current JTA transaction, one will + be started and associated with that JTA transaction the first time you call + <literal>sessionFactory.getCurrentSession()</literal>. The <literal>Session</literal>s + retrieved via <literal>getCurrentSession()</literal> in the<literal>"jta"</literal> context + are set to automatically flush before the transaction completes, close + after the transaction completes, and aggressively release JDBC connections + after each statement. This allows the <literal>Session</literal>s to + be managed by the life cycle of the JTA transaction to which it is associated, + keeping user code clean of such management concerns. Your code can either use + JTA programmatically through <literal>UserTransaction</literal>, or (recommended + for portable code) use the Hibernate <literal>Transaction</literal> API to set + transaction boundaries. If you run in an EJB container, declarative transaction + demarcation with CMT is preferred. + </para> + + </section> + + <section id="configuration-j2ee-jmx" revision="1"> + <title>JMX deployment</title> + + <para> + The line <literal>cfg.buildSessionFactory()</literal> still has to be executed + somewhere to get a <literal>SessionFactory</literal> into JNDI. You can do this + either in a <literal>static</literal> initializer block, like the one in + <literal>HibernateUtil</literal>, or you can deploy Hibernate as a <emphasis>managed + service</emphasis>. + </para> + + <para> + Hibernate is distributed with <literal>org.hibernate.jmx.HibernateService</literal> + for deployment on an application server with JMX capabilities, such as JBoss AS. + The actual deployment and configuration is vendor-specific. Here is an example + <literal>jboss-service.xml</literal> for JBoss 4.0.x: + </para> + + <programlisting role="XML"><![CDATA[<?xml version="1.0"?> +<server> + +<mbean code="org.hibernate.jmx.HibernateService" + name="jboss.jca:service=HibernateFactory,name=HibernateFactory"> + + <!-- Required services --> + <depends>jboss.jca:service=RARDeployer</depends> + <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends> + + <!-- Bind the Hibernate service to JNDI --> + <attribute name="JndiName">java:/hibernate/SessionFactory</attribute> + + <!-- Datasource settings --> + <attribute name="Datasource">java:HsqlDS</attribute> + <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute> + + <!-- Transaction integration --> + <attribute name="TransactionStrategy"> + org.hibernate.transaction.JTATransactionFactory</attribute> + <attribute name="TransactionManagerLookupStrategy"> + org.hibernate.transaction.JBossTransactionManagerLookup</attribute> + <attribute name="FlushBeforeCompletionEnabled">true</attribute> + <attribute name="AutoCloseSessionEnabled">true</attribute> + + <!-- Fetching options --> + <attribute name="MaximumFetchDepth">5</attribute> + + <!-- Second-level caching --> + <attribute name="SecondLevelCacheEnabled">true</attribute> + <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute> + <attribute name="QueryCacheEnabled">true</attribute> + + <!-- Logging --> + <attribute name="ShowSqlEnabled">true</attribute> + + <!-- Mapping files --> + <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute> + +</mbean> + +</server>]]></programlisting> + + <para> + This file is deployed in a directory called <literal>META-INF</literal> and packaged + in a JAR file with the extension <literal>.sar</literal> (service archive). You also need + to package Hibernate, its required third-party libraries, your compiled persistent classes, + as well as your mapping files in the same archive. Your enterprise beans (usually session + beans) can be kept in their own JAR file, but you can include this EJB JAR file in the + main service archive to get a single (hot-)deployable unit. Consult the JBoss AS + documentation for more information about JMX service and EJB deployment. + </para> + + </section> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/events.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/events.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/events.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,296 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="events"> + <title>Interceptors and events</title> + + <para> + It is useful for the application to react to certain events that occur + inside Hibernate. This allows for the implementation of generic + functionality and the extension of Hibernate functionality. + </para> + + <section id="objectstate-interceptors" revision="3"> + <title>Interceptors</title> + + <para> + The <literal>Interceptor</literal> interface provides callbacks from the session to the + application, allowing the application to inspect and/or manipulate properties of a + persistent object before it is saved, updated, deleted or loaded. One + possible use for this is to track auditing information. For example, the following + <literal>Interceptor</literal> automatically sets the <literal>createTimestamp</literal> + when an <literal>Auditable</literal> is created and updates the + <literal>lastUpdateTimestamp</literal> property when an <literal>Auditable</literal> is + updated. + </para> + + <para> + You can either implement <literal>Interceptor</literal> directly or extend + <literal>EmptyInterceptor</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.test; + +import java.io.Serializable; +import java.util.Date; +import java.util.Iterator; + +import org.hibernate.EmptyInterceptor; +import org.hibernate.Transaction; +import org.hibernate.type.Type; + +public class AuditInterceptor extends EmptyInterceptor { + + private int updates; + private int creates; + private int loads; + + public void onDelete(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + // do nothing + } + + public boolean onFlushDirty(Object entity, + Serializable id, + Object[] currentState, + Object[] previousState, + String[] propertyNames, + Type[] types) { + + if ( entity instanceof Auditable ) { + updates++; + for ( int i=0; i < propertyNames.length; i++ ) { + if ( "lastUpdateTimestamp".equals( propertyNames[i] ) ) { + currentState[i] = new Date(); + return true; + } + } + } + return false; + } + + public boolean onLoad(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + if ( entity instanceof Auditable ) { + loads++; + } + return false; + } + + public boolean onSave(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + + if ( entity instanceof Auditable ) { + creates++; + for ( int i=0; i<propertyNames.length; i++ ) { + if ( "createTimestamp".equals( propertyNames[i] ) ) { + state[i] = new Date(); + return true; + } + } + } + return false; + } + + public void afterTransactionCompletion(Transaction tx) { + if ( tx.wasCommitted() ) { + System.out.println("Creations: " + creates + ", Updates: " + updates, "Loads: " + loads); + } + updates=0; + creates=0; + loads=0; + } + +}]]></programlisting> + + <para> + There are two kinds of inteceptors: <literal>Session</literal>-scoped and + <literal>SessionFactory</literal>-scoped. + </para> + + <para> + A <literal>Session</literal>-scoped interceptor is specified + when a session is opened using one of the overloaded SessionFactory.openSession() + methods accepting an <literal>Interceptor</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]></programlisting> + + <para> + A <literal>SessionFactory</literal>-scoped interceptor is registered with the <literal>Configuration</literal> + object prior to building the <literal>SessionFactory</literal>. Unless + a session is opened explicitly specifying the interceptor to use, the supplied interceptor + will be applied to all sessions opened from that <literal>SessionFactory</literal>. <literal>SessionFactory</literal>-scoped + interceptors must be thread safe. Ensure that you do not store session-specific states, since multiple + sessions will use this interceptor potentially concurrently. + </para> + + <programlisting role="JAVA"><![CDATA[new Configuration().setInterceptor( new AuditInterceptor() );]]></programlisting> + + </section> + + <section id="objectstate-events" revision="4"> + <title>Event system</title> + + <para> + If you have to react to particular events in your persistence layer, you can + also use the Hibernate3 <emphasis>event</emphasis> architecture. The event + system can be used in addition, or as a replacement, for interceptors. + </para> + + <para> + All the methods of the <literal>Session</literal> interface correlate + to an event. You have a <literal>LoadEvent</literal>, a <literal>FlushEvent</literal>, etc. + Consult the XML configuration-file DTD or the <literal>org.hibernate.event</literal> + package for the full list of defined event types. When a request is made of one of + these methods, the Hibernate <literal>Session</literal> generates an appropriate + event and passes it to the configured event listeners for that type. Out-of-the-box, + these listeners implement the same processing in which those methods always resulted. + However, you are free to implement a customization of one of the listener interfaces + (i.e., the <literal>LoadEvent</literal> is processed by the registered implementation + of the <literal>LoadEventListener</literal> interface), in which case their + implementation would be responsible for processing any <literal>load()</literal> requests + made of the <literal>Session</literal>. + </para> + + <para> + The listeners should be considered singletons. This means they are shared between + requests, and should not save any state as instance variables. + </para> + + <para> + A custom listener implements the appropriate interface for the event it wants to + process and/or extend one of the convenience base classes (or even the default event + listeners used by Hibernate out-of-the-box as these are declared non-final for this + purpose). Custom listeners can either be registered programmatically through the + <literal>Configuration</literal> object, or specified in the Hibernate configuration + XML. Declarative configuration through the properties file is not supported. Here is an + example of a custom load event listener: + </para> + + <programlisting role="JAVA"><![CDATA[public class MyLoadListener implements LoadEventListener { + // this is the single method defined by the LoadEventListener interface + public void onLoad(LoadEvent event, LoadEventListener.LoadType loadType) + throws HibernateException { + if ( !MySecurity.isAuthorized( event.getEntityClassName(), event.getEntityId() ) ) { + throw MySecurityException("Unauthorized access"); + } + } +}]]></programlisting> + + <para> + You also need a configuration entry telling Hibernate to use the listener in addition + to the default listener: + </para> + +<programlisting role="XML"><![CDATA[<hibernate-configuration> + <session-factory> + ... + <event type="load"> + <listener class="com.eg.MyLoadListener"/> + <listener class="org.hibernate.event.def.DefaultLoadEventListener"/> + </event> + </session-factory> +</hibernate-configuration>]]></programlisting> + + <para> + Instead, you can register it programmatically: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = new Configuration(); +LoadEventListener[] stack = { new MyLoadListener(), new DefaultLoadEventListener() }; +cfg.EventListeners().setLoadEventListeners(stack);]]></programlisting> + + <para> + Listeners registered declaratively cannot share instances. If the same class name is + used in multiple <literal>&lt;listener/&gt;</literal> elements, each reference will + result in a separate instance of that class. If you need to share + listener instances between listener types you must use the programmatic registration + approach. + </para> + + <para> + Why implement an interface and define the specific type during configuration? A + listener implementation could implement multiple event listener interfaces. Having the + type additionally defined during registration makes it easier to turn custom listeners on + or off during configuration. + </para> + + </section> + + <section id="objectstate-decl-security" revision="2"> + <title>Hibernate declarative security</title> + <para> + Usually, declarative security in Hibernate applications is managed in a session facade + layer. Hibernate3 allows certain actions to be permissioned via JACC, and authorized + via JAAS. This is an optional functionality that is built on top of the event architecture. + </para> + + <para> + First, you must configure the appropriate event listeners, to enable the use of JAAS + authorization. + </para> + + <programlisting role="XML"><![CDATA[<listener type="pre-delete" class="org.hibernate.secure.JACCPreDeleteEventListener"/> +<listener type="pre-update" class="org.hibernate.secure.JACCPreUpdateEventListener"/> +<listener type="pre-insert" class="org.hibernate.secure.JACCPreInsertEventListener"/> +<listener type="pre-load" class="org.hibernate.secure.JACCPreLoadEventListener"/>]]></programlisting> + + <para> + Note that <literal>&lt;listener type="..." class="..."/&gt;</literal> is shorthand + for <literal>&lt;event type="..."&gt;&lt;listener class="..."/&gt;&lt;/event&gt;</literal> + when there is exactly one listener for a particular event type. + </para> + + <para> + Next, while still in <literal>hibernate.cfg.xml</literal>, bind the permissions to roles: + </para> + + <programlisting role="XML"><![CDATA[<grant role="admin" entity-name="User" actions="insert,update,read"/> +<grant role="su" entity-name="User" actions="*"/>]]></programlisting> + + <para> + The role names are the roles understood by your JACC provider. + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_mappings.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_mappings.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_mappings.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,690 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="example-mappings"> + <title>Example: Various Mappings</title> + + + <para> + This chapters explores some more complex association mappings. + </para> + + <section id="example-mappings-emp"> + <title>Employer/Employee</title> + + <para> + The following model of the relationship between <literal>Employer</literal> and + <literal>Employee</literal> uses an entity class (<literal>Employment</literal>) + to represent the association. You can do this when there might be more than one + period of employment for the same two parties. Components are used to model monetary + values and employee names. + </para> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/EmployerEmployee.png" format="PNG" align="center" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/EmployerEmployee.png" format="PNG" align="center" width="17cm" /> + </imageobject> + </mediaobject> + + <para> + Here is a possible mapping document: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Employer" table="employers"> + <id name="id"> + <generator class="sequence"> + <param name="sequence">employer_id_seq</param> + </generator> + </id> + <property name="name"/> + </class> + + <class name="Employment" table="employment_periods"> + + <id name="id"> + <generator class="sequence"> + <param name="sequence">employment_id_seq</param> + </generator> + </id> + <property name="startDate" column="start_date"/> + <property name="endDate" column="end_date"/> + + <component name="hourlyRate" class="MonetaryAmount"> + <property name="amount"> + <column name="hourly_rate" sql-type="NUMERIC(12, 2)"/> + </property> + <property name="currency" length="12"/> + </component> + + <many-to-one name="employer" column="employer_id" not-null="true"/> + <many-to-one name="employee" column="employee_id" not-null="true"/> + + </class> + + <class name="Employee" table="employees"> + <id name="id"> + <generator class="sequence"> + <param name="sequence">employee_id_seq</param> + </generator> + </id> + <property name="taxfileNumber"/> + <component name="name" class="Name"> + <property name="firstName"/> + <property name="initial"/> + <property name="lastName"/> + </component> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Here is the table schema generated by <literal>SchemaExport</literal>. + </para> + + <programlisting><![CDATA[create table employers ( + id BIGINT not null, + name VARCHAR(255), + primary key (id) +) + +create table employment_periods ( + id BIGINT not null, + hourly_rate NUMERIC(12, 2), + currency VARCHAR(12), + employee_id BIGINT not null, + employer_id BIGINT not null, + end_date TIMESTAMP, + start_date TIMESTAMP, + primary key (id) +) + +create table employees ( + id BIGINT not null, + firstName VARCHAR(255), + initial CHAR(1), + lastName VARCHAR(255), + taxfileNumber VARCHAR(255), + primary key (id) +) + +alter table employment_periods + add constraint employment_periodsFK0 foreign key (employer_id) references employers +alter table employment_periods + add constraint employment_periodsFK1 foreign key (employee_id) references employees +create sequence employee_id_seq +create sequence employment_id_seq +create sequence employer_id_seq]]></programlisting> + + </section> + + <section id="example-mappings-authorwork"> + <title>Author/Work</title> + + <para> + Consider the following model of the relationships between <literal>Work</literal>, + <literal>Author</literal> and <literal>Person</literal>. In the example, the relationship + between <literal>Work</literal> and <literal>Author</literal> is represented as a many-to-many + association and the relationship between <literal>Author</literal> + and <literal>Person</literal> is represented as one-to-one association. Another possibility would be to + have <literal>Author</literal> extend <literal>Person</literal>. + </para> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/AuthorWork.png" format="PNG" align="center" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/AuthorWork.png" format="PNG" align="center" width="17cm" /> + </imageobject> + </mediaobject> + + <para> + The following mapping document correctly represents these relationships: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Work" table="works" discriminator-value="W"> + + <id name="id" column="id"> + <generator class="native"/> + </id> + <discriminator column="type" type="character"/> + + <property name="title"/> + <set name="authors" table="author_work"> + <key column name="work_id"/> + <many-to-many class="Author" column name="author_id"/> + </set> + + <subclass name="Book" discriminator-value="B"> + <property name="text"/> + </subclass> + + <subclass name="Song" discriminator-value="S"> + <property name="tempo"/> + <property name="genre"/> + </subclass> + + </class> + + <class name="Author" table="authors"> + + <id name="id" column="id"> + <!-- The Author must have the same identifier as the Person --> + <generator class="assigned"/> + </id> + + <property name="alias"/> + <one-to-one name="person" constrained="true"/> + + <set name="works" table="author_work" inverse="true"> + <key column="author_id"/> + <many-to-many class="Work" column="work_id"/> + </set> + + </class> + + <class name="Person" table="persons"> + <id name="id" column="id"> + <generator class="native"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + There are four tables in this mapping: <literal>works</literal>, + <literal>authors</literal> and <literal>persons</literal> hold work, author + and person data respectively. <literal>author_work</literal> is an association + table linking authors to works. Here is the table schema, as generated by + <literal>SchemaExport</literal>: + </para> + + <programlisting><![CDATA[create table works ( + id BIGINT not null generated by default as identity, + tempo FLOAT, + genre VARCHAR(255), + text INTEGER, + title VARCHAR(255), + type CHAR(1) not null, + primary key (id) +) + +create table author_work ( + author_id BIGINT not null, + work_id BIGINT not null, + primary key (work_id, author_id) +) + +create table authors ( + id BIGINT not null generated by default as identity, + alias VARCHAR(255), + primary key (id) +) + +create table persons ( + id BIGINT not null generated by default as identity, + name VARCHAR(255), + primary key (id) +) + +alter table authors + add constraint authorsFK0 foreign key (id) references persons +alter table author_work + add constraint author_workFK0 foreign key (author_id) references authors +alter table author_work + add constraint author_workFK1 foreign key (work_id) references works]]></programlisting> + + </section> + + <section id="example-mappings-customerorderproduct"> + <title>Customer/Order/Product</title> + + <para> + In this section we consider a model of the relationships between <literal>Customer</literal>, + <literal>Order</literal>, <literal>Line Item</literal> and <literal>Product</literal>. + There is a one-to-many association between <literal>Customer</literal> and + <literal>Order</literal>, but how can you represent <literal>Order</literal> / + <literal>LineItem</literal> / <literal>Product</literal>? In the example, + <literal>LineItem</literal> is mapped as an association class representing the many-to-many + association between <literal>Order</literal> and <literal>Product</literal>. In + Hibernate this is called a composite element. + </para> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/CustomerOrderProduct.png" format="PNG" align="center" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/CustomerOrderProduct.png" format="PNG" align="center" width="17cm" /> + </imageobject> + </mediaobject> + + <para> + The mapping document will look like this: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class name="Customer" table="customers"> + <id name="id"> + <generator class="native"/> + </id> + <property name="name"/> + <set name="orders" inverse="true"> + <key column="customer_id"/> + <one-to-many class="Order"/> + </set> + </class> + + <class name="Order" table="orders"> + <id name="id"> + <generator class="native"/> + </id> + <property name="date"/> + <many-to-one name="customer" column="customer_id"/> + <list name="lineItems" table="line_items"> + <key column="order_id"/> + <list-index column="line_number"/> + <composite-element class="LineItem"> + <property name="quantity"/> + <many-to-one name="product" column="product_id"/> + </composite-element> + </list> + </class> + + <class name="Product" table="products"> + <id name="id"> + <generator class="native"/> + </id> + <property name="serialNumber"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + <literal>customers</literal>, <literal>orders</literal>, <literal>line_items</literal> and + <literal>products</literal> hold customer, order, order line item and product data + respectively. <literal>line_items</literal> also acts as an association table linking + orders with products. + </para> + + <programlisting><![CDATA[create table customers ( + id BIGINT not null generated by default as identity, + name VARCHAR(255), + primary key (id) +) + +create table orders ( + id BIGINT not null generated by default as identity, + customer_id BIGINT, + date TIMESTAMP, + primary key (id) +) + +create table line_items ( + line_number INTEGER not null, + order_id BIGINT not null, + product_id BIGINT, + quantity INTEGER, + primary key (order_id, line_number) +) + +create table products ( + id BIGINT not null generated by default as identity, + serialNumber VARCHAR(255), + primary key (id) +) + +alter table orders + add constraint ordersFK0 foreign key (customer_id) references customers +alter table line_items + add constraint line_itemsFK0 foreign key (product_id) references products +alter table line_items + add constraint line_itemsFK1 foreign key (order_id) references orders]]></programlisting> + + </section> + + <section id="misc"> + <title>Miscellaneous example mappings</title> + + <para> + These examples are available from the Hibernate test suite. You + will find many other useful example mappings there by searching in the + <literal>test</literal> folder of the Hibernate distribution. + </para> + + <!-- <<para>TODO: put words around this stuff</para>--> + + <section id="example-mappings-typed-onetone"> + <title>"Typed" one-to-one association</title> +<programlisting role="XML"><![CDATA[<class name="Person"> + <id name="name"/> + <one-to-one name="address" + cascade="all"> + <formula>name</formula> + <formula>'HOME'</formula> + </one-to-one> + <one-to-one name="mailingAddress" + cascade="all"> + <formula>name</formula> + <formula>'MAILING'</formula> + </one-to-one> +</class> + +<class name="Address" batch-size="2" + check="addressType in ('MAILING', 'HOME', 'BUSINESS')"> + <composite-id> + <key-many-to-one name="person" + column="personName"/> + <key-property name="type" + column="addressType"/> + </composite-id> + <property name="street" type="text"/> + <property name="state"/> + <property name="zip"/> +</class>]]></programlisting> + </section> + + <section id="example-mappings-composite-key"> + <title>Composite key example</title> +<programlisting role="XML"><![CDATA[<class name="Customer"> + + <id name="customerId" + length="10"> + <generator class="assigned"/> + </id> + + <property name="name" not-null="true" length="100"/> + <property name="address" not-null="true" length="200"/> + + <list name="orders" + inverse="true" + cascade="save-update"> + <key column="customerId"/> + <index column="orderNumber"/> + <one-to-many class="Order"/> + </list> + +</class> + +<class name="Order" table="CustomerOrder" lazy="true"> + <synchronize table="LineItem"/> + <synchronize table="Product"/> + + <composite-id name="id" + class="Order$Id"> + <key-property name="customerId" length="10"/> + <key-property name="orderNumber"/> + </composite-id> + + <property name="orderDate" + type="calendar_date" + not-null="true"/> + + <property name="total"> + <formula> + ( select sum(li.quantity*p.price) + from LineItem li, Product p + where li.productId = p.productId + and li.customerId = customerId + and li.orderNumber = orderNumber ) + </formula> + </property> + + <many-to-one name="customer" + column="customerId" + insert="false" + update="false" + not-null="true"/> + + <bag name="lineItems" + fetch="join" + inverse="true" + cascade="save-update"> + <key> + <column name="customerId"/> + <column name="orderNumber"/> + </key> + <one-to-many class="LineItem"/> + </bag> + +</class> + +<class name="LineItem"> + + <composite-id name="id" + class="LineItem$Id"> + <key-property name="customerId" length="10"/> + <key-property name="orderNumber"/> + <key-property name="productId" length="10"/> + </composite-id> + + <property name="quantity"/> + + <many-to-one name="order" + insert="false" + update="false" + not-null="true"> + <column name="customerId"/> + <column name="orderNumber"/> + </many-to-one> + + <many-to-one name="product" + insert="false" + update="false" + not-null="true" + column="productId"/> + +</class> + +<class name="Product"> + <synchronize table="LineItem"/> + + <id name="productId" + length="10"> + <generator class="assigned"/> + </id> + + <property name="description" + not-null="true" + length="200"/> + <property name="price" length="3"/> + <property name="numberAvailable"/> + + <property name="numberOrdered"> + <formula> + ( select sum(li.quantity) + from LineItem li + where li.productId = productId ) + </formula> + </property> + +</class>]]></programlisting> + </section> + + <section id="example-mappings-composite-key-manytomany"> + <title>Many-to-many with shared composite key attribute</title> +<programlisting role="XML"><![CDATA[<class name="User" table="`User`"> + <composite-id> + <key-property name="name"/> + <key-property name="org"/> + </composite-id> + <set name="groups" table="UserGroup"> + <key> + <column name="userName"/> + <column name="org"/> + </key> + <many-to-many class="Group"> + <column name="groupName"/> + <formula>org</formula> + </many-to-many> + </set> +</class> + +<class name="Group" table="`Group`"> + <composite-id> + <key-property name="name"/> + <key-property name="org"/> + </composite-id> + <property name="description"/> + <set name="users" table="UserGroup" inverse="true"> + <key> + <column name="groupName"/> + <column name="org"/> + </key> + <many-to-many class="User"> + <column name="userName"/> + <formula>org</formula> + </many-to-many> + </set> +</class> +]]></programlisting> + </section> + + <section id="example-mappings-content-discrimination"> + <title>Content based discrimination</title> +<programlisting role="XML"><![CDATA[<class name="Person" + discriminator-value="P"> + + <id name="id" + column="person_id" + unsaved-value="0"> + <generator class="native"/> + </id> + + + <discriminator + type="character"> + <formula> + case + when title is not null then 'E' + when salesperson is not null then 'C' + else 'P' + end + </formula> + </discriminator> + + <property name="name" + not-null="true" + length="80"/> + + <property name="sex" + not-null="true" + update="false"/> + + <component name="address"> + <property name="address"/> + <property name="zip"/> + <property name="country"/> + </component> + + <subclass name="Employee" + discriminator-value="E"> + <property name="title" + length="20"/> + <property name="salary"/> + <many-to-one name="manager"/> + </subclass> + + <subclass name="Customer" + discriminator-value="C"> + <property name="comments"/> + <many-to-one name="salesperson"/> + </subclass> + +</class>]]></programlisting> + </section> + + <section id="example-mappings-association-alternatekeys" revision="2"> + <title>Associations on alternate keys</title> +<programlisting role="XML"><![CDATA[<class name="Person"> + + <id name="id"> + <generator class="hilo"/> + </id> + + <property name="name" length="100"/> + + <one-to-one name="address" + property-ref="person" + cascade="all" + fetch="join"/> + + <set name="accounts" + inverse="true"> + <key column="userId" + property-ref="userId"/> + <one-to-many class="Account"/> + </set> + + <property name="userId" length="8"/> + +</class> + +<class name="Address"> + + <id name="id"> + <generator class="hilo"/> + </id> + + <property name="address" length="300"/> + <property name="zip" length="5"/> + <property name="country" length="25"/> + <many-to-one name="person" unique="true" not-null="true"/> + +</class> + +<class name="Account"> + <id name="accountId" length="32"> + <generator class="uuid"/> + </id> + + <many-to-one name="user" + column="userId" + property-ref="userId"/> + + <property name="type" not-null="true"/> + +</class>]]></programlisting> + </section> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_parentchild.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_parentchild.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_parentchild.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,332 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="example-parentchild"> + <title>Example: Parent/Child</title> + + <para> + One of the first things that new users want to do with Hibernate is to model a parent/child type + relationship. There are two different approaches to this. The most convenient + approach, especially for new users, is to model both <literal>Parent</literal> and <literal>Child</literal> + as entity classes with a <literal>&lt;one-to-many&gt;</literal> association from <literal>Parent</literal> + to <literal>Child</literal>. The alternative approach is to declare the <literal>Child</literal> as a + <literal>&lt;composite-element&gt;</literal>. The default semantics of a one-to-many + association in Hibernate are much less close to the usual semantics of a parent/child relationship than + those of a composite element mapping. We will explain how to use a <emphasis>bidirectional one-to-many + association with cascades</emphasis> to model a parent/child relationship efficiently and elegantly. + + </para> + + <section id="example-parentchild-collections"> + <title>A note about collections</title> + + <para> + Hibernate collections are considered to be a logical part of their owning entity and not of the + contained entities. Be aware that this is a critical distinction that has the following consequences: + </para> + + <itemizedlist> + <listitem> + <para> + When you remove/add an object from/to a collection, the version number of the collection owner + is incremented. + </para> + </listitem> + <listitem> + <para> + If an object that was removed from a collection is an instance of a value type (e.g. a composite + element), that object will cease to be persistent and its state will be completely removed from + the database. Likewise, adding a value type instance to the collection will cause its state to be + immediately persistent. + </para> + </listitem> + <listitem> + <para> + Conversely, if an entity is removed from a collection (a one-to-many or many-to-many + association), it will not be deleted by default. This behavior is completely consistent; a + change to the internal state of another entity should not cause the associated entity to vanish. + Likewise, adding an entity to a collection does not cause that entity to become persistent, by + default. + </para> + </listitem> + </itemizedlist> + + <para> + Adding an entity to a collection, by default, merely creates a link between + the two entities. Removing the entity will remove the link. This is appropriate for all sorts of cases. + However, it is not appropriate in the case of a parent/child relationship. In this case, the life of the + child is bound to the life cycle of the parent. + </para> + + </section> + + <section id="example-parentchild-bidir"> + <title>Bidirectional one-to-many</title> + + <para> + Suppose we start with a simple <literal>&lt;one-to-many&gt;</literal> association from + <literal>Parent</literal> to <literal>Child</literal>. + </para> + + <programlisting role="XML"><![CDATA[<set name="children"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + If we were to execute the following code: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = .....; +Child c = new Child(); +p.getChildren().add(c); +session.save(c); +session.flush();]]></programlisting> + + <para> + Hibernate would issue two SQL statements: + </para> + + <itemizedlist> + <listitem> + <para>an <literal>INSERT</literal> to create the record for <literal>c</literal></para> + </listitem> + <listitem> + <para> + an <literal>UPDATE</literal> to create the link from <literal>p</literal> to + <literal>c</literal> + </para> + </listitem> + </itemizedlist> + + <para> + This is not only inefficient, but also violates any <literal>NOT NULL</literal> constraint on the + <literal>parent_id</literal> column. You can fix the nullability constraint violation by specifying + <literal>not-null="true"</literal> in the collection mapping: + </para> + + <programlisting role="XML"><![CDATA[<set name="children"> + <key column="parent_id" not-null="true"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + However, this is not the recommended solution. + </para> + <para> + The underlying cause of this behavior is that the link (the foreign key <literal>parent_id</literal>) + from <literal>p</literal> to <literal>c</literal> is not considered part of the state of the + <literal>Child</literal> object and is therefore not created in the <literal>INSERT</literal>. The + solution is to make the link part of the <literal>Child</literal> mapping. + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="parent" column="parent_id" not-null="true"/>]]></programlisting> + + <para> + You also need to add the <literal>parent</literal> property to the <literal>Child</literal> class. + </para> + + <para> + Now that the <literal>Child</literal> entity is managing the state of the link, we tell the collection + not to update the link. We use the <literal>inverse</literal> attribute to do this: + </para> + + <programlisting role="XML"><![CDATA[<set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + The following code would be used to add a new <literal>Child</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +c.setParent(p); +p.getChildren().add(c); +session.save(c); +session.flush();]]></programlisting> + + <para> + Only one SQL <literal>INSERT</literal> would now be issued. + </para> + + <para> + You could also create an <literal>addChild()</literal> method of + <literal>Parent</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[public void addChild(Child c) { + c.setParent(this); + children.add(c); +}]]></programlisting> + + <para> + The code to add a <literal>Child</literal> looks like this: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +p.addChild(c); +session.save(c); +session.flush();]]></programlisting> + + </section> + + <section id="example-parentchild-cascades"> + <title>Cascading life cycle</title> + + <para> + You can address the frustrations of the explicit call to <literal>save()</literal> by + using cascades. + </para> + + <programlisting role="XML"><![CDATA[<set name="children" inverse="true" cascade="all"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + This simplifies the code above to: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +p.addChild(c); +session.flush();]]></programlisting> + + <para> + Similarly, we do not need to iterate over the children when saving or deleting a <literal>Parent</literal>. + The following removes <literal>p</literal> and all its children from the database. + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +session.delete(p); +session.flush();]]></programlisting> + + <para> + However, the following code: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = (Child) p.getChildren().iterator().next(); +p.getChildren().remove(c); +c.setParent(null); +session.flush();]]></programlisting> + + <para> + will not remove <literal>c</literal> from the database. In this case, it will only remove the link to <literal>p</literal> + and cause a <literal>NOT NULL</literal> constraint violation. You need to explicitly + <literal>delete()</literal> the <literal>Child</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = (Child) p.getChildren().iterator().next(); +p.getChildren().remove(c); +session.delete(c); +session.flush();]]></programlisting> + + <para> + In our case, a <literal>Child</literal> cannot exist without its parent. So if we remove + a <literal>Child</literal> from the collection, we do want it to be deleted. To do this, we must + use <literal>cascade="all-delete-orphan"</literal>. + </para> + + <programlisting role="XML"><![CDATA[<set name="children" inverse="true" cascade="all-delete-orphan"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + Even though the collection mapping specifies <literal>inverse="true"</literal>, cascades are + still processed by iterating the collection elements. If you need an object be saved, + deleted or updated by cascade, you must add it to the collection. It is not enough to simply call + <literal>setParent()</literal>. + </para> + + </section> + + <section id="example-parentchild-update"> + <title>Cascades and <literal>unsaved-value</literal></title> + + <para> + Suppose we loaded up a <literal>Parent</literal> in one <literal>Session</literal>, made some changes + in a UI action and wanted to persist these changes in a new session by calling <literal>update()</literal>. + The <literal>Parent</literal> will contain a collection of children and, since the cascading update is enabled, + Hibernate needs to know which children are newly instantiated and which represent existing rows in the + database. We will also assume that both <literal>Parent</literal> and <literal>Child</literal> have generated + identifier properties of type <literal>Long</literal>. Hibernate will use the identifier and + version/timestamp property value to determine which of the children are new. (See + <xref linkend="objectstate-saveorupdate"/>.) <emphasis>In Hibernate3, it is no longer necessary to specify + an <literal>unsaved-value</literal> explicitly.</emphasis> + </para> + + <para> + The following code will update <literal>parent</literal> and <literal>child</literal> and insert + <literal>newChild</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[//parent and child were both loaded in a previous session +parent.addChild(child); +Child newChild = new Child(); +parent.addChild(newChild); +session.update(parent); +session.flush();]]></programlisting> + + <para> + This may be suitable for the case of a generated identifier, but what about assigned identifiers + and composite identifiers? This is more difficult, since Hibernate cannot use the identifier property to + distinguish between a newly instantiated object, with an identifier assigned by the user, and an + object loaded in a previous session. In this case, Hibernate will either use the timestamp or version + property, or will actually query the second-level cache or, worst case, the database, to see if the + row exists. + </para> + + </section> + + <section id="example-parentchild-conclusion"> + <title>Conclusion</title> + + <para> + The sections we have just covered can be a bit confusing. However, in practice, + it all works out nicely. Most Hibernate applications use the parent/child pattern in many places. + </para> + + <para> + We mentioned an alternative in the first paragraph. None of the above issues exist in the case of + <literal>&lt;composite-element&gt;</literal> mappings, which have exactly the semantics of a parent/child + relationship. Unfortunately, there are two big limitations with composite element classes: composite elements + cannot own collections and they should not be the child of any entity other than the unique parent. + </para> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_weblog.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_weblog.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/example_weblog.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,461 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="example-weblog"> + <title>Example: Weblog Application</title> + + <section id="example-weblog-classes"> + <title>Persistent Classes</title> + + <para> + The persistent classes here represent a weblog and an item posted + in a weblog. They are to be modelled as a standard parent/child + relationship, but we will use an ordered bag, instead of a set: + </para> + + <programlisting role="JAVA"><![CDATA[package eg; + +import java.util.List; + +public class Blog { + private Long _id; + private String _name; + private List _items; + + public Long getId() { + return _id; + } + public List getItems() { + return _items; + } + public String getName() { + return _name; + } + public void setId(Long long1) { + _id = long1; + } + public void setItems(List list) { + _items = list; + } + public void setName(String string) { + _name = string; + } +}]]></programlisting> + + <programlisting role="JAVA"><![CDATA[package eg; + +import java.text.DateFormat; +import java.util.Calendar; + +public class BlogItem { + private Long _id; + private Calendar _datetime; + private String _text; + private String _title; + private Blog _blog; + + public Blog getBlog() { + return _blog; + } + public Calendar getDatetime() { + return _datetime; + } + public Long getId() { + return _id; + } + public String getText() { + return _text; + } + public String getTitle() { + return _title; + } + public void setBlog(Blog blog) { + _blog = blog; + } + public void setDatetime(Calendar calendar) { + _datetime = calendar; + } + public void setId(Long long1) { + _id = long1; + } + public void setText(String string) { + _text = string; + } + public void setTitle(String string) { + _title = string; + } +}]]></programlisting> + + </section> + + <section id="example-weblog-mappings"> + <title>Hibernate Mappings</title> + + <para> + The XML mappings are now straightforward. For example: + </para> + + <programlisting role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class + name="Blog" + table="BLOGS"> + + <id + name="id" + column="BLOG_ID"> + + <generator class="native"/> + + </id> + + <property + name="name" + column="NAME" + not-null="true" + unique="true"/> + + <bag + name="items" + inverse="true" + order-by="DATE_TIME" + cascade="all"> + + <key column="BLOG_ID"/> + <one-to-many class="BlogItem"/> + + </bag> + + </class> + +</hibernate-mapping>]]></programlisting> + + <programlisting role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class + name="BlogItem" + table="BLOG_ITEMS" + dynamic-update="true"> + + <id + name="id" + column="BLOG_ITEM_ID"> + + <generator class="native"/> + + </id> + + <property + name="title" + column="TITLE" + not-null="true"/> + + <property + name="text" + column="TEXT" + not-null="true"/> + + <property + name="datetime" + column="DATE_TIME" + not-null="true"/> + + <many-to-one + name="blog" + column="BLOG_ID" + not-null="true"/> + + </class> + +</hibernate-mapping>]]></programlisting> + + </section> + + <section id="example-weblog-code"> + <title>Hibernate Code</title> + + <para> + The following class demonstrates some of the kinds of things + we can do with these classes using Hibernate: + </para> + + <programlisting role="JAVA"><![CDATA[package eg; + +import java.util.ArrayList; +import java.util.Calendar; +import java.util.Iterator; +import java.util.List; + +import org.hibernate.HibernateException; +import org.hibernate.Query; +import org.hibernate.Session; +import org.hibernate.SessionFactory; +import org.hibernate.Transaction; +import org.hibernate.cfg.Configuration; +import org.hibernate.tool.hbm2ddl.SchemaExport; + +public class BlogMain { + + private SessionFactory _sessions; + + public void configure() throws HibernateException { + _sessions = new Configuration() + .addClass(Blog.class) + .addClass(BlogItem.class) + .buildSessionFactory(); + } + + public void exportTables() throws HibernateException { + Configuration cfg = new Configuration() + .addClass(Blog.class) + .addClass(BlogItem.class); + new SchemaExport(cfg).create(true, true); + } + + public Blog createBlog(String name) throws HibernateException { + + Blog blog = new Blog(); + blog.setName(name); + blog.setItems( new ArrayList() ); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.persist(blog); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return blog; + } + + public BlogItem createBlogItem(Blog blog, String title, String text) + throws HibernateException { + + BlogItem item = new BlogItem(); + item.setTitle(title); + item.setText(text); + item.setBlog(blog); + item.setDatetime( Calendar.getInstance() ); + blog.getItems().add(item); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.update(blog); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return item; + } + + public BlogItem createBlogItem(Long blogid, String title, String text) + throws HibernateException { + + BlogItem item = new BlogItem(); + item.setTitle(title); + item.setText(text); + item.setDatetime( Calendar.getInstance() ); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + Blog blog = (Blog) session.load(Blog.class, blogid); + item.setBlog(blog); + blog.getItems().add(item); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return item; + } + + public void updateBlogItem(BlogItem item, String text) + throws HibernateException { + + item.setText(text); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.update(item); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + } + + public void updateBlogItem(Long itemid, String text) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + BlogItem item = (BlogItem) session.load(BlogItem.class, itemid); + item.setText(text); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + } + + public List listAllBlogNamesAndItemCounts(int max) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + List result = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "select blog.id, blog.name, count(blogItem) " + + "from Blog as blog " + + "left outer join blog.items as blogItem " + + "group by blog.name, blog.id " + + "order by max(blogItem.datetime)" + ); + q.setMaxResults(max); + result = q.list(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return result; + } + + public Blog getBlogAndAllItems(Long blogid) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + Blog blog = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "from Blog as blog " + + "left outer join fetch blog.items " + + "where blog.id = :blogid" + ); + q.setParameter("blogid", blogid); + blog = (Blog) q.uniqueResult(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return blog; + } + + public List listBlogsAndRecentItems() throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + List result = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "from Blog as blog " + + "inner join blog.items as blogItem " + + "where blogItem.datetime > :minDate" + ); + + Calendar cal = Calendar.getInstance(); + cal.roll(Calendar.MONTH, false); + q.setCalendar("minDate", cal); + + result = q.list(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return result; + } +}]]></programlisting> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/filters.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/filters.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/filters.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,177 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="filters"> + <title>Filtering data</title> + + <para> + Hibernate3 provides an innovative new approach to handling data with "visibility" rules. + A <emphasis>Hibernate filter</emphasis> is a global, named, parameterized filter that can be + enabled or disabled for a particular Hibernate session. + </para> + + <section id="objectstate-filters" revision="1"> + <title>Hibernate filters</title> + + <para> + Hibernate3 has the ability to pre-define filter criteria and attach those filters at both + a class level and a collection level. A filter criteria allows you to define a restriction clause + similar to the existing "where" attribute available on the class and various collection + elements. These filter conditions, however, can be parameterized. The application can then + decide at runtime whether certain filters should be enabled and what their parameter + values should be. Filters can be used like database views, but they are parameterized inside the + application. + </para> + + <para> + In order to use filters, they must first be defined and then attached to the appropriate + mapping elements. To define a filter, use the <literal>&lt;filter-def/&gt;</literal> element + within a <literal>&lt;hibernate-mapping/&gt;</literal> element: + </para> + + <programlisting role="XML"><![CDATA[<filter-def name="myFilter"> + <filter-param name="myFilterParam" type="string"/> +</filter-def>]]></programlisting> + + <para> + This filter can then be attached to a class: + </para> + + <programlisting role="XML"><![CDATA[<class name="myClass" ...> + ... + <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/> +</class>]]></programlisting> + + <para> + Or, to a collection: + </para> + + <programlisting role="XML"><![CDATA[<set ...> + <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/> +</set>]]></programlisting> + + <para> + Or, to both or multiples of each at the same time. + </para> + + <para> + The methods on <literal>Session</literal> are: <literal>enableFilter(String filterName)</literal>, + <literal>getEnabledFilter(String filterName)</literal>, and <literal>disableFilter(String filterName)</literal>. + By default, filters are <emphasis>not</emphasis> enabled for a given session. Filters must be + enabled through use of the <literal>Session.enableFilter()</literal> method, which returns an + instance of the <literal>Filter</literal> interface. If you used the simple filter defined above, it would + look like this: + </para> + + <programlisting role="JAVA"><![CDATA[session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");]]></programlisting> + + <para> + Methods on the org.hibernate.Filter interface do allow the method-chaining common to much of Hibernate. + </para> + + <para> + The following is a full example, using temporal data with an effective record date pattern: + </para> + + <programlisting role="XML"><![CDATA[<filter-def name="effectiveDate"> + <filter-param name="asOfDate" type="date"/> +</filter-def> + +<class name="Employee" ...> +... + <many-to-one name="department" column="dept_id" class="Department"/> + <property name="effectiveStartDate" type="date" column="eff_start_dt"/> + <property name="effectiveEndDate" type="date" column="eff_end_dt"/> +... + <!-- + Note that this assumes non-terminal records have an eff_end_dt set to + a max db date for simplicity-sake + --> + <filter name="effectiveDate" + condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/> +</class> + +<class name="Department" ...> +... + <set name="employees" lazy="true"> + <key column="dept_id"/> + <one-to-many class="Employee"/> + <filter name="effectiveDate" + condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/> + </set> +</class>]]></programlisting> + + <para> + In order to ensure that you are provided with currently effective records, + enable the filter on the session prior to retrieving employee data: + </para> + +<programlisting role="JAVA"><![CDATA[Session session = ...; +session.enableFilter("effectiveDate").setParameter("asOfDate", new Date()); +List results = session.createQuery("from Employee as e where e.salary > :targetSalary") + .setLong("targetSalary", new Long(1000000)) + .list(); +]]></programlisting> + + <para> + Even though a salary constraint was mentioned explicitly on the results in the above HQL, + because of the enabled filter, the query will return only currently active employees who have + a salary greater than one million dollars. + </para> + + <para> + If you want to use filters with outer joining, either through HQL or load fetching, be + careful of the direction of the condition expression. It is safest to set this up for left + outer joining. Place the parameter first followed by the column name(s) after + the operator. + </para> + + <para> + After being defined, a filter might be attached to multiple entities and/or + collections each with its own condition. This can be problematic when the + conditions are the same each time. Using <literal>&lt;filter-def/&gt;</literal> + allows you to definine a default condition, either as an attribute or CDATA: + </para> + + <programlisting role="XML"><![CDATA[<filter-def name="myFilter" condition="abc > xyz">...</filter-def> +<filter-def name="myOtherFilter">abc=xyz</filter-def>]]></programlisting> + + <para> + This default condition will be used whenever the filter is attached to something + without specifying a condition. This means you can give a specific condition + as part of the attachment of the filter that overrides the default condition in that + particular case. + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/inheritance_mapping.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/inheritance_mapping.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/inheritance_mapping.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,523 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="inheritance"> + <title>Inheritance mapping</title> + + <section id="inheritance-strategies" revision="3"> + <title>The three strategies</title> + + <para> + Hibernate supports the three basic inheritance mapping strategies: + </para> + + <itemizedlist> + <listitem> + <para> + table per class hierarchy + </para> + </listitem> + <listitem> + <para> + table per subclass + </para> + </listitem> + <listitem> + <para> + table per concrete class + </para> + </listitem> + </itemizedlist> + + <para> + In addition, Hibernate supports a fourth, slightly different kind of + polymorphism: + </para> + + <itemizedlist> + <listitem> + <para> + implicit polymorphism + </para> + </listitem> + </itemizedlist> + + <para> + It is possible to use different mapping strategies for different + branches of the same inheritance hierarchy. You can then make use of implicit + polymorphism to achieve polymorphism across the whole hierarchy. However, + Hibernate does not support mixing <literal>&lt;subclass&gt;</literal>, + <literal>&lt;joined-subclass&gt;</literal> and + <literal>&lt;union-subclass&gt;</literal> mappings under the same root + <literal>&lt;class&gt;</literal> element. It is possible to mix together + the table per hierarchy and table per subclass strategies under the + the same <literal>&lt;class&gt;</literal> element, by combining the + <literal>&lt;subclass&gt;</literal> and <literal>&lt;join&gt;</literal> + elements (see below for an example). + </para> + + <para> + It is possible to define <literal>subclass</literal>, <literal>union-subclass</literal>, + and <literal>joined-subclass</literal> mappings in separate mapping documents directly beneath + <literal>hibernate-mapping</literal>. This allows you to extend a class hierarchy by adding + a new mapping file. You must specify an <literal>extends</literal> attribute in the subclass mapping, + naming a previously mapped superclass. Previously this feature made the ordering of the mapping + documents important. Since Hibernate3, the ordering of mapping files is irrelevant when using the + extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses + before subclasses. + </para> + + <programlisting role="XML"><![CDATA[ + <hibernate-mapping> + <subclass name="DomesticCat" extends="Cat" discriminator-value="D"> + <property name="name" type="string"/> + </subclass> + </hibernate-mapping>]]></programlisting> + + + <section id="inheritance-tableperclass" > + <title>Table per class hierarchy</title> + + <para> + Suppose we have an interface <literal>Payment</literal> with the implementors + <literal>CreditCardPayment</literal>, <literal>CashPayment</literal>, + and <literal>ChequePayment</literal>. The table per hierarchy mapping would + display in the following way: + </para> + + <programlisting role="XML"><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + ... + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + ... + </subclass> +</class>]]></programlisting> + + <para> + Exactly one table is required. There is a limitation of this mapping + strategy: columns declared by the subclasses, such as <literal>CCTYPE</literal>, + cannot have <literal>NOT NULL</literal> constraints. + </para> + + </section> + + <section id="inheritance-tablepersubclass"> + <title>Table per subclass</title> + + <para> + A table per subclass mapping looks like this: + </para> + + <programlisting role="XML"><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="AMOUNT"/> + ... + <joined-subclass name="CreditCardPayment" table="CREDIT_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="creditCardType" column="CCTYPE"/> + ... + </joined-subclass> + <joined-subclass name="CashPayment" table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </joined-subclass> + <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </joined-subclass> +</class>]]></programlisting> + + <para> + Four tables are required. The three subclass tables have primary + key associations to the superclass table so the relational model + is actually a one-to-one association. + </para> + + </section> + + <section id="inheritance-tablepersubclass-discriminator" revision="2"> + <title>Table per subclass: using a discriminator</title> + + <para> + Hibernate's implementation of table per subclass + does not require a discriminator column. Other object/relational mappers use a + different implementation of table per subclass that requires a type + discriminator column in the superclass table. The approach taken by + Hibernate is much more difficult to implement, but arguably more + correct from a relational point of view. If you want to use + a discriminator column with the table per subclass strategy, you + can combine the use of <literal>&lt;subclass&gt;</literal> and + <literal>&lt;join&gt;</literal>, as follows: + </para> + + <programlisting role="XML"><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <join table="CREDIT_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="creditCardType" column="CCTYPE"/> + ... + </join> + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + <join table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </join> + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + <join table="CHEQUE_PAYMENT" fetch="select"> + <key column="PAYMENT_ID"/> + ... + </join> + </subclass> +</class>]]></programlisting> + + <para> + The optional <literal>fetch="select"</literal> declaration tells Hibernate + not to fetch the <literal>ChequePayment</literal> subclass data using an + outer join when querying the superclass. + </para> + + </section> + + <section id="inheritance-mixing-tableperclass-tablepersubclass"> + <title>Mixing table per class hierarchy with table per subclass</title> + + <para> + You can even mix the table per hierarchy and table per subclass strategies + using the following approach: + </para> + + <programlisting role="XML"><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <join table="CREDIT_PAYMENT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </join> + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + ... + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + ... + </subclass> +</class>]]></programlisting> + + <para> + For any of these mapping strategies, a polymorphic association to the root + <literal>Payment</literal> class is mapped using + <literal>&lt;many-to-one&gt;</literal>. + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/>]]></programlisting> + + </section> + + <section id="inheritance-tableperconcrete" revision="2"> + <title>Table per concrete class</title> + + <para> + There are two ways we can map the table per concrete class + strategy. First, you can use <literal>&lt;union-subclass&gt;</literal>. + </para> + + <programlisting role="XML"><![CDATA[<class name="Payment"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="sequence"/> + </id> + <property name="amount" column="AMOUNT"/> + ... + <union-subclass name="CreditCardPayment" table="CREDIT_PAYMENT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </union-subclass> + <union-subclass name="CashPayment" table="CASH_PAYMENT"> + ... + </union-subclass> + <union-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + ... + </union-subclass> +</class>]]></programlisting> + + <para> + Three tables are involved for the subclasses. Each table defines columns for + all properties of the class, including inherited properties. + </para> + + <para> + The limitation of this approach is that if a property is mapped on the + superclass, the column name must be the same on all subclass tables. + The identity generator strategy is not allowed in union subclass inheritance. + The primary key seed has to be shared across all unioned subclasses + of a hierarchy. + + </para> + + <para> + If your superclass is abstract, map it with <literal>abstract="true"</literal>. + If it is not abstract, an additional table (it defaults to + <literal>PAYMENT</literal> in the example above), is needed to hold instances + of the superclass. + </para> + + </section> + + <section id="inheritance-tableperconcreate-polymorphism"> + <title>Table per concrete class using implicit polymorphism</title> + + <para> + An alternative approach is to make use of implicit polymorphism: + </para> + + <programlisting role="XML"><![CDATA[<class name="CreditCardPayment" table="CREDIT_PAYMENT"> + <id name="id" type="long" column="CREDIT_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CREDIT_AMOUNT"/> + ... +</class> + +<class name="CashPayment" table="CASH_PAYMENT"> + <id name="id" type="long" column="CASH_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CASH_AMOUNT"/> + ... +</class> + +<class name="ChequePayment" table="CHEQUE_PAYMENT"> + <id name="id" type="long" column="CHEQUE_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CHEQUE_AMOUNT"/> + ... +</class>]]></programlisting> + + <para> + Notice that the <literal>Payment</literal> interface + is not mentioned explicitly. Also notice that properties of <literal>Payment</literal> are + mapped in each of the subclasses. If you want to avoid duplication, consider + using XML entities + (for example, <literal>[ &lt;!ENTITY allproperties SYSTEM "allproperties.xml"&gt; ]</literal> + in the <literal>DOCTYPE</literal> declaration and + <literal>&amp;allproperties&semi;</literal> in the mapping). + </para> + + <para> + The disadvantage of this approach is that Hibernate does not generate SQL + <literal>UNION</literal>s when performing polymorphic queries. + </para> + + <para> + For this mapping strategy, a polymorphic association to <literal>Payment</literal> + is usually mapped using <literal>&lt;any&gt;</literal>. + </para> + + <programlisting role="XML"><![CDATA[<any name="payment" meta-type="string" id-type="long"> + <meta-value value="CREDIT" class="CreditCardPayment"/> + <meta-value value="CASH" class="CashPayment"/> + <meta-value value="CHEQUE" class="ChequePayment"/> + <column name="PAYMENT_CLASS"/> + <column name="PAYMENT_ID"/> +</any>]]></programlisting> + + </section> + + <section id="inheritance-mixingpolymorphism"> + <title>Mixing implicit polymorphism with other inheritance mappings</title> + + <para> + Since the subclasses + are each mapped in their own <literal>&lt;class&gt;</literal> element, and since + <literal>Payment</literal> is just an interface), each of the subclasses could + easily be part of another inheritance hierarchy. You can still use polymorphic + queries against the <literal>Payment</literal> interface. + </para> + + <programlisting role="XML"><![CDATA[<class name="CreditCardPayment" table="CREDIT_PAYMENT"> + <id name="id" type="long" column="CREDIT_PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="CREDIT_CARD" type="string"/> + <property name="amount" column="CREDIT_AMOUNT"/> + ... + <subclass name="MasterCardPayment" discriminator-value="MDC"/> + <subclass name="VisaPayment" discriminator-value="VISA"/> +</class> + +<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN"> + <id name="id" type="long" column="TXN_ID"> + <generator class="native"/> + </id> + ... + <joined-subclass name="CashPayment" table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="amount" column="CASH_AMOUNT"/> + ... + </joined-subclass> + <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="amount" column="CHEQUE_AMOUNT"/> + ... + </joined-subclass> +</class>]]></programlisting> + + <para> + Once again, <literal>Payment</literal> is not mentioned explicitly. If we + execute a query against the <literal>Payment</literal> interface, for + example <literal>from Payment</literal>, Hibernate + automatically returns instances of <literal>CreditCardPayment</literal> + (and its subclasses, since they also implement <literal>Payment</literal>), + <literal>CashPayment</literal> and <literal>ChequePayment</literal>, but + not instances of <literal>NonelectronicTransaction</literal>. + </para> + + </section> + + </section> + + <section id="inheritance-limitations"> + <title>Limitations</title> + + <para> + There are limitations to the "implicit polymorphism" approach to + the table per concrete-class mapping strategy. There are somewhat less + restrictive limitations to <literal>&lt;union-subclass&gt;</literal> + mappings. + </para> + + <para> + The following table shows the limitations of table per concrete-class + mappings, and of implicit polymorphism, in Hibernate. + </para> + + <table frame="topbot"> + <title>Features of inheritance mappings</title> + <tgroup cols='9' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <colspec colname='c6' colwidth="1*"/> + <colspec colname='c7' colwidth="1*"/> + <colspec colname='c8' colwidth="1*"/> + <colspec colname='c9' colwidth="1*"/> + <thead> + <row> + <entry>Inheritance strategy</entry> + <entry>Polymorphic many-to-one</entry> + <entry>Polymorphic one-to-one</entry> + <entry>Polymorphic one-to-many</entry> + <entry>Polymorphic many-to-many</entry> + <entry>Polymorphic <literal>load()/get()</literal></entry> + <entry>Polymorphic queries</entry> + <entry>Polymorphic joins</entry> + <entry>Outer join fetching</entry> + </row> + </thead> + <tbody> + <row> + <entry>table per class-hierarchy</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal></entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per subclass</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal></entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per concrete-class (union-subclass)</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal> (for <literal>inverse="true"</literal> only)</entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per concrete class (implicit polymorphism)</entry> + <entry><literal>&lt;any&gt;</literal></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><literal>&lt;many-to-any&gt;</literal></entry> + <entry><literal>s.createCriteria(Payment.class).add( Restrictions.idEq(id) ).uniqueResult()</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><emphasis>not supported</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/performance.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/performance.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/performance.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1553 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="performance"> + <title>Improving performance</title> + + <section id="performance-fetching" revision="2"> + <title>Fetching strategies</title> + + <para> + Hibernate uses a <emphasis>fetching strategy</emphasis> to + retrieve associated objects if the application needs to navigate the association. + Fetch strategies can be declared in the O/R mapping metadata, or over-ridden by a + particular HQL or <literal>Criteria</literal> query. + </para> + + <para> + Hibernate3 defines the following fetching strategies: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Join fetching</emphasis>: Hibernate retrieves the + associated instance or collection in the same <literal>SELECT</literal>, + using an <literal>OUTER JOIN</literal>. + </para> + </listitem> + <listitem> + <para> + <emphasis>Select fetching</emphasis>: a second <literal>SELECT</literal> + is used to retrieve the associated entity or collection. Unless + you explicitly disable lazy fetching by specifying <literal>lazy="false"</literal>, + this second select will only be executed when you access the + association. + </para> + </listitem> + <listitem> + <para> + <emphasis>Subselect fetching</emphasis>: a second <literal>SELECT</literal> + is used to retrieve the associated collections for all entities retrieved in a + previous query or fetch. Unless you explicitly disable lazy fetching by specifying + <literal>lazy="false"</literal>, this second select will only be executed when you + access the association. + </para> + </listitem> + <listitem> + <para> + <emphasis>Batch fetching</emphasis>: an optimization strategy + for select fetching. Hibernate retrieves a batch of entity instances + or collections in a single <literal>SELECT</literal> by specifying + a list of primary or foreign keys. + </para> + </listitem> + </itemizedlist> + + <para> + Hibernate also distinguishes between: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Immediate fetching</emphasis>: an association, collection or + attribute is fetched immediately when the owner is loaded. + </para> + </listitem> + <listitem> + <para> + <emphasis>Lazy collection fetching</emphasis>: a collection is fetched + when the application invokes an operation upon that collection. This + is the default for collections. + </para> + </listitem> + <listitem> + <para> + <emphasis>"Extra-lazy" collection fetching</emphasis>: individual + elements of the collection are accessed from the database as needed. + Hibernate tries not to fetch the whole collection into memory unless + absolutely needed. It is suitable for large collections. + </para> + </listitem> + <listitem> + <para> + <emphasis>Proxy fetching</emphasis>: a single-valued association is + fetched when a method other than the identifier getter is invoked + upon the associated object. + </para> + </listitem> + <listitem> + <para> + <emphasis>"No-proxy" fetching</emphasis>: a single-valued association is + fetched when the instance variable is accessed. Compared to proxy fetching, + this approach is less lazy; the association is fetched even when only the + identifier is accessed. It is also more transparent, since no proxy is visible to + the application. This approach requires buildtime bytecode instrumentation + and is rarely necessary. + </para> + </listitem> + <listitem> + <para> + <emphasis>Lazy attribute fetching</emphasis>: an attribute or single + valued association is fetched when the instance variable is accessed. + This approach requires buildtime bytecode instrumentation and is rarely + necessary. + </para> + </listitem> + </itemizedlist> + + <para> + We have two orthogonal notions here: <emphasis>when</emphasis> is the association + fetched and <emphasis>how</emphasis> is it fetched. It is important that you do not + confuse them. We use <literal>fetch</literal> to tune performance. We can use + <literal>lazy</literal> to define a contract for what data is always available + in any detached instance of a particular class. + </para> + + <section id="performance-fetching-lazy"> + <title>Working with lazy associations</title> + + <para> + By default, Hibernate3 uses lazy select fetching for collections and lazy proxy + fetching for single-valued associations. These defaults make sense for most + associations in the majority of applications. + </para> + + <para> + If you set + <literal>hibernate.default_batch_fetch_size</literal>, Hibernate will use the + batch fetch optimization for lazy fetching. This optimization can also be enabled + at a more granular level. + </para> + + <para> + Please be aware that access to a + lazy association outside of the context of an open Hibernate session will result + in an exception. For example: + </para> + + <programlisting role="JAVA"><![CDATA[s = sessions.openSession(); +Transaction tx = s.beginTransaction(); + +User u = (User) s.createQuery("from User u where u.name=:userName") + .setString("userName", userName).uniqueResult(); +Map permissions = u.getPermissions(); + +tx.commit(); +s.close(); + +Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]></programlisting> + + <para> + Since the permissions collection was not initialized when the + <literal>Session</literal> was closed, the collection will not be able to + load its state. <emphasis>Hibernate does not support lazy initialization + for detached objects</emphasis>. This can be fixed by moving the code that reads + from the collection to just before the transaction is committed. + </para> + + <para> + Alternatively, you can use a non-lazy collection or association, + by specifying <literal>lazy="false"</literal> for the association mapping. + However, it is intended that lazy initialization be used for almost all + collections and associations. If you define too many non-lazy associations + in your object model, Hibernate will fetch the entire + database into memory in every transaction. + </para> + + <para> + On the other hand, you can use join fetching, which is non-lazy by + nature, instead of select fetching in a particular transaction. We will now explain + how to customize the fetching strategy. In Hibernate3, the mechanisms for + choosing a fetch strategy are identical for single-valued associations and + collections. + </para> + + </section> + + <section id="performance-fetching-custom" revision="4"> + <title>Tuning fetch strategies</title> + + <para> + Select fetching (the default) is extremely vulnerable to N+1 selects problems, + so we might want to enable join fetching in the mapping document: + </para> + + <programlisting role="XML"><![CDATA[<set name="permissions" + fetch="join"> + <key column="userId"/> + <one-to-many class="Permission"/> +</set]]></programlisting> + + <programlisting role="XML"><![CDATA[<many-to-one name="mother" class="Cat" fetch="join"/>]]></programlisting> + + <para> + The <literal>fetch</literal> strategy defined in the mapping document affects: + </para> + + <itemizedlist> + <listitem> + <para> + retrieval via <literal>get()</literal> or <literal>load()</literal> + </para> + </listitem> + <listitem> + <para> + retrieval that happens implicitly when an association is navigated + </para> + </listitem> + <listitem> + <para> + <literal>Criteria</literal> queries + </para> + </listitem> + <listitem> + <para> + HQL queries if <literal>subselect</literal> fetching is used + </para> + </listitem> + </itemizedlist> + + <para> + Irrespective of the fetching strategy you use, the defined non-lazy graph is guaranteed + to be loaded into memory. This might, however, result in several immediate selects + being used to execute a particular HQL query. + </para> + + <para> + Usually, the mapping document is not used to customize fetching. Instead, we + keep the default behavior, and override it for a particular transaction, using + <literal>left join fetch</literal> in HQL. This tells Hibernate to fetch + the association eagerly in the first select, using an outer join. In the + <literal>Criteria</literal> query API, you would use + <literal>setFetchMode(FetchMode.JOIN)</literal>. + </para> + + <para> + If you want to change the fetching strategy used by + <literal>get()</literal> or <literal>load()</literal>, you can use a + <literal>Criteria</literal> query. For example: + </para> + + <programlisting role="JAVA"><![CDATA[User user = (User) session.createCriteria(User.class) + .setFetchMode("permissions", FetchMode.JOIN) + .add( Restrictions.idEq(userId) ) + .uniqueResult();]]></programlisting> + + <para> + This is Hibernate's equivalent of what some ORM solutions call a "fetch plan". + </para> + + <para> + A completely different approach to problems with N+1 selects is to use the + second-level cache. + </para> + + </section> + + <section id="performance-fetching-proxies" revision="2"> + <title>Single-ended association proxies</title> + + <para> + Lazy fetching for collections is implemented using Hibernate's own implementation + of persistent collections. However, a different mechanism is needed for lazy + behavior in single-ended associations. The target entity of the association must + be proxied. Hibernate implements lazy initializing proxies for persistent objects + using runtime bytecode enhancement which is accessed via the CGLIB library. + </para> + + <para> + At startup, Hibernate3 generates proxies by default for all persistent classes + and uses them to enable lazy fetching of <literal>many-to-one</literal> and + <literal>one-to-one</literal> associations. + </para> + + <para> + The mapping file may declare an interface to use as the proxy interface for that + class, with the <literal>proxy</literal> attribute. By default, Hibernate uses a subclass + of the class. <emphasis>The proxied class must implement a default constructor + with at least package visibility. This constructor is recommended for all persistent classes</emphasis>. + </para> + + <para> + There are potential problems to note when extending this approach to polymorphic classes.For example: + </para> + + <programlisting role="XML"><![CDATA[<class name="Cat" proxy="Cat"> + ...... + <subclass name="DomesticCat"> + ..... + </subclass> +</class>]]></programlisting> + + <para> + Firstly, instances of <literal>Cat</literal> will never be castable to + <literal>DomesticCat</literal>, even if the underlying instance is an + instance of <literal>DomesticCat</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = (Cat) session.load(Cat.class, id); // instantiate a proxy (does not hit the db) +if ( cat.isDomesticCat() ) { // hit the db to initialize the proxy + DomesticCat dc = (DomesticCat) cat; // Error! + .... +}]]></programlisting> + + <para> + Secondly, it is possible to break proxy <literal>==</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = (Cat) session.load(Cat.class, id); // instantiate a Cat proxy +DomesticCat dc = + (DomesticCat) session.load(DomesticCat.class, id); // acquire new DomesticCat proxy! +System.out.println(cat==dc); // false]]></programlisting> + + <para> + However, the situation is not quite as bad as it looks. Even though we now have two references + to different proxy objects, the underlying instance will still be the same object: + </para> + + <programlisting role="JAVA"><![CDATA[cat.setWeight(11.0); // hit the db to initialize the proxy +System.out.println( dc.getWeight() ); // 11.0]]></programlisting> + + <para> + Third, you cannot use a CGLIB proxy for a <literal>final</literal> class or a class + with any <literal>final</literal> methods. + </para> + + <para> + Finally, if your persistent object acquires any resources upon instantiation (e.g. in + initializers or default constructor), then those resources will also be acquired by + the proxy. The proxy class is an actual subclass of the persistent class. + </para> + + <para> + These problems are all due to fundamental limitations in Java's single inheritance model. + To avoid these problems your persistent classes must each implement an interface + that declares its business methods. You should specify these interfaces in the mapping file where + <literal>CatImpl</literal> implements the interface <literal>Cat</literal> and <literal>DomesticCatImpl</literal> + implements the interface <literal>DomesticCat</literal>. For example: + </para> + + <programlisting role="XML"><![CDATA[<class name="CatImpl" proxy="Cat"> + ...... + <subclass name="DomesticCatImpl" proxy="DomesticCat"> + ..... + </subclass> +</class>]]></programlisting> + + <para> + Then proxies for instances of <literal>Cat</literal> and <literal>DomesticCat</literal> can be returned + by <literal>load()</literal> or <literal>iterate()</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = (Cat) session.load(CatImpl.class, catid); +Iterator iter = session.createQuery("from CatImpl as cat where cat.name='fritz'").iterate(); +Cat fritz = (Cat) iter.next();]]></programlisting> + + + <note><title>Note</title> + <para> + <literal>list()</literal> does not usually return proxies. + </para> + </note> + + <para> + Relationships are also lazily initialized. This means you must declare any properties to be of + type <literal>Cat</literal>, not <literal>CatImpl</literal>. + </para> + + <para> + Certain operations do <emphasis>not</emphasis> require proxy initialization: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>equals()</literal>: if the persistent class does not override + <literal>equals()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hashCode()</literal>: if the persistent class does not override + <literal>hashCode()</literal> + </para> + </listitem> + <listitem> + <para> + The identifier getter method + </para> + </listitem> + </itemizedlist> + + <para> + Hibernate will detect persistent classes that override <literal>equals()</literal> or + <literal>hashCode()</literal>. + </para> + + <para> + By choosing <literal>lazy="no-proxy"</literal> instead of the default + <literal>lazy="proxy"</literal>, you can avoid problems associated with typecasting. + However, buildtime bytecode instrumentation is required, and all operations + will result in immediate proxy initialization. + </para> + + </section> + + <section id="performance-fetching-initialization" revision="1"> + <title>Initializing collections and proxies</title> + + <para> + A <literal>LazyInitializationException</literal> will be thrown by Hibernate if an uninitialized + collection or proxy is accessed outside of the scope of the <literal>Session</literal>, i.e., when + the entity owning the collection or having the reference to the proxy is in the detached state. + </para> + + <para> + Sometimes a proxy or collection needs to be initialized before closing the + <literal>Session</literal>. You can force initialization by calling + <literal>cat.getSex()</literal> or <literal>cat.getKittens().size()</literal>, for example. + However, this can be confusing to readers of the code and it is not convenient for generic code. + </para> + + <para> + The static methods <literal>Hibernate.initialize()</literal> and <literal>Hibernate.isInitialized()</literal>, + provide the application with a convenient way of working with lazily initialized collections or + proxies. <literal>Hibernate.initialize(cat)</literal> will force the initialization of a proxy, + <literal>cat</literal>, as long as its <literal>Session</literal> is still open. + <literal>Hibernate.initialize( cat.getKittens() )</literal> has a similar effect for the collection + of kittens. + </para> + + <para> + Another option is to keep the <literal>Session</literal> open until all required + collections and proxies have been loaded. In some application architectures, + particularly where the code that accesses data using Hibernate, and the code that + uses it are in different application layers or different physical processes, it + can be a problem to ensure that the <literal>Session</literal> is open when a + collection is initialized. There are two basic ways to deal with this issue: + </para> + + <itemizedlist> + <listitem> + <para> + In a web-based application, a servlet filter can be used to close the + <literal>Session</literal> only at the end of a user request, once + the rendering of the view is complete (the <emphasis>Open Session in + View</emphasis> pattern). Of course, this places heavy demands on the + correctness of the exception handling of your application infrastructure. + It is vitally important that the <literal>Session</literal> is closed and the + transaction ended before returning to the user, even when an exception occurs + during rendering of the view. See the Hibernate Wiki for examples of this + "Open Session in View" pattern. + </para> + </listitem> + <listitem> + <para> + In an application with a separate business tier, the business logic must + "prepare" all collections that the web tier needs before + returning. This means that the business tier should load all the data and + return all the data already initialized to the presentation/web tier that + is required for a particular use case. Usually, the application calls + <literal>Hibernate.initialize()</literal> for each collection that will + be needed in the web tier (this call must occur before the session is closed) + or retrieves the collection eagerly using a Hibernate query with a + <literal>FETCH</literal> clause or a <literal>FetchMode.JOIN</literal> in + <literal>Criteria</literal>. This is usually easier if you adopt the + <emphasis>Command</emphasis> pattern instead of a <emphasis>Session Facade</emphasis>. + </para> + </listitem> + <listitem> + <para> + You can also attach a previously loaded object to a new <literal>Session</literal> + with <literal>merge()</literal> or <literal>lock()</literal> before + accessing uninitialized collections or other proxies. Hibernate does not, + and certainly <emphasis>should</emphasis> not, do this automatically since it + would introduce impromptu transaction semantics. + </para> + </listitem> + </itemizedlist> + + <para> + Sometimes you do not want to initialize a large collection, but still need some + information about it, like its size, for example, or a subset of the data. + </para> + + <para> + You can use a collection filter to get the size of a collection without initializing it: + </para> + + <programlisting role="JAVA"><![CDATA[( (Integer) s.createFilter( collection, "select count(*)" ).list().get(0) ).intValue()]]></programlisting> + + <para> + The <literal>createFilter()</literal> method is also used to efficiently retrieve subsets + of a collection without needing to initialize the whole collection: + </para> + + <programlisting role="JAVA"><![CDATA[s.createFilter( lazyCollection, "").setFirstResult(0).setMaxResults(10).list();]]></programlisting> + + </section> + + <section id="performance-fetching-batch"> + <title>Using batch fetching</title> + + <para> + Using batch fetching, Hibernate can load several uninitialized + proxies if one proxy is accessed. Batch fetching is an optimization of the lazy select + fetching strategy. There are two ways you can configure batch fetching: on the class level and the collection level. + </para> + + <para> + Batch fetching for classes/entities is easier to understand. Consider the following example: + at runtime you have 25 <literal>Cat</literal> instances loaded in a <literal>Session</literal>, and each + <literal>Cat</literal> has a reference to its <literal>owner</literal>, a <literal>Person</literal>. + The <literal>Person</literal> class is mapped with a proxy, <literal>lazy="true"</literal>. If you now + iterate through all cats and call <literal>getOwner()</literal> on each, Hibernate will, by default, + execute 25 <literal>SELECT</literal> statements to retrieve the proxied owners. You can tune this + behavior by specifying a <literal>batch-size</literal> in the mapping of <literal>Person</literal>: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person" batch-size="10">...</class>]]></programlisting> + + <para> + Hibernate will now execute only three queries: the pattern is 10, 10, 5. + </para> + + <para> + You can also enable batch fetching of collections. For example, if each <literal>Person</literal> has + a lazy collection of <literal>Cat</literal>s, and 10 persons are currently loaded in the + <literal>Session</literal>, iterating through all persons will generate 10 <literal>SELECT</literal>s, + one for every call to <literal>getCats()</literal>. If you enable batch fetching for the + <literal>cats</literal> collection in the mapping of <literal>Person</literal>, Hibernate can pre-fetch + collections: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <set name="cats" batch-size="3"> + ... + </set> +</class>]]></programlisting> + + <para> + With a <literal>batch-size</literal> of 3, Hibernate will load 3, 3, 3, 1 collections in four + <literal>SELECT</literal>s. Again, the value of the attribute depends on the expected number of + uninitialized collections in a particular <literal>Session</literal>. + </para> + + <para> + Batch fetching of collections is particularly useful if you have a nested tree of items, i.e. + the typical bill-of-materials pattern. However, a <emphasis>nested set</emphasis> or a + <emphasis>materialized path</emphasis> might be a better option for read-mostly trees. + </para> + + </section> + + <section id="performance-fetching-subselect"> + <title>Using subselect fetching</title> + + <para> + If one lazy collection or single-valued proxy has to be fetched, Hibernate will load all of + them, re-running the original query in a subselect. This works in the same way as + batch-fetching but without the piecemeal loading. + </para> + + <!-- TODO: Write more about this --> + + </section> + + <section id="performance-fetching-profiles"> + <title>Fetch profiles</title> + + <para> + Another way to affect the fetching strategy for loading associated objects is through something + called a fetch profile, which is a named configuration associated with the + <interfacename>org.hibernate.SessionFactory</interfacename> but enabled, by name, on the + <interfacename>org.hibernate.Session</interfacename>. Once enabled on a + <interfacename>org.hibernate.Session</interfacename>, the fetch profile wull be in affect for + that <interfacename>org.hibernate.Session</interfacename> until it is explicitly disabled. + </para> + <para> + So what does that mean? Well lets explain that by way of an example. Say we have + the following mappings: + </para> + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="Customer"> + ... + <set name="orders" inverse="true"> + <key column="cust_id"/> + <one-to-many class="Order"/> + </set> + </class> + <class name="Order"> + ... + </class> +</hibernate-mapping>]]></programlisting> + <para> + Now normally when you get a reference to a particular customer, that customer's set of + orders will be lazy meaning we will not yet have loaded those orders from the database. + Normally this is a good thing. Now lets say that you have a certain use case where + it is more efficient to load the customer and their orders together. One way certainly is + to use "dynamic fetching" strategies via an HQL or criteria queries. But another option is + to use a fetch profile to achieve that. Just add the following to your mapping: + </para> + <programlisting role="XML"><![CDATA[<hibernate-mapping> + ... + <fetch-profile name="customer-with-orders"> + <fetch entity="Customer" association="orders" style="join"/> + </fetch-profile> +</hibernate-mapping>]]></programlisting> + <para> + or even: + </para> + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="Customer"> + ... + <fetch-profile name="customer-with-orders"> + <fetch association="orders" style="join"/> + </fetch-profile> + </class> + ... +</hibernate-mapping>]]></programlisting> + <para> + Now the following code will actually load both the customer <emphasis>and their orders</emphasis>: + </para> + <programlisting role="JAVA"><![CDATA[ + Session session = ...; + session.enableFetchProfile( "customer-with-orders" ); // name matches from mapping + Customer customer = (Customer) session.get( Customer.class, customerId ); + +]]></programlisting> + <para> + Currently only join style fetch profiles are supported, but they plan is to support additional + styles. See <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-3... + for details. + </para> + </section> + + <section id="performance-fetching-lazyproperties"> + <title>Using lazy property fetching</title> + + <para> + Hibernate3 supports the lazy fetching of individual properties. This optimization technique + is also known as <emphasis>fetch groups</emphasis>. Please note that this is mostly a + marketing feature; optimizing row reads is much more important than + optimization of column reads. However, only loading some properties of a class could + be useful in extreme cases. For example, when legacy tables have hundreds of columns and the data model + cannot be improved. + </para> + + <para> + To enable lazy property loading, set the <literal>lazy</literal> attribute on your + particular property mappings: + </para> + + <programlisting role="XML"><![CDATA[<class name="Document"> + <id name="id"> + <generator class="native"/> + </id> + <property name="name" not-null="true" length="50"/> + <property name="summary" not-null="true" length="200" lazy="true"/> + <property name="text" not-null="true" length="2000" lazy="true"/> +</class>]]></programlisting> + + <para> + Lazy property loading requires buildtime bytecode instrumentation. If your persistent + classes are not enhanced, Hibernate will ignore lazy property settings and + return to immediate fetching. + </para> + + <para> + For bytecode instrumentation, use the following Ant task: + </para> + + <programlisting role="XML"><![CDATA[<target name="instrument" depends="compile"> + <taskdef name="instrument" classname="org.hibernate.tool.instrument.InstrumentTask"> + <classpath path="${jar.path}"/> + <classpath path="${classes.dir}"/> + <classpath refid="lib.class.path"/> + </taskdef> + + <instrument verbose="true"> + <fileset dir="${testclasses.dir}/org/hibernate/auction/model"> + <include name="*.class"/> + </fileset> + </instrument> +</target>]]></programlisting> + + <para> + A different way of avoiding unnecessary column reads, at least for + read-only transactions, is to use the projection features of HQL or Criteria + queries. This avoids the need for buildtime bytecode processing and is + certainly a preferred solution. + </para> + + <para> + You can force the usual eager fetching of properties using <literal>fetch all + properties</literal> in HQL. + </para> + + </section> + </section> + + <section id="performance-cache" revision="1"> + <title>The Second Level Cache</title> + + <para> + A Hibernate <literal>Session</literal> is a transaction-level cache of persistent data. It is + possible to configure a cluster or JVM-level (<literal>SessionFactory</literal>-level) cache on + a class-by-class and collection-by-collection basis. You can even plug in a clustered cache. Be + aware that caches are not aware of changes made to the persistent store by another application. + They can, however, be configured to regularly expire cached data. + </para> + + <para revision="1"> + You have the option to tell Hibernate which caching implementation to use by + specifying the name of a class that implements <literal>org.hibernate.cache.CacheProvider</literal> + using the property <literal>hibernate.cache.provider_class</literal>. Hibernate + is bundled with a number of built-in integrations with the open-source cache providers + that are listed below. You can also implement your own and plug it in as + outlined above. Note that versions prior to 3.2 use EhCache as the default + cache provider. + </para> + + <table frame="topbot" id="cacheproviders" revision="1"> + <title>Cache Providers</title> + <tgroup cols='5' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="3*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <thead> + <row> + <entry>Cache</entry> + <entry>Provider class</entry> + <entry>Type</entry> + <entry>Cluster Safe</entry> + <entry>Query Cache Supported</entry> + </row> + </thead> + <tbody> + <row> + <entry>Hashtable (not intended for production use)</entry> + <entry><literal>org.hibernate.cache.HashtableCacheProvider</literal></entry> + <entry>memory</entry> + <entry> </entry> + <entry>yes</entry> + </row> + <row> + <entry>EHCache</entry> + <entry><literal>org.hibernate.cache.EhCacheProvider</literal></entry> + <entry>memory, disk</entry> + <entry> </entry> + <entry>yes</entry> + </row> + <row> + <entry>OSCache</entry> + <entry><literal>org.hibernate.cache.OSCacheProvider</literal></entry> + <entry>memory, disk</entry> + <entry> </entry> + <entry>yes</entry> + </row> + <row> + <entry>SwarmCache</entry> + <entry><literal>org.hibernate.cache.SwarmCacheProvider</literal></entry> + <entry>clustered (ip multicast)</entry> + <entry>yes (clustered invalidation)</entry> + <entry> </entry> + </row> + <row> + <entry>JBoss Cache 1.x</entry> + <entry><literal>org.hibernate.cache.TreeCacheProvider</literal></entry> + <entry>clustered (ip multicast), transactional</entry> + <entry>yes (replication)</entry> + <entry>yes (clock sync req.)</entry> + </row> + <row> + <entry>JBoss Cache 2</entry> + <entry><literal>org.hibernate.cache.jbc.JBossCacheRegionFactory</literal></entry> + <entry>clustered (ip multicast), transactional</entry> + <entry>yes (replication or invalidation)</entry> + <entry>yes (clock sync req.)</entry> + </row> + </tbody> + </tgroup> + </table> + + <section id="performance-cache-mapping" revision="2"> + <title>Cache mappings</title> + + <para> + The <literal>&lt;cache&gt;</literal> element of a class or collection mapping has the + following form: + </para> + + <programlistingco> + <areaspec> + <area id="cache1" coords="2"/> + <area id="cache2" coords="3"/> + <area id="cache3" coords="4"/> + </areaspec> + <programlisting><![CDATA[<cache + usage="transactional|read-write|nonstrict-read-write|read-only" + region="RegionName" + include="all|non-lazy" +/>]]></programlisting> + <calloutlist> + <callout arearefs="cache1"> + <para> + <literal>usage</literal> (required) specifies the caching strategy: + <literal>transactional</literal>, + <literal>read-write</literal>, + <literal>nonstrict-read-write</literal> or + <literal>read-only</literal> + </para> + </callout> + <callout arearefs="cache2"> + <para> + <literal>region</literal> (optional: defaults to the class or + collection role name): specifies the name of the second level cache + region + </para> + </callout> + <callout arearefs="cache3"> + <para> + <literal>include</literal> (optional: defaults to <literal>all</literal>) + <literal>non-lazy</literal>: specifies that properties of the entity mapped + with <literal>lazy="true"</literal> cannot be cached when attribute-level + lazy fetching is enabled + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Alternatively, you can specify <literal>&lt;class-cache&gt;</literal> and + <literal>&lt;collection-cache&gt;</literal> elements in <literal>hibernate.cfg.xml</literal>. + </para> + + <para> + The <literal>usage</literal> attribute specifies a <emphasis>cache concurrency strategy</emphasis>. + </para> + + </section> + + <section id="performance-cache-readonly"> + <title>Strategy: read only</title> + + <para> + If your application needs to read, but not modify, instances of a persistent class, a + <literal>read-only</literal> cache can be used. This is the simplest and optimal performing + strategy. It is even safe for use in a cluster. + </para> + + <programlisting role="XML"><![CDATA[<class name="eg.Immutable" mutable="false"> + <cache usage="read-only"/> + .... +</class>]]></programlisting> + + </section> + + + <section id="performance-cache-readwrite"> + <title>Strategy: read/write</title> + + <para> + If the application needs to update data, a <literal>read-write</literal> cache might be appropriate. + This cache strategy should never be used if serializable transaction isolation level is required. + If the cache is used in a JTA environment, you must specify the property + <literal>hibernate.transaction.manager_lookup_class</literal> and naming a strategy for obtaining the + JTA <literal>TransactionManager</literal>. In other environments, you should ensure that the transaction + is completed when <literal>Session.close()</literal> or <literal>Session.disconnect()</literal> is called. + If you want to use this strategy in a cluster, you should ensure that the underlying cache implementation + supports locking. The built-in cache providers <emphasis>do not</emphasis> support locking. + </para> + + <programlisting role="XML"><![CDATA[<class name="eg.Cat" .... > + <cache usage="read-write"/> + .... + <set name="kittens" ... > + <cache usage="read-write"/> + .... + </set> +</class>]]></programlisting> + + </section> + + <section id="performance-cache-nonstrict"> + <title>Strategy: nonstrict read/write</title> + + <para> + If the application only occasionally needs to update data (i.e. if it is extremely unlikely that two + transactions would try to update the same item simultaneously), and strict transaction isolation is + not required, a <literal>nonstrict-read-write</literal> cache might be appropriate. If the cache is + used in a JTA environment, you must specify <literal>hibernate.transaction.manager_lookup_class</literal>. + In other environments, you should ensure that the transaction is completed when + <literal>Session.close()</literal> or <literal>Session.disconnect()</literal> is called. + </para> + + </section> + + <section id="performance-cache-transactional"> + <title>Strategy: transactional</title> + + <para> + The <literal>transactional</literal> cache strategy provides support for fully transactional cache + providers such as JBoss TreeCache. Such a cache can only be used in a JTA environment and you must + specify <literal>hibernate.transaction.manager_lookup_class</literal>. + </para> + + </section> + + <section id="performance-cache-compat-matrix"> + <title>Cache-provider/concurrency-strategy compatibility</title> + + <important> + <para> + None of the cache providers support all of the cache concurrency strategies. + </para> + </important> + + <para> + The following table shows which providers are compatible with which concurrency strategies. + </para> + + <table frame="topbot"> + <title>Cache Concurrency Strategy Support</title> + <tgroup cols='5' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <thead> + <row> + <entry>Cache</entry> + <entry>read-only</entry> + <entry>nonstrict-read-write</entry> + <entry>read-write</entry> + <entry>transactional</entry> + </row> + </thead> + <tbody> + <row> + <entry>Hashtable (not intended for production use)</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry> </entry> + </row> + <row> + <entry>EHCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry> </entry> + </row> + <row> + <entry>OSCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry> </entry> + </row> + <row> + <entry>SwarmCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry> </entry> + <entry> </entry> + </row> + <row> + <entry>JBoss Cache 1.x</entry> + <entry>yes</entry> + <entry> </entry> + <entry> </entry> + <entry>yes</entry> + </row> + <row> + <entry>JBoss Cache 2</entry> + <entry>yes</entry> + <entry> </entry> + <entry> </entry> + <entry>yes</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + </section> + + <section id="performance-sessioncache" revision="2"> + <title>Managing the caches</title> + + <para> + Whenever you pass an object to <literal>save()</literal>, <literal>update()</literal> + or <literal>saveOrUpdate()</literal>, and whenever you retrieve an object using + <literal>load()</literal>, <literal>get()</literal>, <literal>list()</literal>, + <literal>iterate()</literal> or <literal>scroll()</literal>, that object is added + to the internal cache of the <literal>Session</literal>. + </para> + <para> + When <literal>flush()</literal> is subsequently called, the state of that object will + be synchronized with the database. If you do not want this synchronization to occur, or + if you are processing a huge number of objects and need to manage memory efficiently, + the <literal>evict()</literal> method can be used to remove the object and its collections + from the first-level cache. + </para> + + <programlisting role="JAVA"><![CDATA[ScrollableResult cats = sess.createQuery("from Cat as cat").scroll(); //a huge result set +while ( cats.next() ) { + Cat cat = (Cat) cats.get(0); + doSomethingWithACat(cat); + sess.evict(cat); +}]]></programlisting> + + <para> + The <literal>Session</literal> also provides a <literal>contains()</literal> method to determine + if an instance belongs to the session cache. + </para> + + <para> + To evict all objects from the session cache, call <literal>Session.clear()</literal> + </para> + + <para> + For the second-level cache, there are methods defined on <literal>SessionFactory</literal> for + evicting the cached state of an instance, entire class, collection instance or entire collection + role. + </para> + + <programlisting role="JAVA"><![CDATA[sessionFactory.evict(Cat.class, catId); //evict a particular Cat +sessionFactory.evict(Cat.class); //evict all Cats +sessionFactory.evictCollection("Cat.kittens", catId); //evict a particular collection of kittens +sessionFactory.evictCollection("Cat.kittens"); //evict all kitten collections]]></programlisting> + + <para> + The <literal>CacheMode</literal> controls how a particular session interacts with the second-level + cache: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>CacheMode.NORMAL</literal>: will read items from and write items to the second-level cache + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.GET</literal>: will read items from the second-level cache. Do not write to + the second-level cache except when updating data + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.PUT</literal>: will write items to the second-level cache. Do not read from + the second-level cache + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.REFRESH</literal>: will write items to the second-level cache. Do not read from + the second-level cache. Bypass the effect of <literal>hibernate.cache.use_minimal_puts</literal> forcing + a refresh of the second-level cache for all items read from the database + </para> + </listitem> + </itemizedlist> + + <para> + To browse the contents of a second-level or query cache region, use the <literal>Statistics</literal> + API: + </para> + + <programlisting role="JAVA"><![CDATA[Map cacheEntries = sessionFactory.getStatistics() + .getSecondLevelCacheStatistics(regionName) + .getEntries();]]></programlisting> + + <para> + You will need to enable statistics and, optionally, force Hibernate to keep the cache entries in a + more readable format: + </para> + + <programlisting><![CDATA[hibernate.generate_statistics true +hibernate.cache.use_structured_entries true]]></programlisting> + + </section> + + <section id="performance-querycache" revision="1"> + <title>The Query Cache</title> + + <para> + Query result sets can also be cached. This is only useful for queries that are run + frequently with the same parameters. + </para> + + <section id="performance-querycache-enable"> + <title>Enabling query caching</title> + <para> + Caching of query results introduces some overhead in terms of your applications normal + transactional processing. For example, if you cache results of a query against Person + Hibernate will need to keep track of when those results should be invalidated because + changes have been committed against Person. That, coupled with the fact that most + applications simply gain no benefit from caching query results, leads Hibernate to + disable caching of query results by default. To use query caching, you will first + need to enable the query cache: + </para> + <programlisting><![CDATA[hibernate.cache.use_query_cache true]]></programlisting> + <para> + This setting creates two new cache regions: + <itemizedlist> + <listitem> + <para> + <classname>org.hibernate.cache.StandardQueryCache</classname>, holding + the cached query results + </para> + </listitem> + <listitem> + <para> + <classname>org.hibernate.cache.UpdateTimestampsCache</classname>, holding + timestamps of the most recent updates to queryable tables. These are used + to validate the results as they are served from the query cache. + </para> + </listitem> + </itemizedlist> + </para> + <important> + <para> + If you configure your underlying cache implementation to use expiry or + timeouts is very important that the cache timeout of the underlying + cache region for the UpdateTimestampsCache be set to a higher value than + the timeouts of any of the query caches. In fact, we recommend that the + the UpdateTimestampsCache region not be configured for expiry at all. Note, + in particular, that an LRU cache expiry policy is never appropriate. + </para> + </important> + <para> + As mentioned above, most queries do not benefit from caching or their results. So by + default, individual queries are not cached even after enabling query caching. To enable + results caching for a particular query, call + <literal>org.hibernate.Query.setCacheable(true)</literal>. This call allows the query + to look for existing cache results or add its results to the cache when it is executed. + </para> + <note> + <para> + The query cache does not cache the state of the actual entities in the cache; it + caches only identifier values and results of value type. For this reaso, the query + cache should always be used in conjunction with the second-level cache for those + entities expected to be cached as part of a query result cache (just as with + collection caching). + </para> + </note> + </section> + + <section id="performance-querycache-regions"> + <title>Query cache regions</title> + <para> + If you require fine-grained control over query cache expiration policies, you can + specify a named cache region for a particular query by calling + <literal>Query.setCacheRegion()</literal>. + </para> + <programlisting role="JAVA"><![CDATA[List blogs = sess.createQuery("from Blog blog where blog.blogger = :blogger") + .setEntity("blogger", blogger) + .setMaxResults(15) + .setCacheable(true) + .setCacheRegion("frontpages") + .list();]]></programlisting> + + <para> + If you want to force the query cache to refresh one of its regions (disregard any + cached results it finds there) you can use + <literal>org.hibernate.Query.setCacheMode(CacheMode.REFRESH)</literal>. In conjunction + with the region you have defined for the given query, Hibernate will selectively force + the results cached in that particular region to be refreshed. This is particularly useful + in cases where underlying data may have been updated via a separate process and is a far more + efficient alternative to bulk eviction of the region via + <literal>org.hibernate.SessionFactory.evictQueries()</literal>. + </para> + </section> + </section> + + <section id="performance-collections"> + <title>Understanding Collection performance</title> + + <para> + In the previous sections we have covered collections and their applications. + In this section we explore some more issues in relation to + collections at runtime. + </para> + + <section id="performance-collections-taxonomy"> + <title>Taxonomy</title> + + <para>Hibernate defines three basic kinds of collections:</para> + + <itemizedlist> + <listitem> + <para>collections of values</para> + </listitem> + <listitem> + <para>one-to-many associations</para> + </listitem> + <listitem> + <para>many-to-many associations</para> + </listitem> + </itemizedlist> + + <para> + This classification distinguishes the various table and foreign key + relationships but does not tell us quite everything we need to know + about the relational model. To fully understand the relational structure + and performance characteristics, we must also consider the structure of + the primary key that is used by Hibernate to update or delete collection + rows. This suggests the following classification: + </para> + + <itemizedlist> + <listitem> + <para>indexed collections</para> + </listitem> + <listitem> + <para>sets</para> + </listitem> + <listitem> + <para>bags</para> + </listitem> + </itemizedlist> + + <para> + All indexed collections (maps, lists, and arrays) have a primary key consisting + of the <literal>&lt;key&gt;</literal> and <literal>&lt;index&gt;</literal> + columns. In this case, collection updates are extremely efficient. + The primary key can be efficiently indexed and a particular row can be efficiently + located when Hibernate tries to update or delete it. + </para> + + <para> + Sets have a primary key consisting of <literal>&lt;key&gt;</literal> and element + columns. This can be less efficient for some types of collection element, particularly + composite elements or large text or binary fields, as the database may not be able to index + a complex primary key as efficiently. However, for one-to-many or many-to-many + associations, particularly in the case of synthetic identifiers, it is likely to be just + as efficient. If you want <literal>SchemaExport</literal> to actually create + the primary key of a <literal>&lt;set&gt;</literal>, you must declare all columns + as <literal>not-null="true"</literal>. + </para> + + <para> + <literal>&lt;idbag&gt;</literal> mappings define a surrogate key, so they are + efficient to update. In fact, they are the best case. + </para> + + <para> + Bags are the worst case since they permit duplicate element values and, as they have no + index column, no primary key can be defined. Hibernate has no way of distinguishing + between duplicate rows. Hibernate resolves this problem by completely removing + in a single <literal>DELETE</literal> and recreating the collection whenever it + changes. This can be inefficient. + </para> + + <para> + For a one-to-many association, the "primary key" may not be the physical + primary key of the database table. Even in this case, the above classification + is still useful. It reflects how Hibernate "locates" individual rows of the + collection. + </para> + + </section> + + <section id="performance-collections-mostefficientupdate"> + <title>Lists, maps, idbags and sets are the most efficient collections to update</title> + + <para> + From the discussion above, it should be clear that indexed collections + and sets allow the most efficient operation in terms of adding, + removing and updating elements. + </para> + + <para> + There is, arguably, one more advantage that indexed collections have over sets for + many-to-many associations or collections of values. Because of the structure of a + <literal>Set</literal>, Hibernate does not <literal>UPDATE</literal> a row when + an element is "changed". Changes to a <literal>Set</literal> always work via + <literal>INSERT</literal> and <literal>DELETE</literal> of individual rows. Once + again, this consideration does not apply to one-to-many associations. + </para> + + <para> + After observing that arrays cannot be lazy, you can conclude that lists, maps and + idbags are the most performant (non-inverse) collection types, with sets not far + behind. You can expect sets to be the most common kind of collection in Hibernate + applications. This is because the "set" semantics are most natural in the relational + model. + </para> + + <para> + However, in well-designed Hibernate domain models, most collections + are in fact one-to-many associations with <literal>inverse="true"</literal>. For these + associations, the update is handled by the many-to-one end of the association, and so + considerations of collection update performance simply do not apply. + </para> + + </section> + + <section id="performance-collections-mostefficentinverse"> + <title>Bags and lists are the most efficient inverse collections</title> + + <para> + There is a particular case, however, in which bags, and also lists, + are much more performant than sets. For a collection with <literal>inverse="true"</literal>, + the standard bidirectional one-to-many relationship idiom, for example, we can add elements + to a bag or list without needing to initialize (fetch) the bag elements. This is because, unlike a <literal>set</literal>, + <literal>Collection.add()</literal> or <literal>Collection.addAll()</literal> must always + return true for a bag or <literal>List</literal>. This can + make the following common code much faster: + </para> + + <programlisting role="JAVA"><![CDATA[Parent p = (Parent) sess.load(Parent.class, id); +Child c = new Child(); +c.setParent(p); +p.getChildren().add(c); //no need to fetch the collection! +sess.flush();]]></programlisting> + + </section> + + <section id="performance-collections-oneshotdelete"> + <title>One shot delete</title> + + <para> + Deleting collection elements one by one can sometimes be extremely inefficient. Hibernate + knows not to do that in the case of an newly-empty collection + (if you called <literal>list.clear()</literal>, for example). In this case, Hibernate will + issue a single <literal>DELETE</literal>. + </para> + + <para> + Suppose you added a single element to a collection of size twenty and then remove two elements. + Hibernate will issue one <literal>INSERT</literal> statement and two <literal>DELETE</literal> + statements, unless the collection is a bag. This is certainly desirable. + </para> + + <para> + However, suppose that we remove eighteen elements, leaving two and then add thee new elements. + There are two possible ways to proceed + </para> + + <itemizedlist> + <listitem> + <para>delete eighteen rows one by one and then insert three rows</para> + </listitem> + <listitem> + <para>remove the whole collection in one SQL <literal>DELETE</literal> and insert + all five current elements one by one</para> + </listitem> + </itemizedlist> + + <para> + Hibernate cannot know that the second option is probably quicker. + It would probably be undesirable for Hibernate to be that intuitive as such behavior might + confuse database triggers, etc. + </para> + + <para> + Fortunately, you can force this behavior (i.e. the second strategy) at any time by discarding + (i.e. dereferencing) the original collection and returning a newly instantiated collection with + all the current elements. + </para> + + <para> + One-shot-delete does not apply to collections mapped <literal>inverse="true"</literal>. + </para> + + </section> + + </section> + + <section id="performance-monitoring" revision="1"> + <title>Monitoring performance</title> + + <para> + Optimization is not much use without monitoring and access to performance numbers. + Hibernate provides a full range of figures about its internal operations. + Statistics in Hibernate are available per <literal>SessionFactory</literal>. + </para> + + <section id="performance-monitoring-sf" revision="2"> + <title>Monitoring a SessionFactory</title> + + <para> + You can access <literal>SessionFactory</literal> metrics in two ways. + Your first option is to call <literal>sessionFactory.getStatistics()</literal> and + read or display the <literal>Statistics</literal> yourself. + </para> + + <para> + Hibernate can also use JMX to publish metrics if you enable the + <literal>StatisticsService</literal> MBean. You can enable a single MBean for all your + <literal>SessionFactory</literal> or one per factory. See the following code for + minimalistic configuration examples: + </para> + + <programlisting role="JAVA"><![CDATA[// MBean service registration for a specific SessionFactory +Hashtable tb = new Hashtable(); +tb.put("type", "statistics"); +tb.put("sessionFactory", "myFinancialApp"); +ObjectName on = new ObjectName("hibernate", tb); // MBean object name + +StatisticsService stats = new StatisticsService(); // MBean implementation +stats.setSessionFactory(sessionFactory); // Bind the stats to a SessionFactory +server.registerMBean(stats, on); // Register the Mbean on the server]]></programlisting> + + +<programlisting role="JAVA"><![CDATA[// MBean service registration for all SessionFactory's +Hashtable tb = new Hashtable(); +tb.put("type", "statistics"); +tb.put("sessionFactory", "all"); +ObjectName on = new ObjectName("hibernate", tb); // MBean object name + +StatisticsService stats = new StatisticsService(); // MBean implementation +server.registerMBean(stats, on); // Register the MBean on the server]]></programlisting> + + <para> + You can activate and deactivate the monitoring for a <literal>SessionFactory</literal>: + </para> + <itemizedlist> + <listitem> + <para> + at configuration time, set <literal>hibernate.generate_statistics</literal> to <literal>false</literal> + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para> + at runtime: <literal>sf.getStatistics().setStatisticsEnabled(true)</literal> + or <literal>hibernateStatsBean.setStatisticsEnabled(true)</literal> + </para> + </listitem> + </itemizedlist> + + <para> + Statistics can be reset programmatically using the <literal>clear()</literal> method. + A summary can be sent to a logger (info level) using the <literal>logSummary()</literal> + method. + </para> + + </section> + + <section id="performance-monitoring-metrics" revision="1"> + <title>Metrics</title> + + <para> + Hibernate provides a number of metrics, from basic information to more specialized information + that is only relevant in certain scenarios. All available counters are described in the + <literal>Statistics</literal> interface API, in three categories: + </para> + <itemizedlist> + <listitem> + <para> + Metrics related to the general <literal>Session</literal> usage, such as + number of open sessions, retrieved JDBC connections, etc. + </para> + </listitem> + <listitem> + <para> + Metrics related to the entities, collections, queries, and caches as a + whole (aka global metrics). + </para> + </listitem> + <listitem> + <para> + Detailed metrics related to a particular entity, collection, query or + cache region. + </para> + </listitem> + </itemizedlist> + + <para> + For example, you can check the cache hit, miss, and put ratio of entities, collections + and queries, and the average time a query needs. Be aware that the number of milliseconds + is subject to approximation in Java. Hibernate is tied to the JVM precision and on some + platforms this might only be accurate to 10 seconds. + </para> + + <para> + Simple getters are used to access the global metrics (i.e. not tied to a particular entity, + collection, cache region, etc.). You can access the metrics of a particular entity, collection + or cache region through its name, and through its HQL or SQL representation for queries. Please + refer to the <literal>Statistics</literal>, <literal>EntityStatistics</literal>, + <literal>CollectionStatistics</literal>, <literal>SecondLevelCacheStatistics</literal>, + and <literal>QueryStatistics</literal> API Javadoc for more information. The following + code is a simple example: + </para> + + <programlisting role="JAVA"><![CDATA[Statistics stats = HibernateUtil.sessionFactory.getStatistics(); + +double queryCacheHitCount = stats.getQueryCacheHitCount(); +double queryCacheMissCount = stats.getQueryCacheMissCount(); +double queryCacheHitRatio = + queryCacheHitCount / (queryCacheHitCount + queryCacheMissCount); + +log.info("Query Hit ratio:" + queryCacheHitRatio); + +EntityStatistics entityStats = + stats.getEntityStatistics( Cat.class.getName() ); +long changes = + entityStats.getInsertCount() + + entityStats.getUpdateCount() + + entityStats.getDeleteCount(); +log.info(Cat.class.getName() + " changed " + changes + "times" );]]></programlisting> + + <para> + You can work on all entities, collections, queries and region caches, by retrieving + the list of names of entities, collections, queries and region caches using the + following methods: <literal>getQueries()</literal>, <literal>getEntityNames()</literal>, + <literal>getCollectionRoleNames()</literal>, and + <literal>getSecondLevelCacheRegionNames()</literal>. + </para> + + </section> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/persistent_classes.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/persistent_classes.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/persistent_classes.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,710 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="persistent-classes" revision="2"> + <title>Persistent Classes</title> + + <para> + Persistent classes are classes in an application that implement the entities + of the business problem (e.g. Customer and Order in an E-commerce application). + Not all instances of a persistent class are considered to be in the persistent + state. For example, an instance can instead be transient or detached. + </para> + + <para> + Hibernate works best if these classes follow some simple rules, also known + as the Plain Old Java Object (POJO) programming model. However, none of these + rules are hard requirements. Indeed, Hibernate3 assumes very little about + the nature of your persistent objects. You can express a domain model in other + ways (using trees of <literal>Map</literal> instances, for example). + </para> + + <section id="persistent-classes-pojo"> + <title>A simple POJO example</title> + + <para> + Most Java applications require a persistent class representing felines. For example: + </para> + + <programlisting role="JAVA"><![CDATA[package eg; +import java.util.Set; +import java.util.Date; + +public class Cat { + private Long id; // identifier + + private Date birthdate; + private Color color; + private char sex; + private float weight; + private int litterId; + + private Cat mother; + private Set kittens = new HashSet(); + + private void setId(Long id) { + this.id=id; + } + public Long getId() { + return id; + } + + void setBirthdate(Date date) { + birthdate = date; + } + public Date getBirthdate() { + return birthdate; + } + + void setWeight(float weight) { + this.weight = weight; + } + public float getWeight() { + return weight; + } + + public Color getColor() { + return color; + } + void setColor(Color color) { + this.color = color; + } + + void setSex(char sex) { + this.sex=sex; + } + public char getSex() { + return sex; + } + + void setLitterId(int id) { + this.litterId = id; + } + public int getLitterId() { + return litterId; + } + + void setMother(Cat mother) { + this.mother = mother; + } + public Cat getMother() { + return mother; + } + void setKittens(Set kittens) { + this.kittens = kittens; + } + public Set getKittens() { + return kittens; + } + + // addKitten not needed by Hibernate + public void addKitten(Cat kitten) { + kitten.setMother(this); + kitten.setLitterId( kittens.size() ); + kittens.add(kitten); + } +}]]></programlisting> + + <para> + The four main rules of persistent classes are explored in more detail in the following sections. + </para> + + + <section id="persistent-classes-pojo-constructor" revision="1"> + <title>Implement a no-argument constructor</title> + + <para> + <literal>Cat</literal> has a no-argument constructor. All persistent classes must + have a default constructor (which can be non-public) so that Hibernate can instantiate + them using <literal>Constructor.newInstance()</literal>. It is recommended that you have a + default constructor with at least <emphasis>package</emphasis> visibility for runtime proxy + generation in Hibernate. + </para> + </section> + + <section id="persistent-classes-pojo-identifier" revision="2"> + <title>Provide an identifier property (optional)</title> + + <para> + <literal>Cat</literal> has a property called <literal>id</literal>. This property + maps to the primary key column of a database table. The property might have been called + anything, and its type might have been any primitive type, any primitive "wrapper" + type, <literal>java.lang.String</literal> or <literal>java.util.Date</literal>. If + your legacy database table has composite keys, you can use a user-defined class + with properties of these types (see the section on composite identifiers later in the chapter.) + </para> + + <para> + The identifier property is strictly optional. You can leave them off and let Hibernate + keep track of object identifiers internally. We do not recommend this, however. + </para> + + <para> + In fact, some functionality is available only to classes that declare an + identifier property: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Transitive reattachment for detached objects (cascade update or cascade + merge) - see <xref linkend="objectstate-transitive"/> + </para> + </listitem> + <listitem> + <para> + <literal>Session.saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>Session.merge()</literal> + </para> + </listitem> + </itemizedlist> + + <para> + We recommend that you declare consistently-named identifier properties on persistent + classes and that you use a nullable (i.e., non-primitive) type. + </para> + </section> + + <section id="persistent-classes-pojo-final"> + <title>Prefer non-final classes (optional)</title> + <para> + A central feature of Hibernate, <emphasis>proxies</emphasis>, depends upon the + persistent class being either non-final, or the implementation of an interface + that declares all public methods. + </para> + <para> + You can persist <literal>final</literal> classes that do not implement an interface + with Hibernate. You will not, however, be able to use proxies for lazy association fetching which + will ultimately limit your options for performance tuning. + </para> + <para> + You should also avoid declaring <literal>public final</literal> methods on the + non-final classes. If you want to use a class with a <literal>public final</literal> + method, you must explicitly disable proxying by setting <literal>lazy="false"</literal>. + </para> + </section> + + <section id="persistent-classes-pojo-accessors" revision="2"> + <title>Declare accessors and mutators for persistent fields (optional)</title> + + <para> + <literal>Cat</literal> declares accessor methods for all its persistent fields. + Many other ORM tools directly persist instance variables. It is + better to provide an indirection between the relational schema and internal + data structures of the class. By default, Hibernate persists JavaBeans style + properties and recognizes method names of the form <literal>getFoo</literal>, + <literal>isFoo</literal> and <literal>setFoo</literal>. If required, you can switch to direct + field access for particular properties. + </para> + + <para> + Properties need <emphasis>not</emphasis> be declared public - Hibernate can + persist a property with a default, <literal>protected</literal> or + <literal>private</literal> get / set pair. + </para> + + </section> + + </section> + + <section id="persistent-classes-inheritance"> + <title>Implementing inheritance</title> + + <para> + A subclass must also observe the first and second rules. It inherits its + identifier property from the superclass, <literal>Cat</literal>. For example: + </para> + + <programlisting role="JAVA"><![CDATA[package eg; + +public class DomesticCat extends Cat { + private String name; + + public String getName() { + return name; + } + protected void setName(String name) { + this.name=name; + } +}]]></programlisting> + </section> + + <section id="persistent-classes-equalshashcode" revision="1"> + <title>Implementing <literal>equals()</literal> and <literal>hashCode()</literal></title> + + <para> + You have to override the <literal>equals()</literal> and <literal>hashCode()</literal> + methods if you: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + intend to put instances of persistent classes in a <literal>Set</literal> + (the recommended way to represent many-valued associations); + <emphasis>and</emphasis> + </para> + </listitem> + <listitem> + <para> + intend to use reattachment of detached instances + </para> + </listitem> + </itemizedlist> + + <para> + Hibernate guarantees equivalence of persistent identity (database row) and Java identity + only inside a particular session scope. When you mix instances retrieved in + different sessions, you must implement <literal>equals()</literal> and + <literal>hashCode()</literal> if you wish to have meaningful semantics for + <literal>Set</literal>s. + </para> + + <para> + The most obvious way is to implement <literal>equals()</literal>/<literal>hashCode()</literal> + by comparing the identifier value of both objects. If the value is the same, both must + be the same database row, because they are equal. If both are added to a <literal>Set</literal>, + you will only have one element in the <literal>Set</literal>). Unfortunately, you cannot use that + approach with generated identifiers. Hibernate will only assign identifier values to objects + that are persistent; a newly created instance will not have any identifier value. Furthermore, + if an instance is unsaved and currently in a <literal>Set</literal>, saving it will assign + an identifier value to the object. If <literal>equals()</literal> and <literal>hashCode()</literal> + are based on the identifier value, the hash code would change, breaking the contract of the + <literal>Set</literal>. See the Hibernate website for a full discussion of this problem. This is not + a Hibernate issue, but normal Java semantics of object identity and equality. + </para> + + <para> + It is recommended that you implement <literal>equals()</literal> and <literal>hashCode()</literal> + using <emphasis>Business key equality</emphasis>. Business key equality means that the + <literal>equals()</literal> method compares only the properties that form the business + key. It is a key that would identify our instance in the real world (a + <emphasis>natural</emphasis> candidate key): + </para> + + <programlisting role="JAVA"><![CDATA[public class Cat { + + ... + public boolean equals(Object other) { + if (this == other) return true; + if ( !(other instanceof Cat) ) return false; + + final Cat cat = (Cat) other; + + if ( !cat.getLitterId().equals( getLitterId() ) ) return false; + if ( !cat.getMother().equals( getMother() ) ) return false; + + return true; + } + + public int hashCode() { + int result; + result = getMother().hashCode(); + result = 29 * result + getLitterId(); + return result; + } + +}]]></programlisting> + + <para> + A business key does not have to be as solid as a database + primary key candidate (see <xref linkend="transactions-basics-identity"/>). + Immutable or unique properties are usually good + candidates for a business key. + </para> + + </section> + + <section id="persistent-classes-dynamicmodels"> + <title>Dynamic models</title> + + + <note><title>Note</title> +<para> + <emphasis>The following features are currently considered + experimental and may change in the near future.</emphasis> + + </para> +</note> + <para> + Persistent entities do not necessarily have to be represented as POJO classes + or as JavaBean objects at runtime. Hibernate also supports dynamic models + (using <literal>Map</literal>s of <literal>Map</literal>s at runtime) and the + representation of entities as DOM4J trees. With this approach, you do not + write persistent classes, only mapping files. + </para> + + <para> + By default, Hibernate works in normal POJO mode. You can set a default entity + representation mode for a particular <literal>SessionFactory</literal> using the + <literal>default_entity_mode</literal> configuration option (see + <xref linkend="configuration-optional-properties"/>). + </para> + + <para> + The following examples demonstrate the representation using <literal>Map</literal>s. + First, in the mapping file an <literal>entity-name</literal> has to be declared + instead of, or in addition to, a class name: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + + <class entity-name="Customer"> + + <id name="id" + type="long" + column="ID"> + <generator class="sequence"/> + </id> + + <property name="name" + column="NAME" + type="string"/> + + <property name="address" + column="ADDRESS" + type="string"/> + + <many-to-one name="organization" + column="ORGANIZATION_ID" + class="Organization"/> + + <bag name="orders" + inverse="true" + lazy="false" + cascade="all"> + <key column="CUSTOMER_ID"/> + <one-to-many class="Order"/> + </bag> + + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + + Even though associations are declared using target class names, + the target type of associations can also be a dynamic entity instead + of a POJO. + </para> + + <para> + After setting the default entity mode to <literal>dynamic-map</literal> + for the <literal>SessionFactory</literal>, you can, at runtime, work with + <literal>Map</literal>s of <literal>Map</literal>s: + </para> + + <programlisting role="JAVA"><![CDATA[Session s = openSession(); +Transaction tx = s.beginTransaction(); + +// Create a customer +Map david = new HashMap(); +david.put("name", "David"); + +// Create an organization +Map foobar = new HashMap(); +foobar.put("name", "Foobar Inc."); + +// Link both +david.put("organization", foobar); + +// Save both +s.save("Customer", david); +s.save("Organization", foobar); + +tx.commit(); +s.close();]]></programlisting> + + <para> + One of the main advantages of dynamic mapping is quick turnaround time for prototyping, + without the need for entity class implementation. However, you lose compile-time + type checking and will likely deal with many exceptions at runtime. As a result of + the Hibernate mapping, the database schema can easily be normalized and sound, + allowing to add a proper domain model implementation on top later on. + </para> + + <para> + Entity representation modes can also be set on a per <literal>Session</literal> + basis: + </para> + + <programlisting role="JAVA"><![CDATA[Session dynamicSession = pojoSession.getSession(EntityMode.MAP); + +// Create a customer +Map david = new HashMap(); +david.put("name", "David"); +dynamicSession.save("Customer", david); +... +dynamicSession.flush(); +dynamicSession.close() +... +// Continue on pojoSession +]]></programlisting> + + + <para> + Please note that the call to <literal>getSession()</literal> using an + <literal>EntityMode</literal> is on the <literal>Session</literal> API, not the + <literal>SessionFactory</literal>. That way, the new <literal>Session</literal> + shares the underlying JDBC connection, transaction, and other context + information. This means you do not have to call <literal>flush()</literal> + and <literal>close()</literal> on the secondary <literal>Session</literal>, and + also leave the transaction and connection handling to the primary unit of work. + </para> + + <para> + More information about the XML representation capabilities can be found + in <xref linkend="xml"/>. + </para> + + </section> + + <section id="persistent-classes-tuplizers" revision="1"> + <title>Tuplizers</title> + + <para> + <literal>org.hibernate.tuple.Tuplizer</literal>, and its sub-interfaces, are responsible + for managing a particular representation of a piece of data given that representation's + <literal>org.hibernate.EntityMode</literal>. If a given piece of data is thought of as + a data structure, then a tuplizer is the thing that knows how to create such a data structure + and how to extract values from and inject values into such a data structure. For example, + for the POJO entity mode, the corresponding tuplizer knows how create the POJO through its + constructor. It also knows how to access the POJO properties using the defined property accessors. + </para> + + <para> + There are two high-level types of Tuplizers, represented by the + <literal>org.hibernate.tuple.entity.EntityTuplizer</literal> and <literal>org.hibernate.tuple.component.ComponentTuplizer</literal> + interfaces. <literal>EntityTuplizer</literal>s are responsible for managing the above mentioned + contracts in regards to entities, while <literal>ComponentTuplizer</literal>s do the same for + components. + </para> + + <para> + Users can also plug in their own tuplizers. Perhaps you require that a <literal>java.util.Map</literal> + implementation other than <literal>java.util.HashMap</literal> be used while in the + dynamic-map entity-mode. Or perhaps you need to define a different proxy generation strategy + than the one used by default. Both would be achieved by defining a custom tuplizer + implementation. Tuplizer definitions are attached to the entity or component mapping they + are meant to manage. Going back to the example of our customer entity: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class entity-name="Customer"> + <!-- + Override the dynamic-map entity-mode + tuplizer for the customer entity + --> + <tuplizer entity-mode="dynamic-map" + class="CustomMapTuplizerImpl"/> + + <id name="id" type="long" column="ID"> + <generator class="sequence"/> + </id> + + <!-- other properties --> + ... + </class> +</hibernate-mapping> + + +public class CustomMapTuplizerImpl + extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer { + // override the buildInstantiator() method to plug in our custom map... + protected final Instantiator buildInstantiator( + org.hibernate.mapping.PersistentClass mappingInfo) { + return new CustomMapInstantiator( mappingInfo ); + } + + private static final class CustomMapInstantiator + extends org.hibernate.tuple.DynamicMapInstantitor { + // override the generateMap() method to return our custom map... + protected final Map generateMap() { + return new CustomMap(); + } + } +}]]></programlisting> + + + </section> + + + <section id="persistent-classes-entity-name-resolver" revision="0"> + <title>EntityNameResolvers</title> + + <para> + The <interfacename>org.hibernate.EntityNameResolver</interfacename> interface is a contract for resolving the + entity name of a given entity instance. The interface defines a single method <methodname>resolveEntityName</methodname> + which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and + would indicate that the resolver does not know how to resolve the entity name of the given entity instance). + Generally speaking, an <interfacename>org.hibernate.EntityNameResolver</interfacename> is going to be most + useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The + hibernate test suite has an example of this exact style of usage under the + <package>org.hibernate.test.dynamicentity.tuplizer2</package>. Here is some of the code from that package + for illustration. + </para> + + <programlisting role="JAVA"> +/** + * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as + * the domain model and simply store persistent state in an internal Map. This is an extremely + * trivial example meant only for illustration. + */ +public final class DataProxyHandler implements InvocationHandler { + private String entityName; + private HashMap data = new HashMap(); + + public DataProxyHandler(String entityName, Serializable id) { + this.entityName = entityName; + data.put( "Id", id ); + } + + public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { + String methodName = method.getName(); + if ( methodName.startsWith( "set" ) ) { + String propertyName = methodName.substring( 3 ); + data.put( propertyName, args[0] ); + } + else if ( methodName.startsWith( "get" ) ) { + String propertyName = methodName.substring( 3 ); + return data.get( propertyName ); + } + else if ( "toString".equals( methodName ) ) { + return entityName + "#" + data.get( "Id" ); + } + else if ( "hashCode".equals( methodName ) ) { + return new Integer( this.hashCode() ); + } + return null; + } + + public String getEntityName() { + return entityName; + } + + public HashMap getData() { + return data; + } +} + +/** + * + */ +public class ProxyHelper { + public static String extractEntityName(Object object) { + // Our custom java.lang.reflect.Proxy instances actually bundle + // their appropriate entity name, so we simply extract it from there + // if this represents one of our proxies; otherwise, we return null + if ( Proxy.isProxyClass( object.getClass() ) ) { + InvocationHandler handler = Proxy.getInvocationHandler( object ); + if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) { + DataProxyHandler myHandler = ( DataProxyHandler ) handler; + return myHandler.getEntityName(); + } + } + return null; + } + + // various other utility methods .... + +} + +/** + * The EntityNameResolver implementation. + * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be + * resolved. Since this particular impl can handle resolution for all of our entities we want to + * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever + * have one instance registered. Why? Well, when it comes time to resolve an entity name, + * Hibernate must iterate over all the registered resolvers. So keeping that number down + * helps that process be as speedy as possible. Hence the equals and hashCode impls + */ +public class MyEntityNameResolver implements EntityNameResolver { + public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver(); + + public String resolveEntityName(Object entity) { + return ProxyHelper.extractEntityName( entity ); + } + + public boolean equals(Object obj) { + return getClass().equals( obj.getClass() ); + } + + public int hashCode() { + return getClass().hashCode(); + } +} + +public class MyEntityTuplizer extends PojoEntityTuplizer { + public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) { + super( entityMetamodel, mappedEntity ); + } + + public EntityNameResolver[] getEntityNameResolvers() { + return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE }; + } + + public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) { + String entityName = ProxyHelper.extractEntityName( entityInstance ); + if ( entityName == null ) { + entityName = super.determineConcreteSubclassEntityName( entityInstance, factory ); + } + return entityName; + } + + ... +} + </programlisting> + + <para> + In order to register an <interfacename>org.hibernate.EntityNameResolver</interfacename> users must either: + <orderedlist> + <listitem> + <para> + Implement a custom <link linkend="persistent-classes-tuplizers">Tuplizer</link>, implementing + the <methodname>getEntityNameResolvers</methodname> method. + </para> + </listitem> + <listitem> + <para> + Register it with the <classname>org.hibernate.impl.SessionFactoryImpl</classname> (which is the + implementation class for <interfacename>org.hibernate.SessionFactory</interfacename>) using the + <methodname>registerEntityNameResolver</methodname> method. + </para> + </listitem> + </orderedlist> + </para> + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/portability.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/portability.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/portability.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,209 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Copyright (c) 2009, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="portability"> + <title>Database Portability Considerations</title> + + <section id="portability-basics"> + <title>Portability Basics</title> + + <para> + One of the selling points of Hibernate (and really Object/Relational Mapping as a whole) is + the notion of database portability. This could mean an internal IT user migrating from one + database vendor to another, or it could mean a framework or deployable application consuming + Hibernate to simultaneously target multiple database products by their users. Regardless of + the exact scenario, the basic idea is that you want Hibernate to help you run against any number + of databases without changes to your code, and ideally without any changes to the mapping metadata. + </para> + </section> + + <section id="portability-dialect"> + <title>Dialect</title> + + <para> + The first line of portability for Hibernate is the dialect, which is a specialization of the + <classname>org.hibernate.dialect.Dialect</classname> contract. A dialect encapsulates all + the differences in how Hibernate must communicate with a particular database to accomplish some + task like getting a sequence value or structuring a SELECT query. Hibernate bundles a wide range + of dialects for many of the most popular databases. If you find that your particular database is + not among them, it is not terribly difficult to write your own. + </para> + </section> + + <section id="portability-dialectresolver"> + <title>Dialect resolution</title> + + <para> + Originally, Hibernate would always require that users specify which dialect to use. In the case + of users looking to simultaneously target multiple databases with their build that was problematic. + Generally this required their users to configure the Hibernate dialect or defining their own method + of setting that value. + </para> + + <para> + Starting with version 3.2, Hibernate introduced the notion of automatically detecting the dialect + to use based on the <interfacename>java.sql.DatabaseMetaData</interfacename> obtained from a + <interfacename>java.sql.Connection</interfacename> to that database. This was much better, expect + that this resolution was limited to databases Hibernate know about ahead of time and was in no way + configurable or overrideable. + </para> + + <para> + Starting with version 3.3, Hibernate has a fare more powerful way to automatically determine + which dialect to should be used by relying on a series of delegates which implement the + <interfacename>org.hibernate.dialect.resolver.DialectResolver</interfacename> which defines only a + single method:<programlisting role="JAVA"><![CDATA[public Dialect resolveDialect(DatabaseMetaData metaData) throws JDBCConnectionException]]></programlisting>. + The basic contract here is that if the resolver 'understands' the given database metadata then + it returns the corresponding Dialect; if not it returns null and the process continues to the next + resolver. The signature also identifies <exceptionname>org.hibernate.exception.JDBCConnectionException</exceptionname> + as possibly being thrown. A JDBCConnectionException here is interpreted to imply a "non transient" + (aka non-recoverable) connection problem and is used to indicate an immediate stop to resolution + attempts. All other exceptions result in a warning and continuing on to the next resolver. + </para> + + <para> + The cool part about these resolvers is that users can also register their own custom resolvers + which will be processed ahead of the built-in Hibernate ones. This might be useful in a number of + different situations: it allows easy integration for auto-detection of dialects beyond those + shipped with HIbernate itself; it allows you to specify to use a custom dialect when a particular + database is recognized; etc. To register one or more resolvers, simply specify them (seperated by + commas, tabs or spaces) using the 'hibernate.dialect_resolvers' configuration setting (see the + <constant>DIALECT_RESOLVERS</constant> constant on + <classname>org.hibernate.cfg.Environment</classname>). + </para> + </section> + + <section id="portability-idgen"> + <title>Identifier generation</title> + + <para> + When considering portability between databases, another important decision is selecting the + identifier generation stratagy you want to use. Originally Hibernate provided the + <emphasis>native</emphasis> generator for this purpose, which was intended to select between + a <emphasis>sequence</emphasis>, <emphasis>identity</emphasis>, or <emphasis>table</emphasis> + strategy depending on the capability of the underlying database. However, an insidious implication + of this approach comes about when targtetting some databases which support <emphasis>identity</emphasis> + generation and some which do not. <emphasis>identity</emphasis> generation relies on the SQL + definition of an IDENTITY (or auto-increment) column to manage the identifier value; it is what is + known as a post-insert generation strategy becauase the insert must actually happen before we can + know the identifier value. Because Hibernate relies on this identifier value to uniquely reference + entities within a persistence context it must then issue the insert + immediately when the users requests the entitiy be associated with the session (like via + save() e.g.) regardless of current transactional semantics. + + <note> + <para> + Hibernate was changed slightly once the implication of this was better understood so that + the insert is delayed in cases where that is feasible. + </para> + </note> + + The underlying issue is that the actual semanctics of the application itself changes in these cases. + </para> + + <para> + Starting with version 3.2.3, Hibernate comes with a set of + <ulink url="http://in.relation.to/2082.lace">enhanced</ulink> identifier generators targetting + portability in a much different way. + <note> + <para> + There are specifically 2 bundled <emphasis>enhanced</emphasis>generators: + <itemizedlist> + <listitem> + <para> + <classname>org.hibernate.id.enhanced.SequenceStyleGenerator</classname> + </para> + </listitem> + <listitem> + <para> + <classname>org.hibernate.id.enhanced.TableGenerator</classname> + </para> + </listitem> + </itemizedlist> + </para> + </note> + The idea behind these generators is to port the actual semantics of the identifer value + generation to the different databases. For example, the + <classname>org.hibernate.id.enhanced.SequenceStyleGenerator</classname> mimics the behavior of + a sequence on databases which do not support sequences by using a table. + </para> + </section> + + <section id="portability-functions"> + <title>Database functions</title> + + <warning> + <para> + This is an area in Hibernate in need of improvement. In terms of portability concerns, + this function handling currently works pretty well from HQL; however, it is quite lacking + in all other aspects. + </para> + </warning> + + <para> + SQL functions can be referenced in many ways by users. However, not all databases + support the same set of functions. Hibernate, provides a means of mapping a + <emphasis>logical</emphasis> function name to a delegate which knows how to render + that particular function, perhaps even using a totally different physical function call. + <important> + <para> + Technically this function registration is handled through the + <classname>org.hibernate.dialect.function.SQLFunctionRegistry</classname> class + which is intended to allow users to provide custom function definitions without + having to provide a custom dialect. This specific behavior is not fully completed + as of yet. + </para> + <para> + It is sort of implemented such that users can programatically register functions + with the <classname>org.hibernate.cfg.Configuration</classname> and those functions + will be recognized for HQL. + </para> + </important> + </para> + </section> + + <section id="portability-types"> + <title>Type mappings</title> + + <para> + This section scheduled for completion at a later date... + </para> + + <!-- + todo : + <section id="portability-types-lobs"> + <title>BLOB/CLOB mappings</title> + </section> + + <section id="portability-types-bool"> + <title>Boolean mappings</title> + </section> + --> + </section> +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/preface.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/preface.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/preface.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,199 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Inc. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<preface id="preface"> + <title>Preface</title> + + <para> + Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. + Development costs are significantly higher due to a paradigm mismatch between how data is represented in + objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. + The term Object/Relational Mapping refers to the technique of mapping a data representation from an object model + to a relational data model with a SQL-based schema; + see <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping">... + for a discussion. + </para> + + <note> + <para> + While having a strong background in SQL is not required to use Hibernate, having a basic understanding of + the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single + best background is an understanding of data modeling principles. You might want to consider these resources + as a good starting point: + <itemizedlist> + <listitem> + <para> + <ulink url="http://www.agiledata.org/essays/dataModeling101.html">h... + </para> + </listitem> + <listitem> + <para> + <ulink url="http://en.wikipedia.org/wiki/Data_modeling">http://en.w... + </para> + </listitem> + </itemizedlist> + </para> + </note> + + <para> + Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to + SQL data types), but also provides data query and retrieval facilities. It can also significantly reduce + development time otherwise spent with manual data handling in SQL and JDBC. + </para> + + <para> + Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming + tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC. However, unlike + many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your + investment in relational technology and knowledge is as valid as always. + </para> + + <para> + Hibernate may not be the best solution for data-centric + applications that only use stored-procedures to implement the business logic in the + database, it is most useful with object-oriented domain models and business logic in + the Java-based middle-tier. However, Hibernate can certainly help you to remove or + encapsulate vendor-specific SQL code and will help with the common task of result set + translation from a tabular representation to a graph of objects. + </para> + + <para> + If you are new to Hibernate and Object/Relational Mapping or even Java, + please follow these steps: + </para> + + <orderedlist> + <listitem> + <para> + Read <xref linkend="tutorial"/> for a tutorial with step-by-step + instructions. The source code for the tutorial is included in the + distribution in the <literal>doc/reference/tutorial/</literal> + directory. + </para> + </listitem> + <listitem> + <para> + Read <xref linkend="architecture"/> to understand the environments where + Hibernate can be used. + </para> + </listitem> + <listitem> + <para> + View the <literal>eg/</literal> directory in the Hibernate + distribution. It contains a simple standalone application. Copy your + JDBC driver to the <literal>lib/</literal> directory and edit + <literal>etc/hibernate.properties</literal>, specifying correct values for + your database. From a command prompt in the distribution directory, + type <literal>ant eg</literal> (using Ant), or under Windows, type + <literal>build eg</literal>. + </para> + </listitem> + <listitem> + <para> + Use this reference documentation as your primary source of + information. Consider reading <biblioref linkend="biblio-JPwH"/> + if you need more help with application design, or if you prefer + a step-by-step tutorial. Also visit + <ulink url="http://caveatemptor.hibernate.org"/> and download + the example application from <biblioref linkend="biblio-JPwH"/>. + </para> + </listitem> + <listitem> + <para> + FAQs are answered on the Hibernate website. + </para> + </listitem> + <listitem> + <para> + Links to third party demos, examples, and tutorials are maintained + on the Hibernate website. + </para> + </listitem> + <listitem> + <para> + The Community Area on the Hibernate website is a good resource for + design patterns and various integration solutions (Tomcat, JBoss AS, + Struts, EJB, etc.). + </para> + </listitem> + </orderedlist> + + <para> + There are a number of ways to become involved in the Hibernate community, including + <itemizedlist> + <listitem> + <para> + Trying stuff out and reporting bugs. See + <ulink url="http://hibernate.org/issuetracker.html">http://hibernat... + details. + </para> + </listitem> + <listitem> + <para> + Trying your hand at fixing some bugs or implementing enhancements. Again, see + <ulink url="http://hibernate.org/issuetracker.html">http://hibernat... + details. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://hibernate.org/community.html">http://hibernate.o... list + a few ways to engage in the community. + <itemizedlist> + <listitem> + <para> + There are forums for users to ask questions and receive help from the community. + </para> + </listitem> + <listitem> + <para> + There are also <ulink url="http://en.wikipedia.org/wiki/Internet_Relay_Chat">IRC&l... + channels for both user and developer discussions. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + Helping improve or translate this documentation. Contact us on the developer mailing list + if you have interest. + </para> + </listitem> + <listitem> + <para> + Evangelizing Hibernate within your organization. + </para> + </listitem> + </itemizedlist> + </para> + +</preface> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_criteria.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_criteria.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_criteria.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,492 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="querycriteria"> + <title>Criteria Queries</title> + + <para> + Hibernate features an intuitive, extensible criteria query API. + </para> + + <section id="querycriteria-creating"> + <title>Creating a <literal>Criteria</literal> instance</title> + + <para> + The interface <literal>org.hibernate.Criteria</literal> represents a query against + a particular persistent class. The <literal>Session</literal> is a factory for + <literal>Criteria</literal> instances. + </para> + + <programlisting role="JAVA"><![CDATA[Criteria crit = sess.createCriteria(Cat.class); +crit.setMaxResults(50); +List cats = crit.list();]]></programlisting> + + </section> + + <section id="querycriteria-narrowing"> + <title>Narrowing the result set</title> + + <para> + An individual query criterion is an instance of the interface + <literal>org.hibernate.criterion.Criterion</literal>. The class + <literal>org.hibernate.criterion.Restrictions</literal> defines + factory methods for obtaining certain built-in + <literal>Criterion</literal> types. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .add( Restrictions.between("weight", minWeight, maxWeight) ) + .list();]]></programlisting> + + <para> + Restrictions can be grouped logically. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .add( Restrictions.or( + Restrictions.eq( "age", new Integer(0) ), + Restrictions.isNull("age") + ) ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) ) + .add( Restrictions.disjunction() + .add( Restrictions.isNull("age") ) + .add( Restrictions.eq("age", new Integer(0) ) ) + .add( Restrictions.eq("age", new Integer(1) ) ) + .add( Restrictions.eq("age", new Integer(2) ) ) + ) ) + .list();]]></programlisting> + + <para> + There are a range of built-in criterion types (<literal>Restrictions</literal> + subclasses). One of the most useful allows you to specify SQL directly. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.sqlRestriction("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) ) + .list();]]></programlisting> + + <para> + The <literal>{alias}</literal> placeholder with be replaced by the row alias + of the queried entity. + </para> + + <para> + You can also obtain a criterion from a + <literal>Property</literal> instance. You can create a <literal>Property</literal> + by calling <literal>Property.forName()</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[ +Property age = Property.forName("age"); +List cats = sess.createCriteria(Cat.class) + .add( Restrictions.disjunction() + .add( age.isNull() ) + .add( age.eq( new Integer(0) ) ) + .add( age.eq( new Integer(1) ) ) + .add( age.eq( new Integer(2) ) ) + ) ) + .add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) ) + .list();]]></programlisting> + + </section> + + <section id="querycriteria-ordering"> + <title>Ordering the results</title> + + <para> + You can order the results using <literal>org.hibernate.criterion.Order</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "F%") + .addOrder( Order.asc("name") ) + .addOrder( Order.desc("age") ) + .setMaxResults(50) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Property.forName("name").like("F%") ) + .addOrder( Property.forName("name").asc() ) + .addOrder( Property.forName("age").desc() ) + .setMaxResults(50) + .list();]]></programlisting> + + </section> + + <section id="querycriteria-associations" revision="2"> + <title>Associations</title> + + <para> + By navigating + associations using <literal>createCriteria()</literal> you can specify constraints upon related entities: + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "F%") ) + .createCriteria("kittens") + .add( Restrictions.like("name", "F%") ) + .list();]]></programlisting> + + <para> + The second <literal>createCriteria()</literal> returns a new + instance of <literal>Criteria</literal> that refers to the elements of + the <literal>kittens</literal> collection. + </para> + + <para> + There is also an alternate form that is useful in certain circumstances: + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .createAlias("kittens", "kt") + .createAlias("mate", "mt") + .add( Restrictions.eqProperty("kt.name", "mt.name") ) + .list();]]></programlisting> + + <para> + (<literal>createAlias()</literal> does not create a new instance of + <literal>Criteria</literal>.) + </para> + + <para> + The kittens collections held by the <literal>Cat</literal> instances + returned by the previous two queries are <emphasis>not</emphasis> pre-filtered + by the criteria. If you want to retrieve just the kittens that match the + criteria, you must use a <literal>ResultTransformer</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .createCriteria("kittens", "kt") + .add( Restrictions.eq("name", "F%") ) + .setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP) + .list(); +Iterator iter = cats.iterator(); +while ( iter.hasNext() ) { + Map map = (Map) iter.next(); + Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS); + Cat kitten = (Cat) map.get("kt"); +}]]></programlisting> + + <para> + Additionally you may manipulate the result set using a left outer join: + </para> + <programlisting><![CDATA[ + List cats = session.createCriteria( Cat.class ) + .createAlias("mate", "mt", Criteria.LEFT_JOIN, Restrictions.like("mt.name", "good%") ) + .addOrder(Order.asc("mt.age")) + .list(); + + ]]></programlisting> + + <para> + This will return all of the <literal>Cat</literal>s with a mate whose name starts with "good" + ordered by their mate's age, and all cats who do not have a mate. + This is useful when there is a need to order or limit in the database + prior to returning complex/large result sets, and removes many instances where + multiple queries would have to be performed and the results unioned + by java in memory. + </para> + <para> + Without this feature, first all of the cats without a mate would need to be loaded in one query. + </para> + <para> + A second query would need to retreive the cats with mates who's name started with "good" sorted by the mates age. + </para> + <para> + Thirdly, in memory; the lists would need to be joined manually. + </para> + </section> + + <section id="querycriteria-dynamicfetching" revision="1"> + <title>Dynamic association fetching</title> + + <para> + You can specify association fetching semantics at runtime using + <literal>setFetchMode()</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .setFetchMode("mate", FetchMode.EAGER) + .setFetchMode("kittens", FetchMode.EAGER) + .list();]]></programlisting> + + <para> + This query will fetch both <literal>mate</literal> and <literal>kittens</literal> + by outer join. See <xref linkend="performance-fetching"/> for more information. + </para> + + </section> + + <section id="querycriteria-examples"> + <title>Example queries</title> + + <para> + The class <literal>org.hibernate.criterion.Example</literal> allows + you to construct a query criterion from a given instance. + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = new Cat(); +cat.setSex('F'); +cat.setColor(Color.BLACK); +List results = session.createCriteria(Cat.class) + .add( Example.create(cat) ) + .list();]]></programlisting> + + <para> + Version properties, identifiers and associations are ignored. By default, + null valued properties are excluded. + </para> + + <para> + You can adjust how the <literal>Example</literal> is applied. + </para> + + <programlisting role="JAVA"><![CDATA[Example example = Example.create(cat) + .excludeZeroes() //exclude zero valued properties + .excludeProperty("color") //exclude the property named "color" + .ignoreCase() //perform case insensitive string comparisons + .enableLike(); //use like for string comparisons +List results = session.createCriteria(Cat.class) + .add(example) + .list();]]></programlisting> + + <para> + You can even use examples to place criteria upon associated objects. + </para> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .add( Example.create(cat) ) + .createCriteria("mate") + .add( Example.create( cat.getMate() ) ) + .list();]]></programlisting> + + </section> + + <section id="querycriteria-projection"> + <title>Projections, aggregation and grouping</title> + <para> + The class <literal>org.hibernate.criterion.Projections</literal> is a + factory for <literal>Projection</literal> instances. You can apply a + projection to a query by calling <literal>setProjection()</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.rowCount() ) + .add( Restrictions.eq("color", Color.BLACK) ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount() ) + .add( Projections.avg("weight") ) + .add( Projections.max("weight") ) + .add( Projections.groupProperty("color") ) + ) + .list();]]></programlisting> + + <para> + There is no explicit "group by" necessary in a criteria query. Certain + projection types are defined to be <emphasis>grouping projections</emphasis>, + which also appear in the SQL <literal>group by</literal> clause. + </para> + + <para> + An alias can be assigned to a projection so that the projected value + can be referred to in restrictions or orderings. Here are two different ways to + do this: + </para> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) ) + .addOrder( Order.asc("colr") ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.groupProperty("color").as("colr") ) + .addOrder( Order.asc("colr") ) + .list();]]></programlisting> + + <para> + The <literal>alias()</literal> and <literal>as()</literal> methods simply wrap a + projection instance in another, aliased, instance of <literal>Projection</literal>. + As a shortcut, you can assign an alias when you add the projection to a + projection list: + </para> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount(), "catCountByColor" ) + .add( Projections.avg("weight"), "avgWeight" ) + .add( Projections.max("weight"), "maxWeight" ) + .add( Projections.groupProperty("color"), "color" ) + ) + .addOrder( Order.desc("catCountByColor") ) + .addOrder( Order.desc("avgWeight") ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Domestic.class, "cat") + .createAlias("kittens", "kit") + .setProjection( Projections.projectionList() + .add( Projections.property("cat.name"), "catName" ) + .add( Projections.property("kit.name"), "kitName" ) + ) + .addOrder( Order.asc("catName") ) + .addOrder( Order.asc("kitName") ) + .list();]]></programlisting> + + <para> + You can also use <literal>Property.forName()</literal> to express projections: + </para> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Property.forName("name") ) + .add( Property.forName("color").eq(Color.BLACK) ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount().as("catCountByColor") ) + .add( Property.forName("weight").avg().as("avgWeight") ) + .add( Property.forName("weight").max().as("maxWeight") ) + .add( Property.forName("color").group().as("color" ) + ) + .addOrder( Order.desc("catCountByColor") ) + .addOrder( Order.desc("avgWeight") ) + .list();]]></programlisting> + + </section> + + <section id="querycriteria-detachedqueries"> + <title>Detached queries and subqueries</title> + <para> + The <literal>DetachedCriteria</literal> class allows you to create a query outside the scope + of a session and then execute it using an arbitrary <literal>Session</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[DetachedCriteria query = DetachedCriteria.forClass(Cat.class) + .add( Property.forName("sex").eq('F') ); + +Session session = ....; +Transaction txn = session.beginTransaction(); +List results = query.getExecutableCriteria(session).setMaxResults(100).list(); +txn.commit(); +session.close();]]></programlisting> + + <para> + A <literal>DetachedCriteria</literal> can also be used to express a subquery. Criterion + instances involving subqueries can be obtained via <literal>Subqueries</literal> or + <literal>Property</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class) + .setProjection( Property.forName("weight").avg() ); +session.createCriteria(Cat.class) + .add( Property.forName("weight").gt(avgWeight) ) + .list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[DetachedCriteria weights = DetachedCriteria.forClass(Cat.class) + .setProjection( Property.forName("weight") ); +session.createCriteria(Cat.class) + .add( Subqueries.geAll("weight", weights) ) + .list();]]></programlisting> + + <para> + Correlated subqueries are also possible: + </para> + + <programlisting role="JAVA"><![CDATA[DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2") + .setProjection( Property.forName("weight").avg() ) + .add( Property.forName("cat2.sex").eqProperty("cat.sex") ); +session.createCriteria(Cat.class, "cat") + .add( Property.forName("weight").gt(avgWeightForSex) ) + .list();]]></programlisting> + + </section> + + <!--TODO: ResultSetTransformer + aliasing. AliasToBeanTransformer allow returning arbitrary + user objects - similar to setResultClass in JDO2. General use of ResultTransformer + could also be explained. --> + + <section id="query-criteria-naturalid"> + <title>Queries by natural identifier</title> + + <para> + For most queries, including criteria queries, the query cache is not efficient + because query cache invalidation occurs too frequently. However, there is a special + kind of query where you can optimize the cache invalidation algorithm: lookups by a + constant natural key. In some applications, this kind of query occurs frequently. + The criteria API provides special provision for this use case. + </para> + + <para> + First, map the natural key of your entity using + <literal>&lt;natural-id&gt;</literal> and enable use of the second-level cache. + </para> + + <programlisting role="XML"><![CDATA[<class name="User"> + <cache usage="read-write"/> + <id name="id"> + <generator class="increment"/> + </id> + <natural-id> + <property name="name"/> + <property name="org"/> + </natural-id> + <property name="password"/> +</class>]]></programlisting> + + <para> + This functionality is not intended for use with entities with + <emphasis>mutable</emphasis> natural keys. + </para> + + <para> + Once you have enabled the Hibernate query cache, + the <literal>Restrictions.naturalId()</literal> allows you to make use of + the more efficient cache algorithm. + </para> + + <programlisting role="JAVA"><![CDATA[session.createCriteria(User.class) + .add( Restrictions.naturalId() + .set("name", "gavin") + .set("org", "hb") + ).setCacheable(true) + .uniqueResult();]]></programlisting> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_hql.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_hql.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_hql.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1273 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="queryhql" revision="1"> + <title>HQL: The Hibernate Query Language</title> + + <para> + Hibernate uses a powerful query language (HQL) that is similar in appearance to + SQL. Compared with SQL, however, HQL is fully object-oriented + and understands notions like inheritance, polymorphism and association. + </para> + + <section id="queryhql-casesensitivity"> + <title>Case Sensitivity</title> + + <para> + With the exception of names of Java classes and properties, queries are case-insensitive. + So <literal>SeLeCT</literal> is the same as + <literal>sELEct</literal> is the same as + <literal>SELECT</literal>, but + <literal>org.hibernate.eg.FOO</literal> is not + <literal>org.hibernate.eg.Foo</literal>, and + <literal>foo.barSet</literal> is not + <literal>foo.BARSET</literal>. + </para> + + <para> + This manual uses lowercase HQL keywords. Some users find queries with uppercase keywords + more readable, but this convention is unsuitable for queries embedded in Java code. + </para> + + </section> + + <section id="queryhql-from"> + <title>The from clause</title> + + <para> + The simplest possible Hibernate query is of the form: + </para> + + <programlisting><![CDATA[from eg.Cat]]></programlisting> + + <para> + This returns all instances of the class <literal>eg.Cat</literal>. + You do not usually need to qualify the class name, since <literal>auto-import</literal> + is the default. For example: + </para> + + <programlisting><![CDATA[from Cat]]></programlisting> + + <para> + + In order to refer to the <literal>Cat</literal> in other parts of the + query, you will need to assign an <emphasis>alias</emphasis>. For example: + </para> + + <programlisting><![CDATA[from Cat as cat]]></programlisting> + + <para> + This query assigns the alias <literal>cat</literal> to <literal>Cat</literal> + instances, so you can use that alias later in the query. The <literal>as</literal> + keyword is optional. You could also write: + </para> + + <programlisting><![CDATA[from Cat cat]]></programlisting> + + <para> + Multiple classes can appear, resulting in a cartesian product or "cross" join. + </para> + + <programlisting><![CDATA[from Formula, Parameter]]></programlisting> + <programlisting><![CDATA[from Formula as form, Parameter as param]]></programlisting> + + <para> + It is good practice to name query aliases using an initial lowercase as this is + consistent with Java naming standards for local variables + (e.g. <literal>domesticCat</literal>). + </para> + + </section> + + <section id="queryhql-joins" revision="2"> + <title>Associations and joins</title> + + <para> + You can also assign aliases to associated entities or to elements of a + collection of values using a <literal>join</literal>. For example: + </para> + + <programlisting><![CDATA[from Cat as cat + inner join cat.mate as mate + left outer join cat.kittens as kitten]]></programlisting> + + <programlisting><![CDATA[from Cat as cat left join cat.mate.kittens as kittens]]></programlisting> + + <programlisting><![CDATA[from Formula form full join form.parameter param]]></programlisting> + + <para> + The supported join types are borrowed from ANSI SQL: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>inner join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>left outer join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>right outer join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>full join</literal> (not usually useful) + </para> + </listitem> + </itemizedlist> + + <para> + The <literal>inner join</literal>, <literal>left outer join</literal> and + <literal>right outer join</literal> constructs may be abbreviated. + </para> + + <programlisting><![CDATA[from Cat as cat + join cat.mate as mate + left join cat.kittens as kitten]]></programlisting> + + <para> + You may supply extra join conditions using the HQL <literal>with</literal> + keyword. + </para> + + <programlisting><![CDATA[from Cat as cat + left join cat.kittens as kitten + with kitten.bodyWeight > 10.0]]></programlisting> + + <para> + A "fetch" join allows associations or collections of values to be + initialized along with their parent objects using a single select. This is particularly + useful in the case of a collection. It effectively overrides the outer join and + lazy declarations of the mapping file for associations and collections. See + <xref linkend="performance-fetching"/> for more information. + </para> + + <programlisting><![CDATA[from Cat as cat + inner join fetch cat.mate + left join fetch cat.kittens]]></programlisting> + + <para> + A fetch join does not usually need to assign an alias, because the associated objects + should not be used in the <literal>where</literal> clause (or any other clause). + The associated objects are also not returned directly in the query results. Instead, they may + be accessed via the parent object. The only reason you might need an alias is if you are + recursively join fetching a further collection: + </para> + + <programlisting><![CDATA[from Cat as cat + inner join fetch cat.mate + left join fetch cat.kittens child + left join fetch child.kittens]]></programlisting> + + <para> + The <literal>fetch</literal> construct cannot be used in queries called using + <literal>iterate()</literal> (though <literal>scroll()</literal> can be used). + <literal>Fetch</literal> should be used together with <literal>setMaxResults()</literal> or + <literal>setFirstResult()</literal>, as these operations are based on the result rows which + usually contain duplicates for eager collection fetching, hence, the number of rows is not what + you would expect. + <literal>Fetch</literal> should also not be used together with impromptu <literal>with</literal> condition. + It is possible to create a cartesian product by join fetching more than one collection in a + query, so take care in this case. Join fetching multiple collection roles can produce + unexpected results for bag mappings, so user discretion is advised when formulating queries in this + case. Finally, note that <literal>full join fetch</literal> and <literal>right join fetch</literal> + are not meaningful. + </para> + + <para> + If you are using property-level lazy fetching (with bytecode instrumentation), it is + possible to force Hibernate to fetch the lazy properties in the first query immediately + using <literal>fetch all properties</literal>. + </para> + + <programlisting><![CDATA[from Document fetch all properties order by name]]></programlisting> + <programlisting><![CDATA[from Document doc fetch all properties where lower(doc.name) like '%cats%']]></programlisting> + + </section> + + <section id="queryhql-joins-forms"> + <title>Forms of join syntax</title> + + <para> + HQL supports two forms of association joining: <literal>implicit</literal> and <literal>explicit</literal>. + </para> + + <para> + The queries shown in the previous section all use the <literal>explicit</literal> form, that is, where + the join keyword is explicitly used in the from clause. This is the recommended form. + </para> + + <para> + The <literal>implicit</literal> form does not use the join keyword. Instead, the + associations are "dereferenced" using dot-notation. <literal>implicit</literal> joins + can appear in any of the HQL clauses. <literal>implicit</literal> join result + in inner joins in the resulting SQL statement. + </para> + + <programlisting><![CDATA[from Cat as cat where cat.mate.name like '%s%']]></programlisting> + </section> + + <section id="queryhql-identifier-property"> + <title>Referring to identifier property</title> + + <para> + There are 2 ways to refer to an entity's identifier property: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + The special property (lowercase) <literal>id</literal> may be used to reference the identifier + property of an entity <emphasis>provided that the entity does not define a non-identifier property + named id</emphasis>. + </para> + </listitem> + <listitem> + <para> + If the entity defines a named identifier property, you can use that property name. + </para> + </listitem> + </itemizedlist> + + <para> + References to composite identifier properties follow the same naming rules. If the + entity has a non-identifier property named id, the composite identifier property can only + be referenced by its defined named. Otherwise, the special <literal>id</literal> property + can be used to reference the identifier property. + </para> + + <important> + <para> + Please note that, starting in version 3.2.2, this has changed significantly. In previous versions, + <literal>id</literal> <emphasis>always</emphasis> referred to the identifier property + regardless of its actual name. A ramification of that decision was that non-identifier + properties named <literal>id</literal> could never be referenced in Hibernate queries. + </para> + </important> + + </section> + + <section id="queryhql-select"> + <title>The select clause</title> + + <para> + The <literal>select</literal> clause picks which objects and properties to return in + the query result set. Consider the following: + </para> + + <programlisting><![CDATA[select mate +from Cat as cat + inner join cat.mate as mate]]></programlisting> + + <para> + The query will select <literal>mate</literal>s of other <literal>Cat</literal>s. + You can express this query more compactly as: + </para> + + <programlisting><![CDATA[select cat.mate from Cat cat]]></programlisting> + + <para> + Queries can return properties of any value type including properties of component type: + </para> + + <programlisting><![CDATA[select cat.name from DomesticCat cat +where cat.name like 'fri%']]></programlisting> + + <programlisting><![CDATA[select cust.name.firstName from Customer as cust]]></programlisting> + + <para> + Queries can return multiple objects and/or properties as an array of type + <literal>Object[]</literal>: + </para> + + <programlisting><![CDATA[select mother, offspr, mate.name +from DomesticCat as mother + inner join mother.mate as mate + left outer join mother.kittens as offspr]]></programlisting> + + <para> + Or as a <literal>List</literal>: + </para> + + <programlisting><![CDATA[select new list(mother, offspr, mate.name) +from DomesticCat as mother + inner join mother.mate as mate + left outer join mother.kittens as offspr]]></programlisting> + + <para> + Or - assuming that the class <literal>Family</literal> has an appropriate constructor - as an actual typesafe Java object: + </para> + + <programlisting><![CDATA[select new Family(mother, mate, offspr) +from DomesticCat as mother + join mother.mate as mate + left join mother.kittens as offspr]]></programlisting> + + + <para> + You can assign aliases to selected expressions using <literal>as</literal>: + </para> + + <programlisting><![CDATA[select max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n +from Cat cat]]></programlisting> + + <para> + This is most useful when used together with <literal>select new map</literal>: + </para> + + <programlisting><![CDATA[select new map( max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n ) +from Cat cat]]></programlisting> + + <para> + This query returns a <literal>Map</literal> from aliases to selected values. + </para> + + </section> + + <section id="queryhql-aggregation"> + <title>Aggregate functions</title> + + <para> + HQL queries can even return the results of aggregate functions on properties: + </para> + + <programlisting><![CDATA[select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat) +from Cat cat]]></programlisting> + +<!-- NO LONGER SUPPORTED + <para> + Collections can also appear inside aggregate functions in the <literal>select</literal> + clause. + </para> + + <programlisting><![CDATA[select cat, count( elements(cat.kittens) ) +from Cat cat group by cat]]></programlisting> +--> + + <para> + The supported aggregate functions are: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>avg(...), sum(...), min(...), max(...)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>count(*)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>count(...), count(distinct ...), count(all...)</literal> + </para> + </listitem> + </itemizedlist> + + <para> + You can use arithmetic operators, concatenation, and recognized SQL functions + in the select clause: + </para> + + <programlisting><![CDATA[select cat.weight + sum(kitten.weight) +from Cat cat + join cat.kittens kitten +group by cat.id, cat.weight]]></programlisting> + + <programlisting><![CDATA[select firstName||' '||initial||' '||upper(lastName) from Person]]></programlisting> + + <para> + The <literal>distinct</literal> and <literal>all</literal> keywords can be used and + have the same semantics as in SQL. + </para> + + <programlisting><![CDATA[select distinct cat.name from Cat cat + +select count(distinct cat.name), count(cat) from Cat cat]]></programlisting> + + </section> + + <section id="queryhql-polymorphism"> + <title>Polymorphic queries</title> + + <para> + A query like: + </para> + + <programlisting><![CDATA[from Cat as cat]]></programlisting> + + <para> + returns instances not only of <literal>Cat</literal>, but also of subclasses like + <literal>DomesticCat</literal>. Hibernate queries can name <emphasis>any</emphasis> Java + class or interface in the <literal>from</literal> clause. The query will return instances + of all persistent classes that extend that class or implement the interface. The following + query would return all persistent objects: + </para> + + <programlisting><![CDATA[from java.lang.Object o]]></programlisting> + + <para> + The interface <literal>Named</literal> might be implemented by various persistent + classes: + </para> + + <programlisting><![CDATA[from Named n, Named m where n.name = m.name]]></programlisting> + + <para> + These last two queries will require more than one SQL <literal>SELECT</literal>. This + means that the <literal>order by</literal> clause does not correctly order the whole result set. + It also means you cannot call these queries using <literal>Query.scroll()</literal>. + </para> + + </section> + + <section id="queryhql-where" revision="1"> + <title>The where clause</title> + + <para> + The <literal>where</literal> clause allows you to refine the list of instances returned. + If no alias exists, you can refer to properties by name: + </para> + + <programlisting><![CDATA[from Cat where name='Fritz']]></programlisting> + + <para> + If there is an alias, use a qualified property name: + </para> + + <programlisting><![CDATA[from Cat as cat where cat.name='Fritz']]></programlisting> + + <para> + This returns instances of <literal>Cat</literal> named 'Fritz'. + </para> + + <para> + The following query: + </para> + <programlisting><![CDATA[select foo +from Foo foo, Bar bar +where foo.startDate = bar.date]]></programlisting> + + <para> + returns all instances of <literal>Foo</literal> with an + instance of <literal>bar</literal> with a + <literal>date</literal> property equal to the + <literal>startDate</literal> property of the + <literal>Foo</literal>. Compound path expressions make the + <literal>where</literal> clause extremely powerful. Consider the following: + </para> + + <programlisting><![CDATA[from Cat cat where cat.mate.name is not null]]></programlisting> + + <para> + This query translates to an SQL query with a table (inner) join. For example: + + </para> + + <programlisting><![CDATA[from Foo foo +where foo.bar.baz.customer.address.city is not null]]></programlisting> + + <para> + would result in a query that would require four table joins in SQL. + </para> + + <para> + The <literal>=</literal> operator can be used to compare not only properties, but also + instances: + </para> + + <programlisting><![CDATA[from Cat cat, Cat rival where cat.mate = rival.mate]]></programlisting> + + <programlisting><![CDATA[select cat, mate +from Cat cat, Cat mate +where cat.mate = mate]]></programlisting> + + <para> + The special property (lowercase) <literal>id</literal> can be used to reference the + unique identifier of an object. See <xref linkend="queryhql-identifier-property"/> + for more information. + </para> + + <programlisting><![CDATA[from Cat as cat where cat.id = 123 + +from Cat as cat where cat.mate.id = 69]]></programlisting> + + <para> + The second query is efficient and does not require a table join. + </para> + + <para> + Properties of composite identifiers can also be used. Consider the following example where <literal>Person</literal> + has composite identifiers consisting of <literal>country</literal> and + <literal>medicareNumber</literal>: + </para> + + <programlisting><![CDATA[from bank.Person person +where person.id.country = 'AU' + and person.id.medicareNumber = 123456]]></programlisting> + + <programlisting><![CDATA[from bank.Account account +where account.owner.id.country = 'AU' + and account.owner.id.medicareNumber = 123456]]></programlisting> + + <para> + Once again, the second query does not require a table join. + </para> + + <para> + See <xref linkend="queryhql-identifier-property"/> + for more information regarding referencing identifier properties) + </para> + + <para> + The special property <literal>class</literal> accesses the discriminator value + of an instance in the case of polymorphic persistence. A Java class name embedded in the + where clause will be translated to its discriminator value. + </para> + + <programlisting><![CDATA[from Cat cat where cat.class = DomesticCat]]></programlisting> + + <para> + You can also use components or composite user types, or properties of said + component types. See <xref linkend="queryhql-components"/> for more information. + </para> + + <para> + An "any" type has the special properties <literal>id</literal> and <literal>class</literal> that allows you + to express a join in the following way (where <literal>AuditLog.item</literal> + is a property mapped with <literal>&lt;any&gt;</literal>): + </para> + + <programlisting><![CDATA[from AuditLog log, Payment payment +where log.item.class = 'Payment' and log.item.id = payment.id]]></programlisting> + + <para> + The <literal>log.item.class</literal> and <literal>payment.class</literal> + would refer to the values of completely different database columns in the above query. + </para> + + </section> + + <section id="queryhql-expressions"> + <title>Expressions</title> + + <para> + Expressions used in the <literal>where</literal> clause include the following: + + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + mathematical operators: <literal>+, -, *, /</literal> + </para> + </listitem> + <listitem> + <para> + binary comparison operators: <literal>=, &gt;=, &lt;=, &lt;&gt;, !=, like</literal> + </para> + </listitem> + <listitem> + <para> + logical operations <literal>and, or, not</literal> + </para> + </listitem> + <listitem> + <para> + Parentheses <literal>( )</literal> that indicates grouping + </para> + </listitem> + <listitem> + <para> + <literal>in</literal>, + <literal>not in</literal>, + <literal>between</literal>, + <literal>is null</literal>, + <literal>is not null</literal>, + <literal>is empty</literal>, + <literal>is not empty</literal>, + <literal>member of</literal> and + <literal>not member of</literal> + </para> + </listitem> + <listitem> + <para> + "Simple" case, <literal>case ... when ... then ... else ... end</literal>, and + "searched" case, <literal>case when ... then ... else ... end</literal> + </para> + </listitem> + <listitem> + <para> + string concatenation <literal>...||...</literal> or <literal>concat(...,...)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>current_date()</literal>, <literal>current_time()</literal>, and + <literal>current_timestamp()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>second(...)</literal>, <literal>minute(...)</literal>, + <literal>hour(...)</literal>, <literal>day(...)</literal>, + <literal>month(...)</literal>, and <literal>year(...)</literal> + </para> + </listitem> + <listitem> + <para> + Any function or operator defined by EJB-QL 3.0: <literal>substring(), trim(), + lower(), upper(), length(), locate(), abs(), sqrt(), bit_length(), mod()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>coalesce()</literal> and <literal>nullif()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>str()</literal> for converting numeric or temporal values to a + readable string + </para> + </listitem> + <listitem> + <para> + <literal>cast(... as ...)</literal>, where the second argument is the name of + a Hibernate type, and <literal>extract(... from ...)</literal> if ANSI + <literal>cast()</literal> and <literal>extract()</literal> is supported by + the underlying database + </para> + </listitem> + <listitem> + <para> + the HQL <literal>index()</literal> function, that applies to aliases of + a joined indexed collection + </para> + </listitem> + <listitem> + <para> + HQL functions that take collection-valued path expressions: <literal>size(), + minelement(), maxelement(), minindex(), maxindex()</literal>, along with the + special <literal>elements()</literal> and <literal>indices</literal> functions + that can be quantified using <literal>some, all, exists, any, in</literal>. + </para> + </listitem> + <listitem> + <para> + Any database-supported SQL scalar function like <literal>sign()</literal>, + <literal>trunc()</literal>, <literal>rtrim()</literal>, and <literal>sin()</literal> + </para> + </listitem> + <listitem> + <para> + JDBC-style positional parameters <literal>?</literal> + </para> + </listitem> + <listitem> + <para> + named parameters <literal>:name</literal>, <literal>:start_date</literal>, and <literal>:x1</literal> + </para> + </listitem> + <listitem> + <para> + SQL literals <literal>'foo'</literal>, <literal>69</literal>, <literal>6.66E+2</literal>, + <literal>'1970-01-01 10:00:01.0'</literal> + </para> + </listitem> + <listitem> + <para> + Java <literal>public static final</literal> constants <literal>eg.Color.TABBY</literal> + </para> + </listitem> + </itemizedlist> + + <para> + <literal>in</literal> and <literal>between</literal> can be used as follows: + </para> + + <programlisting><![CDATA[from DomesticCat cat where cat.name between 'A' and 'B']]></programlisting> + + <programlisting><![CDATA[from DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )]]></programlisting> + + <para> + The negated forms can be written as follows: + </para> + + <programlisting><![CDATA[from DomesticCat cat where cat.name not between 'A' and 'B']]></programlisting> + + <programlisting><![CDATA[from DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )]]></programlisting> + + <para> + Similarly, <literal>is null</literal> and <literal>is not null</literal> can be used to test + for null values. + </para> + + <para> + Booleans can be easily used in expressions by declaring HQL query substitutions in Hibernate + configuration: + </para> + + <programlisting><![CDATA[<property name="hibernate.query.substitutions">true 1, false 0</property>]]></programlisting> + + <para> + This will replace the keywords <literal>true</literal> and <literal>false</literal> with the + literals <literal>1</literal> and <literal>0</literal> in the translated SQL from this HQL: + </para> + + <programlisting><![CDATA[from Cat cat where cat.alive = true]]></programlisting> + + <para> + You can test the size of a collection with the special property <literal>size</literal> or + the special <literal>size()</literal> function. + </para> + + <programlisting><![CDATA[from Cat cat where cat.kittens.size > 0]]></programlisting> + + <programlisting><![CDATA[from Cat cat where size(cat.kittens) > 0]]></programlisting> + + <para> + For indexed collections, you can refer to the minimum and maximum indices using + <literal>minindex</literal> and <literal>maxindex</literal> functions. Similarly, + you can refer to the minimum and maximum elements of a collection of basic type + using the <literal>minelement</literal> and <literal>maxelement</literal> + functions. For example: + </para> + + <programlisting><![CDATA[from Calendar cal where maxelement(cal.holidays) > current_date]]></programlisting> + + <programlisting><![CDATA[from Order order where maxindex(order.items) > 100]]></programlisting> + + <programlisting><![CDATA[from Order order where minelement(order.items) > 10000]]></programlisting> + + <para> + The SQL functions <literal>any, some, all, exists, in</literal> are supported when passed the element + or index set of a collection (<literal>elements</literal> and <literal>indices</literal> functions) + or the result of a subquery (see below): + </para> + + <programlisting><![CDATA[select mother from Cat as mother, Cat as kit +where kit in elements(foo.kittens)]]></programlisting> + + <programlisting><![CDATA[select p from NameList list, Person p +where p.name = some elements(list.names)]]></programlisting> + + <programlisting><![CDATA[from Cat cat where exists elements(cat.kittens)]]></programlisting> + + <programlisting><![CDATA[from Player p where 3 > all elements(p.scores)]]></programlisting> + + <programlisting><![CDATA[from Show show where 'fizard' in indices(show.acts)]]></programlisting> + + <para> + Note that these constructs - <literal>size</literal>, <literal>elements</literal>, + <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, + <literal>minelement</literal>, <literal>maxelement</literal> - can only be used in + the where clause in Hibernate3. + </para> + + <para> + Elements of indexed collections (arrays, lists, and maps) can be referred to by + index in a where clause only: + </para> + + <programlisting><![CDATA[from Order order where order.items[0].id = 1234]]></programlisting> + + <programlisting><![CDATA[select person from Person person, Calendar calendar +where calendar.holidays['national day'] = person.birthDay + and person.nationality.calendar = calendar]]></programlisting> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ order.deliveredItemIndices[0] ] = item and order.id = 11]]></programlisting> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ maxindex(order.items) ] = item and order.id = 11]]></programlisting> + + <para> + The expression inside <literal>[]</literal> can even be an arithmetic expression: + </para> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ size(order.items) - 1 ] = item]]></programlisting> + + <para> + HQL also provides the built-in <literal>index()</literal> function for elements + of a one-to-many association or collection of values. + </para> + + <programlisting><![CDATA[select item, index(item) from Order order + join order.items item +where index(item) < 5]]></programlisting> + + <para> + Scalar SQL functions supported by the underlying database can be used: + </para> + + <programlisting><![CDATA[from DomesticCat cat where upper(cat.name) like 'FRI%']]></programlisting> + + <para> + Consider how much longer and less readable the + following query would be in SQL: + </para> + + <programlisting><![CDATA[select cust +from Product prod, + Store store + inner join store.customers cust +where prod.name = 'widget' + and store.location.name in ( 'Melbourne', 'Sydney' ) + and prod = all elements(cust.currentOrder.lineItems)]]></programlisting> + + <para> + <emphasis>Hint:</emphasis> something like + </para> + + <programlisting><![CDATA[SELECT cust.name, cust.address, cust.phone, cust.id, cust.current_order +FROM customers cust, + stores store, + locations loc, + store_customers sc, + product prod +WHERE prod.name = 'widget' + AND store.loc_id = loc.id + AND loc.name IN ( 'Melbourne', 'Sydney' ) + AND sc.store_id = store.id + AND sc.cust_id = cust.id + AND prod.id = ALL( + SELECT item.prod_id + FROM line_items item, orders o + WHERE item.order_id = o.id + AND cust.current_order = o.id + )]]></programlisting> + + </section> + + <section id="queryhql-ordering"> + <title>The order by clause</title> + + <para> + The list returned by a query can be ordered by any property of a returned class or components: + </para> + + <programlisting><![CDATA[from DomesticCat cat +order by cat.name asc, cat.weight desc, cat.birthdate]]></programlisting> + + <para> + The optional <literal>asc</literal> or <literal>desc</literal> indicate ascending or descending order + respectively. + </para> + </section> + + <section id="queryhql-grouping" revision="1"> + <title>The group by clause</title> + + <para> + A query that returns aggregate values can be grouped by any property of a returned class or components: + </para> + + <programlisting><![CDATA[select cat.color, sum(cat.weight), count(cat) +from Cat cat +group by cat.color]]></programlisting> + + <programlisting><![CDATA[select foo.id, avg(name), max(name) +from Foo foo join foo.names name +group by foo.id]]></programlisting> + + <para> + A <literal>having</literal> clause is also allowed. + </para> + + <programlisting><![CDATA[select cat.color, sum(cat.weight), count(cat) +from Cat cat +group by cat.color +having cat.color in (eg.Color.TABBY, eg.Color.BLACK)]]></programlisting> + + <para> + SQL functions and aggregate functions are allowed in the <literal>having</literal> + and <literal>order by</literal> clauses if they are supported by the underlying database + (i.e., not in MySQL). + </para> + + <programlisting><![CDATA[select cat +from Cat cat + join cat.kittens kitten +group by cat.id, cat.name, cat.other, cat.properties +having avg(kitten.weight) > 100 +order by count(kitten) asc, sum(kitten.weight) desc]]></programlisting> + + <para> + Neither the <literal>group by</literal> clause nor the + <literal>order by</literal> clause can contain arithmetic expressions. + Hibernate also does not currently expand a grouped entity, + so you cannot write <literal>group by cat</literal> if all properties + of <literal>cat</literal> are non-aggregated. You have to list all + non-aggregated properties explicitly. + </para> + + </section> + + <section id="queryhql-subqueries" revision="3"> + <title>Subqueries</title> + + <para> + For databases that support subselects, Hibernate supports subqueries within queries. A subquery must + be surrounded by parentheses (often by an SQL aggregate function call). Even correlated subqueries + (subqueries that refer to an alias in the outer query) are allowed. + </para> + + <programlisting><![CDATA[from Cat as fatcat +where fatcat.weight > ( + select avg(cat.weight) from DomesticCat cat +)]]></programlisting> + + <programlisting><![CDATA[from DomesticCat as cat +where cat.name = some ( + select name.nickName from Name as name +)]]></programlisting> + + <programlisting><![CDATA[from Cat as cat +where not exists ( + from Cat as mate where mate.mate = cat +)]]></programlisting> + + <programlisting><![CDATA[from DomesticCat as cat +where cat.name not in ( + select name.nickName from Name as name +)]]></programlisting> + + <programlisting><![CDATA[select cat.id, (select max(kit.weight) from cat.kitten kit) +from Cat as cat]]></programlisting> + + <para> + Note that HQL subqueries can occur only in the select or where clauses. + </para> + + <para> + Note that subqueries can also utilize <literal>row value constructor</literal> syntax. See + <xref linkend="queryhql-tuple"/> for more information. + </para> + + </section> + + <section id="queryhql-examples"> + <title>HQL examples</title> + + <para> + Hibernate queries can be quite powerful and complex. In fact, the power of the query language + is one of Hibernate's main strengths. The following example queries are similar to queries + that have been used on recent projects. Please note that most queries you will write will be much simpler than the following examples. + </para> + + <para> + The following query returns the order id, number of items, the given minimum total value and the total value of the order for all + unpaid orders for a particular customer. The results are ordered by + total value. In determining the prices, it uses the current catalog. The resulting SQL query, + against the <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</literal>, + <literal>CATALOG</literal> and <literal>PRICE</literal> tables has four inner joins and an + (uncorrelated) subselect. + </para> + + <programlisting><![CDATA[select order.id, sum(price.amount), count(item) +from Order as order + join order.lineItems as item + join item.product as product, + Catalog as catalog + join catalog.prices as price +where order.paid = false + and order.customer = :customer + and price.product = product + and catalog.effectiveDate < sysdate + and catalog.effectiveDate >= all ( + select cat.effectiveDate + from Catalog as cat + where cat.effectiveDate < sysdate + ) +group by order +having sum(price.amount) > :minAmount +order by sum(price.amount) desc]]></programlisting> + + <para> + What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was + really more like this: + </para> + + <programlisting><![CDATA[select order.id, sum(price.amount), count(item) +from Order as order + join order.lineItems as item + join item.product as product, + Catalog as catalog + join catalog.prices as price +where order.paid = false + and order.customer = :customer + and price.product = product + and catalog = :currentCatalog +group by order +having sum(price.amount) > :minAmount +order by sum(price.amount) desc]]></programlisting> + + <para> + The next query counts the number of payments in each status, excluding all payments in the + <literal>AWAITING_APPROVAL</literal> status where the most recent status change was made by the + current user. It translates to an SQL query with two inner joins and a correlated subselect + against the <literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal> and + <literal>PAYMENT_STATUS_CHANGE</literal> tables. + </para> + + <programlisting><![CDATA[select count(payment), status.name +from Payment as payment + join payment.currentStatus as status + join payment.statusChanges as statusChange +where payment.status.name <> PaymentStatus.AWAITING_APPROVAL + or ( + statusChange.timeStamp = ( + select max(change.timeStamp) + from PaymentStatusChange change + where change.payment = payment + ) + and statusChange.user <> :currentUser + ) +group by status.name, status.sortOrder +order by status.sortOrder]]></programlisting> + + <para> + If the <literal>statusChanges</literal> collection was mapped as a list, instead of a set, + the query would have been much simpler to write. + </para> + + <programlisting><![CDATA[select count(payment), status.name +from Payment as payment + join payment.currentStatus as status +where payment.status.name <> PaymentStatus.AWAITING_APPROVAL + or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser +group by status.name, status.sortOrder +order by status.sortOrder]]></programlisting> + + <para> + The next query uses the MS SQL Server <literal>isNull()</literal> function to return all + the accounts and unpaid payments for the organization to which the current user belongs. + It translates to an SQL query with three inner joins, an outer join and a subselect against + the <literal>ACCOUNT</literal>, <literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal>, + <literal>ACCOUNT_TYPE</literal>, <literal>ORGANIZATION</literal> and + <literal>ORG_USER</literal> tables. + </para> + + <programlisting><![CDATA[select account, payment +from Account as account + left outer join account.payments as payment +where :currentUser in elements(account.holder.users) + and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID) +order by account.type.sortOrder, account.accountNumber, payment.dueDate]]></programlisting> + + <para> + For some databases, we would need to do away with the (correlated) subselect. + </para> + + <programlisting><![CDATA[select account, payment +from Account as account + join account.holder.users as user + left outer join account.payments as payment +where :currentUser = user + and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID) +order by account.type.sortOrder, account.accountNumber, payment.dueDate]]></programlisting> + + </section> + + <section id="queryhql-bulk" revision="2"> + <title>Bulk update and delete</title> + + <para> + HQL now supports <literal>update</literal>, <literal>delete</literal> and + <literal>insert ... select ...</literal> statements. + See <xref linkend="batch-direct"/> for more information. + </para> + </section> + + <section id="queryhql-tipstricks"> + <title>Tips &amp; Tricks</title> + + <para> + You can count the number of query results without returning them: + </para> + + <programlisting role="JAVA"><![CDATA[( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue()]]></programlisting> + + <para> + To order a result by the size of a collection, use the following query: + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User as usr + left join usr.messages as msg +group by usr.id, usr.name +order by count(msg)]]></programlisting> + + <para> + If your database supports subselects, you can place a condition upon selection + size in the where clause of your query: + </para> + + <programlisting><![CDATA[from User usr where size(usr.messages) >= 1]]></programlisting> + + <para> + If your database does not support subselects, use the following query: + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User usr + join usr.messages msg +group by usr.id, usr.name +having count(msg) >= 1]]></programlisting> + + + <para> + As this solution cannot return a <literal>User</literal> with zero messages + because of the inner join, the following form is also useful: + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User as usr + left join usr.messages as msg +group by usr.id, usr.name +having count(msg) = 0]]></programlisting> + + <para> + Properties of a JavaBean can be bound to named query parameters: + </para> + + <programlisting role="JAVA"><![CDATA[Query q = s.createQuery("from foo Foo as foo where foo.name=:name and foo.size=:size"); +q.setProperties(fooBean); // fooBean has getName() and getSize() +List foos = q.list();]]></programlisting> + + <para> + Collections are pageable by using the <literal>Query</literal> interface with a filter: + </para> + + <programlisting role="JAVA"><![CDATA[Query q = s.createFilter( collection, "" ); // the trivial filter +q.setMaxResults(PAGE_SIZE); +q.setFirstResult(PAGE_SIZE * pageNumber); +List page = q.list();]]></programlisting> + + <para> + Collection elements can be ordered or grouped using a query filter: + </para> + + <programlisting role="JAVA"><![CDATA[Collection orderedCollection = s.filter( collection, "order by this.amount" ); +Collection counts = s.filter( collection, "select this.type, count(this) group by this.type" );]]></programlisting> + + <para> + You can find the size of a collection without initializing it: + </para> + + <programlisting role="JAVA"><![CDATA[( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue();]]></programlisting> + + </section> + + <section id="queryhql-components"> + <title>Components</title> + + <para> + Components can be used similarly to the simple value types that are used in HQL + queries. They can appear in the <literal>select</literal> clause as follows: + </para> + + <programlisting><![CDATA[select p.name from Person p]]></programlisting> + <programlisting><![CDATA[select p.name.first from Person p]]></programlisting> + + <para> + where the Person's name property is a component. Components can also be used + in the <literal>where</literal> clause: + </para> + + <programlisting><![CDATA[from Person p where p.name = :name]]></programlisting> + <programlisting><![CDATA[from Person p where p.name.first = :firstName]]></programlisting> + + <para> + Components can also be used in the <literal>order by</literal> clause: + </para> + + <programlisting><![CDATA[from Person p order by p.name]]></programlisting> + <programlisting><![CDATA[from Person p order by p.name.first]]></programlisting> + + <para> + Another common use of components is in <link linkend="queryhql-tuple">row value constructors</link>. + </para> + </section> + + <section id="queryhql-tuple"> + <title>Row value constructor syntax</title> + + <para> + HQL supports the use of ANSI SQL <literal>row value constructor</literal> syntax, sometimes + referred to AS <literal>tuple</literal> syntax, even though the underlying database may not support + that notion. Here, we are generally referring to multi-valued comparisons, typically associated + with components. Consider an entity Person which defines a name component: + </para> + + <programlisting><![CDATA[from Person p where p.name.first='John' and p.name.last='Jingleheimer-Schmidt']]></programlisting> + + <para> + That is valid syntax although it is a little verbose. You can make this more concise by using + <literal>row value constructor</literal> syntax: + </para> + + <programlisting><![CDATA[from Person p where p.name=('John', 'Jingleheimer-Schmidt')]]></programlisting> + + <para> + It can also be useful to specify this in the <literal>select</literal> clause: + </para> + + <programlisting><![CDATA[select p.name from Person p]]></programlisting> + + <para> + Using <literal>row value constructor</literal> syntax can also be beneficial + when using subqueries that need to compare against multiple values: + </para> + + <programlisting><![CDATA[from Cat as cat +where not ( cat.name, cat.color ) in ( + select cat.name, cat.color from DomesticCat cat +)]]></programlisting> + + <para> + One thing to consider when deciding if you want to use this syntax, is that the query will + be dependent upon the ordering of the component sub-properties in the metadata. + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_sql.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_sql.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/query_sql.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,800 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="querysql" revision="2"> + <title>Native SQL</title> + + <para>You can also express queries in the native SQL dialect of your + database. This is useful if you want to utilize database-specific features + such as query hints or the <literal>CONNECT</literal> keyword in Oracle. It + also provides a clean migration path from a direct SQL/JDBC based + application to Hibernate.</para> + + <para>Hibernate3 allows you to specify handwritten SQL, including stored + procedures, for all create, update, delete, and load operations.</para> + + <section id="querysql-creating" revision="4"> + <title>Using a <literal>SQLQuery</literal></title> + + <para>Execution of native SQL queries is controlled via the + <literal>SQLQuery</literal> interface, which is obtained by calling + <literal>Session.createSQLQuery()</literal>. The following sections describe how + to use this API for querying.</para> + + <section> + <title>Scalar queries</title> + + <para>The most basic SQL query is to get a list of scalars + (values).</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").list(); +sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").list(); +]]></programlisting> + + <para>These will return a List of Object arrays (Object[]) with + scalar values for each column in the CATS table. Hibernate will use + ResultSetMetadata to deduce the actual order and types of the returned + scalar values.</para> + + <para>To avoid the overhead of using + <literal>ResultSetMetadata</literal>, or simply to be more explicit in + what is returned, one can use <literal>addScalar()</literal>:</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT * FROM CATS") + .addScalar("ID", Hibernate.LONG) + .addScalar("NAME", Hibernate.STRING) + .addScalar("BIRTHDATE", Hibernate.DATE) +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>the columns and types to return</para> + </listitem> + </itemizedlist> + + <para>This will return Object arrays, but now it will not use + <literal>ResultSetMetadata</literal> but will instead explicitly get the + ID, NAME and BIRTHDATE column as respectively a Long, String and a Short + from the underlying resultset. This also means that only these three + columns will be returned, even though the query is using + <literal>*</literal> and could return more than the three listed + columns.</para> + + <para>It is possible to leave out the type information for all or some + of the scalars.</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT * FROM CATS") + .addScalar("ID", Hibernate.LONG) + .addScalar("NAME") + .addScalar("BIRTHDATE") +]]></programlisting> + + <para>This is essentially the same query as before, but now + <literal>ResultSetMetaData</literal> is used to determine the type of NAME + and BIRTHDATE, where as the type of ID is explicitly specified.</para> + + <para>How the java.sql.Types returned from ResultSetMetaData is mapped + to Hibernate types is controlled by the Dialect. If a specific type is + not mapped, or does not result in the expected type, it is possible to + customize it via calls to <literal>registerHibernateType</literal> in + the Dialect.</para> + </section> + + <section> + <title>Entity queries</title> + + <para>The above queries were all about returning scalar values, + basically returning the "raw" values from the resultset. The following + shows how to get entity objects from a native sql query via + <literal>addEntity()</literal>.</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").addEntity(Cat.class); +sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").addEntity(Cat.class); +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>the entity returned by the query</para> + </listitem> + </itemizedlist> + + <para>Assuming that Cat is mapped as a class with the columns ID, NAME + and BIRTHDATE the above queries will both return a List where each + element is a Cat entity.</para> + + <para>If the entity is mapped with a <literal>many-to-one</literal> to + another entity it is required to also return this when performing the + native query, otherwise a database specific "column not found" error + will occur. The additional columns will automatically be returned when + using the * notation, but we prefer to be explicit as in the following + example for a <literal>many-to-one</literal> to a + <literal>Dog</literal>:</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, DOG_ID FROM CATS").addEntity(Cat.class); +]]></programlisting> + + <para>This will allow cat.getDog() to function properly.</para> + </section> + + <section> + <title>Handling associations and collections</title> + + <para>It is possible to eagerly join in the <literal>Dog</literal> to + avoid the possible extra roundtrip for initializing the proxy. This is + done via the <literal>addJoin()</literal> method, which allows you to + join in an association or collection.</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT c.ID, NAME, BIRTHDATE, DOG_ID, D_ID, D_NAME FROM CATS c, DOGS d WHERE c.DOG_ID = d.D_ID") + .addEntity("cat", Cat.class) + .addJoin("cat.dog"); +]]></programlisting> + + <para>In this example, the returned <literal>Cat</literal>'s will have + their <literal>dog</literal> property fully initialized without any + extra roundtrip to the database. Notice that you added an alias name + ("cat") to be able to specify the target property path of the join. It + is possible to do the same eager joining for collections, e.g. if the + <literal>Cat</literal> had a one-to-many to <literal>Dog</literal> + instead.</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, D_ID, D_NAME, CAT_ID FROM CATS c, DOGS d WHERE c.ID = d.CAT_ID") + .addEntity("cat", Cat.class) + .addJoin("cat.dogs"); +]]></programlisting> + + <para> + At this stage you are reaching the limits of what is possible with native queries, without starting to + enhance the sql queries to make them usable in Hibernate. Problems can arise when returning + multiple entities of the same type or when the default alias/column names are not enough. + </para> + </section> + + <section> + <title>Returning multiple entities</title> + + <para>Until now, the result set column names are assumed to be the same + as the column names specified in the mapping document. This can be + problematic for SQL queries that join multiple tables, since the same + column names can appear in more than one table.</para> + + <para>Column alias injection is needed in the following query (which + most likely will fail):</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT c.*, m.* FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID") + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class) +]]></programlisting> + + + + <para> + The query was intended to return two Cat instances per + row: a cat and its mother. The query will, however, fail because there is a conflict of + names; the instances are mapped to the same column names. Also, on some + databases the returned column aliases will most likely be on the form + "c.ID", "c.NAME", etc. which are not equal to the columns specified in + the mappings ("ID" and "NAME"). + </para> + + <para>The following form is not vulnerable to column name + duplication:</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT {cat.*}, {mother.*} FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID") + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class) +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string, with placeholders for Hibernate to + inject column aliases</para> + </listitem> + + <listitem> + <para>the entities returned by the query</para> + </listitem> + </itemizedlist> + + <para>The {cat.*} and {mother.*} notation used above is a shorthand for + "all properties". Alternatively, you can list the columns explicitly, but + even in this case Hibernate injects the SQL column aliases for + each property. The placeholder for a column alias is just the property + name qualified by the table alias. In the following example, you retrieve + Cats and their mothers from a different table (cat_log) to the one + declared in the mapping metadata. You can even use the + property aliases in the where clause.</para> + + <programlisting role="JAVA"><![CDATA[String sql = "SELECT ID as {c.id}, NAME as {c.name}, " + + "BIRTHDATE as {c.birthDate}, MOTHER_ID as {c.mother}, {mother.*} " + + "FROM CAT_LOG c, CAT_LOG m WHERE {c.mother} = c.ID"; + +List loggedCats = sess.createSQLQuery(sql) + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class).list() +]]></programlisting> + + <section id="querysql-aliasreferences" revision="2"> + <title>Alias and property references</title> + + <para>In most cases the above alias injection is needed. For + queries relating to more complex mappings, like composite properties, + inheritance discriminators, collections etc., you can use specific + aliases that allow Hibernate to inject the proper aliases.</para> + + <para>The following table shows the different ways you can use + the alias injection. Please note that the alias names in the result are simply examples; + each alias will have a unique and probably different name when + used.</para> + + <table frame="topbot" id="aliasinjection-summary"> + <title>Alias injection names</title> + + <tgroup cols="3"> + <colspec colwidth="1*" /> + + <colspec colwidth="1*" /> + + <colspec colwidth="2.5*" /> + + <thead> + <row> + <entry>Description</entry> + + <entry>Syntax</entry> + + <entry>Example</entry> + </row> + </thead> + + <tbody> + <row> + <entry>A simple property</entry> + + <entry><literal>{[aliasname].[propertyname]</literal></entry> + + <entry><literal>A_NAME as {item.name}</literal></entry> + </row> + + <row> + <entry>A composite property</entry> + + <entry><literal>{[aliasname].[componentname].[propertyname]}</literal></entry> + + <entry><literal>CURRENCY as {item.amount.currency}, VALUE as + {item.amount.value}</literal></entry> + </row> + + <row> + <entry>Discriminator of an entity</entry> + + <entry><literal>{[aliasname].class}</literal></entry> + + <entry><literal>DISC as {item.class}</literal></entry> + </row> + + <row> + <entry>All properties of an entity</entry> + + <entry><literal>{[aliasname].*}</literal></entry> + + <entry><literal>{item.*}</literal></entry> + </row> + + <row> + <entry>A collection key</entry> + + <entry><literal>{[aliasname].key}</literal></entry> + + <entry><literal>ORGID as {coll.key}</literal></entry> + </row> + + <row> + <entry>The id of an collection</entry> + + <entry><literal>{[aliasname].id}</literal></entry> + + <entry><literal>EMPID as {coll.id}</literal></entry> + </row> + + <row> + <entry>The element of an collection</entry> + + <entry><literal>{[aliasname].element}</literal></entry> + + <entry><literal>XID as {coll.element}</literal></entry> + </row> + + <row> + <entry>property of the element in the collection</entry> + + <entry><literal>{[aliasname].element.[propertyname]}</literal></entry> + + <entry><literal>NAME as {coll.element.name}</literal></entry> + </row> + + <row> + <entry>All properties of the element in the collection</entry> + + <entry><literal>{[aliasname].element.*}</literal></entry> + + <entry><literal>{coll.element.*}</literal></entry> + </row> + + <row> + <entry>All properties of the collection</entry> + + <entry><literal>{[aliasname].*}</literal></entry> + + <entry><literal>{coll.*}</literal></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + + <section> + <title>Returning non-managed entities</title> + + <para>It is possible to apply a ResultTransformer to native SQL queries, allowing it to return non-managed entities.</para> + + <programlisting role="JAVA"><![CDATA[sess.createSQLQuery("SELECT NAME, BIRTHDATE FROM CATS") + .setResultTransformer(Transformers.aliasToBean(CatDTO.class))]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>a result transformer</para> + </listitem> + </itemizedlist> + + <para> + The above query will return a list of <literal>CatDTO</literal> which has been instantiated and injected the values of NAME and BIRTHNAME into its corresponding + properties or fields. + </para> + </section> + + <section> + <title>Handling inheritance</title> + + <para>Native SQL queries which query for entities that are mapped as part + of an inheritance must include all properties for the baseclass and all + its subclasses.</para> + </section> + + <section> + <title>Parameters</title> + + <para>Native SQL queries support positional as well as named + parameters:</para> + + <programlisting role="JAVA"><![CDATA[Query query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like ?").addEntity(Cat.class); +List pusList = query.setString(0, "Pus%").list(); + +query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like :name").addEntity(Cat.class); +List pusList = query.setString("name", "Pus%").list(); ]]></programlisting> + </section> + + + + </section> + + <section id="querysql-namedqueries" revision="3"> + <title>Named SQL queries</title> + + <para>Named SQL queries can be defined in the mapping document and called + in exactly the same way as a named HQL query. In this case, you do + <emphasis>not</emphasis> need to call + <literal>addEntity()</literal>.</para> + + <programlisting role="XML"><![CDATA[<sql-query name="persons"> + <return alias="person" class="eg.Person"/> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex} + FROM PERSON person + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List people = sess.getNamedQuery("persons") + .setString("namePattern", namePattern) + .setMaxResults(50) + .list();]]></programlisting> + + <para>The <literal>&lt;return-join&gt;</literal> element is use to join associations and + the <literal>&lt;load-collection&gt;</literal> element is used to define queries which initialize collections, + </para> + + <programlisting role="XML"><![CDATA[<sql-query name="personsWith"> + <return alias="person" class="eg.Person"/> + <return-join alias="address" property="person.mailingAddress"/> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <para>A named SQL query may return a scalar value. You must declare the + column alias and Hibernate type using the + <literal>&lt;return-scalar&gt;</literal> element:</para> + + <programlisting role="XML"><![CDATA[<sql-query name="mySqlQuery"> + <return-scalar column="name" type="string"/> + <return-scalar column="age" type="long"/> + SELECT p.NAME AS name, + p.AGE AS age, + FROM PERSON p WHERE p.NAME LIKE 'Hiber%' +</sql-query>]]></programlisting> + + <para>You can externalize the resultset mapping information in a + <literal>&lt;resultset&gt;</literal> element which will allow you to either reuse them across + several named queries or through the + <literal>setResultSetMapping()</literal> API.</para> + + <programlisting role="XML"><![CDATA[<resultset name="personAddress"> + <return alias="person" class="eg.Person"/> + <return-join alias="address" property="person.mailingAddress"/> +</resultset> + +<sql-query name="personsWith" resultset-ref="personAddress"> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <para>You can, alternatively, use the resultset mapping information in your + hbm files directly in java code.</para> + + <programlisting role="JAVA"><![CDATA[List cats = sess.createSQLQuery( + "select {cat.*}, {kitten.*} from cats cat, cats kitten where kitten.mother = cat.id" + ) + .setResultSetMapping("catAndKitten") + .list();]]></programlisting> + + <section id="propertyresults"> + <title>Using return-property to explicitly specify column/alias + names</title> + + <para>You can explicitly + tell Hibernate what column aliases to use with <literal>&lt;return-property&gt;</literal>, instead of using the + <literal>{}</literal>-syntax to let Hibernate inject its own + aliases.For example:</para> + + <programlisting role="XML"><![CDATA[<sql-query name="mySqlQuery"> + <return alias="person" class="eg.Person"> + <return-property name="name" column="myName"/> + <return-property name="age" column="myAge"/> + <return-property name="sex" column="mySex"/> + </return> + SELECT person.NAME AS myName, + person.AGE AS myAge, + person.SEX AS mySex, + FROM PERSON person WHERE person.NAME LIKE :name +</sql-query> +]]></programlisting> + + <para><literal>&lt;return-property&gt;</literal> also works with + multiple columns. This solves a limitation with the + <literal>{}</literal>-syntax which cannot allow fine grained control of + multi-column properties.</para> + + <programlisting role="XML"><![CDATA[<sql-query name="organizationCurrentEmployments"> + <return alias="emp" class="Employment"> + <return-property name="salary"> + <return-column name="VALUE"/> + <return-column name="CURRENCY"/> + </return-property> + <return-property name="endDate" column="myEndDate"/> + </return> + SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, + STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, + REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY + FROM EMPLOYMENT + WHERE EMPLOYER = :id AND ENDDATE IS NULL + ORDER BY STARTDATE ASC +</sql-query>]]></programlisting> + + <para>In this example + <literal>&lt;return-property&gt;</literal> was used in combination with the + <literal>{}</literal>-syntax for injection. This allows users to choose how + they want to refer column and properties.</para> + + <para>If your mapping has a discriminator you must use + <literal>&lt;return-discriminator&gt;</literal> to specify the + discriminator column.</para> + </section> + + <section id="sp_query" revision="1"> + <title>Using stored procedures for querying</title> + + <para>Hibernate3 provides support for queries via stored procedures + and functions. Most of the following documentation is equivalent for + both. The stored procedure/function must return a resultset as the first + out-parameter to be able to work with Hibernate. An example of such a + stored function in Oracle 9 and higher is as follows:</para> + + <programlisting role="XML"><![CDATA[CREATE OR REPLACE FUNCTION selectAllEmployments + RETURN SYS_REFCURSOR +AS + st_cursor SYS_REFCURSOR; +BEGIN + OPEN st_cursor FOR + SELECT EMPLOYEE, EMPLOYER, + STARTDATE, ENDDATE, + REGIONCODE, EID, VALUE, CURRENCY + FROM EMPLOYMENT; + RETURN st_cursor; + END;]]></programlisting> + + <para>To use this query in Hibernate you need to map it via a named + query.</para> + + <programlisting role="XML"><![CDATA[<sql-query name="selectAllEmployees_SP" callable="true"> + <return alias="emp" class="Employment"> + <return-property name="employee" column="EMPLOYEE"/> + <return-property name="employer" column="EMPLOYER"/> + <return-property name="startDate" column="STARTDATE"/> + <return-property name="endDate" column="ENDDATE"/> + <return-property name="regionCode" column="REGIONCODE"/> + <return-property name="id" column="EID"/> + <return-property name="salary"> + <return-column name="VALUE"/> + <return-column name="CURRENCY"/> + </return-property> + </return> + { ? = call selectAllEmployments() } +</sql-query>]]></programlisting> + + <para>Stored procedures currently only return scalars and + entities. <literal>&lt;return-join&gt;</literal> and + <literal>&lt;load-collection&gt;</literal> are not supported.</para> + + <section id="querysql-limits-storedprocedures" revision="1"> + <title>Rules/limitations for using stored procedures</title> + + <para>You cannot use stored procedures with Hibernate unless you follow some procedure/function + rules. If they do not follow those rules they are + not usable with Hibernate. If you still want to use these procedures + you have to execute them via <literal>session.connection()</literal>. + The rules are different for each database, since database vendors have + different stored procedure semantics/syntax.</para> + + <para>Stored procedure queries cannot be paged with + <literal>setFirstResult()/setMaxResults()</literal>.</para> + + <para>The recommended call form is standard SQL92: <literal>{ ? = call + functionName(&lt;parameters&gt;) }</literal> or <literal>{ ? = call + procedureName(&lt;parameters&gt;}</literal>. Native call syntax is not + supported.</para> + + <para>For Oracle the following rules apply:</para> + + <itemizedlist spacing="compact"> + <listitem> + <para>A function must return a result set. The first parameter of + a procedure must be an <literal>OUT</literal> that returns a + result set. This is done by using a + <literal>SYS_REFCURSOR</literal> type in Oracle 9 or 10. In Oracle + you need to define a <literal>REF CURSOR</literal> type. See + Oracle literature for further information.</para> + </listitem> + </itemizedlist> + + <para>For Sybase or MS SQL server the following rules apply:</para> + + <itemizedlist spacing="compact"> + <listitem> + <para>The procedure must return a result set. Note that since + these servers can return multiple result sets and update + counts, Hibernate will iterate the results and take the first + result that is a result set as its return value. Everything else + will be discarded.</para> + </listitem> + + <listitem> + <para>If you can enable <literal>SET NOCOUNT ON</literal> in your + procedure it will probably be more efficient, but this is not a + requirement.</para> + </listitem> + </itemizedlist> + </section> + </section> + </section> + + <section id="querysql-cud"> + <title>Custom SQL for create, update and delete</title> + + <para>Hibernate3 can use custom SQL for create, update, and delete operations. + The SQL can be overridden at the statement level or inidividual column level. This + section describes statement overrides. For columns, see + <xref linkend="mapping-column-read-and-write"/>. + </para> + <para> + The class and collection persisters in Hibernate already contain a set of + configuration time generated strings (insertsql, deletesql, updatesql etc.). + The mapping tags + <literal>&lt;sql-insert&gt;</literal>, + <literal>&lt;sql-delete&gt;</literal>, and + <literal>&lt;sql-update&gt;</literal> override these strings:</para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <sql-insert>INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? )</sql-insert> + <sql-update>UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?</sql-update> + <sql-delete>DELETE FROM PERSON WHERE ID=?</sql-delete> +</class>]]></programlisting> + + <para>The SQL is directly executed in your database, so you can + use any dialect you like. This will reduce the portability of + your mapping if you use database specific SQL.</para> + + <para>Stored procedures are supported if the <literal>callable</literal> + attribute is set:</para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <sql-insert callable="true">{call createPerson (?, ?)}</sql-insert> + <sql-delete callable="true">{? = call deletePerson (?)}</sql-delete> + <sql-update callable="true">{? = call updatePerson (?, ?)}</sql-update> +</class>]]></programlisting> + + <para>The order of the positional parameters is vital, as they + must be in the same sequence as Hibernate expects them.</para> + + <para>You can view 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 view the expected sequence, do + not include your custom SQL in the mapping files, as this will override the + Hibernate generated static SQL.</para> + + <para>The stored procedures are in most cases + required to return the number of rows inserted, updated and deleted, as + Hibernate has some runtime checks for the success of the statement. + Hibernate always registers the first statement parameter as a numeric + output parameter for the CUD operations:</para> + + <programlisting><![CDATA[CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN VARCHAR2) + RETURN NUMBER IS +BEGIN + + update PERSON + set + NAME = uname, + where + ID = uid; + + return SQL%ROWCOUNT; + +END updatePerson;]]></programlisting> + </section> + + <section id="querysql-load"> + <title>Custom SQL for loading</title> + + <para>You can also declare your own SQL (or HQL) queries for entity + loading. As with inserts, updates, and deletes, this can be done at the + individual column level as described in + <xref linkend="mapping-column-read-and-write"/> + or at the statement level. Here is an example of a statement level override: + </para> + + <programlisting role="XML"><![CDATA[<sql-query name="person"> + <return alias="pers" class="Person" lock-mode="upgrade"/> + SELECT NAME AS {pers.name}, ID AS {pers.id} + FROM PERSON + WHERE ID=? + FOR UPDATE +</sql-query>]]></programlisting> + + <para>This is just a named query declaration, as discussed earlier. You + can reference this named query in a class mapping:</para> + + <programlisting role="XML"><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <loader query-ref="person"/> +</class>]]></programlisting> + + <para>This even works with stored procedures.</para> + + <para>You can even define a query for collection loading:</para> + + <programlisting role="XML"><![CDATA[<set name="employments" inverse="true"> + <key/> + <one-to-many class="Employment"/> + <loader query-ref="employments"/> +</set>]]></programlisting> + + <programlisting role="XML"><![CDATA[<sql-query name="employments"> + <load-collection alias="emp" role="Person.employments"/> + SELECT {emp.*} + FROM EMPLOYMENT emp + WHERE EMPLOYER = :id + ORDER BY STARTDATE ASC, EMPLOYEE ASC +</sql-query>]]></programlisting> + + <para>You can also define an entity loader that loads a collection by + join fetching:</para> + + <programlisting role="XML"><![CDATA[<sql-query name="person"> + <return alias="pers" class="Person"/> + <return-join alias="emp" property="pers.employments"/> + SELECT NAME AS {pers.*}, {emp.*} + FROM PERSON pers + LEFT OUTER JOIN EMPLOYMENT emp + ON pers.ID = emp.PERSON_ID + WHERE ID=? +</sql-query>]]></programlisting> + </section> +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/readonly.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/readonly.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/readonly.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,858 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="readonly"> + <title>Read-only entities</title> + + <important> + <para> + Hibernate's treatment of <emphasis>read-only</emphasis> entities may + differ from what you may have encountered elsewhere. Incorrect usage + may cause unexpected results. + </para> + </important> + + <para> + When an entity is read-only: + + <itemizedlist> + <listitem> + <para> + Hibernate does not dirty-check the entity's simple + properties or single-ended associations; + </para> + </listitem> + <listitem> + <para> + Hibernate will not update simple properties or updatable + single-ended associations; + </para> + </listitem> + <listitem> + <para> + Hibernate will not update the version of the read-only + entity if only simple properties or single-ended + updatable associations are changed; + </para> + </listitem> + </itemizedlist> + </para> + + <para> + In some ways, Hibernate treats read-only entities the same as entities that are + not read-only: + + <itemizedlist> + <listitem> + <para> + Hibernate cascades operations to associations as + defined in the entity mapping. + </para> + </listitem> + <listitem> + <para> + Hibernate updates the version if the entity has a + collection with changes that dirties the entity; + </para> + </listitem> + <listitem> + <para> + A read-only entity can be deleted. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Even if an entity is not read-only, its collection association can + be affected if it contains a read-only entity. + </para> + + <para> + For details about the affect of read-only entities on different + property and association types, see + <xref linkend="readonly-proptypes"/>. + </para> + + <para> + For details about how to make entities read-only, see + <xref linkend="readonly-api"/> + </para> + + <para> + Hibernate does some optimizing for read-only entities: + </para> + <itemizedlist> + <listitem> + <para> + It saves execution time by not dirty-checking simple properties or + single-ended associations. + </para> + </listitem> + <listitem> + <para> + It saves memory by deleting database snapshots. + </para> + </listitem> + </itemizedlist> + + <section id="readonly-api"> + <title>Making persistent entities read-only</title> + + <para> + Only persistent entities can be made read-only. Transient and + detached entities must be put in persistent state before they + can be made read-only. + </para> + + <para> + Hibernate provides the following ways to make persistent entities read-only: + </para> + + <itemizedlist> + <listitem> + <para> + you can map an entity class as <emphasis>immutable</emphasis>; + when an entity of an immutable class is made persistent, + Hibernate automatically makes it read-only. + see <xref linkend="readonly-api-immutable"/> for details + </para> + </listitem> + <listitem> + <para> + you can change a default so that entities loaded + into the session by Hibernate are automatically + made read-only; see <xref linkend="readonly-api-loaddefault"/> for details + </para> + </listitem> + <listitem> + <para> + you can make an HQL query or criteria read-only so + that entities loaded when the query or criteria executes, + scrolls, or iterates, are automatically + made read-only; see <xref linkend="readonly-api-querycriteria"/> for details + </para> + </listitem> + <listitem> + <para> + you can make a persistent entity that is already in the + in the session read-only; see + <xref linkend="readonly-api-entity"/> for details + </para> + </listitem> + </itemizedlist> + + <section id="readonly-api-immutable"> + <title>Entities of immutable classes</title> + + <para> + When an entity instance of an immutable class is made + persistent, Hibernate automatically makes it read-only. + </para> + <para> + An entity of an immutable class can created + and deleted the same as an entity of a mutable class. + </para> + + <para> + Hibernate treats a persistent entity of an immutable + class the same way as a read-only persistent entity + of a mutable class. The only exception is that + Hibernate will not allow an entity of an immutable + class to be changed so it is not read-only. + </para> + + </section> + + <section id="readonly-api-loaddefault"> + <title>Loading persistent entities as read-only</title> + + <note> + <para> + Entities of immutable classes are automatically loaded + as read-only. + </para> + </note> + + <para> + To change the default behavior so Hibernate loads entity + instances of mutable classes into the session and automatically + makes them read-only, call: + </para> + <programlisting role="Java">Session.setDefaultReadOnly( true );</programlisting> + + <para> + To change the default back so entities loaded by Hibernate are not + made read-only, call: + </para> + <programlisting role="Java">Session.setDefaultReadOnly( false );</programlisting> + + <para> + You can determine the current setting by calling: + </para> + <programlisting role="Java">Session.isDefaultReadOnly();</programlisting> + + <para> + If Session.isDefaultReadOnly() returns true, entities loaded by + the following are automatically made read-only: + </para> + <itemizedlist> + <listitem> + <para> + Session.load() + </para> + </listitem> + <listitem> + <para> + Session.get() + </para> + </listitem> + <listitem> + <para> + Session.merge() + </para> + </listitem> + <listitem> + <para> + executing, scrolling, or iterating HQL queries and + criteria; to override this setting for a particular + HQL query or criteria see + <xref linkend="readonly-api-querycriteria"/> + </para> + </listitem> + </itemizedlist> + + <para> + Changing this default has no effect on: + </para> + <itemizedlist> + <listitem> + <para> + persistent entities already in the session when the + default was changed + </para> + </listitem> + <listitem> + <para> + persistent entities that are refreshed via + Session.refresh(); a refreshed persistent + entity will only be read-only if it was + read-only before refreshing + </para> + </listitem> + <listitem> + <para> + persistent entities added by the application via + Session.persist(), Session.save(), and Session.update() + Session.saveOrUpdate() + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="readonly-api-querycriteria"> + <title>Loading read-only entities from an HQL query/criteria</title> + + <note> + <para> + Entities of immutable classes are automatically loaded + as read-only. + </para> + </note> + + <para> + If Session.isDefaultReadOnly() returns false (the default) + when an HQL query or criteria executes, then entities + and proxies of mutable classes loaded by the query will + not be read-only. + </para> + + <para> + You can override this behavior so that entities and proxies loaded + by an HQL query or criteria are automatically made read-only. + </para> + + <para> + For an HQL query, call: + </para> + <programlisting role="Java">Query.setReadOnly( true );</programlisting> + + <para> + <literal>Query.setReadOnly( true )</literal> must be called before + <literal>Query.list()</literal>, <literal>Query.uniqueResult()</literal>, + <literal>Query.scroll()</literal>, or <literal>Query.iterate()</literal> + </para> + + <para> + For an HQL criteria, call: + </para> + <programlisting role="Java">Criteria.setReadOnly( true );</programlisting> + + <para> + <literal>Criteria.setReadOnly( true )</literal> must be called before + <literal>Criteria.list()</literal>, <literal>Criteria.uniqueResult()</literal>, + or <literal>Criteria.scroll()</literal> + </para> + + <para> + Entities and proxies that exist in the session before being returned + by an HQL query or criteria are not affected. + </para> + + <para> + Uninitialized persistent collections returned by the query are + not affected. Later, when the collection is initialized, + entities loaded into the session will be read-only if + Session.isDefaultReadOnly() returns true. + </para> + + <para> + Using <literal>Query.setReadOnly( true )</literal> or + <literal>Criteria.setReadOnly( true )</literal> works well + when a single HQL query or criteria loads all the entities and + intializes all the proxies and collections that the application + needs to be read-only. + </para> + + <para> + When it is not possible to load and initialize all + necessary entities in a single query or criteria, + you can temporarily change the session default to load + entities as read-only before the query is executed. + Then you can explicitly initialize proxies and collections + before restoring the session default. + </para> + + <programlisting role="Java"> +Session session = factory.openSession(); +Transaction tx = session.beginTransaction(); + +setDefaultReadOnly( true ); +Contract contract = + ( Contract ) session.createQuery( + "from Contract where customerName = 'Sherman'" ) + .uniqueResult(); +Hibernate.initialize( contract.getPlan() ); +Hibernate.initialize( contract.getVariations() ); +Hibernate.initialize( contract.getNotes() ); +setDefaultReadOnly( false ); +... +tx.commit(); +session.close(); + +</programlisting> + + <para> + If Session.isDefaultReadOnly() returns true, then you can + use Query.setReadOnly( false ) and Criteria.setReadOnly( false ) + to override this session setting and load entities that are + not read-only. + </para> + + </section> + + <section id="readonly-api-entity"> + <title>Making a persistent entity read-only</title> + <note> + <para> + Persistent entities of immutable classes are automatically + made read-only. + </para> + </note> + + <para> + To make a persistent entity or proxy read-only, call: + </para> + <programlisting>Session.setReadOnly(entityOrProxy, true)</programlisting> + + <para> + To change a read-only entity or proxy of a mutable class so + it is no longer read-only, call: + </para> + <programlisting>Session.setReadOnly(entityOrProxy, false)</programlisting> + + <important> + <para> + When a read-only entity or proxy is changed so it is no longer + read-only, Hibernate assumes that the current state of the + read-only entity is consistent with its database representation. + If this is not true, then any non-flushed changes made before + or while the entity was read-only, will be ignored. + </para> + </important> + + <para> + To throw away non-flushed changes and make the persistent entity + consistent with its database representation, call: </para> + <programlisting role="Java">session.refresh( entity );</programlisting> + + <para> + To flush changes made before or while the entity + was read-only and make the database representation + consistent with the current state of the persistent + entity: + </para> +<programlisting role="Java"> +// evict the read-only entity so it is detached +session.evict( entity ); + +// make the detached entity (with the non-flushed changes) persistent +session.update( entity ); + +// now entity is no longer read-only and its changes can be flushed +s.flush(); +</programlisting> + </section> + </section> + + <section id="readonly-proptypes"> + <title>Read-only affect on property type</title> + + <para> + The following table summarizes how different property types are + affected by making an entity read-only. + </para> + + <table frame="topbot" id="readonly-proptype-summary"> + <title>Affect of read-only entity on property types</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Property/Association Type</entry> + <entry>Changes flushed to DB?</entry> + </row> + </thead> + <tbody> + <row> + <entry> + Simple + <para> + (<xref linkend="readonly-proptypes-simple"/>) + </para> + </entry> + <entry>no*</entry> + </row> + <row> + <entry> + <para>Unidirectional one-to-one</para> + <para>Unidirectional many-to-one</para> + <para> + (<xref linkend="readonly-proptypes-singleended-unidir"/>) + </para> + </entry> + + <entry> + <para>no*</para> + <para>no*</para> + </entry> + </row> + <row> + <entry> + <para>Unidirectional one-to-many</para> + <para>Unidirectional many-to-many</para> + <para> + (<xref linkend="readonly-proptypes-manyended-unidir"/>) + </para> + </entry> + <entry> + <para>yes</para> + <para>yes</para> + </entry> + </row> + <row> + <entry> + <para>Bidirectional one-to-one</para> + <para> + (<xref linkend="readonly-proptypes-onetoone-bidir"/>) + </para> + </entry> + <entry>only if the owning entity is not read-only*</entry> + </row> + <row> + <entry> + <para>Bidirectional one-to-many/many-to-one</para> + <para>inverse collection</para> + <para>non-inverse collection</para> + <para> + (<xref linkend="readonly-proptypes-onetomany-manytoone"/>) + </para> + </entry> + <entry> + <para> </para> + <para>only added/removed entities that are not read-only*</para> + <para>yes</para> + </entry> + </row> + <row> + <entry> + <para>Bidirectional many-to-many</para> + <para> + (<xref linkend="readonly-proptypes-manytomany-bidir"/>) + </para> + </entry> + <entry>yes</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + * Behavior is different when the entity having the property/association + is read-only, compared to when it is not read-only. + </para> + + <section id="readonly-proptypes-simple"> + <title>Simple properties</title> + + <para> + When a persistent object is read-only, Hibernate does not + dirty-check simple properties. + </para> + + <para> + Hibernate will not synchronize simple property state changes + to the database. If you have automatic versioning, Hibernate + will not increment the version if any simple properties change. + </para> + + <programlisting role="Java"> +Session session = factory.openSession(); +Transaction tx = session.beginTransaction(); + +// get a contract and make it read-only +Contract contract = ( Contract ) session.get( Contract.class, contractId ); +session.setReadOnly( contract, true ); + +// contract.getCustomerName() is "Sherman" +contract.setCustomerName( "Yogi" ); +tx.commit(); + +tx = session.beginTransaction(); + +contract = ( Contract ) session.get( Contract.class, contractId ); +// contract.getCustomerName() is still "Sherman" +... +tx.commit(); +session.close(); + </programlisting> + + </section> + + <section id="readonly-prop-types-unidir"> + <title>Unidirectional associations</title> + + <section id="readonly-proptypes-singleended-unidir"> + <title>Unidirectional one-to-one and many-to-one</title> + + <para> + Hibernate treats unidirectional one-to-one and many-to-one + associations in the same way when the owning entity is + read-only. + </para> + + <para> + We use the term <emphasis>unidirectional single-ended + association</emphasis> when referring to functionality + that is common to unidirectional one-to-one and many-to-one + associations. + </para> + + <para> + Hibernate does not dirty-check unidirectional single-ended + associations when the owning entity is read-only. + </para> + + <para> + If you change a read-only entity's reference to a + unidirectional single-ended association to null, + or to refer to a different entity, that change + will not be flushed to the database. + </para> + + <note> + <para> + If an entity is of an immutable class, + then its references to unidirectional single-ended + associations must be assigned when that + entity is first created. Because the entity is + automatically made read-only, these references can + not be updated. + </para> + </note> + + <para> + If automatic versioning is used, Hibernate will not + increment the version due to local changes to + unidirectional single-ended associations. + </para> + + <para> + In the following examples, Contract has a unidirectional + many-to-one association with Plan. Contract cascades save and + update operations to the association. + </para> + + <para> + The following shows that changing a read-only entity's + many-to-one association reference to null has no effect + on the entity's database representation. + </para> + +<programlisting role="Java">// get a contract with an existing plan; +// make the contract read-only and set its plan to null +tx = session.beginTransaction(); +Contract contract = ( Contract ) session.get( Contract.class, contractId ); +session.setReadOnly( contract, true ); +contract.setPlan( null ); +tx.commit(); + +// get the same contract +tx = session.beginTransaction(); +contract = ( Contract ) session.get( Contract.class, contractId ); + +// contract.getPlan() still refers to the original plan; + +tx.commit(); +session.close();</programlisting> + + <para> + The following shows that, even though + an update to a read-only entity's many-to-one + association has no affect on the entity's + database representation, flush still cascades + the save-update operation to the locally + changed association. + </para> + +<programlisting role="Java">// get a contract with an existing plan; +// make the contract read-only and change to a new plan +tx = session.beginTransaction(); +Contract contract = ( Contract ) session.get( Contract.class, contractId ); +session.setReadOnly( contract, true ); +Plan newPlan = new Plan( "new plan" +contract.setPlan( newPlan); +tx.commit(); + +// get the same contract +tx = session.beginTransaction(); +contract = ( Contract ) session.get( Contract.class, contractId ); +newPlan = ( Contract ) session.get( Plan.class, newPlan.getId() ); + +// contract.getPlan() still refers to the original plan; +// newPlan is non-null because it was persisted when +// the previous transaction was committed; + +tx.commit(); +session.close();</programlisting> + + </section> + + <section id="readonly-proptypes-manyended-unidir"> + <title>Unidirectional one-to-many and many-to-many</title> + + <para> + Hibernate treats unidirectional one-to-many + and many-to-many associations owned by a read-only + entity the same as when owned by an entity that is not + read-only. + </para> + + <para> + Hibernate dirty-checks unidirectional one-to-many and + many-to-many associations; + </para> + + <para> + The collection can contain entities that + are read-only, as well as entities + that are not read-only. + </para> + + <para> + Entities can be added and removed from the + collection; changes are flushed to the database. + </para> + + <para> + If automatic versioning is used, Hibernate will + update the version due to changes in the collection + if they dirty the owning entity. + </para> + + </section> + + </section> + + <section id="readonly-proptypes-bidir"> + <title>Bidirectional associations</title> + + <section id="readonly-proptypes-onetoone-bidir"> + <title>Bidirectional one-to-one</title> + + <para> + If a read-only entity owns a bidirectional + one-to-one association: + </para> + + <itemizedlist> + <listitem> + <para> + Hibernate does not dirty-check the association. + </para> + </listitem> + <listitem> + <para> + updates that change the association reference + to null or to refer to a different entity + will not be flushed to the database. + </para> + </listitem> + <listitem> + <para> + If automatic versioning is used, Hibernate will not + increment the version due to local changes to + the association. + </para> + </listitem> + </itemizedlist> + + <note> + <para> + If an entity is of an immutable class, + and it owns a bidirectional one-to-one + association, then its reference must be + assigned when that entity is first created. + Because the entity is automatically made + read-only, these references cannot be updated. + </para> + </note> + + <para> + When the owner is not read-only, Hibernate treats + an association with a read-only entity the same + as when the association is with an entity that is + not read-only. + </para> + + </section> + + <section id="readonly-proptypes-onetomany-manytoone"> + <title>Bidirectional one-to-many/many-to-one</title> + + <para> + A read-only entity has no impact on a bidirectional + one-to-many/many-to-one association if: + </para> + + <itemizedlist> + <listitem> + <para> + the read-only entity is on the one-to-many side + using an inverse collection; + </para> + </listitem> + <listitem> + <para> + the read-only entity is on the one-to-many side + using a non-inverse collection; + </para> + </listitem> + <listitem> + <para> + the one-to-many side uses a non-inverse collection + that contains the read-only entity + </para> + </listitem> + </itemizedlist> + + <para> + When the one-to-many side uses an inverse collection: + </para> + + <itemizedlist> + <listitem> + <para> + a read-only entity can only be added to the collection + when it is created; + </para> + </listitem> + <listitem> + <para> + a read-only entity can only be removed from the + collection by an orphan delete or by explicitly + deleting the entity. + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="readonly-proptypes-manytomany-bidir"> + <title>Bidirectional many-to-many</title> + <para> + Hibernate treats bidirectional many-to-many + associations owned by a read-only entity the + same as when owned by an entity that is not + read-only. + </para> + + <para> + Hibernate dirty-checks bidirectional many-to-many + associations. + </para> + + <para> + The collection on either side of the association + can contain entities that are read-only, as well + as entities that are not read-only. + </para> + + <para> + Entities are added and removed from both sides + of the collection; changes are flushed to the + database. + </para> + + <para> + If automatic versioning is used, Hibernate will + update the version due to changes in both sides of + the collection if they dirty the entity owning the + respective collections. + </para> + + </section> + + </section> + </section> +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/session_api.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/session_api.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/session_api.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1292 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="objectstate"> + <title>Working with objects</title> + + <para> + Hibernate is a full object/relational mapping solution that not only shields + the developer from the details of the underlying database management + system, but also offers <emphasis>state management</emphasis> of objects. This is, + contrary to the management of SQL <literal>statements</literal> in common JDBC/SQL + persistence layers, a natural object-oriented view of persistence in Java + applications. + </para> + + <para> + In other words, Hibernate application developers should always think about the + <emphasis>state</emphasis> of their objects, and not necessarily about the + execution of SQL statements. This part is taken care of by Hibernate and is only + relevant for the application developer when tuning the performance of the system. + </para> + + <section id="objectstate-overview"> + <title>Hibernate object states</title> + + <para> + Hibernate defines and supports the following object states: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Transient</emphasis> - an object is transient if it has just + been instantiated using the <literal>new</literal> operator, and it + is not associated with a Hibernate <literal>Session</literal>. It has no + persistent representation in the database and no identifier value has been + assigned. Transient instances will be destroyed by the garbage collector if + the application does not hold a reference anymore. Use the Hibernate + <literal>Session</literal> to make an object persistent (and let Hibernate + take care of the SQL statements that need to be executed for this transition). + </para> + </listitem> + <listitem> + <para> + <emphasis>Persistent</emphasis> - a persistent instance has a representation + in the database and an identifier value. It might just have been saved or loaded, + however, it is by definition in the scope of a <literal>Session</literal>. + Hibernate will detect any changes made to an object in persistent state and + synchronize the state with the database when the unit of work completes. + Developers do not execute manual <literal>UPDATE</literal> statements, or + <literal>DELETE</literal> statements when an object should be made transient. + </para> + </listitem> + <listitem> + <para> + <emphasis>Detached</emphasis> - a detached instance is an object that has been + persistent, but its <literal>Session</literal> has been closed. The reference + to the object is still valid, of course, and the detached instance might even + be modified in this state. A detached instance can be reattached to a new + <literal>Session</literal> at a later point in time, making it (and all the + modifications) persistent again. This feature enables a programming model for + long running units of work that require user think-time. We call them + <emphasis>application transactions</emphasis>, i.e., a unit of work from the + point of view of the user. + </para> + </listitem> + </itemizedlist> + + <para> + We will now discuss the states and state transitions (and the Hibernate methods that + trigger a transition) in more detail. + </para> + + </section> + + <section id="objectstate-makingpersistent" revision="1"> + <title>Making objects persistent</title> + + <para> + Newly instantiated instances of a persistent class are considered + <emphasis>transient</emphasis> by Hibernate. We can make a transient + instance <emphasis>persistent</emphasis> by associating it with a + session: + </para> + + <programlisting role="JAVA"><![CDATA[DomesticCat fritz = new DomesticCat(); +fritz.setColor(Color.GINGER); +fritz.setSex('M'); +fritz.setName("Fritz"); +Long generatedId = (Long) sess.save(fritz);]]></programlisting> + + <para> + If <literal>Cat</literal> has a generated identifier, the identifier is + generated and assigned to the <literal>cat</literal> when <literal>save()</literal> + is called. If <literal>Cat</literal> has an <literal>assigned</literal> + identifier, or a composite key, the identifier should be assigned to + the <literal>cat</literal> instance before calling <literal>save()</literal>. + You can also use <literal>persist()</literal> instead of <literal>save()</literal>, + with the semantics defined in the EJB3 early draft. + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>persist()</literal> makes a transient instance persistent. + However, it does not guarantee that the identifier value will be assigned to + the persistent instance immediately, the assignment might happen at flush time. + <literal>persist()</literal> also guarantees that it will not execute an + <literal>INSERT</literal> statement if it is called outside of transaction + boundaries. This is useful in long-running conversations with an extended + Session/persistence context. + </para> + </listitem> + <listitem> + <para> + <literal>save()</literal> does guarantee to return an identifier. If an INSERT + has to be executed to get the identifier ( e.g. "identity" generator, not + "sequence"), this INSERT happens immediately, no matter if you are inside or + outside of a transaction. This is problematic in a long-running conversation + with an extended Session/persistence context. + </para> + </listitem> + </itemizedlist> + + <para> + Alternatively, you can assign the identifier using an overloaded version + of <literal>save()</literal>. + </para> + +<programlisting role="JAVA"><![CDATA[DomesticCat pk = new DomesticCat(); +pk.setColor(Color.TABBY); +pk.setSex('F'); +pk.setName("PK"); +pk.setKittens( new HashSet() ); +pk.addKitten(fritz); +sess.save( pk, new Long(1234) );]]></programlisting> + + <para> + If the object you make persistent has associated objects (e.g. the + <literal>kittens</literal> collection in the previous example), + these objects can be made persistent in any order you like unless you + have a <literal>NOT NULL</literal> constraint upon a foreign key column. + There is never a risk of violating foreign key constraints. However, you + might violate a <literal>NOT NULL</literal> constraint if you + <literal>save()</literal> the objects in the wrong order. + </para> + + <para> + Usually you do not bother with this detail, as you will normally use Hibernate's + <emphasis>transitive persistence</emphasis> feature to save the associated + objects automatically. Then, even <literal>NOT NULL</literal> + constraint violations do not occur - Hibernate will take care of everything. + Transitive persistence is discussed later in this chapter. + </para> + + </section> + + <section id="objectstate-loading"> + <title>Loading an object</title> + + <para> + The <literal>load()</literal> methods of <literal>Session</literal> provide + a way of retrieving a persistent instance if you know its identifier. + <literal>load()</literal> takes a class object and loads the state into + a newly instantiated instance of that class in a persistent state. + </para> + + <programlisting role="JAVA"><![CDATA[Cat fritz = (Cat) sess.load(Cat.class, generatedId);]]></programlisting> + +<programlisting role="JAVA"><![CDATA[// you need to wrap primitive identifiers +long id = 1234; +DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new Long(id) );]]></programlisting> + + <para> + Alternatively, you can load state into a given instance: + </para> + +<programlisting role="JAVA"><![CDATA[Cat cat = new DomesticCat(); +// load pk's state into cat +sess.load( cat, new Long(pkId) ); +Set kittens = cat.getKittens();]]></programlisting> + + <para> + Be aware that <literal>load()</literal> will throw an unrecoverable exception if + there is no matching database row. If the class is mapped with a proxy, + <literal>load()</literal> just returns an uninitialized proxy and does not + actually hit the database until you invoke a method of the proxy. This + is useful if you wish to create an association to an object + without actually loading it from the database. It also allows multiple + instances to be loaded as a batch if <literal>batch-size</literal> is + defined for the class mapping. + </para> + + <para> + If you are not certain that a matching row exists, you should use the + <literal>get()</literal> method which hits the database immediately and + returns null if there is no matching row. + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id); +if (cat==null) { + cat = new Cat(); + sess.save(cat, id); +} +return cat;]]></programlisting> + + <para> + You can even load an object using an SQL <literal>SELECT ... FOR UPDATE</literal>, + using a <literal>LockMode</literal>. See the API documentation for more information. + </para> + + <programlisting role="JAVA"><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);]]></programlisting> + + <para> + Any associated instances or contained collections will + <emphasis>not</emphasis> be selected <literal>FOR UPDATE</literal>, unless you decide + to specify <literal>lock</literal> or <literal>all</literal> as a + cascade style for the association. + </para> + + <para> + It is possible to re-load an object and all its collections at any time, using the + <literal>refresh()</literal> method. This is useful when database triggers are used to + initialize some of the properties of the object. + </para> + + <programlisting role="JAVA"><![CDATA[sess.save(cat); +sess.flush(); //force the SQL INSERT +sess.refresh(cat); //re-read the state (after the trigger executes)]]></programlisting> + + <para> + How much does Hibernate load + from the database and how many SQL <literal>SELECT</literal>s will it use? This + depends on the <emphasis>fetching strategy</emphasis>. This is explained in + <xref linkend="performance-fetching"/>. + </para> + + </section> + + <section id="objectstate-querying" revision="1"> + <title>Querying</title> + + <para> + If you do not know the identifiers of the objects you are looking for, + you need a query. Hibernate supports an easy-to-use but powerful object + oriented query language (HQL). For programmatic query creation, Hibernate + supports a sophisticated Criteria and Example query feature (QBC and QBE). + You can also express your query in the native SQL of your database, with + optional support from Hibernate for result set conversion into objects. + </para> + + <section id="objectstate-querying-executing" revision="1"> + <title>Executing queries</title> + + <para> + HQL and native SQL queries are represented with an instance of <literal>org.hibernate.Query</literal>. + This interface offers methods for parameter binding, result set handling, and for the execution + of the actual query. You always obtain a <literal>Query</literal> using the current + <literal>Session</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[List cats = session.createQuery( + "from Cat as cat where cat.birthdate < ?") + .setDate(0, date) + .list(); + +List mothers = session.createQuery( + "select mother from Cat as cat join cat.mother as mother where cat.name = ?") + .setString(0, name) + .list(); + +List kittens = session.createQuery( + "from Cat as cat where cat.mother = ?") + .setEntity(0, pk) + .list(); + +Cat mother = (Cat) session.createQuery( + "select cat.mother from Cat as cat where cat = ?") + .setEntity(0, izi) + .uniqueResult();]] + +Query mothersWithKittens = (Cat) session.createQuery( + "select mother from Cat as mother left join fetch mother.kittens"); +Set uniqueMothers = new HashSet(mothersWithKittens.list());]]></programlisting> + + <para> + A query is usually executed by invoking <literal>list()</literal>. The + result of the query will be loaded completely into a collection in memory. + Entity instances retrieved by a query are in a persistent state. The + <literal>uniqueResult()</literal> method offers a shortcut if you + know your query will only return a single object. Queries that + make use of eager fetching of collections usually return duplicates of + the root objects, but with their collections initialized. You can filter + these duplicates through a <literal>Set</literal>. + </para> + + <section id="objectstate-querying-executing-iterate"> + <title>Iterating results</title> + + <para> + Occasionally, you might be able to achieve better performance by + executing the query using the <literal>iterate()</literal> method. + This will usually be the case if you expect that the actual + entity instances returned by the query will already be in the session + or second-level cache. If they are not already cached, + <literal>iterate()</literal> will be slower than <literal>list()</literal> + and might require many database hits for a simple query, usually + <emphasis>1</emphasis> for the initial select which only returns identifiers, + and <emphasis>n</emphasis> additional selects to initialize the actual instances. + </para> + + <programlisting role="JAVA"><![CDATA[// fetch ids +Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate(); +while ( iter.hasNext() ) { + Qux qux = (Qux) iter.next(); // fetch the object + // something we couldnt express in the query + if ( qux.calculateComplicatedAlgorithm() ) { + // delete the current instance + iter.remove(); + // dont need to process the rest + break; + } +}]]></programlisting> + </section> + + <section id="objectstate-querying-executing-tuples"> + <title>Queries that return tuples</title> + + <para> + Hibernate queries sometimes return tuples of objects. Each tuple + is returned as an array: + </para> + + <programlisting role="JAVA"><![CDATA[Iterator kittensAndMothers = sess.createQuery( + "select kitten, mother from Cat kitten join kitten.mother mother") + .list() + .iterator(); + +while ( kittensAndMothers.hasNext() ) { + Object[] tuple = (Object[]) kittensAndMothers.next(); + Cat kitten = (Cat) tuple[0]; + Cat mother = (Cat) tuple[1]; + .... +}]]></programlisting> + + </section> + + <section id="objectstate-querying-executing-scalar" revision="1"> + <title>Scalar results</title> + + <para> + Queries can specify a property of a class in the <literal>select</literal> clause. + They can even call SQL aggregate functions. Properties or aggregates are considered + "scalar" results and not entities in persistent state. + </para> + + <programlisting role="JAVA"><![CDATA[Iterator results = sess.createQuery( + "select cat.color, min(cat.birthdate), count(cat) from Cat cat " + + "group by cat.color") + .list() + .iterator(); + +while ( results.hasNext() ) { + Object[] row = (Object[]) results.next(); + Color type = (Color) row[0]; + Date oldest = (Date) row[1]; + Integer count = (Integer) row[2]; + ..... +}]]></programlisting> + + </section> + + <section id="objectstate-querying-executing-parameters"> + <title>Bind parameters</title> + + <para> + Methods on <literal>Query</literal> are provided for binding values to + named parameters or JDBC-style <literal>?</literal> parameters. + <emphasis>Contrary to JDBC, Hibernate numbers parameters from zero.</emphasis> + Named parameters are identifiers of the form <literal>:name</literal> in + the query string. The advantages of named parameters are as follows: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + named parameters are insensitive to the order they occur in the + query string + </para> + </listitem> + <listitem> + <para> + they can occur multiple times in the same query + </para> + </listitem> + <listitem> + <para> + they are self-documenting + </para> + </listitem> + </itemizedlist> + + <programlisting role="JAVA"><![CDATA[//named parameter (preferred) +Query q = sess.createQuery("from DomesticCat cat where cat.name = :name"); +q.setString("name", "Fritz"); +Iterator cats = q.iterate();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[//positional parameter +Query q = sess.createQuery("from DomesticCat cat where cat.name = ?"); +q.setString(0, "Izi"); +Iterator cats = q.iterate();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[//named parameter list +List names = new ArrayList(); +names.add("Izi"); +names.add("Fritz"); +Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)"); +q.setParameterList("namesList", names); +List cats = q.list();]]></programlisting> + + </section> + + <section id="objectstate-querying-executing-pagination"> + <title>Pagination</title> + + <para> + If you need to specify bounds upon your result set, that is, the maximum number of rows + you want to retrieve and/or the first row you want to retrieve, you can + use methods of the <literal>Query</literal> interface: + </para> + + <programlisting role="JAVA"><![CDATA[Query q = sess.createQuery("from DomesticCat cat"); +q.setFirstResult(20); +q.setMaxResults(10); +List cats = q.list();]]></programlisting> + + <para> + Hibernate knows how to translate this limit query into the native + SQL of your DBMS. + </para> + + </section> + + <section id="objectstate-querying-executing-scrolling"> + <title>Scrollable iteration</title> + + <para> + If your JDBC driver supports scrollable <literal>ResultSet</literal>s, the + <literal>Query</literal> interface can be used to obtain a + <literal>ScrollableResults</literal> object that allows flexible + navigation of the query results. + </para> + + <programlisting role="JAVA"><![CDATA[Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " + + "order by cat.name"); +ScrollableResults cats = q.scroll(); +if ( cats.first() ) { + + // find the first name on each page of an alphabetical list of cats by name + firstNamesOfPages = new ArrayList(); + do { + String name = cats.getString(0); + firstNamesOfPages.add(name); + } + while ( cats.scroll(PAGE_SIZE) ); + + // Now get the first page of cats + pageOfCats = new ArrayList(); + cats.beforeFirst(); + int i=0; + while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) ); + +} +cats.close()]]></programlisting> + + <para> + Note that an open database connection and cursor is required for this + functionality. Use <literal>setMaxResult()</literal>/<literal>setFirstResult()</literal> + if you need offline pagination functionality. + </para> + + </section> + + <section id="objectstate-querying-executing-named" revision="1"> + <title>Externalizing named queries</title> + + <para> + You can also define named queries in the mapping document. Remember to use a + <literal>CDATA</literal> section if your query contains characters that could + be interpreted as markup. + </para> + + <programlisting role="XML"><![CDATA[<query name="ByNameAndMaximumWeight"><![CDATA[ + from eg.DomesticCat as cat + where cat.name = ? + and cat.weight > ? +] ]></query>]]></programlisting> + + <para> + Parameter binding and executing is done programatically: + </para> + + <programlisting role="JAVA"><![CDATA[Query q = sess.getNamedQuery("ByNameAndMaximumWeight"); +q.setString(0, name); +q.setInt(1, minWeight); +List cats = q.list();]]></programlisting> + + <para> + The actual program code is independent of the query language that + is used. You can also define native SQL queries in metadata, or migrate + existing queries to Hibernate by placing them in mapping files. + </para> + + <para> + Also note that a query declaration inside a <literal>&lt;hibernate-mapping&gt;</literal> + element requires a global unique name for the query, while a query declaration inside a + <literal>&lt;class&gt;</literal> element is made unique automatically by prepending the + fully qualified name of the class. For example + <literal>eg.Cat.ByNameAndMaximumWeight</literal>. + </para> + + </section> + + </section> + + <section id="objectstate-filtering" revision="1"> + <title>Filtering collections</title> + <para> + A collection <emphasis>filter</emphasis> is a special type of query that can be applied to + a persistent collection or array. The query string can refer to <literal>this</literal>, + meaning the current collection element. + </para> + + <programlisting role="JAVA"><![CDATA[Collection blackKittens = session.createFilter( + pk.getKittens(), + "where this.color = ?") + .setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) ) + .list() +);]]></programlisting> + + <para> + The returned collection is considered a bag that is a copy of the given + collection. The original collection is not modified. This is contrary to + the implication of the name "filter", but consistent with expected behavior. + </para> + + <para> + Observe that filters do not require a <literal>from</literal> clause, although they can have + one if required. Filters are not limited to returning the collection elements themselves. + </para> + + <programlisting role="JAVA"><![CDATA[Collection blackKittenMates = session.createFilter( + pk.getKittens(), + "select this.mate where this.color = eg.Color.BLACK.intValue") + .list();]]></programlisting> + + <para> + Even an empty filter query is useful, e.g. to load a subset of elements in a + large collection: + </para> + + <programlisting role="JAVA"><![CDATA[Collection tenKittens = session.createFilter( + mother.getKittens(), "") + .setFirstResult(0).setMaxResults(10) + .list();]]></programlisting> + + </section> + + <section id="objecstate-querying-criteria" revision="1"> + <title>Criteria queries</title> + + <para> + HQL is extremely powerful, but some developers prefer to build queries dynamically + using an object-oriented API, rather than building query strings. Hibernate provides + an intuitive <literal>Criteria</literal> query API for these cases: + </para> + + <programlisting role="JAVA"><![CDATA[Criteria crit = session.createCriteria(Cat.class); +crit.add( Restrictions.eq( "color", eg.Color.BLACK ) ); +crit.setMaxResults(10); +List cats = crit.list();]]></programlisting> + + <para> + The <literal>Criteria</literal> and the associated <literal>Example</literal> + API are discussed in more detail in <xref linkend="querycriteria"/>. + </para> + + </section> + + <section id="objectstate-querying-nativesql" revision="2"> + <title>Queries in native SQL</title> + + <para> + You can express a query in SQL, using <literal>createSQLQuery()</literal> and + let Hibernate manage the mapping from result sets to objects. + You can at any time call <literal>session.connection()</literal> and + use the JDBC <literal>Connection</literal> directly. If you choose to use the + Hibernate API, you must enclose SQL aliases in braces: + </para> + + <programlisting role="JAVA"><![CDATA[List cats = session.createSQLQuery("SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10") + .addEntity("cat", Cat.class) +.list();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[List cats = session.createSQLQuery( + "SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " + + "{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " + + "FROM CAT {cat} WHERE ROWNUM<10") + .addEntity("cat", Cat.class) +.list()]]></programlisting> + + <para> + SQL queries can contain named and positional parameters, just like Hibernate queries. + More information about native SQL queries in Hibernate can be found in + <xref linkend="querysql"/>. + </para> + + </section> + + </section> + + <section id="objectstate-modifying" revision="1"> + <title>Modifying persistent objects</title> + + <para> + <emphasis>Transactional persistent instances</emphasis> (i.e. objects loaded, saved, created or + queried by the <literal>Session</literal>) can be manipulated by the application, + and any changes to persistent state will be persisted when the <literal>Session</literal> + is <emphasis>flushed</emphasis>. This is discussed later in this chapter. There is no need + to call a particular method (like <literal>update()</literal>, which has a different + purpose) to make your modifications persistent. The most straightforward way to update + the state of an object is to <literal>load()</literal> it + and then manipulate it directly while the <literal>Session</literal> is open: + </para> + + <programlisting role="JAVA"><![CDATA[DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(69) ); +cat.setName("PK"); +sess.flush(); // changes to cat are automatically detected and persisted]]></programlisting> + + <para> + Sometimes this programming model is inefficient, as it requires in the same session both an SQL + <literal>SELECT</literal> to load an object and an SQL <literal>UPDATE</literal> + to persist its updated state. Hibernate offers an + alternate approach by using detached instances. + </para> + + <important><para> + Hibernate does not offer its own API for direct execution of + <literal>UPDATE</literal> or <literal>DELETE</literal> statements. Hibernate is a + <emphasis>state management</emphasis> service, you do not have to think in + <emphasis>statements</emphasis> to use it. JDBC is a perfect API for executing + SQL statements, you can get a JDBC <literal>Connection</literal> at any time + by calling <literal>session.connection()</literal>. Furthermore, the notion + of mass operations conflicts with object/relational mapping for online + transaction processing-oriented applications. Future versions of Hibernate + can, however, provide special mass operation functions. See <xref linkend="batch"/> + for some possible batch operation tricks. + </para> +</important> + + </section> + + <section id="objectstate-detached" revision="2"> + <title>Modifying detached objects</title> + + <para> + Many applications need to retrieve an object in one transaction, send it to the + UI layer for manipulation, then save the changes in a new transaction. + Applications that use this kind of approach in a high-concurrency environment + usually use versioned data to ensure isolation for the "long" unit of work. + </para> + + <para> + Hibernate supports this model by providing for reattachment of detached instances + using the <literal>Session.update()</literal> or <literal>Session.merge()</literal> + methods: + </para> + + <programlisting role="JAVA"><![CDATA[// in the first session +Cat cat = (Cat) firstSession.load(Cat.class, catId); +Cat potentialMate = new Cat(); +firstSession.save(potentialMate); + +// in a higher layer of the application +cat.setMate(potentialMate); + +// later, in a new session +secondSession.update(cat); // update cat +secondSession.update(mate); // update mate]]></programlisting> + + <para> + If the <literal>Cat</literal> with identifier <literal>catId</literal> had already + been loaded by <literal>secondSession</literal> when the application tried to + reattach it, an exception would have been thrown. + </para> + + <para> + Use <literal>update()</literal> if you are certain that the session does + not contain an already persistent instance with the same identifier. Use + <literal>merge()</literal> if you want to merge your modifications at any time + without consideration of the state of the session. In other words, <literal>update()</literal> + is usually the first method you would call in a fresh session, ensuring that + the reattachment of your detached instances is the first operation that is executed. + </para> + + <para> + The application should individually <literal>update()</literal> detached instances + that are reachable from the given detached instance <emphasis>only</emphasis> if it wants + their state to be updated. This can be automated using <emphasis>transitive + persistence</emphasis>. See <xref linkend="objectstate-transitive"/> for more information. + </para> + + <para> + The <literal>lock()</literal> method also allows an application to reassociate + an object with a new session. However, the detached instance has to be unmodified. + </para> + + <programlisting role="JAVA"><![CDATA[//just reassociate: +sess.lock(fritz, LockMode.NONE); +//do a version check, then reassociate: +sess.lock(izi, LockMode.READ); +//do a version check, using SELECT ... FOR UPDATE, then reassociate: +sess.lock(pk, LockMode.UPGRADE);]]></programlisting> + + <para> + Note that <literal>lock()</literal> can be used with various + <literal>LockMode</literal>s. See the API documentation and the + chapter on transaction handling for more information. Reattachment is not + the only usecase for <literal>lock()</literal>. + </para> + + <para> + Other models for long units of work are discussed in <xref linkend="transactions-optimistic"/>. + </para> + + </section> + + <section id="objectstate-saveorupdate"> + <title>Automatic state detection</title> + + <para> + Hibernate users have requested a general purpose method that either saves a + transient instance by generating a new identifier or updates/reattaches + the detached instances associated with its current identifier. + The <literal>saveOrUpdate()</literal> method implements this functionality. + </para> + + <programlisting role="JAVA"><![CDATA[// in the first session +Cat cat = (Cat) firstSession.load(Cat.class, catID); + +// in a higher tier of the application +Cat mate = new Cat(); +cat.setMate(mate); + +// later, in a new session +secondSession.saveOrUpdate(cat); // update existing state (cat has a non-null id) +secondSession.saveOrUpdate(mate); // save the new instance (mate has a null id)]]></programlisting> + + <para> + The usage and semantics of <literal>saveOrUpdate()</literal> seems to be confusing + for new users. Firstly, so long as you are not trying to use instances from one session + in another new session, you should not need to use <literal>update()</literal>, + <literal>saveOrUpdate()</literal>, or <literal>merge()</literal>. Some whole + applications will never use either of these methods. + </para> + + <para> + Usually <literal>update()</literal> or <literal>saveOrUpdate()</literal> are used in + the following scenario: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + the application loads an object in the first session + </para> + </listitem> + <listitem> + <para> + the object is passed up to the UI tier + </para> + </listitem> + <listitem> + <para> + some modifications are made to the object + </para> + </listitem> + <listitem> + <para> + the object is passed back down to the business logic tier + </para> + </listitem> + <listitem> + <para> + the application persists these modifications by calling + <literal>update()</literal> in a second session + </para> + </listitem> + </itemizedlist> + + <para> + <literal>saveOrUpdate()</literal> does the following: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + if the object is already persistent in this session, do nothing + </para> + </listitem> + <listitem> + <para> + if another object associated with the session has the same identifier, + throw an exception + </para> + </listitem> + <listitem> + <para> + if the object has no identifier property, <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + if the object's identifier has the value assigned to a newly instantiated + object, <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + if the object is versioned by a <literal>&lt;version&gt;</literal> or + <literal>&lt;timestamp&gt;</literal>, and the version property value + is the same value assigned to a newly instantiated object, + <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + otherwise <literal>update()</literal> the object + </para> + </listitem> + </itemizedlist> + + <para> + and <literal>merge()</literal> is very different: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + if there is a persistent instance with the same identifier currently + associated with the session, copy the state of the given object onto + the persistent instance + </para> + </listitem> + <listitem> + <para> + if there is no persistent instance currently associated with the session, + try to load it from the database, or create a new persistent instance + </para> + </listitem> + <listitem> + <para> + the persistent instance is returned + </para> + </listitem> + <listitem> + <para> + the given instance does not become associated with the session, it + remains detached + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="objectstate-deleting" revision="1"> + <title>Deleting persistent objects</title> + + <para> + <literal>Session.delete()</literal> will remove an object's state from the database. + Your application, however, can still hold a reference to a deleted object. + It is best to think of <literal>delete()</literal> as making a persistent instance, + transient. + </para> + + <programlisting role="JAVA"><![CDATA[sess.delete(cat);]]></programlisting> + + <para> + You can delete objects in any order, without risk of foreign key + constraint violations. It is still possible to violate a <literal>NOT + NULL</literal> constraint on a foreign key column by deleting objects in + the wrong order, e.g. if you delete the parent, but forget to delete the + children. + </para> + + </section> + + <section id="objectstate-replicating" revision="1"> + <title>Replicating object between two different datastores</title> + + <para> + It is sometimes useful to be able to take a graph of persistent instances + and make them persistent in a different datastore, without regenerating identifier + values. + </para> + + <programlisting role="JAVA"><![CDATA[//retrieve a cat from one database +Session session1 = factory1.openSession(); +Transaction tx1 = session1.beginTransaction(); +Cat cat = session1.get(Cat.class, catId); +tx1.commit(); +session1.close(); + +//reconcile with a second database +Session session2 = factory2.openSession(); +Transaction tx2 = session2.beginTransaction(); +session2.replicate(cat, ReplicationMode.LATEST_VERSION); +tx2.commit(); +session2.close();]]></programlisting> + + <para> + The <literal>ReplicationMode</literal> determines how <literal>replicate()</literal> + will deal with conflicts with existing rows in the database: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>ReplicationMode.IGNORE</literal>: ignores the object when there is + an existing database row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.OVERWRITE</literal>: overwrites any existing database + row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.EXCEPTION</literal>: throws an exception if there is + an existing database row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.LATEST_VERSION</literal>: overwrites the row if its + version number is earlier than the version number of the object, or ignore + the object otherwise + </para> + </listitem> + </itemizedlist> + + <para> + Usecases for this feature include reconciling data entered into different database + instances, upgrading system configuration information during product upgrades, + rolling back changes made during non-ACID transactions and more. + </para> + + </section> + + <section id="objectstate-flushing"> + <title>Flushing the Session</title> + + <para> + Sometimes the <literal>Session</literal> will execute the SQL statements + needed to synchronize the JDBC connection's state with the state of objects held in + memory. This process, called <emphasis>flush</emphasis>, occurs by default at the following + points: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + before some query executions + </para> + </listitem> + <listitem> + <para> + from <literal>org.hibernate.Transaction.commit()</literal> + </para> + </listitem> + <listitem> + <para> + from <literal>Session.flush()</literal> + </para> + </listitem> + </itemizedlist> + + <para> + The SQL statements are issued in the following order: + </para> + + <orderedlist spacing="compact"> + <listitem> + <para> + all entity insertions in the same order the corresponding objects + were saved using <literal>Session.save()</literal> + </para> + </listitem> + <listitem> + <para> + all entity updates + </para> + </listitem> + <listitem> + <para> + all collection deletions + </para> + </listitem> + <listitem> + <para> + all collection element deletions, updates and insertions + </para> + </listitem> + <listitem> + <para> + all collection insertions + </para> + </listitem> + <listitem> + <para> + all entity deletions in the same order the corresponding objects + were deleted using <literal>Session.delete()</literal> + </para> + </listitem> + </orderedlist> + + <para> + An exception is that objects using <literal>native</literal> ID generation are + inserted when they are saved. + </para> + + <para> + Except when you explicitly <literal>flush()</literal>, there are absolutely no + guarantees about <emphasis>when</emphasis> the <literal>Session</literal> executes + the JDBC calls, only the <emphasis>order</emphasis> in which they are executed. + However, Hibernate does guarantee that the <literal>Query.list(..)</literal> + will never return stale or incorrect data. + </para> + + <para> + It is possible to change the default behavior so that flush occurs less frequently. + The <literal>FlushMode</literal> class defines three different modes: only flush + at commit time when the Hibernate <literal>Transaction</literal> API + is used, flush automatically using the explained routine, or never flush unless + <literal>flush()</literal> is called explicitly. The last mode is useful for long running + units of work, where a <literal>Session</literal> is kept open and disconnected for + a long time (see <xref linkend="transactions-optimistic-longsession"/>). + </para> + + <programlisting role="JAVA"><![CDATA[sess = sf.openSession(); +Transaction tx = sess.beginTransaction(); +sess.setFlushMode(FlushMode.COMMIT); // allow queries to return stale state + +Cat izi = (Cat) sess.load(Cat.class, id); +izi.setName(iznizi); + +// might return stale data +sess.find("from Cat as cat left outer join cat.kittens kitten"); + +// change to izi is not flushed! +... +tx.commit(); // flush occurs +sess.close();]]></programlisting> + + <para> + During flush, an exception might occur (e.g. if a DML operation violates a constraint). + Since handling exceptions involves some understanding of Hibernate's transactional + behavior, we discuss it in <xref linkend="transactions"/>. + </para> + + </section> + + <section id="objectstate-transitive" revision="1"> + <title>Transitive persistence</title> + + <para> + It is quite cumbersome to save, delete, or reattach individual objects, + especially if you deal with a graph of associated objects. A common case is + a parent/child relationship. Consider the following example: + </para> + + <para> + If the children in a parent/child relationship would be value typed (e.g. a collection + of addresses or strings), their life cycle would depend on the parent and no + further action would be required for convenient "cascading" of state changes. + When the parent is saved, the value-typed child objects are saved and + when the parent is deleted, the children will be deleted, etc. This + works for operations such as the removal of a child from the collection. + Since value-typed objects cannot have shared + references, Hibernate will detect this and delete the child from the database. + </para> + + <para> + Now consider the same scenario with parent and child objects being entities, + not value-types (e.g. categories and items, or parent and child cats). Entities + have their own life cycle and support shared references. Removing an entity from + the collection does not mean it can be deleted), and there is by default no + cascading of state from one entity to any other associated entities. Hibernate + does not implement <emphasis>persistence by reachability</emphasis> by default. + </para> + + <para> + For each basic operation of the Hibernate session - including <literal>persist(), merge(), + saveOrUpdate(), delete(), lock(), refresh(), evict(), replicate()</literal> - there is a + corresponding cascade style. Respectively, the cascade styles are named <literal>create, + merge, save-update, delete, lock, refresh, evict, replicate</literal>. If you want an + operation to be cascaded along an association, you must indicate that in the mapping + document. For example: + </para> + + <programlisting role="XML"><![CDATA[<one-to-one name="person" cascade="persist"/>]]></programlisting> + + <para> + Cascade styles my be combined: + </para> + + <programlisting role="XML"><![CDATA[<one-to-one name="person" cascade="persist,delete,lock"/>]]></programlisting> + + <para> + You can even use <literal>cascade="all"</literal> to specify that <emphasis>all</emphasis> + operations should be cascaded along the association. The default <literal>cascade="none"</literal> + specifies that no operations are to be cascaded. + </para> + + <para> + A special cascade style, <literal>delete-orphan</literal>, applies only to one-to-many + associations, and indicates that the <literal>delete()</literal> operation should + be applied to any child object that is removed from the association. + </para> + + + <para> + Recommendations: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + It does not usually make sense to enable cascade on a <literal>&lt;many-to-one&gt;</literal> + or <literal>&lt;many-to-many&gt;</literal> association. Cascade is often useful for + <literal>&lt;one-to-one&gt;</literal> and <literal>&lt;one-to-many&gt;</literal> + associations. + </para> + </listitem> + <listitem> + <para> + If the child object's lifespan is bounded by the lifespan of the parent + object, make it a <emphasis>life cycle object</emphasis> by specifying + <literal>cascade="all,delete-orphan"</literal>. + </para> + </listitem> + <listitem> + <para> + Otherwise, you might not need cascade at all. But if you think that you will often be + working with the parent and children together in the same transaction, and you want to save + yourself some typing, consider using <literal>cascade="persist,merge,save-update"</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + Mapping an association (either a single valued association, or a collection) with + <literal>cascade="all"</literal> marks the association as a + <emphasis>parent/child</emphasis> style relationship where save/update/delete of the + parent results in save/update/delete of the child or children. + </para> + <para> + Furthermore, a mere reference to a child from a persistent parent will result in + save/update of the child. This metaphor is incomplete, however. A child which becomes + unreferenced by its parent is <emphasis>not</emphasis> automatically deleted, except + in the case of a <literal>&lt;one-to-many&gt;</literal> association mapped with + <literal>cascade="delete-orphan"</literal>. The precise semantics of cascading + operations for a parent/child relationship are as follows: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + If a parent is passed to <literal>persist()</literal>, all children are passed to + <literal>persist()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is passed to <literal>merge()</literal>, all children are passed to + <literal>merge()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is passed to <literal>save()</literal>, <literal>update()</literal> or + <literal>saveOrUpdate()</literal>, all children are passed to <literal>saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + If a transient or detached child becomes referenced by a persistent parent, + it is passed to <literal>saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is deleted, all children are passed to <literal>delete()</literal> + </para> + </listitem> + <listitem> + <para> + If a child is dereferenced by a persistent parent, <emphasis>nothing + special happens</emphasis> - the application should explicitly delete + the child if necessary - unless <literal>cascade="delete-orphan"</literal>, + in which case the "orphaned" child is deleted. + </para> + </listitem> + </itemizedlist> + + <para> + Finally, note that cascading of operations can be applied to an object graph at + <emphasis>call time</emphasis> or at <emphasis>flush time</emphasis>. All operations, + if enabled, are cascaded to associated entities reachable when the operation is + executed. However, <literal>save-update</literal> and <literal>delete-orphan</literal> + are transitive for all associated entities reachable during flush of the + <literal>Session</literal>. + </para> + + </section> + + <section id="objectstate-metadata"> + <title>Using metadata</title> + + <para> + Hibernate requires a rich meta-level model of all entity and value types. + This model can be useful to the application itself. For example, the application + might use Hibernate's metadata to implement a "smart" deep-copy algorithm that understands + which objects should be copied (eg. mutable value types) and which objects that should not (e.g. + immutable value types and, possibly, associated entities). + </para> + <para> + Hibernate exposes metadata via the <literal>ClassMetadata</literal> and + <literal>CollectionMetadata</literal> interfaces and the <literal>Type</literal> + hierarchy. Instances of the metadata interfaces can be obtained from the + <literal>SessionFactory</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[Cat fritz = ......; +ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.class); + +Object[] propertyValues = catMeta.getPropertyValues(fritz); +String[] propertyNames = catMeta.getPropertyNames(); +Type[] propertyTypes = catMeta.getPropertyTypes(); + +// get a Map of all properties which are not collections or associations +Map namedValues = new HashMap(); +for ( int i=0; i<propertyNames.length; i++ ) { + if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].isCollectionType() ) { + namedValues.put( propertyNames[i], propertyValues[i] ); + } +}]]></programlisting> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/toolset_guide.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/toolset_guide.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/toolset_guide.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,640 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="toolsetguide" revision="2"> + <title>Toolset Guide</title> + + <para> + Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins, + commandline tools, and Ant tasks. + </para> + + <para> + <emphasis>Hibernate Tools</emphasis> currently include plugins for the Eclipse + IDE as well as Ant tasks for reverse engineering of existing databases: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>Mapping Editor:</emphasis> an editor for Hibernate XML mapping files that + supports auto-completion and syntax highlighting. It also supports semantic + auto-completion for class names and property/field names, making it more versatile than a normal XML editor. + </para></listitem> + <listitem><para> + <emphasis>Console:</emphasis> the console is a new view in Eclipse. In addition to + a tree overview of your console configurations, you are also provided with an interactive view + of your persistent classes and their relationships. The console allows you to + execute HQL queries against your database and browse the result directly in + Eclipse. + </para></listitem> + <listitem><para> + <emphasis>Development Wizards:</emphasis> several wizards are provided with the + Hibernate Eclipse tools. You can use a wizard to quickly generate Hibernate configuration + (cfg.xml) files, or to reverse engineer an existing database schema + into POJO source files and Hibernate mapping files. The reverse engineering wizard + supports customizable templates. + </para></listitem> + <listitem><para> +<!-- <emphasis>Ant Tasks:</emphasis> --> + </para></listitem> + + </itemizedlist> + + <para> + Please refer to the <emphasis>Hibernate Tools</emphasis> package documentation + for more information. + </para> + + <para> + However, the Hibernate main package comes bundled with an integrated tool : <emphasis>SchemaExport</emphasis> aka + <literal>hbm2ddl</literal>.It can even + be used from "inside" Hibernate. + </para> + + <section id="toolsetguide-s1" revision="2"> + <title>Automatic schema generation</title> + + <para> + DDL can be generated from your mapping files by a Hibernate utility. The generated + schema includes referential integrity constraints, primary and foreign keys, for + entity and collection tables. Tables and sequences are also created for mapped + identifier generators. + </para> + + <para> + You <emphasis>must</emphasis> specify a SQL <literal>Dialect</literal> via the + <literal>hibernate.dialect</literal> property when using this tool, as DDL + is highly vendor-specific. + </para> + + <para> + First, you must customize your mapping files to improve the generated schema. The next section covers schema customization. + </para> + + <section id="toolsetguide-s1-2" revision="3"> + <title>Customizing the schema</title> + + <para> + Many Hibernate mapping elements define optional attributes named <literal>length</literal>, + <literal>precision</literal> and <literal>scale</literal>. You can set the length, precision + and scale of a column with this attribute. + + </para> + + <programlisting role="XML"><![CDATA[<property name="zip" length="5"/>]]></programlisting> + <programlisting role="XML"><![CDATA[<property name="balance" precision="12" scale="2"/>]]></programlisting> + + <para> + Some tags also accept a <literal>not-null</literal> attribute for generating a + <literal>NOT NULL</literal> constraint on table columns, and a <literal>unique</literal> + attribute for generating <literal>UNIQUE</literal> constraint on table columns. + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="bar" column="barId" not-null="true"/>]]></programlisting> + + <programlisting role="XML"><![CDATA[<element column="serialNumber" type="long" not-null="true" unique="true"/>]]></programlisting> + + <para> + A <literal>unique-key</literal> attribute can be used to group columns in + a single, unique key constraint. Currently, the specified value of the + <literal>unique-key</literal> attribute is <emphasis>not</emphasis> used + to name the constraint in the generated DDL. It is only used to group the columns in + the mapping file. + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/> +<property name="employeeId" unique-key="OrgEmployee"/>]]></programlisting> + + <para> + An <literal>index</literal> attribute specifies the name of an index that + will be created using the mapped column or columns. Multiple columns can be + grouped into the same index by simply specifying the same index name. + </para> + + <programlisting role="XML"><![CDATA[<property name="lastName" index="CustName"/> +<property name="firstName" index="CustName"/>]]></programlisting> + + <para> + A <literal>foreign-key</literal> attribute can be used to override the name + of any generated foreign key constraint. + </para> + + <programlisting role="XML"><![CDATA[<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>]]></programlisting> + + <para> + Many mapping elements also accept a child <literal>&lt;column&gt;</literal> element. + This is particularly useful for mapping multi-column types: + </para> + + <programlisting role="XML"><![CDATA[<property name="name" type="my.customtypes.Name"/> + <column name="last" not-null="true" index="bar_idx" length="30"/> + <column name="first" not-null="true" index="bar_idx" length="20"/> + <column name="initial"/> +</property>]]></programlisting> + + <para> + The <literal>default</literal> attribute allows you to specify a default value for + a column.You should assign the same value to the mapped property before + saving a new instance of the mapped class. + </para> + + <programlisting role="XML"><![CDATA[<property name="credits" type="integer" insert="false"> + <column name="credits" default="10"/> +</property>]]></programlisting> + + <programlisting role="XML"><![CDATA[<version name="version" type="integer" insert="false"> + <column name="version" default="0"/> +</property>]]></programlisting> + + <para> + The <literal>sql-type</literal> attribute allows the user to override the default + mapping of a Hibernate type to SQL datatype. + </para> + + <programlisting role="XML"><![CDATA[<property name="balance" type="float"> + <column name="balance" sql-type="decimal(13,3)"/> +</property>]]></programlisting> + + <para> + The <literal>check</literal> attribute allows you to specify a check constraint. + </para> + + <programlisting role="XML"><![CDATA[<property name="foo" type="integer"> + <column name="foo" check="foo > 10"/> +</property>]]></programlisting> + + <programlisting role="XML"><![CDATA[<class name="Foo" table="foos" check="bar < 100.0"> + ... + <property name="bar" type="float"/> +</class>]]></programlisting> + + + <para>The following table summarizes these optional attributes.</para> + + <table frame="topbot" id="schemattributes-summary" revision="2"> + <title>Summary</title> + <tgroup cols="3"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> + <thead> + <row> + <entry>Attribute</entry> + <entry>Values</entry> + <entry>Interpretation</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>length</literal></entry> + <entry>number</entry> + <entry>column length</entry> + </row> + <row> + <entry><literal>precision</literal></entry> + <entry>number</entry> + <entry>column decimal precision</entry> + </row> + <row> + <entry><literal>scale</literal></entry> + <entry>number</entry> + <entry>column decimal scale</entry> + </row> + <row> + <entry><literal>not-null</literal></entry> + <entry><literal>true|false</literal></entry> + <entry>specifies that the column should be non-nullable</entry> + </row> + <row> + <entry><literal>unique</literal></entry> + <entry><literal>true|false</literal></entry> + <entry>specifies that the column should have a unique constraint</entry> + </row> + <row> + <entry><literal>index</literal></entry> + <entry><literal>index_name</literal></entry> + <entry>specifies the name of a (multi-column) index</entry> + </row> + <row> + <entry><literal>unique-key</literal></entry> + <entry><literal>unique_key_name</literal></entry> + <entry>specifies the name of a multi-column unique constraint</entry> + </row> + <row> + <entry><literal>foreign-key</literal></entry> + <entry><literal>foreign_key_name</literal></entry> + <entry> + specifies the name of the foreign key constraint generated + for an association, for a <literal>&lt;one-to-one&gt;</literal>, + <literal>&lt;many-to-one&gt;</literal>, <literal>&lt;key&gt;</literal>, + or <literal>&lt;many-to-many&gt;</literal> mapping element. Note that + <literal>inverse="true"</literal> sides will not be considered + by <literal>SchemaExport</literal>. + </entry> + </row> + <row> + <entry><literal>sql-type</literal></entry> + <entry><literal>SQL column type</literal></entry> + <entry> + overrides the default column type (attribute of + <literal>&lt;column&gt;</literal> element only) + </entry> + </row> + <row> + <entry><literal>default</literal></entry> + <entry>SQL expression</entry> + <entry> + specify a default value for the column + </entry> + </row> + <row> + <entry><literal>check</literal></entry> + <entry>SQL expression</entry> + <entry> + create an SQL check constraint on either column or table + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The <literal>&lt;comment&gt;</literal> element allows you to specify comments + for the generated schema. + </para> + + <programlisting role="XML"><![CDATA[<class name="Customer" table="CurCust"> + <comment>Current customers only</comment> + ... +</class>]]></programlisting> + + <programlisting role="XML"><![CDATA[<property name="balance"> + <column name="bal"> + <comment>Balance in USD</comment> + </column> +</property>]]></programlisting> + + <para> + This results in a <literal>comment on table</literal> or + <literal>comment on column</literal> statement in the generated + DDL where supported. + </para> + + </section> + + <section id="toolsetguide-s1-3" revision="2"> + <title>Running the tool</title> + + <para> + The <literal>SchemaExport</literal> tool writes a DDL script to standard out and/or + executes the DDL statements. + </para> + + <para>The following table displays the <literal>SchemaExport</literal> command line options</para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>options mapping_files</emphasis> + </para> + + <table frame="topbot"> + <title><literal>SchemaExport</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--quiet</literal></entry> + <entry>do not output the script to stdout</entry> + </row> + <row> + <entry><literal>--drop</literal></entry> + <entry>only drop the tables</entry> + </row> + <row> + <entry><literal>--create</literal></entry> + <entry>only create the tables</entry> + </row> + <row> + <entry><literal>--text</literal></entry> + <entry>do not export to the database</entry> + </row> + <row> + <entry><literal>--output=my_schema.ddl</literal></entry> + <entry>output the ddl script to a file</entry> + </row> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>read Hibernate configuration from an XML file</entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--format</literal></entry> + <entry>format the generated SQL nicely in the script</entry> + </row> + <row> + <entry><literal>--delimiter=;</literal></entry> + <entry>set an end of line delimiter for the script</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You can even embed <literal>SchemaExport</literal> in your application: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = ....; +new SchemaExport(cfg).create(false, true);]]></programlisting> + + </section> + + <section id="toolsetguide-s1-4"> + <title>Properties</title> + + <para> + Database properties can be specified: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para>as system properties with <literal>-D</literal><emphasis>&lt;property&gt;</emphasis></para> + </listitem> + <listitem> + <para>in <literal>hibernate.properties</literal></para> + </listitem> + <listitem> + <para>in a named properties file with <literal>--properties</literal></para> + </listitem> + </itemizedlist> + + <para> + The needed properties are: + </para> + + <table frame="topbot"> + <title>SchemaExport Connection Properties</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Property Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>hibernate.connection.driver_class</literal></entry> + <entry>jdbc driver class</entry> + </row> + <row> + <entry><literal>hibernate.connection.url</literal></entry> + <entry>jdbc url</entry> + </row> + <row> + <entry><literal>hibernate.connection.username</literal></entry> + <entry>database user</entry> + </row> + <row> + <entry><literal>hibernate.connection.password</literal></entry> + <entry>user password</entry> + </row> + <row> + <entry><literal>hibernate.dialect</literal></entry> + <entry>dialect</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="toolsetguide-s1-5"> + <title>Using Ant</title> + + <para> + You can call <literal>SchemaExport</literal> from your Ant build script: + </para> + + <programlisting role="XML"><![CDATA[<target name="schemaexport"> + <taskdef name="schemaexport" + classname="org.hibernate.tool.hbm2ddl.SchemaExportTask" + classpathref="class.path"/> + + <schemaexport + properties="hibernate.properties" + quiet="no" + text="no" + drop="no" + delimiter=";" + output="schema-export.sql"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemaexport> +</target>]]></programlisting> + + </section> + + <section id="toolsetguide-s1-6" revision="2"> + <title>Incremental schema updates</title> + + <para> + The <literal>SchemaUpdate</literal> tool will update an existing schema with "incremental" changes. + The <literal>SchemaUpdate</literal> depends upon the JDBC metadata API and, as such, will + not work with all JDBC drivers. + </para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options mapping_files</emphasis> + </para> + + <table frame="topbot"> + <title><literal>SchemaUpdate</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--quiet</literal></entry> + <entry>do not output the script to stdout</entry> + </row> + <row> + <entry><literal>--text</literal></entry> + <entry>do not export the script to the database</entry> + </row> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>specify a <literal>.cfg.xml</literal> file</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You can embed <literal>SchemaUpdate</literal> in your application: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = ....; +new SchemaUpdate(cfg).execute(false);]]></programlisting> + + </section> + + <section id="toolsetguide-s1-7"> + <title>Using Ant for incremental schema updates</title> + + <para> + You can call <literal>SchemaUpdate</literal> from the Ant script: + </para> + + <programlisting role="XML"><![CDATA[<target name="schemaupdate"> + <taskdef name="schemaupdate" + classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask" + classpathref="class.path"/> + + <schemaupdate + properties="hibernate.properties" + quiet="no"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemaupdate> +</target>]]></programlisting> + + </section> + + <section id="toolsetguide-s1-8" revision="1"> + <title>Schema validation</title> + + <para> + The <literal>SchemaValidator</literal> tool will validate that the existing database schema "matches" + your mapping documents. The <literal>SchemaValidator</literal> depends heavily upon the JDBC + metadata API and, as such, will not work with all JDBC drivers. This tool is extremely useful for testing. + </para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> <emphasis>options mapping_files</emphasis> + </para> + <para>The following table displays the <literal>SchemaValidator</literal> command line options: + </para> + <table frame="topbot"> + <title><literal>SchemaValidator</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>specify a <literal>.cfg.xml</literal> file</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You can embed <literal>SchemaValidator</literal> in your application: + </para> + + <programlisting role="JAVA"><![CDATA[Configuration cfg = ....; +new SchemaValidator(cfg).validate();]]></programlisting> + + </section> + + <section id="toolsetguide-s1-9"> + <title>Using Ant for schema validation</title> + + <para> + You can call <literal>SchemaValidator</literal> from the Ant script: + </para> + + <programlisting role="XML"><![CDATA[<target name="schemavalidate"> + <taskdef name="schemavalidator" + classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask" + classpathref="class.path"/> + + <schemavalidator + properties="hibernate.properties"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemavalidator> +</target>]]></programlisting> + + </section> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/transactions.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/transactions.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/transactions.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1157 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="transactions" revision="2"> + <title>Transactions and Concurrency</title> + + <para> + The most important point about Hibernate and concurrency control is that it is + easy to understand. Hibernate directly uses JDBC connections and JTA resources without + adding any additional locking behavior. It is recommended that you spend some time with the + JDBC, ANSI, and transaction isolation specification of your database management system. + </para> + + <para> + Hibernate does not lock objects in memory. Your application can expect the behavior as + defined by the isolation level of your database transactions. Through + <literal>Session</literal>, which is also a transaction-scoped cache, Hibernate + provides repeatable reads for lookup by identifier and entity queries and not + reporting queries that return scalar values. + </para> + + <para> + In addition to versioning for automatic optimistic concurrency control, Hibernate also + offers, using the + <literal>SELECT FOR UPDATE</literal> syntax, a (minor) API for pessimistic locking of rows. Optimistic concurrency control and + this API are discussed later in this chapter. + </para> + + <para> + The discussion of concurrency control in Hibernate begins with the granularity of + <literal>Configuration</literal>, <literal>SessionFactory</literal>, and + <literal>Session</literal>, as well as database transactions and long conversations. + </para> + + <section id="transactions-basics" revision="1"> + <title>Session and transaction scopes</title> + + <para> + A <literal>SessionFactory</literal> is an expensive-to-create, threadsafe object, + intended to be shared by all application threads. It is created once, usually on + application startup, from a <literal>Configuration</literal> instance. + </para> + + <para> + A <literal>Session</literal> is an inexpensive, non-threadsafe object that should be + used once and then discarded for: a single request, a conversation or a single unit of work. + A <literal>Session</literal> will not obtain a JDBC <literal>Connection</literal>, + or a <literal>Datasource</literal>, unless it is needed. It will not consume any + resources until used. + </para> + + <para> + In order to reduce lock contention in the database, a database transaction has to be as short as possible. + Long database transactions will prevent your application from scaling + to a highly concurrent load. It is not recommended that you hold a + database transaction open during user think time until the unit of work is + complete. + </para> + + <para> + What is the scope of a unit of work? Can a single Hibernate <literal>Session</literal> + span several database transactions, or is this a one-to-one relationship of scopes? When + should you open and close a <literal>Session</literal> and how do you demarcate the + database transaction boundaries? These questions are addressed in the following sections. + </para> + + <section id="transactions-basics-uow" revision="1"> + <title>Unit of work</title> + + <para> + First, let's define a unit of work. A unit of work is a + design pattern described by Martin Fowler as + <quote> + [maintaining] a list of objects affected by a business + transaction and coordinates the writing out of changes + and the resolution of concurrency problems. + </quote><citation>PoEAA</citation> + In other words, its a series of operations we wish to carry out + against the database together. Basically, it is a transaction, + though fulfilling a unit of work will often span multiple + physical database transactions (see <xref linkend="transactions-basics-apptx"/>). + So really we are talking about a more abstract notion of a + transaction. The term "business transaction" is also sometimes + used in lieu of unit of work. + </para> + + <para> + Do not use the <emphasis>session-per-operation</emphasis> antipattern: + do not open and close a <literal>Session</literal> for every simple database call in + a single thread. The same is true for database transactions. Database calls + in an application are made using a planned sequence; they are grouped into atomic + units of work. This also means that auto-commit after every single + SQL statement is useless in an application as this mode is intended for ad-hoc SQL + console work. Hibernate disables, or expects the application server to disable, + auto-commit mode immediately. Database transactions are never optional. All + communication with a database has to occur inside a transaction. Auto-commit behavior for reading data + should be avoided, as many small transactions are unlikely to perform better than + one clearly defined unit of work. The latter is also more maintainable + and extensible. + </para> + + <para> + The most common pattern in a multi-user client/server application is + <emphasis>session-per-request</emphasis>. In this model, a request from the client + is sent to the server, where the Hibernate persistence layer runs. A new Hibernate + <literal>Session</literal> is opened, and all database operations are executed in this unit + of work. On completion of the work, and once the response for the client has been prepared, + the session is flushed and closed. Use a single database transaction to + serve the clients request, starting and committing it when you open and close the + <literal>Session</literal>. The relationship between the two is one-to-one and this + model is a perfect fit for many applications. + </para> + + <para> + The challenge lies in the implementation. Hibernate provides built-in management of + the "current session" to simplify this pattern. Start a + transaction when a server request has to be processed, and end the transaction + before the response is sent to the client. Common solutions are <literal>ServletFilter</literal>, AOP interceptor with a + pointcut on the service methods, or a proxy/interception container. An EJB container + is a standardized way to implement cross-cutting aspects such as transaction + demarcation on EJB session beans, declaratively with CMT. If you + use programmatic transaction demarcation, for ease of use and code portability use the Hibernate <literal>Transaction</literal> + API shown later in this chapter. + </para> + + <para> + Your application code can access a "current session" to process the request + by calling <literal>sessionFactory.getCurrentSession()</literal>. + You will always get a <literal>Session</literal> scoped + to the current database transaction. This has to be configured for either + resource-local or JTA environments, see <xref linkend="architecture-current-session"/>. + </para> + + <para> + You can extend the scope of a <literal>Session</literal> and + database transaction until the "view has been rendered". This is especially useful + in servlet applications that utilize a separate rendering phase after the request + has been processed. Extending the database transaction until view rendering, is achieved by implementing + your own interceptor. However, this will be difficult + if you rely on EJBs with container-managed transactions. A + transaction will be completed when an EJB method returns, before rendering of any + view can start. See the Hibernate website and forum for tips and examples relating to + this <emphasis>Open Session in View</emphasis> pattern. + </para> + + </section> + + <section id="transactions-basics-apptx" revision="1"> + <title>Long conversations</title> + + <para> + The session-per-request pattern is not the only way of designing + units of work. Many business processes require a whole series of interactions with the user that are + interleaved with database accesses. In web and enterprise applications, it is + not acceptable for a database transaction to span a user interaction. Consider the following + example: + </para> + + <itemizedlist> + <listitem> + <para> + The first screen of a dialog opens. The data seen by the user has been loaded in + a particular <literal>Session</literal> and database transaction. The user is free to + modify the objects. + </para> + </listitem> + <listitem> + <para> + The user clicks "Save" after 5 minutes and expects their modifications to be made + persistent. The user also expects that they were the only person editing this information and + that no conflicting modification has occurred. + </para> + </listitem> + </itemizedlist> + + <para> + From the point of view of the user, we call this unit of work a long-running + <emphasis>conversation</emphasis> or <emphasis>application transaction</emphasis>. + There are many ways to implement this in your application. + </para> + + <para> + A first naive implementation might keep the <literal>Session</literal> and database + transaction open during user think time, with locks held in the database to prevent + concurrent modification and to guarantee isolation and atomicity. This is + an anti-pattern, since lock contention would not allow the application to scale with + the number of concurrent users. + </para> + + <para> + You have to use several database transactions to implement the conversation. + In this case, maintaining isolation of business processes becomes the + partial responsibility of the application tier. A single conversation + usually spans several database transactions. It will be atomic if only one of + these database transactions (the last one) stores the updated data. All others + simply read data (for example, in a wizard-style dialog spanning several request/response + cycles). This is easier to implement than it might sound, especially if + you utilize some of Hibernate's features: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Automatic Versioning</emphasis>: Hibernate can perform automatic + optimistic concurrency control for you. It can automatically detect + if a concurrent modification occurred during user think time. Check for this at + the end of the conversation. + </para> + </listitem> + <listitem> + <para> + <emphasis>Detached Objects</emphasis>: if you decide to use the + <emphasis>session-per-request</emphasis> pattern, all loaded instances + will be in the detached state during user think time. Hibernate allows you to + reattach the objects and persist the modifications. The pattern is called + <emphasis>session-per-request-with-detached-objects</emphasis>. Automatic + versioning is used to isolate concurrent modifications. + </para> + </listitem> + <listitem> + <para> + <emphasis>Extended (or Long) Session</emphasis>: the Hibernate + <literal>Session</literal> can be disconnected from the underlying JDBC + connection after the database transaction has been committed and reconnected + when a new client request occurs. This pattern is known as + <emphasis>session-per-conversation</emphasis> and makes + even reattachment unnecessary. Automatic versioning is used to isolate + concurrent modifications and the <literal>Session</literal> will not + be allowed to be flushed automatically, but explicitly. + </para> + </listitem> + </itemizedlist> + + <para> + Both <emphasis>session-per-request-with-detached-objects</emphasis> and + <emphasis>session-per-conversation</emphasis> have advantages and disadvantages. + These disadvantages are discussed later in this chapter in the context of optimistic concurrency control. + </para> + + </section> + + <section id="transactions-basics-identity"> + <title>Considering object identity</title> + + <para> + An application can concurrently access the same persistent state in two + different <literal>Session</literal>s. However, an instance of a persistent class + is never shared between two <literal>Session</literal> instances. It is for this reason that there are + two different notions of identity: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term>Database Identity</term> + <listitem> + <para> + <literal>foo.getId().equals( bar.getId() )</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>JVM Identity</term> + <listitem> + <para> + <literal>foo==bar</literal> + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + For objects attached to a <emphasis>particular</emphasis> <literal>Session</literal> + (i.e., in the scope of a <literal>Session</literal>), the two notions are equivalent and + JVM identity for database identity is guaranteed by Hibernate. While the application + might concurrently access the "same" (persistent identity) business object in two different + sessions, the two instances will actually be "different" (JVM identity). Conflicts are + resolved using an optimistic approach and automatic versioning at flush/commit time. + </para> + + <para> + This approach leaves Hibernate and the database to worry about concurrency. It also provides + the best scalability, since guaranteeing identity in single-threaded units of work means that it does not + need expensive locking or other means of synchronization. The application does not need to + synchronize on any business object, as long as it maintains a single thread per + <literal>Session</literal>. Within a <literal>Session</literal> the application can safely use + <literal>==</literal> to compare objects. + </para> + + <para> + However, an application that uses <literal>==</literal> outside of a <literal>Session</literal> + might produce unexpected results. This might occur even in some unexpected places. For example, + if you put two detached instances into the same <literal>Set</literal>, both might have the same + database identity (i.e., they represent the same row). JVM identity, however, is by definition not + guaranteed for instances in a detached state. The developer has to override the <literal>equals()</literal> + and <literal>hashCode()</literal> methods in persistent classes and implement + their own notion of object equality. There is one caveat: never use the database + identifier to implement equality. Use a business key that is a combination of unique, usually + immutable, attributes. The database identifier will change if a transient object is made + persistent. If the transient instance (usually together with detached instances) is held in a + <literal>Set</literal>, changing the hashcode breaks the contract of the <literal>Set</literal>. + Attributes for business keys do not have to be as stable as database primary keys; you only + have to guarantee stability as long as the objects are in the same <literal>Set</literal>. See + the Hibernate website for a more thorough discussion of this issue. Please note that this is not + a Hibernate issue, but simply how Java object identity and equality has to be implemented. + </para> + + </section> + + <section id="transactions-basics-issues"> + <title>Common issues</title> + + <para> + Do not use the anti-patterns <emphasis>session-per-user-session</emphasis> or + <emphasis>session-per-application</emphasis> (there are, however, rare exceptions to + this rule). Some of the following issues might also arise within the recommended + patterns, so ensure that you understand the implications before making a design decision: + </para> + + <itemizedlist> + <listitem> + <para> + A <literal>Session</literal> is not thread-safe. Things that work + concurrently, like HTTP requests, session beans, or Swing workers, will cause race + conditions if a <literal>Session</literal> instance is shared. If you keep your + Hibernate <literal>Session</literal> in your <literal>HttpSession</literal> (this is discussed + later in the chapter), you should consider synchronizing access to your Http session. Otherwise, + a user that clicks reload fast enough can use the same <literal>Session</literal> in + two concurrently running threads. + </para> + </listitem> + <listitem> + <para> + An exception thrown by Hibernate means you have to rollback your database transaction + and close the <literal>Session</literal> immediately (this is discussed in more detail later in the chapter). + If your <literal>Session</literal> is bound to the application, you have to stop + the application. Rolling back the database transaction does not put your business + objects back into the state they were at the start of the transaction. This means that the + database state and the business objects will be out of sync. Usually this is not a + problem, because exceptions are not recoverable and you will have to start over after + rollback anyway. + </para> + </listitem> + <listitem> + <para> + The <literal>Session</literal> caches every object that is in a persistent state (watched + and checked for dirty state by Hibernate). If you keep it open for a long time or simply load too + much data, it will grow endlessly until you + get an OutOfMemoryException. One solution is to call <literal>clear()</literal> and <literal>evict()</literal> + to manage the <literal>Session</literal> cache, but you should consider a + Stored Procedure if you need mass data operations. Some solutions are shown in + <xref linkend="batch"/>. Keeping a <literal>Session</literal> open for the duration + of a user session also means a higher probability of stale data. + </para> + </listitem> + </itemizedlist> + + </section> + + </section> + + <section id="transactions-demarcation"> + <title>Database transaction demarcation</title> + + <para> + Database, or system, transaction boundaries are always necessary. No communication with + the database can occur outside of a database transaction (this seems to confuse many developers + who are used to the auto-commit mode). Always use clear transaction boundaries, even for + read-only operations. Depending on your isolation level and database capabilities this might not + be required, but there is no downside if you always demarcate transactions explicitly. Certainly, + a single database transaction is going to perform better than many small transactions, even + for reading data. + </para> + + <para> + A Hibernate application can run in non-managed (i.e., standalone, simple Web- or Swing applications) + and managed J2EE environments. In a non-managed environment, Hibernate is usually responsible for + its own database connection pool. The application developer has to manually set transaction + boundaries (begin, commit, or rollback database transactions) themselves. A managed environment + usually provides container-managed transactions (CMT), with the transaction assembly defined declaratively + (in deployment descriptors of EJB session beans, for example). Programmatic transaction demarcation is + then no longer necessary. + </para> + + <para> + However, it is often desirable to keep your persistence layer portable between non-managed + resource-local environments, and systems that can rely on JTA but use BMT instead of CMT. + In both cases use programmatic transaction demarcation. Hibernate offers a wrapper + API called <literal>Transaction</literal> that translates into the native transaction system of + your deployment environment. This API is actually optional, but we strongly encourage its use + unless you are in a CMT session bean. + </para> + + <para> + Ending a <literal>Session</literal> usually involves four distinct phases: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + flush the session + </para> + </listitem> + <listitem> + <para> + commit the transaction + </para> + </listitem> + <listitem> + <para> + close the session + </para> + </listitem> + <listitem> + <para> + handle exceptions + </para> + </listitem> + </itemizedlist> + + <para> + We discussed Flushing the session earlier, so we will now have a closer look at transaction + demarcation and exception handling in both managed and non-managed environments. + </para> + + + <section id="transactions-demarcation-nonmanaged" revision="2"> + <title>Non-managed environment</title> + + <para> + If a Hibernate persistence layer runs in a non-managed environment, database connections + are usually handled by simple (i.e., non-DataSource) connection pools from which + Hibernate obtains connections as needed. The session/transaction handling idiom looks + like this: + </para> + + <programlisting role="JAVA"><![CDATA[// Non-managed environment idiom +Session sess = factory.openSession(); +Transaction tx = null; +try { + tx = sess.beginTransaction(); + + // do some work + ... + + tx.commit(); +} +catch (RuntimeException e) { + if (tx != null) tx.rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + You do not have to <literal>flush()</literal> the <literal>Session</literal> explicitly: + the call to <literal>commit()</literal> automatically triggers the synchronization depending + on the <link linkend="objectstate-flushing">FlushMode</link> for the session. + A call to <literal>close()</literal> marks the end of a session. The main implication + of <literal>close()</literal> is that the JDBC connection will be relinquished by the + session. This Java code is portable and runs in both non-managed and JTA environments. + </para> + + <para> + As outlined earlier, a much more flexible solution is Hibernate's built-in "current session" context + management: + </para> + + <programlisting role="JAVA"><![CDATA[// Non-managed environment idiom with getCurrentSession() +try { + factory.getCurrentSession().beginTransaction(); + + // do some work + ... + + factory.getCurrentSession().getTransaction().commit(); +} +catch (RuntimeException e) { + factory.getCurrentSession().getTransaction().rollback(); + throw e; // or display error message +}]]></programlisting> + + <para> + You will not see these code snippets in a regular application; + fatal (system) exceptions should always be caught at the "top". In other words, the + code that executes Hibernate calls in the persistence layer, and the code that handles + <literal>RuntimeException</literal> (and usually can only clean up and exit), are in + different layers. The current context management by Hibernate can significantly + simplify this design by accessing a <literal>SessionFactory</literal>. + Exception handling is discussed later in this chapter. + </para> + + <para> + You should select <literal>org.hibernate.transaction.JDBCTransactionFactory</literal>, + which is the default, and for the second example select <literal>"thread"</literal> as your + <literal>hibernate.current_session_context_class</literal>. + </para> + + </section> + + <section id="transactions-demarcation-jta" revision="3"> + <title>Using JTA</title> + + <para> + If your persistence layer runs in an application server (for example, behind EJB session beans), + every datasource connection obtained by Hibernate will automatically be part of the global + JTA transaction. You can also install a standalone JTA implementation and use it without + EJB. Hibernate offers two strategies for JTA integration. + </para> + + <para> + If you use bean-managed transactions (BMT), Hibernate will tell the application server to start + and end a BMT transaction if you use the <literal>Transaction</literal> API. The + transaction management code is identical to the non-managed environment. + </para> + + <programlisting role="JAVA"><![CDATA[// BMT idiom +Session sess = factory.openSession(); +Transaction tx = null; +try { + tx = sess.beginTransaction(); + + // do some work + ... + + tx.commit(); +} +catch (RuntimeException e) { + if (tx != null) tx.rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + If you want to use a transaction-bound <literal>Session</literal>, that is, the + <literal>getCurrentSession()</literal> functionality for easy context propagation, + use the JTA <literal>UserTransaction</literal> API directly: + </para> + + <programlisting role="JAVA"><![CDATA[// BMT idiom with getCurrentSession() +try { + UserTransaction tx = (UserTransaction)new InitialContext() + .lookup("java:comp/UserTransaction"); + + tx.begin(); + + // Do some work on Session bound to transaction + factory.getCurrentSession().load(...); + factory.getCurrentSession().persist(...); + + tx.commit(); +} +catch (RuntimeException e) { + tx.rollback(); + throw e; // or display error message +}]]></programlisting> + + <para> + With CMT, transaction demarcation is completed in session bean deployment descriptors, not programmatically. + The code is reduced to: + </para> + + <programlisting role="JAVA"><![CDATA[// CMT idiom + Session sess = factory.getCurrentSession(); + + // do some work + ... +]]></programlisting> + + <para> + In a CMT/EJB, even rollback happens automatically. An unhandled <literal>RuntimeException</literal> + thrown by a session bean method tells the container to set the global transaction to rollback. + <emphasis>You do not need to use the Hibernate <literal>Transaction</literal> API at + all with BMT or CMT, and you get automatic propagation of the "current" Session bound to the + transaction.</emphasis> + </para> + + <para> + When configuring Hibernate's transaction factory, choose <literal>org.hibernate.transaction.JTATransactionFactory</literal> + if you use JTA directly (BMT), and <literal>org.hibernate.transaction.CMTTransactionFactory</literal> + in a CMT session bean. Remember to also set + <literal>hibernate.transaction.manager_lookup_class</literal>. Ensure + that your <literal>hibernate.current_session_context_class</literal> is either unset (backwards + compatibility), or is set to <literal>"jta"</literal>. + </para> + + <para> + The <literal>getCurrentSession()</literal> operation has one downside in a JTA environment. + There is one caveat to the use of <literal>after_statement</literal> connection release + mode, which is then used by default. Due to a limitation of the JTA spec, it is not + possible for Hibernate to automatically clean up any unclosed <literal>ScrollableResults</literal> or + <literal>Iterator</literal> instances returned by <literal>scroll()</literal> or + <literal>iterate()</literal>. You <emphasis>must</emphasis> release the underlying database + cursor by calling <literal>ScrollableResults.close()</literal> or + <literal>Hibernate.close(Iterator)</literal> explicitly from a <literal>finally</literal> + block. Most applications can easily avoid using <literal>scroll()</literal> or + <literal>iterate()</literal> from the JTA or CMT code.) + </para> + + </section> + + <section id="transactions-demarcation-exceptions"> + <title>Exception handling</title> + + <para> + If the <literal>Session</literal> throws an exception, including any + <literal>SQLException</literal>, immediately rollback the database + transaction, call <literal>Session.close()</literal> and discard the + <literal>Session</literal> instance. Certain methods of <literal>Session</literal> + will <emphasis>not</emphasis> leave the session in a consistent state. No + exception thrown by Hibernate can be treated as recoverable. Ensure that the + <literal>Session</literal> will be closed by calling <literal>close()</literal> + in a <literal>finally</literal> block. + </para> + + <para> + The <literal>HibernateException</literal>, which wraps most of the errors that + can occur in a Hibernate persistence layer, is an unchecked exception. It was not + in older versions of Hibernate. In our opinion, we should not force the application + developer to catch an unrecoverable exception at a low layer. In most systems, unchecked + and fatal exceptions are handled in one of the first frames of the method call + stack (i.e., in higher layers) and either an error message is presented to the application + user or some other appropriate action is taken. Note that Hibernate might also throw + other unchecked exceptions that are not a <literal>HibernateException</literal>. These + are not recoverable and appropriate action should be taken. + </para> + + <para> + Hibernate wraps <literal>SQLException</literal>s thrown while interacting with the database + in a <literal>JDBCException</literal>. In fact, Hibernate will attempt to convert the exception + into a more meaningful subclass of <literal>JDBCException</literal>. The underlying + <literal>SQLException</literal> is always available via <literal>JDBCException.getCause()</literal>. + Hibernate converts the <literal>SQLException</literal> into an appropriate + <literal>JDBCException</literal> subclass using the <literal>SQLExceptionConverter</literal> + attached to the <literal>SessionFactory</literal>. By default, the + <literal>SQLExceptionConverter</literal> is defined by the configured dialect. However, it is + also possible to plug in a custom implementation. See the javadocs for the + <literal>SQLExceptionConverterFactory</literal> class for details. The standard + <literal>JDBCException</literal> subtypes are: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>JDBCConnectionException</literal>: indicates an error + with the underlying JDBC communication. + </para> + </listitem> + <listitem> + <para> + <literal>SQLGrammarException</literal>: indicates a grammar + or syntax problem with the issued SQL. + </para> + </listitem> + <listitem> + <para> + <literal>ConstraintViolationException</literal>: indicates some + form of integrity constraint violation. + </para> + </listitem> + <listitem> + <para> + <literal>LockAcquisitionException</literal>: indicates an error + acquiring a lock level necessary to perform the requested operation. + </para> + </listitem> + <listitem> + <para> + <literal>GenericJDBCException</literal>: a generic exception + which did not fall into any of the other categories. + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="transactions-demarcation-timeout"> + <title>Transaction timeout</title> + + <para> + An important feature provided by a managed environment like EJB, + that is never provided for non-managed code, is transaction timeout. Transaction + timeouts ensure that no misbehaving transaction can indefinitely tie up + resources while returning no response to the user. Outside a managed (JTA) + environment, Hibernate cannot fully provide this functionality. However, + Hibernate can at least control data access operations, ensuring that database + level deadlocks and queries with huge result sets are limited by a defined + timeout. In a managed environment, Hibernate can delegate transaction timeout + to JTA. This functionality is abstracted by the Hibernate + <literal>Transaction</literal> object. + </para> + + <programlisting role="JAVA"><![CDATA[ +Session sess = factory.openSession(); +try { + //set transaction timeout to 3 seconds + sess.getTransaction().setTimeout(3); + sess.getTransaction().begin(); + + // do some work + ... + + sess.getTransaction().commit() +} +catch (RuntimeException e) { + sess.getTransaction().rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + <literal>setTimeout()</literal> cannot be called in a CMT bean, + where transaction timeouts must be defined declaratively. + </para> + + </section> + + </section> + + <section id="transactions-optimistic"> + <title>Optimistic concurrency control</title> + + <para> + The only approach that is consistent with high concurrency and high + scalability, is optimistic concurrency control with versioning. Version + checking uses version numbers, or timestamps, to detect conflicting updates + and to prevent lost updates. Hibernate provides three possible approaches + to writing application code that uses optimistic concurrency. The use cases + we discuss are in the context of long conversations, but version checking + also has the benefit of preventing lost updates in single database transactions. + </para> + + <section id="transactions-optimistic-manual"> + <title>Application version checking</title> + + <para> + In an implementation without much help from Hibernate, each interaction with the + database occurs in a new <literal>Session</literal> and the developer is responsible + for reloading all persistent instances from the database before manipulating them. + The application is forced to carry out its own version checking to ensure + conversation transaction isolation. This approach is the least efficient in terms of + database access. It is the approach most similar to entity EJBs. + </para> + + <programlisting role="JAVA"><![CDATA[// foo is an instance loaded by a previous Session +session = factory.openSession(); +Transaction t = session.beginTransaction(); + +int oldVersion = foo.getVersion(); +session.load( foo, foo.getKey() ); // load the current state +if ( oldVersion != foo.getVersion() ) throw new StaleObjectStateException(); +foo.setProperty("bar"); + +t.commit(); +session.close();]]></programlisting> + + <para> + The <literal>version</literal> property is mapped using <literal>&lt;version&gt;</literal>, + and Hibernate will automatically increment it during flush if the entity is + dirty. + </para> + + <para> + If you are operating in a low-data-concurrency environment, and do not + require version checking, you can use this approach and skip the version + check. In this case, <emphasis>last commit wins</emphasis> is the default + strategy for long conversations. Be aware that this might + confuse the users of the application, as they might experience lost updates without + error messages or a chance to merge conflicting changes. + </para> + + <para> + Manual version checking is only feasible in trivial circumstances + and not practical for most applications. Often not only single instances, but + complete graphs of modified objects, have to be checked. Hibernate offers automatic + version checking with either an extended <literal>Session</literal> or detached instances + as the design paradigm. + </para> + + </section> + + <section id="transactions-optimistic-longsession"> + <title>Extended session and automatic versioning</title> + + <para> + A single <literal>Session</literal> instance and its persistent instances that are + used for the whole conversation are known as <emphasis>session-per-conversation</emphasis>. + Hibernate checks instance versions at flush time, throwing an exception if concurrent + modification is detected. It is up to the developer to catch and handle this exception. + Common options are the opportunity for the user to merge changes or to restart the + business conversation with non-stale data. + </para> + + <para> + The <literal>Session</literal> is disconnected from any underlying JDBC connection + when waiting for user interaction. This approach is the most efficient in terms + of database access. The application does not version check or + reattach detached instances, nor does it have to reload instances in every + database transaction. + </para> + + <programlisting role="JAVA"><![CDATA[// foo is an instance loaded earlier by the old session +Transaction t = session.beginTransaction(); // Obtain a new JDBC connection, start transaction + +foo.setProperty("bar"); + +session.flush(); // Only for last transaction in conversation +t.commit(); // Also return JDBC connection +session.close(); // Only for last transaction in conversation]]></programlisting> + <para> + The <literal>foo</literal> object knows which <literal>Session</literal> it was + loaded in. Beginning a new database transaction on an old session obtains a new connection + and resumes the session. Committing a database transaction disconnects a session + from the JDBC connection and returns the connection to the pool. After reconnection, to + force a version check on data you are not updating, you can call <literal>Session.lock()</literal> + with <literal>LockMode.READ</literal> on any objects that might have been updated by another + transaction. You do not need to lock any data that you <emphasis>are</emphasis> updating. + Usually you would set <literal>FlushMode.MANUAL</literal> on an extended <literal>Session</literal>, + so that only the last database transaction cycle is allowed to actually persist all + modifications made in this conversation. Only this last database transaction + will include the <literal>flush()</literal> operation, and then + <literal>close()</literal> the session to end the conversation. + </para> + + <para> + This pattern is problematic if the <literal>Session</literal> is too big to + be stored during user think time (for example, an <literal>HttpSession</literal> should + be kept as small as possible). As the <literal>Session</literal> is also the + first-level cache and contains all loaded objects, we can probably + use this strategy only for a few request/response cycles. Use a + <literal>Session</literal> only for a single conversation as it will soon + have stale data. + </para> + + <note> + <title>Note</title> + <para>Earlier versions of Hibernate required explicit disconnection and reconnection + of a <literal>Session</literal>. These methods are deprecated, as beginning and + ending a transaction has the same effect. + </para> + </note> + + <para> + Keep the disconnected <literal>Session</literal> close + to the persistence layer. Use an EJB stateful session bean to + hold the <literal>Session</literal> in a three-tier environment. Do not transfer + it to the web layer, or even serialize it to a separate tier, to store it in the + <literal>HttpSession</literal>. + </para> + + <para> + The extended session pattern, or <emphasis>session-per-conversation</emphasis>, is + more difficult to implement with automatic current session context management. + You need to supply your own implementation of the <literal>CurrentSessionContext</literal> + for this. See the Hibernate Wiki for examples. + </para> + + </section> + + <section id="transactions-optimistic-detached"> + <title>Detached objects and automatic versioning</title> + + <para> + Each interaction with the persistent store occurs in a new <literal>Session</literal>. + 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 + <literal>Session</literal> and then reattaches them using <literal>Session.update()</literal>, + <literal>Session.saveOrUpdate()</literal>, or <literal>Session.merge()</literal>. + </para> + + <programlisting role="JAVA"><![CDATA[// foo is an instance loaded by a previous Session +foo.setProperty("bar"); +session = factory.openSession(); +Transaction t = session.beginTransaction(); +session.saveOrUpdate(foo); // Use merge() if "foo" might have been loaded already +t.commit(); +session.close();]]></programlisting> + + <para> + Again, Hibernate will check instance versions during flush, throwing an + exception if conflicting updates occurred. + </para> + + <para> + You can also call <literal>lock()</literal> instead of <literal>update()</literal>, + and use <literal>LockMode.READ</literal> (performing a version check and bypassing all + caches) if you are sure that the object has not been modified. + </para> + + </section> + + <section id="transactions-optimistic-customizing"> + <title>Customizing automatic versioning</title> + + <para> + You can disable Hibernate's automatic version increment for particular properties and + collections by setting the <literal>optimistic-lock</literal> mapping attribute to + <literal>false</literal>. Hibernate will then no longer increment versions if the + property is dirty. + </para> + + <para> + Legacy database schemas are often static and cannot be modified. Or, other applications + might access the same database and will not know how to handle version numbers or + even timestamps. In both cases, versioning cannot rely on a particular column in a table. + To force a version check with a + comparison of the state of all fields in a row but without a version or timestamp property mapping, + turn on <literal>optimistic-lock="all"</literal> + in the <literal>&lt;class&gt;</literal> mapping. This conceptually only works + if Hibernate can compare the old and the new state (i.e., if you use a single long + <literal>Session</literal> and not session-per-request-with-detached-objects). + </para> + + <para> + Concurrent modification can be permitted in instances where the changes that have been + made do not overlap. If you set <literal>optimistic-lock="dirty"</literal> when mapping the + <literal>&lt;class&gt;</literal>, Hibernate will only compare dirty fields during flush. + </para> + + <para> + In both cases, with dedicated version/timestamp columns or with a full/dirty field + comparison, Hibernate uses a single <literal>UPDATE</literal> statement, with an + appropriate <literal>WHERE</literal> clause, per entity to execute the version check + and update the information. If you use transitive persistence to cascade reattachment + to associated entities, Hibernate may execute unnecessary updates. This is usually + not a problem, but <emphasis>on update</emphasis> triggers in the database might be + executed even when no changes have been made to detached instances. You can customize + this behavior by setting <literal>select-before-update="true"</literal> in the + <literal>&lt;class&gt;</literal> mapping, forcing Hibernate to <literal>SELECT</literal> + the instance to ensure that changes did occur before updating the row. + </para> + + </section> + + </section> + + <section id="transactions-locking"> + <title>Pessimistic locking</title> + + <para> + It is not intended that users spend much time worrying about locking strategies. It is usually + enough to specify an isolation level for the JDBC connections and then simply let the + database do all the work. However, advanced users may wish to obtain + exclusive pessimistic locks or re-obtain locks at the start of a new transaction. + </para> + + <para> + Hibernate will always use the locking mechanism of the database; it never lock objects + in memory. + </para> + + <para> + The <literal>LockMode</literal> class defines the different lock levels that can be acquired + by Hibernate. A lock is obtained by the following mechanisms: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>LockMode.WRITE</literal> is acquired automatically when Hibernate updates or inserts + a row. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.UPGRADE</literal> can be acquired upon explicit user request using + <literal>SELECT ... FOR UPDATE</literal> on databases which support that syntax. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.UPGRADE_NOWAIT</literal> can be acquired upon explicit user request using a + <literal>SELECT ... FOR UPDATE NOWAIT</literal> under Oracle. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.READ</literal> is acquired automatically when Hibernate reads data + under Repeatable Read or Serializable isolation level. It can be re-acquired by explicit user + request. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.NONE</literal> represents the absence of a lock. All objects switch to this + lock mode at the end of a <literal>Transaction</literal>. Objects associated with the session + via a call to <literal>update()</literal> or <literal>saveOrUpdate()</literal> also start out + in this lock mode. + </para> + </listitem> + </itemizedlist> + + <para> + The "explicit user request" is expressed in one of the following ways: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + A call to <literal>Session.load()</literal>, specifying a <literal>LockMode</literal>. + </para> + </listitem> + <listitem> + <para> + A call to <literal>Session.lock()</literal>. + </para> + </listitem> + <listitem> + <para> + A call to <literal>Query.setLockMode()</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + If <literal>Session.load()</literal> is called with <literal>UPGRADE</literal> or + <literal>UPGRADE_NOWAIT</literal>, and the requested object was not yet loaded by + the session, the object is loaded using <literal>SELECT ... FOR UPDATE</literal>. + If <literal>load()</literal> is called for an object that is already loaded with + a less restrictive lock than the one requested, Hibernate calls + <literal>lock()</literal> for that object. + </para> + + <para> + <literal>Session.lock()</literal> performs a version number check if the specified lock + mode is <literal>READ</literal>, <literal>UPGRADE</literal> or + <literal>UPGRADE_NOWAIT</literal>. In the case of <literal>UPGRADE</literal> or + <literal>UPGRADE_NOWAIT</literal>, <literal>SELECT ... FOR UPDATE</literal> is used. + </para> + + <para> + If the requested lock mode is not supported by the database, Hibernate uses an appropriate + alternate mode instead of throwing an exception. This ensures that applications are + portable. + </para> + + </section> + + <section id="transactions-connection-release"> + <title>Connection release modes</title> + + <para> + One of the legacies of Hibernate 2.x JDBC connection management + meant that a <literal>Session</literal> would obtain a connection when it was first + required and then maintain that connection until the session was closed. + Hibernate 3.x introduced the notion of connection release modes that would instruct a session + how to handle its JDBC connections. The following discussion is pertinent + only to connections provided through a configured <literal>ConnectionProvider</literal>. + User-supplied connections are outside the breadth of this discussion. The different + release modes are identified by the enumerated values of + <literal>org.hibernate.ConnectionReleaseMode</literal>: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>ON_CLOSE</literal>: is the legacy behavior described above. The + Hibernate session obtains a connection when it first needs to perform some JDBC access + and maintains that connection until the session is closed. + </para> + </listitem> + <listitem> + <para> + <literal>AFTER_TRANSACTION</literal>: releases connections after a + <literal>org.hibernate.Transaction</literal> has been completed. + </para> + </listitem> + <listitem> + <para> + <literal>AFTER_STATEMENT</literal> (also referred to as aggressive release): + releases connections after every statement execution. This aggressive releasing + is skipped if that statement leaves open resources associated with the given session. + Currently the only situation where this occurs is through the use of + <literal>org.hibernate.ScrollableResults</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + The configuration parameter <literal>hibernate.connection.release_mode</literal> is used + to specify which release mode to use. The possible values are as follows: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>auto</literal> (the default): this choice delegates to the release mode + returned by the <literal>org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode()</literal> + method. For JTATransactionFactory, this returns ConnectionReleaseMode.AFTER_STATEMENT; for + JDBCTransactionFactory, this returns ConnectionReleaseMode.AFTER_TRANSACTION. Do not + change this default behavior as failures due to the value of this setting + tend to indicate bugs and/or invalid assumptions in user code. + </para> + </listitem> + <listitem> + <para> + <literal>on_close</literal>: uses ConnectionReleaseMode.ON_CLOSE. This setting + is left for backwards compatibility, but its use is discouraged. + </para> + </listitem> + <listitem> + <para> + <literal>after_transaction</literal>: uses ConnectionReleaseMode.AFTER_TRANSACTION. + This setting should not be used in JTA environments. Also note that with + ConnectionReleaseMode.AFTER_TRANSACTION, if a session is considered to be in auto-commit + mode, connections will be released as if the release mode were AFTER_STATEMENT. + </para> + </listitem> + <listitem> + <para> + <literal>after_statement</literal>: uses ConnectionReleaseMode.AFTER_STATEMENT. Additionally, + the configured <literal>ConnectionProvider</literal> is consulted to see if it supports this + setting (<literal>supportsAggressiveRelease()</literal>). If not, the release mode is reset + to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only safe in environments where + we can either re-acquire the same underlying JDBC connection each time you make a call into + <literal>ConnectionProvider.getConnection()</literal> or in auto-commit environments where + it does not matter if we re-establish the same connection. + </para> + </listitem> + </itemizedlist> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/tutorial.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/tutorial.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/tutorial.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1623 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; +<!ENTITY mdash "-"> +]> + + +<chapter id="tutorial"> + <title>Tutorial</title> + + <para> + Intended for new users, this chapter provides an step-by-step introduction + to Hibernate, starting with a simple application using an in-memory database. The + tutorial is based on an earlier tutorial developed by Michael Gloegl. All + code is contained in the <filename>tutorials/web</filename> directory of the project + source. + </para> + + <important> + <para> + This tutorial expects the user have knowledge of both Java and + SQL. If you have a limited knowledge of JAVA or SQL, it is advised + that you start with a good introduction to that technology prior + to attempting to learn Hibernate. + </para> + </important> + + <note> + <para> + The distribution contains another example application under + the <filename>tutorial/eg</filename> project source + directory. + </para> + </note> + + <section id="tutorial-firstapp"> + <title>Part 1 - The first Hibernate Application</title> + + <para> + For this example, we will set up a small database application that can store + events we want to attend and information about the host(s) of these events. + </para> + + <note> + <para> + Although you can use whatever database you feel comfortable using, we + will use <ulink url="http://hsqldb.org/">HSQLDB</ulink> (an in-memory, + Java database) to avoid describing installation/setup of any particular + database servers. + </para> + </note> + + <section id="tutorial-firstapp-setup"> + <title>Setup</title> + + <para> + The first thing we need to do is to set up the development environment. We + will be using the "standard layout" advocated by alot of build tools such + as <ulink url="http://maven.org">Maven</ulink>. Maven, in particular, has a + good resource describing this <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the...;. + As this tutorial is to be a web application, we will be creating and making + use of <filename>src/main/java</filename>, <filename>src/main/resources</filename> + and <filename>src/main/webapp</filename> directories. + </para> + + <para> + We will be using Maven in this tutorial, taking advantage of its + transitive dependency management capabilities as well as the ability of + many IDEs to automatically set up a project for us based on the maven descriptor. + </para> + + <programlisting role="XML"><![CDATA[<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + + <modelVersion>4.0.0</modelVersion> + + <groupId>org.hibernate.tutorials</groupId> + <artifactId>hibernate-tutorial</artifactId> + <version>1.0.0-SNAPSHOT</version> + <name>First Hibernate Tutorial</name> + + <build> + <!-- we dont want the version to be part of the generated war file name --> + <finalName>${artifactId}</finalName> + </build> + + <dependencies> + <dependency> + <groupId>org.hibernate</groupId> + <artifactId>hibernate-core</artifactId> + </dependency> + + <!-- Because this is a web app, we also have a dependency on the servlet api. --> + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>servlet-api</artifactId> + </dependency> + + <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend --> + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-simple</artifactId> + </dependency> + + <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist --> + <dependency> + <groupId>javassist</groupId> + <artifactId>javassist</artifactId> + </dependency> + </dependencies> + +</project>]]></programlisting> + + <tip> + <para> + It is not a requirement to use Maven. If you wish to use something else to + build this tutoial (such as Ant), the layout will remain the same. The only + change is that you will need to manually account for all the needed + dependencies. If you use something like <ulink url="http://ant.apache.org/ivy/">Ivy</ulink> + providing transitive dependency management you would still use the dependencies + mentioned below. Otherwise, you'd need to grab <emphasis>all</emphasis> + dependencies, both explicit and transitive, and add them to the project's + classpath. If working from the Hibernate distribution bundle, this would mean + <filename>hibernate3.jar</filename>, all artifacts in the + <filename>lib/required</filename> directory and all files from either the + <filename>lib/bytecode/cglib</filename> or <filename>lib/bytecode/javassist</filename> + directory; additionally you will need both the servlet-api jar and one of the slf4j + logging backends. + </para> + </tip> + + <para> + Save this file as <filename>pom.xml</filename> in the project root directory. + </para> + </section> + + + <section id="tutorial-firstapp-firstclass"> + <title>The first class</title> + + <para> + Next, we create a class that represents the event we want to store in the + database; it is a simple JavaBean class with some properties: + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.domain; + +import java.util.Date; + +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() {} + + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +}]]></programlisting> + + <para> + This class uses standard JavaBean naming conventions for property + getter and setter methods, as well as private visibility for the + fields. Although this is the recommended design, it is not required. + Hibernate can also access fields directly, the benefit of accessor + methods is robustness for refactoring. + </para> + + <para> + The <literal>id</literal> property holds a unique identifier value + for a particular event. All persistent entity classes (there are + less important dependent classes as well) will need such an identifier + property if we want to use the full feature set of Hibernate. In fact, + most applications, especially web applications, need to distinguish + objects by identifier, so you should consider this a feature rather + than a limitation. However, we usually do not manipulate the identity + of an object, hence the setter method should be private. Only Hibernate + will assign identifiers when an object is saved. Hibernate can access + public, private, and protected accessor methods, as well as public, + private and protected fields directly. The choice is up to you and + you can match it to fit your application design. + </para> + + <para> + The no-argument constructor is a requirement for all persistent + classes; Hibernate has to create objects for you, using Java + Reflection. The constructor can be private, however package or public + visibility is required for runtime proxy generation and efficient data + retrieval without bytecode instrumentation. + </para> + + <para> + Save this file to the <filename>src/main/java/org/hibernate/tutorial/domain</filename> + directory. + </para> + </section> + + <section id="tutorial-firstapp-mapping"> + <title>The mapping file</title> + + <para> + Hibernate needs to know how to load and store objects of the + persistent class. This is where the Hibernate mapping file + comes into play. The mapping file tells Hibernate what table in + the database it has to access, and what columns in that table + it should use. + </para> + + <para> + The basic structure of a mapping file looks like this: + </para> + + <programlisting role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="org.hibernate.tutorial.domain"> +[...] +</hibernate-mapping>]]></programlisting> + + <para> + Hibernate DTD is sophisticated. You can use it for auto-completion + of XML mapping elements and attributes in your editor or IDE. + Opening up the DTD file in your text editor is the easiest way to + get an overview of all elements and attributes, and to view the + defaults, as well as some comments. Hibernate will not load the + DTD file from the web, but first look it up from the classpath of + the application. The DTD file is included in + <filename>hibernate-core.jar</filename> (it is also included in the + <filename>hibernate3.jar</filename>, if using the distribution bundle). + </para> + + <important> + <para> + We will omit the DTD declaration in future examples to shorten the code. It is, + of course, not optional. + </para> + </important> + + <para> + Between the two <literal>hibernate-mapping</literal> tags, include a + <literal>class</literal> element. All persistent entity classes (again, there + might be dependent classes later on, which are not first-class entities) need + a mapping to a table in the SQL database: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping package="org.hibernate.tutorial.domain"> + + <class name="Event" table="EVENTS"> + + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + So far we have told Hibernate how to persist and load object of + class <literal>Event</literal> to the table + <literal>EVENTS</literal>. Each instance is now represented by a + row in that table. Now we can continue by mapping the unique + identifier property to the tables primary key. As we do not want + to care about handling this identifier, we configure Hibernate's + identifier generation strategy for a surrogate primary key column: + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping package="org.hibernate.tutorial.domain"> + + <class name="Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + The <literal>id</literal> element is the declaration of the + identifier property. The <literal>name="id"</literal> mapping + attribute declares the name of the JavaBean property and tells + Hibernate to use the <literal>getId()</literal> and + <literal>setId()</literal> methods to access the property. The + column attribute tells Hibernate which column of the + <literal>EVENTS</literal> table holds the primary key value. + </para> + + <para> + The nested <literal>generator</literal> element specifies the + identifier generation strategy (aka how are identifier values + generated?). In this case we choose <literal>native</literal>, + which offers a level of portability depending on the configured + database dialect. Hibernate supports database generated, globally + unique, as well as application assigned, identifiers. Identifier + value generation is also one of Hibernate's many extension points + and you can plugin in your own strategy. + </para> + + <tip> + <para> + <literal>native</literal> is no longer consider the best strategy in terms of portability. for further + discussion, see <xref linkend="portability-idgen"/> + </para> + </tip> + + <para> + Lastly, we need to tell Hibernate about the remaining entity class + properties. By default, no properties of the class are considered + persistent: + </para> + + <programlisting role="XML"><![CDATA[ +<hibernate-mapping package="org.hibernate.tutorial.domain"> + + <class name="Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Similar to the <literal>id</literal> element, the + <literal>name</literal> attribute of the + <literal>property</literal> element tells Hibernate which getter + and setter methods to use. In this case, Hibernate will search + for <literal>getDate()</literal>, <literal>setDate()</literal>, + <literal>getTitle()</literal> and <literal>setTitle()</literal> + methods. + </para> + + <note> + <para> + Why does the <literal>date</literal> property mapping include the + <literal>column</literal> attribute, but the <literal>title</literal> + does not? Without the <literal>column</literal> attribute, Hibernate + by default uses the property name as the column name. This works for + <literal>title</literal>, however, <literal>date</literal> is a reserved + keyword in most databases so you will need to map it to a different name. + </para> + </note> + + <para> + The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The + types declared and used in the mapping files are not Java data types; they are not SQL + database types either. These types are called <emphasis>Hibernate mapping types</emphasis>, + converters which can translate from Java to SQL data types and vice versa. Again, + Hibernate will try to determine the correct conversion and mapping type itself if + the <literal>type</literal> attribute is not present in the mapping. In some cases this + automatic detection using Reflection on the Java class might not have the default you + expect or need. This is the case with the <literal>date</literal> property. Hibernate cannot + know if the property, which is of <literal>java.util.Date</literal>, should map to a + SQL <literal>date</literal>, <literal>timestamp</literal>, or <literal>time</literal> column. + Full date and time information is preserved by mapping the property with a + <literal>timestamp</literal> converter. + </para> + + <tip> + <para> + Hibernate makes this mapping type determination using reflection when the mapping files + are processed. This can take time and resources, so if startup performance is important + you should consider explicitly defining the type to use. + </para> + </tip> + + <para> + Save this mapping file as + <filename>src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml</filename>. + </para> + + </section> + + <section id="tutorial-firstapp-configuration" revision="2"> + <title>Hibernate configuration</title> + + <para> + At this point, you should have the persistent class and its mapping + file in place. It is now time to configure Hibernate. First let's set up + HSQLDB to run in "server mode" + </para> + + <note> + <para> + We do this do that the data remains between runs. + </para> + </note> + + <para> + We will utilize the Maven exec plugin to launch the HSQLDB server + by running: + <command> mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial"</command> + You will see it start up and bind to a TCP/IP socket; this is where + our application will connect later. If you want to start + with a fresh database during this tutorial, shutdown HSQLDB, delete + all files in the <filename>target/data</filename> directory, + and start HSQLDB again. + </para> + + <para> + Hibernate will be connecting to the database on behalf of your application, so it needs to know + how to obtain connections. For this tutorial we will be using a standalone connection + pool (as opposed to a <interfacename>javax.sql.DataSource</interfacename>). Hibernate comes with + support for two third-party open source JDBC connection pools: + <ulink url="https://sourceforge.net/projects/c3p0">c3p0</ulink> and + <ulink url="http://proxool.sourceforge.net/">proxool</ulink>;. However, we will be using the + Hibernate built-in connection pool for this tutorial. + </para> + + <caution> + <para> + The built-in Hibernate connection pool is in no way intended for production use. It + lacks several features found on any decent connection pool. + </para> + </caution> + + <para> + For Hibernate's configuration, we can use a simple <literal>hibernate.properties</literal> file, a + more sophisticated <literal>hibernate.cfg.xml</literal> file, or even complete + programmatic setup. Most users prefer the XML configuration file: + </para> + + <programlisting role="XML"><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> + +<hibernate-configuration> + + <session-factory> + + <!-- Database connection settings --> + <property name="connection.driver_class">org.hsqldb.jdbcDriver</property> + <property name="connection.url">jdbc:hsqldb:hsql://localhost</property> + <property name="connection.username">sa</property> + <property name="connection.password"></property> + + <!-- JDBC connection pool (use the built-in) --> + <property name="connection.pool_size">1</property> + + <!-- SQL dialect --> + <property name="dialect">org.hibernate.dialect.HSQLDialect</property> + + <!-- Enable Hibernate's automatic session context management --> + <property name="current_session_context_class">thread</property> + + <!-- Disable the second-level cache --> + <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property> + + <!-- Echo all executed SQL to stdout --> + <property name="show_sql">true</property> + + <!-- Drop and re-create the database schema on startup --> + <property name="hbm2ddl.auto">update</property> + + <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/> + + </session-factory> + +</hibernate-configuration>]]></programlisting> + + <note> + <para>Notice that this configuration file specifies a different DTD</para> + </note> + + <para> + You configure Hibernate's <literal>SessionFactory</literal>. SessionFactory is a global + factory responsible for a particular database. If you have several databases, for easier + startup you should use several <literal>&lt;session-factory&gt;</literal> configurations in + several configuration files. + </para> + + <para> + The first four <literal>property</literal> elements contain the necessary + configuration for the JDBC connection. The dialect <literal>property</literal> + element specifies the particular SQL variant Hibernate generates. + </para> + + <tip> + <para> + In most cases, Hibernate is able to properly determine which dialect to use. See + <xref linkend="portability-dialectresolver"/> for more information. + </para> + </tip> + + <para> + Hibernate's automatic session management for persistence contexts is particularly useful + in this context. The <literal>hbm2ddl.auto</literal> option turns on automatic generation of + database schemas directly into the database. This can also be turned + off by removing the configuration option, or redirected to a file with the help of + the <literal>SchemaExport</literal> Ant task. Finally, add the mapping file(s) + for persistent classes to the configuration. + </para> + + <para> + Save this file as <filename>hibernate.cfg.xml</filename> into the + <filename>src/main/resources</filename> directory. + </para> + + </section> + + <section id="tutorial-firstapp-mvn" revision="1"> + <title>Building with Maven</title> + + <para> + We will now build the tutorial with Maven. You will need to + have Maven installed; it is available from the + <ulink url="http://maven.apache.org/download.html">Maven download page</ulink>. + Maven will read the <filename>/pom.xml</filename> file we created + earlier and know how to perform some basic project tasks. First, + lets run the <literal>compile</literal> goal to make sure we can compile + everything so far: + </para> + + <programlisting><![CDATA[[hibernateTutorial]$ mvn compile +[INFO] Scanning for projects... +[INFO] ------------------------------------------------------------------------ +[INFO] Building First Hibernate Tutorial +[INFO] task-segment: [compile] +[INFO] ------------------------------------------------------------------------ +[INFO] [resources:resources] +[INFO] Using default encoding to copy filtered resources. +[INFO] [compiler:compile] +[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESSFUL +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 2 seconds +[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009 +[INFO] Final Memory: 5M/547M +[INFO] ------------------------------------------------------------------------]]></programlisting> + + </section> + + <section id="tutorial-firstapp-helpers" revision="3"> + <title>Startup and helpers</title> + + <para> + It is time to load and store some <literal>Event</literal> + objects, but first you have to complete the setup with some + infrastructure code. You have to startup Hibernate by building + a global <interfacename>org.hibernate.SessionFactory</interfacename> + object and storing it somewhere for easy access in application code. A + <interfacename>org.hibernate.SessionFactory</interfacename> is used to + obtain <interfacename>org.hibernate.Session</interfacename> instances. + A <interfacename>org.hibernate.Session</interfacename> represents a + single-threaded unit of work. The + <interfacename>org.hibernate.SessionFactory</interfacename> is a + thread-safe global object that is instantiated once. + </para> + + <para> + We will create a <literal>HibernateUtil</literal> helper class that + takes care of startup and makes accessing the + <interfacename>org.hibernate.SessionFactory</interfacename> more convenient. + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.util; + +import org.hibernate.SessionFactory; +import org.hibernate.cfg.Configuration; + +public class HibernateUtil { + + private static final SessionFactory sessionFactory = buildSessionFactory(); + + private static SessionFactory buildSessionFactory() { + try { + // Create the SessionFactory from hibernate.cfg.xml + return new Configuration().configure().buildSessionFactory(); + } + catch (Throwable ex) { + // Make sure you log the exception, as it might be swallowed + System.err.println("Initial SessionFactory creation failed." + ex); + throw new ExceptionInInitializerError(ex); + } + } + + public static SessionFactory getSessionFactory() { + return sessionFactory; + } + +}]]></programlisting> + + <para> + Save this code as + <filename>src/main/java/org/hibernate/tutorial/util/HibernateUtil.java</filename> + </para> + + <para> + This class not only produces the global + <interfacename>org.hibernate.SessionFactory</interfacename> reference in + its static initializer; it also hides the fact that it uses a + static singleton. We might just as well have looked up the + <interfacename>org.hibernate.SessionFactory</interfacename> reference from + JNDI in an application server or any other location for that matter. + </para> + + <para> + If you give the <interfacename>org.hibernate.SessionFactory</interfacename> + a name in your configuration, Hibernate will try to bind it to + JNDI under that name after it has been built. Another, better option is to + use a JMX deployment and let the JMX-capable container instantiate and bind + a <literal>HibernateService</literal> to JNDI. Such advanced options are + discussed later. + </para> + + <para> + You now need to configure a logging + system. Hibernate uses commons logging and provides two choices: Log4j and + JDK 1.4 logging. Most developers prefer Log4j: copy <literal>log4j.properties</literal> + from the Hibernate distribution in the <literal>etc/</literal> directory to + your <literal>src</literal> directory, next to <literal>hibernate.cfg.xml</literal>. + If you prefer to have + more verbose output than that provided in the example configuration, you can change the settings. By default, only the Hibernate startup message is shown on stdout. + </para> + + <para> + The tutorial infrastructure is complete and you are now ready to do some real work with + Hibernate. + </para> + + </section> + + <section id="tutorial-firstapp-workingpersistence" revision="5"> + <title>Loading and storing objects</title> + + <para> + We are now ready to start doing some real worjk with Hibernate. + Let's start by writing an <literal>EventManager</literal> class + with a <literal>main()</literal> method: + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial; + +import org.hibernate.Session; + +import java.util.*; + +import org.hibernate.tutorial.domain.Event; +import org.hibernate.tutorial.util.HibernateUtil; + +public class EventManager { + + public static void main(String[] args) { + EventManager mgr = new EventManager(); + + if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); + } + + HibernateUtil.getSessionFactory().close(); + } + + private void createAndStoreEvent(String title, Date theDate) { + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + session.save(theEvent); + + session.getTransaction().commit(); + } + +}]]></programlisting> + + <para> + In <literal>createAndStoreEvent()</literal> we created a new + <literal>Event</literal> object and handed it over to Hibernate. + At that point, Hibernate takes care of the SQL and executes an + <literal>INSERT</literal> on the database. + </para> + + <para> + A <interface>org.hibernate.Session</interface> is designed to + represent a single unit of work (a single atmoic piece of work + to be performed). For now we will keep things simple and assume + a one-to-one granularity between a Hibernate + <interface>org.hibernate.Session</interface> and a database + transaction. To shield our code from the actual underlying + transaction system we use the Hibernate + <interfacename>org.hibernate.Transaction</interfacename> API. + In this particular case we are using JDBC-based transactional + semantics, but it could also run with JTA. + </para> + + <para> + What does <literal>sessionFactory.getCurrentSession()</literal> do? + First, you can call it as many times and anywhere you like + once you get hold of your + <interfacename>org.hibernate.SessionFactory</interfacename>. + The <literal>getCurrentSession()</literal> method always returns + the "current" unit of work. Remember that we switched + the configuration option for this mechanism to "thread" in our + <filename>src/main/resources/hibernate.cfg.xml</filename>? + Due to that setting, the context of a current unit of work is bound + to the current Java thread that executes the application. + </para> + + <important> + <para> + Hibernate offers three methods of current session tracking. + The "thread" based method is not intended for production use; + it is merely useful for prototyping and tutorials such as this + one. Current session tracking is discussed in more detail + later on. + </para> + </important> + + <para> + A <interface>org.hibernate.Session</interface> begins when the + first call to <literal>getCurrentSession()</literal> is made for + the current thread. It is then bound by Hibernate to the current + thread. When the transaction ends, either through commit or + rollback, Hibernate automatically unbinds the + <interface>org.hibernate.Session</interface> from the thread + and closes it for you. If you call + <literal>getCurrentSession()</literal> again, you get a new + <interface>org.hibernate.Session</interface> and can start a + new unit of work. + </para> + + <para> + Related to the unit of work scope, should the Hibernate + <interface>org.hibernate.Session</interface> be used to execute + one or several database operations? The above example uses one + <interface>org.hibernate.Session</interface> for one operation. + However this is pure coincidence; the example is just not complex + enough to show any other approach. The scope of a Hibernate + <interface>org.hibernate.Session</interface> is flexible but you + should never design your application to use a new Hibernate + <interface>org.hibernate.Session</interface> for + <emphasis>every</emphasis> database operation. Even though it is + used in the following examples, consider + <emphasis>session-per-operation</emphasis> an anti-pattern. + A real web application is shown later in the tutorial which will + help illustrate this. + </para> + + <para> + See <xref linkend="transactions"/> for more information + about transaction handling and demarcation. The previous + example also skipped any error handling and rollback. + </para> + + <para> + To run this, we will make use of the Maven exec plugin to call our class + with the necessary classpath setup: + <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"</command> + </para> + + <note> + <para> + You may need to perform <command>mvn compile</command> first. + </para> + </note> + + <para> + You should see Hibernate starting up and, depending on your configuration, + lots of log output. Towards the end, the following line will be displayed: + </para> + + <programlisting><![CDATA[[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)]]></programlisting> + + <para> + This is the <literal>INSERT</literal> executed by Hibernate. + </para> + + <para> + To list stored events an option is added to the main method: + </para> + + <programlisting role="JAVA"><![CDATA[ if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); + } + else if (args[0].equals("list")) { + List events = mgr.listEvents(); + for (int i = 0; i < events.size(); i++) { + Event theEvent = (Event) events.get(i); + System.out.println( + "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate() + ); + } + }]]></programlisting> + + <para> + A new <literal>listEvents() method is also added</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[ private List listEvents() { + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + List result = session.createQuery("from Event").list(); + session.getTransaction().commit(); + return result; + }]]></programlisting> + + <para> + Here, we are using a Hibernate Query Language (HQL) query to load all existing + <literal>Event</literal> objects from the database. Hibernate will generate the + appropriate SQL, send it to the database and populate <literal>Event</literal> objects + with the data. You can create more complex queries with HQL. See <xref linkend="queryhql"/> + for more information. + </para> + + <para> + Now we can call our new functionality, again using the Maven exec plugin: + <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"</command> + </para> + + </section> + + </section> + + <section id="tutorial-associations"> + <title>Part 2 - Mapping associations</title> + + <para> + So far we have mapped a single persistent entity class to a table in + isolation. Let's expand on that a bit and add some class associations. + We will add people to the application and store a list of events in + which they participate. + </para> + + <section id="tutorial-associations-mappinguser" revision="1"> + <title>Mapping the Person class</title> + + <para> + The first cut of the <literal>Person</literal> class looks like this: + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.domain; + +public class Person { + + private Long id; + private int age; + private String firstname; + private String lastname; + + public Person() {} + + // Accessor methods for all properties, private setter for 'id' + +}]]></programlisting> + + <para> + Save this to a file named + <filename>src/main/java/org/hibernate/tutorial/domain/Person.java</filename> + </para> + + <para> + Next, create the new mapping file as + <filename>src/main/resources/org/hibernate/tutorial/domain/Person.hbm.xml</filename> + </para> + + <programlisting role="XML"><![CDATA[<hibernate-mapping package="org.hibernate.tutorial.domain"> + + <class name="Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Finally, add the new mapping to Hibernate's configuration: + </para> + + <programlisting role="XML"><![CDATA[<mapping resource="events/Event.hbm.xml"/> +<mapping resource="events/Person.hbm.xml"/>]]></programlisting> + + <para> + Create an association between these two entities. Persons + can participate in events, and events have participants. The design questions + you have to deal with are: directionality, multiplicity, and collection + behavior. + </para> + + </section> + + <section id="tutorial-associations-unidirset" revision="3"> + <title>A unidirectional Set-based association</title> + + <para> + By adding a collection of events to the <literal>Person</literal> + class, you can easily navigate to the events for a particular person, + without executing an explicit query - by calling + <literal>Person#getEvents</literal>. Multi-valued associations + are represented in Hibernate by one of the Java Collection Framework + contracts; here we choose a <interfacename>java.util.Set</interfacename> + because the collection will not contain duplicate elements and the ordering + is not relevant to our examples: + </para> + + <programlisting role="JAVA"><![CDATA[public class Person { + + private Set events = new HashSet(); + + public Set getEvents() { + return events; + } + + public void setEvents(Set events) { + this.events = events; + } +}]]></programlisting> + + <para> + Before mapping this association, let's consider the other side. + We could just keep this unidirectional or create another + collection on the <literal>Event</literal>, if we wanted to be + able to navigate it from both directions. This is not necessary, + from a functional perspective. You can always execute an explicit + query to retrieve the participants for a particular event. This + is a design choice left to you, but what is clear from this + discussion is the multiplicity of the association: "many" valued + on both sides is called a <emphasis>many-to-many</emphasis> + association. Hence, we use Hibernate's many-to-many mapping: + </para> + + <programlisting role="XML"><![CDATA[<class name="Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + + <set name="events" table="PERSON_EVENT"> + <key column="PERSON_ID"/> + <many-to-many column="EVENT_ID" class="Event"/> + </set> + +</class>]]></programlisting> + + <para> + Hibernate supports a broad range of collection mappings, a + <literal>set</literal> being most common. For a many-to-many + association, or <emphasis>n:m</emphasis> entity relationship, an + association table is required. Each row in this table represents + a link between a person and an event. The table name is + decalred using the <literal>table</literal> attribute of the + <literal>set</literal> element. The identifier column name in + the association, for the person side, is defined with the + <literal>key</literal> element, the column name for the event's + side with the <literal>column</literal> attribute of the + <literal>many-to-many</literal>. You also have to tell Hibernate + the class of the objects in your collection (the class on the + other side of the collection of references). + </para> + + <para> + The database schema for this mapping is therefore: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | + |_____________| |__________________| | PERSON | + | | | | |_____________| + | *EVENT_ID | <--> | *EVENT_ID | | | + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | + |_____________| | FIRSTNAME | + | LASTNAME | + |_____________| + ]]></programlisting> + + </section> + + <section id="tutorial-associations-working" revision="2"> + <title>Working the association</title> + + <para> + Now we will bring some people and events together in a new method in <literal>EventManager</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[ private void addPersonToEvent(Long personId, Long eventId) { + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + Event anEvent = (Event) session.load(Event.class, eventId); + aPerson.getEvents().add(anEvent); + + session.getTransaction().commit(); + }]]></programlisting> + + <para> + After loading a <literal>Person</literal> and an + <literal>Event</literal>, simply modify the collection using the + normal collection methods. There is no explicit call to + <literal>update()</literal> or <literal>save()</literal>; + Hibernate automatically detects that the collection has been modified + and needs to be updated. This is called + <emphasis>automatic dirty checking</emphasis>. You can also try + it by modifying the name or the date property of any of your + objects. As long as they are in <emphasis>persistent</emphasis> + state, that is, bound to a particular Hibernate + <interfacename>org.hibernate.Session</interfacename>, Hibernate + monitors any changes and executes SQL in a write-behind fashion. + The process of synchronizing the memory state with the database, + usually only at the end of a unit of work, is called + <emphasis>flushing</emphasis>. In our code, the unit of work + ends with a commit, or rollback, of the database transaction. + </para> + + <para> + You can load person and event in different units of work. Or + you can modify an object outside of a + <interfacename>org.hibernate.Session</interfacename>, when it + is not in persistent state (if it was persistent before, this + state is called <emphasis>detached</emphasis>). You can even + modify a collection when it is detached: + </para> + + <programlisting role="JAVA"><![CDATA[ private void addPersonToEvent(Long personId, Long eventId) { + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session + .createQuery("select p from Person p left join fetch p.events where p.id = :pid") + .setParameter("pid", personId) + .uniqueResult(); // Eager fetch the collection so we can use it detached + Event anEvent = (Event) session.load(Event.class, eventId); + + session.getTransaction().commit(); + + // End of first unit of work + + aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached + + // Begin second unit of work + + Session session2 = HibernateUtil.getSessionFactory().getCurrentSession(); + session2.beginTransaction(); + session2.update(aPerson); // Reattachment of aPerson + + session2.getTransaction().commit(); + }]]></programlisting> + + <para> + The call to <literal>update</literal> makes a detached object + persistent again by binding it to a new unit of work, so any + modifications you made to it while detached can be saved to + the database. This includes any modifications + (additions/deletions) you made to a collection of that entity + object. + </para> + + <para> + This is not much use in our example, but it is an important concept you can + incorporate into your own application. Complete this exercise by adding a new action + to the main method of the <literal>EventManager</literal> and call it from the command line. If + you need the identifiers of a person and an event - the <literal>save()</literal> method + returns it (you might have to modify some of the previous methods to return that identifier): + </para> + + <programlisting role="JAVA"><![CDATA[ else if (args[0].equals("addpersontoevent")) { + Long eventId = mgr.createAndStoreEvent("My Event", new Date()); + Long personId = mgr.createAndStorePerson("Foo", "Bar"); + mgr.addPersonToEvent(personId, eventId); + System.out.println("Added person " + personId + " to event " + eventId); + }]]></programlisting> + + <para> + This is an example of an association between two equally important + classes : two entities. As mentioned earlier, there are other + classes and types in a typical model, usually "less important". + Some you have already seen, like an <literal>int</literal> or a + <classname>java.lang.String</classname>. We call these classes + <emphasis>value types</emphasis>, and their instances + <emphasis>depend</emphasis> on a particular entity. Instances of + these types do not have their own identity, nor are they shared + between entities. Two persons do not reference the same + <literal>firstname</literal> object, even if they have the same + first name. Value types cannot only be found in the JDK , but + you can also write dependent classes yourself + such as an <literal>Address</literal> or + <literal>MonetaryAmount</literal> class. In fact, in a Hibernate + application all JDK classes are considered value types. + </para> + + <para> + You can also design a collection of value types. This is + conceptually different from a collection of references to other + entities, but looks almost the same in Java. + </para> + + </section> + + <section id="tutorial-associations-valuecollections"> + <title>Collection of values</title> + + <para> + Let's add a collection of email addresses to the + <literal>Person</literal> entity. This will be represented as a + <interfacename>java.util.Set</interfacename> of + <classname>java.lang.String</classname> instances: + </para> + <programlisting role="JAVA"><![CDATA[ private Set emailAddresses = new HashSet(); + + public Set getEmailAddresses() { + return emailAddresses; + } + + public void setEmailAddresses(Set emailAddresses) { + this.emailAddresses = emailAddresses; + }]]></programlisting> + + <para> + The mapping of this <literal>Set</literal> is as follows: + </para> + + <programlisting role="XML"><![CDATA[ <set name="emailAddresses" table="PERSON_EMAIL_ADDR"> + <key column="PERSON_ID"/> + <element type="string" column="EMAIL_ADDR"/> + </set>]]></programlisting> + + <para> + The difference compared with the earlier mapping is the use of + the <literal>element</literal> part which tells Hibernate that the + collection does not contain references to another entity, but is + rather a collection whose elements are values types, here specifically + of type <literal>string</literal>. The lowercase name tells you + it is a Hibernate mapping type/converter. Again the + <literal>table</literal> attribute of the <literal>set</literal> + element determines the table name for the collection. The + <literal>key</literal> element defines the foreign-key column + name in the collection table. The <literal>column</literal> + attribute in the <literal>element</literal> element defines the + column name where the email address values will actually + be stored. + </para> + + <para> + Here is the updated schema: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | ___________________ + |_____________| |__________________| | PERSON | | | + | | | | |_____________| | PERSON_EMAIL_ADDR | + | *EVENT_ID | <--> | *EVENT_ID | | | |___________________| + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | | *EMAIL_ADDR | + |_____________| | FIRSTNAME | |___________________| + | LASTNAME | + |_____________| + ]]></programlisting> + + <para> + You can see that the primary key of the collection table is in fact a composite key that + uses both columns. This also implies that there cannot be duplicate email addresses + per person, which is exactly the semantics we need for a set in Java. + </para> + + <para> + You can now try to add elements to this collection, just like we did before by + linking persons and events. It is the same code in Java: + </para> + + <programlisting role="JAVA"><![CDATA[ private void addEmailToPerson(Long personId, String emailAddress) { + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + // adding to the emailAddress collection might trigger a lazy load of the collection + aPerson.getEmailAddresses().add(emailAddress); + + session.getTransaction().commit(); + }]]></programlisting> + + <para> + This time we did not use a <emphasis>fetch</emphasis> query to + initialize the collection. Monitor the SQL log and try to + optimize this with an eager fetch. + </para> + + </section> + + <section id="tutorial-associations-bidirectional" revision="1"> + <title>Bi-directional associations</title> + + <para> + Next you will map a bi-directional association. You will make + the association between person and event work from both sides + in Java. The database schema does not change, so you will still + have many-to-many multiplicity. + </para> + + <note> + <para> + A relational database is more flexible than a network + programming language, in that it does not need a navigation + direction; data can be viewed and retrieved in any possible + way. + </para> + </note> + + <para> + First, add a collection of participants to the + <literal>Event</literal> class: + </para> + + <programlisting role="JAVA"><![CDATA[ private Set participants = new HashSet(); + + public Set getParticipants() { + return participants; + } + + public void setParticipants(Set participants) { + this.participants = participants; + }]]></programlisting> + + <para> + Now map this side of the association in <literal>Event.hbm.xml</literal>. + </para> + + <programlisting role="XML"><![CDATA[ <set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> + </set>]]></programlisting> + + <para> + These are normal <literal>set</literal> mappings in both mapping documents. + Notice that the column names in <literal>key</literal> and <literal>many-to-many</literal> + swap in both mapping documents. The most important addition here is the + <literal>inverse="true"</literal> attribute in the <literal>set</literal> element of the + <literal>Event</literal>'s collection mapping. + </para> + + <para> + What this means is that Hibernate should take the other side, the <literal>Person</literal> class, + when it needs to find out information about the link between the two. This will be a lot easier to + understand once you see how the bi-directional link between our two entities is created. + </para> + + </section> + + <section id="tutorial-associations-usingbidir"> + <title>Working bi-directional links</title> + + <para> + First, keep in mind that Hibernate does not affect normal Java semantics. How did we create a + link between a <literal>Person</literal> and an <literal>Event</literal> in the unidirectional + example? You add an instance of <literal>Event</literal> to the collection of event references, + of an instance of <literal>Person</literal>. If you want to make this link + bi-directional, you have to do the same on the other side by adding a <literal>Person</literal> + reference to the collection in an <literal>Event</literal>. This process of "setting the link on both sides" + is absolutely necessary with bi-directional links. + </para> + + <para> + Many developers program defensively and create link management methods to + correctly set both sides (for example, in <literal>Person</literal>): + </para> + + <programlisting role="JAVA"><![CDATA[ protected Set getEvents() { + return events; + } + + protected void setEvents(Set events) { + this.events = events; + } + + public void addToEvent(Event event) { + this.getEvents().add(event); + event.getParticipants().add(this); + } + + public void removeFromEvent(Event event) { + this.getEvents().remove(event); + event.getParticipants().remove(this); + }]]></programlisting> + + <para> + The get and set methods for the collection are now protected. This allows classes in the + same package and subclasses to still access the methods, but prevents everybody else from altering + the collections directly. Repeat the steps for the collection + on the other side. + </para> + + <para> + What about the <literal>inverse</literal> mapping attribute? For you, and for Java, a bi-directional + link is simply a matter of setting the references on both sides correctly. Hibernate, however, does not + have enough information to correctly arrange SQL <literal>INSERT</literal> and <literal>UPDATE</literal> + statements (to avoid constraint violations). Making one side of the association <literal>inverse</literal> tells Hibernate to consider it a <emphasis>mirror</emphasis> of the other side. That is all that is necessary + for Hibernate to resolve any issues that arise when transforming a directional navigation model to + a SQL database schema. The rules are straightforward: all bi-directional associations + need one side as <literal>inverse</literal>. In a one-to-many association it has to be the many-side, + and in many-to-many association you can select either side. + </para> + + </section> + + </section> + + <section id="tutorial-webapp"> + <title>Part 3 - The EventManager web application</title> + + <para> + A Hibernate web application uses <literal>Session</literal> and <literal>Transaction</literal> + almost like a standalone application. However, some common patterns are useful. You can now write + an <literal>EventManagerServlet</literal>. This servlet can list all events stored in the + database, and it provides an HTML form to enter new events. + </para> + + <section id="tutorial-webapp-servlet" revision="2"> + <title>Writing the basic servlet</title> + + <para> + First we need create our basic processing servlet. Since our + servlet only handles HTTP <literal>GET</literal> requests, we + will only implement the <literal>doGet()</literal> method: + </para> + + <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.web; + +// Imports + +public class EventManagerServlet extends HttpServlet { + + protected void doGet( + HttpServletRequest request, + HttpServletResponse response) throws ServletException, IOException { + + SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" ); + + try { + // Begin unit of work + HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction(); + + // Process request and render page... + + // End unit of work + HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit(); + } + catch (Exception ex) { + HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback(); + if ( ServletException.class.isInstance( ex ) ) { + throw ( ServletException ) ex; + } + else { + throw new ServletException( ex ); + } + } + } + +}]]></programlisting> + + <para> + Save this servlet as + <filename>src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java</filename> + </para> + + <para> + The pattern applied here is called <emphasis>session-per-request</emphasis>. + When a request hits the servlet, a new Hibernate <literal>Session</literal> is + opened through the first call to <literal>getCurrentSession()</literal> on the + <literal>SessionFactory</literal>. A database transaction is then started. All + data access occurs inside a transaction irrespective of whether the data is read or written. + Do not use the auto-commit mode in applications. + </para> + + <para> + Do <emphasis>not</emphasis> use a new Hibernate <literal>Session</literal> for + every database operation. Use one Hibernate <literal>Session</literal> that is + scoped to the whole request. Use <literal>getCurrentSession()</literal>, so that + it is automatically bound to the current Java thread. + </para> + + <para> + Next, the possible actions of the request are processed and the response HTML + is rendered. We will get to that part soon. + </para> + + <para> + Finally, the unit of work ends when processing and rendering are complete. If any + problems occurred during processing or rendering, an exception will be thrown + and the database transaction rolled back. This completes the + <literal>session-per-request</literal> pattern. Instead of the transaction + demarcation code in every servlet, you could also write a servlet filter. + See the Hibernate website and Wiki for more information about this pattern + called <emphasis>Open Session in View</emphasis>. You will need it as soon + as you consider rendering your view in JSP, not in a servlet. + </para> + + </section> + + <section id="tutorial-webapp-processing" revision="1"> + <title>Processing and rendering</title> + + <para> + Now you can implement the processing of the request and the rendering of the page. + </para> + +<programlisting role="JAVA"><![CDATA[ // Write HTML header + PrintWriter out = response.getWriter(); + out.println("<html><head><title>Event Manager</title></head><body>"); + + // Handle actions + if ( "store".equals(request.getParameter("action")) ) { + + String eventTitle = request.getParameter("eventTitle"); + String eventDate = request.getParameter("eventDate"); + + if ( "".equals(eventTitle) || "".equals(eventDate) ) { + out.println("<b><i>Please enter event title and date.</i></b>"); + } + else { + createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate)); + out.println("<b><i>Added event.</i></b>"); + } + } + + // Print page + printEventForm(out); + listEvents(out, dateFormatter); + + // Write HTML footer + out.println("</body></html>"); + out.flush(); + out.close();]]></programlisting> + + <para> + This coding style, with a mix of Java and HTML, would not scale + in a more complex application&mdash;keep in mind that we are only illustrating + basic Hibernate concepts in this tutorial. The code prints an HTML + header and a footer. Inside this page, an HTML form for event entry and + a list of all events in the database are printed. The first method is + trivial and only outputs HTML: + </para> + + <programlisting role="JAVA"><![CDATA[ private void printEventForm(PrintWriter out) { + out.println("<h2>Add new event:</h2>"); + out.println("<form>"); + out.println("Title: <input name='eventTitle' length='50'/><br/>"); + out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>"); + out.println("<input type='submit' name='action' value='store'/>"); + out.println("</form>"); + }]]></programlisting> + + <para> + The <literal>listEvents()</literal> method uses the Hibernate + <literal>Session</literal> bound to the current thread to execute + a query: + </para> + + <programlisting role="JAVA"><![CDATA[ private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) { + + List result = HibernateUtil.getSessionFactory() + .getCurrentSession().createCriteria(Event.class).list(); + if (result.size() > 0) { + out.println("<h2>Events in database:</h2>"); + out.println("<table border='1'>"); + out.println("<tr>"); + out.println("<th>Event title</th>"); + out.println("<th>Event date</th>"); + out.println("</tr>"); + Iterator it = result.iterator(); + while (it.hasNext()) { + Event event = (Event) it.next(); + out.println("<tr>"); + out.println("<td>" + event.getTitle() + "</td>"); + out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>"); + out.println("</tr>"); + } + out.println("</table>"); + } + }]]></programlisting> + + <para> + Finally, the <literal>store</literal> action is dispatched to the + <literal>createAndStoreEvent()</literal> method, which also uses + the <literal>Session</literal> of the current thread: + </para> + + <programlisting role="JAVA"><![CDATA[ protected void createAndStoreEvent(String title, Date theDate) { + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + + HibernateUtil.getSessionFactory() + .getCurrentSession().save(theEvent); + }]]></programlisting> + + <para> + The servlet is now complete. A request to the servlet will be processed + in a single <literal>Session</literal> and <literal>Transaction</literal>. As + earlier in the standalone application, Hibernate can automatically bind these + objects to the current thread of execution. This gives you the freedom to layer + your code and access the <literal>SessionFactory</literal> in any way you like. + Usually you would use a more sophisticated design and move the data access code + into data access objects (the DAO pattern). See the Hibernate Wiki for more + examples. + </para> + + </section> + + <section id="tutorial-webapp-deploy"> + <title>Deploying and testing</title> + + <para> + To deploy this application for testing we must create a + Web ARchive (WAR). First we must define the WAR descriptor + as <filename>src/main/webapp/WEB-INF/web.xml</filename> + </para> + + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<web-app version="2.4" + xmlns="http://java.sun.com/xml/ns/j2ee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> + + <servlet> + <servlet-name>Event Manager</servlet-name> + <servlet-class>org.hibernate.tutorial.web.EventManagerServlet</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>Event Manager</servlet-name> + <url-pattern>/eventmanager</url-pattern> + </servlet-mapping> +</web-app>]]></programlisting> + + <para> + To build and deploy call <literal>mvn package</literal> in your + project directory and copy the <filename>hibernate-tutorial.war</filename> + file into your Tomcat <filename>webapps</filename> directory. + </para> + + <note> + <para> + If you do not have Tomcat installed, download it from + <ulink url="http://tomcat.apache.org/"/> and follow the + installation instructions. Our application requires + no changes to the standard Tomcat configuration. + </para> + </note> + + <para> + Once deployed and Tomcat is running, access the application at + <literal>http://localhost:8080/hibernate-tutorial/eventmanager</literal>. Make + sure you watch the Tomcat log to see Hibernate initialize when the first + request hits your servlet (the static initializer in <literal>HibernateUtil</literal> + is called) and to get the detailed output if any exceptions occurs. + </para> + + </section> + + </section> + + <section id="tutorial-summary" revision="1"> + <title>Summary</title> + + <para> + This tutorial covered the basics of writing a simple standalone Hibernate application + and a small web application. More tutorials are available from the Hibernate + <ulink url="http://hibernate.org">website</ulink>. + </para> + + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/type.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/type.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/type.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1020 @@ +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Inc. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<chapter id="types"> + <title>Types</title> + + <para> + As an Object/Relational Mapping solution, Hibernate deals with both the Java and JDBC representations of + application data. An online catalog application, for example, most likely has <classname>Product</classname> + object with a number of attributes such as a <literal>sku</literal>, <literal>name</literal>, etc. For these + individual attributes, Hibernate must be able to read the values out of the database and write them back. This + 'marshalling' is the function of a <emphasis>Hibernate type</emphasis>, which is an implementation of the + <interfacename>org.hibernate.type.Type</interfacename> interface. In addition, a + <emphasis>Hibernate type</emphasis> describes various aspects of behavior of the Java type such as "how is + equality checked?" or "how are values cloned?". + </para> + + <important> + <para> + A Hibernate type is neither a Java type nor a SQL datatype; it provides a information about both. + </para> + <para> + When you encounter the term <emphasis>type</emphasis> in regards to Hibernate be aware that usage might + refer to the Java type, the SQL/JDBC type or the Hibernate type. + </para> + </important> + + <para> + Hibernate categorizes types into two high-level groups: value types (see <xref linkend="types.value"/>) and + entity types (see <xref linkend="types.entity"/>). + </para> + + <section id="types.value"> + <title>Value types</title> + + <para> + The main distinguishing characteristic of a value type is the fact that they do not define their own + lifecycle. We say that they are "owned" by something else (specifically an entity, as we will see later) + which defines their lifecycle. Value types are further classified into 3 sub-categories: basic types (see + <xref linkend="types.value.basic"/>), composite types (see <xref linkend="types.value.composite"/>) + amd collection types (see <xref linkend="types.value.collection"/>). + </para> + + <section id="types.value.basic"> + <title>Basic value types</title> + <para> + The norm for basic value types is that they map a single database value (column) to a single, + non-aggregated Java type. Hibernate provides a number of built-in basic types, which we will present + in the following sections by the Java type. Mainly these follow the natural mappings recommended in the + JDBC specification. We will later cover how to override these mapping and how to provide and use + alternative type mappings. + </para> + <section id="types.value.basic.string"> + <title>java.lang.String</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.StringType</classname></term> + <listitem> + <para> + Maps a string to the JDBC VARCHAR type. This is the standard mapping for a string if + no Hibernate type is specified. + </para> + <para> + Registered under <literal>string</literal> and <literal>java.lang.String</literal> + in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.MaterializedClob</classname></term> + <listitem> + <para> + Maps a string to a JDBC CLOB type + </para> + <para> + Registered under <literal>materialized_clob</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.TextType</classname></term> + <listitem> + <para> + Maps a string to a JDBC LONGVARCHAR type + </para> + <para> + Registered under <literal>text</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.character"> + <title><classname>java.lang.Character</classname> (or char primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.CharacterType</classname></term> + <listitem> + <para> + Maps a char or <classname>java.lang.Character</classname> to a JDBC CHAR + </para> + <para> + Registered under <literal>char</literal> and <literal>java.lang.Character</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.value.basic.boolean"> + <title><classname>java.lang.Boolean</classname> (or boolean primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BooleanType</classname></term> + <listitem> + <para> + Maps a boolean to a JDBC BIT type + </para> + <para> + Registered under <literal>boolean</literal> and <literal>java.lang.Boolean</literal> in + the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.NumericBooleanType</classname></term> + <listitem> + <para> + Maps a boolean to a JDBC INTEGER type as 0 = false, 1 = true + </para> + <para> + Registered under <literal>numeric_boolean</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.YesNoType</classname></term> + <listitem> + <para> + Maps a boolean to a JDBC CHAR type as ('N' | 'n') = false, ( 'Y' | 'y' ) = true + </para> + <para> + Registered under <literal>yes_no</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.TrueFalseType</classname></term> + <listitem> + <para> + Maps a boolean to a JDBC CHAR type as ('F' | 'f') = false, ( 'T' | 't' ) = true + </para> + <para> + Registered under <literal>true_false</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.byte"> + <title><classname>java.lang.Byte</classname> (or byte primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.ByteType</classname></term> + <listitem> + <para> + Maps a byte or <classname>java.lang.Byte</classname> to a JDBC TINYINT + </para> + <para> + Registered under <literal>byte</literal> and <literal>java.lang.Byte</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.short"> + <title><classname>java.lang.Short</classname> (or short primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.ShortType</classname></term> + <listitem> + <para> + Maps a short or <classname>java.lang.Short</classname> to a JDBC SMALLINT + </para> + <para> + Registered under <literal>short</literal> and <literal>java.lang.Short</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.int"> + <title><classname>java.lang.Integer</classname> (or int primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.IntegerTypes</classname></term> + <listitem> + <para> + Maps an int or <classname>java.lang.Integer</classname> to a JDBC INTEGER + </para> + <para> + Registered under <literal>int</literal> and <literal>java.lang.Integer</literal>in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.long"> + <title><classname>java.lang.Long</classname> (or long primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.LongType</classname></term> + <listitem> + <para> + Maps a long or <classname>java.lang.Long</classname> to a JDBC BIGINT + </para> + <para> + Registered under <literal>long</literal> and <literal>java.lang.Long</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.float"> + <title><classname>java.lang.Float</classname> (or float primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.FloatType</classname></term> + <listitem> + <para> + Maps a float or <classname>java.lang.Float</classname> to a JDBC FLOAT + </para> + <para> + Registered under <literal>float</literal> and <literal>java.lang.Float</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.double"> + <title><classname>java.lang.Double</classname> (or double primitive)</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.DoubleType</classname></term> + <listitem> + <para> + Maps a double or <classname>java.lang.Double</classname> to a JDBC DOUBLE + </para> + <para> + Registered under <literal>double</literal> and <literal>java.lang.Double</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.biginteger"> + <title><classname>java.math.BigInteger</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BigIntegerType</classname></term> + <listitem> + <para> + Maps a <classname>java.math.BigInteger</classname> to a JDBC NUMERIC + </para> + <para> + Registered under <literal>big_integer</literal> and <literal>java.math.BigInteger</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.bigdecimal"> + <title><classname>java.math.BigDecimal</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BigDecimalType</classname></term> + <listitem> + <para> + Maps a <classname>java.math.BigDecimal</classname> to a JDBC NUMERIC + </para> + <para> + Registered under <literal>big_decimal</literal> and <literal>java.math.BigDecimal</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.timestamp"> + <title><classname>java.util.Date</classname> or <classname>java.sql.Timestamp</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.TimestampType</classname></term> + <listitem> + <para> + Maps a <classname>java.sql.Timestamp</classname> to a JDBC TIMESTAMP + </para> + <para> + Registered under <literal>timestamp</literal>, <literal>java.sql.Timestamp</literal> and + <literal>java.util.Date</literal> in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.time"> + <title><classname>java.sql.Time</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.TimeType</classname></term> + <listitem> + <para> + Maps a <classname>java.sql.Time</classname> to a JDBC TIME + </para> + <para> + Registered under <literal>time</literal> and <literal>java.sql.Time</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.date"> + <title><classname>java.sql.Date</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.DateType</classname></term> + <listitem> + <para> + Maps a <classname>java.sql.Date</classname> to a JDBC DATE + </para> + <para> + Registered under <literal>date</literal> and <literal>java.sql.Date</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.calendar"> + <title><classname>java.util.Calendar</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.CalendarType</classname></term> + <listitem> + <para> + Maps a <classname>java.util.Calendar</classname> to a JDBC TIMESTAMP + </para> + <para> + Registered under <literal>calendar</literal>, <literal>java.util.Calendar</literal> and + <literal>java.util.GregorianCalendar</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.CalendarDateType</classname></term> + <listitem> + <para> + Maps a <classname>java.util.Calendar</classname> to a JDBC DATE + </para> + <para> + Registered under <literal>calendar_date</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.currency"> + <title><classname>java.util.Currency</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.CurrencyType</classname></term> + <listitem> + <para> + Maps a <classname>java.util.Currency</classname> to a JDBC VARCHAR (using the Currency code) + </para> + <para> + Registered under <literal>currency</literal> and <literal>java.util.Currency</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.locale"> + <title><classname>java.util.Locale</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.LocaleType</classname></term> + <listitem> + <para> + Maps a <classname>java.util.Locale</classname> to a JDBC VARCHAR (using the Locale code) + </para> + <para> + Registered under <literal>locale</literal> and <literal>java.util.Locale</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.timezone"> + <title><classname>java.util.TimeZone</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.TimeZoneType</classname></term> + <listitem> + <para> + Maps a <classname>java.util.TimeZone</classname> to a JDBC VARCHAR (using the TimeZone ID) + </para> + <para> + Registered under <literal>timezone</literal> and <literal>java.util.TimeZone</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.class"> + <title><classname>java.lang.Class</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.ClassType</classname></term> + <listitem> + <para> + Maps a <classname>java.lang.Class</classname> to a JDBC VARCHAR (using the Class name) + </para> + <para> + Registered under <literal>class</literal> and <literal>java.lang.Class</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.blob"> + <title><classname>java.sql.Blob</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BlobType</classname></term> + <listitem> + <para> + Maps a <classname>java.sql.Blob</classname> to a JDBC BLOB + </para> + <para> + Registered under <literal>blob</literal> and <literal>java.sql.Blob</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.clob"> + <title><classname>java.sql.Clob</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.ClobType</classname></term> + <listitem> + <para> + Maps a <classname>java.sql.Clob</classname> to a JDBC CLOB + </para> + <para> + Registered under <literal>clob</literal> and <literal>java.sql.Clob</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.binary"> + <title>byte[]</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BinaryType</classname></term> + <listitem> + <para> + Maps a primitive byte[] to a JDBC VARBINARY + </para> + <para> + Registered under <literal>binary</literal> and <literal>byte[]</literal> in the + type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.MaterializedBlobType</classname></term> + <listitem> + <para> + Maps a primitive byte[] to a JDBC BLOB + </para> + <para> + Registered under <literal>materialized_blob</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.wrapperbinary"> + <title>byte[]</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.BinaryType</classname></term> + <listitem> + <para> + Maps a java.lang.Byte[] to a JDBC VARBINARY + </para> + <para> + Registered under <literal>wrapper-binary</literal>, <literal>Byte[]</literal> and + <literal>java.lang.Byte[]</literal> in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.chararray"> + <title>char[]</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.CharArrayType</classname></term> + <listitem> + <para> + Maps a char[] to a JDBC VARCHAR + </para> + <para> + Registered under <literal>characters</literal> and <literal>char[]</literal> + in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.characterarray"> + <title>char[]</title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.CharacterArrayType</classname></term> + <listitem> + <para> + Maps a java.lang.Character[] to a JDBC VARCHAR + </para> + <para> + Registered under <literal>wrapper-characters</literal>, <literal>Character[]</literal> + and <literal>java.lang.Character[]</literal> in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.uuid"> + <title><classname>java.util.UUID</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.UUIDBinaryType</classname></term> + <listitem> + <para> + Maps a java.util.UUID to a JDBC BINARY + </para> + <para> + Registered under <literal>uuid-binary</literal> and <literal>java.util.UUID</literal> + in the type registry (see <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.UUIDCharType</classname></term> + <listitem> + <para> + Maps a java.util.UUID to a JDBC CHAR (though VARCHAR is fine too for existing schemas) + </para> + <para> + Registered under <literal>uuid-char</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><classname>org.hibernate.type.PostgresUUIDType</classname></term> + <listitem> + <para> + Maps a java.util.UUID to the PostgreSQL UUID data type (through + <literal>Types#OTHER</literal> which is how the PostgreSQL JDBC driver defines it). + </para> + <para> + Registered under <literal>pg-uuid</literal> in the type registry (see + <xref linkend="types.registry"/>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="types.basic.value.serializable"> + <title><classname>java.io.Serializable</classname></title> + <variablelist> + <varlistentry> + <term><classname>org.hibernate.type.SerializableType</classname></term> + <listitem> + <para> + Maps implementors of java.lang.Serializable to a JDBC VARBINARY + </para> + <para> + Unlike the other value types, there are multiple instances of this type. It + gets registered once under <literal>java.io.Serializable</literal>. Additionally it + gets registered under the specific <interfacename>java.io.Serializable</interfacename> + implementation class names. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + + <section id="types.value.composite"> + <title>Composite types</title> + <note> + <para> + The Java Persistence API calls these embedded types, while Hibernate traditionally called them + components. Just be aware that both terms are used and mean the same thing in the scope of + discussing Hibernate. + </para> + </note> + <para> + Components represent aggregations of values into a single Java type. For example, you might have + an Address class that aggregates street, city, state, etc information or a Name class that + aggregates the parts of a person's Name. In many ways a component looks exactly like an entity. They + are both (generally speaking) classes written specifically for the application. They both might have + references to other application-specific classes, as well as to collections and simple JDK types. As + discussed before, the only distinguishing factory is the fact that a component does not own its own + lifecycle. + </para> + </section> + + <section id="types.value.collection"> + <title>Collection types</title> + <important> + <para> + It is critical understand that we mean the collection itself, not its contents. + The contents of the collection can in turn be basic, component or entity types (though not + collections), but the collection itself is owned. + </para> + </important> + <para> + Collections are covered in <xref linkend="collections"/>. + </para> + </section> + + </section> + + <section id="types.entity"> + <title>Entity types</title> + <para> + The definition of entities is covered in detail in <xref linkend="persistent-classes"/>. For the purpose of + this discussion, it is enough to say that entities are (generally application-specific) classes which + correlate to rows in a table. Specifically they correlate to the row by means of a unique identifier. + Because of this unique identifier, entities exist independently and define their own lifecycle. As an example, + when we delete a <classname>Membership</classname>, both the <classname>User</classname> and + <classname>Group</classname> entities remain. + <note> + <para> + This notion of entity independence can be modified by the application developer using the concept of + cascades. Cascades allow certain operations to continue (or "cascade") across an association from + one entity to another. Cascades are covered in detail in <xref linkend="associations"/>. + </para> + </note> + </para> + </section> + + <section id="types.category.significance"> + <title>Significance of type categories</title> + <para> + Why do we spend so much time categorizing the various types of types? What is the significance of the + distinction? + </para> + <para> + The main categorization was between entity types and value types. To review we said that entities, by + nature of their unique identifier, exist independently of other objects whereas values do not. An + application cannot "delete" a Product sku; instead, the sku is removed when the Product itself is + deleted (obviously you can <emphasis>update</emphasis> the sku of that Product to null to make it + "go away", but even there the access is done through the Product). + </para> + <para> + Nor can you define an association <emphasis>to</emphasis> that Product sku. You <emphasis>can</emphasis> + define an association to Product <emphasis>based on</emphasis> its sku, assuming sku is unique, but that + is totally different. + </para> + <para> + TBC... + </para> + </section> + + <section id="types.custom"> + <title>Custom types</title> + <para> + Hibernate makes it relatively easy for developers to create their own <emphasis>value</emphasis> types. For + example, you might want to persist properties of type <classname>java.lang.BigInteger</classname> to + <literal>VARCHAR</literal> columns. Custom types are not limited to mapping values to a single table + column. So, for example, you might want to concatenate together <literal>FIRST_NAME</literal>, + <literal>INITIAL</literal> and <literal>SURNAME</literal> columsn into a <classname>java,lang.String</classname>. + </para> + + <para> + There are 3 approaches to developing a custom Hibernate type. As a means of illustrating the different + approaches, lets consider a use case where we need to compose a <classname>java.math.BigDecimal</classname> + and <classname>java.util.Currency</classname> together into a custom <classname>Money</classname> class. + </para> + + <section id="types.custom.type"> + <title>Custom types using <interfacename>org.hibernate.type.Type</interfacename></title> + <para> + The first approach is to directly implement the <interfacename>org.hibernate.type.Type</interfacename> + interface (or one of its derivatives). Probably, you will be more interested in the more specific + <interfacename>org.hibernate.type.BasicType</interfacename> contract which would allow registration of + the type (see <xref linkend="types.registry"/>). The benefit of this registration is that whenever + the metadata for a particular property does not specify the Hibernate type to use, Hibernate will + consult the registry for the exposed property type. In our example, the property type would be + <classname>Money</classname>, which is the key we would use to register our type in the registry: + <example id="types.custom.type.ex.definition"> + <title>Defining and registering the custom Type</title> + <programlisting role="JAVA"><![CDATA[public class MoneyType implements BasicType { + public String[] getRegistrationKeys() { + return new String[] { Money.class.getName() }; + } + + public int[] sqlTypes(Mapping mapping) { + // We will simply use delegation to the standard basic types for BigDecimal and Currency for many of the + // Type methods... + return new int[] { + BigDecimalType.INSTANCE.sqlType(), + CurrencyType.INSTANCE.sqlType(), + }; + // we could also have honored any registry overrides via... + //return new int[] { + // mappings.getTypeResolver().basic( BigDecimal.class.getName() ).sqlTypes( mappings )[0], + // mappings.getTypeResolver().basic( Currency.class.getName() ).sqlTypes( mappings )[0] + //}; + } + + public Class getReturnedClass() { + return Money.class; + } + + public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner) throws SQLException { + assert names.length == 2; + BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check + Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check + return amount == null && currency == null + ? null + : new Money( amount, currency ); + } + + public void nullSafeSet(PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session) + throws SQLException { + if ( value == null ) { + BigDecimalType.INSTANCE.set( st, null, index ); + CurrencyType.INSTANCE.set( st, null, index+1 ); + } + else { + final Money money = (Money) value; + BigDecimalType.INSTANCE.set( st, money.getAmount(), index ); + CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 ); + } + } + + ... +}]]></programlisting> + <programlisting role="JAVA"> + Configuration cfg = new Configuration(); + cfg.registerTypeOverride( new MoneyType() ); + cfg...; + </programlisting> + </example> + <important> + <para> + It is important that we registered the type <emphasis>before</emphasis> adding mappings. + </para> + </important> + </para> + </section> + + <section id="types.custom.ut"> + <title>Custom types using <interfacename>org.hibernate.usertype.UserType</interfacename></title> + <note> + <para> + Both <interfacename>org.hibernate.usertype.UserType</interfacename> and + <interfacename>org.hibernate.usertype.CompositeUserType</interfacename> were originally + added to isolate user code from internal changes to the <interfacename>org.hibernate.type.Type</interfacename> + interfaces. + </para> + </note> + <para> + The second approach is the use the <interfacename>org.hibernate.usertype.UserType</interfacename> + interface, which presents a somewhat simplified view of the <interfacename>org.hibernate.type.Type</interfacename> + interface. Using a <interfacename>org.hibernate.usertype.UserType</interfacename>, our + <classname>Money</classname> custom type would look as follows: + </para> + <example id="types.custom.ut.ex.definition"> + <title>Defining the custom UserType</title> + <programlisting role="JAVA"><![CDATA[public class MoneyType implements UserType { + public int[] sqlTypes() { + return new int[] { + BigDecimalType.INSTANCE.sqlType(), + CurrencyType.INSTANCE.sqlType(), + }; + } + + public Class getReturnedClass() { + return Money.class; + } + + public Object nullSafeGet(ResultSet rs, String[] names, Object owner) throws SQLException { + assert names.length == 2; + BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check + Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check + return amount == null && currency == null + ? null + : new Money( amount, currency ); + } + + public void nullSafeSet(PreparedStatement st, Object value, int index) throws SQLException { + if ( value == null ) { + BigDecimalType.INSTANCE.set( st, null, index ); + CurrencyType.INSTANCE.set( st, null, index+1 ); + } + else { + final Money money = (Money) value; + BigDecimalType.INSTANCE.set( st, money.getAmount(), index ); + CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 ); + } + } + + ... +}]]></programlisting> + </example> + <para> + There is not much difference between the <interfacename>org.hibernate.type.Type</interfacename> example + and the <interfacename>org.hibernate.usertype.UserType</interfacename> example, but that is only because + of the snippets shown. If you choose the <interfacename>org.hibernate.type.Type</interfacename> approach + there are quite a few more methods you would need to implement as compared to the + <interfacename>org.hibernate.usertype.UserType</interfacename>. + </para> + </section> + + <section id="types.custom.cut"> + <title>Custom types using <interfacename>org.hibernate.usertype.CompositeUserType</interfacename></title> + <para> + The third and final approach is the use the <interfacename>org.hibernate.usertype.CompositeUserType</interfacename> + interface, which differs from <interfacename>org.hibernate.usertype.UserType</interfacename> in that it + gives us the ability to provide Hibernate the information to handle the composition within the + <classname>Money</classname> class (specifically the 2 attributes). THis would give us the capability, + for example, to reference the <literal>amount</literal> attribute in an HQL query. Using a + <interfacename>org.hibernate.usertype.UserType</interfacename>, our <classname>Money</classname> custom + type would look as follows: + </para> + + <example id="types.custom.cut.ex.definition"> + <title>Defining the custom CompositeUserType</title> + <programlisting role="JAVA"><![CDATA[public class MoneyType implements CompositeUserType { + public String[] getPropertyNames() { + // ORDER IS IMPORTANT! it must match the order the columns are defined in the property mapping + return new String[] { "amount", "currency" }; + } + + public Type[] getPropertyTypes() { + return new Type[] { BigDecimalType.INSTANCE, CurrencyType.INSTANCE }; + } + + public Class getReturnedClass() { + return Money.class; + } + + public Object getPropertyValue(Object component, int propertyIndex) { + if ( component == null ) { + return null; + } + + final Money money = (Money) component; + switch ( propertyIndex ) { + case 0: { + return money.getAmount(); + } + case 1: { + return money.getCurrency(); + } + default: { + throw new HibernateException( "Invalid property index [" + propertyIndex + "]" ); + } + } + } + + public void setPropertyValue(Object component, int propertyIndex, Object value) throws HibernateException { + if ( component == null ) { + return; + } + + final Money money = (Money) component; + switch ( propertyIndex ) { + case 0: { + money.setAmount( (BigDecimal) value ); + break; + } + case 1: { + money.setCurrency( (Currency) value ); + break; + } + default: { + throw new HibernateException( "Invalid property index [" + propertyIndex + "]" ); + } + } + } + + public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner) throws SQLException { + assert names.length == 2; + BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check + Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check + return amount == null && currency == null + ? null + : new Money( amount, currency ); + } + + public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session) throws SQLException { + if ( value == null ) { + BigDecimalType.INSTANCE.set( st, null, index ); + CurrencyType.INSTANCE.set( st, null, index+1 ); + } + else { + final Money money = (Money) value; + BigDecimalType.INSTANCE.set( st, money.getAmount(), index ); + CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 ); + } + } + + ... +}]]></programlisting> + </example> + </section> + + </section> + + <section id="types.registry"> + <title>Type registry</title> + <para> + Internally Hibernate uses a registry of basic types (see <xref linkend="types.value.basic"/>) when + it needs to resolve the specific <interfacename>org.hibernate.type.Type</interfacename> to use in certain + situations. It also provides a way for applications to add extra basic type registrations as well as + override the standard basic type registrations. + </para> + <para> + To register a new type or to override an existing type registration, applications would make use of the + <methodname>registerTypeOverride</methodname> method of the <classname>org.hibernate.cfg.Configuration</classname> + class when bootstrapping Hibernate. For example, lets say you want Hibernate to use your custom + <classname>SuperDuperStringType</classname>; during bootstrap you would call: + <example id="type.registry.override.ex"> + <title>Overriding the standard <classname>StringType</classname></title> + <programlisting role="JAVA"><![CDATA[Configuration cfg = ...; + cfg.registerTypeOverride( new SuperDuperStringType() );]]></programlisting> + </example> + </para> + <para> + The argument to <methodname>registerTypeOverride</methodname> is a <interfacename>org.hibernate.type.BasicType</interfacename> + which is a specialization of the <interfacename>org.hibernate.type.Type</interfacename> we saw before. It + adds a single method: + <example> + <title>Snippet from BasicType.java</title> + <programlisting role="JAVA" > + /** + * Get the names under which this type should be registered in the type registry. + * + * @return The keys under which to register this type. + */ + public String[] getRegistrationKeys(); + </programlisting> + </example> + One approach is to use inheritance (<classname>SuperDuperStringType</classname> extends + <classname>org.hibernate.typeStringType</classname>). Another approach is to use delegation. + </para> + <important> + <para> + Currently UserType and CompositeUserType cannot be registered with the registry. See + <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-5... for details. + </para> + </important> + </section> + +</chapter> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/xml.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/xml.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/content/xml.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,317 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> +%BOOK_ENTITIES; + +]> + +<chapter id="xml"> + <title>XML Mapping</title> + + <para><emphasis> + XML Mapping is an experimental feature in Hibernate 3.0 and is currently under + active development. + </emphasis></para> + + <section id="xml-intro" revision="1"> + <title>Working with XML data</title> + + <para> + Hibernate allows you to work with persistent XML data in much the same way + you work with persistent POJOs. A parsed XML tree can be thought of + as another way of representing the relational data at the object level, + instead of POJOs. + </para> + + <para> + Hibernate supports dom4j as API for manipulating XML trees. You can write + queries that retrieve dom4j trees from the database and have any + modification you make to the tree automatically synchronized to the + database. You can even take an XML document, parse it using dom4j, and + write it to the database with any of Hibernate's basic operations: + <literal>persist(), saveOrUpdate(), merge(), delete(), replicate()</literal> + (merging is not yet supported). + </para> + + <para> + This feature has many applications including data import/export, + externalization of entity data via JMS or SOAP and XSLT-based reporting. + </para> + + <para> + A single mapping can be used to simultaneously map properties of a class + and nodes of an XML document to the database, or, if there is no class to map, + it can be used to map just the XML. + </para> + + <section id="xml-intro-mapping"> + <title>Specifying XML and class mapping together</title> + + <para> + Here is an example of mapping a POJO and XML simultaneously: + </para> + + <programlisting role="XML"><![CDATA[<class name="Account" + table="ACCOUNTS" + node="account"> + + <id name="accountId" + column="ACCOUNT_ID" + node="@id"/> + + <many-to-one name="customer" + column="CUSTOMER_ID" + node="customer/@id" + embed-xml="false"/> + + <property name="balance" + column="BALANCE" + node="balance"/> + + ... + +</class>]]></programlisting> + </section> + + <section id="xml-onlyxml"> + <title>Specifying only an XML mapping</title> + + <para> + Here is an example where there is no POJO class: + </para> + + <programlisting role="XML"><![CDATA[<class entity-name="Account" + table="ACCOUNTS" + node="account"> + + <id name="id" + column="ACCOUNT_ID" + node="@id" + type="string"/> + + <many-to-one name="customerId" + column="CUSTOMER_ID" + node="customer/@id" + embed-xml="false" + entity-name="Customer"/> + + <property name="balance" + column="BALANCE" + node="balance" + type="big_decimal"/> + + ... + +</class>]]></programlisting> + + <para> + This mapping allows you to access the data as a dom4j tree, or as a graph of + property name/value pairs or java <literal>Map</literal>s. The property names + are purely logical constructs that can be referred to in HQL queries. + </para> + + </section> + + </section> + + <section id="xml-mapping" revision="1"> + <title>XML mapping metadata</title> + + <para> + A range of Hibernate mapping elements accept the <literal>node</literal> attribute. + This lets you specify the name of an XML attribute or element that holds the + property or entity data. The format of the <literal>node</literal> attribute + must be one of the following: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para><literal>"element-name"</literal>: map to the named XML element</para> + </listitem> + <listitem> + <para><literal>"@attribute-name"</literal>: map to the named XML attribute</para> + </listitem> + <listitem> + <para><literal>"."</literal>: map to the parent element</para> + </listitem> + <listitem> + <para> + <literal>"element-name/@attribute-name"</literal>: + map to the named attribute of the named element + </para> + </listitem> + </itemizedlist> + + <para> + For collections and single valued associations, there is an additional + <literal>embed-xml</literal> attribute. If <literal>embed-xml="true"</literal>, + the default, the XML tree for the associated entity (or collection of value type) + will be embedded directly in the XML tree for the entity that owns the association. + Otherwise, if <literal>embed-xml="false"</literal>, then only the referenced + identifier value will appear in the XML for single point associations and + collections will not appear at all. + </para> + + <para> + Do not leave <literal>embed-xml="true"</literal> for + too many associations, since XML does not deal well with circularity. + </para> + + <programlisting role="XML"><![CDATA[<class name="Customer" + table="CUSTOMER" + node="customer"> + + <id name="id" + column="CUST_ID" + node="@id"/> + + <map name="accounts" + node="." + embed-xml="true"> + <key column="CUSTOMER_ID" + not-null="true"/> + <map-key column="SHORT_DESC" + node="@short-desc" + type="string"/> + <one-to-many entity-name="Account" + embed-xml="false" + node="account"/> + </map> + + <component name="name" + node="name"> + <property name="firstName" + node="first-name"/> + <property name="initial" + node="initial"/> + <property name="lastName" + node="last-name"/> + </component> + + ... + +</class>]]></programlisting> + + <para> + In this case, the collection of account ids is embedded, but not + the actual account data. The following HQL query: + </para> + + <programlisting><![CDATA[from Customer c left join fetch c.accounts where c.lastName like :lastName]]></programlisting> + + <para> + would return datasets such as this: + </para> + + <programlisting role="XML"><![CDATA[<customer id="123456789"> + <account short-desc="Savings">987632567</account> + <account short-desc="Credit Card">985612323</account> + <name> + <first-name>Gavin</first-name> + <initial>A</initial> + <last-name>King</last-name> + </name> + ... +</customer>]]></programlisting> + + <para> + If you set <literal>embed-xml="true"</literal> on the <literal>&lt;one-to-many&gt;</literal> + mapping, the data might look more like this: + </para> + + <programlisting role="XML"><![CDATA[<customer id="123456789"> + <account id="987632567" short-desc="Savings"> + <customer id="123456789"/> + <balance>100.29</balance> + </account> + <account id="985612323" short-desc="Credit Card"> + <customer id="123456789"/> + <balance>-2370.34</balance> + </account> + <name> + <first-name>Gavin</first-name> + <initial>A</initial> + <last-name>King</last-name> + </name> + ... +</customer>]]></programlisting> + + </section> + + + <section id="xml-manipulation" revision="1"> + <title>Manipulating XML data</title> + + <para> + You can also re-read and update XML documents in the application. You can do this by + obtaining a dom4j session: + </para> + + <programlisting role="JAVA"><![CDATA[Document doc = ....; + +Session session = factory.openSession(); +Session dom4jSession = session.getSession(EntityMode.DOM4J); +Transaction tx = session.beginTransaction(); + +List results = dom4jSession + .createQuery("from Customer c left join fetch c.accounts where c.lastName like :lastName") + .list(); +for ( int i=0; i<results.size(); i++ ) { + //add the customer data to the XML document + Element customer = (Element) results.get(i); + doc.add(customer); +} + +tx.commit(); +session.close();]]></programlisting> + + <programlisting role="JAVA"><![CDATA[Session session = factory.openSession(); +Session dom4jSession = session.getSession(EntityMode.DOM4J); +Transaction tx = session.beginTransaction(); + +Element cust = (Element) dom4jSession.get("Customer", customerId); +for ( int i=0; i<results.size(); i++ ) { + Element customer = (Element) results.get(i); + //change the customer name in the XML and database + Element name = customer.element("name"); + name.element("first-name").setText(firstName); + name.element("initial").setText(initial); + name.element("last-name").setText(lastName); +} + +tx.commit(); +session.close();]]></programlisting> + + <para> + When implementing XML-based data import/export, it is useful to combine this feature with Hibernate's <literal>replicate()</literal> + operation. + </para> + + </section> + +</chapter> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/extras/namespacing.xml_sample =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/extras/namespacing.xml_sample (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/extras/namespacing.xml_sample 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,15 @@ +<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [ + <!ENTITY types SYSTEM "classpath://your/domain/types.xml"> +]> + +<hibernate-mapping package="your.domain"> + <class name="MyEntity"> + <id name="id" type="my-custom-id-type"> + ... + </id> + <class> + &types; +</hibernate-mapping> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Conventions.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Conventions.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Conventions.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,165 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<section> + <title>Document Conventions</title> + <para> + This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. + </para> + <para> + In PDF and paper editions, this manual uses typefaces drawn from the <ulink url="https://fedorahosted.org/liberation-fonts/">Liberation Fonts</ulink> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default. + </para> + <section> + <title>Typographic Conventions</title> + <para> + Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows. + </para> + <para> + <literal>Mono-spaced Bold</literal> + </para> + <para> + Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example: + </para> + <blockquote> + <para> + To see the contents of the file <filename>my_next_bestselling_novel</filename> in your current working directory, enter the <command>cat my_next_bestselling_novel</command> command at the shell prompt and press <keycap>Enter</keycap> to execute the command. + </para> + </blockquote> + <para> + The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context. + </para> + <para> + Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example: + </para> + <blockquote> + <para> + Press <keycap>Enter</keycap> to execute the command. + </para> + <para> + Press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> to switch to the first virtual terminal. Press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F7</keycap></keycombo> to return to your X-Windows session. + </para> + </blockquote> + <para> + The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously). + </para> + <para> + If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in <literal>mono-spaced bold</literal>. For example: + </para> + <blockquote> + <para> + File-related classes include <classname>filesystem</classname> for file systems, <classname>file</classname> for files, and <classname>dir</classname> for directories. Each class has its own associated set of permissions. + </para> + </blockquote> + <para> + <application>Proportional Bold</application> + </para> + <para> + This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example: + </para> + <blockquote> + <para> + Choose <menuchoice><guimenu>System</guimenu><guisubmenu>Preferences</guisubmenu><guimenuitem>Mouse</guimenuitem></menuchoice> from the main menu bar to launch <application>Mouse Preferences</application>. In the <guilabel>Buttons</guilabel> tab, click the <guilabel>Left-handed mouse</guilabel> check box and click <guibutton>Close</guibutton> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). + </para> + <para> + To insert a special character into a <application>gedit</application> file, choose <menuchoice><guimenu>Applications</guimenu><guisubmenu>Accessories</guisubmenu><guimenuitem>Character Map</guimenuitem></menuchoice> from the main menu bar. Next, choose <menuchoice><guimenu>Search</guimenu><guimenuitem>Find&hellip;</guimenuitem></menuchoice> from the <application>Character Map</application> menu bar, type the name of the character in the <guilabel>Search</guilabel> field and click <guibutton>Next</guibutton>. The character you sought will be highlighted in the <guilabel>Character Table</guilabel>. Double-click this highlighted character to place it in the <guilabel>Text to copy</guilabel> field and then click the <guibutton>Copy</guibutton> button. Now switch back to your document and choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice> from the <application>gedit</application> menu bar. + </para> + </blockquote> + <para> + The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. + </para> + <para> + <command><replaceable>Mono-spaced Bold Italic</replaceable></command> or <application><replaceable>Proportional Bold Italic</replaceable></application> + </para> + <para> + Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: + </para> + <blockquote> + <para> + To connect to a remote machine using ssh, type <command>ssh <replaceable&gt;username&lt;/replaceable&gt;(a)&lt;replaceable&gt;domain.name&lt;/replaceable&gt;&lt;/command&gt; at a shell prompt. If the remote machine is <filename>example.com</filename> and your username on that machine is john, type <command>ssh john(a)example.com&lt;/command&gt;. + </para> + <para> + The <command>mount -o remount <replaceable>file-system</replaceable></command> command remounts the named file system. For example, to remount the <filename>/home</filename> file system, the command is <command>mount -o remount /home</command>. + </para> + <para> + To see the version of a currently installed package, use the <command>rpm -q <replaceable>package</replaceable></command> command. It will return a result as follows: <command><replaceable>package-version-release</replaceable></command>. + </para> + </blockquote> + <para> + Note the words in bold italics above &mdash; username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. + </para> + <para> + Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: + </para> + <blockquote> + <para> + Publican is a <firstterm>DocBook</firstterm> publishing system. + </para> + </blockquote> + </section> + + <section> + <title>Pull-quote Conventions</title> + <para> + Terminal output and source code listings are set off visually from the surrounding text. + </para> + <para> + Output sent to a terminal is set in <computeroutput>mono-spaced roman</computeroutput> and presented thus: + </para> + +<screen>books Desktop documentation drafts mss photos stuff svn +books_tests Desktop1 downloads images notes scripts svgs +</screen> + <para> + Source-code listings are also set in <computeroutput>mono-spaced roman</computeroutput> but add syntax highlighting as follows: + </para> + +<programlisting language="Java">package org.jboss.book.jca.ex1; + +import javax.naming.InitialContext; + +public class ExClient +{ + public static void main(String args[]) + throws Exception + { + InitialContext iniCtx = new InitialContext(); + Object ref = iniCtx.lookup("EchoBean"); + EchoHome home = (EchoHome) ref; + Echo echo = home.create(); + + System.out.println("Created Echo"); + + System.out.println("Echo.echo('Hello') = " + echo.echo("Hello")); + } +} +</programlisting> + </section> + + <section> + <title>Notes and Warnings</title> + <para> + Finally, we use three visual styles to draw attention to information that might otherwise be overlooked. + </para> + <note> + <title>Note</title> + <para> + Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier. + </para> + </note> + <important> + <title>Important</title> + <para> + Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' won't cause data loss but may cause irritation and frustration. + </para> + </important> + <warning> + <title>Warning</title> + <para> + Warnings should not be ignored. Ignoring warnings will most likely cause data loss. + </para> + </warning> + </section> + +</section> + + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Feedback.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Feedback.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Feedback.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<section> + <title>We Need Feedback!</title> + <indexterm> + <primary>feedback</primary> + <secondary>contact information for this manual</secondary> + </indexterm> + <para> + You should over ride this by creating your own local Feedback.xml file. + </para> +</section> + + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Legal_Notice.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Legal_Notice.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/fallback_content/Legal_Notice.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<legalnotice> + <para> + Copyright <trademark class="copyright"></trademark> &YEAR; &HOLDER; This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at <ulink url="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org...>). + </para> +</legalnotice> + Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.zargo =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/AuthorWork.zargo ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.zargo =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/CustomerOrderProduct.zargo ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.zargo =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/EmployerEmployee.zargo ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.svg =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.svg (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/full_cream.svg 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,429 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="354.331" + height="336.614" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,5.25349)" + style="font-size:12;" + id="g659"> + <rect + width="212.257" + height="57.2441" + x="17.9576" + y="100.132" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + transform="matrix(0.743454,0,0,0.482981,6.46949,52.2178)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <rect + width="325.86" + height="63.6537" + x="17.4083" + y="15.194" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="325.86" + height="63.6537" + x="13.6713" + y="12.4966" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + <g + transform="matrix(1.14345,0,0,0.729078,-1.67818,105.325)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <text + x="170.824753" + y="58.402939" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="170.824997" + y="58.402901" + id="tspan360"> +Application</tspan> + </text> + <text + x="178.076340" + y="364.281433" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="178.076004" + y="364.281006" + id="tspan421"> +Database</tspan> + </text> + <text + x="68.605331" + y="138.524582" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="68.605301" + y="138.524994" + id="tspan384"> +SessionFactory</tspan> + </text> + <rect + width="67.0014" + height="101.35" + x="196.927" + y="89.2389" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect387" /> + <rect + width="67.0014" + height="101.35" + x="194.633" + y="86.4389" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect388" /> + <text + x="249.108841" + y="173.885559" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text389"> + <tspan + x="249.108994" + y="173.886002" + id="tspan392"> +Session</tspan> + </text> + <rect + width="73.0355" + height="101.35" + x="270.995" + y="90.0018" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect395" /> + <rect + width="73.0355" + height="101.35" + x="267.869" + y="87.2018" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect396" /> + <text + x="328.593658" + y="174.715622" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text397"> + <tspan + x="328.593994" + y="174.716003" + id="tspan563"> +Transaction</tspan> + </text> + <g + transform="matrix(0.29544,0,0,0.397877,9.70533,103.96)" + style="font-size:12;" + id="g565"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect566" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect567" /> + </g> + <text + x="25.592752" + y="204.497803" + transform="scale(0.823795,0.823795)" + style="font-size:10;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text568"> + <tspan + x="25.592800" + y="204.498001" + id="tspan662"> +TransactionFactory</tspan> + </text> + <g + transform="matrix(0.298082,0,0,0.397877,99.6898,103.96)" + style="font-size:12;" + id="g573"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect574" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect575" /> + </g> + <text + x="134.030670" + y="205.532791" + transform="scale(0.823795,0.823795)" + style="font-size:10;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text576"> + <tspan + x="134.031006" + y="205.533005" + id="tspan664"> +ConnectionProvider</tspan> + </text> + <g + transform="matrix(1.14345,0,0,0.729078,-1.67818,38.9539)" + style="font-size:12;" + id="g587"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect588" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect589" /> + </g> + <rect + width="90.951" + height="44.4829" + x="25.6196" + y="206.028" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect594" /> + <rect + width="90.951" + height="44.4829" + x="24.4229" + y="204.135" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect595" /> + <text + x="85.575645" + y="282.300354" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text596"> + <tspan + x="85.575600" + y="282.299988" + id="tspan607"> +JNDI</tspan> + </text> + <rect + width="90.951" + height="44.4829" + x="236.937" + y="206.791" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect610" /> + <rect + width="90.951" + height="44.4829" + x="235.741" + y="204.898" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect611" /> + <text + x="342.093201" + y="283.226410" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text612"> + <tspan + x="342.092987" + y="283.226013" + id="tspan621"> +JTA</tspan> + </text> + <rect + width="90.951" + height="44.4829" + x="130.134" + y="206.791" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect616" /> + <rect + width="90.951" + height="44.4829" + x="128.937" + y="204.898" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect617" /> + <text + x="212.445343" + y="283.226410" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text618"> + <tspan + x="212.445007" + y="283.226013" + id="tspan623"> +JDBC</tspan> + </text> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,6.19341)" + style="font-size:12;" + id="g637"> + <g + transform="matrix(0.499515,0,0,0.415467,-0.237339,5.61339)" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="33.749969" + y="50.589706" + style="font-size:11;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="33.750000" + y="50.589699" + id="tspan635"> +Transient Objects</tspan> + </text> + </g> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,5.25349)" + style="font-size:12;" + id="g644"> + <g + transform="matrix(0.297486,0,0,0.516482,230.251,36.9178)" + id="g364"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect365" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect366" /> + </g> + <text + x="277.123230" + y="85.155571" + style="font-size:11;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text367"> + <tspan + x="277.122986" + y="85.155602" + id="tspan631"> +Persistent</tspan> + <tspan + x="277.122986" + y="96.155602" + id="tspan633"> +Objects</tspan> + </text> + </g> +</svg> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/hibernate_logo_a.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/hibernate_logo_a.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.svg =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.svg (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/lite.svg 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,334 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="318.898" + height="248.031" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <rect + width="291.837" + height="57.0074" + x="17.3169" + y="18.646" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="291.837" + height="57.0074" + x="13.9703" + y="16.2302" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + <g + transform="matrix(0.326107,0,0,0.765831,9.59261,8.98517)" + style="font-size:12;" + id="g161"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <g + transform="matrix(1.02406,0,0,0.652953,0.223384,39.9254)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <g + transform="matrix(0.449834,0,0,0.338463,-3.15909,9.73319)" + style="font-size:12;" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="302.277679" + y="65.943230" + transform="scale(0.73778,0.73778)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="302.277954" + y="65.943184" + id="tspan360"> +Application</tspan> + </text> + <text + x="36.235924" + y="63.796055" + transform="scale(0.73778,0.73778)" + style="font-size:14;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="36.235950" + y="63.796051" + id="tspan427"> +Transient Objects</tspan> + </text> + <text + x="180.416245" + y="290.543701" + transform="scale(0.73778,0.73778)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="180.415939" + y="290.543549" + id="tspan421"> +Database</tspan> + </text> + <text + x="25.037701" + y="179.154755" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="25.037655" + y="179.154648" + id="tspan384"> +SessionFactory</tspan> + </text> + <g + transform="matrix(0.252763,0,0,0.765831,109.104,8.98517)" + style="font-size:12;" + id="g386"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect387" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect388" /> + </g> + <g + transform="matrix(0.297394,0,0,0.572692,101.502,21.6359)" + style="font-size:12;" + id="g364"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect365" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect366" /> + </g> + <text + x="202.746506" + y="102.992203" + transform="scale(0.73778,0.73778)" + style="font-size:14;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text367"> + <tspan + x="202.746948" + y="102.992249" + id="tspan423"> +Persistent</tspan> + <tspan + x="202.746948" + y="116.992355" + id="tspan425"> +Objects</tspan> + </text> + <text + x="174.458496" + y="180.080795" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text389"> + <tspan + x="174.458618" + y="180.080338" + id="tspan392"> +Session</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,188.675,8.98517)" + style="font-size:12;" + id="g394"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect395" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect396" /> + </g> + <text + x="260.413269" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text397"> + <tspan + x="260.412964" + y="179.154343" + id="tspan400"> +JDBC</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,229.156,8.98517)" + style="font-size:12;" + id="g405"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect406" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect407" /> + </g> + <text + x="320.606903" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text408"> + <tspan + x="320.606964" + y="179.154343" + id="tspan417"> +JNDI</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,269.281,8.98517)" + style="font-size:12;" + id="g411"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect412" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect413" /> + </g> + <text + x="377.096313" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text414"> + <tspan + x="377.096008" + y="179.154999" + id="tspan145"> +JTA</tspan> + </text> +</svg> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.png =================================================================== (Binary files differ) Property changes on: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.svg =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.svg (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/images/overview.svg 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,250 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="248.031" + height="248.031" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,-3.02123)" + style="font-size:12;" + id="g158"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="17.3527" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="15.3883" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + </g> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,3.04452)" + style="font-size:12;" + id="g161"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,8.0993)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <g + transform="matrix(0.771934,0,0,0.543505,2.59104,21.1103)" + style="font-size:12;" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="105.392174" + y="56.568123" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="105.392273" + y="56.568146" + id="tspan186"> +Application</tspan> + </text> + <text + x="81.820183" + y="103.149330" + transform="scale(0.771934,0.771934)" + style="font-size:20;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="81.820213" + y="103.149727" + id="tspan206"> +Persistent Objects</tspan> + </text> + <text + x="111.548180" + y="278.927887" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="111.547874" + y="278.927551" + id="tspan200"> +Database</tspan> + </text> + <text + x="94.436180" + y="153.805740" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="94.436180" + y="153.805740" + id="tspan221"> +HIBERNATE</tspan> + </text> + <g + transform="matrix(0.771934,0,0,0.771934,2.59083,1.02261)" + style="font-size:12;" + id="g254"> + <g + transform="translate(4.58374,2.61928)" + id="g176"> + <g + transform="matrix(0.571429,0,0,0.67347,-10.6174,117.093)" + id="g170"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect171" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect172" /> + </g> + <g + transform="matrix(0.571429,0,0,0.67347,138.682,117.093)" + id="g173"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect174" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect175" /> + </g> + </g> + <text + x="47.259438" + y="182.367538" + style="font-weight:bold;stroke-width:1pt;font-family:Courier;" + id="text191"> + <tspan + x="47.259399" + y="182.367996" + id="tspan212"> +hibernate.</tspan> + <tspan + x="47.259399" + y="194.367996" + id="tspan214"> +properties</tspan> + </text> + <text + x="198.523010" + y="188.260941" + style="font-weight:normal;stroke-width:1pt;font-family:helvetica;" + id="text194"> + <tspan + id="tspan195"> +XML Mapping</tspan> + </text> + </g> +</svg> Added: core/branches/gradle2/hibernate-release/src/main/docbook/en-US/legal_notice.xml =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/en-US/legal_notice.xml (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/en-US/legal_notice.xml 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program 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 distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + +]> +<legalnotice id="Legal_Notice"> + <title>Legal Notice</title> + <para> + <address> + <street>1801 Varsity Drive</street> + <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> + <phone>Phone: +1 919 754 3700</phone> + <phone>Phone: 888 733 4281</phone> + <fax>Fax: +1 919 754 3701</fax> + <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> + </address> + </para> + <para> + Copyright <trademark class="copyright"/> 2007 by Red Hat, Inc. This copyrighted material is made available to + anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the + GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published + by the Free Software Foundation. + </para> + <para> + Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> + <para> + The GPG fingerprint of the security(a)redhat.com key is: + </para> + <para> + CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E + </para> +</legalnotice> Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Book_Info.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Book_Info.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Book_Info.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,28 @@ +# +# AUTHOR <EMAIL@ADDRESS>, YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: 0\n" +"POT-Creation-Date: 2010-03-12T00:03:45\n" +"PO-Revision-Date: 2010-02-04T04:51:21\n" +"Last-Translator: Automatically generated\n" +"Language-Team: None\n" +"MIME-Version: 1.0\n" +"Content-Type: application/x-publican; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#, no-c-format +msgid "HIBERNATE - Relational Persistence for Idiomatic Java" +msgstr "" + +#. Tag: subtitle +#, no-c-format +msgid "Hibernate Reference Documentation" +msgstr "" + +#. Tag: releaseinfo +#, no-c-format +msgid "&version;" +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,23 @@ +#, fuzzy +msgid "" +msgstr "" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-04T04:51:21\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Content-Type: text/plain; charset=UTF-8\n" + +#~ msgid "HIBERNATE - Relational Persistence for Idiomatic Java" +#~ msgstr "HIBERNATE - Persistance relationnelle en Java standard" + +#~ msgid "Hibernate Reference Documentation" +#~ msgstr "Documentation de référence d'Hibernate" + +#~ msgid "&copyrightHolder;" +#~ msgstr "&copyrightHolder;" + +#~ msgid "ROLES_OF_TRANSLATORS" +#~ msgstr "<!--TRANS:ROLES_OF_TRANSLATORS-->" + +#~ msgid "CREDIT_FOR_TRANSLATORS" +#~ msgstr "<!--TRANS:CREDIT_FOR_TRANSLATORS-->" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Hibernate_Reference.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Hibernate_Reference.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/Hibernate_Reference.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,30 @@ +# SOME DESCRIPTIVE TITLE. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:14\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <kde-i18n-doc(a)kde.org&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: application/x-xml2pot; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#, no-c-format +msgid "HIBERNATE - Relational Persistence for Idiomatic Java" +msgstr "" + +#. Tag: subtitle +#, no-c-format +msgid "Hibernate Reference Documentation" +msgstr "" + +#. Tag: releaseinfo +#, no-c-format +msgid "&versionNumber;" +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/author_group.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/author_group.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/author_group.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,149 @@ +# Language fr-FR translations for PACKAGE package. +# Automatically generated, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-04T04:51:21\n" +"PO-Revision-Date: 2009-07-14 19:55+0000\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: firstname +#, no-c-format +msgid "Gavin" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Christian" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Max" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Emmanuel" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Steve" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "James" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Cheyenne" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Vincent" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Sebastien" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Michael" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Baptiste" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Anthony" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Alvaro" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Anderson" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Daniel Vieira" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Francisco" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Gamarra" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Luiz Carlos" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Marcel" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Paulo" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Pablo L." +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Renato" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Rogério" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Wanderson" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Cao" +msgstr "" + +#. Tag: orgname +#, no-c-format +msgid "RedSaga" +msgstr "" + +#. Tag: contrib +#, no-c-format +msgid "Translation Lead" +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/architecture.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/architecture.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/architecture.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,623 @@ +# translation of architecture.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: architecture\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-03-12T00:03:45\n" +"PO-Revision-Date: 2010-01-04 16:40+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Architecture" +msgstr "Architecture" + +#. Tag: title +#, no-c-format +msgid "Overview" +msgstr "Généralités" + +#. Tag: para +#, no-c-format +msgid "" +"The diagram below provides a high-level view of the Hibernate architecture:" +msgstr "" +"Le diagramme ci-dessus procure une vue - (très) haut niveau - de " +"l'architecture Hibernate :" + +#. Tag: para +#, no-c-format +msgid "" +"We do not have the scope in this document to provide a more detailed view of " +"all the runtime architectures available; Hibernate is flexible and supports " +"several different approaches. We will, however, show the two extremes: " +"\"minimal\" architecture and \"comprehensive\" architecture." +msgstr "" +"Nous aimerions décrire une vue plus détaillée de l'architecture. Hibernate " +"est flexible et prend en charge différentes approches. Nous allons en " +"montrer les deux extrêmes : l'architecture \"légère\" et l'architecture " +"\"complète\"." + +#. Tag: para +#, no-c-format +msgid "" +"This next diagram illustrates how Hibernate utilizes database and " +"configuration data to provide persistence services, and persistent objects, " +"to the application." +msgstr "" +"Ce diagramme montre Hibernate utilisant la base de données et des données de " +"configuration pour fournir un service de persistance, et des objets " +"persistants, à l'application." + +#. Tag: para +#, no-c-format +msgid "" +"The \"minimal\" architecture has the application provide its own JDBC " +"connections and manage its own transactions. This approach uses a minimal " +"subset of Hibernate's APIs:" +msgstr "" +"L'architecture \"légère\" permet à l'application de fournir ses propres " +"connexions JDBC et de gérer ses propres transactions. Cette approche utilise " +"un sous-ensemble minimum des API Hibernate :" + +#. Tag: para +#, no-c-format +msgid "" +"The \"comprehensive\" architecture abstracts the application away from the " +"underlying JDBC/JTA APIs and allows Hibernate to manage the details." +msgstr "" +"L'architecture \"complète\" abstrait l'application des API JDBC/JTA sous-" +"jacentes et permet à Hibernate de s'occuper des détails." + +#. Tag: para +#, no-c-format +msgid "Here are some definitions of the objects depicted in the diagrams:" +msgstr "Voici quelques définitions des objets dans les diagrammes :" + +#. Tag: term +#, no-c-format +msgid "SessionFactory (<literal>org.hibernate.SessionFactory</literal>)" +msgstr "SessionFactory (<literal>org.hibernate.SessionFactory</literal>)" + +#. Tag: para +#, no-c-format +msgid "" +"A threadsafe, immutable cache of compiled mappings for a single database. A " +"factory for <literal>Session</literal> and a client of " +"<literal>ConnectionProvider</literal>, <literal>SessionFactory</literal> can " +"hold an optional (second-level) cache of data that is reusable between " +"transactions at a process, or cluster, level." +msgstr "" +"Un cache threadsafe (immuable) de mappages compilés pour une base de " +"données. En tant que fabrique de <literal>Session</literal> et que client du " +"<literal>ConnectionProvider</literal>, <literal>SessionFactory</literal>peut " +"contenir un cache optionnel de données (de second niveau), réutilisable " +"entre les différentes transactions, que cela soit au sein du même processus " +"ou au niveau d'un cluster." + +#. Tag: term +#, no-c-format +msgid "Session (<literal>org.hibernate.Session</literal>)" +msgstr "Session (<literal>org.hibernate.Session</literal>)" + +#. Tag: para +#, no-c-format +msgid "" +"A single-threaded, short-lived object representing a conversation between " +"the application and the persistent store. It wraps a JDBC connection and is " +"a factory for <literal>Transaction</literal>. <literal>Session</literal> " +"holds a mandatory first-level cache of persistent objects that are used when " +"navigating the object graph or looking up objects by identifier." +msgstr "" +"Un objet mono-threadé, à durée de vie courte, qui représente une " +"conversation entre l'application et l'entrepôt de persistance. Encapsule une " +"connexion JDBC. Fabrique des objets <literal>Transaction</literal>. La " +"<literal>Session</literal> contient un cache (de premier niveau) des objets " +"persistants, qui sont utilisés lors de la navigation dans le graphe d'objets " +"ou lors de la récupération d'objets par leur identifiant." + +#. Tag: term +#, no-c-format +msgid "Persistent objects and collections" +msgstr "Objets et collections persistants" + +#. Tag: para +#, no-c-format +msgid "" +"Short-lived, single threaded objects containing persistent state and " +"business function. These can be ordinary JavaBeans/POJOs. They are " +"associated with exactly one <literal>Session</literal>. Once the " +"<literal>Session</literal> is closed, they will be detached and free to use " +"in any application layer (for example, directly as data transfer objects to " +"and from presentation)." +msgstr "" +"Objets mono-threadés à vie courte, contenant état persistant et fonction " +"commerciale. Ceux-ci sont en général des objets ordinaires de type JavaBean " +"(ou POJO); la seule particularité est qu'ils sont associés avec une (et une " +"seule) <literal>Session</literal>. Dès que la <literal>Session</literal> est " +"fermée, ils sont détachés et libres d'être utilisés par n'importe quelle " +"couche de l'application (par ex. de et vers la présentation)." + +#. Tag: term +#, no-c-format +msgid "Transient and detached objects and collections" +msgstr "Objets et collections éphémères (transient) et détachés" + +#. Tag: para +#, no-c-format +msgid "" +"Instances of persistent classes that are not currently associated with a " +"<literal>Session</literal>. They may have been instantiated by the " +"application and not yet persisted, or they may have been instantiated by a " +"closed <literal>Session</literal>." +msgstr "" +"Instances de classes persistantes qui ne sont actuellement pas associées à " +"une <literal>Session</literal>. Elles ont pu être instanciées par " +"l'application et ne pas avoir (encore) été persistées, ou elle ont pu être " +"instanciées par une <literal>Session</literal> fermée." + +#. Tag: term +#, no-c-format +msgid "Transaction (<literal>org.hibernate.Transaction</literal>)" +msgstr "Transaction (<literal>org.hibernate.Transaction</literal>)" + +#. Tag: para +#, no-c-format +msgid "" +"(Optional) A single-threaded, short-lived object used by the application to " +"specify atomic units of work. It abstracts the application from the " +"underlying JDBC, JTA or CORBA transaction. A <literal>Session</literal> " +"might span several <literal>Transaction</literal>s in some cases. However, " +"transaction demarcation, either using the underlying API or " +"<literal>Transaction</literal>, is never optional." +msgstr "" +"(Optionnel) Un objet mono-threadé à vie courte utilisé par l'application " +"pour définir une unité de travail atomique. Abstrait l'application des " +"transactions sous-jacentes, qu'elles soient JDBC, JTA ou CORBA. Une " +"<literal>Session</literal> peut fournir plusieurs <literal>Transaction</" +"literal>s dans certains cas. Toutefois, la délimitation des transactions, " +"via l'API d'Hibernate ou par la <literal>Transaction</literal> sous-jacente, " +"n'est jamais optionnelle. " + +#. Tag: term +#, no-c-format +msgid "" +"ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</" +"literal>)" +msgstr "" +"ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</" +"literal>)" + +#. Tag: para +#, no-c-format +msgid "" +"(Optional) A factory for, and pool of, JDBC connections. It abstracts the " +"application from underlying <literal>Datasource</literal> or " +"<literal>DriverManager</literal>. It is not exposed to application, but it " +"can be extended and/or implemented by the developer." +msgstr "" +"(Optionnel) Une fabrique de (pool de) connexions JDBC. Abstrait " +"l'application de la <literal>Datasource</literal> ou du " +"<literal>DriverManager</literal> sous-jacent. Non exposé à l'application, " +"mais peut être étendu/implémenté par le développeur. " + +#. Tag: term +#, no-c-format +msgid "" +"TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)" +msgstr "" +"TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)" + +#. Tag: para +#, no-c-format +msgid "" +"(Optional) A factory for <literal>Transaction</literal> instances. It is not " +"exposed to the application, but it can be extended and/or implemented by the " +"developer." +msgstr "" +"(Optionnel) Une fabrique d'instances de <literal>Transaction</literal>. Non " +"exposée à l'application, mais peut être étendue/implémentée par le " +"développeur. " + +#. Tag: term +#, fuzzy, no-c-format +msgid "<emphasis>Extension Interfaces</emphasis>" +msgstr "<emphasis>Interfaces d'extension</emphasis> " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate offers a range of optional extension interfaces you can implement " +"to customize the behavior of your persistence layer. See the API " +"documentation for details." +msgstr "" +"Hibernate fournit de nombreuses interfaces d'extensions optionnelles que " +"vous pouvez implémenter pour personnaliser le comportement de votre couche " +"de persistance. Reportez vous à la documentation de l'API pour plus de " +"détails. " + +#. Tag: para +#, no-c-format +msgid "" +"Given a \"minimal\" architecture, the application bypasses the " +"<literal>Transaction</literal>/<literal>TransactionFactory</literal> and/or " +"<literal>ConnectionProvider</literal> APIs to communicate with JTA or JDBC " +"directly." +msgstr "" +"Dans une architecture légère, l'application n'aura pas à utiliser les API " +"<literal>Transaction</literal>/<literal>TransactionFactory</literal> et/ou " +"n'utilisera pas les API <literal>ConnectionProvider</literal> pour utiliser " +"directement JTA ou JDBC. " + +#. Tag: title +#, no-c-format +msgid "Instance states" +msgstr "Etats des instances" + +#. Tag: para +#, no-c-format +msgid "" +"An instance of a persistent class can be in one of three different states. " +"These states are defined in relation to a <emphasis>persistence context</" +"emphasis>. The Hibernate <literal>Session</literal> object is the " +"persistence context. The three different states are as follows:" +msgstr "" +"Une instance d'une classe persistante peut être dans l'un des trois états " +"suivants, définis par rapport à un <emphasis>contexte de persistance</" +"emphasis>. L'objet <literal>Session</literal> Hibernate correspond à ce " +"contexte de persistance. Les trois états distincts sont:" + +#. Tag: term +#, no-c-format +msgid "transient" +msgstr "éphémère (transient)" + +#. Tag: para +#, no-c-format +msgid "" +"The instance is not associated with any persistence context. It has no " +"persistent identity or primary key value." +msgstr "" +"L'instance n'est pas et n'a jamais été associée à un contexte de " +"persistance. Elle ne possède pas d'identité persistante (valeur de clé " +"primaire)." + +#. Tag: term +#, no-c-format +msgid "persistent" +msgstr "persistant" + +#. Tag: para +#, no-c-format +msgid "" +"The instance is currently associated with a persistence context. It has a " +"persistent identity (primary key value) and can have a corresponding row in " +"the database. For a particular persistence context, Hibernate " +"<emphasis>guarantees</emphasis> that persistent identity is equivalent to " +"Java identity in relation to the in-memory location of the object." +msgstr "" +"L'instance est associée à un contexte de persistance. Elle possède une " +"identité persistante (valeur de clé primaire) et, peut-être un " +"enregistrement correspondant dans la base de données. Pour un contexte de " +"persistance particulier, Hibernate <emphasis>garantit</emphasis> que " +"l'identité persistante soit équivalente à l'identité Java (emplacement " +"mémoire de l'objet). " + +#. Tag: term +#, no-c-format +msgid "detached" +msgstr "détaché" + +#. Tag: para +#, no-c-format +msgid "" +"The instance was once associated with a persistence context, but that " +"context was closed, or the instance was serialized to another process. It " +"has a persistent identity and can have a corresponding row in the database. " +"For detached instances, Hibernate does not guarantee the relationship " +"between persistent identity and Java identity." +msgstr "" +"L'instance a été associée au contexte de persistance mais ce contexte a été " +"fermé, ou l'instance a été sérialisée vers un autre processus. Elle possède " +"une identité persistante et peut-être un enregistrement correspondant dans " +"la base de données. Pour des instances détachées, Hibernate ne donne aucune " +"garantie sur la relation entre l'identité persistante et l'identité Java. " + +#. Tag: title +#, no-c-format +msgid "JMX Integration" +msgstr "Intégration JMX" + +#. Tag: para +#, no-c-format +msgid "" +"JMX is the J2EE standard for the management of Java components. Hibernate " +"can be managed via a JMX standard service. AN MBean implementation is " +"provided in the distribution: <literal>org.hibernate.jmx.HibernateService</" +"literal>." +msgstr "" +"JMX est le standard J2EE de gestion des composants Java. Hibernate peut être " +"géré via un service JMX standard. Nous fournissons une implémentation d'un " +"MBean dans la distribution : <literal>org.hibernate.jmx.HibernateService</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"For an example of how to deploy Hibernate as a JMX service on the JBoss " +"Application Server, please see the JBoss User Guide. JBoss AS also provides " +"these benefits if you deploy using JMX:" +msgstr "" +"Pour un exemple sur la manière de déployer Hibernate en tant que service JMX " +"dans le serveur d'application JBoss Application Server, référez vous au " +"guide de l'utilisateur JBoss (JBoss User Guide). Si vous déployez Hibernate " +"via JMX sur JBoss AS, vous aurez également les avantages suivants : " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Session Management</emphasis>: the Hibernate <literal>Session</" +"literal>'s life cycle can be automatically bound to the scope of a JTA " +"transaction. This means that you no longer have to manually open and close " +"the <literal>Session</literal>; this becomes the job of a JBoss EJB " +"interceptor. You also do not have to worry about transaction demarcation in " +"your code (if you would like to write a portable persistence layer use the " +"optional Hibernate <literal>Transaction</literal> API for this). You call " +"the <literal>HibernateContext</literal> to access a <literal>Session</" +"literal>." +msgstr "" +"<emphasis>Gestion de la session</emphasis> : le cycle de vie de la " +"<literal>Session</literal> Hibernate peut être automatiquement liée à la " +"portée d'une transaction JTA. Cela signifie que vous n'avez plus besoin " +"d'ouvrir et de fermer la <literal>Session</literal> manuellement, cela " +"devient le travail de l'intercepteur EJB de JBoss. Vous n'avez pas non plus " +"à vous occuper des démarcations des transactions dans votre code (sauf si " +"vous voulez écrire une couche de persistance qui soit portable, dans ce cas " +"vous pouvez utiliser l'API optionnelle <literal>Transaction</literal> de " +"Hibernate). Vous appelez le <literal>HibernateContext</literal> pour accéder " +"à la <literal>Session</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>HAR deployment</emphasis>: the Hibernate JMX service is deployed " +"using a JBoss service deployment descriptor in an EAR and/or SAR file, as it " +"supports all the usual configuration options of a Hibernate " +"<literal>SessionFactory</literal>. However, you still need to name all your " +"mapping files in the deployment descriptor. If you use the optional HAR " +"deployment, JBoss will automatically detect all mapping files in your HAR " +"file." +msgstr "" +"<emphasis>Déploiement HAR :</emphasis>: habituellement vous déployez le " +"service JMX Hibernate en utilisant le descripteur de déploiement de JBoss " +"dans un fichier EAR et/ou un SAR, car il supporte toutes les options de " +"configuration usuelles d'une <literal>SessionFactory</literal> Hibernate. " +"Cependant, vous devez toujours nommer tous vos fichiers de mappage dans le " +"descripteur de déploiement. Si vous décidez d'utiliser le déploiement " +"optionnel sous forme de HAR, JBoss détectera automatiquement tous vos " +"fichiers de mapping dans votre fichier HAR." + +#. Tag: para +#, no-c-format +msgid "" +"Consult the JBoss AS user guide for more information about these options." +msgstr "" +"Consultez le guide d'utilisation de JBoss AS pour plus d'informations sur " +"ces options." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Another feature available as a JMX service is runtime Hibernate statistics. " +"See <xref linkend=\"configuration-optional-statistics\" /> for more " +"information." +msgstr "" +"Les statistiques Hibernate (runtime) représentent une autre fonctionnalité " +"qui est disponible en tant que service JMX. Voyez pour cela les <xref " +"linkend=\"configuration-optional-statistics\" />." + +#. Tag: title +#, no-c-format +msgid "JCA Support" +msgstr "Support JCA" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate can also be configured as a JCA connector. Please see the website " +"for more information. Please note, however, that at this stage Hibernate JCA " +"support is under development." +msgstr "" +"Hibernate peut aussi être configuré en tant que connecteur JCA. Référez-vous " +"au site web pour de plus amples détails. Il est important de noter que le " +"support JCA de Hibernate est encore considéré comme expérimental. " + +#. Tag: title +#, no-c-format +msgid "Contextual sessions" +msgstr "Sessions contextuelles " + +#. Tag: para +#, no-c-format +msgid "" +"Most applications using Hibernate need some form of \"contextual\" session, " +"where a given session is in effect throughout the scope of a given context. " +"However, across applications the definition of what constitutes a context is " +"typically different; different contexts define different scopes to the " +"notion of current. Applications using Hibernate prior to version 3.0 tended " +"to utilize either home-grown <literal>ThreadLocal</literal>-based contextual " +"sessions, helper classes such as <literal>HibernateUtil</literal>, or " +"utilized third-party frameworks, such as Spring or Pico, which provided " +"proxy/interception-based contextual sessions." +msgstr "" +"Certaines applications utilisant Hibernate ont besoin d'une sorte de session " +"\"contextuelle\", où une session donnée est en effet liée à la portée d'un " +"contexte particulier. Cependant, les applications ne définissent pas toutes " +"la notion de contexte de la même manière, et différents contextes " +"définissent différentes portées à la notion de \"courant\". Les applications " +"qui utilisaient Hibernate, versions précédentes à la 3.0, avaient tendance à " +"employer un principe maison de sessions contextuelles basées sur le " +"<literal>ThreadLocal</literal>, ainsi que sur des classes utilitaires comme " +"<literal>HibernateUtil</literal>, ou utilisaient des framework tiers (comme " +"Spring ou Pico) qui fournissaient des sessions contextuelles basées sur " +"l'utilisation de proxy/interception. " + +#. Tag: para +#, no-c-format +msgid "" +"Starting with version 3.0.1, Hibernate added the <literal>SessionFactory." +"getCurrentSession()</literal> method. Initially, this assumed usage of " +"<literal>JTA</literal> transactions, where the <literal>JTA</literal> " +"transaction defined both the scope and context of a current session. Given " +"the maturity of the numerous stand-alone <literal>JTA TransactionManager</" +"literal> implementations, most, if not all, applications should be using " +"<literal>JTA</literal> transaction management, whether or not they are " +"deployed into a <literal>J2EE</literal> container. Based on that, the " +"<literal>JTA</literal>-based contextual sessions are all you need to use." +msgstr "" +"A partir de la version 3.0.1, Hibernate a ajouté la méthode " +"<literal>SessionFactory.getCurrentSession()</literal>. Initialement, cela " +"demandait l'usage de transactions <literal>JTA</literal>, où la transaction " +"<literal>JTA</literal> définissait la portée et le contexte de la session " +"courante. L'équipe Hibernate pense que, étant donnée la maturité des " +"nombreuses implémentations autonomes du <literal>JTA TransactionManager</" +"literal>, la plupart (sinon toutes) des applications devraient utiliser la " +"gestion des transactions par <literal>JTA</literal> qu'elles soient ou non " +"déployées dans un conteneur <literal>J2EE</literal>. Par conséquent, il vous " +"suffira de contextualiser vos sessions via la méthode basée sur " +"<literal>JTA</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"However, as of version 3.1, the processing behind <literal>SessionFactory." +"getCurrentSession()</literal> is now pluggable. To that end, a new extension " +"interface, <literal>org.hibernate.context.CurrentSessionContext</literal>, " +"and a new configuration parameter, <literal>hibernate." +"current_session_context_class</literal>, have been added to allow " +"pluggability of the scope and context of defining current sessions." +msgstr "" +"Cependant, depuis la version 3.1, la logique derrière " +"<literal>SessionFactory.getCurrentSession()</literal> est désormais " +"enfichable. A cette fin, une nouvelle interface d'extension(<literal>org." +"hibernate.context.CurrentSessionContext</literal> et un nouveau paramètre de " +"configuration <literal>hibernate.current_session_context_class</literal> ont " +"été ajoutés pour enficher la portée et le contexte de sessions courantes " +"caractéristiques." + +#. Tag: para +#, no-c-format +msgid "" +"See the Javadocs for the <literal>org.hibernate.context." +"CurrentSessionContext</literal> interface for a detailed discussion of its " +"contract. It defines a single method, <literal>currentSession()</literal>, " +"by which the implementation is responsible for tracking the current " +"contextual session. Out-of-the-box, Hibernate comes with three " +"implementations of this interface:" +msgstr "" +"Pour une description détaillée de son contrat, consultez les Javadocs de " +"l'interface <literal>org.hibernate.context.CurrentSessionContext</literal>. " +"Elle définit une seule méthode, <literal>currentSession()</literal>, par " +"laquelle l'implémentation est responsable de traquer la session contextuelle " +"courante. Hibernate fournit trois implémentations de cette interface :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>org.hibernate.context.JTASessionContext</literal>: current sessions " +"are tracked and scoped by a <literal>JTA</literal> transaction. The " +"processing here is exactly the same as in the older JTA-only approach. See " +"the Javadocs for details." +msgstr "" +"<literal>org.hibernate.context.JTASessionContext</literal> - les sessions " +"courantes sont associées à une transaction <literal>JTA</literal>. La " +"logique est la même que l'ancienne approche basée sur JTA. Consultez les " +"javadocs pour pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>org.hibernate.context.ThreadLocalSessionContext</literal>:current " +"sessions are tracked by thread of execution. See the Javadocs for details." +msgstr "" +"<literal>org.hibernate.context.ThreadLocalSessionContext</literal> - les " +"sessions courantes sont traquées par l'exécution du thread. Consultez les " +"javadocs pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>org.hibernate.context.ManagedSessionContext</literal>: current " +"sessions are tracked by thread of execution. However, you are responsible to " +"bind and unbind a <literal>Session</literal> instance with static methods on " +"this class: it does not open, flush, or close a <literal>Session</literal>." +msgstr "" +"<literal>org.hibernate.context.ManagedSessionContext</literal> - les " +"sessions courantes sont traquées par l'exécution du thread. Toutefois, vous " +"êtes responsable de lier et de délier une instance de <literal>Session</" +"literal> avec des méthodes statiques de cette classe. Elle n'ouvre jamais, " +"ni ne nettoie ou ne ferme une <literal>Session</literal>." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The first two implementations provide a \"one session - one database " +"transaction\" programming model. This is also known and used as " +"<emphasis>session-per-request</emphasis>. The beginning and end of a " +"Hibernate session is defined by the duration of a database transaction. If " +"you use programmatic transaction demarcation in plain JSE without JTA, you " +"are advised to use the Hibernate <literal>Transaction</literal> API to hide " +"the underlying transaction system from your code. If you use JTA, you can " +"utilize the JTA interfaces to demarcate transactions. If you execute in an " +"EJB container that supports CMT, transaction boundaries are defined " +"declaratively and you do not need any transaction or session demarcation " +"operations in your code. Refer to <xref linkend=\"transactions\" /> for more " +"information and code examples." +msgstr "" +"Les deux premières implémentations fournissent un modèle de programmation de " +"type \"une session - une transaction de base de données\", aussi connu sous " +"le nom de <emphasis>session-per-request</emphasis>. Le début et la fin d'une " +"session Hibernate sont définis par la durée d'une transaction de base de " +"données. Si vous utilisez une démarcation programmatique de la transaction " +"avec JSE sans JTA, nous vous conseillons d'utiliser l'API Hibernate " +"<literal>Transaction</literal> pour masquer le système de transaction sous-" +"jacent à votre code. Si vous exécutez sous un conteneur EJB qui prend en " +"charge CMT, vous n'avez besoin d'aucune opération de démarcation de session " +"ou transaction dans votre code puisque tout est géré de manière déclarative. " +"Référez vous au <xref linkend=\"transactions\" /> pour plus d'informations " +"et des exemples de code." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>hibernate.current_session_context_class</literal> configuration " +"parameter defines which <literal>org.hibernate.context." +"CurrentSessionContext</literal> implementation should be used. For backwards " +"compatibility, if this configuration parameter is not set but a <literal>org." +"hibernate.transaction.TransactionManagerLookup</literal> is configured, " +"Hibernate will use the <literal>org.hibernate.context.JTASessionContext</" +"literal>. Typically, the value of this parameter would just name the " +"implementation class to use. For the three out-of-the-box implementations, " +"however, there are three corresponding short names: \"jta\", \"thread\", and " +"\"managed\"." +msgstr "" +"Le paramètre de configuration <literal>hibernate." +"current_session_context_class</literal> définit quelle implémentation de " +"<literal>org.hibernate.context.CurrentSessionContext</literal> doit être " +"utilisée. Notez que pour assurer la compatibilité avec les versions " +"précédentes, si ce paramètre n'est pas défini mais qu'un <literal>org." +"hibernate.transaction.TransactionManagerLookup</literal> est configuré, " +"Hibernate utilisera le <literal>org.hibernate.context.JTASessionContext</" +"literal>. La valeur de ce paramètre devrait juste nommer la classe " +"d'implémentation à utiliser. Pour les trois implémentations prêtes à " +"utiliser, toutefois, il y a trois noms brefs correspondants : \"jta\", " +"\"thread\" et \"managed\"." Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/association_mapping.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/association_mapping.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/association_mapping.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1147 @@ +# translation of association_mapping.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: association_mapping\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:34\n" +"PO-Revision-Date: 2009-11-10 14:49+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Association Mappings" +msgstr "Mapper les associations" + +#. Tag: title +#, no-c-format +msgid "Introduction" +msgstr "Introduction" + +#. Tag: para +#, no-c-format +msgid "" +"Association mappings are often the most difficult thing to implement " +"correctly. In this section we examine some canonical cases one by one, " +"starting with unidirectional mappings and then bidirectional cases. We will " +"use <literal>Person</literal> and <literal>Address</literal> in all the " +"examples." +msgstr "" +"Mapper les associations correctement, est souvent la tâche la plus " +"difficile. Dans cette section, nous traiterons les cas classiques, un par " +"un, en commençant par les mappages unidirectionnels, puis nous aborderons la " +"question des mappages bidirectionnels. Nous illustrons tous nos exemples " +"avec les classes <literal>Person</literal> et <literal>Address</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Associations will be classified by multiplicity and whether or not they map " +"to an intervening join table." +msgstr "" +"Nous classifions les associations selon qu'elles sont ou non bâties sur une " +"table de jointure supplémentaire et sur la multiplicité. " + +#. Tag: para +#, no-c-format +msgid "" +"Nullable foreign keys are not considered to be good practice in traditional " +"data modelling, so our examples do not use nullable foreign keys. This is " +"not a requirement of Hibernate, and the mappings will work if you drop the " +"nullability constraints." +msgstr "" +"Autoriser une clé étrangère nulle est considéré comme un mauvais choix dans " +"la construction d'un modèle de données. Nous supposerons donc que dans tous " +"les exemples qui vont suivre on aura interdit la valeur nulle pour les clés " +"étrangères. Attention, ceci ne veut pas dire que Hibernate ne supporte pas " +"les clés étrangères pouvant prendre des valeurs nulles, et les exemples qui " +"suivent continueront de fonctionner si vous décidiez ne plus imposer la " +"contrainte de non-nullité sur les clés étrangères." + +#. Tag: title +#, no-c-format +msgid "Unidirectional associations" +msgstr "Associations unidirectionnelles" + +#. Tag: title +#, no-c-format +msgid "Many-to-one" +msgstr "plusieurs-à-un " + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional many-to-one association</emphasis> is the most " +"common kind of unidirectional association." +msgstr "" +"Une <emphasis>association plusieurs-à-un unidirectionnelle </emphasis> est " +"le type que l'on rencontre le plus souvent dans les associations " +"unidirectionnelles." + +#. Tag: title +#, no-c-format +msgid "One-to-one" +msgstr "Un-à-un" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional one-to-one association on a foreign key</" +"emphasis> is almost identical. The only difference is the column unique " +"constraint." +msgstr "" +"Une <emphasis>association un-à-un sur une clé étrangère</emphasis> est " +"presque identique. La seule différence est sur la contrainte d'unicité que " +"l'on impose à cette colonne." + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional one-to-one association on a primary key</" +"emphasis> usually uses a special id generator In this example, however, we " +"have reversed the direction of the association:" +msgstr "" +"Une <emphasis>association un-à-un unidirectionnelle sur une clé primaire</" +"emphasis> utilise un générateur d'identifiant particulier. Remarquez que " +"nous avons inversé le sens de cette association dans cet exemple :" + +#. Tag: title +#, no-c-format +msgid "One-to-many" +msgstr "un-à-plusieurs" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional one-to-many association on a foreign key</" +"emphasis> is an unusual case, and is not recommended." +msgstr "" +"Une <emphasis>association un-à-plusieurs unidirectionnelle sur une clé " +"étrangère</emphasis> est un cas inhabituel, et n'est pas vraiment " +"recommandée." + +#. Tag: para +#, no-c-format +msgid "You should instead use a join table for this kind of association." +msgstr "" +"Nous pensons qu'il est préférable d'utiliser une table de jointure pour ce " +"type d'association. " + +#. Tag: title +#, no-c-format +msgid "Unidirectional associations with join tables" +msgstr "Associations unidirectionnelles avec tables de jointure" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional one-to-many association on a join table</" +"emphasis> is the preferred option. Specifying <literal>unique=\"true\"</" +"literal>, changes the multiplicity from many-to-many to one-to-many." +msgstr "" +"Une <emphasis>association unidirectionnelle un-à-plusieurs avec une table de " +"jointure</emphasis> est un bien meilleur choix. Remarquez qu'en spécifiant " +"<literal>unique=\"true\"</literal>, on a changé la multiplicité plusieurs-à-" +"plusieurs pour un-à-plusieurs. " + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional many-to-one association on a join table</" +"emphasis> is common when the association is optional. For example:" +msgstr "" +"Une <emphasis>assiociation plusieurs-à-un unidirectionnelle sur une table de " +"jointure</emphasis> est assez fréquente quand l'association est optionnelle. " +"Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>unidirectional one-to-one association on a join table</emphasis> " +"is possible, but extremely unusual." +msgstr "" +"Une <emphasis>association unidirectionnelle un-à-un sur une table de " +"jointure</emphasis> est extrêmement rare mais envisageable. " + +#. Tag: title +#, no-c-format +msgid "Many-to-many" +msgstr "Plusieurs-à-plusieurs " + +#. Tag: para +#, no-c-format +msgid "" +"Finally, here is an example of a <emphasis>unidirectional many-to-many " +"association</emphasis>." +msgstr "" +"Finalement, nous avons un exemple d' <emphasis>association unidirectionnelle " +"plusieurs-à-plusieurs</emphasis>." + +#. Tag: title +#, no-c-format +msgid "Bidirectional associations" +msgstr "Associations bidirectionnelles " + +#. Tag: title +#, no-c-format +msgid "one-to-many / many-to-one" +msgstr "un-à-plusieurs / plusieurs-à-un " + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>bidirectional many-to-one association</emphasis> is the most " +"common kind of association. The following example illustrates the standard " +"parent/child relationship." +msgstr "" +"Une <emphasis>association bidirectionnelle plusieurs-à-un</emphasis> est le " +"type d'association que l'on rencontre le plus fréquemment. L'exemple suivant " +"illustre la façon standard de créer des relations parents/enfants." + +#. Tag: para +#, no-c-format +msgid "" +"If you use a <literal>List</literal>, or other indexed collection, set the " +"<literal>key</literal> column of the foreign key to <literal>not null</" +"literal>. Hibernate will manage the association from the collections side to " +"maintain the index of each element, making the other side virtually inverse " +"by setting <literal>update=\"false\"</literal> and <literal>insert=\"false" +"\"</literal>:" +msgstr "" +"Si vous utilisez une <literal>List</literal>, ou toute autre collection " +"indexée, vous devez paramétrer la colonne <literal>key</literal> de la clé " +"étrangère à <literal>not null</literal>, et laisser Hibernate gérer " +"l'association depuis l'extrémité collection pour maintenir l'index de chaque " +"élément (rendant l'autre extrémité virtuellement inverse en paramétrant " +"<literal>update=\"false\"</literal> et <literal>insert=\"false\"</literal>) :" + +#. Tag: para +#, no-c-format +msgid "" +"If the underlying foreign key column is <literal>NOT NULL</literal>, it is " +"important that you define <literal>not-null=\"true\"</literal> on the " +"<literal>&lt;key&gt;</literal> element of the collection mapping. Do not " +"only declare <literal>not-null=\"true\"</literal> on a possible nested " +"<literal>&lt;column&gt;</literal> element, but on the <literal>&lt;key&gt;</" +"literal> element." +msgstr "" +"Il est important de définir <literal>not-null=\"true</literal> sur l'élément " +"<literal>&lt;key&gt;</literal> du mapping de la collection si la colonne de " +"clé étrangère sous-jacente est <literal>NOT NULL</literal>. Ne déclarez pas " +"seulement <literal>not-null=\"true\"</literal> sur un élément imbriqué " +"possible<literal>&lt;column&gt;</literal>, mais sur l'élément <literal>&lt;" +"key&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>bidirectional one-to-one association on a foreign key</emphasis> " +"is common:" +msgstr "" +"Une <emphasis>association bidirectionnelle un-à-un sur une clé étrangère</" +"emphasis> est assez fréquente :" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>bidirectional one-to-one association on a primary key</emphasis> " +"uses the special id generator:" +msgstr "" +"Une <emphasis>association bidirectionnelle un-à-un sur une clé primaire</" +"emphasis> utilise un générateur particulier d'id :" + +#. Tag: title +#, no-c-format +msgid "Bidirectional associations with join tables" +msgstr "Associations bidirectionnelles avec tables de jointure" + +#. Tag: para +#, no-c-format +msgid "" +"The following is an example of a <emphasis>bidirectional one-to-many " +"association on a join table</emphasis>. The <literal>inverse=\"true\"</" +"literal> can go on either end of the association, on the collection, or on " +"the join." +msgstr "" +"Une <emphasis>association bidirectionnelle un-à-plusieurs sur une table de " +"jointure</emphasis>. Remarquez que <literal>inverse=\"true\"</literal> peut " +"s'appliquer sur les deux extrémités de l'association, sur la collection, ou " +"sur la jointure." + +#. Tag: title +#, no-c-format +msgid "one to one" +msgstr "un-à-un" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>bidirectional one-to-one association on a join table</emphasis> " +"is possible, but extremely unusual." +msgstr "" +"Une <emphasis>association bidirectionnelle un-à-un sur une table de " +"jointure</emphasis> est extrêmement rare mais envisageable. " + +#. Tag: para +#, no-c-format +msgid "" +"Here is an example of a <emphasis>bidirectional many-to-many association</" +"emphasis>." +msgstr "" +"Finalement nous avons <emphasis>l'association bidirectionnelle plusieurs-à-" +"plusieurs</emphasis>. " + +#. Tag: title +#, no-c-format +msgid "More complex association mappings" +msgstr "Des mappages d'associations plus complexes" + +#. Tag: para +#, no-c-format +msgid "" +"More complex association joins are <emphasis>extremely</emphasis> rare. " +"Hibernate handles more complex situations by using SQL fragments embedded in " +"the mapping document. For example, if a table with historical account " +"information data defines <literal>accountNumber</literal>, " +"<literal>effectiveEndDate</literal> and <literal>effectiveStartDate</" +"literal>columns, it would be mapped as follows:" +msgstr "" +"Des associations encore plus complexes sont <emphasis>extrêmement</emphasis> " +"rares. Hibernate permet de gérer des situations plus complexes en utilisant " +"des extraits SQL embarqués dans le fichier de mapping. Par exemple, si une " +"table avec des informations historiques sur un compte définit les colonnes " +"<literal>accountNumber</literal>, <literal>effectiveEndDate</literal> et " +"<literal>effectiveStartDate</literal>, elle sera mappée de la façon " +"suivante : " + +#. Tag: para +#, no-c-format +msgid "" +"You can then map an association to the <emphasis>current</emphasis> " +"instance, the one with null <literal>effectiveEndDate</literal>, by using:" +msgstr "" +"Nous pouvons mapper une association à l'instance <emphasis>courante</" +"emphasis>, celle avec une <literal>effectiveEndDate</literal> nulle, en " +"utilisant :" + +#. Tag: para +#, no-c-format +msgid "" +"In a more complex example, imagine that the association between " +"<literal>Employee</literal> and <literal>Organization</literal> is " +"maintained in an <literal>Employment</literal> table full of historical " +"employment data. An association to the employee's <emphasis>most recent</" +"emphasis> employer, the one with the most recent <literal>startDate</" +"literal>, could be mapped in the following way:" +msgstr "" +"Dans un exemple plus complexe, imaginez qu'une association entre " +"<literal>Employee</literal> et <literal>Organization</literal> soit gérée " +"dans une table <literal>Employment</literal> pleine de données historiques. " +"Dans ce cas, une association vers l'employeur <emphasis>le plus récent</" +"emphasis> (celui avec la <literal>startDate</literal> (date de commencement " +"de travail la plus récente) pourrait être mappée comme suit :" + +#. Tag: para +#, no-c-format +msgid "" +"This functionality allows a degree of creativity and flexibility, but it is " +"more practical to handle these kinds of cases using HQL or a criteria query." +msgstr "" +"Vous pouvez être créatif grâce à ces possibilités, mais il est généralement " +"plus pratique de gérer ce genre de cas en utilisant des requêtes HQL ou par " +"critère." + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key, addressId " +#~ "bigint not null )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key, addressId " +#~ "bigint not null )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\" \n" +#~ " unique=\"true\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\" \n" +#~ " unique=\"true\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key, addressId " +#~ "bigint not null unique )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key, addressId " +#~ "bigint not null unique )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"foreign\">\n" +#~ " <param name=\"property\">person</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" constrained=\"true\"/>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"foreign\">\n" +#~ " <param name=\"property\">person</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" constrained=\"true\"/>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table Address ( personId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table Address ( personId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\">\n" +#~ " <key column=\"personId\" \n" +#~ " not-null=\"true\"/>\n" +#~ " <one-to-many class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\">\n" +#~ " <key column=\"personId\" \n" +#~ " not-null=\"true\"/>\n" +#~ " <one-to-many class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table Address ( addressId bigint not null primary key, personId " +#~ "bigint not null )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table Address ( addressId bigint not null primary key, personId " +#~ "bigint not null )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " unique=\"true\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " unique=\"true\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId not null, addressId bigint not null " +#~ "primary key )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId not null, addressId bigint not null " +#~ "primary key )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null primary key, " +#~ "addressId bigint not null )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null primary key, " +#~ "addressId bigint not null )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null primary key, " +#~ "addressId bigint not null unique )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null primary key, " +#~ "addressId bigint not null unique )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null, addressId bigint " +#~ "not null, primary key (personId, addressId) )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null, addressId bigint " +#~ "not null, primary key (personId, addressId) )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"people\" inverse=\"true\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <one-to-many class=\"Person\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"people\" inverse=\"true\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <one-to-many class=\"Person\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\"/>\n" +#~ " ...\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\"/>\n" +#~ " ...\n" +#~ " <list name=\"people\">\n" +#~ " <key column=\"addressId\" not-null=\"true\"/>\n" +#~ " <list-index column=\"peopleIdx\"/>\n" +#~ " <one-to-many class=\"Person\"/>\n" +#~ " </list>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\"/>\n" +#~ " ...\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\"\n" +#~ " not-null=\"true\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\"/>\n" +#~ " ...\n" +#~ " <list name=\"people\">\n" +#~ " <key column=\"addressId\" not-null=\"true\"/>\n" +#~ " <list-index column=\"peopleIdx\"/>\n" +#~ " <one-to-many class=\"Person\"/>\n" +#~ " </list>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\" \n" +#~ " unique=\"true\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" \n" +#~ " property-ref=\"address\"/>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <many-to-one name=\"address\" \n" +#~ " column=\"addressId\" \n" +#~ " unique=\"true\"\n" +#~ " not-null=\"true\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" \n" +#~ " property-ref=\"address\"/>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"address\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"foreign\">\n" +#~ " <param name=\"property\">person</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" \n" +#~ " constrained=\"true\"/>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"address\"/>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"foreign\">\n" +#~ " <param name=\"property\">person</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <one-to-one name=\"person\" \n" +#~ " constrained=\"true\"/>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" \n" +#~ " table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " unique=\"true\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " inverse=\"true\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <many-to-one name=\"person\"\n" +#~ " column=\"personId\"\n" +#~ " not-null=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" \n" +#~ " table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " unique=\"true\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " inverse=\"true\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <many-to-one name=\"person\"\n" +#~ " column=\"personId\"\n" +#~ " not-null=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null, addressId bigint " +#~ "not null primary key )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" +#~ msgstr "" +#~ "<![CDATA[\n" +#~ "create table Person ( personId bigint not null primary key )\n" +#~ "create table PersonAddress ( personId bigint not null, addressId bigint " +#~ "not null primary key )\n" +#~ "create table Address ( addressId bigint not null primary key )\n" +#~ " ]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\"\n" +#~ " inverse=\"true\">\n" +#~ " <key column=\"addressId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"person\"\n" +#~ " column=\"personId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\">\n" +#~ " <key column=\"personId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"address\"\n" +#~ " column=\"addressId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <join table=\"PersonAddress\" \n" +#~ " optional=\"true\"\n" +#~ " inverse=\"true\">\n" +#~ " <key column=\"addressId\" \n" +#~ " unique=\"true\"/>\n" +#~ " <many-to-one name=\"person\"\n" +#~ " column=\"personId\" \n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ " </join>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"people\" inverse=\"true\" table=\"PersonAddress\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <many-to-many column=\"personId\"\n" +#~ " class=\"Person\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"id\" column=\"personId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"addresses\" table=\"PersonAddress\">\n" +#~ " <key column=\"personId\"/>\n" +#~ " <many-to-many column=\"addressId\"\n" +#~ " class=\"Address\"/>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ " <id name=\"id\" column=\"addressId\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <set name=\"people\" inverse=\"true\" table=\"PersonAddress\">\n" +#~ " <key column=\"addressId\"/>\n" +#~ " <many-to-many column=\"personId\"\n" +#~ " class=\"Person\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<properties name=\"currentAccountKey\">\n" +#~ " <property name=\"accountNumber\" type=\"string\" not-null=\"true\"/>\n" +#~ " <property name=\"currentAccount\" type=\"boolean\">\n" +#~ " <formula>case when effectiveEndDate is null then 1 else 0 end</" +#~ "formula>\n" +#~ " </property>\n" +#~ "</properties>\n" +#~ "<property name=\"effectiveEndDate\" type=\"date\"/>\n" +#~ "<property name=\"effectiveStateDate\" type=\"date\" not-null=\"true\"/>]]>" +#~ msgstr "" +#~ "<![CDATA[<properties name=\"currentAccountKey\">\n" +#~ " <property name=\"accountNumber\" type=\"string\" not-null=\"true\"/>\n" +#~ " <property name=\"currentAccount\" type=\"boolean\">\n" +#~ " <formula>case when effectiveEndDate is null then 1 else 0 end</" +#~ "formula>\n" +#~ " </property>\n" +#~ "</properties>\n" +#~ "<property name=\"effectiveEndDate\" type=\"date\"/>\n" +#~ "<property name=\"effectiveStateDate\" type=\"date\" not-null=\"true\"/>]]>" + +#~ msgid "" +#~ "<![CDATA[<many-to-one name=\"currentAccountInfo\" \n" +#~ " property-ref=\"currentAccountKey\"\n" +#~ " class=\"AccountInfo\">\n" +#~ " <column name=\"accountNumber\"/>\n" +#~ " <formula>'1'</formula>\n" +#~ "</many-to-one>]]>" +#~ msgstr "" +#~ "<![CDATA[<many-to-one name=\"currentAccountInfo\" \n" +#~ " property-ref=\"currentAccountKey\"\n" +#~ " class=\"AccountInfo\">\n" +#~ " <column name=\"accountNumber\"/>\n" +#~ " <formula>'1'</formula>\n" +#~ "</many-to-one>]]>" + +#~ msgid "" +#~ "<![CDATA[<join>\n" +#~ " <key column=\"employeeId\"/>\n" +#~ " <subselect>\n" +#~ " select employeeId, orgId \n" +#~ " from Employments \n" +#~ " group by orgId \n" +#~ " having startDate = max(startDate)\n" +#~ " </subselect>\n" +#~ " <many-to-one name=\"mostRecentEmployer\" \n" +#~ " class=\"Organization\" \n" +#~ " column=\"orgId\"/>\n" +#~ "</join>]]>" +#~ msgstr "" +#~ "<![CDATA[<join>\n" +#~ " <key column=\"employeeId\"/>\n" +#~ " <subselect>\n" +#~ " select employeeId, orgId \n" +#~ " from Employments \n" +#~ " group by orgId \n" +#~ " having startDate = max(startDate)\n" +#~ " </subselect>\n" +#~ " <many-to-one name=\"mostRecentEmployer\" \n" +#~ " class=\"Organization\" \n" +#~ " column=\"orgId\"/>\n" +#~ "</join>]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/basic_mapping.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/basic_mapping.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/basic_mapping.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,4324 @@ +# translation of basic_mapping.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: basic_mapping\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-04 17:01+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Basic O/R Mapping" +msgstr "Mappage O/R de base" + +#. Tag: title +#, no-c-format +msgid "Mapping declaration" +msgstr "Déclaration de mappage" + +#. Tag: para +#, no-c-format +msgid "" +"Object/relational mappings are usually defined in an XML document. The " +"mapping document is designed to be readable and hand-editable. The mapping " +"language is Java-centric, meaning that mappings are constructed around " +"persistent class declarations and not table declarations." +msgstr "" +"Les mappages objet/relationnel sont généralement définis dans un document " +"XML. Le document de mappage est conçu pour être lisible et éditable à la " +"main. Le langage de mappage est Java-centrique, c'est-à-dire que les " +"mappages sont construits à partir de déclarations de classes persistantes et " +"non à partir de déclarations de tables. " + +#. Tag: para +#, no-c-format +msgid "" +"Please note that even though many Hibernate users choose to write the XML by " +"hand, a number of tools exist to generate the mapping document. These " +"include XDoclet, Middlegen and AndroMDA." +msgstr "" +"Remarquez que même si beaucoup d'utilisateurs de Hibernate préfèrent écrire " +"les fichiers de mappages XML à la main, plusieurs outils existent pour " +"générer ce document, notamment XDoclet, Middlegen et AndroMDA. " + +#. Tag: para +#, no-c-format +msgid "Here is an example mapping:" +msgstr "Commençons avec un exemple de mappage : " + +#. Tag: para +#, no-c-format +msgid "" +"We will now discuss the content of the mapping document. We will only " +"describe, however, the document elements and attributes that are used by " +"Hibernate at runtime. The mapping document also contains some extra optional " +"attributes and elements that affect the database schemas exported by the " +"schema export tool (for example, the <literal> not-null</literal> attribute)." +msgstr "" +"Étudions le contenu du document de mappage. Nous ne décrirons que les " +"éléments et attributs du document utilisés par Hibernate à l'exécution. Le " +"document de mappage contient aussi des attributs et éléments optionnels qui " +"agissent sur le schéma de base de données exporté par l'outil de génération " +"de schéma. (Par exemple l'attribut <literal>not-null</literal>)." + +#. Tag: title +#, no-c-format +msgid "Doctype" +msgstr "Doctype" + +#. Tag: para +#, no-c-format +msgid "" +"All XML mappings should declare the doctype shown. The actual DTD can be " +"found at the URL above, in the directory <literal>hibernate-x.x.x/src/org/" +"hibernate </literal>, or in <literal>hibernate3.jar</literal>. Hibernate " +"will always look for the DTD in its classpath first. If you experience " +"lookups of the DTD using an Internet connection, check the DTD declaration " +"against the contents of your classpath." +msgstr "" +"Tous les mappages XML devraient utiliser le doctype indiqué. En effet vous " +"trouverez le fichier DTD à l'URL ci-dessus, dans le répertoire " +"<literal>hibernate-x.x.x/src/org/hibernate</literal> ou dans " +"<literal>hibernate3.jar</literal>. Hibernate va toujours chercher la DTD " +"dans son classpath en premier lieu. Si vous constatez des recherches de la " +"DTD sur Internet, vérifiez votre déclaration de DTD par rapport au contenu " +"de votre classpath. " + +#. Tag: title +#, no-c-format +msgid "EntityResolver" +msgstr "EntityResolver" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will first attempt to resolve DTDs in its classpath. It does this " +"is by registering a custom <literal>org.xml.sax.EntityResolver</literal> " +"implementation with the SAXReader it uses to read in the xml files. This " +"custom <literal>EntityResolver</literal> recognizes two different systemId " +"namespaces:" +msgstr "" +"Comme mentionné précédemment, Hibernate tentera en premier lieu de résoudre " +"les DTD dans leur classpath. Il réussit à le faire en enregistrant une " +"implémentation personnalisée de <literal>org.xml.sax.EntityResolver</" +"literal> avec le SAXReader qu'il utilise pour lire les fichiers xml. Cet " +"<literal>EntityResolver</literal> personnalisé reconnaît deux espaces de " +"nommage systemId différents :" + +#. Tag: para +#, no-c-format +msgid "" +"a <literal>hibernate namespace</literal> is recognized whenever the resolver " +"encounters a systemId starting with <literal>http://hibernate.sourceforge." +"net/</literal>. The resolver attempts to resolve these entities via the " +"classloader which loaded the Hibernate classes." +msgstr "" +"un <literal>espace de nommage hibernate</literal> est reconnu dès que le " +"résolveur rencontre un systemId commençant par <literal>http://hibernate." +"sourceforge.net/</literal>. Le résolveur tente alors de résoudre ces entités " +"via le chargeur de classe qui a chargé les classes Hibernate." + +#. Tag: para +#, no-c-format +msgid "" +"a <literal>user namespace</literal> is recognized whenever the resolver " +"encounters a systemId using a <literal>classpath://</literal> URL protocol. " +"The resolver will attempt to resolve these entities via (1) the current " +"thread context classloader and (2) the classloader which loaded the " +"Hibernate classes." +msgstr "" +"un <literal>espace de nommage utilisateur</literal> est reconnu dès que le " +"résolveur rencontre un systemId qui utilise un protocole URL " +"<literal>classpath://</literal>. Le résolveur tentera alors de résoudre ces " +"entités via (1) le chargeur de classe du contexte du thread courant et (2) " +"le chargeur de classe qui a chargé les classes Hibernate." + +#. Tag: para +#, no-c-format +msgid "The following is an example of utilizing user namespacing:" +msgstr "Un exemple d'utilisation de l'espace de nommage utilisateur: " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Where <literal>types.xml</literal> is a resource in the <literal>your." +"domain</literal> package and contains a custom <link linkend=\"mapping-types-" +"custom\">typedef</link>." +msgstr "" +"Là où <literal>types.xml</literal> est une ressource dans votre paquetage " +"<literal>your.domain</literal> et contient un <xref linkend=\"mapping-types-" +"custom\"/> personnalisé. " + +#. Tag: title +#, no-c-format +msgid "Hibernate-mapping" +msgstr "Hibernate-mappage" + +#. Tag: para +#, no-c-format +msgid "" +"This element has several optional attributes. The <literal>schema</literal> " +"and <literal>catalog</literal> attributes specify that tables referred to in " +"this mapping belong to the named schema and/or catalog. If they are " +"specified, tablenames will be qualified by the given schema and catalog " +"names. If they are missing, tablenames will be unqualified. The " +"<literal>default-cascade</literal> attribute specifies what cascade style " +"should be assumed for properties and collections that do not specify a " +"<literal>cascade</literal> attribute. By default, the <literal>auto-import</" +"literal> attribute allows you to use unqualified class names in the query " +"language." +msgstr "" +"Cet élément a plusieurs attributs optionnels. Les attributs <literal>schema</" +"literal> et <literal>catalog</literal> indiquent que les tables mentionnées " +"dans ce mappage appartiennent au schéma nommé et/ou au catalogue. S'ils sont " +"spécifiés, les noms de tables seront qualifiés par les noms de schéma et de " +"catalogue. L'attribut <literal>default-cascade</literal> indique quel type " +"de cascade sera utilisé par défaut pour les propriétés et collections qui ne " +"précisent pas l'attribut <literal>cascade</literal>. L'attribut " +"<literal>auto-import</literal> nous permet d'utiliser par défaut des noms de " +"classes non qualifiés dans le langage de requête, par défaut. " + +#. Tag: para +#, no-c-format +msgid "<literal>schema</literal> (optional): the name of a database schema." +msgstr "" +"<literal>schema</literal> (optionnel) : le nom d'un schéma de base de " +"données. " + +#. Tag: para +#, no-c-format +msgid "<literal>catalog</literal> (optional): the name of a database catalog." +msgstr "" +"<literal>catalog</literal> (optionnel) : le nom d'un catalogue de base de " +"données. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>default-cascade</literal> (optional - defaults to <literal>none</" +"literal>): a default cascade style." +msgstr "" +"<literal>default-cascade</literal> (optionnel - par défaut vaut : " +"<literal>none</literal>) : un type de cascade par défaut. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>default-access</literal> (optional - defaults to <literal>property</" +"literal>): the strategy Hibernate should use for accessing all properties. " +"It can be a custom implementation of <literal>PropertyAccessor</literal>." +msgstr "" +"<literal>default-access</literal> (optionnel - par défaut vaut : " +"<literal>property</literal>) : Comment hibernate accèdera aux propriétés. On " +"peut aussi redéfinir sa propre implémentation de <literal>PropertyAccessor</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>default-lazy</literal> (optional - defaults to <literal>true</" +"literal>): the default value for unspecified <literal>lazy</literal> " +"attributes of class and collection mappings." +msgstr "" +"<literal>default-lazy</literal> (optionnel - par défaut vaut : " +"<literal>true</literal>) : Valeur par défaut pour des attributs " +"<literal>lazy</literal> non spécifiés des mappages de classe et de " +"collection. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>auto-import</literal> (optional - defaults to <literal>true</" +"literal>): specifies whether we can use unqualified class names of classes " +"in this mapping in the query language." +msgstr "" +"<literal>auto-import</literal> (optionnel - par défaut vaut : <literal>true</" +"literal>) : spécifie si l'on peut utiliser des noms de classes non qualifiés " +"(de classes de ce mappage) dans le langage de requête. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>package</literal> (optional): specifies a package prefix to use for " +"unqualified class names in the mapping document." +msgstr "" +"<literal>package</literal> (optionnel) : préfixe de paquetage par défaut " +"pour les noms de classe non qualifiés du document de mappage. " + +#. Tag: para +#, no-c-format +msgid "" +"If you have two persistent classes with the same unqualified name, you " +"should set <literal>auto-import=\"false\"</literal>. An exception will " +"result if you attempt to assign two classes to the same \"imported\" name." +msgstr "" +"Si deux classes persistantes possèdent le même nom de classe (non qualifié), " +"vous devez configurer <literal>auto-import=\"false\"</literal>. Hibernate " +"lancera une exception si vous essayez d'assigner le même nom \"importé\" à " +"deux classes." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>hibernate-mapping</literal> element allows you to nest several " +"persistent <literal>&lt;class&gt;</literal> mappings, as shown above. It is, " +"however, good practice (and expected by some tools) to map only a single " +"persistent class, or a single class hierarchy, in one mapping file and name " +"it after the persistent superclass. For example, <literal>Cat.hbm.xml</" +"literal>, <literal>Dog.hbm.xml</literal>, or if using inheritance, " +"<literal>Animal.hbm.xml</literal>." +msgstr "" +"Notez que l'élément <literal>hibernate-mappage</literal> vous permet " +"d'imbriquer plusieurs mappages de <literal>&lt;class&gt;</literal> " +"persistantes, comme dans l'exemple ci-dessus. Cependant il est recommandé " +"(et c'est parfois une exigence de certains outils) de mapper une seule " +"classe persistante (ou une seule hiérarchie de classes) par fichier de " +"mappage et de nommer ce fichier d'après le nom de la superclasse " +"persistante, par exemple <literal>Cat.hbm.xml</literal>, <literal>Dog.hbm." +"xml</literal>, ou en cas d'héritage, <literal>Animal.hbm.xml</literal>. " + +#. Tag: title +#, no-c-format +msgid "Class" +msgstr "Classe" + +#. Tag: para +#, no-c-format +msgid "" +"You can declare a persistent class using the <literal>class</literal> " +"element. For example:" +msgstr "" +"Déclarez une classe persistante avec l'élément <literal>class</literal>. " +"Part exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal> (optional): the fully qualified Java class name of " +"the persistent class or interface. If this attribute is missing, it is " +"assumed that the mapping is for a non-POJO entity." +msgstr "" +"<literal>name</literal> (optionnel) : le nom Java complet de la classe (ou " +"interface) persistante. Si cet attribut est absent, nous supposons que ce " +"mappage ne se rapporte pas à une entité POJO. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>table</literal> (optional - defaults to the unqualified class " +"name): the name of its database table." +msgstr "" +"<literal>table</literal> (optionnel - par défaut le nom non-qualifié de la " +"classe) : le nom de sa table en base de données." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>discriminator-value</literal> (optional - defaults to the class " +"name): a value that distinguishes individual subclasses that is used for " +"polymorphic behavior. Acceptable values include <literal>null</literal> and " +"<literal>not null</literal>." +msgstr "" +"<literal>discriminator-value</literal> (optionnel - par défaut le nom de la " +"classe) : une valeur permettant de distinguer les différentes sous-classes " +"utilisées dans le comportement polymorphique. Les valeurs <literal>null</" +"literal> et <literal>not null</literal> sont autorisées. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>mutable</literal> (optional - defaults to <literal>true</literal>): " +"specifies that instances of the class are (not) mutable." +msgstr "" +"<literal>mutable</literal> (optionnel, vaut <literal>true</literal> par " +"défaut) : spécifie que des instances de la classe sont (ou non) immuables. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>schema</literal> (optional): overrides the schema name specified by " +"the root <literal>&lt;hibernate-mapping&gt;</literal> element." +msgstr "" +"<literal>schema</literal> (optionnel) : surcharge le nom de schéma spécifié " +"par l'élément racine <literal>&lt;hibernate-mappage&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>catalog</literal> (optional): overrides the catalog name specified " +"by the root <literal>&lt;hibernate-mapping&gt;</literal> element." +msgstr "" +"<literal>catalog</literal> (optionnel) : surcharge le nom du catalogue " +"spécifié par l'élément racine <literal>&lt;hibernate-mappage&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>proxy</literal> (optional): specifies an interface to use for lazy " +"initializing proxies. You can specify the name of the class itself." +msgstr "" +"<literal>proxy</literal> (optionnel) : spécifie une interface à utiliser " +"pour l'initialisation différée (lazy loading) des proxies. Vous pouvez " +"indiquer le nom de la classe elle-même. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>dynamic-update</literal> (optional - defaults to <literal>false</" +"literal>): specifies that <literal>UPDATE</literal> SQL should be generated " +"at runtime and can contain only those columns whose values have changed." +msgstr "" +"<literal>dynamic-update</literal> (optionnel, par défaut à <literal>false</" +"literal>) : spécifie que les SQL <literal>UPDATE</literal> doivent être " +"générés à l'exécution et contenir uniquement les colonnes dont les valeurs " +"ont été modifiées. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>dynamic-insert</literal> (optional - defaults to <literal>false</" +"literal>): specifies that <literal>INSERT</literal> SQL should be generated " +"at runtime and contain only the columns whose values are not null." +msgstr "" +"<literal>dynamic-insert</literal> (optionnel, par défaut à <literal>false</" +"literal>) : spécifie que les SQL <literal>INSERT</literal> doivent être " +"générés à l'exécution et ne contenir que les colonnes dont les valeurs sont " +"non nulles. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>select-before-update</literal> (optional - defaults to " +"<literal>false</literal>): specifies that Hibernate should <emphasis>never</" +"emphasis> perform an SQL <literal>UPDATE</literal> unless it is certain that " +"an object is actually modified. Only when a transient object has been " +"associated with a new session using <literal>update()</literal>, will " +"Hibernate perform an extra SQL <literal>SELECT</literal> to determine if an " +"<literal>UPDATE</literal> is actually required." +msgstr "" +"<literal>select-before-update</literal> (optionnel, par défaut à " +"<literal>false</literal>): spécifie que Hibernate ne doit <emphasis>jamais</" +"emphasis> exécuter un SQL <literal>UPDATE</literal> sans être certain qu'un " +"objet a été réellement modifié. Dans certains cas, (en réalité, seulement " +"quand un objet transient a été associé à une nouvelle session par " +"<literal>update()</literal>), cela signifie que Hibernate exécutera un SQL " +"<literal>SELECT</literal> pour déterminer si un SQL <literal>UPDATE</" +"literal> est véritablement nécessaire. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>polymorphism</literal> (optional - defaults to <literal>implicit</" +"literal>): determines whether implicit or explicit query polymorphism is " +"used." +msgstr "" +"<literal>polymorphism</literal> (optionnel, vaut <literal>implicit</literal> " +"par défaut) : détermine si, pour cette classe, une requête polymorphique " +"implicite ou explicite est utilisée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>where</literal> (optional): specifies an arbitrary SQL " +"<literal>WHERE</literal> condition to be used when retrieving objects of " +"this class." +msgstr "" +"<literal>where</literal> (optionnel) spécifie une clause SQL <literal>WHERE</" +"literal> à utiliser lorsque l'on récupère des objets de cette classe. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>persister</literal> (optional): specifies a custom " +"<literal>ClassPersister</literal>." +msgstr "" +"<literal>persister</literal> (optionnel) : spécifie un " +"<literal>ClassPersister</literal> particulier. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>batch-size</literal> (optional - defaults to <literal>1</literal>): " +"specifies a \"batch size\" for fetching instances of this class by " +"identifier." +msgstr "" +"<literal>batch-size</literal> (optionnel, par défaut = <literal>1</" +"literal>) : spécifie une \"taille de lot\" pour remplir les instances de " +"cette classe par identifiant en une seule requête." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>version</" +"literal>): determines the optimistic locking strategy." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel, par défaut = " +"<literal>version</literal>) : détermine la stratégie de verrouillage " +"optimiste. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional): lazy fetching can be disabled by setting " +"<literal>lazy=\"false\"</literal>." +msgstr "" +"<literal>lazy</literal> (optionnel) : l'extraction différée (lazy fetching) " +"peut être totalement désactivée en configurant <literal>lazy=\"false\"</" +"literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>entity-name</literal> (optional - defaults to the class name): " +"Hibernate3 allows a class to be mapped multiple times, potentially to " +"different tables. It also allows entity mappings that are represented by " +"Maps or XML at the Java level. In these cases, you should provide an " +"explicit arbitrary name for the entity. See <xref linkend=\"persistent-" +"classes-dynamicmodels\" /> and <xref linkend=\"xml\" /> for more information." +msgstr "" +"<literal>entity-name</literal> (optionnel - le nom de classe par défaut) : " +"Hibernate3 permet à une classe d'être mappée plusieurs fois (potentiellement " +"à plusieurs tables), et permet aux mappages d'entité d'être représentés par " +"des Maps ou du XML au niveau Java. Dans ces cas, vous devez indiquer un nom " +"explicite arbitraire pour les entités. Consultez <xref linkend=\"persistent-" +"classes-dynamicmodels\"/> et <xref linkend=\"xml\"/> pour plus " +"d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>check</literal> (optional): an SQL expression used to generate a " +"multi-row <emphasis>check</emphasis> constraint for automatic schema " +"generation." +msgstr "" +"<literal>check</literal> (optionnel) : expression SQL utilisée pour générer " +"une contrainte de vérification <emphasis>check</emphasis> multi-lignes pour " +"la génération automatique de schéma. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>rowid</literal> (optional): Hibernate can use ROWIDs on databases. " +"On Oracle, for example, Hibernate can use the <literal>rowid</literal> extra " +"column for fast updates once this option has been set to <literal>rowid</" +"literal>. A ROWID is an implementation detail and represents the physical " +"location of a stored tuple." +msgstr "" +"<literal>rowid</literal> (optionnel) : Hibernate peut utiliser des ROWID sur " +"les bases de données qui utilisent ce mécanisme. Par exemple avec Oracle, " +"Hibernate peut utiliser la colonne additionnelle <literal>rowid</literal> " +"pour des mise à jour rapides si cette option vaut <literal>rowid</literal>. " +"Un ROWID est un détail d'implémentation et représente la localisation " +"physique d'un uplet enregistré. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>subselect</literal> (optional): maps an immutable and read-only " +"entity to a database subselect. This is useful if you want to have a view " +"instead of a base table. See below for more information." +msgstr "" +"<literal>subselect</literal> (optionnel) : permet de mapper une entité " +"immuable en lecture-seule sur un sous-select de base de données. Utile pour " +"avoir une vue au lieu d'une table de base, mais à éviter. Voir plus bas pour " +"plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>abstract</literal> (optional): is used to mark abstract " +"superclasses in <literal>&lt;union-subclass&gt;</literal> hierarchies." +msgstr "" +"<literal>abstract</literal> (optionnel) : utilisé pour marquer des " +"superclasses abstraites dans des hiérarchies de <literal>&lt;union-" +"subclass&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"It is acceptable for the named persistent class to be an interface. You can " +"declare implementing classes of that interface using the <literal>&lt;" +"subclass&gt;</literal> element. You can persist any <emphasis>static</" +"emphasis> inner class. Specify the class name using the standard form i.e. " +"<literal>e.g.Foo$Bar</literal>." +msgstr "" +"Il est tout à fait possible d'utiliser une interface comme nom de classe " +"persistante. Vous devez alors déclarer les classes implémentant cette " +"interface en utilisant l'élément <literal>&lt;subclass&gt;</literal>. Vous " +"pouvez faire persister toute classe interne <emphasis>static</emphasis>. " +"Vous devez alors spécifier le nom de la classe par la notation habituelle " +"des classes internes, c'est à dire <literal>eg.Foo$Bar</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Immutable classes, <literal>mutable=\"false\"</literal>, cannot be updated " +"or deleted by the application. This allows Hibernate to make some minor " +"performance optimizations." +msgstr "" +"Les classes immuables, <literal>mutable=\"false\"</literal>, ne peuvent pas " +"être modifiées ou supprimées par l'application. Cela permet à Hibernate de " +"faire quelques optimisations mineures sur les performances. " + +#. Tag: para +#, no-c-format +msgid "" +"The optional <literal>proxy</literal> attribute enables lazy initialization " +"of persistent instances of the class. Hibernate will initially return CGLIB " +"proxies that implement the named interface. The persistent object will load " +"when a method of the proxy is invoked. See \"Initializing collections and " +"proxies\" below." +msgstr "" +"L'attribut optionnel <literal>proxy</literal> permet les initialisations " +"différées des instances persistantes de la classe. Hibernate retournera " +"initialement des proxies CGLIB qui implémentent l'interface nommée. Le " +"véritable objet persistant ne sera chargé que lorsqu'une méthode du proxy " +"sera appelée. Voir plus bas le paragraphe abordant les Proxies et leur " +"initialisation différée (lazy initialization). " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Implicit</emphasis> polymorphism means that instances of the class " +"will be returned by a query that names any superclass or implemented " +"interface or class, and that instances of any subclass of the class will be " +"returned by a query that names the class itself. <emphasis>Explicit</" +"emphasis> polymorphism means that class instances will be returned only by " +"queries that explicitly name that class. Queries that name the class will " +"return only instances of subclasses mapped inside this <literal>&lt;class&gt;" +"</literal> declaration as a <literal>&lt;subclass&gt;</literal> or " +"<literal>&lt;joined-subclass&gt;</literal>. For most purposes, the default " +"<literal>polymorphism=\"implicit\"</literal> is appropriate. Explicit " +"polymorphism is useful when two different classes are mapped to the same " +"table This allows a \"lightweight\" class that contains a subset of the " +"table columns." +msgstr "" +"Le polymorphisme <emphasis>implicite</emphasis> signifie que des instances " +"de la classe seront retournées par une requête qui utilise les noms de la " +"classe ou de chacune de ses superclasses ou encore des interfaces " +"implémentées par cette classe ou ses superclasses. Les instances des classes " +"filles seront retournées par une requête qui utilise le nom de la classe " +"elle même. Le polymorphisme <emphasis>explicite</emphasis> signifie que les " +"instances de la classe ne seront retournées que par une requête qui utilise " +"explicitement son nom et que seules les instances des classes filles " +"déclarées dans les éléments <literal>&lt;subclass&gt;</literal> ou " +"<literal>&lt;joined-subclass&gt;</literal> seront retournées. Dans la " +"majorités des cas la valeur par défaut, <literal>polymorphism=\"implicit\"</" +"literal>, est appropriée. Le polymorphisme explicite est utile lorsque deux " +"classes différentes sont mappées à la même table (ceci permet d'écrire une " +"classe \"légère\" qui ne contient qu'une partie des colonnes de la table - " +"voir la partie design pattern du site communautaire). " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>persister</literal> attribute lets you customize the " +"persistence strategy used for the class. You can, for example, specify your " +"own subclass of <literal>org.hibernate.persister.EntityPersister</literal>, " +"or you can even provide a completely new implementation of the interface " +"<literal>org.hibernate.persister.ClassPersister</literal> that implements, " +"for example, persistence via stored procedure calls, serialization to flat " +"files or LDAP. See <literal>org.hibernate.test.CustomPersister</literal> for " +"a simple example of \"persistence\" to a <literal>Hashtable</literal>." +msgstr "" +"L'attribut <literal>persister</literal> vous permet de personnaliser la " +"stratégie de persistance utilisée pour la classe. Vous pouvez, par exemple, " +"spécifier votre propre sous-classe de <literal>org.hibernate.persister." +"EntityPersister</literal> ou vous pourriez aussi fournir une nouvelle " +"implémentation de l'interface <literal>org.hibernate.persister." +"ClassPersister</literal> qui proposerait une persistance via, par exemple, " +"des appels de procédures stockées, de la sérialisation vers des fichiers " +"plats ou un annuaire LDAP. Voir <literal>org.hibernate.test.CustomPersister</" +"literal> pour un exemple simple (d'une \"persistance\" vers une " +"<literal>Hashtable</literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>dynamic-update</literal> and <literal>dynamic-insert</literal> " +"settings are not inherited by subclasses, so they can also be specified on " +"the <literal>&lt;subclass&gt;</literal> or <literal>&lt;joined-subclass&gt;</" +"literal> elements. Although these settings can increase performance in some " +"cases, they can actually decrease performance in others." +msgstr "" +"Notez que les paramètres <literal>dynamic-update</literal> et " +"<literal>dynamic-insert</literal> ne sont pas hérités par les sous-classes " +"et peuvent donc être spécifiés pour les éléments <literal>&lt;subclass&gt;</" +"literal> ou <literal>&lt;joined-subclass&gt;</literal>. Ces paramètres " +"peuvent améliorer les performances dans certains cas, mais peuvent aussi les " +"amoindrir. À utiliser en connaissance de causes. " + +#. Tag: para +#, no-c-format +msgid "" +"Use of <literal>select-before-update</literal> will usually decrease " +"performance. It is useful to prevent a database update trigger being called " +"unnecessarily if you reattach a graph of detached instances to a " +"<literal>Session</literal>." +msgstr "" +"L'utilisation de <literal>select-before-update</literal> va généralement " +"faire baisser les performances. Ce paramètre est pratique pour éviter " +"l'appel inutile par un déclenchement de mise à jour de base de donnée, quand " +"on ré-attache un graphe d'instances à une <literal>Session</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"If you enable <literal>dynamic-update</literal>, you will have a choice of " +"optimistic locking strategies:" +msgstr "" +"Si vous utilisez le <literal>dynamic-update</literal>, les différentes " +"stratégies de verrouillage optimiste sont les suivantes :" + +#. Tag: para +#, no-c-format +msgid "<literal>version</literal>: check the version/timestamp columns" +msgstr "<literal>version</literal> vérifie les colonnes version/timestamp " + +#. Tag: para +#, no-c-format +msgid "<literal>all</literal>: check all columns" +msgstr "<literal>all</literal> vérifie toutes les colonnes " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>dirty</literal>: check the changed columns, allowing some " +"concurrent updates" +msgstr "" +"<literal>dirty</literal> vérifie les colonnes modifiées, permettant quelques " +"mise à jour concurrentes " + +#. Tag: para +#, no-c-format +msgid "<literal>none</literal>: do not use optimistic locking" +msgstr "<literal>none</literal> n'utilisez pas le verrouillage optimiste " + +#. Tag: para +#, no-c-format +msgid "" +"It is <emphasis>strongly</emphasis> recommended that you use version/" +"timestamp columns for optimistic locking with Hibernate. This strategy " +"optimizes performance and correctly handles modifications made to detached " +"instances (i.e. when <literal>Session.merge()</literal> is used)." +msgstr "" +"Nous encourageons <emphasis>très</emphasis> fortement l'utilisation de " +"colonnes de version/timestamp pour le verrouillage optimiste avec Hibernate. " +"C'est la meilleure stratégie en ce qui concerne les performances et la seule " +"qui gère correctement les modifications sur les instances détachées (c'est à " +"dire lorsqu'on utilise <literal>Session.merge()</literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"There is no difference between a view and a base table for a Hibernate " +"mapping. This is transparent at the database level, although some DBMS do " +"not support views properly, especially with updates. Sometimes you want to " +"use a view, but you cannot create one in the database (i.e. with a legacy " +"schema). In this case, you can map an immutable and read-only entity to a " +"given SQL subselect expression:" +msgstr "" +"Il n'y a pas de différence entre table et vue pour le mappage Hibernate, " +"comme on peut s'y attendre, cela est transparent au niveau base de données " +"(remarquez que certaines BDD ne supportent pas les vues correctement, " +"notamment pour les mise à jour). Il est possible que vous souhaitiez " +"utiliser une vue mais vous ne puissiez pas en créer une sur votre BDD (c'est-" +"à-dire avec un schéma ancien). Dans ces cas, vous pouvez mapper une entité " +"immuable en lecture seule sur une expression sous-select SQL donnée :" + +#. Tag: para +#, no-c-format +msgid "" +"Declare the tables to synchronize this entity with, ensuring that auto-flush " +"happens correctly and that queries against the derived entity do not return " +"stale data. The <literal>&lt;subselect&gt;</literal> is available both as an " +"attribute and a nested mapping element." +msgstr "" +"Déclarez les tables à synchroniser avec cette entité pour assurer que le " +"flush automatique se produise correctement, et pour que les requêtes sur " +"l'entité dérivée ne renvoient pas des données périmées. Le <literal>&lt;" +"subselect&gt;</literal> est disponible comme attribut ou comme élément de " +"mappage imbriqué. " + +#. Tag: title +#, no-c-format +msgid "id" +msgstr "id" + +#. Tag: para +#, no-c-format +msgid "" +"Mapped classes <emphasis>must</emphasis> declare the primary key column of " +"the database table. Most classes will also have a JavaBeans-style property " +"holding the unique identifier of an instance. The <literal>&lt;id&gt;</" +"literal> element defines the mapping from that property to the primary key " +"column." +msgstr "" +"Les classes mappées <emphasis>doivent</emphasis> déclarer la clé primaire de " +"la table en base de données. La plupart des classes auront aussi une " +"propriété de type JavaBeans présentant l'identifiant unique d'une instance. " +"L'élément <literal>&lt;id&gt;</literal> sert à définir le mappage entre " +"cette propriété et la colonne de la clé primaire." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal> (optional): the name of the identifier property." +msgstr "" +"<literal>name</literal> (optionnel) : nom de la propriété de l'identifiant." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>type</literal> (optional): a name that indicates the Hibernate type." +msgstr "" +"<literal>type</literal> (optionnel) : nom indiquant le type Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional - defaults to the property name): the " +"name of the primary key column." +msgstr "" +"<literal>column</literal> (optionnel - le nom de la propriété est pris par " +"défaut) : nom de la colonne de la clé primaire." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unsaved-value</literal> (optional - defaults to a \"sensible\" " +"value): an identifier property value that indicates an instance is newly " +"instantiated (unsaved), distinguishing it from detached instances that were " +"saved or loaded in a previous session." +msgstr "" +"<literal>unsaved-value</literal> (optionnel - devient par défaut une valeur " +"\"sensible\") : une valeur de propriété d'identifiant qui indique que " +"l'instance est nouvellement instanciée (non sauvegardée), et qui la " +"distingue des instances détachées qui ont été sauvegardées ou chargées dans " +"une session précédente. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>access</literal> (optional - defaults to <literal>property</" +"literal>): the strategy Hibernate should use for accessing the property " +"value." +msgstr "" +"<literal>access</literal> (optionnel - par défaut <literal>property</" +"literal>) : la stratégie que doit utiliser Hibernate pour accéder aux " +"valeurs des propriétés. " + +#. Tag: para +#, no-c-format +msgid "" +"If the <literal>name</literal> attribute is missing, it is assumed that the " +"class has no identifier property." +msgstr "" +"Si l'attribut <literal>name</literal> est absent, Hibernate considère que la " +"classe ne possède pas de propriété d'identifiant." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>unsaved-value</literal> attribute is almost never needed in " +"Hibernate3." +msgstr "" +"L'attribut <literal>unsaved-value</literal> n'est presque jamais nécessaire " +"dans Hibernate3." + +#. Tag: para +#, no-c-format +msgid "" +"There is an alternative <literal>&lt;composite-id&gt;</literal> declaration " +"that allows access to legacy data with composite keys. Its use is strongly " +"discouraged for anything else." +msgstr "" +"La déclaration alternative <literal>&lt;composite-id&gt;</literal> permet " +"l'accès aux données d'anciens systèmes qui utilisent des clés composées. Son " +"utilisation est fortement déconseillée pour d'autres cas." + +#. Tag: title +#, no-c-format +msgid "Generator" +msgstr "Generator" + +#. Tag: para +#, no-c-format +msgid "" +"The optional <literal>&lt;generator&gt;</literal> child element names a Java " +"class used to generate unique identifiers for instances of the persistent " +"class. If any parameters are required to configure or initialize the " +"generator instance, they are passed using the <literal>&lt;param&gt;</" +"literal> element." +msgstr "" +"L'élément enfant <literal>&lt;generator&gt;</literal> nomme une classe Java " +"utilisée pour générer les identifiants uniques pour les instances des " +"classes persistantes. Si des paramètres sont requis pour configurer ou " +"initialiser l'instance du générateur, ils sont passés en utilisant l'élément " +"<literal>&lt;param&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"All generators implement the interface <literal>org.hibernate.id." +"IdentifierGenerator</literal>. This is a very simple interface. Some " +"applications can choose to provide their own specialized implementations, " +"however, Hibernate provides a range of built-in implementations. The " +"shortcut names for the built-in generators are as follows:" +msgstr "" +"Tous les générateurs implémentent l'interface <literal>org.hibernate.id." +"IdentifierGenerator</literal>. C'est une interface très simple ; certaines " +"applications peuvent proposer leurs propres implémentations spécialisées. " +"Cependant, Hibernate propose une série d'implémentations intégrées. Il " +"existe des noms raccourcis pour les générateurs intégrés :" + +#. Tag: term +#, no-c-format +msgid "<literal>increment</literal>" +msgstr "<literal>increment</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"generates identifiers of type <literal>long</literal>, <literal>short</" +"literal> or <literal>int</literal> that are unique only when no other " +"process is inserting data into the same table. <emphasis>Do not use in a " +"cluster.</emphasis>" +msgstr "" +"génère des identifiants de type <literal>long</literal>, <literal>short</" +"literal> ou <literal>int</literal> qui ne sont uniques que si aucun autre " +"processus n'insère de données dans la même table. <emphasis>Ne pas utiliser " +"en environnement clusterisé.</emphasis>" + +#. Tag: term +#, no-c-format +msgid "<literal>identity</literal>" +msgstr "<literal>identity</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"supports identity columns in DB2, MySQL, MS SQL Server, Sybase and " +"HypersonicSQL. The returned identifier is of type <literal>long</literal>, " +"<literal>short</literal> or <literal>int</literal>." +msgstr "" +"prend en charge les colonnes d'identité dans DB2, MySQL, MS SQL Server, " +"Sybase et HypersonicSQL. L'identifiant renvoyé est de type <literal>long</" +"literal>, <literal>short</literal> ou <literal>int</literal>." + +#. Tag: term +#, no-c-format +msgid "<literal>sequence</literal>" +msgstr "<literal>sequence</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"uses a sequence in DB2, PostgreSQL, Oracle, SAP DB, McKoi or a generator in " +"Interbase. The returned identifier is of type <literal>long</literal>, " +"<literal>short</literal> or <literal>int</literal>" +msgstr "" +"utilise une séquence dans DB2, PostgreSQL, Oracle, SAP DB, McKoi ou un " +"générateur dans Interbase. L'identifiant renvoyé est de type <literal>long</" +"literal>, <literal>short</literal> ou <literal>int</literal>" + +#. Tag: term +#, no-c-format +msgid "<literal>hilo</literal>" +msgstr "<literal>hilo</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"uses a hi/lo algorithm to efficiently generate identifiers of type " +"<literal>long</literal>, <literal>short</literal> or <literal>int</literal>, " +"given a table and column (by default <literal>hibernate_unique_key</literal> " +"and <literal>next_hi</literal> respectively) as a source of hi values. The " +"hi/lo algorithm generates identifiers that are unique only for a particular " +"database." +msgstr "" +"utilise un algorithme hi/lo pour générer de façon efficace des identifiants " +"de type <literal>long</literal>, <literal>short</literal> ou <literal>int</" +"literal>, en prenant comme source de valeurs \"hi\" une table et une colonne " +"(par défaut <literal>hibernate_unique_key</literal> et <literal>next_hi</" +"literal> respectivement). L'algorithme hi/lo génère des identifiants uniques " +"pour une base de données particulière seulement." + +#. Tag: term +#, no-c-format +msgid "<literal>seqhilo</literal>" +msgstr "<literal>seqhilo</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"uses a hi/lo algorithm to efficiently generate identifiers of type " +"<literal>long</literal>, <literal>short</literal> or <literal>int</literal>, " +"given a named database sequence." +msgstr "" +"utilise un algorithme hi/lo pour générer efficacement des identifiants de " +"type <literal>long</literal>, <literal>short</literal> ou <literal>int</" +"literal>, en prenant une séquence en base nommée." + +#. Tag: term +#, no-c-format +msgid "<literal>uuid</literal>" +msgstr "<literal>uuid</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"uses a 128-bit UUID algorithm to generate identifiers of type string that " +"are unique within a network (the IP address is used). The UUID is encoded as " +"a string of 32 hexadecimal digits in length." +msgstr "" +"utilise un algorithme de type UUID 128 bits pour générer des identifiants de " +"type string, unique au sein d'un réseau (l'adresse IP est utilisée). Le UUID " +"est encodé en une chaîne de nombre héxadécimaux de longueur 32. " + +#. Tag: term +#, no-c-format +msgid "<literal>guid</literal>" +msgstr "<literal>guid</literal>" + +#. Tag: para +#, no-c-format +msgid "uses a database-generated GUID string on MS SQL Server and MySQL." +msgstr "" +"utilise une chaîne GUID générée par la base pour MS SQL Server et MySQL." + +#. Tag: term +#, no-c-format +msgid "<literal>native</literal>" +msgstr "<literal>native</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"selects <literal>identity</literal>, <literal>sequence</literal> or " +"<literal>hilo</literal> depending upon the capabilities of the underlying " +"database." +msgstr "" +"choisit <literal>identity</literal>, <literal>sequence</literal> ou " +"<literal>hilo</literal> selon les possibilités offertes par la base de " +"données sous-jacente. " + +#. Tag: term +#, no-c-format +msgid "<literal>assigned</literal>" +msgstr "<literal>assigned</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"lets the application assign an identifier to the object before <literal>save" +"()</literal> is called. This is the default strategy if no <literal>&lt;" +"generator&gt;</literal> element is specified." +msgstr "" +"permet à l'application d'affecter un identifiant à l'objet avant que la " +"méthode <literal>save()</literal> soit appelée. Il s'agit de la stratégie " +"par défaut si aucun <literal>&lt;generator&gt;</literal> n'est spécifié. " + +#. Tag: term +#, no-c-format +msgid "<literal>select</literal>" +msgstr "<literal>select</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"retrieves a primary key, assigned by a database trigger, by selecting the " +"row by some unique key and retrieving the primary key value." +msgstr "" +"récupère une clé primaire assignée par un déclencheur (trigger) de base de " +"données en sélectionnant la ligne par une clé unique quelconque et en " +"extrayant la valeur de la clé primaire." + +#. Tag: term +#, no-c-format +msgid "<literal>foreign</literal>" +msgstr "<literal>foreign</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"uses the identifier of another associated object. It is usually used in " +"conjunction with a <literal>&lt;one-to-one&gt;</literal> primary key " +"association." +msgstr "" +"utilise l'identifiant d'un autre objet associé. Habituellement utilisé en " +"conjonction avec une association <literal>&lt;one-to-one&gt;</literal> sur " +"la clé primaire. " + +#. Tag: term +#, no-c-format +msgid "<literal>sequence-identity</literal>" +msgstr "<literal>sequence-identity</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"a specialized sequence generation strategy that utilizes a database sequence " +"for the actual value generation, but combines this with JDBC3 " +"getGeneratedKeys to return the generated identifier value as part of the " +"insert statement execution. This strategy is only supported on Oracle 10g " +"drivers targeted for JDK 1.4. Comments on these insert statements are " +"disabled due to a bug in the Oracle drivers." +msgstr "" +"Une stratégie de génération de séquence spécialisée qui utilise une séquence " +"de base de données pour la génération réelle de valeurs, tout en utilisant " +"JDBC3 getGeneratedKeys pour retourner effectivement la valeur d'identifiant " +"générée, comme faisant partie de l'exécution de la déclaration insert. Cette " +"stratégie est uniquement prise en charge par les pilotes Oracle 10g pour JDK " +"1.4. Notez que les commentaires sur ces déclarations insert sont désactivés " +"à cause d'un bogue dans les pilotes d'Oracle. " + +#. Tag: title +#, no-c-format +msgid "Hi/lo algorithm" +msgstr "Algorithme Hi/lo" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>hilo</literal> and <literal>seqhilo</literal> generators " +"provide two alternate implementations of the hi/lo algorithm. The first " +"implementation requires a \"special\" database table to hold the next " +"available \"hi\" value. Where supported, the second uses an Oracle-style " +"sequence." +msgstr "" +"Les générateurs <literal>hilo</literal> et <literal>seqhilo</literal> " +"proposent deux implémentations alternatives de l'algorithme hi/lo. La " +"première implémentation nécessite une table \"spéciale\" en base pour " +"héberger la prochaine valeur \"hi\" disponible. La seconde utilise une " +"séquence de type Oracle (quand la base sous-jacente le propose). " + +#. Tag: para +#, no-c-format +msgid "" +"Unfortunately, you cannot use <literal>hilo</literal> when supplying your " +"own <literal>Connection</literal> to Hibernate. When Hibernate uses an " +"application server datasource to obtain connections enlisted with JTA, you " +"must configure the <literal>hibernate.transaction.manager_lookup_class</" +"literal>." +msgstr "" +"Malheureusement, vous ne pouvez pas utiliser <literal>hilo</literal> quand " +"vous apportez votre propre <literal>Connection</literal> à Hibernate. Quand " +"Hibernate utilise une datasource du serveur d'application pour obtenir des " +"connexions inscrites avec JTA, vous devez correctement configurer " +"<literal>hibernate.transaction.manager_lookup_class</literal>. " + +#. Tag: title +#, no-c-format +msgid "UUID algorithm" +msgstr "Algorithme UUID " + +#. Tag: para +#, no-c-format +msgid "" +"The UUID contains: IP address, startup time of the JVM that is accurate to a " +"quarter second, system time and a counter value that is unique within the " +"JVM. It is not possible to obtain a MAC address or memory address from Java " +"code, so this is the best option without using JNI." +msgstr "" +"Le contenu du UUID est : l'adresse IP, la date de démarrage de la JVM " +"(précis au quart de seconde), l'heure système et une contre-valeur (unique " +"au sein de la JVM). Il n'est pas possible d'obtenir une adresse MAC ou une " +"adresse mémoire à partir de Java, c'est donc le mieux que l'on puisse faire " +"sans utiliser JNI. " + +#. Tag: title +#, no-c-format +msgid "Identity columns and sequences" +msgstr "Colonnes identifiantes et séquences" + +#. Tag: para +#, no-c-format +msgid "" +"For databases that support identity columns (DB2, MySQL, Sybase, MS SQL), " +"you can use <literal>identity</literal> key generation. For databases that " +"support sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you " +"can use <literal>sequence</literal> style key generation. Both of these " +"strategies require two SQL queries to insert a new object. For example:" +msgstr "" +"Pour les bases qui implémentent les colonnes \"identité\" (DB2, MySQL, " +"Sybase, MS SQL), vous pouvez utiliser la génération de clé par " +"<literal>identity</literal>. Pour les bases qui implémentent les séquences " +"(DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) vous pouvez utiliser la " +"génération de clé par <literal>sequence</literal>. Ces deux méthodes " +"nécessitent deux requêtes SQL pour insérer un nouvel objet. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"For cross-platform development, the <literal>native</literal> strategy will, " +"depending on the capabilities of the underlying database, choose from the " +"<literal>identity</literal>, <literal>sequence</literal> and <literal>hilo</" +"literal> strategies." +msgstr "" +"Pour le développement multi-plateformes, la stratégie <literal>native</" +"literal> choisira entre les méthodes <literal>identity</literal>, " +"<literal>sequence</literal> et <literal>hilo</literal>, selon les " +"possibilités offertes par la base sous-jacente. " + +#. Tag: title +#, no-c-format +msgid "Assigned identifiers" +msgstr "Identifiants assignés" + +#. Tag: para +#, no-c-format +msgid "" +"If you want the application to assign identifiers, as opposed to having " +"Hibernate generate them, you can use the <literal>assigned</literal> " +"generator. This special generator uses the identifier value already assigned " +"to the object's identifier property. The generator is used when the primary " +"key is a natural key instead of a surrogate key. This is the default " +"behavior if you do not specify a <literal>&lt;generator&gt;</literal> " +"element." +msgstr "" +"Si vous souhaitez que l'application assigne des identifiants (par opposition " +"à la génération par Hibernate), vous pouvez utiliser le générateur " +"<literal>assigned</literal>. Ce générateur spécial utilisera une valeur " +"d'identifiant déjà utilisée par la propriété identifiant l'objet. Ce " +"générateur est utilisé quand la clé primaire est une clé naturelle plutôt " +"qu'une clé secondaire. C'est le comportement par défaut si vous ne précisez " +"pas d'élément <literal>&lt;generator&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>assigned</literal> generator makes Hibernate use " +"<literal>unsaved-value=\"undefined\"</literal>. This forces Hibernate to go " +"to the database to determine if an instance is transient or detached, unless " +"there is a version or timestamp property, or you define <literal>Interceptor." +"isUnsaved()</literal>." +msgstr "" +"Choisir le générateur <literal>assigned</literal> fait que Hibernate " +"utilise<literal>unsaved-value=\"undefined\"</literal>, le forçant ainsi à " +"interroger la base de données pour déterminer si une instance est transiente " +"ou détachée, à moins d'utiliser une propriété version ou timestamp, ou alors " +"de définir <literal>Interceptor.isUnsaved()</literal>. " + +#. Tag: title +#, no-c-format +msgid "Primary keys assigned by triggers" +msgstr "Clés primaires assignées par les triggers" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate does not generate DDL with triggers. It is for legacy schemas only." +msgstr "" +"Pour les schémas de base hérités d'anciens systèmes uniquement (Hibernate ne " +"génère pas de DDL avec des triggers) " + +#. Tag: para +#, no-c-format +msgid "" +"In the above example, there is a unique valued property named " +"<literal>socialSecurityNumber</literal>. It is defined by the class, as a " +"natural key and a surrogate key named <literal>person_id</literal>, whose " +"value is generated by a trigger." +msgstr "" +"Dans l'exemple ci-dessus, il y a une valeur de propriété unique appelée " +"<literal>socialSecurityNumber</literal>. Elle est définie par la classe en " +"tant que clé naturelle et il y a également une clé secondaire appelée " +"<literal>person_id</literal> dont la valeur est générée par un trigger." + +#. Tag: title +#, no-c-format +msgid "Enhanced identifier generators" +msgstr "La méthode getter de l'identifiant " + +#. Tag: para +#, no-c-format +msgid "" +"Starting with release 3.2.3, there are 2 new generators which represent a re-" +"thinking of 2 different aspects of identifier generation. The first aspect " +"is database portability; the second is optimization Optimization means that " +"you do not have to query the database for every request for a new identifier " +"value. These two new generators are intended to take the place of some of " +"the named generators described above, starting in 3.3.x. However, they are " +"included in the current releases and can be referenced by FQN." +msgstr "" +"A partir de la version 3.2.3, 2 générateurs représentent une nouvelle " +"conception de 2 aspects séparés de la génération d'identifiants. Le premier " +"aspect est la portabilité de la base de données; le second est " +"l'optimization, c'est à dire que vous n'avez pas à interroger la base de " +"données pour chaque requête de valeur d'identifiant. Ces deux nouveaux " +"générateurs sont sensés prendre la place de générateurs décrits ci-dessus, " +"ayant pour préfixe 3.3.x. Cependant, ils sont inclus dans les versions " +"actuelles, et peuvent être référencés par FQN." + +#. Tag: para +#, no-c-format +msgid "" +"The first of these new generators is <literal>org.hibernate.id.enhanced." +"SequenceStyleGenerator</literal> which is intended, firstly, as a " +"replacement for the <literal>sequence</literal> generator and, secondly, as " +"a better portability generator than <literal>native</literal>. This is " +"because <literal>native</literal> generally chooses between " +"<literal>identity</literal> and <literal>sequence</literal> which have " +"largely different semantics that can cause subtle issues in applications " +"eyeing portability. <literal>org.hibernate.id.enhanced." +"SequenceStyleGenerator</literal>, however, achieves portability in a " +"different manner. It chooses between a table or a sequence in the database " +"to store its incrementing values, depending on the capabilities of the " +"dialect being used. The difference between this and <literal>native</" +"literal> is that table-based and sequence-based storage have the same exact " +"semantic. In fact, sequences are exactly what Hibernate tries to emulate " +"with its table-based generators. This generator has a number of " +"configuration parameters:" +msgstr "" +"Le premier de ces nouveaux générateurs est <literal>org.Hibernate.ID." +"Enhanced.SequenceStyleGenerator</literal> qui est destiné, tout d'abord, " +"comme un remplacement pour le générateur <literal>séquence</literal> et, " +"deuxièmement, comme un générateur de portabilité supérieur à <literal>natif</" +"literal>. C'est parce que <literal>natif</literal> a généralement le choix " +"entre <literal>identité</literal> et <literal>séquence</literal> qui ont des " +"sémantiques largement différentes, ce qui peut entraîner des problèmes " +"subtils en observant la portabilité des applications. <literal>org.Hibernate." +"ID.Enhanced SequenceStyleGenerator.</literal>, cependant, réalise la " +"portabilité d'une manière différente. Il choisit entre une table ou une " +"séquence dans la base de données pour stocker ses valeurs s'incrémentant, " +"selon les capacités du dialecte utilisé. La différence avec <literal>natif</" +"literal> c'est que de stockage basé sur les tables ou basé sur la séquence " +"ont la même sémantique. En fait, les séquences sont exactement ce " +"qu'Hibernate essaie d'émuler avec ses générateurs basée sur les tables. Ce " +"générateur a un certain nombre de paramètres de configuration :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>sequence_name</literal> (optional, defaults to " +"<literal>hibernate_sequence</literal>): the name of the sequence or table to " +"be used." +msgstr "" +"<literal>sequence_name</literal> (en option, par défaut = " +"<literal>hibernate_sequence</literal>): le nom de la séquence ou table à " +"utiliser." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>initial_value</literal> (optional, defaults to <literal>1</" +"literal>): the initial value to be retrieved from the sequence/table. In " +"sequence creation terms, this is analogous to the clause typically named " +"\"STARTS WITH\"." +msgstr "" +"<literal>initial_value</literal> (en option - par défaut = <literal>1</" +"literal>) : la première valeur à extraire de la séquence/table. En termes de " +"création de séquences, c'est semblable à la clause qui s'appelle \"STARTS " +"WITH\" normalement." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>increment_size</literal> (optional - defaults to <literal>1</" +"literal>): the value by which subsequent calls to the sequence/table should " +"differ. In sequence creation terms, this is analogous to the clause " +"typically named \"INCREMENT BY\"." +msgstr "" +"<literal>increment_size</literal> (en option - par défaut = <literal>1</" +"literal>): la valeur par laquelle les appels suivants à la séquence / table " +"doivent différer. En termes de création de séquence, c'est analogue à la " +"clause généralement nommé \"INCREMENT BY\"." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>force_table_use</literal> (optional - defaults to <literal>false</" +"literal>): should we force the use of a table as the backing structure even " +"though the dialect might support sequence?" +msgstr "" +"<literal>force_table_use</literal> (optionnel - par défaut = <literal>false</" +"literal>) : doit-on forcer l'utilisation de la table en tant que structure " +"de soutien même si le dialecte peut supporter la séquence ?" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>value_column</literal> (optional - defaults to <literal>next_val</" +"literal>): only relevant for table structures, it is the name of the column " +"on the table which is used to hold the value." +msgstr "" +"<literal>value_column</literal> (en option - par défaut = <literal>next_val</" +"literal>): uniquement utile pour les structures de tables. Correspond au nom " +"de la colonne de la table qui est utilisée pour contenir la valeur." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimizer</literal> (optional - defaults to <literal>none</" +"literal>): See <xref linkend=\"mapping-declaration-id-enhanced-optimizers\" /" +">" +msgstr "" +"<literal>optimizer</literal> (en option - valeur par défaut = <literal>none</" +"literal>): Voir <xref linkend=\"mapping-declaration-id-enhanced-optimizers" +"\" />" + +#. Tag: para +#, no-c-format +msgid "" +"The second of these new generators is <literal>org.hibernate.id.enhanced." +"TableGenerator</literal>, which is intended, firstly, as a replacement for " +"the <literal>table</literal> generator, even though it actually functions " +"much more like <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</" +"literal>, and secondly, as a re-implementation of <literal>org.hibernate.id." +"MultipleHiLoPerTableGenerator</literal> that utilizes the notion of " +"pluggable optimizers. Essentially this generator defines a table capable of " +"holding a number of different increment values simultaneously by using " +"multiple distinctly keyed rows. This generator has a number of configuration " +"parameters:" +msgstr "" +"Le deuxième de ces nouveaux générateurs est <literal>org.Hibernate.ID." +"Enhanced.TableGenerator</literal>, qui est destiné, tout d'abord, comme un " +"remplacement pour le générateur de la <literal>table</literal>, même si elle " +"fonctionne effectivement beaucoup plus comme <literal>org.Hibernate.ID." +"MultipleHiLoPerTableGenerator</literal>et deuxièmement, comme une remise en " +"œuvre de <literal>org.Hibernate.ID.MultipleHiLoPerTableGenerator</literal>, " +"qui utilise la notion d'optimizers enfichables. Essentiellement ce " +"générateur définit une table susceptible de contenir un certain nombre de " +"valeurs d'incrément différents simultanément à l'aide de plusieurs lignes " +"distinctement masquées. Ce générateur a un certain nombre de paramètres de " +"configuration :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>table_name</literal> (optional - defaults to " +"<literal>hibernate_sequences</literal>): the name of the table to be used." +msgstr "" +"<literal>table_name</literal> (en optin - valeur par défaut = " +"<literal>hibernate_sequences</literal>): le nom de la table à utiliser." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>value_column_name</literal> (optional - defaults to " +"<literal>next_val</literal>): the name of the column on the table that is " +"used to hold the value." +msgstr "" +"<literal>value_column_name</literal> (en option - valeur par défaut " +"=<literal>next_val</literal>): le nom de la colonne contenue dans la table " +"utilisée pour la valeur." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>segment_column_name</literal> (optional - defaults to " +"<literal>sequence_name</literal>): the name of the column on the table that " +"is used to hold the \"segment key\". This is the value which identifies " +"which increment value to use." +msgstr "" +"<literal>segment_column_name</literal> (en option - par défaut = " +"<literal>sequence_name</literal>): le nom de la colonne de la table qui est " +"utilisée pour contenir la \"segment key\". Il s'agit de la valeur qui " +"identifie la valeur d'incrément à utiliser." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>segment_value</literal> (optional - defaults to <literal>default</" +"literal>): The \"segment key\" value for the segment from which we want to " +"pull increment values for this generator." +msgstr "" +"<literal>segment_value</literal> (en option - par défaut = <literal>par " +"défaut</literal>): La \"segment key\"valeur pour le segment à partir de " +"laquelle nous voulons extraire des valeurs d'incrémentation pour ce " +"générateur." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>segment_value_length</literal> (optional - defaults to " +"<literal>255</literal>): Used for schema generation; the column size to " +"create this segment key column." +msgstr "" +"<literal>segment_value_length</literal> (en option - par défaut = " +"<literal>255</literal>): Utilisée pour la génération de schéma ; la taille " +"de la colonne pour créer cette colonne de clé de segment." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>initial_value</literal> (optional - defaults to <literal>1</" +"literal>): The initial value to be retrieved from the table." +msgstr "" +"<literal>initial_value</literal> (en option - par défaut est <literal>1</" +"literal> : La valeur initiale à récupérer à partir de la table." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>increment_size</literal> (optional - defaults to <literal>1</" +"literal>): The value by which subsequent calls to the table should differ." +msgstr "" +"<literal>increment_size</literal> (en option - par défaut = <literal>1</" +"literal>): La valeur par laquelle les appels à la table, qui suivent, " +"devront différer." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimizer</literal> (optional - defaults to <literal></literal>): " +"See <xref linkend=\"mapping-declaration-id-enhanced-optimizers\" />" +msgstr "" +"<literal>optimizer</literal> (en option - valeur par défaut = <literal></" +"literal>): Voir <xref linkend=\"mapping-declaration-id-enhanced-optimizers" +"\" />" + +#. Tag: title +#, no-c-format +msgid "Identifier generator optimization" +msgstr "Optimisation du générateur d'identifiants" + +#. Tag: para +#, no-c-format +msgid "" +"For identifier generators that store values in the database, it is " +"inefficient for them to hit the database on each and every call to generate " +"a new identifier value. Instead, you can group a bunch of them in memory and " +"only hit the database when you have exhausted your in-memory value group. " +"This is the role of the pluggable optimizers. Currently only the two " +"enhanced generators (<xref linkend=\"mapping-declaration-id-enhanced\" /> " +"support this operation." +msgstr "" +"Pour les générateurs d'identifiants qui stockent des valeurs dans la base de " +"données, il est inefficace d'interroger la base de données sur chaque appel " +"en vue de générer une nouvelle valeur d'identifiant. Au lieu de cela, vous " +"pouvez les regrouper dans un ensemble dans la mémoire et interroger la base " +"de données que lorsque vous aurez épuisé votre groupe de valeur en mémoire. " +"C'est le rôle des optimizers enfichables. Actuellement seulement les deux " +"générateurs améliorés (<xref linkend=\"mapping-declaration-id-enhanced\" /> " +"prennent en charge cette opération." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>none</literal> (generally this is the default if no optimizer was " +"specified): this will not perform any optimizations and hit the database for " +"each and every request." +msgstr "" +"<literal>aucun</literal> (en général il s'agit de la valeur par défaut si " +"aucun optimizer n'a été spécifié): n'effectuera pas d'optimisations et " +"n'interrogera pas la base de données à chaque demande." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>hilo</literal>: applies a hi/lo algorithm around the database " +"retrieved values. The values from the database for this optimizer are " +"expected to be sequential. The values retrieved from the database structure " +"for this optimizer indicates the \"group number\". The " +"<literal>increment_size</literal> is multiplied by that value in memory to " +"define a group \"hi value\"." +msgstr "" +"<literal>hilo</literal>: applique un algorithme hi/lo autour des valeurs " +"extraites des base de données. Les valeurs de la base de données de cet " +"optimizer sont censées être séquentielles. Les valeurs extraites de la " +"structure des base de données pour cet optimizer indique le \"numéro de " +"groupe\". Le <literal>increment_size</literal> est multiplié par cette " +"valeur en mémoire pour définir un groupe de \"hi value\"." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>pooled</literal>: as with the case of <literal>hilo</literal>, this " +"optimizer attempts to minimize the number of hits to the database. Here, " +"however, we simply store the starting value for the \"next group\" into the " +"database structure rather than a sequential value in combination with an in-" +"memory grouping algorithm. Here, <literal>increment_size</literal> refers to " +"the values coming from the database." +msgstr "" +"<literal>mise en commun</literal>: tout comme dans le cas de <literal>hilo</" +"literal>, cet optimizer tente de réduire le nombre d'interrogations vers la " +"base de données. Ici, cependant, nous avons simplement stocké la valeur de " +"départ pour le \"prochain groupe\"dans la structure de la base de données " +"plutôt qu'une valeur séquentielle en combinaison avec un algorithme de " +"regroupement en mémoire. Ici, <literal>increment_size</literal> fait " +"référence aux valeurs provenant de la base de données." + +#. Tag: title +#, no-c-format +msgid "composite-id" +msgstr "composite-id" + +#. Tag: para +#, no-c-format +msgid "" +"A table with a composite key can be mapped with multiple properties of the " +"class as identifier properties. The <literal>&lt;composite-id&gt;</literal> " +"element accepts <literal>&lt;key-property&gt;</literal> property mappings " +"and <literal>&lt;key-many-to-one&gt;</literal> mappings as child elements." +msgstr "" +"Pour une table avec clé composée, vous pouvez mapper plusieurs attributs de " +"la classe comme propriétés identifiantes. L'élément <literal>&lt;composite-" +"id&gt;</literal> accepte les mappages de propriétés <literal>&lt;key-" +"property&gt;</literal> et les mappages <literal>&lt;key-many-to-one&gt;</" +"literal> comme éléments enfants. " + +#. Tag: para +#, no-c-format +msgid "" +"The persistent class <emphasis>must</emphasis> override <literal>equals()</" +"literal> and <literal>hashCode()</literal> to implement composite identifier " +"equality. It must also implement <literal>Serializable</literal>." +msgstr "" +"Vos classes persistantes <emphasis>doivent</emphasis> surcharger les " +"méthodes <literal>equals()</literal> et <literal>hashCode()</literal> pour " +"implémenter l'égalité d'identifiant composite. Elles doivent aussi " +"implémenter l'interface <literal>Serializable</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Unfortunately, this approach means that a persistent object is its own " +"identifier. There is no convenient \"handle\" other than the object itself. " +"You must instantiate an instance of the persistent class itself and populate " +"its identifier properties before you can <literal>load()</literal> the " +"persistent state associated with a composite key. We call this approach an " +"<emphasis>embedded</emphasis> composite identifier, and discourage it for " +"serious applications." +msgstr "" +"Malheureusement, cette approche signifie qu'un objet persistant est son " +"propre identifiant. Il n'y a pas d'autre moyen pratique de \"manipuler\" " +"l'objet que par l'objet lui-même. Vous devez instancier une instance de la " +"classe persistante elle-même et peupler ses attributs identifiants avant de " +"pouvoir appeler la méthode <literal>load()</literal> pour charger son état " +"persistant associé à une clé composée. Nous appelons cette approche " +"\"identifiant composé <emphasis>embarqué</emphasis>\" et ne la recommandons " +"pas pour des applications complexes." + +#. Tag: para +#, no-c-format +msgid "" +"A second approach is what we call a <emphasis>mapped</emphasis> composite " +"identifier, where the identifier properties named inside the <literal>&lt;" +"composite-id&gt;</literal> element are duplicated on both the persistent " +"class and a separate identifier class." +msgstr "" +"Une seconde approche, appelée identifiant composé <emphasis>mappé</" +"emphasis>, consiste à dupliquer les propriétés identifiantes nommées dans " +"l'élément <literal>&lt;composite-id&gt;</literal>) à la fois dans la classe " +"persistante et dans une classe identifiante particulière." + +#. Tag: para +#, no-c-format +msgid "" +"In this example, both the composite identifier class, <literal>MedicareId</" +"literal>, and the entity class itself have properties named " +"<literal>medicareNumber</literal> and <literal>dependent</literal>. The " +"identifier class must override <literal>equals()</literal> and " +"<literal>hashCode()</literal> and implement <literal>Serializable</literal>. " +"The main disadvantage of this approach is code duplication." +msgstr "" +"Dans cet exemple, la classe d'identifiant composée,<literal>MedicareId</" +"literal> et la classe mappée elle-même, possèdent les propriétés " +"<literal>medicareNumber</literal> et <literal>dependent</literal>. La classe " +"identifiante doit redéfinir <literal>equals()</literal> et <literal>hashCode" +"()</literal> et implémenter <literal>Serializable</literal>. Le désavantage " +"de cette approche est la duplication du code. " + +#. Tag: para +#, no-c-format +msgid "" +"The following attributes are used to specify a mapped composite identifier:" +msgstr "" +"Les attributs suivants servent à configurer un identifiant composé mappé :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>mapped</literal> (optional - defaults to <literal>false</literal>): " +"indicates that a mapped composite identifier is used, and that the contained " +"property mappings refer to both the entity class and the composite " +"identifier class." +msgstr "" +"<literal>mapped</literal> (optionnel, défaut à <literal>false</literal>) : " +"indique qu'un identifiant composé mappé est utilisé, et que les mappages de " +"propriétés contenues font référence aux deux classes, la classe mappée et la " +"classe identifiante composée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal> (optional - but required for a mapped composite " +"identifier): the class used as a composite identifier." +msgstr "" +"<literal>class</literal> (optionnel, mais requis pour un identifiant composé " +"mappé) : la classe utilisée comme identifiant composé. " + +#. Tag: para +#, no-c-format +msgid "" +"We will describe a third, even more convenient approach, where the composite " +"identifier is implemented as a component class in <xref linkend=\"components-" +"compositeid\" />. The attributes described below apply only to this " +"alternative approach:" +msgstr "" +"Nous décrirons une troisième approche beaucoup plus efficace pour laquelle " +"l'identifiant composé est implémenté comme une classe composant dans <xref " +"linkend=\"components-compositeid\" />. Les attributs décrits ci dessous, ne " +"s'appliquent que pour cette dernière approche :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal> (optional - required for this approach): a property " +"of component type that holds the composite identifier. Please see chapter 9 " +"for more information." +msgstr "" +"<literal>name</literal> (optionnel, requis pour cette approche) : une " +"propriété de type composant qui contient l'identifiant composé (voir " +"chapitre 9). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>access</literal> (optional - defaults to <literal>property</" +"literal>): the strategy Hibernate uses for accessing the property value." +msgstr "" +"<literal>access</literal> (optionnel - par défaut <literal>property</" +"literal>) : la stratégie que doit utiliser Hibernate pour accéder aux " +"valeurs des propriétés. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal> (optional - defaults to the property type " +"determined by reflection): the component class used as a composite " +"identifier. Please see the next section for more information." +msgstr "" +"<literal>class</literal> (optionnel - par défaut le type de la propriété " +"déterminé par réflexion) : la classe composant utilisée comme identifiant " +"(voir prochaine section). " + +#. Tag: para +#, no-c-format +msgid "" +"The third approach, an <emphasis>identifier component</emphasis>, is " +"recommended for almost all applications." +msgstr "" +"La troisième approche, un <emphasis>composant d'identifiant</emphasis>, est " +"celle que nous recommandons pour toutes vos applications." + +#. Tag: title +#, no-c-format +msgid "Discriminator" +msgstr "Discriminator" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;discriminator&gt;</literal> element is required for " +"polymorphic persistence using the table-per-class-hierarchy mapping " +"strategy. It declares a discriminator column of the table. The discriminator " +"column contains marker values that tell the persistence layer what subclass " +"to instantiate for a particular row. A restricted set of types can be used: " +"<literal>string</literal>, <literal>character</literal>, <literal>integer</" +"literal>, <literal>byte</literal>, <literal>short</literal>, " +"<literal>boolean</literal>, <literal>yes_no</literal>, <literal>true_false</" +"literal>." +msgstr "" +"L'élément <literal>&lt;discriminator&gt;</literal> est nécessaire pour la " +"persistance polymorphique qui utilise la stratégie de mappage de table par " +"hiérarchie de classe et déclare une colonne discriminante de la table. La " +"colonne discriminante contient des valeurs marqueur qui permettent à la " +"couche de persistance de savoir quelle sous-classe instancier pour une ligne " +"particulière de table en base. Un nombre restreint de types peuvent être " +"utilisés : <literal>string</literal>, <literal>character</literal>, " +"<literal>integer</literal>, <literal>byte</literal>, <literal>short</" +"literal>, <literal>boolean</literal>, <literal>yes_no</literal>, " +"<literal>true_false</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional - defaults to <literal>class</literal>): " +"the name of the discriminator column." +msgstr "" +"<literal>column</literal> (optionnel - par défaut à <literal>class</" +"literal>), le nom de la colonne discriminante. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>type</literal> (optional - defaults to <literal>string</literal>): " +"a name that indicates the Hibernate type" +msgstr "" +"<literal>type</literal> (optionnel - par défaut à <literal>string</literal>) " +"un nom indiquant le type Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>force</literal> (optional - defaults to <literal>false</literal>): " +"\"forces\" Hibernate to specify the allowed discriminator values, even when " +"retrieving all instances of the root class." +msgstr "" +"<literal>force</literal> (optionnel - par défaut à <literal>false</literal>) " +"\"oblige\" Hibernate à spécifier une valeur discriminante autorisée même " +"quand on récupère toutes les instances de la classe de base. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>insert</literal> (optional - defaults to <literal>true</literal>): " +"set this to <literal>false</literal> if your discriminator column is also " +"part of a mapped composite identifier. It tells Hibernate not to include the " +"column in SQL <literal>INSERTs</literal>." +msgstr "" +"<literal>insert</literal> (optionnel - par défaut à <literal>true</literal>) " +"à passer à <literal>false</literal> si la colonne discriminante fait aussi " +"partie d'un identifiant composé mappé (Indique à Hibernate de ne pas inclure " +"la colonne dans les SQL <literal>INSERT</literal> s). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): an arbitrary SQL expression that is " +"executed when a type has to be evaluated. It allows content-based " +"discrimination." +msgstr "" +"<literal>formula</literal> (optionnel) une expression SQL arbitraire qui est " +"exécutée quand un type doit être évalué. Permet la discrimination basée sur " +"le contenu. " + +#. Tag: para +#, no-c-format +msgid "" +"Actual values of the discriminator column are specified by the " +"<literal>discriminator-value</literal> attribute of the <literal>&lt;" +"class&gt;</literal> and <literal>&lt;subclass&gt;</literal> elements." +msgstr "" +"Les véritables valeurs de la colonne discriminante sont spécifiées par " +"l'attribut <literal>discriminator-value</literal> des éléments <literal>&lt;" +"class&gt;</literal> et <literal>&lt;subclass&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>force</literal> attribute is only useful if the table contains " +"rows with \"extra\" discriminator values that are not mapped to a persistent " +"class. This will not usually be the case." +msgstr "" +"L'attribut <literal>force</literal> n'est utile que si la table contient des " +"lignes avec des valeurs \"extra\" discriminantes qui ne sont pas mappées à " +"une classe persistante. Ce ne sera généralement pas le cas. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>formula</literal> attribute allows you to declare an arbitrary " +"SQL expression that will be used to evaluate the type of a row. For example:" +msgstr "" +"En utilisant l'attribut <literal>formula</literal> vous pouvez déclarer une " +"expression SQL arbitraire qui sera utilisée pour évaluer le type d'une " +"ligne : " + +#. Tag: title +#, no-c-format +msgid "Version (optional)" +msgstr "Version (optionnel)" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;version&gt;</literal> element is optional and indicates " +"that the table contains versioned data. This is particularly useful if you " +"plan to use <emphasis>long transactions</emphasis>. See below for more " +"information:" +msgstr "" +"L'élément <literal>&lt;version&gt;</literal> est optionnel et indique que la " +"table contient des données versionnées. C'est particulièrement utile si vous " +"avez l'intention d'utiliser des <emphasis>transactions longues</emphasis> " +"(voir plus-bas)." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional - defaults to the property name): the " +"name of the column holding the version number." +msgstr "" +"<literal>column</literal> (optionnel - par défaut égal au nom de la " +"propriété) : le nom de la colonne contenant le numéro de version. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal>: the name of a property of the persistent class." +msgstr "" +"<literal>name</literal> : le nom d'un attribut de la classe persistante. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>type</literal> (optional - defaults to <literal>integer</literal>): " +"the type of the version number." +msgstr "" +"<literal>type</literal> (optionnel - par défaut à <literal>integer</" +"literal>) : le type du numéro de version. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>access</literal> (optional - defaults to <literal>property</" +"literal>): the strategy Hibernate uses to access the property value." +msgstr "" +"<literal>access</literal> (optionnel - par défaut <literal>property</" +"literal>) : la stratégie que doit utiliser Hibernate pour accéder aux " +"valeurs des propriétés. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unsaved-value</literal> (optional - defaults to <literal>undefined</" +"literal>): a version property value that indicates that an instance is newly " +"instantiated (unsaved), distinguishing it from detached instances that were " +"saved or loaded in a previous session. <literal>Undefined</literal> " +"specifies that the identifier property value should be used." +msgstr "" +"<literal>unsaved-value</literal> (optionnel - par défaut à " +"<literal>undefined</literal>) : une valeur de la propriété d'identifiant qui " +"indique que l'instance est nouvellement instanciée (non sauvegardée), et qui " +"la distingue des instances détachées qui ont été sauvegardées ou chargées " +"dans une session précédente. <literal>Undefined</literal> indique que la " +"valeur de la propritété identifiant devrait être utilisée." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<literal>generated</literal> (optional - defaults to <literal>never</" +"literal>): specifies that this version property value is generated by the " +"database. See the discussion of <link linkend=\"mapping-generated" +"\">generated properties</link> for more information." +msgstr "" +"<literal>generated</literal> (optionnel - défaut à <literal>never</" +"literal>) : spécifie que cette valeur de la propriété version est en réalité " +"générée par la base de données. Consultez la discussion <xref linkend=" +"\"mapping-generated\"/> pour obtenir des informations supplémentaires." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>insert</literal> (optional - defaults to <literal>true</literal>): " +"specifies whether the version column should be included in SQL insert " +"statements. It can be set to <literal>false</literal> if the database column " +"is defined with a default value of <literal>0</literal>." +msgstr "" +"<literal>insert</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique si la colonne de version doit être incluse dans les " +"ordres SQL insert. Peut être configuré à <literal>false</literal> si et " +"seulement si la colonne de la base de données est définie avec une valeur " +"par défaut égale à <literal>0</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Version numbers can be of Hibernate type <literal>long</literal>, " +"<literal>integer</literal>, <literal>short</literal>, <literal>timestamp</" +"literal> or <literal>calendar</literal>." +msgstr "" +"Les numéros de version doivent avoir les types Hibernate <literal>long</" +"literal>, <literal>integer</literal>, <literal>short</literal>, " +"<literal>timestamp</literal> ou <literal>calendar</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"A version or timestamp property should never be null for a detached " +"instance. Hibernate will detect any instance with a null version or " +"timestamp as transient, irrespective of what other <literal>unsaved-value</" +"literal> strategies are specified. <emphasis>Declaring a nullable version or " +"timestamp property is an easy way to avoid problems with transitive " +"reattachment in Hibernate. It is especially useful for people using assigned " +"identifiers or composite keys</emphasis>." +msgstr "" +"Une propriété de version ou un timestamp ne doit jamais être null pour une " +"instance détachée, ainsi Hibernate pourra détecter toute instance ayant une " +"version ou un timestamp null comme transient, quelles que soient les " +"stratégies <literal>unsaved-value</literal> spécifiées. <emphasis>Déclarer " +"un numéro de version ou un timestamp \"nullable\" est un moyen pratique " +"d'éviter tout problème avec les ré-attachements transitifs dans Hibernate, " +"particulièrement utile pour ceux qui utilisent des identifiants assignés ou " +"des clés composées </emphasis>." + +#. Tag: title +#, no-c-format +msgid "Timestamp (optional)" +msgstr "Timestamp (optionnel) " + +#. Tag: para +#, no-c-format +msgid "" +"The optional <literal>&lt;timestamp&gt;</literal> element indicates that the " +"table contains timestamped data. This provides an alternative to versioning. " +"Timestamps are a less safe implementation of optimistic locking. However, " +"sometimes the application might use the timestamps in other ways." +msgstr "" +"L'élément optionnel <literal>&lt;timestamp&gt;</literal> indique que la " +"table contient des données horodatées (timestamped). Cela sert d'alternative " +"à l'utilisation de numéros de version. Les timestamps (ou horodatage) sont " +"par nature une implémentation moins fiable pour le verrouillage optimiste. " +"Cependant, l'application peut parfois utiliser l'horodatage à d'autres fins. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional - defaults to the property name): the " +"name of a column holding the timestamp." +msgstr "" +"<literal>column</literal> (optionnel - par défaut devient le nom de la " +"propriété) : le nom d'une colonne contenant le timestamp. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal>: the name of a JavaBeans style property of Java type " +"<literal>Date</literal> or <literal>Timestamp</literal> of the persistent " +"class." +msgstr "" +"<literal>name</literal> : le nom d'une propriété au sens JavaBean de type " +"Java <literal>Date</literal> ou <literal>Timestamp</literal> de la classe " +"persistante. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unsaved-value</literal> (optional - defaults to <literal>null</" +"literal>): a version property value that indicates that an instance is newly " +"instantiated (unsaved), distinguishing it from detached instances that were " +"saved or loaded in a previous session. <literal>Undefined</literal> " +"specifies that the identifier property value should be used." +msgstr "" +"<literal>unsaved-value</literal> (optionnel - par défaut à <literal>null</" +"literal>) : propriété dont la valeur est un numéro de version qui indique " +"que l'instance est nouvellement instanciée (non sauvegardée), et qui la " +"distingue des instances détachées qui ont été sauvegardées ou chargées dans " +"une session précédente. (<literal>undefined</literal> indique que la valeur " +"de propriété identifiant devrait être utilisée). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>source</literal> (optional - defaults to <literal>vm</literal>): " +"Where should Hibernate retrieve the timestamp value from? From the database, " +"or from the current JVM? Database-based timestamps incur an overhead because " +"Hibernate must hit the database in order to determine the \"next value\". It " +"is safer to use in clustered environments. Not all <literal>Dialects</" +"literal> are known to support the retrieval of the database's current " +"timestamp. Others may also be unsafe for usage in locking due to lack of " +"precision (Oracle 8, for example)." +msgstr "" +"<literal>source</literal> (optionnel - par défaut à <literal>vm</literal>) : " +"d'où Hibernate doit-il récupérer la valeur du timestamp? Depuis la base de " +"données ou depuis la JVM d'exécution? Les valeurs de timestamp de la base de " +"données provoquent une surcharge puisque Hibernate doit interroger la base " +"pour déterminer la prochaine valeur mais cela est plus sûr lorsque vous " +"fonctionnez dans un cluster. Remarquez aussi que certains des " +"<literal>Dialect</literal> s ne supportent pas cette fonction, et que " +"d'autres l'implémentent mal, à cause d'un manque de précision (Oracle 8 par " +"exemple)." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<literal>generated</literal> (optional - defaults to <literal>never</" +"literal>): specifies that this timestamp property value is actually " +"generated by the database. See the discussion of <link linkend=\"mapping-" +"generated\">generated properties</link> for more information." +msgstr "" +"<literal>generated</literal> (optionnel - par défaut à <literal>never</" +"literal>) : indique que la valeur de ce timestamp est générée par la base de " +"données des propriétés générées. Voir la discussion sur <xref linkend=" +"\"mapping-generated\"/> pour obtenir des informations supplémentaires. " + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Note" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>&lt;Timestamp&gt;</literal> is equivalent to <literal>&lt;version " +"type=\"timestamp\"&gt;</literal>. And <literal>&lt;timestamp source=\"db" +"\"&gt;</literal> is equivalent to <literal>&lt;version type=\"dbtimestamp" +"\"&gt;</literal>" +msgstr "" +"Notez que <literal>&lt;timestamp&gt;</literal> est équivalent à <literal>&lt;" +"version type=\"timestamp\"&gt;</literal> et <literal>&lt;timestamp source=" +"\"db\"&gt;</literal> équivaut à <literal>&lt;version type=\"dbtimestamp\"&gt;" +"</literal>" + +#. Tag: title +#, no-c-format +msgid "Property" +msgstr "Property" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;property&gt;</literal> element declares a persistent " +"JavaBean style property of the class." +msgstr "" +"L'élément <literal>&lt;property&gt;</literal> déclare une propriété " +"persistante de la classe au sens JavaBean." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal>: the name of the property, with an initial lowercase " +"letter." +msgstr "" +"<literal>name</literal> : nom de la propriété, avec une lettre initiale en " +"minuscule. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional - defaults to the property name): the " +"name of the mapped database table column. This can also be specified by " +"nested <literal>&lt;column&gt;</literal> element(s)." +msgstr "" +"<literal>column</literal> (optionnel - par défaut au nom de la propriété) : " +"le nom de la colonne mappée. Cela peut aussi être indiqué dans le(s) sous-" +"élément(s) <literal>&lt;column&gt;</literal> imbriqués. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>update, insert</literal> (optional - defaults to <literal>true</" +"literal>): specifies that the mapped columns should be included in SQL " +"<literal>UPDATE</literal> and/or <literal>INSERT</literal> statements. " +"Setting both to <literal>false</literal> allows a pure \"derived\" property " +"whose value is initialized from some other property that maps to the same " +"column(s), or by a trigger or other application." +msgstr "" +"<literal>update, insert</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique que les colonnes mappées devraient être incluses dans " +"des déclarations SQL <literal>UPDATE</literal> et/ou des <literal>INSERT</" +"literal>. Mettre les deux à <literal>false</literal> autorise une propriété " +"pure dérivée dont la valeur est initialisée de quelque autre propriété qui " +"mappe à la même colonne(s) ou par un trigger ou une autre application. " +"(utile si vous savez qu'un trigger affectera la valeur à la colonne). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): an SQL expression that defines the " +"value for a <emphasis>computed</emphasis> property. Computed properties do " +"not have a column mapping of their own." +msgstr "" +"<literal>formula</literal> (optionnel) : une expression SQL qui définit la " +"valeur pour une propriété <emphasis>calculée</emphasis>. Les propriétés " +"calculées ne possèdent pas leur propre mappage." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>false</literal>): " +"specifies that this property should be fetched lazily when the instance " +"variable is first accessed. It requires build-time bytecode instrumentation." +msgstr "" +"<literal>lazy</literal> (optionnel - par défaut à <literal>false</" +"literal>) : indique que cette propriété devrait être chargée en différé " +"(lazy loading) quand on accède à la variable d'instance pour la première " +"fois (nécessite une instrumentation du bytecode lors de la phase de " +"construction). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unique</literal> (optional): enables the DDL generation of a unique " +"constraint for the columns. Also, allow this to be the target of a " +"<literal>property-ref</literal>." +msgstr "" +"<literal>unique</literal> (optionnel) : génère le DDL d'une contrainte " +"d'unicité pour les colonnes. Permet aussi d'en faire la cible d'une " +"<literal>property-ref</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-null</literal> (optional): enables the DDL generation of a " +"nullability constraint for the columns." +msgstr "" +"<literal>not-null</literal> (optionnel) : génère le DDL d'une contrainte de " +"nullité pour les colonnes." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>true</" +"literal>): specifies that updates to this property do or do not require " +"acquisition of the optimistic lock. In other words, it determines if a " +"version increment should occur when this property is dirty." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique si les mise à jour de cette propriété nécessitent ou non " +"l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine s'il " +"est nécessaire d'incrémenter un numéro de version quand cette propriété est " +"marquée obsolète (dirty)." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<literal>generated</literal> (optional - defaults to <literal>never</" +"literal>): specifies that this property value is actually generated by the " +"database. See the discussion of <link linkend=\"mapping-generated" +"\">generated properties</link> for more information." +msgstr "" +"<literal>generated</literal> (optionnel - par défaut à <literal>never</" +"literal>) : indique que la valeur de ce timestamp est générée par la base de " +"données des propriétés générées. Voir la discussion sur <xref linkend=" +"\"mapping-generated\"/> pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "<emphasis>typename</emphasis> could be:" +msgstr "<emphasis>typename</emphasis> peut être :" + +#. Tag: para +#, no-c-format +msgid "" +"The name of a Hibernate basic type: <literal>integer, string, character, " +"date, timestamp, float, binary, serializable, object, blob</literal> etc." +msgstr "" +"Le nom d'un type basique Hibernate (par ex : <literal>integer, string, " +"character, date, timestamp, float, binary, serializable, object, blob</" +"literal> etc.). " + +#. Tag: para +#, no-c-format +msgid "" +"The name of a Java class with a default basic type: <literal>int, float, " +"char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob</" +"literal> etc." +msgstr "" +"le nom d'une classe Java avec un type basique par défaut (par ex : " +"<literal>int, float, char, java.lang.String, java.util.Date, java.lang." +"Integer, java.sql.Clob</literal> etc.). " + +#. Tag: para +#, no-c-format +msgid "The name of a serializable Java class." +msgstr "Le nom d'une classe Java sérialisable." + +#. Tag: para +#, no-c-format +msgid "" +"The class name of a custom type: <literal>com.illflow.type.MyCustomType</" +"literal> etc." +msgstr "" +"Le nom d'une classe avec un type personnalisé (par ex : <literal>com.illflow." +"type.MyCustomType</literal>)." + +#. Tag: para +#, no-c-format +msgid "" +"If you do not specify a type, Hibernate will use reflection upon the named " +"property and guess the correct Hibernate type. Hibernate will attempt to " +"interpret the name of the return class of the property getter using, in " +"order, rules 2, 3, and 4. In certain cases you will need the <literal>type</" +"literal> attribute. For example, to distinguish between <literal>Hibernate." +"DATE</literal> and <literal>Hibernate.TIMESTAMP</literal>, or to specify a " +"custom type." +msgstr "" +"Si vous n'indiquez pas un type, Hibernate utilisera la réflexion sur le nom " +"de la propriété pour tenter de trouver le type Hibernate correct. Hibernate " +"essayera d'interprêter le nom de la classe retournée par le getter de la " +"propriété en utilisant les règles 2, 3, 4 dans cet ordre. Dans certains cas " +"vous aurez encore besoin de l'attribut <literal>type</literal>. (Par " +"exemple, pour distinguer <literal>Hibernate.DATE</literal> et " +"<literal>Hibernate.TIMESTAMP</literal>, ou pour préciser un type " +"personnalisé)." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>access</literal> attribute allows you to control how Hibernate " +"accesses the property at runtime. By default, Hibernate will call the " +"property get/set pair. If you specify <literal>access=\"field\"</literal>, " +"Hibernate will bypass the get/set pair and access the field directly using " +"reflection. You can specify your own strategy for property access by naming " +"a class that implements the interface <literal>org.hibernate.property." +"PropertyAccessor</literal>." +msgstr "" +"L'attribut <literal>access</literal> permet de contrôler comment Hibernate " +"accédera à la propriété à l'exécution. Par défaut, Hibernate utilisera les " +"méthodes set/get. Si vous indiquez <literal>access=\"field\"</literal>, " +"Hibernate ignorera les getter/setter et accédera à la propriété directement " +"en utilisant la réflexion. Vous pouvez spécifier votre propre stratégie " +"d'accès aux propriétés en nommant une classe qui implémente l'interface " +"<literal>org.hibernate.propertexige une instrumentation de code d'octets " +"build-timey.PropertyAccessor</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"A powerful feature is derived properties. These properties are by definition " +"read-only. The property value is computed at load time. You declare the " +"computation as an SQL expression. This then translates to a <literal>SELECT</" +"literal> clause subquery in the SQL query that loads an instance:" +msgstr "" +"Les propriétés dérivées représentent une fonctionnalité particulièrement " +"intéressante. Ces propriétés sont par définition en lecture seule, la valeur " +"de la propriété est calculée au chargement. Le calcul est déclaré comme une " +"expression SQL, qui se traduit par une sous-requête <literal>SELECT</" +"literal> dans la requête SQL qui charge une instance : " + +#. Tag: para +#, no-c-format +msgid "" +"You can reference the entity table by not declaring an alias on a particular " +"column. This would be <literal>customerId</literal> in the given example. " +"You can also use the nested <literal>&lt;formula&gt;</literal> mapping " +"element if you do not want to use the attribute." +msgstr "" +"Remarquez que vous pouvez référencer la propre table des entités en ne " +"déclarant pas un alias sur une colonne particulière (<literal>customerId</" +"literal> dans l'exemple donné). Notez aussi que vous pouvez utiliser le sous-" +"élément de mappage <literal>&lt;formula&gt;</literal> plutôt que d'utiliser " +"l'attribut si vous le souhaitez. " + +#. Tag: title +#, no-c-format +msgid "Many-to-one" +msgstr "Plusieurs-à-un" + +#. Tag: para +#, no-c-format +msgid "" +"An ordinary association to another persistent class is declared using a " +"<literal>many-to-one</literal> element. The relational model is a many-to-" +"one association; a foreign key in one table is referencing the primary key " +"column(s) of the target table." +msgstr "" +"Une association ordinaire vers une autre classe persistante est déclarée en " +"utilisant un élément <literal>many-to-one</literal>. Le modèle relationnel " +"est une association de type plusieurs-à-un : une clé étrangère dans une " +"table référence la ou les clé(s) primaire(s) dans la table cible. " + +#. Tag: para +#, no-c-format +msgid "<literal>name</literal>: the name of the property." +msgstr "<literal>name</literal> : le nom de la propriété. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional): the name of the foreign key column. " +"This can also be specified by nested <literal>&lt;column&gt;</literal> " +"element(s)." +msgstr "" +"<literal>column</literal> (optionnel) : le nom de la colonne de la clé " +"étrangère. Cela peut être aussi spécifié par un ou des sous-élément(s) " +"<literal>&lt;column&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal> (optional - defaults to the property type " +"determined by reflection): the name of the associated class." +msgstr "" +"<literal>class</literal> (optionnel - par défaut, le type de la propriété " +"déterminé par réflexion) : le nom de la classe associée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>cascade</literal> (optional): specifies which operations should be " +"cascaded from the parent object to the associated object." +msgstr "" +"<literal>cascade</literal> (optionnel) : indique quelles opérations doivent " +"être cascadées de l'objet parent vers l'objet associé. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>fetch</literal> (optional - defaults to <literal>select</literal>): " +"chooses between outer-join fetching or sequential select fetching." +msgstr "" +"<literal>fetch</literal> (optionnel - par défaut à <literal>select</" +"literal>) : choisit entre le chargement de type jointure externe (outer-" +"join) ou le chargement par select successifs." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>update, insert</literal> (optional - defaults to <literal>true</" +"literal>): specifies that the mapped columns should be included in SQL " +"<literal>UPDATE</literal> and/or <literal>INSERT</literal> statements. " +"Setting both to <literal>false</literal> allows a pure \"derived\" " +"association whose value is initialized from another property that maps to " +"the same column(s), or by a trigger or other application." +msgstr "" +"<literal>update, insert</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique que les colonnes mappées devraient être incluses dans " +"des SQL <literal>UPDATE</literal> et/ou des déclarations <literal>INSERT</" +"literal>. Mettre les deux à <literal>false</literal>, permet une association " +"pure dérivée dont la valeur est initialisée à partir d'une autre propriété " +"qui mappe à une ou plusieurs mêmes colonnes, ou par un trigger ou une autre " +"application. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>property-ref</literal> (optional): the name of a property of the " +"associated class that is joined to this foreign key. If not specified, the " +"primary key of the associated class is used." +msgstr "" +"<literal>property-ref</literal> (optionnel) : le nom d'une propriété de la " +"classe associée qui est jointe à cette clé étrangère. Si non-spécifiée, la " +"clé primaire de la classe associée est utilisée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unique</literal> (optional): enables the DDL generation of a unique " +"constraint for the foreign-key column. By allowing this to be the target of " +"a <literal>property-ref</literal>, you can make the association multiplicity " +"one-to-one." +msgstr "" +"<literal>unique</literal> (optionnel) : génère le DDL d'une contrainte " +"unique pour la clé étrangère. Permet aussi d'en faire la cible d'une " +"<literal>property-ref</literal>. Cela permet de créer une véritable " +"association un-à-un. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-null</literal> (optional): enables the DDL generation of a " +"nullability constraint for the foreign key columns." +msgstr "" +"<literal>not-null</literal> (optionnel) : active le DDL d'une contrainte de " +"nullité pour les colonnes de clés étrangères." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>proxy</literal>): " +"by default, single point associations are proxied. <literal>lazy=\"no-proxy" +"\"</literal> specifies that the property should be fetched lazily when the " +"instance variable is first accessed. This requires build-time bytecode " +"instrumentation. <literal>lazy=\"false\"</literal> specifies that the " +"association will always be eagerly fetched." +msgstr "" +"<literal>lazy</literal> (optionnel - par défaut à <literal>proxy</" +"literal>) : par défaut, les associations de point uniques utilisent des " +"proxies. <literal>lazy=\"no-proxy\"</literal> indique que cette propriété " +"doit être chargée en différé au premier accès à la variable d'instance " +"(nécessite une instrumentation du bytecode lors de la phase de " +"construction). <literal>lazy=\"false\"</literal> indique que l'association " +"sera toujours chargée." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-found</literal> (optional - defaults to <literal>exception</" +"literal>): specifies how foreign keys that reference missing rows will be " +"handled. <literal>ignore</literal> will treat a missing row as a null " +"association." +msgstr "" +"<literal>not-found</literal> (optionnel - par défaut = <literal>exception</" +"literal>) : spécifie comment les clés étrangères qui référencent des lignes " +"manquantes seront gérées : <literal>ignore</literal> traitera une ligne " +"manquante comme une association nulle. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>entity-name</literal> (optional): the entity name of the associated " +"class." +msgstr "" +"<literal>entity-name</literal> (optionnel) : le nom de l'entité de la classe " +"associée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): an SQL expression that defines the " +"value for a <emphasis>computed</emphasis> foreign key." +msgstr "" +"<literal>formula</literal> (optionnel) : une expression SQL qui définit la " +"valeur pour une clé étrangère calculée. " + +#. Tag: para +#, no-c-format +msgid "" +"Setting a value of the <literal>cascade</literal> attribute to any " +"meaningful value other than <literal>none</literal> will propagate certain " +"operations to the associated object. The meaningful values are divided into " +"three categories. First, basic operations, which include: <literal>persist, " +"merge, delete, save-update, evict, replicate, lock and refresh</literal>; " +"second, special values: <literal>delete-orphan</literal>; and third," +"<literal>all</literal> comma-separated combinations of operation names: " +"<literal>cascade=\"persist,merge,evict\"</literal> or <literal>cascade=\"all," +"delete-orphan\"</literal>. See <xref linkend=\"objectstate-transitive\" /> " +"for a full explanation. Note that single valued, many-to-one and one-to-one, " +"associations do not support orphan delete." +msgstr "" +"Donner une valeur significative à l'attribut <literal>cascade</literal> " +"autre que <literal>none</literal> propagera certaines opérations à l'objet " +"associé. Les valeurs significatives sont les noms des opérations et sont " +"divisées en trois catégories. Tout d'abord, les valeurs Hibernate basiques, " +"<literal>persist, merge, delete, save-update, evict, replicate, lock, " +"refresh</literal>, puis les valeurs spéciales <literal>delete-orphan</" +"literal> et <literal>all</literal> et enfin, des combinaisons de noms " +"d'opérations séparées par des virgules, comme par exemple <literal>cascade=" +"\"persist,merge,evict\"</literal> ou <literal>cascade=\"all,delete-orphan\"</" +"literal>. Consultez la <xref linkend=\"objectstate-transitive\" /> pour une " +"explication complète. Notez que des associations valuées uniques " +"(associations plusieurs-à-un et un-à-un) ne supportent pas orphan delete. " + +#. Tag: para +#, no-c-format +msgid "" +"Here is an example of a typical <literal>many-to-one</literal> declaration:" +msgstr "" +"Une déclaration <literal>many-to-one</literal> typique est aussi simple " +"que : " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>property-ref</literal> attribute should only be used for " +"mapping legacy data where a foreign key refers to a unique key of the " +"associated table other than the primary key. This is a complicated and " +"confusing relational model. For example, if the <literal>Product</literal> " +"class had a unique serial number that is not the primary key. The " +"<literal>unique</literal> attribute controls Hibernate's DDL generation with " +"the SchemaExport tool." +msgstr "" +"L'attribut <literal>property-ref</literal> devrait être utilisé pour mapper " +"seulement des données provenant d'un ancien système où les clés étrangères " +"font référence à une clé unique de la table associée et qui n'est pas la clé " +"primaire. C'est un cas de mauvaise conception relationnelle. Par exemple, " +"supposez que la classe <literal>Product</literal> ait un numéro de série " +"unique qui n'est pas la clé primaire. L'attribut <literal>unique</literal> " +"contrôle la génération DDL par Hibernate avec l'outil SchemaExport." + +#. Tag: para +#, no-c-format +msgid "Then the mapping for <literal>OrderItem</literal> might use:" +msgstr "Ainsi le mappage pour <literal>OrderItem</literal> peut utiliser :" + +#. Tag: para +#, no-c-format +msgid "This is not encouraged, however." +msgstr "Bien que ce ne soit certainement pas encouragé." + +#. Tag: para +#, no-c-format +msgid "" +"If the referenced unique key comprises multiple properties of the associated " +"entity, you should map the referenced properties inside a named <literal>&lt;" +"properties&gt;</literal> element." +msgstr "" +"Si la clé unique référencée comprend des propriétés multiples de l'entité " +"associée, vous devez mapper ces propriétés à l'intérieur d'un élément nommé " +"<literal>&lt;properties&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"If the referenced unique key is the property of a component, you can specify " +"a property path:" +msgstr "" +"Si la clé unique référencée est la propriété d'un composant, vous pouvez " +"spécifier le chemin de propriété :" + +#. Tag: title +#, no-c-format +msgid "One-to-one" +msgstr "Un-à-un" + +#. Tag: para +#, no-c-format +msgid "" +"A one-to-one association to another persistent class is declared using a " +"<literal>one-to-one</literal> element." +msgstr "" +"Une association un-à-un vers une autre classe persistante est déclarée avec " +"l'élément <literal>one-to-one</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>constrained</literal> (optional): specifies that a foreign key " +"constraint on the primary key of the mapped table and references the table " +"of the associated class. This option affects the order in which <literal>save" +"()</literal> and <literal>delete()</literal> are cascaded, and determines " +"whether the association can be proxied. It is also used by the schema export " +"tool." +msgstr "" +"<literal>constrained</literal> (optionnel) : indique qu'une contrainte de " +"clé étrangère sur la clé primaire de la table mappée référence la table de " +"la classe associée. Cette option affecte l'ordre dans lequel chaque " +"<literal>save()</literal> et chaque <literal>delete()</literal> est cascadé " +"et détermine si l'association peut utiliser un proxy (aussi utilisé par " +"l'outil SchemaExport). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>property-ref</literal> (optional): the name of a property of the " +"associated class that is joined to the primary key of this class. If not " +"specified, the primary key of the associated class is used." +msgstr "" +"<literal>property-ref</literal> (optionnel) : le nom de la propriété de la " +"classe associée qui est jointe à la clé primaire de cette classe. Si ce " +"n'est pas spécifié, la clé primaire de la classe associée est utilisée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): almost all one-to-one associations " +"map to the primary key of the owning entity. If this is not the case, you " +"can specify another column, columns or expression to join on using an SQL " +"formula. See <literal>org.hibernate.test.onetooneformula</literal> for an " +"example." +msgstr "" +"<literal>formula</literal> (optionnel) : presque toutes les associations un-" +"à-un pointent sur la clé primaire de l'entité propriétaire. Dans les rares " +"cas différents, vous devez donner une ou plusieurs autres colonnes ou " +"expression à joindre par une formule SQL . Voir <literal>org.hibernate.test." +"onetooneformula</literal> pour un exemple." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>proxy</literal>): " +"by default, single point associations are proxied. <literal>lazy=\"no-proxy" +"\"</literal> specifies that the property should be fetched lazily when the " +"instance variable is first accessed. It requires build-time bytecode " +"instrumentation. <literal>lazy=\"false\"</literal> specifies that the " +"association will always be eagerly fetched. <emphasis>Note that if " +"<literal>constrained=\"false\"</literal>, proxying is impossible and " +"Hibernate will eagerly fetch the association</emphasis>." +msgstr "" +"<literal>lazy</literal> (optionnel - par défaut <literal>proxy</literal>) : " +"par défaut, les associations simples sont soumises à proxy. <literal>lazy=" +"\"no-proxy\"</literal> spécifie que la propriété doit être chargée en " +"différé au premier accès à l'instance. (nécessite l'instrumentation du " +"bytecode à la construction). <literal>lazy=\"false\"</literal> indique que " +"l'association sera toujours chargée agressivement. <emphasis>. Notez que si " +"<literal>constrained=\"false\"</literal>, l'utilisation de proxy est " +"impossible et Hibernate chargera automatiquement l'association </emphasis>." + +#. Tag: para +#, no-c-format +msgid "There are two varieties of one-to-one associations:" +msgstr "Il existe deux types d'associations un-à-un : " + +#. Tag: para +#, no-c-format +msgid "primary key associations" +msgstr "association par clé primaire " + +#. Tag: para +#, no-c-format +msgid "unique foreign key associations" +msgstr "association par clé étrangère unique" + +#. Tag: para +#, no-c-format +msgid "" +"Primary key associations do not need an extra table column. If two rows are " +"related by the association, then the two table rows share the same primary " +"key value. To relate two objects by a primary key association, ensure that " +"they are assigned the same identifier value." +msgstr "" +"Les associations par clé primaire ne nécessitent pas une colonne " +"supplémentaire en table ; si deux lignes sont liées par l'association alors " +"les deux lignes de la table partagent la même valeur de clé primaire. Donc " +"si vous voulez que deux objets soient liés par une association par clé " +"primaire, vous devez faire en sorte qu'on leur assigne la même valeur " +"d'identifiant. " + +#. Tag: para +#, no-c-format +msgid "" +"For a primary key association, add the following mappings to " +"<literal>Employee</literal> and <literal>Person</literal> respectively:" +msgstr "" +"Pour une association par clé primaire, ajoutez les mappages suivants à " +"<literal>Employee</literal> et <literal>Person</literal>, respectivement :" + +#. Tag: para +#, no-c-format +msgid "" +"Ensure that the primary keys of the related rows in the PERSON and EMPLOYEE " +"tables are equal. You use a special Hibernate identifier generation strategy " +"called <literal>foreign</literal>:" +msgstr "" +"Maintenant, vous devez faire en sorte que les clés primaires des lignes " +"liées dans les tables PERSON et EMPLOYEE sont égales. On utilise une " +"stratégie Hibernate spéciale de génération d'identifiants appelée " +"<literal>foreign</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"A newly saved instance of <literal>Person</literal> is assigned the same " +"primary key value as the <literal>Employee</literal> instance referred with " +"the <literal>employee</literal> property of that <literal>Person</literal>." +msgstr "" +"Une instance fraîchement enregistrée de <literal>Person</literal> se voit " +"alors assignée la même valeur de clé primaire que l'instance de " +"<literal>Employee</literal> référencée par la propriété <literal>employee</" +"literal> de cette <literal>Person</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, a foreign key with a unique constraint, from " +"<literal>Employee</literal> to <literal>Person</literal>, can be expressed " +"as:" +msgstr "" +"Alternativement, une clé étrangère avec contrainte d'unicité de " +"<literal>Employee</literal> vers <literal>Person</literal> peut être " +"indiquée ainsi : " + +#. Tag: para +#, no-c-format +msgid "" +"This association can be made bidirectional by adding the following to the " +"<literal>Person</literal> mapping:" +msgstr "" +"Et cette association peut être rendue bidirectionnelle en ajoutant ceci au " +"mappage de <literal>Person</literal> : " + +#. Tag: title +#, no-c-format +msgid "Natural-id" +msgstr "Natural-id" + +#. Tag: para +#, no-c-format +msgid "" +"Although we recommend the use of surrogate keys as primary keys, you should " +"try to identify natural keys for all entities. A natural key is a property " +"or combination of properties that is unique and non-null. It is also " +"immutable. Map the properties of the natural key inside the <literal>&lt;" +"natural-id&gt;</literal> element. Hibernate will generate the necessary " +"unique key and nullability constraints and, as a result, your mapping will " +"be more self-documenting." +msgstr "" +"Bien que nous recommandions l'utilisation de clés primaires générées, vous " +"devriez toujours essayer d'identifier des clés métier (naturelles) pour " +"toutes vos entités. Une clé naturelle est une propriété ou une combinaison " +"de propriétés unique et non nulle. Si elle est aussi immuable, c'est encore " +"mieux. Mappez les propriétés de la clé naturelle dans l'élément <literal>&lt;" +"natural-id&gt;</literal>. Hibernate générera la clé unique nécessaire et les " +"contraintes de non-nullité, et votre mappage s'auto-documentera. " + +#. Tag: para +#, no-c-format +msgid "" +"It is recommended that you implement <literal>equals()</literal> and " +"<literal>hashCode()</literal> to compare the natural key properties of the " +"entity." +msgstr "" +"Nous vous recommandons fortement d'implémenter <literal>equals()</literal> " +"et <literal>hashCode()</literal> pour comparer les propriétés clés " +"naturelles de l'entité." + +#. Tag: para +#, no-c-format +msgid "" +"This mapping is not intended for use with entities that have natural primary " +"keys." +msgstr "" +"Ce mappage n'est pas destiné à être utilisé avec des entités qui ont des " +"clés naturelles. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>mutable</literal> (optional - defaults to <literal>false</" +"literal>): by default, natural identifier properties are assumed to be " +"immutable (constant)." +msgstr "" +"<literal>mutable</literal> (optionnel, par défaut à <literal>false</" +"literal>) : par défaut, les identifiants naturels sont supposés être " +"immuables (constants). " + +#. Tag: title +#, no-c-format +msgid "Component and dynamic-component" +msgstr "Component, dynamic-component" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;component&gt;</literal> element maps properties of a child " +"object to columns of the table of a parent class. Components can, in turn, " +"declare their own properties, components or collections. See the \"Component" +"\" examples below:" +msgstr "" +"L'élément <literal>&lt;component&gt;</literal> mappe les propriétés d'un " +"objet enfant aux colonnes d'une classe parente. Les composants peuvent en " +"retour déclarer leurs propres propriétés, composants ou collections. Voir " +"\"Components\" plus bas :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal> (optional - defaults to the property type " +"determined by reflection): the name of the component (child) class." +msgstr "" +"<literal>class</literal> (optionnel - par défaut au type de la propriété " +"déterminé par réflexion) : le nom de la classe (enfant) du composant. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>insert</literal>: do the mapped columns appear in SQL " +"<literal>INSERTs</literal>?" +msgstr "" +"<literal>insert</literal> : les colonnes mappées apparaissent-elles dans les " +"SQL <literal>INSERT</literal> s ? " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>update</literal>: do the mapped columns appear in SQL " +"<literal>UPDATEs</literal>?" +msgstr "" +"<literal>update</literal>: les colonnes mappées apparaissent-elles dans les " +"SQL <literal>UPDATE</literal> s ? " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>false</literal>): " +"specifies that this component should be fetched lazily when the instance " +"variable is first accessed. It requires build-time bytecode instrumentation." +msgstr "" +"<literal>lazy</literal> (optionnel - par défaut à <literal>false</" +"literal>) : indique que ce composant doit être chargé en différé au premier " +"accès à la variable d'instance (nécessite une instrumentation du bytecode " +"lors de la phase de construction). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>true</" +"literal>): specifies that updates to this component either do or do not " +"require acquisition of the optimistic lock. It determines if a version " +"increment should occur when this property is dirty." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel - par défaut à <literal>true</" +"literal>) : spécifie si les mise à jour sur ce composant nécessitent ou non " +"l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine si " +"une incrémentation de version doit avoir lieu quand la propriété est marquée " +"obsolète (dirty). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unique</literal> (optional - defaults to <literal>false</literal>): " +"specifies that a unique constraint exists upon all mapped columns of the " +"component." +msgstr "" +"<literal>unique</literal> (optionnel - par défaut à <literal>false</" +"literal>) : Indique qu'une contrainte d'unicité existe sur toutes les " +"colonnes mappées de ce composant. " + +#. Tag: para +#, no-c-format +msgid "" +"The child <literal>&lt;property&gt;</literal> tags map properties of the " +"child class to table columns." +msgstr "" +"Les balises enfant <literal>&lt;property&gt;</literal> mappent les " +"propriétés de la classe enfant sur les colonnes de la table. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;component&gt;</literal> element allows a <literal>&lt;" +"parent&gt;</literal> subelement that maps a property of the component class " +"as a reference back to the containing entity." +msgstr "" +"L'élément <literal>&lt;component&gt;</literal> permet de déclarer un sous-" +"élément <literal>&lt;parent&gt;</literal> qui associe une propriété de la " +"classe composant comme une référence arrière vers l'entité contenante. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;dynamic-component&gt;</literal> element allows a " +"<literal>Map</literal> to be mapped as a component, where the property names " +"refer to keys of the map. See <xref linkend=\"components-dynamic\" /> for " +"more information." +msgstr "" +"L'élément <literal>&lt;dynamic-component&gt;</literal> permet à une " +"<literal>Map</literal> d'être mappée en tant que composant, quand les noms " +"de la propriété font référence aux clés de cette Map. Voir <xref linkend=" +"\"components-dynamic\" />. " + +#. Tag: title +#, no-c-format +msgid "Properties" +msgstr "Propriétés" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;properties&gt;</literal> element allows the definition of a " +"named, logical grouping of the properties of a class. The most important use " +"of the construct is that it allows a combination of properties to be the " +"target of a <literal>property-ref</literal>. It is also a convenient way to " +"define a multi-column unique constraint. For example:" +msgstr "" +"L'élément <literal>&lt;properties&gt;</literal> permet la définition d'un " +"groupement logique nommé des propriétés d'une classe. L'utilisation la plus " +"importante de cette construction est la possibilité pour une combinaison de " +"propriétés d'être la cible d'un <literal>property-ref</literal>. C'est aussi " +"un moyen pratique de définir une contrainte d'unicité multi-colonnes. Par " +"exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal>: the logical name of the grouping. It is " +"<emphasis>not</emphasis> an actual property name." +msgstr "" +"<literal>name</literal> : le nom logique d'un regroupement et <emphasis>non</" +"emphasis> le véritable nom d'une propriété. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>true</" +"literal>): specifies that updates to these properties either do or do not " +"require acquisition of the optimistic lock. It determines if a version " +"increment should occur when these properties are dirty." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique si les mise à jour sur ce composant nécessitent ou non " +"l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine si " +"une incrémentation de version doit avoir lieu quand la propriété est marquée " +"obsolète (dirty). " + +#. Tag: para +#, no-c-format +msgid "" +"For example, if we have the following <literal>&lt;properties&gt;</literal> " +"mapping:" +msgstr "" +"Par exemple, si nous avons le mappage de <literal>&lt;properties&gt;</" +"literal> suivant : " + +#. Tag: para +#, no-c-format +msgid "" +"You might have some legacy data association that refers to this unique key " +"of the <literal>Person</literal> table, instead of to the primary key:" +msgstr "" +"Alors nous pourrions avoir une association sur des données d'un ancien " +"système qui font référence à cette clé unique de la table <literal>Person</" +"literal> au lieu de la clé primaire : " + +#. Tag: para +#, no-c-format +msgid "" +"The use of this outside the context of mapping legacy data is not " +"recommended." +msgstr "" +"Nous ne recommandons pas une telle utilisation, en dehors du contexte de " +"mappage de données héritées d'anciens systèmes. " + +#. Tag: title +#, no-c-format +msgid "Subclass" +msgstr "Subclass" + +#. Tag: para +#, no-c-format +msgid "" +"Polymorphic persistence requires the declaration of each subclass of the " +"root persistent class. For the table-per-class-hierarchy mapping strategy, " +"the <literal>&lt;subclass&gt;</literal> declaration is used. For example:" +msgstr "" +"Pour finir, la persistance polymorphique nécessite la déclaration de chaque " +"sous-classe de la classe racine persistante. Pour la stratégie de mappage de " +"type table-per-class-hierarchy, on utilise la déclaration <literal>&lt;" +"subclass&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>name</literal>: the fully qualified class name of the subclass." +msgstr "<literal>name</literal> : le nom de classe complet de la sous-classe. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>discriminator-value</literal> (optional - defaults to the class " +"name): a value that distinguishes individual subclasses." +msgstr "" +"<literal>discriminator-value</literal> (optionnel - par défaut le nom de la " +"classe) : une valeur qui distingue les différentes sous-classes. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>proxy</literal> (optional): specifies a class or interface used for " +"lazy initializing proxies." +msgstr "" +"<literal>proxy</literal> (optionnel) : indique une classe ou interface à " +"utiliser pour l'initialisation différée des proxies. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>true</literal>): " +"setting <literal>lazy=\"false\"</literal> disables the use of lazy fetching." +msgstr "" +"<literal>lazy</literal> (optionnel, par défaut à <literal>true</literal>) : " +"spécifier <literal>lazy=\"false\"</literal> désactive l'utilisation de " +"l'extraction différée." + +#. Tag: para +#, no-c-format +msgid "" +"Each subclass declares its own persistent properties and subclasses. " +"<literal>&lt;version&gt;</literal> and <literal>&lt;id&gt;</literal> " +"properties are assumed to be inherited from the root class. Each subclass in " +"a hierarchy must define a unique <literal>discriminator-value</literal>. If " +"this is not specified, the fully qualified Java class name is used." +msgstr "" +"Chaque sous-classe devrait déclarer ses propres propriétés persistantes et " +"sous-classes. Les propriétés <literal>&lt;version&gt;</literal> et " +"<literal>&lt;id&gt;</literal> sont implicitement hérités de la classe " +"racine. Chaque sous-classe dans une hiérarchie doit définir une unique " +"<literal>discriminator-value</literal>. Si non spécifiée, le nom complet de " +"la classe Java est utilisé. " + +#. Tag: para +#, no-c-format +msgid "" +"For information about inheritance mappings see <xref linkend=\"inheritance" +"\" />." +msgstr "" +"Pour plus d'informations sur les mappages d'héritage, consultez le <xref " +"linkend=\"inheritance\" />. " + +#. Tag: title +#, no-c-format +msgid "Joined-subclass" +msgstr "Joined-subclass" + +#. Tag: para +#, no-c-format +msgid "" +"Each subclass can also be mapped to its own table. This is called the table-" +"per-subclass mapping strategy. An inherited state is retrieved by joining " +"with the table of the superclass. To do this you use the <literal>&lt;joined-" +"subclass&gt;</literal> element. For example:" +msgstr "" +"Il est également possible de mapper chaque sous-classe vers sa propre table " +"(stratégie de mappage de type table-per-subclass). L'état hérité est " +"récupéré en joignant la table de la super-classe. L'élément <literal>&lt;" +"joined-subclass&gt;</literal> est utilisé. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "<literal>table</literal>: the name of the subclass table." +msgstr "<literal>table</literal>: le nom de la table de la sous-classe. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>proxy</literal> (optional): specifies a class or interface to use " +"for lazy initializing proxies." +msgstr "" +"<literal>proxy</literal> (optionnel) : indique une classe ou interface à " +"utiliser pour l'initialisation différée des proxies. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional, defaults to <literal>true</literal>): " +"setting <literal>lazy=\"false\"</literal> disables the use of lazy fetching." +msgstr "" +"<literal>lazy</literal> (optionnel, par défaut à <literal>true</literal>) : " +"spécifier <literal>lazy=\"false\"</literal> désactive l'utilisation de " +"l'extraction différée. " + +#. Tag: para +#, no-c-format +msgid "" +"A discriminator column is not required for this mapping strategy. Each " +"subclass must, however, declare a table column holding the object identifier " +"using the <literal>&lt;key&gt;</literal> element. The mapping at the start " +"of the chapter would then be re-written as:" +msgstr "" +"Aucune colonne discriminante n'est nécessaire pour cette stratégie de " +"mappage. Cependant, chaque sous-classe doit déclarer une colonne de table " +"contenant l'objet identifiant qui utilise l'élément <literal>&lt;key&gt;</" +"literal>. Le mappage au début de ce chapitre serait ré-écrit ainsi : " + +#. Tag: title +#, no-c-format +msgid "Union-subclass" +msgstr "Union-subclass" + +#. Tag: para +#, no-c-format +msgid "" +"A third option is to map only the concrete classes of an inheritance " +"hierarchy to tables. This is called the table-per-concrete-class strategy. " +"Each table defines all persistent states of the class, including the " +"inherited state. In Hibernate, it is not necessary to explicitly map such " +"inheritance hierarchies. You can map each class with a separate <literal>&lt;" +"class&gt;</literal> declaration. However, if you wish use polymorphic " +"associations (e.g. an association to the superclass of your hierarchy), you " +"need to use the <literal>&lt;union-subclass&gt;</literal> mapping. For " +"example:" +msgstr "" +"Une troisième option est de mapper uniquement les classes concrètes d'une " +"hiérarchie d'héritage vers des tables, (stratégie de type table-per-concrete-" +"class) où chaque table définit tous les états persistants de la classe, y " +"compris les états hérités. Dans Hibernate il n'est absolument pas nécessaire " +"de mapper explicitement de telles hiérarchies d'héritage. Vous pouvez " +"simplement mapper chaque classe avec une déclaration <literal>&lt;class&gt;</" +"literal> différente. Cependant, si vous souhaitez utiliser des associations " +"polymorphiques (c'est-à-dire une association vers la superclasse de votre " +"hiérarchie), vous devez utiliser le mappage <literal>&lt;union-subclass&gt;</" +"literal>. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"No discriminator column or key column is required for this mapping strategy." +msgstr "" +"Aucune colonne discriminante ou colonne clé n'est requise pour cette " +"stratégie de mappage." + +#. Tag: title +#, no-c-format +msgid "Join" +msgstr "Join" + +#. Tag: para +#, no-c-format +msgid "" +"Using the <literal>&lt;join&gt;</literal> element, it is possible to map " +"properties of one class to several tables that have a one-to-one " +"relationship. For example:" +msgstr "" +"En utilisant l'élément <literal>&lt;join&gt;</literal>, il est possible de " +"mapper des propriétés d'une classe sur plusieurs tables quand il existe une " +"relation un-à-un entre les tables. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "<literal>table</literal>: the name of the joined table." +msgstr "<literal>table</literal> : le nom de la table jointe. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>fetch</literal> (optional - defaults to <literal>join</literal>): " +"if set to <literal>join</literal>, the default, Hibernate will use an inner " +"join to retrieve a <literal>&lt;join&gt;</literal> defined by a class or its " +"superclasses. It will use an outer join for a <literal>&lt;join&gt;</" +"literal> defined by a subclass. If set to <literal>select</literal> then " +"Hibernate will use a sequential select for a <literal>&lt;join&gt;</literal> " +"defined on a subclass. This will be issued only if a row represents an " +"instance of the subclass. Inner joins will still be used to retrieve a " +"<literal>&lt;join&gt;</literal> defined by the class and its superclasses." +msgstr "" +"<literal>fetch</literal> (optionnel - par défaut à <literal>join</" +"literal>) : si positionné à <literal>join</literal>, Hibernate utilisera une " +"jointure interne pour charger une <literal>jointure</literal> définie par " +"une classe ou ses super-classes et une jointure externe pour une " +"<literal>&lt;jointure&gt;</literal> définie par une sous-classe. Si " +"positionné à <literal>select</literal>, Hibernate utilisera un select " +"séquentiel pour une <literal>&lt;jointure&gt;</literal> définie sur une sous-" +"classe, qui ne sera délivrée que si une ligne représente une instance de la " +"sous-classe. Les jointures internes seront quand même utilisées pour charger " +"une <literal>&lt;jointure&gt;</literal> définie par une classe et ses super-" +"classes. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>inverse</literal> (optional - defaults to <literal>false</" +"literal>): if enabled, Hibernate will not insert or update the properties " +"defined by this join." +msgstr "" +"<literal>inverse</literal> (optionnel - par défaut à <literal>false</" +"literal>) : si positionné à true, Hibernate n'essaiera pas d'insérer ou de " +"mettre à jour les propriétés définies par cette jointure. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optional</literal> (optional - defaults to <literal>false</" +"literal>): if enabled, Hibernate will insert a row only if the properties " +"defined by this join are non-null. It will always use an outer join to " +"retrieve the properties." +msgstr "" +"<literal>optionnel</literal> (optionnel - par défaut à <literal>false</" +"literal>) : si positionné à true, Hibernate insèrera une ligne seulement si " +"les propriétés définies par cette jointure sont non-nulles et utilisera " +"toujours une jointure externe pour extraire les propriétés. " + +#. Tag: para +#, no-c-format +msgid "" +"For example, address information for a person can be mapped to a separate " +"table while preserving value type semantics for all properties:" +msgstr "" +"Par exemple, les informations d'adresse pour une personne peuvent être " +"mappées vers une table séparée (tout en préservant des sémantiques de type " +"valeur pour toutes ses propriétés) : " + +#. Tag: para +#, no-c-format +msgid "" +"This feature is often only useful for legacy data models. We recommend fewer " +"tables than classes and a fine-grained domain model. However, it is useful " +"for switching between inheritance mapping strategies in a single hierarchy, " +"as explained later." +msgstr "" +"Cette fonctionnalité est souvent seulement utile pour les modèles de données " +"hérités d'anciens systèmes, nous recommandons d'utiliser moins de tables que " +"de classes et un modèle de domaine à granularité fine. Cependant, c'est " +"utile pour passer d'une stratégie de mappage d'héritage à une autre dans une " +"hiérarchie simple, comme nous le verrons plus tard. " + +#. Tag: title +#, no-c-format +msgid "Key" +msgstr "Key" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;key&gt;</literal> element has featured a few times within " +"this guide. It appears anywhere the parent mapping element defines a join to " +"a new table that references the primary key of the original table. It also " +"defines the foreign key in the joined table:" +msgstr "" +"Nous avons rencontré l'élément <literal>&lt;key&gt;</literal> à plusieurs " +"reprises maintenant. Il apparaît partout que l'élément de mappage parent " +"définit une jointure sur une nouvelle table, et définit la clé étrangère " +"dans la table jointe, qui référence la clé primaire de la table d'origine :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>on-delete</literal> (optional - defaults to <literal>noaction</" +"literal>): specifies whether the foreign key constraint has database-level " +"cascade delete enabled." +msgstr "" +"<literal>on-delete</literal> (optionnel, par défaut à <literal>noaction</" +"literal>) : indique si la contrainte de clé étrangère possède la possibilité " +"au niveau base de données de suppression en cascade. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>property-ref</literal> (optional): specifies that the foreign key " +"refers to columns that are not the primary key of the original table. It is " +"provided for legacy data." +msgstr "" +"<literal>property-ref</literal> (optionnel) : indique que la clé étrangère " +"fait référence à des colonnes qui ne sont pas la clé primaire de la table " +"d'origine (Pour les données d'anciens systèmes). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-null</literal> (optional): specifies that the foreign key " +"columns are not nullable. This is implied whenever the foreign key is also " +"part of the primary key." +msgstr "" +"<literal>not-null</literal> (optionnel) : indique que les colonnes des clés " +"étrangères ne peuvent pas être nulles (c'est implicite si la clé étrangère " +"fait partie de la clé primaire). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>update</literal> (optional): specifies that the foreign key should " +"never be updated. This is implied whenever the foreign key is also part of " +"the primary key." +msgstr "" +"<literal>update</literal> (optionnel) : indique que la clé étrangère ne " +"devrait jamais être mise à jour (implicite si celle-ci fait partie de la clé " +"primaire). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unique</literal> (optional): specifies that the foreign key should " +"have a unique constraint. This is implied whenever the foreign key is also " +"the primary key." +msgstr "" +"<literal>unique</literal> (optionnel) : indique que la clé étrangère doit " +"posséder une contrainte d'unicité (implicite si la clé étrangère est aussi " +"la clé primaire). " + +#. Tag: para +#, no-c-format +msgid "" +"For systems where delete performance is important, we recommend that all " +"keys should be defined <literal>on-delete=\"cascade\"</literal>. Hibernate " +"uses a database-level <literal>ON CASCADE DELETE</literal> constraint, " +"instead of many individual <literal>DELETE</literal> statements. Be aware " +"that this feature bypasses Hibernate's usual optimistic locking strategy for " +"versioned data." +msgstr "" +"Là où les suppressions doivent être performantes, nous recommandons pour les " +"systèmes de définir toutes les clés <literal>on-delete=\"cascade\"</" +"literal>, ainsi Hibernate utilisera une contrainte <literal>ON CASCADE " +"DELETE</literal> au niveau base de données, plutôt que de nombreux " +"<literal>DELETE</literal> individuels. Attention, cette fonctionnalité court-" +"circuite la stratégie habituelle de verrou optimiste pour les données " +"versionnées. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>not-null</literal> and <literal>update</literal> attributes are " +"useful when mapping a unidirectional one-to-many association. If you map a " +"unidirectional one-to-many association to a non-nullable foreign key, you " +"<emphasis>must</emphasis> declare the key column using <literal>&lt;key not-" +"null=\"true\"&gt;</literal>." +msgstr "" +"Les attributs <literal>not-null</literal> et <literal>update</literal> sont " +"utiles pour mapper une association un-à-plusieurs unidirectionnelle. Si vous " +"mappez un un-à-plusieurs unidirectionnel vers une clé étrangère non nulle, " +"vous <emphasis>devez</emphasis> déclarer la colonne de la clé en utilisant " +"<literal>&lt;key not-null=\"true\"&gt;</literal>. " + +#. Tag: title +#, no-c-format +msgid "Column and formula elements" +msgstr "Éléments column et formula " + +#. Tag: para +#, no-c-format +msgid "" +"Mapping elements which accept a <literal>column</literal> attribute will " +"alternatively accept a <literal>&lt;column&gt;</literal> subelement. " +"Likewise, <literal>&lt;formula&gt;</literal> is an alternative to the " +"<literal>formula</literal> attribute. For example:" +msgstr "" +"Tout élément de mappage qui accepte un attribut <literal>column</literal> " +"acceptera alternativement un sous-élément <literal>&lt;column&gt;</literal>. " +"Pareillement <literal>&lt;formula&gt;</literal> est une alternative à " +"l'attribut <literal>formula</literal>. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"Most of the attributes on <literal>column</literal> provide a means of " +"tailoring the DDL during automatic schema generation. The <literal>read</" +"literal> and <literal>write</literal> attributes allow you to specify custom " +"SQL that Hibernate will use to access the column's value. For more on this, " +"see the discussion of <link linkend=\"mapping-column-read-and-write\">column " +"read and write expressions</link>." +msgstr "" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The <literal>column</literal> and <literal>formula</literal> elements can " +"even be combined within the same property or association mapping to express, " +"for example, exotic join conditions." +msgstr "" +"Les attributs <literal>column</literal> et <literal>formula</literal> " +"peuvent même être combinés au sein d'une même propriété ou mappage " +"d'association pour exprimer, par exemple, des conditions de jointure " +"exotiques. " + +#. Tag: title +#, no-c-format +msgid "Import" +msgstr "Import" + +#. Tag: para +#, no-c-format +msgid "" +"If your application has two persistent classes with the same name, and you " +"do not want to specify the fully qualified package name in Hibernate " +"queries, classes can be \"imported\" explicitly, rather than relying upon " +"<literal>auto-import=\"true\"</literal>. You can also import classes and " +"interfaces that are not explicitly mapped:" +msgstr "" +"Supposez que votre application possède deux classes persistantes du même " +"nom, et vous ne voulez pas préciser le nom Java complet (paquetage) dans les " +"requêtes Hibernate. Les classes peuvent alors être \"importées\" " +"explicitement plutôt que de compter sur <literal>auto-import=\"true\"</" +"literal>.Vous pouvez même importer des classes et interfaces qui ne sont pas " +"mappées explicitement :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal>: the fully qualified class name of any Java class." +msgstr "<literal>class</literal> : nom complet de toute classe Java. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>rename</literal> (optional - defaults to the unqualified class " +"name): a name that can be used in the query language." +msgstr "" +"<literal>rename</literal> (optionnel - par défaut vaut le nom de la classe " +"non qualifié): nom pouvant être utilisé dans le langage de requête. " + +#. Tag: title +#, no-c-format +msgid "Any" +msgstr "Any" + +#. Tag: para +#, no-c-format +msgid "" +"There is one more type of property mapping. The <literal>&lt;any&gt;</" +"literal> mapping element defines a polymorphic association to classes from " +"multiple tables. This type of mapping requires more than one column. The " +"first column contains the type of the associated entity. The remaining " +"columns contain the identifier. It is impossible to specify a foreign key " +"constraint for this kind of association. This is not the usual way of " +"mapping polymorphic associations and you should use this only in special " +"cases. For example, for audit logs, user session data, etc." +msgstr "" +"Il existe encore un type de mappage de propriété. L'élément de mappage " +"<literal>&lt;any&gt;</literal> définit une association polymorphique vers " +"des classes de tables multiples. Ce type de mappage requiert toujours plus " +"d'une colonne. La première colonne contient le type de l'entité associée. " +"Les colonnes restantes contiennent l'identifiant. Il est impossible de " +"spécifier une contrainte de clé étrangère pour ce type d'association, donc " +"ce n'est certainement pas considéré comme le moyen habituel de mapper des " +"associations (polymorphiques). Ne doit être utilisé que dans des cas " +"particuliers (par exemple des logs d'audit, des données de session " +"utilisateur, etc...). " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>meta-type</literal> attribute allows the application to specify " +"a custom type that maps database column values to persistent classes that " +"have identifier properties of the type specified by <literal>id-type</" +"literal>. You must specify the mapping from values of the meta-type to class " +"names." +msgstr "" +"L'attribut <literal>meta-type</literal> permet à l'application de spécifier " +"un type personnalisé qui mappe des valeurs de colonnes de base de données " +"sur des classes persistantes qui ont un attribut identifiant du type " +"spécifié par <literal>id-type</literal>. Vous devez spécifier le mappage à " +"partir de valeurs du méta-type sur les noms des classes. " + +#. Tag: para +#, no-c-format +msgid "<literal>name</literal>: the property name." +msgstr "<literal>name</literal> : le nom de la propriété. " + +#. Tag: para +#, no-c-format +msgid "<literal>id-type</literal>: the identifier type." +msgstr "<literal>id-type</literal> : le type identifiant." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>meta-type</literal> (optional - defaults to <literal>string</" +"literal>): any type that is allowed for a discriminator mapping." +msgstr "" +"<literal>meta-type</literal> (optionnel - par défaut à <literal>string</" +"literal>) : tout type permis pour un mappage par discriminateur." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>cascade</literal> (optional- defaults to <literal>none</literal>): " +"the cascade style." +msgstr "" +"<literal>cascade</literal> (optionnel - par défaut à <literal>none</" +"literal>) : le style de cascade. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>true</" +"literal>): specifies that updates to this property either do or do not " +"require acquisition of the optimistic lock. It defines whether a version " +"increment should occur if this property is dirty." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel - par défaut à <literal>true</" +"literal>) : indique si les mise à jour sur cette propriété nécessitent ou " +"non l'acquisition d'un verrou optimiste. En d'autres termes, définit si un " +"incrément de version doit avoir lieu quand cette propriété est marquée " +"dirty. " + +#. Tag: title +#, no-c-format +msgid "Hibernate types" +msgstr "Types Hibernate " + +#. Tag: title +#, no-c-format +msgid "Entities and values" +msgstr "Entités et valeurs" + +#. Tag: para +#, no-c-format +msgid "" +"In relation to the persistence service, Java language-level objects are " +"classified into two groups:" +msgstr "" +"Pour le service de persistance, les objets sont classés en deux groupes au " +"niveau langage Java :" + +#. Tag: para +#, no-c-format +msgid "" +"An <emphasis>entity</emphasis> exists independently of any other objects " +"holding references to the entity. Contrast this with the usual Java model, " +"where an unreferenced object is garbage collected. Entities must be " +"explicitly saved and deleted. Saves and deletions, however, can be " +"<emphasis>cascaded</emphasis> from a parent entity to its children. This is " +"different from the ODMG model of object persistence by reachability and " +"corresponds more closely to how application objects are usually used in " +"large systems. Entities support circular and shared references. They can " +"also be versioned." +msgstr "" +"Une <emphasis>entité</emphasis> existe indépendamment de tout autre objet " +"possédant des références vers l'entité. Comparez cela avec le modèle Java " +"habituel où un objet est supprimé par le garbage collector dès qu'il n'est " +"plus référencé. Les entités doivent être explicitement enregistrées et " +"supprimées (sauf dans les cas où sauvegardes et suppressions sont " +"<emphasis>cascadées</emphasis> d'une entité parent vers ses enfants). C'est " +"différent du modèle ODMG de persistance par atteignabilité - et correspond " +"mieux à la façon dont les objets sont habituellement utilisés dans des " +"grands systèmes. Les entités permettent les références circulaires et " +"partagées. Elles peuvent aussi être versionnées." + +#. Tag: para +#, no-c-format +msgid "" +"An entity's persistent state consists of references to other entities and " +"instances of <emphasis>value</emphasis> types. Values are primitives: " +"collections (not what is inside a collection), components and certain " +"immutable objects. Unlike entities, values in particular collections and " +"components, <emphasis>are</emphasis> persisted and deleted by reachability. " +"Since value objects and primitives are persisted and deleted along with " +"their containing entity, they cannot be independently versioned. Values have " +"no independent identity, so they cannot be shared by two entities or " +"collections." +msgstr "" +"L'état persistant d'une entité consiste en des références vers d'autres " +"entités et instances de types <emphasis>valeurs</emphasis>. Ces valeurs sont " +"des types primitifs, des collections (et non le contenu d'une collection), " +"des composants de certains objets immuables. Contrairement aux entités, les " +"valeurs (et en particulier les collections et composants) <emphasis>sont</" +"emphasis> persistées et supprimées par atteignabiliité. Comme les valeurs " +"(et types primitifs) sont persistées et supprimées avec l'entité qui les " +"contient, ils ne peuvent pas posséder leurs propres versions. Les valeurs " +"n'ont pas d'identité indépendantes, ainsi elles ne peuvent pas être " +"partagées par deux entités ou collections. " + +#. Tag: para +#, no-c-format +msgid "" +"Until now, we have been using the term \"persistent class\" to refer to " +"entities. We will continue to do that. Not all user-defined classes with a " +"persistent state, however, are entities. A <emphasis>component</emphasis> is " +"a user-defined class with value semantics. A Java property of type " +"<literal>java.lang.String</literal> also has value semantics. Given this " +"definition, all types (classes) provided by the JDK have value type " +"semantics in Java, while user-defined types can be mapped with entity or " +"value type semantics. This decision is up to the application developer. An " +"entity class in a domain model will normally have shared references to a " +"single instance of that class, while composition or aggregation usually " +"translates to a value type." +msgstr "" +"Jusqu'à présent nous avons utilisé le terme \"classe persistante\" pour " +"parler d'entités. Nous allons continuer à faire ainsi. Cependant, au sens " +"strict, toutes les classes définies par un utilisateur possédant un état " +"persistant ne sont pas des entités. Un <emphasis>composant</emphasis> est " +"une classe définie par un utilisateur avec la sémantique d'une valeur. Une " +"propriété Java de type <literal>java.lang.String</literal> a aussi les " +"caractéristiques d'une valeur. Selon cette définition, nous sommes en mesure " +"de déclarer que tous les types (classes) fournis par JDK possèdent la " +"sémantique d'une valeur dans Java, alors que les types définis par un " +"utilisateur pourront être mappés avec des sémantiques entités ou valeur " +"type. Cette décision est prise par le développeur d'application. Un bon " +"conseil pour une classe entité dans un modèle de domaine sont des références " +"partagées à une instance unique de cette classe, alors que la composition ou " +"l'agrégation se traduit en général par une valeur type. " + +#. Tag: para +#, no-c-format +msgid "We will revisit both concepts throughout this reference guide." +msgstr "" +"Nous nous pencherons sur ces deux concepts tout au long de la documentation. " + +#. Tag: para +#, no-c-format +msgid "" +"The challenge is to map the Java type system, and the developers' definition " +"of entities and value types, to the SQL/database type system. The bridge " +"between both systems is provided by Hibernate. For entities, <literal>&lt;" +"class&gt;</literal>, <literal>&lt;subclass&gt;</literal> and so on are used. " +"For value types we use <literal>&lt;property&gt;</literal>, <literal>&lt;" +"component&gt;</literal>etc., that usually have a <literal>type</literal> " +"attribute. The value of this attribute is the name of a Hibernate " +"<emphasis>mapping type</emphasis>. Hibernate provides a range of mappings " +"for standard JDK value types out of the box. You can write your own mapping " +"types and implement your own custom conversion strategies." +msgstr "" +"Le défi est de mapper les types Javas (et la définition des développeurs des " +"entités et valeurs types) sur les types du SQL ou des bases de données. Le " +"pont entre les deux systèmes est proposé par Hibernate : pour les entités " +"nous utilisons <literal>&lt;class&gt;</literal>, <literal>&lt;subclass&gt;</" +"literal> et ainsi de suite. Pour les types valeurs nous utilisons " +"<literal>&lt;property&gt;</literal>, <literal>&lt;component&gt;</literal>, " +"etc., habituellement avec un attribut <literal>type</literal>. La valeur de " +"cet attribut est le nom d'un <emphasis>type de mappage</emphasis> Hibernate. " +"Hibernate propose de nombreux mappages prêts à l'utilisation (pour les types " +"de valeurs standards du JDK). Vous pouvez écrire vos propres types de " +"mappages et implémenter aussi vos propres stratégies de conversion comme " +"nous le verrons plus tard. " + +#. Tag: para +#, no-c-format +msgid "" +"With the exception of collections, all built-in Hibernate types support null " +"semantics." +msgstr "" +"Tous les types proposés Hibernate à part les collections autorisent les " +"sémantiques null. " + +#. Tag: title +#, no-c-format +msgid "Basic value types" +msgstr "Types valeurs de base " + +#. Tag: para +#, no-c-format +msgid "" +"The built-in <emphasis>basic mapping types</emphasis> can be roughly " +"categorized into the following:" +msgstr "" +"Les <emphasis>types de mappage de base</emphasis> peuvent être classés de la " +"façon suivante :" + +#. Tag: term +#, no-c-format +msgid "" +"<literal>integer, long, short, float, double, character, byte, boolean, " +"yes_no, true_false</literal>" +msgstr "" +"<literal>integer, long, short, float, double, character, byte, boolean, " +"yes_no, true_false</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings from Java primitives or wrapper classes to appropriate (vendor-" +"specific) SQL column types. <literal>boolean, yes_no</literal> and " +"<literal>true_false</literal> are all alternative encodings for a Java " +"<literal>boolean</literal> or <literal>java.lang.Boolean</literal>." +msgstr "" +"Les mappages de type des primitives Java ou leurs classes wrappers (ex : " +"Integer pour int) vers les types de colonne SQL (propriétaires) appropriés. " +"<literal>boolean, yes_no</literal>et <literal>true_false</literal> sont tous " +"des alternatives pour les types Java <literal>boolean</literal> ou " +"<literal>java.lang.Boolean</literal>." + +#. Tag: term +#, no-c-format +msgid "<literal>string</literal>" +msgstr "<literal>string</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"A type mapping from <literal>java.lang.String</literal> to <literal>VARCHAR</" +"literal> (or Oracle <literal>VARCHAR2</literal>)." +msgstr "" +"Mappage de type de <literal>java.lang.String</literal> vers " +"<literal>VARCHAR</literal> (ou le <literal>VARCHAR2</literal> Oracle)." + +#. Tag: term +#, no-c-format +msgid "<literal>date, time, timestamp</literal>" +msgstr "<literal>date, time, timestamp</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings from <literal>java.util.Date</literal> and its subclasses to " +"SQL types <literal>DATE</literal>, <literal>TIME</literal> and " +"<literal>TIMESTAMP</literal> (or equivalent)." +msgstr "" +"mappages de type pour <literal>java.util.Date</literal> et ses sous-classes " +"vers les types SQL <literal>DATE</literal>, <literal>TIME</literal> et " +"<literal>TIMESTAMP</literal> (ou équivalent)." + +#. Tag: term +#, no-c-format +msgid "<literal>calendar, calendar_date</literal>" +msgstr "<literal>calendar, calendar_date</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings from <literal>java.util.Calendar</literal> to SQL types " +"<literal>TIMESTAMP</literal> and <literal>DATE</literal> (or equivalent)." +msgstr "" +"mappages de type pour <literal>java.util.Calendar</literal> vers les types " +"SQL <literal>TIMESTAMP</literal> et <literal>DATE</literal> (ou équivalent)." + +#. Tag: term +#, no-c-format +msgid "<literal>big_decimal, big_integer</literal>" +msgstr "<literal>big_decimal, big_integer</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings from <literal>java.math.BigDecimal</literal> and <literal>java." +"math.BigInteger</literal> to <literal>NUMERIC</literal> (or Oracle " +"<literal>NUMBER</literal>)." +msgstr "" +"mappages de type de <literal>java.math.BigDecimal</literal> et <literal>java." +"math.BigInteger</literal> vers <literal>NUMERIC</literal> (ou le " +"<literal>NUMBER</literal> Oracle)." + +#. Tag: term +#, no-c-format +msgid "<literal>locale, timezone, currency</literal>" +msgstr "<literal>locale, timezone, currency</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings from <literal>java.util.Locale</literal>, <literal>java.util." +"TimeZone</literal> and <literal>java.util.Currency</literal> to " +"<literal>VARCHAR</literal> (or Oracle <literal>VARCHAR2</literal>). " +"Instances of <literal>Locale</literal> and <literal>Currency</literal> are " +"mapped to their ISO codes. Instances of <literal>TimeZone</literal> are " +"mapped to their <literal>ID</literal>." +msgstr "" +"mappages de type pour <literal>java.util.Locale</literal>, <literal>java." +"util.TimeZone</literal> et <literal>java.util.Currency</literal> vers " +"<literal>VARCHAR</literal> (ou le <literal>VARCHAR2</literal> Oracle). Les " +"instances de <literal>Locale</literal> et <literal>Currency</literal> sont " +"mappées sur leurs codes ISO. Les instances de <literal>TimeZone</literal> " +"sont mappées sur leur <literal>ID</literal>." + +#. Tag: term +#, no-c-format +msgid "<literal>class</literal>" +msgstr "<literal>class</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"A type mapping from <literal>java.lang.Class</literal> to <literal>VARCHAR</" +"literal> (or Oracle <literal>VARCHAR2</literal>). A <literal>Class</literal> " +"is mapped to its fully qualified name." +msgstr "" +"Un type de mappage de <literal>java.lang.Class</literal> vers " +"<literal>VARCHAR</literal> (ou le <literal>VARCHAR2</literal> Oracle). Un " +"objet <literal>Class</literal> est mappé sur son nom Java complet." + +#. Tag: term +#, no-c-format +msgid "<literal>binary</literal>" +msgstr "<literal>binary</literal>" + +#. Tag: para +#, no-c-format +msgid "Maps byte arrays to an appropriate SQL binary type." +msgstr "Mappe les tableaux de bytes vers le type binaire SQL approprié." + +#. Tag: term +#, no-c-format +msgid "<literal>text</literal>" +msgstr "<literal>text</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Maps long Java strings to a SQL <literal>CLOB</literal> or <literal>TEXT</" +"literal> type." +msgstr "" +"Mappe les longues chaînes de caractères Java vers les types SQL " +"<literal>CLOB</literal> ou <literal>TEXT</literal>." + +#. Tag: term +#, no-c-format +msgid "<literal>serializable</literal>" +msgstr "<literal>serializable</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Maps serializable Java types to an appropriate SQL binary type. You can also " +"indicate the Hibernate type <literal>serializable</literal> with the name of " +"a serializable Java class or interface that does not default to a basic type." +msgstr "" +"Mappe les types Java sérialisables vers le type SQL binaire approprié. Vous " +"pouvez aussi indiquer le type Hibernate <literal>serializable</literal> avec " +"le nom d'une classe Java sérialisable ou une interface qui ne soit pas par " +"défaut un type de base. " + +#. Tag: term +#, no-c-format +msgid "<literal>clob, blob</literal>" +msgstr "<literal>clob, blob</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings for the JDBC classes <literal>java.sql.Clob</literal> and " +"<literal>java.sql.Blob</literal>. These types can be inconvenient for some " +"applications, since the blob or clob object cannot be reused outside of a " +"transaction. Driver support is patchy and inconsistent." +msgstr "" +"Mappages de type pour les classes JDBC <literal>java.sql.Clob</literal> et " +"<literal>java.sql.Blob</literal>. Ces types peuvent ne pas convenir pour " +"certaines applications car un objet blob ou clob peut ne pas être " +"réutilisable en dehors d'une transaction (de plus l'implémentation par les " +"pilotes comporte des lacunes)." + +#. Tag: term +#, no-c-format +msgid "" +"<literal>imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, " +"imm_serializable, imm_binary</literal>" +msgstr "" +"<literal>imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, " +"imm_serializable, imm_binary</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Type mappings for what are considered mutable Java types. This is where " +"Hibernate makes certain optimizations appropriate only for immutable Java " +"types, and the application treats the object as immutable. For example, you " +"should not call <literal>Date.setTime()</literal> for an instance mapped as " +"<literal>imm_timestamp</literal>. To change the value of the property, and " +"have that change made persistent, the application must assign a new, " +"nonidentical, object to the property." +msgstr "" +"Mappages de type pour ceux qui sont habituellement considérés comme des " +"types Java modifiables, et pour lesquels Hibernate effectue certaines " +"optimisations convenant seulement aux types Java immuables. L'application " +"les traite comme immuables. Par exemple, vous ne devriez pas appeler " +"<literal>Date.setTime()</literal> sur une instance mappée sur un " +"<literal>imm_timestamp</literal>. Pour changer la valeur de la propriété, et " +"faire en sorte que cette modification soit persistée, l'application doit " +"assigner un nouvel (non identique) objet à la propriété. " + +#. Tag: para +#, no-c-format +msgid "" +"Unique identifiers of entities and collections can be of any basic type " +"except <literal>binary</literal>, <literal>blob</literal> and <literal>clob</" +"literal>. Composite identifiers are also allowed. See below for more " +"information." +msgstr "" +"Les identifiants uniques des entités et collections peuvent être de " +"n'importe quel type de base excepté <literal>binary</literal>, " +"<literal>blob</literal> et <literal>clob</literal> (les identifiants " +"composites sont aussi permis, voir plus bas). " + +#. Tag: para +#, no-c-format +msgid "" +"The basic value types have corresponding <literal>Type</literal> constants " +"defined on <literal>org.hibernate.Hibernate</literal>. For example, " +"<literal>Hibernate.STRING</literal> represents the <literal>string</literal> " +"type." +msgstr "" +"Les types de base des valeurs ont des <literal>Type</literal> constants " +"correspondants et définis dans <literal>org.hibernate.Hibernate</literal>. " +"Par exemple, <literal>Hibernate.STRING</literal> représente le type " +"<literal>string</literal>. " + +#. Tag: title +#, no-c-format +msgid "Custom value types" +msgstr "Types de valeur personnalisés" + +#. Tag: para +#, no-c-format +msgid "" +"It is relatively easy for developers to create their own value types. For " +"example, you might want to persist properties of type <literal>java.lang." +"BigInteger</literal> to <literal>VARCHAR</literal> columns. Hibernate does " +"not provide a built-in type for this. Custom types are not limited to " +"mapping a property, or collection element, to a single table column. So, for " +"example, you might have a Java property <literal>getName()</literal>/" +"<literal>setName()</literal> of type <literal>java.lang.String</literal> " +"that is persisted to the columns <literal>FIRST_NAME</literal>, " +"<literal>INITIAL</literal>, <literal>SURNAME</literal>." +msgstr "" +"Il est assez facile pour les développeurs de créer leurs propres types de " +"valeurs. Par exemple, vous aimeriez persister des propriétés du type " +"<literal>java.lang.BigInteger</literal> dans des colonnes <literal>VARCHAR</" +"literal>. Hibernate ne procure pas de type par défaut à cet effet. " +"Toutefois, les types personnalisés ne se limitent pas à mapper des " +"propriétés (ou élément collection) à une simple colonne de table. Donc, par " +"exemple, vous pourriez avoir une propriété Java <literal>getName()</literal>/" +"<literal>setName()</literal> de type <literal>java.lang.String</literal> " +"persistée dans les colonnes <literal>FIRST_NAME</literal>, <literal>INITIAL</" +"literal>, <literal>SURNAME</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"To implement a custom type, implement either <literal>org.hibernate." +"UserType</literal> or <literal>org.hibernate.CompositeUserType</literal> and " +"declare properties using the fully qualified classname of the type. View " +"<literal>org.hibernate.test.DoubleStringType</literal> to see the kind of " +"things that are possible." +msgstr "" +"Pour implémenter votre propre type, vous pouvez soit implémenter " +"<literal>org.hibernate.UserType</literal> soit <literal>org.hibernate." +"CompositeUserType</literal> et déclarer des propriétés utilisant des noms de " +"classes complets du type. Consultez <literal>org.hibernate.test." +"DoubleStringType</literal> pour étudier les possibilités. " + +#. Tag: para +#, no-c-format +msgid "" +"Notice the use of <literal>&lt;column&gt;</literal> tags to map a property " +"to multiple columns." +msgstr "" +"Remarquez l'utilisation des balises <literal>&lt;column&gt;</literal> pour " +"mapper une propriété sur des colonnes multiples." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>CompositeUserType</literal>, <literal>EnhancedUserType</" +"literal>, <literal>UserCollectionType</literal>, and " +"<literal>UserVersionType</literal> interfaces provide support for more " +"specialized uses." +msgstr "" +"Les interfaces <literal>CompositeUserType</literal>, " +"<literal>EnhancedUserType</literal>, <literal>UserCollectionType</literal>, " +"et <literal>UserVersionType</literal> prennent en charge des utilisations " +"plus spécialisées. " + +#. Tag: para +#, no-c-format +msgid "" +"You can even supply parameters to a <literal>UserType</literal> in the " +"mapping file. To do this, your <literal>UserType</literal> must implement " +"the <literal>org.hibernate.usertype.ParameterizedType</literal> interface. " +"To supply parameters to your custom type, you can use the <literal>&lt;" +"type&gt;</literal> element in your mapping files." +msgstr "" +"Vous pouvez même fournir des paramètres en indiquant <literal>UserType</" +"literal> dans le fichier de mappage. À cet effet, votre <literal>UserType</" +"literal> doit implémenter l'interface <literal>org.hibernate.usertype." +"ParameterizedType</literal>. Pour spécifier des paramètres dans votre type " +"propre, vous pouvez utiliser l'élément <literal>&lt;type&gt;</literal> dans " +"vos fichiers de mappage. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>UserType</literal> can now retrieve the value for the parameter " +"named <literal>default</literal> from the <literal>Properties</literal> " +"object passed to it." +msgstr "" +"Le <literal>UserType</literal> permet maintenant de récupérer la valeur pour " +"le paramètre nommé <literal>default</literal> à partir de l'objet " +"<literal>Properties</literal> qui lui est passé. " + +#. Tag: para +#, no-c-format +msgid "" +"If you regularly use a certain <literal>UserType</literal>, it is useful to " +"define a shorter name for it. You can do this using the <literal>&lt;" +"typedef&gt;</literal> element. Typedefs assign a name to a custom type, and " +"can also contain a list of default parameter values if the type is " +"parameterized." +msgstr "" +"Si vous utilisez fréquemment un <literal>UserType</literal>, il est utile de " +"lui définir un nom plus court. Vous pouvez l'effectuer, en utilisant " +"l'élément <literal>&lt;typedef&gt;</literal>. Les typedefs permettent " +"d'assigner un nom à votre type propre et peuvent aussi contenir une liste de " +"valeurs de paramètres par défaut si ce type est paramétré. " + +#. Tag: para +#, no-c-format +msgid "" +"It is also possible to override the parameters supplied in a typedef on a " +"case-by-case basis by using type parameters on the property mapping." +msgstr "" +"Il est également possible de redéfinir les paramètres par défaut du typedef " +"au cas par cas en utilisant des paramètres type sur le mappage de la " +"propriété. " + +#. Tag: para +#, no-c-format +msgid "" +"Even though Hibernate's rich range of built-in types and support for " +"components means you will rarely need to use a custom type, it is considered " +"good practice to use custom types for non-entity classes that occur " +"frequently in your application. For example, a <literal>MonetaryAmount</" +"literal> class is a good candidate for a <literal>CompositeUserType</" +"literal>, even though it could be mapped as a component. One reason for this " +"is abstraction. With a custom type, your mapping documents would be " +"protected against changes to the way monetary values are represented." +msgstr "" +"Alors que Hibernate offre une riche variété de types, et la prise en charge " +"des composants, vous aurez très rarement <emphasis>besoin</emphasis> " +"d'utiliser un type personnalisé, il est néanmoins recommandé d'utiliser des " +"types personnalisés pour les classes (non entités) qui apparaissent " +"fréquemment dans votre application. Par exemple, une classe " +"<literal>MonetaryAmount</literal> est un bon candidat pour un " +"<literal>CompositeUserType</literal> même si elle pourrait facilement être " +"mappée en tant que composant. Une motivation pour cela est l'abstraction. " +"Avec un type personnalisé, vos documents de mappage sont à l'abri des " +"changements futurs dans votre façon de représenter des valeurs monétaires. " + +#. Tag: title +#, no-c-format +msgid "Mapping a class more than once" +msgstr "Mapper une classe plus d'une fois" + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to provide more than one mapping for a particular persistent " +"class. In this case, you must specify an <emphasis>entity name</emphasis> to " +"disambiguate between instances of the two mapped entities. By default, the " +"entity name is the same as the class name. Hibernate lets you specify the " +"entity name when working with persistent objects, when writing queries, or " +"when mapping associations to the named entity." +msgstr "" +"Il est possible de fournir plus d'un mappage par classe persistante. Dans ce " +"cas, vous devez spécifier un <emphasis>nom d'entité</emphasis> pour lever " +"l'ambiguité entre les instances des entités mappées (par défaut, le nom de " +"l'entité est celui de la classe). Hibernate vous permet de spécifier le nom " +"de l'entité lorsque vous utilisez des objets persistants, lorsque vous " +"écrivez des requêtes ou quand vous mappez des associations vers les entités " +"nommées. " + +#. Tag: para +#, no-c-format +msgid "" +"Associations are now specified using <literal>entity-name</literal> instead " +"of <literal>class</literal>." +msgstr "" +"Remarquez comment les associations sont désormais spécifiées en utilisant " +"<literal>entity-name</literal> au lieu de <literal>class</literal>. " + +#. Tag: title +#, no-c-format +msgid "SQL quoted identifiers" +msgstr "SQL quoted identifiers" + +#. Tag: para +#, no-c-format +msgid "" +"You can force Hibernate to quote an identifier in the generated SQL by " +"enclosing the table or column name in backticks in the mapping document. " +"Hibernate will use the correct quotation style for the SQL <literal>Dialect</" +"literal>. This is usually double quotes, but the SQL Server uses brackets " +"and MySQL uses backticks." +msgstr "" +"Vous pouvez forcer Hibernate à mettre un identifiant entre quotes dans le " +"SQL généré en mettant le nom de la table ou de la colonne entre backticks " +"dans le document de mappage. Hibernate utilisera les bons styles de quotes " +"pour le SQL <literal>Dialect</literal> (habituellement des doubles quotes, " +"mais des parenthèses pour SQL Server et des backticks pour MySQL). " + +#. Tag: title +#, no-c-format +msgid "Metadata alternatives" +msgstr "Métadonnées alternatives" + +#. Tag: para +#, no-c-format +msgid "" +"XML does not suit all users so there are some alternative ways to define O/R " +"mapping metadata in Hibernate." +msgstr "" +"XML ne convient pas à tout le monde, il y a donc des moyens alternatifs pour " +"définir des métadonnées de mappage O/R dans Hibernate. " + +#. Tag: title +#, no-c-format +msgid "Using XDoclet markup" +msgstr "Utilisation de XDoclet " + +#. Tag: para +#, no-c-format +msgid "" +"Many Hibernate users prefer to embed mapping information directly in " +"sourcecode using XDoclet <literal&gt;(a)hibernate.tags&lt;/literal&gt;. We do not cover " +"this approach in this reference guide since it is considered part of " +"XDoclet. However, we include the following example of the <literal>Cat</" +"literal> class with XDoclet mappings:" +msgstr "" +"De nombreux utilisateurs de Hibernate préfèrent embarquer les informations " +"de mappages directement au sein du code source en utilisant lesbalises " +"XDoclet <literal&gt;(a)hibernate.tags&lt;/literal&gt;. Nous ne couvrons pas cette " +"approche dans ce document puisque cela est considéré comme faisant partie de " +"XDoclet. Cependant, nous présentons l'exemple suivant de la classe " +"<literal>Cat</literal> avec des mappages XDoclet :" + +#. Tag: para +#, no-c-format +msgid "See the Hibernate website for more examples of XDoclet and Hibernate." +msgstr "" +"Voyez le site web de Hibernate pour plus d'exemples sur XDoclet et " +"Hibernate. " + +#. Tag: title +#, no-c-format +msgid "Using JDK 5.0 Annotations" +msgstr "Utilisation des annotations JDK 5.0" + +#. Tag: para +#, no-c-format +msgid "" +"JDK 5.0 introduced XDoclet-style annotations at the language level that are " +"type-safe and checked at compile time. This mechanism is more powerful than " +"XDoclet annotations and better supported by tools and IDEs. IntelliJ IDEA, " +"for example, supports auto-completion and syntax highlighting of JDK 5.0 " +"annotations. The new revision of the EJB specification (JSR-220) uses JDK " +"5.0 annotations as the primary metadata mechanism for entity beans. " +"Hibernate3 implements the <literal>EntityManager</literal> of JSR-220 (the " +"persistence API). Support for mapping metadata is available via the " +"<emphasis>Hibernate Annotations</emphasis> package as a separate download. " +"Both EJB3 (JSR-220) and Hibernate3 metadata is supported." +msgstr "" +"Le JDK 5.0 introduit des annotations proches de celles de XDoclet au niveau " +"java, qui sont type-safe et vérifiées à la compilation. Ce mécanisme est " +"plus puissant que XDoclet et mieux supporté par les outils et les IDE. " +"IntelliJ IDEA, par exemple, supporte l'auto-complétion et le surlignement " +"syntaxique des annotations JDK 5.0. La nouvelle révision des spécifications " +"des EJB (JSR-220) utilise les annotations JDK 5.0 comme mécanisme primaire " +"pour les metadonnées des beans entités. Hibernate3 implémente " +"l'<literal>EntityManager</literal> de la JSR-220 (API de persistance), le " +"support du mappage de métadonnées est disponible via le paquetage " +"<emphasis>Hibernate Annotations</emphasis>, en tant que module séparé à " +"télécharger. EJB3 (JSR-220) et les métadonnées Hibernate3 sont supportés. " + +#. Tag: para +#, no-c-format +msgid "This is an example of a POJO class annotated as an EJB entity bean:" +msgstr "Ceci est un exemple d'une classe POJO annotée comme un EJB entité :" + +#. Tag: para +#, no-c-format +msgid "" +"Support for JDK 5.0 Annotations (and JSR-220) is currently under " +"development. Please refer to the Hibernate Annotations module for more " +"details." +msgstr "" +"Notez que le support des annotations JDK 5.0 (et de la JSR-220) est encore " +"en cours et n'est pas terminé. Référez vous au module Hibernate Annotation " +"pour plus d'informations. " + +#. Tag: title +#, no-c-format +msgid "Generated properties" +msgstr "Propriétés générées " + +#. Tag: para +#, no-c-format +msgid "" +"Generated properties are properties that have their values generated by the " +"database. Typically, Hibernate applications needed to <literal>refresh</" +"literal> objects that contain any properties for which the database was " +"generating values. Marking properties as generated, however, lets the " +"application delegate this responsibility to Hibernate. When Hibernate issues " +"an SQL INSERT or UPDATE for an entity that has defined generated properties, " +"it immediately issues a select afterwards to retrieve the generated values." +msgstr "" +"Les propriétés générées sont des propriétés dont les valeurs sont générées " +"par la base de données. Typiquement, les applications Hibernate avaient " +"besoin d'invoquer <literal>refresh</literal> sur les instances qui " +"contenaient des propriétés pour lesquelles la base de données générait des " +"valeurs. Marquer les propriétés comme générées, permet à l'application de " +"déléguer cette responsabilité à Hibernate. Principalement, à chaque fois que " +"Hibernate réalise un SQL INSERT ou UPDATE en base de données pour une entité " +"marquée comme telle, cela provoque immédiatement un select pour récupérer " +"les valeurs générées. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Properties marked as generated must additionally be non-insertable and non-" +"updateable. Only <link linkend=\"mapping-declaration-version\">versions</" +"link>, <link linkend=\"mapping-declaration-timestamp\">timestamps</link>, " +"and <link linkend=\"mapping-declaration-property\">simple properties</link>, " +"can be marked as generated." +msgstr "" +"Les propriétés marquées comme générées doivent de plus ne pas être " +"insérables et modifiables. Seules les versions <xref linkend=\"mapping-" +"declaration-version\"/>, les timestamps <xref linkend=\"mapping-declaration-" +"timestamp\"/>, et les propriétés simples <xref linkend=\"mapping-declaration-" +"property\" /> peuvent être marqués comme générés. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>never</literal> (the default): the given property value is not " +"generated within the database." +msgstr "" +"<literal>never</literal> (par défaut) - indique que la valeur donnée de la " +"propriété n'est pas générée dans la base de données. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<literal>insert</literal>: the given property value is generated on insert, " +"but is not regenerated on subsequent updates. Properties like created-date " +"fall into this category. Even though <link linkend=\"mapping-declaration-" +"version\">version</link> and <link linkend=\"mapping-declaration-timestamp" +"\">timestamp</link> properties can be marked as generated, this option is " +"not available." +msgstr "" +"<literal>insert</literal> - indique que la valeur de la propriété donnée est " +"générée à l'insertion mais pas lors des futures mise à jour de " +"l'enregistrement. Les colonnes de type \"date de création\" sont le cas " +"d'utilisation typique de cette option. Notez que bien que la version <xref " +"linkend=\"mapping-declaration-version\"/> et les propriétés timestamp <xref " +"linkend=\"mapping-declaration-timestamp\" /> puissent être déclarées comme " +"générées, cette option n'est pas disponible." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>always</literal>: the property value is generated both on insert " +"and on update." +msgstr "" +"<literal>always</literal> - indique que la valeur de la propriété est " +"générée à l'insertion comme aux mise à jour. " + +#. Tag: title +#, no-c-format +msgid "Column read and write expressions" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate allows you to customize the SQL it uses to read and write the " +"values of columns mapped to <link linkend=\"mapping-declaration-property" +"\">simple properties</link>. For example, if your database provides a set of " +"data encryption functions, you can invoke them for individual columns like " +"this: <programlisting role=\"XML\">&lt;property name=\"creditCardNumber" +"\"&gt; &lt;column name=\"credit_card_num\" read=\"decrypt(credit_card_num)\" " +"write=\"encrypt(?)\"/&gt; &lt;/property&gt;</programlisting>" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate applies the custom expressions automatically whenever the property " +"is referenced in a query. This functionality is similar to a derived-" +"property <literal>formula</literal> with two differences:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"The property is backed by one or more columns that are exported as part of " +"automatic schema generation." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "The property is read-write, not read-only." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>write</literal> expression, if specified, must contain exactly " +"one '?' placeholder for the value." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Auxiliary database objects" +msgstr "Objets auxiliaires de la base de données " + +#. Tag: para +#, no-c-format +msgid "" +"Auxiliary database objects allow for the CREATE and DROP of arbitrary " +"database objects. In conjunction with Hibernate's schema evolution tools, " +"they have the ability to fully define a user schema within the Hibernate " +"mapping files. Although designed specifically for creating and dropping " +"things like triggers or stored procedures, any SQL command that can be run " +"via a <literal>java.sql.Statement.execute()</literal> method is valid (for " +"example, ALTERs, INSERTS, etc.). There are essentially two modes for " +"defining auxiliary database objects:" +msgstr "" +"Permettent les ordres CREATE et DROP d'objets arbitraire de la base de " +"données, en conjonction avec les outils Hibernate d'évolutions de schéma, " +"pour permettre de définir complètement un schéma utilisateur au sein des " +"fichiers de mappage Hibernate. Bien que conçu spécifiquement pour créer et " +"supprimer des objets tels que les triggers et les procédures stockées, en " +"réalité toute commande pouvant être exécutée via une méthode de " +"<literal>java.sql.Statement.execute()</literal> (ALTERs, INSERTS, etc) est " +"valable à cet endroit. Il y a principalement deux modes pour définir les " +"objets auxiliaires de base de données :" + +#. Tag: para +#, no-c-format +msgid "" +"The first mode is to explicitly list the CREATE and DROP commands in the " +"mapping file:" +msgstr "" +"Le premier mode est de lister explicitement les commandes CREATE et DROP " +"dans le fichier de mappage : " + +#. Tag: para +#, no-c-format +msgid "" +"The second mode is to supply a custom class that constructs the CREATE and " +"DROP commands. This custom class must implement the <literal>org.hibernate." +"mapping.AuxiliaryDatabaseObject</literal> interface." +msgstr "" +"Le second mode est de fournir une classe personnalisée qui sait comment " +"construire les commandes CREATE et DROP. Cette classe personnalisée doit " +"implémenter l'interface <literal>org.hibernate.mappage." +"AuxiliaryDatabaseObject</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Additionally, these database objects can be optionally scoped so that they " +"only apply when certain dialects are used." +msgstr "" +"De plus, ces objets de base de données peuvent être optionnellement traités " +"selon l'utilisation de dialectes particuliers. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/batch.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/batch.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/batch.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,482 @@ +# translation of batch.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: batch\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-04 17:03+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Batch processing" +msgstr "Traitement par lot" + +#. Tag: para +#, no-c-format +msgid "" +"A naive approach to inserting 100,000 rows in the database using Hibernate " +"might look like this:" +msgstr "" +"Une approche naïve pour insérer 100 000 lignes dans la base de données en " +"utilisant Hibernate ressemblerait à : " + +#. Tag: para +#, no-c-format +msgid "" +"This would fall over with an <literal>OutOfMemoryException</literal> " +"somewhere around the 50,000th row. That is because Hibernate caches all the " +"newly inserted <literal>Customer</literal> instances in the session-level " +"cache. In this chapter we will show you how to avoid this problem." +msgstr "" +"Ceci devrait s'écrouler avec une <literal>OutOfMemoryException</literal> " +"quelque part aux alentours de la 50 000ème ligne. C'est parce que Hibernate " +"cache toutes les instances de <literal>Customer</literal> nouvellement " +"insérées dans le cache de second niveau. Dans ce chapitre, nous allons vous " +"montrer comment éviter ce problème." + +#. Tag: para +#, no-c-format +msgid "" +"If you are undertaking batch processing you will need to enable the use of " +"JDBC batching. This is absolutely essential if you want to achieve optimal " +"performance. Set the JDBC batch size to a reasonable number (10-50, for " +"example):" +msgstr "" +"Dans ce chapitre nous montrerons comment éviter ce problème. Mais tout " +"d'abord, si vous faites des traitements par lot, il est absolument " +"indispensable d'activer l'utilisation des lots JDBC, pour obtenir des " +"performances raisonnables. Configurez la taille du lot JDBC à un nombre " +"raisonnable (disons, 10-50) : " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate disables insert batching at the JDBC level transparently if you " +"use an <literal>identity</literal> identifier generator." +msgstr "" +"Notez que Hibernate désactive, de manière transparente, l'insertion par lot " +"au niveau JDBC si vous utilisez un générateur d'identifiant de type " +"<literal>identity</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"You can also do this kind of work in a process where interaction with the " +"second-level cache is completely disabled:" +msgstr "" +"Vous désirez peut-être effectuer ce genre de tâche dans un traitement où " +"l'interaction avec le cache de second niveau est complètement désactivée :" + +#. Tag: para +#, no-c-format +msgid "" +"However, this is not absolutely necessary, since we can explicitly set the " +"<literal>CacheMode</literal> to disable interaction with the second-level " +"cache." +msgstr "" +"Toutefois ce n'est pas absolument nécessaire puisque nous pouvons configurer " +"le <literal>CacheMode</literal> de façon à désactiver l'interaction avec le " +"cache de second niveau." + +#. Tag: title +#, no-c-format +msgid "Batch inserts" +msgstr "Insertions en lot" + +#. Tag: para +#, no-c-format +msgid "" +"When making new objects persistent <literal>flush()</literal> and then " +"<literal>clear()</literal> the session regularly in order to control the " +"size of the first-level cache." +msgstr "" +"Lorsque vous rendez des nouveaux objets persistants, vous devez " +"régulièrement appeler <literal>flush()</literal> et puis <literal>clear()</" +"literal> sur la session, pour contrôler la taille du cache de premier " +"niveau. " + +#. Tag: title +#, no-c-format +msgid "Batch updates" +msgstr "Mise à jour des lots" + +#. Tag: para +#, no-c-format +msgid "" +"For retrieving and updating data, the same ideas apply. In addition, you " +"need to use <literal>scroll()</literal> to take advantage of server-side " +"cursors for queries that return many rows of data." +msgstr "" +"Pour récupérer et mettre à jour des données les mêmes idées s'appliquent. De " +"plus, vous devez utiliser <literal>scroll()</literal> pour tirer partie des " +"curseurs côté serveur pour les requêtes qui retournent beaucoup de lignes de " +"données. " + +#. Tag: title +#, no-c-format +msgid "The StatelessSession interface" +msgstr "L'interface StatelessSession" + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, Hibernate provides a command-oriented API that can be used " +"for streaming data to and from the database in the form of detached objects. " +"A <literal>StatelessSession</literal> has no persistence context associated " +"with it and does not provide many of the higher-level life cycle semantics. " +"In particular, a stateless session does not implement a first-level cache " +"nor interact with any second-level or query cache. It does not implement " +"transactional write-behind or automatic dirty checking. Operations performed " +"using a stateless session never cascade to associated instances. Collections " +"are ignored by a stateless session. Operations performed via a stateless " +"session bypass Hibernate's event model and interceptors. Due to the lack of " +"a first-level cache, Stateless sessions are vulnerable to data aliasing " +"effects. A stateless session is a lower-level abstraction that is much " +"closer to the underlying JDBC." +msgstr "" +"Alternativement, Hibernate fournit une API orientée commande qui peut être " +"utilisée avec des flux de données vers et en provenance de la base de " +"données sous la forme d'objets détachés. Une <literal>StatelessSession</" +"literal> n'a pas de contexte de persistance associé et ne fournit pas " +"beaucoup de sémantique de cycle de vie de haut niveau. En particulier, une " +"session sans état n'implémente pas de cache de premier niveau et n'interagit " +"pas non plus avec un cache de seconde niveau ou un cache de requêtes. Elle " +"n'implémente pas les transactions ou la vérification sale automatique " +"(automatic dirty checking). Les opérations réalisées avec une session sans " +"état ne sont jamais répercutées en cascade sur les instances associées. Les " +"collections sont ignorées par une session sans état. Les opérations " +"exécutées via une session sans état outrepassent le modèle d'événements de " +"Hibernate et les intercepteurs. Les sessions sans état sont vulnérables aux " +"effets de réplication des données, ceci est dû au manque de cache de premier " +"niveau. Une session sans état est une abstraction bas niveau, plus proche de " +"la couche JDBC sous-jacente. " + +#. Tag: para +#, no-c-format +msgid "" +"In this code example, the <literal>Customer</literal> instances returned by " +"the query are immediately detached. They are never associated with any " +"persistence context." +msgstr "" +"Notez que dans le code de l'exemple, les instances de <literal>Customer</" +"literal> retournées par la requête sont immédiatement détachées. Elles ne " +"sont jamais associées à un contexte de persistance. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>insert(), update()</literal> and <literal>delete()</literal> " +"operations defined by the <literal>StatelessSession</literal> interface are " +"considered to be direct database row-level operations. They result in the " +"immediate execution of a SQL <literal>INSERT, UPDATE</literal> or " +"<literal>DELETE</literal> respectively. They have different semantics to the " +"<literal>save(), saveOrUpdate()</literal> and <literal>delete()</literal> " +"operations defined by the <literal>Session</literal> interface." +msgstr "" +"Les opérations <literal>insert()</literal>, <literal>update()</literal> et " +"<literal>delete()</literal> définies par l'interface " +"<literal>StatelessSession</literal> sont considérées comme des opérations " +"d'accès direct aux lignes de la base de données, ce qui résulte en une " +"exécution immédiate du SQL <literal>INSERT</literal>, <literal>UPDATE</" +"literal> ou <literal>DELETE</literal> respectivement. Ainsi, elles ont des " +"sémantiques très différentes des opérations <literal>save()</literal>, " +"<literal>saveOrUpdate()</literal> et <literal>delete()</literal> définies " +"par l'interface <literal>Session</literal>." + +#. Tag: title +#, no-c-format +msgid "DML-style operations" +msgstr "Opérations de style DML" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"As already discussed, automatic and transparent object/relational mapping is " +"concerned with the management of the object state. The object state is " +"available in memory. This means that manipulating data directly in the " +"database (using the SQL <literal>Data Manipulation Language</literal> (DML) " +"the statements: <literal>INSERT</literal>, <literal>UPDATE</literal>, " +"<literal>DELETE</literal>) will not affect in-memory state. However, " +"Hibernate provides methods for bulk SQL-style DML statement execution that " +"is performed through the Hibernate Query Language (<link linkend=\"queryhql" +"\">HQL</link>)." +msgstr "" +"Comme mentionné auparavant, le mapping objet/relationnel automatique et " +"transparent s'intéresse à la gestion de l'état de l'objet. Ceci implique que " +"l'état de l'objet soit disponible en mémoire, c'est pourquoi manipuler (en " +"utilisant des expressions SQL du langage de manipulation de données - " +"<literal>Data Manipulation Language</literal> (DML) : les données " +"<literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</" +"literal>) directement dans la base n'affecteront pas l'état en mémoire. " +"Cependant, Hibernate fournit des méthodes pour l'exécution d'expression DML " +"de style SQL en gros, qui sont réalisées à travers le langage de requête de " +"Hibernate, Hibernate Query Language (<xref linkend=\"queryhql\"/> HQL)." + +#. Tag: para +#, no-c-format +msgid "" +"The pseudo-syntax for <literal>UPDATE</literal> and <literal>DELETE</" +"literal> statements is: <literal>( UPDATE | DELETE ) FROM? EntityName (WHERE " +"where_conditions)?</literal>." +msgstr "" +"La pseudo-syntaxe pour les expressions <literal>UPDATE</literal> et " +"<literal>DELETE</literal> est : <literal>( UPDATE | DELETE ) FROM? " +"EntityName (WHERE where_conditions)?</literal>. " + +#. Tag: para +#, no-c-format +msgid "Some points to note:" +msgstr "Certains points à noter :" + +#. Tag: para +#, no-c-format +msgid "In the from-clause, the FROM keyword is optional" +msgstr "Dans la clause from, le mot-clef FROM est optionnel" + +#. Tag: para +#, no-c-format +msgid "" +"There can only be a single entity named in the from-clause. It can, however, " +"be aliased. If the entity name is aliased, then any property references must " +"be qualified using that alias. If the entity name is not aliased, then it is " +"illegal for any property references to be qualified." +msgstr "" +"Il ne peut y avoir qu'une seule entité nommée dans la clause from ; elle " +"peut optionnellement avoir un alias. Si le nom de l'entité a un alias, alors " +"n'importe quelle référence de propriété doit être qualifiée en utilisant un " +"alias ; si le nom de l'entité n'a pas d'alias, il sera illégal pour " +"n'importe quelle référence de propriété d'être qualifiée." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"No <link linkend=\"queryhql-joins-forms\">joins</link>, either implicit or " +"explicit, can be specified in a bulk HQL query. Sub-queries can be used in " +"the where-clause, where the subqueries themselves may contain joins." +msgstr "" +"Aucune jointure <xref linkend=\"queryhql-joins-forms\" /> (implicite ou " +"explicite) ne peut être spécifiée dans une requête HQL en gros. Les sous-" +"requêtes peuvent être utilisées dans la clause where- ; les sous-requêtes, " +"elles-mêmes, peuvent contenir des jointures." + +#. Tag: para +#, no-c-format +msgid "The where-clause is also optional." +msgstr "La clause where- est aussi optionnelle." + +#. Tag: para +#, no-c-format +msgid "" +"As an example, to execute an HQL <literal>UPDATE</literal>, use the " +"<literal>Query.executeUpdate()</literal> method. The method is named for " +"those familiar with JDBC's <literal>PreparedStatement.executeUpdate()</" +"literal>:" +msgstr "" +"Par exemple, pour exécuter un HQL <literal>UPDATE</literal>, utilisez la " +"méthode <literal>Query.executeUpdate()</literal> (la méthode est données " +"pour ceux qui connaissent <literal>PreparedStatement.executeUpdate()</" +"literal> de JDBC) : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"In keeping with the EJB3 specification, HQL <literal>UPDATE</literal> " +"statements, by default, do not effect the <link linkend=\"mapping-" +"declaration-version\">version</link> or the <link linkend=\"mapping-" +"declaration-timestamp\">timestamp</link> property values for the affected " +"entities. However, you can force Hibernate to reset the <literal>version</" +"literal> or <literal>timestamp</literal> property values through the use of " +"a <literal>versioned update</literal>. This is achieved by adding the " +"<literal>VERSIONED</literal> keyword after the <literal>UPDATE</literal> " +"keyword." +msgstr "" +"Par défaut, les déclarations HQL <literal>UPDATE</literal>, n'affectent pas " +"la version <xref linkend=\"mapping-declaration-version\"/> ou les valeurs " +"<xref linkend=\"mapping-declaration-timestamp\" /> de propriétés timestamp " +"pour les entités concernées; ceci est compatible avec la spécification EJB3. " +"Toutefois, vous pouvez forcer Hibernate à mettre à jour les valeurs des " +"propriétés <literal>version</literal> ou <literal>timestamp</literal> en " +"utilisant le <literal>versioned update</literal>. Pour ce faire, ajoutez le " +"mot clé <literal>VERSIONED</literal> après le mot clé <literal>UPDATE</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Custom version types, <literal>org.hibernate.usertype.UserVersionType</" +"literal>, are not allowed in conjunction with a <literal>update versioned</" +"literal> statement." +msgstr "" +"Notez que les types personnalisés (<literal>org.hibernate.usertype." +"UserVersionType</literal>) ne sont pas permis en conjonction avec la " +"déclaration <literal>update versioned</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"To execute an HQL <literal>DELETE</literal>, use the same <literal>Query." +"executeUpdate()</literal> method:" +msgstr "" +"Pour exécuter un HQL <literal>DELETE</literal>, utilisez la même méthode " +"<literal>Query.executeUpdate()</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>int</literal> value returned by the <literal>Query.executeUpdate" +"()</literal> method indicates the number of entities effected by the " +"operation. This may or may not correlate to the number of rows effected in " +"the database. An HQL 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." +msgstr "" +"La valeur du <literal>int</literal> retourné par la méthode <literal>Query." +"executeUpdate()</literal> indique le nombre d'entités affectées par " +"l'opération. Considérez que cela peut ou non, corréler le nombre de lignes " +"affectées dans la base de données. Une opération HQL pourrait entraîner " +"l'exécution de multiples expressions SQL réelles, pour des classes filles " +"mappées par jointure (join-subclass), par exemple. Le nombre retourné " +"indique le nombre d'entités réelles affectées par l'expression. Si on " +"revient à l'exemple de la classe fille mappée par jointure, un effacement " +"d'une des classes filles peut réellement entraîner des suppressions pas " +"seulement dans la table à laquelle la classe fille est mappée, mais " +"également dans la table \"racine\" et potentillement dans les tables des " +"classes filles plus bas dans la hiérarchie d'héritage. " + +#. Tag: para +#, no-c-format +msgid "" +"The pseudo-syntax for <literal>INSERT</literal> statements is: " +"<literal>INSERT INTO EntityName properties_list select_statement</literal>. " +"Some points to note:" +msgstr "" +"La pseudo-syntaxe pour l'expression <literal>INSERT</literal> est : " +"<literal>INSERT INTO EntityName properties_list select_statement</literal>. " +"Quelques points sont à noter :" + +#. Tag: para +#, no-c-format +msgid "" +"Only the INSERT INTO ... SELECT ... form is supported; not the INSERT " +"INTO ... VALUES ... form." +msgstr "" +"Seule la forme INSERT INTO ... SELECT ... est supportée ; pas la forme " +"INSERT INTO ... VALUES ... ." + +#. Tag: para +#, no-c-format +msgid "" +"The properties_list is analogous to the <literal>column specification</" +"literal> in the SQL <literal>INSERT</literal> statement. For entities " +"involved in mapped inheritance, only properties directly defined on that " +"given class-level can be used in the properties_list. Superclass properties " +"are not allowed and subclass properties do not make sense. In other words, " +"<literal>INSERT</literal> statements are inherently non-polymorphic." +msgstr "" +"La properties_list est analogue à la <literal>column speficiation</literal> " +"dans la déclaration SQL <literal>INSERT</literal>. Pour les entités " +"impliquées dans un héritage mappé, seules les propriétés directement " +"définies à ce niveau de classe donné peuvent être utilisées dans " +"properties_list. Les propriétés de la classe mère ne sont pas permises ; et " +"les propriétés des classes filles n'ont pas de sens. En d'autres termes, les " +"expressions <literal>INSERT</literal> sont par nature non polymorphiques. " + +#. Tag: para +#, no-c-format +msgid "" +"select_statement can be any valid HQL select query, with the caveat that the " +"return types must match the types expected by the insert. Currently, this is " +"checked during query compilation rather than allowing the check to relegate " +"to the database. This might, however, cause problems between Hibernate " +"<literal>Type</literal>s which are <emphasis>equivalent</emphasis> as " +"opposed to <emphasis>equal</emphasis>. This might cause issues with " +"mismatches between a property defined as a <literal>org.hibernate.type." +"DateType</literal> and a property defined as a <literal>org.hibernate.type." +"TimestampType</literal>, even though the database might not make a " +"distinction or might be able to handle the conversion." +msgstr "" +"select_statement peut être n'importe quelle requête de sélection HQL valide, " +"avec l'avertissement que les types de retour doivent correspondre aux types " +"attendus par l'insertion. Actuellement, cela est vérifié durant la " +"compilation de la requête plutôt que de reléguer la vérification à la base " +"de données. Notez cependant que cela pourrait poser des problèmes entre les " +"<literal>Type</literal>s de Hibernate qui sont <emphasis>équivalents</" +"emphasis> contrairement à <emphasis>égaux</emphasis>. Cela pourrait poser " +"des problèmes avec des disparités entre une propriété définie comme un " +"<literal>org.hibernate.type.DateType</literal> et une propriété définie " +"comme un <literal>org.hibernate.type.TimestampType</literal>, bien que la " +"base de données ne fasse pas de distinction ou ne soit pas capable de gérer " +"la conversion." + +#. Tag: para +#, no-c-format +msgid "" +"For the id property, the insert statement gives you two options. You can " +"either explicitly specify the id property in the properties_list, in which " +"case its value is taken from the corresponding select expression, or omit it " +"from the properties_list, in which case a generated value is used. This " +"latter option is only available when using id generators that operate in the " +"database; attempting to use this option with any \"in memory\" type " +"generators will cause an exception during parsing. For the purposes of this " +"discussion, in-database generators are considered to be <literal>org." +"hibernate.id.SequenceGenerator</literal> (and its subclasses) and any " +"implementers of <literal>org.hibernate.id.PostInsertIdentifierGenerator</" +"literal>. The most notable exception here is <literal>org.hibernate.id." +"TableHiLoGenerator</literal>, which cannot be used because it does not " +"expose a selectable way to get its values." +msgstr "" +"Pour la propriété id, l'expression d'insertion vous donne deux options. Vous " +"pouvez soit spécifier explicitement la propriété id dans properties_list " +"(auquel cas sa valeur est extraite de l'expression de sélection " +"correspondante), soit l'omettre de properties_list (auquel cas une valeur " +"générée est utilisée). Cette dernière option est seulement disponible si " +"vous utilisez le générateur d'identifiant qui opère dans la base de " +"données ; tenter d'utiliser cette option avec n'importe quel type de " +"générateur \"en mémoire\" causera une exception durant l'analyse. Notez que " +"pour les buts de cette discussion, les générateurs \"en base\" sont " +"considérés comme <literal>org.hibernate.id.SequenceGenerator</literal> (et " +"ses classes filles) et n'importe quelles implémentations de <literal>org." +"hibernate.id.PostInsertIdentifierGenerator</literal>. L'exception la plus " +"notable ici est <literal>org.hibernate.id.TableHiLoGenerator</literal>, qui " +"ne peut pas être utilisée parce qu'elle ne propose pas de moyen d'obtenir " +"ses valeurs par un select. " + +#. Tag: para +#, no-c-format +msgid "" +"For properties mapped as either <literal>version</literal> or " +"<literal>timestamp</literal>, the insert statement gives you two options. " +"You can either specify the property in the properties_list, in which case " +"its value is taken from the corresponding select expressions, or omit it " +"from the properties_list, in which case the <literal>seed value</literal> " +"defined by the <literal>org.hibernate.type.VersionType</literal> is used." +msgstr "" +"Pour des propriétés mappées comme <literal>version</literal> ou " +"<literal>timestamp</literal>, l'expression d'insertion vous donne deux " +"options. Vous pouvez soit spécifier la propriété dans properties_list " +"(auquel cas sa valeur est extraite des expressions select correspondantes), " +"soit l'omettre de properties_list (auquel cas la <literal>seed value</" +"literal> définie par le <literal>org.hibernate.type.VersionType</literal> " +"est utilisée). " + +#. Tag: para +#, no-c-format +msgid "" +"The following is an example of an HQL <literal>INSERT</literal> statement " +"execution:" +msgstr "" +"Un exemple d'exécution d'une expression HQL <literal>INSERT</literal> : " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/best_practices.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/best_practices.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/best_practices.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,437 @@ +# translation of best_practices.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: best_practices\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2009-11-10 16:06+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Best Practices" +msgstr "Meilleures pratiques" + +#. Tag: term +#, no-c-format +msgid "" +"Write fine-grained classes and map them using <literal>&lt;component&gt;</" +"literal>:" +msgstr "" +"Découpez finement vos classes et mappez-les en utilisant <literal>&lt;" +"component&gt;</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Use an <literal>Address</literal> class to encapsulate <literal>street</" +"literal>, <literal>suburb</literal>, <literal>state</literal>, " +"<literal>postcode</literal>. This encourages code reuse and simplifies " +"refactoring." +msgstr "" +"Utilisez une classe <literal>Address</literal> pour résumer <literal>street</" +"literal>, <literal>suburb</literal>, <literal>state</literal>, " +"<literal>postcode</literal>. Ceci permet la réutilisation du code et " +"simplifie la maintenance. " + +#. Tag: term +#, no-c-format +msgid "Declare identifier properties on persistent classes:" +msgstr "Déclarez des propriétés d'identifiants dans les classes persistantes :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate makes identifier properties optional. There are a range of reasons " +"why you should use them. We recommend that identifiers be 'synthetic', that " +"is, generated with no business meaning." +msgstr "" +"Hibernate rend les propriétés d'identifiants optionnelles. Il est recommandé " +"de les utiliser pour de nombreuses raisons. Utilisez les identifiants comme " +"'synthetic' (générés, et sans connotation métier)." + +#. Tag: term +#, no-c-format +msgid "Identify natural keys:" +msgstr "Identifiez les clefs naturelles :" + +#. Tag: para +#, no-c-format +msgid "" +"Identify natural keys for all entities, and map them using <literal>&lt;" +"natural-id&gt;</literal>. Implement <literal>equals()</literal> and " +"<literal>hashCode()</literal> to compare the properties that make up the " +"natural key." +msgstr "" +"Identifiez les clefs naturelles pour toutes les entités, et mappez-les avec " +"<literal>&lt;natural-id&gt;</literal>. Implémentez <literal>equals()</" +"literal> et <literal>hashCode()</literal> pour comparer les propriétés qui " +"composent la clef naturelle. " + +#. Tag: term +#, no-c-format +msgid "Place each class mapping in its own file:" +msgstr "Placez chaque mapping de classe dans son propre fichier :" + +#. Tag: para +#, no-c-format +msgid "" +"Do not use a single monolithic mapping document. Map <literal>com.eg.Foo</" +"literal> in the file <literal>com/eg/Foo.hbm.xml</literal>. This makes " +"sense, particularly in a team environment." +msgstr "" +"N'utilisez pas un unique document de mapping. Mappez <literal>com.eg.Foo</" +"literal> dans le fichier <literal>com/eg/Foo.hbm.xml</literal>. Cela prend " +"tout son sens lors d'un travail en équipe. " + +#. Tag: term +#, no-c-format +msgid "Load mappings as resources:" +msgstr "Chargez les mappings comme des ressources :" + +#. Tag: para +#, no-c-format +msgid "Deploy the mappings along with the classes they map." +msgstr "Déployez les mappings en même temps que les classes qu'ils mappent." + +#. Tag: term +#, no-c-format +msgid "Consider externalizing query strings:" +msgstr "Pensez à externaliser les chaînes de requêtes :" + +#. Tag: para +#, no-c-format +msgid "" +"This is recommended if your queries call non-ANSI-standard SQL functions. " +"Externalizing the query strings to mapping files will make the application " +"more portable." +msgstr "" +"Ceci est une bonne habitude si vos requêtes appellent des fonctions SQL qui " +"ne sont pas au standard ANSI. Cette externalisation des chaînes de requête " +"dans les fichiers de mapping rendra votre application plus portable. " + +#. Tag: term +#, no-c-format +msgid "Use bind variables." +msgstr "Utilisez les variables bindées." + +#. Tag: para +#, no-c-format +msgid "" +"As in JDBC, always replace non-constant values by \"?\". Do not use string " +"manipulation to bind a non-constant value in a query. You should also " +"consider using named parameters in queries." +msgstr "" +"Comme dans JDBC, remplacez toujours les valeurs non constantes par \"?\". " +"N'utilisez jamais la manipulation des chaînes de caractères pour lier des " +"valeurs non constantes dans une requête ! Encore mieux, utilisez les " +"paramètres nommés dans les requêtes." + +#. Tag: term +#, no-c-format +msgid "Do not manage your own JDBC connections:" +msgstr "Ne gérez pas vous-même les connexions JDBC :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate allows the application to manage JDBC connections, but his " +"approach should be considered a last-resort. If you cannot use the built-in " +"connection providers, consider providing your own implementation of " +"<literal>org.hibernate.connection.ConnectionProvider</literal>." +msgstr "" +"Hibernate permet à l'application de gérer les connexions JDBC. Vous ne " +"devriez gérer vos connexions qu'en dernier recours. Si vous ne pouvez pas " +"utiliser les systèmes de connexions livrés, considérez la fourniture de " +"votre propre implémentation de <literal>org.hibernate.connection." +"ConnectionProvider</literal>. " + +#. Tag: term +#, no-c-format +msgid "Consider using a custom type:" +msgstr "Considérez l'utilisation de types personnalisés :" + +#. Tag: para +#, no-c-format +msgid "" +"Suppose you have a Java type from a library that needs to be persisted but " +"does not provide the accessors needed to map it as a component. You should " +"consider implementing <literal>org.hibernate.UserType</literal>. This " +"approach frees the application code from implementing transformations to/" +"from a Hibernate type." +msgstr "" +"Supposez que vous ayez un type Java, de telle bibliothèque, qui a besoin " +"d'être persisté mais qui ne fournit pas les accesseurs nécessaires pour le " +"mapper comme composant. Vous devriez implémenter <literal>org.hibernate." +"UserType</literal>. Cette approche évite au code de l'application, " +"l'implémentation de transformations vers / depuis les types Hibernate. " + +#. Tag: term +#, no-c-format +msgid "Use hand-coded JDBC in bottlenecks:" +msgstr "Utilisez du JDBC pur dans les goulots d'étranglement :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"In performance-critical areas of the system, some kinds of operations might " +"benefit from direct JDBC. Do not assume, however, that JDBC is necessarily " +"faster. Please wait until you <emphasis>know</emphasis> something is a " +"bottleneck. If you need to use direct JDBC, you can open a Hibernate " +"<literal>Session</literal>, wrap your JDBC operation as a <literal>org." +"hibernate.jdbc.Work</literal> object and using that JDBC connection. This " +"way you can still use the same transaction strategy and underlying " +"connection provider." +msgstr "" +"En ce qui concerne les performances dans certaines parties critiques de " +"votre système, quelques opérations peuvent tirer partie d'un appel JDBC " +"natif. Mais attendez de <emphasis>savoir</emphasis> que c'est un goulet " +"d'étranglement. Ne supposez jamais qu'un appel JDBC sera forcément plus " +"rapide. Si vous devez utiliser JDBC directement, ouvrez une " +"<literal>Session</literal> Hibernate et utilisez la connexion SQL sous-" +"jacente. Ainsi vous pourrez utiliser la même stratégie de transation et la " +"même gestion des connexions. " + +#. Tag: term +#, no-c-format +msgid "Understand <literal>Session</literal> flushing:" +msgstr "Comprenez le flush de <literal>Session</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Sometimes the Session synchronizes its persistent state with the database. " +"Performance will be affected if this process occurs too often. You can " +"sometimes minimize unnecessary flushing by disabling automatic flushing, or " +"even by changing the order of queries and other operations within a " +"particular transaction." +msgstr "" +"De temps en temps la Session synchronise ses états persistants avec la base " +"de données. Les performances seront affectées si ce processus arrive trop " +"souvent. Vous pouvez parfois minimiser les flush non nécessaires en " +"désactivant le flush automatique ou même en changeant l'ordre des requêtes " +"et autres opérations effectuées dans une transaction particulière. " + +#. Tag: term +#, no-c-format +msgid "In a three tiered architecture, consider using detached objects:" +msgstr "" +"Dans une architecture à trois couches, vous pouvez utilisez des objets " +"détachés :" + +#. Tag: para +#, no-c-format +msgid "" +"When using a servlet/session bean architecture, you can pass persistent " +"objects loaded in the session bean to and from the servlet/JSP layer. Use a " +"new session to service each request. Use <literal>Session.merge()</literal> " +"or <literal>Session.saveOrUpdate()</literal> to synchronize objects with the " +"database." +msgstr "" +"Quand vous utilisez une architecture à base de servlet / session bean, vous " +"pouvez passer des objets chargés dans le bean session vers et depuis la " +"couche servlet / JSP. Utilisez une nouvelle session pour traiter chaque " +"requête. Utilisez <literal>Session.merge()</literal> ou <literal>Session." +"saveOrUpdate()</literal> pour synchroniser les objets avec la base de " +"données. " + +#. Tag: term +#, no-c-format +msgid "In a two tiered architecture, consider using long persistence contexts:" +msgstr "" +"Dans une architecture à deux couches, pensez à utiliser les contextes de " +"persistance longue :" + +#. Tag: para +#, no-c-format +msgid "" +"Database Transactions have to be as short as possible for best scalability. " +"However, it is often necessary to implement long running " +"<emphasis>application transactions</emphasis>, a single unit-of-work from " +"the point of view of a user. An application transaction might span several " +"client request/response cycles. It is common to use detached objects to " +"implement application transactions. An appropriate alternative in a two " +"tiered architecture, is to maintain a single open persistence contact " +"session for the whole life cycle of the application transaction. Then simply " +"disconnect from the JDBC connection at the end of each request and reconnect " +"at the beginning of the subsequent request. Never share a single session " +"across more than one application transaction or you will be working with " +"stale data." +msgstr "" +"Les transactions de bases de données doivent être aussi courtes que possible " +"pour une meilleure extensibilité. Cependant, il est souvent nécessaire " +"d'implémenter de longues <emphasis>transactions applicatives</emphasis>, une " +"simple unité de travail du point de vue de l'utilisateur. Une transaction " +"applicative peut s'étaler sur plusieurs cycles de requêtes/réponses du " +"client. Il est commun d'utiliser des objets détachés pour implémenter des " +"transactions applicatives. Une alternative, extrêmement appropriée dans une " +"architecture à deux couches, est de maintenir un seul contact de persistance " +"ouvert (session) pour toute la durée de vie de la transaction applicative et " +"simplement se déconnecter de la connexion JDBC à la fin de chaque requête, " +"et se reconnecter au début de la requête suivante. Ne partagez jamais une " +"seule session avec plus d'une transaction applicative, ou bien vous " +"travaillerez avec des données périmées. " + +#. Tag: term +#, no-c-format +msgid "Do not treat exceptions as recoverable:" +msgstr "Considérez que les exceptions ne sont pas rattrapables :" + +#. Tag: para +#, no-c-format +msgid "" +"This is more of a necessary practice than a \"best\" practice. When an " +"exception occurs, roll back the <literal>Transaction</literal> and close the " +"<literal>Session</literal>. If you do not do this, Hibernate cannot " +"guarantee that in-memory state accurately represents the persistent state. " +"For example, do not use <literal>Session.load()</literal> to determine if an " +"instance with the given identifier exists on the database; use " +"<literal>Session.get()</literal> or a query instead." +msgstr "" +"Il s'agit plus d'une pratique obligatoire que d'une \"meilleure pratique\". " +"Quand une exception intervient, il faut faire un rollback de la " +"<literal>Transaction</literal> et fermer la <literal>Session</literal>. " +"Sinon, Hibernate ne peut garantir l'intégrité des états persistants en " +"mémoire. En particulier, n'utilisez pas <literal>Session.load()</literal> " +"pour déterminer si une instance avec l'identifiant donné existe en base de " +"données, à la place utilisez <literal>Session.get()</literal> ou une " +"requête. " + +#. Tag: term +#, no-c-format +msgid "Prefer lazy fetching for associations:" +msgstr "Préférez le chargement différé des associations :" + +#. Tag: para +#, no-c-format +msgid "" +"Use eager fetching sparingly. Use proxies and lazy collections for most " +"associations to classes that are not likely to be completely held in the " +"second-level cache. For associations to cached classes, where there is an a " +"extremely high probability of a cache hit, explicitly disable eager fetching " +"using <literal>lazy=\"false\"</literal>. When join fetching is appropriate " +"to a particular use case, use a query with a <literal>left join fetch</" +"literal>." +msgstr "" +"Utilisez le chargement complet avec modération. Utilisez les proxies et les " +"collections chargées tardivement pour la plupart des associations vers des " +"classes qui ne sont pas susceptibles d'être complètement retenues dans le " +"cache de second niveau. Pour les associations de classes en cache, où il y a " +"une forte probabilité que l'élément soit en cache, désactivez explicitement " +"le chargement par jointures ouvertes en utilisant <literal>outer-join=\"false" +"\"</literal>. Lorsqu'un chargement par jointure ouverte est approprié pour " +"un cas d'utilisation particulier, utilisez une requête avec un <literal>left " +"join fetch</literal>. " + +#. Tag: term +#, no-c-format +msgid "" +"Use the <emphasis>open session in view</emphasis> pattern, or a disciplined " +"<emphasis>assembly phase</emphasis> to avoid problems with unfetched data:" +msgstr "" +"Utilisez le pattern <emphasis>d'une ouverture de session dans une vue</" +"emphasis>, ou une <emphasis>phase d'assemblage</emphasis> disciplinée pour " +"éviter des problèmes avec des données non rapatriées :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate frees the developer from writing tedious <emphasis>Data Transfer " +"Objects</emphasis> (DTO). In a traditional EJB architecture, DTOs serve dual " +"purposes: first, they work around the problem that entity beans are not " +"serializable; second, they implicitly define an assembly phase where all " +"data to be used by the view is fetched and marshalled into the DTOs before " +"returning control to the presentation tier. Hibernate eliminates the first " +"purpose. Unless you are prepared to hold the persistence context (the " +"session) open across the view rendering process, you will still need an " +"assembly phase. Think of your business methods as having a strict contract " +"with the presentation tier about what data is available in the detached " +"objects. This is not a limitation of Hibernate. It is a fundamental " +"requirement of safe transactional data access." +msgstr "" +"Hibernate libère les développeurs de l'écriture fastidieuse des " +"<emphasis>objets de transfert de données </emphasis> (DTO). Dans une " +"architecture EJB traditionnelle, les DTO ont deux buts : premièrement, ils " +"contournent le problème des beans entités qui ne sont pas sérialisables ; " +"deuxièmement, ils définissent implicitement une phase d'assemblage où toutes " +"les données utilisées par la vue sont rapatriées et organisées dans les DTO " +"avant de retourner sous le contrôle de la couche de présentation. Hibernate " +"élimine le premier but. Cependant, vous aurez encore besoin d'une phase " +"d'assemblage (pensez à vos méthodes métier comme ayant un contrat strict " +"avec la couche de présentation, en ce qui concerne les données disponibles " +"dans les objets détachés) à moins que vous soyez préparés à garder le " +"contexte de persistance (la session) ouvert à travers tout le processus de " +"rendu de la vue. Ceci ne représente pas une limitation de Hibernate! Au " +"contraire c'est une exigence fondamentale d'un accès sécurisé aux données " +"transactionnelles. " + +#. Tag: term +#, no-c-format +msgid "Consider abstracting your business logic from Hibernate:" +msgstr "Pensez à abstraire votre logique métier d'Hibernate :" + +#. Tag: para +#, no-c-format +msgid "" +"Hide Hibernate data-access code behind an interface. Combine the " +"<emphasis>DAO</emphasis> and <emphasis>Thread Local Session</emphasis> " +"patterns. You can even have some classes persisted by handcoded JDBC " +"associated to Hibernate via a <literal>UserType</literal>. This advice is, " +"however, intended for \"sufficiently large\" applications. It is not " +"appropriate for an application with five tables." +msgstr "" +"Cachez le mécanisme d'accès aux données (Hibernate) derrière une interface. " +"Combinez les modèles <emphasis>DAO</emphasis> et <emphasis>Thread Local " +"Session</emphasis>. Vous pouvez même avoir quelques classes persistées par " +"du JDBC pur, associées à Hibernate via un <literal>UserType</literal> (ce " +"conseil est valable pour des applications de taille respectables ; il n'est " +"pas valable pour une application avec cinq tables). " + +#. Tag: term +#, no-c-format +msgid "Do not use exotic association mappings:" +msgstr "N'utilisez pas d'associations de mapping exotiques :" + +#. Tag: para +#, no-c-format +msgid "" +"Practical test cases for real many-to-many associations are rare. Most of " +"the time you need additional information stored in the \"link table\". In " +"this case, it is much better to use two one-to-many associations to an " +"intermediate link class. In fact, most associations are one-to-many and many-" +"to-one. For this reason, you should proceed cautiously when using any other " +"association style." +msgstr "" +"Les utilisations appropriées de vraies associations plusieurs-à-plusieurs " +"sont rares. La plupart du temps vous avez besoin d'informations " +"additionnelles stockées dans la table d'association. Dans ce cas, il est " +"préférable d'utiliser deux associations un-à-plusieurs vers une classe de " +"liaisons intermédiaire. En fait, nous pensons que la plupart des " +"associations sont de type un-à-plusieurs ou plusieurs-à-un, vous devez être " +"très prudent lorsque vous utilisez toute autre association et vous demander " +"si c'est vraiment nécessaire. " + +#. Tag: term +#, no-c-format +msgid "Prefer bidirectional associations:" +msgstr "Préférez les associations bidirectionnelles :" + +#. Tag: para +#, no-c-format +msgid "" +"Unidirectional associations are more difficult to query. In a large " +"application, almost all associations must be navigable in both directions in " +"queries." +msgstr "" +"Les associations unidirectionnelles sont plus difficiles à questionner. Dans " +"une grande application, la plupart des associations devraient être " +"navigables dans les deux directions dans les requêtes. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/bibliography.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/bibliography.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/bibliography.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,49 @@ +# Language fr-FR translations for PACKAGE package. +# Automatically generated, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-04T04:51:21\n" +"PO-Revision-Date: 2009-07-14 19:55+0000\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#, no-c-format +msgid "References" +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Patterns of Enterprise Application Architecture" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Martin" +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Java Persistence with Hibernate" +msgstr "" + +#. Tag: subtitle +#, no-c-format +msgid "Second Edition of Hibernate in Action" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Christian" +msgstr "" + +#. Tag: firstname +#, no-c-format +msgid "Gavin" +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/collection_mapping.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/collection_mapping.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/collection_mapping.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1249 @@ +# translation of collection_mapping.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: collection_mapping\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:34\n" +"PO-Revision-Date: 2010-01-05 08:54+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Collection mapping" +msgstr "Mapper une collection " + +#. Tag: title +#, no-c-format +msgid "Persistent collections" +msgstr "Collections persistantes" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate requires that persistent collection-valued fields be declared as " +"an interface type. For example:" +msgstr "" +"Hibernate requiert que les champs contenant des collections persistantes " +"soient déclarés comme des types d'interface, par exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"The actual interface might be <literal>java.util.Set</literal>, " +"<literal>java.util.Collection</literal>, <literal>java.util.List</literal>, " +"<literal>java.util.Map</literal>, <literal>java.util.SortedSet</literal>, " +"<literal>java.util.SortedMap</literal> or anything you like (\"anything you " +"like\" means you will have to write an implementation of <literal>org." +"hibernate.usertype.UserCollectionType</literal>.)" +msgstr "" +"L'interface réelle peut être <literal>java.util.Set</literal>, <literal>java." +"util.Collection</literal>, <literal>java.util.List</literal>, <literal>java." +"util.Map</literal>, <literal>java.util.SortedSet</literal>, <literal>java." +"util.SortedMap</literal> ou n'importe quoi d'autre ! (Où \"n'importe quoi " +"d'autre\" signifie que vous devrez écrire une implémentation de <literal>org." +"hibernate.usertype.UserCollectionType</literal>.)" + +#. Tag: para +#, no-c-format +msgid "" +"Notice how the instance variable was initialized with an instance of " +"<literal>HashSet</literal>. This is the best way to initialize collection " +"valued properties of newly instantiated (non-persistent) instances. When you " +"make the instance persistent, by calling <literal>persist()</literal> for " +"example, Hibernate will actually replace the <literal>HashSet</literal> with " +"an instance of Hibernate's own implementation of <literal>Set</literal>. Be " +"aware of the following errors:" +msgstr "" +"Notez comment nous avons initialisé la variable d'instance avec une instance " +"de <literal>HashSet</literal>. C'est le meilleur moyen pour initialiser les " +"collections d'instances nouvellement créées (non persistantes). Quand nous " +"fabriquons l'instance persistante - en appelant <literal>persist()</" +"literal>, par exemple - Hibernate remplacera réellement le <literal>HashSet</" +"literal> par une instance d'une implémentation propre à Hibernate de " +"<literal>Set</literal>. Prenez garde aux erreurs suivantes : " + +#. Tag: para +#, no-c-format +msgid "" +"The persistent collections injected by Hibernate behave like " +"<literal>HashMap</literal>, <literal>HashSet</literal>, <literal>TreeMap</" +"literal>, <literal>TreeSet</literal> or <literal>ArrayList</literal>, " +"depending on the interface type." +msgstr "" +"Les collections persistantes injectées par Hibernate se comportent de la " +"même manière que <literal>HashMap</literal>, <literal>HashSet</literal>, " +"<literal>TreeMap</literal>, <literal>TreeSet</literal> ou " +"<literal>ArrayList</literal>, selon le type de l'interface. " + +#. Tag: para +#, no-c-format +msgid "" +"Collections instances have the usual behavior of value types. They are " +"automatically persisted when referenced by a persistent object and are " +"automatically deleted when unreferenced. If a collection is passed from one " +"persistent object to another, its elements might be moved from one table to " +"another. Two entities cannot share a reference to the same collection " +"instance. Due to the underlying relational model, collection-valued " +"properties do not support null value semantics. Hibernate does not " +"distinguish between a null collection reference and an empty collection." +msgstr "" +"Les instances des collections ont le comportement habituel des types de " +"valeurs. Elles sont automatiquement persistées quand elles sont référencées " +"par un objet persistant et automatiquement effacées quand elles sont " +"déréférencées. Si une collection est passée d'un objet persistant à un " +"autre, ses éléments peuvent être déplacés d'une table à une autre. Deux " +"entités ne peuvent pas partager une référence vers une même instance de " +"collection. Dû au modèle relationnel sous-jacent, les propriétés contenant " +"des collections ne supportent pas la sémantique de la valeur null ; " +"Hibernate ne fait pas de distinction entre une référence de collection nulle " +"et une collection vide. " + +#. Tag: para +#, no-c-format +msgid "" +"Use persistent collections the same way you use ordinary Java collections. " +"However, please ensure you understand the semantics of bidirectional " +"associations (these are discussed later)." +msgstr "" +"Ne vous en souciez pas trop. Utilisez les collections persistantes de la " +"même manière que vous utilisez des collections Java ordinaires. Assurez-vous " +"de comprendre la sémantique des associations bidirectionnelles (traitée plus " +"loin). " + +#. Tag: title +#, no-c-format +msgid "Collection mappings" +msgstr "Mapper une collection" + +#. Tag: para +#, no-c-format +msgid "" +"There are quite a range of mappings that can be generated for collections " +"that cover many common relational models. We suggest you experiment with the " +"schema generation tool so that you understand how various mapping " +"declarations translate to database tables." +msgstr "" +"Il y a une grande variété de mappages qui peuvent être générés pour les " +"collections, couvrant beaucoup de nombreux modèles relationnels communs. " +"Nous vous suggérons d'expérimenter avec l'outil de génération de schéma pour " +"cerner comment les différentes déclarations de mappage se traduisent vers " +"des tables de bases de données. " + +#. Tag: para +#, no-c-format +msgid "" +"The Hibernate mapping element used for mapping a collection depends upon the " +"type of interface. For example, a <literal>&lt;set&gt;</literal> element is " +"used for mapping properties of type <literal>Set</literal>." +msgstr "" +"L'élément de mappage d'Hibernate utilisé pour mapper une collection dépend " +"du type de l'interface. Par exemple, un élément <literal>&lt;set&gt;</" +"literal> est utilisé pour mapper des propriétés de type <literal>Set</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Apart from <literal>&lt;set&gt;</literal>, there is also <literal>&lt;" +"list&gt;</literal>, <literal>&lt;map&gt;</literal>, <literal>&lt;bag&gt;</" +"literal>, <literal>&lt;array&gt;</literal> and <literal>&lt;primitive-" +"array&gt;</literal> mapping elements. The <literal>&lt;map&gt;</literal> " +"element is representative:" +msgstr "" +"À part <literal>&lt;set&gt;</literal>, il y aussi les éléments de mappage " +"<literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</literal>, " +"<literal>&lt;bag&gt;</literal>, <literal>&lt;array&gt;</literal> et " +"<literal>&lt;primitive-array&gt;</literal>. L'élément <literal>&lt;map&gt;</" +"literal> est représentatif : " + +#. Tag: para +#, no-c-format +msgid "<literal>name</literal>: the collection property name" +msgstr "" +"<literal>name</literal> : le nom de la propriété contenant la collection " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>table</literal> (optional - defaults to property name): the name of " +"the collection table. It is not used for one-to-many associations." +msgstr "" +"<literal>table</literal> (optionnel - par défaut = nom de la propriété) : le " +"nom de la table de la collection (non utilisé pour les associations un-à-" +"plusieurs) " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>schema</literal> (optional): the name of a table schema to override " +"the schema declared on the root element" +msgstr "" +"<literal>schema</literal> (optionnel) : le nom du schéma pour surcharger le " +"schéma déclaré dans l'élément racine " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>lazy</literal> (optional - defaults to <literal>true</literal>): " +"disables lazy fetching and specifies that the association is always eagerly " +"fetched. It can also be used to enable \"extra-lazy\" fetching where most " +"operations do not initialize the collection. This is suitable for large " +"collections." +msgstr "" +"<literal>lazy</literal> (optionnel - par défaut = <literal>true</literal>) : " +"peut être utilisé pour désactiver l'initialisation tardive et spécifier que " +"l'association est toujours rapportée, ou pour activer la récupération extra-" +"paresseuse (extra-lazy) où la plupart des opérations n'initialisent pas la " +"collection (approprié pour de très grosses collections)." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>inverse</literal> (optional - defaults to <literal>false</" +"literal>): marks this collection as the \"inverse\" end of a bidirectional " +"association." +msgstr "" +"<literal>inverse</literal> (optionnel - par défaut = <literal>false</" +"literal>) : définit cette collection comme l'extrémité \"inverse\" de " +"l'association bidirectionnelle." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>cascade</literal> (optional - defaults to <literal>none</literal>): " +"enables operations to cascade to child entities." +msgstr "" +"<literal>cascade</literal> (optionnel - par défaut = <literal>none</" +"literal>) : active les opérations de cascade vers les entités filles." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>sort</literal> (optional): specifies a sorted collection with " +"<literal>natural</literal> sort order or a given comparator class." +msgstr "" +"<literal>sort</literal> (optionnel) : spécifie une collection triée via un " +"ordre de tri <literal>naturel</literal>, ou via une classe comparateur " +"donnée." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>order-by</literal> (optional, JDK1.4 only): specifies a table " +"column or columns that define the iteration order of the <literal>Map</" +"literal>, <literal>Set</literal> or bag, together with an optional " +"<literal>asc</literal> or <literal>desc</literal>." +msgstr "" +"<literal>order-by</literal> (optionnel, seulement à partir du JDK1.4) : " +"spécifie une colonne de table (ou des colonnes) qui définit l'ordre " +"d'itération de <literal>Map</literal>, <literal>Set</literal> ou Bag, avec " +"en option <literal>asc</literal> ou <literal>desc</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>where</literal> (optional): specifies an arbitrary SQL " +"<literal>WHERE</literal> condition that is used when retrieving or removing " +"the collection. This is useful if the collection needs to contain only a " +"subset of the available data." +msgstr "" +"<literal>where</literal> (optionnel) : spécifie une condition SQL arbitraire " +"<literal>WHERE</literal> à utiliser au chargement ou à la suppression d'une " +"collection (utile si la collection ne doit contenir qu'un sous ensemble des " +"données disponibles)." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>fetch</literal> (optional, defaults to <literal>select</literal>): " +"chooses between outer-join fetching, fetching by sequential select, and " +"fetching by sequential subselect." +msgstr "" +"<literal>fetch</literal> (optionnel, par défaut = <literal>select</" +"literal>) : à choisir entre récupération par jointures externes, " +"récupération par selects séquentiels, et récupération par sous-selects " +"séquentiels." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>batch-size</literal> (optional, defaults to <literal>1</literal>): " +"specifies a \"batch size\" for lazily fetching instances of this collection." +msgstr "" +"<literal>batch-size</literal> (optionnel, par défaut = <literal>1</" +"literal>) : une \"taille de batch\" utilisée pour charger plusieurs " +"instances de cette collection." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>access</literal> (optional - defaults to <literal>property</" +"literal>): the strategy Hibernate uses for accessing the collection property " +"value." +msgstr "" +"<literal>access</literal> (optionnel - par défaut = <literal>property</" +"literal>) : la stratégie que Hibernate doit utiliser pour accéder à la " +"valeur de la propriété." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>optimistic-lock</literal> (optional - defaults to <literal>true</" +"literal>): specifies that changes to the state of the collection results in " +"increments of the owning entity's version. For one-to-many associations you " +"may want to disable this setting." +msgstr "" +"<literal>optimistic-lock</literal> (optionnel - par défaut = <literal>true</" +"literal>) : spécifie que changer l'état des résultats de la collection " +"entraîne l'incrémentation de la version appartenant à l'entité (Pour une " +"association un-à-plusieurs, il est souvent raisonnable de désactiver ce " +"paramètre)." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>mutable</literal> (optional - defaults to <literal>true</literal>): " +"a value of <literal>false</literal> specifies that the elements of the " +"collection never change. This allows for minor performance optimization in " +"some cases." +msgstr "" +"<literal>mutable</literal> (optionnel - par défaut = <literal>true</" +"literal>) : une valeur à <literal>false</literal> spécifie que les éléments " +"de la collection ne changent jamais (une optimisation mineure dans certains " +"cas)." + +#. Tag: title +#, no-c-format +msgid "Collection foreign keys" +msgstr "Les clés étrangères d'une collection" + +#. Tag: para +#, no-c-format +msgid "" +"Collection instances are distinguished in the database by the foreign key of " +"the entity that owns the collection. This foreign key is referred to as the " +"<emphasis>collection key column</emphasis>, or columns, of the collection " +"table. The collection key column is mapped by the <literal>&lt;key&gt;</" +"literal> element." +msgstr "" +"Les instances d'une collection sont distinguées dans la base de données par " +"la clé étrangère de l'entité qui possède la collection. Cette clé étrangère " +"est référencée comme la(es) <emphasis>colonne(s) de la clé de la collection</" +"emphasis> de la table de la collection. La colonne de la clé de la " +"collection est mappée par l'élément <literal>&lt;key&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"There can be a nullability constraint on the foreign key column. For most " +"collections, this is implied. For unidirectional one-to-many associations, " +"the foreign key column is nullable by default, so you may need to specify " +"<literal>not-null=\"true\"</literal>." +msgstr "" +"Il peut y avoir une contrainte de nullité sur la colonne de la clé " +"étrangère. Pour les associations unidirectionnelles un-à-plusieurs, la " +"colonne de la clé étrangère peut être nulle par défaut, donc vous pourriez " +"avoir besoin de spécifier <literal>not-null=\"true\"</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The foreign key constraint can use <literal>ON DELETE CASCADE</literal>." +msgstr "" +"La contraite de la clé étrangère peut utiliser <literal>ON DELETE CASCADE</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"See the previous chapter for a full definition of the <literal>&lt;key&gt;</" +"literal> element." +msgstr "" +"Voir le chapitre précédent pour une définition complète de l'élément " +"<literal>&lt;key&gt;</literal>." + +#. Tag: title +#, no-c-format +msgid "Collection elements" +msgstr "Les éléments d'une collection" + +#. Tag: para +#, no-c-format +msgid "" +"Collections can contain almost any other Hibernate type, including: basic " +"types, custom types, components and references to other entities. This is an " +"important distinction. An object in a collection might be handled with " +"\"value\" semantics (its life cycle fully depends on the collection owner), " +"or it might be a reference to another entity with its own life cycle. In the " +"latter case, only the \"link\" between the two objects is considered to be a " +"state held by the collection." +msgstr "" +"Les collections peuvent contenir la plupart des autres types Hibernate, y " +"compris tous les types basiques, les types utilisateur, les composants, et " +"bien sûr, les références vers d'autres entités. C'est une distinction " +"importante. Un objet dans une collection pourrait être géré avec une " +"sémantique de \"valeur\" (sa durée de vie dépend complètement du " +"propriétaire de la collection) ou il pourrait avoir une référence vers une " +"autre entité, avec sa propre durée de vie. Dans le dernier cas, seul le " +"\"lien\" entre les deux objets est considéré être l'état retenu par la " +"collection. " + +#. Tag: para +#, no-c-format +msgid "" +"The contained type is referred to as the <emphasis>collection element type</" +"emphasis>. Collection elements are mapped by <literal>&lt;element&gt;</" +"literal> or <literal>&lt;composite-element&gt;</literal>, or in the case of " +"entity references, with <literal>&lt;one-to-many&gt;</literal> or " +"<literal>&lt;many-to-many&gt;</literal>. The first two map elements with " +"value semantics, the next two are used to map entity associations." +msgstr "" +"Le type contenu est référencé comme le <emphasis>type de l'élément de la " +"collection</emphasis>. Les éléments de la collections sont mappés par " +"<literal>&lt;element&gt;</literal> ou <literal>&lt;composite-element&gt;</" +"literal>, ou dans le cas des références d'entité, avec <literal>&lt;one-to-" +"many&gt;</literal> ou <literal>&lt;many-to-many&gt;</literal>. Les deux " +"premiers mappent des éléments avec une sémantique de valeur, les deux " +"suivants sont utilisés pour mapper des associations d'entité." + +#. Tag: title +#, no-c-format +msgid "Indexed collections" +msgstr "Collections indexées" + +#. Tag: para +#, no-c-format +msgid "" +"All collection mappings, except those with set and bag semantics, need an " +"<emphasis>index column</emphasis> in the collection table. An index column " +"is a column that maps to an array index, or <literal>List</literal> index, " +"or <literal>Map</literal> key. The index of a <literal>Map</literal> may be " +"of any basic type, mapped with <literal>&lt;map-key&gt;</literal>. It can be " +"an entity reference mapped with <literal>&lt;map-key-many-to-many&gt;</" +"literal>, or it can be a composite type mapped with <literal>&lt;composite-" +"map-key&gt;</literal>. The index of an array or list is always of type " +"<literal>integer</literal> and is mapped using the <literal>&lt;list-" +"index&gt;</literal> element. The mapped column contains sequential integers " +"that are numbered from zero by default." +msgstr "" +"Tous les mappages de collection, exceptés ceux avec les sémantiques " +"d'ensemble (set) et de sac (bag), ont besoin d'une <emphasis>colonne " +"d'index</emphasis> dans la table de la collection - une colonne qui mappe un " +"index de tableau, ou un index de <literal>List</literal>, ou une clé de " +"<literal>Map</literal>. L'index d'une <literal>Map</literal> peut être " +"n'importe quel type basique, mappé avec <literal>&lt;map-key&gt;</literal>, " +"ou peut être une référence d'entité mappée avec <literal>&lt;map-key-many-to-" +"many&gt;</literal>, ou peut être un type composé, mappé avec <literal>&lt;" +"composite-map-key&gt;</literal>. L'index d'un tableau ou d'une liste est " +"toujours de type <literal>integer</literal> et est mappé en utilisant " +"l'élément <literal>&lt;list-index&gt;</literal>. Les colonnes mappées " +"contiennent des entiers séquentiels (numérotés à partir de zéro par défaut). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column_name</literal> (required): the name of the column holding " +"the collection index values." +msgstr "" +"<literal>column_name</literal> (champ requis): lenom de la lolonne qui " +"contient les valeurs 'index' de la collection." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>base</literal> (optional - defaults to <literal>0</literal>): the " +"value of the index column that corresponds to the first element of the list " +"or array." +msgstr "" +"<literal>base</literal> (optionnel - par défaut = <literal>0</literal>) : la " +"valeur de la colonne 'index' qui correspond au premier élément de la liste " +"ou de la table." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional): the name of the column holding the " +"collection index values." +msgstr "" +"<literal>colonne</literal> (optionnel) : le nom de la colonne qui contient " +"les valeurs 'index' de la collection." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): a SQL formula used to evaluate the " +"key of the map." +msgstr "" +"<literal>formula</literal> (optionnel): formule SQL utilisée pour évaluer la " +"clé de la mappe." + +#. Tag: para +#, no-c-format +msgid "<literal>type</literal> (required): the type of the map keys." +msgstr "<literal>type</literal> (requis) : le type de clés de mappe." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional): the name of the foreign key column for " +"the collection index values." +msgstr "" +"<literal>colonne</literal> (optionnel) : le nom de la colonne de clés " +"étrangères pour la collection de valeurs 'index'." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): a SQ formula used to evaluate the " +"foreign key of the map key." +msgstr "" +"<literal>formula</literal> (optionnel): formule SQ utilisée pour évaluer la " +"clé étrangère d'une clé de mappe." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>class</literal> (required): the entity class used as the map key." +msgstr "" +"<literal>class</literal> (requis) : le nom de la classe utilisée en tant que " +"clé de mappe." + +#. Tag: para +#, no-c-format +msgid "" +"If your table does not have an index column, and you still wish to use " +"<literal>List</literal> as the property type, you can map the property as a " +"Hibernate <emphasis>&lt;bag&gt;</emphasis>. A bag does not retain its order " +"when it is retrieved from the database, but it can be optionally sorted or " +"ordered." +msgstr "" +"Si votre table n'a pas de colonne d'index, et que vous souhaitez tout de " +"même utiliser <literal>List</literal> comme type de propriété, vous devriez " +"mapper la propriété comme un <emphasis>&lt;bag&gt;</emphasis> Hibernate. Un " +"sac (bag) ne garde pas son ordre quand il est récupéré de la base de " +"données, mais il peut être optionnellement trié ou ordonné. " + +#. Tag: title +#, no-c-format +msgid "Collections of values and many-to-many associations" +msgstr "Collections de valeurs et associations plusieurs-à-plusieurs" + +#. Tag: para +#, no-c-format +msgid "" +"Any collection of values or many-to-many associations requires a dedicated " +"<emphasis>collection table</emphasis> with a foreign key column or columns, " +"<emphasis>collection element column</emphasis> or columns, and possibly an " +"index column or columns." +msgstr "" +"Toute collection de valeurs ou association plusieurs-à-plusieurs requiert " +"une <emphasis>table de collection</emphasis> avec une(des) colonne(s) de clé " +"étrangère, une(des) <emphasis>colonne(s) d'élément de la collection</" +"emphasis> ou des colonnes et éventuellement une(des) colonne(s) d'index. " + +#. Tag: para +#, no-c-format +msgid "" +"For a collection of values use the <literal>&lt;element&gt;</literal> tag. " +"For example:" +msgstr "" +"Pour une collection de valeurs, nous utilisons la balise <literal>&lt;" +"element&gt;</literal>. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional): the name of the column holding the " +"collection element values." +msgstr "" +"<literal>colonne</literal> (optionnel) : le nom de la colonne qui contient " +"les valeurs des éléments de collection." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): an SQL formula used to evaluate the " +"element." +msgstr "" +"<literal>formula</literal> (optionnel) : formule SQL utilisée pour évaluer " +"l'élément." + +#. Tag: para +#, no-c-format +msgid "<literal>type</literal> (required): the type of the collection element." +msgstr "<literal>type</literal> (requis) : le type d'élément de collection." + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>many-to-many association</emphasis> is specified using the " +"<literal>&lt;many-to-many&gt;</literal> element." +msgstr "" +"Une association <emphasis>many-to-many</emphasis> est spécifiée en utilisant " +"l'élément <literal>&lt;many-to-many&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>column</literal> (optional): the name of the element foreign key " +"column." +msgstr "" +"<literal>colonne</literal> (optionnel) : le nom de la colonne de clés " +"étrangères des éléments." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>formula</literal> (optional): an SQL formula used to evaluate the " +"element foreign key value." +msgstr "" +"<literal>formula</literal> (optionnel): formule SQL utilisée pour évaluer la " +"valeur des clés étrangères des éléments." + +#. Tag: para +#, no-c-format +msgid "<literal>class</literal> (required): the name of the associated class." +msgstr "<literal>class</literal> (requis) : le nom de la classe associée." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>fetch</literal> (optional - defaults to <literal>join</literal>): " +"enables outer-join or sequential select fetching for this association. This " +"is a special case; for full eager fetching in a single <literal>SELECT</" +"literal> of an entity and its many-to-many relationships to other entities, " +"you would enable <literal>join</literal> fetching,not only of the collection " +"itself, but also with this attribute on the <literal>&lt;many-to-many&gt;</" +"literal> nested element." +msgstr "" +"<literal>fetch</literal> (optionnel - par défaut <literal>join</literal>): " +"permet la récupération par jointures externes ou bien par selects " +"séquentiels pour cette association. Il s'agit d'un cas particulier de " +"récupération. Pour que la récupération soit toujours rapportée en un seul " +"<literal>SELECT</literal> d'entité ou à partir de ses relations many-to-many " +"à d'autres entités, vous devrez activer la récupération <literal>join</" +"literal>, non seulement pour la collection elle-même, mais aussi avec cet " +"attribut qui se trouve sur l'élément <literal>&lt;many-to-many&gt;</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>unique</literal> (optional): enables the DDL generation of a unique " +"constraint for the foreign-key column. This makes the association " +"multiplicity effectively one-to-many." +msgstr "" +"<literal>unique</literal> (optionnel): permet la génération DDL d'une seule " +"contrainte pour la colonne de la clé étrangère. Cela transforme la " +"muticiplicité de l'association en one-to-many." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-found</literal> (optional - defaults to <literal>exception</" +"literal>): specifies how foreign keys that reference missing rows will be " +"handled: <literal>ignore</literal> will treat a missing row as a null " +"association." +msgstr "" +"<literal>not-found</literal> (optionnel - par défaut <literal>exception</" +"literal>) : spécifie comment les clés étrangères cachées qui référencent des " +"lignes manquantes seront gérées : <literal>ignore</literal> traitera une " +"ligne manquante comme une association nulle." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>entity-name</literal> (optional): the entity name of the associated " +"class, as an alternative to <literal>class</literal>." +msgstr "" +"<literal>entity-name</literal> (optionnel) : le nom de l'entité de la classe " +"associée, comme une alternative à <literal>class</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>property-ref</literal> (optional): the name of a property of the " +"associated class that is joined to this foreign key. If not specified, the " +"primary key of the associated class is used." +msgstr "" +"<literal>property-ref</literal> (optionnel): nom d'une propriété de la " +"classe associée associée à une clé étrangère. Si elle n'est pas précisée, la " +"clé primaire de la classe associée sera alors utilisée." + +#. Tag: para +#, no-c-format +msgid "Here are some examples." +msgstr "Voici quelques exemples :" + +#. Tag: para +#, no-c-format +msgid "A set of strings:" +msgstr "Un ensemble de chaînes de caractères :" + +#. Tag: para +#, no-c-format +msgid "" +"A bag containing integers with an iteration order determined by the " +"<literal>order-by</literal> attribute:" +msgstr "" +"Un sac contenant des entiers (avec un ordre d'itération déterminé par " +"l'attribut <literal>order-by</literal>) : " + +#. Tag: para +#, no-c-format +msgid "An array of entities, in this case, a many-to-many association:" +msgstr "" +"Un tableau d'entités - dans ce cas, une association plusieurs-à-plusieurs : " + +#. Tag: para +#, no-c-format +msgid "A map from string indices to dates:" +msgstr "Une map de chaînes de caractères vers des dates :" + +#. Tag: para +#, no-c-format +msgid "A list of components (this is discussed in the next chapter):" +msgstr "Une liste de composants (traité dans le prochain chapitre) : " + +#. Tag: title +#, no-c-format +msgid "One-to-many associations" +msgstr "Associations un-à-plusieurs" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>one-to-many association</emphasis> links the tables of two " +"classes via a foreign key with no intervening collection table. This mapping " +"loses certain semantics of normal Java collections:" +msgstr "" +"Une <emphasis>association un-à-plusieurs</emphasis> lie les tables de deux " +"classes par une clé étrangère, sans l'intervention d'une table de " +"collection. Ce mappage perd certaines sémantiques des collections Java " +"normales : " + +#. Tag: para +#, no-c-format +msgid "" +"An instance of the contained entity class cannot belong to more than one " +"instance of the collection." +msgstr "" +"Une instance de la classe de l'entité contenue ne peut pas appartenir à plus " +"d'une instance de la collection." + +#. Tag: para +#, no-c-format +msgid "" +"An instance of the contained entity class cannot appear at more than one " +"value of the collection index." +msgstr "" +"Une instance de la classe de l'entité contenue peut ne pas apparaître à plus " +"plus d'une valeur d'index de la collection." + +#. Tag: para +#, no-c-format +msgid "" +"An association from <literal>Product</literal> to <literal>Part</literal> " +"requires the existence of a foreign key column and possibly an index column " +"to the <literal>Part</literal> table. A <literal>&lt;one-to-many&gt;</" +"literal> tag indicates that this is a one-to-many association." +msgstr "" +"Une association de <literal>Product</literal> vers <literal>Part</literal> " +"requiert l'existence d'une clé étrangère et éventuellement une colonne " +"d'index pour la table <literal>Part</literal>. Une balise <literal>&lt;one-" +"to-many&gt;</literal> indique que c'est une association un-à-plusieurs. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>not-found</literal> (optional - defaults to <literal>exception</" +"literal>): specifies how cached identifiers that reference missing rows will " +"be handled. <literal>ignore</literal> will treat a missing row as a null " +"association." +msgstr "" +"<literal>not-found</literal> (optionnel - par défaut <literal>exception</" +"literal>) : spécifie comment les identifiants cachés qui référencent des " +"lignes manquantes seront gérés : <literal>ignore</literal> traitera une " +"ligne manquante comme une association nulle." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;one-to-many&gt;</literal> element does not need to declare " +"any columns. Nor is it necessary to specify the <literal>table</literal> " +"name anywhere." +msgstr "" +"Notez que l'élément <literal>&lt;one-to-many&gt;</literal> n'a pas besoin de " +"déclarer de colonnes. Il n'est pas non plus nécessaire de spécifier le nom " +"de la <literal>table</literal> à aucun endroit." + +#. Tag: para +#, no-c-format +msgid "" +"If the foreign key column of a <literal>&lt;one-to-many&gt;</literal> " +"association is declared <literal>NOT NULL</literal>, you must declare the " +"<literal>&lt;key&gt;</literal> mapping <literal>not-null=\"true\"</literal> " +"or <emphasis>use a bidirectional association</emphasis> with the collection " +"mapping marked <literal>inverse=\"true\"</literal>. See the discussion of " +"bidirectional associations later in this chapter for more information." +msgstr "" +"<emphasis>Note très importante :</emphasis> si la colonne de la clé d'une " +"association <literal>&lt;one-to-many&gt;</literal> est déclarée <literal>NOT " +"NULL</literal>, vous devez déclarer le mappage de <literal>&lt;key&gt;</" +"literal> avec <literal>not-null=\"true\"</literal> ou <emphasis> utiliser " +"une association bidirectionnelle </emphasis> avec le mappage de la " +"collection marqué <literal>inverse=\"true\"</literal>. Voir la discussion " +"sur les associations bidirectionnelles plus tard dans ce chapitre. " + +#. Tag: para +#, no-c-format +msgid "" +"The following example shows a map of <literal>Part</literal> entities by " +"name, where <literal>partName</literal> is a persistent property of " +"<literal>Part</literal>. Notice the use of a formula-based index:" +msgstr "" +"Cet exemple montre une map d'entités <literal>Part</literal> par nom (où " +"<literal>partName</literal> est une propriété persistante de <literal>Part</" +"literal>). Notez l'utilisation d'un index basé sur une formule :" + +#. Tag: title +#, no-c-format +msgid "Advanced collection mappings" +msgstr "Mappages de collection avancés" + +#. Tag: title +#, no-c-format +msgid "Sorted collections" +msgstr "Collections triées" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate supports collections implementing <literal>java.util.SortedMap</" +"literal> and <literal>java.util.SortedSet</literal>. You must specify a " +"comparator in the mapping file:" +msgstr "" +"Hibernate supporte des collections implémentant <literal>java.util." +"SortedMap</literal> et <literal>java.util.SortedSet</literal>. Vous devez " +"spécifier un comparateur dans le fichier de mappage :" + +#. Tag: para +#, no-c-format +msgid "" +"Allowed values of the <literal>sort</literal> attribute are " +"<literal>unsorted</literal>, <literal>natural</literal> and the name of a " +"class implementing <literal>java.util.Comparator</literal>." +msgstr "" +"Les valeurs permises pour l'attribut <literal>sort</literal> sont " +"<literal>unsorted</literal>, <literal>natural</literal> et le nom d'une " +"classe implémentant <literal>java.util.Comparator</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Sorted collections actually behave like <literal>java.util.TreeSet</literal> " +"or <literal>java.util.TreeMap</literal>." +msgstr "" +"Les collections triées se comportent réellement comme <literal>java.util." +"TreeSet</literal> ou <literal>java.util.TreeMap</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"If you want the database itself to order the collection elements, use the " +"<literal>order-by</literal> attribute of <literal>set</literal>, " +"<literal>bag</literal> or <literal>map</literal> mappings. This solution is " +"only available under JDK 1.4 or higher and is implemented using " +"<literal>LinkedHashSet</literal> or <literal>LinkedHashMap</literal>. This " +"performs the ordering in the SQL query and not in the memory." +msgstr "" +"Si vous voulez que la base de données elle-même ordonne les éléments de la " +"collection, utilisez l'attribut <literal>order-by</literal> des mappages " +"<literal>set</literal>, <literal>bag</literal> ou <literal>map</literal>. " +"Cette solution est seulement disponible à partir du JDK 1.4 (c'est " +"implémenté en utilisant <literal>LinkedHashSet</literal> ou " +"<literal>LinkedHashMap</literal>). Ceci exécute le tri dans la requête SQL, " +"pas en mémoire. " + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Note" + +#. Tag: para +#, no-c-format +msgid "" +"The value of the <literal>order-by</literal> attribute is an SQL ordering, " +"not an HQL ordering." +msgstr "" +"Notez que la valeur de l'attribut <literal>order-by</literal> est un ordre " +"SQL, et non pas un ordre HQL." + +#. Tag: para +#, no-c-format +msgid "" +"Associations can even be sorted by arbitrary criteria at runtime using a " +"collection <literal>filter()</literal>:" +msgstr "" +"Les associations peuvent même être triées sur des critères arbitraires à " +"l'exécution en utilisant un <literal>filter()</literal> de collection :" + +#. Tag: title +#, no-c-format +msgid "Bidirectional associations" +msgstr "Associations bidirectionnelles" + +#. Tag: para +#, no-c-format +msgid "" +"A <emphasis>bidirectional association</emphasis> allows navigation from both " +"\"ends\" of the association. Two kinds of bidirectional association are " +"supported:" +msgstr "" +"Une <emphasis>association bidirectionnelle</emphasis> permet la navigation à " +"partir des deux extrémités de l'association. Deux types d'associations " +"bidirectionnelles sont supportées : " + +#. Tag: term +#, no-c-format +msgid "one-to-many" +msgstr "un-à-plusieurs (one-to-many)" + +#. Tag: para +#, no-c-format +msgid "set or bag valued at one end and single-valued at the other" +msgstr "ensemble ou sac à une extrémité, une seule valeur à l'autre " + +#. Tag: term +#, no-c-format +msgid "many-to-many" +msgstr "plusieurs-à-plusieurs " + +#. Tag: para +#, no-c-format +msgid "set or bag valued at both ends" +msgstr "ensemble ou sac aux deux extrémités" + +#. Tag: para +#, no-c-format +msgid "" +"You can specify a bidirectional many-to-many association by mapping two many-" +"to-many associations to the same database table and declaring one end as " +"<emphasis>inverse</emphasis>. You cannot select an indexed collection." +msgstr "" +"Vous pouvez spécifier une association bidirectionnelle plusieurs-à-plusieurs " +"simplement en mappant deux associations plusieurs-à-plusieurs vers la même " +"table de base de données et en déclarant une extrémité comme " +"<emphasis>inverse</emphasis> (celle de votre choix, mais pas une collection " +"indexée). " + +#. Tag: para +#, no-c-format +msgid "" +"Here is an example of a bidirectional many-to-many association that " +"illustrates how each category can have many items and each item can be in " +"many categories:" +msgstr "" +"Voici un exemple d'association bidirectionnelle plusieurs-à-plusieurs ; " +"chaque catégorie peut avoir plusieurs objets et chaque objet peut être dans " +"plusieurs catégories : " + +#. Tag: para +#, no-c-format +msgid "" +"Changes made only to the inverse end of the association are <emphasis>not</" +"emphasis> persisted. This means that Hibernate has two representations in " +"memory for every bidirectional association: one link from A to B and another " +"link from B to A. This is easier to understand if you think about the Java " +"object model and how a many-to-many relationship in Javais created:" +msgstr "" +"Les changements faits uniquement sur l'extrémité inverse de l'association " +"<emphasis>ne sont pas</emphasis> persistés. Ceci signifie qu'Hibernate a " +"deux représentations en mémoire pour chaque association bidirectionnelle, un " +"lien de A vers B et un autre de B vers A. Ceci est plus facile à comprendre " +"si vous pensez au modèle objet de Java et à la façon dont nous créons une " +"relation plusieurs-à-plusieurs dans Java : " + +#. Tag: para +#, no-c-format +msgid "" +"The non-inverse side is used to save the in-memory representation to the " +"database." +msgstr "" +"La partie non-inverse est utilisée pour sauvegarder la représentation en " +"mémoire dans la base de données." + +#. Tag: para +#, no-c-format +msgid "" +"You can define a bidirectional one-to-many association by mapping a one-to-" +"many association to the same table column(s) as a many-to-one association " +"and declaring the many-valued end <literal>inverse=\"true\"</literal>." +msgstr "" +"Vous pouvez définir une association bidirectionnelle un-à-plusieurs en " +"mappant une association un-à-plusieurs vers la(es) même(s) colonne(s) de " +"table qu'une association plusieurs-à-un et en déclarant l'extrémité pluri-" +"valuée <literal>inverse=\"true\"</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Mapping one end of an association with <literal>inverse=\"true\"</literal> " +"does not affect the operation of cascades as these are orthogonal concepts." +msgstr "" +"Mapper une extrémité d'une association avec <literal>inverse=\"true\"</" +"literal> n'affecte pas l'opération de cascades, ce sont des concepts " +"orthogonaux." + +#. Tag: title +#, no-c-format +msgid "Bidirectional associations with indexed collections" +msgstr "Associations bidirectionnelles avec des collections indexées" + +#. Tag: para +#, no-c-format +msgid "" +"A bidirectional association where one end is represented as a <literal>&lt;" +"list&gt;</literal> or <literal>&lt;map&gt;</literal>, requires special " +"consideration. If there is a property of the child class that maps to the " +"index column you can use <literal>inverse=\"true\"</literal> on the " +"collection mapping:" +msgstr "" +"Une association bidirectionnelle où une extrémité est représentée comme une " +"<literal>&lt;list&gt;</literal> ou une <literal>&lt;map&gt;</literal> " +"requiert une considération spéciale. S'il y a une propriété de la classe " +"enfant qui mappe la colonne de l'index, pas de problème, nous pouvons " +"continuer à utiliser <literal>inverse=\"true\"</literal> sur le mappage de " +"la collection : " + +#. Tag: para +#, no-c-format +msgid "" +"If there is no such property on the child class, the association cannot be " +"considered truly bidirectional. That is, there is information available at " +"one end of the association that is not available at the other end. In this " +"case, you cannot map the collection <literal>inverse=\"true\"</literal>. " +"Instead, you could use the following mapping:" +msgstr "" +"Mais, si il n'y a pas de telle propriété sur la classe enfant, nous ne " +"pouvons pas considérer l'association comme vraiment bidirectionnelle (il y a " +"des informations disponibles à une extrémité de l'association qui ne sont " +"pas disponibles à l'autre extrémité). Dans ce cas, nous ne pouvons pas " +"mapper la collection <literal>inverse=\"true\"</literal>. Par contre, nous " +"utiliserons le mappage suivant : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Note that in this mapping, the collection-valued end of the association is " +"responsible for updates to the foreign key." +msgstr "" +"Notez que dans ce mappage, l'extrémité de l'association contenant la " +"collection est responsable des mise à jour de la clé étrangère. <!-- TODO: " +"Does this really result in some unnecessary update statements? -->" + +#. Tag: title +#, no-c-format +msgid "Ternary associations" +msgstr "Associations ternaires" + +#. Tag: para +#, no-c-format +msgid "" +"There are three possible approaches to mapping a ternary association. One " +"approach is to use a <literal>Map</literal> with an association as its index:" +msgstr "" +"Il y a trois approches possibles pour mapper une association ternaire. L'une " +"est d'utiliser une <literal>Map</literal> avec une association comme son " +"index : " + +#. Tag: para +#, no-c-format +msgid "" +"A second approach is to remodel the association as an entity class. This is " +"the most common approach." +msgstr "" +"Une seconde approche est simplement de remodeler l'association comme une " +"classe d'entité. C'est l'approche la plus commune. " + +#. Tag: para +#, no-c-format +msgid "" +"A final alternative is to use composite elements, which will be discussed " +"later." +msgstr "" +"Une alternative finale est d'utiliser des éléments composites, dont nous " +"discuterons plus tard. " + +#. Tag: title +#, fuzzy, no-c-format +msgid "<literal>Using an &lt;idbag&gt;</literal>" +msgstr "<literal>Using an &lt;idbag&gt;</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"The majority of the many-to-many associations and collections of values " +"shown previously all map to tables with composite keys, even though it has " +"been have suggested that entities should have synthetic identifiers " +"(surrogate keys). A pure association table does not seem to benefit much " +"from a surrogate key, although a collection of composite values " +"<emphasis>might</emphasis>. It is for this reason that Hibernate provides a " +"feature that allows you to map many-to-many associations and collections of " +"values to a table with a surrogate key." +msgstr "" +"Si vous êtes bien d'accord avec nous sur le fait que les clés composées sont " +"une mauvaise chose et que les entités devraient avoir des identifiants " +"artificiels (des clés subrogées), vous pourrez trouver un peu curieux que " +"les associations plusieurs-à-plusieurs et les collections de valeurs que " +"nous avons montrées jusqu'ici, mappent toutes des tables avec des clés " +"composées ! Il est vrai que ce point est ambigu ; une table d'association " +"pure ne semble pas tirer avantage d'une clé subrogée (bien qu'une collection " +"de valeur composées le <emphasis>pourrait</emphasis>). Néanmoins, Hibernate " +"fournit une fonctionnalité qui vous permet de mapper des associations " +"plusieurs-à-plusieurs et des collections de valeurs vers une table avec une " +"clé subrogée. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;idbag&gt;</literal> element lets you map a <literal>List</" +"literal> (or <literal>Collection</literal>) with bag semantics. For example:" +msgstr "" +"L'élément <literal>&lt;idbag&gt;</literal> vous laisse mapper une " +"<literal>List</literal> (ou une <literal>Collection</literal>) avec une " +"sémantique de sac. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"An <literal>&lt;idbag&gt;</literal> has a synthetic id generator, just like " +"an entity class. A different surrogate key is assigned to each collection " +"row. Hibernate does not, however, provide any mechanism for discovering the " +"surrogate key value of a particular row." +msgstr "" +"Comme vous pouvez le constater, un <literal>&lt;idbag&gt;</literal> a un " +"générateur d'id artificiel, exactement comme une classe d'entité ! Une clé " +"subrogée différente est assignée à chaque ligne de la collection. Cependant, " +"Hibernate ne fournit pas de mécanisme pour découvrir la valeur d'une clé " +"subrogée d'une ligne particulière. " + +#. Tag: para +#, no-c-format +msgid "" +"The update performance of an <literal>&lt;idbag&gt;</literal> supersedes a " +"regular <literal>&lt;bag&gt;</literal>. Hibernate can locate individual rows " +"efficiently and update or delete them individually, similar to a list, map " +"or set." +msgstr "" +"Notez que les performances de la mise à jour d'un <literal>&lt;idbag&gt;</" +"literal> sont <emphasis>bien</emphasis> meilleures qu'un <literal>&lt;bag&gt;" +"</literal> ordinaire ! Hibernate peut localiser des lignes individuelles " +"efficacement et les mettre à jour ou les effacer individuellement, comme une " +"liste, une map ou un ensemble. " + +#. Tag: para +#, no-c-format +msgid "" +"In the current implementation, the <literal>native</literal> identifier " +"generation strategy is not supported for <literal>&lt;idbag&gt;</literal> " +"collection identifiers." +msgstr "" +"Dans l'implémentation actuelle, la stratégie de la génération de " +"l'identifiant <literal>native</literal> n'est pas supportée pour les " +"identifiants de collection <literal>&lt;idbag&gt;</literal>. " + +#. Tag: title +#, no-c-format +msgid "Collection examples" +msgstr "Exemples de collections" + +#. Tag: para +#, no-c-format +msgid "This section covers collection examples." +msgstr "Exemples de collections " + +#. Tag: para +#, no-c-format +msgid "" +"The following class has a collection of <literal>Child</literal> instances:" +msgstr "" +"La classe suivante possède une collection d'instances <literal>Child</" +"literal>(filles) :" + +#. Tag: para +#, no-c-format +msgid "" +"If each child has, at most, one parent, the most natural mapping is a one-to-" +"many association:" +msgstr "" +"Si chaque instance fille a au plus un parent, le mappage le plus naturel est " +"une association un-à-plusieurs :" + +#. Tag: para +#, no-c-format +msgid "This maps to the following table definitions:" +msgstr "Ceci mappe les définitions de tables suivantes :" + +#. Tag: para +#, no-c-format +msgid "" +"If the parent is <emphasis>required</emphasis>, use a bidirectional one-to-" +"many association:" +msgstr "" +"Si le parent est <emphasis>requis</emphasis>, utilisez une association " +"bidirectionnelle un-à-plusieurs : " + +#. Tag: para +#, no-c-format +msgid "Notice the <literal>NOT NULL</literal> constraint:" +msgstr "Notez la contrainte <literal>NOT NULL</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, if this association must be unidirectional you can declare " +"the <literal>NOT NULL</literal> constraint on the <literal>&lt;key&gt;</" +"literal> mapping:" +msgstr "" +"Alternativement, si vous insistez absolument pour que cette association soit " +"unidirectionnelle, vous pouvez déclarer la contrainte <literal>NOT NULL</" +"literal> sur le mappage <literal>&lt;key&gt;</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"On the other hand, if a child has multiple parents, a many-to-many " +"association is appropriate:" +msgstr "" +"D'autre part, si un enfant peut avoir plusieurs parents, une association " +"plusieurs-à-plusieurs est plus appropriée : " + +#. Tag: para +#, no-c-format +msgid "Table definitions:" +msgstr "Définitions des tables :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"For more examples and a complete explanation of a parent/child relationship " +"mapping, see <xref linkend=\"example-parentchild\" /> for more information." +msgstr "" +"Pour plus d'exemples et une revue complète du mappage de la relation parent/" +"enfant, consultez le <xref linkend=\"example-parentchild\" />. " + +#. Tag: para +#, no-c-format +msgid "Even more complex association mappings are covered in the next chapter." +msgstr "" +"Des mappages d'association plus exotiques sont possibles, nous cataloguerons " +"toutes les possibilités dans le prochain chapitre. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/component_mapping.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/component_mapping.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/component_mapping.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,789 @@ +# translation of component_mapping.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: component_mapping\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2009-11-11 08:51+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Component Mapping" +msgstr "Mappage de composants" + +#. Tag: para +#, no-c-format +msgid "" +"The notion of a <emphasis>component</emphasis> is re-used in several " +"different contexts and purposes throughout Hibernate." +msgstr "" +"La notion de <emphasis>composants</emphasis> est réutilisée dans différents " +"contextes, avec différents objectifs, à travers Hibernate. " + +#. Tag: title +#, no-c-format +msgid "Dependent objects" +msgstr "Objets dépendants" + +#. Tag: para +#, no-c-format +msgid "" +"A component is a contained object that is persisted as a value type and not " +"an entity reference. The term \"component\" refers to the object-oriented " +"notion of composition and not to architecture-level components. For example, " +"you can model a person like this:" +msgstr "" +"Le composant est un objet inclus dans un autre objet, sauvegardé en tant que " +"type valeur, et non en tant que référence entité. Le terme \"composant\" " +"fait référence à la notion (au sens objet) de composition et non pas de " +"composant au sens d'architecture de composants. Par exemple, on pourrait " +"modéliser l'objet personne de la façon suivante :" + +#. Tag: para +#, no-c-format +msgid "" +"Now <literal>Name</literal> can be persisted as a component of " +"<literal>Person</literal>. <literal>Name</literal> defines getter and setter " +"methods for its persistent properties, but it does not need to declare any " +"interfaces or identifier properties." +msgstr "" +"Maintenant <literal>Name</literal> pourra être sauvegardé en tant que " +"composant de <literal>Person</literal>. Remarquez que <literal>Name</" +"literal> définit des méthodes getter et setter pour ses propriétés " +"persistantes, mais ne doit déclarer aucune interface ou propriété " +"d'identification." + +#. Tag: para +#, no-c-format +msgid "Our Hibernate mapping would look like this:" +msgstr "Dans Hibernate le mappage du composant serait :" + +#. Tag: para +#, no-c-format +msgid "" +"The person table would have the columns <literal>pid</literal>, " +"<literal>birthday</literal>, <literal>initial</literal>, <literal>first</" +"literal> and <literal>last</literal>." +msgstr "" +"La table \"person\" aurait les colonnes <literal>pid</literal>, " +"<literal>birthday</literal>, <literal>initial</literal>, <literal>first</" +"literal> et <literal>last</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Like value types, components do not support shared references. In other " +"words, two persons could have the same name, but the two person objects " +"would contain two independent name objects that were only \"the same\" by " +"value. The null value semantics of a component are <emphasis>ad hoc</" +"emphasis>. When reloading the containing object, Hibernate will assume that " +"if all component columns are null, then the entire component is null. This " +"is suitable for most purposes." +msgstr "" +"Comme tous les types valeurs, les composants ne supportent pas les " +"références partagées. En d'autres termes, deux instances de person peuvent " +"avoir un même nom, mais ces noms sont indépendants, ils peuvent être " +"identiques si on les compare par valeur mais ils représentent deux objets " +"distincts en mémoire. La sémantique de la valeur null d'un composant est " +"<emphasis>ad hoc</emphasis>. Quand il recharge l'objet qui contient le " +"composant, Hibernate suppose que si toutes les colonnes de composants sont " +"nulles, le composant est positionné à la valeur null. Ce choix programmatif " +"devrait être satisfaisant dans la plupart des cas. " + +#. Tag: para +#, no-c-format +msgid "" +"The properties of a component can be of any Hibernate type (collections, " +"many-to-one associations, other components, etc). Nested components should " +"<emphasis>not</emphasis> be considered an exotic usage. Hibernate is " +"intended to support a fine-grained object model." +msgstr "" +"Les propriétés d'un composant peuvent être de tous les types habituellement " +"supportés par Hibernate (collections, associations plusieurs-à-un, autres " +"composants, etc). Les composants imbriqués ne doivent <emphasis>pas</" +"emphasis> être vus comme quelque chose d'exotique. Hibernate a été conçu " +"pour supporter un modèle d'objet finement granulé. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;component&gt;</literal> element allows a <literal>&lt;" +"parent&gt;</literal> subelement that maps a property of the component class " +"as a reference back to the containing entity." +msgstr "" +"L'élément <literal>&lt;component&gt;</literal> permet de déclarer un sous-" +"élément <literal>&lt;parent&gt;</literal> qui associe une propriété de la " +"classe composant comme une référence arrière vers l'entité contenante." + +#. Tag: title +#, no-c-format +msgid "Collections of dependent objects" +msgstr "Collection d'objets dépendants" + +#. Tag: para +#, no-c-format +msgid "" +"Collections of components are supported (e.g. an array of type " +"<literal>Name</literal>). Declare your component collection by replacing the " +"<literal>&lt;element&gt;</literal> tag with a <literal>&lt;composite-" +"element&gt;</literal> tag:" +msgstr "" +"Les collections d'objets dépendants sont supportées (exemple: un tableau de " +"type <literal>Name</literal>). Déclarez votre collection de composants en " +"remplaçant la balise <literal>&lt;element&gt;</literal> par la balise " +"<literal>&lt;composite-element&gt;</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"If you define a <literal>Set</literal> of composite elements, it is " +"important to implement <literal>equals()</literal> and <literal>hashCode()</" +"literal> correctly." +msgstr "" +"Remarque : si vous définissez un <literal>Set</literal> d'éléments " +"composites, il est très important d'implémenter les méthodes <literal>equals" +"()</literal> et <literal>hashCode()</literal> correctement. " + +#. Tag: para +#, no-c-format +msgid "" +"Composite elements can contain components but not collections. If your " +"composite element contains components, use the <literal>&lt;nested-composite-" +"element&gt;</literal> tag. This case is a collection of components which " +"themselves have components. You may want to consider if a one-to-many " +"association is more appropriate. Remodel the composite element as an entity, " +"but be aware that even though the Java model is the same, the relational " +"model and persistence semantics are still slightly different." +msgstr "" +"Les éléments composites peuvent aussi contenir des composants mais pas des " +"collections. Si votre élément composite contient aussi des composants, " +"utilisez la balise <literal>&lt;nested-composite-element&gt;</literal>. Une " +"collection de composants qui contiennent eux-mêmes des composants est un cas " +"très exotique. A ce stade, demandez-vous si une association un-à-plusieurs " +"ne serait pas plus appropriée. Essayez de remodeler votre élément composite " +"comme une entité - remarquez que si le modèle Java est le même, toutefois le " +"modèle relationnel et la sémantique de persistance diffèrent quelque peu. " + +#. Tag: para +#, no-c-format +msgid "" +"A composite element mapping does not support null-able properties if you are " +"using a <literal>&lt;set&gt;</literal>. There is no separate primary key " +"column in the composite element table. Hibernate uses each column's value to " +"identify a record when deleting objects, which is not possible with null " +"values. You have to either use only not-null properties in a composite-" +"element or choose a <literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</" +"literal>, <literal>&lt;bag&gt;</literal> or <literal>&lt;idbag&gt;</literal>." +msgstr "" +"Remarquez que le mappage d'éléments composites ne supporte pas la nullité " +"des propriétés lorsqu'on utilise un <literal>&lt;set&gt;</literal>. " +"Hibernate lorsqu'il supprime un objet, utilise chaque colonne pour " +"identifier un objet (il n'y a pas de colonne distincte de clés primaires " +"dans la table d'éléments composites), ce qui n'est pas possible avec des " +"valeurs nulles. Vous devez donc choisir d'interdire la nullité des " +"propriétés d'un élément composite ou choisir un autre type de collection " +"comme : <literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</literal>, " +"<literal>&lt;bag&gt;</literal> ou <literal>&lt;idbag&gt;</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"A special case of a composite element is a composite element with a nested " +"<literal>&lt;many-to-one&gt;</literal> element. This mapping allows you to " +"map extra columns of a many-to-many association table to the composite " +"element class. The following is a many-to-many association from " +"<literal>Order</literal> to <literal>Item</literal>, where " +"<literal>purchaseDate</literal>, <literal>price</literal> and " +"<literal>quantity</literal> are properties of the association:" +msgstr "" +"Un cas particulier d'élément composite est un élément composite qui inclut " +"un élément imbriqué <literal>&lt;many-to-one&gt;</literal>. Un mappage comme " +"celui-ci vous permet d'associer des colonnes supplémentaires d'une table " +"d'association plusieurs à plusieurs à la classe de l'élément composite. " +"L'exemple suivant est une association plusieurs à plusieurs de " +"<literal>Order</literal> à <literal>Item</literal> où <literal>purchaseDate</" +"literal>, <literal>price</literal> et <literal>quantity</literal> sont des " +"propriétés de l'association :" + +#. Tag: para +#, no-c-format +msgid "" +"There cannot be a reference to the purchase on the other side for " +"bidirectional association navigation. Components are value types and do not " +"allow shared references. A single <literal>Purchase</literal> can be in the " +"set of an <literal>Order</literal>, but it cannot be referenced by the " +"<literal>Item</literal> at the same time." +msgstr "" +"Par ailleurs, on ne peut évidemment pas faire référence à l'achat " +"(purchase), pour pouvoir naviguer de façon bidirectionnelle dans " +"l'association. N'oubliez pas que les composants sont de type valeurs et " +"n'autorisent pas les références partagées. Un <literal>Purchase</literal> " +"unique peut être dans le set d'un <literal>Order</literal>, mais ne peut pas " +"être référencé par <literal>Item</literal> simultanément." + +#. Tag: para +#, no-c-format +msgid "Even ternary (or quaternary, etc) associations are possible:" +msgstr "" +"Même les associations ternaires, quaternaires ou autres sont possibles :" + +#. Tag: para +#, no-c-format +msgid "" +"Composite elements can appear in queries using the same syntax as " +"associations to other entities." +msgstr "" +"Des éléments composites peuvent apparaître dans les requêtes en utilisant la " +"même syntaxe que les associations vers d'autres entités. " + +#. Tag: title +#, no-c-format +msgid "Components as Map indices" +msgstr "Les composants en tant qu'indices de Map" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;composite-map-key&gt;</literal> element allows you to map a " +"component class as the key of a <literal>Map</literal>. Ensure that you " +"override <literal>hashCode()</literal> and <literal>equals()</literal> " +"correctly on the component class." +msgstr "" +"L'élément <literal>&lt;composite-map-key&gt;</literal> vous permet de mapper " +"une classe de composant comme indice d'une <literal>Map</literal>. Assurez-" +"vous de surcharger correctement <literal>hashCode()</literal> et " +"<literal>equals()</literal> dans la classe du composant. " + +#. Tag: title +#, no-c-format +msgid "Components as composite identifiers" +msgstr "Les composants en tant qu'identifiants composites" + +#. Tag: para +#, no-c-format +msgid "" +"You can use a component as an identifier of an entity class. Your component " +"class must satisfy certain requirements:" +msgstr "" +"Vous pouvez utiliser un composant comme identifiant d'une classe entité. À " +"cet effet, votre classe de composant doit respecter certaines exigences : " + +#. Tag: para +#, no-c-format +msgid "It must implement <literal>java.io.Serializable</literal>." +msgstr "Elle doit implémenter <literal>java.io.Serializable</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"It must re-implement <literal>equals()</literal> and <literal>hashCode()</" +"literal> consistently with the database's notion of composite key equality." +msgstr "" +"Elle doit redéfinir <literal>equals()</literal> et <literal>hashCode()</" +"literal>, de façon cohérente avec la notion d'égalité de clé composite de la " +"base de données. " + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Remarque" + +#. Tag: para +#, no-c-format +msgid "" +"In Hibernate3, although the second requirement is not an absolutely hard " +"requirement of Hibernate, it is recommended." +msgstr "" +"Avec Hibernate3, la seconde exigence n'est plus absolument nécessaire, " +"néanmoins continuez de l'effectuer." + +#. Tag: para +#, no-c-format +msgid "" +"You cannot use an <literal>IdentifierGenerator</literal> to generate " +"composite keys. Instead the application must assign its own identifiers." +msgstr "" +"Vous ne pouvez pas utiliser de <literal>IdentifierGenerator</literal> pour " +"générer des clés composites, par contre l'application doit assigner ses " +"propres identifiants. " + +#. Tag: para +#, no-c-format +msgid "" +"Use the <literal>&lt;composite-id&gt;</literal> tag, with nested " +"<literal>&lt;key-property&gt;</literal> elements, in place of the usual " +"<literal>&lt;id&gt;</literal> declaration. For example, the " +"<literal>OrderLine</literal> class has a primary key that depends upon the " +"(composite) primary key of <literal>Order</literal>." +msgstr "" +"Utiliser la balise <literal>&lt;composite-id&gt;</literal> (avec les " +"éléments imbriqués <literal>&lt;key-property&gt;</literal>) à la place de " +"l'habituel déclaration <literal>&lt;id&gt;</literal>. Par exemple, la classe " +"<literal>OrderLine</literal> possède une clé primaire qui dépend de la clé " +"primaire (composite) de <literal>Order</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Any foreign keys referencing the <literal>OrderLine</literal> table are now " +"composite. Declare this in your mappings for other classes. An association " +"to <literal>OrderLine</literal> is mapped like this:" +msgstr "" +"Toutes les clés étrangères référençant la table <literal>OrderLine</literal> " +"sont également composites. Vous devez en tenir compte lorsque vous écrivez " +"vos mappage d'association pour les autres classes. Une association à " +"<literal>OrderLine</literal> sera mappée de la façon suivante : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The <literal>column</literal> element is an alternative to the " +"<literal>column</literal> attribute everywhere. Using the <literal>column</" +"literal> element just gives more declaration options, which are mostly " +"useful when utilizing <literal>hbm2ddl</literal>" +msgstr "" +"Remarquez que la balise <literal>&lt;column&gt;</literal> est une " +"alternative à l'attribut <literal>column</literal> que l'on utilise partout." + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>many-to-many</literal> association to <literal>OrderLine</" +"literal> also uses the composite foreign key:" +msgstr "" +"Une association <literal>plusieurs-à-plusieurs</literal> à " +"<literal>OrderLine</literal> utilisera aussi une clé étrangère composite :" + +#. Tag: para +#, no-c-format +msgid "" +"The collection of <literal>OrderLine</literal>s in <literal>Order</literal> " +"would use:" +msgstr "" +"La collection des <literal>OrderLine</literal> s dans <literal>Order</" +"literal> utilisera : " + +#. Tag: para +#, no-c-format +msgid "The <literal>&lt;one-to-many&gt;</literal> element declares no columns." +msgstr "" +"Comme d'habitude, l'élément <literal>&lt;one-to-many&gt;</literal> ne " +"déclare pas de colonne." + +#. Tag: para +#, no-c-format +msgid "" +"If <literal>OrderLine</literal> itself owns a collection, it also has a " +"composite foreign key." +msgstr "" +"Si <literal>OrderLine</literal> lui-même possède une collection, il " +"possédera de même une clé composite étrangère." + +#. Tag: title +#, no-c-format +msgid "Dynamic components" +msgstr "Les composants dynamiques" + +#. Tag: para +#, no-c-format +msgid "You can also map a property of type <literal>Map</literal>:" +msgstr "" +"Vous pouvez également mapper une propriété de type <literal>Map</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"The semantics of a <literal>&lt;dynamic-component&gt;</literal> mapping are " +"identical to <literal>&lt;component&gt;</literal>. The advantage of this " +"kind of mapping is the ability to determine the actual properties of the " +"bean at deployment time just by editing the mapping document. Runtime " +"manipulation of the mapping document is also possible, using a DOM parser. " +"You can also access, and change, Hibernate's configuration-time metamodel " +"via the <literal>Configuration</literal> object." +msgstr "" +"La sémantique de l'association à un <literal>&lt;dynamic-component&gt;</" +"literal> est identique à celle que l'on utilise pour le <literal>&lt;" +"component&gt;</literal>. L'avantage de ce type de mappage est qu'il permet " +"de déterminer les véritables propriétés du bean au moment du déploiement, en " +"éditant simplement le document de mappage. La manipulation du document de " +"mappage pendant l'exécution de l'application est aussi possible en utilisant " +"un parser DOM. Il y a même mieux, vous pouvez accéder (et changer) le " +"métamodèle de configuration-temps de Hibernate en utilisant l'objet " +"<literal>Configuration</literal>." + +#~ msgid "" +#~ "<![CDATA[public class Person {\n" +#~ " private java.util.Date birthday;\n" +#~ " private Name name;\n" +#~ " private String key;\n" +#~ " public String getKey() {\n" +#~ " return key;\n" +#~ " }\n" +#~ " private void setKey(String key) {\n" +#~ " this.key=key;\n" +#~ " }\n" +#~ " public java.util.Date getBirthday() {\n" +#~ " return birthday;\n" +#~ " }\n" +#~ " public void setBirthday(java.util.Date birthday) {\n" +#~ " this.birthday = birthday;\n" +#~ " }\n" +#~ " public Name getName() {\n" +#~ " return name;\n" +#~ " }\n" +#~ " public void setName(Name name) {\n" +#~ " this.name = name;\n" +#~ " }\n" +#~ " ......\n" +#~ " ......\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[public class Person {\n" +#~ " private java.util.Date birthday;\n" +#~ " private Name name;\n" +#~ " private String key;\n" +#~ " public String getKey() {\n" +#~ " return key;\n" +#~ " }\n" +#~ " private void setKey(String key) {\n" +#~ " this.key=key;\n" +#~ " }\n" +#~ " public java.util.Date getBirthday() {\n" +#~ " return birthday;\n" +#~ " }\n" +#~ " public void setBirthday(java.util.Date birthday) {\n" +#~ " this.birthday = birthday;\n" +#~ " }\n" +#~ " public Name getName() {\n" +#~ " return name;\n" +#~ " }\n" +#~ " public void setName(Name name) {\n" +#~ " this.name = name;\n" +#~ " }\n" +#~ " ......\n" +#~ " ......\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[public class Name {\n" +#~ " char initial;\n" +#~ " String first;\n" +#~ " String last;\n" +#~ " public String getFirst() {\n" +#~ " return first;\n" +#~ " }\n" +#~ " void setFirst(String first) {\n" +#~ " this.first = first;\n" +#~ " }\n" +#~ " public String getLast() {\n" +#~ " return last;\n" +#~ " }\n" +#~ " void setLast(String last) {\n" +#~ " this.last = last;\n" +#~ " }\n" +#~ " public char getInitial() {\n" +#~ " return initial;\n" +#~ " }\n" +#~ " void setInitial(char initial) {\n" +#~ " this.initial = initial;\n" +#~ " }\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[public class Name {\n" +#~ " char initial;\n" +#~ " String first;\n" +#~ " String last;\n" +#~ " public String getFirst() {\n" +#~ " return first;\n" +#~ " }\n" +#~ " void setFirst(String first) {\n" +#~ " this.first = first;\n" +#~ " }\n" +#~ " public String getLast() {\n" +#~ " return last;\n" +#~ " }\n" +#~ " void setLast(String last) {\n" +#~ " this.last = last;\n" +#~ " }\n" +#~ " public char getInitial() {\n" +#~ " return initial;\n" +#~ " }\n" +#~ " void setInitial(char initial) {\n" +#~ " this.initial = initial;\n" +#~ " }\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"eg.Person\" table=\"person\">\n" +#~ " <id name=\"Key\" column=\"pid\" type=\"string\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " <property name=\"birthday\" type=\"date\"/>\n" +#~ " <component name=\"Name\" class=\"eg.Name\"> <!-- class attribute " +#~ "optional -->\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </component>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"eg.Person\" table=\"person\">\n" +#~ " <id name=\"Key\" column=\"pid\" type=\"string\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " <property name=\"birthday\" type=\"date\"/>\n" +#~ " <component name=\"Name\" class=\"eg.Name\"> <!-- class attribute " +#~ "optional -->\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </component>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"eg.Person\" table=\"person\">\n" +#~ " <id name=\"Key\" column=\"pid\" type=\"string\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " <property name=\"birthday\" type=\"date\"/>\n" +#~ " <component name=\"Name\" class=\"eg.Name\" unique=\"true\">\n" +#~ " <parent name=\"namedPerson\"/> <!-- reference back to the Person " +#~ "-->\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </component>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"eg.Person\" table=\"person\">\n" +#~ " <id name=\"Key\" column=\"pid\" type=\"string\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " <property name=\"birthday\" type=\"date\"/>\n" +#~ " <component name=\"Name\" class=\"eg.Name\" unique=\"true\">\n" +#~ " <parent name=\"namedPerson\"/> <!-- reference back to the Person " +#~ "-->\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </component>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<set name=\"someNames\" table=\"some_names\" lazy=\"true\">\n" +#~ " <key column=\"id\"/>\n" +#~ " <composite-element class=\"eg.Name\"> <!-- class attribute required --" +#~ ">\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </composite-element>\n" +#~ "</set>]]>" +#~ msgstr "" +#~ "<![CDATA[<set name=\"someNames\" table=\"some_names\" lazy=\"true\">\n" +#~ " <key column=\"id\"/>\n" +#~ " <composite-element class=\"eg.Name\"> <!-- class attribute required --" +#~ ">\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"first\"/>\n" +#~ " <property name=\"last\"/>\n" +#~ " </composite-element>\n" +#~ "</set>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"eg.Order\" .... >\n" +#~ " ....\n" +#~ " <set name=\"purchasedItems\" table=\"purchase_items\" lazy=\"true\">\n" +#~ " <key column=\"order_id\">\n" +#~ " <composite-element class=\"eg.Purchase\">\n" +#~ " <property name=\"purchaseDate\"/>\n" +#~ " <property name=\"price\"/>\n" +#~ " <property name=\"quantity\"/>\n" +#~ " <many-to-one name=\"item\" class=\"eg.Item\"/> <!-- class " +#~ "attribute is optional -->\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"eg.Order\" .... >\n" +#~ " ....\n" +#~ " <set name=\"purchasedItems\" table=\"purchase_items\" lazy=\"true\">\n" +#~ " <key column=\"order_id\">\n" +#~ " <composite-element class=\"eg.Purchase\">\n" +#~ " <property name=\"purchaseDate\"/>\n" +#~ " <property name=\"price\"/>\n" +#~ " <property name=\"quantity\"/>\n" +#~ " <many-to-one name=\"item\" class=\"eg.Item\"/> <!-- class " +#~ "attribute is optional -->\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"eg.Order\" .... >\n" +#~ " ....\n" +#~ " <set name=\"purchasedItems\" table=\"purchase_items\" lazy=\"true\">\n" +#~ " <key column=\"order_id\">\n" +#~ " <composite-element class=\"eg.OrderLine\">\n" +#~ " <many-to-one name=\"purchaseDetails class=\"eg.Purchase\"/>\n" +#~ " <many-to-one name=\"item\" class=\"eg.Item\"/>\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"eg.Order\" .... >\n" +#~ " ....\n" +#~ " <set name=\"purchasedItems\" table=\"purchase_items\" lazy=\"true\">\n" +#~ " <key column=\"order_id\">\n" +#~ " <composite-element class=\"eg.OrderLine\">\n" +#~ " <many-to-one name=\"purchaseDetails class=\"eg.Purchase\"/>\n" +#~ " <many-to-one name=\"item\" class=\"eg.Item\"/>\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"OrderLine\">\n" +#~ " \n" +#~ " <composite-id name=\"id\" class=\"OrderLineId\">\n" +#~ " <key-property name=\"lineId\"/>\n" +#~ " <key-property name=\"orderId\"/>\n" +#~ " <key-property name=\"customerId\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"name\"/>\n" +#~ " \n" +#~ " <many-to-one name=\"order\" class=\"Order\"\n" +#~ " insert=\"false\" update=\"false\">\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </many-to-one>\n" +#~ " ....\n" +#~ " \n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"OrderLine\">\n" +#~ " \n" +#~ " <composite-id name=\"id\" class=\"OrderLineId\">\n" +#~ " <key-property name=\"lineId\"/>\n" +#~ " <key-property name=\"orderId\"/>\n" +#~ " <key-property name=\"customerId\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"name\"/>\n" +#~ " \n" +#~ " <many-to-one name=\"order\" class=\"Order\"\n" +#~ " insert=\"false\" update=\"false\">\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </many-to-one>\n" +#~ " ....\n" +#~ " \n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<many-to-one name=\"orderLine\" class=\"OrderLine\">\n" +#~ "<!-- the \"class\" attribute is optional, as usual -->\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ "</many-to-one>]]>" +#~ msgstr "" +#~ "<![CDATA[<many-to-one name=\"orderLine\" class=\"OrderLine\">\n" +#~ "<!-- the \"class\" attribute is optional, as usual -->\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ "</many-to-one>]]>" + +#~ msgid "" +#~ "<![CDATA[<set name=\"undeliveredOrderLines\">\n" +#~ " <key column name=\"warehouseId\"/>\n" +#~ " <many-to-many class=\"OrderLine\">\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </many-to-many>\n" +#~ "</set>]]>" +#~ msgstr "" +#~ "<![CDATA[<set name=\"undeliveredOrderLines\">\n" +#~ " <key column name=\"warehouseId\"/>\n" +#~ " <many-to-many class=\"OrderLine\">\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </many-to-many>\n" +#~ "</set>]]>" + +#~ msgid "" +#~ "<![CDATA[<set name=\"orderLines\" inverse=\"true\">\n" +#~ " <key>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </key>\n" +#~ " <one-to-many class=\"OrderLine\"/>\n" +#~ "</set>]]>" +#~ msgstr "" +#~ "<![CDATA[<set name=\"orderLines\" inverse=\"true\">\n" +#~ " <key>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </key>\n" +#~ " <one-to-many class=\"OrderLine\"/>\n" +#~ "</set>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"OrderLine\">\n" +#~ " ....\n" +#~ " ....\n" +#~ " <list name=\"deliveryAttempts\">\n" +#~ " <key> <!-- a collection inherits the composite key type -->\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </key>\n" +#~ " <list-index column=\"attemptId\" base=\"1\"/>\n" +#~ " <composite-element class=\"DeliveryAttempt\">\n" +#~ " ...\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"OrderLine\">\n" +#~ " ....\n" +#~ " ....\n" +#~ " <list name=\"deliveryAttempts\">\n" +#~ " <key> <!-- a collection inherits the composite key type -->\n" +#~ " <column name=\"lineId\"/>\n" +#~ " <column name=\"orderId\"/>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " </key>\n" +#~ " <list-index column=\"attemptId\" base=\"1\"/>\n" +#~ " <composite-element class=\"DeliveryAttempt\">\n" +#~ " ...\n" +#~ " </composite-element>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<dynamic-component name=\"userAttributes\">\n" +#~ " <property name=\"foo\" column=\"FOO\" type=\"string\"/>\n" +#~ " <property name=\"bar\" column=\"BAR\" type=\"integer\"/>\n" +#~ " <many-to-one name=\"baz\" class=\"Baz\" column=\"BAZ_ID\"/>\n" +#~ "</dynamic-component>]]>" +#~ msgstr "" +#~ "<![CDATA[<dynamic-component name=\"userAttributes\">\n" +#~ " <property name=\"foo\" column=\"FOO\" type=\"string\"/>\n" +#~ " <property name=\"bar\" column=\"BAR\" type=\"integer\"/>\n" +#~ " <many-to-one name=\"baz\" class=\"Baz\" column=\"BAZ_ID\"/>\n" +#~ "</dynamic-component>]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/configuration.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/configuration.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/configuration.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,2683 @@ +# translation of configuration.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: configuration\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:05+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Configuration" +msgstr "Configuration" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate is designed to operate in many different environments and, as " +"such, there is a broad range of configuration parameters. Fortunately, most " +"have sensible default values and Hibernate is distributed with an example " +"<literal>hibernate.properties</literal> file in <literal>etc/</literal> that " +"displays the various options. Simply put the example file in your classpath " +"and customize it to suit your needs." +msgstr "" +"Hibernate est conçu pour fonctionner dans de nombreux environnements , c'est " +"pourquoi il existe beaucoup de paramètres de configuration. Heureusement, la " +"plupart ont des valeurs par défaut appropriées et la Hibernate inclut un " +"fichier d'exemples <literal>hibernate.properties</literal> dans le " +"répertoire <literal>etc/</literal> qui fournit les différentes options. " +"Vous n'avez qu'à placer ce fichier dans votre classpath et à l'adapter à vos " +"besoins." + +#. Tag: title +#, no-c-format +msgid "Programmatic configuration" +msgstr "Configuration par programmation" + +#. Tag: para +#, no-c-format +msgid "" +"An instance of <classname>org.hibernate.cfg.Configuration</classname> " +"represents an entire set of mappings of an application's Java types to an " +"SQL database. The <classname>org.hibernate.cfg.Configuration</classname> is " +"used to build an immutable <interfacename>org.hibernate.SessionFactory</" +"interfacename>. The mappings are compiled from various XML mapping files." +msgstr "" +"Une instance de <literal>org.hibernate.cfg.Configuration</literal> " +"représente un ensemble de mappages des classes Java d'une application vers " +"la base de données SQL. La <literal>Configuration</literal> est utilisée " +"pour construire un objet (immuable) <literal>SessionFactory</literal>. Les " +"mappages sont constitués d'un ensemble de fichiers de mappage XML. " + +#. Tag: para +#, no-c-format +msgid "" +"You can obtain a <classname>org.hibernate.cfg.Configuration</classname> " +"instance by instantiating it directly and specifying XML mapping documents. " +"If the mapping files are in the classpath, use <literal>addResource()</" +"literal>. For example:" +msgstr "" +"Vous pouvez obtenir une instance de <literal>Configuration</literal> en " +"l'instanciant directement et en spécifiant la liste des documents XML de " +"mappage. Si les fichiers de mappage sont dans le classpath, vous pouvez " +"utiliser la méthode <literal>addResource()</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"An alternative way is to specify the mapped class and allow Hibernate to " +"find the mapping document for you:" +msgstr "" +"Une solution alternative consiste à spécifier la classe mappée et à donner à " +"Hibernate la possibilité de trouver les documents de mappage pour vous :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will then search for mapping files named <filename>/org/hibernate/" +"auction/Item.hbm.xml</filename> and <filename>/org/hibernate/auction/Bid.hbm." +"xml</filename> in the classpath. This approach eliminates any hardcoded " +"filenames." +msgstr "" +"Hibernate va rechercher les fichiers de mappages <literal>/org/hibernate/" +"auction/Item.hbm.xml</literal> et <literal>/org/hibernate/auction/Bid.hbm." +"xml</literal> dans le classpath. Cette approche élimine les noms de fichiers " +"en dur. " + +#. Tag: para +#, no-c-format +msgid "" +"A <classname>org.hibernate.cfg.Configuration</classname> also allows you to " +"specify configuration properties. For example:" +msgstr "" +"Une <literal>Configuration</literal> vous permet également de préciser des " +"propriétés de configuration. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"This is not the only way to pass configuration properties to Hibernate. Some " +"alternative options include:" +msgstr "" +"Ce n'est pas le seul moyen de passer des propriétés de configuration à " +"Hibernate. Les différentes options sont : " + +#. Tag: para +#, no-c-format +msgid "" +"Pass an instance of <classname>java.util.Properties</classname> to " +"<literal>Configuration.setProperties()</literal>." +msgstr "" +"Passer une instance de <literal>java.util.Properties</literal> à " +"<literal>Configuration.setProperties()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Place a file named <filename>hibernate.properties</filename> in a root " +"directory of the classpath." +msgstr "" +"Placer <literal>hibernate.properties</literal> dans un répertoire racine du " +"chemin de classe." + +#. Tag: para +#, no-c-format +msgid "" +"Set <literal>System</literal> properties using <literal>java -" +"Dproperty=value</literal>." +msgstr "" +"Positionner les propriétés <literal>System</literal> en utilisant " +"<literal>java -Dproperty=value</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Include <literal>&lt;property&gt;</literal> elements in <literal>hibernate." +"cfg.xml</literal> (this is discussed later)." +msgstr "" +"Inclure des éléments <literal>&lt;property&gt;</literal> dans le fichier " +"<literal>hibernate.cfg.xml</literal> (voir plus loin). " + +#. Tag: para +#, no-c-format +msgid "" +"If you want to get started quickly<filename>hibernate.properties</filename> " +"is the easiest approach." +msgstr "" +"Si vous souhaitez démarrer rapidement, <filename>hibernate.properties</" +"filename> est l'approche la plus facile." + +#. Tag: para +#, no-c-format +msgid "" +"The <classname>org.hibernate.cfg.Configuration</classname> is intended as a " +"startup-time object that will be discarded once a <literal>SessionFactory</" +"literal> is created." +msgstr "" +"<classname>org.hibernate.cfg.Configuration</classname> est un objet de " +"démarrage qui sera supprimé une fois qu'une <literal>SessionFactory</" +"literal> aura été créée." + +#. Tag: title +#, no-c-format +msgid "Obtaining a SessionFactory" +msgstr "Obtenir une SessionFactory" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"When all mappings have been parsed by the <classname>org.hibernate.cfg." +"Configuration</classname>, the application must obtain a factory for " +"<interfacename>org.hibernate.Session</interfacename> instances. This factory " +"is intended to be shared by all application threads:" +msgstr "" +"Une fois que tous les mappages ont été parsés par la <literal>Configuration</" +"literal>, l'application doit obtenir une fabrique d'instances de " +"<literal>Session</literal>. Cette fabrique sera partagée entre tous les " +"threads de l'application : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Hibernate does allow your application to instantiate more than one " +"<interfacename>org.hibernate.SessionFactory</interfacename>. This is useful " +"if you are using more than one database." +msgstr "" +"Hibernate permet à votre application d'instancier plus d'une " +"<literal>SessionFactory</literal>. Cela est pratique lorsque vous utilisez " +"plus d'une base de données. " + +#. Tag: title +#, no-c-format +msgid "JDBC connections" +msgstr "Connexions JDBC " + +#. Tag: para +#, no-c-format +msgid "" +"It is advisable to have the <interfacename>org.hibernate.SessionFactory</" +"interfacename> create and pool JDBC connections for you. If you take this " +"approach, opening a <interfacename>org.hibernate.Session</interfacename> is " +"as simple as:" +msgstr "" +"Il est conseillé que <interfacename>org.hibernate.SessionFactory</" +"interfacename> crée les connexions JDBC et les mette dans un pool pour vous. " +"Si vous suivez cette approche, ouvrir une <interfacename>org.hibernate." +"Session</interfacename> est aussi simple que :" + +#. Tag: para +#, no-c-format +msgid "" +"Once you start a task that requires access to the database, a JDBC " +"connection will be obtained from the pool." +msgstr "" +"Dès que vous initierez une action qui requiert un accès à la base de " +"données, une connexion JDBC sera récupérée dans le pool." + +#. Tag: para +#, no-c-format +msgid "" +"Before you can do this, you first need to pass some JDBC connection " +"properties to Hibernate. All Hibernate property names and semantics are " +"defined on the class <classname>org.hibernate.cfg.Environment</classname>. " +"The most important settings for JDBC connection configuration are outlined " +"below." +msgstr "" +"À cet effet, il faut passer les propriétés de la connexion JDBC à Hibernate. " +"Tous les noms des propriétés Hibernate et leur signification sont définies " +"dans la classe <literal>org.hibernate.cfg.Environment</literal>. Nous allons " +"maintenant décrire les paramètres de configuration des connexions JDBC les " +"plus importants. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will obtain and pool connections using <classname>java.sql." +"DriverManager</classname> if you set the following properties:" +msgstr "" +"Hibernate obtiendra des connexions (et les mettra dans un pool) en utilisant " +"<literal>java.sql.DriverManager</literal> si vous positionnez les paramètres " +"de la manière suivante : " + +#. Tag: title +#, no-c-format +msgid "Hibernate JDBC Properties" +msgstr "Propriétés JDBC de Hibernate" + +#. Tag: entry +#, no-c-format +msgid "Property name" +msgstr "Nom de la propriété" + +#. Tag: entry +#, no-c-format +msgid "Purpose" +msgstr "Fonction" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.driver_class</property>" +msgstr "<property>hibernate.connection.driver_class</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>JDBC driver class</emphasis>" +msgstr "<emphasis>Classe de pilote JDBC</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.url</property>" +msgstr "<property>hibernate.connection.url</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>JDBC URL</emphasis>" +msgstr "<emphasis>JDBC URL</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.username</property>" +msgstr "<property>hibernate.connection.username</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>database user</emphasis>" +msgstr "<emphasis>utilisateur de la base de données</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.password</property>" +msgstr "<property>hibernate.connection.password</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>database user password</emphasis>" +msgstr "<emphasis>mot de passe de l'utilisateur de base de données</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.pool_size</property>" +msgstr "<property>hibernate.connection.pool_size</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>maximum number of pooled connections</emphasis>" +msgstr "<emphasis>nombre maximum de connexions dans le pool</emphasis>" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate's own connection pooling algorithm is, however, quite rudimentary. " +"It is intended to help you get started and is <emphasis>not intended for use " +"in a production system</emphasis>, or even for performance testing. You " +"should use a third party pool for best performance and stability. Just " +"replace the <property>hibernate.connection.pool_size</property> property " +"with connection pool specific settings. This will turn off Hibernate's " +"internal pool. For example, you might like to use c3p0." +msgstr "" +"L'algorithme natif de pool de connexions de Hibernate est plutôt " +"rudimentaire. Il a été conçu dans le but de vous aider à démarrer et " +"<emphasis>n'est pas prévu pour un système en production</emphasis> ou même " +"pour un test de performance. Utilisez plutôt un pool tiers pour de " +"meilleures performances et une meilleure stabilité : remplacez la propriété " +"<literal>hibernate.connection.pool_size</literal> avec les propriétés " +"spécifiques au pool de connexions que vous avez choisi. Cela désactivera le " +"pool de connexions interne de Hibernate. Vous pouvez par exemple utiliser " +"C3P0. " + +#. Tag: para +#, no-c-format +msgid "" +"C3P0 is an open source JDBC connection pool distributed along with Hibernate " +"in the <filename>lib</filename> directory. Hibernate will use its " +"<classname>org.hibernate.connection.C3P0ConnectionProvider</classname> for " +"connection pooling if you set <property>hibernate.c3p0.*</property> " +"properties. If you would like to use Proxool, refer to the packaged " +"<filename>hibernate.properties</filename> and the Hibernate web site for " +"more information." +msgstr "" +"C3P0 est un pool de connexions JDBC open source distribué avec Hibernate " +"dans le répertoire <literal>lib</literal>. Hibernate utilisera son provider " +"<literal>C3P0ConnectionProvider</literal> pour le pool de connexions si vous " +"configurez les propriétés <literal>hibernate.c3p0.*</literal>. Si vous " +"voulez utiliser Proxool, référez vous au groupe de propriétés " +"<literal>hibernate.properties</literal> correspondant et consultez le site " +"web Hibernate pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"The following is an example <filename>hibernate.properties</filename> file " +"for c3p0:" +msgstr "" +"Voici un exemple de fichier <literal>hibernate.properties</literal> pour " +"C3P0: " + +#. Tag: para +#, no-c-format +msgid "" +"For use inside an application server, you should almost always configure " +"Hibernate to obtain connections from an application server " +"<interfacename>javax.sql.Datasource</interfacename> registered in JNDI. You " +"will need to set at least one of the following properties:" +msgstr "" +"Pour l'utilisation de Hibernate au sein d'un serveur d'applications, il est " +"recommandé de configurer Hibernate presque toujours de façon à ce qu'il " +"obtienne ses connexions de la <literal>DataSource</literal> enregistrée du " +"serveur d'applications dans le JNDI. À cet effet, vous devrez définir au " +"moins une des propriétés suivantes : " + +#. Tag: title +#, no-c-format +msgid "Hibernate Datasource Properties" +msgstr "Propriétés d'une Datasource Hibernate" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.datasource</property>" +msgstr "<property>hibernate.connection.datasource</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>datasource JNDI name</emphasis>" +msgstr "<emphasis>nom JNDI de la source de données</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jndi.url</property>" +msgstr "<property>hibernate.jndi.url</property>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>URL of the JNDI provider</emphasis> (optional)" +msgstr "<emphasis>URL du fournisseur JNDI</emphasis> (optionnel)" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jndi.class</property>" +msgstr "<property>hibernate.jndi.class</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"<emphasis>class of the JNDI <literal>InitialContextFactory</literal></" +"emphasis> (optional)" +msgstr "" +"<emphasis>classe de JNDI <literal>InitialContextFactory</literal></emphasis> " +"(optionnel)" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>database user</emphasis> (optional)" +msgstr "<emphasis>utilisateur de base de données</emphasis> (optionnel)" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>database user password</emphasis> (optional)" +msgstr "" +"<emphasis>mot de passe de l'utilisateur de base de données</emphasis> " +"(optionnel)" + +#. Tag: para +#, no-c-format +msgid "" +"Here is an example <filename>hibernate.properties</filename> file for an " +"application server provided JNDI datasource:" +msgstr "" +"Voici un exemple de fichier <literal>hibernate.properties</literal> pour " +"l'utilisation d'une datasource JNDI fournie par un serveur d'applications : " + +#. Tag: para +#, no-c-format +msgid "" +"JDBC connections obtained from a JNDI datasource will automatically " +"participate in the container-managed transactions of the application server." +msgstr "" +"Les connexions JDBC obtenues à partir d'une datasource JNDI participeront " +"automatiquement aux transactions gérées par le conteneur du serveur " +"d'applications." + +#. Tag: para +#, no-c-format +msgid "" +"Arbitrary connection properties can be given by prepending " +"\"<literal>hibernate.connection</literal>\" to the connection property name. " +"For example, you can specify a <property>charSet</property> connection " +"property using <property>hibernate.connection.charSet</property>." +msgstr "" +"Des propriétés arbitraires de connexion peuvent être passées en préfixant le " +"nom de la propriété par \"<literal>hibernate.connnection</literal>\". Par " +"exemple, vous pouvez spécifier un <literal>charSet</literal> en utilisant " +"<literal>hibernate.connection.charSet</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"You can define your own plugin strategy for obtaining JDBC connections by " +"implementing the interface <interfacename>org.hibernate.connection." +"ConnectionProvider</interfacename>, and specifying your custom " +"implementation via the <property>hibernate.connection.provider_class</" +"property> property." +msgstr "" +"Vous pouvez fournir votre propre stratégie d'obtention des connexions JDBC " +"en implémentant l'interface <literal>org.hibernate.connection." +"ConnectionProvider</literal>. Vous pouvez sélectionner une implémentation " +"spécifique par la propriété <literal>hibernate.connection.provider_class</" +"literal>." + +#. Tag: title +#, no-c-format +msgid "Optional configuration properties" +msgstr "Propriétés de configuration optionnelles" + +#. Tag: para +#, no-c-format +msgid "" +"There are a number of other properties that control the behavior of " +"Hibernate at runtime. All are optional and have reasonable default values." +msgstr "" +"Il y a un certain nombre d'autres propriétés qui contrôlent le " +"fonctionnement d'Hibernate à l'exécution. Toutes sont optionnelles et ont " +"comme valeurs par défaut des valeurs raisonnables." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<emphasis>Some of these properties are \"system-level\" only.</emphasis> " +"System-level properties can be set only via <literal>java -Dproperty=value</" +"literal> or <filename>hibernate.properties</filename>. They " +"<emphasis>cannot</emphasis> be set by the other techniques described above." +msgstr "" +"Attention : certaines de ces propriétés sont uniquement de niveau System. " +"Les propriétés de niveau System ne peuvent être positionnées que via la " +"ligne de commande <literal>java -Dproperty=value</literal> ou être définies " +"dans <literal>hibernate.properties</literal>. Elles peuvent <emphasis>ne " +"pas</emphasis> être configurées par les autres techniques décrites ci-" +"dessus. " + +#. Tag: title +#, no-c-format +msgid "Hibernate Configuration Properties" +msgstr "Propriétés de configuration Hibernate" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.dialect</property>" +msgstr "<property>hibernate.dialect</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"The classname of a Hibernate <classname>org.hibernate.dialect.Dialect</" +"classname> which allows Hibernate to generate SQL optimized for a particular " +"relational database." +msgstr "" +"Le nom de la classe d'un <classname>org.hibernate.dialect.Dialect</" +"classname> Hibernate qui permet à Hibernate de générer du SQL optimisé pour " +"une base de données relationnelle particulière. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>full.classname.of." +"Dialect</literal>" +msgstr "" +" <emphasis role=\"strong\">par ex.</emphasis><literal>full.classname.of." +"Dialect</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"In most cases Hibernate will actually be able to choose the correct " +"<classname>org.hibernate.dialect.Dialect</classname> implementation based on " +"the <literal>JDBC metadata</literal> returned by the JDBC driver." +msgstr "" +"Dans la plupart des cas, Hibernate sera en mesure de choisir " +"l'implémentation <classname>org.hibernate.dialect.Dialect</classname> qui " +"convient sur la base des <literal>métadonnées JDBC</literal> retournées par " +"le driver JDBC." + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.show_sql</property>" +msgstr "<property>hibernate.show_sql</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Write all SQL statements to console. This is an alternative to setting the " +"log category <literal>org.hibernate.SQL</literal> to <literal>debug</" +"literal>." +msgstr "" +"Écrit toutes les requêtes SQL sur la console. Il s'agit d'une alternative au " +"paramétrage de la catégorie de log <literal>org.hibernate.SQL</literal> à " +"<literal>debug</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>true</literal> | " +"<literal>false</literal>" +msgstr "" +" <emphasis role=\"strong\">par ex.</emphasis><literal>true</literal> | " +"<literal>false</literal> " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.format_sql</property>" +msgstr "<property>hibernate.format_sql</property>" + +#. Tag: entry +#, no-c-format +msgid "Pretty print the SQL in the log and console." +msgstr "Effectue un pretty print du SQL dans la console et dans le log. " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.default_schema</property>" +msgstr "<property>hibernate.default_schema</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Qualify unqualified table names with the given schema/tablespace in " +"generated SQL." +msgstr "" +"Qualifie des noms de table non qualifiés avec le schéma/tablespace dans le " +"SQL généré." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>SCHEMA_NAME</literal>" +msgstr "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>SCHEMA_NAME</literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.default_catalog</property>" +msgstr "<property>hibernate.default_catalog</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Qualifies unqualified table names with the given catalog in generated SQL." +msgstr "" +"Qualifie les noms de tables non qualifiées avec ce catalogue dans le SQL " +"généré. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>CATALOG_NAME</literal>" +msgstr "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>CATALOG_NAME</literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.session_factory_name</property>" +msgstr "<property>hibernate.session_factory_name</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"The <interfacename>org.hibernate.SessionFactory</interfacename> will be " +"automatically bound to this name in JNDI after it has been created." +msgstr "" +"<interfacename>org.hibernate.SessionFactory</interfacename> sera " +"automatiquement liée à ce nom dans JNDI après sa création. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>jndi/composite/name</" +"literal>" +msgstr "" +" <emphasis role=\"strong\">par ex.</emphasis><literal>jndi/composite/name</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.max_fetch_depth</property>" +msgstr "<property>hibernate.max_fetch_depth</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Sets a maximum \"depth\" for the outer join fetch tree for single-ended " +"associations (one-to-one, many-to-one). A <literal>0</literal> disables " +"default outer join fetching." +msgstr "" +"Configure la profondeur maximale d'un arbre de chargement par jointures " +"externes pour les associations à cardinalité unitaire (un-à-un, plusieurs-à-" +"un). Un <literal>0</literal> désactive le chargement par défaut par jointure " +"externe." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> recommended values between " +"<literal>0</literal> and <literal>3</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis> valeurs recommandées entre " +"<literal>0</literal> et <literal>3</literal> " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.default_batch_fetch_size</property>" +msgstr "<property>hibernate.default_batch_fetch_size</property>" + +#. Tag: entry +#, no-c-format +msgid "Sets a default size for Hibernate batch fetching of associations." +msgstr "" +"Configure une taille par défaut pour le chargement par lot des associations " +"Hibernate " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> recommended values <literal>4</" +"literal>, <literal>8</literal>, <literal>16</literal>" +msgstr "" +"<emphasis role=\"strong\">ex.</emphasis> valeurs recommandées : <literal>4</" +"literal>, <literal>8</literal>, <literal>16</literal> " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.default_entity_mode</property>" +msgstr "<property>hibernate.default_entity_mode</property>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"Sets a default mode for entity representation for all sessions opened from " +"this <literal>SessionFactory</literal>" +msgstr "" +"Configure un mode de représentation par défaut des entités pour toutes les " +"sessions ouvertes depuis cette <literal>SessionFactory</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>dynamic-map</literal>, <literal>dom4j</literal>, <literal>pojo</" +"literal>" +msgstr "" +"<literal>dynamic-map</literal>, <literal>dom4j</literal>, <literal>pojo</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.order_updates</property>" +msgstr "<property>hibernate.order_updates</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Forces Hibernate to order SQL updates by the primary key value of the items " +"being updated. This will result in fewer transaction deadlocks in highly " +"concurrent systems." +msgstr "" +"Force Hibernate à trier les mises à jour SQL par la valeur de la clé " +"primaire des éléments mis à jour. Cela permet de limiter les deadlocks de " +"transaction dans les systèmes hautement concurrents." + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.generate_statistics</property>" +msgstr "<property>hibernate.generate_statistics</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"If enabled, Hibernate will collect statistics useful for performance tuning." +msgstr "" +"Si activé, Hibernate va collecter des statistiques utiles pour le réglage " +"des performances. " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.use_identifier_rollback</property>" +msgstr "<property>hibernate.use_identifer_rollback</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"If enabled, generated identifier properties will be reset to default values " +"when objects are deleted." +msgstr "" +"Si activé, les propriétés correspondant à l'identifiant des objets sont " +"remises aux valeurs par défaut lorsque les objets sont supprimés. " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.use_sql_comments</property>" +msgstr "<property>hibernate.use_sql_comments</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"If turned on, Hibernate will generate comments inside the SQL, for easier " +"debugging, defaults to <literal>false</literal>." +msgstr "" +"Si activé, Hibernate génère des commentaires à l'intérieur des requêtes SQL " +"pour faciliter le débogage, par défaut à <literal>false</literal>." + +#. Tag: title +#, no-c-format +msgid "Hibernate JDBC and Connection Properties" +msgstr "Propriétés Hibernate liées à JDBC et aux connexions" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.fetch_size</property>" +msgstr "<property>hibernate.jdbc.fetch_size</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"A non-zero value determines the JDBC fetch size (calls <literal>Statement." +"setFetchSize()</literal>)." +msgstr "" +"Une valeur non nulle détermine la taille des chargements JDBC (appelle " +"<literal>Statement.setFetchSize()</literal>)." + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.batch_size</property>" +msgstr "<property>hibernate.jdbc.batch_size</property>" + +#. Tag: entry +#, no-c-format +msgid "A non-zero value enables use of JDBC2 batch updates by Hibernate." +msgstr "" +"Une valeur non nulle active l'utilisation par Hibernate des mise à jour par " +"lot de JDBC2. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> recommended values between " +"<literal>5</literal> and <literal>30</literal>" +msgstr "" +"<emphasis role=\"strong\">ex.</emphasis> les valeurs recommandées entre " +"<literal>5</literal> et <literal>30</literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.batch_versioned_data</property>" +msgstr "<property>hibernate.jdbc.batch_versioned_data</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Set this property to <literal>true</literal> if your JDBC driver returns " +"correct row counts from <literal>executeBatch()</literal>. Iit is usually " +"safe to turn this option on. Hibernate will then use batched DML for " +"automatically versioned data. Defaults to <literal>false</literal>." +msgstr "" +"Paramétrez cette propriété à <literal>true</literal> si votre pilote JDBC " +"retourne des comptes de lignes corrects depuis <literal>executeBatch()</" +"literal> (il est souvent approprié d'activer cette option). Hibernate " +"utilisera alors le \"batched DML\" pour les données automatiquement " +"versionnées. Par défaut à <literal>false</literal>. " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.factory_class</property>" +msgstr "<property>hibernate.jdbc.factory_class</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Select a custom <interfacename>org.hibernate.jdbc.Batcher</interfacename>. " +"Most applications will not need this configuration property." +msgstr "" +"Sélectionne un <interfacename>org.hibernate.jdbc.Batcher</interfacename> " +"personnalisé. La plupart des applications n'auront pas besoin de cette " +"propriété de configuration." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of." +"BatcherFactory</literal>" +msgstr "" +"<emphasis role=\"strong\">par.ex.</emphasis> <literal>classname.of." +"BatcherFactory</literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.use_scrollable_resultset</property>" +msgstr "<property>hibernate.jdbc.use_scrollable_resultset</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Enables use of JDBC2 scrollable resultsets by Hibernate. This property is " +"only necessary when using user-supplied JDBC connections. Hibernate uses " +"connection metadata otherwise." +msgstr "" +"Active l'utilisation par Hibernate des ensembles de résultats déroulants de " +"JDBC2. Cette propriété est seulement nécessaire lorsque l'on utilise des " +"connexions JDBC fournies par l'utilisateur. Autrement, Hibernate utilise les " +"métadonnées de la connexion." + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.use_streams_for_binary</property>" +msgstr "<property>hibernate.jdbc.use_streams_for_binary</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Use streams when writing/reading <literal>binary</literal> or " +"<literal>serializable</literal> types to/from JDBC. <emphasis>*system-level " +"property*</emphasis>" +msgstr "" +"Utilise des flux lorsque l'on écrit/lit des types <literal>binary</literal> " +"ou des types <literal>serializable</literal>vers/à partir de JDBC. " +"<emphasis>*system-level property*</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.jdbc.use_get_generated_keys</property>" +msgstr "<property>hibernate.jdbc.use_get_generated_keys</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Enables use of JDBC3 <literal>PreparedStatement.getGeneratedKeys()</literal> " +"to retrieve natively generated keys after insert. Requires JDBC3+ driver and " +"JRE1.4+, set to false if your driver has problems with the Hibernate " +"identifier generators. By default, it tries to determine the driver " +"capabilities using connection metadata." +msgstr "" +"Active l'utilisation de <literal>PreparedStatement.getGeneratedKeys()</" +"literal> de JDBC3 pour récupérer nativement les clés générées après " +"insertion. Nécessite un pilote JDBC3+ et JRE1.4+, configurés à false si " +"votre pilote a des problèmes avec les générateurs d'identifiant Hibernate. " +"Par défaut, essaie de déterminer les possibilités du pilote en utilisant les " +"metadonnées de connexion." + +#. Tag: para +#, no-c-format +msgid "<emphasis role=\"strong\">e.g.</emphasis> <literal>true|false</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis> <literal>true|false</literal>" + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.provider_class</property>" +msgstr "<property>hibernate.connection.provider_class</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"The classname of a custom <interfacename>org.hibernate.connection." +"ConnectionProvider</interfacename> which provides JDBC connections to " +"Hibernate." +msgstr "" +"Le nom de la classe d'un <interfacename>org.hibernate.connection." +"ConnectionProvider</interfacename> personnalisé qui fournit des connexions " +"JDBC à Hibernate." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of." +"ConnectionProvider</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>classname.of." +"ConnectionProvider</literal> " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.isolation</property>" +msgstr "<property>hibernate.connection.isolation</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Sets the JDBC transaction isolation level. Check <interfacename>java.sql." +"Connection</interfacename> for meaningful values, but note that most " +"databases do not support all isolation levels and some define additional, " +"non-standard isolations." +msgstr "" +"Définit le niveau d'isolation des transactions JDBC. Regardez <literal>java." +"sql.Connection</literal> pour des valeurs significatives mais notez " +"également que la plupart des bases de données ne supportent pas tous les " +"niveaux d'isolation et que certaines définissent des isolations non standard " +"supplémentaires." + +#. Tag: para +#, no-c-format +msgid "<emphasis role=\"strong\">e.g.</emphasis> <literal>1, 2, 4, 8</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>1, 2, 4, 8</literal> " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.autocommit</property>" +msgstr " hibernate.connection.autocommit" + +#. Tag: entry +#, no-c-format +msgid "Enables autocommit for JDBC pooled connections (it is not recommended)." +msgstr "" +"Active le mode de commit automatique (autocommit) pour les connexions JDBC " +"du pool (non recommandé). " + +#. Tag: entry +#, no-c-format +msgid "<property>hibernate.connection.release_mode</property>" +msgstr "<property>hibernate.connection.release_mode</property>" + +#. Tag: entry +#, no-c-format +msgid "" +"Specifies when Hibernate should release JDBC connections. By default, a JDBC " +"connection is held until the session is explicitly closed or disconnected. " +"For an application server JTA datasource, use <literal>after_statement</" +"literal> to aggressively release connections after every JDBC call. For a " +"non-JTA connection, it often makes sense to release the connection at the " +"end of each transaction, by using <literal>after_transaction</literal>. " +"<literal>auto</literal> will choose <literal>after_statement</literal> for " +"the JTA and CMT transaction strategies and <literal>after_transaction</" +"literal> for the JDBC transaction strategy." +msgstr "" +"Spécifie à quel moment Hibernate doit relâcher les connexions JDBC. Par " +"défaut, une connexion JDBC est conservée jusqu'à ce que la session soit " +"explicitement fermée ou déconnectée. Pour une source de données JTA d'un " +"serveur d'applications, vous devriez utiliser <literal>after_statement</" +"literal> pour libérer les connexions de manière plus agressive après chaque " +"appel JDBC. Pour une connexion non JTA, il est souvent préférable de libérer " +"la connexion à la fin de chaque transaction en utilisant " +"<literal>after_transaction</literal>. <literal>auto</literal> choisira " +"<literal>after_statement</literal> pour les stratégies de transactions JTA " +"et CMT et <literal>after_transaction</literal> pour des stratégies de " +"transactions JDBC. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>auto</literal> (default) " +"| <literal>on_close</literal> | <literal>after_transaction</literal> | " +"<literal>after_statement</literal>" +msgstr "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>auto</literal> (default) " +"| <literal>on_close</literal> | <literal>after_transaction</literal> | " +"<literal>after_statement</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"This setting only affects <literal>Session</literal>s returned from " +"<literal>SessionFactory.openSession</literal>. For <literal>Session</" +"literal>s obtained through <literal>SessionFactory.getCurrentSession</" +"literal>, the <literal>CurrentSessionContext</literal> implementation " +"configured for use controls the connection release mode for those " +"<literal>Session</literal>s. See <xref linkend=\"architecture-current-session" +"\" />" +msgstr "" +"Remarquez que ce paramètre influence uniquement les <literal>Session</" +"literal> s retournées depuis <literal>SessionFactory.openSession</literal>. " +"Pour les <literal>Session</literal> s obtenues depuis " +"<literal>SessionFactory.getCurrentSession</literal>, l'implémentation " +"<literal>CurrentSessionContext</literal> configurée pour l'utilisation, " +"contrôle le mode de libération des connexions pour ces <literal>Session</" +"literal> s. Consultez <xref linkend=\"architecture-current-session\" />" + +#. Tag: entry +#, no-c-format +msgid "" +"<property>hibernate.connection.</property><emphasis>&lt;propertyName&gt;</" +"emphasis>" +msgstr "" +"<property>hibernate.connection.</property><emphasis>&lt;propertyName&gt;</" +"emphasis>" + +#. Tag: entry +#, no-c-format +msgid "" +"Pass the JDBC property <emphasis>&lt;propertyName&gt;</emphasis> to " +"<literal>DriverManager.getConnection()</literal>." +msgstr "" +"Passez une propriété JDBC <literal>propertyName</literal> à " +"<literal>DriverManager.getConnection()</literal>. " + +#. Tag: entry +#, no-c-format +msgid "" +"<property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis>" +msgstr "" +"<property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis>" + +#. Tag: entry +#, no-c-format +msgid "" +"Pass the property <emphasis>&lt;propertyName&gt;</emphasis> to the JNDI " +"<literal>InitialContextFactory</literal>." +msgstr "" +"Passez la propriété <emphasis>&lt;propertyName&gt;</emphasis> au JNDI " +"<literal>InitialContextFactory</literal>." + +#. Tag: title +#, no-c-format +msgid "Hibernate Cache Properties" +msgstr "Propriétés du Cache Hibernate" + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.provider_class</literal>" +msgstr "<literal>hibernate.cache.provider_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "The classname of a custom <literal>CacheProvider</literal>." +msgstr "Le nom de classe d'un <literal>CacheProvider</literal> personnalisé." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of." +"CacheProvider</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>classname.of." +"CacheProvider</literal> " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.use_minimal_puts</literal>" +msgstr "<literal>hibernate.cache.use_minimal_puts</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Optimizes second-level cache operation to minimize writes, at the cost of " +"more frequent reads. This setting is most useful for clustered caches and, " +"in Hibernate3, is enabled by default for clustered cache implementations." +msgstr "" +"Optimise le cache de second niveau en minimisant les écritures, au prix de " +"plus de lectures. Ce paramètre est surtout utile pour les caches en cluster," +"et est activé par défaut dans hibernate3 pour les implémentations de cache " +"en cluster. " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.use_query_cache</literal>" +msgstr "<literal>hibernate.cache.use_query_cache</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Enables the query cache. Individual queries still have to be set cachable." +msgstr "" +"Activer le cache de requête, les requêtes individuelles doivent tout de même " +"être déclarées comme pouvant être mises en cache." + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.use_second_level_cache</literal>" +msgstr "<literal>hibernate.cache.use_second_level_cache</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Can be used to completely disable the second level cache, which is enabled " +"by default for classes which specify a <literal>&lt;cache&gt;</literal> " +"mapping." +msgstr "" +"Peut être utilisé pour désactiver complètement le cache de second niveau qui " +"est activé par défaut pour les classes qui spécifient un élément " +"<literal>&lt;cache&gt;</literal> dans leur mappage. " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.query_cache_factory</literal>" +msgstr "<literal>hibernate.cache.query_cache_factory</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"The classname of a custom <literal>QueryCache</literal> interface, defaults " +"to the built-in <literal>StandardQueryCache</literal>." +msgstr "" +"Le nom de classe d'une interface <literal>QueryCache</literal> " +"personnalisée, par défaut prend la valeur du <literal>StandardQueryCache</" +"literal> imbriqué." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of.QueryCache</" +"literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>classname.of." +"QueryCache</literal> " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.region_prefix</literal>" +msgstr "<literal>hibernate.cache.region_prefix</literal>" + +#. Tag: entry +#, no-c-format +msgid "A prefix to use for second-level cache region names." +msgstr "" +"Un préfixe à utiliser pour les noms de régions du cache de second niveau. " + +#. Tag: para +#, no-c-format +msgid "<emphasis role=\"strong\">e.g.</emphasis> <literal>prefix</literal>" +msgstr "<emphasis role=\"strong\">par ex.</emphasis> <literal>prefix</literal>" + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.cache.use_structured_entries</literal>" +msgstr "<literal>hibernate.cache.use_structured_entries</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Forces Hibernate to store data in the second-level cache in a more human-" +"friendly format." +msgstr "" +"Force Hibernate à stocker les données dans le cache de second niveau en un " +"format plus adapté à la visualisation. " + +#. Tag: title +#, no-c-format +msgid "Hibernate Transaction Properties" +msgstr "Propriétés des transactions Hibernate" + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.transaction.factory_class</literal>" +msgstr "<literal>hibernate.transaction.factory_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"The classname of a <literal>TransactionFactory</literal> to use with " +"Hibernate <literal>Transaction</literal> API (defaults to " +"<literal>JDBCTransactionFactory</literal>)." +msgstr "" +"Le nom de classe d'une <literal>TransactionFactory</literal> qui sera " +"utilisée par l'API <literal>Transaction</literal> de Hibernate (la valeur " +"par défaut est <literal>JDBCTransactionFactory</literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of." +"TransactionFactory</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>classname.of." +"TransactionFactory</literal> " + +#. Tag: entry +#, no-c-format +msgid "<literal>jta.UserTransaction</literal>" +msgstr "<literal>jta.UserTransaction</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"A JNDI name used by <literal>JTATransactionFactory</literal> to obtain the " +"JTA <literal>UserTransaction</literal> from the application server." +msgstr "" +"Le nom JNDI utilisé par la <literal>JTATransactionFactory</literal> pour " +"obtenir la <literal>UserTransaction</literal> JTA du serveur d'applications." + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.transaction.manager_lookup_class</literal>" +msgstr "<literal>hibernate.transaction. manager_lookup_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"The classname of a <literal>TransactionManagerLookup</literal>. It is " +"required when JVM-level caching is enabled or when using hilo generator in a " +"JTA environment." +msgstr "" +"Le nom de la classe d'une <literal>TransactionManagerLookup</literal> - " +"requise lorsque le cache de niveau JVM est activé ou lorsque l'on utilise un " +"générateur hilo dans un environnement JTA." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>classname.of." +"TransactionManagerLookup</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>classname.of." +"TransactionManagerLookup</literal> " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.transaction.flush_before_completion</literal>" +msgstr "<literal>hibernate.transaction. flush_before_completion</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"If enabled, the session will be automatically flushed during the before " +"completion phase of the transaction. Built-in and automatic session context " +"management is preferred, see <xref linkend=\"architecture-current-session\" /" +">." +msgstr "" +"Si activé, la session sera automatiquement vidée durant la phase qui précède " +"la fin de la transaction. La gestion automatique et imbriquée du contexte de " +"session fourni par Hibernate est préférable, consultez <xref linkend=" +"\"architecture-current-session\" />." + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.transaction.auto_close_session</literal>" +msgstr "<literal>hibernate.transaction. auto_close_session</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"If enabled, the session will be automatically closed during the after " +"completion phase of the transaction. Built-in and automatic session context " +"management is preferred, see <xref linkend=\"architecture-current-session\" /" +">." +msgstr "" +"Si activé, la session sera automatiquement fermée pendant la phase qui suit " +"la fin de la transaction. La gestion automatique et imbriquée du contexte de " +"session fourni par Hibernate est préférable, consultez <xref linkend=" +"\"architecture-current-session\" />." + +#. Tag: title +#, no-c-format +msgid "Miscellaneous Properties" +msgstr "Propriétés diverses" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.current_session_context_class</literal>" +msgstr "<literal>hibernate. current_session_context_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Supply a custom strategy for the scoping of the \"current\" " +"<literal>Session</literal>. See <xref linkend=\"architecture-current-session" +"\" /> for more information about the built-in strategies." +msgstr "" +"Fournit une stratégie particulière pour la portée de la <literal>Session</" +"literal> courante. Consultez <xref linkend=\"architecture-current-session\" /" +"> pour plus d'informations sur les stratégies incorporées. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>jta</literal> | " +"<literal>thread</literal> | <literal>managed</literal> | <literal>custom." +"Class</literal>" +msgstr "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>jta</literal> | " +"<literal>thread</literal> | <literal>managed</literal> | <literal>custom." +"Class</literal>" + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.query.factory_class</literal>" +msgstr "<literal>hibernate.query.factory_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "Chooses the HQL parser implementation." +msgstr "Choisit l'implémentation du parseur de requête HQL. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>org.hibernate.hql.ast." +"ASTQueryTranslatorFactory</literal> or <literal>org.hibernate.hql.classic." +"ClassicQueryTranslatorFactory</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>org.hibernate.hql.ast." +"ASTQueryTranslatorFactory</literal> ou <literal>org.hibernate.hql.classic." +"ClassicQueryTranslatorFactory</literal> " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.query.substitutions</literal>" +msgstr "<literal>hibernate.query.substitutions</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Is used to map from tokens in Hibernate queries to SQL tokens (tokens might " +"be function or literal names, for example)." +msgstr "" +"Lien entre les jetons de requêtes Hibernate et les jetons SQL (les jetons " +"peuvent être des fonctions ou des noms textuels par exemple)." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>hqlLiteral=SQL_LITERAL, " +"hqlFunction=SQLFUNC</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>hqlLiteral=SQL_LITERAL, " +"hqlFunction=SQLFUNC</literal> " + +#. Tag: entry +#, no-c-format +msgid "<literal>hibernate.hbm2ddl.auto</literal>" +msgstr "<literal>hibernate.hbm2ddl.auto</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Automatically validates or exports schema DDL to the database when the " +"<literal>SessionFactory</literal> is created. With <literal>create-drop</" +"literal>, the database schema will be dropped when the " +"<literal>SessionFactory</literal> is closed explicitly." +msgstr "" +"Valide ou exporte automatiquement le schéma DDL vers la base de données " +"lorsque la <literal>SessionFactory</literal> est créée. La valeur " +"<literal>create-drop</literal> permet de supprimer le schéma de base de " +"données lorsque la <literal>SessionFactory</literal> est fermée " +"explicitement." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis role=\"strong\">e.g.</emphasis> <literal>validate</literal> | " +"<literal>update</literal> | <literal>create</literal> | <literal>create-" +"drop</literal>" +msgstr "" +"<emphasis role=\"strong\">par ex.</emphasis><literal>validate</literal> | " +"<literal>update</literal> | <literal>create</literal> | <literal>create-" +"drop</literal> " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.cglib.use_reflection_optimizer</literal>" +msgstr "<literal>hibernate.cglib. use_reflection_optimizer</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Enables the use of CGLIB instead of runtime reflection (System-level " +"property). Reflection can sometimes be useful when troubleshooting. " +"Hibernate always requires CGLIB even if you turn off the optimizer. You " +"cannot set this property in <literal>hibernate.cfg.xml</literal>." +msgstr "" +"Active l'utilisation de CGLIB à la place de la réflexion à l'exécution " +"(Propriété de niveau système). La réflexion peut parfois être utile pour " +"résoudre des problèmes. Notez que Hibernate a encore besoin et toujours de " +"CGLIB, même si l'optimiseur est désactivé. Vous ne pouvez pas configurer " +"cette propriété dans la <literal>hibernate.cfg.xml</literal>. " + +#. Tag: title +#, no-c-format +msgid "SQL Dialects" +msgstr "Dialectes SQL" + +#. Tag: para +#, no-c-format +msgid "" +"Always set the <literal>hibernate.dialect</literal> property to the correct " +"<literal>org.hibernate.dialect.Dialect</literal> subclass for your database. " +"If you specify a dialect, Hibernate will use sensible defaults for some of " +"the other properties listed above. This means that you will not have to " +"specify them manually." +msgstr "" +"Il est recommandé de toujours positionner la propriété <literal>hibernate." +"dialect</literal> à la sous-classe de <literal>org.hibernate.dialect." +"Dialect</literal> appropriée à votre base de données. Si vous spécifiez un " +"dialecte, Hibernate utilisera des valeurs adaptées pour certaines autres " +"propriétés listées ci-dessus, vous évitant ainsi de l'effectuer à la main. " + +#. Tag: title +#, no-c-format +msgid "Hibernate SQL Dialects (<literal>hibernate.dialect</literal>)" +msgstr "Dialectes SQL de Hibernate (<literal>hibernate.dialect</literal>)" + +#. Tag: entry +#, no-c-format +msgid "RDBMS" +msgstr "RDBMS" + +#. Tag: entry +#, no-c-format +msgid "Dialect" +msgstr "Dialecte" + +#. Tag: entry +#, no-c-format +msgid "DB2" +msgstr "DB2" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.DB2Dialect</literal>" +msgstr "<literal>org.hibernate.dialect.DB2Dialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "DB2 AS/400" +msgstr "DB2 AS/400" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.DB2400Dialect</literal>" +msgstr "<literal>org.hibernate.dialect.DB2400Dialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "DB2 OS390" +msgstr "DB2 OS390" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.DB2390Dialect</literal>" +msgstr "<literal>org.hibernate.dialect.DB2390Dialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "PostgreSQL" +msgstr "PostgreSQL" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.PostgreSQLDialect</literal>" +msgstr "<literal>org.hibernate.dialect.PostgreSQLDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "MySQL" +msgstr "MySQL" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.MySQLDialect</literal>" +msgstr "<literal>org.hibernate.dialect.MySQLDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "MySQL with InnoDB" +msgstr "MySQL with InnoDB" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.MySQLInnoDBDialect</literal>" +msgstr "<literal>org.hibernate.dialect.MySQLInnoDBDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "MySQL with MyISAM" +msgstr "MySQL with MyISAM" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.MySQLMyISAMDialect</literal>" +msgstr "<literal>org.hibernate.dialect.MySQLMyISAMDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Oracle (any version)" +msgstr "Oracle (toutes versions)" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.OracleDialect</literal>" +msgstr "<literal>org.hibernate.dialect.OracleDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Oracle 9i" +msgstr "Oracle 9i" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.Oracle9iDialect</literal>" +msgstr "<literal>org.hibernate.dialect.Oracle9iDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Oracle 10g" +msgstr "Oracle 10g" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.Oracle10gDialect</literal>" +msgstr "<literal>org.hibernate.dialect.Oracle10gDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Sybase" +msgstr "Sybase" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.SybaseDialect</literal>" +msgstr "<literal>org.hibernate.dialect.SybaseDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Sybase Anywhere" +msgstr "Sybase Anywhere" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.SybaseAnywhereDialect</literal>" +msgstr "<literal>org.hibernate.dialect.SybaseAnywhereDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Microsoft SQL Server" +msgstr "Microsoft SQL Server" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.SQLServerDialect</literal>" +msgstr "<literal>org.hibernate.dialect.SQLServerDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "SAP DB" +msgstr "SAP DB" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.SAPDBDialect</literal>" +msgstr "<literal>org.hibernate.dialect.SAPDBDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Informix" +msgstr "Informix" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.InformixDialect</literal>" +msgstr "<literal>org.hibernate.dialect.InformixDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "HypersonicSQL" +msgstr "HypersonicSQL" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.HSQLDialect</literal>" +msgstr "<literal>org.hibernate.dialect.HSQLDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Ingres" +msgstr "Ingres" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.IngresDialect</literal>" +msgstr "<literal>org.hibernate.dialect.IngresDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Progress" +msgstr "Progress" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.ProgressDialect</literal>" +msgstr "<literal>org.hibernate.dialect.ProgressDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Mckoi SQL" +msgstr "Mckoi SQL" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.MckoiDialect</literal>" +msgstr "<literal>org.hibernate.dialect.MckoiDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Interbase" +msgstr "Interbase" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.InterbaseDialect</literal>" +msgstr "<literal>org.hibernate.dialect.InterbaseDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Pointbase" +msgstr "Pointbase" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.PointbaseDialect</literal>" +msgstr "<literal>org.hibernate.dialect.PointbaseDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "FrontBase" +msgstr "FrontBase" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.FrontbaseDialect</literal>" +msgstr "<literal>org.hibernate.dialect.FrontbaseDialect</literal>" + +#. Tag: entry +#, no-c-format +msgid "Firebird" +msgstr "Firebird" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.dialect.FirebirdDialect</literal>" +msgstr "<literal>org.hibernate.dialect.FirebirdDialect</literal>" + +#. Tag: title +#, no-c-format +msgid "Outer Join Fetching" +msgstr "Chargement par jointure externe" + +#. Tag: para +#, no-c-format +msgid "" +"If your database supports ANSI, Oracle or Sybase style outer joins, " +"<emphasis>outer join fetching</emphasis> will often increase performance by " +"limiting the number of round trips to and from the database. This is, " +"however, at the cost of possibly more work performed by the database itself. " +"Outer join fetching allows a whole graph of objects connected by many-to-" +"one, one-to-many, many-to-many and one-to-one associations to be retrieved " +"in a single SQL <literal>SELECT</literal>." +msgstr "" +"Si votre base de données supporte les jointures externes de type ANSI, " +"Oracle ou Sybase, <emphasis>le chargement par jointure externe</emphasis> " +"devrait améliorer les performances en limitant le nombre d'aller-retour avec " +"la base de données (la base de données effectuant donc potentiellement plus " +"de travail). Le chargement par jointure ouverte permet à un graphe entier " +"d'objets connectés par une relation plusieurs-à-un, un-à-plusieurs ou un-à-" +"un d'être chargé en un seul SQL<literal>SELECT</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Outer join fetching can be disabled <emphasis>globally</emphasis> by setting " +"the property <literal>hibernate.max_fetch_depth</literal> to <literal>0</" +"literal>. A setting of <literal>1</literal> or higher enables outer join " +"fetching for one-to-one and many-to-one associations that have been mapped " +"with <literal>fetch=\"join\"</literal>." +msgstr "" +"Le chargement par jointure ouverte peut être désactivé " +"<emphasis>globalement</emphasis> en mettant la propriété <literal>hibernate." +"max_fetch_depth</literal> à <literal>0</literal>. Une valeur de <literal>1</" +"literal> ou plus active le chargement par jointure externe pour les " +"associations un-à-un et plusieurs-à-un qui ont été mappées avec " +"<literal>fetch=\"join\"</literal>. " + +#. Tag: para +#, no-c-format +msgid "See <xref linkend=\"performance-fetching\" /> for more information." +msgstr "" +"Reportez vous à <xref linkend=\"performance-fetching\" /> pour plus " +"d'informations." + +#. Tag: title +#, no-c-format +msgid "Binary Streams" +msgstr "Flux binaires" + +#. Tag: para +#, no-c-format +msgid "" +"Oracle limits the size of <literal>byte</literal> arrays that can be passed " +"to and/or from its JDBC driver. If you wish to use large instances of " +"<literal>binary</literal> or <literal>serializable</literal> type, you " +"should enable <literal>hibernate.jdbc.use_streams_for_binary</literal>. " +"<emphasis>This is a system-level setting only.</emphasis>" +msgstr "" +"Oracle limite la taille d'un tableau d'<literal>octets</literal> qui peuvent " +"être passés vers et à partir de son pilote JDBC. Si vous souhaitez utiliser " +"des instances larges de type <literal>binary</literal> ou " +"<literal>serializable</literal>, vous devez activer la propriété " +"<literal>hibernate.jdbc.use_streams_for_binary</literal>. <emphasis>C'est " +"une fonctionalité de niveau système uniquement.</emphasis>" + +#. Tag: title +#, no-c-format +msgid "Second-level and query cache" +msgstr "Cache de second niveau et cache de requêtes" + +#. Tag: para +#, no-c-format +msgid "" +"The properties prefixed by <literal>hibernate.cache</literal> allow you to " +"use a process or cluster scoped second-level cache system with Hibernate. " +"See the <xref linkend=\"performance-cache\" /> for more information." +msgstr "" +"Les propriétés préfixées par <literal>hibernate.cache</literal> vous " +"permettent d'utiliser un système de cache de second niveau avec Hibernate. " +"Référez vous à <xref linkend=\"performance-cache\" /> pour plus de détails." + +#. Tag: title +#, no-c-format +msgid "Query Language Substitution" +msgstr "Substitution dans le langage de requêtes" + +#. Tag: para +#, no-c-format +msgid "" +"You can define new Hibernate query tokens using <literal>hibernate.query." +"substitutions</literal>. For example:" +msgstr "" +"Vous pouvez définir de nouveaux jetons dans les requêtes Hibernate en " +"utilisant <literal>hibernate.query.substitutions</literal>. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"This would cause the tokens <literal>true</literal> and <literal>false</" +"literal> to be translated to integer literals in the generated SQL." +msgstr "" +"Cela signifierait que les jetons <literal>true</literal> et <literal>false</" +"literal> seraient transformés par des entiers dans le SQL généré." + +#. Tag: para +#, no-c-format +msgid "" +"This would allow you to rename the SQL <literal>LOWER</literal> function." +msgstr "Cela permettrait de renommer la fonction SQL <literal>LOWER</literal>." + +#. Tag: title +#, no-c-format +msgid "Hibernate statistics" +msgstr "Statistiques Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"If you enable <literal>hibernate.generate_statistics</literal>, Hibernate " +"exposes a number of metrics that are useful when tuning a running system via " +"<literal>SessionFactory.getStatistics()</literal>. Hibernate can even be " +"configured to expose these statistics via JMX. Read the Javadoc of the " +"interfaces in <literal>org.hibernate.stats</literal> for more information." +msgstr "" +"Si vous activez <literal>hibernate.generate_statistics</literal>, Hibernate " +"fournira un certain nombre de métriques utiles pour régler les performances " +"d'une application qui tourne via <literal>SessionFactory.getStatistics()</" +"literal>. Hibernate peut aussi être configuré pour exposer ces statistiques " +"via JMX. Lisez les Javadoc des interfaces dans le paquetage <literal>org." +"hibernate.stats</literal> pour plus d'informations. " + +#. Tag: title +#, no-c-format +msgid "Logging" +msgstr "Journalisation" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate utilizes <ulink url=\"http://www.slf4j.org/\">Simple Logging " +"Facade for Java</ulink> (SLF4J) in order to log various system events. SLF4J " +"can direct your logging output to several logging frameworks (NOP, Simple, " +"log4j version 1.2, JDK 1.4 logging, JCL or logback) depending on your chosen " +"binding. In order to setup logging you will need <filename>slf4j-api.jar</" +"filename> in your classpath together with the jar file for your preferred " +"binding - <filename>slf4j-log4j12.jar</filename> in the case of Log4J. See " +"the SLF4J <ulink url=\"http://www.slf4j.org/manual.html\">documentation</&... +"ulink> for more detail. To use Log4j you will also need to place a " +"<filename>log4j.properties</filename> file in your classpath. An example " +"properties file is distributed with Hibernate in the <literal>src/</literal> " +"directory." +msgstr "" +"Hibernate utilise <ulink url=\"http://www.slf4j.org/\">Simple Logging Facade " +"for Java</ulink> (SLF4J) pour enregistrer divers événements du système. " +"SLF4J peut diriger votre sortie de logging vers plusieurs structures de " +"loggings (NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) " +"suivant la liaison que vous choisirez. Pour pouvoir configurer votre " +"logging, vous aurez besoin de <filename>slf4j-api.jar</filename> dans votre " +"chemin de classe, ainsi que du fichier jar pour votre liaison préférée - " +"<filename>slf4j-log4j12.jar</filename> pour Log4J. Voir la documentation " +"SLF4J <ulink url=\"http://www.slf4j.org/manual.html\">documentation</u... " +"pour davantage d'informations. Pour utiliser Log4j, vous aurez aussi besoin " +"de mettre un fichier <filename>log4j.properties</filename> dans votre chemin " +"de classe. Un exemple de fichier de propriétés est distribué avec Hibernate " +"dans le répertoire <literal>src/</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"It is recommended that you familiarize yourself with Hibernate's log " +"messages. A lot of work has been put into making the Hibernate log as " +"detailed as possible, without making it unreadable. It is an essential " +"troubleshooting device. The most interesting log categories are the " +"following:" +msgstr "" +"Il est vivement recommandé de vous familiariser avec les messages des logs " +"de Hibernate. Beaucoup de soin a été apporté pour donner le plus de détails " +"possible sans les rendre illisibles. C'est un outil essentiel en cas de " +"problèmes. Les catégories de logs les plus intéressantes sont les " +"suivantes : " + +#. Tag: title +#, no-c-format +msgid "Hibernate Log Categories" +msgstr "Catégories de logs de Hibernate" + +#. Tag: entry +#, no-c-format +msgid "Category" +msgstr "Catégorie" + +#. Tag: entry +#, no-c-format +msgid "Function" +msgstr "Fonction" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.SQL</literal>" +msgstr "<literal>org.hibernate.SQL</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all SQL DML statements as they are executed" +msgstr "" +"Journalise toutes les requêtes SQL de type DML (gestion des données) qui " +"sont exécutées" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.type</literal>" +msgstr "<literal>org.hibernate.type</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all JDBC parameters" +msgstr "Journalise tous les paramètres JDBC" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.tool.hbm2ddl</literal>" +msgstr "<literal>org.hibernate.tool. hbm2ddl</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all SQL DDL statements as they are executed" +msgstr "" +"Journalise toutes les requêtes SQL de type DDL (gestion de la structure de " +"la base) qui sont exécutées" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.pretty</literal>" +msgstr "<literal>org.hibernate.pretty</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Log the state of all entities (max 20 entities) associated with the session " +"at flush time" +msgstr "" +"Journalise l'état de toutes les entités (20 entités maximum) associées avec " +"la session Hibernate au moment du flush" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.cache</literal>" +msgstr "<literal>org.hibernate.cache</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all second-level cache activity" +msgstr "Journalise toute activité du cache de second niveau" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.transaction</literal>" +msgstr "<literal>org.hibernate. transaction</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log transaction related activity" +msgstr "Journalise toute activité relative aux transactions" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.jdbc</literal>" +msgstr "<literal>org.hibernate.jdbc</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all JDBC resource acquisition" +msgstr "Journalise toute acquisition de ressource JDBC " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.hql.ast.AST</literal>" +msgstr "<literal>org.hibernate.hql. ast.AST</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log HQL and SQL ASTs during query parsing" +msgstr "" +"Journalise l'arbre syntaxique des requêtes HQL et SQL durant l'analyse " +"syntaxique des requêtes" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate.secure</literal>" +msgstr "<literal>org.hibernate.secure</literal>" + +#. Tag: entry +#, no-c-format +msgid "Log all JAAS authorization requests" +msgstr "Journalise toutes les demandes d'autorisation JAAS" + +#. Tag: entry +#, no-c-format +msgid "<literal>org.hibernate</literal>" +msgstr "<literal>org.hibernate</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"Log everything. This is a lot of information but it is useful for " +"troubleshooting" +msgstr "" +"Journalise tout (beaucoup d'informations, mais très utile pour résoudre les " +"problèmes)." + +#. Tag: para +#, no-c-format +msgid "" +"When developing applications with Hibernate, you should almost always work " +"with <literal>debug</literal> enabled for the category <literal>org." +"hibernate.SQL</literal>, or, alternatively, the property <literal>hibernate." +"show_sql</literal> enabled." +msgstr "" +"Lorsque vous développez des applications avec Hibernate, vous devriez " +"quasiment toujours travailler avec le niveau <literal>debug</literal> activé " +"pour la catégorie <literal>org.hibernate.SQL</literal>, ou sinon avec la " +"propriété <literal>hibernate.show_sql</literal> activée." + +#. Tag: title +#, no-c-format +msgid "Implementing a <literal>NamingStrategy</literal>" +msgstr "" +"Sélectionne une <literal>NamingStrategy</literal> (stratégie de nommage)" + +#. Tag: para +#, no-c-format +msgid "" +"The interface <literal>org.hibernate.cfg.NamingStrategy</literal> allows you " +"to specify a \"naming standard\" for database objects and schema elements." +msgstr "" +"L'interface <literal>org.hibernate.cfg.NamingStrategy</literal> vous permet " +"de spécifier une \"stratégie de nommage\" des objets et éléments de la base " +"de données." + +#. Tag: para +#, no-c-format +msgid "" +"You can provide rules for automatically generating database identifiers from " +"Java identifiers or for processing \"logical\" column and table names given " +"in the mapping file into \"physical\" table and column names. This feature " +"helps reduce the verbosity of the mapping document, eliminating repetitive " +"noise (<literal>TBL_</literal> prefixes, for example). The default strategy " +"used by Hibernate is quite minimal." +msgstr "" +"Vous pouvez fournir des règles pour automatiquement générer les identifiants " +"de base de données à partir des identifiants Java, ou transformer une " +"colonne ou table \"logique\" donnée dans le fichier de mappage en une " +"colonne ou table \"physique\". Cette fonctionnalité aide à réduire la " +"verbosité de documents de mappage, en éliminant le bruit répétitif (les " +"préfixes <literal>TBL_</literal> par exemple). La stratégie par défaut " +"utilisée par Hibernate est assez minimale." + +#. Tag: para +#, no-c-format +msgid "" +"You can specify a different strategy by calling <literal>Configuration." +"setNamingStrategy()</literal> before adding mappings:" +msgstr "" +"Vous pouvez définir une stratégie différente en appelant " +"<literal>Configuration.setNamingStrategy()</literal> avant d'ajouter des " +"mappages : " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a built-in " +"strategy that might be a useful starting point for some applications." +msgstr "" +"<literal>net.sf.hibernate.cfg.ImprovedNamingStrategy</literal> est une " +"stratégie fournie qui peut être utile comme point de départ de quelques " +"applications." + +#. Tag: title +#, no-c-format +msgid "XML configuration file" +msgstr "Fichier de configuration XML" + +#. Tag: para +#, no-c-format +msgid "" +"An alternative approach to configuration is to specify a full configuration " +"in a file named <literal>hibernate.cfg.xml</literal>. This file can be used " +"as a replacement for the <literal>hibernate.properties</literal> file or, if " +"both are present, to override properties." +msgstr "" +"Une approche alternative est de spécifier toute la configuration dans un " +"fichier nommé <literal>hibernate.cfg.xml</literal>. Ce fichier peut être " +"utilisé à la place du fichier <literal>hibernate.properties</literal>, voire " +"même peut servir à surcharger les propriétés si les deux fichiers sont " +"présents." + +#. Tag: para +#, no-c-format +msgid "" +"The XML configuration file is by default expected to be in the root of your " +"<literal>CLASSPATH</literal>. Here is an example:" +msgstr "" +"Le fichier de configuration XML doit par défaut se placer à la racine du " +"<literal>CLASSPATH</literal>. En voici un exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"The advantage of this approach is the externalization of the mapping file " +"names to configuration. The <literal>hibernate.cfg.xml</literal> is also " +"more convenient once you have to tune the Hibernate cache. It is your choice " +"to use either <literal>hibernate.properties</literal> or <literal>hibernate." +"cfg.xml</literal>. Both are equivalent, except for the above mentioned " +"benefits of using the XML syntax." +msgstr "" +"Comme vous pouvez le constater, l'avantage de cette approche est " +"l'externalisation des noms des fichiers de mappage de la configuration. Le " +"fichier <literal>hibernate.cfg.xml</literal> est également plus pratique " +"quand on commence à régler le cache d'Hibernate. Notez que vous pouvez " +"choisir entre utiliser <literal>hibernate.properties</literal> ou " +"<literal>hibernate.cfg.xml</literal>, les deux sont équivalents, sauf en ce " +"qui concerne les bénéfices de l'utilisation de la syntaxe XML mentionnés ci-" +"dessus. " + +#. Tag: para +#, no-c-format +msgid "With the XML configuration, starting Hibernate is then as simple as:" +msgstr "" +"Avec la configuration XML, démarrer Hibernate devient donc aussi simple que " +"ceci : " + +#. Tag: para +#, no-c-format +msgid "You can select a different XML configuration file using:" +msgstr "" +"Vous pouvez choisir un fichier de configuration XML différent en utilisant : " + +#. Tag: title +#, no-c-format +msgid "J2EE Application Server integration" +msgstr "Intégration à un serveur d'applications J2EE" + +#. Tag: para +#, no-c-format +msgid "Hibernate has the following integration points for J2EE infrastructure:" +msgstr "" +"Hibernate possède les points d'intégration suivants pour l'infrastructure " +"J2EE :" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Container-managed datasources</emphasis>: Hibernate can use JDBC " +"connections managed by the container and provided through JNDI. Usually, a " +"JTA compatible <literal>TransactionManager</literal> and a " +"<literal>ResourceManager</literal> take care of transaction management " +"(CMT), especially distributed transaction handling across several " +"datasources. You can also demarcate transaction boundaries programmatically " +"(BMT), or you might want to use the optional Hibernate <literal>Transaction</" +"literal> API for this to keep your code portable." +msgstr "" +"<emphasis>Source de données gérée par le conteneur</emphasis> : Hibernate " +"peut utiliser des connexions JDBC gérées par le conteneur et fournies par " +"l'intermédiaire de JNDI. Souvent, un <literal>TransactionManager</literal> " +"compatible JTA et un <literal>ResourceManager</literal> s'occupent de la " +"gestion des transactions (CMT). Ils sont conçus en particulier pour gérer " +"des transactions distribuées sur plusieurs sources de données. Vous pouvez " +"biensûr également définir les limites des transactions dans votre programme " +"(BMT) ou vous pouvez par ailleurs utiliser l'API optionnelle " +"<literal>Transaction</literal> de Hibernate qui vous garantira la " +"portabilité de votre code entre plusieurs serveurs d'application. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Automatic JNDI binding</emphasis>: Hibernate can bind its " +"<literal>SessionFactory</literal> to JNDI after startup." +msgstr "" +"<emphasis>Association JNDI automatique</emphasis>: Hibernate peut associer " +"sa <literal>SessionFactory</literal> à JNDI après le démarrage." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>JTA Session binding:</emphasis> the Hibernate <literal>Session</" +"literal> can be automatically bound to the scope of JTA transactions. Simply " +"lookup the <literal>SessionFactory</literal> from JNDI and get the current " +"<literal>Session</literal>. Let Hibernate manage flushing and closing the " +"<literal>Session</literal> when your JTA transaction completes. Transaction " +"demarcation is either declarative (CMT) or programmatic (BMT/" +"UserTransaction)." +msgstr "" +"<emphasis>Association de la Session à JTA:</emphasis> la <literal>Session</" +"literal> Hibernate peut être automatiquement associée à la portée des " +"transactions JTA si vous utilisez les EJB. Vous avez juste à récupérer la " +"<literal>SessionFactory</literal> depuis JNDI et à récupérer la " +"<literal>Session</literal> courante. Hibernate s'occupe de vider et fermer " +"la <literal>Session</literal> lorsque votre transaction JTA se termine. La " +"démarcation des transactions se fait de manière déclarative (CMT) ou de " +"façon programmatique (BMT/UserTransaction)." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>JMX deployment:</emphasis> if you have a JMX capable application " +"server (e.g. JBoss AS), you can choose to deploy Hibernate as a managed " +"MBean. This saves you the one line startup code to build your " +"<literal>SessionFactory</literal> from a <literal>Configuration</literal>. " +"The container will startup your <literal>HibernateService</literal> and also " +"take care of service dependencies (datasource has to be available before " +"Hibernate starts, etc)." +msgstr "" +"<emphasis>Déploiement JMX :</emphasis>Si vous avez un serveur d'applications " +"compatible JMX (JBoss AS par exemple), vous pouvez choisir de déployer " +"Hibernate en tant que MBean géré par le serveur. Cela vous évite de coder la " +"ligne de démarrage qui permet de construire la <literal>SessionFactory</" +"literal> depuis la <literal>Configuration</literal>. Le conteneur va " +"démarrer votre <literal>HibernateService</literal>, et va idéalement " +"s'occuper des dépendances entre les services (la source de données doit être " +"disponible avant le démarrage de Hibernate, etc). " + +#. Tag: para +#, no-c-format +msgid "" +"Depending on your environment, you might have to set the configuration " +"option <literal>hibernate.connection.aggressive_release</literal> to true if " +"your application server shows \"connection containment\" exceptions." +msgstr "" +"En fonction de votre environnement, vous mettrez l'option de configuration " +"<literal>hibernate.connection.aggressive_release</literal> à true si le " +"serveur d'applications affiche des exceptions de type \"connection " +"containment\"." + +#. Tag: title +#, no-c-format +msgid "Transaction strategy configuration" +msgstr "Configuration de la stratégie transactionnelle" + +#. Tag: para +#, no-c-format +msgid "" +"The Hibernate <literal>Session</literal> API is independent of any " +"transaction demarcation system in your architecture. If you let Hibernate " +"use JDBC directly through a connection pool, you can begin and end your " +"transactions by calling the JDBC API. If you run in a J2EE application " +"server, you might want to use bean-managed transactions and call the JTA API " +"and <literal>UserTransaction</literal> when needed." +msgstr "" +"L'API de la <literal>Session</literal> Hibernate est indépendante de tout " +"système de démarcation des transactions, présent dans votre architecture. Si " +"vous laissez Hibernate utiliser l'API JDBC directement via un pool de " +"connexion, vous commencerez et terminerez vos transactions en appelant l'API " +"JDBC. Si votre application tourne à l'intérieur d'un serveur d'applications " +"J2EE, vous utiliserez peut être les transactions gérées par les beans (BMT) " +"et vous appellerez l'API JTA et <literal>UserTransaction</literal> lorsque " +"cela est nécessaire. " + +#. Tag: para +#, no-c-format +msgid "" +"To keep your code portable between these two (and other) environments we " +"recommend the optional Hibernate <literal>Transaction</literal> API, which " +"wraps and hides the underlying system. You have to specify a factory class " +"for <literal>Transaction</literal> instances by setting the Hibernate " +"configuration property <literal>hibernate.transaction.factory_class</" +"literal>." +msgstr "" +"Pour conserver votre code portable entre ces deux environnements (et " +"d'autres), nous vous recommandons d'utiliser l'API optionnelle " +"<literal>Transaction</literal> d'Hibernate, qui encapsule et masque le " +"système de transaction sous-jacent. Pour cela, vous devez préciser une " +"classe de fabrique d'instances de <literal>Transaction</literal> en " +"positionnant la propriété de configuration <literal>hibernate.transaction." +"factory_class</literal>." + +#. Tag: para +#, no-c-format +msgid "There are three standard, or built-in, choices:" +msgstr "Il existe trois choix standards (intégrés) : " + +#. Tag: term +#, no-c-format +msgid "<literal>org.hibernate.transaction.JDBCTransactionFactory</literal>" +msgstr "<literal>org.hibernate.transaction.JDBCTransactionFactory</literal>" + +#. Tag: para +#, no-c-format +msgid "delegates to database (JDBC) transactions (default)" +msgstr "" +"délègue aux transactions de la base de données (JDBC) (valeur par défaut)." + +#. Tag: term +#, no-c-format +msgid "<literal>org.hibernate.transaction.JTATransactionFactory</literal>" +msgstr "<literal>org.hibernate.transaction.JTATransactionFactory</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"delegates to container-managed transactions if an existing transaction is " +"underway in this context (for example, EJB session bean method). Otherwise, " +"a new transaction is started and bean-managed transactions are used." +msgstr "" +"délègue à CMT si une transaction existante est sous ce contexte (par ex : " +"méthode d'un EJB session), sinon une nouvelle transaction est entamée et une " +"transaction gérée par le bean est utilisée. " + +#. Tag: term +#, no-c-format +msgid "<literal>org.hibernate.transaction.CMTTransactionFactory</literal>" +msgstr "<literal>org.hibernate.transaction.CMTTransactionFactory</literal>" + +#. Tag: para +#, no-c-format +msgid "delegates to container-managed JTA transactions" +msgstr "délègue aux transactions JTA gérées par le conteneur" + +#. Tag: para +#, no-c-format +msgid "" +"You can also define your own transaction strategies (for a CORBA transaction " +"service, for example)." +msgstr "" +"Vous pouvez également définir vos propres stratégies transactionnelles (pour " +"un service de transaction CORBA par exemple). " + +#. Tag: para +#, no-c-format +msgid "" +"Some features in Hibernate (i.e., the second level cache, Contextual " +"Sessions with JTA, etc.) require access to the JTA " +"<literal>TransactionManager</literal> in a managed environment. In an " +"application server, since J2EE does not standardize a single mechanism, you " +"have to specify how Hibernate should obtain a reference to the " +"<literal>TransactionManager</literal>:" +msgstr "" +"Certaines fonctionnalités de Hibernate (c'est-à-dire le cache de second " +"niveau, l'association automatique des Sessions à JTA, etc.) nécessitent " +"l'accès au <literal>TransactionManager</literal> JTA dans un environnement " +"géré. Dans un serveur d'applications, vous devez indiquer comment Hibernate " +"peut obtenir une référence vers le <literal>TransactionManager</literal>, " +"car J2EE ne fournit pas un seul mécanisme standard. " + +#. Tag: title +#, no-c-format +msgid "JTA TransactionManagers" +msgstr "TransactionManagers JTA" + +#. Tag: entry +#, no-c-format +msgid "Transaction Factory" +msgstr "Fabrique de transaction" + +#. Tag: entry +#, no-c-format +msgid "Application Server" +msgstr "Serveur d'applications" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.JBossTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. JBossTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "JBoss" +msgstr "JBoss" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.WeblogicTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. WeblogicTransactionManagerLookup</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "Weblogic" +msgstr "Weblogic" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.WebSphereTransactionManagerLookup</" +"literal>" +msgstr "" +"<literal>org.hibernate.transaction. WebSphereTransactionManagerLookup</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "WebSphere" +msgstr "WebSphere" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.WebSphereExtendedJTATransactionLookup</" +"literal>" +msgstr "" +"<literal>org.hibernate.transaction. WebSphereExtendedJTATransactionLookup</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "WebSphere 6" +msgstr "WebSphere 6" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.OrionTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. OrionTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "Orion" +msgstr "Orion" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.ResinTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. ResinTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "Resin" +msgstr "Resin" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.JOTMTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. JOTMTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "JOTM" +msgstr "JOTM" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.JOnASTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. JOnASTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "JOnAS" +msgstr "JOnAS" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.JRun4TransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. JRun4TransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "JRun4" +msgstr "JRun4" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>org.hibernate.transaction.BESTransactionManagerLookup</literal>" +msgstr "" +"<literal>org.hibernate.transaction. BESTransactionManagerLookup</literal>" + +#. Tag: entry +#, no-c-format +msgid "Borland ES" +msgstr "Borland ES" + +#. Tag: title +#, no-c-format +msgid "JNDI-bound <literal>SessionFactory</literal>" +msgstr "<literal>SessionFactory</literal> associée au JNDI" + +#. Tag: para +#, no-c-format +msgid "" +"A JNDI-bound Hibernate <literal>SessionFactory</literal> can simplify the " +"lookup function of the factory and create new <literal>Session</literal>s. " +"This is not, however, related to a JNDI bound <literal>Datasource</literal>; " +"both simply use the same registry." +msgstr "" +"Une <literal>SessionFactory</literal> Hibernate associée au JNDI peut " +"simplifier l'accès à la fabrique et donc la création de nouvelles " +"<literal>Session</literal> s. Notez que cela n'est pas lié avec les " +"<literal>Datasource</literal> associées au JNDI, elles utilisent juste le " +"même registre ! " + +#. Tag: para +#, no-c-format +msgid "" +"If you wish to have the <literal>SessionFactory</literal> bound to a JNDI " +"namespace, specify a name (e.g. <literal>java:hibernate/SessionFactory</" +"literal>) using the property <literal>hibernate.session_factory_name</" +"literal>. If this property is omitted, the <literal>SessionFactory</literal> " +"will not be bound to JNDI. This is especially useful in environments with a " +"read-only JNDI default implementation (in Tomcat, for example)." +msgstr "" +"Si vous désirez associer la <literal>SessionFactory</literal> à un nom JNDI, " +"spécifiez un nom (par ex. <literal>java:hibernate/SessionFactory</literal>) " +"en utilisant la propriété <literal>hibernate.session_factory_name</literal>. " +"Si cette propriété est omise, la <literal>SessionFactory</literal> ne sera " +"pas associée au JNDI (c'est particulièrement pratique dans les " +"environnements ayant une implémentation JNDI par défaut en lecture seule, " +"comme c'est le cas pour Tomcat). " + +#. Tag: para +#, no-c-format +msgid "" +"When binding the <literal>SessionFactory</literal> to JNDI, Hibernate will " +"use the values of <literal>hibernate.jndi.url</literal>, <literal>hibernate." +"jndi.class</literal> to instantiate an initial context. If they are not " +"specified, the default <literal>InitialContext</literal> will be used." +msgstr "" +"Lorsqu'il associe la <literal>SessionFactory</literal> au JNDI, Hibernate " +"utilisera les valeurs de <literal>hibernate.jndi.url</literal>, " +"<literal>hibernate.jndi.class</literal> pour instancier un contexte " +"d'initialisation. S'ils ne sont pas spécifiés, l'<literal>InitialContext</" +"literal> par défaut sera utilisé. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will automatically place the <literal>SessionFactory</literal> in " +"JNDI after you call <literal>cfg.buildSessionFactory()</literal>. This means " +"you will have this call in some startup code, or utility class in your " +"application, unless you use JMX deployment with the " +"<literal>HibernateService</literal> (this is discussed later in greater " +"detail)." +msgstr "" +"Hibernate va automatiquement placer la <literal>SessionFactory</literal> " +"dans JNDI après avoir appelé <literal>cfg.buildSessionFactory()</literal>. " +"Cela signifie que vous devez avoir cet appel dans un code de démarrage (ou " +"dans une classe utilitaire) dans votre application sauf si vous utilisez le " +"déploiement JMX avec le service <literal>HibernateService</literal> présenté " +"plus tard dans ce document. " + +#. Tag: para +#, no-c-format +msgid "" +"If you use a JNDI <literal>SessionFactory</literal>, an EJB or any other " +"class, you can obtain the <literal>SessionFactory</literal> using a JNDI " +"lookup." +msgstr "" +"Si vous utilisez <literal>SessionFactory</literal> JNDI, un EJB ou n'importe " +"quelle autre classe peut obtenir la <literal>SessionFactory</literal> en " +"utilisant une recherche JNDI. " + +#. Tag: para +#, no-c-format +msgid "" +"It is recommended that you bind the <literal>SessionFactory</literal> to " +"JNDI in a managed environment and use a <literal>static</literal> singleton " +"otherwise. To shield your application code from these details, we also " +"recommend to hide the actual lookup code for a <literal>SessionFactory</" +"literal> in a helper class, such as <literal>HibernateUtil.getSessionFactory" +"()</literal>. Note that such a class is also a convenient way to startup " +"Hibernate&mdash;see chapter 1." +msgstr "" +"Nous recommandons de lier la <literal>SessionFactory</literal> à JNDI dans " +"les environnements gérés et d'utilisier un singleton <literal>static</" +"literal> si ce n'est pas le cas. Pour isoler votre application de ces " +"détails, nous vous recommandons aussi de masquer le code de recherche actuel " +"pour une <literal>SessionFactory</literal> dans une classe helper, comme " +"<literal>HibernateUtil.getSessionFactory()</literal>. Notez qu'une telle " +"classe est aussi un moyen efficace de démarrer Hibernate - voir chapitre 1. " + +#. Tag: title +#, no-c-format +msgid "Current Session context management with JTA" +msgstr "Gestion du contexte de la session courante à JTA" + +#. Tag: para +#, no-c-format +msgid "" +"The easiest way to handle <literal>Sessions</literal> and transactions is " +"Hibernate's automatic \"current\" <literal>Session</literal> management. For " +"a discussion of contextual sessions see <xref linkend=\"architecture-current-" +"session\" />. Using the <literal>\"jta\"</literal> session context, if there " +"is no Hibernate <literal>Session</literal> associated with the current JTA " +"transaction, one will be started and associated with that JTA transaction " +"the first time you call <literal>sessionFactory.getCurrentSession()</" +"literal>. The <literal>Session</literal>s retrieved via " +"<literal>getCurrentSession()</literal> in the<literal>\"jta\"</literal> " +"context are set to automatically flush before the transaction completes, " +"close after the transaction completes, and aggressively release JDBC " +"connections after each statement. This allows the <literal>Session</" +"literal>s to be managed by the life cycle of the JTA transaction to which it " +"is associated, keeping user code clean of such management concerns. Your " +"code can either use JTA programmatically through <literal>UserTransaction</" +"literal>, or (recommended for portable code) use the Hibernate " +"<literal>Transaction</literal> API to set transaction boundaries. If you run " +"in an EJB container, declarative transaction demarcation with CMT is " +"preferred." +msgstr "" +"Le moyen le plus simple de gérer les <literal>Session</literal>s et " +"transactions est la gestion automatique de session \"courante\" offerte par " +"Hibernate. Pour plus d'informations, consultez les sessions courantes <xref " +"linkend=\"architecture-current-session\" />. En utilisant le contexte de " +"session <literal>\"jta\"</literal> session context, s'il n'y a pas de " +"<literal>Session</literal> associée à la transaction JTA courante, une " +"session sera démarrée et associée à la transaction JTA courante la première " +"fois que vous appelez <literal>sessionFactory.getCurrentSession()</literal>. " +"Les <literal>Session</literal> s obtenues via <literal>getCurrentSession()</" +"literal> dans un contexte <literal>\"jta\"</literal> seront automatiquement " +"flushées avant la validation de la transaction, fermées une fois la " +"transaction complétée, et libèreront les connexions JDBC de manière " +"agressive après chaque statement. Ceci permet aux <literal>Session</literal> " +"s d'être gérées par le cycle de vie de la transaction JTA à laquelle il est " +"associé, ainsi le code de l'utilisateur n'a pas à se préoccupper de ce type " +"de gestion. Votre code peut soit utiliser JTA de manière programmatique via " +"<literal>UserTransaction</literal>, ou (ce qui est recommandé pour la " +"portabilité du code) utiliser l'API <literal>Transaction</literal> pour " +"marquer les limites. Si vous exécutez sous un conteneur EJB, la démarcation " +"déclarative des transactions avec CMT est recommandée. " + +#. Tag: title +#, no-c-format +msgid "JMX deployment" +msgstr "Déploiement JMX" + +#. Tag: para +#, no-c-format +msgid "" +"The line <literal>cfg.buildSessionFactory()</literal> still has to be " +"executed somewhere to get a <literal>SessionFactory</literal> into JNDI. You " +"can do this either in a <literal>static</literal> initializer block, like " +"the one in <literal>HibernateUtil</literal>, or you can deploy Hibernate as " +"a <emphasis>managed service</emphasis>." +msgstr "" +"La ligne <literal>cfg.buildSessionFactory()</literal> doit toujours être " +"exécutée quelque part pour obtenir une <literal>SessionFactory</literal> " +"dans JNDI. Vous pouvez faire cela dans un bloc d'initialisation " +"<literal>static</literal> (comme celui qui se trouve dans la classe " +"<literal>HibernateUtil</literal>) ou vous pouvez déployer Hibernate en temps " +"que <emphasis>service géré</emphasis>. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate is distributed with <literal>org.hibernate.jmx.HibernateService</" +"literal> for deployment on an application server with JMX capabilities, such " +"as JBoss AS. The actual deployment and configuration is vendor-specific. " +"Here is an example <literal>jboss-service.xml</literal> for JBoss 4.0.x:" +msgstr "" +"Hibernate est distribué avec <literal>org.hibernate.jmx.HibernateService</" +"literal> pour le déploiement sur un serveur d'applications avec le support " +"de JMX comme JBoss AS. Le déploiement et la configuration sont spécifiques à " +"chaque vendeur. Voici un fichier <literal>jboss-service.xml</literal> " +"d'exemple pour JBoss 4.0.x :" + +#. Tag: para +#, no-c-format +msgid "" +"This file is deployed in a directory called <literal>META-INF</literal> and " +"packaged in a JAR file with the extension <literal>.sar</literal> (service " +"archive). You also need to package Hibernate, its required third-party " +"libraries, your compiled persistent classes, as well as your mapping files " +"in the same archive. Your enterprise beans (usually session beans) can be " +"kept in their own JAR file, but you can include this EJB JAR file in the " +"main service archive to get a single (hot-)deployable unit. Consult the " +"JBoss AS documentation for more information about JMX service and EJB " +"deployment." +msgstr "" +"Ce fichier est déployé dans un répertoire <literal>META-INF</literal> et est " +"empaqueté dans un fichier JAR avec l'extension <literal>.sar</literal> " +"(service archive). Vous devez également empaqueter Hibernate, les librairies " +"tierces requises, vos classes persistantes compilées et vos fichiers de " +"mappage dans la même archive. Vos beans entreprise (souvent des EJB session) " +"peuvent rester dans leur propre fichier JAR mais vous pouvez inclure ce " +"fichier JAR dans le jar principal du service pour avoir une seule unité " +"déployable à chaud. Vous pouvez consulter la documentation de JBoss AS pour " +"plus d'informations sur les services JMX et le déploiement des EJB. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/events.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/events.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/events.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,566 @@ +# translation of events.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: events\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:34\n" +"PO-Revision-Date: 2009-11-11 09:16+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Interceptors and events" +msgstr "Intercepteurs et événements" + +#. Tag: para +#, no-c-format +msgid "" +"It is useful for the application to react to certain events that occur " +"inside Hibernate. This allows for the implementation of generic " +"functionality and the extension of Hibernate functionality." +msgstr "" +"Il est souvent utile pour l'application de réagir à certains événements qui " +"surviennent dans Hibernate. Cela autorise l'implémentation de certaines " +"fonctionnalités génériques, et l'extension de fonctionnalités d'Hibernate." + +#. Tag: title +#, no-c-format +msgid "Interceptors" +msgstr "Intercepteurs" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>Interceptor</literal> interface provides callbacks from the " +"session to the application, allowing the application to inspect and/or " +"manipulate properties of a persistent object before it is saved, updated, " +"deleted or loaded. One possible use for this is to track auditing " +"information. For example, the following <literal>Interceptor</literal> " +"automatically sets the <literal>createTimestamp</literal> when an " +"<literal>Auditable</literal> is created and updates the " +"<literal>lastUpdateTimestamp</literal> property when an <literal>Auditable</" +"literal> is updated." +msgstr "" +"L'interface <literal>Interceptor</literal> fournit des \"callbacks\" de la " +"session vers l'application permettant à l'application de consulter et/ou de " +"manipuler des propriétés d'un objet persistant avant qu'il soit sauvegardé, " +"mis à jour, supprimé ou chargé. Une utilisation possible de cette " +"fonctionnalité est de tracer l'accès à l'information. Par exemple, " +"l'<literal>Interceptor</literal> suivant positionne " +"<literal>createTimestamp</literal> quand un <literal>Auditable</literal> est " +"créé et met à jour la propriété <literal>lastUpdateTimestamp</literal> quand " +"un <literal>Auditable</literal> est mis à jour. " + +#. Tag: para +#, no-c-format +msgid "" +"You can either implement <literal>Interceptor</literal> directly or extend " +"<literal>EmptyInterceptor</literal>." +msgstr "" +"Vous pouvez soit implémenter <literal>Interceptor</literal> directement ou " +"(mieux) étendre <literal>EmptyInterceptor</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"There are two kinds of inteceptors: <literal>Session</literal>-scoped and " +"<literal>SessionFactory</literal>-scoped." +msgstr "" +"Il y a deux types d'intercepteurs : lié à la <literal>Session</literal> et " +"lié à la <literal>SessionFactory</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>Session</literal>-scoped interceptor is specified when a session " +"is opened using one of the overloaded SessionFactory.openSession() methods " +"accepting an <literal>Interceptor</literal>." +msgstr "" +"Un intercepteur lié à la <literal>Session</literal> est défini lorsqu'une " +"session est ouverte via l'invocation des méthodes surchargées SessionFactory." +"openSession() acceptant un <literal>Interceptor</literal> (comme argument)." + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>SessionFactory</literal>-scoped interceptor is registered with " +"the <literal>Configuration</literal> object prior to building the " +"<literal>SessionFactory</literal>. Unless a session is opened explicitly " +"specifying the interceptor to use, the supplied interceptor will be applied " +"to all sessions opened from that <literal>SessionFactory</literal>. " +"<literal>SessionFactory</literal>-scoped interceptors must be thread safe. " +"Ensure that you do not store session-specific states, since multiple " +"sessions will use this interceptor potentially concurrently." +msgstr "" +"Un intercepteur lié à <literal>SessionFactory</literal> est enregistré avec " +"l'objet <literal>Configuration</literal> avant la construction de la " +"<literal>SessionFactory</literal>. Dans ce cas, les intercepteurs fournis " +"seront appliqués à toutes les sessions ouvertes pour cette " +"<literal>SessionFactory</literal>; ceci est vrai à moins que la session ne " +"soit ouverte en spécifiant l'intercepteur à utiliser. Les intercepteurs liés " +"à la <literal>SessionFactory</literal> doivent être thread safe, en faisant " +"attention à ne pas stocker des états spécifiques de la session puisque " +"plusieurs sessions peuvent utiliser cet intercepteur (potentiellement) de " +"manière concurrente. " + +#. Tag: title +#, no-c-format +msgid "Event system" +msgstr "Système d'événements" + +#. Tag: para +#, no-c-format +msgid "" +"If you have to react to particular events in your persistence layer, you can " +"also use the Hibernate3 <emphasis>event</emphasis> architecture. The event " +"system can be used in addition, or as a replacement, for interceptors." +msgstr "" +"Si vous devez réagir à des événements particuliers dans votre couche de " +"persistance, vous pouvez aussi utiliser l'architecture " +"d'<emphasis>événements</emphasis> de Hibernate3. Le système d'événements " +"peut être utilisé en supplément ou en remplacement des interceptors. " + +#. Tag: para +#, no-c-format +msgid "" +"All the methods of the <literal>Session</literal> interface correlate to an " +"event. You have a <literal>LoadEvent</literal>, a <literal>FlushEvent</" +"literal>, etc. Consult the XML configuration-file DTD or the <literal>org." +"hibernate.event</literal> package for the full list of defined event types. " +"When a request is made of one of these methods, the Hibernate " +"<literal>Session</literal> generates an appropriate event and passes it to " +"the configured event listeners for that type. Out-of-the-box, these " +"listeners implement the same processing in which those methods always " +"resulted. However, you are free to implement a customization of one of the " +"listener interfaces (i.e., the <literal>LoadEvent</literal> is processed by " +"the registered implementation of the <literal>LoadEventListener</literal> " +"interface), in which case their implementation would be responsible for " +"processing any <literal>load()</literal> requests made of the " +"<literal>Session</literal>." +msgstr "" +"Essentiellement toutes les méthodes de l'interface <literal>Session</" +"literal> sont corrélées à un événement. Vous avez un <literal>LoadEvent</" +"literal>, un <literal>FlushEvent</literal>, etc (consultez la DTD du fichier " +"de configuration XML ou le paquetage <literal>org.hibernate.event</literal> " +"pour avoir la liste complète des types d'événement définis). Quand une " +"requête est faite à partir d'une de ces méthodes, la <literal>Session</" +"literal> Hibernate génère un événement approprié et le passe au listener " +"configuré pour ce type. Par défaut, ces listeners implémentent le même " +"traitement dans lequel ces méthodes aboutissent toujours. Cependant, vous " +"êtes libre d'implémenter une version personnalisée d'une de ces interfaces " +"de listener (c'est-à-dire, le <literal>LoadEvent</literal> est traité par " +"l'implémentation de l'interface <literal>LoadEventListener</literal> " +"déclarée), dans quel cas leur implémentation devrait être responsable du " +"traitement des requêtes <literal>load()</literal> faites par la " +"<literal>Session</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The listeners should be considered singletons. This means they are shared " +"between requests, and should not save any state as instance variables." +msgstr "" +"Les listeners devraient effectivement être considérés comme des singletons ; " +"dans le sens où ils sont partagés entre des requêtes, et donc ne devraient " +"pas sauvegarder des états en tant que variables d'instance. " + +#. Tag: para +#, no-c-format +msgid "" +"A custom listener implements the appropriate interface for the event it " +"wants to process and/or extend one of the convenience base classes (or even " +"the default event listeners used by Hibernate out-of-the-box as these are " +"declared non-final for this purpose). Custom listeners can either be " +"registered programmatically through the <literal>Configuration</literal> " +"object, or specified in the Hibernate configuration XML. Declarative " +"configuration through the properties file is not supported. Here is an " +"example of a custom load event listener:" +msgstr "" +"Un listener personnalisé devrait implémenter l'interface appropriée pour " +"l'événement qu'il veut traiter et/ou étendre une des classes de base (ou " +"même l'événement prêt à l'emploi utilisé par Hibernate comme ceux déclarés " +"non-finaux à cette intention). Les listeners personnalisés peuvent être soit " +"inscrits par programmation à travers l'objet <literal>Configuration</" +"literal>, ou spécifiés dans la configuration XML de Hibernate (la " +"configuration déclarative à travers le fichier de propriétés n'est pas " +"supportée). Voici un exemple de listener personnalisé pour l'événement de " +"chargement :" + +#. Tag: para +#, no-c-format +msgid "" +"You also need a configuration entry telling Hibernate to use the listener in " +"addition to the default listener:" +msgstr "" +"Vous avez aussi besoin d'une entrée de configuration indiquant à Hibernate " +"d'utiliser ce listener en plus du listener par défaut :" + +#. Tag: para +#, no-c-format +msgid "Instead, you can register it programmatically:" +msgstr "Vous pouvez aussi l'inscrire par programmation : " + +#. Tag: para +#, no-c-format +msgid "" +"Listeners registered declaratively cannot share instances. If the same class " +"name is used in multiple <literal>&lt;listener/&gt;</literal> elements, each " +"reference will result in a separate instance of that class. If you need to " +"share listener instances between listener types you must use the " +"programmatic registration approach." +msgstr "" +"Les listeners inscrits déclarativement ne peuvent pas partager d'instances. " +"Si le même nom de classe est utilisée dans plusieurs éléments <literal>&lt;" +"listener/&gt;</literal>, chaque référence résultera en une instance " +"distincte de cette classe. Si vous avez besoin de la faculté de partager des " +"instances de listener entre plusieurs types de listener, vous devez utiliser " +"l'approche d'inscription par programmation. " + +#. Tag: para +#, no-c-format +msgid "" +"Why implement an interface and define the specific type during " +"configuration? A listener implementation could implement multiple event " +"listener interfaces. Having the type additionally defined during " +"registration makes it easier to turn custom listeners on or off during " +"configuration." +msgstr "" +"Pourquoi implémenter une interface et définir le type spécifique durant la " +"configuration ? Une implémentation de listener pourrait implémenter " +"plusieurs interfaces de listener d'événements. Par ailleurs, le fait de " +"définir le type durant l'inscription, rend l'activation ou la désactivation " +"plus facile au moment de la configuration. " + +#. Tag: title +#, no-c-format +msgid "Hibernate declarative security" +msgstr "Sécurité déclarative de Hibernate " + +#. Tag: para +#, no-c-format +msgid "" +"Usually, declarative security in Hibernate applications is managed in a " +"session facade layer. Hibernate3 allows certain actions to be permissioned " +"via JACC, and authorized via JAAS. This is an optional functionality that is " +"built on top of the event architecture." +msgstr "" +"Généralement, la sécurité déclarative dans les applications Hibernate est " +"gérée dans la couche de session. Maintenant, Hibernate3 permet à certaines " +"actions d'être approuvées via JACC, et autorisées via JAAS. Cette " +"fonctionnalité optionnelle est construite au dessus de l'architecture " +"d'événements. " + +#. Tag: para +#, no-c-format +msgid "" +"First, you must configure the appropriate event listeners, to enable the use " +"of JAAS authorization." +msgstr "" +"D'abord, vous devez configurer les listeners d'événements appropriés pour " +"permettre l'utilisation d'autorisations JAAS. " + +#. Tag: para +#, no-c-format +msgid "" +"Note that <literal>&lt;listener type=\"...\" class=\"...\"/&gt;</literal> is " +"shorthand for <literal>&lt;event type=\"...\"&gt;&lt;listener class=\"...\"/" +"&gt;&lt;/event&gt;</literal> when there is exactly one listener for a " +"particular event type." +msgstr "" +"Notez que <literal>&lt;listener type=\"...\" class=\"...\"/&gt;</literal> " +"est juste un raccourci pour <literal>&lt;event type=\"...\"&gt;&lt;listener " +"class=\"...\"/&gt;&lt;/event&gt;</literal> quand il y a exactement un " +"listener pour un type d'événement particulier. " + +#. Tag: para +#, no-c-format +msgid "" +"Next, while still in <literal>hibernate.cfg.xml</literal>, bind the " +"permissions to roles:" +msgstr "" +"Ensuite, toujours dans <literal>hibernate.cfg.xml</literal>, liez les " +"permissions aux rôles : " + +#. Tag: para +#, no-c-format +msgid "The role names are the roles understood by your JACC provider." +msgstr "Les noms de rôle sont les rôles compris par votre fournisseur JAAC." + +#~ msgid "" +#~ "<![CDATA[package org.hibernate.test;\n" +#~ "\n" +#~ "import java.io.Serializable;\n" +#~ "import java.util.Date;\n" +#~ "import java.util.Iterator;\n" +#~ "\n" +#~ "import org.hibernate.EmptyInterceptor;\n" +#~ "import org.hibernate.Transaction;\n" +#~ "import org.hibernate.type.Type;\n" +#~ "\n" +#~ "public class AuditInterceptor extends EmptyInterceptor {\n" +#~ "\n" +#~ " private int updates;\n" +#~ " private int creates;\n" +#~ " private int loads;\n" +#~ "\n" +#~ " public void onDelete(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ " // do nothing\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onFlushDirty(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] currentState,\n" +#~ " Object[] previousState,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ "\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " updates++;\n" +#~ " for ( int i=0; i < propertyNames.length; i++ ) {\n" +#~ " if ( \"lastUpdateTimestamp\".equals( propertyNames[i] ) ) " +#~ "{\n" +#~ " currentState[i] = new Date();\n" +#~ " return true;\n" +#~ " }\n" +#~ " }\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onLoad(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " loads++;\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onSave(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ "\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " creates++;\n" +#~ " for ( int i=0; i<propertyNames.length; i++ ) {\n" +#~ " if ( \"createTimestamp\".equals( propertyNames[i] ) ) {\n" +#~ " state[i] = new Date();\n" +#~ " return true;\n" +#~ " }\n" +#~ " }\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public void afterTransactionCompletion(Transaction tx) {\n" +#~ " if ( tx.wasCommitted() ) {\n" +#~ " System.out.println(\"Creations: \" + creates + \", Updates: " +#~ "\" + updates, \"Loads: \" + loads);\n" +#~ " }\n" +#~ " updates=0;\n" +#~ " creates=0;\n" +#~ " loads=0;\n" +#~ " }\n" +#~ "\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[package org.hibernate.test;\n" +#~ "\n" +#~ "import java.io.Serializable;\n" +#~ "import java.util.Date;\n" +#~ "import java.util.Iterator;\n" +#~ "\n" +#~ "import org.hibernate.EmptyInterceptor;\n" +#~ "import org.hibernate.Transaction;\n" +#~ "import org.hibernate.type.Type;\n" +#~ "\n" +#~ "public class AuditInterceptor extends EmptyInterceptor {\n" +#~ "\n" +#~ " private int updates;\n" +#~ " private int creates;\n" +#~ " private int loads;\n" +#~ "\n" +#~ " public void onDelete(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ " // do nothing\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onFlushDirty(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] currentState,\n" +#~ " Object[] previousState,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ "\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " updates++;\n" +#~ " for ( int i=0; i < propertyNames.length; i++ ) {\n" +#~ " if ( \"lastUpdateTimestamp\".equals( propertyNames[i] ) ) " +#~ "{\n" +#~ " currentState[i] = new Date();\n" +#~ " return true;\n" +#~ " }\n" +#~ " }\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onLoad(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " loads++;\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public boolean onSave(Object entity,\n" +#~ " Serializable id,\n" +#~ " Object[] state,\n" +#~ " String[] propertyNames,\n" +#~ " Type[] types) {\n" +#~ "\n" +#~ " if ( entity instanceof Auditable ) {\n" +#~ " creates++;\n" +#~ " for ( int i=0; i<propertyNames.length; i++ ) {\n" +#~ " if ( \"createTimestamp\".equals( propertyNames[i] ) ) {\n" +#~ " state[i] = new Date();\n" +#~ " return true;\n" +#~ " }\n" +#~ " }\n" +#~ " }\n" +#~ " return false;\n" +#~ " }\n" +#~ "\n" +#~ " public void afterTransactionCompletion(Transaction tx) {\n" +#~ " if ( tx.wasCommitted() ) {\n" +#~ " System.out.println(\"Creations: \" + creates + \", Updates: " +#~ "\" + updates, \"Loads: \" + loads);\n" +#~ " }\n" +#~ " updates=0;\n" +#~ " creates=0;\n" +#~ " loads=0;\n" +#~ " }\n" +#~ "\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]>" +#~ msgstr "" +#~ "<![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]>" + +#~ msgid "" +#~ "<![CDATA[new Configuration().setInterceptor( new AuditInterceptor() );]]>" +#~ msgstr "" +#~ "<![CDATA[new Configuration().setInterceptor( new AuditInterceptor() );]]>" + +#~ msgid "" +#~ "<![CDATA[public class MyLoadListener implements LoadEventListener {\n" +#~ " // this is the single method defined by the LoadEventListener " +#~ "interface\n" +#~ " public void onLoad(LoadEvent event, LoadEventListener.LoadType " +#~ "loadType)\n" +#~ " throws HibernateException {\n" +#~ " if ( !MySecurity.isAuthorized( event.getEntityClassName(), event." +#~ "getEntityId() ) ) {\n" +#~ " throw MySecurityException(\"Unauthorized access\");\n" +#~ " }\n" +#~ " }\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[public class MyLoadListener implements LoadEventListener {\n" +#~ " // this is the single method defined by the LoadEventListener " +#~ "interface\n" +#~ " public void onLoad(LoadEvent event, LoadEventListener.LoadType " +#~ "loadType)\n" +#~ " throws HibernateException {\n" +#~ " if ( !MySecurity.isAuthorized( event.getEntityClassName(), event." +#~ "getEntityId() ) ) {\n" +#~ " throw MySecurityException(\"Unauthorized access\");\n" +#~ " }\n" +#~ " }\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[<hibernate-configuration>\n" +#~ " <session-factory>\n" +#~ " ...\n" +#~ " <event type=\"load\">\n" +#~ " <listener class=\"com.eg.MyLoadListener\"/>\n" +#~ " <listener class=\"org.hibernate.event.def." +#~ "DefaultLoadEventListener\"/>\n" +#~ " </event>\n" +#~ " </session-factory>\n" +#~ "</hibernate-configuration>]]>" +#~ msgstr "" +#~ "<![CDATA[<hibernate-configuration>\n" +#~ " <session-factory>\n" +#~ " ...\n" +#~ " <event type=\"load\">\n" +#~ " <listener class=\"com.eg.MyLoadListener\"/>\n" +#~ " <listener class=\"org.hibernate.event.def." +#~ "DefaultLoadEventListener\"/>\n" +#~ " </event>\n" +#~ " </session-factory>\n" +#~ "</hibernate-configuration>]]>" + +#~ msgid "" +#~ "<![CDATA[Configuration cfg = new Configuration();\n" +#~ "LoadEventListener[] stack = { new MyLoadListener(), new " +#~ "DefaultLoadEventListener() };\n" +#~ "cfg.EventListeners().setLoadEventListeners(stack);]]>" +#~ msgstr "" +#~ "<![CDATA[Configuration cfg = new Configuration();\n" +#~ "LoadEventListener[] stack = { new MyLoadListener(), new " +#~ "DefaultLoadEventListener() };\n" +#~ "cfg.EventListeners().setLoadEventListeners(stack);]]>" + +#~ msgid "" +#~ "<![CDATA[<listener type=\"pre-delete\" class=\"org.hibernate.secure." +#~ "JACCPreDeleteEventListener\"/>\n" +#~ "<listener type=\"pre-update\" class=\"org.hibernate.secure." +#~ "JACCPreUpdateEventListener\"/>\n" +#~ "<listener type=\"pre-insert\" class=\"org.hibernate.secure." +#~ "JACCPreInsertEventListener\"/>\n" +#~ "<listener type=\"pre-load\" class=\"org.hibernate.secure." +#~ "JACCPreLoadEventListener\"/>]]>" +#~ msgstr "" +#~ "<![CDATA[<listener type=\"pre-delete\" class=\"org.hibernate.secure." +#~ "JACCPreDeleteEventListener\"/>\n" +#~ "<listener type=\"pre-update\" class=\"org.hibernate.secure." +#~ "JACCPreUpdateEventListener\"/>\n" +#~ "<listener type=\"pre-insert\" class=\"org.hibernate.secure." +#~ "JACCPreInsertEventListener\"/>\n" +#~ "<listener type=\"pre-load\" class=\"org.hibernate.secure." +#~ "JACCPreLoadEventListener\"/>]]>" + +#~ msgid "" +#~ "<![CDATA[<grant role=\"admin\" entity-name=\"User\" actions=\"insert," +#~ "update,read\"/>\n" +#~ "<grant role=\"su\" entity-name=\"User\" actions=\"*\"/>]]>" +#~ msgstr "" +#~ "<![CDATA[<grant role=\"admin\" entity-name=\"User\" actions=\"insert," +#~ "update,read\"/>\n" +#~ "<grant role=\"su\" entity-name=\"User\" actions=\"*\"/>]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_mappings.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_mappings.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_mappings.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1264 @@ +# translation of example_mappings.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: example_mappings\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:35\n" +"PO-Revision-Date: 2009-11-11 09:19+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Example: Various Mappings" +msgstr "Exemple : quelques mappages" + +#. Tag: para +#, no-c-format +msgid "This chapters explores some more complex association mappings." +msgstr "Ce chapitre montre quelques mappages plus complexes. " + +#. Tag: title +#, no-c-format +msgid "Employer/Employee" +msgstr "Employeur/Employé (Employer/Employee)" + +#. Tag: para +#, no-c-format +msgid "" +"The following model of the relationship between <literal>Employer</literal> " +"and <literal>Employee</literal> uses an entity class (<literal>Employment</" +"literal>) to represent the association. You can do this when there might be " +"more than one period of employment for the same two parties. Components are " +"used to model monetary values and employee names." +msgstr "" +"Le modèle suivant de relation entre <literal>Employer</literal> et " +"<literal>Employee</literal> utilise une vraie classe entité " +"(<literal>Employment</literal>) pour représenter l'association. La raison " +"étant qu'il peut y avoir plus d'une période d'emploi pour les deux mêmes " +"parties. Des composants sont utilisés pour modéliser les valeurs monétaires " +"et les noms des employés. " + +#. Tag: para +#, no-c-format +msgid "Here is a possible mapping document:" +msgstr "Voici un document de mappage possible : " + +#. Tag: para +#, no-c-format +msgid "Here is the table schema generated by <literal>SchemaExport</literal>." +msgstr "" +"Et voici le schéma des tables générées par <literal>SchemaExport</literal>. " + +#. Tag: title +#, no-c-format +msgid "Author/Work" +msgstr "Auteur/Travail " + +#. Tag: para +#, no-c-format +msgid "" +"Consider the following model of the relationships between <literal>Work</" +"literal>, <literal>Author</literal> and <literal>Person</literal>. In the " +"example, the relationship between <literal>Work</literal> and " +"<literal>Author</literal> is represented as a many-to-many association and " +"the relationship between <literal>Author</literal> and <literal>Person</" +"literal> is represented as one-to-one association. Another possibility would " +"be to have <literal>Author</literal> extend <literal>Person</literal>." +msgstr "" +"Examinons le modèle suivant de la relation entre <literal>Work</literal>, " +"<literal>Author</literal> et <literal>Person</literal>. Nous représentons la " +"relation entre <literal>Work</literal> et <literal>Author</literal> comme " +"une association plusieurs-à-plusieurs. Nous avons choisi de représenter la " +"relation entre <literal>Author</literal> et <literal>Person</literal> comme " +"une association un-à-un. Une autre possibilité aurait été que " +"<literal>Author</literal> étende <literal>Person</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The following mapping document correctly represents these relationships:" +msgstr "Le mappage suivant représente exactement ces relations :" + +#. Tag: para +#, no-c-format +msgid "" +"There are four tables in this mapping: <literal>works</literal>, " +"<literal>authors</literal> and <literal>persons</literal> hold work, author " +"and person data respectively. <literal>author_work</literal> is an " +"association table linking authors to works. Here is the table schema, as " +"generated by <literal>SchemaExport</literal>:" +msgstr "" +"Il y a quatre tables dans ce mappage. <literal>works</literal>, " +"<literal>authors</literal> et <literal>persons</literal> qui contiennent " +"respectivement les données de work, author et person. <literal>author_work</" +"literal> est une table d'association qui lie authors à works. Voici le " +"schéma de tables, généré par <literal>SchemaExport</literal> :" + +#. Tag: title +#, no-c-format +msgid "Customer/Order/Product" +msgstr "Client/Commande/Produit " + +#. Tag: para +#, no-c-format +msgid "" +"In this section we consider a model of the relationships between " +"<literal>Customer</literal>, <literal>Order</literal>, <literal>Line Item</" +"literal> and <literal>Product</literal>. There is a one-to-many association " +"between <literal>Customer</literal> and <literal>Order</literal>, but how " +"can you represent <literal>Order</literal> / <literal>LineItem</literal> / " +"<literal>Product</literal>? In the example, <literal>LineItem</literal> is " +"mapped as an association class representing the many-to-many association " +"between <literal>Order</literal> and <literal>Product</literal>. In " +"Hibernate this is called a composite element." +msgstr "" +"Imaginons maintenant le modèle de relations entre <literal>Customer</" +"literal>, <literal>Order</literal>, <literal>LineItem</literal> et " +"<literal>Product</literal>. Il y a une association un-à-plusieurs entre " +"<literal>Customer</literal> et <literal>Order</literal>, mais comment devons " +"nous représenter <literal>Order</literal> / <literal>LineItem</literal> / " +"<literal>Product</literal> ? J'ai choisi de mapper <literal>LineItem</" +"literal> comme une classe d'association représentant l'association plusieurs-" +"à-plusieurs entre <literal>Order</literal> et <literal>Product</literal>. " +"Dans Hibernate, on appelle cela un élément composite. " + +#. Tag: para +#, no-c-format +msgid "The mapping document will look like this:" +msgstr "Le document de mappage : " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>customers</literal>, <literal>orders</literal>, " +"<literal>line_items</literal> and <literal>products</literal> hold customer, " +"order, order line item and product data respectively. <literal>line_items</" +"literal> also acts as an association table linking orders with products." +msgstr "" +"<literal>customers</literal>, <literal>orders</literal>, " +"<literal>line_items</literal> et <literal>products</literal> contiennent les " +"données de customer, order, order line item et product. <literal>line_items</" +"literal> est aussi la table d'association liant orders à products. " + +#. Tag: title +#, no-c-format +msgid "Miscellaneous example mappings" +msgstr "Divers exemples de mappages" + +#. Tag: para +#, no-c-format +msgid "" +"These examples are available from the Hibernate test suite. You will find " +"many other useful example mappings there by searching in the <literal>test</" +"literal> folder of the Hibernate distribution." +msgstr "" +"Ces exemples sont tous pris de la suite de tests de Hibernate. Vous en " +"trouverez beaucoup d'autres. Regardez dans le dossier <literal>test</" +"literal> de la distribution Hibernate. " + +#. Tag: title +#, no-c-format +msgid "\"Typed\" one-to-one association" +msgstr "\"Typed\" association un-à-un" + +#. Tag: title +#, no-c-format +msgid "Composite key example" +msgstr "Exemple de clef composée" + +#. Tag: title +#, no-c-format +msgid "Many-to-many with shared composite key attribute" +msgstr "Plusieurs-à-plusieurs avec un attribut de clef composée partagée" + +#. Tag: title +#, no-c-format +msgid "Content based discrimination" +msgstr "Contenu basé sur une discrimination" + +#. Tag: title +#, no-c-format +msgid "Associations on alternate keys" +msgstr "Associations sur des clés alternées" + +#~ msgid "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ " \n" +#~ " <class name=\"Employer\" table=\"employers\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employer_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Employment\" table=\"employment_periods\">\n" +#~ "\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employment_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"startDate\" column=\"start_date\"/>\n" +#~ " <property name=\"endDate\" column=\"end_date\"/>\n" +#~ "\n" +#~ " <component name=\"hourlyRate\" class=\"MonetaryAmount\">\n" +#~ " <property name=\"amount\">\n" +#~ " <column name=\"hourly_rate\" sql-type=\"NUMERIC(12, 2)\"/" +#~ ">\n" +#~ " </property>\n" +#~ " <property name=\"currency\" length=\"12\"/>\n" +#~ " </component>\n" +#~ "\n" +#~ " <many-to-one name=\"employer\" column=\"employer_id\" not-null=" +#~ "\"true\"/>\n" +#~ " <many-to-one name=\"employee\" column=\"employee_id\" not-null=" +#~ "\"true\"/>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Employee\" table=\"employees\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employee_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"taxfileNumber\"/>\n" +#~ " <component name=\"name\" class=\"Name\">\n" +#~ " <property name=\"firstName\"/>\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"lastName\"/>\n" +#~ " </component>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" +#~ msgstr "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ " \n" +#~ " <class name=\"Employer\" table=\"employers\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employer_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Employment\" table=\"employment_periods\">\n" +#~ "\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employment_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"startDate\" column=\"start_date\"/>\n" +#~ " <property name=\"endDate\" column=\"end_date\"/>\n" +#~ "\n" +#~ " <component name=\"hourlyRate\" class=\"MonetaryAmount\">\n" +#~ " <property name=\"amount\">\n" +#~ " <column name=\"hourly_rate\" sql-type=\"NUMERIC(12, 2)\"/" +#~ ">\n" +#~ " </property>\n" +#~ " <property name=\"currency\" length=\"12\"/>\n" +#~ " </component>\n" +#~ "\n" +#~ " <many-to-one name=\"employer\" column=\"employer_id\" not-null=" +#~ "\"true\"/>\n" +#~ " <many-to-one name=\"employee\" column=\"employee_id\" not-null=" +#~ "\"true\"/>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Employee\" table=\"employees\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"sequence\">\n" +#~ " <param name=\"sequence\">employee_id_seq</param>\n" +#~ " </generator>\n" +#~ " </id>\n" +#~ " <property name=\"taxfileNumber\"/>\n" +#~ " <component name=\"name\" class=\"Name\">\n" +#~ " <property name=\"firstName\"/>\n" +#~ " <property name=\"initial\"/>\n" +#~ " <property name=\"lastName\"/>\n" +#~ " </component>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" + +#~ msgid "" +#~ "<![CDATA[create table employers (\n" +#~ " id BIGINT not null, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table employment_periods (\n" +#~ " id BIGINT not null,\n" +#~ " hourly_rate NUMERIC(12, 2),\n" +#~ " currency VARCHAR(12), \n" +#~ " employee_id BIGINT not null, \n" +#~ " employer_id BIGINT not null, \n" +#~ " end_date TIMESTAMP, \n" +#~ " start_date TIMESTAMP, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table employees (\n" +#~ " id BIGINT not null, \n" +#~ " firstName VARCHAR(255), \n" +#~ " initial CHAR(1), \n" +#~ " lastName VARCHAR(255), \n" +#~ " taxfileNumber VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table employment_periods \n" +#~ " add constraint employment_periodsFK0 foreign key (employer_id) " +#~ "references employers\n" +#~ "alter table employment_periods \n" +#~ " add constraint employment_periodsFK1 foreign key (employee_id) " +#~ "references employees\n" +#~ "create sequence employee_id_seq\n" +#~ "create sequence employment_id_seq\n" +#~ "create sequence employer_id_seq]]>" +#~ msgstr "" +#~ "<![CDATA[create table employers (\n" +#~ " id BIGINT not null, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table employment_periods (\n" +#~ " id BIGINT not null,\n" +#~ " hourly_rate NUMERIC(12, 2),\n" +#~ " currency VARCHAR(12), \n" +#~ " employee_id BIGINT not null, \n" +#~ " employer_id BIGINT not null, \n" +#~ " end_date TIMESTAMP, \n" +#~ " start_date TIMESTAMP, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table employees (\n" +#~ " id BIGINT not null, \n" +#~ " firstName VARCHAR(255), \n" +#~ " initial CHAR(1), \n" +#~ " lastName VARCHAR(255), \n" +#~ " taxfileNumber VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table employment_periods \n" +#~ " add constraint employment_periodsFK0 foreign key (employer_id) " +#~ "references employers\n" +#~ "alter table employment_periods \n" +#~ " add constraint employment_periodsFK1 foreign key (employee_id) " +#~ "references employees\n" +#~ "create sequence employee_id_seq\n" +#~ "create sequence employment_id_seq\n" +#~ "create sequence employer_id_seq]]>" + +#~ msgid "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ "\n" +#~ " <class name=\"Work\" table=\"works\" discriminator-value=\"W\">\n" +#~ "\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <discriminator column=\"type\" type=\"character\"/>\n" +#~ "\n" +#~ " <property name=\"title\"/>\n" +#~ " <set name=\"authors\" table=\"author_work\">\n" +#~ " <key column name=\"work_id\"/>\n" +#~ " <many-to-many class=\"Author\" column name=\"author_id\"/>\n" +#~ " </set>\n" +#~ "\n" +#~ " <subclass name=\"Book\" discriminator-value=\"B\">\n" +#~ " <property name=\"text\"/>\n" +#~ " </subclass>\n" +#~ "\n" +#~ " <subclass name=\"Song\" discriminator-value=\"S\">\n" +#~ " <property name=\"tempo\"/>\n" +#~ " <property name=\"genre\"/>\n" +#~ " </subclass>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Author\" table=\"authors\">\n" +#~ "\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <!-- The Author must have the same identifier as the Person --" +#~ ">\n" +#~ " <generator class=\"assigned\"/> \n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"alias\"/>\n" +#~ " <one-to-one name=\"person\" constrained=\"true\"/>\n" +#~ "\n" +#~ " <set name=\"works\" table=\"author_work\" inverse=\"true\">\n" +#~ " <key column=\"author_id\"/>\n" +#~ " <many-to-many class=\"Work\" column=\"work_id\"/>\n" +#~ " </set>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Person\" table=\"persons\">\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" +#~ msgstr "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ "\n" +#~ " <class name=\"Work\" table=\"works\" discriminator-value=\"W\">\n" +#~ "\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <discriminator column=\"type\" type=\"character\"/>\n" +#~ "\n" +#~ " <property name=\"title\"/>\n" +#~ " <set name=\"authors\" table=\"author_work\">\n" +#~ " <key column name=\"work_id\"/>\n" +#~ " <many-to-many class=\"Author\" column name=\"author_id\"/>\n" +#~ " </set>\n" +#~ "\n" +#~ " <subclass name=\"Book\" discriminator-value=\"B\">\n" +#~ " <property name=\"text\"/>\n" +#~ " </subclass>\n" +#~ "\n" +#~ " <subclass name=\"Song\" discriminator-value=\"S\">\n" +#~ " <property name=\"tempo\"/>\n" +#~ " <property name=\"genre\"/>\n" +#~ " </subclass>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Author\" table=\"authors\">\n" +#~ "\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <!-- The Author must have the same identifier as the Person --" +#~ ">\n" +#~ " <generator class=\"assigned\"/> \n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"alias\"/>\n" +#~ " <one-to-one name=\"person\" constrained=\"true\"/>\n" +#~ "\n" +#~ " <set name=\"works\" table=\"author_work\" inverse=\"true\">\n" +#~ " <key column=\"author_id\"/>\n" +#~ " <many-to-many class=\"Work\" column=\"work_id\"/>\n" +#~ " </set>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Person\" table=\"persons\">\n" +#~ " <id name=\"id\" column=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" + +#~ msgid "" +#~ "<![CDATA[create table works (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " tempo FLOAT, \n" +#~ " genre VARCHAR(255), \n" +#~ " text INTEGER, \n" +#~ " title VARCHAR(255), \n" +#~ " type CHAR(1) not null, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table author_work (\n" +#~ " author_id BIGINT not null, \n" +#~ " work_id BIGINT not null, \n" +#~ " primary key (work_id, author_id)\n" +#~ ")\n" +#~ "\n" +#~ "create table authors (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " alias VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table persons (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table authors \n" +#~ " add constraint authorsFK0 foreign key (id) references persons\n" +#~ "alter table author_work \n" +#~ " add constraint author_workFK0 foreign key (author_id) references " +#~ "authors\n" +#~ "alter table author_work\n" +#~ " add constraint author_workFK1 foreign key (work_id) references works]]" +#~ ">" +#~ msgstr "" +#~ "<![CDATA[create table works (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " tempo FLOAT, \n" +#~ " genre VARCHAR(255), \n" +#~ " text INTEGER, \n" +#~ " title VARCHAR(255), \n" +#~ " type CHAR(1) not null, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table author_work (\n" +#~ " author_id BIGINT not null, \n" +#~ " work_id BIGINT not null, \n" +#~ " primary key (work_id, author_id)\n" +#~ ")\n" +#~ "\n" +#~ "create table authors (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " alias VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table persons (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table authors \n" +#~ " add constraint authorsFK0 foreign key (id) references persons\n" +#~ "alter table author_work \n" +#~ " add constraint author_workFK0 foreign key (author_id) references " +#~ "authors\n" +#~ "alter table author_work\n" +#~ " add constraint author_workFK1 foreign key (work_id) references works]]" +#~ ">" + +#~ msgid "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ "\n" +#~ " <class name=\"Customer\" table=\"customers\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " <set name=\"orders\" inverse=\"true\">\n" +#~ " <key column=\"customer_id\"/>\n" +#~ " <one-to-many class=\"Order\"/>\n" +#~ " </set>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Order\" table=\"orders\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"date\"/>\n" +#~ " <many-to-one name=\"customer\" column=\"customer_id\"/>\n" +#~ " <list name=\"lineItems\" table=\"line_items\">\n" +#~ " <key column=\"order_id\"/>\n" +#~ " <list-index column=\"line_number\"/>\n" +#~ " <composite-element class=\"LineItem\">\n" +#~ " <property name=\"quantity\"/>\n" +#~ " <many-to-one name=\"product\" column=\"product_id\"/>\n" +#~ " </composite-element>\n" +#~ " </list>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Product\" table=\"products\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"serialNumber\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" +#~ msgstr "" +#~ "<![CDATA[<hibernate-mapping>\n" +#~ "\n" +#~ " <class name=\"Customer\" table=\"customers\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"name\"/>\n" +#~ " <set name=\"orders\" inverse=\"true\">\n" +#~ " <key column=\"customer_id\"/>\n" +#~ " <one-to-many class=\"Order\"/>\n" +#~ " </set>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Order\" table=\"orders\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"date\"/>\n" +#~ " <many-to-one name=\"customer\" column=\"customer_id\"/>\n" +#~ " <list name=\"lineItems\" table=\"line_items\">\n" +#~ " <key column=\"order_id\"/>\n" +#~ " <list-index column=\"line_number\"/>\n" +#~ " <composite-element class=\"LineItem\">\n" +#~ " <property name=\"quantity\"/>\n" +#~ " <many-to-one name=\"product\" column=\"product_id\"/>\n" +#~ " </composite-element>\n" +#~ " </list>\n" +#~ " </class>\n" +#~ "\n" +#~ " <class name=\"Product\" table=\"products\">\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " <property name=\"serialNumber\"/>\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" + +#~ msgid "" +#~ "<![CDATA[create table customers (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table orders (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " customer_id BIGINT, \n" +#~ " date TIMESTAMP, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table line_items (\n" +#~ " line_number INTEGER not null, \n" +#~ " order_id BIGINT not null, \n" +#~ " product_id BIGINT, \n" +#~ " quantity INTEGER, \n" +#~ " primary key (order_id, line_number)\n" +#~ ")\n" +#~ "\n" +#~ "create table products (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " serialNumber VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table orders \n" +#~ " add constraint ordersFK0 foreign key (customer_id) references " +#~ "customers\n" +#~ "alter table line_items\n" +#~ " add constraint line_itemsFK0 foreign key (product_id) references " +#~ "products\n" +#~ "alter table line_items\n" +#~ " add constraint line_itemsFK1 foreign key (order_id) references " +#~ "orders]]>" +#~ msgstr "" +#~ "<![CDATA[create table customers (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " name VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table orders (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " customer_id BIGINT, \n" +#~ " date TIMESTAMP, \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "create table line_items (\n" +#~ " line_number INTEGER not null, \n" +#~ " order_id BIGINT not null, \n" +#~ " product_id BIGINT, \n" +#~ " quantity INTEGER, \n" +#~ " primary key (order_id, line_number)\n" +#~ ")\n" +#~ "\n" +#~ "create table products (\n" +#~ " id BIGINT not null generated by default as identity, \n" +#~ " serialNumber VARCHAR(255), \n" +#~ " primary key (id)\n" +#~ ")\n" +#~ "\n" +#~ "alter table orders \n" +#~ " add constraint ordersFK0 foreign key (customer_id) references " +#~ "customers\n" +#~ "alter table line_items\n" +#~ " add constraint line_itemsFK0 foreign key (product_id) references " +#~ "products\n" +#~ "alter table line_items\n" +#~ " add constraint line_itemsFK1 foreign key (order_id) references " +#~ "orders]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"name\"/>\n" +#~ " <one-to-one name=\"address\" \n" +#~ " cascade=\"all\">\n" +#~ " <formula>name</formula>\n" +#~ " <formula>'HOME'</formula>\n" +#~ " </one-to-one>\n" +#~ " <one-to-one name=\"mailingAddress\" \n" +#~ " cascade=\"all\">\n" +#~ " <formula>name</formula>\n" +#~ " <formula>'MAILING'</formula>\n" +#~ " </one-to-one>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\" batch-size=\"2\" \n" +#~ " check=\"addressType in ('MAILING', 'HOME', 'BUSINESS')\">\n" +#~ " <composite-id>\n" +#~ " <key-many-to-one name=\"person\" \n" +#~ " column=\"personName\"/>\n" +#~ " <key-property name=\"type\" \n" +#~ " column=\"addressType\"/>\n" +#~ " </composite-id>\n" +#~ " <property name=\"street\" type=\"text\"/>\n" +#~ " <property name=\"state\"/>\n" +#~ " <property name=\"zip\"/>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " <id name=\"name\"/>\n" +#~ " <one-to-one name=\"address\" \n" +#~ " cascade=\"all\">\n" +#~ " <formula>name</formula>\n" +#~ " <formula>'HOME'</formula>\n" +#~ " </one-to-one>\n" +#~ " <one-to-one name=\"mailingAddress\" \n" +#~ " cascade=\"all\">\n" +#~ " <formula>name</formula>\n" +#~ " <formula>'MAILING'</formula>\n" +#~ " </one-to-one>\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\" batch-size=\"2\" \n" +#~ " check=\"addressType in ('MAILING', 'HOME', 'BUSINESS')\">\n" +#~ " <composite-id>\n" +#~ " <key-many-to-one name=\"person\" \n" +#~ " column=\"personName\"/>\n" +#~ " <key-property name=\"type\" \n" +#~ " column=\"addressType\"/>\n" +#~ " </composite-id>\n" +#~ " <property name=\"street\" type=\"text\"/>\n" +#~ " <property name=\"state\"/>\n" +#~ " <property name=\"zip\"/>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Customer\">\n" +#~ "\n" +#~ " <id name=\"customerId\"\n" +#~ " length=\"10\">\n" +#~ " <generator class=\"assigned\"/>\n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"name\" not-null=\"true\" length=\"100\"/>\n" +#~ " <property name=\"address\" not-null=\"true\" length=\"200\"/>\n" +#~ "\n" +#~ " <list name=\"orders\"\n" +#~ " inverse=\"true\"\n" +#~ " cascade=\"save-update\">\n" +#~ " <key column=\"customerId\"/>\n" +#~ " <index column=\"orderNumber\"/>\n" +#~ " <one-to-many class=\"Order\"/>\n" +#~ " </list>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Order\" table=\"CustomerOrder\" lazy=\"true\">\n" +#~ " <synchronize table=\"LineItem\"/>\n" +#~ " <synchronize table=\"Product\"/>\n" +#~ " \n" +#~ " <composite-id name=\"id\" \n" +#~ " class=\"Order$Id\">\n" +#~ " <key-property name=\"customerId\" length=\"10\"/>\n" +#~ " <key-property name=\"orderNumber\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"orderDate\" \n" +#~ " type=\"calendar_date\"\n" +#~ " not-null=\"true\"/>\n" +#~ " \n" +#~ " <property name=\"total\">\n" +#~ " <formula>\n" +#~ " ( select sum(li.quantity*p.price) \n" +#~ " from LineItem li, Product p \n" +#~ " where li.productId = p.productId \n" +#~ " and li.customerId = customerId \n" +#~ " and li.orderNumber = orderNumber )\n" +#~ " </formula>\n" +#~ " </property>\n" +#~ " \n" +#~ " <many-to-one name=\"customer\"\n" +#~ " column=\"customerId\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\"/>\n" +#~ " \n" +#~ " <bag name=\"lineItems\"\n" +#~ " fetch=\"join\" \n" +#~ " inverse=\"true\"\n" +#~ " cascade=\"save-update\">\n" +#~ " <key>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " <column name=\"orderNumber\"/>\n" +#~ " </key>\n" +#~ " <one-to-many class=\"LineItem\"/>\n" +#~ " </bag>\n" +#~ " \n" +#~ "</class>\n" +#~ " \n" +#~ "<class name=\"LineItem\">\n" +#~ " \n" +#~ " <composite-id name=\"id\" \n" +#~ " class=\"LineItem$Id\">\n" +#~ " <key-property name=\"customerId\" length=\"10\"/>\n" +#~ " <key-property name=\"orderNumber\"/>\n" +#~ " <key-property name=\"productId\" length=\"10\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"quantity\"/>\n" +#~ " \n" +#~ " <many-to-one name=\"order\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\">\n" +#~ " <column name=\"customerId\"/>\n" +#~ " <column name=\"orderNumber\"/>\n" +#~ " </many-to-one>\n" +#~ " \n" +#~ " <many-to-one name=\"product\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\"\n" +#~ " column=\"productId\"/>\n" +#~ " \n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Product\">\n" +#~ " <synchronize table=\"LineItem\"/>\n" +#~ "\n" +#~ " <id name=\"productId\"\n" +#~ " length=\"10\">\n" +#~ " <generator class=\"assigned\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <property name=\"description\" \n" +#~ " not-null=\"true\" \n" +#~ " length=\"200\"/>\n" +#~ " <property name=\"price\" length=\"3\"/>\n" +#~ " <property name=\"numberAvailable\"/>\n" +#~ " \n" +#~ " <property name=\"numberOrdered\">\n" +#~ " <formula>\n" +#~ " ( select sum(li.quantity) \n" +#~ " from LineItem li \n" +#~ " where li.productId = productId )\n" +#~ " </formula>\n" +#~ " </property>\n" +#~ " \n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Customer\">\n" +#~ "\n" +#~ " <id name=\"customerId\"\n" +#~ " length=\"10\">\n" +#~ " <generator class=\"assigned\"/>\n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"name\" not-null=\"true\" length=\"100\"/>\n" +#~ " <property name=\"address\" not-null=\"true\" length=\"200\"/>\n" +#~ "\n" +#~ " <list name=\"orders\"\n" +#~ " inverse=\"true\"\n" +#~ " cascade=\"save-update\">\n" +#~ " <key column=\"customerId\"/>\n" +#~ " <index column=\"orderNumber\"/>\n" +#~ " <one-to-many class=\"Order\"/>\n" +#~ " </list>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Order\" table=\"CustomerOrder\" lazy=\"true\">\n" +#~ " <synchronize table=\"LineItem\"/>\n" +#~ " <synchronize table=\"Product\"/>\n" +#~ " \n" +#~ " <composite-id name=\"id\" \n" +#~ " class=\"Order$Id\">\n" +#~ " <key-property name=\"customerId\" length=\"10\"/>\n" +#~ " <key-property name=\"orderNumber\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"orderDate\" \n" +#~ " type=\"calendar_date\"\n" +#~ " not-null=\"true\"/>\n" +#~ " \n" +#~ " <property name=\"total\">\n" +#~ " <formula>\n" +#~ " ( select sum(li.quantity*p.price) \n" +#~ " from LineItem li, Product p \n" +#~ " where li.productId = p.productId \n" +#~ " and li.customerId = customerId \n" +#~ " and li.orderNumber = orderNumber )\n" +#~ " </formula>\n" +#~ " </property>\n" +#~ " \n" +#~ " <many-to-one name=\"customer\"\n" +#~ " column=\"customerId\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\"/>\n" +#~ " \n" +#~ " <bag name=\"lineItems\"\n" +#~ " fetch=\"join\" \n" +#~ " inverse=\"true\"\n" +#~ " cascade=\"save-update\">\n" +#~ " <key>\n" +#~ " <column name=\"customerId\"/>\n" +#~ " <column name=\"orderNumber\"/>\n" +#~ " </key>\n" +#~ " <one-to-many class=\"LineItem\"/>\n" +#~ " </bag>\n" +#~ " \n" +#~ "</class>\n" +#~ " \n" +#~ "<class name=\"LineItem\">\n" +#~ " \n" +#~ " <composite-id name=\"id\" \n" +#~ " class=\"LineItem$Id\">\n" +#~ " <key-property name=\"customerId\" length=\"10\"/>\n" +#~ " <key-property name=\"orderNumber\"/>\n" +#~ " <key-property name=\"productId\" length=\"10\"/>\n" +#~ " </composite-id>\n" +#~ " \n" +#~ " <property name=\"quantity\"/>\n" +#~ " \n" +#~ " <many-to-one name=\"order\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\">\n" +#~ " <column name=\"customerId\"/>\n" +#~ " <column name=\"orderNumber\"/>\n" +#~ " </many-to-one>\n" +#~ " \n" +#~ " <many-to-one name=\"product\"\n" +#~ " insert=\"false\"\n" +#~ " update=\"false\" \n" +#~ " not-null=\"true\"\n" +#~ " column=\"productId\"/>\n" +#~ " \n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Product\">\n" +#~ " <synchronize table=\"LineItem\"/>\n" +#~ "\n" +#~ " <id name=\"productId\"\n" +#~ " length=\"10\">\n" +#~ " <generator class=\"assigned\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <property name=\"description\" \n" +#~ " not-null=\"true\" \n" +#~ " length=\"200\"/>\n" +#~ " <property name=\"price\" length=\"3\"/>\n" +#~ " <property name=\"numberAvailable\"/>\n" +#~ " \n" +#~ " <property name=\"numberOrdered\">\n" +#~ " <formula>\n" +#~ " ( select sum(li.quantity) \n" +#~ " from LineItem li \n" +#~ " where li.productId = productId )\n" +#~ " </formula>\n" +#~ " </property>\n" +#~ " \n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"User\" table=\"`User`\">\n" +#~ " <composite-id>\n" +#~ " <key-property name=\"name\"/>\n" +#~ " <key-property name=\"org\"/>\n" +#~ " </composite-id>\n" +#~ " <set name=\"groups\" table=\"UserGroup\">\n" +#~ " <key>\n" +#~ " <column name=\"userName\"/>\n" +#~ " <column name=\"org\"/>\n" +#~ " </key>\n" +#~ " <many-to-many class=\"Group\">\n" +#~ " <column name=\"groupName\"/>\n" +#~ " <formula>org</formula>\n" +#~ " </many-to-many>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ " \n" +#~ "<class name=\"Group\" table=\"`Group`\">\n" +#~ " <composite-id>\n" +#~ " <key-property name=\"name\"/>\n" +#~ " <key-property name=\"org\"/>\n" +#~ " </composite-id>\n" +#~ " <property name=\"description\"/>\n" +#~ " <set name=\"users\" table=\"UserGroup\" inverse=\"true\">\n" +#~ " <key>\n" +#~ " <column name=\"groupName\"/>\n" +#~ " <column name=\"org\"/>\n" +#~ " </key>\n" +#~ " <many-to-many class=\"User\">\n" +#~ " <column name=\"userName\"/>\n" +#~ " <formula>org</formula>\n" +#~ " </many-to-many>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"User\" table=\"`User`\">\n" +#~ " <composite-id>\n" +#~ " <key-property name=\"name\"/>\n" +#~ " <key-property name=\"org\"/>\n" +#~ " </composite-id>\n" +#~ " <set name=\"groups\" table=\"UserGroup\">\n" +#~ " <key>\n" +#~ " <column name=\"userName\"/>\n" +#~ " <column name=\"org\"/>\n" +#~ " </key>\n" +#~ " <many-to-many class=\"Group\">\n" +#~ " <column name=\"groupName\"/>\n" +#~ " <formula>org</formula>\n" +#~ " </many-to-many>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ " \n" +#~ "<class name=\"Group\" table=\"`Group`\">\n" +#~ " <composite-id>\n" +#~ " <key-property name=\"name\"/>\n" +#~ " <key-property name=\"org\"/>\n" +#~ " </composite-id>\n" +#~ " <property name=\"description\"/>\n" +#~ " <set name=\"users\" table=\"UserGroup\" inverse=\"true\">\n" +#~ " <key>\n" +#~ " <column name=\"groupName\"/>\n" +#~ " <column name=\"org\"/>\n" +#~ " </key>\n" +#~ " <many-to-many class=\"User\">\n" +#~ " <column name=\"userName\"/>\n" +#~ " <formula>org</formula>\n" +#~ " </many-to-many>\n" +#~ " </set>\n" +#~ "</class>\n" +#~ "]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\"\n" +#~ " discriminator-value=\"P\">\n" +#~ " \n" +#~ " <id name=\"id\" \n" +#~ " column=\"person_id\" \n" +#~ " unsaved-value=\"0\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " \n" +#~ " <discriminator \n" +#~ " type=\"character\">\n" +#~ " <formula>\n" +#~ " case \n" +#~ " when title is not null then 'E' \n" +#~ " when salesperson is not null then 'C' \n" +#~ " else 'P' \n" +#~ " end\n" +#~ " </formula>\n" +#~ " </discriminator>\n" +#~ "\n" +#~ " <property name=\"name\" \n" +#~ " not-null=\"true\"\n" +#~ " length=\"80\"/>\n" +#~ " \n" +#~ " <property name=\"sex\" \n" +#~ " not-null=\"true\"\n" +#~ " update=\"false\"/>\n" +#~ " \n" +#~ " <component name=\"address\">\n" +#~ " <property name=\"address\"/>\n" +#~ " <property name=\"zip\"/>\n" +#~ " <property name=\"country\"/>\n" +#~ " </component>\n" +#~ " \n" +#~ " <subclass name=\"Employee\" \n" +#~ " discriminator-value=\"E\">\n" +#~ " <property name=\"title\"\n" +#~ " length=\"20\"/>\n" +#~ " <property name=\"salary\"/>\n" +#~ " <many-to-one name=\"manager\"/>\n" +#~ " </subclass>\n" +#~ " \n" +#~ " <subclass name=\"Customer\" \n" +#~ " discriminator-value=\"C\">\n" +#~ " <property name=\"comments\"/>\n" +#~ " <many-to-one name=\"salesperson\"/>\n" +#~ " </subclass>\n" +#~ " \n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\"\n" +#~ " discriminator-value=\"P\">\n" +#~ " \n" +#~ " <id name=\"id\" \n" +#~ " column=\"person_id\" \n" +#~ " unsaved-value=\"0\">\n" +#~ " <generator class=\"native\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " \n" +#~ " <discriminator \n" +#~ " type=\"character\">\n" +#~ " <formula>\n" +#~ " case \n" +#~ " when title is not null then 'E' \n" +#~ " when salesperson is not null then 'C' \n" +#~ " else 'P' \n" +#~ " end\n" +#~ " </formula>\n" +#~ " </discriminator>\n" +#~ "\n" +#~ " <property name=\"name\" \n" +#~ " not-null=\"true\"\n" +#~ " length=\"80\"/>\n" +#~ " \n" +#~ " <property name=\"sex\" \n" +#~ " not-null=\"true\"\n" +#~ " update=\"false\"/>\n" +#~ " \n" +#~ " <component name=\"address\">\n" +#~ " <property name=\"address\"/>\n" +#~ " <property name=\"zip\"/>\n" +#~ " <property name=\"country\"/>\n" +#~ " </component>\n" +#~ " \n" +#~ " <subclass name=\"Employee\" \n" +#~ " discriminator-value=\"E\">\n" +#~ " <property name=\"title\"\n" +#~ " length=\"20\"/>\n" +#~ " <property name=\"salary\"/>\n" +#~ " <many-to-one name=\"manager\"/>\n" +#~ " </subclass>\n" +#~ " \n" +#~ " <subclass name=\"Customer\" \n" +#~ " discriminator-value=\"C\">\n" +#~ " <property name=\"comments\"/>\n" +#~ " <many-to-one name=\"salesperson\"/>\n" +#~ " </subclass>\n" +#~ " \n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " \n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"hilo\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <property name=\"name\" length=\"100\"/>\n" +#~ " \n" +#~ " <one-to-one name=\"address\" \n" +#~ " property-ref=\"person\"\n" +#~ " cascade=\"all\"\n" +#~ " fetch=\"join\"/>\n" +#~ " \n" +#~ " <set name=\"accounts\" \n" +#~ " inverse=\"true\">\n" +#~ " <key column=\"userId\"\n" +#~ " property-ref=\"userId\"/>\n" +#~ " <one-to-many class=\"Account\"/>\n" +#~ " </set>\n" +#~ " \n" +#~ " <property name=\"userId\" length=\"8\"/>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ "\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"hilo\"/>\n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"address\" length=\"300\"/>\n" +#~ " <property name=\"zip\" length=\"5\"/>\n" +#~ " <property name=\"country\" length=\"25\"/>\n" +#~ " <many-to-one name=\"person\" unique=\"true\" not-null=\"true\"/>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Account\">\n" +#~ " <id name=\"accountId\" length=\"32\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <many-to-one name=\"user\"\n" +#~ " column=\"userId\"\n" +#~ " property-ref=\"userId\"/>\n" +#~ " \n" +#~ " <property name=\"type\" not-null=\"true\"/>\n" +#~ " \n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"Person\">\n" +#~ " \n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"hilo\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <property name=\"name\" length=\"100\"/>\n" +#~ " \n" +#~ " <one-to-one name=\"address\" \n" +#~ " property-ref=\"person\"\n" +#~ " cascade=\"all\"\n" +#~ " fetch=\"join\"/>\n" +#~ " \n" +#~ " <set name=\"accounts\" \n" +#~ " inverse=\"true\">\n" +#~ " <key column=\"userId\"\n" +#~ " property-ref=\"userId\"/>\n" +#~ " <one-to-many class=\"Account\"/>\n" +#~ " </set>\n" +#~ " \n" +#~ " <property name=\"userId\" length=\"8\"/>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Address\">\n" +#~ "\n" +#~ " <id name=\"id\">\n" +#~ " <generator class=\"hilo\"/>\n" +#~ " </id>\n" +#~ "\n" +#~ " <property name=\"address\" length=\"300\"/>\n" +#~ " <property name=\"zip\" length=\"5\"/>\n" +#~ " <property name=\"country\" length=\"25\"/>\n" +#~ " <many-to-one name=\"person\" unique=\"true\" not-null=\"true\"/>\n" +#~ "\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Account\">\n" +#~ " <id name=\"accountId\" length=\"32\">\n" +#~ " <generator class=\"uuid\"/>\n" +#~ " </id>\n" +#~ " \n" +#~ " <many-to-one name=\"user\"\n" +#~ " column=\"userId\"\n" +#~ " property-ref=\"userId\"/>\n" +#~ " \n" +#~ " <property name=\"type\" not-null=\"true\"/>\n" +#~ " \n" +#~ "</class>]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_parentchild.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_parentchild.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_parentchild.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,428 @@ +# translation of example_parentchild.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: example_parentchild\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:35\n" +"PO-Revision-Date: 2010-01-05 09:05+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Example: Parent/Child" +msgstr "Exemple : père/fils" + +#. Tag: para +#, no-c-format +msgid "" +"One of the first things that new users want to do with Hibernate is to model " +"a parent/child type relationship. There are two different approaches to " +"this. The most convenient approach, especially for new users, is to model " +"both <literal>Parent</literal> and <literal>Child</literal> as entity " +"classes with a <literal>&lt;one-to-many&gt;</literal> association from " +"<literal>Parent</literal> to <literal>Child</literal>. The alternative " +"approach is to declare the <literal>Child</literal> as a <literal>&lt;" +"composite-element&gt;</literal>. The default semantics of a one-to-many " +"association in Hibernate are much less close to the usual semantics of a " +"parent/child relationship than those of a composite element mapping. We will " +"explain how to use a <emphasis>bidirectional one-to-many association with " +"cascades</emphasis> to model a parent/child relationship efficiently and " +"elegantly." +msgstr "" +"L'une des premières choses que les nouveaux utilisateurs essaient de faire " +"avec Hibernate est de modéliser une relation père/fils. Il y a deux " +"approches différentes pour cela. Pour un certain nombre de raisons, la " +"méthode la plus courante, en particulier pour les nouveaux utilisateurs, est " +"de modéliser les deux relations <literal>Père</literal> et <literal>Fils</" +"literal> comme des classes entités liées par une association <literal>&lt;" +"one-to-many&gt;</literal> du <literal>Père</literal> vers le <literal>Fils</" +"literal> (l'autre approche est de déclarer le <literal>Fils</literal> comme " +"un <literal>&lt;composite-element&gt;</literal>). On constate que la " +"sémantique par défaut de l'association un-à-plusieurs (dans Hibernate) est " +"bien moins proche du sens habituel d'une relation père/fils que celle d'un " +"mappage d'élément composite. Nous allons vous expliquer comment utiliser une " +"association <emphasis>un-à-plusieurs bidirectionnelle avec cascade</" +"emphasis> afin de modéliser efficacement et élégamment une relation père/" +"fils." + +#. Tag: title +#, no-c-format +msgid "A note about collections" +msgstr "Une note à propos des collections" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate collections are considered to be a logical part of their owning " +"entity and not of the contained entities. Be aware that this is a critical " +"distinction that has the following consequences:" +msgstr "" +"Les collections Hibernate sont considérées comme étant une partie logique de " +"leur entité propriétaire, jamais des entités qu'elle contient. C'est une " +"distinction cruciale ! Les conséquences sont les suivantes : " + +#. Tag: para +#, no-c-format +msgid "" +"When you remove/add an object from/to a collection, the version number of " +"the collection owner is incremented." +msgstr "" +"Quand nous ajoutons / retirons un objet d'une collection, le numéro de " +"version du propriétaire de la collection est incrémenté. " + +#. Tag: para +#, no-c-format +msgid "" +"If an object that was removed from a collection is an instance of a value " +"type (e.g. a composite element), that object will cease to be persistent and " +"its state will be completely removed from the database. Likewise, adding a " +"value type instance to the collection will cause its state to be immediately " +"persistent." +msgstr "" +"Si un objet qui a été enlevé d'une collection est une instance de type " +"valeur (par ex : élément composite), cet objet cessera d'être persistant et " +"son état sera complètement effacé de la base de données. Par ailleurs, " +"ajouter une instance de type valeur dans une collection entraînera que son " +"état sera immédiatement persistant. " + +#. Tag: para +#, no-c-format +msgid "" +"Conversely, if an entity is removed from a collection (a one-to-many or many-" +"to-many association), it will not be deleted by default. This behavior is " +"completely consistent; a change to the internal state of another entity " +"should not cause the associated entity to vanish. Likewise, adding an entity " +"to a collection does not cause that entity to become persistent, by default." +msgstr "" +"Si une entité est enlevée d'une collection (association un-à-plusieurs ou " +"plusieurs-à-plusieurs), elle ne sera pas effacée par défaut. Ce comportement " +"est complètement logique - une modification de l'un des états internes d'une " +"autre entité ne doit pas causer la disparition de l'entité associée. De " +"même, l'ajout d'une entité dans une collection n'engendre pas, par défaut, " +"la persistance de cette entité." + +#. Tag: para +#, no-c-format +msgid "" +"Adding an entity to a collection, by default, merely creates a link between " +"the two entities. Removing the entity will remove the link. This is " +"appropriate for all sorts of cases. However, it is not appropriate in the " +"case of a parent/child relationship. In this case, the life of the child is " +"bound to the life cycle of the parent." +msgstr "" +"Le comportement par défaut est donc que l'ajout d'une entité dans une " +"collection crée simplement le lien entre les deux entités, alors qu'effacer " +"une entité supprime ce lien. C'est le comportement le plus approprié dans la " +"plupart des cas. Ce comportement n'est cependant pas approprié lorsque la " +"vie du fils est liée au cycle de vie du père. " + +#. Tag: title +#, no-c-format +msgid "Bidirectional one-to-many" +msgstr "Un-à-plusieurs bidirectionnel" + +#. Tag: para +#, no-c-format +msgid "" +"Suppose we start with a simple <literal>&lt;one-to-many&gt;</literal> " +"association from <literal>Parent</literal> to <literal>Child</literal>." +msgstr "" +"Supposons que nous ayons une simple association <literal>&lt;one-to-many&gt;" +"</literal> de <literal>Parent</literal> à <literal>Child</literal>." + +#. Tag: para +#, no-c-format +msgid "If we were to execute the following code:" +msgstr "Si nous exécutions le code suivant :" + +#. Tag: para +#, no-c-format +msgid "Hibernate would issue two SQL statements:" +msgstr "Hibernate exécuterait deux ordres SQL :" + +#. Tag: para +#, no-c-format +msgid "" +"an <literal>INSERT</literal> to create the record for <literal>c</literal>" +msgstr "" +"un <literal>INSERT</literal> pour créer l'enregistrement pour <literal>c</" +"literal>" + +#. Tag: para +#, no-c-format +msgid "" +"an <literal>UPDATE</literal> to create the link from <literal>p</literal> to " +"<literal>c</literal>" +msgstr "" +"un <literal>UPDATE</literal> pour créer le lien de <literal>p</literal> vers " +"<literal>c</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"This is not only inefficient, but also violates any <literal>NOT NULL</" +"literal> constraint on the <literal>parent_id</literal> column. You can fix " +"the nullability constraint violation by specifying <literal>not-null=\"true" +"\"</literal> in the collection mapping:" +msgstr "" +"Ceci est non seulement inefficace, mais viole aussi toute contrainte " +"<literal>NOT NULL</literal> sur la colonne <literal>parent_id</literal>. " +"Nous pouvons réparer la contrainte de nullité en spécifiant <literal>not-" +"null=\"true\"</literal> dans le mappage de la collection : " + +#. Tag: para +#, no-c-format +msgid "However, this is not the recommended solution." +msgstr "Cependant ce n'est pas la solution recommandée." + +#. Tag: para +#, no-c-format +msgid "" +"The underlying cause of this behavior is that the link (the foreign key " +"<literal>parent_id</literal>) from <literal>p</literal> to <literal>c</" +"literal> is not considered part of the state of the <literal>Child</literal> " +"object and is therefore not created in the <literal>INSERT</literal>. The " +"solution is to make the link part of the <literal>Child</literal> mapping." +msgstr "" +"La cause sous jacente à ce comportement est que le lien (la clé étrangère " +"<literal>parent_id</literal>) de <literal>p</literal> vers <literal>c</" +"literal> n'est pas considérée comme faisant partie de l'état de l'objet " +"<literal>Child</literal> et n'est donc pas créé par l'<literal>INSERT</" +"literal>. La solution est donc que ce lien fasse partie du mappage de " +"<literal>Child</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"You also need to add the <literal>parent</literal> property to the " +"<literal>Child</literal> class." +msgstr "" +"Nous avons aussi besoin d'ajouter la propriété <literal>parent</literal> " +"dans la classe <literal>Child</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Now that the <literal>Child</literal> entity is managing the state of the " +"link, we tell the collection not to update the link. We use the " +"<literal>inverse</literal> attribute to do this:" +msgstr "" +"Maintenant que l'état du lien est géré par l'entité <literal>Child</" +"literal>, nous spécifions à la collection de ne pas mettre à jour le lien. " +"Nous utilisons l'attribut <literal>inverse</literal> pour faire cela :" + +#. Tag: para +#, no-c-format +msgid "The following code would be used to add a new <literal>Child</literal>:" +msgstr "" +"Le code suivant serait utilisé pour ajouter un nouveau <literal>Child</" +"literal> :" + +#. Tag: para +#, no-c-format +msgid "Only one SQL <literal>INSERT</literal> would now be issued." +msgstr "Maintenant, seul un SQL <literal>INSERT</literal> est nécessaire." + +#. Tag: para +#, no-c-format +msgid "" +"You could also create an <literal>addChild()</literal> method of " +"<literal>Parent</literal>." +msgstr "" +"Pour alléger encore un peu les choses, nous créerons une méthode " +"<literal>addChild()</literal> de <literal>Parent</literal>. " + +#. Tag: para +#, no-c-format +msgid "The code to add a <literal>Child</literal> looks like this:" +msgstr "Le code d'ajout d'un <literal>Child</literal> serait alors :" + +#. Tag: title +#, no-c-format +msgid "Cascading life cycle" +msgstr "Cycle de vie en cascade " + +#. Tag: para +#, no-c-format +msgid "" +"You can address the frustrations of the explicit call to <literal>save()</" +"literal> by using cascades." +msgstr "" +"L'appel explicite de <literal>save()</literal> est un peu fastidieux. Nous " +"pouvons simplifier cela en utilisant les cascades. " + +#. Tag: para +#, no-c-format +msgid "This simplifies the code above to:" +msgstr "Cela simplifie le code précédent en :" + +#. Tag: para +#, no-c-format +msgid "" +"Similarly, we do not need to iterate over the children when saving or " +"deleting a <literal>Parent</literal>. The following removes <literal>p</" +"literal> and all its children from the database." +msgstr "" +"De la même manière, nous n'avons pas à itérer sur les fils lorsque nous " +"sauvons ou effaçons un <literal>Parent</literal>. Le code suivant efface " +"<literal>p</literal> et tous ses fils de la base de données. " + +#. Tag: para +#, no-c-format +msgid "However, the following code:" +msgstr "Par contre, ce code :" + +#. Tag: para +#, no-c-format +msgid "" +"will not remove <literal>c</literal> from the database. In this case, it " +"will only remove the link to <literal>p</literal> and cause a <literal>NOT " +"NULL</literal> constraint violation. You need to explicitly <literal>delete()" +"</literal> the <literal>Child</literal>." +msgstr "" +"n'effacera pas <literal>c</literal> de la base de données, il enlèvera " +"seulement le lien vers <literal>p</literal> (et causera une violation de " +"contrainte <literal>NOT NULL</literal>, dans ce cas). Vous devez " +"explicitement utiliser <literal>delete()</literal> sur <literal>Child</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"In our case, a <literal>Child</literal> cannot exist without its parent. So " +"if we remove a <literal>Child</literal> from the collection, we do want it " +"to be deleted. To do this, we must use <literal>cascade=\"all-delete-orphan" +"\"</literal>." +msgstr "" +"Dans notre cas, un <literal>Child</literal> ne peut pas vraiment exister " +"sans son père. Si nous effaçons un <literal>Child</literal> de la " +"collection, nous voulons vraiment qu'il soit effacé. Pour cela, nous devons " +"utiliser <literal>cascade=\"all-delete-orphan\"</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Even though the collection mapping specifies <literal>inverse=\"true\"</" +"literal>, cascades are still processed by iterating the collection elements. " +"If you need an object be saved, deleted or updated by cascade, you must add " +"it to the collection. It is not enough to simply call <literal>setParent()</" +"literal>." +msgstr "" +"À noter : même si le mappage de la collection spécifie <literal>inverse=" +"\"true\"</literal>, les cascades sont toujours assurées par l'itération sur " +"les éléments de la collection. Donc, si vous avez besoin qu'un objet soit " +"enregistré, effacé ou mis à jour par cascade, vous devez l'ajouter dans la " +"collection. Il ne suffit pas d'appeler explicitement <literal>setParent()</" +"literal>." + +#. Tag: title +#, no-c-format +msgid "Cascades and <literal>unsaved-value</literal>" +msgstr "" +"Cascades et <literal>unsaved-value</literal> (valeurs non sauvegardées)" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Suppose we loaded up a <literal>Parent</literal> in one <literal>Session</" +"literal>, made some changes in a UI action and wanted to persist these " +"changes in a new session by calling <literal>update()</literal>. The " +"<literal>Parent</literal> will contain a collection of children and, since " +"the cascading update is enabled, Hibernate needs to know which children are " +"newly instantiated and which represent existing rows in the database. We " +"will also assume that both <literal>Parent</literal> and <literal>Child</" +"literal> have generated identifier properties of type <literal>Long</" +"literal>. Hibernate will use the identifier and version/timestamp property " +"value to determine which of the children are new. (See <xref linkend=" +"\"objectstate-saveorupdate\" />.) <emphasis>In Hibernate3, it is no longer " +"necessary to specify an <literal>unsaved-value</literal> explicitly.</" +"emphasis>" +msgstr "" +"Supposons que nous ayons chargé un <literal>Parent</literal> dans une " +"<literal>Session</literal>, que nous l'ayons ensuite modifié et que voulions " +"persister ces modifications dans une nouvelle session en appelant " +"<literal>update()</literal>. Le <literal>Parent</literal> contiendra une " +"collection de fils et, puisque la cascade est activée, Hibernate a besoin de " +"savoir quels fils viennent d'être instanciés et quels fils représentent des " +"lignes existantes dans la base de données. Supposons aussi que " +"<literal>Parent</literal> et <literal>Child</literal> ont tous deux des " +"identifiants du type <literal>Long</literal>. Hibernate utilisera la " +"propriété de l'identifiant et la propriété de la version/horodatage pour " +"déterminer quels fils sont nouveaux (vous pouvez aussi utiliser la propriété " +"version ou timestamp, consultez <xref linkend=\"objectstate-saveorupdate\" /" +">.) <emphasis>Dans Hibernate3, il n'est plus nécessaire de spécifier une " +"<literal>unsaved-value</literal> explicitement.</emphasis> " + +#. Tag: para +#, no-c-format +msgid "" +"The following code will update <literal>parent</literal> and <literal>child</" +"literal> and insert <literal>newChild</literal>:" +msgstr "" +"Le code suivant mettra à jour <literal>parent</literal> et <literal>child</" +"literal> et insérera <literal>newChild</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"This may be suitable for the case of a generated identifier, but what about " +"assigned identifiers and composite identifiers? This is more difficult, " +"since Hibernate cannot use the identifier property to distinguish between a " +"newly instantiated object, with an identifier assigned by the user, and an " +"object loaded in a previous session. In this case, Hibernate will either use " +"the timestamp or version property, or will actually query the second-level " +"cache or, worst case, the database, to see if the row exists." +msgstr "" +"Ceci est très bien pour des identifiants générés, mais qu'en est-il des " +"identifiants assignés et des identifiants composés ? C'est plus difficile, " +"puisque Hibernate ne peut pas utiliser la propriété de l'identifiant pour " +"distinguer entre un objet nouvellement instancié (avec un identifiant " +"assigné par l'utilisateur) et un objet chargé dans une session précédente. " +"Dans ce cas, Hibernate utilisera soit la propriété de version ou " +"d'horodatage, soit effectuera vraiment une requête au cache de second " +"niveau, soit, dans le pire des cas, à la base de données, pour voir si la " +"ligne existe. " + +#. Tag: title +#, no-c-format +msgid "Conclusion" +msgstr "Conclusion" + +#. Tag: para +#, no-c-format +msgid "" +"The sections we have just covered can be a bit confusing. However, in " +"practice, it all works out nicely. Most Hibernate applications use the " +"parent/child pattern in many places." +msgstr "" +"Il y a quelques principes à maîtriser dans ce chapitre et tout cela peut " +"paraître déroutant la première fois. Cependant, dans la pratique, tout " +"fonctionne parfaitement. La plupart des applications Hibernate utilisent le " +"modèle père / fils. " + +#. Tag: para +#, no-c-format +msgid "" +"We mentioned an alternative in the first paragraph. None of the above issues " +"exist in the case of <literal>&lt;composite-element&gt;</literal> mappings, " +"which have exactly the semantics of a parent/child relationship. " +"Unfortunately, there are two big limitations with composite element classes: " +"composite elements cannot own collections and they should not be the child " +"of any entity other than the unique parent." +msgstr "" +"Nous avons évoqué une alternative dans le premier paragraphe. Aucun des " +"points traités précédemment n'existe dans le cas de mappings <literal>&lt;" +"composite-element&gt;</literal> qui possède exactement la sémantique d'une " +"relation père / fils. Malheureusement, il y a deux grandes limitations pour " +"les classes d'éléments composites : les éléments composites ne peuvent " +"contenir de collections, et ils ne peuvent être les fils d'entités autres " +"que l'unique parent. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_weblog.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_weblog.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/example_weblog.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,863 @@ +# translation of example_weblog.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: example_weblog\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:35\n" +"PO-Revision-Date: 2009-10-30 13:49+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Example: Weblog Application" +msgstr "Exemple : application Weblog" + +#. Tag: title +#, no-c-format +msgid "Persistent Classes" +msgstr "Classes persistantes" + +#. Tag: para +#, no-c-format +msgid "" +"The persistent classes here represent a weblog and an item posted in a " +"weblog. They are to be modelled as a standard parent/child relationship, but " +"we will use an ordered bag, instead of a set:" +msgstr "" +"Les classes persistantes représentent un weblog, et un article posté dans un " +"weblog. Il seront modélisés comme une relation père/fils standard, mais nous " +"allons utiliser un sac trié au lieu d'un set :" + +#. Tag: title +#, no-c-format +msgid "Hibernate Mappings" +msgstr "Mappages Hibernate" + +#. Tag: para +#, no-c-format +msgid "The XML mappings are now straightforward. For example:" +msgstr "" +"Le mappage XML doit maintenant être relativement simple à vos yeux. Par " +"exemple :" + +#. Tag: title +#, no-c-format +msgid "Hibernate Code" +msgstr "Code Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"The following class demonstrates some of the kinds of things we can do with " +"these classes using Hibernate:" +msgstr "" +"La classe suivante montre quelques utilisations de ces classes avec " +"Hibernate :" + +#~ msgid "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.util.List;\n" +#~ "\n" +#~ "public class Blog {\n" +#~ " private Long _id;\n" +#~ " private String _name;\n" +#~ " private List _items;\n" +#~ "\n" +#~ " public Long getId() {\n" +#~ " return _id;\n" +#~ " }\n" +#~ " public List getItems() {\n" +#~ " return _items;\n" +#~ " }\n" +#~ " public String getName() {\n" +#~ " return _name;\n" +#~ " }\n" +#~ " public void setId(Long long1) {\n" +#~ " _id = long1;\n" +#~ " }\n" +#~ " public void setItems(List list) {\n" +#~ " _items = list;\n" +#~ " }\n" +#~ " public void setName(String string) {\n" +#~ " _name = string;\n" +#~ " }\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.util.List;\n" +#~ "\n" +#~ "public class Blog {\n" +#~ " private Long _id;\n" +#~ " private String _name;\n" +#~ " private List _items;\n" +#~ "\n" +#~ " public Long getId() {\n" +#~ " return _id;\n" +#~ " }\n" +#~ " public List getItems() {\n" +#~ " return _items;\n" +#~ " }\n" +#~ " public String getName() {\n" +#~ " return _name;\n" +#~ " }\n" +#~ " public void setId(Long long1) {\n" +#~ " _id = long1;\n" +#~ " }\n" +#~ " public void setItems(List list) {\n" +#~ " _items = list;\n" +#~ " }\n" +#~ " public void setName(String string) {\n" +#~ " _name = string;\n" +#~ " }\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.text.DateFormat;\n" +#~ "import java.util.Calendar;\n" +#~ "\n" +#~ "public class BlogItem {\n" +#~ " private Long _id;\n" +#~ " private Calendar _datetime;\n" +#~ " private String _text;\n" +#~ " private String _title;\n" +#~ " private Blog _blog;\n" +#~ "\n" +#~ " public Blog getBlog() {\n" +#~ " return _blog;\n" +#~ " }\n" +#~ " public Calendar getDatetime() {\n" +#~ " return _datetime;\n" +#~ " }\n" +#~ " public Long getId() {\n" +#~ " return _id;\n" +#~ " }\n" +#~ " public String getText() {\n" +#~ " return _text;\n" +#~ " }\n" +#~ " public String getTitle() {\n" +#~ " return _title;\n" +#~ " }\n" +#~ " public void setBlog(Blog blog) {\n" +#~ " _blog = blog;\n" +#~ " }\n" +#~ " public void setDatetime(Calendar calendar) {\n" +#~ " _datetime = calendar;\n" +#~ " }\n" +#~ " public void setId(Long long1) {\n" +#~ " _id = long1;\n" +#~ " }\n" +#~ " public void setText(String string) {\n" +#~ " _text = string;\n" +#~ " }\n" +#~ " public void setTitle(String string) {\n" +#~ " _title = string;\n" +#~ " }\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.text.DateFormat;\n" +#~ "import java.util.Calendar;\n" +#~ "\n" +#~ "public class BlogItem {\n" +#~ " private Long _id;\n" +#~ " private Calendar _datetime;\n" +#~ " private String _text;\n" +#~ " private String _title;\n" +#~ " private Blog _blog;\n" +#~ "\n" +#~ " public Blog getBlog() {\n" +#~ " return _blog;\n" +#~ " }\n" +#~ " public Calendar getDatetime() {\n" +#~ " return _datetime;\n" +#~ " }\n" +#~ " public Long getId() {\n" +#~ " return _id;\n" +#~ " }\n" +#~ " public String getText() {\n" +#~ " return _text;\n" +#~ " }\n" +#~ " public String getTitle() {\n" +#~ " return _title;\n" +#~ " }\n" +#~ " public void setBlog(Blog blog) {\n" +#~ " _blog = blog;\n" +#~ " }\n" +#~ " public void setDatetime(Calendar calendar) {\n" +#~ " _datetime = calendar;\n" +#~ " }\n" +#~ " public void setId(Long long1) {\n" +#~ " _id = long1;\n" +#~ " }\n" +#~ " public void setText(String string) {\n" +#~ " _text = string;\n" +#~ " }\n" +#~ " public void setTitle(String string) {\n" +#~ " _title = string;\n" +#~ " }\n" +#~ "}]]>" + +#~ msgid "" +#~ "<![CDATA[<?xml version=\"1.0\"?>\n" +#~ "<!DOCTYPE hibernate-mapping PUBLIC\n" +#~ " \"-//Hibernate/Hibernate Mapping DTD 3.0//EN\"\n" +#~ " \"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd\">\n" +#~ "\n" +#~ "<hibernate-mapping package=\"eg\">\n" +#~ "\n" +#~ " <class\n" +#~ " name=\"Blog\"\n" +#~ " table=\"BLOGS\">\n" +#~ "\n" +#~ " <id\n" +#~ " name=\"id\"\n" +#~ " column=\"BLOG_ID\">\n" +#~ "\n" +#~ " <generator class=\"native\"/>\n" +#~ "\n" +#~ " </id>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"name\"\n" +#~ " column=\"NAME\"\n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ "\n" +#~ " <bag\n" +#~ " name=\"items\"\n" +#~ " inverse=\"true\"\n" +#~ " order-by=\"DATE_TIME\"\n" +#~ " cascade=\"all\">\n" +#~ "\n" +#~ " <key column=\"BLOG_ID\"/>\n" +#~ " <one-to-many class=\"BlogItem\"/>\n" +#~ "\n" +#~ " </bag>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" +#~ msgstr "" +#~ "<![CDATA[<?xml version=\"1.0\"?>\n" +#~ "<!DOCTYPE hibernate-mapping PUBLIC\n" +#~ " \"-//Hibernate/Hibernate Mapping DTD 3.0//EN\"\n" +#~ " \"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd\">\n" +#~ "\n" +#~ "<hibernate-mapping package=\"eg\">\n" +#~ "\n" +#~ " <class\n" +#~ " name=\"Blog\"\n" +#~ " table=\"BLOGS\">\n" +#~ "\n" +#~ " <id\n" +#~ " name=\"id\"\n" +#~ " column=\"BLOG_ID\">\n" +#~ "\n" +#~ " <generator class=\"native\"/>\n" +#~ "\n" +#~ " </id>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"name\"\n" +#~ " column=\"NAME\"\n" +#~ " not-null=\"true\"\n" +#~ " unique=\"true\"/>\n" +#~ "\n" +#~ " <bag\n" +#~ " name=\"items\"\n" +#~ " inverse=\"true\"\n" +#~ " order-by=\"DATE_TIME\"\n" +#~ " cascade=\"all\">\n" +#~ "\n" +#~ " <key column=\"BLOG_ID\"/>\n" +#~ " <one-to-many class=\"BlogItem\"/>\n" +#~ "\n" +#~ " </bag>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" + +#~ msgid "" +#~ "<![CDATA[<?xml version=\"1.0\"?>\n" +#~ "<!DOCTYPE hibernate-mapping PUBLIC\n" +#~ " \"-//Hibernate/Hibernate Mapping DTD 3.0//EN\"\n" +#~ " \"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd\">\n" +#~ "\n" +#~ "<hibernate-mapping package=\"eg\">\n" +#~ "\n" +#~ " <class\n" +#~ " name=\"BlogItem\"\n" +#~ " table=\"BLOG_ITEMS\"\n" +#~ " dynamic-update=\"true\">\n" +#~ "\n" +#~ " <id\n" +#~ " name=\"id\"\n" +#~ " column=\"BLOG_ITEM_ID\">\n" +#~ "\n" +#~ " <generator class=\"native\"/>\n" +#~ "\n" +#~ " </id>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"title\"\n" +#~ " column=\"TITLE\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"text\"\n" +#~ " column=\"TEXT\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"datetime\"\n" +#~ " column=\"DATE_TIME\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <many-to-one\n" +#~ " name=\"blog\"\n" +#~ " column=\"BLOG_ID\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" +#~ msgstr "" +#~ "<![CDATA[<?xml version=\"1.0\"?>\n" +#~ "<!DOCTYPE hibernate-mapping PUBLIC\n" +#~ " \"-//Hibernate/Hibernate Mapping DTD 3.0//EN\"\n" +#~ " \"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd\">\n" +#~ "\n" +#~ "<hibernate-mapping package=\"eg\">\n" +#~ "\n" +#~ " <class\n" +#~ " name=\"BlogItem\"\n" +#~ " table=\"BLOG_ITEMS\"\n" +#~ " dynamic-update=\"true\">\n" +#~ "\n" +#~ " <id\n" +#~ " name=\"id\"\n" +#~ " column=\"BLOG_ITEM_ID\">\n" +#~ "\n" +#~ " <generator class=\"native\"/>\n" +#~ "\n" +#~ " </id>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"title\"\n" +#~ " column=\"TITLE\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"text\"\n" +#~ " column=\"TEXT\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <property\n" +#~ " name=\"datetime\"\n" +#~ " column=\"DATE_TIME\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " <many-to-one\n" +#~ " name=\"blog\"\n" +#~ " column=\"BLOG_ID\"\n" +#~ " not-null=\"true\"/>\n" +#~ "\n" +#~ " </class>\n" +#~ "\n" +#~ "</hibernate-mapping>]]>" + +#~ msgid "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.util.ArrayList;\n" +#~ "import java.util.Calendar;\n" +#~ "import java.util.Iterator;\n" +#~ "import java.util.List;\n" +#~ "\n" +#~ "import org.hibernate.HibernateException;\n" +#~ "import org.hibernate.Query;\n" +#~ "import org.hibernate.Session;\n" +#~ "import org.hibernate.SessionFactory;\n" +#~ "import org.hibernate.Transaction;\n" +#~ "import org.hibernate.cfg.Configuration;\n" +#~ "import org.hibernate.tool.hbm2ddl.SchemaExport;\n" +#~ "\n" +#~ "public class BlogMain {\n" +#~ " \n" +#~ " private SessionFactory _sessions;\n" +#~ " \n" +#~ " public void configure() throws HibernateException {\n" +#~ " _sessions = new Configuration()\n" +#~ " .addClass(Blog.class)\n" +#~ " .addClass(BlogItem.class)\n" +#~ " .buildSessionFactory();\n" +#~ " }\n" +#~ " \n" +#~ " public void exportTables() throws HibernateException {\n" +#~ " Configuration cfg = new Configuration()\n" +#~ " .addClass(Blog.class)\n" +#~ " .addClass(BlogItem.class);\n" +#~ " new SchemaExport(cfg).create(true, true);\n" +#~ " }\n" +#~ " \n" +#~ " public Blog createBlog(String name) throws HibernateException {\n" +#~ " \n" +#~ " Blog blog = new Blog();\n" +#~ " blog.setName(name);\n" +#~ " blog.setItems( new ArrayList() );\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.persist(blog);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return blog;\n" +#~ " }\n" +#~ " \n" +#~ " public BlogItem createBlogItem(Blog blog, String title, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " BlogItem item = new BlogItem();\n" +#~ " item.setTitle(title);\n" +#~ " item.setText(text);\n" +#~ " item.setBlog(blog);\n" +#~ " item.setDatetime( Calendar.getInstance() );\n" +#~ " blog.getItems().add(item);\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.update(blog);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return item;\n" +#~ " }\n" +#~ " \n" +#~ " public BlogItem createBlogItem(Long blogid, String title, String " +#~ "text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " BlogItem item = new BlogItem();\n" +#~ " item.setTitle(title);\n" +#~ " item.setText(text);\n" +#~ " item.setDatetime( Calendar.getInstance() );\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Blog blog = (Blog) session.load(Blog.class, blogid);\n" +#~ " item.setBlog(blog);\n" +#~ " blog.getItems().add(item);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return item;\n" +#~ " }\n" +#~ " \n" +#~ " public void updateBlogItem(BlogItem item, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " item.setText(text);\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.update(item);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " }\n" +#~ " \n" +#~ " public void updateBlogItem(Long itemid, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " BlogItem item = (BlogItem) session.load(BlogItem.class, " +#~ "itemid);\n" +#~ " item.setText(text);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " }\n" +#~ " \n" +#~ " public List listAllBlogNamesAndItemCounts(int max)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " List result = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"select blog.id, blog.name, count(blogItem) \" +\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"left outer join blog.items as blogItem \" +\n" +#~ " \"group by blog.name, blog.id \" +\n" +#~ " \"order by max(blogItem.datetime)\"\n" +#~ " );\n" +#~ " q.setMaxResults(max);\n" +#~ " result = q.list();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return result;\n" +#~ " }\n" +#~ " \n" +#~ " public Blog getBlogAndAllItems(Long blogid)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " Blog blog = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"left outer join fetch blog.items \" +\n" +#~ " \"where blog.id = :blogid\"\n" +#~ " );\n" +#~ " q.setParameter(\"blogid\", blogid);\n" +#~ " blog = (Blog) q.uniqueResult();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return blog;\n" +#~ " }\n" +#~ " \n" +#~ " public List listBlogsAndRecentItems() throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " List result = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"inner join blog.items as blogItem \" +\n" +#~ " \"where blogItem.datetime > :minDate\"\n" +#~ " );\n" +#~ "\n" +#~ " Calendar cal = Calendar.getInstance();\n" +#~ " cal.roll(Calendar.MONTH, false);\n" +#~ " q.setCalendar(\"minDate\", cal);\n" +#~ " \n" +#~ " result = q.list();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return result;\n" +#~ " }\n" +#~ "}]]>" +#~ msgstr "" +#~ "<![CDATA[package eg;\n" +#~ "\n" +#~ "import java.util.ArrayList;\n" +#~ "import java.util.Calendar;\n" +#~ "import java.util.Iterator;\n" +#~ "import java.util.List;\n" +#~ "\n" +#~ "import org.hibernate.HibernateException;\n" +#~ "import org.hibernate.Query;\n" +#~ "import org.hibernate.Session;\n" +#~ "import org.hibernate.SessionFactory;\n" +#~ "import org.hibernate.Transaction;\n" +#~ "import org.hibernate.cfg.Configuration;\n" +#~ "import org.hibernate.tool.hbm2ddl.SchemaExport;\n" +#~ "\n" +#~ "public class BlogMain {\n" +#~ " \n" +#~ " private SessionFactory _sessions;\n" +#~ " \n" +#~ " public void configure() throws HibernateException {\n" +#~ " _sessions = new Configuration()\n" +#~ " .addClass(Blog.class)\n" +#~ " .addClass(BlogItem.class)\n" +#~ " .buildSessionFactory();\n" +#~ " }\n" +#~ " \n" +#~ " public void exportTables() throws HibernateException {\n" +#~ " Configuration cfg = new Configuration()\n" +#~ " .addClass(Blog.class)\n" +#~ " .addClass(BlogItem.class);\n" +#~ " new SchemaExport(cfg).create(true, true);\n" +#~ " }\n" +#~ " \n" +#~ " public Blog createBlog(String name) throws HibernateException {\n" +#~ " \n" +#~ " Blog blog = new Blog();\n" +#~ " blog.setName(name);\n" +#~ " blog.setItems( new ArrayList() );\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.persist(blog);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return blog;\n" +#~ " }\n" +#~ " \n" +#~ " public BlogItem createBlogItem(Blog blog, String title, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " BlogItem item = new BlogItem();\n" +#~ " item.setTitle(title);\n" +#~ " item.setText(text);\n" +#~ " item.setBlog(blog);\n" +#~ " item.setDatetime( Calendar.getInstance() );\n" +#~ " blog.getItems().add(item);\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.update(blog);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return item;\n" +#~ " }\n" +#~ " \n" +#~ " public BlogItem createBlogItem(Long blogid, String title, String " +#~ "text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " BlogItem item = new BlogItem();\n" +#~ " item.setTitle(title);\n" +#~ " item.setText(text);\n" +#~ " item.setDatetime( Calendar.getInstance() );\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Blog blog = (Blog) session.load(Blog.class, blogid);\n" +#~ " item.setBlog(blog);\n" +#~ " blog.getItems().add(item);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return item;\n" +#~ " }\n" +#~ " \n" +#~ " public void updateBlogItem(BlogItem item, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " item.setText(text);\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " session.update(item);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " }\n" +#~ " \n" +#~ " public void updateBlogItem(Long itemid, String text)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " BlogItem item = (BlogItem) session.load(BlogItem.class, " +#~ "itemid);\n" +#~ " item.setText(text);\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " }\n" +#~ " \n" +#~ " public List listAllBlogNamesAndItemCounts(int max)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " List result = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"select blog.id, blog.name, count(blogItem) \" +\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"left outer join blog.items as blogItem \" +\n" +#~ " \"group by blog.name, blog.id \" +\n" +#~ " \"order by max(blogItem.datetime)\"\n" +#~ " );\n" +#~ " q.setMaxResults(max);\n" +#~ " result = q.list();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return result;\n" +#~ " }\n" +#~ " \n" +#~ " public Blog getBlogAndAllItems(Long blogid)\n" +#~ " throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " Blog blog = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"left outer join fetch blog.items \" +\n" +#~ " \"where blog.id = :blogid\"\n" +#~ " );\n" +#~ " q.setParameter(\"blogid\", blogid);\n" +#~ " blog = (Blog) q.uniqueResult();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return blog;\n" +#~ " }\n" +#~ " \n" +#~ " public List listBlogsAndRecentItems() throws HibernateException {\n" +#~ " \n" +#~ " Session session = _sessions.openSession();\n" +#~ " Transaction tx = null;\n" +#~ " List result = null;\n" +#~ " try {\n" +#~ " tx = session.beginTransaction();\n" +#~ " Query q = session.createQuery(\n" +#~ " \"from Blog as blog \" +\n" +#~ " \"inner join blog.items as blogItem \" +\n" +#~ " \"where blogItem.datetime > :minDate\"\n" +#~ " );\n" +#~ "\n" +#~ " Calendar cal = Calendar.getInstance();\n" +#~ " cal.roll(Calendar.MONTH, false);\n" +#~ " q.setCalendar(\"minDate\", cal);\n" +#~ " \n" +#~ " result = q.list();\n" +#~ " tx.commit();\n" +#~ " }\n" +#~ " catch (HibernateException he) {\n" +#~ " if (tx!=null) tx.rollback();\n" +#~ " throw he;\n" +#~ " }\n" +#~ " finally {\n" +#~ " session.close();\n" +#~ " }\n" +#~ " return result;\n" +#~ " }\n" +#~ "}]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/filters.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/filters.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/filters.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,332 @@ +# translation of filters.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: filters\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:35\n" +"PO-Revision-Date: 2009-11-11 09:26+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Filtering data" +msgstr "Filtrer les données" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 provides an innovative new approach to handling data with " +"\"visibility\" rules. A <emphasis>Hibernate filter</emphasis> is a global, " +"named, parameterized filter that can be enabled or disabled for a particular " +"Hibernate session." +msgstr "" +"Hibernate3 fournit une nouvelle approche innovatrice pour manipuler des " +"données avec des règles de \"visibilité\". Un <emphasis>filtre Hibernate</" +"emphasis> est un filtre global, nommé, paramétré qui peut être activé ou " +"désactivé pour une session Hibernate particulière. " + +#. Tag: title +#, no-c-format +msgid "Hibernate filters" +msgstr "Filtres Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 has the ability to pre-define filter criteria and attach those " +"filters at both a class level and a collection level. A filter criteria " +"allows you to define a restriction clause similar to the existing \"where\" " +"attribute available on the class and various collection elements. These " +"filter conditions, however, can be parameterized. The application can then " +"decide at runtime whether certain filters should be enabled and what their " +"parameter values should be. Filters can be used like database views, but " +"they are parameterized inside the application." +msgstr "" +"Hibernate3 ajoute la capacité de prédéfinir des critères de filtre et " +"d'attacher ces filtres à une classe ou à une collection. Un critère de " +"filtre est la faculté de définir une clause de restriction très similaire à " +"l'attribut \"where\" existant disponible sur une classe et divers éléments " +"d'une collection. Par ailleurs ces conditions de filtre peuvent être " +"paramétrées. L'application peut alors prendre la décision à l'exécution si " +"des filtres donnés doivent être activés et quels doivent être leurs " +"paramètres. Des filtres peuvent être utilisés comme des vues de base de " +"données, mais paramétrées dans l'application. " + +#. Tag: para +#, no-c-format +msgid "" +"In order to use filters, they must first be defined and then attached to the " +"appropriate mapping elements. To define a filter, use the <literal>&lt;" +"filter-def/&gt;</literal> element within a <literal>&lt;hibernate-mapping/" +"&gt;</literal> element:" +msgstr "" +"Afin d'utiliser des filtres, ils doivent d'abord être définis, puis attachés " +"aux éléments de mapping appropriés. Pour définir un filtre, utilisez " +"l'élément <literal>&lt;filter-def/&gt;</literal> dans un élément " +"<literal>&lt;hibernate-mapping/&gt;</literal> :" + +#. Tag: para +#, no-c-format +msgid "This filter can then be attached to a class:" +msgstr "Puis, ce filtre peut être attaché à une classe : " + +#. Tag: para +#, no-c-format +msgid "Or, to a collection:" +msgstr "Ou bien, à une collection :" + +#. Tag: para +#, no-c-format +msgid "Or, to both or multiples of each at the same time." +msgstr "Ou même encore, aux deux (ou à plusieurs de chaque) en même temps." + +#. Tag: para +#, no-c-format +msgid "" +"The methods on <literal>Session</literal> are: <literal>enableFilter(String " +"filterName)</literal>, <literal>getEnabledFilter(String filterName)</" +"literal>, and <literal>disableFilter(String filterName)</literal>. By " +"default, filters are <emphasis>not</emphasis> enabled for a given session. " +"Filters must be enabled through use of the <literal>Session.enableFilter()</" +"literal> method, which returns an instance of the <literal>Filter</literal> " +"interface. If you used the simple filter defined above, it would look like " +"this:" +msgstr "" +"Les méthodes sur <literal>Session</literal> sont : <literal>enableFilter" +"(String filterName)</literal>, <literal>getEnabledFilter(String filterName)</" +"literal>, et <literal>disableFilter(String filterName)</literal>. Par " +"défaut, les filtres <emphasis>ne sont pas</emphasis> activés pour une " +"session donnée ; ils doivent être explicitement activés en appelant la " +"méthode <literal>Session.enabledFilter()</literal>, laquelle retourne une " +"instance de l'interface <literal>Filter</literal>. Utiliser le simple filtre " +"défini ci-dessus ressemblerait à : " + +#. Tag: para +#, no-c-format +msgid "" +"Methods on the org.hibernate.Filter interface do allow the method-chaining " +"common to much of Hibernate." +msgstr "" +"Notez que des méthodes sur l'interface org.hibernate.Filter autorisent le " +"chaînage de beaucoup de méthodes communes à Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"The following is a full example, using temporal data with an effective " +"record date pattern:" +msgstr "" +"Un exemple complet, utilisant des données temporelles avec une structure de " +"date d'enregistrement effectif : " + +#. Tag: para +#, no-c-format +msgid "" +"In order to ensure that you are provided with currently effective records, " +"enable the filter on the session prior to retrieving employee data:" +msgstr "" +"Puis, afin de s'assurer que vous pouvez toujours récupérer les " +"enregistrements actuellement effectifs, activez simplement le filtre sur la " +"session avant de récupérer des données des employés : " + +#. Tag: para +#, no-c-format +msgid "" +"Even though a salary constraint was mentioned explicitly on the results in " +"the above HQL, because of the enabled filter, the query will return only " +"currently active employees who have a salary greater than one million " +"dollars." +msgstr "" +"Dans le HQL ci-dessus, bien que nous ayons seulement mentionné une " +"contrainte de salaire sur les résultats, à cause du filtre activé, la " +"requête retournera seulement les employés actuellement actifs qui ont un " +"salaire supérieur à un million de dollars. " + +#. Tag: para +#, no-c-format +msgid "" +"If you want to use filters with outer joining, either through HQL or load " +"fetching, be careful of the direction of the condition expression. It is " +"safest to set this up for left outer joining. Place the parameter first " +"followed by the column name(s) after the operator." +msgstr "" +"A noter : si vous prévoyez d'utiliser des filtres avec des jointures " +"externes (soit à travers HQL, soit par le chargement), faites attention à la " +"direction de l'expression de condition. Il est plus sûr de la positionner " +"pour les jointures externes à gauche ; en général, placez le paramètre " +"d'abord, suivi du(des) nom(s) de colonne après l'opérateur. " + +#. Tag: para +#, no-c-format +msgid "" +"After being defined, a filter might be attached to multiple entities and/or " +"collections each with its own condition. This can be problematic when the " +"conditions are the same each time. Using <literal>&lt;filter-def/&gt;</" +"literal> allows you to definine a default condition, either as an attribute " +"or CDATA:" +msgstr "" +"Après avoir été défini, un filtre peut être attaché à de nombreuses entités " +"et/ou des collections, chacune avec sa propre condition. Cela peut être " +"fastidieux quand les conditions sont les mêmes à chaque fois. Ainsi " +"<literal>&lt;filter-def/&gt;</literal> permet de définir une condition par " +"défaut, soit en tant qu'attribut, soit comme CDATA. " + +#. Tag: para +#, no-c-format +msgid "" +"This default condition will be used whenever the filter is attached to " +"something without specifying a condition. This means you can give a specific " +"condition as part of the attachment of the filter that overrides the default " +"condition in that particular case." +msgstr "" +"Cette condition par défaut sera alors utilisée à chaque fois que le filtre " +"est attaché à quelque chose sans spécifier la condition. Notez que cela " +"signifie que vous pouvez fournir une condition spécifique en tant que " +"faisant partie de la pièce attachée du filtre qui surcharge la condition par " +"défaut dans ce cas particulier. " + +#~ msgid "" +#~ "<![CDATA[<filter-def name=\"myFilter\">\n" +#~ " <filter-param name=\"myFilterParam\" type=\"string\"/>\n" +#~ "</filter-def>]]>" +#~ msgstr "" +#~ "<![CDATA[<filter-def name=\"myFilter\">\n" +#~ " <filter-param name=\"myFilterParam\" type=\"string\"/>\n" +#~ "</filter-def>]]>" + +#~ msgid "" +#~ "<![CDATA[<class name=\"myClass\" ...>\n" +#~ " ...\n" +#~ " <filter name=\"myFilter\" condition=\":myFilterParam = " +#~ "MY_FILTERED_COLUMN\"/>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<class name=\"myClass\" ...>\n" +#~ " ...\n" +#~ " <filter name=\"myFilter\" condition=\":myFilterParam = " +#~ "MY_FILTERED_COLUMN\"/>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[<set ...>\n" +#~ " <filter name=\"myFilter\" condition=\":myFilterParam = " +#~ "MY_FILTERED_COLUMN\"/>\n" +#~ "</set>]]>" +#~ msgstr "" +#~ "<![CDATA[<set ...>\n" +#~ " <filter name=\"myFilter\" condition=\":myFilterParam = " +#~ "MY_FILTERED_COLUMN\"/>\n" +#~ "</set>]]>" + +#~ msgid "" +#~ "<![CDATA[session.enableFilter(\"myFilter\").setParameter(\"myFilterParam" +#~ "\", \"some-value\");]]>" +#~ msgstr "" +#~ "<![CDATA[session.enableFilter(\"myFilter\").setParameter(\"myFilterParam" +#~ "\", \"some-value\");]]>" + +#~ msgid "" +#~ "<![CDATA[<filter-def name=\"effectiveDate\">\n" +#~ " <filter-param name=\"asOfDate\" type=\"date\"/>\n" +#~ "</filter-def>\n" +#~ "\n" +#~ "<class name=\"Employee\" ...>\n" +#~ "...\n" +#~ " <many-to-one name=\"department\" column=\"dept_id\" class=\"Department" +#~ "\"/>\n" +#~ " <property name=\"effectiveStartDate\" type=\"date\" column=" +#~ "\"eff_start_dt\"/>\n" +#~ " <property name=\"effectiveEndDate\" type=\"date\" column=\"eff_end_dt" +#~ "\"/>\n" +#~ "...\n" +#~ " <!--\n" +#~ " Note that this assumes non-terminal records have an eff_end_dt " +#~ "set to\n" +#~ " a max db date for simplicity-sake\n" +#~ " -->\n" +#~ " <filter name=\"effectiveDate\"\n" +#~ " condition=\":asOfDate BETWEEN eff_start_dt and eff_end_dt\"/" +#~ ">\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Department\" ...>\n" +#~ "...\n" +#~ " <set name=\"employees\" lazy=\"true\">\n" +#~ " <key column=\"dept_id\"/>\n" +#~ " <one-to-many class=\"Employee\"/>\n" +#~ " <filter name=\"effectiveDate\"\n" +#~ " condition=\":asOfDate BETWEEN eff_start_dt and eff_end_dt" +#~ "\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" +#~ msgstr "" +#~ "<![CDATA[<filter-def name=\"effectiveDate\">\n" +#~ " <filter-param name=\"asOfDate\" type=\"date\"/>\n" +#~ "</filter-def>\n" +#~ "\n" +#~ "<class name=\"Employee\" ...>\n" +#~ "...\n" +#~ " <many-to-one name=\"department\" column=\"dept_id\" class=\"Department" +#~ "\"/>\n" +#~ " <property name=\"effectiveStartDate\" type=\"date\" column=" +#~ "\"eff_start_dt\"/>\n" +#~ " <property name=\"effectiveEndDate\" type=\"date\" column=\"eff_end_dt" +#~ "\"/>\n" +#~ "...\n" +#~ " <!--\n" +#~ " Note that this assumes non-terminal records have an eff_end_dt " +#~ "set to\n" +#~ " a max db date for simplicity-sake\n" +#~ " -->\n" +#~ " <filter name=\"effectiveDate\"\n" +#~ " condition=\":asOfDate BETWEEN eff_start_dt and eff_end_dt\"/" +#~ ">\n" +#~ "</class>\n" +#~ "\n" +#~ "<class name=\"Department\" ...>\n" +#~ "...\n" +#~ " <set name=\"employees\" lazy=\"true\">\n" +#~ " <key column=\"dept_id\"/>\n" +#~ " <one-to-many class=\"Employee\"/>\n" +#~ " <filter name=\"effectiveDate\"\n" +#~ " condition=\":asOfDate BETWEEN eff_start_dt and eff_end_dt" +#~ "\"/>\n" +#~ " </set>\n" +#~ "</class>]]>" + +#~ msgid "" +#~ "<![CDATA[Session session = ...;\n" +#~ "session.enableFilter(\"effectiveDate\").setParameter(\"asOfDate\", new " +#~ "Date());\n" +#~ "List results = session.createQuery(\"from Employee as e where e.salary > :" +#~ "targetSalary\")\n" +#~ " .setLong(\"targetSalary\", new Long(1000000))\n" +#~ " .list();\n" +#~ "]]>" +#~ msgstr "" +#~ "<![CDATA[Session session = ...;\n" +#~ "session.enableFilter(\"effectiveDate\").setParameter(\"asOfDate\", new " +#~ "Date());\n" +#~ "List results = session.createQuery(\"from Employee as e where e.salary > :" +#~ "targetSalary\")\n" +#~ " .setLong(\"targetSalary\", new Long(1000000))\n" +#~ " .list();\n" +#~ "]]>" + +#~ msgid "" +#~ "<![CDATA[<filter-def name=\"myFilter\" condition=\"abc > xyz\">...</" +#~ "filter-def>\n" +#~ "<filter-def name=\"myOtherFilter\">abc=xyz</filter-def>]]>" +#~ msgstr "" +#~ "<![CDATA[<filter-def name=\"myFilter\" condition=\"abc > xyz\">...</" +#~ "filter-def>\n" +#~ "<filter-def name=\"myOtherFilter\">abc=xyz</filter-def>]]>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/inheritance_mapping.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/inheritance_mapping.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/inheritance_mapping.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,580 @@ +# translation of inheritance_mapping.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: inheritance_mapping\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:37+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Inheritance mapping" +msgstr "Mapping d'héritage de classe " + +#. Tag: title +#, no-c-format +msgid "The three strategies" +msgstr "Les trois stratégies " + +#. Tag: para +#, no-c-format +msgid "Hibernate supports the three basic inheritance mapping strategies:" +msgstr "Hibernate supporte les trois stratégies d'héritage de base :" + +#. Tag: para +#, no-c-format +msgid "table per class hierarchy" +msgstr "une table par hiérarchie de classe" + +#. Tag: para +#, fuzzy, no-c-format +msgid "table per subclass" +msgstr "Une table par classe fille" + +#. Tag: para +#, no-c-format +msgid "table per concrete class" +msgstr "une table par classe concrète " + +#. Tag: para +#, no-c-format +msgid "" +"In addition, Hibernate supports a fourth, slightly different kind of " +"polymorphism:" +msgstr "" +"Par ailleurs, Hibernate supporte une quatrième stratégie, avec un " +"polymorphisme légèrement différent : " + +#. Tag: para +#, no-c-format +msgid "implicit polymorphism" +msgstr "le polymorphisme implicite" + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to use different mapping strategies for different branches of " +"the same inheritance hierarchy. You can then make use of implicit " +"polymorphism to achieve polymorphism across the whole hierarchy. However, " +"Hibernate does not support mixing <literal>&lt;subclass&gt;</literal>, " +"<literal>&lt;joined-subclass&gt;</literal> and <literal>&lt;union-" +"subclass&gt;</literal> mappings under the same root <literal>&lt;class&gt;</" +"literal> element. It is possible to mix together the table per hierarchy and " +"table per subclass strategies under the the same <literal>&lt;class&gt;</" +"literal> element, by combining the <literal>&lt;subclass&gt;</literal> and " +"<literal>&lt;join&gt;</literal> elements (see below for an example)." +msgstr "" +"Il est possible d'utiliser différentes stratégies de mapping pour " +"différentes branches d'une même hiérarchie d'héritage, et ensuite d'employer " +"le polymorphisme implicite pour réaliser le polymorphisme à travers toute la " +"hiérarchie. Toutefois, Hibernate ne supporte pas les mélanges de mappages " +"<literal>&lt;subclass&gt;</literal>, <literal>&lt;joined-subclass&gt;</" +"literal> et <literal>&lt;union-subclass&gt;</literal> pour le même élément " +"<literal>&lt;class&gt;</literal> racine. Il est possible de mélanger les " +"stratégies d'une table par hiérarchie et d'une table par sous-classe, pour " +"le même élément <literal>&lt;class&gt;</literal>, en combinant les éléments " +"<literal>&lt;subclass&gt;</literal> et <literal>&lt;join&gt;</literal> (voir " +"ci-dessous). " + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to define <literal>subclass</literal>, <literal>union-" +"subclass</literal>, and <literal>joined-subclass</literal> mappings in " +"separate mapping documents directly beneath <literal>hibernate-mapping</" +"literal>. This allows you to extend a class hierarchy by adding a new " +"mapping file. You must specify an <literal>extends</literal> attribute in " +"the subclass mapping, naming a previously mapped superclass. Previously this " +"feature made the ordering of the mapping documents important. Since " +"Hibernate3, the ordering of mapping files is irrelevant when using the " +"extends keyword. The ordering inside a single mapping file still needs to be " +"defined as superclasses before subclasses." +msgstr "" +"Il est possible de définir des mappages de <literal>subclass</literal>, " +"<literal>union-subclass</literal>, et <literal>joined-subclass</literal> " +"dans des documents de mappage séparés, directement sous <literal>hibernate-" +"mappage</literal>. Ceci vous permet d'étendre une hiérarchie de classe juste " +"en ajoutant un nouveau fichier de mappage. Vous devez spécifier un attribut " +"<literal>extends</literal> dans le mappage de la sous-classe, en nommant une " +"super-classe précédemment mappée. Note : précédemment cette fonctionnalité " +"rendait important l'ordre des documents de mappage. Depuis Hibernate3, " +"l'ordre des fichier de mappage n'importe plus lors de l'utilisation du mot-" +"clef \"extends\". L'ordre à l'intérieur d'un simple fichier de mappage " +"impose encore de définir les classes mères avant les classes filles. " + +#. Tag: title +#, no-c-format +msgid "Table per class hierarchy" +msgstr "Une table par hiérarchie de classe" + +#. Tag: para +#, no-c-format +msgid "" +"Suppose we have an interface <literal>Payment</literal> with the " +"implementors <literal>CreditCardPayment</literal>, <literal>CashPayment</" +"literal>, and <literal>ChequePayment</literal>. The table per hierarchy " +"mapping would display in the following way:" +msgstr "" +"Supposons que nous ayons une interface <literal>Payment</literal>, " +"implémentée par <literal>CreditCardPayment</literal>, <literal>CashPayment</" +"literal>, <literal>ChequePayment</literal>. La stratégie une table par " +"hiérarchie serait : " + +#. Tag: para +#, no-c-format +msgid "" +"Exactly one table is required. There is a limitation of this mapping " +"strategy: columns declared by the subclasses, such as <literal>CCTYPE</" +"literal>, cannot have <literal>NOT NULL</literal> constraints." +msgstr "" +"Une seule table est requise. Une grande limitation de cette stratégie est " +"que les colonnes déclarées par les classes filles, telles que " +"<literal>CCTYPE</literal>, peuvent ne pas avoir de contrainte <literal>NOT " +"NULL</literal>. " + +#. Tag: title +#, no-c-format +msgid "Table per subclass" +msgstr "Une table par classe fille" + +#. Tag: para +#, no-c-format +msgid "A table per subclass mapping looks like this:" +msgstr "Une table par classe-fille de mappage serait : " + +#. Tag: para +#, no-c-format +msgid "" +"Four tables are required. The three subclass tables have primary key " +"associations to the superclass table so the relational model is actually a " +"one-to-one association." +msgstr "" +"Quatre tables sont requises. Les trois tables des classes filles ont une clé " +"primaire associée à la table classe mère (le modèle relationnel est une " +"association un-à-un)." + +#. Tag: title +#, no-c-format +msgid "Table per subclass: using a discriminator" +msgstr "Une table par classe fille, en utilisant un discriminant " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate's implementation of table per subclass does not require a " +"discriminator column. Other object/relational mappers use a different " +"implementation of table per subclass that requires a type discriminator " +"column in the superclass table. The approach taken by Hibernate is much more " +"difficult to implement, but arguably more correct from a relational point of " +"view. If you want to use a discriminator column with the table per subclass " +"strategy, you can combine the use of <literal>&lt;subclass&gt;</literal> and " +"<literal>&lt;join&gt;</literal>, as follows:" +msgstr "" +"Notez que l'implémentation Hibernate de la stratégie une table par classe " +"fille, ne nécessite pas de colonne discriminante dans la table classe mère. " +"D'autres implémentations de mappers Objet/Relationnel utilisent une autre " +"implémentation de la stratégie une table par classe fille qui nécessite une " +"colonne de type discriminant dans la table de la classe mère. L'approche " +"prise par Hibernate est plus difficile à implémenter mais plus correcte " +"d'une point de vue relationnel. Si vous aimeriez utiliser une colonne " +"discriminante avec la stratégie d'une table par classe fille, vous pouvez " +"combiner l'utilisation de <literal>&lt;subclass&gt;</literal> et " +"<literal>&lt;join&gt;</literal>, comme suit : " + +#. Tag: para +#, no-c-format +msgid "" +"The optional <literal>fetch=\"select\"</literal> declaration tells Hibernate " +"not to fetch the <literal>ChequePayment</literal> subclass data using an " +"outer join when querying the superclass." +msgstr "" +"La déclaration optionnelle <literal>fetch=\"select\"</literal> indique à " +"Hibernate de ne pas récupérer les données de la classe fille " +"<literal>ChequePayment</literal> par une jointure externe lors des requêtes " +"sur la classe mère. " + +#. Tag: title +#, no-c-format +msgid "Mixing table per class hierarchy with table per subclass" +msgstr "" +"Mélange d'une table par hiérarchie de classe avec une table par classe fille" + +#. Tag: para +#, no-c-format +msgid "" +"You can even mix the table per hierarchy and table per subclass strategies " +"using the following approach:" +msgstr "" +"Vous pouvez même mélanger les stratégies d'une table par hiérarchie de " +"classe et d'une table par classe fille en utilisant cette approche : " + +#. Tag: para +#, no-c-format +msgid "" +"For any of these mapping strategies, a polymorphic association to the root " +"<literal>Payment</literal> class is mapped using <literal>&lt;many-to-one&gt;" +"</literal>." +msgstr "" +"Pour importe laquelle de ces stratégies, une association polymorphique vers " +"la classe racine <literal>Payment</literal> est mappée en utilisant " +"<literal>&lt;many-to-one&gt;</literal>." + +#. Tag: title +#, no-c-format +msgid "Table per concrete class" +msgstr "Une table par classe concrète" + +#. Tag: para +#, no-c-format +msgid "" +"There are two ways we can map the table per concrete class strategy. First, " +"you can use <literal>&lt;union-subclass&gt;</literal>." +msgstr "" +"Il y a deux manières d'utiliser la stratégie d'une table par classe " +"concrète. La première est d'employer <literal>&lt;union-subclass&gt;</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Three tables are involved for the subclasses. Each table defines columns for " +"all properties of the class, including inherited properties." +msgstr "" +"Trois tables sont nécessaires pour les classes filles. Chaque table définit " +"des colonnes pour toutes les propriétés de la classe, y compris les " +"propriétés héritées. " + +#. Tag: para +#, no-c-format +msgid "" +"The limitation of this approach is that if a property is mapped on the " +"superclass, the column name must be the same on all subclass tables. The " +"identity generator strategy is not allowed in union subclass inheritance. " +"The primary key seed has to be shared across all unioned subclasses of a " +"hierarchy." +msgstr "" +"La limitation de cette approche est que si une propriété est mappée sur la " +"classe mère, le nom de la colonne doit être le même pour toutes les classes " +"filles (Une future version de Hibernate pourra assouplir ce comportement). " +"La stratégie du générateur d'identifiant n'est pas permise dans l'héritage " +"de classes filles par union, en effet la valeur de graine de la clef " +"primaire doit être partagée par toutes les classes filles fusionnées d'une " +"hiérarchie. " + +#. Tag: para +#, no-c-format +msgid "" +"If your superclass is abstract, map it with <literal>abstract=\"true\"</" +"literal>. If it is not abstract, an additional table (it defaults to " +"<literal>PAYMENT</literal> in the example above), is needed to hold " +"instances of the superclass." +msgstr "" +"Si votre classe mère est abstraite, mappez la avec <literal>abstract=\"true" +"\"</literal>. Bien sûr, si elle n'est pas abstraite, une table " +"supplémentaire (par défaut, <literal>PAYMENT</literal> dans l'exemple ci-" +"dessus) est requise pour contenir des instances de la classe mère. " + +#. Tag: title +#, no-c-format +msgid "Table per concrete class using implicit polymorphism" +msgstr "" +"Une table par classe concrète, en utilisant le polymorphisme implicite " + +#. Tag: para +#, no-c-format +msgid "An alternative approach is to make use of implicit polymorphism:" +msgstr "Une approche alternative est l'emploi du polymorphisme implicite :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Notice that the <literal>Payment</literal> interface is not mentioned " +"explicitly. Also notice that properties of <literal>Payment</literal> are " +"mapped in each of the subclasses. If you want to avoid duplication, consider " +"using XML entities (for example, <literal>[ &lt;!ENTITY allproperties SYSTEM " +"\"allproperties.xml\"&gt; ]</literal> in the <literal>DOCTYPE</literal> " +"declaration and <literal>&amp;allproperties&semi;</literal> in the mapping)." +msgstr "" +"Notez que nulle part nous ne mentionnons l'interface <literal>Payment</" +"literal> explicitement. Notez aussi que des propriétés de <literal>Payment</" +"literal> sont mappées dans chaque classe fille. Si vous voulez éviter des " +"duplications, considérez l'utilisation des entités XML (par ex. <literal>" +"[ &lt;!ENTITY allproperties SYSTEM \"allproperties.xml\"&gt; ]</literal> " +"dans la déclaration <literal>DOCTYPE</literal> et dans le mappage " +"<literal>&amp;allproperties&semi;</literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"The disadvantage of this approach is that Hibernate does not generate SQL " +"<literal>UNION</literal>s when performing polymorphic queries." +msgstr "" +"L'inconvénient de cette approche est que Hibernate ne génère pas de SQL " +"<literal>UNION</literal> s lors de l'exécution des requêtes polymorphiques. " + +#. Tag: para +#, no-c-format +msgid "" +"For this mapping strategy, a polymorphic association to <literal>Payment</" +"literal> is usually mapped using <literal>&lt;any&gt;</literal>." +msgstr "" +"Pour cette stratégie de mappage, une association polymorphique pour " +"<literal>Payment</literal> est habituellement mappée en utilisant " +"<literal>&lt;any&gt;</literal>. " + +#. Tag: title +#, no-c-format +msgid "Mixing implicit polymorphism with other inheritance mappings" +msgstr "Mélange du polymorphisme implicite avec d'autres mappages d'héritage " + +#. Tag: para +#, no-c-format +msgid "" +"Since the subclasses are each mapped in their own <literal>&lt;class&gt;</" +"literal> element, and since <literal>Payment</literal> is just an " +"interface), each of the subclasses could easily be part of another " +"inheritance hierarchy. You can still use polymorphic queries against the " +"<literal>Payment</literal> interface." +msgstr "" +"Il y a une chose supplémentaire à noter à propos de ce mappage. Puisque les " +"classes filles sont chacune mappées avec leur propre élément <literal>&lt;" +"class&gt;</literal> (et puisque <literal>Payment</literal> est juste une " +"interface), chaque classe fille pourrait facilement faire partie d'une autre " +"hiérarchie d'héritage ! (Et vous pouvez encore faire des requêtes " +"polymorphiques pour l'interface <literal>Payment</literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"Once again, <literal>Payment</literal> is not mentioned explicitly. If we " +"execute a query against the <literal>Payment</literal> interface, for " +"example <literal>from Payment</literal>, Hibernate automatically returns " +"instances of <literal>CreditCardPayment</literal> (and its subclasses, since " +"they also implement <literal>Payment</literal>), <literal>CashPayment</" +"literal> and <literal>ChequePayment</literal>, but not instances of " +"<literal>NonelectronicTransaction</literal>." +msgstr "" +"Encore une fois, nous ne mentionnons pas explicitement <literal>Payment</" +"literal>. Si nous exécutons une requête sur l'interface <literal>Payment</" +"literal> - par exemple, <literal>from Payment</literal> - Hibernate " +"retournera automatiquement les instances de <literal>CreditCardPayment</" +"literal> (et ses classes filles puisqu'elles implémentent aussi " +"<literal>Payment</literal>), <literal>CashPayment</literal> et " +"<literal>ChequePayment</literal> mais pas les instances de " +"<literal>NonelectronicTransaction</literal>. " + +#. Tag: title +#, no-c-format +msgid "Limitations" +msgstr "Limitations" + +#. Tag: para +#, no-c-format +msgid "" +"There are limitations to the \"implicit polymorphism\" approach to the table " +"per concrete-class mapping strategy. There are somewhat less restrictive " +"limitations to <literal>&lt;union-subclass&gt;</literal> mappings." +msgstr "" +"Il y a certaines limitations à l'approche du \"polymorphisme implicite\" " +"pour la stratégie de mappage d'une table par classe concrète. Il y a plutôt " +"moins de limitations restrictives aux mappages <literal>&lt;union-" +"subclass&gt;</literal>. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The following table shows the limitations of table per concrete-class " +"mappings, and of implicit polymorphism, in Hibernate." +msgstr "" +"La table suivante montre les limitations des mappages d'une table par classe " +"concrète, et du polymorphisme implicite, dans Hibernate. " + +#. Tag: title +#, fuzzy, no-c-format +msgid "Features of inheritance mappings" +msgstr "Mapping d'héritage de classe " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "Inheritance strategy" +msgstr "Mapping d'héritage de classe " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "Polymorphic many-to-one" +msgstr "Polymorphisme many-to-one : <code>&lt;any&gt;</code>" + +#. Tag: entry +#, no-c-format +msgid "Polymorphic one-to-one" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "Polymorphic one-to-many" +msgstr "" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "Polymorphic many-to-many" +msgstr "Polymorphisme many-to-one : <code>&lt;any&gt;</code>" + +#. Tag: entry +#, no-c-format +msgid "Polymorphic <literal>load()/get()</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "Polymorphic queries" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "Polymorphic joins" +msgstr "" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "Outer join fetching" +msgstr "Récupération par jointure externe supportée." + +#. Tag: entry +#, fuzzy, no-c-format +msgid "table per class-hierarchy" +msgstr "une table par hiérarchie de classe" + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;many-to-one&gt;</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;one-to-one&gt;</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;one-to-many&gt;</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;many-to-many&gt;</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>s.get(Payment.class, id)</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>from Payment p</literal>" +msgstr "" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>from Order o join o.payment p</literal>" +msgstr "Jointures polymorphiques <code>from o join o.payment p</code>" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>supported</emphasis>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "table per concrete-class (union-subclass)" +msgstr "une table par classe concrète (union-classe fille)" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>&lt;one-to-many&gt;</literal> (for <literal>inverse=\"true\"</" +"literal> only)" +msgstr "" +"Polymorphisme one-to-many : <literal>&lt;one-to-many&gt;</literal> " +"(uniquement pour <literal>inverse=\"true\"</literal>)" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "table per concrete class (implicit polymorphism)" +msgstr "une table par classe concrète (polymorphisme implicite) " + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;any&gt;</literal>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<emphasis>not supported</emphasis>" +msgstr "" + +#. Tag: entry +#, no-c-format +msgid "<literal>&lt;many-to-any&gt;</literal>" +msgstr "" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>s.createCriteria(Payment.class).add( Restrictions.idEq(id) )." +"uniqueResult()</literal>" +msgstr "" +"Polymorphisme <literal>load()</literal> ou <literal>get()</literal>: <code>s." +"createCriteria(Payment.class).add( Restrictions.idEq(id) ).uniqueResult()</" +"code>" + +#~ msgid "table per class-heirarchy" +#~ msgstr "une table par hiérarchie de classe " + +#~ msgid "Polymorphic many-to-one: <code>&lt;many-to-one&gt;</code>" +#~ msgstr "Polymorphisme many-to-one : <code>&lt;many-to-one&gt;</code>" + +#~ msgid "Polymorphic one-to-one: <code>&lt;one-to-one&gt;</code>" +#~ msgstr "Polymorphisme one-to-one : <code>&lt;one-to-one&gt;</code>" + +#~ msgid "Polymorphic one-to-many: <code>&lt;one-to-many&gt;</code>" +#~ msgstr "Polymorphisme one-to-many : <code>&lt;one-to-many&gt;</code>" + +#~ msgid "Polymorphic many-to-many: <code>&lt;many-to-many&gt;</code>" +#~ msgstr "Polymorphisme many-to-many : <code>&lt;many-to-many&gt;</code>" + +#~ msgid "" +#~ "Polymorphic <literal>load()</literal> or <literal>get()</literal>: " +#~ "<code>s.get(Payment.class, id)</code>" +#~ msgstr "" +#~ "Polymorphisme <literal>load()</literal> ou <literal>get()</literal>: " +#~ "<code>s.get(Payment.class, id)</code>" + +#~ msgid "Polymorphic queries: <code>from Payment p</code>" +#~ msgstr "Requêtes polymorphiques : <code>from Payment p</code>" + +#~ msgid "" +#~ "Polymorphic one-to-one, polymorphic one-to-many, polymorphic joins, and " +#~ "outer join fetching are not supported." +#~ msgstr "" +#~ "Polymorphisme one-to-one, polymorphisme one-to-many, les jointures " +#~ "polymorphiques, et les récupération de jointures externes ne sont pas " +#~ "supportées." + +#, fuzzy +#~ msgid "<para>table per subclass</para>" +#~ msgstr "Une table par classe fille " + +#, fuzzy +#~ msgid "<term>table per subclass</term>" +#~ msgstr "Une table par classe fille " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/performance.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/performance.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/performance.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,2262 @@ +# translation of performance.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: performance\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:38+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Improving performance" +msgstr "Améliorer les performances" + +#. Tag: title +#, no-c-format +msgid "Fetching strategies" +msgstr "Stratégies de chargement" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate uses a <emphasis>fetching strategy</emphasis> to retrieve " +"associated objects if the application needs to navigate the association. " +"Fetch strategies can be declared in the O/R mapping metadata, or over-ridden " +"by a particular HQL or <literal>Criteria</literal> query." +msgstr "" +"Une <emphasis>stratégie de chargement</emphasis> est une stratégie que " +"Hibernate va utiliser pour récupérer des objets associés si l'application a " +"besoin de naviguer à travers une association. Les stratégies de chargement " +"peuvent être déclarées dans les méta-données de l'outil de mappage objet " +"relationnel, ou surchargées par une requête de type HQL ou " +"<literal>Criteria</literal> particulière." + +#. Tag: para +#, no-c-format +msgid "Hibernate3 defines the following fetching strategies:" +msgstr "Hibernate3 définit les stratégies de chargement suivantes :" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Join fetching</emphasis>: Hibernate retrieves the associated " +"instance or collection in the same <literal>SELECT</literal>, using an " +"<literal>OUTER JOIN</literal>." +msgstr "" +"<emphasis>Chargement par jointure</emphasis> - Hibernate récupère l'instance " +"associée ou la collection dans un même <literal>SELECT</literal>, en " +"utilisant un <literal>OUTER JOIN</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Select fetching</emphasis>: a second <literal>SELECT</literal> is " +"used to retrieve the associated entity or collection. Unless you explicitly " +"disable lazy fetching by specifying <literal>lazy=\"false\"</literal>, this " +"second select will only be executed when you access the association." +msgstr "" +"<emphasis>Chargement par select</emphasis> - Un second <literal>SELECT</" +"literal> est utilisé pour récupérer l'instance associée à l'entité ou à la " +"collection. À moins que vous ne désactiviez explicitement le chargement " +"différé en spécifiant <literal>lazy=\"false\"</literal>, ce second select ne " +"sera exécuté que lorsque vous accéderez réellement à l'association." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Subselect fetching</emphasis>: a second <literal>SELECT</literal> " +"is used to retrieve the associated collections for all entities retrieved in " +"a previous query or fetch. Unless you explicitly disable lazy fetching by " +"specifying <literal>lazy=\"false\"</literal>, this second select will only " +"be executed when you access the association." +msgstr "" +"<emphasis>Chargement par sous-select</emphasis> - Un second <literal>SELECT</" +"literal> est utilisé pour récupérer les associations pour toutes les entités " +"récupérées dans une requête ou un chargement préalable. A moins que vous ne " +"désactiviez explicitement le chargement différé en spécifiant <literal>lazy=" +"\"false\"</literal>, ce second select ne sera exécuté que lorsque vous " +"accéderez réellement à l'association. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Batch fetching</emphasis>: an optimization strategy for select " +"fetching. Hibernate retrieves a batch of entity instances or collections in " +"a single <literal>SELECT</literal> by specifying a list of primary or " +"foreign keys." +msgstr "" +"<emphasis>Chargement par lot</emphasis> - Il s'agit d'une stratégie " +"d'optimisation pour le chargement par select - Hibernate récupère un lot " +"d'instances ou de collections en un seul <literal>SELECT</literal> en " +"spécifiant une liste de clés primaires ou de clés étrangères. " + +#. Tag: para +#, no-c-format +msgid "Hibernate also distinguishes between:" +msgstr "Hibernate fait également la distinction entre :" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Immediate fetching</emphasis>: an association, collection or " +"attribute is fetched immediately when the owner is loaded." +msgstr "" +"<emphasis>Chargement immédiat</emphasis> - Une association, une collection " +"ou un attribut est chargé immédiatement lorsque l'objet auquel appartient " +"cet élément est chargé. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Lazy collection fetching</emphasis>: a collection is fetched when " +"the application invokes an operation upon that collection. This is the " +"default for collections." +msgstr "" +"<emphasis>Chargement différé d'une collection</emphasis> - Une collection " +"est chargée lorsque l'application invoque une méthode sur cette collection " +"(il s'agit du mode de chargement par défaut pour les collections). " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>\"Extra-lazy\" collection fetching</emphasis>: individual elements " +"of the collection are accessed from the database as needed. Hibernate tries " +"not to fetch the whole collection into memory unless absolutely needed. It " +"is suitable for large collections." +msgstr "" +"<emphasis>Chargement \"super différé\" d'une collection</emphasis> - On " +"accède aux éléments de la collection depuis la base de données lorsque c'est " +"nécessaire. Hibernate essaie de ne pas charger toute la collection en " +"mémoire sauf si cela est absolument nécessaire (bien adapté aux très grandes " +"collections). " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Proxy fetching</emphasis>: a single-valued association is fetched " +"when a method other than the identifier getter is invoked upon the " +"associated object." +msgstr "" +"<emphasis>Chargement par proxy</emphasis> - Une association vers un seul " +"objet est chargée lorsqu'une méthode autre que le getter sur l'identifiant " +"est appelée sur l'objet associé." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>\"No-proxy\" fetching</emphasis>: a single-valued association is " +"fetched when the instance variable is accessed. Compared to proxy fetching, " +"this approach is less lazy; the association is fetched even when only the " +"identifier is accessed. It is also more transparent, since no proxy is " +"visible to the application. This approach requires buildtime bytecode " +"instrumentation and is rarely necessary." +msgstr "" +"<emphasis>Chargement \"sans proxy\"</emphasis> - une association vers un " +"seul objet est chargée lorsque l'on accède à la variable d'instance. Par " +"rapport au chargement par proxy, cette approche est moins différée " +"(l'association est quand même chargée même si on n'accède qu'à " +"l'identifiant) mais plus transparente car il n'y a pas de proxy visible dans " +"l'application. Cette approche requiert une instrumentation du bytecode à la " +"compilation et est rarement nécessaire. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Lazy attribute fetching</emphasis>: an attribute or single valued " +"association is fetched when the instance variable is accessed. This approach " +"requires buildtime bytecode instrumentation and is rarely necessary." +msgstr "" +"<emphasis>Chargement différé des attributs</emphasis> - Un attribut ou un " +"objet associé seul est chargé lorsque l'on accède à la variable d'instance. " +"Cette approche requiert une instrumentation du bytecode à la compilation et " +"est rarement nécessaire. " + +#. Tag: para +#, no-c-format +msgid "" +"We have two orthogonal notions here: <emphasis>when</emphasis> is the " +"association fetched and <emphasis>how</emphasis> is it fetched. It is " +"important that you do not confuse them. We use <literal>fetch</literal> to " +"tune performance. We can use <literal>lazy</literal> to define a contract " +"for what data is always available in any detached instance of a particular " +"class." +msgstr "" +"Nous avons ici deux notions orthogonales : <emphasis>quand</emphasis> " +"l'association est chargée et <emphasis>comment</emphasis> (quelle requête " +"SQL est utilisée). Il ne faut pas les confondre. Le mode de chargement " +"<literal>fetch</literal> est utilisé pour améliorer les performances. On " +"peut utiliser le mode <literal>lazy</literal> pour définir un contrat sur " +"quelles données sont toujours accessibles sur toute instance détachée d'une " +"classe particulière. " + +#. Tag: title +#, no-c-format +msgid "Working with lazy associations" +msgstr "Travailler avec des associations chargées en différé" + +#. Tag: para +#, no-c-format +msgid "" +"By default, Hibernate3 uses lazy select fetching for collections and lazy " +"proxy fetching for single-valued associations. These defaults make sense for " +"most associations in the majority of applications." +msgstr "" +"Par défaut, Hibernate3 utilise le chargement différé par select pour les " +"collections et le chargement différé par proxy pour les associations vers un " +"seul objet. Ces valeurs par défaut sont valables pour la plupart des " +"associations dans la plupart des applications. " + +#. Tag: para +#, no-c-format +msgid "" +"If you set <literal>hibernate.default_batch_fetch_size</literal>, Hibernate " +"will use the batch fetch optimization for lazy fetching. This optimization " +"can also be enabled at a more granular level." +msgstr "" +"Si vous définissez <literal>hibernate.default_batch_fetch_size</literal>, " +"Hibernate va utiliser l'optimisation du chargement par lot pour le " +"chargement différé (cette optimisation peut aussi être activée à un niveau " +"de granularité plus fin). " + +#. Tag: para +#, no-c-format +msgid "" +"Please be aware that access to a lazy association outside of the context of " +"an open Hibernate session will result in an exception. For example:" +msgstr "" +"L'accès à une association définie comme \"différé\", hors du contexte d'une " +"session Hibernate ouverte, entraîne une exception. Par exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"Since the permissions collection was not initialized when the " +"<literal>Session</literal> was closed, the collection will not be able to " +"load its state. <emphasis>Hibernate does not support lazy initialization for " +"detached objects</emphasis>. This can be fixed by moving the code that reads " +"from the collection to just before the transaction is committed." +msgstr "" +"Étant donné que la collection des permissions n'a pas été initialisée avant " +"de fermer la <literal>Session</literal>, la collection n'est pas capable de " +"charger son état. <emphasis>Hibernate ne supporte pas le chargement différé " +"pour des objets détachés</emphasis>. La solution à ce problème est de " +"déplacer le code qui lit à partir de la collection avant le \"commit\" de la " +"transaction. " + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, you can use a non-lazy collection or association, by " +"specifying <literal>lazy=\"false\"</literal> for the association mapping. " +"However, it is intended that lazy initialization be used for almost all " +"collections and associations. If you define too many non-lazy associations " +"in your object model, Hibernate will fetch the entire database into memory " +"in every transaction." +msgstr "" +"Une autre alternative est d'utiliser une collection ou une association non " +"\"différée\" en spécifiant <literal>lazy=\"false\"</literal> dans le mappage " +"de l'association. Cependant il est prévu que le chargement différé soit " +"utilisé pour quasiment toutes les collections ou associations. Si vous " +"définissez trop d'associations non \"différées\" dans votre modèle objet, " +"Hibernate va finir par devoir charger toute la base de données en mémoire à " +"chaque transaction." + +#. Tag: para +#, no-c-format +msgid "" +"On the other hand, you can use join fetching, which is non-lazy by nature, " +"instead of select fetching in a particular transaction. We will now explain " +"how to customize the fetching strategy. In Hibernate3, the mechanisms for " +"choosing a fetch strategy are identical for single-valued associations and " +"collections." +msgstr "" +"Par ailleurs, on veut souvent choisir un chargement par jointure (qui est " +"par défaut non différé) à la place du chargement par select dans une " +"transaction particulière. Nous allons maintenant voir comment adapter les " +"stratégies de chargement. Dans Hibernate3 les mécanismes pour choisir une " +"stratégie de chargement sont identiques que l'on ait une association vers un " +"objet simple ou vers une collection. " + +#. Tag: title +#, no-c-format +msgid "Tuning fetch strategies" +msgstr "Personnalisation des stratégies de chargement" + +#. Tag: para +#, no-c-format +msgid "" +"Select fetching (the default) is extremely vulnerable to N+1 selects " +"problems, so we might want to enable join fetching in the mapping document:" +msgstr "" +"Le chargement par select (mode par défaut) est très vulnérable au problème " +"du N+1 selects, ainsi vous souhaiterez peut-être activer le chargement par " +"jointure dans les fichiers de mappage :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>fetch</literal> strategy defined in the mapping document " +"affects:" +msgstr "" +"La stratégie de chargement définie à l'aide du mot <literal>fetch</literal> " +"dans les fichiers de mappage affecte :" + +#. Tag: para +#, no-c-format +msgid "retrieval via <literal>get()</literal> or <literal>load()</literal>" +msgstr "" +"La récupération via <literal>get()</literal> ou <literal>load()</literal>" + +#. Tag: para +#, no-c-format +msgid "retrieval that happens implicitly when an association is navigated" +msgstr "" +"La récupération implicite lorsque l'on navigue à travers une association" + +#. Tag: para +#, no-c-format +msgid "<literal>Criteria</literal> queries" +msgstr "Les requêtes par <literal>Criteria</literal>" + +#. Tag: para +#, no-c-format +msgid "HQL queries if <literal>subselect</literal> fetching is used" +msgstr "" +"Les requêtes HQL si l'on utilise le chargement par <literal>subselect</" +"literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Irrespective of the fetching strategy you use, the defined non-lazy graph is " +"guaranteed to be loaded into memory. This might, however, result in several " +"immediate selects being used to execute a particular HQL query." +msgstr "" +"Quelle que soit la stratégie de chargement que vous utilisez, la partie du " +"graphe d'objets, non-différée, sera chargée en mémoire. Cela peut mener à " +"l'exécution de plusieurs selects successifs pour une seule requête HQL. " + +#. Tag: para +#, no-c-format +msgid "" +"Usually, the mapping document is not used to customize fetching. Instead, we " +"keep the default behavior, and override it for a particular transaction, " +"using <literal>left join fetch</literal> in HQL. This tells Hibernate to " +"fetch the association eagerly in the first select, using an outer join. In " +"the <literal>Criteria</literal> query API, you would use " +"<literal>setFetchMode(FetchMode.JOIN)</literal>." +msgstr "" +"On n'utilise pas souvent les documents de mappage pour adapter le " +"chargement. En revanche, on conserve le comportement par défaut et on le " +"surcharge pour une transaction particulière en utilisant <literal>left join " +"fetch</literal> dans les requêtes HQL. Cela indique à Hibernate de charger " +"l'association de manière agressive lors du premier select en utilisant une " +"jointure externe. Dans la requête API <literal>Criteria</literal> vous " +"utiliserez la méthode <literal>setFetchMode(FetchMode.JOIN)</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"If you want to change the fetching strategy used by <literal>get()</literal> " +"or <literal>load()</literal>, you can use a <literal>Criteria</literal> " +"query. For example:" +msgstr "" +"S'il vous arrive de vouloir changer la stratégie de chargement utilisée par " +"utilisée par <literal>get()</literal> ou <literal>load()</literal>, vous " +"pouvez juste utiliser une requête de type <literal>Criteria</literal> comme " +"par exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"This is Hibernate's equivalent of what some ORM solutions call a \"fetch plan" +"\"." +msgstr "" +"Il s'agit de l'équivalent pour Hibernate de ce que d'autres outils de " +"mappage appellent un \"fetch plan\" ou \"plan de chargement\"." + +#. Tag: para +#, no-c-format +msgid "" +"A completely different approach to problems with N+1 selects is to use the " +"second-level cache." +msgstr "" +"Une autre manière complètement différente d'éviter le problème des N+1 " +"selects est d'utiliser le cache de second niveau. " + +#. Tag: title +#, no-c-format +msgid "Single-ended association proxies" +msgstr "Proxies pour des associations vers un seul objet " + +#. Tag: para +#, no-c-format +msgid "" +"Lazy fetching for collections is implemented using Hibernate's own " +"implementation of persistent collections. However, a different mechanism is " +"needed for lazy behavior in single-ended associations. The target entity of " +"the association must be proxied. Hibernate implements lazy initializing " +"proxies for persistent objects using runtime bytecode enhancement which is " +"accessed via the CGLIB library." +msgstr "" +"Le chargement différé des collections est implémenté par Hibernate qui " +"utilise ses propres implémentations pour des collections persistantes. Si " +"l'on veut un chargement différé pour des associations vers un seul objet, il " +"faut utiliser un autre mécanisme. L'entité qui est pointée par l'association " +"doit être masquée derrière un proxy. Hibernate implémente l'initialisation " +"différée des proxies sur des objets persistants via une mise à jour à chaud " +"du bytecode (à l'aide de l'excellente librairie CGLIB)." + +#. Tag: para +#, no-c-format +msgid "" +"At startup, Hibernate3 generates proxies by default for all persistent " +"classes and uses them to enable lazy fetching of <literal>many-to-one</" +"literal> and <literal>one-to-one</literal> associations." +msgstr "" +"Par défaut, Hibernate génère des proxies (au démarrage) pour toutes les " +"classes persistantes et les utilise pour activer le chargement différé des " +"associations <literal>many-to-one</literal> et <literal>one-to-one</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"The mapping file may declare an interface to use as the proxy interface for " +"that class, with the <literal>proxy</literal> attribute. By default, " +"Hibernate uses a subclass of the class. <emphasis>The proxied class must " +"implement a default constructor with at least package visibility. This " +"constructor is recommended for all persistent classes</emphasis>." +msgstr "" +"Le fichier de mappage peut déclarer une interface à utiliser comme interface " +"de proxy pour cette classe à l'aide de l'attribut <literal>proxy</literal>. " +"Par défaut Hibernate utilise une sous-classe de la classe persistante. " +"<emphasis>Il faut que les classes pour lesquelles on ajoute un proxy " +"implémentent un constructeur par défaut avec au minimum une visibilité de " +"paquetage. Ce constructeur est recommandé pour toutes les classes " +"persistantes !</emphasis>." + +#. Tag: para +#, no-c-format +msgid "" +"There are potential problems to note when extending this approach to " +"polymorphic classes.For example:" +msgstr "" +"Il y a quelques précautions à prendre lorsque l'on étend cette approche à " +"des classes polymorphiques, par exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"Firstly, instances of <literal>Cat</literal> will never be castable to " +"<literal>DomesticCat</literal>, even if the underlying instance is an " +"instance of <literal>DomesticCat</literal>:" +msgstr "" +"Tout d'abord, les instances de <literal>Cat</literal> ne pourront jamais " +"être \"castées\" en <literal>DomesticCat</literal>, même si l'instance sous-" +"jacente est une instance de <literal>DomesticCat</literal> :" + +#. Tag: para +#, no-c-format +msgid "Secondly, it is possible to break proxy <literal>==</literal>:" +msgstr "" +"Deuxièmement, il est possible de casser la notion de <literal>==</literal> " +"des proxies. " + +#. Tag: para +#, no-c-format +msgid "" +"However, the situation is not quite as bad as it looks. Even though we now " +"have two references to different proxy objects, the underlying instance will " +"still be the same object:" +msgstr "" +"Cette situation n'est pas si mauvaise qu'il n'y parait. Même si nous avons " +"deux références à deux objets proxies différents, l'instance sous-jacente " +"sera quand même le même objet :" + +#. Tag: para +#, no-c-format +msgid "" +"Third, you cannot use a CGLIB proxy for a <literal>final</literal> class or " +"a class with any <literal>final</literal> methods." +msgstr "" +"Troisièmement, vous ne pourrez pas utiliser un proxy CGLIB pour une classe " +"<literal>final</literal> ou pour une classe contenant la moindre méthode " +"<literal>final</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Finally, if your persistent object acquires any resources upon instantiation " +"(e.g. in initializers or default constructor), then those resources will " +"also be acquired by the proxy. The proxy class is an actual subclass of the " +"persistent class." +msgstr "" +"Enfin, si votre objet persistant obtient une quelconque ressource à " +"l'instanciation (par exemple dans les initialiseurs ou dans le constructeur " +"par défaut), alors ces ressources seront aussi obtenues par le proxy. La " +"classe proxy est en réalité une sous-classe de la classe persistante. " + +#. Tag: para +#, no-c-format +msgid "" +"These problems are all due to fundamental limitations in Java's single " +"inheritance model. To avoid these problems your persistent classes must each " +"implement an interface that declares its business methods. You should " +"specify these interfaces in the mapping file where <literal>CatImpl</" +"literal> implements the interface <literal>Cat</literal> and " +"<literal>DomesticCatImpl</literal> implements the interface " +"<literal>DomesticCat</literal>. For example:" +msgstr "" +"Ces problèmes sont tous dus aux limitations fondamentales du modèle " +"d'héritage unique de Java. Si vous souhaitez éviter ces problèmes, vos " +"classes persistantes doivent chacune implémenter une interface qui déclare " +"ses méthodes métier. Vous devriez alors spécifier ces interfaces dans le " +"fichier de mappage : <literal>CatImpl</literal> implémente l'interface " +"<literal>Cat</literal> et <literal>DomesticCatImpl</literal> implémente " +"l'interface <literal>DomesticCat</literal>. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"Then proxies for instances of <literal>Cat</literal> and " +"<literal>DomesticCat</literal> can be returned by <literal>load()</literal> " +"or <literal>iterate()</literal>." +msgstr "" +"Tout d'abord, les instances de <literal>Cat</literal> et de " +"<literal>DomesticCat</literal> peuvent être retournées par <literal>load()</" +"literal> ou par <literal>iterate()</literal>." + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Remarque" + +#. Tag: para +#, no-c-format +msgid "<literal>list()</literal> does not usually return proxies." +msgstr "<literal>list()</literal> ne retourne pas les proxies normalement." + +#. Tag: para +#, no-c-format +msgid "" +"Relationships are also lazily initialized. This means you must declare any " +"properties to be of type <literal>Cat</literal>, not <literal>CatImpl</" +"literal>." +msgstr "" +"Les relations sont aussi initialisées en différé. Ceci signifie que vous " +"devez déclarer chaque propriété comme étant de type <literal>Cat</literal>, " +"et non <literal>CatImpl</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"Certain operations do <emphasis>not</emphasis> require proxy initialization:" +msgstr "" +"Certaines opérations ne nécessitent <emphasis>pas</emphasis> " +"l'initialisation du proxy :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>equals()</literal>: if the persistent class does not override " +"<literal>equals()</literal>" +msgstr "" +"<literal>equals()</literal>, si la classe persistante ne surcharge pas " +"<literal>equals()</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>hashCode()</literal>: if the persistent class does not override " +"<literal>hashCode()</literal>" +msgstr "" +"<literal>hashCode()</literal>, si la classe persistante ne surcharge pas " +"<literal>hashCode()</literal> " + +#. Tag: para +#, no-c-format +msgid "The identifier getter method" +msgstr "La méthode getter de l'identifiant " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will detect persistent classes that override <literal>equals()</" +"literal> or <literal>hashCode()</literal>." +msgstr "" +"Hibernate détectera les classes qui surchargent <literal>equals()</literal> " +"ou <literal>hashCode()</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"By choosing <literal>lazy=\"no-proxy\"</literal> instead of the default " +"<literal>lazy=\"proxy\"</literal>, you can avoid problems associated with " +"typecasting. However, buildtime bytecode instrumentation is required, and " +"all operations will result in immediate proxy initialization." +msgstr "" +"Eh choisissant <literal>lazy=\"no-proxy\"</literal> au lieu de <literal>lazy=" +"\"proxy\"</literal> qui est la valeur par défaut, il est possible d'éviter " +"les problèmes liés au transtypage. Il faudra alors une instrumentation du " +"bytecode à la compilation et toutes les opérations résulteront immédiatement " +"en une initialisation du proxy. " + +#. Tag: title +#, no-c-format +msgid "Initializing collections and proxies" +msgstr "Initialisation des collections et des proxies" + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>LazyInitializationException</literal> will be thrown by Hibernate " +"if an uninitialized collection or proxy is accessed outside of the scope of " +"the <literal>Session</literal>, i.e., when the entity owning the collection " +"or having the reference to the proxy is in the detached state." +msgstr "" +"Une exception de type <literal>LazyInitializationException</literal> sera " +"renvoyée par Hibernate si une collection ou un proxy non initialisé est " +"accédé en dehors de la portée de la <literal>Session</literal>, par ex. " +"lorsque l'entité à laquelle appartient la collection ou qui a une référence " +"vers le proxy, est dans l'état \"détaché\". " + +#. Tag: para +#, no-c-format +msgid "" +"Sometimes a proxy or collection needs to be initialized before closing the " +"<literal>Session</literal>. You can force initialization by calling " +"<literal>cat.getSex()</literal> or <literal>cat.getKittens().size()</" +"literal>, for example. However, this can be confusing to readers of the code " +"and it is not convenient for generic code." +msgstr "" +"Parfois, nous devons nous assurer qu'un proxy ou une collection est " +"initialisé avant de fermer la <literal>Session</literal>. Bien sûr, nous " +"pouvons toujours forcer l'initialisation en appelant par exemple " +"<literal>cat.getSex()</literal> ou <literal>cat.getKittens().size()</" +"literal>. Mais ceci n'est pas très lisible pour les personnes parcourant le " +"code et n'est pas approprié pour le code générique. " + +#. Tag: para +#, no-c-format +msgid "" +"The static methods <literal>Hibernate.initialize()</literal> and " +"<literal>Hibernate.isInitialized()</literal>, provide the application with a " +"convenient way of working with lazily initialized collections or proxies. " +"<literal>Hibernate.initialize(cat)</literal> will force the initialization " +"of a proxy, <literal>cat</literal>, as long as its <literal>Session</" +"literal> is still open. <literal>Hibernate.initialize( cat.getKittens() )</" +"literal> has a similar effect for the collection of kittens." +msgstr "" +"Les méthodes statiques <literal>Hibernate.initialize()</literal> et " +"<literal>Hibernate.isInitialized()</literal> fournissent à l'application un " +"moyen de travailler avec des proxies ou des collections initialisés. " +"<literal>Hibernate.initialize(cat)</literal> forcera l'initialisation d'un " +"proxy de <literal>cat</literal>, si tant est que sa <literal>Session</" +"literal> est ouverte. <literal>Hibernate.initialize( cat.getKittens() )</" +"literal> a le même effet sur la collection kittens. " + +#. Tag: para +#, no-c-format +msgid "" +"Another option is to keep the <literal>Session</literal> open until all " +"required collections and proxies have been loaded. In some application " +"architectures, particularly where the code that accesses data using " +"Hibernate, and the code that uses it are in different application layers or " +"different physical processes, it can be a problem to ensure that the " +"<literal>Session</literal> is open when a collection is initialized. There " +"are two basic ways to deal with this issue:" +msgstr "" +"Une autre option est de conserver la <literal>Session</literal> ouverte " +"jusqu'à ce que toutes les collections et tous les proxies nécessaires aient " +"été chargés. Dans certaines architectures applicatives, particulièrement " +"celles ou le code d'accès aux données via Hiberante et le code qui utilise " +"ces données sont dans des couches applicatives différentes ou des processus " +"physiques différents, il sera alors difficile de garantir que la " +"<literal>Session</literal> est ouverte lorsqu'une collection est " +"initialisée. Il y a deux moyens de maîtriser ce problème : " + +#. Tag: para +#, no-c-format +msgid "" +"In a web-based application, a servlet filter can be used to close the " +"<literal>Session</literal> only at the end of a user request, once the " +"rendering of the view is complete (the <emphasis>Open Session in View</" +"emphasis> pattern). Of course, this places heavy demands on the correctness " +"of the exception handling of your application infrastructure. It is vitally " +"important that the <literal>Session</literal> is closed and the transaction " +"ended before returning to the user, even when an exception occurs during " +"rendering of the view. See the Hibernate Wiki for examples of this \"Open " +"Session in View\" pattern." +msgstr "" +"Dans une application web, un filtre de servlet peut être utilisé pour fermer " +"la <literal>Session</literal> uniquement lorsque la requête a été " +"entièrement traitée, lorsque le rendu de la vue est fini (il s'agit du " +"modèle <emphasis>Vue de la session ouverte</emphasis>). Bien sûr, cela " +"demande plus d'attention à la bonne gestion des exceptions de l'application. " +"Il est d'une importance vitale que la <literal>Session</literal> soit fermée " +"et la transaction terminée avant que l'on rende la main à l'utilisateur même " +"si une exception survient durant le traitement de la vue. Voir le wiki " +"Hibernate pour des exemples sur le modèle \"Open Session in View\". " + +#. Tag: para +#, no-c-format +msgid "" +"In an application with a separate business tier, the business logic must " +"\"prepare\" all collections that the web tier needs before returning. This " +"means that the business tier should load all the data and return all the " +"data already initialized to the presentation/web tier that is required for a " +"particular use case. Usually, the application calls <literal>Hibernate." +"initialize()</literal> for each collection that will be needed in the web " +"tier (this call must occur before the session is closed) or retrieves the " +"collection eagerly using a Hibernate query with a <literal>FETCH</literal> " +"clause or a <literal>FetchMode.JOIN</literal> in <literal>Criteria</" +"literal>. This is usually easier if you adopt the <emphasis>Command</" +"emphasis> pattern instead of a <emphasis>Session Facade</emphasis>." +msgstr "" +"Dans une application avec une couche métier multiniveaux séparée, la couche " +"contenant la logique métier doit \"préparer\" toutes les collections qui " +"seront nécessaires à la couche web multiniveaux avant de retourner les " +"données. Cela signifie que la couche métier doit charger toutes les données " +"et retourner toutes les données déjà initialisées à la couche de " +"présentation/web pour un cas d'utilisation donné. En général l'application " +"appelle la méthode <literal>Hibernate.initialize()</literal> pour chaque " +"collection nécessaire dans la couche web (cet appel doit être fait avant la " +"fermeture de la session) ou bien récupère les collections de manière " +"agressive à l'aide d'une requête HQL avec une clause <literal>FETCH</" +"literal> ou à l'aide du mode <literal>FetchMode.JOIN</literal> pour une " +"requête de type <literal>Criteria</literal>. Cela est en général plus facile " +"si vous utilisez le modèle <emphasis>Command</emphasis> plutôt que " +"<emphasis>Session Facade</emphasis>. " + +#. Tag: para +#, no-c-format +msgid "" +"You can also attach a previously loaded object to a new <literal>Session</" +"literal> with <literal>merge()</literal> or <literal>lock()</literal> before " +"accessing uninitialized collections or other proxies. Hibernate does not, " +"and certainly <emphasis>should</emphasis> not, do this automatically since " +"it would introduce impromptu transaction semantics." +msgstr "" +"Vous pouvez également attacher à une <literal>Session</literal> un objet " +"chargé au préalable à l'aide des méthodes <literal>merge()</literal> ou " +"<literal>lock()</literal> avant d'accéder aux collections (ou aux proxies) " +"non initialisés. Non, Hibernate ne fait pas, et ne doit pas faire cela " +"automatiquement car cela pourrait introduire une sémantique transactionnelle " +"ad hoc. " + +#. Tag: para +#, no-c-format +msgid "" +"Sometimes you do not want to initialize a large collection, but still need " +"some information about it, like its size, for example, or a subset of the " +"data." +msgstr "" +"Parfois, vous ne voulez pas initialiser une grande collection mais vous avez " +"quand même besoin d'informations sur elle (comme sa taille) ou un sous-" +"ensemble de ses données." + +#. Tag: para +#, no-c-format +msgid "" +"You can use a collection filter to get the size of a collection without " +"initializing it:" +msgstr "" +"Vous pouvez utiliser un filtre de collection pour récupérer sa taille sans " +"l'initialiser :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>createFilter()</literal> method is also used to efficiently " +"retrieve subsets of a collection without needing to initialize the whole " +"collection:" +msgstr "" +"La méthode <literal>createFilter()</literal> est également utilisée pour " +"récupérer efficacement des sous-ensembles d'une collection sans avoir besoin " +"de l'initialiser dans son ensemble :" + +#. Tag: title +#, no-c-format +msgid "Using batch fetching" +msgstr "Utiliser le chargement par lot" + +#. Tag: para +#, no-c-format +msgid "" +"Using batch fetching, Hibernate can load several uninitialized proxies if " +"one proxy is accessed. Batch fetching is an optimization of the lazy select " +"fetching strategy. There are two ways you can configure batch fetching: on " +"the class level and the collection level." +msgstr "" +"Pour améliorer les performances, Hibernate peut utiliser le chargement par " +"lot ce qui veut dire que Hibernate peut charger plusieurs proxies (ou " +"collections) non initialisés en une seule requête lorsque l'on accède à l'un " +"de ces proxies. Le chargement par lot est une optimisation intimement liée à " +"la stratégie de chargement en différé par select. Il y a deux moyens " +"d'activer le chargement par lot : au niveau de la classe et au niveau de la " +"collection." + +#. Tag: para +#, no-c-format +msgid "" +"Batch fetching for classes/entities is easier to understand. Consider the " +"following example: at runtime you have 25 <literal>Cat</literal> instances " +"loaded in a <literal>Session</literal>, and each <literal>Cat</literal> has " +"a reference to its <literal>owner</literal>, a <literal>Person</literal>. " +"The <literal>Person</literal> class is mapped with a proxy, <literal>lazy=" +"\"true\"</literal>. If you now iterate through all cats and call " +"<literal>getOwner()</literal> on each, Hibernate will, by default, execute " +"25 <literal>SELECT</literal> statements to retrieve the proxied owners. You " +"can tune this behavior by specifying a <literal>batch-size</literal> in the " +"mapping of <literal>Person</literal>:" +msgstr "" +"Le chargement par lot pour les classes/entités est plus simple à comprendre. " +"Imaginez que vous ayez la situation suivante à l'exécution : vous avez 25 " +"instances de <literal>Cat</literal> chargées dans une <literal>Session</" +"literal>, chaque <literal>Cat</literal> a une référence à son " +"<literal>owner</literal>, une <literal>Person</literal>. La classe " +"<literal>Person</literal> est mappée avec un proxy, <literal>lazy=\"true\"</" +"literal>. Si vous itérez sur tous les cats et appelez <literal>getOwner()</" +"literal> sur chacun d'eux, Hibernate exécutera par défaut 25 " +"<literal>SELECT</literal>, pour charger les owners (initialiser le proxy). " +"Vous pouvez paramétrer ce comportement en spécifiant une <literal>batch-" +"size</literal> (taille du lot) dans le mappage de <literal>Person</" +"literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will now execute only three queries: the pattern is 10, 10, 5." +msgstr "" +"Hibernate exécutera désormais trois requêtes, en chargeant respectivement " +"10, 10, et 5 entités. " + +#. Tag: para +#, no-c-format +msgid "" +"You can also enable batch fetching of collections. For example, if each " +"<literal>Person</literal> has a lazy collection of <literal>Cat</literal>s, " +"and 10 persons are currently loaded in the <literal>Session</literal>, " +"iterating through all persons will generate 10 <literal>SELECT</literal>s, " +"one for every call to <literal>getCats()</literal>. If you enable batch " +"fetching for the <literal>cats</literal> collection in the mapping of " +"<literal>Person</literal>, Hibernate can pre-fetch collections:" +msgstr "" +"Vous pouvez aussi activer le chargement par lot pour les collections. Par " +"exemple, si chaque <literal>Person</literal> a une collection chargée en " +"différé des <literal>Cat</literal>s, et que 10 personnes sont actuellement " +"chargées dans la <literal>Session</literal>, itérer sur toutes les persons " +"générera 10 <literal>SELECT</literal> s, un pour chaque appel de " +"<literal>getCats()</literal>. Si vous activez le chargement par lot pour la " +"collection <literal>cats</literal> dans le mappage de <literal>Person</" +"literal>, Hibernate pourra précharger les collections :" + +#. Tag: para +#, no-c-format +msgid "" +"With a <literal>batch-size</literal> of 3, Hibernate will load 3, 3, 3, 1 " +"collections in four <literal>SELECT</literal>s. Again, the value of the " +"attribute depends on the expected number of uninitialized collections in a " +"particular <literal>Session</literal>." +msgstr "" +"Avec une taille de lot <literal>batch-size</literal> de 8, Hibernate " +"chargera respectivement des collections 3, 3, 3, et 1 en quatre " +"<literal>SELECT</literal> s. Encore une fois, la valeur de l'attribut dépend " +"du nombre de collections non initialisées dans une <literal>Session</" +"literal> particulière. " + +#. Tag: para +#, no-c-format +msgid "" +"Batch fetching of collections is particularly useful if you have a nested " +"tree of items, i.e. the typical bill-of-materials pattern. However, a " +"<emphasis>nested set</emphasis> or a <emphasis>materialized path</emphasis> " +"might be a better option for read-mostly trees." +msgstr "" +"Le chargement par lot de collections est particulièrement utile si vous avez " +"une arborescence imbriquée d'éléments, c'est-à-dire le le schéma facture de " +"matériels typique. (Bien qu'un <emphasis>sous ensemble</emphasis> ou un " +"<emphasis>chemin matérialisé</emphasis> soit probablement une meilleure " +"option pour des arbres principalement en lecture.) " + +#. Tag: title +#, no-c-format +msgid "Using subselect fetching" +msgstr "Utilisation du chargement par sous select" + +#. Tag: para +#, no-c-format +msgid "" +"If one lazy collection or single-valued proxy has to be fetched, Hibernate " +"will load all of them, re-running the original query in a subselect. This " +"works in the same way as batch-fetching but without the piecemeal loading." +msgstr "" +"Si une collection en différé ou un proxy vers un objet doit être chargée, " +"Hibernate va tous les charger en ré-exécutant la requête originale dans un " +"sous select. Cela fonctionne de la même manière que le chargement par lot " +"sans la possibilité de fragmenter le chargement." + +#. Tag: title +#, fuzzy, no-c-format +msgid "Fetch profiles" +msgstr "Stratégies de chargement" + +#. Tag: para +#, no-c-format +msgid "" +"Another way to affect the fetching strategy for loading associated objects " +"is through something called a fetch profile, which is a named configuration " +"associated with the <interfacename>org.hibernate.SessionFactory</" +"interfacename> but enabled, by name, on the <interfacename>org.hibernate." +"Session</interfacename>. Once enabled on a <interfacename>org.hibernate." +"Session</interfacename>, the fetch profile wull be in affect for that " +"<interfacename>org.hibernate.Session</interfacename> until it is explicitly " +"disabled." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"So what does that mean? Well lets explain that by way of an example. Say we " +"have the following mappings:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Now normally when you get a reference to a particular customer, that " +"customer's set of orders will be lazy meaning we will not yet have loaded " +"those orders from the database. Normally this is a good thing. Now lets say " +"that you have a certain use case where it is more efficient to load the " +"customer and their orders together. One way certainly is to use \"dynamic " +"fetching\" strategies via an HQL or criteria queries. But another option is " +"to use a fetch profile to achieve that. Just add the following to your " +"mapping:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "or even:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Now the following code will actually load both the customer <emphasis>and " +"their orders</emphasis>:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Currently only join style fetch profiles are supported, but they plan is to " +"support additional styles. See <ulink url=\"http://opensource.atlassian.com/" +"projects/hibernate/browse/HHH-3414\">HHH-3414</ulink> for details." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Using lazy property fetching" +msgstr "Utiliser le chargement en différé des propriétés" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 supports the lazy fetching of individual properties. This " +"optimization technique is also known as <emphasis>fetch groups</emphasis>. " +"Please note that this is mostly a marketing feature; optimizing row reads is " +"much more important than optimization of column reads. However, only loading " +"some properties of a class could be useful in extreme cases. For example, " +"when legacy tables have hundreds of columns and the data model cannot be " +"improved." +msgstr "" +"Hibernate3 supporte le chargement en différé de propriétés individuelles. La " +"technique d'optimisation est également connue sous le nom de <emphasis>fetch " +"groups</emphasis> (groupes de chargement). Il faut noter qu'il s'agit " +"principalement d'une fonctionnalité marketing car en pratique l'optimisation " +"de la lecture d'un enregistrement est beaucoup plus importante que " +"l'optimisation de la lecture d'une colonne. Cependant, la restriction du " +"chargement à certaines colonnes peut être pratique dans des cas extrêmes, " +"lorsque des tables \"legacy\" possèdent des centaines de colonnes et que le " +"modèle de données ne peut pas être amélioré." + +#. Tag: para +#, no-c-format +msgid "" +"To enable lazy property loading, set the <literal>lazy</literal> attribute " +"on your particular property mappings:" +msgstr "" +"Pour activer le chargement en différé d'une propriété, il faut mettre " +"l'attribut <literal>lazy</literal> sur une propriété particulière du " +"mappage :" + +#. Tag: para +#, no-c-format +msgid "" +"Lazy property loading requires buildtime bytecode instrumentation. If your " +"persistent classes are not enhanced, Hibernate will ignore lazy property " +"settings and return to immediate fetching." +msgstr "" +"Le chargement en différé des propriétés requiert une instrumentation du " +"bytecode lors de la compilation ! Si les classes persistantes ne sont pas " +"instrumentées, Hibernate ignorera de manière silencieuse le mode en différé " +"et retombera dans le mode de chargement immédiat. " + +#. Tag: para +#, no-c-format +msgid "For bytecode instrumentation, use the following Ant task:" +msgstr "" +"Pour l'instrumentation du bytecode vous pouvez utiliser la tâche Ant " +"suivante :" + +#. Tag: para +#, no-c-format +msgid "" +"A different way of avoiding unnecessary column reads, at least for read-only " +"transactions, is to use the projection features of HQL or Criteria queries. " +"This avoids the need for buildtime bytecode processing and is certainly a " +"preferred solution." +msgstr "" +"Une autre façon (meilleure ?) pour éviter de lire plus de colonnes que " +"nécessaire au moins pour des transactions en lecture seule est d'utiliser " +"les fonctionnalités de projection des requêtes HQL ou Criteria. Cela évite " +"de devoir instrumenter le bytecode à la compilation et est certainement une " +"solution préférable. " + +#. Tag: para +#, no-c-format +msgid "" +"You can force the usual eager fetching of properties using <literal>fetch " +"all properties</literal> in HQL." +msgstr "" +"Vous pouvez forcer le mode de chargement agressif des propriétés en " +"utilisant <literal>fetch all properties</literal> dans les requêtes HQL. " + +#. Tag: title +#, no-c-format +msgid "The Second Level Cache" +msgstr "Le cache de second niveau" + +#. Tag: para +#, no-c-format +msgid "" +"A Hibernate <literal>Session</literal> is a transaction-level cache of " +"persistent data. It is possible to configure a cluster or JVM-level " +"(<literal>SessionFactory</literal>-level) cache on a class-by-class and " +"collection-by-collection basis. You can even plug in a clustered cache. Be " +"aware that caches are not aware of changes made to the persistent store by " +"another application. They can, however, be configured to regularly expire " +"cached data." +msgstr "" +"Une <literal>Session</literal> Hibernate est un cache de niveau " +"transactionnel de données persistantes. Il est possible de configurer un " +"cache de cluster ou de JVM (de niveau <literal>SessionFactory</literal>) " +"défini classe par classe et collection par collection. Vous pouvez même " +"utiliser votre choix de cache en implémentant le fournisseur associé. Faites " +"attention, les caches ne sont jamais avertis des modifications faites dans " +"la base de données par d'autres applications (ils peuvent cependant être " +"configurés pour régulièrement expirer les données en cache). " + +#. Tag: para +#, no-c-format +msgid "" +"You have the option to tell Hibernate which caching implementation to use by " +"specifying the name of a class that implements <literal>org.hibernate.cache." +"CacheProvider</literal> using the property <literal>hibernate.cache." +"provider_class</literal>. Hibernate is bundled with a number of built-in " +"integrations with the open-source cache providers that are listed below. You " +"can also implement your own and plug it in as outlined above. Note that " +"versions prior to 3.2 use EhCache as the default cache provider." +msgstr "" +"Vous pouvez choisir une autre implémentation en spécifiant le nom de la " +"classe qui implémente <literal>org.hibernate.cache.CacheProvider</literal> " +"en utilisant la propriété <literal>hibernate.cache.provider_class</literal>. " +"Hibernate est accompagné de plusieurs intégrations imbriquées avec des " +"fournisseurs de cache open-source (listés ci-dessous) ; par ailleurs vous " +"pouvez implémenter votre propre fournisseur et le brancher comme indiqué ci-" +"dessus. Notez que les versions antérieures à 3.2, utilisaient par défaut le " +"EhCache comme le fournisseur de cache par défaut, ce qui n'est plus le cas. " + +#. Tag: title +#, no-c-format +msgid "Cache Providers" +msgstr "Fournisseurs de cache" + +#. Tag: entry +#, no-c-format +msgid "Cache" +msgstr "Cache" + +#. Tag: entry +#, no-c-format +msgid "Provider class" +msgstr "Classe pourvoyeuse" + +#. Tag: entry +#, no-c-format +msgid "Type" +msgstr "Type" + +#. Tag: entry +#, no-c-format +msgid "Cluster Safe" +msgstr "Cluster sécurisé" + +#. Tag: entry +#, no-c-format +msgid "Query Cache Supported" +msgstr "Cache de requêtes supporté" + +#. Tag: entry +#, no-c-format +msgid "Hashtable (not intended for production use)" +msgstr "Table de hachage (ne pas utiliser en production)" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.HashtableCacheProvider</literal>" +msgstr "<literal>org.hibernate.cache.HashtableCacheProvider</literal>" + +#. Tag: entry +#, no-c-format +msgid "memory" +msgstr "mémoire" + +#. Tag: entry +#, no-c-format +msgid "yes" +msgstr "oui" + +#. Tag: entry +#, no-c-format +msgid "EHCache" +msgstr "EHCache" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.EhCacheProvider</literal>" +msgstr "<literal>org.hibernate.cache.EhCacheProvider</literal>" + +#. Tag: entry +#, no-c-format +msgid "memory, disk" +msgstr "mémoire, disque" + +#. Tag: entry +#, no-c-format +msgid "OSCache" +msgstr "OSCache" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.OSCacheProvider</literal>" +msgstr "<literal>org.hibernate.cache.OSCacheProvider</literal>" + +#. Tag: entry +#, no-c-format +msgid "SwarmCache" +msgstr "SwarmCache" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.SwarmCacheProvider</literal>" +msgstr "<literal>org.hibernate.cache.SwarmCacheProvider</literal>" + +#. Tag: entry +#, no-c-format +msgid "clustered (ip multicast)" +msgstr "en cluster (multicast ip)" + +#. Tag: entry +#, no-c-format +msgid "yes (clustered invalidation)" +msgstr "oui (invalidation de cluster)" + +#. Tag: entry +#, no-c-format +msgid "JBoss Cache 1.x" +msgstr "JBoss Cache 1.x" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.TreeCacheProvider</literal>" +msgstr " org.hibernate.cache.TreeCacheProvider" + +#. Tag: entry +#, no-c-format +msgid "clustered (ip multicast), transactional" +msgstr "en cluster (multicast ip), transactionnel" + +#. Tag: entry +#, no-c-format +msgid "yes (replication)" +msgstr "oui (réplication)" + +#. Tag: entry +#, no-c-format +msgid "yes (clock sync req.)" +msgstr "oui (horloge sync. nécessaire)" + +#. Tag: entry +#, no-c-format +msgid "JBoss Cache 2" +msgstr "JBoss Cache 2" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>org.hibernate.cache.jbc.JBossCacheRegionFactory</literal>" +msgstr "<literal>org.hibernate.cache.jbc2.JBossCacheRegionFactory</literal>" + +#. Tag: entry +#, no-c-format +msgid "yes (replication or invalidation)" +msgstr "oui (replication ou invalidation)" + +#. Tag: title +#, no-c-format +msgid "Cache mappings" +msgstr "Mappages de Cache" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;cache&gt;</literal> element of a class or collection " +"mapping has the following form:" +msgstr "" +"L'élément <literal>&lt;cache&gt;</literal> d'une classe ou d'une collection " +"a la forme suivante :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>usage</literal> (required) specifies the caching strategy: " +"<literal>transactional</literal>, <literal>read-write</literal>, " +"<literal>nonstrict-read-write</literal> or <literal>read-only</literal>" +msgstr "" +"<literal>usage</literal> (requis) spécifie la stratégie de cache : " +"<literal>transactionel</literal>, <literal>lecture-écriture</literal>, " +"<literal>lecture-écriture non stricte</literal> ou <literal>lecture seule</" +"literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>region</literal> (optional: defaults to the class or collection " +"role name): specifies the name of the second level cache region" +msgstr "" +"<literal>region</literal> (optionnel, par défaut il s'agit du nom de la " +"classe ou du nom de rôle de la collection) : spécifie le nom de la région du " +"cache de second niveau" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>include</literal> (optional: defaults to <literal>all</literal>) " +"<literal>non-lazy</literal>: specifies that properties of the entity mapped " +"with <literal>lazy=\"true\"</literal> cannot be cached when attribute-level " +"lazy fetching is enabled" +msgstr "" +"<literal>include</literal> (optionnel, par défaut <literal>all</literal>) " +"<literal>non-lazy</literal> : spécifie que les propriétés des entités " +"mappées avec <literal>lazy=\"true\"</literal> ne doivent pas être mises en " +"cache lorsque le chargement en différé des attributs est activé." + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, you can specify <literal>&lt;class-cache&gt;</literal> and " +"<literal>&lt;collection-cache&gt;</literal> elements in <literal>hibernate." +"cfg.xml</literal>." +msgstr "" +"Alternativement (voir préférentiellement), vous pouvez spécifier les " +"éléments <literal>&lt;class-cache&gt;</literal> et <literal>&lt;collection-" +"cache&gt;</literal> dans <literal>hibernate.cfg.xml</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>usage</literal> attribute specifies a <emphasis>cache " +"concurrency strategy</emphasis>." +msgstr "" +"L'attribut <literal>usage</literal> spécifie une <emphasis>stratégie de " +"concurrence d'accès au cache</emphasis>." + +#. Tag: title +#, no-c-format +msgid "Strategy: read only" +msgstr "Stratégie : lecture seule" + +#. Tag: para +#, no-c-format +msgid "" +"If your application needs to read, but not modify, instances of a persistent " +"class, a <literal>read-only</literal> cache can be used. This is the " +"simplest and optimal performing strategy. It is even safe for use in a " +"cluster." +msgstr "" +"Si votre application a besoin de lire mais ne modifie jamais les instances " +"d'une classe, un cache <literal>read-only</literal> peut être utilisé. C'est " +"la stratégie la plus simple et la plus performante. Elle est même " +"parfaitement sûre dans un cluster. " + +#. Tag: title +#, no-c-format +msgid "Strategy: read/write" +msgstr "Stratégie : lecture/écriture" + +#. Tag: para +#, no-c-format +msgid "" +"If the application needs to update data, a <literal>read-write</literal> " +"cache might be appropriate. This cache strategy should never be used if " +"serializable transaction isolation level is required. If the cache is used " +"in a JTA environment, you must specify the property <literal>hibernate." +"transaction.manager_lookup_class</literal> and naming a strategy for " +"obtaining the JTA <literal>TransactionManager</literal>. In other " +"environments, you should ensure that the transaction is completed when " +"<literal>Session.close()</literal> or <literal>Session.disconnect()</" +"literal> is called. If you want to use this strategy in a cluster, you " +"should ensure that the underlying cache implementation supports locking. The " +"built-in cache providers <emphasis>do not</emphasis> support locking." +msgstr "" +"Si l'application a besoin de mettre à jour des données, un cache " +"<literal>read-write</literal> peut être approprié. Cette stratégie ne " +"devrait jamais être utilisée si votre application nécessite un niveau " +"d'isolation transactionnelle sérialisable. Si le cache est utilisé dans un " +"environnement JTA, vous devez spécifier la propriété <literal>hibernate." +"transaction.manager_lookup_class</literal>, fournissant une stratégie pour " +"obtenir le JTA <literal>TransactionManager</literal>. Dans d'autres " +"environnements, vous devriez vous assurer que la transation est terminée à " +"l'appel de <literal>Session.close()</literal> ou <literal>Session.disconnect" +"()</literal>. Si vous souhaitez utiliser cette stratégie dans un cluster, " +"vous devriez vous assurer que l'implémentation de cache utilisée supporte le " +"verrouillage, ce que ne font <emphasis>pas</emphasis> les pourvoyeurs caches " +"fournis. " + +#. Tag: title +#, no-c-format +msgid "Strategy: nonstrict read/write" +msgstr "Stratégie : lecture/écriture non stricte" + +#. Tag: para +#, no-c-format +msgid "" +"If the application only occasionally needs to update data (i.e. if it is " +"extremely unlikely that two transactions would try to update the same item " +"simultaneously), and strict transaction isolation is not required, a " +"<literal>nonstrict-read-write</literal> cache might be appropriate. If the " +"cache is used in a JTA environment, you must specify <literal>hibernate." +"transaction.manager_lookup_class</literal>. In other environments, you " +"should ensure that the transaction is completed when <literal>Session.close()" +"</literal> or <literal>Session.disconnect()</literal> is called." +msgstr "" +"Si l'application a besoin de mettre à jour les données de manière " +"occasionnelle (il est très peu probable que deux transactions essaient de " +"mettre à jour le même élément simultanément) et si une isolation " +"transactionnelle stricte n'est pas nécessaire, un cache <literal>nonstrict-" +"read-write</literal> peut être approprié. Si le cache est utilisé dans un " +"environnement JTA, vous devez spécifier <literal>hibernate.transaction." +"manager_lookup_class</literal>. Dans d'autres environnements, vous devriez " +"vous assurer que la transation est terminée à l'appel de <literal>Session." +"close()</literal> ou <literal>Session.disconnect()</literal>." + +#. Tag: title +#, no-c-format +msgid "Strategy: transactional" +msgstr "Stratégie : transactionelle" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>transactional</literal> cache strategy provides support for " +"fully transactional cache providers such as JBoss TreeCache. Such a cache " +"can only be used in a JTA environment and you must specify " +"<literal>hibernate.transaction.manager_lookup_class</literal>." +msgstr "" +"La stratégie de cache <literal>transactional</literal> supporte un cache " +"complètement transactionnel comme, par exemple, JBoss TreeCache. Un tel " +"cache ne peut être utilisé que dans un environnement JTA et vous devez " +"spécifier <literal>hibernate.transaction.manager_lookup_class</literal>. " + +#. Tag: title +#, no-c-format +msgid "Cache-provider/concurrency-strategy compatibility" +msgstr "Support de stratégie de concurrence du fournisseur-cache" + +#. Tag: para +#, no-c-format +msgid "" +"None of the cache providers support all of the cache concurrency strategies." +msgstr "" +"Aucun des caches livrés ne supporte toutes les stratégies de concurrence. Le " +"tableau suivant montre quels caches sont compatibles avec quelles stratégies " +"de concurrence. " + +#. Tag: para +#, no-c-format +msgid "" +"The following table shows which providers are compatible with which " +"concurrency strategies." +msgstr "" +"Aucun des caches livrés ne supporte toutes les stratégies de concurrence. Le " +"tableau suivant montre quels caches sont compatibles avec quelles stratégies " +"de concurrence. " + +#. Tag: title +#, no-c-format +msgid "Cache Concurrency Strategy Support" +msgstr "Support de stratégie de concurrence du cache" + +#. Tag: entry +#, no-c-format +msgid "read-only" +msgstr "read-only (lecture seule)" + +#. Tag: entry +#, no-c-format +msgid "nonstrict-read-write" +msgstr "nonstrict-read-write (lecture-écriture non stricte)" + +#. Tag: entry +#, no-c-format +msgid "read-write" +msgstr "read-write (lecture-écriture)" + +#. Tag: entry +#, no-c-format +msgid "transactional" +msgstr "transactional (transactionnel)" + +#. Tag: title +#, no-c-format +msgid "Managing the caches" +msgstr "Gérer les caches" + +#. Tag: para +#, no-c-format +msgid "" +"Whenever you pass an object to <literal>save()</literal>, <literal>update()</" +"literal> or <literal>saveOrUpdate()</literal>, and whenever you retrieve an " +"object using <literal>load()</literal>, <literal>get()</literal>, " +"<literal>list()</literal>, <literal>iterate()</literal> or <literal>scroll()" +"</literal>, that object is added to the internal cache of the " +"<literal>Session</literal>." +msgstr "" +"A chaque fois que vous passez un objet à la méthode <literal>save()</" +"literal>, <literal>update()</literal> ou <literal>saveOrUpdate()</literal> " +"et à chaque fois que vous récupérez un objet avec <literal>load()</literal>, " +"<literal>get()</literal>, <literal>list()</literal>, <literal>iterate()</" +"literal> ou <literal>scroll()</literal>, cet objet est ajouté au cache " +"interne de la <literal>Session</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"When <literal>flush()</literal> is subsequently called, the state of that " +"object will be synchronized with the database. If you do not want this " +"synchronization to occur, or if you are processing a huge number of objects " +"and need to manage memory efficiently, the <literal>evict()</literal> method " +"can be used to remove the object and its collections from the first-level " +"cache." +msgstr "" +"Lorsqu'il y a un appel à la méthode <literal>flush()</literal>, l'état de " +"cet objet va être synchronisé avec la base de données. Si vous ne voulez pas " +"que cette synchronisation ait lieu ou si vous traitez un grand nombre " +"d'objets et que vous avez besoin de gérer la mémoire de manière efficace, " +"vous pouvez utiliser la méthode <literal>evict()</literal> pour supprimer " +"l'objet et ses collections dépendantes du cache de premier niveau de la " +"session. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>Session</literal> also provides a <literal>contains()</literal> " +"method to determine if an instance belongs to the session cache." +msgstr "" +"La <literal>Session</literal> fournit également une méthode <literal>contains" +"()</literal> pour déterminer si une instance appartient au cache de la " +"session. " + +#. Tag: para +#, no-c-format +msgid "" +"To evict all objects from the session cache, call <literal>Session.clear()</" +"literal>" +msgstr "" +"Pour retirer tous les objets du cache session, appelez <literal>Session.clear" +"()</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"For the second-level cache, there are methods defined on " +"<literal>SessionFactory</literal> for evicting the cached state of an " +"instance, entire class, collection instance or entire collection role." +msgstr "" +"Pour le cache de second niveau, il existe des méthodes définies dans " +"<literal>SessionFactory</literal> pour retirer du cache d'une instance, de " +"la classe entière, d'une instance de collection ou du rôle entier d'une " +"collection." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>CacheMode</literal> controls how a particular session interacts " +"with the second-level cache:" +msgstr "" +"Le <literal>CacheMode</literal> contrôle la manière dont une session " +"particulière interagit avec le cache de second niveau :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>CacheMode.NORMAL</literal>: will read items from and write items to " +"the second-level cache" +msgstr "" +"<literal>CacheMode.NORMAL</literal> - lit et écrit les articles dans le " +"cache de second niveau " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>CacheMode.GET</literal>: will read items from the second-level " +"cache. Do not write to the second-level cache except when updating data" +msgstr "" +"<literal>CacheMode.GET</literal> - lit les articles du cache de second " +"niveau mais ne les écrit pas sauf dans le cas d'une mise à jour des données " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>CacheMode.PUT</literal>: will write items to the second-level " +"cache. Do not read from the second-level cache" +msgstr "" +"<literal>CacheMode.PUT</literal> - écrit les articles dans le cache de " +"second niveau mais ne les lit pas dans le cache de second niveau " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>CacheMode.REFRESH</literal>: will write items to the second-level " +"cache. Do not read from the second-level cache. Bypass the effect of " +"<literal>hibernate.cache.use_minimal_puts</literal> forcing a refresh of the " +"second-level cache for all items read from the database" +msgstr "" +"<literal>CacheMode.REFRESH</literal> - écrit les articles dans le cache de " +"second niveau mais ne les lit pas dans le cache de second niveau, outrepasse " +"l'effet de <literal>hibernate.cache.use_minimal_puts</literal>, en forçant " +"un rafraîchissement du cache de second niveau pour chaque article lu dans la " +"base de données. " + +#. Tag: para +#, no-c-format +msgid "" +"To browse the contents of a second-level or query cache region, use the " +"<literal>Statistics</literal> API:" +msgstr "" +"Pour parcourir le contenu du cache de second niveau ou la région du cache " +"dédiée aux requêtes, vous pouvez utiliser l'API <literal>Statistics</" +"literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"You will need to enable statistics and, optionally, force Hibernate to keep " +"the cache entries in a more readable format:" +msgstr "" +"Vous devez pour cela activer les statistiques et optionnellement forcer " +"Hibernate à conserver les entrées dans le cache sous un format plus " +"compréhensible pour l'utilisateur : " + +#. Tag: title +#, no-c-format +msgid "The Query Cache" +msgstr "Le cache de requêtes" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Query result sets can also be cached. This is only useful for queries that " +"are run frequently with the same parameters." +msgstr "" +"Les résultats d'une requête peuvent aussi être placés en cache. Ceci n'est " +"utile que pour les requêtes qui sont exécutées avec les mêmes paramètres. " +"Pour utiliser le cache de requêtes, vous devez d'abord l'activer : " + +#. Tag: title +#, no-c-format +msgid "Enabling query caching" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Caching of query results introduces some overhead in terms of your " +"applications normal transactional processing. For example, if you cache " +"results of a query against Person Hibernate will need to keep track of when " +"those results should be invalidated because changes have been committed " +"against Person. That, coupled with the fact that most applications simply " +"gain no benefit from caching query results, leads Hibernate to disable " +"caching of query results by default. To use query caching, you will first " +"need to enable the query cache:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "This setting creates two new cache regions:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"<classname>org.hibernate.cache.StandardQueryCache</classname>, holding the " +"cached query results" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"<classname>org.hibernate.cache.UpdateTimestampsCache</classname>, holding " +"timestamps of the most recent updates to queryable tables. These are used to " +"validate the results as they are served from the query cache." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"If you configure your underlying cache implementation to use expiry or " +"timeouts is is very important that the cache timeout of the underlying cache " +"region for the UpdateTimestampsCache be set to a higher value than the " +"timeouts of any of the query caches. In fact, we recommend that the the " +"UpdateTimestampsCache region not be configured for expiry at all. Note, in " +"particular, that an LRU cache expiry policy is never appropriate." +msgstr "" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"As mentioned above, most queries do not benefit from caching or their " +"results. So by default, individual queries are not cached even after " +"enabling query caching. To enable results caching for a particular query, " +"call <literal>org.hibernate.Query.setCacheable(true)</literal>. This call " +"allows the query to look for existing cache results or add its results to " +"the cache when it is executed." +msgstr "" +"La plupart des requêtes ne tirent pas avantage du cache, donc par défaut les " +"requêtes ne sont pas mises en cache. Pour activer le cache, appelez " +"<literal>Query.setCacheable(true)</literal>. Cet appel permet de vérifier si " +"les résultats sont en cache ou non, voire d'ajouter ces résultats quand la " +"requête est exécutée. " + +#. Tag: para +#, no-c-format +msgid "" +"The query cache does not cache the state of the actual entities in the " +"cache; it caches only identifier values and results of value type. For this " +"reaso, the query cache should always be used in conjunction with the second-" +"level cache for those entities expected to be cached as part of a query " +"result cache (just as with collection caching)." +msgstr "" + +#. Tag: title +#, fuzzy, no-c-format +msgid "Query cache regions" +msgstr "Cache de requêtes supporté" + +#. Tag: para +#, no-c-format +msgid "" +"If you require fine-grained control over query cache expiration policies, " +"you can specify a named cache region for a particular query by calling " +"<literal>Query.setCacheRegion()</literal>." +msgstr "" +"Si vous avez besoin de contrôler finement les délais d'expiration du cache, " +"vous pouvez spécifier une région de cache nommée pour une requête " +"particulière en appelant <literal>Query.setCacheRegion()</literal>. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"If you want to force the query cache to refresh one of its regions " +"(disregard any cached results it finds there) you can use <literal>org." +"hibernate.Query.setCacheMode(CacheMode.REFRESH)</literal>. In conjunction " +"with the region you have defined for the given query, Hibernate will " +"selectively force the results cached in that particular region to be " +"refreshed. This is particularly useful in cases where underlying data may " +"have been updated via a separate process and is a far more efficient " +"alternative to bulk eviction of the region via <literal>org.hibernate." +"SessionFactory.evictQueries()</literal>." +msgstr "" +"Si une requête doit forcer le rafraîchissement de sa région de cache, vous " +"devez appeler <literal>Query.setCacheMode(CacheMode.REFRESH)</literal>. " +"C'est particulièrement utile lorsque les données peuvent avoir été mises à " +"jour par un processus séparé (c'est-à-dire qu'elles n'ont pas été modifiées " +"par Hibernate). Cela permet à l'application de rafraîchir de manière " +"sélective les résultats d'une requête particulière. Il s'agit d'une " +"alternative plus efficace à l'éviction d'une région du cache à l'aide de la " +"méthode <literal>SessionFactory.evictQueries()</literal>." + +#. Tag: title +#, no-c-format +msgid "Understanding Collection performance" +msgstr "Comprendre les performances des collections" + +#. Tag: para +#, no-c-format +msgid "" +"In the previous sections we have covered collections and their applications. " +"In this section we explore some more issues in relation to collections at " +"runtime." +msgstr "" +"Dans les sections précédentes, nous avons couvert les collections et leurs " +"applications. Dans cette section, nous allons explorer de nouveaux problèmes " +"en rapport aux collections en cours d'exécution." + +#. Tag: title +#, no-c-format +msgid "Taxonomy" +msgstr "Taxinomie" + +#. Tag: para +#, no-c-format +msgid "Hibernate defines three basic kinds of collections:" +msgstr "Hibernate définit trois types de collections de base :" + +#. Tag: para +#, no-c-format +msgid "collections of values" +msgstr "les collections de valeurs" + +#. Tag: para +#, no-c-format +msgid "one-to-many associations" +msgstr "Association un-à-plusieurs " + +#. Tag: para +#, no-c-format +msgid "many-to-many associations" +msgstr "les associations plusieurs-à-plusieurs " + +#. Tag: para +#, no-c-format +msgid "" +"This classification distinguishes the various table and foreign key " +"relationships but does not tell us quite everything we need to know about " +"the relational model. To fully understand the relational structure and " +"performance characteristics, we must also consider the structure of the " +"primary key that is used by Hibernate to update or delete collection rows. " +"This suggests the following classification:" +msgstr "" +"Cette classification distingue les différentes relations entre les tables et " +"les clés étrangères mais ne n'en dit pas suffisamment sur le modèle " +"relationnel. Pour comprendre parfaitement la structure relationnelle et les " +"caractéristiques des performances, nous devons considérer la structure de la " +"clé primaire qui est utilisée par Hibernate pour mettre à jour ou supprimer " +"les lignes des collections. Cela nous amène aux classifications suivantes :" + +#. Tag: para +#, no-c-format +msgid "indexed collections" +msgstr "collections indexées" + +#. Tag: para +#, no-c-format +msgid "sets" +msgstr "ensembles (sets)" + +#. Tag: para +#, no-c-format +msgid "bags" +msgstr "sacs (bags)" + +#. Tag: para +#, no-c-format +msgid "" +"All indexed collections (maps, lists, and arrays) have a primary key " +"consisting of the <literal>&lt;key&gt;</literal> and <literal>&lt;index&gt;</" +"literal> columns. In this case, collection updates are extremely efficient. " +"The primary key can be efficiently indexed and a particular row can be " +"efficiently located when Hibernate tries to update or delete it." +msgstr "" +"Toutes les collections indexées (maps, lists, arrays) ont une clé primaire " +"constituée des colonnes clés (<literal>&lt;key&gt;</literal>) et " +"<literal>&lt;index&gt;</literal>. Avec ce type de clé primaire, la mise à " +"jour de collection est en général très performante - la clé primaire peut " +"être indexées efficacement et une ligne particulière peut être localisée " +"efficacement lorsque Hibernate essaie de la mettre à jour ou de la " +"supprimer. " + +#. Tag: para +#, no-c-format +msgid "" +"Sets have a primary key consisting of <literal>&lt;key&gt;</literal> and " +"element columns. This can be less efficient for some types of collection " +"element, particularly composite elements or large text or binary fields, as " +"the database may not be able to index a complex primary key as efficiently. " +"However, for one-to-many or many-to-many associations, particularly in the " +"case of synthetic identifiers, it is likely to be just as efficient. If you " +"want <literal>SchemaExport</literal> to actually create the primary key of a " +"<literal>&lt;set&gt;</literal>, you must declare all columns as <literal>not-" +"null=\"true\"</literal>." +msgstr "" +"Les ensembles ont une clé primaire composée de <literal>&lt;key&gt;</" +"literal> et des colonnes représentant l'élément. Elle est donc moins " +"efficace pour certains types d'éléments de collection, en particulier les " +"éléments composites, les textes volumineux ou les champs binaires ; la base " +"de données peut ne pas être capable d'indexer aussi efficacement une clé " +"primaire aussi complexe. Cependant, pour les associations un-à-plusieurs ou " +"plusieurs-à-plusieurs, en particulier lorsqu'on utilise des entités ayant " +"des identifiants techniques, il est probable que cela soit aussi efficace " +"(note : si vous voulez que <literal>SchemaExport</literal> crée " +"effectivement la clé primaire d'un <literal>&lt;set&gt;</literal> pour vous, " +"vous devez déclarer toutes les colonnes avec <literal>not-null=\"true\"</" +"literal>). " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>&lt;idbag&gt;</literal> mappings define a surrogate key, so they " +"are efficient to update. In fact, they are the best case." +msgstr "" +"Le mappage à l'aide de <literal>&lt;idbag&gt;</literal> définit une clé de " +"substitution ce qui leur permet d'être très efficaces lors de la mise à " +"jour. En fait il s'agit du meilleur cas de mise à jour d'une collection." + +#. Tag: para +#, no-c-format +msgid "" +"Bags are the worst case since they permit duplicate element values and, as " +"they have no index column, no primary key can be defined. Hibernate has no " +"way of distinguishing between duplicate rows. Hibernate resolves this " +"problem by completely removing in a single <literal>DELETE</literal> and " +"recreating the collection whenever it changes. This can be inefficient." +msgstr "" +"Le pire cas intervient pour les sacs. Dans la mesure où un sac permet la " +"duplication des valeurs d'éléments et n'a pas de colonne d'index, aucune clé " +"primaire ne peut être définie. Hibernate n'a aucun moyen de distinguer entre " +"les lignes dupliquées. Hibernate résout ce problème en supprimant " +"complètement (via un simple <literal>DELETE</literal>), puis en recréant la " +"collection chaque fois qu'elle change. Ce qui peut être très inefficace. " + +#. Tag: para +#, no-c-format +msgid "" +"For a one-to-many association, the \"primary key\" may not be the physical " +"primary key of the database table. Even in this case, the above " +"classification is still useful. It reflects how Hibernate \"locates\" " +"individual rows of the collection." +msgstr "" +"Notez que pour une relation un-à-plusieurs, la \"clé primaire\" peut ne pas " +"être la clé primaire de la table en base de données - mais même dans ce cas, " +"la classification ci-dessus reste utile (Elle explique comment Hibernate " +"localise les lignes individuelles de la collection). " + +#. Tag: title +#, no-c-format +msgid "" +"Lists, maps, idbags and sets are the most efficient collections to update" +msgstr "" +"Les lists, les maps, les idbags et les ensembles sont les collections les " +"plus efficaces pour la mise à jour " + +#. Tag: para +#, no-c-format +msgid "" +"From the discussion above, it should be clear that indexed collections and " +"sets allow the most efficient operation in terms of adding, removing and " +"updating elements." +msgstr "" +"La discussion précédente montre clairement que les collections indexées et " +"(la plupart du temps) les ensembles, permettent de réaliser le plus " +"efficacement les opérations d'ajout, de suppression ou mise à jour " +"d'éléments. " + +#. Tag: para +#, no-c-format +msgid "" +"There is, arguably, one more advantage that indexed collections have over " +"sets for many-to-many associations or collections of values. Because of the " +"structure of a <literal>Set</literal>, Hibernate does not <literal>UPDATE</" +"literal> a row when an element is \"changed\". Changes to a <literal>Set</" +"literal> always work via <literal>INSERT</literal> and <literal>DELETE</" +"literal> of individual rows. Once again, this consideration does not apply " +"to one-to-many associations." +msgstr "" +"Les collections indexées ont un avantage sur les ensembles, dans le cadre " +"des associations plusieurs-à-plusieurs ou de collections de valeurs. À cause " +"de la structure inhérente d'un <literal>Set</literal>, Hibernate n'effectue " +"jamais de ligne <literal>UPDATE</literal> quand un élément est modifié. Les " +"modifications apportées à un <literal>Set</literal> se font via un " +"<literal>INSERT</literal> et <literal>DELETE</literal> (de chaque ligne). " +"Une fois de plus, ce cas ne s'applique pas aux associations un-à-plusieurs. " + +#. Tag: para +#, no-c-format +msgid "" +"After observing that arrays cannot be lazy, you can conclude that lists, " +"maps and idbags are the most performant (non-inverse) collection types, with " +"sets not far behind. You can expect sets to be the most common kind of " +"collection in Hibernate applications. This is because the \"set\" semantics " +"are most natural in the relational model." +msgstr "" +"Après s'être rappelé que les tableaux ne peuvent pas être chargés en " +"différé, nous pouvons conclure que les lists, les maps et les idbags sont " +"les types de collections (non inversées) les plus performants, avec les " +"ensembles pas loin derrière. Les ensembles sont le type de collection le " +"plus courant dans les applications Hibernate. Cela vient du fait que la " +"sémantique des ensembles est la plus naturelle dans le modèle relationnel. " + +#. Tag: para +#, no-c-format +msgid "" +"However, in well-designed Hibernate domain models, most collections are in " +"fact one-to-many associations with <literal>inverse=\"true\"</literal>. For " +"these associations, the update is handled by the many-to-one end of the " +"association, and so considerations of collection update performance simply " +"do not apply." +msgstr "" +"Cependant, dans des modèles objet bien conçus avec Hibernate, on constate " +"que la plupart des collections sont en fait des associations un-à-plusieurs " +"avec <literal>inverse=\"true\"</literal>. Pour ces associations, les mises à " +"jour sont gérées au niveau de l'association \"plusieurs-à-un\" et les " +"considérations de performance de mise à jour des collections ne s'appliquent " +"tout simplement pas dans ces cas-là. " + +#. Tag: title +#, no-c-format +msgid "Bags and lists are the most efficient inverse collections" +msgstr "" +"Les sacs et les listes sont les plus efficaces pour les collections inverses" + +#. Tag: para +#, no-c-format +msgid "" +"There is a particular case, however, in which bags, and also lists, are much " +"more performant than sets. For a collection with <literal>inverse=\"true\"</" +"literal>, the standard bidirectional one-to-many relationship idiom, for " +"example, we can add elements to a bag or list without needing to initialize " +"(fetch) the bag elements. This is because, unlike a <literal>set</literal>, " +"<literal>Collection.add()</literal> or <literal>Collection.addAll()</" +"literal> must always return true for a bag or <literal>List</literal>. This " +"can make the following common code much faster:" +msgstr "" +"Avant que vous n'oubliez les sacs pour toujours, il y a un cas précis où les " +"sacs (et les listes) sont bien plus performants que les ensembles. Pour une " +"collection marquée comme <literal>inverse=\"true\"</literal> (le choix le " +"plus courant pour un relation un-à-plusieurs bidirectionnelle), nous pouvons " +"ajouter des éléments à un sac ou une liste sans avoir besoin de " +"l'initialiser (charger) les éléments du sac! Ceci parce que " +"<literal>Collection.add()</literal> ou <literal>Collection.addAll()</" +"literal> doit toujours retourner vrai pour un sac ou une <literal>List</" +"literal> (contrairement au <literal>Set</literal>). Cela peut rendre le code " +"suivant beaucoup plus rapide :" + +#. Tag: title +#, no-c-format +msgid "One shot delete" +msgstr "Suppression en un coup" + +#. Tag: para +#, no-c-format +msgid "" +"Deleting collection elements one by one can sometimes be extremely " +"inefficient. Hibernate knows not to do that in the case of an newly-empty " +"collection (if you called <literal>list.clear()</literal>, for example). In " +"this case, Hibernate will issue a single <literal>DELETE</literal>." +msgstr "" +"Parfois, effacer les éléments d'une collection un par un peut être " +"extrêmement inefficace. Hibernate n'est pas totalement stupide, il sait " +"qu'il ne faut pas le faire dans le cas d'une collection complètement vidée " +"(lorsque vous appelez <literal>list.clear()</literal>, par exemple). Dans ce " +"cas, Hibernate fera un simple <literal>DELETE</literal> et le travail est " +"fait ! " + +#. Tag: para +#, no-c-format +msgid "" +"Suppose you added a single element to a collection of size twenty and then " +"remove two elements. Hibernate will issue one <literal>INSERT</literal> " +"statement and two <literal>DELETE</literal> statements, unless the " +"collection is a bag. This is certainly desirable." +msgstr "" +"Supposons que nous ajoutions un élément unique dans une collection de taille " +"vingt et que nous enlevions ensuite deux éléments. Hibernate effectuera un " +"<literal>INSERT</literal> puis deux <literal>DELETE</literal> (à moins que " +"la collection ne soit un sac). Cela est préférable. " + +#. Tag: para +#, no-c-format +msgid "" +"However, suppose that we remove eighteen elements, leaving two and then add " +"thee new elements. There are two possible ways to proceed" +msgstr "" +"Cependant, supposons que nous enlevions dix-huit éléments, laissant ainsi " +"deux éléments, puis que nous ajoutions trois nouveaux éléments. Il y a deux " +"moyens de procéder." + +#. Tag: para +#, no-c-format +msgid "delete eighteen rows one by one and then insert three rows" +msgstr "effacer dix-huit lignes une à une puis en insérer trois" + +#. Tag: para +#, no-c-format +msgid "" +"remove the whole collection in one SQL <literal>DELETE</literal> and insert " +"all five current elements one by one" +msgstr "" +"effacer la totalité de la collection (en un SQL <literal>DELETE</literal>) " +"puis insérer les cinq éléments restant (un à un) " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate cannot know that the second option is probably quicker. It would " +"probably be undesirable for Hibernate to be that intuitive as such behavior " +"might confuse database triggers, etc." +msgstr "" +"Hibernate n'est pas assez intelligent pour savoir que, dans ce cas, la " +"seconde option est plus rapide (Il vaut mieux que Hibernate ne soit pas trop " +"intelligent ; un tel comportement pourrait rendre l'utilisation de triggers " +"de bases de données plutôt aléatoire, etc...). " + +#. Tag: para +#, no-c-format +msgid "" +"Fortunately, you can force this behavior (i.e. the second strategy) at any " +"time by discarding (i.e. dereferencing) the original collection and " +"returning a newly instantiated collection with all the current elements." +msgstr "" +"Heureusement, vous pouvez forcer ce comportement (c'est-à-dire la deuxième " +"stratégie) à tout moment en libérant (c'est-à-dire en déréférençant) la " +"collection initiale et en retournant une collection nouvellement instanciée " +"avec tous les éléments restants. " + +#. Tag: para +#, no-c-format +msgid "" +"One-shot-delete does not apply to collections mapped <literal>inverse=\"true" +"\"</literal>." +msgstr "" +"Bien sûr, la suppression en un coup ne s'applique pas pour les collections " +"qui sont mappées avec <literal>inverse=\"true\"</literal>. " + +#. Tag: title +#, no-c-format +msgid "Monitoring performance" +msgstr "Moniteur de performance" + +#. Tag: para +#, no-c-format +msgid "" +"Optimization is not much use without monitoring and access to performance " +"numbers. Hibernate provides a full range of figures about its internal " +"operations. Statistics in Hibernate are available per " +"<literal>SessionFactory</literal>." +msgstr "" +"L'optimisation n'est pas d'un grand intérêt sans le suivi et l'accès aux " +"données de performance. Hibernate fournit toute une panoplie de rapport sur " +"ses opérations internes. Les statistiques dans Hibernate sont fournies par " +"<literal>SessionFactory</literal>." + +#. Tag: title +#, no-c-format +msgid "Monitoring a SessionFactory" +msgstr "Suivi d'une SessionFactory" + +#. Tag: para +#, no-c-format +msgid "" +"You can access <literal>SessionFactory</literal> metrics in two ways. Your " +"first option is to call <literal>sessionFactory.getStatistics()</literal> " +"and read or display the <literal>Statistics</literal> yourself." +msgstr "" +"Vous pouvez accéder aux métriques d'une <literal>SessionFactory</literal> de " +"deux manières. La première option est d'appeler <literal>sessionFactory." +"getStatistics()</literal> et de lire ou d'afficher les <literal>Statistics</" +"literal> vous-même." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate can also use JMX to publish metrics if you enable the " +"<literal>StatisticsService</literal> MBean. You can enable a single MBean " +"for all your <literal>SessionFactory</literal> or one per factory. See the " +"following code for minimalistic configuration examples:" +msgstr "" +"Hibernate peut également utiliser JMX pour publier les métriques si vous " +"activez le MBean <literal>StatisticsService</literal>. Vous pouvez activer " +"un seul MBean pour toutes vos <literal>SessionFactory</literal> ou un par " +"fabrique. Voici un code qui montre un exemple de configuration minimaliste : " + +#. Tag: para +#, no-c-format +msgid "" +"You can activate and deactivate the monitoring for a " +"<literal>SessionFactory</literal>:" +msgstr "" +"Vous pouvez (dés)activer le suivi pour une <literal>SessionFactory</" +"literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"at configuration time, set <literal>hibernate.generate_statistics</literal> " +"to <literal>false</literal>" +msgstr "" +"au moment de la configuration en mettant <literal>hibernate." +"generate_statistics</literal> à <literal>false</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"at runtime: <literal>sf.getStatistics().setStatisticsEnabled(true)</literal> " +"or <literal>hibernateStatsBean.setStatisticsEnabled(true)</literal>" +msgstr "" +"à chaud avec <literal>sf.getStatistics().setStatisticsEnabled(true)</" +"literal> ou <literal>hibernateStatsBean.setStatisticsEnabled(true)</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Statistics can be reset programmatically using the <literal>clear()</" +"literal> method. A summary can be sent to a logger (info level) using the " +"<literal>logSummary()</literal> method." +msgstr "" +"Les statistiques peuvent être remises à zéro de manière programmatique à " +"l'aide de la méthode <literal>clear()</literal> Un résumé peut être envoyé à " +"un logger (niveau info) à l'aide de la méthode <literal>logSummary()</" +"literal>." + +#. Tag: title +#, no-c-format +msgid "Metrics" +msgstr "Métriques" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate provides a number of metrics, from basic information to more " +"specialized information that is only relevant in certain scenarios. All " +"available counters are described in the <literal>Statistics</literal> " +"interface API, in three categories:" +msgstr "" +"Hibernate fournit plusieurs métriques, qui vont des informations très " +"basiques aux informations très spécialisées qui ne sont appropriées que dans " +"certains scénarios. Tous les compteurs accessibles sont décrits dans l'API " +"de l'interface <literal>Statistics</literal> dans trois catégories : " + +#. Tag: para +#, no-c-format +msgid "" +"Metrics related to the general <literal>Session</literal> usage, such as " +"number of open sessions, retrieved JDBC connections, etc." +msgstr "" +"Les métriques relatives à l'usage général de la <literal>Session</literal> " +"comme le nombre de sessions ouvertes, le nombre de connexions JDBC " +"récupérées, etc..." + +#. Tag: para +#, no-c-format +msgid "" +"Metrics related to the entities, collections, queries, and caches as a whole " +"(aka global metrics)." +msgstr "" +"Les métriques relatives aux entités, collections, requêtes et caches dans " +"leur ensemble (métriques globales aka)." + +#. Tag: para +#, no-c-format +msgid "" +"Detailed metrics related to a particular entity, collection, query or cache " +"region." +msgstr "" +"Les métriques détaillées relatives à une entité, une collection, une requête " +"ou une région de cache particulière." + +#. Tag: para +#, no-c-format +msgid "" +"For example, you can check the cache hit, miss, and put ratio of entities, " +"collections and queries, and the average time a query needs. Be aware that " +"the number of milliseconds is subject to approximation in Java. Hibernate is " +"tied to the JVM precision and on some platforms this might only be accurate " +"to 10 seconds." +msgstr "" +"Par exemple, vous pouvez vérifier les hit, miss du cache ainsi que le taux " +"d'éléments manquants et de mise à jour des entités, collections et requêtes " +"et le temps moyen que met une requête. Il faut faire attention au fait que " +"le nombre de millisecondes est sujet à approximation en Java. Hibernate est " +"lié à la précision de la machine virtuelle, sur certaines plateformes, cela " +"n'offre qu'une précision de l'ordre de 10 secondes. " + +#. Tag: para +#, no-c-format +msgid "" +"Simple getters are used to access the global metrics (i.e. not tied to a " +"particular entity, collection, cache region, etc.). You can access the " +"metrics of a particular entity, collection or cache region through its name, " +"and through its HQL or SQL representation for queries. Please refer to the " +"<literal>Statistics</literal>, <literal>EntityStatistics</literal>, " +"<literal>CollectionStatistics</literal>, " +"<literal>SecondLevelCacheStatistics</literal>, and <literal>QueryStatistics</" +"literal> API Javadoc for more information. The following code is a simple " +"example:" +msgstr "" +"Des accesseurs simples sont utilisés pour accéder aux métriques globales " +"(c'est-à-dire, celles qui ne sont pas liées à une entité, collection ou " +"région de cache particulière). Vous pouvez accéder aux métriques d'une " +"entité, collection, région de cache particulière à l'aide de son nom et à " +"l'aide de sa représentation HQL ou SQL pour une requête. Référez vous à la " +"javadoc des APIS <literal>Statistics</literal>, <literal>EntityStatistics</" +"literal>, <literal>CollectionStatistics</literal>, " +"<literal>SecondLevelCacheStatistics</literal>, et <literal>QueryStatistics</" +"literal> pour plus d'informations. Le code ci-dessous montre un exemple " +"simple : " + +#. Tag: para +#, no-c-format +msgid "" +"You can work on all entities, collections, queries and region caches, by " +"retrieving the list of names of entities, collections, queries and region " +"caches using the following methods: <literal>getQueries()</literal>, " +"<literal>getEntityNames()</literal>, <literal>getCollectionRoleNames()</" +"literal>, and <literal>getSecondLevelCacheRegionNames()</literal>." +msgstr "" +"Pour travailler sur toutes les entités, collections, requêtes et régions de " +"cache, vous pouvez récupérer la liste des noms des entités, collections, " +"requêtes et régions de cache avec les méthodes suivantes : " +"<literal>getQueries()</literal>, <literal>getEntityNames()</literal>, " +"<literal>getCollectionRoleNames()</literal>, et " +"<literal>getSecondLevelCacheRegionNames()</literal>. " + +#~ msgid "" +#~ "This setting creates two new cache regions: one holding cached query " +#~ "result sets (<literal>org.hibernate.cache.StandardQueryCache</literal>), " +#~ "the other holding timestamps of the most recent updates to queryable " +#~ "tables (<literal>org.hibernate.cache.UpdateTimestampsCache</literal>). " +#~ "Note that the query cache does not cache the state of the actual entities " +#~ "in the result set; it caches only identifier values and results of value " +#~ "type. The query cache should always be used in conjunction with the " +#~ "second-level cache." +#~ msgstr "" +#~ "Ce paramètre amène la création de deux nouvelles régions dans le cache, " +#~ "une qui va conserver le résultat des requêtes mises en cache " +#~ "(<literal>org.hibernate.cache.StandardQueryCache</literal>) et l'autre " +#~ "qui va conserver l'horodatage des mises à jour les plus récentes " +#~ "effectuées sur les tables requêtables (<literal>org.hibernate.cache." +#~ "UpdateTimestampsCache</literal>). Il faut noter que le cache de requête " +#~ "ne conserve pas l'état des entités dans les résultats, il met en cache " +#~ "uniquement les valeurs de l'identifiant et les résultats de types de " +#~ "valeurs. Par conséquent, le cache de requête doit toujours être utilisé " +#~ "avec le cache de second niveau. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/persistent_classes.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/persistent_classes.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/persistent_classes.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,663 @@ +# translation of persistent_classes.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: persistent_classes\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:39+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Persistent Classes" +msgstr "Classes persistantes" + +#. Tag: para +#, no-c-format +msgid "" +"Persistent classes are classes in an application that implement the entities " +"of the business problem (e.g. Customer and Order in an E-commerce " +"application). Not all instances of a persistent class are considered to be " +"in the persistent state. For example, an instance can instead be transient " +"or detached." +msgstr "" +"Les classes persistantes sont les classes d'une application qui implémentent " +"les entités d'un problème métier (par ex. Client et Commande dans une " +"application de commerce électronique). Toutes les instances d'une classe " +"persistante ne sont pas forcément dans l'état persistant - en revanche, une " +"instance peut être éphémère (transient) ou détachée." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate works best if these classes follow some simple rules, also known " +"as the Plain Old Java Object (POJO) programming model. However, none of " +"these rules are hard requirements. Indeed, Hibernate3 assumes very little " +"about the nature of your persistent objects. You can express a domain model " +"in other ways (using trees of <literal>Map</literal> instances, for example)." +msgstr "" +"Hibernate fonctionne de manière optimale lorsque ces classes suivent " +"quelques règles simples, aussi connues comme le modèle de programmation " +"Plain Old Java Object (POJO). Cependant, aucune de ces règles ne sont des " +"besoins absolus. En effet, Hibernate3 présuppose très peu de choses à propos " +"de la nature de vos objets persistants. Vous pouvez exprimer un modèle de " +"domaine par d'autres moyens : utiliser des arbres d'instances de " +"<literal>Map</literal>, par exemple." + +#. Tag: title +#, no-c-format +msgid "A simple POJO example" +msgstr "Un exemple simple de POJO" + +#. Tag: para +#, no-c-format +msgid "" +"Most Java applications require a persistent class representing felines. For " +"example:" +msgstr "" +"Toute bonne application Java nécessite une classe persistante représentant " +"les félins. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"The four main rules of persistent classes are explored in more detail in the " +"following sections." +msgstr "" +"On explore quatre règles principales de classes persistantes en détail dans " +"les sections qui suivent :" + +#. Tag: title +#, no-c-format +msgid "Implement a no-argument constructor" +msgstr "Implémenter un constructeur sans argument" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>Cat</literal> has a no-argument constructor. All persistent classes " +"must have a default constructor (which can be non-public) so that Hibernate " +"can instantiate them using <literal>Constructor.newInstance()</literal>. It " +"is recommended that you have a default constructor with at least " +"<emphasis>package</emphasis> visibility for runtime proxy generation in " +"Hibernate." +msgstr "" +"<literal>Cat</literal> a un constructeur sans argument. Toutes les classes " +"persistantes doivent avoir un constructeur par défaut (lequel peut ne pas " +"être public) pour que Hibernate puisse les instancier en utilisant " +"<literal>Constructor.newInstance()</literal>. Nous recommandons fortement " +"d'avoir un constructeur par défaut avec au moins une visibilité " +"<emphasis>paquetage</emphasis> pour la génération du proxy à l'exécution " +"dans Hibernate. " + +#. Tag: title +#, no-c-format +msgid "Provide an identifier property (optional)" +msgstr "Fournir une propriété d'identifiant (optionnel)" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>Cat</literal> has a property called <literal>id</literal>. This " +"property maps to the primary key column of a database table. The property " +"might have been called anything, and its type might have been any primitive " +"type, any primitive \"wrapper\" type, <literal>java.lang.String</literal> or " +"<literal>java.util.Date</literal>. If your legacy database table has " +"composite keys, you can use a user-defined class with properties of these " +"types (see the section on composite identifiers later in the chapter.)" +msgstr "" +"<literal>Cat</literal> possède une propriété appelée <literal>id</literal>. " +"Cette propriété mappe la valeur de la colonne de clé primaire de la table " +"d'une base de données. La propriété aurait pu s'appeler autrement, et son " +"type aurait pu être n'importe quel type primitif, n'importe quel " +"\"encapsuleur\" de type primitif, <literal>java.lang.String</literal> ou " +"<literal>java.util.Date</literal>. (Si votre base de données héritée possède " +"des clés composites, elles peuvent être mappées en utilisant une classe " +"définie par l'utilisateur et possédant les propriétés associées aux types de " +"la clé composite - voir la section concernant les identifiants composites " +"ultérieurement). " + +#. Tag: para +#, no-c-format +msgid "" +"The identifier property is strictly optional. You can leave them off and let " +"Hibernate keep track of object identifiers internally. We do not recommend " +"this, however." +msgstr "" +"La propriété d'identifiant est strictement optionnelle. Vous pouvez " +"l'oublier et laisser Hibernate s'occuper des identifiants de l'objet en " +"interne. Toutefois, ce n'est pas recommandé. " + +#. Tag: para +#, no-c-format +msgid "" +"In fact, some functionality is available only to classes that declare an " +"identifier property:" +msgstr "" +"En fait, quelques fonctionnalités ne sont disponibles que pour les classes " +"déclarant un identifiant de propriété : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Transitive reattachment for detached objects (cascade update or cascade " +"merge) - see <xref linkend=\"objectstate-transitive\" />" +msgstr "" +"Pour les rattachements transitifs pour les objets détachés (mise à jour en " +"cascade ou fusion en cascade) - consultez <xref linkend=\"objectstate-" +"transitive\" />" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>Session.saveOrUpdate()</literal>" +msgstr "<literal>Session.saveOrUpdate()</literal>" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>Session.merge()</literal>" +msgstr "<literal>Session.merge()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"We recommend that you declare consistently-named identifier properties on " +"persistent classes and that you use a nullable (i.e., non-primitive) type." +msgstr "" +"Nous recommandons que vous déclariez les propriétés d'identifiant de manière " +"uniforme. Nous recommandons également que vous utilisiez un type nullable " +"(c'est-à-dire non primitif). " + +#. Tag: title +#, no-c-format +msgid "Prefer non-final classes (optional)" +msgstr "Favoriser les classes non finales (optionnel)" + +#. Tag: para +#, no-c-format +msgid "" +"A central feature of Hibernate, <emphasis>proxies</emphasis>, depends upon " +"the persistent class being either non-final, or the implementation of an " +"interface that declares all public methods." +msgstr "" +"Une fonctionnalité clé de Hibernate, les <emphasis>proxies</emphasis>, " +"nécessitent que la classe persistante soit non finale ou qu'elle soit " +"l'implémentation d'une interface qui déclare toutes les méthodes publiques." + +#. Tag: para +#, no-c-format +msgid "" +"You can persist <literal>final</literal> classes that do not implement an " +"interface with Hibernate. You will not, however, be able to use proxies for " +"lazy association fetching which will ultimately limit your options for " +"performance tuning." +msgstr "" +"Vous pouvez persister, grâce à Hibernate, les classes <literal>final</" +"literal> qui n'implémentent pas d'interface, mais vous ne pourrez pas " +"utiliser les proxies pour les chargements d'associations paresseux - ce qui " +"limitera vos possibilités d'ajustement des performances. " + +#. Tag: para +#, no-c-format +msgid "" +"You should also avoid declaring <literal>public final</literal> methods on " +"the non-final classes. If you want to use a class with a <literal>public " +"final</literal> method, you must explicitly disable proxying by setting " +"<literal>lazy=\"false\"</literal>." +msgstr "" +"Vous devriez aussi éviter de déclarer des méthodes <literal>public final</" +"literal> sur des classes non-finales. Si vous voulez utiliser une classe " +"avec une méthode <literal>public final</literal>, vous devez explicitement " +"désactiver les proxies en paramétrant <literal>lazy=\"false\"</literal>. " + +#. Tag: title +#, no-c-format +msgid "Declare accessors and mutators for persistent fields (optional)" +msgstr "" +"Déclarer les accesseurs et mutateurs des attributs persistants (optionnel)" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>Cat</literal> declares accessor methods for all its persistent " +"fields. Many other ORM tools directly persist instance variables. It is " +"better to provide an indirection between the relational schema and internal " +"data structures of the class. By default, Hibernate persists JavaBeans style " +"properties and recognizes method names of the form <literal>getFoo</" +"literal>, <literal>isFoo</literal> and <literal>setFoo</literal>. If " +"required, you can switch to direct field access for particular properties." +msgstr "" +"<literal>Cat</literal> déclare des mutateurs pour tous ses champs " +"persistants. Beaucoup d'autres solutions de mappage Objet/relationnel " +"persistent directement les variables d'instance. Nous pensons qu'il est " +"préférable de fournir une indirection entre le schéma relationnel et les " +"structures de données internes de la classe. Par défaut, Hibernate persiste " +"les propriétés suivant le style JavaBean, et reconnaît les noms de méthodes " +"de la forme <literal> getFoo</literal>, <literal>isFoo</literal> et " +"<literal>setFoo</literal>. Vous pouvez changer pour un accès direct aux " +"champs pour des propriétés particulières, si besoin est. " + +#. Tag: para +#, no-c-format +msgid "" +"Properties need <emphasis>not</emphasis> be declared public - Hibernate can " +"persist a property with a default, <literal>protected</literal> or " +"<literal>private</literal> get / set pair." +msgstr "" +"Les propriétés <emphasis>n'ont pas</emphasis> à être déclarées publiques - " +"Hibernate peut persister une propriété avec une paire de getter/setter par " +"défault, <literal>protected</literal> ou <literal> private</literal>. " + +#. Tag: title +#, no-c-format +msgid "Implementing inheritance" +msgstr "Implémenter l'héritage" + +#. Tag: para +#, no-c-format +msgid "" +"A subclass must also observe the first and second rules. It inherits its " +"identifier property from the superclass, <literal>Cat</literal>. For example:" +msgstr "" +"Une sous-classe doit également suivre la première et la seconde règle. Elle " +"hérite sa propriété d'identifiant de la classe mère <literal>Cat</literal>. " +"Par exemple :" + +#. Tag: title +#, no-c-format +msgid "" +"Implementing <literal>equals()</literal> and <literal>hashCode()</literal>" +msgstr "" +"Implémenter <literal>equals()</literal> et <literal>hashCode()</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"You have to override the <literal>equals()</literal> and <literal>hashCode()" +"</literal> methods if you:" +msgstr "" +"Vous devez surcharger les méthodes <literal>equals()</literal> et " +"<literal>hashCode()</literal> si vous :" + +#. Tag: para +#, no-c-format +msgid "" +"intend to put instances of persistent classes in a <literal>Set</literal> " +"(the recommended way to represent many-valued associations); <emphasis>and</" +"emphasis>" +msgstr "" +"avez l'intention de mettre des instances de classes persistantes dans un " +"<literal>Set</literal> (la manière recommandée pour représenter des " +"associations pluri-valuées); <emphasis>et</emphasis>" + +#. Tag: para +#, no-c-format +msgid "intend to use reattachment of detached instances" +msgstr "avez l'intention d'utiliser le rattachement d'instances détachées" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate guarantees equivalence of persistent identity (database row) and " +"Java identity only inside a particular session scope. When you mix instances " +"retrieved in different sessions, you must implement <literal>equals()</" +"literal> and <literal>hashCode()</literal> if you wish to have meaningful " +"semantics for <literal>Set</literal>s." +msgstr "" +"Hibernate garantit l'équivalence de l'identité persistante (ligne de base de " +"données) et l'identité Java seulement à l'intérieur de la portée d'une " +"session particulière. Donc dès que nous mélangeons des instances venant de " +"différentes sessions, nous devons implémenter <literal>equals()</literal> et " +"<literal>hashCode()</literal> si nous souhaitons avoir une sémantique " +"correcte pour les <literal>Set</literal> s. " + +#. Tag: para +#, no-c-format +msgid "" +"The most obvious way is to implement <literal>equals()</literal>/" +"<literal>hashCode()</literal> by comparing the identifier value of both " +"objects. If the value is the same, both must be the same database row, " +"because they are equal. If both are added to a <literal>Set</literal>, you " +"will only have one element in the <literal>Set</literal>). Unfortunately, " +"you cannot use that approach with generated identifiers. Hibernate will only " +"assign identifier values to objects that are persistent; a newly created " +"instance will not have any identifier value. Furthermore, if an instance is " +"unsaved and currently in a <literal>Set</literal>, saving it will assign an " +"identifier value to the object. If <literal>equals()</literal> and " +"<literal>hashCode()</literal> are based on the identifier value, the hash " +"code would change, breaking the contract of the <literal>Set</literal>. See " +"the Hibernate website for a full discussion of this problem. This is not a " +"Hibernate issue, but normal Java semantics of object identity and equality." +msgstr "" +"La manière la plus évidente est d'implémenter <literal>equals()</literal>/" +"<literal>hashCode()</literal> en comparant la valeur de l'identifiant des " +"deux objets. Si cette valeur est identique, les deux doivent représenter la " +"même ligne de base de données, ils sont donc égaux (si les deux sont ajoutés " +"à un <literal>Set</literal>, nous n'aurons qu'un seul élément dans le " +"<literal>Set</literal>). Malheureusement, nous ne pouvons pas utiliser cette " +"approche avec des identifiants générés ! Hibernate n'assignera de valeur " +"d'identifiant qu'aux objets qui sont persistants, une instance nouvellement " +"créée n'aura donc pas de valeur d'identifiant ! De plus, si une instance est " +"non sauvegardée et actuellement dans un <literal>Set</literal>, le " +"sauvegarder assignera une valeur d'identifiant à l'objet. Si <literal>equals" +"()</literal> et <literal>hashCode()</literal> sont basées sur la valeur de " +"l'identifiant, le code de hachage devrait changer, rompant le contrat du " +"<literal>Set</literal>. Consultez le site web de Hibernate pour des " +"informations plus approfondies. Notez que ceci n'est pas un problème " +"Hibernate, mais concerne la sémantique normale de Java pour l'identité et " +"l'égalité d'un objet. " + +#. Tag: para +#, no-c-format +msgid "" +"It is recommended that you implement <literal>equals()</literal> and " +"<literal>hashCode()</literal> using <emphasis>Business key equality</" +"emphasis>. Business key equality means that the <literal>equals()</literal> " +"method compares only the properties that form the business key. It is a key " +"that would identify our instance in the real world (a <emphasis>natural</" +"emphasis> candidate key):" +msgstr "" +"Nous recommandons donc d'implémenter <literal>equals()</literal> et " +"<literal>hashCode()</literal> en utilisant <emphasis> l'égalité par clé " +"métier</emphasis>. L'égalité par clé métier signifie que la méthode " +"<literal>equals()</literal> compare uniquement les propriétés qui forment " +"une clé métier, une clé qui identifierait notre instance dans le monde réel " +"(une clé candidate <emphasis>naturelle</emphasis>) : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"A business key does not have to be as solid as a database primary key " +"candidate (see <xref linkend=\"transactions-basics-identity\" />). Immutable " +"or unique properties are usually good candidates for a business key." +msgstr "" +"Notez qu'une clé métier ne doit pas être solide comme une clé primaire de " +"base de données (voir <xref linkend=\"transactions-basics-identity\" />). " +"Les propriétés immuables ou uniques sont généralement de bonnes candidates " +"pour une clé métier. " + +#. Tag: title +#, no-c-format +msgid "Dynamic models" +msgstr "Modèles dynamiques" + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Remarque" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<emphasis>The following features are currently considered experimental and " +"may change in the near future.</emphasis>" +msgstr "" +"<emphasis>Notez que les fonctionnalités suivantes sont actuellement " +"considérées comme expérimentales et pourront changer dans un futur proche.</" +"emphasis>" + +#. Tag: para +#, no-c-format +msgid "" +"Persistent entities do not necessarily have to be represented as POJO " +"classes or as JavaBean objects at runtime. Hibernate also supports dynamic " +"models (using <literal>Map</literal>s of <literal>Map</literal>s at runtime) " +"and the representation of entities as DOM4J trees. With this approach, you " +"do not write persistent classes, only mapping files." +msgstr "" +"Les entités persistantes ne doivent pas nécessairement être représentées " +"comme des classes POJO ou des objets JavaBean à l'exécution. Hibernate " +"supporte aussi les modèles dynamiques (en utilisant des <literal>Map</" +"literal> s de <literal>Map</literal> s à l'exécution) et la représentation " +"des entités comme des arbres DOM4J. Avec cette approche, vous n'écrivez pas " +"de classes persistantes, seulement des fichiers de mappage. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"By default, Hibernate works in normal POJO mode. You can set a default " +"entity representation mode for a particular <literal>SessionFactory</" +"literal> using the <literal>default_entity_mode</literal> configuration " +"option (see <xref linkend=\"configuration-optional-properties\" />)." +msgstr "" +"Par défaut, Hibernate fonctionne en mode POJO normal. Vous pouvez paramétrer " +"un mode de représentation d'entité par défaut pour une " +"<literal>SessionFactory</literal> particulière en utilisant l'option de " +"configuration <literal>default_entity_mode</literal> (voir <xref linkend=" +"\"configuration-optional-properties\" />)." + +#. Tag: para +#, no-c-format +msgid "" +"The following examples demonstrate the representation using <literal>Map</" +"literal>s. First, in the mapping file an <literal>entity-name</literal> has " +"to be declared instead of, or in addition to, a class name:" +msgstr "" +"Les exemples suivants démontrent la représentation utilisant des " +"<literal>Map</literal> s. D'abord, dans le fichier de mappage, un " +"<literal>entity-name</literal> doit être déclaré au lieu (ou en plus) d'un " +"nom de classe :" + +#. Tag: para +#, no-c-format +msgid "" +"Even though associations are declared using target class names, the target " +"type of associations can also be a dynamic entity instead of a POJO." +msgstr "" +"Notez que même si des associations sont déclarées en utilisant des noms de " +"classe cible, le type de cible d'une association peut aussi être une entité " +"dynamique au lieu d'un POJO. " + +#. Tag: para +#, no-c-format +msgid "" +"After setting the default entity mode to <literal>dynamic-map</literal> for " +"the <literal>SessionFactory</literal>, you can, at runtime, work with " +"<literal>Map</literal>s of <literal>Map</literal>s:" +msgstr "" +"Après avoir configuré le mode d'entité par défaut à <literal>dynamic-map</" +"literal> pour la <literal>SessionFactory</literal>, nous pouvons lors de " +"l'exécution fonctionner avec des <literal>Map</literal> s de <literal>Map</" +"literal> s : " + +#. Tag: para +#, no-c-format +msgid "" +"One of the main advantages of dynamic mapping is quick turnaround time for " +"prototyping, without the need for entity class implementation. However, you " +"lose compile-time type checking and will likely deal with many exceptions at " +"runtime. As a result of the Hibernate mapping, the database schema can " +"easily be normalized and sound, allowing to add a proper domain model " +"implementation on top later on." +msgstr "" +"Les avantages d'un mappage dynamique sont un gain de temps pour le " +"prototypage sans la nécessité d'implémenter les classes d'entité. Pourtant, " +"vous perdez la vérification du typage au moment de la compilation et aurez " +"plus d'exceptions à gérer lors de l'exécution. Grâce au mappage de " +"Hibernate, le schéma de la base de données peut facilement être normalisé et " +"solidifié, permettant de rajouter une implémentation propre du modèle de " +"domaine plus tard. " + +#. Tag: para +#, no-c-format +msgid "" +"Entity representation modes can also be set on a per <literal>Session</" +"literal> basis:" +msgstr "" +"Les modes de représentation d'une entité peuvent aussi être configurés en se " +"basant sur <literal>Session</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Please note that the call to <literal>getSession()</literal> using an " +"<literal>EntityMode</literal> is on the <literal>Session</literal> API, not " +"the <literal>SessionFactory</literal>. That way, the new <literal>Session</" +"literal> shares the underlying JDBC connection, transaction, and other " +"context information. This means you do not have to call <literal>flush()</" +"literal> and <literal>close()</literal> on the secondary <literal>Session</" +"literal>, and also leave the transaction and connection handling to the " +"primary unit of work." +msgstr "" +"Veuillez noter que l'appel à <literal>getSession()</literal> en utilisant un " +"<literal>EntityMode</literal> se fait sur l'API <literal>Session</literal>, " +"et non sur <literal>SessionFactory</literal>. De cette manière, la nouvelle " +"<literal>Session</literal> partage les connexions JDBC, transactions et " +"autres informations de contexte sous-jacentes. Cela signifie que vous n'avez " +"pas à appeler <literal>flush()</literal> et <literal>close()</literal> sur " +"la <literal>Session</literal> secondaire, et laissez aussi la gestion de la " +"transaction et de la connexion à l'unité de travail primaire. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"More information about the XML representation capabilities can be found in " +"<xref linkend=\"xml\" />." +msgstr "" +"Pour plus d'informations à propos de la représentation XML, veuillez " +"consulter <xref linkend=\"xml\" />." + +#. Tag: title +#, no-c-format +msgid "Tuplizers" +msgstr "Tuplizers" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>org.hibernate.tuple.Tuplizer</literal>, and its sub-interfaces, are " +"responsible for managing a particular representation of a piece of data " +"given that representation's <literal>org.hibernate.EntityMode</literal>. If " +"a given piece of data is thought of as a data structure, then a tuplizer is " +"the thing that knows how to create such a data structure and how to extract " +"values from and inject values into such a data structure. For example, for " +"the POJO entity mode, the corresponding tuplizer knows how create the POJO " +"through its constructor. It also knows how to access the POJO properties " +"using the defined property accessors." +msgstr "" +"<literal>org.hibernate.tuple.Tuplizer</literal>, et ses sous-interfaces, " +"sont responsables de la gestion d'une représentation particulière d'un " +"fragment de données, en fonction du <literal>org.hibernate.EntityMode</" +"literal> de représentation. Si un fragment donné de données est considéré " +"comme une structure de données, alors un tuplizer sait comment créer une " +"telle structure de données, comment extraire des valeurs et injecter des " +"valeurs dans une telle structure de données. Par exemple, pour le mode " +"d'entité POJO, le tuplizer correspondant sait comment créer le POJO à " +"travers son constructeur et comment accéder aux propriétés du POJO utilisant " +"les accesseurs de la propriété définie. " + +#. Tag: para +#, no-c-format +msgid "" +"There are two high-level types of Tuplizers, represented by the <literal>org." +"hibernate.tuple.entity.EntityTuplizer</literal> and <literal>org.hibernate." +"tuple.component.ComponentTuplizer</literal> interfaces. " +"<literal>EntityTuplizer</literal>s are responsible for managing the above " +"mentioned contracts in regards to entities, while " +"<literal>ComponentTuplizer</literal>s do the same for components." +msgstr "" +"Il y a deux types de Tuplizers de haut niveau, représentés par les " +"interfaces <literal>org.hibernate.tuple.EntityTuplizer</literal> et " +"<literal>org.hibernate.tuple.ComponentTuplizer</literal>. Les " +"<literal>EntityTuplizer</literal> s sont responsables de la gestion des " +"contrats mentionnés ci-dessus pour les entités, alors que les " +"<literal>ComponentTuplizer</literal> s s'occupent des composants." + +#. Tag: para +#, no-c-format +msgid "" +"Users can also plug in their own tuplizers. Perhaps you require that a " +"<literal>java.util.Map</literal> implementation other than <literal>java." +"util.HashMap</literal> be used while in the dynamic-map entity-mode. Or " +"perhaps you need to define a different proxy generation strategy than the " +"one used by default. Both would be achieved by defining a custom tuplizer " +"implementation. Tuplizer definitions are attached to the entity or component " +"mapping they are meant to manage. Going back to the example of our customer " +"entity:" +msgstr "" +"Les utilisateurs peuvent aussi brancher leurs propres tuplizers. Il vous " +"faudra peut-être utiliser une implémentation de <literal>java.util.Map</" +"literal> autre que <literal>java.util.HashMap</literal> dans le mode " +"d'entité dynamic-map ; ou peut-être aurez vous besoin de définir une " +"stratégie de génération de proxy différente de celle utilisée par défaut. " +"Les deux devraient être effectuées en définissant une implémentation de " +"tuplizer utilisateur. Les définitions de tuplizers sont attachées au mappage " +"de l'entité ou du composant qu'ils devraient gérer. Revenons à l'exemple de " +"notre entité utilisateur : " + +#. Tag: title +#, no-c-format +msgid "EntityNameResolvers" +msgstr "EntityNameResolvers" + +#. Tag: para +#, no-c-format +msgid "" +"The <interfacename>org.hibernate.EntityNameResolver</interfacename> " +"interface is a contract for resolving the entity name of a given entity " +"instance. The interface defines a single method " +"<methodname>resolveEntityName</methodname> which is passed the entity " +"instance and is expected to return the appropriate entity name (null is " +"allowed and would indicate that the resolver does not know how to resolve " +"the entity name of the given entity instance). Generally speaking, an " +"<interfacename>org.hibernate.EntityNameResolver</interfacename> is going to " +"be most useful in the case of dynamic models. One example might be using " +"proxied interfaces as your domain model. The hibernate test suite has an " +"example of this exact style of usage under the <package>org.hibernate.test." +"dynamicentity.tuplizer2</package>. Here is some of the code from that " +"package for illustration." +msgstr "" +"L'interface <interfacename>org.hibernate.EntityNameResolver</interfacename> " +"représente un contrat pour résoudre le nom de l'entité d'une instance " +"d'entité donnée. L'interface définit une méthode simple " +"<methodname>resolveEntityName</methodname>, à qui l'on passe l'instance " +"d'entité et qui doit retourner le nom d'entité qui convient (null est " +"accepté et indiquerait que le resolver ne sait pas comment résoudre le nom " +"de l'entité de l'instance d'entité donnée). Normalement, un " +"<interfacename>org.hibernate.EntityNameResolver</interfacename> est surtout " +"utile pour les modèles dynamiques. Vous pourriez, par exemple, utiliser des " +"interfaces proxy comme modèle de domaine. La suite de test Hibernate " +"comprend un exemple de ce style précis d'utilisation dans <package>org." +"hibernate.test.dynamicentity.tuplizer2</package>. Vous trouverez ci dessous " +"une illustration du code de ce package." + +#. Tag: para +#, no-c-format +msgid "" +"In order to register an <interfacename>org.hibernate.EntityNameResolver</" +"interfacename> users must either:" +msgstr "" +"Pour enregistrer un <interfacename>org.hibernate.EntityNameResolver</" +"interfacename>, les utilisateurs doivent soit :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Implement a custom <link linkend=\"persistent-classes-tuplizers\">Tuplizer</" +"link>, implementing the <methodname>getEntityNameResolvers</methodname> " +"method." +msgstr "" +"Implémenter un <xref linkend=\"persistent-classes-tuplizers\" /> " +"personnalisé, en implémentant la méthode <methodname>getEntityNameResolvers</" +"methodname>." + +#. Tag: para +#, no-c-format +msgid "" +"Register it with the <classname>org.hibernate.impl.SessionFactoryImpl</" +"classname> (which is the implementation class for <interfacename>org." +"hibernate.SessionFactory</interfacename>) using the " +"<methodname>registerEntityNameResolver</methodname> method." +msgstr "" +"L'enregistrer dans <classname>org.hibernate.impl.SessionFactoryImpl</" +"classname> (qui est la classe d'implémentation de <interfacename>org." +"hibernate.SessionFactory</interfacename>) à l'aide de la méthode " +"<methodname>registerEntityNameResolver</methodname>." Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/portability.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/portability.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/portability.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,384 @@ +# translation of portability.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: portability\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-03-25 06:26+0000\n" +"PO-Revision-Date: 2010-01-05 09:42+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#: portability.xml:31 +#, no-c-format +msgid "Database Portability Considerations" +msgstr "Considérations de portabilité des bases de données" + +#. Tag: title +#: portability.xml:34 +#, no-c-format +msgid "Portability Basics" +msgstr "Aspects fondamentaux de la portabilité" + +#. Tag: para +#: portability.xml:36 +#, no-c-format +msgid "" +"One of the selling points of Hibernate (and really Object/Relational Mapping " +"as a whole) is the notion of database portability. This could mean an " +"internal IT user migrating from one database vendor to another, or it could " +"mean a framework or deployable application consuming Hibernate to " +"simultaneously target multiple database products by their users. Regardless " +"of the exact scenario, the basic idea is that you want Hibernate to help you " +"run against any number of databases without changes to your code, and " +"ideally without any changes to the mapping metadata." +msgstr "" +"La portabilité des bases de données est un des atouts qui sont mis en avant " +"pour vendre Hibernate (et plus largement le mappage objet/relationnel dans " +"son ensemble). Il pourrait s'agir d'un utilisateur IT interne qui migre " +"d'une base de données de fournisseur vers une autre, ou il pourrait s'agir " +"d'un framework ou d'une application déployable consommant Hibernate pour " +"cibler simultanément plusieurs produits de base de données par leurs " +"utilisateurs. Quel que soit le scénario exact, l'idée de base est que vous " +"souhaitez que HIBERNATE vous permettre d'exécuter avec un certain nombre de " +"bases de données sans modifications à votre code et idéalement sans " +"modifications des métadonnées de mappage." + +#. Tag: title +#: portability.xml:47 +#, no-c-format +msgid "Dialect" +msgstr "Dialecte" + +#. Tag: para +#: portability.xml:49 +#, no-c-format +msgid "" +"The first line of portability for Hibernate is the dialect, which is a " +"specialization of the <classname>org.hibernate.dialect.Dialect</classname> " +"contract. A dialect encapsulates all the differences in how Hibernate must " +"communicate with a particular database to accomplish some task like getting " +"a sequence value or structuring a SELECT query. Hibernate bundles a wide " +"range of dialects for many of the most popular databases. If you find that " +"your particular database is not among them, it is not terribly difficult to " +"write your own." +msgstr "" +"La première ligne de la portabilité d'Hibernate est le dialecte, qui est une " +"spécialisation du contrat <classname>org.Hibernate.dialect.dialect</" +"classname>. Un dialecte encapsule toutes les différences selon lesquelles " +"Hibernate doit communiquer avec une base de données particulière pour " +"accomplir certaines tâches comme l'obtention d'une valeur de la séquence ou " +"de structuration d'une requête SELECT. Hibernate regroupe un large éventail " +"de dialectes pour la plupart des bases de données les plus communes. Si vous " +"trouvez que votre base de données particulière n'en fait pas partie, il " +"n'est pas difficile d'écrire votre propre dialecte." + +#. Tag: title +#: portability.xml:60 +#, no-c-format +msgid "Dialect resolution" +msgstr "Résolution de dialecte" + +#. Tag: para +#: portability.xml:62 +#, no-c-format +msgid "" +"Originally, Hibernate would always require that users specify which dialect " +"to use. In the case of users looking to simultaneously target multiple " +"databases with their build that was problematic. Generally this required " +"their users to configure the Hibernate dialect or defining their own method " +"of setting that value." +msgstr "" +"À l'origine, Hibernate exigeait toujours que les utilisateurs spécifient " +"quel dialecte utiliser. Dans le cas des utilisateurs qui cherchent à cibler " +"simultanément plusieurs bases de données avec leur version, c'était " +"problématique. Généralement cela amenait leurs utilisateurs à configurer le " +"dialecte Hibernate ou à définir leur propre méthode de définition de cette " +"valeur." + +#. Tag: para +#: portability.xml:69 +#, no-c-format +msgid "" +"Starting with version 3.2, Hibernate introduced the notion of automatically " +"detecting the dialect to use based on the <interfacename>java.sql." +"DatabaseMetaData</interfacename> obtained from a <interfacename>java.sql." +"Connection</interfacename> to that database. This was much better, expect " +"that this resolution was limited to databases Hibernate know about ahead of " +"time and was in no way configurable or overrideable." +msgstr "" +"A partir de la version 3.2, Hibernate a introduit la détection " +"automatiquement du dialecte à utiliser basé sur les <interfacename>Java.SQL." +"DatabaseMetaData</interfacename> obtenues à partir d'un <interfacename>Java." +"SQL.Connexion</interfacename> vers cette base de données. C'était beaucoup " +"mieux, sauf que cette résolution a été limitée aux bases de données déjà " +"connues d'Hibernate et elle n'était ni configurable, ni remplaçable." + +#. Tag: para +#: portability.xml:77 +#, fuzzy, no-c-format +msgid "" +"Starting with version 3.3, Hibernate has a fare more powerful way to " +"automatically determine which dialect to should be used by relying on a " +"series of delegates which implement the <interfacename>org.hibernate.dialect." +"resolver.DialectResolver</interfacename> which defines only a single method:" +"<programlisting role=\"JAVA\"><![CDATA[public Dialect resolveDialect" +"(DatabaseMetaData metaData) throws JDBCConnectionException]]></" +"programlisting>. The basic contract here is that if the resolver " +"'understands' the given database metadata then it returns the corresponding " +"Dialect; if not it returns null and the process continues to the next " +"resolver. The signature also identifies <exceptionname>org.hibernate." +"exception.JDBCConnectionException</exceptionname> as possibly being thrown. " +"A JDBCConnectionException here is interpreted to imply a \"non transient" +"\" (aka non-recoverable) connection problem and is used to indicate an " +"immediate stop to resolution attempts. All other exceptions result in a " +"warning and continuing on to the next resolver." +msgstr "" +"A partir de la version 3.3, Hibernate a un moyen bien plus puissant de " +"déterminer automatiquement quel dialecte devrait être utilisé en s'appuyant " +"sur une série de délégués qui implémentent le <interfacename>org.hibernate." +"dialect.resolver.DialectResolver</interfacename>. Le résolveur ne définit " +"qu'une seule méthode :<programlisting>public Dialect resolveDialect" +"(DatabaseMetaData metaData) throws JDBCConnectionException</programlisting>. " +"Le contrat de base ici est que si le résolveur 'comprend' les métadonnées de " +"base de données, alors il renvoie le dialecte correspondant ; si non, il " +"renvoie la valeur null et le processus se poursuit avec le prochain " +"résolveur. La signature identifie également l'envoi éventuel de l'exception " +"<exceptionname>org.hibernate.exception.JDBCConnectionException</" +"exceptionname>. Une JDBCConnectionException ici implique un problème de " +"connexion \"non transient\" (aka non récupérable) et est utilisé pour " +"indiquer un arrêt immédiat à des tentatives de résolution. Toutes les autres " +"exceptions entraînent un avertissement et de passer à la résolution suivante." + +#. Tag: para +#: portability.xml:90 +#, no-c-format +msgid "" +"The cool part about these resolvers is that users can also register their " +"own custom resolvers which will be processed ahead of the built-in Hibernate " +"ones. This might be useful in a number of different situations: it allows " +"easy integration for auto-detection of dialects beyond those shipped with " +"HIbernate itself; it allows you to specify to use a custom dialect when a " +"particular database is recognized; etc. To register one or more resolvers, " +"simply specify them (seperated by commas, tabs or spaces) using the " +"'hibernate.dialect_resolvers' configuration setting (see the " +"<constant>DIALECT_RESOLVERS</constant> constant on <classname>org.hibernate." +"cfg.Environment</classname>)." +msgstr "" +"Le bon côté de ces outils de résolution, c'est que les utilisateurs peuvent " +"également enregistrer leurs propres outils de résolution personnalisés, qui " +"seront traités avant les résolveurs Hibernate intégrés. Cette option peut " +"être utile dans un certain nombre de situations différentes : elle permet " +"une intégration aisée pour la détection automatique des dialectes au-delà de " +"ceux qui sont livrés avec Hibernate lui-même ; elle vous permet de spécifier " +"d'utiliser un dialecte personnalisé lorsqu'une base de données particulière " +"est reconnue ; etc.. Pour enregistrer un ou plusieurs outils de résolution, " +"il vous suffit de les spécifier (séparés par des virgules, des onglets ou " +"des espaces) à l'aide du paramètre de configuration 'hibernate." +"dialect_resolvers' (voir la constante <constant>DIALECT_RESOLVERS</constant> " +"sur <classname>cfg.Environment org.Hibernate.</classname>)." + +#. Tag: title +#: portability.xml:103 +#, no-c-format +msgid "Identifier generation" +msgstr "Générer les identifiants" + +#. Tag: para +#: portability.xml:105 +#, fuzzy, no-c-format +msgid "" +"When considering portability between databases, another important decision " +"is selecting the identifier generation stratagy you want to use. Originally " +"Hibernate provided the <emphasis>native</emphasis> generator for this " +"purpose, which was intended to select between a <emphasis>sequence</" +"emphasis>, <emphasis>identity</emphasis>, or <emphasis>table</emphasis> " +"strategy depending on the capability of the underlying database. However, an " +"insidious implication of this approach comes about when targtetting some " +"databases which support <emphasis>identity</emphasis> generation and some " +"which do not. <emphasis>identity</emphasis> generation relies on the SQL " +"definition of an IDENTITY (or auto-increment) column to manage the " +"identifier value; it is what is known as a post-insert generation strategy " +"becauase the insert must actually happen before we can know the identifier " +"value. Because Hibernate relies on this identifier value to uniquely " +"reference entities within a persistence context it must then issue the " +"insert immediately when the users requests the entitiy be associated with " +"the session (like via save() e.g.) regardless of current transactional " +"semantics. <note> <para> Hibernate was changed slightly once the implication " +"of this was better understood so that the insert is delayed in cases where " +"that is feasible. </para> </note> The underlying issue is that the actual " +"semanctics of the application itself changes in these cases." +msgstr "" +"Quand on considère la portabilité entre les bases de données, la sélection " +"de stratégie de génération d'identifiant à utiliser est une autre décision " +"importante. Initialement, Hibernate fournissait le générateur " +"<emphasis>natif</emphasis> à cette fin, dans le but de choisir entre une " +"stratégie <emphasis>séquence</emphasis>, <emphasis>identité</emphasis>, ou " +"<emphasis>table</emphasis> suivant la capacité de la base de données sous-" +"jacente. Toutefois, une implication insidieuse de cette approche surgit au " +"moment de cibler certaines bases de données entre celles qui prennent en " +"charge la génération d' <emphasis>identité</emphasis> et celles qui ne la " +"prenne pas. La génération d'<emphasis>identité</emphasis> s'appuie sur la " +"définition SQL d'une colonne IDENTITY (ou auto-incrémentation) pour gérer la " +"valeur d'identificateur ; c'est ce qui est connu sous le nom de stratégie de " +"génération car l'insersion doit effectivement avoir lieu avant que nous " +"puissions connaître la valeur de l'identifiant. Étant donné qu'Hibernate " +"repose sur la valeur de cet identifiant pour indentifier les entités de " +"façon unique dans un contexte de persistance, il doit alors émettre " +"l'insertion immédiatement, quand les utilisateurs demandent que l'entité " +"soit associée à la session (comme par exemple, via save()) indépendamment de " +"la sémantique transactionnelle actuelle. La question sous-jacente est que la " +"sémantique de l'application elle-même change dans ces cas." + +#. Tag: para +#: portability.xml:130 +#, no-c-format +msgid "" +"Starting with version 3.2.3, Hibernate comes with a set of <ulink url=" +"\"http://in.relation.to/2082.lace\">enhanced</ulink> identifier generators " +"targetting portability in a much different way. <note> <para> There are " +"specifically 2 bundled <emphasis>enhanced</emphasis>generators: " +"<itemizedlist> <listitem> <para> <classname>org.hibernate.id.enhanced." +"SequenceStyleGenerator</classname> </para> </listitem> <listitem> <para> " +"<classname>org.hibernate.id.enhanced.TableGenerator</classname> </para> </" +"listitem> </itemizedlist> </para> </note> The idea behind these generators " +"is to port the actual semantics of the identifer value generation to the " +"different databases. For example, the <classname>org.hibernate.id.enhanced." +"SequenceStyleGenerator</classname> mimics the behavior of a sequence on " +"databases which do not support sequences by using a table." +msgstr "" + +#. Tag: title +#: portability.xml:159 +#, no-c-format +msgid "Database functions" +msgstr "Fonctions de base de données" + +#. Tag: para +#: portability.xml:162 +#, no-c-format +msgid "" +"This is an area in Hibernate in need of improvement. In terms of portability " +"concerns, this function handling currently works pretty well from HQL; " +"however, it is quite lacking in all other aspects." +msgstr "" + +#. Tag: para +#: portability.xml:169 +#, fuzzy, no-c-format +msgid "" +"SQL functions can be referenced in many ways by users. However, not all " +"databases support the same set of functions. Hibernate, provides a means of " +"mapping a <emphasis>logical</emphasis> function name to a delegate which " +"knows how to render that particular function, perhaps even using a totally " +"different physical function call." +msgstr "" +"Les fonctions SQL peuvent être référencées de bien des façons par les " +"utilisateurs. Cependant, toutes les bases de données ne supportent pas le " +"même groupe de fonctions. Hibernate procure une façon de faire correspondre " +"un nom de fonction <emphasis>logique</emphasis> à un délégué qui sait " +"comment traduire cette fonction particulière, peut-être en utilisant un " +"appel de fonction physique totalement différente." + +#. Tag: para +#: portability.xml:175 +#, no-c-format +msgid "" +"Technically this function registration is handled through the <classname>org." +"hibernate.dialect.function.SQLFunctionRegistry</classname> class which is " +"intended to allow users to provide custom function definitions without " +"having to provide a custom dialect. This specific behavior is not fully " +"completed as of yet." +msgstr "" +"Techniquement, cet enregistrement de la fonction est géré par le biais de la " +"classe <classname>hibernate.dialect.function.SQLFunctionRegistry org.</" +"classname> qui est destinée à permettre aux utilisateurs de fournir des " +"définitions de fonction personnalisée sans avoir à fournir un dialecte " +"personnalisé. Ce comportement spécifique n'est pas encore entièrement " +"terminé." + +#. Tag: para +#: portability.xml:182 +#, no-c-format +msgid "" +"It is sort of implemented such that users can programatically register " +"functions with the <classname>org.hibernate.cfg.Configuration</classname> " +"and those functions will be recognized for HQL." +msgstr "" +"Il est mis en oeuvre de telle sorte que les utilisateurs peuvent enregistrer " +"des fonctions par programmation avec <classname>org.Hibernate.cfg." +"Configuration</classname> et ces fonctions seront reconnues pour HQL." + +#. Tag: title +#: portability.xml:192 +#, no-c-format +msgid "Type mappings" +msgstr "" + +#. Tag: para +#: portability.xml:194 +#, no-c-format +msgid "This section scheduled for completion at a later date..." +msgstr "" + +#, fuzzy +#~ msgid "" +#~ "Hibernate was changed slightly once the implication of this was better " +#~ "understood so that the insert is delayed in cases where that is feasible." +#~ msgstr "" +#~ "Hibernate a été amélioré de façon à ce que l'insertion puisse être " +#~ "retardée quand c'est possible." + +#~ msgid "" +#~ "Starting with version 3.2.3, Hibernate comes with a set of <ulink url=" +#~ "\"http://in.relation.to/2082.lace\">enhanced</ulink> identifier " +#~ "generators targetting portability in a much different way." +#~ msgstr "" +#~ "A partir de la version 3.2.3, Hibernate est fourni avec un ensemble de " +#~ "générateurs d'identifiants <ulink url=\"http://in.relation.to/2082.lace" +#~ "\">améliorés</ulink>qui ciblent la portabilité d'une façon très " +#~ "différente." + +#~ msgid "" +#~ "There are specifically 2 bundled <emphasis>enhanced</emphasis>generators:" +#~ msgstr "" +#~ "Il existe 2 générateurs <emphasis>améliorés</emphasis> spécifiques qui " +#~ "sont livrés." + +#, fuzzy +#~ msgid "" +#~ "<classname>org.hibernate.id.enhanced.SequenceStyleGenerator</classname>" +#~ msgstr "" +#~ "<classname>org.hibernate.id.enhanced.SequenceStyleGenerator</classname>" + +#, fuzzy +#~ msgid "<classname>org.hibernate.id.enhanced.TableGenerator</classname>" +#~ msgstr "<classname>org.hibernate.id.enhanced.TableGenerator</classname>" + +#~ msgid "" +#~ "The idea behind these generators is to port the actual semantics of the " +#~ "identifer value generation to the different databases. For example, the " +#~ "<classname>org.hibernate.id.enhanced.SequenceStyleGenerator</classname> " +#~ "mimics the behavior of a sequence on databases which do not support " +#~ "sequences by using a table." +#~ msgstr "" +#~ "L'idée qui se cache là derrière, c'est de porter la sémantique de la " +#~ "génération de la valeur d'identifiant vers les bases de données diverses. " +#~ "Ainsi, <classname>org.hibernate.id.enhanced.SequenceStyleGenerator</" +#~ "classname> imite le comportement d'une séquence de databases, ne " +#~ "supportant pas les séquences par une table." + +#~ msgid "" +#~ "This is a new area in Hibernate and as such it is not as mature as the " +#~ "overall Hibernate experience." +#~ msgstr "" +#~ "Il s'agit d'une nouveau domaine pour Hibernate, et de ce fait, n'a pas " +#~ "encore atteint une maturité." Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/preface.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/preface.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/preface.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,195 @@ +# translation of Preface.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: Preface\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:43+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Preface" +msgstr "Préface" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Working with object-oriented software and a relational database can be " +"cumbersome and time consuming in today's enterprise environments. Hibernate " +"is an Object/Relational Mapping tool for Java environments. The term Object/" +"Relational Mapping (ORM) refers to the technique of mapping a data " +"representation from an object model to a relational data model with a SQL-" +"based schema." +msgstr "" +"Travailler avec des logiciels orientés-objet et une base de données " +"relationnelle peut sembler parfois lourd et coûteux en temps dans les " +"environnements entreprise de nos jours. Hibernate est un outil de mappage " +"objet/relationnel pour les environnements Java. Le terme de mappage objet/" +"relationnel (ORM de l'anglais Objet Relational Mapping) fait référence à la " +"technique de mappage d'une représentation de données à partir d'un modèle " +"d'objet vers un modèle de données relationnelles dans un schéma basé-SQL." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate not only takes care of the mapping from Java classes to database " +"tables (and from Java data types to SQL data types), but also provides data " +"query and retrieval facilities. It can also significantly reduce development " +"time otherwise spent with manual data handling in SQL and JDBC." +msgstr "" +"Hibernate s'occupe du mappage des classes Java vers les tables de bases de " +"données (et des types de données Java vers les types de données SQL), mais " +"fournit également des facilités de recherche et de retrait de données. " +"Hibernate peut réduire énormément le temps de développement, normalement " +"passé à traiter des données manuellement dans SQL ou JDBC." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate's goal is to relieve the developer from 95 percent of common data " +"persistence related programming tasks. Hibernate may not be the best " +"solution for data-centric applications that only use stored-procedures to " +"implement the business logic in the database, it is most useful with object-" +"oriented domain models and business logic in the Java-based middle-tier. " +"However, Hibernate can certainly help you to remove or encapsulate vendor-" +"specific SQL code and will help with the common task of result set " +"translation from a tabular representation to a graph of objects." +msgstr "" +"Le but d'Hibernate est de libérer le développeur de 95 pour cent des tâches " +"de programmation liées à la persistance de données communes. Hibernate n'est " +"peut-être pas la meilleure solution pour les applications centrées-données " +"qui utilisent uniquement les procédures-stored pour implémenter la logique " +"métier dans la base de données. Cela est surtout utile avec les modèles de " +"domaines orientés-objet et la logique métier dans l'étape intermédiaire " +"basée Java. Malgré tout, Hibernate peut vous aider à supprimer ou à " +"encapsuler le code SQL propre à un distributeur et vous aidera à régler la " +"tâche commune qui consiste à transposer un ensemble de résultats à partir " +"d'un tableau de représentation vers un graphe d'objets. " + +#. Tag: para +#, no-c-format +msgid "" +"If you are new to Hibernate and Object/Relational Mapping or even Java, " +"please follow these steps:" +msgstr "" +"Si vous n'êtes pas familiarisé avec Hibernate et le mappage Objet/" +"Relationnel ou même Java, veuillez suivre les étapes suivantes :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Read <xref linkend=\"tutorial\" /> for a tutorial with step-by-step " +"instructions. The source code for the tutorial is included in the " +"distribution in the <literal>doc/reference/tutorial/</literal> directory." +msgstr "" +"Lisez <xref linkend=\"tutorial\" /> pour bénéficier d'un tutoriel avec des " +"instructions étape par étape. Le code source du tutoriel est inclus dans la " +"distribution du répertoire <literal>doc/reference/tutorial/</literal>. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Read <xref linkend=\"architecture\" /> to understand the environments where " +"Hibernate can be used." +msgstr "" +"Veuillez lire <xref linkend=\"architecture\" /> pour comprendre dans quels " +"environnements Hibernate peuvent-être utilisés." + +#. Tag: para +#, no-c-format +msgid "" +"View the <literal>eg/</literal> directory in the Hibernate distribution. It " +"contains a simple standalone application. Copy your JDBC driver to the " +"<literal>lib/</literal> directory and edit <literal>etc/hibernate." +"properties</literal>, specifying correct values for your database. From a " +"command prompt in the distribution directory, type <literal>ant eg</literal> " +"(using Ant), or under Windows, type <literal>build eg</literal>." +msgstr "" +"Veuillez consulter le répertoire <literal>eg/</literal> dans la distribution " +"Hibernate, qui contient une application autonome simple. Copier votre pilote " +"JDBC dans le répertoire <literal>lib/</literal> et éditez <literal>etc/" +"hibernate.properties</literal>, en spécifiant les valeurs qu'il faut dans " +"votre base de données. A partir d'une invite de commande du répertoire de " +"distribution, veuillez saisir <literal>ant eg</literal> (en utilisant Ant), " +"et sous Windows, tapez <literal>build eg</literal>." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Use this reference documentation as your primary source of information. " +"Consider reading <biblioref linkend=\"biblio-JPwH\"></biblioref> if you need " +"more help with application design, or if you prefer a step-by-step tutorial. " +"Also visit <ulink url=\"http://caveatemptor.hibernate.org\" /> and download " +"the example application from <biblioref linkend=\"biblio-JPwH\"></biblioref>." +msgstr "" +"Utiliser cette documentation de référence en tant que source primaire " +"d'information. Vous pourrez lire <emphasis>Hibernate in Action</emphasis> " +"(http://www.manning.com/bauer) si vous avez besoin d'aide supplémentaire au " +"niveau de la conception des applications ou si vous préférez un tutoriel " +"étape par étape. Aussi, veuillez consulter http://caveatemptor.hibernate.org " +"et décharger l'exemple d'application pour Hibernate en action." + +#. Tag: para +#, no-c-format +msgid "FAQs are answered on the Hibernate website." +msgstr "Les questions FAQ sont traitées sur le site Hibernate." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Links to third party demos, examples, and tutorials are maintained on the " +"Hibernate website." +msgstr "" +"Des démos de tierces parties, des exemples et des tutoriels sont accessibles " +"à partir du site Hibernate." + +#. Tag: para +#, no-c-format +msgid "" +"The Community Area on the Hibernate website is a good resource for design " +"patterns and various integration solutions (Tomcat, JBoss AS, Struts, EJB, " +"etc.)." +msgstr "" +"La section Community Area (Zône communautaire) du site Hibernate constitue " +"une ressource intéressante pour les modèles conceptuels et autres solutions " +"diverses d'intégration (Tomcat, JBoss AS, Struts, EJB, etc.)." + +#. Tag: para +#, no-c-format +msgid "" +"If you have questions, use the user forum linked on the Hibernate website. " +"We also provide a JIRA issue tracking system for bug reports and feature " +"requests. If you are interested in the development of Hibernate, join the " +"developer mailing list. If you are interested in translating this " +"documentation into your language, contact us on the developer mailing list." +msgstr "" +"Si vous avez des questions, participez au forum utilisateur sur le site " +"Hibernate. Nous proposons également des systèmes de traçage JIRA pour les " +"rapports de bogues et les demandes sur les fonctionalités. Si vous êtes " +"intéressé à participer au développement d'Hibernate, veuillez rejoindre la " +"liste de distribution électronique des développeurs. " + +#. Tag: para +#, no-c-format +msgid "" +"Commercial development support, production support, and training for " +"Hibernate is available through JBoss Inc. (see http://www.hibernate.org/" +"SupportTraining/). Hibernate is a Professional Open Source project and a " +"critical component of the JBoss Enterprise Middleware System (JEMS) suite of " +"products." +msgstr "" +"Le support pour le développement commercial, le support production, et la " +"formation Hibernate sont disponibles à travers JBoss Inc. (voir http://www." +"hibernate.org/SupportTraining/). Hibernate est un projet professionnel en " +"source ouverte et un composant critique de la suite de produits JBoss " +"Enterprise Middleware System (JEMS). " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_criteria.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_criteria.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_criteria.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,412 @@ +# translation of query_criteria.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: query_criteria\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:43+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Criteria Queries" +msgstr "Requêtes par critères" + +#. Tag: para +#, no-c-format +msgid "Hibernate features an intuitive, extensible criteria query API." +msgstr "" +"Hibernate offre une API d'interrogation par critères intuitive et extensible." + +#. Tag: title +#, no-c-format +msgid "Creating a <literal>Criteria</literal> instance" +msgstr "Créer une instance de <literal>Criteria</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"The interface <literal>org.hibernate.Criteria</literal> represents a query " +"against a particular persistent class. The <literal>Session</literal> is a " +"factory for <literal>Criteria</literal> instances." +msgstr "" +"L'interface <literal>net.sf.hibernate.Criteria</literal> représente une " +"requête sur une classe persistante donnée. La <literal>Session</literal> " +"fournit les instances de <literal>Criteria</literal>." + +#. Tag: title +#, no-c-format +msgid "Narrowing the result set" +msgstr "Restriction du résultat" + +#. Tag: para +#, no-c-format +msgid "" +"An individual query criterion is an instance of the interface <literal>org." +"hibernate.criterion.Criterion</literal>. The class <literal>org.hibernate." +"criterion.Restrictions</literal> defines factory methods for obtaining " +"certain built-in <literal>Criterion</literal> types." +msgstr "" +"Un critère de recherche (criterion) individuel est une instance de " +"l'interface <literal>org.hibernate.criterion.Criterion</literal>. La classe " +"<literal>org.hibernate.criterion.Restrictions</literal> définit des méthodes " +"de fabrique pour obtenir des types de <literal>Criterion</literal> intégrés." + +#. Tag: para +#, no-c-format +msgid "Restrictions can be grouped logically." +msgstr "Les restrictions peuvent être groupées de manière logique. " + +#. Tag: para +#, no-c-format +msgid "" +"There are a range of built-in criterion types (<literal>Restrictions</" +"literal> subclasses). One of the most useful allows you to specify SQL " +"directly." +msgstr "" +"Il y a un grand choix de types de critères intégrés (sous classes de " +"<literal>Restriction</literal>), dont un est particulièrement utile " +"puisqu'il vous permet de spécifier directement SQL." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>{alias}</literal> placeholder with be replaced by the row alias " +"of the queried entity." +msgstr "" +"La zone <literal>{alias}</literal> sera remplacée par l'alias de colonne de " +"l'entité que l'on souhaite interroger." + +#. Tag: para +#, no-c-format +msgid "" +"You can also obtain a criterion from a <literal>Property</literal> instance. " +"You can create a <literal>Property</literal> by calling <literal>Property." +"forName()</literal>:" +msgstr "" +"Une autre approche pour obtenir un critère est de le récupérer d'une " +"instance de <literal>Property</literal>. Vous pouvez créer une " +"<literal>Property</literal> en appelant <literal>Property.forName()</" +"literal>. " + +#. Tag: title +#, no-c-format +msgid "Ordering the results" +msgstr "Trier les résultats" + +#. Tag: para +#, no-c-format +msgid "" +"You can order the results using <literal>org.hibernate.criterion.Order</" +"literal>." +msgstr "" +"Vous pouvez trier les résultats en utilisant <literal>org.hibernate." +"criterion.Order</literal>. " + +#. Tag: title +#, no-c-format +msgid "Associations" +msgstr "Associations" + +#. Tag: para +#, no-c-format +msgid "" +"By navigating associations using <literal>createCriteria()</literal> you can " +"specify constraints upon related entities:" +msgstr "" +"En naviguant les associations qui utilisent <literal>createCriteria()</" +"literal>, vous pouvez spécifier des contraintes associées à des entités :" + +#. Tag: para +#, no-c-format +msgid "" +"The second <literal>createCriteria()</literal> returns a new instance of " +"<literal>Criteria</literal> that refers to the elements of the " +"<literal>kittens</literal> collection." +msgstr "" +"Notez que la seconde <literal>createCriteria()</literal> retourne une " +"nouvelle instance de <literal>Criteria</literal>, qui se rapporte aux " +"éléments de la collection <literal>kittens</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"There is also an alternate form that is useful in certain circumstances:" +msgstr "La forme alternative suivante est utile dans certains cas :" + +#. Tag: para +#, no-c-format +msgid "" +"(<literal>createAlias()</literal> does not create a new instance of " +"<literal>Criteria</literal>.)" +msgstr "" +"(<literal>createAlias()</literal> ne crée pas de nouvelle instance de " +"<literal>Criteria</literal>.)" + +#. Tag: para +#, no-c-format +msgid "" +"The kittens collections held by the <literal>Cat</literal> instances " +"returned by the previous two queries are <emphasis>not</emphasis> pre-" +"filtered by the criteria. If you want to retrieve just the kittens that " +"match the criteria, you must use a <literal>ResultTransformer</literal>." +msgstr "" +"Notez que les collections kittens contenues dans les instances de " +"<literal>Cat</literal> retournées par les deux précédentes requêtes ne sont " +"<emphasis>pas</emphasis> pré-filtrées par les critères ! Si vous souhaitez " +"récupérer uniquement les kittens correspondant aux critères, vous devez " +"utiliser <literal>ResultTransformer</literal>. " + +#. Tag: para +#, no-c-format +msgid "Additionally you may manipulate the result set using a left outer join:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"This will return all of the <literal>Cat</literal>s with a mate whose name " +"starts with \"good\" ordered by their mate's age, and all cats who do not " +"have a mate. This is useful when there is a need to order or limit in the " +"database prior to returning complex/large result sets, and removes many " +"instances where multiple queries would have to be performed and the results " +"unioned by java in memory." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"Without this feature, first all of the cats without a mate would need to be " +"loaded in one query." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"A second query would need to retreive the cats with mates who's name started " +"with \"good\" sorted by the mates age." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Thirdly, in memory; the lists would need to be joined manually." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Dynamic association fetching" +msgstr "Peuplement d'associations de manière dynamique" + +#. Tag: para +#, no-c-format +msgid "" +"You can specify association fetching semantics at runtime using " +"<literal>setFetchMode()</literal>." +msgstr "" +"Vous pouvez spécifier, au moment de l'exécution, le peuplement d'une " +"association en utilisant <literal>setFetchMode()</literal>." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"This query will fetch both <literal>mate</literal> and <literal>kittens</" +"literal> by outer join. See <xref linkend=\"performance-fetching\" /> for " +"more information." +msgstr "" +"Cette requête recherchera <literal>mate</literal> et <literal>kittens</" +"literal> via les jointures externes. Consultez <xref linkend=\"performance-" +"fetching\" /> pour plus d'informations." + +#. Tag: title +#, no-c-format +msgid "Example queries" +msgstr "Requêtes par l'exemple" + +#. Tag: para +#, no-c-format +msgid "" +"The class <literal>org.hibernate.criterion.Example</literal> allows you to " +"construct a query criterion from a given instance." +msgstr "" +"La classe <literal>org.hibernate.criterion.Example</literal> vous permet de " +"construire un critère de requête à partir d'une instance d'objet donnée." + +#. Tag: para +#, no-c-format +msgid "" +"Version properties, identifiers and associations are ignored. By default, " +"null valued properties are excluded." +msgstr "" +"Les propriétés de type version, identifiant et association sont ignorées. " +"Par défaut, les valeurs null sont exclues." + +#. Tag: para +#, no-c-format +msgid "You can adjust how the <literal>Example</literal> is applied." +msgstr "" +"Vous pouvez ajuster la stratégie d'utilisation de valeurs de " +"l'<literal>Exemple</literal>." + +#. Tag: para +#, no-c-format +msgid "You can even use examples to place criteria upon associated objects." +msgstr "" +"Vous pouvez utiliser les \"exemples\" pour des critères sur des objets " +"associés." + +#. Tag: title +#, no-c-format +msgid "Projections, aggregation and grouping" +msgstr "Projections, agrégation et regroupement" + +#. Tag: para +#, no-c-format +msgid "" +"The class <literal>org.hibernate.criterion.Projections</literal> is a " +"factory for <literal>Projection</literal> instances. You can apply a " +"projection to a query by calling <literal>setProjection()</literal>." +msgstr "" +"La classe <literal>org.hibernate.criterion.Projections</literal> est une " +"fabrique d'instances de <literal>Projection</literal>. Nous appliquons une " +"projection sur une requête en appelant <literal>setProjection()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"There is no explicit \"group by\" necessary in a criteria query. Certain " +"projection types are defined to be <emphasis>grouping projections</" +"emphasis>, which also appear in the SQL <literal>group by</literal> clause." +msgstr "" +"Il n'y a pas besoin de \"group by\" explicite dans une requête par critère. " +"Certains types de projection sont définis pour être des " +"<emphasis>projections de regroupement</emphasis>, qui apparaissent aussi " +"dans la clause SQL <literal>group by</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"An alias can be assigned to a projection so that the projected value can be " +"referred to in restrictions or orderings. Here are two different ways to do " +"this:" +msgstr "" +"Un alias peut optionnellement être assigné à une projection, ainsi la valeur " +"projetée peut être référencée dans des restrictions ou des tris. À cet " +"effet, voici deux procédés différents : " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>alias()</literal> and <literal>as()</literal> methods simply " +"wrap a projection instance in another, aliased, instance of " +"<literal>Projection</literal>. As a shortcut, you can assign an alias when " +"you add the projection to a projection list:" +msgstr "" +"Les méthodes <literal>alias()</literal> et <literal>as()</literal> " +"enveloppent simplement une instance de projection dans une autre instance " +"(aliasée) de <literal>Projection</literal>. Pour un raccourci, vous pouvez " +"assigner un alias lorsque vous ajoutez la projection à une liste de " +"projections :" + +#. Tag: para +#, no-c-format +msgid "" +"You can also use <literal>Property.forName()</literal> to express " +"projections:" +msgstr "" +"Vous pouvez aussi utiliser <literal>Property.forName()</literal> pour " +"formuler des projections :" + +#. Tag: title +#, no-c-format +msgid "Detached queries and subqueries" +msgstr "Requêtes et sous-requêtes détachées" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>DetachedCriteria</literal> class allows you to create a query " +"outside the scope of a session and then execute it using an arbitrary " +"<literal>Session</literal>." +msgstr "" +"La classe <literal>DetachedCriteria</literal> vous laisse créer une requête " +"en dehors de la portée de la session, et puis l'exécuter plus tard en " +"utilisant une <literal>Session</literal> arbitraire. " + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>DetachedCriteria</literal> can also be used to express a " +"subquery. Criterion instances involving subqueries can be obtained via " +"<literal>Subqueries</literal> or <literal>Property</literal>." +msgstr "" +"Les <literal>DetachedCriteria</literal> peuvent aussi être utilisés pour " +"exprimer une sous-requête. Des instances de critère impliquant des sous-" +"requêtes peuvent être obtenues via <literal>Subqueries</literal> ou " +"<literal>Property</literal>. " + +#. Tag: para +#, no-c-format +msgid "Correlated subqueries are also possible:" +msgstr "Des sous-requêtes corrélées sont également possibles :" + +#. Tag: title +#, no-c-format +msgid "Queries by natural identifier" +msgstr "Requêtes par identifiant naturel" + +#. Tag: para +#, no-c-format +msgid "" +"For most queries, including criteria queries, the query cache is not " +"efficient because query cache invalidation occurs too frequently. However, " +"there is a special kind of query where you can optimize the cache " +"invalidation algorithm: lookups by a constant natural key. In some " +"applications, this kind of query occurs frequently. The criteria API " +"provides special provision for this use case." +msgstr "" +"Pour la plupart des requêtes, incluant les requêtes par critère, le cache de " +"requêtes n'est pas très efficace, parce que l'invalidation du cache de " +"requêtes arrive trop souvent. Cependant, il y existe une requête spéciale où " +"l'on peut optimiser l'algorithme d'invalidation du cache : les recherches " +"par une clef naturelle constante. Dans certaines applications, ce genre de " +"requête se produit fréquemment. L'API des critères fournit une disposition " +"spéciale pour ce cas d'utilisation. " + +#. Tag: para +#, no-c-format +msgid "" +"First, map the natural key of your entity using <literal>&lt;natural-id&gt;</" +"literal> and enable use of the second-level cache." +msgstr "" +"D'abord, vous devrez mapper la clé naturelle de votre entité en utilisant " +"<literal>&lt;natural-id&gt;</literal>, et activer l'utilisation du cache de " +"second niveau." + +#. Tag: para +#, no-c-format +msgid "" +"This functionality is not intended for use with entities with " +"<emphasis>mutable</emphasis> natural keys." +msgstr "" +"Cette fonctionnalité n'est pas prévue pour l'utilisation avec des entités " +"avec des clés naturelles <emphasis>mutables</emphasis>." + +#. Tag: para +#, no-c-format +msgid "" +"Once you have enabled the Hibernate query cache, the <literal>Restrictions." +"naturalId()</literal> allows you to make use of the more efficient cache " +"algorithm." +msgstr "" +"Une fois que vous aurez activé le cache de requête d'Hibernate, " +"<literal>Restrictions.naturalId()</literal> vous permettra de rendre " +"l'utilisation de l'algorithme de cache plus efficace." Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_hql.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_hql.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_hql.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1471 @@ +# translation of query_hql.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: query_hql\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:15\n" +"PO-Revision-Date: 2010-01-05 09:46+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "HQL: The Hibernate Query Language" +msgstr "HQL : langage d'interrogation d'Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate uses a powerful query language (HQL) that is similar in appearance " +"to SQL. Compared with SQL, however, HQL is fully object-oriented and " +"understands notions like inheritance, polymorphism and association." +msgstr "" +"Hibernate fournit un langage d'interrogation extrêmement puissant qui " +"ressemble (et c'est voulu) au SQL. Mais ne soyez pas dupe de la syntaxe ; " +"HQL est totalement orienté objet, cernant des notions comme l'héritage, le " +"polymorphisme et les associations. " + +#. Tag: title +#, no-c-format +msgid "Case Sensitivity" +msgstr "Sensibilité à la casse" + +#. Tag: para +#, no-c-format +msgid "" +"With the exception of names of Java classes and properties, queries are case-" +"insensitive. So <literal>SeLeCT</literal> is the same as <literal>sELEct</" +"literal> is the same as <literal>SELECT</literal>, but <literal>org." +"hibernate.eg.FOO</literal> is not <literal>org.hibernate.eg.Foo</literal>, " +"and <literal>foo.barSet</literal> is not <literal>foo.BARSET</literal>." +msgstr "" +"Les requêtes sont insensibles à la casse, à l'exception des noms de classes " +"Java et des propriétés. Ainsi, <literal>SeLeCT</literal> est identique à " +"<literal>sELEct</literal> et à <literal>SELECT</literal> mais <literal>net." +"sf.hibernate.eg.FOO</literal> n'est pas identique <literal>net.sf.hibernate." +"eg.Foo</literal> et <literal>foo.barSet</literal> n'est pas identique à " +"<literal>foo.BARSET</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"This manual uses lowercase HQL keywords. Some users find queries with " +"uppercase keywords more readable, but this convention is unsuitable for " +"queries embedded in Java code." +msgstr "" +"Ce guide utilise les mots clés HQL en minuscules. Certains utilisateurs " +"trouvent les requêtes écrites avec les mots clés en majuscules plus " +"lisibles, mais nous trouvons cette convention pénible lorsqu'elle est lue " +"dans du code Java. " + +#. Tag: title +#, no-c-format +msgid "The from clause" +msgstr "La clause from" + +#. Tag: para +#, no-c-format +msgid "The simplest possible Hibernate query is of the form:" +msgstr "La requête Hibernate la plus simple est de la forme :" + +#. Tag: para +#, no-c-format +msgid "" +"This returns all instances of the class <literal>eg.Cat</literal>. You do " +"not usually need to qualify the class name, since <literal>auto-import</" +"literal> is the default. For example:" +msgstr "" +"Retourne toutes les instances de la classe <literal>eg.Cat</literal>. Nous " +"n'avons pas besoin de qualifier le nom de la classe, puisque <literal>auto-" +"import</literal> est la valeur par défaut. Donc nous écrivons presque " +"toujours :" + +#. Tag: para +#, no-c-format +msgid "" +"In order to refer to the <literal>Cat</literal> in other parts of the query, " +"you will need to assign an <emphasis>alias</emphasis>. For example:" +msgstr "" +"Pour pouvoir nous référer à <literal>Cat</literal> dans des autres parties " +"de la requête, vous aurez besoin d'y assigner un <emphasis>alias</emphasis>. " +"Ainsi :" + +#. Tag: para +#, no-c-format +msgid "" +"This query assigns the alias <literal>cat</literal> to <literal>Cat</" +"literal> instances, so you can use that alias later in the query. The " +"<literal>as</literal> keyword is optional. You could also write:" +msgstr "" +"Cette requête assigne l'alias <literal>cat</literal> à l'instance " +"<literal>Cat</literal>, nous pouvons donc utiliser cet alias ailleurs dans " +"la requête. Le mot clé <literal>as</literal> est optionnel. Nous aurions pu " +"écrire :" + +#. Tag: para +#, no-c-format +msgid "" +"Multiple classes can appear, resulting in a cartesian product or \"cross\" " +"join." +msgstr "" +"Plusieurs classes peuvent apparaître, ce qui conduira à un produit cartésien " +"(encore appelé jointures croisées). " + +#. Tag: para +#, no-c-format +msgid "" +"It is good practice to name query aliases using an initial lowercase as this " +"is consistent with Java naming standards for local variables (e.g. " +"<literal>domesticCat</literal>)." +msgstr "" +"C'est une bonne pratique que de nommer les alias dans les requêtes en " +"utilisant l'initiale en miniscule, ce qui correspond aux standards de " +"nommage Java pour les variables locales (par ex. <literal>domesticCat</" +"literal>)." + +#. Tag: title +#, no-c-format +msgid "Associations and joins" +msgstr "Associations et jointures" + +#. Tag: para +#, no-c-format +msgid "" +"You can also assign aliases to associated entities or to elements of a " +"collection of values using a <literal>join</literal>. For example:" +msgstr "" +"On peut aussi assigner des alias à des entités associées, ou même aux " +"éléments d'une collection de valeurs, en utilisant un <literal>join</" +"literal> (jointure). Par exemple :" + +#. Tag: para +#, no-c-format +msgid "The supported join types are borrowed from ANSI SQL:" +msgstr "Les types de jointures supportées sont empruntées de ANSI SQL :" + +#. Tag: para +#, no-c-format +msgid "<literal>inner join</literal>" +msgstr "<literal>inner join</literal> (jointure interne)" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>left outer join</literal>" +msgstr "<literal>inner join</literal> (jointure interne)" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>right outer join</literal>" +msgstr "<literal>inner join</literal> (jointure interne)" + +#. Tag: para +#, no-c-format +msgid "<literal>full join</literal> (not usually useful)" +msgstr "" +"<literal>full join</literal> (jointure ouverte totalement - généralement " +"inutile)" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>inner join</literal>, <literal>left outer join</literal> and " +"<literal>right outer join</literal> constructs may be abbreviated." +msgstr "" +"Les constructions des jointures <literal>inner join</literal>, <literal>left " +"outer join</literal> et <literal>right outer join</literal> peuvent être " +"abrégées." + +#. Tag: para +#, no-c-format +msgid "" +"You may supply extra join conditions using the HQL <literal>with</literal> " +"keyword." +msgstr "" +"Nous pouvons soumettre des conditions de jointure supplémentaires en " +"utilisant le mot-clef HQL <literal>with</literal>." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"A \"fetch\" join allows associations or collections of values to be " +"initialized along with their parent objects using a single select. This is " +"particularly useful in the case of a collection. It effectively overrides " +"the outer join and lazy declarations of the mapping file for associations " +"and collections. See <xref linkend=\"performance-fetching\" /> for more " +"information." +msgstr "" +"Par ailleurs, une jointure \"fetch\" (rapportée) permet d'initialiser les " +"associations ou collections de valeurs en même temps que leurs objets " +"parents, en utilisant qu'un seul Select. Ceci est particulièrement utile " +"dans le cas des collections. Ce système permet de surcharger les " +"déclarations \"lazy\" et \"outer-join\" des fichiers de mapping pour les " +"associations et collections. Consultez <xref linkend=\"performance-fetching" +"\" /> pour plus d'informations." + +#. Tag: para +#, no-c-format +msgid "" +"A fetch join does not usually need to assign an alias, because the " +"associated objects should not be used in the <literal>where</literal> clause " +"(or any other clause). The associated objects are also not returned directly " +"in the query results. Instead, they may be accessed via the parent object. " +"The only reason you might need an alias is if you are recursively join " +"fetching a further collection:" +msgstr "" +"Une jointure \"fetch\" (rapportée) n'a généralement pas besoin de se voir " +"assigner un alias puisque les objets associés ne doivent pas être utilisés " +"dans la clause <literal>where</literal> ou toute autre clause. Notez aussi " +"que les objets associés ne sont pas retournés directement dans le résultat " +"de la requête mais l'on peut y accéder via l'objet parent. La seule raison " +"pour laquelle nous pourrions avoir besoin d'un alias est si nous récupérons " +"récursivement une collection supplémentaire :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>fetch</literal> construct cannot be used in queries called " +"using <literal>iterate()</literal> (though <literal>scroll()</literal> can " +"be used). <literal>Fetch</literal> should be used together with " +"<literal>setMaxResults()</literal> or <literal>setFirstResult()</literal>, " +"as these operations are based on the result rows which usually contain " +"duplicates for eager collection fetching, hence, the number of rows is not " +"what you would expect. <literal>Fetch</literal> should also not be used " +"together with impromptu <literal>with</literal> condition. It is possible to " +"create a cartesian product by join fetching more than one collection in a " +"query, so take care in this case. Join fetching multiple collection roles " +"can produce unexpected results for bag mappings, so user discretion is " +"advised when formulating queries in this case. Finally, note that " +"<literal>full join fetch</literal> and <literal>right join fetch</literal> " +"are not meaningful." +msgstr "" +"Notez que la construction de <literal>fetch</literal> ne peut pas être " +"utilisée dans les requêtes appelées par <literal>scroll()</literal> ou " +"<literal>iterate()</literal>. De même <literal>Fetch</literal> ne devrait " +"pas être utilisé avec <literal>setMaxResults()</literal> ou " +"<literal>setFirstResult()</literal>, ces opérations étant basées sur le " +"nombre de résultats contenant généralement des doublons dès que des " +"collections sont chargées agressivement, par conséquent le nombre de lignes " +"est imprévisible. <literal>Fetch</literal> ne peut pas non plus être utilisé " +"avec une condition <literal>with</literal> ad hoc. Il est possible de créer " +"un produit cartésien par jointure en récupérant plus d'une collection dans " +"une requête, donc faites attention dans ce cas. Récupérer par jointure de " +"multiples collections donne aussi parfois des résultats inattendus pour des " +"mappages de sac, donc soyez prudent lorsque vous formulez vos requêtes dans " +"de tels cas. Finalement, notez que <literal>full join fetch</literal> et " +"<literal>right join fetch</literal> ne sont pas utiles en général." + +#. Tag: para +#, no-c-format +msgid "" +"If you are using property-level lazy fetching (with bytecode " +"instrumentation), it is possible to force Hibernate to fetch the lazy " +"properties in the first query immediately using <literal>fetch all " +"properties</literal>." +msgstr "" +"Si vous utilisez un chargement retardé pour les propriétés (avec une " +"instrumentation par bytecode), il est possible de forcer Hibernate à " +"récupérer les propriétés non encore chargées immédiatement (dans la première " +"requête) en utilisant <literal>fetch all properties</literal>. " + +#. Tag: title +#, no-c-format +msgid "Forms of join syntax" +msgstr "Formes de syntaxes pour les jointures" + +#. Tag: para +#, no-c-format +msgid "" +"HQL supports two forms of association joining: <literal>implicit</literal> " +"and <literal>explicit</literal>." +msgstr "" +"HQL supporte deux formes pour joindre les associations : <literal>implicit</" +"literal> et <literal>explicit</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"The queries shown in the previous section all use the <literal>explicit</" +"literal> form, that is, where the join keyword is explicitly used in the " +"from clause. This is the recommended form." +msgstr "" +"Les requêtes présentes dans la section précédente utilisent la forme " +"<literal>explicit</literal> où le mot clé join est explicitement utilisé " +"dans la clause from. C'est la forme recommandée. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>implicit</literal> form does not use the join keyword. Instead, " +"the associations are \"dereferenced\" using dot-notation. <literal>implicit</" +"literal> joins can appear in any of the HQL clauses. <literal>implicit</" +"literal> join result in inner joins in the resulting SQL statement." +msgstr "" +"La forme <literal>implicit</literal> n'utilise pas le mot clé join. En " +"revanche, les associations sont \"déréférencées\" en utilisant la notation. " +"Ces jointures <literal>implicit</literal> peuvent apparaître dans toutes les " +"clauses HQL. Les jointures <literal>implicit</literal> résultent en des " +"jointures internes dans le SQL généré." + +#. Tag: title +#, no-c-format +msgid "Referring to identifier property" +msgstr "Faire référence à la propriété identifiant " + +#. Tag: para +#, no-c-format +msgid "There are 2 ways to refer to an entity's identifier property:" +msgstr "" +"Il y a en général deux façons de faire référence à une propriété " +"d'identifiant d'une entité :" + +#. Tag: para +#, no-c-format +msgid "" +"The special property (lowercase) <literal>id</literal> may be used to " +"reference the identifier property of an entity <emphasis>provided that the " +"entity does not define a non-identifier property named id</emphasis>." +msgstr "" +"La propriété particulière (minuscule) <literal>id</literal> peut être " +"utilisée pour référencer la propriété d'identifiant d'une entité " +"<emphasis>du moment que l'entité ne définisse pas une propriété de non-" +"identifiant appelée id</emphasis>." + +#. Tag: para +#, no-c-format +msgid "" +"If the entity defines a named identifier property, you can use that property " +"name." +msgstr "" +"Si l'identité définit une propriété d'identifiant nommée, vous pouvez " +"utiliser ce nom de propriété." + +#. Tag: para +#, no-c-format +msgid "" +"References to composite identifier properties follow the same naming rules. " +"If the entity has a non-identifier property named id, the composite " +"identifier property can only be referenced by its defined named. Otherwise, " +"the special <literal>id</literal> property can be used to reference the " +"identifier property." +msgstr "" +"Les références aux propriétés d'identifiant composites suivent les mêmes " +"règles de nommage. Si l'entité a une propriété de non-identifiant appelée " +"id, la propriété d'identifiant composite ne peut être référencée que par son " +"nom défini ; sinon la propriété spéciale <literal>id</literal> peut être " +"utilisée pour référencer la propriété d'identifiant. " + +#. Tag: para +#, no-c-format +msgid "" +"Please note that, starting in version 3.2.2, this has changed significantly. " +"In previous versions, <literal>id</literal> <emphasis>always</emphasis> " +"referred to the identifier property regardless of its actual name. A " +"ramification of that decision was that non-identifier properties named " +"<literal>id</literal> could never be referenced in Hibernate queries." +msgstr "" +"Note : cela a changé de façon significative depuis la version 3.2.2. Dans " +"les versions précédentes, <literal>id</literal> référait <emphasis>toujours</" +"emphasis> à la propriété identifiant quel que soit son nom réel. Une des " +"conséquences de cette décision fut que les propriétés de non-identifiant " +"appelées <literal>id</literal> ne pouvaient jamais être référencées dans les " +"requêtes Hibernate." + +#. Tag: title +#, no-c-format +msgid "The select clause" +msgstr "La clause select" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>select</literal> clause picks which objects and properties to " +"return in the query result set. Consider the following:" +msgstr "" +"La clause <literal>select</literal> sélectionne les objets et propriétés qui " +"doivent être retournés dans le résultat de la requête. Soit : " + +#. Tag: para +#, no-c-format +msgid "" +"The query will select <literal>mate</literal>s of other <literal>Cat</" +"literal>s. You can express this query more compactly as:" +msgstr "" +"La requête recherchera les <literal>mate</literal> s liés aux <literal>Cat</" +"literal> s. Vous pouvez exprimer cette requête de manière plus compacte : " + +#. Tag: para +#, no-c-format +msgid "" +"Queries can return properties of any value type including properties of " +"component type:" +msgstr "" +"Les requêtes peuvent retourner des propriétés de n'importe quel type de " +"valeur, même celles de type composant : " + +#. Tag: para +#, no-c-format +msgid "" +"Queries can return multiple objects and/or properties as an array of type " +"<literal>Object[]</literal>:" +msgstr "" +"Les requêtes peuvent retourner de multiples objets et/ou propriétés sous la " +"forme d'un tableau du type <literal>Object[]</literal> :" + +#. Tag: para +#, no-c-format +msgid "Or as a <literal>List</literal>:" +msgstr "Ou sous la forme d'une <literal>List</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Or - assuming that the class <literal>Family</literal> has an appropriate " +"constructor - as an actual typesafe Java object:" +msgstr "" +"Ou bien - à condition que la classe <literal>Family</literal> possède le " +"constructeur approprié - en tant qu'objet typesafe Java :" + +#. Tag: para +#, no-c-format +msgid "" +"You can assign aliases to selected expressions using <literal>as</literal>:" +msgstr "" +"Vous pouvez assigner des alias aux expressions sélectionnées en utilisant " +"<literal>as</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"This is most useful when used together with <literal>select new map</" +"literal>:" +msgstr "" +"C'est surtout utile lorsque c'est utilisé avec <literal>select new map</" +"literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"This query returns a <literal>Map</literal> from aliases to selected values." +msgstr "" +"Cette requête retourne une <literal>Map</literal> à partir des alias vers " +"les valeurs sélectionnées." + +#. Tag: title +#, no-c-format +msgid "Aggregate functions" +msgstr "Fonctions d'agrégation" + +#. Tag: para +#, no-c-format +msgid "" +"HQL queries can even return the results of aggregate functions on properties:" +msgstr "" +"Les requêtes HQL peuvent aussi retourner les résultats de fonctions " +"d'agrégation sur les propriétés : " + +#. Tag: para +#, no-c-format +msgid "The supported aggregate functions are:" +msgstr "Les fonctions d'agrégation supportées sont :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>avg(...), sum(...), min(...), max(...)</literal>" +msgstr "<literal>avg(...), sum(...), min(...), max(...)</literal>" + +#. Tag: para +#, no-c-format +msgid "<literal>count(*)</literal>" +msgstr "<literal>count(*)</literal>" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>count(...), count(distinct ...), count(all...)</literal>" +msgstr "<literal>count(...), count(distinct ...), count(all...)</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"You can use arithmetic operators, concatenation, and recognized SQL " +"functions in the select clause:" +msgstr "" +"Vous pouvez utiliser des opérateurs arithmétiques, la concaténation, et des " +"fonctions SQL reconnues dans la clause select : " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>distinct</literal> and <literal>all</literal> keywords can be " +"used and have the same semantics as in SQL." +msgstr "" +"Les mots clé <literal>distinct</literal> et <literal>all</literal> peuvent " +"être utilisés et ont la même sémantique qu'en SQL. " + +#. Tag: title +#, no-c-format +msgid "Polymorphic queries" +msgstr "Requêtes polymorphiques" + +#. Tag: para +#, no-c-format +msgid "A query like:" +msgstr "Une requête comme :" + +#. Tag: para +#, no-c-format +msgid "" +"returns instances not only of <literal>Cat</literal>, but also of subclasses " +"like <literal>DomesticCat</literal>. Hibernate queries can name " +"<emphasis>any</emphasis> Java class or interface in the <literal>from</" +"literal> clause. The query will return instances of all persistent classes " +"that extend that class or implement the interface. The following query would " +"return all persistent objects:" +msgstr "" +"retourne non seulement les instances de <literal>Cat</literal>, mais aussi " +"celles des sous classes comme <literal>DomesticCat</literal>. Les requêtes " +"Hibernate peuvent nommer n'importe quelle classe ou interface Java dans la " +"clause <literal>from</literal>. La requête retournera les instances de " +"toutes les classes persistantes qui étendent cette classe ou implémente " +"cette interface. La requête suivante retournera tous les objets " +"persistants : " + +#. Tag: para +#, no-c-format +msgid "" +"The interface <literal>Named</literal> might be implemented by various " +"persistent classes:" +msgstr "" +"L'interface <literal>Named</literal> peut être implémentée par plusieurs " +"classes persistantes :" + +#. Tag: para +#, no-c-format +msgid "" +"These last two queries will require more than one SQL <literal>SELECT</" +"literal>. This means that the <literal>order by</literal> clause does not " +"correctly order the whole result set. It also means you cannot call these " +"queries using <literal>Query.scroll()</literal>." +msgstr "" +"Notez que ces deux dernières requêtes nécessitent plus d'un SQL " +"<literal>SELECT</literal>. Ce qui signifie que la clause <literal>order by</" +"literal> ne trie pas correctement la totalité des résultats (cela signifie " +"aussi que vous ne pouvez exécuter ces requêtes en appelant <literal>Query." +"scroll()</literal>). " + +#. Tag: title +#, no-c-format +msgid "The where clause" +msgstr "La clause where" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>where</literal> clause allows you to refine the list of " +"instances returned. If no alias exists, you can refer to properties by name:" +msgstr "" +"La clause <literal>where</literal> vous permet de réduire la liste des " +"instances retournées. Si aucun alias n'existe, vous pouvez vous référer aux " +"propriétés par leur nom : " + +#. Tag: para +#, no-c-format +msgid "If there is an alias, use a qualified property name:" +msgstr "S'il y a un alias, utilisez un nom de propriété qualifié :" + +#. Tag: para +#, no-c-format +msgid "This returns instances of <literal>Cat</literal> named 'Fritz'." +msgstr "Retourne les instances de <literal>Cat</literal> appelé 'Fritz'." + +#. Tag: para +#, no-c-format +msgid "The following query:" +msgstr "La requête suivante :" + +#. Tag: para +#, no-c-format +msgid "" +"returns all instances of <literal>Foo</literal> with an instance of " +"<literal>bar</literal> with a <literal>date</literal> property equal to the " +"<literal>startDate</literal> property of the <literal>Foo</literal>. " +"Compound path expressions make the <literal>where</literal> clause extremely " +"powerful. Consider the following:" +msgstr "" +"retournera les instances de <literal>Foo</literal> pour lesquelles il existe " +"une instance de <literal>bar</literal> avec la propriété <literal>date</" +"literal> égale à la propriété <literal>startDate</literal> de <literal>Foo</" +"literal>. Les expressions de chemin composées rendent la clause " +"<literal>where</literal> extrêmement puissante. Soit : " + +#. Tag: para +#, no-c-format +msgid "" +"This query translates to an SQL query with a table (inner) join. For example:" +msgstr "" +"Cette requête se traduit en une requête SQL par une jointure interne de " +"table. Si vous souhaitez écrire quelque chose comme :" + +#. Tag: para +#, no-c-format +msgid "would result in a query that would require four table joins in SQL." +msgstr "" +"vous finiriez avec une requête qui nécessiterait quatre jointures de table " +"en SQL. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>=</literal> operator can be used to compare not only " +"properties, but also instances:" +msgstr "" +"L'opérateur <literal>=</literal> peut être utilisé pour comparer aussi bien " +"des propriétés que des instances : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The special property (lowercase) <literal>id</literal> can be used to " +"reference the unique identifier of an object. See <xref linkend=\"queryhql-" +"identifier-property\" /> for more information." +msgstr "" +"La propriété spéciale (en minuscule) <literal>id</literal> peut être " +"utilisée pour référencer l'identifiant unique d'un objet. Pour plus " +"d'informations, consultez <xref linkend=\"queryhql-identifier-property\" />." + +#. Tag: para +#, no-c-format +msgid "The second query is efficient and does not require a table join." +msgstr "" +"La seconde requête est particulièrement efficace. Aucune jointure n'est " +"nécessaire ! " + +#. Tag: para +#, no-c-format +msgid "" +"Properties of composite identifiers can also be used. Consider the following " +"example where <literal>Person</literal> has composite identifiers consisting " +"of <literal>country</literal> and <literal>medicareNumber</literal>:" +msgstr "" +"Les propriétés d'identifiants composites peuvent aussi être utilisées. " +"Supposez que <literal>Person</literal> ait un identifiant composite composé " +"de <literal>country</literal> et <literal>medicareNumber</literal>. " + +#. Tag: para +#, no-c-format +msgid "Once again, the second query does not require a table join." +msgstr "" +"Une fois de plus, la seconde requête ne nécessite pas de jointure de table. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"See <xref linkend=\"queryhql-identifier-property\" /> for more information " +"regarding referencing identifier properties)" +msgstr "" +"Voir <xref linkend=\"queryhql-identifier-property\" /> pour obtenir des " +"informations supplémentaires sur le référencement de propriétés " +"d'identifiant." + +#. Tag: para +#, no-c-format +msgid "" +"The special property <literal>class</literal> accesses the discriminator " +"value of an instance in the case of polymorphic persistence. A Java class " +"name embedded in the where clause will be translated to its discriminator " +"value." +msgstr "" +"De même, la propriété spéciale <literal>class</literal> accède à la valeur " +"discriminante d'une instance dans le cas d'une persistance polymorphique. Le " +"nom d'une classe Java incorporée dans la clause where sera traduite par sa " +"valeur discriminante. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"You can also use components or composite user types, or properties of said " +"component types. See <xref linkend=\"queryhql-components\" /> for more " +"information." +msgstr "" +"Vous pouvez également utiliser des composants ou des types d'utilisateur " +"composites, ou des propriétés de types composant. Consultez <xref linkend=" +"\"queryhql-components\" /> pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"An \"any\" type has the special properties <literal>id</literal> and " +"<literal>class</literal> that allows you to express a join in the following " +"way (where <literal>AuditLog.item</literal> is a property mapped with " +"<literal>&lt;any&gt;</literal>):" +msgstr "" +"Un type \"any\" possède les propriétés particulières <literal>id</literal> " +"et <literal>class</literal>, qui nous permettent d'exprimer une jointure de " +"la manière suivante (là où <literal>AuditLog.item</literal> est une " +"propriété mappée avec <literal>&lt;any&gt;</literal>) :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>log.item.class</literal> and <literal>payment.class</literal> " +"would refer to the values of completely different database columns in the " +"above query." +msgstr "" +"Dans la requête précédente, notez que <literal>log.item.class</literal> et " +"<literal>payment.class</literal> feraient référence à des valeurs de " +"colonnes de la base de données complètement différentes. " + +#. Tag: title +#, no-c-format +msgid "Expressions" +msgstr "Expressions" + +#. Tag: para +#, no-c-format +msgid "" +"Expressions used in the <literal>where</literal> clause include the " +"following:" +msgstr "" +"Les expressions permises dans la clause <literal>where</literal> incluent :" + +#. Tag: para +#, no-c-format +msgid "mathematical operators: <literal>+, -, *, /</literal>" +msgstr "opérateurs mathématiques : <literal>+, -, *, /</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"binary comparison operators: <literal>=, &gt;=, &lt;=, &lt;&gt;, !=, like</" +"literal>" +msgstr "" +"opérateurs de comparaison binaire : <literal>=, &gt;=, &lt;=, &lt;&gt;, !=, " +"like</literal>" + +#. Tag: para +#, no-c-format +msgid "logical operations <literal>and, or, not</literal>" +msgstr "opérations logiques : <literal>and, or, not</literal>" + +#. Tag: para +#, no-c-format +msgid "Parentheses <literal>( )</literal> that indicates grouping" +msgstr "Parenthèses <literal>( )</literal>, indiquant un regroupement " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>in</literal>, <literal>not in</literal>, <literal>between</" +"literal>, <literal>is null</literal>, <literal>is not null</literal>, " +"<literal>is empty</literal>, <literal>is not empty</literal>, " +"<literal>member of</literal> and <literal>not member of</literal>" +msgstr "" +"<literal>in</literal>, <literal>not in</literal>, <literal>between</" +"literal>, <literal>is null</literal>, <literal>is not null</literal>, " +"<literal>is empty</literal>, <literal>is not empty</literal>, " +"<literal>member of</literal> et <literal>not member of</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"\"Simple\" case, <literal>case ... when ... then ... else ... end</literal>, " +"and \"searched\" case, <literal>case when ... then ... else ... end</literal>" +msgstr "" +"Cas simple <literal>case ... when ... then ... else ... end</literal>, et " +"cas \"searched\", <literal>case when ... then ... else ... end</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"string concatenation <literal>...||...</literal> or <literal>concat(...,...)" +"</literal>" +msgstr "" +"concaténation de chaîne de caractères <literal>...||...</literal> ou " +"<literal>concat(...,...)</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>current_date()</literal>, <literal>current_time()</literal>, and " +"<literal>current_timestamp()</literal>" +msgstr "" +"<literal>current_date()</literal>, <literal>current_time()</literal>, and " +"<literal>current_timestamp()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>second(...)</literal>, <literal>minute(...)</literal>, <literal>hour" +"(...)</literal>, <literal>day(...)</literal>, <literal>month(...)</literal>, " +"and <literal>year(...)</literal>" +msgstr "" +"<literal>second(...)</literal>, <literal>minute(...)</literal>, <literal>hour" +"(...)</literal>, <literal>day(...)</literal>, <literal>month(...)</literal>, " +"<literal>year(...)</literal>," + +#. Tag: para +#, no-c-format +msgid "" +"Any function or operator defined by EJB-QL 3.0: <literal>substring(), trim" +"(), lower(), upper(), length(), locate(), abs(), sqrt(), bit_length(), mod()" +"</literal>" +msgstr "" +"N'importe quelle fonction ou opérateur défini par EJB-QL 3.0 : " +"<literal>substring(), trim(), lower(), upper(), length(), locate(), abs(), " +"sqrt(), bit_length(), mod()</literal>" + +#. Tag: para +#, no-c-format +msgid "<literal>coalesce()</literal> and <literal>nullif()</literal>" +msgstr "<literal>coalesce()</literal> et <literal>nullif()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>str()</literal> for converting numeric or temporal values to a " +"readable string" +msgstr "" +"<literal>str()</literal> pour convertir des valeurs numériques ou " +"temporelles vers une chaîne de caractères lisible" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>cast(... as ...)</literal>, where the second argument is the name " +"of a Hibernate type, and <literal>extract(... from ...)</literal> if ANSI " +"<literal>cast()</literal> and <literal>extract()</literal> is supported by " +"the underlying database" +msgstr "" +"<literal>cast(... as ...)</literal>, où le second argument est le nom d'un " +"type Hibernate, et <literal>extract(... from ...)</literal> si le " +"<literal>cast()</literal> ANSI et <literal>extract()</literal> sont " +"supportés par la base de données sous-jacente" + +#. Tag: para +#, no-c-format +msgid "" +"the HQL <literal>index()</literal> function, that applies to aliases of a " +"joined indexed collection" +msgstr "" +"La fonction HQL <literal>index()</literal>, qui s'applique aux alias d'une " +"collection indexée jointe" + +#. Tag: para +#, no-c-format +msgid "" +"HQL functions that take collection-valued path expressions: <literal>size(), " +"minelement(), maxelement(), minindex(), maxindex()</literal>, along with the " +"special <literal>elements()</literal> and <literal>indices</literal> " +"functions that can be quantified using <literal>some, all, exists, any, in</" +"literal>." +msgstr "" +"Les fonctions HQL qui prennent des expressions de chemin représentant des " +"collections : <literal>size(), minelement(), maxelement(), minindex(), " +"maxindex()</literal>, ainsi que les fonctions particulières <literal>elements" +"()</literal> et <literal>indices</literal> qui peuvent être quantifiées en " +"utilisant <literal>some, all, exists, any, in</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Any database-supported SQL scalar function like <literal>sign()</literal>, " +"<literal>trunc()</literal>, <literal>rtrim()</literal>, and <literal>sin()</" +"literal>" +msgstr "" +"N'importe quelle fonction scalaire SQL supportée par la base de données " +"comme <literal>sign()</literal>, <literal>trunc()</literal>, <literal>rtrim()" +"</literal>, et <literal>sin()</literal>" + +#. Tag: para +#, no-c-format +msgid "JDBC-style positional parameters <literal>?</literal>" +msgstr "Les paramètres de position de JDBC <literal>?</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"named parameters <literal>:name</literal>, <literal>:start_date</literal>, " +"and <literal>:x1</literal>" +msgstr "" +"paramètres nommés <literal>:name</literal>, <literal>:start_date</literal>, " +"et <literal>:x1</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"SQL literals <literal>'foo'</literal>, <literal>69</literal>, <literal>6.66E" +"+2</literal>, <literal>'1970-01-01 10:00:01.0'</literal>" +msgstr "" +"SQL textuel <literal>'foo'</literal>, <literal>69</literal>, <literal>6.66E" +"+2</literal>, <literal>'1970-01-01 10:00:01.0'</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Java <literal>public static final</literal> constants <literal>eg.Color." +"TABBY</literal>" +msgstr "" +"Constantes Java <literal>public static final</literal><literal>eg.Color." +"TABBY</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>in</literal> and <literal>between</literal> can be used as follows:" +msgstr "" +"<literal>in</literal> et <literal>between</literal> peuvent être utilisés " +"comme suit : " + +#. Tag: para +#, no-c-format +msgid "The negated forms can be written as follows:" +msgstr "Les formes négatives peuvent être écrites ainsi :" + +#. Tag: para +#, no-c-format +msgid "" +"Similarly, <literal>is null</literal> and <literal>is not null</literal> can " +"be used to test for null values." +msgstr "" +"De même, <literal>is null</literal> et <literal>is not null</literal> " +"peuvent être utilisés pour tester les valeurs nulles." + +#. Tag: para +#, no-c-format +msgid "" +"Booleans can be easily used in expressions by declaring HQL query " +"substitutions in Hibernate configuration:" +msgstr "" +"Les booléens peuvent être facilement utilisés en déclarant les substitutions " +"de requêtes HQL dans la configuration Hibernate : " + +#. Tag: para +#, no-c-format +msgid "" +"This will replace the keywords <literal>true</literal> and <literal>false</" +"literal> with the literals <literal>1</literal> and <literal>0</literal> in " +"the translated SQL from this HQL:" +msgstr "" +"Ce qui remplacera les mots clés <literal>true</literal> et <literal>false</" +"literal> par <literal>1</literal> et <literal>0</literal> dans la traduction " +"SQL du HQL suivant :" + +#. Tag: para +#, no-c-format +msgid "" +"You can test the size of a collection with the special property " +"<literal>size</literal> or the special <literal>size()</literal> function." +msgstr "" +"Vous pouvez tester la taille d'une collection par la propriété particulière " +"<literal>size</literal>, ou la fonction spéciale <literal>size()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"For indexed collections, you can refer to the minimum and maximum indices " +"using <literal>minindex</literal> and <literal>maxindex</literal> functions. " +"Similarly, you can refer to the minimum and maximum elements of a collection " +"of basic type using the <literal>minelement</literal> and " +"<literal>maxelement</literal> functions. For example:" +msgstr "" +"Pour les collections indexées, vous pouvez faire référence aux indices " +"minimum et maximum en utilisant les fonctions <literal>minindex</literal> et " +"<literal>maxindex</literal>. De manière similaire, vous pouvez faire " +"référence aux éléments minimum et maximum d'une collection de type basique " +"en utilisant les fonctions <literal>minelement</literal> et " +"<literal>maxelement</literal>. Par exemple : " + +#. Tag: para +#, no-c-format +msgid "" +"The SQL functions <literal>any, some, all, exists, in</literal> are " +"supported when passed the element or index set of a collection " +"(<literal>elements</literal> and <literal>indices</literal> functions) or " +"the result of a subquery (see below):" +msgstr "" +"Les fonctions SQL <literal>any, some, all, exists, in</literal> sont " +"supportées quand l'élément ou l'ensemble des indexes d'une collection (les " +"fonctions <literal>elements</literal> et <literal>indices</literal>) ou le " +"résultat d'une sous requête sont passés (voir ci dessous) :" + +#. Tag: para +#, no-c-format +msgid "" +"Note that these constructs - <literal>size</literal>, <literal>elements</" +"literal>, <literal>indices</literal>, <literal>minindex</literal>, " +"<literal>maxindex</literal>, <literal>minelement</literal>, " +"<literal>maxelement</literal> - can only be used in the where clause in " +"Hibernate3." +msgstr "" +"Notez que l'écriture de - <literal>size</literal>, <literal>elements</" +"literal>, <literal>indices</literal>, <literal>minindex</literal>, " +"<literal>maxindex</literal>, <literal>minelement</literal>, " +"<literal>maxelement</literal> - peut seulement être utilisée dans la clause " +"where dans Hibernate3. " + +#. Tag: para +#, no-c-format +msgid "" +"Elements of indexed collections (arrays, lists, and maps) can be referred to " +"by index in a where clause only:" +msgstr "" +"Les éléments de collections indexées (arrays, lists, maps) peuvent être " +"référencés via index dans une clause where seulement :" + +#. Tag: para +#, no-c-format +msgid "" +"The expression inside <literal>[]</literal> can even be an arithmetic " +"expression:" +msgstr "" +"L'expression entre <literal>[]</literal> peut même être une expression " +"arithmétique :" + +#. Tag: para +#, no-c-format +msgid "" +"HQL also provides the built-in <literal>index()</literal> function for " +"elements of a one-to-many association or collection of values." +msgstr "" +"HQL propose aussi une fonction <literal>index()</literal> interne, pour les " +"éléments d'une association un-à-plusieurs ou d'une collection de valeurs." + +#. Tag: para +#, no-c-format +msgid "Scalar SQL functions supported by the underlying database can be used:" +msgstr "" +"Les fonctions SQL scalaires supportées par la base de données utilisée " +"peuvent être utilisées :" + +#. Tag: para +#, no-c-format +msgid "" +"Consider how much longer and less readable the following query would be in " +"SQL:" +msgstr "" +"Si vous n'êtes pas encore convaincu par tout cela, imaginez la taille et " +"l'illisibilité qui caractériseraient la requête suivante en SQL :" + +#. Tag: para +#, no-c-format +msgid "<emphasis>Hint:</emphasis> something like" +msgstr "<emphasis>Un indice :</emphasis> cela donne quelque chose comme" + +#. Tag: title +#, no-c-format +msgid "The order by clause" +msgstr "La clause order by" + +#. Tag: para +#, no-c-format +msgid "" +"The list returned by a query can be ordered by any property of a returned " +"class or components:" +msgstr "" +"La liste retournée par la requête peut être triée par n'importe quelle " +"propriété de la classe ou des composants retournés : " + +#. Tag: para +#, no-c-format +msgid "" +"The optional <literal>asc</literal> or <literal>desc</literal> indicate " +"ascending or descending order respectively." +msgstr "" +"Le mot optionnel <literal>asc</literal> ou <literal>desc</literal> indique " +"respectivement si le tri doit être croissant ou décroissant." + +#. Tag: title +#, no-c-format +msgid "The group by clause" +msgstr "La clause group by" + +#. Tag: para +#, no-c-format +msgid "" +"A query that returns aggregate values can be grouped by any property of a " +"returned class or components:" +msgstr "" +"Si la requête retourne des valeurs agrégées, celles-ci peuvent être groupées " +"par propriété d'une classe retournée ou par des composants : " + +#. Tag: para +#, no-c-format +msgid "A <literal>having</literal> clause is also allowed." +msgstr "Une clause <literal>having</literal> est aussi permise." + +#. Tag: para +#, no-c-format +msgid "" +"SQL functions and aggregate functions are allowed in the <literal>having</" +"literal> and <literal>order by</literal> clauses if they are supported by " +"the underlying database (i.e., not in MySQL)." +msgstr "" +"Les fonctions SQL et les fonctions d'agrégat sont permises dans les clauses " +"<literal>having</literal> et <literal>order by</literal>, si elles sont " +"prises en charge par la base de données sous-jacente (ce que ne fait pas " +"MySQL par exemple). " + +#. Tag: para +#, no-c-format +msgid "" +"Neither the <literal>group by</literal> clause nor the <literal>order by</" +"literal> clause can contain arithmetic expressions. Hibernate also does not " +"currently expand a grouped entity, so you cannot write <literal>group by " +"cat</literal> if all properties of <literal>cat</literal> are non-" +"aggregated. You have to list all non-aggregated properties explicitly." +msgstr "" +"Notez que ni la clause <literal>group by</literal> ni la clause " +"<literal>order by</literal> ne peuvent contenir d'expressions arithmétiques. " +"Notez aussi qu'Hibernate ne développe pas actuellement une entité faisant " +"partie du regroupement, donc vous ne pouvez pas écrire <literal>group by " +"cat</literal> si toutes les propriétés de <literal>cat</literal> sont non-" +"agrégées. Vous devez lister toutes les propriétés non-agrégées explicitement." + +#. Tag: title +#, no-c-format +msgid "Subqueries" +msgstr "Sous-requêtes" + +#. Tag: para +#, no-c-format +msgid "" +"For databases that support subselects, Hibernate supports subqueries within " +"queries. A subquery must be surrounded by parentheses (often by an SQL " +"aggregate function call). Even correlated subqueries (subqueries that refer " +"to an alias in the outer query) are allowed." +msgstr "" +"Pour les bases de données supportant les sous-selects, Hibernate supporte " +"les sous requêtes dans les requêtes. Une sous-requête doit être entre " +"parenthèses (souvent pour un appel à une fonction d'agrégation SQL). Même " +"les sous-requêtes corrélées (celles qui font référence à un alias de la " +"requête principale) sont supportées." + +#. Tag: para +#, no-c-format +msgid "Note that HQL subqueries can occur only in the select or where clauses." +msgstr "" +"Notez que les sous-requêtes HQL peuvent survenir uniquement dans les clauses " +"select ou where. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Note that subqueries can also utilize <literal>row value constructor</" +"literal> syntax. See <xref linkend=\"queryhql-tuple\" /> for more " +"information." +msgstr "" +"Notez que les sous-requêtes peuvent également utiliser la syntaxe " +"<literal>row value constructor</literal>. Pour plus d'informations, " +"consultez <xref linkend=\"queryhql-tuple\" />." + +#. Tag: title +#, no-c-format +msgid "HQL examples" +msgstr "Exemples HQL" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate queries can be quite powerful and complex. In fact, the power of " +"the query language is one of Hibernate's main strengths. The following " +"example queries are similar to queries that have been used on recent " +"projects. Please note that most queries you will write will be much simpler " +"than the following examples." +msgstr "" +"Les requêtes Hibernate peuvent être relativement puissantes et complexes. En " +"fait, la puissance du langage d'interrogation est l'un des arguments " +"principaux de vente de Hibernate. Voici quelques exemples très similaires " +"aux requêtes que nous avons utilisées lors d'un récent projet. Notez que la " +"plupart des requêtes que vous écrirez seront plus simples que les exemples " +"qui suivent." + +#. Tag: para +#, no-c-format +msgid "" +"The following query returns the order id, number of items, the given minimum " +"total value and the total value of the order for all unpaid orders for a " +"particular customer. The results are ordered by total value. In determining " +"the prices, it uses the current catalog. The resulting SQL query, against " +"the <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, " +"<literal>PRODUCT</literal>, <literal>CATALOG</literal> and <literal>PRICE</" +"literal> tables has four inner joins and an (uncorrelated) subselect." +msgstr "" +"La requête suivante retourne l'id de commande, le nombre d'articles et la " +"valeur totale de la commande pour toutes les commandes non payées d'un " +"client particulier pour une valeur totale minimum donnée, ces résultats " +"étant triés par la valeur totale. La requête SQL générée sur les tables " +"<literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</" +"literal>, <literal>CATALOG</literal> et <literal>PRICE</literal> est " +"composée de quatre jointures internes ainsi que d'un sous-select (non " +"corrélé)." + +#. Tag: para +#, no-c-format +msgid "" +"What a monster! Actually, in real life, I'm not very keen on subqueries, so " +"my query was really more like this:" +msgstr "" +"Quel monstre ! En principe, dans des situations réelles, nous n'approuvons " +"pas les sous-requêtes, notre requête ressemblait donc plutôt à ce qui suit :" + +#. Tag: para +#, no-c-format +msgid "" +"The next query counts the number of payments in each status, excluding all " +"payments in the <literal>AWAITING_APPROVAL</literal> status where the most " +"recent status change was made by the current user. It translates to an SQL " +"query with two inner joins and a correlated subselect against the " +"<literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal> and " +"<literal>PAYMENT_STATUS_CHANGE</literal> tables." +msgstr "" +"La requête suivante compte le nombre de paiements pour chaque statut, en " +"excluant tout paiement dans le statut <literal>AWAITING_APPROVAL</literal> " +"où le changement de statut le plus récent à été fait par l'utilisateur " +"courant. En SQL, cette requête effectue deux jointures internes et un sous-" +"select corrélé sur les tables <literal>PAYMENT</literal>, " +"<literal>PAYMENT_STATUS</literal> et <literal>PAYMENT_STATUS_CHANGE</" +"literal>." + +#. Tag: para +#, no-c-format +msgid "" +"If the <literal>statusChanges</literal> collection was mapped as a list, " +"instead of a set, the query would have been much simpler to write." +msgstr "" +"Si nous avions mappé la collection <literal>statusChanges</literal> comme " +"une liste, au lieu d'un ensemble, la requête aurait été plus facile à " +"écrire. " + +#. Tag: para +#, no-c-format +msgid "" +"The next query uses the MS SQL Server <literal>isNull()</literal> function " +"to return all the accounts and unpaid payments for the organization to which " +"the current user belongs. It translates to an SQL query with three inner " +"joins, an outer join and a subselect against the <literal>ACCOUNT</literal>, " +"<literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal>, " +"<literal>ACCOUNT_TYPE</literal>, <literal>ORGANIZATION</literal> and " +"<literal>ORG_USER</literal> tables." +msgstr "" +"La prochaine requête utilise la fonction de serveur MS SQL <literal>isNull()" +"</literal> pour retourner tous les comptes et paiements impayés pour " +"l'organisation à laquelle l'utilisateur courant appartient. Elle est " +"traduite en SQL par trois jointures internes, une jointure externe ainsi " +"qu'un sous-select sur les tables <literal>ACCOUNT</literal>, " +"<literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal>, " +"<literal>ACCOUNT_TYPE</literal>, <literal>ORGANIZATION</literal> et " +"<literal>ORG_USER</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"For some databases, we would need to do away with the (correlated) subselect." +msgstr "" +"Pour certaines bases de données, nous devons éliminer le sous-select " +"(corrélé)." + +#. Tag: title +#, no-c-format +msgid "Bulk update and delete" +msgstr "Nombreuses mises à jour et suppressions " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"HQL now supports <literal>update</literal>, <literal>delete</literal> and " +"<literal>insert ... select ...</literal> statements. See <xref linkend=" +"\"batch-direct\" /> for more information." +msgstr "" +"HQL supporte maintenant les expressions <literal>update</literal>, " +"<literal>delete</literal> et <literal>insert ... select ...</literal>. Voir " +"<xref linkend=\"batch-direct\" /> pour des informations plus détaillées." + +#. Tag: title +#, no-c-format +msgid "Tips &amp; Tricks" +msgstr "Trucs &amp; Astuces" + +#. Tag: para +#, no-c-format +msgid "You can count the number of query results without returning them:" +msgstr "" +"Vous pouvez compter le nombre de résultats d'une requête sans les " +"retourner : " + +#. Tag: para +#, no-c-format +msgid "To order a result by the size of a collection, use the following query:" +msgstr "" +"Pour trier les résultats par la taille d'une collection, utilisez la requête " +"suivante :" + +#. Tag: para +#, no-c-format +msgid "" +"If your database supports subselects, you can place a condition upon " +"selection size in the where clause of your query:" +msgstr "" +"Si votre base de données supporte les sous-selects, vous pouvez placer des " +"conditions sur la taille de la sélection dans la clause where de votre " +"requête :" + +#. Tag: para +#, no-c-format +msgid "If your database does not support subselects, use the following query:" +msgstr "" +"Si votre base de données ne supporte pas les sous-selects, utilisez la " +"requête suivante : " + +#. Tag: para +#, no-c-format +msgid "" +"As this solution cannot return a <literal>User</literal> with zero messages " +"because of the inner join, the following form is also useful:" +msgstr "" +"Cette solution ne peut pas retourner un <literal>User</literal> avec zéro " +"message à cause de la jointure interne, la forme suivante peut donc être " +"utile : " + +#. Tag: para +#, no-c-format +msgid "Properties of a JavaBean can be bound to named query parameters:" +msgstr "" +"Les propriétés d'un JavaBean peuvent être injectées dans les paramètres " +"nommés d'une requête :" + +#. Tag: para +#, no-c-format +msgid "" +"Collections are pageable by using the <literal>Query</literal> interface " +"with a filter:" +msgstr "" +"Les collections sont paginables via l'utilisation de l'interface " +"<literal>Query</literal> avec un filtre :" + +#. Tag: para +#, no-c-format +msgid "Collection elements can be ordered or grouped using a query filter:" +msgstr "" +"Les éléments d'une collection peuvent être triés ou groupés en utilisant un " +"filtre de requête : " + +#. Tag: para +#, no-c-format +msgid "You can find the size of a collection without initializing it:" +msgstr "Vous pouvez récupérer la taille d'une collection sans l'initialiser :" + +#. Tag: title +#, no-c-format +msgid "Components" +msgstr "Composants" + +#. Tag: para +#, no-c-format +msgid "" +"Components can be used similarly to the simple value types that are used in " +"HQL queries. They can appear in the <literal>select</literal> clause as " +"follows:" +msgstr "" +"Les composants peuvent être utilisés dans presque tous les cas comme les " +"types de valeur dans les requêtes HQL. Ils peuvent apparaître dans la clause " +"<literal>select</literal> comme ce qui suit :" + +#. Tag: para +#, no-c-format +msgid "" +"where the Person's name property is a component. Components can also be used " +"in the <literal>where</literal> clause:" +msgstr "" +"où la propriété de nom de Person est un composant. Des composants peuvent " +"aussi être utilisés dans la clause <literal>where</literal> :" + +#. Tag: para +#, no-c-format +msgid "Components can also be used in the <literal>order by</literal> clause:" +msgstr "" +"Des composants peuvent être utilisés dans la clause <literal>order by</" +"literal> :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Another common use of components is in <link linkend=\"queryhql-tuple\">row " +"value constructors</link>." +msgstr "" +"Voici encore un usage commun des composants <xref linkend=\"queryhql-tuple" +"\" />." + +#. Tag: title +#, no-c-format +msgid "Row value constructor syntax" +msgstr "Syntaxe des constructeurs de valeur de ligne" + +#. Tag: para +#, no-c-format +msgid "" +"HQL supports the use of ANSI SQL <literal>row value constructor</literal> " +"syntax, sometimes referred to AS <literal>tuple</literal> syntax, even " +"though the underlying database may not support that notion. Here, we are " +"generally referring to multi-valued comparisons, typically associated with " +"components. Consider an entity Person which defines a name component:" +msgstr "" +"HQL supporte l'utilisation de la syntaxe <literal>row value constructor</" +"literal> SQL ANSI (aussi appelée syntaxe <literal>tuple</literal>), bien que " +"la base de données sous-jacente ne supporte pas nécessairement cette notion. " +"Là, nous faisons généralement référence à des comparaisons multi-valuées, " +"typiquement associées à des composants. Considérez une entité Person qui " +"définit un composant de nom :" + +#. Tag: para +#, no-c-format +msgid "" +"That is valid syntax although it is a little verbose. You can make this more " +"concise by using <literal>row value constructor</literal> syntax:" +msgstr "" +"Voici une syntaxe valide, bien que quelque peu fastidieuse. Pour la rendre " +"plus concise, utilisez la syntaxe <literal>row value constructor</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"It can also be useful to specify this in the <literal>select</literal> " +"clause:" +msgstr "" +"Il est utile de spécifier cela dans la clause <literal>select</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Using <literal>row value constructor</literal> syntax can also be beneficial " +"when using subqueries that need to compare against multiple values:" +msgstr "" +"Alternativement, utiliser la syntaxe <literal>row value constructor</" +"literal> peut être avantageux quand vous utilisez des sous-requêtes " +"nécessitant une comparaison avec des valeurs multiples : " + +#. Tag: para +#, no-c-format +msgid "" +"One thing to consider when deciding if you want to use this syntax, is that " +"the query will be dependent upon the ordering of the component sub-" +"properties in the metadata." +msgstr "" +"Si vous décidez d'utiliser cette syntaxe, il vous faudra prendre en " +"considération le fait que la requête sera dépendante de la commande des sous-" +"propriétés du composant dans les métadonnées. " + +#, fuzzy +#~ msgid "left outer join" +#~ msgstr "<literal>left outer join</literal> (jointure ouverte par la gauche)" + +#, fuzzy +#~ msgid "right outer join" +#~ msgstr "" +#~ "<literal>right outer join</literal> (jointure ouverte par la droite)" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_sql.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_sql.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/query_sql.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1057 @@ +# translation of query_sql.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: query_sql\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-03-12T00:03:47\n" +"PO-Revision-Date: 2010-01-05 09:47+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Native SQL" +msgstr "SQL natif" + +#. Tag: para +#, no-c-format +msgid "" +"You can also express queries in the native SQL dialect of your database. " +"This is useful if you want to utilize database-specific features such as " +"query hints or the <literal>CONNECT</literal> keyword in Oracle. It also " +"provides a clean migration path from a direct SQL/JDBC based application to " +"Hibernate." +msgstr "" +"Vous pouvez aussi écrire vos requêtes dans le dialecte SQL natif de votre " +"base de données. Ceci est utile si vous souhaitez utiliser les " +"fonctionnalités spécifiques de votre base de données comme le mot clé " +"<literal>CONNECT</literal> d'Oracle. Cette fonctionnalité offre par ailleurs " +"un moyen de migration plus propre et doux d'une application basée " +"directement sur SQL/JDBC vers Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 allows you to specify handwritten SQL, including stored " +"procedures, for all create, update, delete, and load operations." +msgstr "" +"Hibernate3 vous permet de spécifier du SQL écrit à la main (y compris les " +"procédures stockées) pour toutes les opérations de création, mise à jour, " +"suppression et chargement. " + +#. Tag: title +#, no-c-format +msgid "Using a <literal>SQLQuery</literal>" +msgstr "Utiliser une requête <literal>SQLQuery</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"Execution of native SQL queries is controlled via the <literal>SQLQuery</" +"literal> interface, which is obtained by calling <literal>Session." +"createSQLQuery()</literal>. The following sections describe how to use this " +"API for querying." +msgstr "" +"L'exécution des requêtes en SQL natif est contrôlée par l'interface " +"<literal>SQLQuery</literal>, qui est obtenue en appelant <literal>Session." +"createSQLQuery()</literal>. Ce qui suit décrit comment utiliser cette API " +"pour les requêtes." + +#. Tag: title +#, no-c-format +msgid "Scalar queries" +msgstr "Requêtes scalaires" + +#. Tag: para +#, no-c-format +msgid "The most basic SQL query is to get a list of scalars (values)." +msgstr "" +"La requête SQL la plus basique permet de récupérer une liste de (valeurs) " +"scalaires." + +#. Tag: para +#, no-c-format +msgid "" +"These will return a List of Object arrays (Object[]) with scalar values for " +"each column in the CATS table. Hibernate will use ResultSetMetadata to " +"deduce the actual order and types of the returned scalar values." +msgstr "" +"Ces deux requêtes retourneront un tableau d'objets (Object[]) avec les " +"valeurs scalaires de chacune des colonnes de la table CATS. Hibernate " +"utilisera le ResultSetMetadata pour déduire l'ordre final et le type des " +"valeurs scalaires retournées. " + +#. Tag: para +#, no-c-format +msgid "" +"To avoid the overhead of using <literal>ResultSetMetadata</literal>, or " +"simply to be more explicit in what is returned, one can use " +"<literal>addScalar()</literal>:" +msgstr "" +"Pour éviter l'overhead lié à <literal>ResultSetMetadata</literal> ou " +"simplement pour être plus explicite dans ce qui est retourné, vous pouvez " +"utiliser <literal>addScalar()</literal>. " + +#. Tag: para +#, no-c-format +msgid "This query specified:" +msgstr "Cette requête spécifie :" + +#. Tag: para +#, no-c-format +msgid "the SQL query string" +msgstr "la chaîne de requêtes SQL" + +#. Tag: para +#, no-c-format +msgid "the columns and types to return" +msgstr "les colonnes et les types retournés" + +#. Tag: para +#, no-c-format +msgid "" +"This will return Object arrays, but now it will not use " +"<literal>ResultSetMetadata</literal> but will instead explicitly get the ID, " +"NAME and BIRTHDATE column as respectively a Long, String and a Short from " +"the underlying resultset. This also means that only these three columns will " +"be returned, even though the query is using <literal>*</literal> and could " +"return more than the three listed columns." +msgstr "" +"Cela retournera toujours un tableau d'objets, mais sans utiliser le " +"<literal>ResultSetMetdata</literal>. Il récupérera à la place explicitement " +"les colonnes ID, NAME et BIRTHDATE comme étant respectivement de type Long, " +"String et Short, depuis l'ensemble de résultats sous-jacent. Cela signifie " +"aussi que seules ces trois colonnes seront retournées même si la requête " +"utilise <literal>*</literal> et pourait retourner plus que les trois " +"colonnes listées." + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to leave out the type information for all or some of the " +"scalars." +msgstr "" +"Il est possible de ne pas définir l'information sur le type pour toutes ou " +"une partie des scalaires." + +#. Tag: para +#, no-c-format +msgid "" +"This is essentially the same query as before, but now " +"<literal>ResultSetMetaData</literal> is used to determine the type of NAME " +"and BIRTHDATE, where as the type of ID is explicitly specified." +msgstr "" +"Il s'agit essentiellement de la même requête que précédemment, mais le " +"<literal>ResultSetMetaData</literal> est utilisé pour décider des types de " +"NAME et BIRTHDATE alors que le type de ID est explicitement spécifié. " + +#. Tag: para +#, no-c-format +msgid "" +"How the java.sql.Types returned from ResultSetMetaData is mapped to " +"Hibernate types is controlled by the Dialect. If a specific type is not " +"mapped, or does not result in the expected type, it is possible to customize " +"it via calls to <literal>registerHibernateType</literal> in the Dialect." +msgstr "" +"Les java.sql.Types retournés par le ResultSetMetaData sont mappés aux types " +"Hibernate via le Dialect. Si un type spécifique n'est pas mappé ou est mappé " +"à un type non souhaité, il est possible de le personnaliser en invoquant " +"<literal>registerHibernateType</literal> dans le Dialect. " + +#. Tag: title +#, no-c-format +msgid "Entity queries" +msgstr "Requêtes d'entités" + +#. Tag: para +#, no-c-format +msgid "" +"The above queries were all about returning scalar values, basically " +"returning the \"raw\" values from the resultset. The following shows how to " +"get entity objects from a native sql query via <literal>addEntity()</" +"literal>." +msgstr "" +"Les requêtes précédentes ne retournaient que des valeurs scalaires, en ne " +"retournant que les valeurs brutes de l'ensemble de résultats. Ce qui suit " +"montre comment récupérer des entités depuis une requête native SQL, grâce à " +"<literal>addEntity()</literal>." + +#. Tag: para +#, no-c-format +msgid "the entity returned by the query" +msgstr "L'entité retournée par la requête" + +#. Tag: para +#, no-c-format +msgid "" +"Assuming that Cat is mapped as a class with the columns ID, NAME and " +"BIRTHDATE the above queries will both return a List where each element is a " +"Cat entity." +msgstr "" +"Avec Cat mappé comme classe avec les colonnes ID, NAME et BIRTHDATE, les " +"requêtes précédentes retournent toutes deux, une liste où chaque élément est " +"une entité Cat." + +#. Tag: para +#, no-c-format +msgid "" +"If the entity is mapped with a <literal>many-to-one</literal> to another " +"entity it is required to also return this when performing the native query, " +"otherwise a database specific \"column not found\" error will occur. The " +"additional columns will automatically be returned when using the * notation, " +"but we prefer to be explicit as in the following example for a <literal>many-" +"to-one</literal> to a <literal>Dog</literal>:" +msgstr "" +"Si l'entité est mappée avec un <literal>many-to-one</literal> vers une autre " +"entité, il est requis de retourner aussi cette entité en exécutant la " +"requête native, sinon une erreur \"column not found\" spécifique à la base " +"de données sera soulevée. Les colonnes additionnelles seront automatiquement " +"retournées en utilisant la notation *, mais nous préférons être explicites " +"comme dans l'exemple suivant avec le <literal>many-to-one</literal> vers " +"<literal>Dog</literal>:" + +#. Tag: para +#, no-c-format +msgid "This will allow cat.getDog() to function properly." +msgstr "Ceci permet à cat.getDog() de fonctionner normalement." + +#. Tag: title +#, no-c-format +msgid "Handling associations and collections" +msgstr "Gérer les associations et collections" + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to eagerly join in the <literal>Dog</literal> to avoid the " +"possible extra roundtrip for initializing the proxy. This is done via the " +"<literal>addJoin()</literal> method, which allows you to join in an " +"association or collection." +msgstr "" +"Il est possible de charger agressivement <literal>Dog</literal> pour éviter " +"le chargement de proxies c'est-à-dire un aller-retour supplémentaire vers la " +"base de données. Ceci est effectué via la méthode <literal>addJoin()</" +"literal>, qui vous permet de joindre une association ou collection." + +#. Tag: para +#, no-c-format +msgid "" +"In this example, the returned <literal>Cat</literal>'s will have their " +"<literal>dog</literal> property fully initialized without any extra " +"roundtrip to the database. Notice that you added an alias name (\"cat\") to " +"be able to specify the target property path of the join. It is possible to " +"do the same eager joining for collections, e.g. if the <literal>Cat</" +"literal> had a one-to-many to <literal>Dog</literal> instead." +msgstr "" +"Dans cet exemple, les <literal>Cat</literal> retournés auront leur propriété " +"<literal>dog</literal> entièrement initialisée sans aucun aller-retour " +"supplémentaire vers la base de données. Notez que nous avons ajouté un alias " +"(\"cat\") pour être capable de spécifier le chemin de la propriété cible de " +"la jointure. Il est possible de faire la même jointure agressive pour les " +"collections, par ex. si le <literal>Cat</literal> a un un-à-plusieurs vers " +"<literal>Dog</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"At this stage you are reaching the limits of what is possible with native " +"queries, without starting to enhance the sql queries to make them usable in " +"Hibernate. Problems can arise when returning multiple entities of the same " +"type or when the default alias/column names are not enough." +msgstr "" +"À ce stade, nous arrivons aux limites de ce qui est possible avec les " +"requêtes natives sans modifier les requêtes SQL pour les rendre utilisables " +"par Hibernate; les problèmes surviennent lorsque nous essayons de retourner " +"des entités du même type ou lorsque les alias/colonnes par défaut ne sont " +"plus suffisants." + +#. Tag: title +#, no-c-format +msgid "Returning multiple entities" +msgstr "Retour d'entités multiples" + +#. Tag: para +#, no-c-format +msgid "" +"Until now, the result set column names are assumed to be the same as the " +"column names specified in the mapping document. This can be problematic for " +"SQL queries that join multiple tables, since the same column names can " +"appear in more than one table." +msgstr "" +"Jusqu'à présent, les colonnes de l'ensemble de résultats sont supposées être " +"les mêmes que les noms de colonnes spécifiés dans les documents de mapping. " +"Ceci peut être problématique pour les requêtes SQL qui effectuent de " +"multiples jointures vers différentes tables, puisque les mêmes colonnes " +"peuvent apparaître dans plus d'une table. " + +#. Tag: para +#, no-c-format +msgid "" +"Column alias injection is needed in the following query (which most likely " +"will fail):" +msgstr "" +"L'injection d'alias de colonne est requise pour la requête suivante (qui " +"risque de ne pas fonctionner) :" + +#. Tag: para +#, no-c-format +msgid "" +"The query was intended to return two Cat instances per row: a cat and its " +"mother. The query will, however, fail because there is a conflict of names; " +"the instances are mapped to the same column names. Also, on some databases " +"the returned column aliases will most likely be on the form \"c.ID\", \"c." +"NAME\", etc. which are not equal to the columns specified in the mappings " +"(\"ID\" and \"NAME\")." +msgstr "" +"Le but de cette requête est de retourner deux instances de Cat par ligne, un " +"chat et sa mère. Cela échouera puisqu'il y a conflit de noms puisqu'ils sont " +"mappés au même nom de colonne et que sur certaines base de données, les " +"alias de colonnes retournés seront plutôt de la forme \"c.ID\", \"c.NAME\", " +"etc. qui ne sont pas égaux aux colonnes spécifiées dans les mappings (\"ID\" " +"et \"NAME\"). " + +#. Tag: para +#, no-c-format +msgid "The following form is not vulnerable to column name duplication:" +msgstr "" +"La forme suivante n'est pas vulnérable à la duplication des noms de " +"colonnes :" + +#. Tag: para +#, no-c-format +msgid "" +"the SQL query string, with placeholders for Hibernate to inject column " +"aliases" +msgstr "" +"la requête SQL, avec des réceptacles pour que Hibernate injecte les alias de " +"colonnes" + +#. Tag: para +#, no-c-format +msgid "the entities returned by the query" +msgstr "les entités retournées par la requête" + +#. Tag: para +#, no-c-format +msgid "" +"The {cat.*} and {mother.*} notation used above is a shorthand for \"all " +"properties\". Alternatively, you can list the columns explicitly, but even " +"in this case Hibernate injects the SQL column aliases for each property. The " +"placeholder for a column alias is just the property name qualified by the " +"table alias. In the following example, you retrieve Cats and their mothers " +"from a different table (cat_log) to the one declared in the mapping " +"metadata. You can even use the property aliases in the where clause." +msgstr "" +"Les notations {cat.*} et {mother.*} utilisées ci-dessus sont un équivalent à " +"'toutes les propriétés'. Alternativement, vous pouvez lister les colonnes " +"explicitement, mais même dans ce cas, nous laissons Hibernate injecter les " +"alias de colonne pour chaque propriété. Le paramètre fictif pour un alias de " +"colonne est simplement le nom de la propriété qualifié par l'alias de la " +"table. Dans l'exemple suivant, nous récupérons les Cats et leur mère depuis " +"une table différente (cat_log) de celle déclarée dans les mappages. Notez " +"que nous pouvons aussi utiliser les alias de propriété dans la clause where " +"si désiré. " + +#. Tag: title +#, no-c-format +msgid "Alias and property references" +msgstr "Références d'alias et de propriété" + +#. Tag: para +#, no-c-format +msgid "" +"In most cases the above alias injection is needed. For queries relating to " +"more complex mappings, like composite properties, inheritance " +"discriminators, collections etc., you can use specific aliases that allow " +"Hibernate to inject the proper aliases." +msgstr "" +"Pour la plupart des cas précédents, l'injection d'alias est requise, mais " +"pour les requêtes relatives à des mappings plus complexes, comme les " +"propriétés composites, les discriminants d'héritage, les collections etc., " +"il y a des alias spécifiques à utiliser pour permettre à Hibernate " +"l'injection des alias appropriés. " + +#. Tag: para +#, no-c-format +msgid "" +"The following table shows the different ways you can use the alias " +"injection. Please note that the alias names in the result are simply " +"examples; each alias will have a unique and probably different name when " +"used." +msgstr "" +"Le tableau suivant montre les diverses possibilités d'utilisation " +"d'injection d'alias. Note : les noms d'alias dans le résultat sont des " +"exemples, chaque alias aura un nom unique et probablement différent " +"lorsqu'ils seront utilisés. " + +#. Tag: title +#, no-c-format +msgid "Alias injection names" +msgstr "Nom d'injection d'alias" + +#. Tag: entry +#, no-c-format +msgid "Description" +msgstr "Description" + +#. Tag: entry +#, no-c-format +msgid "Syntax" +msgstr "Syntaxe" + +#. Tag: entry +#, no-c-format +msgid "Example" +msgstr "Exemple" + +#. Tag: entry +#, no-c-format +msgid "A simple property" +msgstr "Une propriété simple" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].[propertyname]</literal>" +msgstr "<literal>{[aliasname].[propertyname]</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>A_NAME as {item.name}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "A composite property" +msgstr "Une propriété composite" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].[componentname].[propertyname]}</literal>" +msgstr "<literal>{[aliasname].[componentname].[propertyname]}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "" +"<literal>CURRENCY as {item.amount.currency}, VALUE as {item.amount.value}</" +"literal>" +msgstr "" +"<literal>CURRENCY as {item.amount.currency}, VALUE as {item.amount.value}</" +"literal>" + +#. Tag: entry +#, no-c-format +msgid "Discriminator of an entity" +msgstr "Discriminateur d'une entité" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].class}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>DISC as {item.class}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "All properties of an entity" +msgstr "Toutes les propriétés d'une entité" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].*}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "<literal>{item.*}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "A collection key" +msgstr "La clé d'une collection" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].key}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>ORGID as {coll.key}</literal>" +msgstr "<literal>{coll.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "The id of an collection" +msgstr "L'id d'une collection" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].id}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>EMPID as {coll.id}</literal>" +msgstr "<literal>{coll.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "The element of an collection" +msgstr "L'élément d'une collection" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].element}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>XID as {coll.element}</literal>" +msgstr "<literal>{coll.*}</literal>" + +#. Tag: entry +#, no-c-format +msgid "property of the element in the collection" +msgstr "Propriété de l'élément dans une collection " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].element.[propertyname]}</literal>" +msgstr "<literal>{[aliasname].element.[propertyname]}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>NAME as {coll.element.name}</literal>" +msgstr "<literal>NAME as {coll.element.name}</literal>" + +#. Tag: entry +#, no-c-format +msgid "All properties of the element in the collection" +msgstr "Toutes les propriétés d'un élément dans la collection" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{[aliasname].element.*}</literal>" +msgstr "<literal>{item.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>{coll.element.*}</literal>" +msgstr "<literal>{coll.*}</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "All properties of the collection" +msgstr "Toutes les propriétés d'une collection" + +#. Tag: entry +#, no-c-format +msgid "<literal>{coll.*}</literal>" +msgstr "<literal>{coll.*}</literal>" + +#. Tag: title +#, no-c-format +msgid "Returning non-managed entities" +msgstr "Retour d'entités non gérées" + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to apply a ResultTransformer to native SQL queries, allowing " +"it to return non-managed entities." +msgstr "" +"Il est possible d'appliquer un ResultTransformer à une requête native SQL. " +"Ce qui permet, par exemple, de retourner des entités non gérées. " + +#. Tag: para +#, no-c-format +msgid "a result transformer" +msgstr "un transformateur de résultat" + +#. Tag: para +#, no-c-format +msgid "" +"The above query will return a list of <literal>CatDTO</literal> which has " +"been instantiated and injected the values of NAME and BIRTHNAME into its " +"corresponding properties or fields." +msgstr "" +"La requête précédente retournera la liste de <literal>CatDTO</literal> qui " +"ont été instanciés et dans lesquels les valeurs de NAME et BIRTHNAME auront " +"été injectées dans leurs propriétés ou champs correspondants." + +#. Tag: title +#, no-c-format +msgid "Handling inheritance" +msgstr "Gérer l'héritage" + +#. Tag: para +#, no-c-format +msgid "" +"Native SQL queries which query for entities that are mapped as part of an " +"inheritance must include all properties for the baseclass and all its " +"subclasses." +msgstr "" +"Les requêtes natives SQL qui interrogent des entités mappées en tant que " +"part d'un héritage doivent inclure toutes les propriétés de la classe de " +"base et de toutes ses sous classes. " + +#. Tag: title +#, no-c-format +msgid "Parameters" +msgstr "Paramètres" + +#. Tag: para +#, no-c-format +msgid "Native SQL queries support positional as well as named parameters:" +msgstr "" +"Les requêtes natives SQL supportent aussi bien les paramètres de position " +"que les paramètres nommés : " + +#. Tag: title +#, no-c-format +msgid "Named SQL queries" +msgstr "Requêtes SQL nommées" + +#. Tag: para +#, no-c-format +msgid "" +"Named SQL queries can be defined in the mapping document and called in " +"exactly the same way as a named HQL query. In this case, you do " +"<emphasis>not</emphasis> need to call <literal>addEntity()</literal>." +msgstr "" +"Les requêtes SQL nommées peuvent être définies dans le document de mapping " +"et appelées exactement de la même manière qu'une requête HQL nommée. Dans ce " +"cas, nous <emphasis>n'avons pas besoin</emphasis> d'appeler " +"<literal>addEntity()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;return-join&gt;</literal> element is use to join " +"associations and the <literal>&lt;load-collection&gt;</literal> element is " +"used to define queries which initialize collections," +msgstr "" +"Les éléments <literal>&lt;return-join&gt;</literal> et <literal>&lt;load-" +"collection&gt;</literal> sont respectivement utilisés pour lier des " +"associations et définir des requêtes qui initialisent des collections," + +#. Tag: para +#, no-c-format +msgid "" +"A named SQL query may return a scalar value. You must declare the column " +"alias and Hibernate type using the <literal>&lt;return-scalar&gt;</literal> " +"element:" +msgstr "" +"Une requête SQL nommée peut retourner une valeur scalaire. Vous devez " +"spécifier l'alias de colonne et le type Hibernate utilisant l'élément " +"<literal>&lt;return-scalar&gt;</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"You can externalize the resultset mapping information in a <literal>&lt;" +"resultset&gt;</literal> element which will allow you to either reuse them " +"across several named queries or through the <literal>setResultSetMapping()</" +"literal> API." +msgstr "" +"Vous pouvez externaliser les informations de mapping des résultats dans un " +"élément <literal>&lt;resultset&gt;</literal> pour soit les réutiliser dans " +"différentes requêtes nommées, soit à travers l'API " +"<literal>setResultSetMapping()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"You can, alternatively, use the resultset mapping information in your hbm " +"files directly in java code." +msgstr "" +"Vous pouvez également utiliser les informations de mapping de l'ensemble de " +"résultats dans vos fichiers hbm directement dans le code java. " + +#. Tag: title +#, no-c-format +msgid "Using return-property to explicitly specify column/alias names" +msgstr "" +"Utilisation de return-property pour spécifier explicitement les noms des " +"colonnes/alias" + +#. Tag: para +#, no-c-format +msgid "" +"You can explicitly tell Hibernate what column aliases to use with " +"<literal>&lt;return-property&gt;</literal>, instead of using the <literal>{}" +"</literal>-syntax to let Hibernate inject its own aliases.For example:" +msgstr "" +"Avec <literal>&lt;return-property&gt;</literal> vous pouvez explicitement " +"dire à Hibernate quels alias de colonne utiliser, plutôt que d'employer la " +"syntaxe <literal>{}</literal> pour laisser Hibernate injecter ses propres " +"alias. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>&lt;return-property&gt;</literal> also works with multiple columns. " +"This solves a limitation with the <literal>{}</literal>-syntax which cannot " +"allow fine grained control of multi-column properties." +msgstr "" +"<literal>&lt;return-property&gt;</literal> fonctionne aussi avec de " +"multiples colonnes. Cela résout une limitation de la syntaxe <literal>{}</" +"literal> qui ne permet pas une fine granularité des propriétés multi-" +"colonnes. " + +#. Tag: para +#, no-c-format +msgid "" +"In this example <literal>&lt;return-property&gt;</literal> was used in " +"combination with the <literal>{}</literal>-syntax for injection. This allows " +"users to choose how they want to refer column and properties." +msgstr "" +"Notez que dans cet exemple nous avons utilisé <literal>&lt;return-" +"property&gt;</literal> en combinaison avec la syntaxe <literal>{}</literal> " +"pour l'injection. Cela autorise les utilisateurs à choisir comment ils " +"veulent référencer les colonnes et les propriétés. " + +#. Tag: para +#, no-c-format +msgid "" +"If your mapping has a discriminator you must use <literal>&lt;return-" +"discriminator&gt;</literal> to specify the discriminator column." +msgstr "" +"Si votre mapping a un discriminant vous devez utiliser <literal>&lt;return-" +"discriminator&gt;</literal> pour spécifier la colonne discriminante." + +#. Tag: title +#, no-c-format +msgid "Using stored procedures for querying" +msgstr "Utilisation de procédures stockées pour les requêtes" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 provides support for queries via stored procedures and functions. " +"Most of the following documentation is equivalent for both. The stored " +"procedure/function must return a resultset as the first out-parameter to be " +"able to work with Hibernate. An example of such a stored function in Oracle " +"9 and higher is as follows:" +msgstr "" +"Hibernate 3 introduit le support des requêtes via les procédures stockées et " +"les fonctions. La documentation suivante est valable pour les deux. Les " +"procédures stockées/fonctions doivent retourner un ensemble de résultats en " +"tant que premier paramètre sortant (out-parameter\") pour être capable de " +"fonctionner avec Hibernate. Voici un exemple d'une telle procédure stockée " +"en Oracle 9 et version supérieure : " + +#. Tag: para +#, no-c-format +msgid "To use this query in Hibernate you need to map it via a named query." +msgstr "" +"Pour utiliser cette requête dans Hibernate vous avez besoin de la mapper via " +"une requête nommée." + +#. Tag: para +#, no-c-format +msgid "" +"Stored procedures currently only return scalars and entities. <literal>&lt;" +"return-join&gt;</literal> and <literal>&lt;load-collection&gt;</literal> are " +"not supported." +msgstr "" +"Notez que les procédures stockées ne retournent, pour le moment, que des " +"scalaires et des entités. <literal>&lt;return-join&gt;</literal> et " +"<literal>&lt;load-collection&gt;</literal> ne sont pas supportés. " + +#. Tag: title +#, no-c-format +msgid "Rules/limitations for using stored procedures" +msgstr "Règles/limitations lors de l'utilisation des procédures stockées" + +#. Tag: para +#, no-c-format +msgid "" +"You cannot use stored procedures with Hibernate unless you follow some " +"procedure/function rules. If they do not follow those rules they are not " +"usable with Hibernate. If you still want to use these procedures you have to " +"execute them via <literal>session.connection()</literal>. The rules are " +"different for each database, since database vendors have different stored " +"procedure semantics/syntax." +msgstr "" +"Pour utiliser des procédures stockées avec Hibernate, les procédures doivent " +"suivre certaines règles. Si elles ne suivent pas ces règles, elles ne sont " +"pas utilisables avec Hibernate. Si néanmoins, vous désirez utiliser ces " +"procédures vous devez les exécuter via <literal>session.connection()</" +"literal>. Les règles sont différentes pour chaque base de données, puisque " +"les vendeurs de base de données ont des sémantiques/syntaxes différentes " +"pour les procédures stockées. " + +#. Tag: para +#, no-c-format +msgid "" +"Stored procedure queries cannot be paged with <literal>setFirstResult()/" +"setMaxResults()</literal>." +msgstr "" +"Les requêtes de procédures stockées ne peuvent pas être paginées avec " +"<literal>setFirstResult()/setMaxResults()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The recommended call form is standard SQL92: <literal>{ ? = call functionName" +"(&lt;parameters&gt;) }</literal> or <literal>{ ? = call procedureName(&lt;" +"parameters&gt;}</literal>. Native call syntax is not supported." +msgstr "" +"La forme d'appel recommandée est le SQL92 standard : <literal>{ ? = call " +"functionName(&lt;parameters&gt;) }</literal> or <literal>{ ? = call " +"procedureName(&lt;parameters&gt;}</literal>. La syntaxe d'appel native n'est " +"pas supportée." + +#. Tag: para +#, no-c-format +msgid "For Oracle the following rules apply:" +msgstr "Pour Oracle les règles suivantes sont applicables :" + +#. Tag: para +#, no-c-format +msgid "" +"A function must return a result set. The first parameter of a procedure must " +"be an <literal>OUT</literal> that returns a result set. This is done by " +"using a <literal>SYS_REFCURSOR</literal> type in Oracle 9 or 10. In Oracle " +"you need to define a <literal>REF CURSOR</literal> type. See Oracle " +"literature for further information." +msgstr "" +"La procédure doit retourner un ensemble de résultats. Le premier paramètre " +"d'une procédure doit être un <literal>OUT</literal> qui retourne un ensemble " +"de résultats. Ceci est effectué en retournant un <literal>SYS_REFCURSOR</" +"literal> dans Oracle 9 ou 10. Dans Oracle vous avez besoin de définir un " +"type <literal>REF CURSOR</literal>, consultez la documentation Oracle. " + +#. Tag: para +#, no-c-format +msgid "For Sybase or MS SQL server the following rules apply:" +msgstr "Pour Sybase ou MS SQL server les règles suivantes sont applicables :" + +#. Tag: para +#, no-c-format +msgid "" +"The procedure must return a result set. Note that since these servers can " +"return multiple result sets and update counts, Hibernate will iterate the " +"results and take the first result that is a result set as its return value. " +"Everything else will be discarded." +msgstr "" +"La procédure doit retourner un ensemble de résultats. Notez que comme ces " +"serveurs peuvent retourner de multiples ensembles de résultats et mettre à " +"jour des compteurs, Hibernate itèrera les résultats et prendra le premier " +"résultat qui est un ensemble de résultats comme valeur de retour. Tout le " +"reste sera ignoré. " + +#. Tag: para +#, no-c-format +msgid "" +"If you can enable <literal>SET NOCOUNT ON</literal> in your procedure it " +"will probably be more efficient, but this is not a requirement." +msgstr "" +"Si vous pouvez activer <literal>SET NOCOUNT ON</literal> dans votre " +"procédure, elle sera probablement plus efficace, mais ce n'est pas une " +"obligation." + +#. Tag: title +#, no-c-format +msgid "Custom SQL for create, update and delete" +msgstr "SQL personnalisé pour créer, mettre à jour et effacer" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate3 can use custom SQL for create, update, and delete operations. The " +"SQL can be overridden at the statement level or inidividual column level. " +"This section describes statement overrides. For columns, see <xref linkend=" +"\"mapping-column-read-and-write\" />." +msgstr "" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The class and collection persisters in Hibernate already contain a set of " +"configuration time generated strings (insertsql, deletesql, updatesql etc.). " +"The mapping tags <literal>&lt;sql-insert&gt;</literal>, <literal>&lt;sql-" +"delete&gt;</literal>, and <literal>&lt;sql-update&gt;</literal> override " +"these strings:" +msgstr "" +"Hibernate3 peut utiliser des expressions SQL personnalisées pour des " +"opérations de création, de mise à jour, et de suppression. Les objets " +"persistants les classes et les collections dans Hibernate contiennent déjà " +"un ensemble de chaînes de caractères générées lors de la configuration " +"(insertsql, deletesql, updatesql, etc). Les balises de mappage <literal>&lt;" +"sql-insert&gt;</literal>, <literal>&lt;sql-delete&gt;</literal>, et " +"<literal>&lt;sql-update&gt;</literal> surchargent ces chaînes de caractères :" + +#. Tag: para +#, no-c-format +msgid "" +"The SQL is directly executed in your database, so you can use any dialect " +"you like. This will reduce the portability of your mapping if you use " +"database specific SQL." +msgstr "" +"Le SQL est directement exécuté dans votre base de données, donc vous êtes " +"libre d'utiliser le dialecte que vous souhaitez. Cela réduira bien sûr la " +"portabilité de votre mappage si vous utilisez du SQL spécifique à votre base " +"de données. " + +#. Tag: para +#, no-c-format +msgid "" +"Stored procedures are supported if the <literal>callable</literal> attribute " +"is set:" +msgstr "" +"Les procédures stockées sont supportées si l'attribut <literal>callable</" +"literal> est paramétré :" + +#. Tag: para +#, no-c-format +msgid "" +"The order of the positional parameters is vital, as they must be in the same " +"sequence as Hibernate expects them." +msgstr "" +"L'ordre des paramètres de position est essentiel, car ils doivent être dans " +"la séquence attendue par Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"You can view 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 view the expected sequence, do not include " +"your custom SQL in the mapping files, as this will override the Hibernate " +"generated static SQL." +msgstr "" +"Vous pouvez voir l'ordre attendu en activant la journalisation de débogage " +"pour le niveau <literal>org.hibernate.persister.entity</literal>. Avec ce " +"niveau activé, Hibernate imprimera le SQL statique qui est utilisé pour " +"créer, mettre à jour, supprimer, etc. des entités. Pour voir la séquence " +"attendue, rappelez-vous de ne pas inclure votre SQL personnalisé dans les " +"fichiers de mappage car cela surchargera le SQL statique généré par " +"Hibernate." + +#. Tag: para +#, no-c-format +msgid "" +"The stored procedures are in most cases required to return the number of " +"rows inserted, updated and deleted, as Hibernate has some runtime checks for " +"the success of the statement. Hibernate always registers the first statement " +"parameter as a numeric output parameter for the CUD operations:" +msgstr "" +"Les procédures stockées sont dans la plupart des cas (lire : il vaut mieux " +"le faire) requises pour retourner le nombre de lignes insérées/mises à jour/" +"supprimées, puisque Hibernate vérifie plusieurs fois le succès de " +"l'expression. Hibernate inscrit toujours le premier paramètre de " +"l'expression comme un paramètre de sortie numérique pour les opérations " +"CUD : " + +#. Tag: title +#, no-c-format +msgid "Custom SQL for loading" +msgstr "SQL personnalisé pour le chargement" + +#. Tag: para +#, no-c-format +msgid "" +"You can also declare your own SQL (or HQL) queries for entity loading. As " +"with inserts, updates, and deletes, this can be done at the individual " +"column level as described in <xref linkend=\"mapping-column-read-and-write" +"\" /> or at the statement level. Here is an example of a statement level " +"override:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "" +"This is just a named query declaration, as discussed earlier. You can " +"reference this named query in a class mapping:" +msgstr "" +"Ceci est juste une déclaration de requête nommée, comme vu précédemment. " +"Vous pouvez référencer cette requête nommée dans un mappage de classe : " + +#. Tag: para +#, no-c-format +msgid "This even works with stored procedures." +msgstr "Ceci fonctionne même avec des procédures stockées." + +#. Tag: para +#, no-c-format +msgid "You can even define a query for collection loading:" +msgstr "" +"Vous pouvez même définir une requête pour le chargement d'une collection : " + +#. Tag: para +#, no-c-format +msgid "" +"You can also define an entity loader that loads a collection by join " +"fetching:" +msgstr "" +"Vous pourriez même définir un chargeur d'entité qui charge une collection " +"par jointure : " + +#~ msgid "" +#~ "You can also declare your own SQL (or HQL) queries for entity loading:" +#~ msgstr "" +#~ "Vous pouvez aussi déclarer vos propres requêtes SQL (ou HQL) pour le " +#~ "chargement d'entité : " + +#, fuzzy +#~ msgid "A_NAME as {item.name}" +#~ msgstr "<literal>A_NAME as {item.name}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].class}" +#~ msgstr "<literal>{[aliasname].class}</literal>" + +#, fuzzy +#~ msgid "DISC as {item.class}" +#~ msgstr "<literal>DISC as {item.class}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].*}" +#~ msgstr "<literal>{[aliasname].*}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].key}" +#~ msgstr "<literal>{[aliasname].key}</literal>" + +#, fuzzy +#~ msgid "ORGID as {coll.key}" +#~ msgstr "<literal>ORGID as {coll.key}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].id}" +#~ msgstr "<literal>{[aliasname].id}</literal>" + +#, fuzzy +#~ msgid "EMPID as {coll.id}" +#~ msgstr "<literal>EMPID as {coll.id}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].element}" +#~ msgstr "<literal>{[aliasname].element}</literal>" + +#, fuzzy +#~ msgid "XID as {coll.element}" +#~ msgstr "<literal>XID as {coll.element}</literal>" + +#, fuzzy +#~ msgid "{[aliasname].element.*}" +#~ msgstr "<literal>{[aliasname].element.*}</literal>" + +#, fuzzy +#~ msgid "{coll.element.*}" +#~ msgstr "<literal>{coll.element.*}</literal>" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/quickstart.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/quickstart.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/quickstart.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,12 @@ +#, fuzzy +msgid "" +msgstr "" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Content-Type: text/plain; charset=utf-8\n" +msgid "ROLES_OF_TRANSLATORS" +msgstr "<!--TRANS:ROLES_OF_TRANSLATORS-->" + +msgid "CREDIT_FOR_TRANSLATORS" +msgstr "<!--TRANS:CREDIT_FOR_TRANSLATORS-->" + Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/readonly.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/readonly.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/readonly.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1124 @@ +# Language fr-FR translations for PACKAGE package. +# Automatically generated, 2010. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-03-25 06:26+0000\n" +"PO-Revision-Date: 2010-03-25 06:26+0000\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#: readonly.xml:33 +#, no-c-format +msgid "Read-only entities" +msgstr "" + +#. Tag: para +#: readonly.xml:36 +#, no-c-format +msgid "" +"Hibernate's treatment of <emphasis>read-only</emphasis> entities may differ " +"from what you may have encountered elsewhere. Incorrect usage may cause " +"unexpected results." +msgstr "" + +#. Tag: para +#: readonly.xml:43 +#, no-c-format +msgid "When an entity is read-only:" +msgstr "" + +#. Tag: para +#: readonly.xml:48 +#, no-c-format +msgid "" +"Hibernate does not dirty-check the entity's simple properties or single-" +"ended associations;" +msgstr "" + +#. Tag: para +#: readonly.xml:54 +#, no-c-format +msgid "" +"Hibernate will not update simple properties or updatable single-ended " +"associations;" +msgstr "" + +#. Tag: para +#: readonly.xml:60 +#, no-c-format +msgid "" +"Hibernate will not update the version of the read-only entity if only simple " +"properties or single-ended updatable associations are changed;" +msgstr "" + +#. Tag: para +#: readonly.xml:69 +#, no-c-format +msgid "" +"In some ways, Hibernate treats read-only entities the same as entities that " +"are not read-only:" +msgstr "" + +#. Tag: para +#: readonly.xml:75 +#, no-c-format +msgid "" +"Hibernate cascades operations to associations as defined in the entity " +"mapping." +msgstr "" + +#. Tag: para +#: readonly.xml:81 +#, no-c-format +msgid "" +"Hibernate updates the version if the entity has a collection with changes " +"that dirties the entity;" +msgstr "" + +#. Tag: para +#: readonly.xml:87 +#, no-c-format +msgid "A read-only entity can be deleted." +msgstr "" + +#. Tag: para +#: readonly.xml:94 +#, no-c-format +msgid "" +"Even if an entity is not read-only, its collection association can be " +"affected if it contains a read-only entity." +msgstr "" + +#. Tag: para +#: readonly.xml:99 +#, no-c-format +msgid "" +"For details about the affect of read-only entities on different property and " +"association types, see <xref linkend=\"readonly-proptypes\"/>." +msgstr "" + +#. Tag: para +#: readonly.xml:105 +#, no-c-format +msgid "For details about how to make entities read-only, see" +msgstr "" + +#. Tag: para +#: readonly.xml:110 +#, no-c-format +msgid "Hibernate does some optimizing for read-only entities:" +msgstr "" + +#. Tag: para +#: readonly.xml:115 +#, no-c-format +msgid "" +"It saves execution time by not dirty-checking simple properties or single-" +"ended associations." +msgstr "" + +#. Tag: para +#: readonly.xml:121 +#, no-c-format +msgid "It saves memory by deleting database snapshots." +msgstr "" + +#. Tag: title +#: readonly.xml:128 +#, no-c-format +msgid "Making persistent entities read-only" +msgstr "" + +#. Tag: para +#: readonly.xml:130 +#, no-c-format +msgid "" +"Only persistent entities can be made read-only. Transient and detached " +"entities must be put in persistent state before they can be made read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:136 +#, no-c-format +msgid "" +"Hibernate provides the following ways to make persistent entities read-only:" +msgstr "" + +#. Tag: para +#: readonly.xml:142 +#, no-c-format +msgid "" +"you can map an entity class as <emphasis>immutable</emphasis>; when an " +"entity of an immutable class is made persistent, Hibernate automatically " +"makes it read-only. see <xref linkend=\"readonly-api-immutable\"/> for " +"details" +msgstr "" + +#. Tag: para +#: readonly.xml:150 +#, no-c-format +msgid "" +"you can change a default so that entities loaded into the session by " +"Hibernate are automatically made read-only; see <xref linkend=\"readonly-api-" +"loaddefault\"/> for details" +msgstr "" + +#. Tag: para +#: readonly.xml:157 +#, no-c-format +msgid "" +"you can make an HQL query or criteria read-only so that entities loaded when " +"the query or criteria executes, scrolls, or iterates, are automatically made " +"read-only; see <xref linkend=\"readonly-api-querycriteria\"/> for details" +msgstr "" + +#. Tag: para +#: readonly.xml:165 +#, no-c-format +msgid "" +"you can make a persistent entity that is already in the in the session read-" +"only; see <xref linkend=\"readonly-api-entity\"/> for details" +msgstr "" + +#. Tag: title +#: readonly.xml:174 +#, no-c-format +msgid "Entities of immutable classes" +msgstr "" + +#. Tag: para +#: readonly.xml:176 +#, no-c-format +msgid "" +"When an entity instance of an immutable class is made persistent, Hibernate " +"automatically makes it read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:180 +#, no-c-format +msgid "" +"An entity of an immutable class can created and deleted the same as an " +"entity of a mutable class." +msgstr "" + +#. Tag: para +#: readonly.xml:185 +#, no-c-format +msgid "" +"Hibernate treats a persistent entity of an immutable class the same way as a " +"read-only persistent entity of a mutable class. The only exception is that " +"Hibernate will not allow an entity of an immutable class to be changed so it " +"is not read-only." +msgstr "" + +#. Tag: title +#: readonly.xml:196 +#, no-c-format +msgid "Loading persistent entities as read-only" +msgstr "" + +#. Tag: para +#: readonly.xml:199 readonly.xml:286 +#, no-c-format +msgid "Entities of immutable classes are automatically loaded as read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:205 +#, no-c-format +msgid "" +"To change the default behavior so Hibernate loads entity instances of " +"mutable classes into the session and automatically makes them read-only, " +"call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:210 +#, no-c-format +msgid "Session.setDefaultReadOnly( true );" +msgstr "" + +#. Tag: para +#: readonly.xml:212 +#, no-c-format +msgid "" +"To change the default back so entities loaded by Hibernate are not made read-" +"only, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:216 +#, no-c-format +msgid "Session.setDefaultReadOnly( false );" +msgstr "" + +#. Tag: para +#: readonly.xml:218 +#, no-c-format +msgid "You can determine the current setting by calling:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:221 +#, no-c-format +msgid "Session.isDefaultReadOnly();" +msgstr "" + +#. Tag: para +#: readonly.xml:223 +#, no-c-format +msgid "" +"If Session.isDefaultReadOnly() returns true, entities loaded by the " +"following are automatically made read-only:" +msgstr "" + +#. Tag: para +#: readonly.xml:229 +#, no-c-format +msgid "Session.load()" +msgstr "" + +#. Tag: para +#: readonly.xml:234 +#, no-c-format +msgid "Session.get()" +msgstr "" + +#. Tag: para +#: readonly.xml:239 +#, no-c-format +msgid "Session.merge()" +msgstr "" + +#. Tag: para +#: readonly.xml:244 +#, no-c-format +msgid "" +"executing, scrolling, or iterating HQL queries and criteria; to override " +"this setting for a particular HQL query or criteria see" +msgstr "" + +#. Tag: para +#: readonly.xml:253 +#, no-c-format +msgid "Changing this default has no effect on:" +msgstr "" + +#. Tag: para +#: readonly.xml:258 +#, no-c-format +msgid "persistent entities already in the session when the default was changed" +msgstr "" + +#. Tag: para +#: readonly.xml:264 +#, no-c-format +msgid "" +"persistent entities that are refreshed via Session.refresh(); a refreshed " +"persistent entity will only be read-only if it was read-only before " +"refreshing" +msgstr "" + +#. Tag: para +#: readonly.xml:272 +#, no-c-format +msgid "" +"persistent entities added by the application via Session.persist(), Session." +"save(), and Session.update() Session.saveOrUpdate()" +msgstr "" + +#. Tag: title +#: readonly.xml:283 +#, no-c-format +msgid "Loading read-only entities from an HQL query/criteria" +msgstr "" + +#. Tag: para +#: readonly.xml:292 +#, no-c-format +msgid "" +"If Session.isDefaultReadOnly() returns false (the default) when an HQL query " +"or criteria executes, then entities and proxies of mutable classes loaded by " +"the query will not be read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:299 +#, no-c-format +msgid "" +"You can override this behavior so that entities and proxies loaded by an HQL " +"query or criteria are automatically made read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:304 +#, no-c-format +msgid "For an HQL query, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:307 +#, no-c-format +msgid "Query.setReadOnly( true );" +msgstr "" + +#. Tag: para +#: readonly.xml:309 +#, no-c-format +msgid "" +"<literal>Query.setReadOnly( true )</literal> must be called before " +"<literal>Query.list()</literal>, <literal>Query.uniqueResult()</literal>, " +"<literal>Query.scroll()</literal>, or <literal>Query.iterate()</literal>" +msgstr "" + +#. Tag: para +#: readonly.xml:315 +#, no-c-format +msgid "For an HQL criteria, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:318 +#, no-c-format +msgid "Criteria.setReadOnly( true );" +msgstr "" + +#. Tag: para +#: readonly.xml:320 +#, no-c-format +msgid "" +"<literal>Criteria.setReadOnly( true )</literal> must be called before " +"<literal>Criteria.list()</literal>, <literal>Criteria.uniqueResult()</" +"literal>, or <literal>Criteria.scroll()</literal>" +msgstr "" + +#. Tag: para +#: readonly.xml:326 +#, no-c-format +msgid "" +"Entities and proxies that exist in the session before being returned by an " +"HQL query or criteria are not affected." +msgstr "" + +#. Tag: para +#: readonly.xml:331 +#, no-c-format +msgid "" +"Uninitialized persistent collections returned by the query are not affected. " +"Later, when the collection is initialized, entities loaded into the session " +"will be read-only if Session.isDefaultReadOnly() returns true." +msgstr "" + +#. Tag: para +#: readonly.xml:338 +#, no-c-format +msgid "" +"Using <literal>Query.setReadOnly( true )</literal> or <literal>Criteria." +"setReadOnly( true )</literal> works well when a single HQL query or criteria " +"loads all the entities and intializes all the proxies and collections that " +"the application needs to be read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:346 +#, no-c-format +msgid "" +"When it is not possible to load and initialize all necessary entities in a " +"single query or criteria, you can temporarily change the session default to " +"load entities as read-only before the query is executed. Then you can " +"explicitly initialize proxies and collections before restoring the session " +"default." +msgstr "" + +#. Tag: programlisting +#: readonly.xml:355 +#, no-c-format +msgid "" +"Session session = factory.openSession();\n" +"Transaction tx = session.beginTransaction();\n" +" \n" +"setDefaultReadOnly( true );\n" +"Contract contract = \n" +" ( Contract ) session.createQuery(\n" +" \"from Contract where customerName = 'Sherman'\" )\n" +" .uniqueResult();\n" +"Hibernate.initialize( contract.getPlan() );\n" +"Hibernate.initialize( contract.getVariations() );\n" +"Hibernate.initialize( contract.getNotes() );\n" +"setDefaultReadOnly( false );\n" +"...\n" +"tx.commit();\n" +"session.close();" +msgstr "" + +#. Tag: para +#: readonly.xml:357 +#, no-c-format +msgid "" +"If Session.isDefaultReadOnly() returns true, then you can use Query." +"setReadOnly( false ) and Criteria.setReadOnly( false ) to override this " +"session setting and load entities that are not read-only." +msgstr "" + +#. Tag: title +#: readonly.xml:367 +#, no-c-format +msgid "Making a persistent entity read-only" +msgstr "" + +#. Tag: para +#: readonly.xml:369 +#, no-c-format +msgid "" +"Persistent entities of immutable classes are automatically made read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:375 +#, no-c-format +msgid "To make a persistent entity or proxy read-only, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:378 +#, no-c-format +msgid "Session.setReadOnly(entityOrProxy, true)" +msgstr "" + +#. Tag: para +#: readonly.xml:380 +#, no-c-format +msgid "" +"To change a read-only entity or proxy of a mutable class so it is no longer " +"read-only, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:384 +#, no-c-format +msgid "Session.setReadOnly(entityOrProxy, false)" +msgstr "" + +#. Tag: para +#: readonly.xml:387 +#, no-c-format +msgid "" +"When a read-only entity or proxy is changed so it is no longer read-only, " +"Hibernate assumes that the current state of the read-only entity is " +"consistent with its database representation. If this is not true, then any " +"non-flushed changes made before or while the entity was read-only, will be " +"ignored." +msgstr "" + +#. Tag: para +#: readonly.xml:396 +#, no-c-format +msgid "" +"To throw away non-flushed changes and make the persistent entity consistent " +"with its database representation, call:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:400 +#, no-c-format +msgid "session.refresh( entity );" +msgstr "" + +#. Tag: para +#: readonly.xml:402 +#, no-c-format +msgid "" +"To flush changes made before or while the entity was read-only and make the " +"database representation consistent with the current state of the persistent " +"entity:" +msgstr "" + +#. Tag: programlisting +#: readonly.xml:408 +#, no-c-format +msgid "" +"// evict the read-only entity so it is detached\n" +"session.evict( entity );\n" +"\n" +"// make the detached entity (with the non-flushed changes) persistent\n" +"session.update( entity );\n" +"\n" +"// now entity is no longer read-only and its changes can be flushed\n" +"s.flush();" +msgstr "" + +#. Tag: title +#: readonly.xml:413 +#, no-c-format +msgid "Read-only affect on property type" +msgstr "" + +#. Tag: para +#: readonly.xml:415 +#, no-c-format +msgid "" +"The following table summarizes how different property types are affected by " +"making an entity read-only." +msgstr "" + +#. Tag: title +#: readonly.xml:421 +#, no-c-format +msgid "Affect of read-only entity on property types" +msgstr "" + +#. Tag: entry +#: readonly.xml:427 +#, no-c-format +msgid "Property/Association Type" +msgstr "" + +#. Tag: entry +#: readonly.xml:428 +#, no-c-format +msgid "Changes flushed to DB?" +msgstr "" + +#. Tag: entry +#: readonly.xml:433 +#, no-c-format +msgid "Simple" +msgstr "" + +#. Tag: para +#: readonly.xml:435 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-simple\"/>)" +msgstr "" + +#. Tag: entry +#: readonly.xml:439 +#, no-c-format +msgid "<entry>no*</entry>" +msgstr "" + +#. Tag: para +#: readonly.xml:443 +#, no-c-format +msgid "Unidirectional one-to-one" +msgstr "" + +#. Tag: para +#: readonly.xml:444 +#, no-c-format +msgid "Unidirectional many-to-one" +msgstr "" + +#. Tag: para +#: readonly.xml:445 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-singleended-unidir\"/>)" +msgstr "" + +#. Tag: para +#: readonly.xml:451 readonly.xml:452 +#, no-c-format +msgid "<para>no*</para>" +msgstr "" + +#. Tag: para +#: readonly.xml:457 +#, no-c-format +msgid "Unidirectional one-to-many" +msgstr "" + +#. Tag: para +#: readonly.xml:458 +#, no-c-format +msgid "Unidirectional many-to-many" +msgstr "" + +#. Tag: para +#: readonly.xml:459 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-manyended-unidir\"/>)" +msgstr "" + +#. Tag: para +#: readonly.xml:464 readonly.xml:465 readonly.xml:489 +#, no-c-format +msgid "<para>yes</para>" +msgstr "" + +#. Tag: para +#: readonly.xml:470 +#, no-c-format +msgid "<para>Bidirectional one-to-one</para>" +msgstr "" + +#. Tag: para +#: readonly.xml:471 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-onetoone-bidir\"/>)" +msgstr "" + +#. Tag: entry +#: readonly.xml:475 +#, no-c-format +msgid "only if the owning entity is not read-only*" +msgstr "" + +#. Tag: para +#: readonly.xml:479 +#, no-c-format +msgid "<para>Bidirectional one-to-many/many-to-one</para>" +msgstr "" + +#. Tag: para +#: readonly.xml:480 +#, no-c-format +msgid "inverse collection" +msgstr "" + +#. Tag: para +#: readonly.xml:481 +#, no-c-format +msgid "non-inverse collection" +msgstr "" + +#. Tag: para +#: readonly.xml:482 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-onetomany-manytoone\"/>)" +msgstr "" + +#. Tag: para +#: readonly.xml:488 +#, no-c-format +msgid "only added/removed entities that are not read-only*" +msgstr "" + +#. Tag: para +#: readonly.xml:494 +#, no-c-format +msgid "<para>Bidirectional many-to-many</para>" +msgstr "" + +#. Tag: para +#: readonly.xml:495 +#, no-c-format +msgid "(<xref linkend=\"readonly-proptypes-manytomany-bidir\"/>)" +msgstr "" + +#. Tag: entry +#: readonly.xml:499 +#, no-c-format +msgid "<entry>yes</entry>" +msgstr "" + +#. Tag: para +#: readonly.xml:505 +#, no-c-format +msgid "" +"* Behavior is different when the entity having the property/association is " +"read-only, compared to when it is not read-only." +msgstr "" + +#. Tag: title +#: readonly.xml:511 +#, no-c-format +msgid "Simple properties" +msgstr "" + +#. Tag: para +#: readonly.xml:513 +#, no-c-format +msgid "" +"When a persistent object is read-only, Hibernate does not dirty-check simple " +"properties." +msgstr "" + +#. Tag: para +#: readonly.xml:518 +#, no-c-format +msgid "" +"Hibernate will not synchronize simple property state changes to the " +"database. If you have automatic versioning, Hibernate will not increment the " +"version if any simple properties change." +msgstr "" + +#. Tag: programlisting +#: readonly.xml:524 +#, no-c-format +msgid "" +"Session session = factory.openSession();\n" +"Transaction tx = session.beginTransaction();\n" +"\n" +"// get a contract and make it read-only\n" +"Contract contract = ( Contract ) session.get( Contract.class, contractId );\n" +"session.setReadOnly( contract, true );\n" +"\n" +"// contract.getCustomerName() is \"Sherman\"\n" +"contract.setCustomerName( \"Yogi\" );\n" +"tx.commit();\n" +"\n" +"tx = session.beginTransaction();\n" +"\n" +"contract = ( Contract ) session.get( Contract.class, contractId );\n" +"// contract.getCustomerName() is still \"Sherman\"\n" +"...\n" +"tx.commit();\n" +"session.close();" +msgstr "" + +#. Tag: title +#: readonly.xml:529 +#, no-c-format +msgid "Unidirectional associations" +msgstr "" + +#. Tag: title +#: readonly.xml:532 +#, no-c-format +msgid "Unidirectional one-to-one and many-to-one" +msgstr "" + +#. Tag: para +#: readonly.xml:534 +#, no-c-format +msgid "" +"Hibernate treats unidirectional one-to-one and many-to-one associations in " +"the same way when the owning entity is read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:540 +#, no-c-format +msgid "" +"We use the term <emphasis>unidirectional single-ended association</emphasis> " +"when referring to functionality that is common to unidirectional one-to-one " +"and many-to-one associations." +msgstr "" + +#. Tag: para +#: readonly.xml:547 +#, no-c-format +msgid "" +"Hibernate does not dirty-check unidirectional single-ended associations when " +"the owning entity is read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:552 +#, no-c-format +msgid "" +"If you change a read-only entity's reference to a unidirectional single-" +"ended association to null, or to refer to a different entity, that change " +"will not be flushed to the database." +msgstr "" + +#. Tag: para +#: readonly.xml:560 +#, no-c-format +msgid "" +"If an entity is of an immutable class, then its references to unidirectional " +"single-ended associations must be assigned when that entity is first " +"created. Because the entity is automatically made read-only, these " +"references can not be updated." +msgstr "" + +#. Tag: para +#: readonly.xml:570 +#, no-c-format +msgid "" +"If automatic versioning is used, Hibernate will not increment the version " +"due to local changes to unidirectional single-ended associations." +msgstr "" + +#. Tag: para +#: readonly.xml:576 +#, no-c-format +msgid "" +"In the following examples, Contract has a unidirectional many-to-one " +"association with Plan. Contract cascades save and update operations to the " +"association." +msgstr "" + +#. Tag: para +#: readonly.xml:582 +#, no-c-format +msgid "" +"The following shows that changing a read-only entity's many-to-one " +"association reference to null has no effect on the entity's database " +"representation." +msgstr "" + +#. Tag: programlisting +#: readonly.xml:588 +#, no-c-format +msgid "" +"// get a contract with an existing plan;\n" +"// make the contract read-only and set its plan to null \n" +"tx = session.beginTransaction();\n" +"Contract contract = ( Contract ) session.get( Contract.class, contractId );\n" +"session.setReadOnly( contract, true );\n" +"contract.setPlan( null );\n" +"tx.commit();\n" +"\n" +"// get the same contract\n" +"tx = session.beginTransaction();\n" +"contract = ( Contract ) session.get( Contract.class, contractId );\n" +"\n" +"// contract.getPlan() still refers to the original plan;\n" +"\n" +"tx.commit();\n" +"session.close();" +msgstr "" + +#. Tag: para +#: readonly.xml:590 +#, no-c-format +msgid "" +"The following shows that, even though an update to a read-only entity's many-" +"to-one association has no affect on the entity's database representation, " +"flush still cascades the save-update operation to the locally changed " +"association." +msgstr "" + +#. Tag: programlisting +#: readonly.xml:599 +#, no-c-format +msgid "" +"// get a contract with an existing plan;\n" +"// make the contract read-only and change to a new plan\n" +"tx = session.beginTransaction();\n" +"Contract contract = ( Contract ) session.get( Contract.class, contractId );\n" +"session.setReadOnly( contract, true );\n" +"Plan newPlan = new Plan( \"new plan\"\n" +"contract.setPlan( newPlan);\n" +"tx.commit();\n" +"\n" +"// get the same contract\n" +"tx = session.beginTransaction();\n" +"contract = ( Contract ) session.get( Contract.class, contractId );\n" +"newPlan = ( Contract ) session.get( Plan.class, newPlan.getId() ); \n" +"\n" +"// contract.getPlan() still refers to the original plan;\n" +"// newPlan is non-null because it was persisted when \n" +"// the previous transaction was committed; \n" +"\n" +"tx.commit();\n" +"session.close();" +msgstr "" + +#. Tag: title +#: readonly.xml:604 +#, no-c-format +msgid "Unidirectional one-to-many and many-to-many" +msgstr "" + +#. Tag: para +#: readonly.xml:606 +#, no-c-format +msgid "" +"Hibernate treats unidirectional one-to-many and many-to-many associations " +"owned by a read-only entity the same as when owned by an entity that is not " +"read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:613 +#, no-c-format +msgid "" +"Hibernate dirty-checks unidirectional one-to-many and many-to-many " +"associations;" +msgstr "" + +#. Tag: para +#: readonly.xml:618 +#, no-c-format +msgid "" +"The collection can contain entities that are read-only, as well as entities " +"that are not read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:624 +#, no-c-format +msgid "" +"Entities can be added and removed from the collection; changes are flushed " +"to the database." +msgstr "" + +#. Tag: para +#: readonly.xml:629 +#, no-c-format +msgid "" +"If automatic versioning is used, Hibernate will update the version due to " +"changes in the collection if they dirty the owning entity." +msgstr "" + +#. Tag: title +#: readonly.xml:640 +#, no-c-format +msgid "Bidirectional associations" +msgstr "" + +#. Tag: title +#: readonly.xml:643 +#, no-c-format +msgid "<title>Bidirectional one-to-one</title>" +msgstr "" + +#. Tag: para +#: readonly.xml:645 +#, no-c-format +msgid "If a read-only entity owns a bidirectional one-to-one association:" +msgstr "" + +#. Tag: para +#: readonly.xml:652 +#, no-c-format +msgid "Hibernate does not dirty-check the association." +msgstr "" + +#. Tag: para +#: readonly.xml:657 +#, no-c-format +msgid "" +"updates that change the association reference to null or to refer to a " +"different entity will not be flushed to the database." +msgstr "" + +#. Tag: para +#: readonly.xml:664 +#, no-c-format +msgid "" +"If automatic versioning is used, Hibernate will not increment the version " +"due to local changes to the association." +msgstr "" + +#. Tag: para +#: readonly.xml:673 +#, no-c-format +msgid "" +"If an entity is of an immutable class, and it owns a bidirectional one-to-" +"one association, then its reference must be assigned when that entity is " +"first created. Because the entity is automatically made read-only, these " +"references cannot be updated." +msgstr "" + +#. Tag: para +#: readonly.xml:683 +#, no-c-format +msgid "" +"When the owner is not read-only, Hibernate treats an association with a read-" +"only entity the same as when the association is with an entity that is not " +"read-only." +msgstr "" + +#. Tag: title +#: readonly.xml:693 +#, no-c-format +msgid "<title>Bidirectional one-to-many/many-to-one</title>" +msgstr "" + +#. Tag: para +#: readonly.xml:695 +#, no-c-format +msgid "" +"A read-only entity has no impact on a bidirectional one-to-many/many-to-one " +"association if:" +msgstr "" + +#. Tag: para +#: readonly.xml:702 +#, no-c-format +msgid "" +"the read-only entity is on the one-to-many side using an inverse collection;" +msgstr "" + +#. Tag: para +#: readonly.xml:708 +#, no-c-format +msgid "" +"the read-only entity is on the one-to-many side using a non-inverse " +"collection;" +msgstr "" + +#. Tag: para +#: readonly.xml:714 +#, no-c-format +msgid "" +"the one-to-many side uses a non-inverse collection that contains the read-" +"only entity" +msgstr "" + +#. Tag: para +#: readonly.xml:721 +#, no-c-format +msgid "When the one-to-many side uses an inverse collection:" +msgstr "" + +#. Tag: para +#: readonly.xml:727 +#, no-c-format +msgid "" +"a read-only entity can only be added to the collection when it is created;" +msgstr "" + +#. Tag: para +#: readonly.xml:733 +#, no-c-format +msgid "" +"a read-only entity can only be removed from the collection by an orphan " +"delete or by explicitly deleting the entity." +msgstr "" + +#. Tag: title +#: readonly.xml:744 +#, no-c-format +msgid "<title>Bidirectional many-to-many</title>" +msgstr "" + +#. Tag: para +#: readonly.xml:745 +#, no-c-format +msgid "" +"Hibernate treats bidirectional many-to-many associations owned by a read-" +"only entity the same as when owned by an entity that is not read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:752 +#, no-c-format +msgid "Hibernate dirty-checks bidirectional many-to-many associations." +msgstr "" + +#. Tag: para +#: readonly.xml:757 +#, no-c-format +msgid "" +"The collection on either side of the association can contain entities that " +"are read-only, as well as entities that are not read-only." +msgstr "" + +#. Tag: para +#: readonly.xml:763 +#, no-c-format +msgid "" +"Entities are added and removed from both sides of the collection; changes " +"are flushed to the database." +msgstr "" + +#. Tag: para +#: readonly.xml:769 +#, no-c-format +msgid "" +"If automatic versioning is used, Hibernate will update the version due to " +"changes in both sides of the collection if they dirty the entity owning the " +"respective collections." +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/session_api.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/session_api.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/session_api.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1646 @@ +# translation of session_api.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: session_api\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-03-12T00:03:48\n" +"PO-Revision-Date: 2010-01-05 09:57+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Working with objects" +msgstr "Travailler avec des objets" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate is a full object/relational mapping solution that not only shields " +"the developer from the details of the underlying database management system, " +"but also offers <emphasis>state management</emphasis> of objects. This is, " +"contrary to the management of SQL <literal>statements</literal> in common " +"JDBC/SQL persistence layers, a natural object-oriented view of persistence " +"in Java applications." +msgstr "" +"Hibernate est une solution de mappage objet/relationnel complète qui ne " +"masque pas seulement au développeur les détails du système de gestion de " +"base de données sous-jacent, mais offre aussi <emphasis>la gestion d'état</" +"emphasis> des objets. C'est, contrairement à la gestion de " +"<literal>statements</literal> SQL dans les couches de persistance " +"habituelles JDBC/SQL, une vue orientée objet très naturelle de la " +"persistance dans les applications Java." + +#. Tag: para +#, no-c-format +msgid "" +"In other words, Hibernate application developers should always think about " +"the <emphasis>state</emphasis> of their objects, and not necessarily about " +"the execution of SQL statements. This part is taken care of by Hibernate and " +"is only relevant for the application developer when tuning the performance " +"of the system." +msgstr "" +"En d'autres termes, les développeurs d'applications Hibernate devraient " +"toujours réfléchir à <emphasis>l'état</emphasis> de leurs objets, et pas " +"nécessairement à l'exécution des expressions SQL. Cette part est prise en " +"charge par Hibernate et importante seulement aux développeurs d'applications " +"lors du réglage de la performance de leur système." + +#. Tag: title +#, no-c-format +msgid "Hibernate object states" +msgstr "États des objets Hibernate" + +#. Tag: para +#, no-c-format +msgid "Hibernate defines and supports the following object states:" +msgstr "Hibernate définit et prend en charge les états d'objets suivants :" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Transient</emphasis> - an object is transient if it has just been " +"instantiated using the <literal>new</literal> operator, and it is not " +"associated with a Hibernate <literal>Session</literal>. It has no persistent " +"representation in the database and no identifier value has been assigned. " +"Transient instances will be destroyed by the garbage collector if the " +"application does not hold a reference anymore. Use the Hibernate " +"<literal>Session</literal> to make an object persistent (and let Hibernate " +"take care of the SQL statements that need to be executed for this " +"transition)." +msgstr "" +"<emphasis>Éphémère</emphasis> (transient) - un objet est éphémère s'il a " +"juste été instancié en utilisant l'opérateur <literal>new</literal>. Il n'a " +"aucune représentation persistante dans la base de données et aucune valeur " +"d'identifiant n'a été assignée. Les instances éphémères seront détruites par " +"le ramasse-miettes si l'application n'en conserve aucune référence. Utilisez " +"la <literal>Session</literal> d'Hibernate pour rendre un objet persistant " +"(et laisser Hibernate s'occuper des expressions SQL qui ont besoin d'être " +"exécutées pour cette transistion)." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Persistent</emphasis> - a persistent instance has a representation " +"in the database and an identifier value. It might just have been saved or " +"loaded, however, it is by definition in the scope of a <literal>Session</" +"literal>. Hibernate will detect any changes made to an object in persistent " +"state and synchronize the state with the database when the unit of work " +"completes. Developers do not execute manual <literal>UPDATE</literal> " +"statements, or <literal>DELETE</literal> statements when an object should be " +"made transient." +msgstr "" +"<emphasis>Persistant</emphasis> - une instance persistante a une " +"représentation dans la base de données et une valeur d'identifiant. Elle " +"pourrait avoir juste été sauvegardée ou chargée, pourtant, elle est par " +"définition dans la portée d'une <literal>Session</literal>. Hibernate " +"détectera tout changement effectué sur un objet dans l'état persistant et " +"synchronisera l'état avec la base de données lors de la fin de l'unité de " +"travail. Les développeurs n'exécutent pas d'expressions <literal>UPDATE</" +"literal> ou <literal>DELETE</literal> manuelles lorsqu'un objet devrait être " +"rendu éphémère. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Detached</emphasis> - a detached instance is an object that has " +"been persistent, but its <literal>Session</literal> has been closed. The " +"reference to the object is still valid, of course, and the detached instance " +"might even be modified in this state. A detached instance can be reattached " +"to a new <literal>Session</literal> at a later point in time, making it (and " +"all the modifications) persistent again. This feature enables a programming " +"model for long running units of work that require user think-time. We call " +"them <emphasis>application transactions</emphasis>, i.e., a unit of work " +"from the point of view of the user." +msgstr "" +"<emphasis>Détaché</emphasis> - une instance détachée est un objet qui a été " +"persistant, mais dont la <literal>Session</literal> a été fermée. La " +"référence à l'objet est encore valide, bien sûr, et l'instance détachée " +"pourrait même être modifiée dans cet état. Une instance détachée peut être " +"rattachée à une nouvelle <literal>Session</literal> ultérieurement, la " +"rendant (et toutes les modifications avec) de nouveau persistante. Cette " +"fonctionnalité rend possible un modèle de programmation pour de longues " +"unités de travail qui requièrent un temps de réflexion de l'utilisateur. " +"Nous les appelons des <emphasis>conversations</emphasis>, c'est-à-dire une " +"unité de travail du point de vue de l'utilisateur. " + +#. Tag: para +#, no-c-format +msgid "" +"We will now discuss the states and state transitions (and the Hibernate " +"methods that trigger a transition) in more detail." +msgstr "" +"Nous allons maintenant approfondir le sujet des états et des transitions " +"d'état (et des méthodes Hibernate qui déclenchent une transition)." + +#. Tag: title +#, no-c-format +msgid "Making objects persistent" +msgstr "Rendre des objets persistants" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Newly instantiated instances of a persistent class are considered " +"<emphasis>transient</emphasis> by Hibernate. We can make a transient " +"instance <emphasis>persistent</emphasis> by associating it with a session:" +msgstr "" +"Les instances nouvellement instanciées d'une classe persistante sont " +"considérées comme <emphasis>éphémères</emphasis> par Hibernate. Nous pouvons " +"rendre une instance éphémère <emphasis>persistante</emphasis> en l'associant " +"à une session :" + +#. Tag: para +#, no-c-format +msgid "" +"If <literal>Cat</literal> has a generated identifier, the identifier is " +"generated and assigned to the <literal>cat</literal> when <literal>save()</" +"literal> is called. If <literal>Cat</literal> has an <literal>assigned</" +"literal> identifier, or a composite key, the identifier should be assigned " +"to the <literal>cat</literal> instance before calling <literal>save()</" +"literal>. You can also use <literal>persist()</literal> instead of " +"<literal>save()</literal>, with the semantics defined in the EJB3 early " +"draft." +msgstr "" +"Si <literal>Cat</literal> a un identifiant généré, l'identifiant est généré " +"et assigné au <literal>cat</literal> lorsque <literal>save()</literal> est " +"appelé. Si <literal>Cat</literal> a un identifiant <literal>assigned</" +"literal>, ou une clef composée, l'identifiant devrait être assigné à " +"l'instance de <literal>cat</literal> avant d'appeler <literal>save()</" +"literal>. Vous pouvez aussi utiliser <literal>persist()</literal> à la place " +"de <literal>save()</literal>, avec la sémantique définie plus tôt dans la " +"première ébauche d'EJB3. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>persist()</literal> makes a transient instance persistent. However, " +"it does not guarantee that the identifier value will be assigned to the " +"persistent instance immediately, the assignment might happen at flush time. " +"<literal>persist()</literal> also guarantees that it will not execute an " +"<literal>INSERT</literal> statement if it is called outside of transaction " +"boundaries. This is useful in long-running conversations with an extended " +"Session/persistence context." +msgstr "" +"<literal>persist()</literal> rend une instance éphémère persistante. " +"Toutefois, il ne garantit pas que la valeur d'identificateur soit affectée à " +"l'instance permanente immédiatement, l'affectation peut se produire au " +"moment de flush. <literal>Persist()</literal> garantit également qu'il ne " +"s'exécutera pas un énoncé <literal>INSERT</literal> s'il est appelée en " +"dehors des limites de transaction. C'est utile pour les longues " +"conversations dans un contexte de session/persistance étendu." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>save()</literal> does guarantee to return an identifier. If an " +"INSERT has to be executed to get the identifier ( e.g. \"identity\" " +"generator, not \"sequence\"), this INSERT happens immediately, no matter if " +"you are inside or outside of a transaction. This is problematic in a long-" +"running conversation with an extended Session/persistence context." +msgstr "" +"<literal>save()</literal> garantit le retour d'un identifiant. Si une " +"instruction INSERT doit être exécutée pour obtenir l'identifiant (par " +"exemple, le générateur \"identity\", et non pas \"sequence\"), cet INSERT " +"se produit immédiatement, que vous soyez à l'intérieur ou à l'extérieur " +"d'une transaction. C'est problématique dans une conversation longue dans un " +"contexte de session/persistance étendu." + +#. Tag: para +#, no-c-format +msgid "" +"Alternatively, you can assign the identifier using an overloaded version of " +"<literal>save()</literal>." +msgstr "" +"Alternativement, vous pouvez assigner l'identifiant en utilisant une version " +"surchargée de <literal>save()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"If the object you make persistent has associated objects (e.g. the " +"<literal>kittens</literal> collection in the previous example), these " +"objects can be made persistent in any order you like unless you have a " +"<literal>NOT NULL</literal> constraint upon a foreign key column. There is " +"never a risk of violating foreign key constraints. However, you might " +"violate a <literal>NOT NULL</literal> constraint if you <literal>save()</" +"literal> the objects in the wrong order." +msgstr "" +"Si l'objet que vous rendez persistant a des objets associés (par exemple, la " +"collection <literal>kittens</literal> dans l'exemple précédent), ces objets " +"peuvent être rendus persistants dans n'importe quel ordre désiré, à moins " +"que vous ayez une contrainte <literal>NOT NULL</literal> sur la colonne de " +"la clé étrangère. Il n'y a jamais de risque de violer une contrainte de cl. " +"étrangère. Cependant, vous pourriez violer une contrainte <literal>NOT NULL</" +"literal> si vous appeliez <literal>save()</literal> sur les objets dans le " +"mauvais ordre. " + +#. Tag: para +#, no-c-format +msgid "" +"Usually you do not bother with this detail, as you will normally use " +"Hibernate's <emphasis>transitive persistence</emphasis> feature to save the " +"associated objects automatically. Then, even <literal>NOT NULL</literal> " +"constraint violations do not occur - Hibernate will take care of everything. " +"Transitive persistence is discussed later in this chapter." +msgstr "" +"Habituellement, vous ne vous préoccupez pas de ce détail, puisque vous " +"utiliserez très probablement la fonctionnalité de <emphasis>persistance " +"transitive</emphasis> de Hibernate pour sauvegarder les objets associés " +"automatiquement. Alors, même les violations de contrainte <literal>NOT NULL</" +"literal> n'ont plus lieu - Hibernate prendra soin de tout. La persistance " +"transitive est traitée plus loin dans ce chapitre. " + +#. Tag: title +#, no-c-format +msgid "Loading an object" +msgstr "Chargement d'un objet" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>load()</literal> methods of <literal>Session</literal> provide " +"a way of retrieving a persistent instance if you know its identifier. " +"<literal>load()</literal> takes a class object and loads the state into a " +"newly instantiated instance of that class in a persistent state." +msgstr "" +"Les méthodes <literal>load()</literal> de <literal>Session</literal> vous " +"donnent un moyen de récupérer une instance persistante si vous connaissez " +"déjà son identifiant. <literal>load()</literal> prend un objet de classe et " +"chargera l'état dans une instance nouvellement instanciée de cette classe, " +"dans un état persistant. " + +#. Tag: para +#, no-c-format +msgid "Alternatively, you can load state into a given instance:" +msgstr "" +"Alternativement, vous pouvez charger un état dans une instance donnée :" + +#. Tag: para +#, no-c-format +msgid "" +"Be aware that <literal>load()</literal> will throw an unrecoverable " +"exception if there is no matching database row. If the class is mapped with " +"a proxy, <literal>load()</literal> just returns an uninitialized proxy and " +"does not actually hit the database until you invoke a method of the proxy. " +"This is useful if you wish to create an association to an object without " +"actually loading it from the database. It also allows multiple instances to " +"be loaded as a batch if <literal>batch-size</literal> is defined for the " +"class mapping." +msgstr "" +"Notez que <literal>load()</literal> lèvera une exception irrécupérable s'il " +"n'y a pas de ligne correspondante dans la base de données. Si la classe est " +"mappée avec un proxy, <literal>load()</literal> retourne juste un proxy non " +"initialisé et n'accède en fait pas à la base de données jusqu'à ce que vous " +"invoquiez une méthode du proxy. Ce comportement est très utile si vous " +"souhaitez créer une association vers un objet sans réellement le charger à " +"partir de la base de données. Cela permet aussi à de multiples instances " +"d'être chargées comme un lot si <literal>batch-size</literal> est défini " +"pour le mapping de la classe. " + +#. Tag: para +#, no-c-format +msgid "" +"If you are not certain that a matching row exists, you should use the " +"<literal>get()</literal> method which hits the database immediately and " +"returns null if there is no matching row." +msgstr "" +"Si vous n'êtes pas certain qu'une ligne correspondante existe, vous " +"utiliserez la méthode <literal>get()</literal>, laquelle accède à la base de " +"données immédiatement et retourne null s'il n'y a pas de ligne " +"correspondante. " + +#. Tag: para +#, no-c-format +msgid "" +"You can even load an object using an SQL <literal>SELECT ... FOR UPDATE</" +"literal>, using a <literal>LockMode</literal>. See the API documentation for " +"more information." +msgstr "" +"Vous pouvez même charger un objet en employant un SQL <literal>SELECT ... " +"FOR UPDATE</literal>, en utilisant un <literal>LockMode</literal>. Voir la " +"documentation de l'API pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"Any associated instances or contained collections will <emphasis>not</" +"emphasis> be selected <literal>FOR UPDATE</literal>, unless you decide to " +"specify <literal>lock</literal> or <literal>all</literal> as a cascade style " +"for the association." +msgstr "" +"Notez que n'importe quelle instance associée ou collection contenue " +"<emphasis>ne sont pas</emphasis> sélectionnées par <literal>FOR UPDATE</" +"literal>, à moins que vous ne décidiez de spécifier <literal>lock</literal> " +"ou <literal>all</literal> en tant que style de cascade pour l'association." + +#. Tag: para +#, no-c-format +msgid "" +"It is possible to re-load an object and all its collections at any time, " +"using the <literal>refresh()</literal> method. This is useful when database " +"triggers are used to initialize some of the properties of the object." +msgstr "" +"Il est possible de re-charger un objet et toutes ses collections à tout " +"moment, en utilisant la méthode <literal>refresh()</literal>. C'est utile " +"lorsque des \"triggers\" de base de données sont utilisés pour initialiser " +"certaines propriétés de l'objet." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"How much does Hibernate load from the database and how many SQL " +"<literal>SELECT</literal>s will it use? This depends on the " +"<emphasis>fetching strategy</emphasis>. This is explained in <xref linkend=" +"\"performance-fetching\" />." +msgstr "" +"Combien de données Hibernate charge-t-il de la base de données et combien de " +"<literal>SELECT</literal>s utilisera-t-il ? Cela dépend de la " +"<emphasis>stratégie de récupération</emphasis> et cela est expliqué dans " +"<xref linkend=\"performance-fetching\" />." + +#. Tag: title +#, no-c-format +msgid "Querying" +msgstr "Requêtage" + +#. Tag: para +#, no-c-format +msgid "" +"If you do not know the identifiers of the objects you are looking for, you " +"need a query. Hibernate supports an easy-to-use but powerful object oriented " +"query language (HQL). For programmatic query creation, Hibernate supports a " +"sophisticated Criteria and Example query feature (QBC and QBE). You can also " +"express your query in the native SQL of your database, with optional support " +"from Hibernate for result set conversion into objects." +msgstr "" +"Si vous ne connaissez par les identifiants des objets que vous recherchez, " +"vous avez besoin d'une requête. Hibernate supporte un langage de requêtes " +"orientées objet, facile à utiliser mais puissant. Pour la création de " +"requêtes par programmation, Hibernate supporte une fonction de requêtage " +"sophistiquée Criteria et Example (QBC et QBE). Vous pouvez aussi exprimer " +"votre requête dans le SQL natif de votre base de données, avec un support " +"optionnel de Hibernate pour la conversion des ensembles de résultats en " +"objets. " + +#. Tag: title +#, no-c-format +msgid "Executing queries" +msgstr "Exécution de requêtes" + +#. Tag: para +#, no-c-format +msgid "" +"HQL and native SQL queries are represented with an instance of <literal>org." +"hibernate.Query</literal>. This interface offers methods for parameter " +"binding, result set handling, and for the execution of the actual query. You " +"always obtain a <literal>Query</literal> using the current <literal>Session</" +"literal>:" +msgstr "" +"Les requêtes HQL et SQL natives sont représentées avec une instance de " +"<literal>org.hibernate.Query</literal>. L'interface offre des méthodes pour " +"la liaison des paramètres, la gestion des ensembles de résultats, et pour " +"l'exécution de la requête réelle. Vous obtenez toujours une <literal>Query</" +"literal> en utilisant la <literal>Session</literal> courante : " + +#. Tag: para +#, no-c-format +msgid "" +"A query is usually executed by invoking <literal>list()</literal>. The " +"result of the query will be loaded completely into a collection in memory. " +"Entity instances retrieved by a query are in a persistent state. The " +"<literal>uniqueResult()</literal> method offers a shortcut if you know your " +"query will only return a single object. Queries that make use of eager " +"fetching of collections usually return duplicates of the root objects, but " +"with their collections initialized. You can filter these duplicates through " +"a <literal>Set</literal>." +msgstr "" +"Une requête est généralement exécutée en invoquant <literal>list()</" +"literal>, le résultat de la requête sera chargée complètement dans une " +"collection en mémoire. Les instances d'entités récupérées par une requête " +"sont dans un état persistant. La méthode <literal>uniqueResult()</literal> " +"offre un raccourci si vous savez que votre requête retournera un seul objet. " +"Notez que les requêtes qui utilisent le chargement agressif de collections " +"retournent habituellement des copies des objets racine (mais avec leurs " +"collections initialisées). Vous pouvez simplement filtrer ces copies via un " +"<literal>Set</literal>. " + +#. Tag: title +#, no-c-format +msgid "Iterating results" +msgstr "Itération de résultats" + +#. Tag: para +#, no-c-format +msgid "" +"Occasionally, you might be able to achieve better performance by executing " +"the query using the <literal>iterate()</literal> method. This will usually " +"be the case if you expect that the actual entity instances returned by the " +"query will already be in the session or second-level cache. If they are not " +"already cached, <literal>iterate()</literal> will be slower than " +"<literal>list()</literal> and might require many database hits for a simple " +"query, usually <emphasis>1</emphasis> for the initial select which only " +"returns identifiers, and <emphasis>n</emphasis> additional selects to " +"initialize the actual instances." +msgstr "" +"Parfois, vous serez en mesure d'obtenir de meilleures performances en " +"exécutant la requête avec la méthode <literal>iterate()</literal>. En " +"général, ce sera uniquement le cas si vous attendez que les instances " +"réelles d'entité retournées par la requête, soient déjà chargées dans la " +"session ou le cache de second niveau. Si elles ne sont pas déjà cachées, " +"<literal>iterate()</literal> sera plus lent que <literal>list()</literal> et " +"pourrait nécessiter plusieurs accès à la base de données pour une simple " +"requête, généralement <emphasis>1</emphasis> pour le select initial qui " +"retourne seulement les identifiants, et <emphasis>n</emphasis> selects " +"supplémentaires pour initialiser les instances réelles. " + +#. Tag: title +#, no-c-format +msgid "Queries that return tuples" +msgstr "Requêtes qui retournent des tuples" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate queries sometimes return tuples of objects. Each tuple is returned " +"as an array:" +msgstr "" +"Les requêtes d'Hibernate retournent parfois des tuples d'objets, auquel cas " +"chaque tuple est retourné comme un tableau : " + +#. Tag: title +#, no-c-format +msgid "Scalar results" +msgstr "Résultats scalaires" + +#. Tag: para +#, no-c-format +msgid "" +"Queries can specify a property of a class in the <literal>select</literal> " +"clause. They can even call SQL aggregate functions. Properties or aggregates " +"are considered \"scalar\" results and not entities in persistent state." +msgstr "" +"Certaines requêtes peuvent spécifier une propriété de classe dans la clause " +"<literal>select</literal>. Elles peuvent même appeler des fonctions " +"d'aggrégat SQL. Les propriétés ou les aggrégats sont considérés comme des " +"résultats \"scalaires\" (et non des entités dans un état persistant). " + +#. Tag: title +#, no-c-format +msgid "Bind parameters" +msgstr "Lier des paramètres" + +#. Tag: para +#, no-c-format +msgid "" +"Methods on <literal>Query</literal> are provided for binding values to named " +"parameters or JDBC-style <literal>?</literal> parameters. <emphasis>Contrary " +"to JDBC, Hibernate numbers parameters from zero.</emphasis> Named parameters " +"are identifiers of the form <literal>:name</literal> in the query string. " +"The advantages of named parameters are as follows:" +msgstr "" +"Des méthodes de <literal>Query</literal> sont fournies pour lier des valeurs " +"à des paramètres nommés ou à des paramètres de style JDBC <literal>?</" +"literal>. <emphasis>Contrairement à JDBC, les numéros des paramètres de " +"Hibernate commencent à zéro.</emphasis> Les paramètres nommés sont des " +"identifiants de la forme <literal>:nom</literal> dans la chaîne de " +"caractères de la requête. Les avantages des paramètres nommés sont : " + +#. Tag: para +#, no-c-format +msgid "" +"named parameters are insensitive to the order they occur in the query string" +msgstr "" +"les paramètres nommés sont insensibles à l'ordre dans lequel ils " +"apparaissent dans la chaîne de la requête" + +#. Tag: para +#, no-c-format +msgid "they can occur multiple times in the same query" +msgstr "ils peuvent apparaître plusieurs fois dans la même requête " + +#. Tag: para +#, no-c-format +msgid "they are self-documenting" +msgstr "ils sont auto-documentés" + +#. Tag: title +#, no-c-format +msgid "Pagination" +msgstr "Pagination" + +#. Tag: para +#, no-c-format +msgid "" +"If you need to specify bounds upon your result set, that is, the maximum " +"number of rows you want to retrieve and/or the first row you want to " +"retrieve, you can use methods of the <literal>Query</literal> interface:" +msgstr "" +"Si vous avez besoin de spécifier des liens sur votre ensemble de résultats " +"(le nombre maximum de lignes et/ou la première ligne que vous voulez " +"récupérer) vous utiliserez des méthodes de l'interface <literal>Query</" +"literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate knows how to translate this limit query into the native SQL of " +"your DBMS." +msgstr "" +"Hibernate sait comment traduire cette requête de limite en SQL natif pour " +"votre SGBD." + +#. Tag: title +#, no-c-format +msgid "Scrollable iteration" +msgstr "Itération \"scrollable\"" + +#. Tag: para +#, no-c-format +msgid "" +"If your JDBC driver supports scrollable <literal>ResultSet</literal>s, the " +"<literal>Query</literal> interface can be used to obtain a " +"<literal>ScrollableResults</literal> object that allows flexible navigation " +"of the query results." +msgstr "" +"Si votre connecteur JDBC supporte les <literal>ResultSet</literal> s " +"\"scrollables\", l'interface <literal>Query</literal> peut être utilisée " +"pour obtenir un objet <literal>ScrollableResults</literal>, qui permettra " +"une navigation flexible dans les résultats de la requête. " + +#. Tag: para +#, no-c-format +msgid "" +"Note that an open database connection and cursor is required for this " +"functionality. Use <literal>setMaxResult()</literal>/<literal>setFirstResult" +"()</literal> if you need offline pagination functionality." +msgstr "" +"Notez qu'une connexion ouverte (et un curseur) est requise pour cette " +"fonctionnalité, utilisez <literal>setMaxResult()</literal>/" +"<literal>setFirstResult()</literal> si vous avez besoin d'une fonctionnalité " +"de pagination hors ligne. " + +#. Tag: title +#, no-c-format +msgid "Externalizing named queries" +msgstr "Externaliser des requêtes nommées" + +#. Tag: para +#, no-c-format +msgid "" +"You can also define named queries in the mapping document. Remember to use a " +"<literal>CDATA</literal> section if your query contains characters that " +"could be interpreted as markup." +msgstr "" +"Vous pouvez aussi définir des requêtes nommées dans le document de mapping. " +"Souvenez-vous d'utiliser une section <literal>CDATA</literal> si votre " +"requête contient des caractères qui pourraient être interprétés comme des " +"éléments XML." + +#. Tag: para +#, no-c-format +msgid "Parameter binding and executing is done programatically:" +msgstr "" +"La liaison de paramètres et l'exécution sont effectués par programmation :" + +#. Tag: para +#, no-c-format +msgid "" +"The actual program code is independent of the query language that is used. " +"You can also define native SQL queries in metadata, or migrate existing " +"queries to Hibernate by placing them in mapping files." +msgstr "" +"Notez que le code réel du programme est indépendant du langage de requête " +"utilisé, vous pouvez aussi définir des requêtes SQL natives dans les méta-" +"données, ou migrer des requêtes existantes vers Hibernate en les plaçant " +"dans les fichiers de mapping. " + +#. Tag: para +#, no-c-format +msgid "" +"Also note that a query declaration inside a <literal>&lt;hibernate-" +"mapping&gt;</literal> element requires a global unique name for the query, " +"while a query declaration inside a <literal>&lt;class&gt;</literal> element " +"is made unique automatically by prepending the fully qualified name of the " +"class. For example <literal>eg.Cat.ByNameAndMaximumWeight</literal>." +msgstr "" +"Notez aussi que la déclaration d'une requête dans un élément <literal>&lt;" +"hibernate-mapping&gt;</literal> nécessite un nom globalement unique pour la " +"requête, alors que la déclaration d'une requête dans un élément <literal>&lt;" +"class&gt;</literal> est rendue unique de manière automatique par la mise en " +"préfixe du nom entièrement qualifié de la classe, par exemple <literal>eg." +"Cat.ByNameAndMaximumWeight</literal>. " + +#. Tag: title +#, no-c-format +msgid "Filtering collections" +msgstr "Filtrer des collections" + +#. Tag: para +#, no-c-format +msgid "" +"A collection <emphasis>filter</emphasis> is a special type of query that can " +"be applied to a persistent collection or array. The query string can refer " +"to <literal>this</literal>, meaning the current collection element." +msgstr "" +"Un <emphasis>filtre</emphasis> de collection est un type spécial de requête " +"qui peut être appliqué à une collection persistante ou à un tableau. La " +"chaîne de requêtes peut se référer à <literal>this</literal>, correspondant " +"à l'élément de la collection courant. " + +#. Tag: para +#, no-c-format +msgid "" +"The returned collection is considered a bag that is a copy of the given " +"collection. The original collection is not modified. This is contrary to the " +"implication of the name \"filter\", but consistent with expected behavior." +msgstr "" +"La collection retournée est considérée comme un bag, et c'est une copie de " +"la collection donnée. La collection originale n'est pas modifiée. C'est " +"contraire à l'implication du nom \"filtre\"; mais cohérent avec le " +"comportement attendu." + +#. Tag: para +#, no-c-format +msgid "" +"Observe that filters do not require a <literal>from</literal> clause, " +"although they can have one if required. Filters are not limited to returning " +"the collection elements themselves." +msgstr "" +"Observez que les filtres ne nécessitent pas une clause <literal>from</" +"literal> (bien qu'ils puissent en avoir une si besoin est). Les filtres ne " +"sont pas limités à retourner des éléments de la collection eux-mêmes. " + +#. Tag: para +#, no-c-format +msgid "" +"Even an empty filter query is useful, e.g. to load a subset of elements in a " +"large collection:" +msgstr "" +"Même une requête de filtre vide est utile, par exemple pour charger un sous-" +"ensemble d'éléments dans une énorme collection : " + +#. Tag: title +#, no-c-format +msgid "Criteria queries" +msgstr "Requêtes par critères" + +#. Tag: para +#, no-c-format +msgid "" +"HQL is extremely powerful, but some developers prefer to build queries " +"dynamically using an object-oriented API, rather than building query " +"strings. Hibernate provides an intuitive <literal>Criteria</literal> query " +"API for these cases:" +msgstr "" +"HQL est extrêmement puissant, mais certains développeurs préfèrent " +"construire des requêtes dynamiquement, en utilisant l'API orientée objet, " +"plutôt que de construire des chaînes de requêtes. Hibernate fournit une API " +"intuitive de requête <literal>Criteria</literal> pour ces cas :" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The <literal>Criteria</literal> and the associated <literal>Example</" +"literal> API are discussed in more detail in <xref linkend=\"querycriteria" +"\" />." +msgstr "" +"L'API <literal>Criteria</literal> et l'API<literal>Example</literal> associé " +"sont traités plus en détail dans <xref linkend=\"querycriteria\" />." + +#. Tag: title +#, no-c-format +msgid "Queries in native SQL" +msgstr "Requêtes en SQL natif" + +#. Tag: para +#, no-c-format +msgid "" +"You can express a query in SQL, using <literal>createSQLQuery()</literal> " +"and let Hibernate manage the mapping from result sets to objects. You can at " +"any time call <literal>session.connection()</literal> and use the JDBC " +"<literal>Connection</literal> directly. If you choose to use the Hibernate " +"API, you must enclose SQL aliases in braces:" +msgstr "" +"Vous pouvez exprimer une requête en SQL, en utilisant <literal>createSQLQuery" +"()</literal> et laisser Hibernate s'occuper du mappage des résultats vers " +"des objets. Notez que vous pouvez à tout moment, appeler <literal>session." +"connection()</literal> et utiliser directement la <literal>Connection</" +"literal> JDBC. Si vous choisissez d'utiliser l'API Hibernate, vous devez " +"mettre les alias SQL entre accolades : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"SQL queries can contain named and positional parameters, just like Hibernate " +"queries. More information about native SQL queries in Hibernate can be found " +"in <xref linkend=\"querysql\" />." +msgstr "" +"Les requêtes SQL peuvent contenir des paramètres nommés et positionnels, " +"comme les requêtes Hibernate. Vous trouverez plus d'informations à propos " +"des requêtes SQL natives dans Hibernate dans <xref linkend=\"querysql\" />." + +#. Tag: title +#, no-c-format +msgid "Modifying persistent objects" +msgstr "Modifier des objets persistants" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Transactional persistent instances</emphasis> (i.e. objects " +"loaded, saved, created or queried by the <literal>Session</literal>) can be " +"manipulated by the application, and any changes to persistent state will be " +"persisted when the <literal>Session</literal> is <emphasis>flushed</" +"emphasis>. This is discussed later in this chapter. There is no need to call " +"a particular method (like <literal>update()</literal>, which has a different " +"purpose) to make your modifications persistent. The most straightforward way " +"to update the state of an object is to <literal>load()</literal> it and then " +"manipulate it directly while the <literal>Session</literal> is open:" +msgstr "" +"Les <emphasis>instances persistantes transactionnelles</emphasis> (c'est-à-" +"dire des objets chargés, sauvegardés, créés ou requêtés par la " +"<literal>Session</literal>) peuvent être manipulés par l'application et tout " +"changement vers l'état persistant sera persisté lorsque la <literal>Session</" +"literal> est <emphasis>\"flushée\"</emphasis> (traité plus tard dans ce " +"chapitre). Il n'est pas nécessaire d'appeler une méthode particulière (comme " +"<literal>update()</literal>, qui a un but différent) pour rendre vos " +"modifications persistantes. Donc la manière la plus directe de mettre à jour " +"l'état d'un objet est de le charger avec <literal>load()</literal>, et puis " +"de le manipuler directement, tant que la <literal>Session</literal> est " +"ouverte : " + +#. Tag: para +#, no-c-format +msgid "" +"Sometimes this programming model is inefficient, as it requires in the same " +"session both an SQL <literal>SELECT</literal> to load an object and an SQL " +"<literal>UPDATE</literal> to persist its updated state. Hibernate offers an " +"alternate approach by using detached instances." +msgstr "" +"Parfois ce modèle de programmation est inefficace puisqu'il nécessiterait un " +"SQL <literal>SELECT</literal> (pour charger l'objet) et un SQL " +"<literal>UPDATE</literal> (pour persister son état mis à jour) dans la même " +"session. Ainsi Hibernate offre une autre approche, en utilisant des " +"instances détachées. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Hibernate does not offer its own API for direct execution of " +"<literal>UPDATE</literal> or <literal>DELETE</literal> statements. Hibernate " +"is a <emphasis>state management</emphasis> service, you do not have to think " +"in <emphasis>statements</emphasis> to use it. JDBC is a perfect API for " +"executing SQL statements, you can get a JDBC <literal>Connection</literal> " +"at any time by calling <literal>session.connection()</literal>. Furthermore, " +"the notion of mass operations conflicts with object/relational mapping for " +"online transaction processing-oriented applications. Future versions of " +"Hibernate can, however, provide special mass operation functions. See <xref " +"linkend=\"batch\" /> for some possible batch operation tricks." +msgstr "" +"Notez que Hibernate n'offre par sa propre API pour l'exécution directe " +"d'expressions <literal>UPDATE</literal> ou <literal>DELETE</literal>. " +"Hibernate est un service de <emphasis>gestion d'état</emphasis>, vous n'avez " +"pas à penser aux <emphasis>expressions</emphasis> pour l'utiliser. JDBC est " +"une API parfaite pour exécuter des expressions SQL, vous pouvez obtenir une " +"<literal>Connection</literal> JDBC à tout moment en appelant " +"<literal>session.connection()</literal>. En outre, la notion d'opérations de " +"masse entre en conflit avec le mapping objet/relationnel pour les " +"applications orientées processus de transactions en ligne. Les futures " +"versions de Hibernate pourront cependant fournir des fonctions particulières " +"d'opération de masse. Voir <xref linkend=\"batch\" /> pour des astuces " +"possibles d'opérations groupées. " + +#. Tag: title +#, no-c-format +msgid "Modifying detached objects" +msgstr "Modifier des objets détachés" + +#. Tag: para +#, no-c-format +msgid "" +"Many applications need to retrieve an object in one transaction, send it to " +"the UI layer for manipulation, then save the changes in a new transaction. " +"Applications that use this kind of approach in a high-concurrency " +"environment usually use versioned data to ensure isolation for the \"long\" " +"unit of work." +msgstr "" +"Beaucoup d'applications ont besoin de récupérer un objet dans une " +"transaction, de l'envoyer à la couche interfacée avec l'utilisateur pour les " +"manipulations, et de sauvegarder les changements dans une nouvelle " +"transaction. Les applications qui utilisent cette approche dans un " +"environnement à haute concurrence utilisent généralement des données " +"versionnées pour assurer l'isolation des \"longues\" unités de travail." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate supports this model by providing for reattachment of detached " +"instances using the <literal>Session.update()</literal> or <literal>Session." +"merge()</literal> methods:" +msgstr "" +"Hibernate supporte ce modèle en permettant pour le rattachement d'instances " +"détachées en utilisant des méthodes <literal>Session.update()</literal> ou " +"<literal>Session.merge()</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"If the <literal>Cat</literal> with identifier <literal>catId</literal> had " +"already been loaded by <literal>secondSession</literal> when the application " +"tried to reattach it, an exception would have been thrown." +msgstr "" +"Si le <literal>Cat</literal> avec l'identifiant <literal>catId</literal> " +"avait déjà été chargé par <literal>secondSession</literal> lorsque " +"l'application a essayé de le rattacher, une exception aurait été levée." + +#. Tag: para +#, no-c-format +msgid "" +"Use <literal>update()</literal> if you are certain that the session does not " +"contain an already persistent instance with the same identifier. Use " +"<literal>merge()</literal> if you want to merge your modifications at any " +"time without consideration of the state of the session. In other words, " +"<literal>update()</literal> is usually the first method you would call in a " +"fresh session, ensuring that the reattachment of your detached instances is " +"the first operation that is executed." +msgstr "" +"Utilisez <literal>update()</literal> si vous êtes sûr que la session ne " +"contient pas déjà une instance persistante avec le même identifiant, et " +"<literal>merge()</literal> si vous voulez fusionner vos modifications " +"n'importe quand sans considérer l'état de la session. En d'autres termes, " +"<literal>update()</literal> est généralement la première méthode que vous " +"devez appeler dans une session fraîche, pour vous assurer que le " +"rattachement de vos instances détachées est la première opération qui est " +"exécutée. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The application should individually <literal>update()</literal> detached " +"instances that are reachable from the given detached instance " +"<emphasis>only</emphasis> if it wants their state to be updated. This can be " +"automated using <emphasis>transitive persistence</emphasis>. See <xref " +"linkend=\"objectstate-transitive\" /> for more information." +msgstr "" +"L'application devrait individuellement <literal>update()</literal> (NdT : " +"mettre à jour) les instances détachées accessibles depuis l'instance " +"détachée donnée si et <emphasis>seulement</emphasis> si elle veut que leur " +"état soit aussi mis à jour. Ceci peut être automatisé bien sûr, en utilisant " +"la <emphasis>persistance transitive</emphasis>. Voir <xref linkend=" +"\"objectstate-transitive\" /> pour plus d'informations." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>lock()</literal> method also allows an application to " +"reassociate an object with a new session. However, the detached instance has " +"to be unmodified." +msgstr "" +"La méthode <literal>lock()</literal> permet aussi à une application de ré-" +"associer un objet avec une nouvelle session. Cependant, l'instance détachée " +"doit être non modifiée." + +#. Tag: para +#, no-c-format +msgid "" +"Note that <literal>lock()</literal> can be used with various " +"<literal>LockMode</literal>s. See the API documentation and the chapter on " +"transaction handling for more information. Reattachment is not the only " +"usecase for <literal>lock()</literal>." +msgstr "" +"Notez que <literal>lock()</literal> peut être utilisé avec différents " +"<literal>LockMode</literal> s, voir la documentation de l'API et le chapitre " +"sur la gestion des transactions pour plus d'informations. Le rattachement " +"n'est pas le seul cas d'utilisation pour <literal>lock()</literal>. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Other models for long units of work are discussed in <xref linkend=" +"\"transactions-optimistic\" />." +msgstr "" +"D'autres modèles pour de longues unités de travail sont traités dans <xref " +"linkend=\"transactions-optimistic\" />." + +#. Tag: title +#, no-c-format +msgid "Automatic state detection" +msgstr "Détection automatique d'un état" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate users have requested a general purpose method that either saves a " +"transient instance by generating a new identifier or updates/reattaches the " +"detached instances associated with its current identifier. The " +"<literal>saveOrUpdate()</literal> method implements this functionality." +msgstr "" +"Les utilisateurs d'Hibernate ont demandé une méthode dont l'intention " +"générale serait soit de sauvegarder une instance éphémère en générant un " +"nouvel identifiant, soit mettre à jour/rattacher les instances détachées " +"associées à l'identifiant courant. La méthode <literal>saveOrUpdate()</" +"literal> implémente cette fonctionnalité." + +#. Tag: para +#, no-c-format +msgid "" +"The usage and semantics of <literal>saveOrUpdate()</literal> seems to be " +"confusing for new users. Firstly, so long as you are not trying to use " +"instances from one session in another new session, you should not need to " +"use <literal>update()</literal>, <literal>saveOrUpdate()</literal>, or " +"<literal>merge()</literal>. Some whole applications will never use either of " +"these methods." +msgstr "" +"L'usage et la sémantique de <literal>saveOrUpdate()</literal> semble être " +"confuse pour les nouveaux utilisateurs. Premièrement, aussi longtemps que " +"vous n'essayez pas d'utiliser des instances d'une session dans une autre, " +"vous ne devriez pas avoir besoin d'utiliser <literal>update()</literal>, " +"<literal>saveOrUpdate()</literal>, ou <literal>merge()</literal>. Certaines " +"applications n'utiliseront jamais ces méthodes." + +#. Tag: para +#, no-c-format +msgid "" +"Usually <literal>update()</literal> or <literal>saveOrUpdate()</literal> are " +"used in the following scenario:" +msgstr "" +"Généralement <literal>update()</literal> ou <literal>saveOrUpdate()</" +"literal> sont utilisées dans le scénario suivant :" + +#. Tag: para +#, no-c-format +msgid "the application loads an object in the first session" +msgstr "l'application charge un objet dans la première session" + +#. Tag: para +#, no-c-format +msgid "the object is passed up to the UI tier" +msgstr "l'objet est passé à la couche utilisateur" + +#. Tag: para +#, no-c-format +msgid "some modifications are made to the object" +msgstr "certaines modifications sont effectuées sur l'objet" + +#. Tag: para +#, no-c-format +msgid "the object is passed back down to the business logic tier" +msgstr "l'objet est retourné à la couche logique métier" + +#. Tag: para +#, no-c-format +msgid "" +"the application persists these modifications by calling <literal>update()</" +"literal> in a second session" +msgstr "" +"l'application persiste ces modifications en appelant <literal>update()</" +"literal> dans une seconde session" + +#. Tag: para +#, no-c-format +msgid "<literal>saveOrUpdate()</literal> does the following:" +msgstr "<literal>saveOrUpdate()</literal> s'utilise dans le cas suivant :" + +#. Tag: para +#, no-c-format +msgid "if the object is already persistent in this session, do nothing" +msgstr "si l'objet est déjà persistant dans cette session, ne rien faire" + +#. Tag: para +#, no-c-format +msgid "" +"if another object associated with the session has the same identifier, throw " +"an exception" +msgstr "" +"si un autre objet associé à la session a le même identifiant, lever une " +"exception" + +#. Tag: para +#, no-c-format +msgid "if the object has no identifier property, <literal>save()</literal> it" +msgstr "" +"si l'objet n'a pas de propriété d'identifiant, appeler <literal>save()</" +"literal>" + +#. Tag: para +#, no-c-format +msgid "" +"if the object's identifier has the value assigned to a newly instantiated " +"object, <literal>save()</literal> it" +msgstr "" +"si l'identifiant de l'objet a une valeur assignée à un objet nouvellement " +"instancié, appeler <literal>save()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"if the object is versioned by a <literal>&lt;version&gt;</literal> or " +"<literal>&lt;timestamp&gt;</literal>, and the version property value is the " +"same value assigned to a newly instantiated object, <literal>save()</" +"literal> it" +msgstr "" +"si l'objet est versionné (par <literal>&lt;version&gt;</literal> ou " +"<literal>&lt;timestamp&gt;</literal>), et la valeur de la propriété de " +"version est la même valeur que celle assignée à un objet nouvellement " +"instancié, appeler <literal>save()</literal> " + +#. Tag: para +#, no-c-format +msgid "otherwise <literal>update()</literal> the object" +msgstr "sinon mettre à jour l'objet avec <literal>update()</literal>" + +#. Tag: para +#, no-c-format +msgid "and <literal>merge()</literal> is very different:" +msgstr "et <literal>merge()</literal> est très différent :" + +#. Tag: para +#, no-c-format +msgid "" +"if there is a persistent instance with the same identifier currently " +"associated with the session, copy the state of the given object onto the " +"persistent instance" +msgstr "" +"s'il y a une instance persistante avec le même identifiant couramment " +"associé à la session, copier l'état de l'objet donné dans l'instance " +"persistante" + +#. Tag: para +#, no-c-format +msgid "" +"if there is no persistent instance currently associated with the session, " +"try to load it from the database, or create a new persistent instance" +msgstr "" +"s'il n'y a pas d'instance persistante associée à cette session, essayer de " +"le charger à partir de la base de données, ou créer une nouvelle instance " +"persistante" + +#. Tag: para +#, no-c-format +msgid "the persistent instance is returned" +msgstr "l'instance persistante est retournée" + +#. Tag: para +#, no-c-format +msgid "" +"the given instance does not become associated with the session, it remains " +"detached" +msgstr "" +"l'instance donnée ne devient pas associée à la session, elle reste détachée" + +#. Tag: title +#, no-c-format +msgid "Deleting persistent objects" +msgstr "Suppression d'objets persistants" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>Session.delete()</literal> will remove an object's state from the " +"database. Your application, however, can still hold a reference to a deleted " +"object. It is best to think of <literal>delete()</literal> as making a " +"persistent instance, transient." +msgstr "" +"<literal>Session.delete()</literal> supprimera l'état d'un objet de la base " +"de données. Bien sûr, votre application pourrait encore conserver une " +"référence vers un objet effacé. Il est préférable de penser à <literal>delete" +"()</literal> comme rendant une instance persistante éphémère. " + +#. Tag: para +#, no-c-format +msgid "" +"You can delete objects in any order, without risk of foreign key constraint " +"violations. It is still possible to violate a <literal>NOT NULL</literal> " +"constraint on a foreign key column by deleting objects in the wrong order, e." +"g. if you delete the parent, but forget to delete the children." +msgstr "" +"Vous pouvez effacer des objets dans l'ordre que vous voulez, sans risque de " +"violations de contrainte de clef étrangère. Il est encore possible de violer " +"une contrainte <literal>NOT NULL</literal> sur une colonne de clef étrangère " +"en effaçant des objets dans le mauvais ordre, par exemple si vous effacez le " +"parent, mais oubliez d'effacer les enfants. " + +#. Tag: title +#, no-c-format +msgid "Replicating object between two different datastores" +msgstr "Réplication d'objets entre deux entrepôts de données" + +#. Tag: para +#, no-c-format +msgid "" +"It is sometimes useful to be able to take a graph of persistent instances " +"and make them persistent in a different datastore, without regenerating " +"identifier values." +msgstr "" +"Il est occasionnellement utile de pouvoir prendre un graphe d'instances " +"persistantes et de les rendre persistantes dans un entrepôt différent, sans " +"regénérer les valeurs des identifiants. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>ReplicationMode</literal> determines how <literal>replicate()</" +"literal> will deal with conflicts with existing rows in the database:" +msgstr "" +"Le <literal>ReplicationMode</literal> détermine comment <literal>replicate()" +"</literal> traitera les conflits avec des lignes existantes dans la base de " +"données. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ReplicationMode.IGNORE</literal>: ignores the object when there is " +"an existing database row with the same identifier" +msgstr "" +"<literal>ReplicationMode.IGNORE</literal> - ignore l'objet s'il y a une " +"ligne existante dans la base de données avec le même identifiant " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ReplicationMode.OVERWRITE</literal>: overwrites any existing " +"database row with the same identifier" +msgstr "" +"<literal>ReplicationMode.OVERWRITE</literal> - écrase n'importe quelle ligne " +"existante dans la base de données avec le même identifiant " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ReplicationMode.EXCEPTION</literal>: throws an exception if there " +"is an existing database row with the same identifier" +msgstr "" +"<literal>ReplicationMode.EXCEPTION</literal> - lève une exception s'il y a " +"une ligne dans la base de données avec le même identifiant " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ReplicationMode.LATEST_VERSION</literal>: overwrites the row if its " +"version number is earlier than the version number of the object, or ignore " +"the object otherwise" +msgstr "" +"<literal>ReplicationMode.LATEST_VERSION</literal> - écrase la ligne si son " +"numéro de version est plus petit que le numéro de version de l'objet, sinon " +"ignore l'objet " + +#. Tag: para +#, no-c-format +msgid "" +"Usecases for this feature include reconciling data entered into different " +"database instances, upgrading system configuration information during " +"product upgrades, rolling back changes made during non-ACID transactions and " +"more." +msgstr "" +"Les cas d'utilisation de cette fonctionnalité incluent la réconciliation de " +"données entrées dans différentes base de données, l'extension des " +"informations de configuration du système durant une mise à jour du produit, " +"retour en arrière sur les changements effectués durant des transactions non-" +"ACID, et plus." + +#. Tag: title +#, no-c-format +msgid "Flushing the Session" +msgstr "Flush de la session" + +#. Tag: para +#, no-c-format +msgid "" +"Sometimes the <literal>Session</literal> will execute the SQL statements " +"needed to synchronize the JDBC connection's state with the state of objects " +"held in memory. This process, called <emphasis>flush</emphasis>, occurs by " +"default at the following points:" +msgstr "" +"De temps en temps la <literal>Session</literal> exécutera les expressions " +"SQL requises pour synchroniser l'état de la connexion JDBC avec l'état des " +"objets retenus en mémoire. Ce processus, <emphasis>flush</emphasis>, " +"survient par défaut aux points suivants : " + +#. Tag: para +#, no-c-format +msgid "before some query executions" +msgstr "avant certaines exécutions de requête" + +#. Tag: para +#, no-c-format +msgid "from <literal>org.hibernate.Transaction.commit()</literal>" +msgstr "" +"lors d'un appel à <literal>org.hibernate.Transaction.commit()</literal>" + +#. Tag: para +#, no-c-format +msgid "from <literal>Session.flush()</literal>" +msgstr "lors d'un appel à <literal>Session.flush()</literal>" + +#. Tag: para +#, no-c-format +msgid "The SQL statements are issued in the following order:" +msgstr "Les expressions SQL sont effectuées dans l'ordre suivant : " + +#. Tag: para +#, no-c-format +msgid "" +"all entity insertions in the same order the corresponding objects were saved " +"using <literal>Session.save()</literal>" +msgstr "" +"insertion des entités, dans le même ordre que celui des objets " +"correspondants sauvegardés par l'appel à <literal>Session.save()</literal> " + +#. Tag: para +#, no-c-format +msgid "all entity updates" +msgstr "mise à jour des entités" + +#. Tag: para +#, no-c-format +msgid "all collection deletions" +msgstr "suppression des collections" + +#. Tag: para +#, no-c-format +msgid "all collection element deletions, updates and insertions" +msgstr "suppression, mise à jour et insertion des éléments des collections" + +#. Tag: para +#, no-c-format +msgid "all collection insertions" +msgstr "insertion des collections" + +#. Tag: para +#, no-c-format +msgid "" +"all entity deletions in the same order the corresponding objects were " +"deleted using <literal>Session.delete()</literal>" +msgstr "" +"suppression des entités, dans le même ordre que celui des objets " +"correspondants qui ont été supprimés par l'appel de <literal>Session.delete()" +"</literal> " + +#. Tag: para +#, no-c-format +msgid "" +"An exception is that objects using <literal>native</literal> ID generation " +"are inserted when they are saved." +msgstr "" +"Une exception est que des objets utilisant la génération <literal>native</" +"literal> d'identifiants sont insérés lorsqu'ils sont sauvegardés." + +#. Tag: para +#, no-c-format +msgid "" +"Except when you explicitly <literal>flush()</literal>, there are absolutely " +"no guarantees about <emphasis>when</emphasis> the <literal>Session</literal> " +"executes the JDBC calls, only the <emphasis>order</emphasis> in which they " +"are executed. However, Hibernate does guarantee that the <literal>Query.list" +"(..)</literal> will never return stale or incorrect data." +msgstr "" +"Excepté lorsque vous appelez <literal>flush()</literal> explicitement, il " +"n'y a absolument aucune garantie à propos de <emphasis>quand</emphasis> la " +"<literal>Session</literal> exécute les appels JDBC, seulement sur " +"l'<emphasis>ordre</emphasis> dans lequel ils sont exécutés. Cependant, " +"Hibernate garantit que <literal>Query.list(..)</literal> ne retournera " +"jamais de données périmées, ni des données fausses. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"It is possible to change the default behavior so that flush occurs less " +"frequently. The <literal>FlushMode</literal> class defines three different " +"modes: only flush at commit time when the Hibernate <literal>Transaction</" +"literal> API is used, flush automatically using the explained routine, or " +"never flush unless <literal>flush()</literal> is called explicitly. The last " +"mode is useful for long running units of work, where a <literal>Session</" +"literal> is kept open and disconnected for a long time (see <xref linkend=" +"\"transactions-optimistic-longsession\" />)." +msgstr "" +"Il est possible de changer le comportement par défaut, donc que le flush se " +"produise moins fréquemment. La classe <literal>FlushMode</literal> définit " +"trois modes différents : flush seulement lors du commit (et seulement quand " +"l'API <literal>Transaction</literal> de Hibernate est utilisé), flush " +"automatiquement en utilisant la procédure courante expliquée, ou jamais de " +"flush à moins que <literal>flush()</literal> soit appelé explicitement. Le " +"dernier mode est utile pour l'exécution de longues unités de travail, où une " +"<literal>Session</literal> est gardée ouverte et déconnectée pour un long " +"moment (voir <xref linkend=\"transactions-optimistic-longsession\" />)." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"During flush, an exception might occur (e.g. if a DML operation violates a " +"constraint). Since handling exceptions involves some understanding of " +"Hibernate's transactional behavior, we discuss it in <xref linkend=" +"\"transactions\" />." +msgstr "" +"Durant le flush, une exception peut se produire (par exemple, si une " +"opération de la DML viole une contrainte). Les exceptions de gestion " +"impliquent une certaine compréhension du comportement transactionnel de " +"Hibernate, le sujet sera donc abordé dans <xref linkend=\"transactions\" />." + +#. Tag: title +#, no-c-format +msgid "Transitive persistence" +msgstr "Persistance transitive" + +#. Tag: para +#, no-c-format +msgid "" +"It is quite cumbersome to save, delete, or reattach individual objects, " +"especially if you deal with a graph of associated objects. A common case is " +"a parent/child relationship. Consider the following example:" +msgstr "" +"Il est assez pénible de sauvegarder, supprimer, ou rattacher des objets un " +"par un, surtout si vous traitez un graphe d'objets associés. Un cas courant " +"est une relation parent/enfant. Considérez l'exemple suivant :" + +#. Tag: para +#, no-c-format +msgid "" +"If the children in a parent/child relationship would be value typed (e.g. a " +"collection of addresses or strings), their life cycle would depend on the " +"parent and no further action would be required for convenient \"cascading\" " +"of state changes. When the parent is saved, the value-typed child objects " +"are saved and when the parent is deleted, the children will be deleted, etc. " +"This works for operations such as the removal of a child from the " +"collection. Since value-typed objects cannot have shared references, " +"Hibernate will detect this and delete the child from the database." +msgstr "" +"Si les enfants de la relation parent/enfant étaient des types de valeur (par " +"exemple, une collection d'adresses ou de chaînes de caractères), leur cycle " +"de vie dépendrait du parent et aucune action ne serait requise pour " +"\"cascader\" facilement les changements d'état. Si le parent est sauvegardé, " +"les objets enfants de type de valeur sont sauvegardés également, si le " +"parent est supprimé, les enfants sont supprimés, etc. Ceci fonctionne même " +"pour des opérations telles que la suppression d'un enfant de la collection ; " +"Hibernate le détectera et étant donné que les objets de type de valeur ne " +"peuvent pas avoir de références partagées, il supprimera l'enfant de la base " +"de données. " + +#. Tag: para +#, no-c-format +msgid "" +"Now consider the same scenario with parent and child objects being entities, " +"not value-types (e.g. categories and items, or parent and child cats). " +"Entities have their own life cycle and support shared references. Removing " +"an entity from the collection does not mean it can be deleted), and there is " +"by default no cascading of state from one entity to any other associated " +"entities. Hibernate does not implement <emphasis>persistence by " +"reachability</emphasis> by default." +msgstr "" +"Maintenant considérez le même scénario avec un parent dont les objets " +"enfants sont des entités, et non des types de valeur (par exemple, des " +"catégories et des objets, ou un parent et des chatons). Les entités ont leur " +"propre cycle de vie, supportent les références partagées (donc supprimer une " +"entité de la collection ne signifie pas qu'elle peut être supprimée), et il " +"n'y a par défaut pas de cascade d'état d'une entité vers n'importe quelle " +"entité associée. Hibernate n'implémente pas la <emphasis>persistance par " +"accessibilité</emphasis> par défaut. " + +#. Tag: para +#, no-c-format +msgid "" +"For each basic operation of the Hibernate session - including " +"<literal>persist(), merge(), saveOrUpdate(), delete(), lock(), refresh(), " +"evict(), replicate()</literal> - there is a corresponding cascade style. " +"Respectively, the cascade styles are named <literal>create, merge, save-" +"update, delete, lock, refresh, evict, replicate</literal>. If you want an " +"operation to be cascaded along an association, you must indicate that in the " +"mapping document. For example:" +msgstr "" +"Pour chaque opération basique de la session Hibernate - incluant " +"<literal>persist(), merge(), saveOrUpdate(), delete(), lock(), refresh(), " +"evict(), replicate()</literal> - il y a un style de cascade correspondant. " +"Respectivement, les styles de cascade s'appellent <literal>persist, merge, " +"save-update, delete, lock, refresh, evict, replicate</literal>. Si vous " +"voulez qu'une opération soit cascadée le long d'une association, vous devez " +"l'indiquer dans le document de mappage. Par exemple :" + +#. Tag: para +#, no-c-format +msgid "Cascade styles my be combined:" +msgstr "Les styles de cascade peuvent être combinés :" + +#. Tag: para +#, no-c-format +msgid "" +"You can even use <literal>cascade=\"all\"</literal> to specify that " +"<emphasis>all</emphasis> operations should be cascaded along the " +"association. The default <literal>cascade=\"none\"</literal> specifies that " +"no operations are to be cascaded." +msgstr "" +"Vous pouvez même utiliser <literal>cascade=\"all\"</literal> pour spécifier " +"que <emphasis>toutes</emphasis> les opérations devraient être cascadées le " +"long de l'association. La valeur par défaut <literal>cascade=\"none\"</" +"literal> spécifie qu'aucune opération ne sera cascadée. " + +#. Tag: para +#, no-c-format +msgid "" +"A special cascade style, <literal>delete-orphan</literal>, applies only to " +"one-to-many associations, and indicates that the <literal>delete()</literal> " +"operation should be applied to any child object that is removed from the " +"association." +msgstr "" +"Un style de cascade spécial, <literal>delete-orphan</literal>, s'applique " +"seulement aux associations un-à-plusieurs, et indique que l'opération " +"<literal>delete()</literal> devrait être appliquée à tout enfant supprimé de " +"l'association." + +#. Tag: para +#, no-c-format +msgid "Recommendations:" +msgstr "Recommandations :" + +#. Tag: para +#, no-c-format +msgid "" +"It does not usually make sense to enable cascade on a <literal>&lt;many-to-" +"one&gt;</literal> or <literal>&lt;many-to-many&gt;</literal> association. " +"Cascade is often useful for <literal>&lt;one-to-one&gt;</literal> and " +"<literal>&lt;one-to-many&gt;</literal> associations." +msgstr "" +"Cela n'a généralement aucun sens d'activer la cascade sur une association " +"<literal>&lt;many-to-one&gt;</literal> ou <literal>&lt;many-to-many&gt;</" +"literal>. Les cascades sont souvent utiles pour des associations " +"<literal>&lt;one-to-one&gt;</literal> et <literal>&lt;one-to-many&gt;</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"If the child object's lifespan is bounded by the lifespan of the parent " +"object, make it a <emphasis>life cycle object</emphasis> by specifying " +"<literal>cascade=\"all,delete-orphan\"</literal>." +msgstr "" +"Si la durée de vie de l'objet enfant est liée à la durée de vie de l'objet " +"parent, faites-en un <emphasis>objet du cycle de vie</emphasis> en " +"spécifiant <literal>cascade=\"all,delete-orphan\"</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Otherwise, you might not need cascade at all. But if you think that you will " +"often be working with the parent and children together in the same " +"transaction, and you want to save yourself some typing, consider using " +"<literal>cascade=\"persist,merge,save-update\"</literal>." +msgstr "" +"Sinon, vous pourriez ne pas avoir besoin de cascade du tout. Mais si vous " +"pensez que vous travaillerez souvent avec le parent et les enfants ensemble " +"dans la même transaction, et que vous voulez vous éviter quelques frappes, " +"considérez l'utilisation de <literal>cascade=\"persist,merge,save-update\"</" +"literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Mapping an association (either a single valued association, or a collection) " +"with <literal>cascade=\"all\"</literal> marks the association as a " +"<emphasis>parent/child</emphasis> style relationship where save/update/" +"delete of the parent results in save/update/delete of the child or children." +msgstr "" +"Mapper une association (soit une simple association valuée, soit une " +"collection) avec <literal>cascade=\"all\"</literal> marque l'association " +"comme une relation de style <emphasis>parent/enfant</emphasis> où la " +"sauvegarde/mise à jour/suppression du parent entraîne la sauvegarde/mise à " +"jour/suppression de l'enfant ou des enfants." + +#. Tag: para +#, no-c-format +msgid "" +"Furthermore, a mere reference to a child from a persistent parent will " +"result in save/update of the child. This metaphor is incomplete, however. A " +"child which becomes unreferenced by its parent is <emphasis>not</emphasis> " +"automatically deleted, except in the case of a <literal>&lt;one-to-many&gt;</" +"literal> association mapped with <literal>cascade=\"delete-orphan\"</" +"literal>. The precise semantics of cascading operations for a parent/child " +"relationship are as follows:" +msgstr "" +"Par ailleurs, une simple référence à un enfant d'un parent persistant aura " +"pour conséquence la sauvegarde/mise à jour de l'enfant. Cette métaphore est " +"cependant incomplète. Un enfant qui devient non référencé par son parent " +"<emphasis>n'est pas</emphasis> automatiquement supprimé, sauf dans le cas " +"d'une association <literal>&lt;one-to-many&gt;</literal> mappée avec " +"<literal>cascade=\"delete-orphan\"</literal>. La sémantique précise des " +"opérations de cascade pour une relation parent/enfant est la suivante : " + +#. Tag: para +#, no-c-format +msgid "" +"If a parent is passed to <literal>persist()</literal>, all children are " +"passed to <literal>persist()</literal>" +msgstr "" +"Si un parent est passé à <literal>persist()</literal>, tous les enfant sont " +"passés à <literal>persist()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"If a parent is passed to <literal>merge()</literal>, all children are passed " +"to <literal>merge()</literal>" +msgstr "" +"Si un parent est passé à <literal>merge()</literal>, tous les enfants sont " +"passés à <literal>merge()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"If a parent is passed to <literal>save()</literal>, <literal>update()</" +"literal> or <literal>saveOrUpdate()</literal>, all children are passed to " +"<literal>saveOrUpdate()</literal>" +msgstr "" +"Si un parent est passé à <literal>save()</literal>, <literal>update()</" +"literal> ou <literal>saveOrUpdate()</literal>, tous les enfants sont passés " +"à <literal>saveOrUpdate()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"If a transient or detached child becomes referenced by a persistent parent, " +"it is passed to <literal>saveOrUpdate()</literal>" +msgstr "" +"Si un enfant détaché ou éphémère devient référencé par un parent persistant, " +"il est passé à <literal>saveOrUpdate()</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"If a parent is deleted, all children are passed to <literal>delete()</" +"literal>" +msgstr "" +"Si un parent est supprimé, tous les enfants sont passés à <literal>delete()</" +"literal>" + +#. Tag: para +#, no-c-format +msgid "" +"If a child is dereferenced by a persistent parent, <emphasis>nothing special " +"happens</emphasis> - the application should explicitly delete the child if " +"necessary - unless <literal>cascade=\"delete-orphan\"</literal>, in which " +"case the \"orphaned\" child is deleted." +msgstr "" +"Si un enfant est déréférencé par un parent persistant, <emphasis>rien de " +"spécial n'arrive</emphasis> - l'application devrait explicitement supprimer " +"l'enfant si nécessaire - à moins que <literal>cascade=\"delete-orphan\"</" +"literal> soit paramétré, auquel cas l'enfant \"orphelin\" est supprimé." + +#. Tag: para +#, no-c-format +msgid "" +"Finally, note that cascading of operations can be applied to an object graph " +"at <emphasis>call time</emphasis> or at <emphasis>flush time</emphasis>. All " +"operations, if enabled, are cascaded to associated entities reachable when " +"the operation is executed. However, <literal>save-update</literal> and " +"<literal>delete-orphan</literal> are transitive for all associated entities " +"reachable during flush of the <literal>Session</literal>." +msgstr "" +"Enfin, la cascade des opérations peut être effectuée sur un graphe donné " +"lors de l'<emphasis>appel de l'opération</emphasis> or lors du " +"<emphasis>flush</emphasis> suivant. Toutes les opérations, lorsqu'elles sont " +"cascadées, le sont sur toutes les entités associées accessibles lorsque " +"l'opération est exécutée. Cependant <literal>save-upate</literal> et " +"<literal>delete-orphan</literal> sont cascadés à toutes les entités " +"associées accessibles lors du flush de la <literal>Session</literal>. " + +#. Tag: title +#, no-c-format +msgid "Using metadata" +msgstr "Utilisation des méta-données" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate requires a rich meta-level model of all entity and value types. " +"This model can be useful to the application itself. For example, the " +"application might use Hibernate's metadata to implement a \"smart\" deep-" +"copy algorithm that understands which objects should be copied (eg. mutable " +"value types) and which objects that should not (e.g. immutable value types " +"and, possibly, associated entities)." +msgstr "" +"Hibernate requiert un modèle de méta-niveau très riche de toutes les entités " +"et types valués. De temps en temps, ce modèle est très utile à l'application " +"elle même. Par exemple, l'application pourrait utiliser les méta-données de " +"Hibernate pour implémenter un algorithme de copie en profondeur \"intelligent" +"\" qui comprendrait quels objets devraient être copiés (par exemple les " +"types de valeur mutables) et lesquels ne devraient pas l'être (par exemple " +"les types de valeurs immutables et, éventuellement, les entités associées). " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate exposes metadata via the <literal>ClassMetadata</literal> and " +"<literal>CollectionMetadata</literal> interfaces and the <literal>Type</" +"literal> hierarchy. Instances of the metadata interfaces can be obtained " +"from the <literal>SessionFactory</literal>." +msgstr "" +"Hibernate expose les méta-données via les interfaces <literal>ClassMetadata</" +"literal> et <literal>CollectionMetadata</literal> et la hiérarchie " +"<literal>Type</literal>. Les instances des interfaces de méta-données " +"peuvent être obtenues à partir de la <literal>SessionFactory</literal>. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/toolset_guide.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/toolset_guide.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/toolset_guide.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,892 @@ +# translation of toolset_guide.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: toolset_guide\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:16\n" +"PO-Revision-Date: 2010-01-05 10:05+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Toolset Guide" +msgstr "Guide de la boîte à outils" + +#. Tag: para +#, no-c-format +msgid "" +"Roundtrip engineering with Hibernate is possible using a set of Eclipse " +"plugins, commandline tools, and Ant tasks." +msgstr "" +"Des outils en ligne de commande, des plugins Eclipse ainsi que des tâches " +"Ant permettent de gérer le développement complet de projets à travers " +"Hibernate. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Hibernate Tools</emphasis> currently include plugins for the " +"Eclipse IDE as well as Ant tasks for reverse engineering of existing " +"databases:" +msgstr "" +"Les <emphasis>outils Hibernate</emphasis> actuels incluent des plugins pour " +"l'IDE Eclipse ainsi que des tâches Ant pour l'ingénierie inverse de bases de " +"données existantes : " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Mapping Editor:</emphasis> an editor for Hibernate XML mapping " +"files that supports auto-completion and syntax highlighting. It also " +"supports semantic auto-completion for class names and property/field names, " +"making it more versatile than a normal XML editor." +msgstr "" +"<emphasis>Mapping Editor :</emphasis> un éditeur pour les fichiers de " +"mappage XML Hibernate, supportant l'auto-finalisation et la mise en valeur " +"de la syntaxe. Il supporte aussi la sémantique d'auto-finalisation pour les " +"noms de classes et les noms de propriété/champs, le rendant beaucoup plus " +"polyvalent qu'un éditeur XML ordinaire." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Console:</emphasis> the console is a new view in Eclipse. In " +"addition to a tree overview of your console configurations, you are also " +"provided with an interactive view of your persistent classes and their " +"relationships. The console allows you to execute HQL queries against your " +"database and browse the result directly in Eclipse." +msgstr "" +"<emphasis>Console :</emphasis> la console est une nouvelle vue d'Eclipse. En " +"plus de la vue d'ensemble arborescente de vos configurations de console, " +"vous obtenez aussi une vue interactive de vos classes persistantes et de " +"leurs relations. La console vous permet d'exécuter des requête HQL dans " +"votre base de données et de parcourir les résultats directement dans Eclipse." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Development Wizards:</emphasis> several wizards are provided with " +"the Hibernate Eclipse tools. You can use a wizard to quickly generate " +"Hibernate configuration (cfg.xml) files, or to reverse engineer an existing " +"database schema into POJO source files and Hibernate mapping files. The " +"reverse engineering wizard supports customizable templates." +msgstr "" +"<emphasis>Development Wizards :</emphasis> plusieurs assistants sont fournis " +"avec les outils de Hibernate pour Eclipse ; vous pouvez utiliser un " +"assistant pour générer rapidement les fichiers de configuration Hibernate " +"(cfg.xml), ou vous pouvez même complètement générer les fichiers de mappage " +"Hibernate et les sources des POJOs à partir d'un schéma de base de données " +"existant. L'assistant d'ingénierie inverse supporte les modèles utilisateur. " + +#. Tag: para +#, no-c-format +msgid "" +"Please refer to the <emphasis>Hibernate Tools</emphasis> package " +"documentation for more information." +msgstr "" +"Veuillez-vous référer au paquetage <emphasis>Outils Hibernate</emphasis> et " +"à sa documentation pour plus d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"However, the Hibernate main package comes bundled with an integrated tool : " +"<emphasis>SchemaExport</emphasis> aka <literal>hbm2ddl</literal>.It can even " +"be used from \"inside\" Hibernate." +msgstr "" +"Cependant, le paquetage principal de Hibernate arrive avec un ensemble " +"d'outils intégrés (il peut même être utilisé de \"l'intérieur\" de Hibernate " +"à la volée) : <emphasis>SchemaExport</emphasis> aussi connu comme " +"<literal>hbm2ddl</literal>. " + +#. Tag: title +#, no-c-format +msgid "Automatic schema generation" +msgstr "Génération automatique du schéma" + +#. Tag: para +#, no-c-format +msgid "" +"DDL can be generated from your mapping files by a Hibernate utility. The " +"generated schema includes referential integrity constraints, primary and " +"foreign keys, for entity and collection tables. Tables and sequences are " +"also created for mapped identifier generators." +msgstr "" +"La DDL peut être générée à partir de vos fichiers de mappage par un " +"utilitaire Hibernate. Le schéma généré inclut les contraintes d'intégrité " +"référentielle (clefs primaires et étrangères) pour les tables d'entités et " +"de collections. Les tables et les séquences sont aussi créées pour les " +"générateurs d'identifiants mappés. " + +#. Tag: para +#, no-c-format +msgid "" +"You <emphasis>must</emphasis> specify a SQL <literal>Dialect</literal> via " +"the <literal>hibernate.dialect</literal> property when using this tool, as " +"DDL is highly vendor-specific." +msgstr "" +"Vous <emphasis>devez</emphasis> spécifier un <literal>Dialect</literal> SQL " +"via la propriété <literal>hibernate.dialect</literal> lors de l'utilisation " +"de cet outil, puisque la DDL est fortement dépendante du vendeur spécifique. " + +#. Tag: para +#, no-c-format +msgid "" +"First, you must customize your mapping files to improve the generated " +"schema. The next section covers schema customization." +msgstr "" +"D'abord, personnalisez vos fichiers de mappage pour améliorer le schéma " +"généré. " + +#. Tag: title +#, no-c-format +msgid "Customizing the schema" +msgstr "Personnaliser le schéma" + +#. Tag: para +#, no-c-format +msgid "" +"Many Hibernate mapping elements define optional attributes named " +"<literal>length</literal>, <literal>precision</literal> and <literal>scale</" +"literal>. You can set the length, precision and scale of a column with this " +"attribute." +msgstr "" +"Plusieurs éléments du mappage Hibernate définissent des attributs optionnels " +"nommés <literal>length</literal>, <literal>precision</literal> et " +"<literal>scale</literal>. Vous pouvez paramétrer la taille, la précision, et " +"l'échelle d'une colonne avec cet attribut. " + +#. Tag: para +#, no-c-format +msgid "" +"Some tags also accept a <literal>not-null</literal> attribute for generating " +"a <literal>NOT NULL</literal> constraint on table columns, and a " +"<literal>unique</literal> attribute for generating <literal>UNIQUE</literal> " +"constraint on table columns." +msgstr "" +"Certaines balises acceptent aussi un attribut <literal>not-null</literal> " +"utilisé pour générer les contraintes de colonnes <literal>NOT NULL</literal> " +"et un attribut <literal>unique</literal> pour générer une contrainte " +"<literal>UNIQUE</literal> de colonnes de table." + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>unique-key</literal> attribute can be used to group columns in a " +"single, unique key constraint. Currently, the specified value of the " +"<literal>unique-key</literal> attribute is <emphasis>not</emphasis> used to " +"name the constraint in the generated DDL. It is only used to group the " +"columns in the mapping file." +msgstr "" +"Un attribut <literal>unique-key</literal> peut être utilisé pour grouper les " +"colonnes en une seule contrainte d'unicité. Actuellement, la valeur " +"spécifiée par l'attribut <literal>unique-key</literal> n'est <emphasis>pas</" +"emphasis> utilisée pour nommer la contrainte dans la DDL générée, elle sert " +"juste à grouper les colonnes dans le fichier de mappage. " + +#. Tag: para +#, no-c-format +msgid "" +"An <literal>index</literal> attribute specifies the name of an index that " +"will be created using the mapped column or columns. Multiple columns can be " +"grouped into the same index by simply specifying the same index name." +msgstr "" +"Un attribut <literal>index</literal> indique le nom d'un index qui sera créé " +"en utilisant la ou les colonnes mappées. Plusieurs colonnes peuvent être " +"groupées dans un même index, en spécifiant le même nom d'index. " + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>foreign-key</literal> attribute can be used to override the name " +"of any generated foreign key constraint." +msgstr "" +"Un attribut <literal>foreign-key</literal> peut être utilisé pour surcharger " +"le nom des clés étrangères générées. " + +#. Tag: para +#, no-c-format +msgid "" +"Many mapping elements also accept a child <literal>&lt;column&gt;</literal> " +"element. This is particularly useful for mapping multi-column types:" +msgstr "" +"Plusieurs éléments de mappage acceptent aussi un élément fils <literal>&lt;" +"column&gt;</literal>. Ceci est particulièrement utile pour les type multi-" +"colonnes :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>default</literal> attribute allows you to specify a default " +"value for a column.You should assign the same value to the mapped property " +"before saving a new instance of the mapped class." +msgstr "" +"L'attribut <literal>default</literal> vous laisse spécifier une valeur par " +"défaut pour une colonne. Vous devez assigner la même valeur à la propriété " +"mappée avant de sauvegarder une nouvelle instance de la classe mappée." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>sql-type</literal> attribute allows the user to override the " +"default mapping of a Hibernate type to SQL datatype." +msgstr "" +"L'attribut <literal>sql-type</literal> permet à l'utilisateur de surcharger " +"le mappage par défaut d'un type Hibernate vers un type de données SQL. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>check</literal> attribute allows you to specify a check " +"constraint." +msgstr "" +"L'attribut <literal>check</literal> permet de spécifier une contrainte de " +"vérification." + +#. Tag: para +#, no-c-format +msgid "The following table summarizes these optional attributes." +msgstr "Le tableau suivant dresse la liste des attributs en option." + +#. Tag: title +#, no-c-format +msgid "Summary" +msgstr "Résumé" + +#. Tag: entry +#, no-c-format +msgid "Attribute" +msgstr "Attribut" + +#. Tag: entry +#, no-c-format +msgid "Values" +msgstr "Valeurs" + +#. Tag: entry +#, no-c-format +msgid "Interpretation" +msgstr "Interprétation" + +#. Tag: entry +#, no-c-format +msgid "<literal>length</literal>" +msgstr "<literal>length</literal> (longueur)" + +#. Tag: entry +#, no-c-format +msgid "number" +msgstr "numérique" + +#. Tag: entry +#, no-c-format +msgid "column length" +msgstr "taille d'une colonne" + +#. Tag: entry +#, no-c-format +msgid "<literal>precision</literal>" +msgstr "<literal>precision</literal>(précision)" + +#. Tag: entry +#, no-c-format +msgid "column decimal precision" +msgstr "précision décimale de la colonne" + +#. Tag: entry +#, no-c-format +msgid "<literal>scale</literal>" +msgstr "<literal>scale</literal> (échelle)" + +#. Tag: entry +#, no-c-format +msgid "column decimal scale" +msgstr "échelle décimale de la colonne" + +#. Tag: entry +#, no-c-format +msgid "<literal>not-null</literal>" +msgstr "<literal>not-null</literal> (non-nulle)" + +#. Tag: entry +#, no-c-format +msgid "<literal>true|false</literal>" +msgstr "<literal>true|false</literal> (vrai|faux)" + +#. Tag: entry +#, no-c-format +msgid "specifies that the column should be non-nullable" +msgstr "spécifie que la colonne doit être non-nulle " + +#. Tag: entry +#, no-c-format +msgid "<literal>unique</literal>" +msgstr "<literal>unique</literal>" + +#. Tag: entry +#, no-c-format +msgid "specifies that the column should have a unique constraint" +msgstr "spécifie que la colonne doit avoir une contrainte d'unicité" + +#. Tag: entry +#, no-c-format +msgid "<literal>index</literal>" +msgstr "<literal>index</literal>" + +#. Tag: entry +#, no-c-format +msgid "<literal>index_name</literal>" +msgstr "<literal>index_name</literal>" + +#. Tag: entry +#, no-c-format +msgid "specifies the name of a (multi-column) index" +msgstr "spécifie le nom d'un index (multi-colonnes)" + +#. Tag: entry +#, no-c-format +msgid "<literal>unique-key</literal>" +msgstr "<literal>unique-key</literal> (clé-unique)" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>unique_key_name</literal>" +msgstr "<literal>unique-key</literal> (clé-unique)" + +#. Tag: entry +#, no-c-format +msgid "specifies the name of a multi-column unique constraint" +msgstr "spécifie le nom d'une contrainte d'unicité multi-colonnes" + +#. Tag: entry +#, no-c-format +msgid "<literal>foreign-key</literal>" +msgstr "<literal>foreign-key</literal> (clé étrangère)" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>foreign_key_name</literal>" +msgstr "<literal>foreign-key</literal> (clé étrangère)" + +#. Tag: entry +#, no-c-format +msgid "" +"specifies the name of the foreign key constraint generated for an " +"association, for a <literal>&lt;one-to-one&gt;</literal>, <literal>&lt;many-" +"to-one&gt;</literal>, <literal>&lt;key&gt;</literal>, or <literal>&lt;many-" +"to-many&gt;</literal> mapping element. Note that <literal>inverse=\"true\"</" +"literal> sides will not be considered by <literal>SchemaExport</literal>." +msgstr "" +"spécifie le nom de la contrainte de clé étrangère générée par une " +"association, pour un élément de mappage <literal>&lt;one-to-one&gt;</" +"literal>, <literal>&lt;many-to-one&gt;</literal>, <literal>&lt;key&gt;</" +"literal>, ou <literal>&lt;many-to-many&gt;</literal>. Notez que les côtés " +"<literal>inverse=\"true\"</literal> ne seront pas pris en considération par " +"le <literal>SchemaExport</literal>." + +#. Tag: entry +#, no-c-format +msgid "<literal>sql-type</literal>" +msgstr "<literal>sql-type</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>SQL column type</literal>" +msgstr "<literal>sql-type</literal>" + +#. Tag: entry +#, no-c-format +msgid "" +"overrides the default column type (attribute of <literal>&lt;column&gt;</" +"literal> element only)" +msgstr "" +"surcharge le type par défaut (attribut de l'élément <literal>&lt;column&gt;</" +"literal> uniquement)" + +#. Tag: entry +#, no-c-format +msgid "<literal>default</literal>" +msgstr "<literal>défaut</literal>" + +#. Tag: entry +#, no-c-format +msgid "SQL expression" +msgstr "Expression SQL" + +#. Tag: entry +#, no-c-format +msgid "specify a default value for the column" +msgstr "spécifie une valeur par défaut pour la colonne" + +#. Tag: entry +#, no-c-format +msgid "<literal>check</literal>" +msgstr "<literal>vérification</literal>" + +#. Tag: entry +#, no-c-format +msgid "create an SQL check constraint on either column or table" +msgstr "crée une contrainte de vérification sur la table ou la colonne" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>&lt;comment&gt;</literal> element allows you to specify " +"comments for the generated schema." +msgstr "" +"L'élément <literal>&lt;comment&gt;</literal> vous permet de spécifier des " +"commentaires pour le schéma généré." + +#. Tag: para +#, no-c-format +msgid "" +"This results in a <literal>comment on table</literal> or <literal>comment on " +"column</literal> statement in the generated DDL where supported." +msgstr "" +"Ceci a pour résultat une expression <literal>comment on table</literal> ou " +"<literal>comment on column</literal> dans la DDL générée (là où elle est " +"supportée). " + +#. Tag: title +#, no-c-format +msgid "Running the tool" +msgstr "Exécuter l'outil" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>SchemaExport</literal> tool writes a DDL script to standard out " +"and/or executes the DDL statements." +msgstr "" +"L'outil <literal>SchemaExport</literal> génère un script DDL vers la sortie " +"standard et/ou exécute les ordres DDL." + +#. Tag: para +#, no-c-format +msgid "" +"The following table displays the <literal>SchemaExport</literal> command " +"line options" +msgstr "" +"Le tableau suivant affiche les options de ligne de commande du " +"<literal>SchemaExport</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> " +"<literal>org.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>options " +"mapping_files</emphasis>" +msgstr "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</" +"emphasis><literal>org.hibernate.tool.hbm2ddl.SchemaExport</" +"literal><emphasis>options mapping_files</emphasis> " + +#. Tag: title +#, no-c-format +msgid "<literal>SchemaExport</literal> Command Line Options" +msgstr "<literal>SchemaExport</literal> Options de la ligne de commande" + +#. Tag: entry +#, no-c-format +msgid "Option" +msgstr "Option" + +#. Tag: entry +#, no-c-format +msgid "Description" +msgstr "Description" + +#. Tag: entry +#, no-c-format +msgid "<literal>--quiet</literal>" +msgstr "<literal>--quiet</literal>" + +#. Tag: entry +#, no-c-format +msgid "do not output the script to stdout" +msgstr "ne pas écrire le script vers la sortie standard stdout" + +#. Tag: entry +#, no-c-format +msgid "<literal>--drop</literal>" +msgstr "<literal>--drop</literal>" + +#. Tag: entry +#, no-c-format +msgid "only drop the tables" +msgstr "supprime uniquement les tables" + +#. Tag: entry +#, no-c-format +msgid "<literal>--create</literal>" +msgstr "<literal>--create</literal>" + +#. Tag: entry +#, no-c-format +msgid "only create the tables" +msgstr "ne crée que les tables" + +#. Tag: entry +#, no-c-format +msgid "<literal>--text</literal>" +msgstr "<literal>--text</literal>" + +#. Tag: entry +#, no-c-format +msgid "do not export to the database" +msgstr "n'exporte pas vers la base de données " + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>--output=my_schema.ddl</literal>" +msgstr "<literal>scale</literal> (échelle)" + +#. Tag: entry +#, no-c-format +msgid "output the ddl script to a file" +msgstr "écrit le script ddl vers un fichier" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>--naming=eg.MyNamingStrategy</literal>" +msgstr "<literal>--naming=eg.MyNamingStrategy</literal>" + +#. Tag: entry +#, no-c-format +msgid "select a <literal>NamingStrategy</literal>" +msgstr "sélectionne une <literal>NamingStrategy</literal>" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>--config=hibernate.cfg.xml</literal>" +msgstr "<literal>--config=hibernate.cfg.xml</literal>" + +#. Tag: entry +#, no-c-format +msgid "read Hibernate configuration from an XML file" +msgstr "lit la configuration Hibernate à partir d'un fichier XML" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>--properties=hibernate.properties</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: entry +#, no-c-format +msgid "read database properties from a file" +msgstr "lit les propriétés de la base de données à partir d'un fichier" + +#. Tag: entry +#, no-c-format +msgid "<literal>--format</literal>" +msgstr "<literal>--format</literal>" + +#. Tag: entry +#, no-c-format +msgid "format the generated SQL nicely in the script" +msgstr "formatte proprement le SQL généré dans le script" + +#. Tag: entry +#, no-c-format +msgid "<literal>--delimiter=;</literal>" +msgstr "<literal>--delimiter=;</literal>" + +#. Tag: entry +#, no-c-format +msgid "set an end of line delimiter for the script" +msgstr "paramètre un délimiteur de fin de ligne pour le script" + +#. Tag: para +#, no-c-format +msgid "You can even embed <literal>SchemaExport</literal> in your application:" +msgstr "" +"Vous pouvez même intégrer <literal>SchemaExport</literal> dans votre " +"application : " + +#. Tag: title +#, no-c-format +msgid "Properties" +msgstr "Propriétés" + +#. Tag: para +#, no-c-format +msgid "Database properties can be specified:" +msgstr "Les propriétés de la base de données peuvent être spécifiées :" + +#. Tag: para +#, no-c-format +msgid "" +"as system properties with <literal>-D</literal><emphasis>&lt;property&gt;</" +"emphasis>" +msgstr "" +"comme propriétés système avec <literal>-D</literal><emphasis>&lt;property&gt;" +"</emphasis>" + +#. Tag: para +#, no-c-format +msgid "in <literal>hibernate.properties</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: para +#, no-c-format +msgid "in a named properties file with <literal>--properties</literal>" +msgstr "" +"dans un fichier de propriétés déclaré avec <literal>--properties</literal>" + +#. Tag: para +#, no-c-format +msgid "The needed properties are:" +msgstr "Les propriétés nécessaires sont :" + +#. Tag: title +#, no-c-format +msgid "SchemaExport Connection Properties" +msgstr "Les propriétés de connexion SchemaExport " + +#. Tag: entry +#, no-c-format +msgid "Property Name" +msgstr "Nom de la propriété" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.connection.driver_class</literal>" +msgstr "<literal>hibernate.connection.driver_class</literal>" + +#. Tag: entry +#, no-c-format +msgid "jdbc driver class" +msgstr "classe du driver JDBC" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.connection.url</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: entry +#, no-c-format +msgid "jdbc url" +msgstr "URL JDBC" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.connection.username</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: entry +#, no-c-format +msgid "database user" +msgstr "utilisateur de la base de données" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.connection.password</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: entry +#, no-c-format +msgid "user password" +msgstr "mot de passe de l'utilisateur" + +#. Tag: entry +#, fuzzy, no-c-format +msgid "<literal>hibernate.dialect</literal>" +msgstr "dans <literal>hibernate.properties</literal>" + +#. Tag: entry +#, no-c-format +msgid "dialect" +msgstr "dialecte" + +#. Tag: title +#, no-c-format +msgid "Using Ant" +msgstr "Utiliser Ant" + +#. Tag: para +#, no-c-format +msgid "" +"You can call <literal>SchemaExport</literal> from your Ant build script:" +msgstr "" +"Vous pouvez appeler <literal>SchemaExport</literal> depuis votre script de " +"construction Ant :" + +#. Tag: title +#, no-c-format +msgid "Incremental schema updates" +msgstr "Mises à jour incrémentales du schéma" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>SchemaUpdate</literal> tool will update an existing schema with " +"\"incremental\" changes. The <literal>SchemaUpdate</literal> depends upon " +"the JDBC metadata API and, as such, will not work with all JDBC drivers." +msgstr "" +"L'outil <literal>SchemaUpdate</literal> mettra à jour un schéma existant en " +"effectuant les changements par \"incrément\". Notez que " +"<literal>SchemaUpdate</literal> dépend fortement de l'API des métadonnées " +"JDBC, par conséquent il ne fonctionne pas avec tous les drivers JDBC. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> " +"<literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options " +"mapping_files</emphasis>" +msgstr "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> " +"<literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options " +"mapping_files</emphasis>" + +#. Tag: title +#, no-c-format +msgid "<literal>SchemaUpdate</literal> Command Line Options" +msgstr "<literal>SchemaUpdate</literal> Options de ligne de commande" + +#. Tag: entry +#, no-c-format +msgid "do not export the script to the database" +msgstr "ne pas exporter vers la base de données " + +#. Tag: entry +#, no-c-format +msgid "specify a <literal>.cfg.xml</literal> file" +msgstr "spécifier un fichier <literal>.cfg.xml</literal>" + +#. Tag: para +#, no-c-format +msgid "You can embed <literal>SchemaUpdate</literal> in your application:" +msgstr "" +"Vous pouvez intégrer <literal>SchemaUpdate</literal> dans votre " +"application : " + +#. Tag: title +#, no-c-format +msgid "Using Ant for incremental schema updates" +msgstr "Utiliser Ant pour des mises à jour de schéma par incrément" + +#. Tag: para +#, no-c-format +msgid "You can call <literal>SchemaUpdate</literal> from the Ant script:" +msgstr "" +"Vous pouvez appeler <literal>SchemaUpdate</literal> depuis le script Ant :" + +#. Tag: title +#, no-c-format +msgid "Schema validation" +msgstr "Validation du schéma" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>SchemaValidator</literal> tool will validate that the existing " +"database schema \"matches\" your mapping documents. The " +"<literal>SchemaValidator</literal> depends heavily upon the JDBC metadata " +"API and, as such, will not work with all JDBC drivers. This tool is " +"extremely useful for testing." +msgstr "" +"L'outil <literal>SchemaValidator</literal> confirmera que le schéma existant " +"correspond à vos documents de mappage. Notez que le " +"<literal>SchemaValidator</literal> dépend de l'API des métadonnées de JDBC, " +"il ne fonctionne donc pas avec tous les drivers JDBC. Cet outil est " +"extrêmement utile pour les tests. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> " +"<literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> " +"<emphasis>options mapping_files</emphasis>" +msgstr "" +"<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> " +"<literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> " +"<emphasis>options mapping_files</emphasis>" + +#. Tag: para +#, no-c-format +msgid "" +"The following table displays the <literal>SchemaValidator</literal> command " +"line options:" +msgstr "" +"Le tableau suivant affiche les options de ligne de commande du " +"<literal>SchemaValidator</literal>" + +#. Tag: title +#, no-c-format +msgid "<literal>SchemaValidator</literal> Command Line Options" +msgstr "<literal>SchemaValidator</literal> Options de ligne de commande" + +#. Tag: para +#, no-c-format +msgid "You can embed <literal>SchemaValidator</literal> in your application:" +msgstr "" +"Vous pouvez inclure <literal>SchemaValidator</literal> dans votre " +"application : " + +#. Tag: title +#, no-c-format +msgid "Using Ant for schema validation" +msgstr "Utiliser Ant pour la validation du Schéma" + +#. Tag: para +#, no-c-format +msgid "You can call <literal>SchemaValidator</literal> from the Ant script:" +msgstr "" +"Vous pouvez appeler <literal>SchemaValidator</literal> depuis le script Ant:" + +#, fuzzy +#~ msgid "length" +#~ msgstr "taille d'une colonne" + +#, fuzzy +#~ msgid "precision" +#~ msgstr "Expression SQL" + +#, fuzzy +#~ msgid "unique_key_name" +#~ msgstr "<literal>unique_key_name</literal>" + +#, fuzzy +#~ msgid "foreign_key_name" +#~ msgstr "<literal>foreign_key_name</literal>" + +#, fuzzy +#~ msgid "SQL column type" +#~ msgstr "<literal>SQL column type</literal> (type de colonne SQL)" + +#, fuzzy +#~ msgid "--output=my_schema.ddl" +#~ msgstr "<literal>--output=my_schema.ddl</literal>" + +#, fuzzy +#~ msgid "--properties=hibernate.properties" +#~ msgstr "<literal>--properties=hibernate.properties</literal>" + +#, fuzzy +#~ msgid "hibernate.connection.url" +#~ msgstr "<literal>hibernate.connection.url</literal>" + +#, fuzzy +#~ msgid "hibernate.connection.username" +#~ msgstr "<literal>hibernate.connection.username</literal>" + +#, fuzzy +#~ msgid "hibernate.connection.password" +#~ msgstr "<literal>hibernate.connection.password</literal>" + +#, fuzzy +#~ msgid "hibernate.dialect" +#~ msgstr "<literal>hibernate.dialect</literal>" + +#~ msgid "<!-- <emphasis>Ant Tasks:</emphasis> -->" +#~ msgstr "<!-- <emphasis>Ant Tasks:</emphasis> -->" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/transactions.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/transactions.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/transactions.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1929 @@ +# translation of transactions.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: transactions\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:16\n" +"PO-Revision-Date: 2010-01-05 10:06+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Transactions and Concurrency" +msgstr "Transactions et Accès concurrents" + +#. Tag: para +#, no-c-format +msgid "" +"The most important point about Hibernate and concurrency control is that it " +"is easy to understand. Hibernate directly uses JDBC connections and JTA " +"resources without adding any additional locking behavior. It is recommended " +"that you spend some time with the JDBC, ANSI, and transaction isolation " +"specification of your database management system." +msgstr "" +"L'un des principaux avantages du mécanisme de contrôle des accès concurrents " +"de Hibernate est qu'il est très facile à comprendre. Hibernate utilise " +"directement les connexions JDBC ainsi que les ressources JTA sans y ajouter " +"davantage de mécanisme de blocage. Nous vous recommandons de vous " +"familiariser avec les spécifications JDBC, ANSI et d'isolement de " +"transaction du système de gestion de la base de données que vous utilisez. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate does not lock objects in memory. Your application can expect the " +"behavior as defined by the isolation level of your database transactions. " +"Through <literal>Session</literal>, which is also a transaction-scoped " +"cache, Hibernate provides repeatable reads for lookup by identifier and " +"entity queries and not reporting queries that return scalar values." +msgstr "" +"Hibernate ne verrouille pas vos objets en mémoire. Votre application peut " +"suivre le comportement défini par le niveau d'isolation de vos transactions " +"de base de données. Notez que grâce à la <literal>Session</literal>, qui est " +"aussi un cache de portée de transaction, Hibernate fournit des lectures " +"répétées pour les recherches par identifiants et les requêtes d'entités (ne " +"rapporte pas les requêtes qui retournent des valeurs scalaires). " + +#. Tag: para +#, no-c-format +msgid "" +"In addition to versioning for automatic optimistic concurrency control, " +"Hibernate also offers, using the <literal>SELECT FOR UPDATE</literal> " +"syntax, a (minor) API for pessimistic locking of rows. Optimistic " +"concurrency control and this API are discussed later in this chapter." +msgstr "" +"En plus du versioning, pour le contrôle automatique optimiste de " +"concurrence, Hibernate fournit également une API (mineure) pour le " +"verrouillage pessimiste des lignes, en générant une syntaxe <literal>SELECT " +"FOR UPDATE</literal>. Le contrôle de concurrence optimiste et cette API " +"seront approfondis ultérieurement dans ce chapitre. " + +#. Tag: para +#, no-c-format +msgid "" +"The discussion of concurrency control in Hibernate begins with the " +"granularity of <literal>Configuration</literal>, <literal>SessionFactory</" +"literal>, and <literal>Session</literal>, as well as database transactions " +"and long conversations." +msgstr "" +"Nous abordons la gestion des accès concurrents en discutant de la " +"granularité des objets <literal>Configuration</literal>, " +"<literal>SessionFactory</literal>, et <literal>Session</literal>, ainsi que " +"des transactions de la base de données et des longues transactions " +"applicatives. " + +#. Tag: title +#, no-c-format +msgid "Session and transaction scopes" +msgstr "Portées des sessions et des transactions" + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>SessionFactory</literal> is an expensive-to-create, threadsafe " +"object, intended to be shared by all application threads. It is created " +"once, usually on application startup, from a <literal>Configuration</" +"literal> instance." +msgstr "" +"Il est important de savoir qu'un objet <literal>SessionFactory</literal> est " +"un objet complexe et optimisé pour fonctionner avec les threads(thread- " +"safe). Il est coûteux à créer et est ainsi prévu pour n'être instancié " +"qu'une seule fois via une instance <literal>Configuration</literal> en " +"général au démarrage de l'application. " + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>Session</literal> is an inexpensive, non-threadsafe object that " +"should be used once and then discarded for: a single request, a conversation " +"or a single unit of work. A <literal>Session</literal> will not obtain a " +"JDBC <literal>Connection</literal>, or a <literal>Datasource</literal>, " +"unless it is needed. It will not consume any resources until used." +msgstr "" +"Une <literal>Session</literal> n'est pas coûteuse, et c'est un objet non-" +"threadsafe qui ne devrait être utilisé qu'une seule fois pour une requête " +"unique, une conversation, une unité de travail unique et devrait être " +"relâché ensuite. Un objet <literal>Session</literal> ne tentera pas " +"d'obtenir une <literal>Connection</literal>JBDC (ou une <literal>Datasource</" +"literal>) si ce n'est pas nécessaire, par conséquent il ne consommera pas de " +"ressource jusqu'à son utilisation." + +#. Tag: para +#, no-c-format +msgid "" +"In order to reduce lock contention in the database, a database transaction " +"has to be as short as possible. Long database transactions will prevent your " +"application from scaling to a highly concurrent load. It is not recommended " +"that you hold a database transaction open during user think time until the " +"unit of work is complete." +msgstr "" +"Afin de compléter ce tableau, vous devez également penser aux transactions " +"de base de données. Une transaction de base de données doit être aussi " +"courte que possible afin de réduire les risques de contention de verrou dans " +"la base de données. De longues transactions à la base de données nuiront à " +"l'extensibilité de vos applications lorsque confrontées à de hauts niveaux " +"de charge. Par conséquent, ce n'est un bon design que de maintenir une " +"transaction ouverte pendant la durée de reflexion de l'utilisateur, jusqu'à " +"ce que l'unité de travail soit achevée. " + +#. Tag: para +#, no-c-format +msgid "" +"What is the scope of a unit of work? Can a single Hibernate " +"<literal>Session</literal> span several database transactions, or is this a " +"one-to-one relationship of scopes? When should you open and close a " +"<literal>Session</literal> and how do you demarcate the database transaction " +"boundaries? These questions are addressed in the following sections." +msgstr "" +"Quelle est la portée d'une unité de travail? Est-ce qu'une <literal>Session</" +"literal> unique de Hibernate peut avoir une durée de vie dépassant plusieurs " +"transactions à la base de données, ou bien est-ce une relation un-à-un des " +"portées? Quand faut-il ouvrir et fermer une <literal>Session</literal> et " +"comment définir les démarcations de vos transactions à la base de données ? " + +#. Tag: title +#, no-c-format +msgid "Unit of work" +msgstr "Unité de travail" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"First, let's define a unit of work. A unit of work is a design pattern " +"described by Martin Fowler as <quote> [maintaining] a list of objects " +"affected by a business transaction and coordinates the writing out of " +"changes and the resolution of concurrency problems. </quote><citation>PoEAA</" +"citation> In other words, its a series of operations we wish to carry out " +"against the database together. Basically, it is a transaction, though " +"fulfilling a unit of work will often span multiple physical database " +"transactions (see <xref linkend=\"transactions-basics-apptx\" />). So really " +"we are talking about a more abstract notion of a transaction. The term " +"\"business transaction\" is also sometimes used in lieu of unit of work." +msgstr "" +"Tout d'abord, nous allons définir une unité de travail. Une unité de travail " +"est un modèle de conception décrit par Martin Fowler qui <quote> [gère] une " +"liste d'objets concernés par une transaction d'entreprise et coordonne la " +"rédaction de modifications et la résolution des problèmes d'accès " +"concurrentiel. </quote><citation>PoEAA</citation>. En d'autres termes, il " +"s'agit d'une série d'opérations que nous voulons réaliser ensemble sur la " +"base de données. Il s'agit essentiellement d'une transaction, bien qu'en " +"remplissant une unité de travail, on couvrira souvent plusieurs transactions " +"physiques de base de données (voir <xref linkend=\"transactions-basics-apptx" +"\" />). Nous parlons donc vraiment une notion plus abstraite de transaction. " +"Le terme \"business transaction\"est aussi parfois utilisé à la place " +"d'unité de travail." + +#. Tag: para +#, no-c-format +msgid "" +"Do not use the <emphasis>session-per-operation</emphasis> antipattern: do " +"not open and close a <literal>Session</literal> for every simple database " +"call in a single thread. The same is true for database transactions. " +"Database calls in an application are made using a planned sequence; they are " +"grouped into atomic units of work. This also means that auto-commit after " +"every single SQL statement is useless in an application as this mode is " +"intended for ad-hoc SQL console work. Hibernate disables, or expects the " +"application server to disable, auto-commit mode immediately. Database " +"transactions are never optional. All communication with a database has to " +"occur inside a transaction. Auto-commit behavior for reading data should be " +"avoided, as many small transactions are unlikely to perform better than one " +"clearly defined unit of work. The latter is also more maintainable and " +"extensible." +msgstr "" +"Tout d'abord n'utilisez pas l'anti-pattern <emphasis>session-par-operation</" +"emphasis> et n'ouvrez et ne fermez pas la <literal>Session</literal> à " +"chacun de vos accès simples à la base de données dans un même thread ! Par " +"conséquent, le même raisonnement est applicable à la gestion des " +"transactions dans la base de données. Dans une application, les appels à la " +"base de données doivent être effectués selon une séquence ordonnée et sont " +"regroupés en unités de travail atomiques. (Notez que l'utilisation d'une " +"connexion auto-commit après chaque déclaration SQL est inutile dans une " +"application. Ce mode de fonctionnement existe pour les applications émettant " +"des commandes SQL ad-hoc à partir d'une console. Hibernate désengage le mode " +"auto-commit et s'attend à ce qu'un serveur d'applications le fasse " +"également.) Les transactions avec la base de données ne sont jamais " +"optionnelles. Toute communication avec une base de données doit se dérouler " +"dans une transaction, peu importe si vous lisez ou écrivez des données. " +"Comme déjà mentionné, le comportement auto-commit pour lire les données " +"devrait être évité, puisque plusieurs petites transactions ne seront jamais " +"aussi efficaces qu'une seule plus grosse clairement définie comme unité de " +"travail. Ce dernier choix est de plus beaucoup plus facile à maintenir et " +"plus extensible." + +#. Tag: para +#, no-c-format +msgid "" +"The most common pattern in a multi-user client/server application is " +"<emphasis>session-per-request</emphasis>. In this model, a request from the " +"client is sent to the server, where the Hibernate persistence layer runs. A " +"new Hibernate <literal>Session</literal> is opened, and all database " +"operations are executed in this unit of work. On completion of the work, and " +"once the response for the client has been prepared, the session is flushed " +"and closed. Use a single database transaction to serve the clients request, " +"starting and committing it when you open and close the <literal>Session</" +"literal>. The relationship between the two is one-to-one and this model is a " +"perfect fit for many applications." +msgstr "" +"Le modèle d'utilisation le plus fréquemment rencontré dans des applications " +"clients serveur multi-usagers est la <emphasis>session-par-requête</" +"emphasis>. Dans ce modèle, la requête d'un client est envoyée au serveur (où " +"la couche de persistance est implémentée via Hibernate), une nouvelle " +"<literal>Session</literal> Hibernate est ouverte et toutes les opérations " +"d'accès à la base de données sont exécutées à l'intérieur de celle-ci. " +"Lorsque le travail est terminé (et que les réponses à envoyer au client ont " +"été préparées), la session est flushée et fermée. Une seule transaction à la " +"base de données peut être utilisée pour répondre à la requête du client. La " +"transaction est démarrée et validée au même moment où la Session est ouverte " +"et fermée. La relation entre la <literal>Session</literal> et la " +"<literal>Transaction</literal> est donc un-à-un. Cette relation entre les " +"deux est un-à-un et ce modèle permet de répondre parfaitement aux attentes " +"de la grande majorité des applications. " + +#. Tag: para +#, no-c-format +msgid "" +"The challenge lies in the implementation. Hibernate provides built-in " +"management of the \"current session\" to simplify this pattern. Start a " +"transaction when a server request has to be processed, and end the " +"transaction before the response is sent to the client. Common solutions are " +"<literal>ServletFilter</literal>, AOP interceptor with a pointcut on the " +"service methods, or a proxy/interception container. An EJB container is a " +"standardized way to implement cross-cutting aspects such as transaction " +"demarcation on EJB session beans, declaratively with CMT. If you use " +"programmatic transaction demarcation, for ease of use and code portability " +"use the Hibernate <literal>Transaction</literal> API shown later in this " +"chapter." +msgstr "" +"Le défi réside dans l'implémentation. Hibernate fournit une fonction de " +"gestion intégrée de la \"session courante\" pour simplifier ce pattern. Il " +"vous suffit de démarrer une transaction lorsqu'une requête est traitée par " +"le serveur, et la terminer avant que la réponse ne soit envoyée au client. " +"Vous pouvez choisir la manière de l'effectuer, les solutions communes sont " +"un <literal>ServletFilter</literal>, l'interception via AOP avec une coupe " +"transverse (pointcut) sur les méthodes de type \"service\", ou un conteneur " +"avec interception/proxy. Un conteneur EJB est un moyen standard " +"d'implémenter ce genre d'acpect transverse comme la démarcation des " +"transactions sur les EJB session, de manière déclarative avec CMT. Si vous " +"décidez d'utiliser la démarcation programmatique des transactions, préferrez " +"l'API Hibernate <literal>Transaction</literal> traitée plus tard dans ce " +"chapitre, afin de faciliter l'utilisation et la portabilité du code. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Your application code can access a \"current session\" to process the " +"request by calling <literal>sessionFactory.getCurrentSession()</literal>. " +"You will always get a <literal>Session</literal> scoped to the current " +"database transaction. This has to be configured for either resource-local or " +"JTA environments, see <xref linkend=\"architecture-current-session\" />." +msgstr "" +"Votre application peut accéder à une \"session courante\" pour traiter une " +"requête en invoquant simplement <literal>sessionFactory.getCurrentSession()</" +"literal> n'importe où et autant de fois que nécessaire. Vous obtiendrez " +"toujours une <literal>Session</literal> dont la portée est la transaction " +"courante avec la base de données. Ceci doit être configuré soit dans les " +"ressources locales ou dans l'environnement JTA, voir <xref linkend=" +"\"architecture-current-session\" />." + +#. Tag: para +#, no-c-format +msgid "" +"You can extend the scope of a <literal>Session</literal> and database " +"transaction until the \"view has been rendered\". This is especially useful " +"in servlet applications that utilize a separate rendering phase after the " +"request has been processed. Extending the database transaction until view " +"rendering, is achieved by implementing your own interceptor. However, this " +"will be difficult if you rely on EJBs with container-managed transactions. A " +"transaction will be completed when an EJB method returns, before rendering " +"of any view can start. See the Hibernate website and forum for tips and " +"examples relating to this <emphasis>Open Session in View</emphasis> pattern." +msgstr "" +"Il est parfois utile d'étendre la portée d'une <literal>Session</literal> et " +"d'une transaction à la base de données jusqu'à ce que \"la vue soit rendue" +"\". Ceci est particulièrement utile dans des applications à base de servlet " +"qui utilisent une phase de rendue séparée une fois que la réponse a été " +"préparée. Étendre la transaction avec la base de données jusqu'à la fin du " +"rendering de la vue est aisé si vous implémentez votre propre intercepteur. " +"Cependant, ce n'est pas facile si vous vous appuyez sur les EJB avec CMT, " +"puisqu'une transaction sera achevée au retour de la méthode EJB, avant le " +"rendu de la vue. Rendez vous sur le site Hibernate et sur le forum pour des " +"astuces et des exemples sur le pattern <emphasis>Open Session in View</" +"emphasis> . " + +#. Tag: title +#, no-c-format +msgid "Long conversations" +msgstr "Longue conversation" + +#. Tag: para +#, no-c-format +msgid "" +"The session-per-request pattern is not the only way of designing units of " +"work. Many business processes require a whole series of interactions with " +"the user that are interleaved with database accesses. In web and enterprise " +"applications, it is not acceptable for a database transaction to span a user " +"interaction. Consider the following example:" +msgstr "" +"Le paradigme \"session-per-request\" n'est pas le seul élément à utiliser " +"dans le design de vos unités de travail. Plusieurs processus d'affaire " +"requièrent toute une série d'interactions avec l'utilisateur, entrelacées " +"d'accès à la base de donnée. Dans une application Web ou une application " +"d'entreprise, il serait inacceptable que la durée de vie d'une transaction " +"s'étale sur plusieurs interactions avec l'usager. Considérez l'exemple " +"suivant :" + +#. Tag: para +#, no-c-format +msgid "" +"The first screen of a dialog opens. The data seen by the user has been " +"loaded in a particular <literal>Session</literal> and database transaction. " +"The user is free to modify the objects." +msgstr "" +"Un écran s'affiche. Les données vues par l'usager ont été chargées dans " +"l'instance d'un objet <literal>Session</literal> , dans le cadre d'une " +"transaction de base de données. L'usager est libre de modifier ces objets. " + +#. Tag: para +#, no-c-format +msgid "" +"The user clicks \"Save\" after 5 minutes and expects their modifications to " +"be made persistent. The user also expects that they were the only person " +"editing this information and that no conflicting modification has occurred." +msgstr "" +"L'usager clique \"Sauvegarder\" après 5 minutes et souhaite persister les " +"modifications qu'il a apportées. Il s'attend à être la seule personne a " +"avoir modifié ces données et qu'aucune modification conflictuelle ne se soit " +"produite durant ce laps de temps. " + +#. Tag: para +#, no-c-format +msgid "" +"From the point of view of the user, we call this unit of work a long-running " +"<emphasis>conversation</emphasis> or <emphasis>application transaction</" +"emphasis>. There are many ways to implement this in your application." +msgstr "" +"Ceci s'appelle une unité de travail. Du point de vue de l'utilisateur: une " +"<emphasis>conversation</emphasis> (ou <emphasis>transaction d'application</" +"emphasis>). Il y a plusieurs façon de mettre ceci en place dans votre " +"application. " + +#. Tag: para +#, no-c-format +msgid "" +"A first naive implementation might keep the <literal>Session</literal> and " +"database transaction open during user think time, with locks held in the " +"database to prevent concurrent modification and to guarantee isolation and " +"atomicity. This is an anti-pattern, since lock contention would not allow " +"the application to scale with the number of concurrent users." +msgstr "" +"Une première implémentation naïve pourrait consister à garder la " +"<literal>Session</literal> et la transaction à la base de données ouvertes " +"durant le temps de travail de l'usager, à maintenir les enregistrements " +"verrouillés dans la base de données afin d'éviter des modifications " +"concurrentes et de maintenir l'isolation et l'atomicité de la transaction de " +"l'usager. Ceci est un anti-pattern à éviter, puisque le verrouillage des " +"enregistrements dans la base de données ne permettrait pas à l'application " +"de gérer un grand nombre d'usagers concurrents. " + +#. Tag: para +#, no-c-format +msgid "" +"You have to use several database transactions to implement the conversation. " +"In this case, maintaining isolation of business processes becomes the " +"partial responsibility of the application tier. A single conversation " +"usually spans several database transactions. It will be atomic if only one " +"of these database transactions (the last one) stores the updated data. All " +"others simply read data (for example, in a wizard-style dialog spanning " +"several request/response cycles). This is easier to implement than it might " +"sound, especially if you utilize some of Hibernate's features:" +msgstr "" +"Il apparaît donc évident qu'il faille utiliser plusieurs transactions BDD " +"afin d'implémenter la conversation. Dans ce cas, maintenir l'isolation des " +"processus d'affaire devient partiellement la responsabilité de la couche " +"applicative. Ainsi, la durée de vie d'une conversation devrait englober " +"celle d'une ou de plusieurs transactions de base de données. Celle-ci sera " +"atomique seulement si l'écriture des données mises à jour est faite " +"exclusivement par la dernière transaction BDD la composant. Toutes les " +"autres sous transactions BD ne doivent faire que la lecture de données. Ceci " +"est relativement facile à mettre en place, surtout avec l'utilisation de " +"certaines fonctionnalités d'Hibernate :" + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Automatic Versioning</emphasis>: Hibernate can perform automatic " +"optimistic concurrency control for you. It can automatically detect if a " +"concurrent modification occurred during user think time. Check for this at " +"the end of the conversation." +msgstr "" +"<emphasis>Versionnage Automatique</emphasis> - Hibernate peut gérer " +"automatiquement les accès concurrents de manière optimiste et détecter si " +"une modification concurrente s'est produite durant le temps de réflexion " +"d'un usager. A vérifier en fin de conversation." + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Detached Objects</emphasis>: if you decide to use the " +"<emphasis>session-per-request</emphasis> pattern, all loaded instances will " +"be in the detached state during user think time. Hibernate allows you to " +"reattach the objects and persist the modifications. The pattern is called " +"<emphasis>session-per-request-with-detached-objects</emphasis>. Automatic " +"versioning is used to isolate concurrent modifications." +msgstr "" +"<emphasis>Objets Détachés</emphasis> - Si vous décidez d'utiliser le " +"paradigme <emphasis>session-par-requête</emphasis> discuté plus haut, toutes " +"les entités chargées en mémoire deviendront des objets détachés durant le " +"temps de réflexion de l'usager. Hibernate vous permet de rattacher ces " +"objets et de persister les modifications y ayant été apportées. Ce pattern " +"est appelé: <emphasis>session-per- request-with-detached-objects</emphasis> " +"(littéralement: session- par-requête-avec-objets-détachés). Le versionnage " +"automatique est utilisé afin d'isoler les modifications concurrentes. " + +#. Tag: para +#, no-c-format +msgid "" +"<emphasis>Extended (or Long) Session</emphasis>: the Hibernate " +"<literal>Session</literal> can be disconnected from the underlying JDBC " +"connection after the database transaction has been committed and reconnected " +"when a new client request occurs. This pattern is known as <emphasis>session-" +"per-conversation</emphasis> and makes even reattachment unnecessary. " +"Automatic versioning is used to isolate concurrent modifications and the " +"<literal>Session</literal> will not be allowed to be flushed automatically, " +"but explicitly." +msgstr "" +"<emphasis>Session Longues (conversation)</emphasis> - Une <literal>Session</" +"literal> Hibernate peut être déconnectée de la couche JDBC sous-jacente " +"après que commit() ait été appelé sur une transaction à la base de données " +"et reconnectée lors d'une nouvelle requête-client. Ce pattern s'appelle: " +"<emphasis>session-per-conversation</emphasis> (Littéralement: session-par- " +"conversation) et rend superflu le rattachement des objets. Le versionnage " +"automatique est utilisé afin d'isoler les modifications concurrentes. " + +#. Tag: para +#, no-c-format +msgid "" +"Both <emphasis>session-per-request-with-detached-objects</emphasis> and " +"<emphasis>session-per-conversation</emphasis> have advantages and " +"disadvantages. These disadvantages are discussed later in this chapter in " +"the context of optimistic concurrency control." +msgstr "" +"Les deux patterns <emphasis>session-per-request-with- detached- objects</" +"emphasis> (session-par-requête-avec-objets- détachés) et <emphasis>session-" +"per-conversation</emphasis> (session-par-conversation) ont chacun leurs " +"avantages et désavantages qui seront exposés dans ce même chapitre, dans la " +"section au sujet du contrôle optimiste de concurrence. " + +#. Tag: title +#, no-c-format +msgid "Considering object identity" +msgstr "L'identité des objets" + +#. Tag: para +#, no-c-format +msgid "" +"An application can concurrently access the same persistent state in two " +"different <literal>Session</literal>s. However, an instance of a persistent " +"class is never shared between two <literal>Session</literal> instances. It " +"is for this reason that there are two different notions of identity:" +msgstr "" +"Une application peut accéder à la même entité persistante de manière " +"concurrente dans deux <literal>Session</literal> s différentes. Toutefois, " +"une instance d'une classe persistante n'est jamais partagée par deux " +"instances distinctes de la classe <literal>Session</literal>. Il existe donc " +"deux notions de l'identité d'un objet :" + +#. Tag: term +#, no-c-format +msgid "Database Identity" +msgstr "Identité de database" + +#. Tag: para +#, fuzzy, no-c-format +msgid "<literal>foo.getId().equals( bar.getId() )</literal>" +msgstr "<literal>foo.getId().equals( bar.getId() )</literal>" + +#. Tag: term +#, no-c-format +msgid "JVM Identity" +msgstr "Identité JVM" + +#. Tag: para +#, no-c-format +msgid "<literal>foo==bar</literal>" +msgstr "<literal>foo==bar</literal>" + +#. Tag: para +#, no-c-format +msgid "" +"For objects attached to a <emphasis>particular</emphasis> <literal>Session</" +"literal> (i.e., in the scope of a <literal>Session</literal>), the two " +"notions are equivalent and JVM identity for database identity is guaranteed " +"by Hibernate. While the application might concurrently access the \"same" +"\" (persistent identity) business object in two different sessions, the two " +"instances will actually be \"different\" (JVM identity). Conflicts are " +"resolved using an optimistic approach and automatic versioning at flush/" +"commit time." +msgstr "" +"Ainsi, pour des objets attachés à une <literal>Session</" +"literal><emphasis>particulière</emphasis> (c'est-à-dire dans la portée d'une " +"instance de <literal>Session</literal>), ces deux notions d'identité sont " +"équivalentes et l'identité JVM pour l'identité de la base de données sont " +"garanties par Hibernate. Cependant, alors qu'une application peut accéder de " +"manière concurrente au \"même\" objet métier (identité persistante) dans " +"deux sessions différentes, les deux instances seront en fait \"différentes" +"\" (en ce qui a trait à l'identité JVM). Les conflits sont résolus " +"automatiquement par approche optimiste grâce au système de versionnage " +"automatique au moment du flush/sauvegarde. " + +#. Tag: para +#, no-c-format +msgid "" +"This approach leaves Hibernate and the database to worry about concurrency. " +"It also provides the best scalability, since guaranteeing identity in single-" +"threaded units of work means that it does not need expensive locking or " +"other means of synchronization. The application does not need to synchronize " +"on any business object, as long as it maintains a single thread per " +"<literal>Session</literal>. Within a <literal>Session</literal> the " +"application can safely use <literal>==</literal> to compare objects." +msgstr "" +"Cette approche permet de reléguer à Hibernate et à la base de données sous-" +"jacente le soin de gérer les problèmes d'accès concurrents. Cette manière de " +"faire assure également une meilleure extensibilité de l'application puisque " +"assurer l'identité JVM dans un thread ne nécessite pas de mécanismes de " +"verrouillage coûteux ou d'autres dispositifs de synchronisation. Une " +"application n'aura jamais besoin de synchroniser des objets d'affaire tant " +"qu'elle peut garantir qu'un seul thread aura accès à une instance de " +"<literal>Session</literal> . Dans le cadre d'exécution d'un objet " +"<literal>Session</literal>, l'application peut utiliser en toute sécurité " +"<literal>== </literal> pour comparer des objets. " + +#. Tag: para +#, no-c-format +msgid "" +"However, an application that uses <literal>==</literal> outside of a " +"<literal>Session</literal> might produce unexpected results. This might " +"occur even in some unexpected places. For example, if you put two detached " +"instances into the same <literal>Set</literal>, both might have the same " +"database identity (i.e., they represent the same row). JVM identity, " +"however, is by definition not guaranteed for instances in a detached state. " +"The developer has to override the <literal>equals()</literal> and " +"<literal>hashCode()</literal> methods in persistent classes and implement " +"their own notion of object equality. There is one caveat: never use the " +"database identifier to implement equality. Use a business key that is a " +"combination of unique, usually immutable, attributes. The database " +"identifier will change if a transient object is made persistent. If the " +"transient instance (usually together with detached instances) is held in a " +"<literal>Set</literal>, changing the hashcode breaks the contract of the " +"<literal>Set</literal>. Attributes for business keys do not have to be as " +"stable as database primary keys; you only have to guarantee stability as " +"long as the objects are in the same <literal>Set</literal>. See the " +"Hibernate website for a more thorough discussion of this issue. Please note " +"that this is not a Hibernate issue, but simply how Java object identity and " +"equality has to be implemented." +msgstr "" +"Une application qui utiliserait <literal>==</literal> à l'extérieur du cadre " +"d'exécution d'une <literal>Session</literal> pourrait obtenir des résultats " +"inattendus. Par exemple, si vous mettez deux objets dans le même " +"<literal>Set</literal> , ceux-ci pourraient avoir la même identité de base " +"de données (c'est-à-dire ils représentent le même enregistrement), mais leur " +"identité JVM pourrait être différente (elle ne peut, par définition, pas " +"être garantie sur deux objets détachés). Le développeur doit donc redéfinir " +"l'implémentation des méthodes <literal>equals()</literal> et " +"<literal>hashcode()</literal> dans les classes persistantes et y adjoindre " +"sa propre notion d'identité. Il existe toutefois une restriction : il ne " +"faut jamais utiliser uniquement l'identifiant de la base de données dans " +"l'implémentation de l'égalité; il faut utiliser une clé d'affaire, " +"généralement une combinaison de plusieurs attributs uniques, si possible " +"immuables. Les identifiants de base de données vont changer si un objet " +"transitoire (transient) devient persistant. Si une instance transitoire (en " +"général avec des instances dégachées) est contenue dans un <literal>Set</" +"literal>, changer le hashcode brisera le contrat du <literal>Set</literal> . " +"Les attributs pour les clés d'affaire n'ont pas à être aussi stables que des " +"clés primaires de bases de données. Il suffit simplement qu'elles soient " +"stables tant et aussi longtemps que les objets sont dans le même " +"<literal>Set</literal> . Veuillez consulter le site web Hibernate pour des " +"discussions plus pointues à ce sujet. Notez que ce concept n'est pas propre " +"à Hibernate mais bien général à l'implémentation de l'identité et de " +"l'égalité en Java. " + +#. Tag: title +#, no-c-format +msgid "Common issues" +msgstr "Problèmes communs" + +#. Tag: para +#, no-c-format +msgid "" +"Do not use the anti-patterns <emphasis>session-per-user-session</emphasis> " +"or <emphasis>session-per-application</emphasis> (there are, however, rare " +"exceptions to this rule). Some of the following issues might also arise " +"within the recommended patterns, so ensure that you understand the " +"implications before making a design decision:" +msgstr "" +"Bien qu'il puisse y avoir quelques rares exceptions à cette règle, il est " +"recommandé de ne jamais utiliser les anti-modèles <emphasis>session-par- " +"utilisateur-session</emphasis> ou <emphasis>session-par-application</" +"emphasis> . Notez que certains des problèmes suivants pourraient néanmoins " +"survenir avec des modèles recommandés, assurez-vous de bien comprendre les " +"implications de chacun des modèles avant de prendre une décision concernant " +"votre design :" + +#. Tag: para +#, no-c-format +msgid "" +"A <literal>Session</literal> is not thread-safe. Things that work " +"concurrently, like HTTP requests, session beans, or Swing workers, will " +"cause race conditions if a <literal>Session</literal> instance is shared. If " +"you keep your Hibernate <literal>Session</literal> in your " +"<literal>HttpSession</literal> (this is discussed later in the chapter), you " +"should consider synchronizing access to your Http session. Otherwise, a user " +"that clicks reload fast enough can use the same <literal>Session</literal> " +"in two concurrently running threads." +msgstr "" +"L'objet <literal>Session</literal> n'est pas conçu pour être utilisé par de " +"multiples threads. En conséquence, les objets potentiellement multi-thread " +"comme les requêtes HTTP, les EJB Session et Swing Worker, risquent de " +"provoquer des conditions de course dans la <literal>Session</literal> si " +"celle-ci est partagée. Si vous gardez votre <literal>Session</literal> " +"Hibernate dans la <literal>HttpSession</literal> (le sujet sera traité " +"ultérieurement), il serait préférable de synchroniser les accès à la session " +"Http afin d'éviter qu'un usager ne recharge une page assez rapidement pour " +"que deux requêtes exécutant dans des threads concurrents n'utilisent la même " +"<literal>Session</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"An exception thrown by Hibernate means you have to rollback your database " +"transaction and close the <literal>Session</literal> immediately (this is " +"discussed in more detail later in the chapter). If your <literal>Session</" +"literal> is bound to the application, you have to stop the application. " +"Rolling back the database transaction does not put your business objects " +"back into the state they were at the start of the transaction. This means " +"that the database state and the business objects will be out of sync. " +"Usually this is not a problem, because exceptions are not recoverable and " +"you will have to start over after rollback anyway." +msgstr "" +"Lorsque Hibernate lance une exception, le rollback de la transaction en " +"cours dans la base de données, doit être effectué et la <literal>Session</" +"literal> immédiatement fermée. (Nous approfondirons le sujet plus loin) Si " +"votre <literal>Session</literal> est liée à l'application, il faut arrêter " +"l'application. Le rollback de la transaction de base de données ne remettra " +"pas les objets dans leur état du début de la transaction. Ainsi, cela " +"signifie que l'état de la base de données et les objets d'affaires " +"pourraient être désynchronisés d'avec les enregistrements. Généralement, " +"cela ne cause pas de réel problème puisque la plupart des exceptions sont " +"non traitables et de toutes façons, vous devez recommencer le processus " +"après le rollback). " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The <literal>Session</literal> caches every object that is in a persistent " +"state (watched and checked for dirty state by Hibernate). If you keep it " +"open for a long time or simply load too much data, it will grow endlessly " +"until you get an OutOfMemoryException. One solution is to call <literal>clear" +"()</literal> and <literal>evict()</literal> to manage the <literal>Session</" +"literal> cache, but you should consider a Stored Procedure if you need mass " +"data operations. Some solutions are shown in <xref linkend=\"batch\" />. " +"Keeping a <literal>Session</literal> open for the duration of a user session " +"also means a higher probability of stale data." +msgstr "" +"La <literal>Session</literal> met en mémoire cache tous les objets " +"persistants (les objets surveillés et dont l'état (dirty) est vérifié par " +"Hibernate.) Si la <literal>Session</literal> est ouverte indéfiniment ou si " +"une trop grande quantité d'objets y est chargée, l'utilisation de la mémoire " +"peut potentiellement croître jusqu'à atteindre java.lang.OutOfMemoryError, " +"le maximum alouable à l'application. Une solution à ce problème est " +"d'appeler les méthodes <literal>Session.clear()</literal> et " +"<literal>Session.evict()</literal> pour gérer la mémoire cache de la " +"<literal>Session</literal>. Vous pouvez également utiliser des procédures " +"stockées si vous devez lancer des traitements sur de grandes quantités " +"d'informations. Certaines solutions sont décrites ici : <xref linkend=\"batch" +"\" />. Garder une <literal>Session</literal> ouverte pour toute la durée " +"d'une session usager, augmente également considérablement le risque de " +"travailler avec des informations périmées. " + +#. Tag: title +#, no-c-format +msgid "Database transaction demarcation" +msgstr "Démarcation des transactions de base de données" + +#. Tag: para +#, no-c-format +msgid "" +"Database, or system, transaction boundaries are always necessary. No " +"communication with the database can occur outside of a database transaction " +"(this seems to confuse many developers who are used to the auto-commit " +"mode). Always use clear transaction boundaries, even for read-only " +"operations. Depending on your isolation level and database capabilities this " +"might not be required, but there is no downside if you always demarcate " +"transactions explicitly. Certainly, a single database transaction is going " +"to perform better than many small transactions, even for reading data." +msgstr "" +"La démarcation des transactions de base de données (ou système) est toujours " +"nécessaire. Aucune communication avec la base de données ne peut être " +"effectuée à l'extérieur du cadre d'une transaction. (Il semble que ce " +"concept soit mal compris par plusieurs développeurs trop habitués à utiliser " +"le mode auto-commit.) Utilisez toujours la démarcation des des transactions, " +"même pour des opérations en lecture seule. Certains niveaux d'isolation et " +"certaines possibilités offertes par les bases de données permettent de " +"l'éviter, il n'est jamais désavantageux de toujours explicitement indiquer " +"les bornes de transaction. Il est certain qu'une transaction unique de base " +"de données sera plus performante que de nombreuses petites transactions, " +"même pour les opérations simples de lecture. " + +#. Tag: para +#, no-c-format +msgid "" +"A Hibernate application can run in non-managed (i.e., standalone, simple " +"Web- or Swing applications) and managed J2EE environments. In a non-managed " +"environment, Hibernate is usually responsible for its own database " +"connection pool. The application developer has to manually set transaction " +"boundaries (begin, commit, or rollback database transactions) themselves. A " +"managed environment usually provides container-managed transactions (CMT), " +"with the transaction assembly defined declaratively (in deployment " +"descriptors of EJB session beans, for example). Programmatic transaction " +"demarcation is then no longer necessary." +msgstr "" +"Une application utilisant Hibernate peut s'exécuter dans un environnement " +"léger n'offrant pas la gestion automatique des transactions (application " +"autonome, application web simple ou applications Swing) ou dans un " +"environnement J2EE offrant des services de gestion automatiques des " +"transactions JTA. Dans un environnement simple, Hibernate a généralement la " +"responsabilité de la gestion de son propre pool de connexions à la base de " +"données. Le développeur de l'application doit manuellement délimiter les " +"transactions. En d'autres mots, il appartient au développeur de gérer les " +"appels à <literal>Transaction.begin()</literal> , <literal>Transaction.commit" +"()</literal> et <literal>Transaction.rollback()</literal>. Un environnement " +"transactionnel J2EE (serveur d'application J2EE) doit offrir la gestion des " +"transactions au niveau du conteneur J2EE. Les bornes de transaction peuvent " +"normalement être définies de manière déclarative dans les descripteurs de " +"déploiement d'EJB Session, par exemple. La gestion programmatique des " +"transactions n'y est donc plus nécessaire." + +#. Tag: para +#, no-c-format +msgid "" +"However, it is often desirable to keep your persistence layer portable " +"between non-managed resource-local environments, and systems that can rely " +"on JTA but use BMT instead of CMT. In both cases use programmatic " +"transaction demarcation. Hibernate offers a wrapper API called " +"<literal>Transaction</literal> that translates into the native transaction " +"system of your deployment environment. This API is actually optional, but we " +"strongly encourage its use unless you are in a CMT session bean." +msgstr "" +"Cependant, il est souvent préférable d'avoir une couche de persistance " +"portable entre les environnements non gérés de ressources locales et les " +"systèmes qui s'appuient sur JTA mais utilisent BMT à la place de CMT. Dans " +"les deux cas, vous utiliserez la démarcation de transaction programmatique. " +"Hibernate offre donc une API appelée <literal>Transaction</literal> qui sert " +"d'enveloppe pour le système de transaction natif de l'environnement de " +"déploiement. Il n'est pas obligatoire d'utiliser cette API, mais il est " +"fortement conseillé de le faire, sauf lors de l'utilisation de CMT Session " +"Bean." + +#. Tag: para +#, no-c-format +msgid "" +"Ending a <literal>Session</literal> usually involves four distinct phases:" +msgstr "" +"Il existe quatre étapes distinctes lors de la fermeture d'une " +"<literal>Session</literal> :" + +#. Tag: para +#, no-c-format +msgid "flush the session" +msgstr "flush de la session" + +#. Tag: para +#, no-c-format +msgid "commit the transaction" +msgstr "commit de la transaction" + +#. Tag: para +#, no-c-format +msgid "close the session" +msgstr "fermeture de la session " + +#. Tag: para +#, no-c-format +msgid "handle exceptions" +msgstr "gestion des exceptions" + +#. Tag: para +#, no-c-format +msgid "" +"We discussed Flushing the session earlier, so we will now have a closer look " +"at transaction demarcation and exception handling in both managed and non-" +"managed environments." +msgstr "" +"La notion de \"Flushing\" a déjà été expliquée, nous abordons maintenant la " +"démarcation des transactions et la gestion des exceptions dans les " +"environnements gérés et non-gérés." + +#. Tag: title +#, no-c-format +msgid "Non-managed environment" +msgstr "Environnement non gérés" + +#. Tag: para +#, no-c-format +msgid "" +"If a Hibernate persistence layer runs in a non-managed environment, database " +"connections are usually handled by simple (i.e., non-DataSource) connection " +"pools from which Hibernate obtains connections as needed. The session/" +"transaction handling idiom looks like this:" +msgstr "" +"Si la couche de persistance Hibernate s'exécute dans un environnement non " +"géré, les connexions à la base de données seront généralement prises en " +"charge par le mécanisme de pool d'Hibernate qui obtient les connexions. La " +"gestion de la session et de la transaction se fera donc de la manière " +"suivante : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"You do not have to <literal>flush()</literal> the <literal>Session</literal> " +"explicitly: the call to <literal>commit()</literal> automatically triggers " +"the synchronization depending on the <link linkend=\"objectstate-flushing" +"\">FlushMode</link> for the session. A call to <literal>close()</literal> " +"marks the end of a session. The main implication of <literal>close()</" +"literal> is that the JDBC connection will be relinquished by the session. " +"This Java code is portable and runs in both non-managed and JTA environments." +msgstr "" +"Vous n'avez pas à invoquer <literal>flush()</literal> explicitement sur la " +"<literal>Session</literal> - l'appel de <literal>commit()</literal> " +"déclenchera automatiquement la synchronisation (selon le FlushMode <xref " +"linkend=\"objectstate-flushing\" /> de la session. Un appel à <literal>close" +"()</literal> marque la fin de la session. La conséquence directe de " +"<literal>close()</literal> est que la connexion à la base de données sera " +"relâchée par la session. Ce code est portable et fonctionne dans les " +"environnements non gérés et les environnements JTA. " + +#. Tag: para +#, no-c-format +msgid "" +"As outlined earlier, a much more flexible solution is Hibernate's built-in " +"\"current session\" context management:" +msgstr "" +"Une solution plus flexible est la gestion par contexte de la session " +"courante intégrée, fournie par Hibernate que nous avons déjà rencontrée :" + +#. Tag: para +#, no-c-format +msgid "" +"You will not see these code snippets in a regular application; fatal " +"(system) exceptions should always be caught at the \"top\". In other words, " +"the code that executes Hibernate calls in the persistence layer, and the " +"code that handles <literal>RuntimeException</literal> (and usually can only " +"clean up and exit), are in different layers. The current context management " +"by Hibernate can significantly simplify this design by accessing a " +"<literal>SessionFactory</literal>. Exception handling is discussed later in " +"this chapter." +msgstr "" +"Vous ne verrez probablement jamais ces exemples de code dans les " +"applications ; les exceptions fatales (exceptions du système) ne devraient " +"être traitées que dans la couche la plus \"haute\". En d'autres termes, le " +"code qui exécute les appels à Hibernate (à la couche de persistance) et le " +"code qui gère les <literal>RuntimeException</literal> (qui ne peut " +"généralement effectuer qu'un nettoyage et une sortie) sont dans des couches " +"différentes. La gestion du contexte courant par Hibernate peut simplifier " +"notablement ce design, puisqu'il vous suffit d'accéder à la " +"<literal>SessionFactory</literal>. La gestion des exceptions est traitée " +"plus loin dans ce chapitre. " + +#. Tag: para +#, no-c-format +msgid "" +"You should select <literal>org.hibernate.transaction.JDBCTransactionFactory</" +"literal>, which is the default, and for the second example select <literal>" +"\"thread\"</literal> as your <literal>hibernate." +"current_session_context_class</literal>." +msgstr "" +"Notez que vous devriez sélectionner <literal>org.hibernate.transaction." +"JDBCTransactionFactory</literal> (le défaut), pour le second exemple " +"<literal>\"thread\"</literal> comme votre <literal>hibernate." +"current_session_context_class</literal>. " + +#. Tag: title +#, no-c-format +msgid "Using JTA" +msgstr "Utilisation de JTA" + +#. Tag: para +#, no-c-format +msgid "" +"If your persistence layer runs in an application server (for example, behind " +"EJB session beans), every datasource connection obtained by Hibernate will " +"automatically be part of the global JTA transaction. You can also install a " +"standalone JTA implementation and use it without EJB. Hibernate offers two " +"strategies for JTA integration." +msgstr "" +"Si votre couche de persistance s'exécute dans un serveur d'applications (par " +"exemple, derrière un EJB Session Bean), toutes les datasources utilisées par " +"Hibernate feront automatiquement partie de transactions JTA globales. Vous " +"pouvez également installer une implémentation autonome JTA et l'utiliser " +"sans l'EJB.Hibernate propose deux stratégies pour réussir l'intégration JTA. " + +#. Tag: para +#, no-c-format +msgid "" +"If you use bean-managed transactions (BMT), Hibernate will tell the " +"application server to start and end a BMT transaction if you use the " +"<literal>Transaction</literal> API. The transaction management code is " +"identical to the non-managed environment." +msgstr "" +"Si vous utilisez des transactions gérées par un EJB (bean managed " +"transactions - BMT), Hibernate informera le serveur d'applications du début " +"et de la fin des transactions si vous utilisez l'API <literal>Transaction</" +"literal>. Ainsi, le code de gestion des transactions sera identique dans les " +"environnements non gérés. " + +#. Tag: para +#, no-c-format +msgid "" +"If you want to use a transaction-bound <literal>Session</literal>, that is, " +"the <literal>getCurrentSession()</literal> functionality for easy context " +"propagation, use the JTA <literal>UserTransaction</literal> API directly:" +msgstr "" +"Si vous souhaitez utiliser une <literal>Session</literal> couplée à la " +"transaction, c'est à dire, utiliser la fonctionnalité " +"<literal>getCurrentSession()</literal> pour la propagation facile du " +"contexte, vous devez utiliser l'API JTA <literal>UserTransaction</literal> " +"directement :" + +#. Tag: para +#, no-c-format +msgid "" +"With CMT, transaction demarcation is completed in session bean deployment " +"descriptors, not programmatically. The code is reduced to:" +msgstr "" +"Avec CMT, la démarcation des transactions est faite dans les descripteurs de " +"déploiement des Beans Sessions et non de manière programmatique, par " +"conséquent le code est réduit à : " + +#. Tag: para +#, no-c-format +msgid "" +"In a CMT/EJB, even rollback happens automatically. An unhandled " +"<literal>RuntimeException</literal> thrown by a session bean method tells " +"the container to set the global transaction to rollback. <emphasis>You do " +"not need to use the Hibernate <literal>Transaction</literal> API at all with " +"BMT or CMT, and you get automatic propagation of the \"current\" Session " +"bound to the transaction.</emphasis>" +msgstr "" +"Dans un EJB CMT, le rollback aussi intervient automatiquement, puisqu'une " +"<literal>RuntimeException</literal> non traitée et soulevée par une méthode " +"d'un bean session indique au conteneur d'annuler la transaction globale. " +"<emphasis>Ceci veut donc dire que vous n'avez pas à utiliser l'API " +"<literal>Transaction</literal> de Hibernate dans CMT ou BMT et vous obtenez " +"la propagation automatique de la session courante liée à la transaction.</" +"emphasis>" + +#. Tag: para +#, no-c-format +msgid "" +"When configuring Hibernate's transaction factory, choose <literal>org." +"hibernate.transaction.JTATransactionFactory</literal> if you use JTA " +"directly (BMT), and <literal>org.hibernate.transaction." +"CMTTransactionFactory</literal> in a CMT session bean. Remember to also set " +"<literal>hibernate.transaction.manager_lookup_class</literal>. Ensure that " +"your <literal>hibernate.current_session_context_class</literal> is either " +"unset (backwards compatibility), or is set to <literal>\"jta\"</literal>." +msgstr "" +"Notez que le fichier de configuration Hibernate devrait contenir les valeurs " +"<literal>org.hibernate.transaction.JTATransactionFactory</literal> dans un " +"environnement BMT ou <literal>org.hibernate.transaction." +"CMTTransactionFactory</literal> dans un environnement CMT là où vous " +"configurez votre fabrique de transaction Hibernate. N'oubliez pas non plus " +"de spécifier le paramètre <literal>org.hibernate.transaction." +"manager_lookup_class</literal> . De plus, assurez vous de fixer votre " +"<literal>hibernate.current_session_context_class</literal> soit à <literal>" +"\"jta\"</literal> ou de ne pas le configurer (compatibilité avec les " +"versions précédentes). " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>getCurrentSession()</literal> operation has one downside in a " +"JTA environment. There is one caveat to the use of <literal>after_statement</" +"literal> connection release mode, which is then used by default. Due to a " +"limitation of the JTA spec, it is not possible for Hibernate to " +"automatically clean up any unclosed <literal>ScrollableResults</literal> or " +"<literal>Iterator</literal> instances returned by <literal>scroll()</" +"literal> or <literal>iterate()</literal>. You <emphasis>must</emphasis> " +"release the underlying database cursor by calling <literal>ScrollableResults." +"close()</literal> or <literal>Hibernate.close(Iterator)</literal> explicitly " +"from a <literal>finally</literal> block. Most applications can easily avoid " +"using <literal>scroll()</literal> or <literal>iterate()</literal> from the " +"JTA or CMT code.)" +msgstr "" +"La méthode <literal>getCurrentSession()</literal> a un inconvénient dans les " +"environnements JTA. Il y a une astuce qui est d'utiliser un mode de " +"libération de connexion <literal>after_statement</literal> , qui est alors " +"utilisé par défaut. Du à une étrange limitation de la spec JTA, il n'est pas " +"possible à Hibernate de nettoyer automatiquement un " +"<literal>ScrollableResults</literal> ouvert ou une instance " +"d'<literal>Iterator</literal> retournés <literal>scroll()</literal> ou " +"<literal>iterate()</literal>. Vous <emphasis>devez</emphasis> libérer le " +"curseur base de données sous jacent ou invoquer <literal>Hibernate.close" +"(Iterator)</literal> explicitement depuis un bloc <literal>finally</" +"literal>. (Bien sur, la plupart des applications peuvent éviter d'utiliser " +"<literal>scroll()</literal> ou <literal>iterate()</literal> dans un code JTA " +"ou CMT.) " + +#. Tag: title +#, no-c-format +msgid "Exception handling" +msgstr "Gestion des exceptions" + +#. Tag: para +#, no-c-format +msgid "" +"If the <literal>Session</literal> throws an exception, including any " +"<literal>SQLException</literal>, immediately rollback the database " +"transaction, call <literal>Session.close()</literal> and discard the " +"<literal>Session</literal> instance. Certain methods of <literal>Session</" +"literal> will <emphasis>not</emphasis> leave the session in a consistent " +"state. No exception thrown by Hibernate can be treated as recoverable. " +"Ensure that the <literal>Session</literal> will be closed by calling " +"<literal>close()</literal> in a <literal>finally</literal> block." +msgstr "" +"Si une <literal>Session</literal> lance une exception (incluant les " +"exceptions du type <literal>SQLException</literal> ou d'un sous-type), vous " +"devez immédiatement effectuer le rollback de la transaction, appeler " +"<literal>Session.close()</literal> et relâcher les références sur l'objet " +"<literal>Session</literal> . La <literal>Session</literal> contient des " +"méthodes pouvant la mettre dans un état inutilisable. Vous devez considérer " +"qu'<emphasis>aucune</emphasis> exception lancée par Hibernate n'est " +"traitable comme recouvrable. Assurez-vous de fermer la session en appelant " +"<literal>close()</literal> dans un bloc <literal>finally</literal> . " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>HibernateException</literal>, which wraps most of the errors " +"that can occur in a Hibernate persistence layer, is an unchecked exception. " +"It was not in older versions of Hibernate. In our opinion, we should not " +"force the application developer to catch an unrecoverable exception at a low " +"layer. In most systems, unchecked and fatal exceptions are handled in one of " +"the first frames of the method call stack (i.e., in higher layers) and " +"either an error message is presented to the application user or some other " +"appropriate action is taken. Note that Hibernate might also throw other " +"unchecked exceptions that are not a <literal>HibernateException</literal>. " +"These are not recoverable and appropriate action should be taken." +msgstr "" +"L'exception <literal>HibernateException</literal>, qui englobe la plupart " +"des exceptions pouvant survenir dans la couche de persistance Hibernate, est " +"une exception non vérifiée (Ceci n'était pas le cas dans des versions " +"antérieures de Hibernate.) Nous pensons que nous ne devrions pas forcer un " +"développeur à gérer une exception qu'il ne peut de toute façon pas traiter " +"dans une couche technique. Dans la plupart des systèmes, les exceptions non " +"vérifiées et les exceptions fatales sont gérées en amont du processus (dans " +"les couches hautes) et un message d'erreur est alors affiché à l'usager (ou " +"un traitement alternatif est invoqué.) Veuillez noter que Hibernate peut " +"également lancer des exceptions non vérifiées d'un autre type que " +"<literal>HibernateException</literal>. Celles-ci sont également non " +"traitables et vous devez les traiter comme telles. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate wraps <literal>SQLException</literal>s thrown while interacting " +"with the database in a <literal>JDBCException</literal>. In fact, Hibernate " +"will attempt to convert the exception into a more meaningful subclass of " +"<literal>JDBCException</literal>. The underlying <literal>SQLException</" +"literal> is always available via <literal>JDBCException.getCause()</" +"literal>. Hibernate converts the <literal>SQLException</literal> into an " +"appropriate <literal>JDBCException</literal> subclass using the " +"<literal>SQLExceptionConverter</literal> attached to the " +"<literal>SessionFactory</literal>. By default, the " +"<literal>SQLExceptionConverter</literal> is defined by the configured " +"dialect. However, it is also possible to plug in a custom implementation. " +"See the javadocs for the <literal>SQLExceptionConverterFactory</literal> " +"class for details. The standard <literal>JDBCException</literal> subtypes " +"are:" +msgstr "" +"Hibernate englobe les <literal>SQLException</literal> s lancées lors des " +"interactions directes avec la base de données dans des exceptions de type: " +"<literal>JDBCException</literal>. En fait, Hibernate essaiera de convertir " +"l'exception dans un sous-type plus significatif de <literal>JDBCException</" +"literal>. L'exception <literal>SQLException</literal> sous-jacente est " +"toujours disponible via la méthode <literal>JDBCException.getCause()</" +"literal>. Hibernate convertit le <literal>SQLExceptionConverter</literal> en " +"une sous-classe <literal>JDBCException</literal>, en utilisant le " +"<literal>SQLExceptionConverter</literal> qui est rattaché à l'objet " +"<literal>SessionFactory</literal>. Par défaut, le " +"<literal>SQLExceptionConverter</literal> est défini par le dialecte " +"configuré dans Hibernate. Toutefois, il est possible de fournir sa propre " +"implémentation de l'interface. (Veuillez vous référer à la javadoc sur la " +"classe <literal>SQLExceptionConverterFactory</literal> pour plus de détails. " +"Les sous-types standard de <literal>JDBCException</literal> sont :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>JDBCConnectionException</literal>: indicates an error with the " +"underlying JDBC communication." +msgstr "" +"<literal>JDBCConnectionException</literal> - indique une erreur de " +"communication avec la couche JDBC sous-jacente. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>SQLGrammarException</literal>: indicates a grammar or syntax " +"problem with the issued SQL." +msgstr "" +"<literal>SQLGrammarException</literal> - indique un problème de grammaire ou " +"de syntaxe avec la requête SQL envoyée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ConstraintViolationException</literal>: indicates some form of " +"integrity constraint violation." +msgstr "" +"<literal>ConstraintViolationException</literal> - indique une violation de " +"contrainte d'intégrité. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockAcquisitionException</literal>: indicates an error acquiring a " +"lock level necessary to perform the requested operation." +msgstr "" +"<literal>LockAcquisitionException</literal> - indique une erreur de " +"verrouillage lors de l'exécution de la requête. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>GenericJDBCException</literal>: a generic exception which did not " +"fall into any of the other categories." +msgstr "" +"<literal>GenericJDBCException</literal> - indique une erreur générique ne " +"correspondant à aucune autre catégorie. " + +#. Tag: title +#, no-c-format +msgid "Transaction timeout" +msgstr "Timeout de transaction" + +#. Tag: para +#, no-c-format +msgid "" +"An important feature provided by a managed environment like EJB, that is " +"never provided for non-managed code, is transaction timeout. Transaction " +"timeouts ensure that no misbehaving transaction can indefinitely tie up " +"resources while returning no response to the user. Outside a managed (JTA) " +"environment, Hibernate cannot fully provide this functionality. However, " +"Hibernate can at least control data access operations, ensuring that " +"database level deadlocks and queries with huge result sets are limited by a " +"defined timeout. In a managed environment, Hibernate can delegate " +"transaction timeout to JTA. This functionality is abstracted by the " +"Hibernate <literal>Transaction</literal> object." +msgstr "" +"Une des caractéristiques extrêmement importante fournie dans les " +"environnements gérés tels les EJB, est la gestion du timeout de transaction " +"qui n'est jamais fournie pour le code non géré. La gestion des dépassements " +"de temps de transaction vise à s'assurer qu'une transaction agissant " +"incorrectement ne viendra pas bloquer indéfiniment les ressources de " +"l'application et ne retourner aucune réponse à l'utilisateur. Hibernate ne " +"peut fournir cette fonctionnalité dans un environnement transactionnel non-" +"JTA. Par contre, Hibernate gère les opérations d'accès aux données en " +"allouant un temps maximal aux requêtes pour s'exécuter. Ainsi, une requête " +"créant de l'inter blocage ou retournant de très grandes quantités " +"d'informations pourrait être interrompue. Dans un environnement géré, " +"Hibernate peut déléguer au gestionnaire de transaction JTA, le soin de gérer " +"les dépassements de temps. Cette fonctionnalité est abstraite par l'objet " +"<literal>Transaction</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>setTimeout()</literal> cannot be called in a CMT bean, where " +"transaction timeouts must be defined declaratively." +msgstr "" +"Notez que <literal>setTimeout()</literal> ne peut pas être appelé d'un EJB " +"CMT, puisque le timeout des transaction doit être spécifié de manière " +"déclarative. " + +#. Tag: title +#, no-c-format +msgid "Optimistic concurrency control" +msgstr "Contrôle de concurrence optimiste" + +#. Tag: para +#, no-c-format +msgid "" +"The only approach that is consistent with high concurrency and high " +"scalability, is optimistic concurrency control with versioning. Version " +"checking uses version numbers, or timestamps, to detect conflicting updates " +"and to prevent lost updates. Hibernate provides three possible approaches to " +"writing application code that uses optimistic concurrency. The use cases we " +"discuss are in the context of long conversations, but version checking also " +"has the benefit of preventing lost updates in single database transactions." +msgstr "" +"La gestion optimiste des accès concurrents avec versionnage est la seule " +"approche pouvant garantir l'extensibilité des applications à haut niveau de " +"charge. Le système de versionnage utilise des numéros de version ou " +"l'horodatage pour détecter les mise à jour causant des conflits avec " +"d'autres actualisations antérieures (et pour éviter la perte de mise à " +"jour). Hibernate propose trois approches possibles pour l'écriture de code " +"applicatif utilisant la gestion optimiste d'accès concurrents. Le cas " +"d'utilisation décrit plus bas fait mention de longues conversations, mais le " +"versionnage peut également améliorer la qualité d'une application en " +"prévenant la perte de mise à jour dans les transactions uniques de base de " +"données. " + +#. Tag: title +#, no-c-format +msgid "Application version checking" +msgstr "Vérification du versionnage au niveau applicatif" + +#. Tag: para +#, no-c-format +msgid "" +"In an implementation without much help from Hibernate, each interaction with " +"the database occurs in a new <literal>Session</literal> and the developer is " +"responsible for reloading all persistent instances from the database before " +"manipulating them. The application is forced to carry out its own version " +"checking to ensure conversation transaction isolation. This approach is the " +"least efficient in terms of database access. It is the approach most similar " +"to entity EJBs." +msgstr "" +"Dans cet exemple d'implémentation utilisant peu les fonctionnalités de " +"Hibernate, chaque interaction avec la base de données se fait en utilisant " +"une nouvelle <literal>Session</literal> et le développeur doit recharger les " +"données persistantes à partir de la base de données avant de les manipuler. " +"Cette implémentation force l'application à vérifier la version des objets " +"afin de maintenir l'isolation transactionnelle. Cette approche, semblable à " +"celle retrouvée pour les EJB, est la moins efficace parmi celles qui sont " +"présentées dans ce chapitre. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>version</literal> property is mapped using <literal>&lt;" +"version&gt;</literal>, and Hibernate will automatically increment it during " +"flush if the entity is dirty." +msgstr "" +"Le mappage de la propriété <literal>version</literal> est fait via " +"<literal>&lt;version&gt;</literal> et Hibernate l'incrémentera " +"automatiquement à chaque flush() si l'entité doit être mise à jour." + +#. Tag: para +#, no-c-format +msgid "" +"If you are operating in a low-data-concurrency environment, and do not " +"require version checking, you can use this approach and skip the version " +"check. In this case, <emphasis>last commit wins</emphasis> is the default " +"strategy for long conversations. Be aware that this might confuse the users " +"of the application, as they might experience lost updates without error " +"messages or a chance to merge conflicting changes." +msgstr "" +"Bien sûr, si votre application ne fait pas face à beaucoup d'accès " +"concurrents et ne nécessite pas l'utilisation du versionnage, cette approche " +"peut également être utilisée, il n'y a qu'à ignorer le code relié au " +"versionnage. Dans ce cas, la stratégie du <emphasis>last commit wins</" +"emphasis> (littéralement: le dernier commit l'emporte) sera utilisée pour " +"les conversations (longues transactions applicatives). Gardez à l'esprit que " +"cette approche pourrait rendre perplexe les utilisateurs de l'application " +"car ils pourraient perdre des données mises à jour sans qu'aucun message " +"d'erreur ne leur soit présenté et sans avoir la possibilité de fusionner les " +"données. " + +#. Tag: para +#, no-c-format +msgid "" +"Manual version checking is only feasible in trivial circumstances and not " +"practical for most applications. Often not only single instances, but " +"complete graphs of modified objects, have to be checked. Hibernate offers " +"automatic version checking with either an extended <literal>Session</" +"literal> or detached instances as the design paradigm." +msgstr "" +"Il est clair que la gestion manuelle de la vérification du versionnage des " +"objets ne peut être effectuée que dans certains cas triviaux et que cette " +"approche n'est pas valable pour la plupart des applications. De manière " +"générale, les applications ne cherchent pas à actualiser de simples objets " +"sans relations, elles le font généralement pour de larges graphes d'objets. " +"Hibernate peut gérer automatiquement la vérification des versions d'objets " +"en utilisant soit une <literal>Session</literal> longue, soit des instances " +"détachées comme paradigme des conversations. " + +#. Tag: title +#, no-c-format +msgid "Extended session and automatic versioning" +msgstr "Les sessions longues et le versionnage automatique." + +#. Tag: para +#, no-c-format +msgid "" +"A single <literal>Session</literal> instance and its persistent instances " +"that are used for the whole conversation are known as <emphasis>session-per-" +"conversation</emphasis>. Hibernate checks instance versions at flush time, " +"throwing an exception if concurrent modification is detected. It is up to " +"the developer to catch and handle this exception. Common options are the " +"opportunity for the user to merge changes or to restart the business " +"conversation with non-stale data." +msgstr "" +"Dans ce scénario, une seule instance de <literal>Session</literal> et des " +"objets persistants est utilisée pour toute la conversation, connue sous " +"<emphasis>session-par-conversation</emphasis>. Hibernate vérifie la version " +"des objets persistants avant d'effectuer le flush() et lance une exception " +"si une modification concurrente est détectée. Il appartient alors au " +"développeur de gérer l'exception. Les traitements alternatifs généralement " +"proposés sont alors de permettre à l'usager de faire la fusion des données " +"ou de lui offrir de recommencer son travail à partie des données les plus " +"récentes dans la base de données. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>Session</literal> is disconnected from any underlying JDBC " +"connection when waiting for user interaction. This approach is the most " +"efficient in terms of database access. The application does not version " +"check or reattach detached instances, nor does it have to reload instances " +"in every database transaction." +msgstr "" +"Notez que lorsqu'une application est en attente d'une action de la part de " +"l'usager, la <literal>Session</literal> n'est pas connectée à la couche JDBC " +"sous-jacente. C'est la manière la plus efficace de gérer les accès à la base " +"de données. L'application ne devrait pas se préoccuper du versionnage des " +"objets, ou du rattachement des objets détachés, ni du rechargement de tous " +"les objets à chaque transaction. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>foo</literal> object knows which <literal>Session</literal> it " +"was loaded in. Beginning a new database transaction on an old session " +"obtains a new connection and resumes the session. Committing a database " +"transaction disconnects a session from the JDBC connection and returns the " +"connection to the pool. After reconnection, to force a version check on data " +"you are not updating, you can call <literal>Session.lock()</literal> with " +"<literal>LockMode.READ</literal> on any objects that might have been updated " +"by another transaction. You do not need to lock any data that you " +"<emphasis>are</emphasis> updating. Usually you would set <literal>FlushMode." +"MANUAL</literal> on an extended <literal>Session</literal>, so that only the " +"last database transaction cycle is allowed to actually persist all " +"modifications made in this conversation. Only this last database transaction " +"will include the <literal>flush()</literal> operation, and then " +"<literal>close()</literal> the session to end the conversation." +msgstr "" +"L'objet <literal>foo</literal> sait quel objet <literal>Session</literal> " +"l'a chargé. <literal>Session.reconnect()</literal> obtient une nouvelle " +"connexion (celle-ci peut être également fournie) et permet à la session de " +"continuer son travail. La méthode <literal>Session.disconnect()</literal> " +"déconnecte la session de la connexion JDBC et retourne celle-ci au pool de " +"connexion (à moins que vous ne lui ayez fourni vous même la connexion.) " +"Après la reconnexion, afin de forcer la vérification du versionnage de " +"certaines entités que vous ne cherchez pas à actualiser, vous pouvez faire " +"un appel à <literal>Session.lock()</literal> en mode <literal>LockMode.READ</" +"literal> pour tout objet ayant pu être modifié par une autre transaction. Il " +"n'est pas nécessaire de verrouiller les données que vous désirez mettre à " +"jour. En général, vous configurerez<literal>FlushMode.NEVER</literal> sur " +"une <literal>Session</literal> étendue, de façon que seul le dernier cycle " +"de transaction de la base de données puissent persister toutes les " +"modifications effectuées dans cette conversation. Par conséquent, cette " +"dernière transaction inclura l'opération <literal>flush()</literal>, de même " +"que <literal>close()</literal> la session pour finir la conversation." + +#. Tag: para +#, no-c-format +msgid "" +"This pattern is problematic if the <literal>Session</literal> is too big to " +"be stored during user think time (for example, an <literal>HttpSession</" +"literal> should be kept as small as possible). As the <literal>Session</" +"literal> is also the first-level cache and contains all loaded objects, we " +"can probably use this strategy only for a few request/response cycles. Use a " +"<literal>Session</literal> only for a single conversation as it will soon " +"have stale data." +msgstr "" +"Ce modèle peut présenter des problèmes si la <literal>Session</literal> est " +"trop volumineuse pour être stockée entre les actions de l'usager. Plus " +"spécifiquement, une session <literal>HttpSession</literal> se doit d'être la " +"plus petite possible. Puisque la <literal>Session</literal> joue " +"obligatoirement le rôle de mémoire cache de premier niveau et contient à ce " +"titre tous les objets chargés, il est préférable de n'utiliser une " +"<literal>Session</literal> que pour une seule conversation, car les objets " +"risquent d'y être rapidement périmés." + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "Remarque" + +#. Tag: para +#, no-c-format +msgid "" +"Earlier versions of Hibernate required explicit disconnection and " +"reconnection of a <literal>Session</literal>. These methods are deprecated, " +"as beginning and ending a transaction has the same effect." +msgstr "" +"Notez que des versions précédentes de Hibernate exigeaient une déconnexion " +"explicite et une reconnexion d'une <literal>Session</literal>. Ces méthodes " +"sont périmées, puisque commencer et terminer une transaction a le même effet." + +#. Tag: para +#, no-c-format +msgid "" +"Keep the disconnected <literal>Session</literal> close to the persistence " +"layer. Use an EJB stateful session bean to hold the <literal>Session</" +"literal> in a three-tier environment. Do not transfer it to the web layer, " +"or even serialize it to a separate tier, to store it in the " +"<literal>HttpSession</literal>." +msgstr "" +"Notez que la <literal>Session</literal> déconnectée devrait être conservée " +"près de la couche de persistance. Autrement dit, utilisez un EJB stateful " +"pour conserver la <literal>Session</literal> dans un environnement 3 niveaux " +"et évitez de la sérialiser et de la transférer à la couche de présentation " +"(c'est-à-dire qu'il est préférable de ne pas la conserver dans la session " +"<literal>HttpSession</literal> .) " + +#. Tag: para +#, no-c-format +msgid "" +"The extended session pattern, or <emphasis>session-per-conversation</" +"emphasis>, is more difficult to implement with automatic current session " +"context management. You need to supply your own implementation of the " +"<literal>CurrentSessionContext</literal> for this. See the Hibernate Wiki " +"for examples." +msgstr "" +"Le modèle de session étendue, ou <emphasis>session-par-conversation</" +"emphasis>, est plus difficile à implémenter avec la gestion automatique de " +"contexte de session courante. À cet effet, vous devez fournir votre propre " +"implémentation de<literal>CurrentSessionContext</literal>, pour des exemples " +"consultez Hibernate Wiki. " + +#. Tag: title +#, no-c-format +msgid "Detached objects and automatic versioning" +msgstr "Les objets détachés et le versionnage automatique" + +#. Tag: para +#, no-c-format +msgid "" +"Each interaction with the persistent store occurs in a new <literal>Session</" +"literal>. 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 <literal>Session</literal> " +"and then reattaches them using <literal>Session.update()</literal>, " +"<literal>Session.saveOrUpdate()</literal>, or <literal>Session.merge()</" +"literal>." +msgstr "" +"Chaque interaction avec le système de persistance se fait via une nouvelle " +"<literal>Session</literal> . Toutefois, les mêmes instances d'objets " +"persistants sont réutilisées pour chacune de ces interactions. L'application " +"doit pouvoir manipuler l'état des instances détachées ayant été chargées " +"antérieurement via une autre session. Pour ce faire, ces objets persistants " +"doivent être rattachés à la <literal>Session</literal> courante en utilisant " +"<literal>Session.update()</literal>, <literal>Session.saveOrUpdate()</" +"literal>, ou <literal>Session.merge()</literal> ." + +#. Tag: para +#, no-c-format +msgid "" +"Again, Hibernate will check instance versions during flush, throwing an " +"exception if conflicting updates occurred." +msgstr "" +"Encore une fois, Hibernate vérifiera la version des instances devant être " +"actualisées durant le flush(). Une exception sera lancée si des conflits " +"sont détectés. " + +#. Tag: para +#, no-c-format +msgid "" +"You can also call <literal>lock()</literal> instead of <literal>update()</" +"literal>, and use <literal>LockMode.READ</literal> (performing a version " +"check and bypassing all caches) if you are sure that the object has not been " +"modified." +msgstr "" +"Vous pouvez également utiliser <literal>lock()</literal> au lieu de " +"<literal>update()</literal> et utiliser le mode <literal>LockMode.READ</" +"literal> (qui lancera une vérification de version, en ignorant tous les " +"niveaux de mémoire cache) si vous êtes certain que l'objet n'a pas été " +"modifié. " + +#. Tag: title +#, no-c-format +msgid "Customizing automatic versioning" +msgstr "Personnaliser le versionnage automatique" + +#. Tag: para +#, no-c-format +msgid "" +"You can disable Hibernate's automatic version increment for particular " +"properties and collections by setting the <literal>optimistic-lock</literal> " +"mapping attribute to <literal>false</literal>. Hibernate will then no longer " +"increment versions if the property is dirty." +msgstr "" +"Vous pouvez désactiver l'incrémentation automatique du numéro de version de " +"certains attributs et collections en mettant la valeur du paramètre de " +"mapping <literal>optimistic-lock</literal> à <literal>false</literal>. " +"Hibernate cessera ainsi d'incrémenter leur numéro de version si la propriété " +"est dirty. " + +#. Tag: para +#, no-c-format +msgid "" +"Legacy database schemas are often static and cannot be modified. Or, other " +"applications might access the same database and will not know how to handle " +"version numbers or even timestamps. In both cases, versioning cannot rely on " +"a particular column in a table. To force a version check with a comparison " +"of the state of all fields in a row but without a version or timestamp " +"property mapping, turn on <literal>optimistic-lock=\"all\"</literal> in the " +"<literal>&lt;class&gt;</literal> mapping. This conceptually only works if " +"Hibernate can compare the old and the new state (i.e., if you use a single " +"long <literal>Session</literal> and not session-per-request-with-detached-" +"objects)." +msgstr "" +"Certaines entreprises possèdent de vieux systèmes dont les schémas de bases " +"de données sont statiques et ne peuvent être modifiés. Il existe aussi des " +"cas où plusieurs applications doivent accéder à la même base de données, " +"mais certaines d'entre elles ne peuvent gérer les numéros de version ou les " +"champs horodatés. Dans les deux cas, le versionnage ne peut se fier à une " +"colonne particulière dans une table. Afin de forcer la vérification de " +"version dans un système sans en faire le mappage, mais en forçant une " +"comparaison des états de tous les attributs d'une entité, vous pouvez " +"utiliser l'attribut <literal>optimistic- lock=\"all\"</literal> dans le " +"mappage <literal>&lt;class&gt;</literal>. Veuillez noter que cette manière " +"de gérer le versionnage ne peut être utilisée que si l'application utilise " +"de longues sessions, lui permettant de comparer l'ancien état et le nouvel " +"état d'une entité. L'utilisation d'un modèle <literal>session-per-request-" +"with-detached- objects</literal> devient alors impossible. " + +#. Tag: para +#, no-c-format +msgid "" +"Concurrent modification can be permitted in instances where the changes that " +"have been made do not overlap. If you set <literal>optimistic-lock=\"dirty" +"\"</literal> when mapping the <literal>&lt;class&gt;</literal>, Hibernate " +"will only compare dirty fields during flush." +msgstr "" +"Il peut être souhaitable de permettre les modifications concurrentes du " +"moment que les modifications ne se chevauchent pas. En configurant la " +"propriété à <literal>optimistic-lock=\"dirty\"</literal> quand vous mappez " +"le <literal>&lt;class&gt;</literal>, Hibernate ne fera la comparaison que " +"des champs devant être actualisés lors du flush." + +#. Tag: para +#, no-c-format +msgid "" +"In both cases, with dedicated version/timestamp columns or with a full/dirty " +"field comparison, Hibernate uses a single <literal>UPDATE</literal> " +"statement, with an appropriate <literal>WHERE</literal> clause, per entity " +"to execute the version check and update the information. If you use " +"transitive persistence to cascade reattachment to associated entities, " +"Hibernate may execute unnecessary updates. This is usually not a problem, " +"but <emphasis>on update</emphasis> triggers in the database might be " +"executed even when no changes have been made to detached instances. You can " +"customize this behavior by setting <literal>select-before-update=\"true\"</" +"literal> in the <literal>&lt;class&gt;</literal> mapping, forcing Hibernate " +"to <literal>SELECT</literal> the instance to ensure that changes did occur " +"before updating the row." +msgstr "" +"Dans les deux cas: en utilisant une colonne de version/horodatée ou via la " +"comparaison de l'état complet de l'objet ou de ses champs modifiés, " +"Hibernate ne créera qu'une seule commande <literal>UPDATE</literal> par " +"entité avec la clause <literal>WHERE</literal> appropriée pour vérifier la " +"version et mettre à jour les informations. Si vous utilisez la persistance " +"transitive pour propager l'évènement de rattachement à des entités " +"associées, il est possible que Hibernate génère des commandes de mise à jour " +"inutiles. Ceci n'est généralement pas un problème, mais certains " +"déclencheurs <emphasis>on update</emphasis> dans la base de données " +"pourraient être activés même si aucun changement n'était réellement persisté " +"sur des objets détachés. Vous pouvez personnaliser ce comportement en " +"indiquant <literal>select-before- update=\"true\"</literal> dans l'élément " +"de mappage <literal>&lt;class&gt;</literal>. Ceci forcera Hibernate à faire " +"le <literal>SELECT</literal> de l'instance afin de s'assurer que l'entité " +"doit réellement être actualisée avant de lancer la commande de mise à jour " +"de l'enregistrement. " + +#. Tag: title +#, no-c-format +msgid "Pessimistic locking" +msgstr "Verrouillage pessimiste " + +#. Tag: para +#, no-c-format +msgid "" +"It is not intended that users spend much time worrying about locking " +"strategies. It is usually enough to specify an isolation level for the JDBC " +"connections and then simply let the database do all the work. However, " +"advanced users may wish to obtain exclusive pessimistic locks or re-obtain " +"locks at the start of a new transaction." +msgstr "" +"Il n'est nécessaire de s'attarder à la stratégie de verrouillage des entités " +"dans une application utilisant Hibernate. Il est généralement suffisant de " +"définir le niveau d'isolation pour les connexions JDBC et de laisser ensuite " +"la base de donnée effectuer son travail. Toutefois, certains utilisateurs " +"avancés peuvent vouloir obtenir un verrouillage pessimiste exclusif sur un " +"enregistrement, ou le ré-obtenir au lancement d'une nouvelle transaction. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will always use the locking mechanism of the database; it never " +"lock objects in memory." +msgstr "" +"Hibernate utilisera toujours le mécanisme de verrouillage de la base de " +"données et ne verrouillera jamais les objets en mémoire." + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>LockMode</literal> class defines the different lock levels that " +"can be acquired by Hibernate. A lock is obtained by the following mechanisms:" +msgstr "" +"La classe <literal>LockMode</literal> définit les différents niveaux de " +"verrouillage pouvant être obtenus par Hibernate. Le verrouillage est obtenu " +"par les mécanismes suivants : " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockMode.WRITE</literal> is acquired automatically when Hibernate " +"updates or inserts a row." +msgstr "" +"<literal>LockMode.WRITE</literal> est obtenu automatiquement quand Hibernate " +"actualise ou insère un enregistrement." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockMode.UPGRADE</literal> can be acquired upon explicit user " +"request using <literal>SELECT ... FOR UPDATE</literal> on databases which " +"support that syntax." +msgstr "" +"<literal>LockMode.UPGRADE</literal> peut être obtenu de manière explicite " +"via la requête en utilisant <literal>SELECT ... FOR UPDATE</literal> sur une " +"base de données supportant cette syntaxe. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockMode.UPGRADE_NOWAIT</literal> can be acquired upon explicit " +"user request using a <literal>SELECT ... FOR UPDATE NOWAIT</literal> under " +"Oracle." +msgstr "" +"<literal>LockMode.UPGRADE_NOWAIT</literal> peut être obtenu de manière " +"explicite en utilisant <literal>SELECT ... FOR UPDATE NOWAIT</literal> sur " +"Oracle. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockMode.READ</literal> is acquired automatically when Hibernate " +"reads data under Repeatable Read or Serializable isolation level. It can be " +"re-acquired by explicit user request." +msgstr "" +"<literal>LockMode.READ</literal> est obtenu automatiquement quand Hibernate " +"lit des données dans un contexte d'isolation <literal>Repeatable Read</" +"literal> ou <literal>Serializable</literal>. Peut être ré-obtenu " +"explicitement via une requête d'utilisateur. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>LockMode.NONE</literal> represents the absence of a lock. All " +"objects switch to this lock mode at the end of a <literal>Transaction</" +"literal>. Objects associated with the session via a call to <literal>update()" +"</literal> or <literal>saveOrUpdate()</literal> also start out in this lock " +"mode." +msgstr "" +"<literal>LockMode.NONE</literal> représente l'absence de verrouillage. Tous " +"les objets migrent vers ce mode à la fin d'une <literal>Transaction</" +"literal> . Les objets associés à une session via un appel à " +"<literal>saveOrUpdate()</literal> commencent également leur cycle de vie " +"dans ce mode verrouillé. " + +#. Tag: para +#, no-c-format +msgid "" +"The \"explicit user request\" is expressed in one of the following ways:" +msgstr "" +"Les requêtes explicites d'utilisateur sont exprimées d'une des manières " +"suivantes :" + +#. Tag: para +#, no-c-format +msgid "" +"A call to <literal>Session.load()</literal>, specifying a <literal>LockMode</" +"literal>." +msgstr "" +"Un appel à <literal>Session.load()</literal>, en spécifiant un niveau " +"verrouillage <literal>LockMode</literal> ." + +#. Tag: para +#, no-c-format +msgid "A call to <literal>Session.lock()</literal>." +msgstr "Un appel à <literal>Session.lock()</literal>." + +#. Tag: para +#, no-c-format +msgid "A call to <literal>Query.setLockMode()</literal>." +msgstr "Une appel à <literal>Query.setLockMode()</literal>." + +#. Tag: para +#, no-c-format +msgid "" +"If <literal>Session.load()</literal> is called with <literal>UPGRADE</" +"literal> or <literal>UPGRADE_NOWAIT</literal>, and the requested object was " +"not yet loaded by the session, the object is loaded using " +"<literal>SELECT ... FOR UPDATE</literal>. If <literal>load()</literal> is " +"called for an object that is already loaded with a less restrictive lock " +"than the one requested, Hibernate calls <literal>lock()</literal> for that " +"object." +msgstr "" +"Si <literal>Session.load()</literal> est appelé avec le paramètre de niveau " +"de verrouillage <literal>UPGRADE</literal> ou <literal>UPGRADE_NOWAIT</" +"literal> et que l'objet demandé n'est pas présent dans la session, celui-ci " +"sera chargé à l'aide d'une requête <literal>SELECT ... FOR UPDATE</" +"literal> . Si la méthode <literal>load()</literal> est appelée pour un objet " +"déjà en session avec un verrouillage moindre que celui demandé, Hibernate " +"appellera la méthode <literal>lock()</literal> pour cet objet." + +#. Tag: para +#, no-c-format +msgid "" +"<literal>Session.lock()</literal> performs a version number check if the " +"specified lock mode is <literal>READ</literal>, <literal>UPGRADE</literal> " +"or <literal>UPGRADE_NOWAIT</literal>. In the case of <literal>UPGRADE</" +"literal> or <literal>UPGRADE_NOWAIT</literal>, <literal>SELECT ... FOR " +"UPDATE</literal> is used." +msgstr "" +"<literal>Session.lock()</literal> effectue une vérification de version si le " +"niveau de verrouillage est <literal>READ</literal> , <literal>UPGRADE</" +"literal> ou <literal>UPGRADE_NOWAIT</literal> . Dans le cas des niveaux " +"<literal>UPGRADE</literal> ou <literal>UPGRADE_NOWAIT</literal> , une " +"requête <literal>SELECT ... FOR UPDATE</literal> sera utilisée." + +#. Tag: para +#, no-c-format +msgid "" +"If the requested lock mode is not supported by the database, Hibernate uses " +"an appropriate alternate mode instead of throwing an exception. This ensures " +"that applications are portable." +msgstr "" +"Si une base de données ne supporte pas le niveau de verrouillage demandé, " +"Hibernate utilisera un niveau alternatif convenable au lieu de lancer une " +"exception. Ceci assurera la portabilité de vos applications." + +#. Tag: title +#, no-c-format +msgid "Connection release modes" +msgstr "Modes de libération de connexion" + +#. Tag: para +#, no-c-format +msgid "" +"One of the legacies of Hibernate 2.x JDBC connection management meant that a " +"<literal>Session</literal> would obtain a connection when it was first " +"required and then maintain that connection until the session was closed. " +"Hibernate 3.x introduced the notion of connection release modes that would " +"instruct a session how to handle its JDBC connections. The following " +"discussion is pertinent only to connections provided through a configured " +"<literal>ConnectionProvider</literal>. User-supplied connections are outside " +"the breadth of this discussion. The different release modes are identified " +"by the enumerated values of <literal>org.hibernate.ConnectionReleaseMode</" +"literal>:" +msgstr "" +"Le comportement original (2.x) de Hibernate pour la gestion des connexions " +"JDBC était que la <literal>Session</literal> obtenait une connexion dès " +"qu'elle en avait besoin et la libérait une fois la session fermée. Hibernate " +"3.x a introduit les modes de libération de connexion pour indiquer à la " +"session comment gérer les transactions JDBC. Notez que la discussion " +"suivante n'est pertinente que pour des connexions fournies par un " +"<literal>ConnectionProvider</literal>, celles gérées par l'utilisateur " +"dépassent l'objectif de cette discussion. Les différents modes de libération " +"sont identifiés par les valeurs énumérées de <literal>org.hibernate." +"ConnectionReleaseMode</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"<literal>ON_CLOSE</literal>: is the legacy behavior described above. The " +"Hibernate session obtains a connection when it first needs to perform some " +"JDBC access and maintains that connection until the session is closed." +msgstr "" +"<literal>ON_CLOSE</literal> - est essentiellement le comportement passé " +"décrit ci-dessus. La session Hibernate obtient une connexion lorsqu'elle en " +"a besoin et la garde jusqu'à ce que la session se ferme. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>AFTER_TRANSACTION</literal>: releases connections after a " +"<literal>org.hibernate.Transaction</literal> has been completed." +msgstr "" +"<literal>AFTER_TRANSACTION</literal> - indique de relâcher la connexion " +"après qu'une <literal>org.hibernate.Transaction</literal> soit achevée. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>AFTER_STATEMENT</literal> (also referred to as aggressive release): " +"releases connections after every statement execution. This aggressive " +"releasing is skipped if that statement leaves open resources associated with " +"the given session. Currently the only situation where this occurs is through " +"the use of <literal>org.hibernate.ScrollableResults</literal>." +msgstr "" +"<literal>AFTER_STATEMENT</literal> (aussi appelé libération brutale) - " +"indique de relâcher les connexions après chaque exécution d'un statement. Ce " +"relâchement agressif est annulé si ce statement laisse des ressources " +"associées à une session donnée ouvertes, actuellement ceci n'arrive que lors " +"de l'utilisation de <literal>org.hibernate.ScrollableResults</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"The configuration parameter <literal>hibernate.connection.release_mode</" +"literal> is used to specify which release mode to use. The possible values " +"are as follows:" +msgstr "" +"Le paramètre de configuration <literal>hibernate.connection.release_mode</" +"literal> est utilisé pour spécifier quel mode de libération doit être " +"utilisé. Les valeurs possibles sont : " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>auto</literal> (the default): this choice delegates to the release " +"mode returned by the <literal>org.hibernate.transaction.TransactionFactory." +"getDefaultReleaseMode()</literal> method. For JTATransactionFactory, this " +"returns ConnectionReleaseMode.AFTER_STATEMENT; for JDBCTransactionFactory, " +"this returns ConnectionReleaseMode.AFTER_TRANSACTION. Do not change this " +"default behavior as failures due to the value of this setting tend to " +"indicate bugs and/or invalid assumptions in user code." +msgstr "" +"<literal>auto</literal> (valeur par défaut) - ce choix délègue le choix de " +"libération à la méthode <literal>org.hibernate.transaction." +"TransactionFactory.getDefaultReleaseMode()</literal> Pour la " +"JTATransactionFactory, elle retourne ConnectionReleaseMode.AFTER_STATEMENT; " +"pour JDBCTransactionFactory, elle retourne ConnectionReleaseMode." +"AFTER_TRANSACTION. C'est rarement une bonne idée de changer ce comportement " +"par défaut puisque les erreurs soulevées par ce paramétrage tend à indiquer " +"la présence de bogues et/ou d'erreurs dans le code de l'utilisateur. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>on_close</literal>: uses ConnectionReleaseMode.ON_CLOSE. This " +"setting is left for backwards compatibility, but its use is discouraged." +msgstr "" +"<literal>on_close</literal> - indique d'utiliser ConnectionReleaseMode." +"ON_CLOSE. Ce paramétrage existe pour garantir la compatibilité avec les " +"versions précédentes, mais ne devrait plus être utilisé. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>after_transaction</literal>: uses ConnectionReleaseMode." +"AFTER_TRANSACTION. This setting should not be used in JTA environments. Also " +"note that with ConnectionReleaseMode.AFTER_TRANSACTION, if a session is " +"considered to be in auto-commit mode, connections will be released as if the " +"release mode were AFTER_STATEMENT." +msgstr "" +"<literal>after_transaction</literal> - indique d'utiliser " +"ConnectionReleaseMode.AFTER_TRANSACTION. Ne devrait pas être utilisé dans " +"les environnements JTA. Notez aussi qu'avec ConnectionReleaseMode." +"AFTER_TRANSACTION, si une session est considérée comme étant en mode auto-" +"commit les connexions seront relâchées comme si le mode était " +"AFTER_STATEMENT. " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>after_statement</literal>: uses ConnectionReleaseMode." +"AFTER_STATEMENT. Additionally, the configured <literal>ConnectionProvider</" +"literal> is consulted to see if it supports this setting " +"(<literal>supportsAggressiveRelease()</literal>). If not, the release mode " +"is reset to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only " +"safe in environments where we can either re-acquire the same underlying JDBC " +"connection each time you make a call into <literal>ConnectionProvider." +"getConnection()</literal> or in auto-commit environments where it does not " +"matter if we re-establish the same connection." +msgstr "" +"<literal>after_statement</literal> - indique d'utiliser " +"ConnectionReleaseMode.AFTER_STATEMENT. De plus, le " +"<literal>ConnectionProvider</literal> utilisé est consulté pour savoir s'il " +"supporte ce paramétrage (<literal>supportsAggressiveRelease()</literal>). Si " +"ce n'est pas le cas, le mode de libération est ré-initialisé à " +"ConnectionReleaseMode.AFTER_TRANSACTION. Ce paramétrage n'est sûr que dans " +"les environnements où il est possible d'obtenir à nouveau la même connexion " +"JDBC à chaque fois que l'on fait un appel de <literal>ConnectionProvider." +"getConnection()</literal> ou dans les environnements auto-commit où il n'est " +"pas important d'obtenir plusieurs fois la même connexion. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/tutorial.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/tutorial.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/tutorial.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,1792 @@ +# translation of tutorial.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: tutorial\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-11T05:38:16\n" +"PO-Revision-Date: 2010-01-05 10:08+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "Tutorial" +msgstr "Tutoriel" + +#. Tag: para +#, no-c-format +msgid "" +"Intended for new users, this chapter provides an step-by-step introduction " +"to Hibernate, starting with a simple application using an in-memory " +"database. The tutorial is based on an earlier tutorial developed by Michael " +"Gloegl. All code is contained in the <filename>tutorials/web</filename> " +"directory of the project source." +msgstr "" +"A l'intention des nouveaux utilisateurs, ce chapitre fournit une " +"introduction étape par étape à Hibernate, en commençant par une application " +"simple, avec une base de données en-mémoire. Le tutoriel est basé sur une " +"tutoriel antérieur qui avait été développé par Michael Gloegl. Tout le code " +"est contenu dans <filename>tutorials/web</filename> qui se trouve dans le " +"répertoire source du projet. " + +#. Tag: para +#, no-c-format +msgid "" +"This tutorial expects the user have knowledge of both Java and SQL. If you " +"have a limited knowledge of JAVA or SQL, it is advised that you start with a " +"good introduction to that technology prior to attempting to learn Hibernate." +msgstr "" +"Ce tutoriel assume que l'utilisateur est déjà familier avec Java et SQL à la " +"fois. Si vous ne possédez qu'une connaissance de Java et d'SQL limitée, il " +"est conseillé de commencer par vous familiariser avec ces technologies avant " +"d'aborder Hibernate." + +#. Tag: para +#, no-c-format +msgid "" +"The distribution contains another example application under the " +"<filename>tutorial/eg</filename> project source directory." +msgstr "" +"La distribution contient un autre exemple d'application qui se trouve dans " +"le répertoire source du projet <filename>tutorial/eg</filename>." + +#. Tag: title +#, no-c-format +msgid "Part 1 - The first Hibernate Application" +msgstr "Section 1 - Première application Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"For this example, we will set up a small database application that can store " +"events we want to attend and information about the host(s) of these events." +msgstr "" +"Supposons que nous ayons besoin d'une petite application de base de données " +"qui puisse stocker des événements que nous voulons suivre, et des " +"informations à propos des hôtes de ces événements." + +#. Tag: para +#, no-c-format +msgid "" +"Although you can use whatever database you feel comfortable using, we will " +"use <ulink url=\"http://hsqldb.org/\">HSQLDB</ulink> (an in-memory, Java " +"database) to avoid describing installation/setup of any particular database " +"servers." +msgstr "" +"Malgré que vous puissiez utiliser tout base de données qui vous convienne, " +"on choisira <ulink url=\"http://hsqldb.org/\">HSQLDB</ulink> (une base de " +"données Java, en-mémoire) pour éviter de décrire l'installation et la " +"configuration de n'importe quel serveur de base de données particulière." + +#. Tag: title +#, no-c-format +msgid "Setup" +msgstr "Configuration" + +#. Tag: para +#, no-c-format +msgid "" +"The first thing we need to do is to set up the development environment. We " +"will be using the \"standard layout\" advocated by alot of build tools such " +"as <ulink url=\"http://maven.org\">Maven</ulink>. Maven, in particular, has " +"a good resource describing this <ulink url=\"http://maven.apache.org/guides/" +"introduction/introduction-to-the-standard-directory-layout.html\">layout</" +"ulink>. As this tutorial is to be a web application, we will be creating and " +"making use of <filename>src/main/java</filename>, <filename>src/main/" +"resources</filename> and <filename>src/main/webapp</filename> directories." +msgstr "" +"La première chose que nous devons faire est de configurer l'environnement de " +"développement. Nous utiliserons la \"standard layout\" préconisée par de " +"nombreux outils de génération tels que <ulink url=\"http://maven.org" +"\">Maven</ulink>. Maven, en particulier, a une bonne ressource décrivant " +"cette <ulink url=\"http://maven.apache.org/guides/introduction/introduction-" +"to-the-standard-directory-layout.html\">layout</ulink>. Comme ce tutoriel va " +"devenir une application web, nous allons créer et utiliser les répertoires " +"<filename>src/main/java.</filename>, <filename>src/main/ressources</" +"filename> et <filename>src/main/webapp</filename>." + +#. Tag: para +#, no-c-format +msgid "" +"We will be using Maven in this tutorial, taking advantage of its transitive " +"dependency management capabilities as well as the ability of many IDEs to " +"automatically set up a project for us based on the maven descriptor." +msgstr "" +"Nous utiliserons Maven dans ce tutoriel. Nous profiterons de ses capacités " +"de gestion de dépendances transitives, ainsi que de la capacité des nombreux " +"IDE à installer automatiquement un projet sur la base du descripteur Maven." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"It is not a requirement to use Maven. If you wish to use something else to " +"build this tutoial (such as Ant), the layout will remain the same. The only " +"change is that you will need to manually account for all the needed " +"dependencies. If you use something like <ulink url=\"http://ant.apache.org/" +"ivy/\">Ivy</ulink> providing transitive dependency management you would " +"still use the dependencies mentioned below. Otherwise, you'd need to grab " +"<emphasis>all</emphasis> dependencies, both explicit and transitive, and add " +"them to the project's classpath. If working from the Hibernate distribution " +"bundle, this would mean <filename>hibernate3.jar</filename>, all artifacts " +"in the <filename>lib/required</filename> directory and all files from either " +"the <filename>lib/bytecode/cglib</filename> or <filename>lib/bytecode/" +"javassist</filename> directory; additionally you will need both the servlet-" +"api jar and one of the slf4j logging backends." +msgstr "" +"Vous n'êtes pas obligés d'utiliser Maven. Si vous souhaitez utiliser une " +"autre technologie pour créer ce tutoriel (comme Ant), la mise en page " +"restera le même. Le seul changement est que vous devrez manuellement tenir " +"compte de toutes les dépendances nécessaires. Si vous utilisez <ulink url=" +"\"http://ant.apache.org/ivy/\">Ivy</ulink> pour assurer la gestion des " +"dépendances transitives, vous utiliserez toujours les dépendances " +"mentionnées ci-dessous. Dans le cas contraire, vous devrez trouver toutes " +"les dépendances, explicites et transitives, et les ajouter au chemin de " +"classe des projets. Si vous travaillez à partir de l'offre de distribution " +"Hibernate, il s'agit de <filename>hibernate3.jar</filename>, de tous les " +"artefacts du répertoire <filename>lib / requis</filename> et de tous les " +"fichiers des répertoires <filename>lib / pseudo-code binaire/cglib</" +"filename> ou <filename>lib/pseudo-code binaire/javassist</filename>; en " +"outre, vous aurez besoin à la fois du bocal servlet-api et de l'un des " +"gestionnaires de journalisation slf4j." + +#. Tag: para +#, no-c-format +msgid "" +"Save this file as <filename>pom.xml</filename> in the project root directory." +msgstr "" +"Sauvegardez ce fichier sous la forme <filename>pom.xml</filename> dans le " +"répertoire root du projet." + +#. Tag: title +#, no-c-format +msgid "The first class" +msgstr "La première classe" + +#. Tag: para +#, no-c-format +msgid "" +"Next, we create a class that represents the event we want to store in the " +"database; it is a simple JavaBean class with some properties:" +msgstr "" +"Ensuite, nous créons une classe qui représente l'évènement que nous voulons " +"stocker dans notre base de données. Il s'agit d'une simple classe JavaBean " +"avec quelques propriétés :" + +#. Tag: para +#, no-c-format +msgid "" +"This class uses standard JavaBean naming conventions for property getter and " +"setter methods, as well as private visibility for the fields. Although this " +"is the recommended design, it is not required. Hibernate can also access " +"fields directly, the benefit of accessor methods is robustness for " +"refactoring." +msgstr "" +"Vous constaterez que cette classe utilise les conventions de nommage " +"standard JavaBean pour les méthodes getter/setter des propriétés, ainsi " +"qu'une visibilité privée pour les champs. Ceci est la conception recommandée " +"- mais pas obligatoire. Hibernate peut aussi accéder aux champs directement, " +"le bénéfice des méthodes d'accès est la robustesse pour la refonte de code. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>id</literal> property holds a unique identifier value for a " +"particular event. All persistent entity classes (there are less important " +"dependent classes as well) will need such an identifier property if we want " +"to use the full feature set of Hibernate. In fact, most applications, " +"especially web applications, need to distinguish objects by identifier, so " +"you should consider this a feature rather than a limitation. However, we " +"usually do not manipulate the identity of an object, hence the setter method " +"should be private. Only Hibernate will assign identifiers when an object is " +"saved. Hibernate can access public, private, and protected accessor methods, " +"as well as public, private and protected fields directly. The choice is up " +"to you and you can match it to fit your application design." +msgstr "" +"La propriété <literal>id</literal> contient la valeur d'un identifiant " +"unique pour un événement particulier. Toutes les classes d'entités " +"persistantes (il y a également des classes dépendantes de moindre " +"importance) auront besoin d'une telle propriété identifiante si nous voulons " +"utiliser l'ensemble complet des fonctionnalités de Hibernate. En fait, la " +"plupart des applications (surtout les applications web) ont besoin de " +"distinguer des objets par des identifiants, par conséquent considérez cela " +"comme une fonctionnalité et non comme une limitation. Cependant, nous ne " +"manipulons généralement pas l'identité d'un objet, dorénavant la méthode " +"setter devrait être privée. Seul Hibernate assignera les identifiants " +"lorsqu'un objet est sauvegardé. Remarquez que Hibernate peut accéder aux " +"méthodes publiques, privées et protégées, ainsi qu'aux champs (publics, " +"privés, protégés) directement. À vous de choisir, et vous pouvez également " +"l'ajuster à la conception de votre application. " + +#. Tag: para +#, no-c-format +msgid "" +"The no-argument constructor is a requirement for all persistent classes; " +"Hibernate has to create objects for you, using Java Reflection. The " +"constructor can be private, however package or public visibility is required " +"for runtime proxy generation and efficient data retrieval without bytecode " +"instrumentation." +msgstr "" +"Le constructeur sans argument est requis pour toutes les classes " +"persistantes; Hibernate doit créer des objets pour vous en utilisant la " +"réflexion Java. Le constructeur peut être privé, cependant, la visibilité du " +"paquet est requise pour la génération de proxies à l'exécution et une " +"récupération efficace des données sans instrumentation du bytecode. " + +#. Tag: para +#, no-c-format +msgid "" +"Save this file to the <filename>src/main/java/org/hibernate/tutorial/domain</" +"filename> directory." +msgstr "" +"Sauvegardez ce fichier dans le répertoire <filename>src/main/java/org/" +"hibernate/tutorial/domain</filename>." + +#. Tag: title +#, no-c-format +msgid "The mapping file" +msgstr "Le fichier de mappage" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate needs to know how to load and store objects of the persistent " +"class. This is where the Hibernate mapping file comes into play. The mapping " +"file tells Hibernate what table in the database it has to access, and what " +"columns in that table it should use." +msgstr "" +"Hibernate a besoin de savoir comment charger et stocker des objets d'une " +"classe persistante. C'est là qu'intervient le fichier de mappage Hibernate. " +"Le fichier de mappage indique à Hibernate à quelle table accéder dans la " +"base de données, et les colonnes de cette table à utiliser." + +#. Tag: para +#, no-c-format +msgid "The basic structure of a mapping file looks like this:" +msgstr "" +"La structure basique de ce fichier de mappage ressemble à ce qui suit :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate DTD is sophisticated. You can use it for auto-completion of XML " +"mapping elements and attributes in your editor or IDE. Opening up the DTD " +"file in your text editor is the easiest way to get an overview of all " +"elements and attributes, and to view the defaults, as well as some comments. " +"Hibernate will not load the DTD file from the web, but first look it up from " +"the classpath of the application. The DTD file is included in " +"<filename>hibernate-core.jar</filename> (it is also included in the " +"<filename>hibernate3.jar</filename>, if using the distribution bundle)." +msgstr "" +"Notez que la DTD Hibernate est très sophistiquée. Vous pouvez l'utiliser " +"pour l'auto-finalisation des éléments et des attributs de mappage XML dans " +"votre éditeur ou votre IDE. Ouvrez également le fichier DTD dans votre " +"éditeur de texte - c'est le moyen le plus facile d'obtenir une vue " +"d'ensemble de tous les éléments et attributs, et de voir les valeurs par " +"défaut, ainsi que quelques commentaires. Notez qu'Hibernate ne chargera pas " +"le fichier DTD à partir du web, mais regardera d'abord dans le chemin de " +"classe de l'application. Le fichier DTD est inclus dans <filename>hibernate-" +"core.jar ainsi que </filename>dans le répertoire <filename>src</filename> de " +"la distribution Hibernate)." + +#. Tag: para +#, no-c-format +msgid "" +"We will omit the DTD declaration in future examples to shorten the code. It " +"is, of course, not optional." +msgstr "" +"Nous omettrons la déclaration de la DTD dans les exemples futurs pour " +"raccourcir le code. Évidemment il n'est pas optionnel. " + +#. Tag: para +#, no-c-format +msgid "" +"Between the two <literal>hibernate-mapping</literal> tags, include a " +"<literal>class</literal> element. All persistent entity classes (again, " +"there might be dependent classes later on, which are not first-class " +"entities) need a mapping to a table in the SQL database:" +msgstr "" +"Entre les deux balises <literal>hibernate-mapping</literal>, incluez un " +"élément <literal>class</literal>. Toutes les classes d'entités persistantes " +"(encore une fois, il pourrait y avoir des classes dépendantes plus tard, qui " +"ne sont pas des entités mère) ont besoin d'un mappage vers une table de la " +"base de données SQL :" + +#. Tag: para +#, no-c-format +msgid "" +"So far we have told Hibernate how to persist and load object of class " +"<literal>Event</literal> to the table <literal>EVENTS</literal>. Each " +"instance is now represented by a row in that table. Now we can continue by " +"mapping the unique identifier property to the tables primary key. As we do " +"not want to care about handling this identifier, we configure Hibernate's " +"identifier generation strategy for a surrogate primary key column:" +msgstr "" +"Plus loin, nous indiquons à Hibernate comment persister et charger un objet " +"de la classe <literal>Event</literal> dans la table <literal>EVENTS</" +"literal>, chaque instance étant représentée par une ligne dans cette table. " +"Maintenant nous continuons avec le mappage de la propriété de l'identifiant " +"unique vers la clef primaire des tables. De plus, comme nous ne voulons pas " +"nous occuper de la gestion de cet identifiant, nous utilisons une stratégie " +"de génération d'identifiant Hibernate pour la colonne de la clé primaire " +"subrogée : " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>id</literal> element is the declaration of the identifier " +"property. The <literal>name=\"id\"</literal> mapping attribute declares the " +"name of the JavaBean property and tells Hibernate to use the <literal>getId()" +"</literal> and <literal>setId()</literal> methods to access the property. " +"The column attribute tells Hibernate which column of the <literal>EVENTS</" +"literal> table holds the primary key value." +msgstr "" +"L'élément <literal>ID</literal> est la déclaration de l'identifiant de " +"propriété. L'attribut de mappage <literal>name=\"id\"</literal> déclare le " +"nom de la propriété JavaBean et indique à Hibernate d'utiliser les méthodes " +"<literal>getId()</literal> et <literal>setId()</literal> pour accéder à la " +"propriété. L'attribut de colonne indique à Hibernate quelle colonne de la " +"table <literal>EVENTS</literal> contient la valeur de clé primaire." + +#. Tag: para +#, no-c-format +msgid "" +"The nested <literal>generator</literal> element specifies the identifier " +"generation strategy (aka how are identifier values generated?). In this case " +"we choose <literal>native</literal>, which offers a level of portability " +"depending on the configured database dialect. Hibernate supports database " +"generated, globally unique, as well as application assigned, identifiers. " +"Identifier value generation is also one of Hibernate's many extension points " +"and you can plugin in your own strategy." +msgstr "" +"L'élément imbriqué <literal>Générateur</literal> spécifie la stratégie de " +"génération d'identifiant (c'est à dire comment les valeurs d'identifiant " +"sont-elles générées?). Dans ce cas nous avons choisi <literal>native</" +"literal>, qui offre un niveau de la portabilité selon le dialecte de base de " +"données configurée. Mise en veille prolongée prend en charge la base de " +"données générée, unique au monde, ainsi que l'application affectée, les " +"identifiants. Génération de valeur d'identifiant est aussi l'un des nombreux " +"points d'extension d'Hibernate et vous pouvez plug-in votre propre stratégie." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<literal>native</literal> is no longer consider the best strategy in terms " +"of portability. for further discussion, see <xref linkend=\"portability-idgen" +"\" />" +msgstr "" +"<literal>native</literal> n'est plus considéré comme la meilleure stratégie " +"en terme de portabilité. Pour obtenir davantage d'explications, voir <xref " +"linkend=\"portability-idgen\" />" + +#. Tag: para +#, no-c-format +msgid "" +"Lastly, we need to tell Hibernate about the remaining entity class " +"properties. By default, no properties of the class are considered persistent:" +msgstr "" +"Enfin, nous incluons des déclarations pour les propriétés persistantes de la " +"classe dans le fichier de mappage. Par défaut, aucune propriété de la classe " +"n'est considérée comme persistante : " + +#. Tag: para +#, no-c-format +msgid "" +"Similar to the <literal>id</literal> element, the <literal>name</literal> " +"attribute of the <literal>property</literal> element tells Hibernate which " +"getter and setter methods to use. In this case, Hibernate will search for " +"<literal>getDate()</literal>, <literal>setDate()</literal>, <literal>getTitle" +"()</literal> and <literal>setTitle()</literal> methods." +msgstr "" +"Comme avec l'élément <literal>id</literal>, l'attribut <literal>name</" +"literal> de l'élément <literal>property</literal> indique à Hibernate " +"quelles méthodes getters/setters utiliser. Par conséquent dans ce cas, " +"Hibernate cherchera <literal>getDate()/setDate()</literal>, de même que " +"<literal>getTitle()/setTitle()</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Why does the <literal>date</literal> property mapping include the " +"<literal>column</literal> attribute, but the <literal>title</literal> does " +"not? Without the <literal>column</literal> attribute, Hibernate by default " +"uses the property name as the column name. This works for <literal>title</" +"literal>, however, <literal>date</literal> is a reserved keyword in most " +"databases so you will need to map it to a different name." +msgstr "" +"Pourquoi le mappage de la propriété <literal>date</literal> inclut-il " +"l'attribut <literal>column</literal>, mais non le <literal>title</literal> ? " +"Sans l'attribut <literal>column</literal>, Hibernate utilise par défaut le " +"nom de la propriété comme nom de colonne. Cela fonctionne bien pour " +"<literal>title</literal>. Cependant, <literal>date</literal> est un mot clé " +"réservé dans la plupart des bases de données, donc nous utilisons un nom " +"différent pour le mappage. " + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>title</literal> mapping also lacks a <literal>type</literal> " +"attribute. The types declared and used in the mapping files are not Java " +"data types; they are not SQL database types either. These types are called " +"<emphasis>Hibernate mapping types</emphasis>, converters which can translate " +"from Java to SQL data types and vice versa. Again, Hibernate will try to " +"determine the correct conversion and mapping type itself if the " +"<literal>type</literal> attribute is not present in the mapping. In some " +"cases this automatic detection using Reflection on the Java class might not " +"have the default you expect or need. This is the case with the " +"<literal>date</literal> property. Hibernate cannot know if the property, " +"which is of <literal>java.util.Date</literal>, should map to a SQL " +"<literal>date</literal>, <literal>timestamp</literal>, or <literal>time</" +"literal> column. Full date and time information is preserved by mapping the " +"property with a <literal>timestamp</literal> converter." +msgstr "" +"Il est intéressant de noter que le mappage de <literal>title</literal> " +"manque également d'un attribut <literal>type</literal>. Les types que nous " +"déclarons et utilisons dans les fichiers de mappage ne sont pas, comme vous " +"pourriez vous y attendre, des types de données Java. Ce ne sont pas, non " +"plus, des types de base de données SQL. Ces types sont donc appelés " +"<emphasis>types de mappage Hibernate</emphasis>, des convertisseurs qui " +"peuvent traduire des types Java en types SQL et vice versa. De plus, " +"Hibernate tentera de déterminer la bonne conversion et le type de mappage " +"lui-même si l'attribut <literal>type</literal> n'est pas présent dans le " +"mappage. Dans certains cas, cette détection automatique (utilisant la " +"réflexion sur la classe Java) pourrait ne pas donner la valeur attendue ou " +"dont vous avez besoin. C'est le cas avec la propriété <literal>date</" +"literal>. Hibernate ne peut pas savoir si la propriété \"mappera\" une " +"colonne SQL de type <literal>date</literal>, <literal>timestamp</literal> ou " +"<literal>time</literal>. Nous déclarons que nous voulons conserver des " +"informations avec une date complète et l'heure en mappant la propriété avec " +"un convertisseur <literal>timestamp</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate makes this mapping type determination using reflection when the " +"mapping files are processed. This can take time and resources, so if startup " +"performance is important you should consider explicitly defining the type to " +"use." +msgstr "" +"Hibernate rend cette détermination de type de mappage en utilisant la " +"réflection au moment du traitement des fichiers de mappage. Cela prend du " +"temps et consomme des ressources, donc, si la performance de démarrage est " +"importante, vous devriez considérer définir explicitement quel type utiliser." + +#. Tag: para +#, no-c-format +msgid "" +"Save this mapping file as <filename>src/main/resources/org/hibernate/" +"tutorial/domain/Event.hbm.xml</filename>." +msgstr "" +"Sauvegardez ce fichier de mappage ainsi <filename>src/main/resources/org/" +"hibernate/tutorial/domain/Event.hbm.xml</filename>." + +#. Tag: title +#, no-c-format +msgid "Hibernate configuration" +msgstr "Configuration d'Hibernate" + +#. Tag: para +#, no-c-format +msgid "" +"At this point, you should have the persistent class and its mapping file in " +"place. It is now time to configure Hibernate. First let's set up HSQLDB to " +"run in \"server mode\"" +msgstr "" +"A ce niveau là, vous devriez avoir la classe persistante et son fichier de " +"mappage en place. Il est temps maintenant de configurer Hibernate. Tout " +"d'abord, il nous faut configurer HSQLDB pour qu'il puisse exécuter en " +"\"server mode\"" + +#. Tag: para +#, fuzzy, no-c-format +msgid "We do this do that the data remains between runs." +msgstr "xxx" + +#. Tag: para +#, no-c-format +msgid "" +"We will utilize the Maven exec plugin to launch the HSQLDB server by " +"running: <command> mvn exec:java -Dexec.mainClass=\"org.hsqldb.Server\" -" +"Dexec.args=\"-database.0 file:target/data/tutorial\"</command> You will see " +"it start up and bind to a TCP/IP socket; this is where our application will " +"connect later. If you want to start with a fresh database during this " +"tutorial, shutdown HSQLDB, delete all files in the <filename>target/data</" +"filename> directory, and start HSQLDB again." +msgstr "" +"Vous utiliserez le lugin exec Maven pour lancer le serveur HSQLDB en " +"exécutant : <command> mvn exec:java -Dexec.mainClass=\"org.hsqldb.Server\" -" +"Dexec.args=\"-database.0 file:target/data/tutorial\"</command>. Vous " +"observez qu'elle démarre et ouvre un socket TCP/IP, c'est là que notre " +"application se connectera plus tard. Si vous souhaitez démarrez à partir " +"d'une nouvelle base de données pour ce tutoriel (choisissez <literal>CTRL + " +"C</literal> dans la fenêtre), effacez tous les fichiers dans le répertoire " +"<filename>target/data</filename> et redémarrez HSQL DB." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate will be connecting to the database on behalf of your application, " +"so it needs to know how to obtain connections. For this tutorial we will be " +"using a standalone connection pool (as opposed to a <interfacename>javax.sql." +"DataSource</interfacename>). Hibernate comes with support for two third-" +"party open source JDBC connection pools: <ulink url=\"https://sourceforge." +"net/projects/c3p0\">c3p0</ulink> and <ulink url=\"http://proxool.sourceforge." +"net/\">proxool</ulink>. However, we will be using the Hibernate built-in " +"connection pool for this tutorial." +msgstr "" +"Hibernate se connectera à la base de données pour le compte de votre " +"application, donc il devra savoir comment obtenir des connexions. Pour ce " +"tutoriel, nous devrons utliser un pool de connexions autonomes (et non pas " +"<interfacename>javax.sql.DataSource</interfacename>). Hibernate bénéficie du " +"support de deux pools de connexions JDBC open source de tierce partie : " +"<ulink url=\"https://sourceforge.net/projects/c3p0\">c3p0</ulink... and <ulink " +"url=\"http://proxool.sourceforge.net/\">proxool</ulink>. Cependant, nous " +"utiliserons le pool de connexions intégré Hibernate pour ce tutoriel." + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"The built-in Hibernate connection pool is in no way intended for production " +"use. It lacks several features found on any decent connection pool." +msgstr "" +"Le pool de connexions intégré Hibernate n'est pas conçu pour les " +"environnements de production." + +#. Tag: para +#, no-c-format +msgid "" +"For Hibernate's configuration, we can use a simple <literal>hibernate." +"properties</literal> file, a more sophisticated <literal>hibernate.cfg.xml</" +"literal> file, or even complete programmatic setup. Most users prefer the " +"XML configuration file:" +msgstr "" +"Pour la configuration de Hibernate, nous pouvons utiliser un simple fichier " +"<literal>hibernate.properties</literal>, un fichier <literal>hibernate.cfg." +"xml</literal> légèrement plus sophistiqué, ou même une configuration " +"complète par programmation. La plupart des utilisateurs préfèrent le fichier " +"de configuration XML : " + +#. Tag: para +#, no-c-format +msgid "Notice that this configuration file specifies a different DTD" +msgstr "" +"Vous pourrez remarquer que cette configuration XML utilise une DTD " +"différente." + +#. Tag: para +#, no-c-format +msgid "" +"You configure Hibernate's <literal>SessionFactory</literal>. SessionFactory " +"is a global factory responsible for a particular database. If you have " +"several databases, for easier startup you should use several <literal>&lt;" +"session-factory&gt;</literal> configurations in several configuration files." +msgstr "" +"Nous configurons une <literal>SessionFactory</literal> de Hibernate - une " +"fabrique globale responsable d'une base de données particulière. Si vous " +"avez plusieurs base de données, utilisez plusieurs configurations " +"<literal>&lt;session-factory&gt;</literal>, généralement dans des fichiers " +"de configuration différents (pour un démarrage plus facile)." + +#. Tag: para +#, no-c-format +msgid "" +"The first four <literal>property</literal> elements contain the necessary " +"configuration for the JDBC connection. The dialect <literal>property</" +"literal> element specifies the particular SQL variant Hibernate generates." +msgstr "" +"Les quatre premiers éléments <literal>property</literal> contiennent la " +"configuration nécessaire pour la connexion JDBC. L'élément " +"<literal>property</literal> du dialecte spécifie quelle variante du SQL " +"Hibernate va générer. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"In most cases, Hibernate is able to properly determine which dialect to use. " +"See <xref linkend=\"portability-dialectresolver\" /> for more information." +msgstr "" +"Hibernate est capable de déterminer correctement quel dialecte utiliser dans " +"la plupart des cas. Voir <xref linkend=\"portability-dialectresolver\" /> " +"pour obtenir davantage d'informations. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate's automatic session management for persistence contexts is " +"particularly useful in this context. The <literal>hbm2ddl.auto</literal> " +"option turns on automatic generation of database schemas directly into the " +"database. This can also be turned off by removing the configuration option, " +"or redirected to a file with the help of the <literal>SchemaExport</literal> " +"Ant task. Finally, add the mapping file(s) for persistent classes to the " +"configuration." +msgstr "" +"La gestion automatique des sessions d'Hibernate pour les contextes de " +"persistance est bien pratique, comme vous pourrez le constater. L'option " +"<literal>hbm2ddl.auto</literal> active la génération automatique des schémas " +"de base de données - directement dans la base de données. Cela peut " +"également être désactivé (en supprimant l'option de configuration) ou " +"redirigé vers un fichier avec l'aide de la tâche Ant <literal>SchemaExport</" +"literal>. Finalement, nous ajoutons le(s) fichier(s) de mappage pour les " +"classes persistantes." + +#. Tag: para +#, no-c-format +msgid "" +"Save this file as <filename>hibernate.cfg.xml</filename> into the " +"<filename>src/main/resources</filename> directory." +msgstr "" +"Sauvegarder ce fichier en tant que <filename>hibernate.cfg.xml</filename> " +"dans le répertoire <filename>src/main/resources</filename>." + +#. Tag: title +#, no-c-format +msgid "Building with Maven" +msgstr "Construction avec Maven" + +#. Tag: para +#, no-c-format +msgid "" +"We will now build the tutorial with Maven. You will need to have Maven " +"installed; it is available from the <ulink url=\"http://maven.apache.org/" +"download.html\">Maven download page</ulink>. Maven will read the <filename>/" +"pom.xml</filename> file we created earlier and know how to perform some " +"basic project tasks. First, lets run the <literal>compile</literal> goal to " +"make sure we can compile everything so far:" +msgstr "" +"Nous allons maintenant construire le tutoriel avec Maven. Vous aurez besoin " +"d'installer Maven pour cela. Il est disponible dans la page <ulink url=" +"\"http://maven.apache.org/download.html\">Maven download page</ulink>. Maven " +"pourra lire le fichier <filename>/pom.xml</filename> que nous avons créé " +"plus tôt et saura comment effectuer quelques tâches du projet de base. Tout " +"d'abord, exécutons <literal>compile</literal> pour s'assurer que nous " +"pouvons tout compiler jusqu'à maintenant :" + +#. Tag: title +#, no-c-format +msgid "Startup and helpers" +msgstr "Démarrage et aides" + +#. Tag: para +#, no-c-format +msgid "" +"It is time to load and store some <literal>Event</literal> objects, but " +"first you have to complete the setup with some infrastructure code. You have " +"to startup Hibernate by building a global <interfacename>org.hibernate." +"SessionFactory</interfacename> object and storing it somewhere for easy " +"access in application code. A <interfacename>org.hibernate.SessionFactory</" +"interfacename> is used to obtain <interfacename>org.hibernate.Session</" +"interfacename> instances. A <interfacename>org.hibernate.Session</" +"interfacename> represents a single-threaded unit of work. The " +"<interfacename>org.hibernate.SessionFactory</interfacename> is a thread-safe " +"global object that is instantiated once." +msgstr "" +"Il est temps de charger et de stocker quelques objets <literal>Event</" +"literal>, mais d'abord nous devons compléter la configuration avec du code " +"d'infrastructure. Nous devons démarrer Hibernate. Ce démarrage inclut la " +"construction d'un objet <literal>SessionFactory</literal> global et le " +"stocker dans un lieu facile d'accès dans le code de l'application. Une " +"<literal>SessionFactory</literal> peut ouvrir de nouvelles <literal>Session</" +"literal>s. Une <literal>Session</literal> représente une unité de travail " +"simplement \"threadée\". La <interfacename>org.hibernate.SessionFactory</" +"interfacename> est un objet global \"thread-safe\", instancié une seule fois." + +#. Tag: para +#, no-c-format +msgid "" +"We will create a <literal>HibernateUtil</literal> helper class that takes " +"care of startup and makes accessing the <interfacename>org.hibernate." +"SessionFactory</interfacename> more convenient." +msgstr "" +"Nous créerons une classe d'aide <literal>HibernateUtil</literal> qui " +"s'occupe du démarrage et rend la gestion des <interfacename>org.hibernate." +"SessionFactory</interfacename> plus facile. " + +#. Tag: para +#, no-c-format +msgid "" +"Save this code as <filename>src/main/java/org/hibernate/tutorial/util/" +"HibernateUtil.java</filename>" +msgstr "" +"Sauvegardez ce code en tant que <filename>src/main/java/org/hibernate/" +"tutorial/util/HibernateUtil.java</filename>" + +#. Tag: para +#, no-c-format +msgid "" +"This class not only produces the global <interfacename>org.hibernate." +"SessionFactory</interfacename> reference in its static initializer; it also " +"hides the fact that it uses a static singleton. We might just as well have " +"looked up the <interfacename>org.hibernate.SessionFactory</interfacename> " +"reference from JNDI in an application server or any other location for that " +"matter." +msgstr "" +"Cette classe ne produit pas seulement la <interfacename>org.hibernate." +"SessionFactory</interfacename> globale dans un initialiseur statique. Elle " +"masque le fait qu'elle exploite un singleton statique. Nous aurions pu aussi " +"bien vérouiller la référence <interfacename>org.hibernate.SessionFactory</" +"interfacename> à partir de JNDI dans un serveur d'application ou dans " +"n'importe quelle location en fait. Elle pourrait aussi obtenir la " +"<literal>SessionFactory</literal> depuis JNDI dans un serveur d'applications." + +#. Tag: para +#, no-c-format +msgid "" +"If you give the <interfacename>org.hibernate.SessionFactory</interfacename> " +"a name in your configuration, Hibernate will try to bind it to JNDI under " +"that name after it has been built. Another, better option is to use a JMX " +"deployment and let the JMX-capable container instantiate and bind a " +"<literal>HibernateService</literal> to JNDI. Such advanced options are " +"discussed later." +msgstr "" +"Si vous nommez <interfacename>org.hibernate.SessionFactory</interfacename> " +"dans votre fichier de configuration, Hibernate tentera la récupération " +"depuis JNDI. Pour éviter ce code, vous pouvez aussi utiliser un déploiement " +"JMX et laisser le conteneur (compatible JMX) instancier et lier un " +"<literal>HibernateService</literal> à JNDI. Ces options avancées sont " +"expliquées plus loin." + +#. Tag: para +#, no-c-format +msgid "" +"You now need to configure a logging system. Hibernate uses commons logging " +"and provides two choices: Log4j and JDK 1.4 logging. Most developers prefer " +"Log4j: copy <literal>log4j.properties</literal> from the Hibernate " +"distribution in the <literal>etc/</literal> directory to your <literal>src</" +"literal> directory, next to <literal>hibernate.cfg.xml</literal>. If you " +"prefer to have more verbose output than that provided in the example " +"configuration, you can change the settings. By default, only the Hibernate " +"startup message is shown on stdout." +msgstr "" +"Nous avons finalement besoin de configurer le système de journalisation - " +"Hibernate utilise commons-logging et vous laisse le choix entre log4j et le " +"système de logs du JDK 1.4. La plupart des développeurs préfèrent log4j : " +"copiez <literal>log4j.properties</literal> de la distribution de Hibernate " +"(il est dans le répertoire <literal>etc/</literal>) dans votre répertoire " +"<literal>src</literal>, puis faîtes de même avec <literal>hibernate.cfg.xml</" +"literal>. Regardez la configuration d'exemple et changez les paramètres si " +"vous voulez une sortie plus verbeuse. Par défaut, seul le message de " +"démarrage de Hibernate est affiché sur la sortie standard." + +#. Tag: para +#, no-c-format +msgid "" +"The tutorial infrastructure is complete and you are now ready to do some " +"real work with Hibernate." +msgstr "" +"L'infrastructure de ce toturiel est complète - et nous sommes prêts à " +"effectuer un travail réel avec Hibernate. " + +#. Tag: title +#, no-c-format +msgid "Loading and storing objects" +msgstr "Charger et stocker des objets" + +#. Tag: para +#, no-c-format +msgid "" +"We are now ready to start doing some real worjk with Hibernate. Let's start " +"by writing an <literal>EventManager</literal> class with a <literal>main()</" +"literal> method:" +msgstr "" +"Enfin nous pouvons utiliser Hibernate pour charger et stocker des objets. " +"Nous écrivons une classe <literal>EventManager</literal> avec une méthode " +"<literal>main()</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"In <literal>createAndStoreEvent()</literal> we created a new <literal>Event</" +"literal> object and handed it over to Hibernate. At that point, Hibernate " +"takes care of the SQL and executes an <literal>INSERT</literal> on the " +"database." +msgstr "" +"Nous créons un nouvel objet <literal>Event</literal> dans " +"<literal>createAndStoreEvent()</literal>, et nous le remettons à Hibernate, " +"qui s'occupe maintenant du SQL et exécute les <literal>INSERT</literal> s " +"dans la base de données." + +#. Tag: para +#, no-c-format +msgid "" +"A <interface>org.hibernate.Session</interface> is designed to represent a " +"single unit of work (a single atmoic piece of work to be performed). For now " +"we will keep things simple and assume a one-to-one granularity between a " +"Hibernate <interface>org.hibernate.Session</interface> and a database " +"transaction. To shield our code from the actual underlying transaction " +"system we use the Hibernate <interfacename>org.hibernate.Transaction</" +"interfacename> API. In this particular case we are using JDBC-based " +"transactional semantics, but it could also run with JTA." +msgstr "" +"Une <interface>org.hibernate.Session</interface> est une unité de travail " +"unique (une unité atmoic simple). Pour le moment, nous allons faire les " +"choses simplement et présumer une granularité un-à-un entre une " +"<literal>Session</literal> Hibernate et une transaction de la base de " +"données. Pour isoler notre code du système de transaction sous-jacent, nous " +"utilisons l'API <interfacename>org.hibernate.Transaction</interfacename> " +"Hibernate. Dans notre cas, nous utilisons du pur JDBC, mais on aurait pu " +"utiliser JTA." + +#. Tag: para +#, no-c-format +msgid "" +"What does <literal>sessionFactory.getCurrentSession()</literal> do? First, " +"you can call it as many times and anywhere you like once you get hold of " +"your <interfacename>org.hibernate.SessionFactory</interfacename>. The " +"<literal>getCurrentSession()</literal> method always returns the \"current\" " +"unit of work. Remember that we switched the configuration option for this " +"mechanism to \"thread\" in our <filename>src/main/resources/hibernate.cfg." +"xml</filename>? Due to that setting, the context of a current unit of work " +"is bound to the current Java thread that executes the application." +msgstr "" +"Quelle est la fonction de <literal>sessionFactory.getCurrentSession()</" +"literal> ? Premièrement, vous pouvez l'invoquer autant de fois que vous le " +"voulez et n'importe où, du moment que vous avez votre " +"<literal>SessionFactory</literal> (facile grâce à <literal>HibernateUtil</" +"literal>). La méthode <literal>getCurrentSession()</literal> renvoie " +"toujours l'unité de travail courante. Souvenez vous que nous avons basculé " +"notre option de configuration au mécanisme basé sur le \"thread\" dans " +"<literal>hibernate.cfg.xml</literal>. Par conséquent, l'unité de travail " +"courante est liée au thread Java courant qui exécute notre application." + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate offers three methods of current session tracking. The \"thread\" " +"based method is not intended for production use; it is merely useful for " +"prototyping and tutorials such as this one. Current session tracking is " +"discussed in more detail later on." +msgstr "" +"Hibernate offre trois méthodes le suivi de session courant. La méthode basée " +"\"thread\" qui n'est pas conçue pour une utilisation de la production ; " +"seulement utile pour les prototypes et des tutoriels comme celui-ci. Le " +"suivi de session courant est abordé plus en détail par la suite." + +#. Tag: para +#, no-c-format +msgid "" +"A <interface>org.hibernate.Session</interface> begins when the first call to " +"<literal>getCurrentSession()</literal> is made for the current thread. It is " +"then bound by Hibernate to the current thread. When the transaction ends, " +"either through commit or rollback, Hibernate automatically unbinds the " +"<interface>org.hibernate.Session</interface> from the thread and closes it " +"for you. If you call <literal>getCurrentSession()</literal> again, you get a " +"new <interface>org.hibernate.Session</interface> and can start a new unit of " +"work." +msgstr "" +"Une <interface>org.hibernate.Session</interface> commence lorsque le thread " +"courant commence à appeler <literal>getCurrentSession()</literal>. Ensuite, " +"elle est attachée par Hibernate au thread courant. Lorsque la transaction " +"s'achève, par commit ou par rollback, Hibernate détache automatiquement la " +"<literal>Session</literal> du thread et la ferme pour vous. Si vous invoquez " +"<literal>getCurrentSession()</literal> une nouvelle fois, vous obtenez une " +"nouvelle <literal>Session</literal> et pouvez entamer une nouvelle unité de " +"travail. " + +#. Tag: para +#, no-c-format +msgid "" +"Related to the unit of work scope, should the Hibernate <interface>org." +"hibernate.Session</interface> be used to execute one or several database " +"operations? The above example uses one <interface>org.hibernate.Session</" +"interface> for one operation. However this is pure coincidence; the example " +"is just not complex enough to show any other approach. The scope of a " +"Hibernate <interface>org.hibernate.Session</interface> is flexible but you " +"should never design your application to use a new Hibernate <interface>org." +"hibernate.Session</interface> for <emphasis>every</emphasis> database " +"operation. Even though it is used in the following examples, consider " +"<emphasis>session-per-operation</emphasis> an anti-pattern. A real web " +"application is shown later in the tutorial which will help illustrate this." +msgstr "" +"A propos de la portée de l'unité de travail, la session <interface>org." +"hibernate.Session</interface> Hibernate devrait-elle être utilisée pour " +"exécuter une ou plusieurs opérations en base de données ? L'exemple ci-" +"dessus utilise une <literal>Session</literal> pour une opération. C'est une " +"pure coïncidence, l'exemple n'est pas assez complexe pour montrer d'autres " +"approches. La portée d'une <literal>Session</literal> Hibernate est flexible " +"mais vous ne devriez jamais concevoir votre application de manière à " +"utiliser une nouvelle <literal>Session</literal> Hibernate pour " +"<emphasis>chaque</emphasis> opération en base de données. Donc même si vous " +"le voyez quelquefois dans les exemples suivants, considérez <emphasis>une " +"session par opération</emphasis> comme un anti-modèle. Une véritable " +"application (web) est affichée plus loin dans ce tutoriel. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"See <xref linkend=\"transactions\" /> for more information about transaction " +"handling and demarcation. The previous example also skipped any error " +"handling and rollback." +msgstr "" +"Consultez <xref linkend=\"transactions\" /> pour plus d'informations sur la " +"gestion des transactions et leur démarcation. Nous n'avons pas géré les " +"erreurs et rollback dans l'exemple précédent." + +#. Tag: para +#, no-c-format +msgid "" +"To run this, we will make use of the Maven exec plugin to call our class " +"with the necessary classpath setup: <command>mvn exec:java -Dexec.mainClass=" +"\"org.hibernate.tutorial.EventManager\" -Dexec.args=\"store\"</command>" +msgstr "" +"Pour pouvoir exécuter ceci, nous utiliserons le plugin exec Maven pour " +"appeler notre classe avec la configuration de classpath qui convient : " +"<command>mvn exec:java -Dexec.mainClass=\"org.hibernate.tutorial.EventManager" +"\" -Dexec.args=\"store\"</command>" + +#. Tag: para +#, no-c-format +msgid "You may need to perform <command>mvn compile</command> first." +msgstr "" +"Vous aurez sans doute besoin d'effectuer <command>mvn compile</command> pour " +"commencer." + +#. Tag: para +#, no-c-format +msgid "" +"You should see Hibernate starting up and, depending on your configuration, " +"lots of log output. Towards the end, the following line will be displayed:" +msgstr "" +"Vous devriez constater qu'Hibernate démarre et selon votre configuration, " +"beaucoup de traces sur la sortie. À la fin, vous trouverez la ligne " +"suivante :" + +#. Tag: para +#, no-c-format +msgid "This is the <literal>INSERT</literal> executed by Hibernate." +msgstr "C'est l' <literal>INSERT</literal> exécutée par Hibernate." + +#. Tag: para +#, no-c-format +msgid "To list stored events an option is added to the main method:" +msgstr "" +"Maintenant nous aimerions aussi lister les événements stockés, donc nous " +"ajoutons une option à la méthode principale : " + +#. Tag: para +#, no-c-format +msgid "A new <literal>listEvents() method is also added</literal>:" +msgstr "" +"Nous ajoutons aussi une nouvelle méthode <literal>listEvents()</literal> : " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Here, we are using a Hibernate Query Language (HQL) query to load all " +"existing <literal>Event</literal> objects from the database. Hibernate will " +"generate the appropriate SQL, send it to the database and populate " +"<literal>Event</literal> objects with the data. You can create more complex " +"queries with HQL. See <xref linkend=\"queryhql\" /> for more information." +msgstr "" +"Ici nous utilisons une requête HQL (Hibernate Query Language) pour charger " +"tous les objets <literal>Event</literal> existants de la base de données. " +"Hibernate générera le SQL approprié, l'enverra à la base de données et " +"peuplera des objets <literal>Event</literal> avec les données. Vous pouvez " +"évidemment créer des requêtes plus complexes avec HQL. Voir <xref linkend=" +"\"queryhql\" /> pour obtenir davantage d'informations." + +#. Tag: para +#, no-c-format +msgid "" +"Now we can call our new functionality, again using the Maven exec plugin: " +"<command>mvn exec:java -Dexec.mainClass=\"org.hibernate.tutorial.EventManager" +"\" -Dexec.args=\"list\"</command>" +msgstr "" +"Nous pouvons maintenant appeler notre nouvelle fonctionnalité, en utilisant " +"à nouveau le plugin exec Maven : <command>mvn exec:java -Dexec.mainClass=" +"\"org.hibernate.tutorial.EventManager\" -Dexec.args=\"list\"</command>" + +#. Tag: title +#, no-c-format +msgid "Part 2 - Mapping associations" +msgstr "Section 2 - Mapper des associations" + +#. Tag: para +#, no-c-format +msgid "" +"So far we have mapped a single persistent entity class to a table in " +"isolation. Let's expand on that a bit and add some class associations. We " +"will add people to the application and store a list of events in which they " +"participate." +msgstr "" +"Pour l'instant, nous nous sommes contentés de mapper une classe d'une entité " +"persistante vers une table. Profitons-en pour ajouter quelques associations " +"de classe. D'abord nous ajouterons des gens à notre application, et " +"stockerons une liste d'événements auxquels ils participent." + +#. Tag: title +#, no-c-format +msgid "Mapping the Person class" +msgstr "Mapper la classe Person" + +#. Tag: para +#, no-c-format +msgid "The first cut of the <literal>Person</literal> class looks like this:" +msgstr "" +"La première version de la classe <literal>Person</literal> est simple : " + +#. Tag: para +#, no-c-format +msgid "" +"Save this to a file named <filename>src/main/java/org/hibernate/tutorial/" +"domain/Person.java</filename>" +msgstr "" +"A sauvegarder dans le fichier nommé <filename>src/main/java/org/hibernate/" +"tutorial/domain/Person.java</filename>" + +#. Tag: para +#, no-c-format +msgid "" +"Next, create the new mapping file as <filename>src/main/resources/org/" +"hibernate/tutorial/domain/Person.hbm.xml</filename>" +msgstr "" +"Puis, créez le nouveau fichier de mappage <filename>src/main/resources/org/" +"hibernate/tutorial/domain/Person.hbm.xml</filename>" + +#. Tag: para +#, no-c-format +msgid "Finally, add the new mapping to Hibernate's configuration:" +msgstr "" +"Finalement, ajoutez le nouveau mappage à la configuration d'Hibernate :" + +#. Tag: para +#, no-c-format +msgid "" +"Create an association between these two entities. Persons can participate in " +"events, and events have participants. The design questions you have to deal " +"with are: directionality, multiplicity, and collection behavior." +msgstr "" +"Nous allons maintenant créer une association entre ces deux entités. " +"Évidemment, des personnes peuvent participer aux événements, et des " +"événements ont des participants. Les questions de conception que nous devons " +"traiter sont : direction, cardinalité et comportement de la collection. " + +#. Tag: title +#, no-c-format +msgid "A unidirectional Set-based association" +msgstr "Une association unidirectionnelle basée sur Set" + +#. Tag: para +#, no-c-format +msgid "" +"By adding a collection of events to the <literal>Person</literal> class, you " +"can easily navigate to the events for a particular person, without executing " +"an explicit query - by calling <literal>Person#getEvents</literal>. Multi-" +"valued associations are represented in Hibernate by one of the Java " +"Collection Framework contracts; here we choose a <interfacename>java.util." +"Set</interfacename> because the collection will not contain duplicate " +"elements and the ordering is not relevant to our examples:" +msgstr "" +"Nous allons ajouter une collection d'événements à la classe <literal>Person</" +"literal>. De cette manière nous pouvons facilement naviguer dans les " +"événements d'une personne particulière, sans exécuter une requête explicite " +"- en appelant <literal>aPerson.getEvents()</literal>. Nous utilisons une " +"collection Java, un <literal>Set</literal>, parce que la collection ne " +"contiendra pas d'éléments dupliqués et l'ordre ne nous importe pas pour ces " +"exemples :" + +#. Tag: para +#, no-c-format +msgid "" +"Before mapping this association, let's consider the other side. We could " +"just keep this unidirectional or create another collection on the " +"<literal>Event</literal>, if we wanted to be able to navigate it from both " +"directions. This is not necessary, from a functional perspective. You can " +"always execute an explicit query to retrieve the participants for a " +"particular event. This is a design choice left to you, but what is clear " +"from this discussion is the multiplicity of the association: \"many\" valued " +"on both sides is called a <emphasis>many-to-many</emphasis> association. " +"Hence, we use Hibernate's many-to-many mapping:" +msgstr "" +"D'abord nous mappons cette association, mais pensez à l'autre côté. " +"Clairement, nous pouvons la laisser unidirectionnelle. Ou bien, nous " +"pourrions créer une autre collection sur <literal>Event</literal>, si nous " +"voulons être capable de la parcourir de manière bidirectionnelle. Ce n'est " +"pas nécessaire d'un point de vue fonctionnel. Vous pourrez toujours exécuter " +"une requête explicite pour récupérer les participants d'un évènement " +"particulier. Vous êtes libre de choisir la conception, ce qui est certain, " +"c'est que la cardinalité de l'association : \"plusieurs\" valués des deux " +"côtés, est appelée <emphasis>plusieurs-à-plusieurs</emphasis>. Par " +"conséquent nous utilisons un mappage Hibernate plusieurs-à-plusieurs :" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate supports a broad range of collection mappings, a <literal>set</" +"literal> being most common. For a many-to-many association, or <emphasis>n:" +"m</emphasis> entity relationship, an association table is required. Each row " +"in this table represents a link between a person and an event. The table " +"name is decalred using the <literal>table</literal> attribute of the " +"<literal>set</literal> element. The identifier column name in the " +"association, for the person side, is defined with the <literal>key</literal> " +"element, the column name for the event's side with the <literal>column</" +"literal> attribute of the <literal>many-to-many</literal>. You also have to " +"tell Hibernate the class of the objects in your collection (the class on the " +"other side of the collection of references)." +msgstr "" +"Hibernate supporte toutes sortes de mappage de collection, un <literal>set</" +"literal> étant le plus commun. Pour une association plusieurs-à-plusieurs " +"(ou une relation d'entité <emphasis>n:m</emphasis>), une table d'association " +"est requise. Chaque ligne dans cette table représente un lien entre une " +"personne et un événement. Le nom de la table est configuré avec l'attribut " +"<literal>table</literal> de l'élément <literal>set</literal>. Le nom de la " +"colonne identifiant dans l'association, du côté de la personne, est défini " +"avec l'élément <literal>key</literal>, et le nom de la colonne pour " +"l'événement avec l'attribut <literal>column</literal> de <literal>many-to-" +"many</literal>. Vous devez aussi donner à Hibernate la classe des objets de " +"votre collection (c'est-à-dire : la classe de l'autre côté de la collection)." + +#. Tag: para +#, no-c-format +msgid "The database schema for this mapping is therefore:" +msgstr "Le schéma de base de données pour ce mappage est donc :" + +#. Tag: title +#, no-c-format +msgid "Working the association" +msgstr "Travailler avec l'association" + +#. Tag: para +#, no-c-format +msgid "" +"Now we will bring some people and events together in a new method in " +"<literal>EventManager</literal>:" +msgstr "" +"Réunissons quelques personnes et quelques événements dans une nouvelle " +"méthode dans <literal>EventManager</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"After loading a <literal>Person</literal> and an <literal>Event</literal>, " +"simply modify the collection using the normal collection methods. There is " +"no explicit call to <literal>update()</literal> or <literal>save()</" +"literal>; Hibernate automatically detects that the collection has been " +"modified and needs to be updated. This is called <emphasis>automatic dirty " +"checking</emphasis>. You can also try it by modifying the name or the date " +"property of any of your objects. As long as they are in " +"<emphasis>persistent</emphasis> state, that is, bound to a particular " +"Hibernate <interfacename>org.hibernate.Session</interfacename>, Hibernate " +"monitors any changes and executes SQL in a write-behind fashion. The process " +"of synchronizing the memory state with the database, usually only at the end " +"of a unit of work, is called <emphasis>flushing</emphasis>. In our code, the " +"unit of work ends with a commit, or rollback, of the database transaction." +msgstr "" +"Après le chargement d'une <literal>Person</literal> et d'un <literal>Event</" +"literal>, modifiez simplement la collection en utilisant les méthodes " +"normales de la collection. Comme vous pouvez le constater, il n'y a pas " +"d'appel explicite à <literal>update()</literal> ou <literal>save()</" +"literal>, Hibernate détecte automatiquement que la collection a été modifiée " +"et a besoin d'être mise à jour. Ceci est appelé <emphasis>la vérification " +"sale automatique</emphasis> (automatic dirty checking), et vous pouvez aussi " +"l'essayer en modifiant le nom ou la propriété date de n'importe lequel de " +"vos objets. Tant qu'ils sont dans un état <emphasis>persistant</emphasis>, " +"c'est-à-dire, liés à une <literal>Session</literal> Hibernate particulière " +"(c-à-d qu'ils ont juste été chargés ou sauvegardés dans une unité de " +"travail), Hibernate surveille les changements et exécute le SQL " +"correspondants. Le processus de synchronisation de l'état de la mémoire avec " +"la base de données, généralement seulement à la fin d'une unité de travail, " +"est appelé <emphasis>flushing</emphasis>. Dans notre code, l'unité de " +"travail s'achève par un commit (ou rollback) de la transaction avec la base " +"de données." + +#. Tag: para +#, no-c-format +msgid "" +"You can load person and event in different units of work. Or you can modify " +"an object outside of a <interfacename>org.hibernate.Session</interfacename>, " +"when it is not in persistent state (if it was persistent before, this state " +"is called <emphasis>detached</emphasis>). You can even modify a collection " +"when it is detached:" +msgstr "" +"Vous pourriez bien sûr charger une personne et un événement dans différentes " +"unités de travail. Ou vous modifiez un objet à l'extérieur d'une " +"<literal>Session</literal>, s'il n'est pas dans un état persistant (s'il " +"était persistant avant, nous appelons cet état <emphasis>détaché</" +"emphasis>). Vous pouvez même modifier une collection lorsqu'elle est " +"détachée :" + +#. Tag: para +#, no-c-format +msgid "" +"The call to <literal>update</literal> makes a detached object persistent " +"again by binding it to a new unit of work, so any modifications you made to " +"it while detached can be saved to the database. This includes any " +"modifications (additions/deletions) you made to a collection of that entity " +"object." +msgstr "" +"L'appel à <literal>update</literal> rend un objet détaché à nouveau " +"persistant, vous pourriez dire qu'il le lie à une nouvelle unité de travail, " +"ainsi toutes les modifications que vous avez faites pendant qu'il était " +"détaché peuvent être sauvegardées dans la base de données, cela inclut toute " +"modification effectuées sur une collection de cet objet entité." + +#. Tag: para +#, no-c-format +msgid "" +"This is not much use in our example, but it is an important concept you can " +"incorporate into your own application. Complete this exercise by adding a " +"new action to the main method of the <literal>EventManager</literal> and " +"call it from the command line. If you need the identifiers of a person and " +"an event - the <literal>save()</literal> method returns it (you might have " +"to modify some of the previous methods to return that identifier):" +msgstr "" +"Cela n'a pas grand intérêt dans notre situation, mais c'est un concept " +"important qu'il vous faut concevoir dans votre application. Pour le moment, " +"complétez cet exercice en ajoutant une nouvelle action à la méthode " +"principale de l'<literal>EventManager</literal> et invoquez-la depuis la " +"ligne de commande. Si vous avez besoin des identifiants d'un client et d'un " +"évènement - la méthode <literal>save()</literal> vous les retourne (vous " +"devrez peut-être modifier certaines méthodes précédentes pour retourner ces " +"identifiants) :" + +#. Tag: para +#, no-c-format +msgid "" +"This is an example of an association between two equally important classes : " +"two entities. As mentioned earlier, there are other classes and types in a " +"typical model, usually \"less important\". Some you have already seen, like " +"an <literal>int</literal> or a <classname>java.lang.String</classname>. We " +"call these classes <emphasis>value types</emphasis>, and their instances " +"<emphasis>depend</emphasis> on a particular entity. Instances of these types " +"do not have their own identity, nor are they shared between entities. Two " +"persons do not reference the same <literal>firstname</literal> object, even " +"if they have the same first name. Value types cannot only be found in the " +"JDK , but you can also write dependent classes yourself such as an " +"<literal>Address</literal> or <literal>MonetaryAmount</literal> class. In " +"fact, in a Hibernate application all JDK classes are considered value types." +msgstr "" +"C'était un exemple d'une association entre deux classes de même importance, " +"deux entités. Comme mentionné plus tôt, il y a d'autres classes et d'autres " +"types dans un modèle typique, généralement \"moins importants\". Vous en " +"avez déjà vu certains, comme un <literal>int</literal> ou une " +"<literal>String</literal>. Nous appelons ces classes des <emphasis>types de " +"valeur</emphasis>, et leurs instances <emphasis>dépendent</emphasis> d'une " +"entité particulière. Des instances de ces types n'ont pas leur propre " +"identité, elles ne sont pas non plus partagées entre des entités (deux " +"personnes ne référencent pas le même objet <literal>firstname</literal>, " +"même si elles ont le même prénom). Bien sûr, des types de valeur n'existent " +"pas seulement dans le JDK (en fait, dans une application Hibernate toutes " +"les classes du JDK sont considérées comme des types de valeur), vous pouvez " +"aussi écrire vous-même des classes dépendantes, <literal>Address</literal> " +"ou <literal>MonetaryAmount</literal>, par exemple. " + +#. Tag: para +#, no-c-format +msgid "" +"You can also design a collection of value types. This is conceptually " +"different from a collection of references to other entities, but looks " +"almost the same in Java." +msgstr "" +"Vous pouvez aussi concevoir une collection de types de valeur. C'est " +"conceptuellement très différent d'une collection de références vers d'autres " +"entités, mais très ressemblant dans Java. " + +#. Tag: title +#, no-c-format +msgid "Collection of values" +msgstr "Collection de valeurs" + +#. Tag: para +#, no-c-format +msgid "" +"Let's add a collection of email addresses to the <literal>Person</literal> " +"entity. This will be represented as a <interfacename>java.util.Set</" +"interfacename> of <classname>java.lang.String</classname> instances:" +msgstr "" +"Ajoutons un ensemble d'adresses email à l'entité <literal>Person</literal> " +"qui sera représenté en tant que <interfacename>java.util.Set</interfacename> " +"d'instance <classname>java.lang.String</classname> :" + +#. Tag: para +#, no-c-format +msgid "The mapping of this <literal>Set</literal> is as follows:" +msgstr "Le mappage de ce <literal>Set</literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"The difference compared with the earlier mapping is the use of the " +"<literal>element</literal> part which tells Hibernate that the collection " +"does not contain references to another entity, but is rather a collection " +"whose elements are values types, here specifically of type <literal>string</" +"literal>. The lowercase name tells you it is a Hibernate mapping type/" +"converter. Again the <literal>table</literal> attribute of the <literal>set</" +"literal> element determines the table name for the collection. The " +"<literal>key</literal> element defines the foreign-key column name in the " +"collection table. The <literal>column</literal> attribute in the " +"<literal>element</literal> element defines the column name where the email " +"address values will actually be stored." +msgstr "" +"La différence comparée au mappage vu plus tôt est la partie " +"<literal>element</literal>, qui indique à Hibernate que la collection ne " +"contient pas de référence vers une autre entité, mais une collection " +"d'éléments de type <literal>String</literal> (le nom en minuscule vous " +"indique que c'est un type/convertisseur du mappage Hibernate). Une fois " +"encore, l'attribut <literal>table</literal> de l'élément <literal>set</" +"literal> détermine le nom de la table pour la collection. L'élément " +"<literal>key</literal> définit le nom de la colonne de la clé étrangère dans " +"la table de la collection. L'attribut <literal>column</literal> dans " +"l'élément <literal>element</literal> définit le nom de la colonne où les " +"valeurs de <literal>String</literal> seront réellement stockées. " + +#. Tag: para +#, no-c-format +msgid "Here is the updated schema:" +msgstr "Considérons le schéma mis à jour : " + +#. Tag: para +#, no-c-format +msgid "" +"You can see that the primary key of the collection table is in fact a " +"composite key that uses both columns. This also implies that there cannot be " +"duplicate email addresses per person, which is exactly the semantics we need " +"for a set in Java." +msgstr "" +"Vous pouvez voir que la clé primaire de la table de la collection est en " +"fait une clé composée, utilisant les deux colonnes. Ceci implique aussi " +"qu'il ne peut pas y avoir d'adresses email dupliquées par personne, ce qui " +"est exactement la sémantique dont nous avons besoin pour un ensemble dans " +"Java. " + +#. Tag: para +#, no-c-format +msgid "" +"You can now try to add elements to this collection, just like we did before " +"by linking persons and events. It is the same code in Java:" +msgstr "" +"Vous pouvez maintenant tester et ajouter des éléments à cette collection, " +"juste comme nous l'avons fait auparavant en liant des personnes et des " +"événements. C'est le même code dans Java. " + +#. Tag: para +#, no-c-format +msgid "" +"This time we did not use a <emphasis>fetch</emphasis> query to initialize " +"the collection. Monitor the SQL log and try to optimize this with an eager " +"fetch." +msgstr "" +"Cette fois-ci, nous n'avons pas utilisé de requête de chargement " +"<emphasis>fetch</emphasis> pour initialiser la collection. Traquez les logs " +"SQL et tentez d'optimiser ce cas avec un chargement agressif." + +#. Tag: title +#, no-c-format +msgid "Bi-directional associations" +msgstr "Associations bidirectionnelles" + +#. Tag: para +#, no-c-format +msgid "" +"Next you will map a bi-directional association. You will make the " +"association between person and event work from both sides in Java. The " +"database schema does not change, so you will still have many-to-many " +"multiplicity." +msgstr "" +"Ensuite nous allons mapper une association bidirectionnelle - faire " +"fonctionner l'association entre une personne et un événement à partir des " +"deux côtés dans Java. Bien sûr, le schéma de la base de données ne change " +"pas, nous avons toujours une pluralité plusieurs-à-plusieurs. " + +#. Tag: para +#, no-c-format +msgid "" +"A relational database is more flexible than a network programming language, " +"in that it does not need a navigation direction; data can be viewed and " +"retrieved in any possible way." +msgstr "" +"Une base de données relationnelle est plus flexible qu'un langage de " +"programmation réseau, donc elle n'a pas besoin de direction de navigation - " +"les données peuvent être vues et récupérées de toutes les manières possibles." + +#. Tag: para +#, no-c-format +msgid "" +"First, add a collection of participants to the <literal>Event</literal> " +"class:" +msgstr "" +"D'abord, ajoutez une collection de participants à la classe <literal>Event</" +"literal> : " + +#. Tag: para +#, no-c-format +msgid "" +"Now map this side of the association in <literal>Event.hbm.xml</literal>." +msgstr "" +"Maintenant mappez ce côté de l'association aussi, dans <literal>Event.hbm." +"xml</literal>. " + +#. Tag: para +#, no-c-format +msgid "" +"These are normal <literal>set</literal> mappings in both mapping documents. " +"Notice that the column names in <literal>key</literal> and <literal>many-to-" +"many</literal> swap in both mapping documents. The most important addition " +"here is the <literal>inverse=\"true\"</literal> attribute in the " +"<literal>set</literal> element of the <literal>Event</literal>'s collection " +"mapping." +msgstr "" +"Comme vous le voyez, ce sont des mappages de <literal>set</literal>s normaux " +"dans les deux documents de mappage. Notez que les noms de colonne dans " +"<literal>key</literal> et <literal>many-to-many</literal> sont inversés dans " +"les 2 documents de mappage. L'ajout le plus important ici est l'attribut " +"<literal>inverse=\"true\"</literal> dans l'élément <literal>set</literal> du " +"mappage de la collection des <literal>Event</literal>s. " + +#. Tag: para +#, no-c-format +msgid "" +"What this means is that Hibernate should take the other side, the " +"<literal>Person</literal> class, when it needs to find out information about " +"the link between the two. This will be a lot easier to understand once you " +"see how the bi-directional link between our two entities is created." +msgstr "" +"Cela signifie que Hibernate devrait prendre l'autre côté - la classe " +"<literal>Person</literal> - quand il a besoin de trouver des informations à " +"propos du lien entre les deux. Ce sera beaucoup plus facile à comprendre une " +"fois que vous verrez comment le lien bidirectionnel entre les deux entités " +"est créé. " + +#. Tag: title +#, no-c-format +msgid "Working bi-directional links" +msgstr "Travailler avec des liens bidirectionnels" + +#. Tag: para +#, no-c-format +msgid "" +"First, keep in mind that Hibernate does not affect normal Java semantics. " +"How did we create a link between a <literal>Person</literal> and an " +"<literal>Event</literal> in the unidirectional example? You add an instance " +"of <literal>Event</literal> to the collection of event references, of an " +"instance of <literal>Person</literal>. If you want to make this link bi-" +"directional, you have to do the same on the other side by adding a " +"<literal>Person</literal> reference to the collection in an <literal>Event</" +"literal>. This process of \"setting the link on both sides\" is absolutely " +"necessary with bi-directional links." +msgstr "" +"Premièrement, gardez à l'esprit qu'Hibernate n'affecte pas la sémantique " +"normale de Java. Comment avons-nous créé un lien entre une <literal>Person</" +"literal> et un <literal>Event</literal> dans l'exemple unidirectionnel? Nous " +"avons ajouté une instance de <literal>Event</literal> à la collection des " +"références d'événement d'une instance de <literal>Person</literal>. Donc, " +"évidemment, si vous voulons rendre ce lien bidirectionnel, nous devons faire " +"la même chose de l'autre côté, en ajoutant une référence de <literal>Person</" +"literal> à la collection dans un <literal>Event</literal>. Cette " +"\"configuration du lien des deux côtés\" est absolument nécessaire et vous " +"ne devriez jamais oublier de le faire. " + +#. Tag: para +#, no-c-format +msgid "" +"Many developers program defensively and create link management methods to " +"correctly set both sides (for example, in <literal>Person</literal>):" +msgstr "" +"Beaucoup de développeurs programment de manière défensive et créent des " +"méthodes de gestion de lien pour affecter correctement les deux côtés, par " +"exemple dans <literal>Person</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"The get and set methods for the collection are now protected. This allows " +"classes in the same package and subclasses to still access the methods, but " +"prevents everybody else from altering the collections directly. Repeat the " +"steps for the collection on the other side." +msgstr "" +"Notez que les méthodes get et set pour la collection sont maintenant " +"protégées - ceci permet aux classes et aux sous-classes du même paquetage " +"d'accéder aux méthodes, mais empêche quiconque de mettre le désordre " +"directement dans les collections (enfin, presque). Vous devriez probablement " +"faire de même avec la collection de l'autre côté. " + +#. Tag: para +#, no-c-format +msgid "" +"What about the <literal>inverse</literal> mapping attribute? For you, and " +"for Java, a bi-directional link is simply a matter of setting the references " +"on both sides correctly. Hibernate, however, does not have enough " +"information to correctly arrange SQL <literal>INSERT</literal> and " +"<literal>UPDATE</literal> statements (to avoid constraint violations). " +"Making one side of the association <literal>inverse</literal> tells " +"Hibernate to consider it a <emphasis>mirror</emphasis> of the other side. " +"That is all that is necessary for Hibernate to resolve any issues that arise " +"when transforming a directional navigation model to a SQL database schema. " +"The rules are straightforward: all bi-directional associations need one side " +"as <literal>inverse</literal>. In a one-to-many association it has to be the " +"many-side, and in many-to-many association you can select either side." +msgstr "" +"Et à propos de l'attribut de mappage <literal>inverse</literal> ? Pour vous, " +"et pour Java, un lien bidirectionnel consiste simplement à configurer " +"correctement les références des deux côtés. Hibernate n'a cependant pas " +"assez d'informations pour ordonner correctement les expressions SQL " +"<literal>INSERT</literal> et <literal>UPDATE</literal> (pour éviter les " +"violations de contrainte), et a besoin d'aide pour gérer proprement les " +"associations bidirectionnelles. Rendre <literal>inverse</literal> un côté de " +"l'association, indique à Hibernate de l'ignorer, pour le considérer comme un " +"<emphasis>miroir</emphasis> de l'autre côté. Cela suffit à Hibernate pour " +"gérer tous les problèmes de transformation d'un modèle de navigation " +"directionnelle vers un schéma SQL de base de données. Les règles dont vous " +"devez vous souvenir sont : toutes les associations bidirectionnelles ont " +"besoin d'un côté marqué <literal>inverse</literal>. Dans une association un-" +"à-plusieurs ce doit être le côté plusieurs, dans une association plusieurs-à-" +"plusieurs, vous pouvez choisir n'importe quel côté, il n'y pas de différence." + +#. Tag: title +#, no-c-format +msgid "Part 3 - The EventManager web application" +msgstr "Section 3 - L'application web EventManager" + +#. Tag: para +#, no-c-format +msgid "" +"A Hibernate web application uses <literal>Session</literal> and " +"<literal>Transaction</literal> almost like a standalone application. " +"However, some common patterns are useful. You can now write an " +"<literal>EventManagerServlet</literal>. This servlet can list all events " +"stored in the database, and it provides an HTML form to enter new events." +msgstr "" +"Une application web Hibernate utilise la <literal>Session</literal> et " +"<literal>Transaction</literal> comme une application autonome. Cependant, " +"quelques modèles communs sont utiles. Nous allons coder une " +"<literal>EventManagerServlet</literal>. Ce servlet peut lister tous les " +"évènements stockés dans la base de données, et fournir une formulaire HTML " +"pour saisir de nouveaux évènements. " + +#. Tag: title +#, no-c-format +msgid "Writing the basic servlet" +msgstr "Écrire la servlet de base" + +#. Tag: para +#, no-c-format +msgid "" +"First we need create our basic processing servlet. Since our servlet only " +"handles HTTP <literal>GET</literal> requests, we will only implement the " +"<literal>doGet()</literal> method:" +msgstr "" +"Tout d'abord, nous devons créer notre servlet de base. La servlet n'accepte " +"que les requêtes HTTP <literal>GET</literal>, la méthode à implémenter est " +"donc <literal>doGet()</literal> :" + +#. Tag: para +#, no-c-format +msgid "" +"Save this servlet as <filename>src/main/java/org/hibernate/tutorial/web/" +"EventManagerServlet.java</filename>" +msgstr "" +"Servir la servlet en tant que <filename>src/main/java/org/hibernate/tutorial/" +"web/EventManagerServlet.java</filename>" + +#. Tag: para +#, no-c-format +msgid "" +"The pattern applied here is called <emphasis>session-per-request</emphasis>. " +"When a request hits the servlet, a new Hibernate <literal>Session</literal> " +"is opened through the first call to <literal>getCurrentSession()</literal> " +"on the <literal>SessionFactory</literal>. A database transaction is then " +"started. All data access occurs inside a transaction irrespective of whether " +"the data is read or written. Do not use the auto-commit mode in applications." +msgstr "" +"Le modèle appliqué ici est appelé <emphasis>session-per-request</emphasis>. " +"Lorsqu'une requête appelle la servlet, une nouvelle <literal>Session</" +"literal> Hibernate est ouverte à la première invocation de " +"<literal>getCurrentSession()</literal> sur la <literal>SessionFactory</" +"literal>. Ensuite, une transaction avec la base de données est démarrée - " +"tous les accès à la base de données interviennent au sein de la transaction, " +"peu importe que les données soient lues ou écrites (nous n'utilisons pas le " +"mode auto-commit dans les applications). " + +#. Tag: para +#, no-c-format +msgid "" +"Do <emphasis>not</emphasis> use a new Hibernate <literal>Session</literal> " +"for every database operation. Use one Hibernate <literal>Session</literal> " +"that is scoped to the whole request. Use <literal>getCurrentSession()</" +"literal>, so that it is automatically bound to the current Java thread." +msgstr "" +"<emphasis>N'utilisez pas</emphasis> une nouvelle <literal>Session</literal> " +"Hibernate pour chaque opération en base de données. Utilisez une " +"<literal>Session</literal> Hibernate qui porte sur l'ensemble de la requête. " +"Utlisez <literal>getCurrentSession()</literal>, ainsi elle est " +"automatiquement attachée au thread Java courant." + +#. Tag: para +#, no-c-format +msgid "" +"Next, the possible actions of the request are processed and the response " +"HTML is rendered. We will get to that part soon." +msgstr "" +"Ensuite, les actions possibles de la requêtes sont exécutées et la réponse " +"HTML est rendue. Nous y reviendrons ultérieurement. " + +#. Tag: para +#, no-c-format +msgid "" +"Finally, the unit of work ends when processing and rendering are complete. " +"If any problems occurred during processing or rendering, an exception will " +"be thrown and the database transaction rolled back. This completes the " +"<literal>session-per-request</literal> pattern. Instead of the transaction " +"demarcation code in every servlet, you could also write a servlet filter. " +"See the Hibernate website and Wiki for more information about this pattern " +"called <emphasis>Open Session in View</emphasis>. You will need it as soon " +"as you consider rendering your view in JSP, not in a servlet." +msgstr "" +"Enfin, l'unité de travail s'achève lorsque l'exécution et le rendu sont " +"achevés. Si un problème survient lors de ces deux phases, une exception est " +"lancée et la transaction avec la base de données subit un rollback. Cela " +"complète le modèle <literal>session-per-request</literal>. Au lieu d'avoir " +"un code de délimitant les transactions au sein de chaque servlet, vous " +"pouvez écrire un filtre de servlet. Voir le site Hibernate et le Wiki pour " +"plus d'informations sur ce modèle, appelé <emphasis>Open Session in View</" +"emphasis> - vous en aurez besoin dès que vous utiliserez des JSP et non des " +"servlets pour le rendu de vos vues. " + +#. Tag: title +#, no-c-format +msgid "Processing and rendering" +msgstr "Traiter et interpréter" + +#. Tag: para +#, no-c-format +msgid "" +"Now you can implement the processing of the request and the rendering of the " +"page." +msgstr "Implémentons l'exécution de la requête et le rendu de la page. " + +#. Tag: para +#, no-c-format +msgid "" +"This coding style, with a mix of Java and HTML, would not scale in a more " +"complex application&mdash;keep in mind that we are only illustrating basic " +"Hibernate concepts in this tutorial. The code prints an HTML header and a " +"footer. Inside this page, an HTML form for event entry and a list of all " +"events in the database are printed. The first method is trivial and only " +"outputs HTML:" +msgstr "" +"Ce style de code avec une mixture de Java et d'HTML ne serait pas extensible " +"dans une application plus complexe - gardez à l'esprit que nous ne faisons " +"qu'illustrer les concepts basiques de Hibernate dans ce didacticiel. Ce code " +"affiche une entête et un pied de page HTML. Dans cette page, sont affichés " +"un formulaire pour la saisie d'évènements ainsi qu'une liste de tous les " +"évènements de la base de données. La première méthode est triviale et ne " +"fait que sortir de l'HTML :" + +#. Tag: para +#, no-c-format +msgid "" +"The <literal>listEvents()</literal> method uses the Hibernate " +"<literal>Session</literal> bound to the current thread to execute a query:" +msgstr "" +"La méthode <literal>listEvents()</literal> utilise la <literal>Session</" +"literal> Hibernate liée au thread courant pour exécuter la requête :" + +#. Tag: para +#, no-c-format +msgid "" +"Finally, the <literal>store</literal> action is dispatched to the " +"<literal>createAndStoreEvent()</literal> method, which also uses the " +"<literal>Session</literal> of the current thread:" +msgstr "" +"Enfin, l'action <literal>store</literal> renvoie à la méthode " +"<literal>createAndStoreEvent()</literal>, qui utilise aussi la " +"<literal>Session</literal> du thread courant:" + +#. Tag: para +#, no-c-format +msgid "" +"The servlet is now complete. A request to the servlet will be processed in a " +"single <literal>Session</literal> and <literal>Transaction</literal>. As " +"earlier in the standalone application, Hibernate can automatically bind " +"these objects to the current thread of execution. This gives you the freedom " +"to layer your code and access the <literal>SessionFactory</literal> in any " +"way you like. Usually you would use a more sophisticated design and move the " +"data access code into data access objects (the DAO pattern). See the " +"Hibernate Wiki for more examples." +msgstr "" +"La servlet est complétée. Une requête à la servlet sera exécutée par une " +"seule <literal>Session</literal> et <literal>Transaction</literal>. Comme " +"dans l'application autonome vue auparavant, Hibernate peut automatiquement " +"lier ces objets au thread courant d'exécution. Cela vous laisse la liberté " +"de séparer votre code en couches et d'accéder à la <literal>SessionFactory</" +"literal> selon le moyen que vous aurez choisi. Généralement, vous utiliserez " +"des conceptions plus sophistiquées et déplacerez le code d'accès aux données " +"dans une couche DAO. Consultez le wiki Hibernate pour plus d'exemples. " + +#. Tag: title +#, no-c-format +msgid "Deploying and testing" +msgstr "Déployer et tester" + +#. Tag: para +#, no-c-format +msgid "" +"To deploy this application for testing we must create a Web ARchive (WAR). " +"First we must define the WAR descriptor as <filename>src/main/webapp/WEB-INF/" +"web.xml</filename>" +msgstr "" +"Pour déployer cette application en vue de procéder à des tests, nous devons " +"créer un WAR (Web ARchive). Tout d'abord, nous devons définir le descripteur " +"WAR en tant que <filename>src/main/webapp/WEB-INF/web.xml</filename>" + +#. Tag: para +#, no-c-format +msgid "" +"To build and deploy call <literal>mvn package</literal> in your project " +"directory and copy the <filename>hibernate-tutorial.war</filename> file into " +"your Tomcat <filename>webapps</filename> directory." +msgstr "" +"Pour construire et déployer, appelez <literal>ant war</literal> dans votre " +"projet et copiez le fichier <literal>hibernate-tutorial.war</literal> dans " +"le répertoire <literal>webapp</literal> de Tomcat. " + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"If you do not have Tomcat installed, download it from <ulink url=\"http://" +"tomcat.apache.org/\" /> and follow the installation instructions. Our " +"application requires no changes to the standard Tomcat configuration." +msgstr "" +"Si vous n'avez pas installé Tomcat, téléchargez-le de <ulink url=\"http://" +"tomcat.apache.org/\" /> et suivez la notice d'installation. Vous n'avez pas " +"à modifier la configuration Tomcat pour déployer cette application." + +#. Tag: para +#, no-c-format +msgid "" +"Once deployed and Tomcat is running, access the application at " +"<literal>http://localhost:8080/hibernate-tutorial/eventmanager</literal>. " +"Make sure you watch the Tomcat log to see Hibernate initialize when the " +"first request hits your servlet (the static initializer in " +"<literal>HibernateUtil</literal> is called) and to get the detailed output " +"if any exceptions occurs." +msgstr "" +"Une fois l'application déployée et Tomcat lancé, accédez à l'application via " +"<literal>http://localhost:8080/hibernate-tutorial/eventmanager</literal>. " +"Assurez vous de consulter les traces Tomcat pour observer l'initialisation " +"d'Hibernate à la première requête touchant votre servlet (l'initialisation " +"statique dans <literal>HibernateUtil</literal> est invoquée) et pour " +"vérifier qu'aucune exception ne survienne." + +#. Tag: title +#, no-c-format +msgid "Summary" +msgstr "Résumé" + +#. Tag: para +#, no-c-format +msgid "" +"This tutorial covered the basics of writing a simple standalone Hibernate " +"application and a small web application. More tutorials are available from " +"the Hibernate <ulink url=\"http://hibernate.org\">website</ulink>." +msgstr "" +"Ce didacticiel a couvert les bases de l'écriture d'une simple application " +"Hibernate ainsi qu'une petite application web. Vous trouverez des tutoriels " +"supplémentaires dans le site Hibernate <ulink url=\"http://hibernate.org" +"\">website</ulink>." Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/xml.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/xml.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/content/xml.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,243 @@ +# translation of xml.po to French +# Myriam Malga <mmalga(a)redhat.com&gt;, 2007. +# Xi HUANG <xhuang(a)redhat.com&gt;, 2007. +# Corina Roe <croe(a)redhat.com&gt;, 2009, 2010. +# translation of Collection_Mapping.po to +msgid "" +msgstr "" +"Project-Id-Version: xml\n" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-10T07:25:35\n" +"PO-Revision-Date: 2010-01-05 10:08+1000\n" +"Last-Translator: Corina Roe <croe(a)redhat.com&gt;\n&quot; +"Language-Team: French <i18(a)redhat.com&gt;\n&quot; +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: KBabel 1.11.4\n" + +#. Tag: title +#, no-c-format +msgid "XML Mapping" +msgstr "Mappage XML" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<emphasis> XML Mapping is an experimental feature in Hibernate 3.0 and is " +"currently under active development. </emphasis>" +msgstr "" +"<emphasis>Notez que cette fonctionnalité est expérimentale dans Hibernate " +"3.0 et est en développement extrêmement actif. </emphasis>" + +#. Tag: title +#, no-c-format +msgid "Working with XML data" +msgstr "Travailler avec des données XML" + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate allows you to work with persistent XML data in much the same way " +"you work with persistent POJOs. A parsed XML tree can be thought of as " +"another way of representing the relational data at the object level, instead " +"of POJOs." +msgstr "" +"Hibernate vous laisse travailler avec des données XML persistantes de la " +"même manière que vous travaillez avec des POJO persistants. Un arbre XML " +"peut être vu comme une autre manière de représenter les données " +"relationnelles au niveau objet, à la place des POJO. " + +#. Tag: para +#, no-c-format +msgid "" +"Hibernate supports dom4j as API for manipulating XML trees. You can write " +"queries that retrieve dom4j trees from the database and have any " +"modification you make to the tree automatically synchronized to the " +"database. You can even take an XML document, parse it using dom4j, and write " +"it to the database with any of Hibernate's basic operations: <literal>persist" +"(), saveOrUpdate(), merge(), delete(), replicate()</literal> (merging is not " +"yet supported)." +msgstr "" +"Hibernate supporte dom4j en tant qu'API pour la manipulation des arbres XML. " +"Vous pouvez écrire des requêtes qui récupèrent des arbres dom4j à partir de " +"la base de données, et avoir toutes les modifications que vous faites sur " +"l'arbre automatiquement synchronisées dans la base de données. Vous pouvez " +"même prendre un document XML, l'analyser en utilisant dom4j, et l'écrire " +"dans la base de données via les opérations basiques de Hibernate : " +"<literal>persist(), saveOrUpdate(), merge(), delete(), replicate()</literal> " +"(merge n'est pas encore supporté)." + +#. Tag: para +#, no-c-format +msgid "" +"This feature has many applications including data import/export, " +"externalization of entity data via JMS or SOAP and XSLT-based reporting." +msgstr "" +"Cette fonctionnalité a plusieurs applications dont l'import/export de " +"données, l'externalisation de données d'entités via JMS ou SOAP et les " +"rapports XSLT." + +#. Tag: para +#, no-c-format +msgid "" +"A single mapping can be used to simultaneously map properties of a class and " +"nodes of an XML document to the database, or, if there is no class to map, " +"it can be used to map just the XML." +msgstr "" +"Un simple mappage peut être utilisé pour simultanément mapper les propriétés " +"d'une classe et les noeuds d'un document XML vers la base de données, ou, " +"s'il n'y a pas de classe à mapper, il peut être utilisé juste pour mapper le " +"XML. " + +#. Tag: title +#, no-c-format +msgid "Specifying XML and class mapping together" +msgstr "Spécifier le mappage XML et le mappage d'une classe ensemble" + +#. Tag: para +#, no-c-format +msgid "Here is an example of mapping a POJO and XML simultaneously:" +msgstr "Voici un exemple de mappage d'un POJO et du XML simultanément :" + +#. Tag: title +#, no-c-format +msgid "Specifying only an XML mapping" +msgstr "Spécifier seulement un mappage XML" + +#. Tag: para +#, no-c-format +msgid "Here is an example where there is no POJO class:" +msgstr "Voici un exemple dans lequel il n'y a pas de classe POJO :" + +#. Tag: para +#, no-c-format +msgid "" +"This mapping allows you to access the data as a dom4j tree, or as a graph of " +"property name/value pairs or java <literal>Map</literal>s. The property " +"names are purely logical constructs that can be referred to in HQL queries." +msgstr "" +"Ce mappage vous permet d'accéder aux données comme un arbre dom4j, ou comme " +"un graphe de paire nom/valeur de propriété (<literal>Map</literal> s java). " +"Les noms des propriétés sont des constructions purement logiques qui peuvent " +"être référées dans des requêtes HQL. " + +#. Tag: title +#, no-c-format +msgid "XML mapping metadata" +msgstr "Métadonnées du mappage XML" + +#. Tag: para +#, no-c-format +msgid "" +"A range of Hibernate mapping elements accept the <literal>node</literal> " +"attribute. This lets you specify the name of an XML attribute or element " +"that holds the property or entity data. The format of the <literal>node</" +"literal> attribute must be one of the following:" +msgstr "" +"Plusieurs éléments du mappage Hibernate acceptent l'attribut <literal>node</" +"literal>. Ceci vous permet de spécifier le nom d'un attribut XML ou d'un " +"élément qui contient la propriété ou les données de l'entité. Le format de " +"l'attribut <literal>node</literal> doit être un des suivants : " + +#. Tag: para +#, no-c-format +msgid "<literal>\"element-name\"</literal>: map to the named XML element" +msgstr "<literal>\"element-name\"</literal> - mappe vers l'élément XML nommé " + +#. Tag: para +#, no-c-format +msgid "<literal>\"@attribute-name\"</literal>: map to the named XML attribute" +msgstr "" +"<literal>\"@attribute-name\"</literal> - mappe vers l'attribut XML nommé " + +#. Tag: para +#, no-c-format +msgid "<literal>\".\"</literal>: map to the parent element" +msgstr "<literal>\".\"</literal> - mappe vers le parent de l'élément " + +#. Tag: para +#, no-c-format +msgid "" +"<literal>\"element-name/@attribute-name\"</literal>: map to the named " +"attribute of the named element" +msgstr "" +"<literal>\"element-name/@attribute-name\"</literal> - mappe vers l'élément " +"nommé de l'attribut nommé " + +#. Tag: para +#, no-c-format +msgid "" +"For collections and single valued associations, there is an additional " +"<literal>embed-xml</literal> attribute. If <literal>embed-xml=\"true\"</" +"literal>, the default, the XML tree for the associated entity (or collection " +"of value type) will be embedded directly in the XML tree for the entity that " +"owns the association. Otherwise, if <literal>embed-xml=\"false\"</literal>, " +"then only the referenced identifier value will appear in the XML for single " +"point associations and collections will not appear at all." +msgstr "" +"Pour des collections et de simples associations valuées, il y a un attribut " +"<literal>embed-xml</literal> supplémentaire. Si <literal>embed-xml=\"true\"</" +"literal>, qui est la valeur par défaut, l'arbre XML pour l'entité associée " +"(ou la collection des types de valeurs) sera embarquée directement dans " +"l'arbre XML pour l'entité qui possède l'association. Sinon, si " +"<literal>embed-xml=\"false\"</literal>, alors seule la valeur de " +"l'identifiant référencé apparaîtra dans le XML pour de simples associations " +"de points, et les collections n'apparaîtront pas. " + +#. Tag: para +#, no-c-format +msgid "" +"Do not leave <literal>embed-xml=\"true\"</literal> for too many " +"associations, since XML does not deal well with circularity." +msgstr "" +"Faire attention à ne pas laisser <literal>embed-xml=\"true\"</literal> pour " +"trop d'associations, puisque XML ne traite pas bien les liens circulaires. " + +#. Tag: para +#, no-c-format +msgid "" +"In this case, the collection of account ids is embedded, but not the actual " +"account data. The following HQL query:" +msgstr "" +"Dans ce cas, nous avons décidé d'embarquer la collection d'identifiants de " +"compte, mais pas les données actuelles du compte. La requête HQL suivante :" + +#. Tag: para +#, no-c-format +msgid "would return datasets such as this:" +msgstr "devrait retourner l'ensemble de données suivant : " + +#. Tag: para +#, no-c-format +msgid "" +"If you set <literal>embed-xml=\"true\"</literal> on the <literal>&lt;one-to-" +"many&gt;</literal> mapping, the data might look more like this:" +msgstr "" +"Si vous positionnez <literal>embed-xml=\"true\"</literal> sur le mappage " +"<literal>&lt;one-to-many&gt;</literal>, les données ressembleraient à ce qui " +"suit :" + +#. Tag: title +#, no-c-format +msgid "Manipulating XML data" +msgstr "Manipuler des données XML" + +#. Tag: para +#, no-c-format +msgid "" +"You can also re-read and update XML documents in the application. You can do " +"this by obtaining a dom4j session:" +msgstr "" +"Relisons et mettons à jour des documents XML dans l'application. Nous " +"effectuons cela en obtenant une session dom4j : " + +#. Tag: para +#, no-c-format +msgid "" +"When implementing XML-based data import/export, it is useful to combine this " +"feature with Hibernate's <literal>replicate()</literal> operation." +msgstr "" +"Il est extrêmement utile de combiner cette fonctionnalité avec l'opération " +"<literal>replicate()</literal> de Hibernate pour implémenter des imports/" +"exports de données XML. " Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Conventions.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Conventions.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Conventions.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,214 @@ +# +# AUTHOR <EMAIL@ADDRESS>, YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: 0\n" +"POT-Creation-Date: 2010-02-04T04:51:23\n" +"PO-Revision-Date: 2010-02-04T04:51:23\n" +"Last-Translator: Automatically generated\n" +"Language-Team: None\n" +"MIME-Version: 1.0\n" +"Content-Type: application/x-publican; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#, no-c-format +msgid "Document Conventions" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "In PDF and paper editions, this manual uses typefaces drawn from the <ulink url=\"https://fedorahosted.org/liberation-fonts/\">Liberation Fonts</ulink> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Typographic Conventions" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "<literal>Mono-spaced Bold</literal>" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "To see the contents of the file <filename>my_next_bestselling_novel</filename> in your current working directory, enter the <command>cat my_next_bestselling_novel</command> command at the shell prompt and press <keycap>Enter</keycap> to execute the command." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Press <keycap>Enter</keycap> to execute the command." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> to switch to the first virtual terminal. Press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F7</keycap></keycombo> to return to your X-Windows session." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously)." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in <literal>mono-spaced bold</literal>. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "File-related classes include <classname>filesystem</classname> for file systems, <classname>file</classname> for files, and <classname>dir</classname> for directories. Each class has its own associated set of permissions." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "<application>Proportional Bold</application>" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Choose <menuchoice><guimenu>System</guimenu><guisubmenu>Preferences</guisubmenu><guimenuitem>Mouse</guimenuitem></menuchoice> from the main menu bar to launch <application>Mouse Preferences</application>. In the <guilabel>Buttons</guilabel> tab, click the <guilabel>Left-handed mouse</guilabel> check box and click <guibutton>Close</guibutton> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand)." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "To insert a special character into a <application>gedit</application> file, choose <menuchoice><guimenu>Applications</guimenu><guisubmenu>Accessories</guisubmenu><guimenuitem>Character Map</guimenuitem></menuchoice> from the main menu bar. Next, choose <menuchoice><guimenu>Search</guimenu><guimenuitem>Find&hellip;</guimenuitem></menuchoice> from the <application>Character Map</application> menu bar, type the name of the character in the <guilabel>Search</guilabel> field and click <guibutton>Next</guibutton>. The character you sought will be highlighted in the <guilabel>Character Table</guilabel>. Double-click this highlighted character to place it in the <guilabel>Text to copy</guilabel> field and then click the <guibutton>Copy</guibutton> button. Now switch back to your document and choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice> from the <application>gedit</application> menu bar." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "<command><replaceable>Mono-spaced Bold Italic</replaceable></command> or <application><replaceable>Proportional Bold Italic</replaceable></application>" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "To connect to a remote machine using ssh, type <command>ssh <replaceable&gt;username&lt;/replaceable&gt;(a)&lt;replaceable&gt;domain.name&lt;/replaceable&gt;&lt;/command&gt; at a shell prompt. If the remote machine is <filename>example.com</filename> and your username on that machine is john, type <command>ssh john(a)example.com&lt;/command&gt;.&quot; +msgstr "" + +#. Tag: para +#, no-c-format +msgid "The <command>mount -o remount <replaceable>file-system</replaceable></command> command remounts the named file system. For example, to remount the <filename>/home</filename> file system, the command is <command>mount -o remount /home</command>." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "To see the version of a currently installed package, use the <command>rpm -q <replaceable>package</replaceable></command> command. It will return a result as follows: <command><replaceable>package-version-release</replaceable></command>." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Note the words in bold italics above &mdash; username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Publican is a <firstterm>DocBook</firstterm> publishing system." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Pull-quote Conventions" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Terminal output and source code listings are set off visually from the surrounding text." +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Output sent to a terminal is set in <computeroutput>mono-spaced roman</computeroutput> and presented thus:" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Source-code listings are also set in <computeroutput>mono-spaced roman</computeroutput> but add syntax highlighting as follows:" +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Notes and Warnings" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Finally, we use three visual styles to draw attention to information that might otherwise be overlooked." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Note" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Important" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' won't cause data loss but may cause irritation and frustration." +msgstr "" + +#. Tag: title +#, no-c-format +msgid "Warning" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "Warnings should not be ignored. Ignoring warnings will most likely cause data loss." +msgstr "" + Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Feedback.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Feedback.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Feedback.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,23 @@ +# +# AUTHOR <EMAIL@ADDRESS>, YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: 0\n" +"POT-Creation-Date: 2010-03-12T00:03:48\n" +"PO-Revision-Date: 2010-02-04T04:51:23\n" +"Last-Translator: Automatically generated\n" +"Language-Team: None\n" +"MIME-Version: 1.0\n" +"Content-Type: application/x-publican; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: title +#, no-c-format +msgid "We Need Feedback!" +msgstr "" + +#. Tag: para +#, no-c-format +msgid "You should over ride this by creating your own local Feedback.xml file." +msgstr "" Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Legal_Notice.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Legal_Notice.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/fallback_content/Legal_Notice.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,19 @@ +# +# AUTHOR <EMAIL@ADDRESS>, YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: 0\n" +"POT-Creation-Date: 2010-02-04T04:51:23\n" +"PO-Revision-Date: 2010-02-04T04:51:23\n" +"Last-Translator: Automatically generated\n" +"Language-Team: None\n" +"MIME-Version: 1.0\n" +"Content-Type: application/x-publican; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. Tag: para +#, no-c-format +msgid "Copyright <trademark class=\"copyright\"></trademark> &YEAR; &HOLDER; This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at <ulink url=\"http://www.gnu.org/licenses/fdl.txt\">http://www.gnu.o... +msgstr "" + Added: core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/legal_notice.po =================================================================== --- core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/legal_notice.po (rev 0) +++ core/branches/gradle2/hibernate-release/src/main/docbook/fr-FR/legal_notice.po 2010-06-05 00:54:54 UTC (rev 19694) @@ -0,0 +1,78 @@ +#, fuzzy +msgid "" +msgstr "" +"Report-Msgid-Bugs-To: http://bugs.kde.org\n" +"POT-Creation-Date: 2010-02-04T04:51:23\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Content-Type: text/plain; charset=UTF-8\n" + +#. Tag: title +#, no-c-format +msgid "Legal Notice" +msgstr "Legal Notice" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"<address> <street>1801 Varsity Drive</street> <city>Raleigh</city>, " +"<state>NC</state><postcode>27606-2072</postcode><country>USA</country> " +"<phone>Phone: +1 919 754 3700</phone> <phone>Phone: 888 733 4281</phone> " +"<fax>Fax: +1 919 754 3701</fax> <pob>PO Box 13588</pob><city>Research " +"Triangle Park</city>, <state>NC</state><postcode>27709</" +"postcode><country>USA</country> </address>" +msgstr "" +"<address> <street>1801 Varsity Drive</street> <city>Raleigh</city>, <state>NC</" +"state><postcode>27606-2072</postcode><country>USA</country> <phone>Phone: +1 " +"919 754 3700</phone> <phone>Phone: 888 733 4281</phone> <fax>Fax: +1 919 754 " +"3701</fax> <pob>PO Box 13588</pob><city>Research Triangle Park</city>, " +"<state>NC</state><postcode>27709</postcode><country>USA</country> </address>" + +#. Tag: para +#, fuzzy, no-c-format +msgid "" +"Copyright <trademark class=\"copyright\"></trademark> 2007 by Red Hat, Inc. " +"This copyrighted material is made available to anyone wishing to use, " +"modify, copy, or redistribute it subject to the terms and conditions of the " +"GNU <ulink url=\"http://www.gnu.org/licenses/lgpl-2.1.html\">Lesser General " +"Public License</ulink>, as published by the Free Software Foundation." +msgstr "" +"Copyright <trademark class=\"copyright\"></trademark> 2007 by Red Hat, Inc. " +"This copyrighted material is made available to anyone wishing to use, " +"modify, copy, or redistribute it subject to the terms and conditions of the " +"GNU <ulink url=\"http://www.gnu.org/licenses/lgpl-2.1.html\">Lesser General " +"Public License</ulink>, as published by the Free Software Foundation." + +#. Tag: para +#, no-c-format +msgid "" +"Red Hat and the Red Hat \"Shadow Man\" logo are registered trademarks of Red " +"Hat, Inc. in the United States and other countries." +msgstr "" +"Red Hat and the Red Hat \"Shadow Man\" logo are registered trademarks of Red " +"Hat, Inc. in the United States and other countries." + +#. Tag: para +#, no-c-format +msgid "" +"All other trademarks referenced herein are the property of their respective " +"owners." +msgstr "" +"All other trademarks referenced herein are the property of their respective " +"owners." + +#. Tag: para +#, no-c-format +msgid "The GPG fingerprint of the security(a)redhat.com key is:" +msgstr "The GPG fingerprint of the security(a)redhat.com key is:" + +#. Tag: para +#, no-c-format +msgid "CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E" +msgstr "CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E" + +#~ msgid "ROLES_OF_TRANSLATORS" +#~ msgstr "<!--TRANS:ROLES_OF_TRANSLATORS-->" + +#~ msgid "CREDIT_FOR_TRANSLATORS" +#~ msgstr "<!--TRANS:CREDIT_FOR_TRANSLATORS-->" Modified: core/branches/gradle2/settings.gradle =================================================================== --- core/branches/gradle2/settings.gradle 2010-06-04 18:42:32 UTC (rev 19693) +++ core/branches/gradle2/settings.gradle 2010-06-05 00:54:54 UTC (rev 19694) @@ -17,10 +17,9 @@ include 'hibernate-jbosscache' include 'hibernate-oscache' include 'hibernate-swarmcache' +include 'hibernate-release' -//include 'hibernate-release' - rootProject.children.each {project -> project.buildFileName = "${project.name}.gradle" assert project.projectDir.isDirectory()