Deploying the Sample Application on JBoss 3.0

The following instructions for deploying the sample application begin with a "factory" install of JBoss 3.0. This can be created simply by extracting the distribution archive, jboss-3.0.0.zip, into an appropriate location, which I'll refer to as $JBOSS_HOME.

This ZIP is the JBoss distribution with the Jetty web container. JBoss is also distributed in a bundle with the Tomcat web container, which is the Reference Implementation for J2EE web technologies. However, Jetty appears to offer superior performance. (The sample application has been tested with JBoss/Tomcat).

Understanding the JBoss Directory Structure

The final release of JBoss 3.0 moves towards a multiple server concept, as used by WebLogic 6.0 and above.

The root directory of the JBoss installation contains a /server directory, which in turn contains a directory for each of any number of independent JBoss server configurations. In the following example, I've used the /default server, which is started by the default startup script. The directory of the server to start can be set as the value of the system property jboss.server.name when invoking the JBoss boot class.

The JBoss startup JARs, used by all servers, are found in the $JBOSS_HOME/lib directory.

Each server directory, such as $JBOSS_HOME/server/default, contains the following subdirectories relevant to application deployment:

  • /conf

    Contains global configuration information for this server, such as authentication configuration and default EJB deployment settings.

  • /lib

    Contains the binaries used by the server, including JBoss and standard J2EE libraries. JAR and ZIP files in this directory are automatically loaded by the server. Database drivers required by applications are typically placed in this directory.

  • /log

    Server and HTTP request log files

  • /deploy

    Contains deployment units (EARs, WARs, EJB JAR files and Resource Adapters) that will automatically be deployed by JBoss, and service definition files.

Service definition files are XML files that define JBoss services in the form of JMX MBean definitions. Any file with a name ending with -service.xml which is placed in a server's /deploy directory will be treated as containing MBean definitions. Each file must include a number of <mbean> elements in a <server> element. However, the attributes applicable to each MBean vary with the relevant class. The way in which MBean classes and properties are set is analogous to, although more complex than, the XML bean factory definition we saw in Chapter 11. As with the bean factory approach, it provides a consistent way of defining different objects, meaning that it's only necessary to learn the basic concepts to understand how it can be used with any MBean implementation.

Since several MBeans, concerning different aspects of server configuration, can be included in the one service definition file, it is often possible to specify all the configuration required for an application in a single XML file, making deployment particularly easy. We use this approach in the sample application.

JBoss doesn't restrict us to defining standard MBeans, shipped withJBoss. For example, we can use the same mechanism to add our own custom classes, or third-party classes, to the global JNDI context when JBoss starts up.

Configuring a JBoss Server to Run the Sample Application

Following the steps we described above, we begin by defining the DataSource used by the application.

Creating a Connection Pool

JBoss includes example definitions for several databases, including Oracle, in the $JBOSS_HOME/docs/examples/jca directory. A wider range of examples is available in the JBoss CVS repository at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jboss/jbosscx/src/etc/example-cconfig/. However, as these files are under active development, finding the correct version can be a challenge. (Check the CVS tags carefully.)

I took the oracle-service.xml file from the examples directory as a basis for the definition of the Oracle connection pool for the sample application.

Here is the complete MBean definition. I've highlighted the lines of the database connection definition that set the URL, driver class, username, and password of my Oracle database. Change them as necessary in your environment:

    <server>      <mbean           code="org.jboss.resource.connectionmanager.LocalTxConnectionManager"           name="jboss.jca:service=LocalTxCM,name=OracleDS">       <depends optional-attribute-name="ManagedConnectionFactoryName">         <mbean             code="org.jboss.resource.connectionmanager.RARDeployment"             name="jboss.jca:service=LocalTxDS,name=OracleDS">

         <attribute name="jndiName">OracleDS</attribute>

          <attribute name="ManagedConnectionFactoryProperties">            <properties>

              <config-property name="ConnectionURL" type="java.lang.String">                   jdbc:oracle:thin:@127.0.0.1:1521:rj              </config-property>              <config-property name="DriverClass" type="java.lang.String">                     oracle.jdbc.driver.OracleDriver              </config-property>              <config-property name="UserName" type="java.lang.String">                     SYSTEM              </config-property>              <config-property name="Password" type="java.lang.String">                     MANAGER              </config-property>

            </properties>          </attribute>          <depends optional-attribute-name="OldRarDeployment">               jboss.jca:service=RARDeployment,               name=JBoss LocalTransaction JDBC Wrapper          </depends>         </mbean>       </depends>       <depends optional-attribute-name="ManagedConnectionPool">         <mbean code="org.jboss.resource.connectionmanager.                      JBossManagedConnectionPool"           name="jboss.jca:service=LocalTxPool,name=OracleDS">          <attribute name="MinSize">1</attribute>          <attribute name="MaxSize">20</attribute>          <attribute name="BlockingTimeoutMillis">5000</attribute>          <attribute name="IdleTimeoutMinutes">15</attribute>          <attribute name="Criteria">ByContainer</attribute>         </mbean>       </depends>       <depends optional-attribute-name="CachedConnectionManager">               jboss.jca:service=CachedConnectionManager       </depends>       <attribute name="TransactionManager">java:/TransactionManager</attribute>       <depends>jboss.jca:service=RARDeployer</depends>      </mbean>    </server> 

Note that this example uses the default administration login to Oracle. This should be changed to a user account with the privileges appropriate for the application.

Note 

Before the connection pool will work, we must make the Oracle driver available to JBoss, by copying the classes12.zip file included with Oracle to the /lib directory of the JBoss server.

Creating JMS Destinations

Next we create the JMS topic used by the application, through the following MBean definition. See the jbossmq-destinations-service.xml file included in the default JBoss installation for examples of JMS MBean definition syntax:

    <mbean code="org.jboss.mq.server.jmx.Topic"           name="jboss.mq.destination:service=Topic,name=data-update">           <depends optional-attribute-name="DestinationManager">              jboss.mq:service=DestinationManager>           </depends>           <depends optional-attribute-name="SecurityManager">              jboss.mq:service=SecurityManager</depends>           <attribute name="SecurityConf">              <security>                <role name="guest" read="true" write="true"/>                <role name="publisher" read="true" write="true" create="false"/>                <role name="durpublisher" read="true" write="true" create="true"/>             </security>           </attribute>    </mbean> 

To gain a slight improvement in JBoss startup time, I deleted the jbossmq-destinations-service.xml file in the default server's /deploy directory, which defines JMS destinations used by the JBoss test suite and sample JMS applications.

As with DataSources, topics can be defined in any file with a name of the form -service.xml in the /deploy directory.

Installing the Service Definition File

Both these MBean definitions need to be included in a service definition file. I put both definitions shown above in the same file: ticket-service.xml. This file is in the /deploy/jboss directory of the download, and must be copied to the default server's /deploy directory on application deployment. The jboss task in the sample application's Ant build script performs this automatically. It also ensures that the Oracle driver is copied to the JBoss server's /lib directory. The location of the JBoss server and the name of the deployment unit are parameterized as Ant properties. The complete task is listed below:

   <target name="jboss" depends="ear">          <copy todir="${jboss.home}/server/${jboss.server}/lib"              file="lib/oracle/classes12.zip"/>          <copy todir="${jboss.home}/server/${jboss.server}/deploy"              file="deploy/jboss/ticket-service.xml"/>          <copy todir="${jboss.home}/server/${jboss.server}/deploy"              file="${app-ear.product}"/>    </target> 

Reviewing Configuration

JBoss 3.0.0 uses the JMX Reference Implementation's simple web interface to expose the JMX MBeans running on the server. By viewing the default page on port 8082 we can see the DataSources, JNDI topics, and other global resources available to applications. This can be invaluable during troubleshooting:

click to expand

JBoss 3.0.1 introduces its own JMX HTML adapter. The WebLogic console is also JMX-based, and provides a more sophisticated interface. No other configuration changes are required to the JBoss server to run the application.

Writing JBoss Deployment Descriptors for the Sample Application

As our sample application doesn't use entity beans, and uses only one session EJB, EJB configuration is straightforward.

The necessary configuration is held in the jboss.xml proprietary deployment descriptor, which must be included in the EJB JAR file's /META-INF directory along with the standard ejb-jar.xml deployment descriptor. The jboss.xml file enables us to fill the gaps in the standard descriptor and provide further, JBoss-specific information.

For reference, the complete <session> bean element from ejb-jar.xml is:

    <session>          <ejb-name>BoxOffice</ejb-name>          <local-home>              com.wrox.expertj2ee.ticket.boxoffice.ejb.BoxOfficeHome          </local-home>          <local>              com.wrox.expertj2ee.ticket.boxoffice.ejb.BoxOfficeLocal          </local>          <ejb-class>              com.wrox.expertj2ee.ticket.boxoffice.ejb.BoxOfficeEJB          </ejb-class>          <session-type>Stateless</session-type>          <transaction-type>Container</transaction-type>         <env-entry>             <env-entry-name>beans.dao.class</env-entry-name>             <env-entry-type>Java.lang.String</env-entry-type>             <env-entry-value>                  com.wrox.expertj2ee.ticket.boxoffice.support.jdbc.                  JBoss3OOracleJdbcBoxOfficeDao             </env-entry-value>         </env-entry>         <env-entry>             <env-entry-name>beans.creditCardProcessor.class</env-entry-name>             <env-entry-type>java.lang.String</env-entry-type>             <env-entry-value>                  com.wrox.expertj2ee.ticket.boxoffice.support.                  DummyCreditCardProcessor             </env-entry-value>         </env-entry>

        <resource-ref>             <description/>             <res-ref-name>jdbc/ticket-ds</res-ref-name>             <res-type>javax.sql.DataSource</res-type>             <res-auth>Container</res-auth>         <resource-ref>    </session> 

We must use jboss.xml to provide a mapping from the DataSource JNDI name used in code and declared in ejb-jar.xml (jdbc/ticket-ds) to the JNDI name of the server-wide connection pool we created above (java:/OracleDS). We also specify the JNDI name of the bean, although this is strictly unnecessary as it defaults to the value of the <ejb-name> element, which indicates which EJB defined in ejb-jar.xml this configuration element applies to. The following is the complete jboss.xml file for the sample application:

    <jboss>      <enterprise-beans>

       <session>               <ejb-name>BoxOffice</ejb-name>               <jndi-name>BoxOffice</jndi-name>               <resource-ref>                      <res-ref-name>jdbc/ticket-ds</res-ref-name>                      <jndi-name>java:/OracleDS</jndi-name>               </resource-ref>        </session>      </enterprise-beans>    </jboss> 

The jboss.xml deployment descriptor can be used to configure many aspects of EJB behavior, including the chain of "interceptors" used to intercept calls on EJBs. JBoss uses one of a number of standard interceptors to handle each aspect of server-managed functionality, such as thread and transaction management. The jboss.xml deployment descriptor even allows us to specify our own custom interceptors to perform application-specific behavior, although this goes well beyond the present scope of the EJB specification and isn't required by most applications.

The downside of all this configurability is that overriding simple configuration parameters such as EJB pool size is harder in JBoss than in many servers. Most servers do not offer comparable ability to customize any aspect of EJB invocation, but do provide a simpler way of specifying common settings.

Each JBoss server's default EJB and other configuration settings are defined in the server's /conf/standardjboss.xml file, so another option is to override them on a server-wide basis there. The default stateless session bean pool size maximum is 100. Although this is far more than will be required for our single bean, as it is a maximum value, and the server will not need to create this many instances at runtime, so overriding it is unnecessary, either at server or at bean level.

The jboss-web.xml deployment descriptor has the same relationship to the standard web.xml as jboss.xml has to ejb-jar.xml. Fortunately the configuration involved is much simpler. All we need to do for the sample application is to provide the same mapping between JNDI names used in code running in the web container (declared in web.xml) and the JNDI name of the server-wide objects we created in the server configuration step above. The resource references are defined in web.xml as follows:

    <resource-ref>         <res-ref-name>jms/TopicFactory</res-ref-name>         <res-type>javax.jms.TopicConnectionFactory</res-type>         <res-auth>Container</res-auth>         <res-sharing-scope>Shareable</res-sharing-scope>    </resource-ref>    <resource-ref>         <res-ref-name>jms/topic/data-update</res-ref-name>         <res-type>javax.jms.Topic</res-type>         <res-auth>Container</res-auth>         <res-sharing-scope>Shareable</res-sharing-scope>    </resource-ref> 

The following is a complete listing of jboss-web.xml, showing how these are mapped onto theJNDI names we declared for the data source and JMS topic:

    <?xml version="1.0" encoding="UTF-8"?>    <jboss-web>         <resource-ref>            <res-ref-name>jdbc/ticket-ds</res-ref-name>            <res-type>javax.sql.DataSource</res-type>            <jndi-name>java:/OracleDS</jndi-name>         </resource-ref>         <resource-ref>            <res-ref-name>jms/TopicFactory</res-ref-name>            <res-type>javax.jms.TopicConnectionFactory</res-type>            <jndi-name>java:ConnectionFactory</jndi-name>         </resource-ref>         <resource-ref>            <res-ref-name>jms/topic/data-update</res-ref-name>            <res-type>javax.jms.Topic</res-type>            <jndi-name<topic/data-update</jndi-name>         </resource-ref>    </jboss-web> 

Note aJBoss-specific naming convention here for JMS destinations. We declared the topic as follows:

    <mbean code="org.jboss.mq.server.jmx.Topic"            name="jboss.mq.destination:service=Topic,name=data-update"> 

The server-wide JNDI name resulting from this MBean definition, and specified in the <jndi-name> element above, is /topic/data-update.

Deploying the Application

Once the server is configured and we have a packaged deployment unit, deployment on JBoss is very simple. We merely need to copy the packaged deployment unit to the /deploy directory of the appropriate JBoss server and define any services that it requires. As JBoss uses dynamic proxies to implement EJB home and EJB object interfaces, there is no need to generate container-specific classes, and deployment is fast.

We've already seen the jboss target in the sample application's Ant build script which copies the EAR deployment unit and necessary service definition file to the JBoss deploy directory, after rebuilding the EAR if necessary.

Finally, we can start JBoss by issuing the relevant command from the /bin directory under the JBoss root:

   run.sh 

or:

   run.bat 

As JBoss starts up, log output will initially appear on the console. The sample application will be deployed automatically.



Expert One-on-One J2EE Design and Development
Microsoft Office PowerPoint 2007 On Demand
ISBN: B0085SG5O4
EAN: 2147483647
Year: 2005
Pages: 183

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net