Deploying a XEO Application to a J2EE Server (EAR)

The final step in XEO Development is deploying the application to a J2EE Server (JBoss, WebLogic, etc..). XEO Studio provides built-in support to development using Oracle's OC4J and JBoss, but a XEO Application can be deployed to any compatible J2EE Server, with the following steps:

Don't forget thay your MySQL installation must be configured in a certain way to be compatible with XEO.

Exporting the XEO Application as an EAR

The first step to deploy a XEO Application is generating an EAR ( Enterprise Archive). XEO Studio provides a wizard to export a current project to an EAR file. In order to export a XEO project to an EAR file you need to select the "File" menu and choose "Export", find the "XEO Studio" folder and choose the "Export Project to EAR" option, which in turn will open a new window depicted in figure DeployEar.1.

Figure DeployEar.1 - Export to EAR Wizard Step 1(XEO Studio)

Depicted in figure DeployEar.1 (numbered from 1 to 7) are the options when exporting a project to EAR. The options have the following meaning:

1. The Export Profile, you can reuse an existing profile or create a new one. An export profile basically saves the selected options for later reuse.
2. The name of the profile (which will appear in "Use an existing profile" combo box the next time you run the wizard).
3. The name of the .EAR file to be generated.
4. The J2EE server to which the EAR will be deployed (currently there's support for JBOSS and OC4J)
5. The destination folder where the EAR will be created (must have write permission)
6. If an ant script with the operations to create the EAR file should be saved for later reuse.
7. If the XEO Application should be rebuilt (XEO Builder invoked) before creating the EAR.

When you fill the necessary options, press the "Next" button, which will display a window depicted in figure DeployEar.2

Figure DeployEar.2 - Export to EAR Wizard Step 2 (XEO Studio)

In figure DeployEar.2, the step 2 of the EAR exporting process, you're presented with an interface to customize the boconfig.xml file for the current export. When you press finish, XEO Studio will generate the EAR for you and place it in the directory you chose.

Two different boConfig (development and production)?

One common scenario is to have a boconfig.xml file that has settings for local development, but when an EAR is created with the application those settings no longer apply, as such, you'll probably have a different boconfig.xml file for when you want to deploy your application. One way to do this is by having a boconfig-PRODUCTION.xml file in your project (which won't be used in development because the file XEO picks up has to be named boconfig.xml) and having an ant file (option 6 when exporting) that generates the EAR which includes the following:

<copy todir='${basedir}/.deploytmp/ear/'>
            <fileset dir="${basedir}" includes='boconfig-PRODUCTION.xml' />
            <mapper type="merge" to="boconfig.xml" />
</copy>

Instead of the default ant file, which includes the following:

<copy todir='${basedir}/.deploytmp/ear/'>
        <!-- Remaing code omitted for clarity -->
        <fileset dir="${basedir}/.xeometasettings/.eardefs/ApplicationProfile/" includes='boconfig.xml' />
</copy>

Installing and configuring the J2EE Server (example for JBOSS 4.2.3GA)

An important notice: This tutorial is not about installing and configuring J2EE Servers (nor about generic deploying of a J2EE application in one of those servers), that kind of information can easily be found with the help of google.

• Download JBoss 4.2.3GA from JBoss and extract the package to a directory.
• Copy the generated EAR file in the previous step to the JBOSSHOME/server/default/deploy directory (JBOSSHOME being the directory where JBoss was installed) or to JBOSSHOME/server/INSTANCE/default/deploy directory (INSTANCE being the name of your instance)
• Configure the data sources for the current application.
• Copy the MySQL JDBC Connector to JBOSSHome/server/default/deploy/lib (or to your JBoss instance directory in JBOSSHOME/server/INSTANCE/deploy/lib)

A sample configuration using as a datasource a MySQL database running on localhost, default settings (port 3306, for MySQL) and configurations, which should be placed in a file named mysql-ds.xml along side the EAR file (JBOSSHOME/server/default/deploy or JBOSSHOME/server/INSTANCE/deploy), the USERNAME/PASSWORD,DATABASE values should be replaced with the correct values for your database):

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
        <no-tx-datasource>
                <jndi-name>jdbc/xeo_nojta</jndi-name>
                <use-java-context>false</use-java-context>
                <connection-url>jdbc:mysql://localhost:3306/DATABASE</connection-url>
                <driver-class>com.mysql.jdbc.Driver</driver-class>
                <user-name>USERNAME</user-name>
                <password>PASSWORD</password>
                <max-pool-size>30</max-pool-size>
                <idle-timeout-minutes>2</idle-timeout-minutes>
                <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exception-sorter-class-name>
                <metadata>
                        <type-mapping>mySQL</type-mapping>
                </metadata>
        </no-tx-datasource>
        <xa-datasource>
                <jndi-name>jdbc/xeo</jndi-name>
                <use-java-context>false</use-java-context>
                <track-connection-by-tx/>
                <isSameRM-override-value>false</isSameRM-override-value>
                <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
                <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/DATABASE</xa-datasource-property>
                <xa-datasource-property name="User">USERNAME</xa-datasource-property>
                <xa-datasource-property name="Password">PASSWORD</xa-datasource-property>
                <max-pool-size>30</max-pool-size>
                <idle-timeout-minutes>2</idle-timeout-minutes>
                <no-tx-separate-pools/>
                <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exception-sorter-class-name>
                <metadata>
                        <type-mapping>mySQL</type-mapping>
                </metadata>
        </xa-d

For more information on configuring DataSources with JBoss, visit JBoss's documentation page about datasources.

After configuring the data sources, you can now execute the run.bat (Windows) file to launch the JBoss server and execute the application, which will be accessible on http://localhost:8080/xeo/Login.xvw (8080 is JBOss's default port).