JBoss Application Server

Now that you’ve downloaded JBoss and have run the server for the first time, the next thing you will want to know is how the installation is laid out and what goes where. At first glance there seems to be a lot of stuff in there, and it’s not obvious what you need to look at and what you can safely ignore for the time being. To remedy that, we’ll explore the server directory structure, locations of the key configuration files, log files, deployment and so on. It’s worth familiarizing yourself with the layout at this stage as it will help you understand the JBoss service architecture so that you’ll be able to find your way around when it comes to deploying your own applications.

[usr@localhost jboss-4.2.2.GA]$ls server/default/conf 
jbossjta-properties.xml  jboss-service.xml  props                      xmdesc
jboss-log4j.xml          jndi.properties    standardjbosscmp-jdbc.xml
jboss-minimal.xml        login-config.xml   standardjboss.xml

[user@localhost jboss-4.2.2.GA]$ tree
|-- bin
|-- client
|-- docs
|   |-- dtd
|   |-- examples
|   |   |-- binding-manager
|   |   |   `-- sample-bindings.xml
|   |   |-- jca
|   |   |-- jms
|   |   |-- jmx
|   |   |-- netboot
|   |   |   `-- netboot.war
|   |   `-- varia
|   |       |-- deployment-service
|   |       |-- derby-plugin.jar
|   |       |-- entity-resolver-manager
|   |       |   `-- xmlresolver-service.xml
|   |       `-- jboss-bindings.xml
|   `-- schema
|-- lib
|   |-- commons-codec.jar
|   |-- commons-httpclient.jar
|   |-- commons-logging.jar
|   |-- concurrent.jar
|   |-- endorsed
|   |   |-- serializer.jar
|   |   |-- xalan.jar
|   |   `-- xercesImpl.jar
|   |-- getopt.jar
|   |-- jboss-common.jar
|   |-- jboss-jmx.jar
|   |-- jboss-system.jar
|   |-- jboss-xml-binding.jar
|   `-- log4j-boot.jar
`-- server
|-- all
|   |-- conf
|   |   |-- jacorb.properties
|   |   |-- jboss-log4j.xml
|   |   |-- jboss-minimal.xml
|   |   |-- jboss-service.xml
|   |   |-- jbossjta-properties.xml
|   |   |-- jndi.properties
|   |   |-- login-config.xml
|   |   |-- props
|   |   |   |-- jbossws-roles.properties
|   |   |   |-- jbossws-users.properties
|   |   |   |-- jmx-console-roles.properties
|   |   |   `-- jmx-console-users.properties
|   |   |-- standardjboss.xml
|   |   |-- standardjbosscmp-jdbc.xml
|   |   `-- xmdesc
|   |-- deploy
|   |-- deploy-hasingleton
|   |   `-- jms
|   |-- farm
|   |   `-- cluster-examples-service.xml
|   `-- lib
|-- default
|   |-- conf
|   |   |-- jboss-log4j.xml
|   |   |-- jboss-minimal.xml
|   |   |-- jboss-service.xml
|   |   |-- jbossjta-properties.xml
|   |   |-- jndi.properties
|   |   |-- login-config.xml
|   |   |-- props
|   |   |   |-- jbossws-roles.properties
|   |   |   |-- jbossws-users.properties
|   |   |   |-- jmx-console-roles.properties
|   |   |   `-- jmx-console-users.properties
|   |   |-- standardjboss.xml
|   |   |-- standardjbosscmp-jdbc.xml
|   |   `-- xmdesc
|   |       |-- AttributePersistenceService-xmbean.xml
|   |       |-- ClientUserTransaction-xmbean.xml
|   |       |-- JNDIView-xmbean.xml
|   |       |-- Log4jService-xmbean.xml
|   |       |-- NamingBean-xmbean.xml
|   |       |-- NamingService-xmbean.xml
|   |       |-- TransactionManagerService-xmbean.xml
|   |       |-- org.jboss.deployment.JARDeployer-xmbean.xml
|   |       |-- org.jboss.deployment.MainDeployer-xmbean.xml
|   |       `-- org.jboss.deployment.SARDeployer-xmbean.xml
|   |-- data
|   |   |-- hypersonic
|   |   |-- jboss.identity
|   |   |-- tx-object-store
|   |   `-- xmbean-attrs
|   |-- deploy
|   |-- lib
|   |-- log
|   |   |-- boot.log
|   |   |-- server.log
|   |   `-- server.log.2008-01-09
|   |-- tmp
|   `-- work
|       `-- jboss.web
|           `-- localhost
`-- minimal
|-- conf
|   |-- jboss-log4j.xml
|   |-- jboss-service.xml
|   |-- jndi.properties
|   `-- xmdesc
|       |-- NamingBean-xmbean.xml
|       `-- NamingService-xmbean.xml
|-- deploy
`-- lib
|-- jboss-management.jar
|-- jboss-minimal.jar
|-- jnpserver.jar
            `-- log4j.jar

./run.sh -c myconfig

[user@localhost bin]$ ./run.sh 
=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: /home/user/jboss-4.2.2.GA/jboss-as

  JAVA: java

  JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client.
gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true

CLASSPATH: /home/user/jboss-4.2.2.GA/jboss-as/bin/run.jar

=========================================================================

[bin]$ ./run.sh -c minimal
...
...
...
15:05:40,301 INFO  [Server] JBoss (MX MicroKernel) [4.2.2 (build: SVNTag=JBoss_4_2_2 date=200801082100)] Started in 5s:75ms

usage: run.sh [options]
-h, --help                          Show help message
-V, --version                       Show version information
--                                  Stop processing options
-D<name>[=<value>]      Set a system property
-d, --bootdir=<dir>           Set the boot patch directory; Must be absolute or url
-p, --patchdir=<dir>          Set the patch directory; Must be absolute or url
-n, --netboot=<url>           Boot from net with the given url as base
-c, --configuration=<name>    Set the server configuration name
-B, --bootlib=<filename>      Add an extra library to the front bootclasspath
-L, --library=<filename>      Add an extra library to the loaders classpath
-C, --classpath=<url>         Add an extra url to the loaders classpath
-P, --properties=<url>        Load system properties from the given url
-b, --host=<host or ip>       Bind address for all JBoss services
-g, --partition=<name>        HA Partition name (default=DefaultDomain)
-u, --udp=<ip>                UDP multicast address
-l, --log=<log4j|jdk>         Specify the logger plugin type

[bin]$ ./shutdown.sh -S

A JMX client to shutdown (exit or halt) a remote JBoss server.

usage: shutdown [options] <operation>

options:
-h, --help                Show this help message (default)
-D<name>[=<value>]        Set a system property
--                        Stop processing options
-s, --server=<url>        Specify the JNDI URL of the remote server
-n, --serverName=<url>    Specify the JMX name of the ServerImpl
-a, --adapter=<name>      Specify JNDI name of the MBeanServerConnection to use
-u, --user=<name>         Specify the username for authentication
-p, --password=<name>     Specify the password for authentication

operations:
-S, --shutdown            Shutdown the server
-e, --exit=<code>         Force the VM to exit with a status code
-H, --halt=<code>         Force the VM to halt with a status code

JBossInstall.bat <depends> [-auto | -manual]

When the JBoss Server is running, you can get a live view of the server by going to the JMX console application at http://localhost:8080/jmx-console. You should see something similar to Figure 1.1, “View of the JMX Management Console Web Application”.

The JMX Console is the JBoss Management Console which provides a raw view of the JMX MBeans which make up the server. They can provide a lot of information about the running server and allow you to modify its configuration, start and stop components and so on.

For example, find the service=JNDIView link and click on it. This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. Now find the operation called list near the bottom of the MBean view page and click the invoke button. The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.

Figure 1.1. View of the JMX Management Console Web Application

Look at some of the other MBeans and their listed operations; try changing some of the configuration attributes and see what happens. With a very few exceptions, none of the changes made through the console are persistent. The original configuration will be reloaded when you restart JBoss, so you can experiment freely without doing any permanent damage.

Hot-deployable services are those which can be added to or removed from the running server. These are placed in the JBOSS_DIST/jboss-as/server/<instance-name>/deploy directory. Let’s have a look at a practical example of hot-deployment of services in JBoss before we go on to look at server configuration issues in more detail.

Start JBoss if it isn’t already running and take a look at the server/production/deploy directory. Remove the mail-service.xml file and watch the output from the server:

13:10:05,235 INFO  [MailService] Mail service 'java:/Mail' removed from JNDI

Then replace the file and watch JBoss re-install the service:

13:58:54,331 INFO  [MailService] Mail Service bound to java:/Mail

This is hot-deployment in action.

Now that we have examined the JBoss server, we will take a look at some of the main configuration files and what they are used for. All paths are relative to the server configuration directory (server/production, for example).

<!-- Section 1 commented out
<mbean code="org.jboss.naming.JNDIView"
    name="jboss:service=JNDIView"
    xmbean-dd="resource:xmdesc/JNDIView-xmbean.xml">
-->
    <!-- The HANamingService service name -->
<!-- Section two commented out
    <attribute name="HANamingService">jboss:service=HAJNDI</attribute></mbean>
-->
                

<!-- Limit JBoss categories to INFO --> 
<category name="org.jboss"> 
    <priority value="INFO"/> 
</category>    

<appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender"> 
    <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> 
    <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/> 
    <param name="Append" value="false"/> 
    <param name="MaxFileSize" value="500KB"/> 
    <param name="MaxBackupIndex" value="1"/> 
 
    <layout class="org.apache.log4j.PatternLayout"> 
        <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> 
    </layout> 
</appender> 
 
<category name="org.jboss.ejb.plugins.cmp"> 
    <priority value="DEBUG" /> 
    <appender-ref ref="CMP"/> 
</category> 

<jboss-web>
    <security-domain>java:/jaas/jmx-console</security-domain>
</jboss-web>

<!-- 
   A security constraint that restricts access to the HTML JMX console
   to users with the role JBossAdmin. Edit the roles to what you want and
   uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
   secured access to the HTML JMX console.
-->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>HtmlAdaptor</web-resource-name>
        <description>
            An example security config that only allows users with the
            role JBossAdmin to access the HTML JMX console web application
        </description>
        <url-pattern>/*</url-pattern>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
        <role-name>JBossAdmin</role-name>
    </auth-constraint>
</security-constraint>

<application-policy name="jmx-console">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
                     flag="required">
            <module-option name="usersProperties">
                props/jmx-console-users.properties
            </module-option>
            <module-option name="rolesProperties">
                props/jmx-console-roles.properties
            </module-option>
        </login-module>
    </authentication> 
</application-policy>

JBoss Application Server comes with Tomcat as the default web container. The embedded Tomcat service is the expanded deploy/jboss-web.deployer. All the necessary jar files needed by Tomcat can be found in there, as well as a web.xml (under the ROOT.war/WEB-INF) file which provides a default configuration set for web applications.

If you are already familiar with configuring Tomcat, have a look at the server.xml, which contains a subset of the standard Tomcat format configuration information. As it stands, this includes setting up the HTTP connector on the default port 8080, an AJP connector on port 8009 (can be used if you want to connect via a web server such as Apache) and an example of how to configure an SSL connector (commented out by default).

You shouldn’t need to modify any of this other than for advanced use. If you’ve used Tomcat before as a stand-alone server you should be aware that things are a bit different when using the embedded service. JBoss is in charge and you shouldn’t need to access the Tomcat directory at all. Web applications are deployed by putting them in the JBoss deploy directory and logging output from Tomcat can be found in the JBoss log directory.

The Release Notes for JBoss Application Server 4.0.0 contain information on EJB3 features that are not yet implemented, or partially implemented. The Release Notes include links to issues in JIRA for information on workarounds and further details.

JBoss Application Server 5 fully supports the entire Java 5 Enterprise Edition specification. JBoss Application Server 4.2.2 implemented EJB3 functionality by way of an EJB MBean container running as a plugin in the JBoss Application Server. This had certain implications for application development.

The EJB3 plugin injects references to an EntityManager and @EJB references from one EJB object to another. However this support is limited to the EJB3 MBean and the JAR files it manages. Any JAR files which are loaded from a WAR (such as Servlets, JSF backing beans, and so forth) do not undergo this processing. The Java 5 Enterprise Edition standard specifies that a Servlet can reference a Session Bean through an @EJB annotated reference, this was not implemented in JBoss Application Server 4.2.2.

To compile and package the examples, you must have Apache Ant 1.6+ installed in your machine. You can download it from http://ant.apache.org and have it installed in few steps:

Let's take a look at the contents of the Data Model represented by the Todo class in the Todo.java file. Each instance of the Todo class corresponds to a row in the relational database table. The 'Todo' class has three properties: id, title and description. Each of these correspond to a column in the database table.

The 'Entity class' to 'Database Table' mapping information is specified using EJB3 Annotations in the 'Todo' class. This eliminates the need for XML configuration and makes it a lot clearer. The @Entity annotation defines the Todo class as an Entity Bean. The @Id and @GeneratedValue annotations on the id property indicate that the id column is the primary key and that the server automatically generates its value for each Todo object saved into the database.

@Entity
public class Todo implements Serializable {

  private long id;
  private String title;
  private String description;

  public Todo () {
    title ="";
    description ="";
  }

  @Id @GeneratedValue
  public long getId() { return id;}
  public void setId(long id) { this.id = id; }

  public String getTitle() { return title; }
  public void setTitle(String title) {this.title = title;}

  public String getDescription() { return description; }
  public void setDescription(String description) {
    this.description = description;
  }

}

In this section we will show you how the web interface is defined using JSF pages. We will also see how the data model is mapped to the web form using JSF EL. Using the #{...} notation to reference Java objects is called JSF EL (JSF Expression Language). Lets take a look at the pages used in our application:

EJB 3.0 is one of the major improvements introduced with Java EE 5.0. It aims at reducing the complexity of older versions of EJB and simplifies Enterprise Java development and deployment. You will notice that to declare a class as a 'Session Bean' you simply have to annotate it. Using annotations eliminates the complexity involved with too many deployment descriptors. Also the only interface an EJB3 Session Bean requires is a business interface that declares all the business methods that must be implemented by the bean.

We will explore the two important source files associated with the Bean implementation in our application: TodoDaoInt.java and TodoDao.java.

We will build the sample application using Ant and explore the configuration and packaging details. If you haven't installed Ant yet, do so now.

[user@localhost jsfejb3]$ ant
Buildfile: build.xml

compile:
    [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/classes
    [javac] Compiling 4 source files to /home/skittoli/Desktop/gettingstarted/jsfejb3/build/classes
    [javac] Note: /jboss/gettingstarted/jsfejb3/src/TodoDao.java uses unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.

war:
    [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/jars
      [war] Building war: /jboss/gettingstarted/jsfejb3/build/jars/app.war

ejb3jar:
      [jar] Building jar: /jboss/gettingstarted/jsfejb3/build/jars/app.jar

ear:
      [ear] Building ear: /jboss/gettingstarted/jsfejb3/build/jars/jsfejb3.ear

main:

BUILD SUCCESSFUL
Total time: 3 seconds

jsfejb3.ear
|+ app.jar   // contains the EJB code
    |+ import.sql
    |+ Todo.class
    |+ TodoDao.class
    |+ TodoDaoInt.class
    |+ META-INF
        |+ persistence.xml
|+ app.war   // contains web UI
    |+ index.html
    |+ index.xhtml
    |+ create.xhtml
    |+ edit.xhtml
    |+ todos.xhtml
    |+ TodoBean.class
    |+ style.css
    |+ META-INF
    |+ WEB-INF
       |+ faces-config.xml
       |+ navigation.xml
       |+ web.xml
|+ META-INF  // contains the descriptors
    |+ application.xml
    |+ jboss-app.xml

Deploying an application in JBoss is simple and easy. You just have to copy the EAR file to the deploy directory in the 'server configuration' directory of your choice. Here, we will deploy it to the 'default' configuration, so we copy the EAR file to the JBOSS_DIST/jboss-as/server/default/deploy directory.

You should see something close to the following output from the server:

15:32:23,997 INFO  [EARDeployer] Init J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
15:32:24,212 INFO  [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
entity.PersistenceUnitDeployment
15:32:24,213 INFO  [JmxKernelAbstraction] installing MBean: persistence.units:ear=
jsfejb3.ear,jar=app.jar,unitName=helloworld with dependencies:
15:32:24,213 INFO  [JmxKernelAbstraction]       jboss.jca:name=DefaultDS,service=
DataSourceBinding
15:32:24,275 INFO  [PersistenceUnitDeployment] Starting persistence unit persistence.
units:ear=jsfejb3.ear,jar=app.jar,unitName=helloworld
15:32:24,392 INFO  [Ejb3Configuration] found EJB3 Entity bean: Todo
15:32:24,450 WARN  [Ejb3Configuration] Persistence provider caller does not implements 
the EJB3 spec correctly. PersistenceUnitInfo.getNewTempClassLoader() is null.
15:32:24,512 INFO  [Configuration] Reading mappings from resource : META-INF/orm.xml
15:32:24,512 INFO  [Ejb3Configuration] [PersistenceUnit: helloworld] no META-INF/orm.xml 
found
15:32:24,585 INFO  [AnnotationBinder] Binding entity from annotated class: Todo
15:32:24,586 INFO  [EntityBinder] Bind entity Todo on table Todo
.
.
.
.
15:32:26,311 INFO  [SchemaExport] Running hbm2ddl schema export
15:32:26,312 INFO  [SchemaExport] exporting generated schema to database
15:32:26,314 INFO  [SchemaExport] Executing import script: /import.sql
15:32:26,418 INFO  [SchemaExport] schema export complete
15:32:26,454 INFO  [NamingHelper] JNDI InitialContext properties:{java.naming.factory.
initial=org.jnp.interfaces.NamingContextFactory, java.naming.factory.url.pkgs=org.jboss.
naming:org.jnp.interfaces}
15:32:26,484 INFO  [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
stateless.StatelessContainer
15:32:26,485 INFO  [JmxKernelAbstraction] installing MBean: jboss.j2ee:ear=jsfejb3.ear,
jar=app.jar,name=TodoDao,service=EJB3 with dependencies:
15:32:26,513 INFO  [JmxKernelAbstraction]       persistence.units:ear=jsfejb3.ear,
jar=app.jar,unitName=helloworld
15:32:26,557 INFO  [EJBContainer] STARTED EJB: TodoDao ejbName: TodoDao
15:32:26,596 INFO  [EJB3Deployer] Deployed: file:/jboss/jboss-as-5.0.0<release>
server/default/tmp/deploy/
tmp33761jsfejb3.ear-contents/app.jar
15:32:26,625 INFO  [TomcatDeployer] deploy, ctxPath=/jsfejb3, warUrl=.../tmp/deploy/
tmp33761jsfejb3.ear-contents/app-exp.war/
15:32:26,914 INFO  [EARDeployer] Started J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear

If there are any errors or exceptions, make a note of the error message. Check that the EAR is complete and inspect the WAR file and the EJB jar files to make sure they contain all the necessary components (classes, descriptors etc.).

You can safely redeploy the application if it is already deployed. To undeploy it you just have to remove the archive from the deploy directory. There’s no need to restart the server in either case. If everything seems to have gone OK, then point your browser at the application URL.

http://localhost:8080/jsfejb3

You will be forwarded to the application main page. Figure 4.5, “Sample TODO” shows the sample application in action.

Figure 4.5. Sample TODO

Let's start off our examination of the Seam implementation in the same way, by examining how the Data Model is implemented. This is done in the Todo.java file.

@Entity
@Name("todo")
public class Todo implements Serializable {

  private long id;
  private String title;
  private String description;

  public Todo () {
    title ="";
    description ="";
  }

  @Id @GeneratedValue
  public long getId() { return id;}
  public void setId(long id) { this.id = id; }

  @NotNull
  public String getTitle() { return title; }
  public void setTitle(String title) {this.title = title;}

  @NotNull
  @Length(max=250) 
  public String getDescription() { return description; }
  public void setDescription(String description) {
    this.description = description;
  }

}

The @Entity annotation defines the class as an EJB3 entity bean, and tells the container to map the Todo class to a relational database table. Each property of the class will become a column in the table. Each instance of the class will become a row in this table. Since we have not used the @Table annotation, Seam's "configuration by exception" default will name the table after the class.

@Entity and @Table are both EJB3 annotations, and are not specific to Seam. It is possible to use Seam completely with POJOs (Plain Old Java Objects) without any EJB3-specific annotations. However, EJB3 brings a lot of advantages to the table, including container managed security, message-driven components, transaction and component level persistence context, and @PersistenceContext injection, which we will encounter a little further on.

The @Name annotation is specific to Seam, and defines the string name for Seam to use to register the Entity Bean. This will be the default name for the relational database table. Each component in a Seam application must have a unique name. In the other components in the Seam framework, such as JSF web pages and session beans, you can reference the managed Todo bean using this name. If no instance of this class exists when it is referenced from another component, then Seam will instantiate one.

The @Id annotation defines a primary key id field for the component. @GeneratedValue specifies that the server will automatically generate this value for the component when it is saved to the database.

Seam provides support for model-based constraints defined using Hibernate Validator, although Hibernate does not have to be the object persister used. The @NotNull annotation is a validation constraint that requires this property to have a value before the component can be persisted into the database. Using this annotation allows the validation to be enforced by the JSF code at the view level, without having to specify the exact validation constraint in the JSF code.

At this point the only apparent difference between the Seam version and the EJB3/JSF version of the app is the inclusion of the validator annotation @NotNull, and the @Name annotation. However, while the EJB3/JSF version of this application requires a further TodoBean class to be manually coded and managed in order to handle the interaction between the Todo class and the web interface, when using Seam the Seam framework takes care of this work for us. We'll see how this is done in practice as we examine the implementation of the user interface.

The index.xhtml file used is the same as in the EJB3/JSF example.

create.xhtml begins to reveal the difference that coding using the Seam framework makes.

<h:form id="create">

<f:facet name="beforeInvalidField">
  <h:graphicImage styleClass="errorImg" value="error.png"/>
</f:facet>
<f:facet name="afterInvalidField">
  <s:message styleClass="errorMsg" />
</f:facet>
<f:facet name="aroundInvalidField">
  <s:div styleClass="error"/>
</f:facet>

<s:validateAll>

<table>

  <tr>
    <td>Title:</td>
    <td>
      <s:decorate>
        <h:inputText id="title" value="#{todo.title}" size="15"/>
      </s:decorate>
    </td>
  </tr>

  <tr>
    <td>Description:</td>
    <td>
      <s:decorate>
        <h:inputTextarea id="description" value="#{todo.description}"/>
      </s:decorate>
    </td>
  </tr>

</table>

</s:validateAll>

<h:commandButton type="submit" id="create" value="Create"
                 action="#{todoDao.persist}"/>
</h:form>
		

The first thing that is different here is the Java Server Facelet code at the beginning, which works with the @NotNull validation constraint of our todo class to enforce and indicate invalid input to the user.

Also notice here that rather than requiring the use of a TodoBean class as we did in the EJB3/JSF example we back the form directly with a Todo entity bean. When this page is called, JSF asks Seam to resolve the variable todo due to JSF EL references such as #{todo.title}. Since there is no value already bound to that variable name, Seam will instantiate an entity bean of the todo class and return it to JSF, after storing it in the Seam context. The Seam context replaces the need for an intermediary bean.

The form input values are validated against the Hibernate Validator constraints specified in the todo class. JSF will redisplay the page if the constraints are violated, or it will bind the form input values to the Todo entity bean.

Entity beans shouldn't do database access or transaction management, so we can't use the Todo entity bean as a JSF action listener. Instead, creation of a new todo item in the database is accomplished by calling the persist method of a TodoDao session bean. When JSF requests Seam to resolve the variable todoDao through the JSF EL expression #{todoDao.persist}, Seam will either instantiate an object if one does not already exist, or else pass the existing stateful todoDao object from the Seam context. Seam will intercept the persist method call and inject the todo entity from the session context.

Let's have a look at the TodoDao class (defined in TodoDao.java) to see how this injection capability is implemented.

Let's go through a listing of the code for the TodoDao class.

@Stateful
@Name("todoDao")
public class TodoDao implements TodoDaoInt {

  @In (required=false) @Out (required=false)
  private Todo todo;

  @PersistenceContext (type=EXTENDED)
  private EntityManager em;

  // Injected from pages.xml
  Long id;
 
  public String persist () {
    em.persist (todo);
    return "persisted";
  }

  @DataModel
  private List <Todo> todos;

  @Factory("todos")
  public void findTodos () {
    todos = em.createQuery("select t from Todo t")
                                  .getResultList();
  }

  public void setId (Long id) {
    this.id = id;
    
    if (id != null) {
      todo = (Todo) em.find(Todo.class, id);
    } else {
      todo = new Todo ();
    }
  }
  
  public Long getId () {
    return id;
  }

  public String delete () {
    em.remove( todo );
    return "removed";
  }

  public String update () {
    return "updated";
  }

  @Remove @Destroy
  public void destroy() {}

}

First of all notice that this is a stateful session bean. Seam can use both stateful and stateless session beans, the two most common types of EJB3 beans.

The @In and @Out annotations define an attribute that is injected by Seam. The attribute is injected to this object or from this object to another via a Seam context variable named todo, a reference to the Seam registered name of our Todo class defined in Todo.java.

The @PersistenceContext annotation injects the EJB3 Entity manager, allowing this object to persist objects to the database. Because this is a stateful session bean and the PersistenceContext type is set to EXTENDED, the same Entity Manager instance is used until the Remove method of the session bean is called. The database to be used (a persistence-unit) is defined in the file resources/META-INF/persistence.xml

Note that this session bean has simultaneous access to context associated with web request (the form values of the todo object), and state held in transactional resources (the EntityManager). This is a break from traditional J2EE architectures, but Seam does not force you to work this way. You can use more traditional forms of application layering if you wish.

The @DataModel annotation initializes the todos property, which will be outjected or "exposed" to the view. The @Factory annotated method performs the work of generating the todos list, and is called by Seam if it attempts to access the exposed DataModel property and finds it to be null. Notice the absence of property access methods for the todos property. Seam takes care of this for you automatically.

Let's take a look at the JSF code that we use for displaying and editing the list of todos, to get an idea of how to use these interfaces in practice.

Using the DataModel exposed property of the Session Bean it becomes trivial to produce a list of todos:

<h:form>

<h:dataTable value="#{todos}" var="todo">
  <h:column>
    <f:facet name="header">Title</f:facet>
    #{todo.title}
  </h:column>
  <h:column>
    <f:facet name="header">Description</f:facet>
    #{todo.description}
  </h:column>
  <h:column>
    <a href="edit.seam?tid=#{todo.id}">Edit</a>
  </h:column>
</h:dataTable>

<center>
  <h:commandButton action="create"
            value="Create New Todo" type="submit"/>
</center>

</h:form>

When the JSF variable resolver encounters {#todos} and requests todos, Seam finds that there is no "todos" component in the current scope, so it calls the @Factory("todos") method to make one. The todos object is then outjected once the factory method is done since it is annotated with the @DataModel annotation.

Constructing the view for the edit page is similarly straight forward:

<h:form id="edit">
  
<f:facet name="beforeInvalidField">
  <h:graphicImage styleClass="errorImg" value="error.png"/>
</f:facet>
<f:facet name="afterInvalidField">
  <s:message styleClass="errorMsg" />
</f:facet>
<f:facet name="aroundInvalidField">
  <s:div styleClass="error"/>
</f:facet>

<s:validateAll>

<table>

  <tr>
    <td>Title:</td>
    <td>
      <s:decorate>
        <h:inputText id="title" value="#{todo.title}" size="15"/>
      </s:decorate>
    </td>
  </tr>

  <tr>
    <td>Description:</td>
    <td>
      <s:decorate>
        <h:inputTextarea id="description" value="#{todo.description}"/>
      </s:decorate>
    </td>
  </tr>

</table>

</s:validateAll>

<h:commandButton type="submit" id="update" value="Update"
                 action="#{todoDao.update}"/>
 
<h:commandButton type="submit" id="delete" value="Delete"
                 action="#{todoDao.delete}"/>
</h:form>
		

Here we see the same factors in play. JSF validation code taking advantage of the validation constraints defined in our Entity Bean, and the use of the todoDao Session Bean's update and delete methods to update the database.

The call from todos.xhtml: edit.seam?tid=#{todo.id} causes Seam to create a todoDao and set it's id property to tid. Setting its id property causes the todoDao to retrieve the appropriate record from the database.

The functionality that allows the edit page to be called with a parameter in this way is implemented through pages.xml. Let's have a look at the pages.xml file and how it is used by Seam applications.

Seam drastically reduces the amount of xml coding that needs to be done. One file that is of interest is the pages.xml, packaged in the app.war file's WEB-INF directory. This file is available in the resources/WEB-INF directory in the source code bundle. The pages.xml file is used to define page descriptions including Seam page parameters (HTTP GET parameters), page actions, page navigation rules, error pages etc. Among other things it can be used in a Seam application to define exception handlers and redirections.

In the case of our sample application we are using it to define a Seam page parameter. The pages.xml in this example contains the following code:

<page view-id="/edit.xhtml">
    <param name="tid" value="#{todoDao.id}" 
           converterId="javax.faces.Long"/>
</page>

This defines a parameter named tid for the edit.xhtml page. When the edit.xhtml page is loaded, the HTTP GET request parameter tid is converted to a Long value and assigned to the id property of the todoDao object. You can have as many page parameters as required to bind HTTP GET request parameters to the back-end components in your application.

This completes our walkthrough of the sample Seam application. For further, detailed information on developing applications using the Seam framework, please refer to the The Seam Reference Guide.

Datasource configuration file names end with the suffix -ds.xml so that they will be recognized correctly by the JCA deployer. The docs/example/jca directory contains sample files for a wide selection of databases and it is a good idea to use one of these as a starting point. For a full description of the configuration format, the best place to look is the DTD file docs/dtd/jboss-ds_1_5.dtd. Additional documentation on the files and the JBoss JCA implementation can also be found in the JBoss Application Server Guide available at http://labs.jboss.com/projects/docs/.

Local transaction datasources are configured using the local-tx-datasource element and XA-compliant ones using xa-tx-datasource. The example file generic-ds.xml shows how to use both types and also some of the other elements that are available for things like connection pool configuration. Examples of both local and XA configurations are available for Oracle, DB2 and Informix.

If you look at the example files firebird-ds.xml, facets-ds.xml and sap3-ds.xml, you’ll notice that they have a completely different format, with the root element being connection-factories rather than datasources. These use an alternative, more generic JCA configuration syntax used with a pre-packaged JCA resource adapter. The syntax is not specific to datasource configuration and is used, for example, in the jms-ds.xml file to configure the JMS resource adapter.

We would also highly recommend consulting the JCA wiki pages at http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossJCA

Next, we’ll work through some step-by-step examples to illustrate what’s involved setting up a datasource for a specific database.

The MySQL® database has become the world's most popular open source database thanks to its consistent fast performance, high reliability and ease of use. This database server is used in millions of installations ranging from large corporations to specialized embedded applications across every continent of the world. . In this section, we'll be using the community version of their database server (GA 5.0.45) and the latest JDBC driver (GA 5.1.5) both available at http://www.mysql.com.

 
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
	<local-tx-datasource>
	  <jndi-name>DefaultDS</jndi-name>
	  <connection-url>jdbc:mysql://localhost:3306/test</connection-url>
	  <driver-class>com.mysql.jdbc.Driver</driver-class>
	  <user-name>root</user-name>
	  <password>jboss</password>
	  <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLValidConnectionChecker</valid-connection-checker-class-name>
	  <metadata>
	<type-mapping>mySQL</type-mapping>
	</metadata>
	</local-tx-datasource>
</datasources>

 
<mbean code="org.jboss.mq.pm.jdbc2.PersistenceManager"
	name="jboss.mq:service=PersistenceManager">
	<depends optional-attribute-name="ConnectionManager">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
....

Oracle is one of the main players in the commercial database field and most readers will probably have come across it at some point. You can download it freely for non-commercial purposes from http://www.oracle.com/technology/products/database/xe/index.html

In this section, we'll connect the server to Oracle Database 10g Express Edition using the latest JDBC driver (11g) available at http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html

	
				<?xml version="1.0" encoding="UTF-8"?>
				<datasources>
					<local-tx-datasource>
						<jndi-name>DefaultDS</jndi-name>
						<connection-url>jdbc:oracle:thin:@localhost:1521:xe</connection-url>
						<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
						<user-name>SYSTEM</user-name>
						<password>jboss</password>
						<valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</valid-connection-checker-class-name>
						<metadata>
							<type-mapping>Oracle9i</type-mapping>
						</metadata>
					</local-tx-datasource>
				</datasources>
				
			

<mbean code="org.jboss.mq.pm.jdbc2.PersistenceManager"
     name="jboss.mq:service=PersistenceManager">
<depends optional-attribute-name="ConnectionManager">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
....

SQL> connect; Enter user-name: SYSTEM Enter password:
Connected.
SQL> begin 2 dbms_xdb.sethttpport('8090'); 3 end; 4 /
PL/SQL procedure successfully completed.
SQL> select dbms_xdb.gethttpport from dual;
GETHTTPPORT
-----------
8090	

In this section, we'll connect the server to MS SQL Server 2000 using the latest JDBC driver (v1.2) available at http://msdn2.microsoft.com/en-us/data/aa937724.aspx.

 
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
  <jndi-name>DefaultDS</jndi-name>
  <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=pubs</connection-url>
  <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
  <user-name>sa</user-name>
  <password>jboss</password>
  <check-valid-connection-sql>SELECT 1 FROM sysobjects</check-valid-connection-sql>
  <metadata>
	  <type-mapping>MS SQLSERVER2000</type-mapping>
  </metadata>
  </local-tx-datasource>
</datasources> 		

<mbean code="org.jboss.mq.pm.jdbc2.PersistenceManager"
	name="jboss.mq:service=PersistenceManager">
 <depends optional-attribute-name="ConnectionManager">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
....

When testing a newly configured datasource we suggest using some very basic JDBC client code embedded in a JSP page. First of all, you should create an exploded WAR archive under the deploy directory which is simply a folder named "jdbcclient.war". In this folder, create a text document named client.jsp and paste the code below:

<%@page contentType="text/html"
 import="java.util.*,javax.naming.*,javax.sql.DataSource,java.sql.*"
 %>
 <%
   
  DataSource ds = null;
  Connection con = null; 
  PreparedStatement pr = null; 
  InitialContext ic; 
  try {
  ic = new InitialContext();
  ds = (DataSource)ic.lookup( "java:/DefaultDS" );
  con = ds.getConnection(); 
  pr = con.prepareStatement("SELECT USERID, PASSWD FROM JMS_USERS");
  ResultSet rs = pr.executeQuery();
  while (rs.next()) {
  out.println("<br> " +rs.getString("USERID") + " | " +rs.getString("PASSWD")); 
  }
  rs.close();
  pr.close();
  }catch(Exception e){
  out.println("Exception thrown " +e); 
  }finally{
  if(con != null){
  con.close();
 }      
}

Open up a web browser and hit the url: http://localhost:8080/jdbcclient/client.jsp. A list of users and password should show up as a result of the jdbc query:

dynsub | dynsub 
guest | guest 
j2ee | j2ee 
john | needle 
nobody | nobody