openxava / documentation / JBoss

You can deploy your OpenXava application on JBoss, indeed you can deploy your OpenXava application in any Java EE server. But, each application server has its own tricks, so we explain here a step by step guide to deploy on JBoss.
This guide uses JBoss 6.1.0.Final and OpenXava 5.3.1. We assume you're new to JBoss. We'll deploy the MySchool example project included in OpenXava distribution, against PostgreSQL.

Datasource

To define the datasource create a file named my-school-ds.xml in jboss-6.1.0.Final/server/default/deploy with the next content:

<?xml version="1.0" encoding="UTF-8"?>
 
<datasources>
    <local-tx-datasource>
 
        <jndi-name>MySchoolDS</jndi-name>
        <connection-url>jdbc:postgresql://localhost/my-school</connection-url>
        <driver-class>org.postgresql.Driver</driver-class>
 
        <user-name>postgres</user-name>
        <password>openxava</password>
 
        <min-pool-size>5</min-pool-size>
        <max-pool-size>20</max-pool-size>
        <idle-timeout-minutes>0</idle-timeout-minutes>
        <track-statements/>
        <prepared-statement-cache-size>32</prepared-statement-cache-size>
 
    </local-tx-datasource>
</datasources>

Of course, you should adapt the connection URL, the driver class, the user and password to your own database.

JDBC driver

Copy JDBC driver jar for you database into jboss-6.1.0.Final/server/default/lib. In our example we copy there postgresql-8.3-604.jdbc3.jar to work with our PostgreSQL 8.3.

Your persistence.xml

In the persistence.xml of your project (in persistence/META-INF) you have to make two changes. The first one is to change the format of the URL, change:

<non-jta-data-source>java://comp/env/jdbc/MySchoolDS</non-jta-data-source>

By:

<non-jta-data-source>java:/MySchoolDS</non-jta-data-source>

The second change is to enumerate explicitly all the entities of your project. Add the next entries:

<class>org.openxava.school.model.Teacher</class>
<class>org.openxava.school.model.Pupil</class>

The complete persistence.xml for MySchool could be:

<?xml version="1.0" encoding="UTF-8"?>
 
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
    version="1.0">
 
    <persistence-unit name="default">
        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
        <non-jta-data-source>java:/MySchoolDS</non-jta-data-source>
        <class>org.openxava.session.GalleryImage</class>
        <class>org.openxava.school.model.Teacher</class>
        <class>org.openxava.school.model.Pupil</class>
        <properties>
            <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>
        </properties>
    </persistence-unit>
 
</persistence>

Remember to put the correct dialect for your database.

The web.xml file of OpenXava (only for OpenXava 5.2, 5.2.1, 5.3, 5.3.1)

This step does not apply to XavaPro
Remove the organization servlet definition from OpenXava project. Edit OpenXava/web/WEB-INF/web.xml, and remove or comment the next declarations:

<!-- Remove or comment the next declaration -->
<servlet>
    <servlet-name>organization</servlet-name>
    <servlet-class>com.openxava.naviox.web.OrganizationServlet</servlet-class>
</servlet>
 
...
 
<!-- Remove or comment the next declaration -->
<servlet-mapping>
    <servlet-name>organization</servlet-name>
    <url-pattern>/o/*</url-pattern>
</servlet-mapping>

Disable JPA deployers (optional)

The above configuration is enough to run your application in JBoss. However, in that way JBoss will show the next error:

Deployment "persistence.unit:unitName=MySchool.war#default" is in error due to the following reason(s):
java.lang.RuntimeException: Specification violation [EJB3 JPA 6.2.1.2]
- You have not defined a jta-data-source for a JTA enabled persistence context named: default

You can ignore this error, everything will work fine. But, if you want to remove it, you can. Edit the jpa-deployers-jboss-beans.xml file from the jboss-6.1.0.Final/server/default/deployers/ejb3.deployer/META-INF folder, and remove or comment the bean PersistenceParsingDeployer:

<!-- Remove or comment the next declaration -->
<bean name="PersistenceParsingDeployer" class="org.jboss.jpa.deployers.PersistenceParsingDeployer">
 
...
 
</bean>

Beware, because this modification can affect other applications deployed in your JBoss, specially if they use the JPA engine provided by JBoss.

Deploy and run your application

Execute the createWar Ant target of your build.xml. It will create a MySchool.war into the workspace.dist/MySchool.dist folder. Take that war and copy it into the jboss-6.1.0.Final/server/default/deploy folder. Start JBoss executing run.bat/.sh in jboss-6.1.0.Final/bin. Open your browser, go to http://localhost:8080/MySchool and you will see your application running on JBoss.