[hibernate-commits] Hibernate SVN: r14075 - in
core/trunk/documentation/manual/es-ES/src/main: docbook and 2
other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Oct 9 14:45:36 EDT 2007
Author: steve.ebersole at jboss.com
Date: 2007-10-09 14:45:36 -0400 (Tue, 09 Oct 2007)
New Revision: 14075
Added:
core/trunk/documentation/manual/es-ES/src/main/docbook/Hibernate_Reference.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/
core/trunk/documentation/manual/es-ES/src/main/docbook/content/architecture.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/association_mapping.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/basic_mapping.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/batch.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/best_practices.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/collection_mapping.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/component_mapping.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/configuration.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/events.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/example_mappings.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/example_parentchild.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/example_weblog.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/filters.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/inheritance_mapping.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/performance.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/persistent_classes.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/preface.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/query_criteria.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/query_hql.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/query_sql.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/quickstart.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/session_api.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/toolset_guide.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/transactions.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/tutorial.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/content/xml.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/images/
core/trunk/documentation/manual/es-ES/src/main/docbook/images/AuthorWork.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/AuthorWork.zargo
core/trunk/documentation/manual/es-ES/src/main/docbook/images/CustomerOrderProduct.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/CustomerOrderProduct.zargo
core/trunk/documentation/manual/es-ES/src/main/docbook/images/EmployerEmployee.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/EmployerEmployee.zargo
core/trunk/documentation/manual/es-ES/src/main/docbook/images/full_cream.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/full_cream.svg
core/trunk/documentation/manual/es-ES/src/main/docbook/images/hibernate_logo_a.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/lite.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/lite.svg
core/trunk/documentation/manual/es-ES/src/main/docbook/images/overview.png
core/trunk/documentation/manual/es-ES/src/main/docbook/images/overview.svg
core/trunk/documentation/manual/es-ES/src/main/docbook/legal_notice.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/legal_notice2.xml
core/trunk/documentation/manual/es-ES/src/main/docbook/translators.xml
Removed:
core/trunk/documentation/manual/es-ES/src/main/docbook/master.xml
core/trunk/documentation/manual/es-ES/src/main/resources/
Log:
new docbook layout (prep for translations migration to PO)
Added: core/trunk/documentation/manual/es-ES/src/main/docbook/Hibernate_Reference.xml
===================================================================
--- core/trunk/documentation/manual/es-ES/src/main/docbook/Hibernate_Reference.xml (rev 0)
+++ core/trunk/documentation/manual/es-ES/src/main/docbook/Hibernate_Reference.xml 2007-10-09 18:45:36 UTC (rev 14075)
@@ -0,0 +1,88 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!--
+ ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved.
+ ~
+ ~ 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, v. 2.1. This program is distributed in the
+ ~ hope that it will be useful, but WITHOUT A 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, v.2.1 along with this
+ ~ distribution; if not, write to the Free Software Foundation, Inc.,
+ ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ ~
+ ~ Red Hat Author(s): Steve Ebersole
+ -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY versionNumber "3.3.0.alpha1">
+ <!ENTITY copyrightYear "2004">
+ <!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+]>
+
+<book>
+
+ <bookinfo>
+ <title>HIBERNATE - Persistencia Relacional para Java Idiomático</title>
+ <subtitle>Documentación de Referencia de Hibernate</subtitle>
+ <releaseinfo>&versionNumber;</releaseinfo>
+ <productnumber>&versionNumber;</productnumber>
+ <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>©rightYear;</year>
+ <holder>©rightHolder;</holder>
+ </copyright>
+ <xi:include href="translators.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="legal_notice2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </bookinfo>
+
+ <toc/>
+
+ <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/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" />
+
+</book>
+
Copied: core/trunk/documentation/manual/es-ES/src/main/docbook/content/architecture.xml (from rev 12794, core/trunk/documentation/manual/es-ES/src/main/docbook/modules/architecture.xml)
===================================================================
--- core/trunk/documentation/manual/es-ES/src/main/docbook/content/architecture.xml (rev 0)
+++ core/trunk/documentation/manual/es-ES/src/main/docbook/content/architecture.xml 2007-10-09 18:45:36 UTC (rev 14075)
@@ -0,0 +1,279 @@
+<chapter id="architecture">
+
+ <title>Arquitectura</title>
+
+ <sect1 id="architecture-overview" revision="1">
+ <title>Visión General</title>
+
+ <para>
+ Una visión a (muy) alto nivel de la arquitectura de Hibernate:
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/overview.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/overview.gif" format="GIF" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ Este diagrama muestra a Hibernate usando la base de datos y los datos de
+ configuración para proveer servicios de persistencia (y objetos
+ persistentes) a la aplicación.
+ </para>
+
+ <para>
+ Nos gustaría mostrar una vista más detallada de la arquitectura de tiempo
+ de ejecución. Desafortunadamente, Hibernate es flexible y soporta diferentes
+ enfoques. Mostraremos los dos extremos. En la arquitectura "sencilla", es la
+ aplicación la que provee su propias conexiones JDBC y gestiona sus propias
+ transacciones. Este enfoque usa un mínimo subconjunto de la API de Hibernate:
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/lite.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/lite.gif" format="GIF" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ La arquitectura "full cream" abstrae a la aplicación de las APIs
+ de JDBC/JTA y deja que Hibernate se encargue de los detalles.
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/full_cream.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/full_cream.gif" format="GIF" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ He aquí algunas definiciones de los objetos en los diagramas:
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term>
+ <listitem>
+ <para>
+ Caché threadsafe (inmutable) de mapeos compilados para
+ una sola base de datos. Es una fábrica de <literal>Session</literal>
+ y un cliente de <literal>ConnectionProvider</literal>. Opcionalmente,
+ puede mantener una caché (de segundo nivel) de datos reusables
+ entre transacciones, a un nivel de proceso o de cluster.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Session (<literal>org.hibernate.Session</literal>)</term>
+ <listitem>
+ <para>
+ Objeto mono-hebra, de corta vida que representa una conversación
+ entre la aplicación y el almacenamiento persistente. Envuelve una
+ conexión JDBC. Es una fábrica de <literal>Transaction</literal>.
+ Mantiene una caché requerida (de primer nivel) de objetos persistentes,
+ usada mientras se navega el grafo de objetos o se recuperen objetos por
+ identificador.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Objetos y colecciones persistentes</term>
+ <listitem>
+ <para>
+ Objetos de corta vida, mono-hebra conteniendo estado persistente y
+ funciónalidad de negocio. Estos pueden ser JavaBeans/POJOs
+ (Plain Old Java Objects, o sea, cualquier objeto Java), la única
+ cosa especial en ellos es que estan asociados actualmente con una
+ (y sólo una) <literal>Session</literal>. Tan pronto como la
+ <literal>Session</literal> sea cerrada, serán separados y
+ estarán libres para ser usados en cualquier capa de aplicación.
+ (por ejemplo, directamente como objetos de transferencia de datos hacia
+ y desde la capa de presentación).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Objetos y colecciones transitorios y separados</term>
+ <listitem>
+ <para>
+ Instancias de clases persistentes que no estan acutualmente asociadas
+ con una <literal>Session</literal>. Pueden haber sido instanciadas por
+ la aplicación y (aún) no haber sido hechas persistentes,
+ o pueden haber sido instanciadas por una <literal>Session</literal> cerrada.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transaction (<literal>org.hibernate.Transaction</literal>)</term>
+ <listitem>
+ <para>
+ (Opcional) Un objeto de corta vida, mono-hebra, usado por la aplicación
+ para especificar unidades atómicas de trabajo. Abstrae a la aplicación
+ de las subyacentes transacciones JDBC, JTA o CORBA. En algunos casos, una
+ <literal>Session</literal> puede extenderse sobre varias <literal>Transaction</literal>s.
+ Sin embargo, la demarcación de la transacción, ya sea usando la API
+ subyacente o <literal>Transaction</literal>, nunca es opcional!
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term>
+ <listitem>
+ <para>
+ (Opcional) Una fábrica (y pool) de conexiones JDBC. Abstrae a la aplicación
+ del <literal>Datasource</literal> o <literal>DriverManager</literal> subyacente.
+ No se expone a la aplicación, pero puede ser extendido/implementado por
+ el desarrollador.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term>
+ <listitem>
+ <para>
+ (Opcional) Una fábrica de instancias de <literal>Transaction</literal>.
+ No se expone a la aplicación, pero puede ser extendido/implementado por
+ el desarrollador.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Interfaces de Extensión</emphasis></term>
+ <listitem>
+ <para>
+ Hibernate ofrece muchas interfaces de extensión opcional que puedes
+ implementar para modificar a medida el comportamiento de tu capa de persistencia.
+ Para más detalles, mira la documentación de la API.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ Dada una arquitectura "sencilla", la aplicación pasa por alto las APIs
+ de <literal>Transaction</literal>/<literal>TransactionFactory</literal> y/o
+ <literal>ConnectionProvider</literal>, para hablar directamente a JTA o JDBC.
+ </para>
+ </sect1>
+
+ <sect1 id="architecture-states" revision="1">
+ <title>Estados de instancia</title>
+ <para>
+ Una instancia de una clase persistente puede estar en uno de tres estados
+ diferentes, definidos respecto de su <emphasis>contexto de persistencia</emphasis>.
+ El objeto <literal>Session</literal> de Hibernate es el contexto de persistencia:
+ </para>
+
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>transitorio</term>
+ <listitem>
+ <para>
+ La instancia no está y nunca estuvo asociada con
+ un contexto de persistencia. No tiene identidad persistente
+ (valor de clave primaria).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>persistente</term>
+ <listitem>
+ <para>
+ La instancia está actualmente asociada con un
+ contexto de persistencia. Tiene una identidad persistente
+ (valor de clave primaria) y, quizás, una fila
+ correspondiente en la base de datos. Para un contexto de
+ persistencia en particular, Hibernate <emphasis>garantiza</emphasis>
+ que la identidad persistente es equivalente a la identidad
+ Java (localización en memoria del objeto).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>separado</term>
+ <listitem>
+ <para>
+ La instancia estuvo una vez asociada con un contexto
+ de persistencia, pero ese contexto fue cerrado, o la
+ instancia fue serializada a otro proceso. Tiene una
+ identidad persistente y, quizás, una fila correspondiente
+ en la base de datos. Para las instancias separadas,
+ Hibernate no establece ninguna garantía sobre
+ la relación entre identidad persistente e identidad Java.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 id="architecture-jmx" revision="1">
+ <title>Integración JMX</title>
+
+ <para>
+ JMX es el estándar J2EE para la gestión de componentes Java. Hibernate
+ puede ser gestionado por medio de un servicio estándar JMX.
+ Proveemos una implementación de MBean en la distribución,
+ <literal>org.hibernate.jmx.HibernateService</literal>.
+ </para>
+
+ <para>
+ Para ejemplo de cómo desplegar Hibernate como un servicio JMX en un Servidor
+ de Aplicaciones JBoss, por favor, mira la Guía del Usuario de JBoss.
+ En JBoss AS, tienes además estos beneficios si despliegas usando JMX:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Gestión de Sesión:</emphasis> El ciclo de vida de la <literal>Session</literal>
+ de Hibernate puede estar automáticamente ligado al ámbito de una transacción
+ JTA. Esto significa que ya no tienes que abrir ni cerrar la <literal>Session</literal> manualmente,
+ esto pasa a ser trabajo de un interceptor EJB de JBoss. Además tampoco tienes
+ que preocuparte más de la demarcación de la transacción (a menos que
+ que quieras escribir una capa de persitencia portable, por supuesto, usa la API de
+ <literal>Transaction</literal> de Hibernate para esto). Para acceder a una
+ <literal>Session</literal> llama al <literal>HibernateContext</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Despliegue de HAR:</emphasis> Usualmente despliegas el servicio JMX de Hibernate
+ usando un descriptor de despliegue de servicio de JBoss (en un fichero EAR y/o SAR), que soporta
+ todas las opciones de configuración usuales de una <literal>SessionFactory</literal> de
+ Hibernate. Sin embargo, todavía tienes que nombrar todos tus ficheros de mapeo en el
+ descriptor de despliegue. Si decides usar el depliegue de HAR opcional, JBoss detectará
+ automáticamente todos los ficheros de mapeo en tu fichero HAR.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Para más información sobre estas opciones, consulta la
+ Guía de Usuario del JBoss AS.
+ </para>
+
+ <para>
+ Otra funcionalidad disponible como un servicio JMX son las estadísticas en
+ tiempo de ejecución de Hibernate. Mira <xref linkend="configuration-optional-statistics"/>.
+ </para>
+ </sect1>
+
+ <sect1 id="architecture-jca" revision="1">
+ <title>Soporte JCA:</title>
+ <para>
+ Hiberate puede además ser configurado como un conector JCA. Por favor mira el
+ sitio web para más detalles. Por favor ten en cuenta que el soporte de JCA
+ de Hibernate está aún considerado experimental.
+ </para>
+ </sect1>
+
+</chapter>
+
Copied: core/trunk/documentation/manual/es-ES/src/main/docbook/content/association_mapping.xml (from rev 12794, core/trunk/documentation/manual/es-ES/src/main/docbook/modules/association_mapping.xml)
===================================================================
--- core/trunk/documentation/manual/es-ES/src/main/docbook/content/association_mapping.xml (rev 0)
+++ core/trunk/documentation/manual/es-ES/src/main/docbook/content/association_mapping.xml 2007-10-09 18:45:36 UTC (rev 14075)
@@ -0,0 +1,527 @@
+<chapter id="associations">
+
+ <title>Mapeos de Asociación</title>
+
+ <sect1 id="assoc-intro" revision="1">
+ <title>Introducción</title>
+
+ <para>
+ Los mapeos de asociación son frecuentemente las cosas mas difíciles
+ de hacer correctamente. En esta sección iremos a través de los casos
+ canónicos uno a uno, comenzando con los mapeos unidireccionales, y considerando
+ luego los casos bidireccionales. Usaremos <literal>Person</literal> y <literal>Address</literal>
+ en todos los ejemplos.
+ </para>
+
+ <para>
+ Clasificaremos las asociaciones por cuanto mapeen o no a una tabla
+ de unión interviniente, y por su multiplicidad.
+ </para>
+
+ <para>
+ Las claves foráneas que aceptan valores nulos (en adelante, nullables)
+ no son consideradas una buena práctica en el modelado tradicional de datos,
+ así que todos nuestros ejemplos usan claves foráneas no nullables.
+ Esto no es un requerimiento de Hibernate, y todos los mapeos funcionarán
+ si quitas las restricciones de nulabilidad.
+ </para>
+
+ </sect1>
+
+ <sect1 id="assoc-unidirectional" revision="1">
+ <title>Asociaciones Unidireccionales</title>
+
+ <sect2 id="assoc-unidirectional-m21">
+ <title>muchos a uno</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional muchos-a-uno</emphasis> es el tipo
+ más común de asociaciones unidireccionales.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-121">
+ <title>uno a uno</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional uno-a-uno en una clave primaria</emphasis>
+ es casi idéntica. La única diferencia es la restricción de unicidad
+ de la columna.
+ </para>
+
+ <programlisting><![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>
+ Usualmente, una <emphasis>asociación unidireccional uno-a-uno en una
+ clave primaria</emphasis> usa un generador de id especial. (Observa que hemos
+ invertido el sentido de la asociación en este ejemplo).
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-12m">
+ <title>uno a muchos</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional uno-a-muchos en una clave foránea</emphasis>
+ es un caso muy inusual, y realmente no está recomendada.
+ </para>
+
+ <programlisting><![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>
+ Creemos que es mejor usar una tabla de unión para este tipo de asociación.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-unidirectional-join" revision="1">
+ <title>Asociaciones unidireccionales con tablas de unión</title>
+
+ <sect2 id="assoc-unidirectional-join-12m">
+ <title>uno a muchos</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional uno-a-muchos en una tabla de unión</emphasis>
+ es más preferible. Observa que especificando <literal>unique="true"</literal>, hemos
+ cambiado la multiplicidad de muchos-a-muchos a uno-a-muchos.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-m21">
+ <title>muchos a uno</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional muchos-a-uno en una tabla de unión</emphasis>
+ es bastante común cuando la asociación es opcional.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-121">
+ <title>uno a uno</title>
+
+ <para>
+ Una <emphasis>asociación unidireccional uno-a-uno en una tabla de unión</emphasis>
+ es inusual en extremo, pero posible.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-m2m">
+ <title>muchos a muchos</title>
+
+ <para>
+ Finalmente, tenemos una <emphasis>asociación unidireccional muchos-a-muchos</emphasis>
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-bidirectional" revision="1">
+ <title>Asociaciones Bidireccionales</title>
+
+ <sect2 id="assoc-bidirectional-m21">
+ <title>uno a muchos / muchos a uno</title>
+
+ <para>
+ Una <emphasis>asociación bidireccional muchos-a-uno</emphasis> es
+ el tipo más común de asociación. (Esta es la relación
+ estándar padre/hijo.)
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-121">
+ <title>uno a uno</title>
+
+ <para>
+ Una <emphasis>asociación bidireccional uno-a-uno en una clave foránea</emphasis>
+ es bastante común.
+ </para>
+
+ <programlisting><![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>
+ Una <emphasis>asociación bidireccional uno-a-uno en una clave primaria</emphasis>
+ usa el generador de id especial.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-bidirectional-join" revision="1">
+ <title>Asociaciones bidireccionales con tablas de unión</title>
+
+ <sect2 id="assoc-bidirectional-join-12m">
+ <title>uno a muchos / muchos a uno</title>
+
+ <para>
+ Una <emphasis>asociación bidireccional uno-a-muchos en una tabla de unión</emphasis>.
+ Observa que el <literal>inverse="true"</literal> puede ir a cualquier lado de la asociación,
+ en la colección, o en la unión.
+ </para>
+
+ <programlisting><![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>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-join-121">
+ <title>uno a uno</title>
+
+ <para>
+ Una <emphasis>asociación bidireccional uno-a-uno en una tabla de unión</emphasis>
+ es inusual en extremo, pero posible.
+ </para>
+
+ <programlisting><![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="address"
+ 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>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-join-m2m">
+ <title>muchos a muchos</title>
+
+ <para>
+ Finalmente, tenemos una <emphasis>asociación bidireccional muchos-a-muchos</emphasis>.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses">
+ <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">
+ <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>
+
+ </sect2>
+
+ </sect1>
+
+
+</chapter>
+
Copied: core/trunk/documentation/manual/es-ES/src/main/docbook/content/basic_mapping.xml (from rev 12794, core/trunk/documentation/manual/es-ES/src/main/docbook/modules/basic_mapping.xml)
===================================================================
--- core/trunk/documentation/manual/es-ES/src/main/docbook/content/basic_mapping.xml (rev 0)
+++ core/trunk/documentation/manual/es-ES/src/main/docbook/content/basic_mapping.xml 2007-10-09 18:45:36 UTC (rev 14075)
@@ -0,0 +1,3222 @@
+<chapter id="mapping">
+ <title>Mapeo O/R Básico</title>
+
+ <sect1 id="mapping-declaration" revision="1">
+ <title>Declaración de mapeo</title>
+
+ <para>
+ Los mapeos objeto/relacional se definen usualmente en un documento XML.
+ El documento de mapeo está diseñado para ser leíble y
+ editable a mano. El lenguaje de mapeo es Java-céntrico, o sea que los
+ mapeos se construyen alrededor de declaraciones de clases persistentes,
+ no declaraciones de tablas.
+ </para>
+
+ <para>
+ Observa que, incluso aunque muchos usuarios de Hibernate eligen escribir el
+ XML a mano, existe una cantidad de herramientas para generar el documento de
+ mapeo, incluyendo XDoclet, Middlegen y AndroMDA.
+ </para>
+
+ <para>
+ Comencemos por un mapeo de ejemplo:
+ </para>
+
+ <programlisting id="mapping-declaration-ex1" revision="1"><![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="Cat"
+ table="cats"
+ discriminator-value="C">
+
+ <id name="id">
+ <generator class="native"/>
+ </id>
+
+ <discriminator column="subclass"
+ type="character"/>
+
+ <property name="weight"/>
+
+ <property name="birthdate"
+ type="date"
+ not-null="true"
+ update="false"/>
+
+ <property name="color"
+ type="eg.types.ColorUserType"
+ not-null="true"
+ update="false"/>
+
+ <property name="sex"
+ not-null="true"
+ update="false"/>
+
+ <property name="litterId"
+ column="litterId"
+ update="false"/>
+
+ <many-to-one name="mother"
+ column="mother_id"
+ update="false"/>
+
+ <set name="kittens"
+ inverse="true"
+ order-by="litter_id">
+ <key column="mother_id"/>
+ <one-to-many class="Cat"/>
+ </set>
+
+ <subclass name="DomesticCat"
+ discriminator-value="D">
+
+ <property name="name"
+ type="string"/>
+
+ </subclass>
+
+ </class>
+
+ <class name="Dog">
+ <!-- mapping for Dog could go here -->
+ </class>
+
+</hibernate-mapping>]]></programlisting>
+
+ <para>
+ Discutiremos ahora el contenido del documento de mapeo. Describiremos sólo los
+ elementos y atributos que son usados por Hibernate en tiempo de ejecución. El
+ documento de mapeo contiene además algunos atributos y elementos extra opcionales
+ que afectan los esquemas de base de datos exportados por la herramienta de exportación
+ de esquemas. (Por ejemplo, el atributo <literal>not-null</literal>.)
+ </para>
+
+
+
+ <sect2 id="mapping-declaration-doctype" revision="2">
+ <title>Doctype</title>
+
+ <para>
+ Todos los mapeos XML deben declarar el doctype mostrado. El DTD actual puede
+ ser encontrado en el URL mencionado arriba, en el directorio
+ <literal>hibernate-x.x.x/src/org/hibernate</literal>, o en <literal>hibernate3.jar</literal>.
+ Hibernate siempre buscará el DTD primero en el classpath. Si experimentas
+ búsquedas del DTD usando una conexión de Internet, chequea tu declaración
+ de DTD contra la contenida en el classpath.
+ </para>
+ </sect2>
+
+ <sect2 id="mapping-declaration-mapping" revision="3">
+ <title>hibernate-mapping</title>
+
+ <para>
+ Este elemento tiene muchos atributos opcionales. Los atributos <literal>schema</literal>
+ y <literal>catalog</literal> especifican que las tablas a las que se refiere en el mapeo
+ pertenecen al esquema y/o catálogo mencionado(s). De especificarse, los nombres de
+ tablas serán cualificados por el nombre de esquema y catálogo dados.
+ De omitirse, los nombres de tablas no serán cualificados. El atributo
+ <literal>default-cascade</literal> especifica qué estilo de cascada debe asumirse
+ para las propiedades y colecciones que no especifican un atributo <literal>cascade</literal>.
+ El atributo <literal>auto-import</literal> nos permite usar nombres de clase sin cualificar
+ en el lenguaje de consulta, por defecto.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="hm1" coords="2 55"/>
+ <area id="hm2" coords="3 55"/>
+ <area id="hm3" coords="4 55"/>
+ <area id="hm4" coords="5 55"/>
+ <area id="hm5" coords="6 55"/>
+ <area id="hm6" coords="7 55"/>
+ <area id="hm7" coords="8 55"/>
+ </areaspec>
+ <programlisting><![CDATA[<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"
+ />]]></programlisting>
+ <calloutlist>
+ <callout arearefs="hm1">
+ <para>
+ <literal>schema</literal> (opcional): El nombre de un esquema de la base de datos.
+ </para>
+ </callout>
+ <callout arearefs="hm2">
+ <para>
+ <literal>catalog</literal> (opcional): El nombre de un catálogo de la base de datos.
+ </para>
+ </callout>
+ <callout arearefs="hm3">
+ <para>
+ <literal>default-cascade</literal> (opcional - por defecto a <literal>none</literal>):
+ Un estilo de cascada por defecto.
+ </para>
+ </callout>
+ <callout arearefs="hm4">
+ <para>
+ <literal>default-access</literal> (opcional - por defecto a <literal>property</literal>):
+ La estrategia que Hibernate debe usar para acceder a todas las propiedades.
+ Puede ser una implementación personalizada de <literal>PropertyAccessor</literal>.
+ </para>
+ </callout>
+ <callout arearefs="hm5">
+ <para>
+ <literal>default-lazy</literal> (opcional - por defecto a <literal>true</literal>):
+ El valor por defecto para los atributos <literal>lazy</literal> de mapeos de clase
+ y colleción no especificados.
+ </para>
+ </callout>
+ <callout arearefs="hm6">
+ <para>
+ <literal>auto-import</literal> (opcional - por defecto a <literal>true</literal>):
+ Especifica si podemos usar nombres de clases no cualificados (de clases en este mapeo)
+ en el lenguaje de consulta.
+ </para>
+ </callout>
+ <callout arearefs="hm7">
+ <para>
+ <literal>package</literal> (opcional): Especifica un prefijo de paquete a asumir
+ para los nombres no cualificados de clase en el documento de mapeo.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Si tienes dos clases persistentes con el mismo nombre (sin cualificar), debes establecer
+ <literal>auto-import="false"</literal>. Hibernate lanzará una excepción si
+ intentas asignar dos clases al mismo nombre "importado".
+ </para>
+
+ <para>
+ Observa que el elemento <literal>hibernate-mapping</literal> te permite anidar
+ muchos mapeos <literal><class></literal> persistentes, como se muestra arriba.
+ Sin embargo, es una buena práctica (y se espera de algunas herramientas) mapear
+ sólo a una sola clase persistente (o a una sola jerarquía de clases) en
+ un fichero de mapeo y nombrarlo después de la superclase persistente;
+ por ejemplo, <literal>Cat.hbm.xml</literal>, <literal>Dog.hbm.xml</literal>,
+ o, si se usa herencia, <literal>Animal.hbm.xml</literal>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-class" revision="3">
+ <title>class</title>
+
+ <para>
+ Puedes declarar una clase persistente usando el elemento <literal>class</literal>:
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="class1" coords="2 55"/>
+ <area id="class2" coords="3 55" />
+ <area id="class3" coords="4 55"/>
+ <area id="class4" coords="5 55" />
+ <area id="class5" coords="6 55"/>
+ <area id="class6" coords="7 55" />
+ <area id="class7" coords="8 55"/>
+ <area id="class8" coords="9 55" />
+ <area id="class9" coords="10 55" />
+ <area id="class10" coords="11 55"/>
+ <area id="class11" coords="12 55"/>
+ <area id="class12" coords="13 55"/>
+ <area id="class13" coords="14 55"/>
+ <area id="class14" coords="15 55"/>
+ <area id="class15" coords="16 55"/>
+ <area id="class16" coords="17 55"/>
+ <area id="class17" coords="18 55"/>
+ <area id="class18" coords="19 55"/>
+ <area id="class19" coords="20 55"/>
+ <area id="class20" coords="21 55"/>
+ <area id="class21" coords="22 55"/>
+ </areaspec>
+ <programlisting><![CDATA[<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"
+/>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="class1">
+ <para>
+ <literal>name</literal> (opcional): El nombre completamente cualificado de la clase
+ Java persistente (o interface). Si este atributo es omitido, se asume que el mapeo
+ es para una entidad non-POJO.
+ </para>
+ </callout>
+ <callout arearefs="class2">
+ <para>
+ <literal>table</literal> (opcional - por defecto al nombre no cualificado de la clase):
+ El nombre de su tabla en base de datos.
+ </para>
+ </callout>
+ <callout arearefs="class3">
+ <para>
+ <literal>discriminator-value</literal> (opcional - por defecto al nombre de la clase):
+ Un valor que distingue subclases individuales, usado para el comportamiento
+ polimórfico. Los valores aceptables incluyen <literal>null</literal>
+ y <literal>not null</literal>.
+ </para>
+ </callout>
+ <callout arearefs="class4">
+ <para>
+ <literal>mutable</literal> (opcional, por defecto a <literal>true</literal>):
+ Especifica que las instancias de la clase (no) son mutables.
+ </para>
+ </callout>
+ <callout arearefs="class5">
+ <para>
+ <literal>schema</literal> (opcional): Sobreescribe el nombre de esquema especificado
+ por el elemento raíz <literal><hibernate-mapping></literal>.
+ </para>
+ </callout>
+ <callout arearefs="class6">
+ <para>
+ <literal>catalog</literal> (opcional): Sobreescribe el nombre de catálogo
+ especificado por el elemento raíz <literal><hibernate-mapping></literal>.
+ </para>
+ </callout>
+ <callout arearefs="class7">
+ <para>
+ <literal>proxy</literal> (opcional): Especifica una interface a usar para proxies
+ de inicialización perezosa. Puedes especificar el nombre mismo de la clase.
+ </para>
+ </callout>
+ <callout arearefs="class8">
+ <para>
+ <literal>dynamic-update</literal> (opcional, por defecto a <literal>false</literal>):
+ Especifica que el SQL <literal>UPDATE</literal> debe ser generado en tiempo de
+ ejecución y contener solamente aquellas columnas cuyo valor haya cambiado.
+ </para>
+ </callout>
+ <callout arearefs="class9">
+ <para>
+ <literal>dynamic-insert</literal> (opcional, por defecto a <literal>false</literal>):
+ Especifica que el SQL <literal>INSERT</literal> debe ser generado en tiempo de
+ ejecución y contener solamente aquellas columnas cuyo valores no son nulos.
+ </para>
+ </callout>
+ <callout arearefs="class10">
+ <para>
+ <literal>select-before-update</literal> (opcional, por defecto a <literal>false</literal>):
+ Especifica que Hibernate <emphasis>nunca</emphasis> debe realizar un SQL <literal>UPDATE</literal>
+ a menos que se tenga certeza que un objeto haya sido modificado realmente.
+ En ciertos casos, (realmente, sólo cuando un objeto transitorio ha sido asociado
+ con una sesión nueva usando <literal>update()</literal>), esto significa que Hibernate
+ realizará una SQL <literal>SELECT</literal> extra para determinar si un
+ <literal>UPDATE</literal> es realmente requerido.
+ </para>
+ </callout>
+ <callout arearefs="class11">
+ <para>
+ <literal>polymorphism</literal> (opcional, por defecto a <literal>implicit</literal>):
+ Determina si se usa polimorfismo de consulta implícito o explícito.
+ </para>
+ </callout>
+ <callout arearefs="class12">
+ <para>
+ <literal>where</literal> (opcional) especifica una condición SQL <literal>WHERE</literal>
+ arbitraria paraa ser usada al recuperar objetos de esta clase.
+ </para>
+ </callout>
+ <callout arearefs="class13">
+ <para>
+ <literal>persister</literal> (opcional): Especifica un <literal>ClassPersister</literal>
+ personalizado.
+ </para>
+ </callout>
+ <callout arearefs="class14">
+ <para>
+ <literal>batch-size</literal> (opcional, por defecto a <literal>1</literal>)
+ especifica un "tamaño de lote" para traer instancias de esta clase por
+ identificador.
+ </para>
+ </callout>
+ <callout arearefs="class15">
+ <para>
+ <literal>optimistic-lock</literal> (opcional, por defecto a <literal>version</literal>):
+ Determina la estrategia optimista de bloqueo.
+ </para>
+ </callout>
+ <callout arearefs="class16">
+ <para>
+ <literal>lazy</literal> (opcional):
+ La recuperación perezosa puede ser deshabilitada por completo estableciendo
+ <literal>lazy="false"</literal>.
+ </para>
+ </callout>
+ <callout arearefs="class17">
+ <para>
+ <literal>entity-name</literal> (opcional): Hibernate3 permite que una clase sea
+ mapeada varias veces (potencialmente a tablas diferentes), y permite que los mapeos
+ de entidad sean representados por Maps o XML al nivel de Java. En estos casos,
+ debes proveer un nombre explícito arbitrario para la entidad.
+ Para más información, mira
+ <xref linkend="persistent-classes-dynamicmodels"/> y <xref linkend="xml"/>.
+ </para>
+ </callout>
+ <callout arearefs="class18">
+ <para>
+ <literal>check</literal> (opcional): Una expresión SQL usada para generar
+ una restricción <emphasis>check</emphasis> multi-fila para la generación
+ automática de esquema.
+ </para>
+ </callout>
+ <callout arearefs="class19">
+ <para>
+ <literal>rowid</literal> (opcional): Hibernate puede usar los llamados ROWIDs en las
+ bases de datos que los soporten. Por ejemplo, en Oracle, Hibernate puede usar la columna
+ extra <literal>rowid</literal> para actualizaciones rápidas si estableces esta
+ opción a <literal>rowid</literal>. Un ROWID es un detalle de implementación
+ y representa la posición física de la tupla almacenada.
+ </para>
+ </callout>
+ <callout arearefs="class20">
+ <para>
+ <literal>subselect</literal> (opcional): Mapea una entidad inmutable y de sólo
+ lectura a una subselect de base de datos. Es útil si quieres tener una vista
+ en vez de una tabla base, pero no tienes vistas. Mira debajo para más información.
+ </para>
+ </callout>
+ <callout arearefs="class21">
+ <para>
+ <literal>abstract</literal> (opcional): Usado para marcar superclases abstractas en
+ jerarquías <literal><union-subclass></literal>.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Es perfectamente aceptable que la clase persistente mencionada sea una interface.
+ Entonces declararías clases que implementan esa interface usando el elemento
+ <literal><subclass></literal>. Puedes persistir cualquier clase interna
+ <emphasis>estática</emphasis>. Debes especificar el nombre de la clase usando la forma
+ estándar. Por ejemplo, <literal>eg.Foo$Bar</literal>.
+ </para>
+
+ <para>
+ Las clases inmutables, <literal>mutable="false"</literal>, no pueden ser actualizadas o
+ borradas por la aplicación. Esto permite a Hibernate hacer ciertas optimizaciones
+ menores de rendimiento.
+ </para>
+
+ <para>
+ El atributo opcional <literal>proxy</literal> habilita la inicialización postergada
+ de instancias persistentes de la clase. Hibernate inicialmente retornará proxies
+ CGLIB que implementan la interface mencionada. El objeto persistente real será
+ cargado cuando se invoque un método del proxy. Mira "Proxies para Inicialización
+ Postergada" debajo.
+ </para>
+
+ <para>
+ Por polimorfismo <emphasis>implícito</emphasis> se entiende que las instancias de la clase
+ serán devueltas por una consulta que mencione cualquier superclase, o interface implementada,
+ o la clase misma; y que las instancias de cualquier subclase de la clase serán devueltas
+ por una clase que mencione a la clase en sí.
+ Por polimorfismo <emphasis>explícito</emphasis> se entiende que instancias de la clase
+ serán devueltas sólo por consultas que mencionen explícitamente la clase;
+ y que las consultas que mencionen la clase devolverán sólo instancias de subclases
+ mapeadas dentro de esta declaración <literal><class></literal> como una
+ <literal><subclass></literal> o <literal><joined-subclass></literal>.
+ Para la mayoría de los propósitos el defecto,
+ <literal>polymorphism="implicit"</literal>, resulta apropiado.
+ El polimorfismo explícito es útil cuando dos clases diferentes están
+ mapeadas a la misma tabla (esto permite tener una clase "liviana" que contenga un subconjunto
+ de columnas de la tabla).
+ </para>
+
+ <para>
+ El atributo <literal>persister</literal> te permite personalizar la estrategia de persistencia
+ para la clase. Puedes, por ejemplo, especificar tu propia subclase de
+ <literal>org.hibernate.persister.EntityPersister</literal> o incluso puedes proveer una implementación
+ completamente nueva de la interface <literal>org.hibernate.persister.ClassPersister</literal> que implemente
+ la persistencia por medio, por ejemplo, de llamadas a procedimientos almacenados, serialización a
+ ficheros planos o LDAP. Para un ejemplo simple (de persistencia a una <literal>Hashtable</literal>) mira
+ <literal>org.hibernate.test.CustomPersister</literal>.
+ </para>
+
+ <para>
+ Observa que los valores de <literal>dynamic-update</literal> y <literal>dynamic-insert</literal>
+ no son heredados por las subclases y por lo tanto deben especificarse en los elementos
+ <literal><subclass></literal> o <literal><joined-subclass></literal>.
+ Estos ajustes pueden incrementar el rendimiento en algunos casos, pero podrían mermarlo en otros.
+ Ten juicio en su uso.
+ </para>
+
+ <para>
+ Generalmente el uso de <literal>select-before-update</literal> disminuirá el rendimiento.
+ Es muy útil prevenir que se llame innecesariamente a un disparador de actualización de
+ base de datos al volver a unir un grafo de instancias separadas a una <literal>Session</literal>.
+ </para>
+
+ <para>
+ Si habilitas <literal>dynamic-update</literal>, tendrás opción de estrategias
+ de bloqueo optimistas:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>version</literal> chequea las columnas de versión/timestamp
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>all</literal> chequea todas las columnas
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>dirty</literal> chequea las columnas modificadas, permitiendo algunas
+ actualizaciones concurrentes
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>none</literal> no usa bloqueo optimista
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Recomendamos <emphasis>muy</emphasis> fuertemente que uses columnas de
+ versión/timestamp para bloqueo optimista con Hibernate. Esta es la estrategia
+ óptima con respecto al rendimiento y es la única estrategia que maneja
+ correctamente las modificaciones hechas a las instancias separadas.
+ (por ejemplo, cuando se usa <literal>Session.merge()</literal>).
+ </para>
+
+ <para>
+ Para un mapeo de Hibernate, no hay diferencia entre una vista y una tabla base.
+ Como se supone esto es transparente a nivel de base de datos (observa que algunos
+ DBMS no soportan correctamente las vistas, especialmente con las actualizaciones).
+ A veces quieres usar una vista, pero no puedes crear una en la base de datos
+ (por ejemplo, con un esquema heredado). En este caso, puedes mapear una entidad inmutable
+ de sólo lectura a una expresión de subconsulta SQL dada.
+ </para>
+
+ <programlisting><![CDATA[<class name="Summary">
+ <subselect>
+ select item.name, max(bid.amount), count(*)
+ from item
+ join bid on bid.item_id = item.id
+ group by item.name
+ </subselect>
+ <synchronize table="item"/>
+ <synchronize table="bid"/>
+ <id name="name"/>
+ ...
+</class>]]></programlisting>
+
+ <para>
+ Declara las tablas con las que sincronizar esta entidad, asegurando que el auto-flush
+ ocurre correctamente, y que las consultas contra la entidad derivada no devuelven datos
+ desactualizados. El <literal><subselect></literal> está disponible tanto
+ como un atributo o como un elemento anidado de mapeo.
+ </para>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-id" revision="3">
+ <title>id</title>
+
+ <para>
+ Las clases mapeadas <emphasis>deben</emphasis> declarar la columna de clave primaria de la tabla
+ de la base de datos. En la mayoría de los casos tendrá también una propiedad
+ estilo Javabeans que tenga el identificador único de una instancia. El elemento
+ <literal><id></literal> define el mapeo de esa propiedad a la columna de clave primaria.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="id1" coords="2 70"/>
+ <area id="id2" coords="3 70" />
+ <area id="id3" coords="4 70"/>
+ <area id="id4" coords="5 70" />
+ <area id="id5" coords="6 70" />
+ </areaspec>
+ <programlisting><![CDATA[<id
+ name="propertyName"
+ type="typename"
+ column="column_name"
+ unsaved-value="null|any|none|undefined|id_value"
+ access="field|property|ClassName"
+ node="element-name|@attribute-name|element/@attribute|.">
+
+ <generator class="generatorClass"/>
+</id>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="id1">
+ <para>
+ <literal>name</literal> (opcional): El nombre de la propiedad del indentificador.
+ </para>
+ </callout>
+ <callout arearefs="id2">
+ <para>
+ <literal>type</literal> (opcional): Un nombre que indica el tipo Hibernate.
+ </para>
+ </callout>
+ <callout arearefs="id3">
+ <para>
+ <literal>column</literal> (opcional - por defecto al nombre de la propiedad):
+ El nombre de la columna de clave primaria.
+ </para>
+ </callout>
+ <callout arearefs="id4">
+ <para>
+ <literal>unsaved-value</literal> (opcional - por defecto al valor "sensible"):
+ Una valor de la propiedad identificadora que indica que una instancia está
+ recién instanciada (sin salvar), distinguiéndola de instancias separadas
+ que fueran salvadas o cargadas en una sesión previa.
+ </para>
+ </callout>
+ <callout arearefs="id5">
+ <para>
+ <literal>access</literal> (opcional - por defecto a <literal>property</literal>):
+ La estrategia que Hibernate debe usar para acceder al valor de la propiedad.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Si se omite el atributo <literal>name</literal>, se asume que la clase no tiene propiedad
+ identificadora.
+ </para>
+
+ <para>
+ El atributo <literal>unsaved-value</literal> es importante! Si la propiedad identificadora de tu
+ clase no tiene por defecto el valor por defecto normal de Java (null o cero), entonces debes especificar
+ el valor por defecto real.
+ </para>
+
+ <para>
+ Hay una declaración <literal><composite-id></literal> alternativa para permitir acceso
+ a datos heredados con claves compuestas. Desalentamos fuertemente su uso para cualquier otra cosa.
+ </para>
+
+ <sect3 id="mapping-declaration-id-generator" revision="2">
+ <title>Generator</title>
+
+ <para>
+ El elemento hijo opcional <literal><generator></literal> nombra una clase Java
+ usada en generar identificadores únicos para instancias de la clase persistente.
+ De requerirse algún parámetro para configurar o inicializar la instancia del generador,
+ se pasa usando el elemento <literal><param></literal>.
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="org.hibernate.id.TableHiLoGenerator">
+ <param name="table">uid_table</param>
+ <param name="column">next_hi_value_column</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ Todos los generadores implementan la interface <literal>org.hibernate.id.IdentifierGenerator</literal>.
+ Esta es una interface muy simple; algunas aplicaciones pueden escoger proveer sus propias
+ implementaciones especializadas. Sin embargo, Hibernate provee un rango de implementaciones
+ prefabricadas. Hay nombres alias de atajo para los generadores prefabricados:
+ <variablelist>
+ <varlistentry>
+ <term><literal>increment</literal></term>
+ <listitem>
+ <para>
+ genera indentificadores de tipo <literal>long</literal>, <literal>short</literal> o
+ <literal>int</literal> que sólo son únicos cuando ningún otro proceso
+ está insertando datos en la misma tabla. <emphasis>No usar en un cluster.</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>identity</literal></term>
+ <listitem>
+ <para>
+ soporta columnas de identidad en DB2, MySQL, MS SQL Server, Sybase y
+ HypersonicSQL. El identificador devuelto es de tipo <literal>long</literal>,
+ <literal>short</literal> o <literal>int</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>sequence</literal></term>
+ <listitem>
+ <para>
+ usa una secuencia en DB2, PostgreSQL, Oracle, SAP DB, McKoi o un generador
+ en Interbase. El identificador devuelto es de tipo <literal>long</literal>,
+ <literal>short</literal> o <literal>int</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>hilo</literal></term>
+ <listitem>
+ <para id="mapping-declaration-id-hilodescription" revision="1">
+ usa un algoritmo alto/bajo para generar eficientemente identificadores de tipo
+ <literal>long</literal>, <literal>short</literal> o <literal>int</literal>,
+ dada una tabla y columna como fuente de valores altos (por defecto
+ <literal>hibernate_unique_key</literal> y <literal>next_hi</literal> respectivamente).
+ El algoritmo alto/bajo genera identificadores que son únicos sólo para una
+ base de datos particular.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>seqhilo</literal></term>
+ <listitem>
+ <para>
+ usa un algoritmo alto/bajo para generar eficientemente identificadores de tipo
+ <literal>long</literal>, <literal>short</literal> o <literal>int</literal>,
+ dada una secuencia de base de datos.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>uuid</literal></term>
+ <listitem>
+ <para>
+ usa un algoritmo UUID de 128 bits para generar identificadore de tipo
+ cadena, únicos en una ref (se usa la direccón IP). El UUID
+ se codifica como una cadena hexadecimal de 32 dígitos de largo.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>guid</literal></term>
+ <listitem>
+ <para>
+ usa una cadena GUID generada por base de datos en MS SQL Server y MySQL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>native</literal></term>
+ <listitem>
+ <para>
+ selecciona <literal>identity</literal>, <literal>sequence</literal> o
+ <literal>hilo</literal> dependiendo de las capacidades de la base de datos
+ subyacente.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>assigned</literal></term>
+ <listitem>
+ <para>
+ deja a la aplicación asignar un identificador al objeto antes
+ de que se llame a <literal>save()</literal>. Esta es la estrategia
+ por defecto si no se especifica un elemento <literal><generator></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>select</literal></term>
+ <listitem>
+ <para>
+ recupera una clave primaria asignada por un disparador de base de datos
+ seleccionando la fila por alguna clave única y recuperando el valor de
+ la clave primaria.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>foreign</literal></term>
+ <listitem>
+ <para>
+ usa el identificador de otro objeto asociado. Generalmente usado en conjuncón
+ a una asociacón de clave primaria <literal><uno-a-uno></literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-hilo" revision="1">
+ <title>Algoritmo alto/bajo</title>
+ <para>
+ Los generadores <literal>hilo</literal> y <literal>seqhilo</literal> proveen dos implementaciones
+ alternativas del algoritmo alto/bajo, un enfoque favorito en generación de identificadores.
+ La primera implementación requiere de una tabla "especial" de base de datos para tener el siguiente
+ valor "alto" disponible.
+ La segunda usa una secuencia del estilo de Oracle (donde se soporte).
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="hilo">
+ <param name="table">hi_value</param>
+ <param name="column">next_value</param>
+ <param name="max_lo">100</param>
+ </generator>
+</id>]]></programlisting>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="seqhilo">
+ <param name="sequence">hi_value</param>
+ <param name="max_lo">100</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ Desafortunadamente, no puedes usar <literal>hilo</literal> cuando le proveas tu propia
+ <literal>Connection</literal> a Hibernate. Cuando Hibernate está usando un datasource
+ del servidor de aplicaciones para obtener conexiones alistadas con JTA, debes configurar
+ correctamente el <literal>hibernate.transaction.manager_lookup_class</literal>.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-uuid">
+ <title>Algoritmo UUID</title>
+ <para>
+ El UUID contiene: la dirección IP, el instante de arranque de la JVM
+ (con una precisión de un cuarto de segundo), el tiempo de sistema y un valor
+ de contador (único en la JVM). No es posible obtener una dirección MAC o
+ una dirección de memoria desde código Java, así que esto es lo mejor
+ que podemos hacer sin usar JNI.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-sequences">
+ <title>Columnas de identidad y secuencias</title>
+ <para>
+ Para las bases de datos que soportan columnas de identidad (DB2, MySQL, Sybase, MS SQL),
+ puedes usar generación de claves <literal>identity</literal>. Para las bases de datos
+ que soportan secuencias (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) puedes usar la generación
+ de claves del estilo <literal>sequence</literal>. Ambas estrategias requieren dos consultas SQL
+ para insertar un nuevo objeto.
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id">
+ <generator class="sequence">
+ <param name="sequence">person_id_sequence</param>
+ </generator>
+</id>]]></programlisting>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id" unsaved-value="0">
+ <generator class="identity"/>
+</id>]]></programlisting>
+
+ <para>
+ Para desarrollos multiplataforma, la estrategia <literal>native</literal>
+ eiligirá de entre las estrategias <literal>identity</literal>,
+ <literal>sequence</literal> y <literal>hilo</literal>, dependiendo de las capacidades
+ de la base de datos subyacentes.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-assigned">
+ <title>Identificadores asignados</title>
+ <para>
+ Si quieres que la aplicación asigne los identificadores (en contraposición
+ a que los genere Hibernate), puedes usar el generador <literal>assigned</literal>.
+ Este generador especial usará el valor identificador ya asignado a la
+ propiedad identificadora del objeto. Este generador se usa cuandola clave primaria es
+ una clave natural en vez de una clave sustituta. Este es el comportamiento por defecto si
+ no especificas un elemento <literal><generator></literal>.
+ </para>
+
+ <para>
+ Elegir el generador <literal>assigned</literal> hace que Hibernate use
+ <literal>unsaved-value="undefined"</literal>, forzando a Hibernate a ir
+ a la base de datos para determinar si una instancia es transitoria o separada,
+ a menos que haya una propiedad de versión o timestamp, o que tu definas
+ <literal>Interceptor.isUnsaved()</literal>.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-select">
+ <title>Claves primarias asignadas por disparadores</title>
+ <para>
+ Para esquemas heredados solamente (Hibernate no genera DDL con disparadores).
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id">
+ <generator class="select">
+ <param name="key">socialSecurityNumber</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ En el ejemplo de arriba, hay una propiedad ánica llamada
+ <literal>socialSecurityNumber</literal> definida por la clase, como
+ una clave natural, y una clave sustituta llamada <literal>person_id</literal>
+ cuyo valor es generado por un disparador.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-compositeid" revision="2">
+ <title>composite-id</title>
+
+ <programlisting><![CDATA[<composite-id
+ name="propertyName"
+ class="ClassName"
+ unsaved-value="undefined|any|none"
+ access="field|property|ClassName"
+ node="element-name|.">
+
+ <key-property name="propertyName" type="typename" column="column_name"/>
+ <key-many-to-one name="propertyName class="ClassName" column="column_name"/>
+ ......
+</composite-id>]]></programlisting>
+
+ <para>
+ Para una tabla con clave compuesta, puedes mapear múltiples propiedades
+ de la clase como propiedades identificadoras. El elemento <literal><composite-id></literal>
+ acepta los mapeos de propiedad <literal><key-property></literal> y
+ los mapeos <literal><key-many-to-one></literal> como elementos hijo.
+ </para>
+
+ <programlisting><![CDATA[<composite-id>
+ <key-property name="medicareNumber"/>
+ <key-property name="dependent"/>
+</composite-id>]]></programlisting>
+
+ <para>
+ Tu clase persistente <emphasis>debe</emphasis> sobreescribir <literal>equals()</literal>
+ y <literal>hashCode()</literal> para implementar igualdad de identificador compuesto.
+ Debe también implementar <literal>Serializable</literal>.
+ </para>
+
+ <para>
+ Desafortunadamente, este enfoque de identificadores compuestos significa que un objeto
+ persistente es su propio identificador. No existe otra "asa" conveniente más que el
+ objeto mismo. Debes instanciar una instancia de la clase misma y poblar sus propiedades
+ identificadoras antes que puedas <literal>load()</literal> el estado persistente asociado
+ a una clave compuesta. Describiremos un enfoque mucho más conveniente donde el identificador
+ compuesto está implementado como una clase separada en <xref linkend="components-compositeid"/>.
+ Los atributos descriptos debajo solamente se aplican a este enfoque alternativo:
+ </para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>name</literal> (opcional): Una propiedad de tipo componente que tiene el identificador
+ compuesto (ver siguiente sección).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>class</literal> (opcional - por defecto al tipo de la propiedad determinado
+ por reflección): La clase del componente usado como identificador compuesto (ver siguiente sección).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>unsaved-value</literal> (opcional - por defecto a <literal>undefined</literal>):
+ Indica que las instancias transitorias deben ser consideradas como recién instanciadas,
+ si se establece a <literal>any</literal>, o separadas, si se establece a <literal>none</literal>.
+ Lo mejor
+
+ Indicates that transient instances should be considered newly instantiated, if set
+ to <literal>any</literal>, or detached, if set to <literal>none</literal>.
+ Lo mejor en todos los casos es dejar el valor por defecto.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-discriminator" revision="3">
+ <title>discriminator</title>
+
+ <para>
+ El elemento <literal><discriminator></literal> es requerido para la persistencia
+ polimórfica usando la estrategia de mapeo de tabla-por-jerarquía-de-clases y
+ declara una columna discriminadora de la tabla. La columna discriminidora contiene valores
+ de marca que le dicen a la capa de persistencia qué subclase instanciar para una fila
+ en particular. Un conjunto restringido de tipos puede ser usado:
+ <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>
+
+ <programlistingco>
+ <areaspec>
+ <area id="discriminator1" coords="2 60"/>
+ <area id="discriminator2" coords="3 60" />
+ <area id="discriminator3" coords="4 60" />
+ <area id="discriminator4" coords="5 60" />
+ <area id="discriminator5" coords="6 60" />
+ </areaspec>
+ <programlisting><![CDATA[<discriminator
+ column="discriminator_column"
+ type="discriminator_type"
+ force="true|false"
+ insert="true|false"
+ formula="arbitrary sql expression"
+/>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="discriminator1">
+ <para>
+ <literal>column</literal> (opcional - por defecto a <literal>class</literal>) el
+ nombre de la columna discriminadora.
+ </para>
+ </callout>
+ <callout arearefs="discriminator2">
+ <para>
+ <literal>type</literal> (opcional - por defecto a <literal>string</literal>) un
+ nombre que indique el tipo Hibernate
+ </para>
+ </callout>
+ <callout arearefs="discriminator3">
+ <para>
+ <literal>force</literal> (optconal - por defecto a <literal>false</literal>)
+ "fuerza" a Hibernate a especificar valores discriminadores permitidos incluso
+ cuando se recuperan todas las instancias de la clase raíz.
+ </para>
+ </callout>
+ <callout arearefs="discriminator4">
+ <para>
+ <literal>insert</literal> (opcional - por defecto a <literal>true</literal>)
+ establezca este a <literal>false</literal> si tu columna discriminadora es
+ también parte de un identificador mapeado compuesto. (Le dice a Hibernate
+ que no incluya la columna en los SQL <literal>INSERT</literal>s.)
+ </para>
+ </callout>
+ <callout arearefs="discriminator5">
+ <para>
+ <literal>formula</literal> (opcional) una expresión SQL arbitraria que
+ es ejecutada cuando un tipo tenga que ser evaluado. Permite dicriminación
+ basada en el contenido.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Los valores reales de la columna discriminadora están especificados por
+ el atributo <literal>discriminator-value</literal> de los elementos
+ <literal><class></literal> y <literal><subclass></literal>.
+ </para>
+
+ <para>
+ El atributo <literal>force</literal> es (sólo) útil si la tabla contiene
+ filas con valores discriminadores "extra" que no están mapeados a la clase
+ persistente. Generalmente este no es el caso.
+ </para>
+
+ <para>
+ Usando el atributo <literal>formula</literal> puedes declarar una expresión SQL
+ arbitraria que será usada para evaluar el tipo de una fila:
+ </para>
+
+ <programlisting><![CDATA[<discriminator
+ formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
+ type="integer"/>]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-version" revision="1">
+ <title>version (opcional)</title>
+
+ <para>
+ El elemento <literal><version></literal> es opcional e indica que la
+ tabla contiene datos versionados. Esto es particularmente útil si planeas
+ usar <emphasis>transacciones largas</emphasis> (ver debajo).
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="version1" coords="2 70"/>
+ <area id="version2" coords="3 70"/>
+ <area id="version3" coords="4 70"/>
+ <area id="version4" coords="5 70"/>
+ <area id="version5" coords="6 70"/>
+ </areaspec>
+ <programlisting><![CDATA[<version
+ column="version_column"
+ name="propertyName"
+ type="typename"
+ access="field|property|ClassName"
+ unsaved-value="null|negative|undefined"
+ node="element-name|@attribute-name|element/@attribute|."
+/>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="version1">
+ <para>
+ <literal>column</literal> (opcional - por defecto al nombre de la propiedad): El nombre
+ de la columna que tiene el número de versión.
+ </para>
+ </callout>
+ <callout arearefs="version2">
+ <para>
+ <literal>name</literal>: El nombre de una propiedad de la clase persistente.
+ </para>
+ </callout>
+ <callout arearefs="version3">
+ <para>
+ <literal>type</literal> (opcional - por defecto a <literal>integer</literal>):
+ El tipo del nú.mero de vesión.
+ </para>
+ </callout>
+ <callout arearefs="version4">
+ <para>
+ <literal>access</literal> (opcional - por defecto a <literal>property</literal>): La
+ estrategia que Hibernate debe usar para acceder al valor de la propiedad.
+ </para>
+ </callout>
+ <callout arearefs="version5">
+ <para>
+ <literal>unsaved-value</literal> (opcional - por defecto a <literal>undefined</literal>):
+ Un valor de la propiedad de versión que indica que una instancia está
+ recién instanciada (sin guardar), distinguiéndola de instancias
+ separadas que fueran guardadas o cargadas en una sesión previa.
+ (<literal>undefined</literal> especifica que debe usarse el valor de la
+ propiedad identificadora.)
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Los números de versión deben ser de tipo <literal>long</literal>,
+ <literal>integer</literal>, <literal>short</literal>, <literal>timestamp</literal> o
+ <literal>calendar</literal> de Hibernate.
+ </para>
+
+ <para>
+ Una propiedad de versión o timestamp nunca debe ser nula para una instancia
+ separada, de modo que Hibernate detectará cualquier instancia con una versión
+ o timestamp nulo como transitoria, sin importar qué otras estrategias
+ <literal>unsaved-value</literal> se hayan especificado.
+ <emphasis>Declarar una propiedad de versón o timestamp nulable es una forma
+ fácil de evitar cualquier problema con la re-unión transitiva en Hibernate,
+ especialmente útil para que usa identificadores asignados o claves compuestas!</emphasis>
+ </para>
+ </sect2>
+
+ <sect2 id="mapping-declaration-timestamp">
+ <title>timestamp (opcional)</title>
+
+ <para>
+ El elemento opcional <literal><timestamp></literal> indica que la tabla contiene
+ datos con sellos de tiempo. Esto esta concebido como una alternativa al versionado.
+ Los timestamps (sellos de tiempo) son por su naturaleza una implementación menos
+ segura de bloqueo optimista. Sin embrago, a veces la aplicación puede usar los
+ timestamps en otras formas.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="timestamp1" coords="2 70"/>
+ <area id="timestamp2" coords="3 70" />
+ <area id="timestamp3" coords="4 70" />
+ <area id="timestamp4" coords="5 70" />
+ </areaspec>
+ <programlisting><![CDATA[<timestamp
+ column="timestamp_column"
+ name="propertyName"
+ access="field|property|ClassName"
+ unsaved-value="null|undefined"
+ node="element-name|@attribute-name|element/@attribute|."
+/>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="timestamp1">
+ <para>
+ <literal>column</literal> (opcional - por defecto al nombre de la propiedad): El nombre
+ de una columna que tiene el timestamp.
+ </para>
+ </callout>
+ <callout arearefs="timestamp2">
+ <para>
+ <literal>name</literal>: El nombre de una propiedad del estilo JavaBeans de tipo
+ Java <literal>Date</literal> o <literal>Timestamp</literal> de la clase persistente.
+ </para>
+ </callout>
+ <callout arearefs="timestamp3">
+ <para>
+ <literal>access</literal> (opcional - por defecto a <literal>property</literal>): La
+ estrategia que Hibernate debe usar para acceder al valor de la propiedad.
+ </para>
+ </callout>
+ <callout arearefs="timestamp4">
+ <para>
+ <literal>unsaved-value</literal> (opcional - por defecto a <literal>null</literal>):
+ Un valor de propiedad de versión que ind