Changes: JBoss Modules

JBoss AS 7 is quite a different beast from its predecessors. The most striking difference is the usage of JBoss modules, which is a modular class loading system, comparable to Jigsaw, THE modular system for Java that will (one day) (probably) reach the JVM. Till that day however, JBoss modules can be used.

After downloading and unzipping the JBoss AS 7 CR1 release, you’ll find all the modules in the ”modules” subdirectory, grouped in a structure that somewhat resembles a maven repository: you’ll for example find directories for ”org”, ”javax” and ”net”, similar to the directory structure of group-ids and artifact-ids in a Maven2 repository layout. At some level, however, there will be a ”main” folder and that’s where the implementation details of the module are kept: a small XML file describing the module and some jar files that constitute the modules content. A very useful side effect of this is that finding out which versions of which jars the AS is using is rather simple: The jar files in the module are usually the maven artifacts and thus contain the version number in their name. See for example the javax.activation module below.

Another consequence of this change is that the usual JBoss structure with a ”server” directory with several profiles, like ”default”, ”web” and ”minimal” no longer exists. The main structure now has a ”standalone” directory for running a simple server, and a ”domain” directory for running a cluster.

Installation

Installation is as always straight forward. A development environment however is not ready for use without good integration between the IDE and the application server on the local system. IDE of choice is Eclipse, because of the nice JBoss Tools plugin suite. Following these instructions is already a large part of the installation.

To make things really easy, we include Maven integration for Eclipse with WTP from Sonatype into the mix. Especially finding the right version of the Maven integration for WTP was difficult. I finally found a copy that worked with the rest of the setup at this update site.

Starting the server can now be done from the Eclipse servers window. Browsing to the default port shows a nice welcome window and going to the admin console shows a simple but useful administrative interface.

Two small problems with the setup so far:
1. Eclipse doesn’t seem to detect the startup of the server. Which is kind of annoying, because Eclipse now wont compile anything since it is waiting for the process to end.

This can be worked around by setting the Startup Poller to ”Web Port Poller” in the Server overview screen of the JBoss 7 AS server.

2. Eclipse is not able to stop JBoss. At least not from the server view.

JBoss can still be stopped from the Console view, but that means restarting the server always takes at least 4 mouse clicks: (1) go to console (2) stop (3) go to servers (4) restart, which is kind of annoying.

Anyway, living with small annoyances is second nature for everybody in IT industry I suppose, so why would a simple JEE application developer be any different

Starting up the project

Now that everything is set up, we can continue to the more interesting part, the project and the Java code. With the help of M2Eclipse we create a maven project with the following pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.xebia.library</groupId>
	<artifactId>library</artifactId>
	<version>0.9-SNAPSHOT</version>
	<packaging>war</packaging>
	<repositories>
		<repository>
			<id>jboss</id>
			<url>https://repository.jboss.org/nexus/content/groups/public-jboss/</url>
		</repository>
	</repositories>
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-resources-plugin</artifactId>
				<version>2.4.3</version>
				<configuration>
					<encoding>UTF-8</encoding>
				</configuration>
			</plugin>
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>2.3.2</version>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
				</configuration>
			</plugin>
			<plugin>
				<artifactId>maven-war-plugin</artifactId>
				<version>2.1.1</version>
				<configuration>
					<failOnMissingWebXml>false</failOnMissingWebXml>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<dependencies>
		<dependency>
			<groupId>org.jboss.spec</groupId>
			<artifactId>jboss-javaee-6.0</artifactId>
			<version>2.0.0.CR1</version>
			<type>pom</type>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-jaxrs</artifactId>
			<version>2.2.1.GA</version>
			<scope>provided</scope>
		</dependency>
	</dependencies>
</project>

This pom will configure the maven project and the Eclipse-WTP project correctly for deployment on JBoss. The highlighted lines show the dependency on a pom with the Aggregated Java EE 6.0 APIs that JBoss provides. This pom is supposed to be used to import the right version numbers of all the Java EE APIs into your own pom. Since I am lazy, I’ll just depend on this pom, so all the APIs are already available in my project without having to specify them separately.

Now we have a well configured Maven Web project in Eclipse. The layout will look like the image below.

And now for some Java code, how do we configure RESTeasy framework?

package com.xebia.library;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("services")
public class LibraryApplication extends Application {

}

That’s it! From the class RESTeasy will be configured and the RESTful web services will be available at ”/services” in the context of the project.

Let’s add a simple web service.

package com.xebia.library;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import com.xebia.library.model.Book;

@Path("books")
public interface BookRepository {

	@GET
	@Path("/")
	@Produces(MediaType.APPLICATION_JSON)
	List<Book> all();
}

This interface defines the RESTful web service by means of the JAX-RS annotations. Adding an interface is useful, but not necessary.

package com.xebia.library.impl;

import java.util.Collections;
import java.util.List;

import com.xebia.library.BookRepository;
import com.xebia.library.model.Book;

public class BookRepositoryBean implements BookRepository {

	@Override
	public List<Book> all() {
		return Collections.singletonList(new Book("My Title"));
	}

}

The implementation of the web service is very simple (for now) and it uses a very simple POJO as return value.

package com.xebia.library.model;

public class Book {

	private String title;

	public Book() {
	}

	public Book(String title) {
		this.title = title;
	}

	public String getTitle() {
		return title;
	}
}

With these simple files, we have all we need to get a RESTful web service running on JBoss AS 7. Pointing the browser to the correct URL, we get a JSON string as shown below.

The URL is built up from a few parts:

1. http://localhost:8080 The JBoss web server
2. library The application context
3. services The path configured for the JAX-RS application in the @ApplicationPath annotation
4. books The path for the BookRepository resource as given in the @Path annotation

JBoss AS 7 comes with RESTeasy (an implementation of JAX-RS) and Jackson (a Java-JSON serializarion framework) configured and that is how the final result is obtained. This makes JBoss AS 7 an ideal platform for developing RESTful applications: it works out-of-the-box and is build on well known open source projects, making it easy to adapt the container to specific requirements in you application.

Conclusion

In this blog we have set up a development environment for JBoss AS 7 using Maven, Eclipse and WTP and we deployed a very simple RESTful application. The setup works pretty well.
Keep an eye out for new blogs, in which I’ll improve on the current project to show more aspects of JBoss 7 and RESTful applications.

1. The BLD (build) project is the parent project of all the other projects, that in turn are modules of the BLD project. The main purpose of this project is to provide a place for common configuration and a common build for all modules.
2. The WAR project depends on the EJB project, because it will use some of the services.
3. The EAR project depends on both the WAR and the EJB project, because these should be packaged in the ear.

Maven – Dependencies
Maven is all about dependencies. Luckily Seam libraries are available in the repositories, both the special repositories hosted by JBoss and the central repository. And there is more: Seam provides a very useful maven project, that can be used as the parent for our own project: org.jboss.seam:root. This project contains the JBoss repositories and a dependency management section that will ensure that compatible versions of all libraries are referenced. So the first step is to make our BLD project a child of the org.jboss.seam:root project.
Then we have to add the necessary dependencies for Seam.

• The EJB project depends on org.jboss.seam:jboss-seam:ejb and on org.hibernate:hibernate-entitymanager, since we’re gonig to use hibernate for persistence.
• The WAR project depends on org.jboss.seam:jboss-seam-ui. Now depending on your preference of front end technology, other dependencies will need to e added, but we will come to that later.

The good thing is that since we’re using the org.jboss.seam:root as parent, we don’t need to specify versions, this is handled by dependency management.
The Maven structure and dependencies (and some more support files like web.xml and ejb-jar.xml) can be packaged in a Maven archetype. Attached to this blog, you can find the one we are building right now. It can also be found in Xebias Opensource Maven repository or the snapshot repository.

Eclipse
Now, after handling Maven, let’s turn our attention to this Eclipse beast. We would like to have an easy path from the Maven project to the Eclipse development environment. Eventually we would like to have JBoss Tools running out-of-the-box starting from the simple Maven project. First let’s take a look at a JBoss Tools Seam project.
The image on the left shows the outline of a Seam project as created by JBoss Tools. There are 4 projects: test (WAR), test-ejb, test-ear and test-test. The last contains the tests, which in a maven project will be part of the same project, so we will not discuss it further. The other three projects are WTP enabled projects. looking at the configuration files (.settings/org.eclipse.wst.common.component in each project), we find that it is using WTP version 1.5.
Now we’ll try to build a similar configuration starting from the maven project.

Eclipse – WTP support
Maven has a maven-eclipse-plugin, that has as sole purpose to transform a maven project into a working eclipse project configuration. Unfortunately, it’s WTP support is seriously broken. To configure the plugin, we use this XML snipped, taken from the official documentation.

        maven-eclipse-plugin
        
          true
          true
          true
          1.5
          ${basedir}/src/main/resources/META-INF/MANIFEST.MF
        
      
    

This snipped should be placed in the pom.xml of the BLD project, so it is applied to all projects.

Now, running the eclipse:eclipse maven goal on the BLD project will generate the eclipse configuration (.project, .classpath and WTP files) for all projects. The version of the JEE specifications will be inferred by the maven-eclipse-plugin by looking at the maven dependencies for the respective specifications. To make sure the plugin generates the correct WTP configuration, we need to add the javax.ejb:ejb-api:3.0 dependency to the EJB project and the javax.serlet:servlet-api:2.5 to the WAR project. With this, the configuration for these two projects is working fine. Unfortunately, the EAR project is not working and cannot be deployed. For some reason WTP does not recognize the modules for this project and when trying to deploy it, some ClassCastException is thrown. So much for maven-eclipse-plugin…

eclipse:m2eclipse
…or not? The plugin features another goal, that could be useful here: eclipse:m2eclipse. This will generate the eclipse configuration in the same manner, but it will add the M2Eclipse plugin to the projects. This plugin has a lot of useful features: It makes synchronizing the eclipse configuration with the maven configuration a breeze. It will, for example, add the maven dependencies to the eclipse classpath, but it will also synchronize other properties, like the java version. Furthermore adding dependencies and changing the POM in general becomes really easy and, finally, creating new Maven project or modules from within eclipse becomes really easy.
This way of setting up the eclipse project is rather different from the previous one: In stead of generating all the configuration files correctly, the M2Eclipse plugin works from within eclipse to synchronize the eclipse and WTP configuration. The eclipse:m2eclipse goal does not work well with the configuration given above for the eclipse:eclipse goal, especially for EAR projects. It is better to remove all configuration from the maven-eclipse-plugin configuration and let the plugin do it’s work. This means that after generating the eclipse project files, you’ll have to open the Eclipse workspace and kick-off the synchronization process manually. More about this can be found on the Maven site for the archetype.

JBoss Tools support
JBoss tools is a Eclipse feature, that can be enabled on a project by adding some configuration (JSF and Seam facets, the SeamBuilder and SeamNature) to the eclipse project. JBoss Tools will manage two projects: the WAR and the EJB project, but the WAR project will be the main source of configuration. By adding the necessary items to the maven-eclipse-plugin configuration for this project and also adding a special Seam configuration file to the .settings directory, JBoss tools will recognize the project correctly.
For some reason, JBoss tools also stores some configuration in the workspace configuration. This can not be configured from the Maven Archetype and thus the JBoss Tools configuration is not complete. Because of this, the link between the WAR and EJB project will not be found by JBoss Tools from the EJB project. When a new Seam Artifact (Action, Entity, Form or Conversation) is added from the EJB project context meny, the configurations made in the WAR project are not picked up. When adding from the WAR project they are picked up and some sources will also be written in the EJB projects, as required.

JBoss Tools – JSF templates
JBoss Tools will generate Java sources and JSF pages when a new component is added. The JSF pages expect certain templates to exist in the Seam project and wont work correctly if they are not found. Adding these files to the Maven Archetype makes the generated JBoss Tools project work correctly. Also the Maven projects needs additional dependencies on RichFaces and Facelets in a certain configuration (some jars should go in the WEB-INF/lib, some in the EAR/lib) to make the deployed application work correctly.
The JBoss Tools project generated by the (current version of the) archetype will be exactly the same as a project created from within JBoss Tools, except for the security configuration.

Deploying on JBoss – application.xml troubles
One last problem arises when trying to deploy the generated application on JBoss AS 4.2: It will complain about the missing META-INF/application.xml. As per latest JEE spec, the application.xml is no longer mandatory, but JBoss AS 4.2 doesn’t handle this correctly. To make it work with WTP on JBoss and also with the Maven created artifacts, we have to apply a few tricks to make it all work:

1. We need to add an ‘empty’ application.xml file in the META-INF directory in src/main/application of the EAR project.
   This file is changed by the M2Eclipse plugin and used by WTP to make the deployment work on JBoss AS.
2. We let Maven generate an application.xml file during the build by setting the property generateApplicationXml on the ear plugin.
   The file is generated in the normal bulid directory and not the same as the previous.
3. We exclude the first file from the maven-bulid EAR file using the property earSourceExcludes on the ear plugin (value:META-INF/application.xml).
   this way the first file is ignored and the second is used in the maven build.

Et voila! At this point we have reached our goal of building a Seam project with Maven while still being able to use JBoss Tools, Eclipse and WTP for development.

Happy Coding!

So what is Seam??

Seam is a powerful open source development platform for building rich Internet applications in Java. Seam integrates technologies such as Asynchronous JavaScript and XML (AJAX), JavaServer Faces (JSF), Java Persistence (JPA), Enterprise Java Beans (EJB 3.0) and Business Process Management (BPM) into a unified full-stack solution, complete with sophisticated tooling(1). The simple chart of architectural design will show you about this:

Diagram 1.1 Architecute of Seam

So Seam basically does the job of plumbing these disconnected frameworks. We had all the good things in J2EE world, but making them work together was a pain. But, now we do have Seam to do all the dirty work for us.

How to get started with Seam application development??
Following could be the possible ways in which we could get started with a simple seam project structure.

• Seam- gen
• Jboss Tools
• Maven

It was really fun to work on Seam, as it greatly reduced the initial project setup time which we normally have with J2EE project. Seam is basically a tool which give you more Return on Investment (ROI) for the same number of lines you write in any other Java framework like spring or struts.

So, let’s get started with the main aim of this article to have feature differentitation between seam-gen and Jboss Tools .

First of all I would write something about both the Tools and after that will try to get into more details about each.

Seam-gen

We will start with using seam-gen to generate a project structure, as seam-gen provides out-of –box scripts to generate Seam Action, Entity and Conversations

So what is Seam-gen??

Seam-gen is a rapid application generator shipped with the Seam distribution. With a few command line commands, seam-gen generates an array of artifacts for Seam projects to help you get started. In particular, seam-gen is useful for the following.

• Automatically generate an empty Seam project with common configuration files, a build script, and directories for Java code and JSF view pages.
• Automatically generate complete Eclipse and NetBeans project files for the Seam project.
• Reverse-engineer entity bean objects from relational database tables.
• Generate template files for common Seam components.

Jboss tools

JBoss Tools is a collection of Eclipse plugins. JBoss Tools a project creation wizard for Seam, Content Assist for the Unified Expression Language (EL) in both facelets and Java code, a graphical editor for jPDL, a graphical editor for Seam configuration files, support for running Seam integration tests from within Eclipse, and much more.
In short, if you are an Eclipse user, then you’ll want to use JBoss Tools!

Now, we will mainly look at different aspects in which seam-gen and Jboss Tools are different and what could be the best option for building Seam application from scratch

Aspects in which they are different:

1. Project Structure
2. Build process
3. Deployment strategy
4. Profiles
5. Testing approach

Difference in Project Structure:

Seam-gen source directories

The source directories created by seam-gen are each dedicated to holding certain types of source files. This enables seam-gen to determine what tests need to be executed as well as selectively hot-deploy your Seam components.(Diagram 1.2)

So in this project structure, we only have one source folder which contains both, the EJB entities and the War content. This is one thing, which I don’t like about seam-gen. They could have provided a better project structure like the one we have with Jboss tools.

Jboss tools source directories

Jboss tools source directory is well arranged compared to the seam-gen project directory, as it follow the standard J2EE application packaging.In this struture we have a war project, ejb project and finally both of them bundled into a ear distribution. In addition to that they have separated out a test project, which is good for doing testing.This kind of structure also helps to manage large projects, where we have teams working on different module of the project.

Diagram 1.2 Project struture of Seam-gen and JBoss tools

Differences in Build process:

First let start with the build process seam-gen follows. The seam-gen project is built using the ant tool and they provide an extensive target in the build.xml. So most of what you want to do in different phases of application development, you can do that using the build.xml provided.

Some sample targets which might be of interest to everyone

In case of Jboss tools on the other hand, we don’t have a build.xml file provided, but we can tweet the build script of Seam-gen project to work with JBoss tools. I have attached a strip down version of the build.xml of seam-gen to provide the minimum task needed for Seam project, which works fine with JBoss Tools.

Differences in Deployment Process:

As we have already discussed that the Jboss tools can be configured to use Eclipse Web Tool Platform (WTP) Project, so when we deploy the seam application using WTP the ear bundle along with the datasource deployment descriptor file are copied to the following directory.

“C: workspace .metadata.pluginsorg.jboss.ide.eclipse.as.coreJBoss_4.2_Serverdeploy”

Whereas, in case of ant build, both the files goes directly into the Jboss main deploy directory .In my case it was this directory:

“C:Program Filesjboss-4.2.2.GAserverdefaultdeploy”

In this regard, the former process looks to be better, since we don’t clutter the main Jboss deploy directory.

Differences in Profiles

Seam-gen Profiles

Seam-gen supports the concept of “profile”. The idea is that the application probably needs different settings (e.g. database settings, etc) in the development, test, and production phases. So, the project provides alternative configuration files for each of the three scenarios. In the resources directory, you will find the following configuration files:

/META-INF/persistence-*.xml	Provides configuration of a JPA persistence-unit for each environment.
import-*.sql	Imports data into a generated schema based on deployment environment. Generally useful for testing purposes.s
components-*.properties	Allows wild-card replacement of Seam component properties based on environment.

Jboss Tool Profiles

Jboss tools doesn’t provide any support for profiles , so we only have one set of configuration files, which we have to use for different phases by making changes in them .

So this could be one more drawback of using Jboss tools.

Differences in Testing approach:

Testing is a very important part of the Agile programming, so we also need a very good project structure for doing the same. Jboss tools, surely knows this and have done a good job of keeping a separate project, only for test. This really solves lot of problems you might face while running test in Eclipse for a seam- gen project

For a seam-gen project, if you are running test using ant task then its fine, but otherwise you would need to make some changes in classpath of all the test classes.

Conclusion Matrix:

We could conclude this article with a matrix which contains feature by feature comparison.

For me mixture of both is the winner for developing a Seam application.But till we don’t have that from the Seam’s framework , we can surely go with Jboss Tools. Even though it misses the ant support, we can tweak the ant script provided by seam-gen and use it in our Jboss Tools project.

References

1. Build. xml for JBoss Tools Project (Build.xml)
2. http://seamframework.org/
3. Seam-gen Command guide http://www.jboss.org/community/docs/DOC-10750
4. Seam-gen and JBoss Tools together http://relation.to/Bloggers/UsingASeamgenProjectInJBossTools