# Entity Configuration Files

## Intro

This section talks about various configuration parameters for getting entities to work within JBoss. JBoss EJB 3.0 is built on top of the Hibernate ORM solution, and more specifically, the Hibernate Entity Manager whose documentation comes with your JBoss EJB 3.0 distribution. JBoss EJB 3.0 also requires JBoss JDBC connection pools. You'll learn you to configure both and how they relate to eachother.

## Configuration Files

To use Entity beans within JBoss EJB 3.0 you'll need to do a few things.

- Configure a JBoss datasource.
- Create hibernate configuration file.

### Configure JBoss datasource

If you want to rapidly prototype or just play around, you don't have to create any configuration files. For datasources, JBoss uses the DefaultDS defined in the deploy directory under hsqldb-ds.xml. JBoss comes with the Hypersonic SQL database embedded within it. Otherwise, you'll need to specify your own datasource. Please refer to the JBoss AS guide on how to create a jBoss connection pool. Also, there are examples in the jboss distrubtion under docs/examples/jca.

### persistence.xml and .par files

The configuration for entity managers inside an application server resides in a persistence archive (.par). A persistence archive is a JAR file with the .par suffix instead of .jar. You must also define a persistence.xml file that resides in the META-INF folder of the .par file. Alternatively, JBoss EJB 3.0 allows you to put the persistence.xml file in the .ejb3 archive if you so desire. persistence.xml is not required if you use all the default settings provided in ejb3.deployer service (see below). Here's an example of a persistence.xml file.

                 <entity-manager>
                    <name>manager1</name>
                    <provider>org.hibernate.ejb.HibernatePersistence</provider>
                    <jta-data-source>java:/DefaultDS</jta-data-source>
                    <mapping-file>ormap.xml</mapping-file>
                    <jar-file>MyApp.jar</jar-file>
                    <class>org.acme.Employee</class>
                    <class>org.acme.Person</class>
                    <class>org.acme.Address</class>
                    <properties>
                       <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
                       <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
                    </properties>
                 </entity-manager>

`name`

  You do not have to name your entity manager. It will default to the short name of the .par or .ejb3 file. If your persistence classes are within a .ejb3 archive, an EntityManager will be created that is local to the EJBs define in the .ejb3 file and the EntityManager name is the empty string, "" or the short name of the jar file if you have not specified a nmae.

`provider`

  The provider is a fully-qualified class name of the EJB Persistence provider. You do not have to put this in as it will default to Hibernate. This is needed when you are using multiple vendor implementations of EJB Persistence.

`jta-data-source`, `non-jta-data-source`

  This is the JNDI name of where the javax.sql.DataSource is located. This is ignored when *not* used within an application server. When running outside of an application server, you must specify JDBC connections with Hibernate specific properties (see below). If you're running inside JBoss, put the jndi name of the datasource you defined in the earlier section. Remember to put the "java:/" in front of the jndi name you selected for your datasource.

`mapping-file, jar-file, class`

  The class element specifies a fully qualified classname that you will map. If you are running inside of JBoss, the application service will automatically find all your annotated classes with the deployment. Mapping-file is not supported yet.

`properties`

  The properties element is used to specify vendor specific properties. This is where you will define your Hibernate specific configurations. This is also where you will have to specify JDBC connection information as well.

JBoss EJB 3.0 is built on top of Hibernate 3.0 ORM solution. You will need to provide information to Hibernate so that it knows the database vendor dialect (MySQL, Oracle, etc...), caching, what JBoss JDBC connection pool to use, as well as other settings.

You can define this stuff in a few ways. JBoss has defined a default hibernate properties in `deploy/ejb3.deployer/META-INF/persistence.properties`. It defines a number of configuration options. You can change those options there, but this will change the defaults for the entire application server. You would instead create add to the `properties` element of your persistence.xml file. The properties you define in persistence.xml override the default persistence.properties file.

Please refer to the Hibernate 3.0 and Hibernate EntityManager documentation in this distribution for how to configure hibernate specific properties. Here's a few for you to gnaw on though... `hibernate.properties` file. Here's a little explanation though:

    hibernate.hbm2ddl.auto=create-drop
    hibernate.cache.provider_class=org.hibernate.cache.HashtableCacheProvider
    hibernate.dialect=org.hibernate.dialect.HSQLDialect

The above is the default hibernate.properties that will be used for your EJB 3.0 applications in `ejb3.deployer/META-INF/hibernate.properties`.

#### Example Config Properties

Property | Description
--- | ---
hibernate.dialect | By default is Hypersonic SQL, but you can change it to other dialects like Oracle.
hibernate.hbm2ddl.auto=create-drop | Creates the database schema on deploy, deletes it on undeploy. See Hibernate manual for more options.
hibernate.cache.provider_class | Defines the caching architecture that Hibernate should use. There is a tutorial to set up a clustered cache.