JBoss Application Server

You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.

To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's downloads folder.

[user@localhost]$ cd /home/user/downloads/jboss-<release>-src/build
[user@localhost build]$ ls
aspects    component-matrix  docbook-support  iiop     jmx           mbeans          security    system-jmx  tools
bootstrap  connector         ejb3             j2se     jmx-remoting  messaging       server      testsuite   varia
build      console           embedded         jbossas  main          pom.xml         spring-int  thirdparty  webservices
cluster    deployment        hibernate-int    jbossmq  management    profileservice  system      tomcat

From the contents of the build directory above, you can see the build.xml file which is used by Apache ANT as a configuration file when building your source files. The next step is to perform the build using Apache ANT as illustrated below.

[user@localhost build]$ ant
	
compile-classes:
[mkdir] Created dir: /jboss/jboss-<release>-src/tomcat/output/classes
[javac] Compiling 89 source files to /jboss/jboss-<release>-src/tomcat/output/classes
....
....content truncated
.....
.....
_buildmagic:build-bypass-check:
jars:
most:
main:
BUILD SUCCESSFUL
Total time: 2 seconds

A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the build/output/jboss-<release> directory as indicated below.

[user@localhost build]$ ls
build.bat        build-old.xml      build-thirdparty-old.xml  eclipse.psf       output
build-distr.xml  build-release.xml  build.xml                 etc               pom.xml
build.log        build.sh           docs                      local.properties  VersionRelease.java

[user@localhost build]$ cd output/jboss-<release>
[user@localhost build]$ ls
bin  client  docs  lib  server

Before you can run the JBoss Application Server, you need to ensure that you've configured the JBOSS_HOME environment variable in your .bashrc file as follows. In this example the Application Server folder has beeen copied to the /usr/jboss/jboss-<release> folder. The following is a .bashrc file used in this installation. Please ensure that your .bashrc file has a similar configuration.

[user@localhost ~]$ gedit .bashrc
	
# Source global definitions
if [ -f /etc/bashrc ]; then
/etc/bashrc
fi
......
# User specific aliases and functions
# The following are the environment variables for Java, ANT and JBoss

export JAVA_HOME=/usr/java/jdk1.6.0_07
export PATH=$PATH:$JAVA_HOME/bin
	
export ANT_HOME=/usr/ant/apache-ant-1.6.0
export PATH=$PATH:$ANT_HOME/bin

export JBOSS_HOME=/usr/jboss/jboss-<release>
export PATH=$PATH:$JBOSS_HOME/bin

To implement your .bashrc file changes run the following command.

[user@localhost ~]$ source .bashrc
[user@localhost ~]$

If no errors are displayed on your terminal, you are now ready to run your JBoss Application Server.

You are now ready to start the 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.

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).

The Release Notes for JBoss Application Server 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.

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. Please install Ant if currently not installed on your computer.

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.

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.

The persistence manager of JBoss Messaging uses the default datasource to create tables to store messages, transaction data and other indexes. Configuration of "persistence" is grouped in xxx-persistence-service.xml files. JBoss Application Server ships with a default hsqldb-persistence-service.xml file, which configures the Messaging server to use the Hypersonic database instance that ships by default with the JBoss Application Server.

You can view the hsqldb-persistence-service.xml file in configurations based on the all or default configurations:

<JBoss_Home>/server/all/deploy/messaging/hsqldb-persistence-service.xml  and
			<JBoss_Home>/server/default/deploy/messaging/hsqldb-persistence-service.xml

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();
 }      
} %>