====== Configurando ======
Como con cualquier otro framework es necesario configurarlo para su correcto funcionamiento.
Ya hemos visto que se puede configurar usando los ficheros de mapeo o las anotaciones [[02_entidad]].
Sin embargo, aún quedan aspectos que debemos configurar como:
  * Datos de conexión a la base de datos
  * Ubicación de las clases a persistir.
  * Ubicación de los ficheros ''.hbm.xml''.
  * Nivel de Log
  * [[wpes>Connection_pool|Pool de conexiones]] a usar.
  * Etc, etc.


===== hibernate.cfg.xml =====
La forma de configurar hibernate es usando el fichero XML de configuración llamado ''hibernate.cfg.xml''. Este fichero deberemos guardarlo en el paquete raíz de nuestras clases Java, es decir fuera de cualquier paquete.Si estamos usando NetBeans deberá ser en la carpeta ''src'' de nuestro proyecto.

La información que contiene es la siguiente:
  * Propiedades de configuración.
  * Las clases que se quieren mapear.

El fichero tiene la siguiente estructura:

<code xml 1| Fichero hibernate.cfg.xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
  <session-factory>
    <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
    <property name="connection.url">jdbc:mysql://localhost/hibernate1</property>
    <property name="connection.username">hibernate1</property>
    <property name="connection.password">hibernate1</property>
    <property name="dialect">org.hibernate.dialect.MySQL5Dialect</property>
    <property name="hibernate.show_sql">true</property>
    
    <mapping resource="ejemplo01/Profesor.hbm.xml"/>
    <mapping class="ejemplo01.Profesor"/>

  </session-factory>
</hibernate-configuration>
</code>


Podemos ver que el fichero ''hibernate.cfg.xml'' es un típico fichero xml.
  * En la línea 1 vemos la declaración de que es un fichero XML.
  * En la línea 2 se aprecia la declaración del [[wpes>DOCTYPE]] junto con la referencia al documento [[http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd]] [[wpes>DTD]] que permite validarlo. Es decir que si nos descargamos el fichero [[http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd|hibernate-configuration-3.0.dtd]] podremos saber todos los elementos que hay en un fichero de mapeo.
  * El tag raiz del documento xml se llama ''<hibernate-configuration>'' y se encuentra en la línea 3.
  * Dentro del tag ''<hibernate-configuration>'' encontramos,en la línea 4, el tag ''<session-factory>'' que contendrá la configuración de hibernate.
  * Las siguientes 5 líneas (desde la 5 a la 10) contienen propiedades de configuración mediante el tag ''<property>''
    * El atributo ''name'' contiene el nombre de la propiedad de configuración.
    * El contenido del tag ''<property>'' define el valor de la propiedad de configuración.
  * Las líneas 12 y 13 contienen el tag ''<mapping>'' que se usa para indicarle a hibernate las clases que queremos usar desde hibernate.
    * El atributo ''resource'' contiene el nombre de un fichero ''.hbm.xml'' asociada a la clase que queremos persistir. En nuestro caso del fichero ''Profesor.hbm.xml''.
    * El atributo ''class'' contiene la FQCN ((Fully-Qualified Class Name. Es decir el nombre completo de una clase Java incluyendo el paquete al que pertenece.)) de la clase que queremos persistir. En nuestro ejemplo será la clase ''ejemplo02.Usuario''.

<note important>
Para una misma clase solo es necesario indicar una única vez el tag ''<mapping>'' con el atributo ''resource'' o ''class''.

En el fichero se ha incluido dos veces para indicar las dos posibilidades **excluyentes**.

</note>

<note tip>
Si buscamos documentación sobre hibernate podemos encontrar que el ''DOCTYPE'' del fichero ''hibernate.cfg.xml'' antes de la versión 3.6 era (( [[https://community.jboss.org/wiki/HibernateCoreMigrationGuide36|Hibernate Core Migration Guide : 3.6]] )) :

  <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
  
Así que no confundirlo al hacer algún //copy-empastre// desde algún tutorial de Internet de versiones anteriores.
</note>

Pasemos ahora a explicar en detalle los tag ''<property>'' y ''<mapping>''.

==== Tag <property> ====
El tag ''<property>'' se usa para definir cada una de las propiedades de configuración (( también llamadas parámetros de  configuración o opciones de configuración )) de hibernate.
Como ya hemos indicado consta del atributo ''name'' con el nombre de la propiedad de configuración. Dentro del tag ''<property>'' incluiremos el valor de dicha propiedad de configuración.

Volvamos ahora a ver las propiedades de configuración del fichero ''''
<code xml 1 | Propiedades de configuración hibernate.cfg.xml >
<property name="connection.driver_class">com.mysql.jdbc.Driver</property>
<property name="connection.url">jdbc:mysql://localhost/hibernate1</property>
<property name="connection.username">hibernate1</property>
<property name="connection.password">hibernate1</property>
<property name="dialect">org.hibernate.dialect.MySQL5Dialect</property>
<property name="hibernate.show_sql">true</property>
</code>

Estas propiedades se usan para poder conectarse mediante JDBC a la base de datos.

^ Propiedad de configuración ^ Explicación ^
| connection.driver_class | Contiene la FQCN del driver de la base de datos a usar. |
| connection.url | La URL de conexión a la base de datos tal y como se usa en JDBC |
| connection.username | El usuario de la base de datos |
| connection.password | La contraseña de la base de datos |
| dialect | El lenguaje de SQL que usará Hibernate contra la base de datos. Este parámetro es opcional ya que hibernate lo puede intentar deducir a partir de los datos de la conexión (( [[http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#portability-dialectresolver|Dialect resolution]] )). Los posibles valores de esta propiedad de configuración son la FQCN de una clase Java que extienda de la clase <javadoc h41>org.hibernate.dialect.Dialect</javadoc>. La lista de dialectos que soporta hibernate se encuentra en el paquete <javadoc h41>org.hibernate.dialect.package-summary|org.hibernate.dialect</javadoc>.|
| hibernate.show_sql | Propiedad opcional que indica si se mostrará por la consola la SQL que lanza Hibernate contra la base de datos. Su posibles valores son ''true'' o ''false''. Esta propiedad es muy útil mientras programamos ya que nos ayudará a entender cómo está funcionanado Hibernate |
| connection.datasource | Indica el nombre del ''DataSource'' con el que se conectará Hibernate a la base de datos. En caso de estar esta propiedad no debería estar ninguna de las 4 primeras propiedades sobre la conexión o viceversa. Esta propiedad se usa en aplicaciones Web ya que los datos de la conexión se definen en el servidor de aplicaciones y se accede a la base de datos a través del ''DataSource''. |

<note important>
Al utilizar la propiedad ''connection.datasource'' recuerda que antes del nombre que se le haya dado al datasource hay que añadir:
  java:/comp/env/
  
Es decir que si nuestro datasource se llama ''jdbc/hibernate1'' el valor de ''connection.datasource'' deberá ser:
  java:/comp/env/jdbc/hibernate1
</note>

<note tip>Los dialectos de hibenate son importantes ya que indican en qué base de datos podemos usarlo. En caso de que una base de datos no esté soportada , se puede definir una nueva clase que extienda de <javadoc h41>org.hibernate.dialect.Dialect</javadoc> para poder soportar dicha base de datos.
</note>
==== Tag <mapping> ====
El tag ''<mapping>'' se usa para indicarle a Hibernate las clases queremos mapear. Este tag se usa de 2 formas distintas:

  * [[#Fichero de mapeo .hbm.xml|Indicando el nombre del fichero de mapeo ''.hbm.xml'']]
  * [[#FQCN de la clase Java|Indicando la FQCN de la clase Java que hemos anotado]]

=== Fichero de mapeo .hbm.xml ===
Si hemos creado un fichero de mapeo ''.hbm.xml'' para poder persistir una clase Java a la base de datos , deberemos utilizar el atributo ''resource'' en el tag ''<mapping>''.

<code xml>
<mapping resource="ejemplo01/Profesor.hbm.xml"/>
</code>

El atributo ''resource'' contiene el //path// dentro de los paquetes Java al fichero ''.hbm.xml''. 

<note tip>Nótese que para separar el //path// se usa la barra y no el punto.</note>

<note important>Estamos indicando un path dentro del sistema de paquetes de Java y **NO** una ruta en el sistema de ficheros del disco duro.</note>

=== FQCN de la clase Java ===
Si la clase Java la hemos anotado para poder persistirla en vez de usar el fichero ''.hbm.xml'' deberemos utilizar el atributo ''class'' en el tag ''<mapping>''.

<code xml>
<mapping class="ejemplo01.Profesor"/>
</code>

El atributo ''class'' contiene la FQCN de la clase Java que deseamos que se pueda persistir.

<note tip>Nótese que para separar los paquetes ahora se usa el punto en vez de la barra.</note>

===== Referencias =====

  * [[http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#session-configuration|Parámetros de configuración de Hibernate]]