Showing posts with label maven. Show all posts
Showing posts with label maven. Show all posts

Friday, July 30, 2010

Using Seam 2 with JPA 2

It’s a difficult time to architect new Java web applications. Seam 2 is a proven and well working application stack, but we will hardly see many new versions on the Seam 2 train. Java EE 6 is in general an excellent option, but if your customer’s choice of application server does not yet support it, it is not reasonable. Also there is still some time left for Seam 3 prime time, which builds on top of Java EE 6.

Facing this kind of choice recently, I looked into possible migration paths between the two variants. One thing I have seen often on Seam 2 applications is that people really like the Hibernate criteria API and therefore use Hibernate directly. While Hibernate is an excellent ORM framework, it’s preferrable to use the JPA API when moving to Java EE 6. So - why not use Seam 2 with JPA 2, which finally features an even better (typesafe) criteria API?

It turns out to be a quite easy setup (once you get classloading right), with some small extra modifications. I’ve been using Maven, Seam 2.2 and Hibernate 3.5.4 on JBoss 4.2.3. Lets start with preparing the server. You need to remove the old Hibernate and JPA classes and add the new persistence provider with some dependencies (of course this will be different on other servers):

To be removed from server/lib:


Add to server/lib:


Next lets create a sample Seam project. I’m using the CTP Maven archetype for Seam. In the POM file, remove the references to the Hibernate and old JPA libraries and add the new JPA 2 libraries:

<!-- Remove all embedded dependencies
<dependency>
<groupId>org.jboss.seam.embedded</groupId>
<artifactId>...</artifactId>
</dependency -->

<dependency>
<groupId>org.hibernate.javax.persistence</groupId>
<artifactId>hibernate-jpa-2.0-api</artifactId>
<version>1.0.0.Final</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>3.5.4-Final</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>1.0.0.Final</version>
<scope>provided</scope>
</dependency>

Note: If you’ve been using embedded JBoss for your integration tests, this will probably not work without exchanging the JARS there too. I’ve been moving away from this approach as it turned out to be a common reason for headache on our nightly builds as well as running tests in Eclipse. I’m very excited to see Arquillian evolving on this topic!

JPA 2 integrates with JSR 303 bean validation, which is the successor of Hibernate Validator. Unfortunately Seam 2 has references to Hibernate Validator 3, where JPA needs version 4. Adding the validator legacy JAR fixes this problem. As bean validation is now part of Java EE 6, we can add it to the server classpath as shown above, as well as to our POM:

<dependency>
<artifactId>validation-api</artifactId>
<groupId>javax.validation</groupId>
<version>1.0.0.GA</version>
<scope>provided</scope>
</dependency>

Now it’s time to move to some code. You can jump straight in your persistence config files and bring the schema up to version 2:

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0"> ...

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_2_0.xsd"
version="2.0"> ...

Seam proxies entity managers to implement features like EL replacements in JPQL queries. This proxy does not implement methods new in JPA 2 and will therefore fail. You can write your own proxy very easy:

public class Jpa2EntityManagerProxy implements EntityManager {

private EntityManager delegate;

public Jpa2EntityManagerProxy(EntityManager entityManager) {
this.delegate = entityManager;
}

@Override
public Object getDelegate() {
return PersistenceProvider.instance()
.proxyDelegate(delegate.getDelegate());
}

@Override
public void persist(Object entity) {
delegate.persist(entity);
}
...
}

Add the special Seam functionality as needed. In order to use the proxy with Seam, you’ll have to overwrite the HibernatePersistenceProvider Seam component:

@Name("org.jboss.seam.persistence.persistenceProvider")
@Scope(ScopeType.STATELESS)
@BypassInterceptors
// The original component is precedence FRAMEWORK
@Install(precedence = Install.APPLICATION,
classDependencies={"org.hibernate.Session",
"javax.persistence.EntityManager"})
public class HibernateJpa2PersistenceProvider extends HibernatePersistenceProvider {

@Override
public EntityManager proxyEntityManager(EntityManager entityManager) {
return new Jpa2EntityManagerProxy(entityManager);
}

}

If you use Hibernate Search, have a look at the superclass implementation - you might want to instantiate a FullTextEntityManager directly (as you have it in your classpath - but note that this has not been tested here).

Both implementations are on our Google Code repository, and you can integrate them directly over the following Maven dependency:

<dependency>
<groupId>com.ctp.seam</groupId>
<artifactId>seam-jpa2</artifactId>
<version>1.0.0</version>
</dependency>


You’re now ready to code JPA 2 queries! We’ve already included the meta model generator utility, so let’s activate it for the build:

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-source</id>
<phase>validate</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${basedir}/src/main/hot</source>
<source>${basedir}/target/metamodel</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<version>1.3.1</version>
<executions>
<execution>
<id>process</id>
<goals>
<goal>process</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<outputDirectory>${basedir}/target/metamodel</outputDirectory>
<processors>
<processor>
org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor
</processor>
</processors>
</configuration>
</execution>
</executions>
</plugin>


In order to use the processor plugin, you also need the following Maven repositories in your POM:

<pluginRepository>
<id>annotation-processing-repository</id>
<name>Annotation Processing Repository</name>
<url>http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenrepo</url>
</pluginRepository>
<pluginRepository>
<id>jfrog-repository</id>
<name>JFrog Releases Repository</name>
<url>http://repo.jfrog.org/artifactory/plugins-releases</url>
</pluginRepository>

Run the build, update the project config to include the new source folder - and finally we’re ready for some sample code:

@Name("userDao")
@AutoCreate
public class UserDao {

@In
private EntityManager entityManager;

private ParameterExpression<String> param;
private CriteriaQuery<User> query;

@Create
public void init() {
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
query = cb.createQuery(User.class);
param = cb.parameter(String.class);
Root<User> user = query.from(User.class);
query.select(user)
.where(cb.equal(user.get(User_.username), param));
}

public User lookupUser(String username) {
return entityManager.createQuery(query)
.setParameter(param, username)
.getSingleResult();
}
}

This is now quite close to Java EE 6 code - all we will have to do is exchange some annotations:

@Stateful
public class UserDao {

@PersistenceContext
private EntityManager entityManager; ...

@Inject
public void init() { ...
}

Enjoy!

Wednesday, April 28, 2010

JBoss Seam Maven Archetype Video Tutorial

While the release of Seam 3 is getting closer, you might still want to do quick prototyping based on a Seam 2 project. Of course this is easiest done with either seam-gen, or if you're like me a Maven user, with an Archetype.

Chris has prepared a video tutorial on how to get started with our Maven WAR archetype (featuring hot deploy, TestNG with embedded JBoss and either RichFaces or ICEFaces inclusion) based on one of my previous articles. Check it out here (best seen in HD [UPDATE: sorry, missed the HD embed]):



Enjoy!

Friday, October 30, 2009

Unit Testing EJBs and JPA with Embeddable GlassFish

Java EE 6 has been a topic here at CTP for quite a while now. During summer I had the pleasure of conducting an internship which was targeted to explore the possibilities of the upcoming standard, namely EJB 3.1, JPA 2.0, JAX-RS, JSF 2.0 and JCDI on top of GlassFish v3 - and it turned out surprisingly productive, although all implementations were far from being in a release state!

Only one thing we failed to run in a stable way: The new EJB 3.1 container API refused to run our unit tests. The main problem was JPA support - persistence units got not recognized and EJBs usually failed with a NullPointerException calling the EntityManager.

Alexis and Adam recently blogged about this specific feature, and of course I had to get back and try it out myself! Indeed, starting up a container and looking up EJBs works fine. But to test your Entities there are still a few tweaks you might want to apply.

Start with creating a Maven project and add the embeddable GlassFish dependency. I'm also using TestNG instead of JUnit, as it has a nice @BeforeSuite annotation which allows starting the container only once before running your tests.

<dependency>
<groupId>org.glassfish.extras</groupId>
<artifactId>glassfish-embedded-all</artifactId>
<version>3.0-b69</version>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>5.9</version>
<scope>test</scope>
<classifier>jdk15</classifier>
</dependency>

As described in Alexis' blog, you can start your EJBContainer with a reference to your GlassFish domain. This will allow you to start up data sources you most probably need to properly test your JPA code.

The disadvantage here is that you either depend on a hardcoded location or a system property which each of your team members have to set. Or, in case of your continuous integration system, you might not want to have a GlassFish installation at all.

Fortunately you can create a mini GlassFish domain with only a few files. The image below shows the files you need and how I placed them in my Maven module:



You can take your existing domain.xml containing your data sources and place it in here - you can reference it now relatively to your module location. Your unit tests then start with:

private static Context ctx;
private static EJBContainer container;

@BeforeSuite
public static void createContainer() {
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(EJBContainer.MODULES, new File("target/classes");
properties.put("org.glassfish.ejb.embedded.glassfish.installation.root",
"./src/test/glassfish");
container = EJBContainer.createEJBContainer(properties);
ctx = container.getContext();
}

This will run your unit tests against your development database. In case you want to run them in a local database, you can simple replace the connection pool config in your domain.xml, e.g. with a local Derby installation:

<jdbc-connection-pool datasource-classname="org.apache.derby.jdbc.EmbeddedDataSource"
res-type="javax.sql.DataSource" name="[your DS name]" ping="true">
<property name="ConnectionAttributes" value="create=true" />
<property name="DatabaseName" value="./target/unit-test" />
<property name="Password" value="" />
<property name="User" value="" />
</jdbc-connection-pool>

This creates the database in your target folder and requires adding Derby to your Maven POM:

<dependency>
<groupId>org.apache.derby</groupId>
<artifactId>derby</artifactId>
<version>10.5.3.0_1</version>
<scope>test</scope>
</dependency>

Unfortunately this setup might not match with the configuration in your persistence.xml and generate invalid SQL for your test database. You can either solve this with Maven filters in different profiles, or alternatively create a staging directory for your EJBContainer. I'm using the Apache Commons IO tools here for convenience:

...
private static final String MODULE_NAME = "embedded";
private static final String TARGET_DIR = "target/" + MODULE_NAME;

@BeforeSuite
public static void createContainer() throws Exception {
File target = prepareModuleDirectory();
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(EJBContainer.MODULES, target);
properties.put("org.glassfish.ejb.embedded.glassfish.installation.root",
"./src/test/glassfish");
...
}

private static File prepareModuleDirectory() throws IOException {
File result = new File(TARGET_DIR);
FileUtils.copyDirectory(new File("target/classes"), result);
FileUtils.copyFile(new File("target/test-classes/META-INF/persistence.xml"),
new File(TARGET_DIR + "/META-INF/persistence.xml"));
return result;
}

You can use the @AfterSuite annotation to clean up the temporary folder. Note that with this setup, the EJB lookups change:

protected <T> T lookupBy(Class<T> type) throws NamingException {
return (T) ctx.lookup("java:global/" + MODULE_NAME + "/"
+ type.getSimpleName());
}

Friday, September 18, 2009

Thoughts on Jason van Zyl talking about Maven 3

Today I've been to the talk from Jason van Zyl hosted by the JUGS (Java User Group Switzerland, yes I know it's a ridiculous name). He is one of the authors of Maven 1 and 2, he talked about Maven 3 and what it's going to bring us. And I must say it's quite impressive. Being an open source contributor myself I know that good software is written in 3 times. This was also the main point of his talk. He first made the joke that he never expected us to use Maven 1 but that Maven 2 was useable, and now they are fixing everything in Maven 3. I now use Netbeans because I love the Maven support that it's got. But with Maven 3 they are also developing the m2eclipse plugin. And what Jason told us during his presentation is that also here they are fixing a lot of things there. For instance Maven will have a query-able life cycle, with this eclipse can use only a part of Maven for instance to do a compile. So no longer adding a resource will kickoff an entire maven build and 5 minutes later we are ready to code again. I still think that the editor of Eclipse is better than the one Netbeans provides and Jason also says that the Maven integration was better in Netbeans. In fact they've used a lot of the Netbeans plugin features in the new m2eclipse plugin. Knowing all this I must really give Eclipse another try. What the new maven 3 also will have is a way to describe your maven model how you would like it, so for instance you could use ruby or groovy to create you're maven object model, instead of a xml, we could do something with this just don't know what. One thing I'm really excited about is they are making the maven integration also communicate with other plugins. For instance when you make changes in the WTP plugin about your war, this will also be put in you're pom. The same holds true for PMD plugin, the settings that are in your pom will also be set in the PMD plugin and changes made will reflect back.

Jason is quite a talker, his slides were full with text and he only briefly stopped talking to take a zip of water. His company also makes Nexus a proxy for maven repositories. Other products that do something similar are Artifactory or Archiva. The cool things they've build into Nexus is the ability to also be a proxy for Eclipse plugins. But all the cool things about Nexus are in the commercial version of Nexus like for instance LDAP authentication and lots of features around provisioning repositories.

Talking about their commercial products, they also sell this concept where one can have everything setup for a developer in one go. The m2eclipse plugin will discover where Nexus is, install the necessary plugins, show the projects a developer can work on and even download wiki documentation from confluence or twiki. This can all be configured by the technical lead of the project. I really like this concept, to many times I've seen it take days for a new developer to be up to speed. Not only taking time on his one, but also needing intensive support. With this in place some of that time can be saved.

So all in all I'm very positive about this presentation, JUGS keep up the good work. And I'll be trying the dev build of maven 3 and m2eclipse right away tomorrow. I'll let you know how it works out.

Wednesday, July 1, 2009

JBoss Seam Archetype - now with ICEfaces

Last week I visited Jazoon - and had a great opportunity to see several impressive demos of ICEfaces! Of course I had to immediately get my hands on it, and started to integrate ICEfaces in the JBoss Seam Maven archetype (as described in my previous post).

You can give it a spin by starting a shell and running Maven with the Archetype plugin:

>mvn archetype:generate -DarchetypeCatalog=http://tinyurl.com/jbsarch -DajaxLibrary=icefaces
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
...
Choose archetype:
1: http://tinyurl.com/jbsarch -> jboss-seam-archetype (Archetype for JBoss Seam Projects)
Choose a number: (1): 1
Define value for serverDir: : [your JBoss 5 server location]
Define value for groupId: : [your groupId]
Define value for artifactId: : [your artifactId]
Define value for version: 1.0-SNAPSHOT: : [your version]
Define value for package: : [your package]
Confirm properties configuration:
serverType: jboss5
ajaxLibrary: icefaces
...
Y: : y
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...


Make sure you don't misspell "icefaces", this will otherwise screw up the application. No input validation in Maven Archetype yet, but I started looking into it ;-)

Again, change to the project directory and build the project:

>mvn package

Now this also executes a sample unit test (fingers crossed it works this time ;-) - thanks to Oscar for the feedback!

Have fun with it! Anybody mind contributing a decent layout template?

Friday, June 19, 2009

Creating a JBoss Seam Maven Archetype

In case you're a regular reader of this blog, I guess you're aware that I'm a frequent user of both Maven and JBoss Seam - and that I'm regularly trying to combine working with both! My usual approach for setting up a new project was either to start with an empty Maven web application project and copying the missing files over, or to start with a seam-gen project and move it into a Maven structure. Both less than ideal...

Maven provides so called archetypes for a quick project setup. As there is not (yet?) an official archetype for Seam projects, I've been working on my own - and here's how you can use it as well!

All you need is
  • a recent version of Maven downloaded (I used 2.0.10)
  • and the Maven executable referenced in your path so you can use it on the console.
Open up a console, cd to your projects directory and type:

mvn archetype:generate -DarchetypeCatalog=http://tinyurl.com/jbsarch

This will start Maven and show the following command line output:

[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: http://tinyurl.com/jbsarch -> jboss-seam-archetype (Archetype for JBoss Seam Projects)
Choose a number: (1):


The remote archetype catalog contains so far only one archetype (BTW: the jbsarch in tinyurl.com/jbsarch stands for JBoss Seam ARCHetype - hope you can remember this better than the full URL :-) Select the archetype by typing 1 and enter your Maven project properties as well as your JBoss Server directory:

[INFO] snapshot com.ctp.archetype:jboss-seam-archetype:1.0.0-SNAPSHOT: checking for updates from jboss-seam-archetype-repo
Define value for serverDir: : /Developer/Servers/JBoss/jboss-5.1.0.GA
Define value for groupId: : com.ctp
Define value for artifactId: : fluxcapacitor
Define value for version: 1.0-SNAPSHOT: :
Define value for package: com.ctp: : com.ctp.fluxcapacitor
Confirm properties configuration:
serverType: jboss5
serverDir: /Developer/Servers/JBoss/jboss-5.1.0.GA
groupId: com.ctp
artifactId: fluxcapacitor
version: 1.0-SNAPSHOT
package: com.ctp.fluxcapacitor
Y: : y
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4 minutes 57 seconds
[INFO] Finished at: Fri Jun 19 19:12:19 CEST 2009
[INFO] Final Memory: 12M/79M
[INFO] ------------------------------------------------------------------------


Note that the serverType property defaults to jboss5. If you have a JBoss 4.2.x installation, quit with n and retype everything (hmm...) and use jboss4 instead.

In case anything fails here, make sure your archetype plugin is at least version 2.0-alpha-4 (I had to delete the local repo info file in the local repository once). Now with your project created, lets build and deploy it!

Aragorn:sandbox thug$ cd fluxcapacitor/
Aragorn:fluxcapacitor thug$ mvn package
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] [fluxcapacitor]
[INFO] [fluxcapacitor :: JBoss Configuration]
[INFO] [fluxcapacitor :: Web Application]


The project currently features two modules: One with the actual web application, and the other one containing JBoss Server configuration files. With the basic archetype you only get a datasource there, but you can also use it to change server ports, define security realms, queues etc.

Environment specific properties are referenced in filter property files. You can find the development filter file in ${artifactId}/environment/filters/${artifactId}-development.properties. The filter file selection happens in the parent POM. It defines a development profile which sets the environment property. Setting this property to test will look for a ${artifactId}/environment/filters/${artifactId}-test.properties filter file.

Note that the parent POM contains your JBoss installation directory hard coded. You might want to factor this out into a developer specific profile when working in a team. Fire up your JBoss instance. Everything should start up well (fingers crossed...) and you can point your browser to the base URL of your application.


Done! Import the project in your favorite IDE and start prototyping!

Unfortunately this is still far away of what seam-gen provides up to now. Maven archetypes have improved over time but are currently still not as flexible to be useful in complex setups:
  • Entering project properties is not even close to be user friendly. At least a description, input validation (enumerations) and reasonable handling of default values might help.
  • Conditional installation of files. If you know how this works - let me know :-) This would be required to distinguish between WAR and EAR projects, and for targeting different applications servers (yeah, like GlassFish!).
In case I find some time to contribute something here, I'll report back. If you have feedback / contributions to the archetype, this is as usual very welcome (the code is available at our Google Code repository)!

Friday, May 29, 2009

JBoss Seam Hot Deploy with Maven - EAR Projects

As requested on some comments on my previous posts (initial post and update), the Seam Hotdeploy Maven plugin now works also with EAR projects.

Some more details on how to configure your project can be found in our Google Code Wiki. The plugin now defines a new packaging type for Seam WAR modules - the only possibility to override the war:war goal in the package phase.

If you're interested in how to override the default lifecycle Maven goal, you can check out the plugin source - something I haven't been able to google easily. Or, maybe wait for a dedicated blog post - stay tuned!

Something you should definitely checkout with the Hot Deploy plugin is the Maven CLI plugin. See the great post from Dan here, or the integration in the sample POM.

As usual, feedback and contributions are very welcome!

Friday, March 20, 2009

JBoss Seam Hot Deploy with Maven - Update

I just published an updated version of the Seam Hotdeploy Maven Plugin (see my previous post here). For a detailed description on how to use it, have a look at the Google Code Wiki. I also updated the sample Maven POM featuring JBoss Seam 2.1.1.GA.

The new version should be easier to configure and play nicer with e.g. the Eclipse Maven plugin (I'm not using NetBeans/IntelliJ too often, but I hope this works also fine there). The new Eclipse builder configuration looks like shown in the image below:



Note: The Eclipse Maven plugin using its embedded Maven had somehow problems with the extended lifecycle of the Hotdeploy Plugin. Using an external Maven installation (2.0.10) felt not only faster but was also not having problems with it.

Saturday, December 6, 2008

Using JBoss Seam Hot Deployment with a Maven Build

[UPDATE: The new plugin version is documented here]

As you might have read in previous posts, one of our favorite web application stacks consists of JBoss Seam. While combining this with our favorite tooling suite consisting of Eclipse and Maven, we had to realize that Seam has a much longer tradition with Ant, and Maven support is only slowly moving in. Today I want to share some ideas on how to tackle the combination issues.


While JBoss Tools provides a nice code hot deployment feature when working with Seam on JBoss, things can get a little hairy when using a Maven build with the project. Seam uses a special classloader and relies on monitoring the WEB-INF/dev folder for changed classes - where Maven is completely unaware of this and uses the standard WEB-INF/classes folder to deploy all classes in the project. More than once I've seen the situation where JBoss Tools and Maven got in each others way, ending with JBoss rejecting to restart the application due to "duplicate components". The reason was that Eclipse hot deployed classes to WEB-INF/dev where Seam expects them, but Maven being completely unaware of it packaging all classes in the common WEB-INF/classes folder.

In order to avoid trouble and also to allow using hot deployment from a command line build, I experimented with several approaches to achieve hot deployment with Maven. The main challenges here are:
  • Distinguishing compiler output: The Maven compiler plugin by default compiles everything in the same output folder. We need to be able to distinguish between hot and regular deployable code.
  • Publish updated resources to JBoss, including domain model classes, seam components as well as XHTML pages.
  • Make sure Seam unit tests still compile.
The solution I came up with was to write a new Maven plugin which extends the Maven compiler plugin with a new hotdeploy:compile goal and the following functionalities (source code as well as a simple Maven 2 repository is available in our Google Code account):
  • Hook into the compile phase and compile the source code to a dedicated directory. The source code location is configurable as well as the output directory.
  • Remove outdated hot deployable class files from the JBoss deployment. This is necessary for the Seam classloader to pick up the changes, only updating the file is not enough.
The plugin configuration is straight forward as it's based on the regular compiler plugin and is shown in the XML snippet below. Note that it is recommended to create a profile for this build setup as both your continuous build as well as your operations team might not care too much about using hot deployment.
<plugin>
<groupId>com.ctp.seam.maven</groupId>
<artifactId>maven-hotdeploy-plugin</artifactId>
<version>0.1.0</version>
<configuration>
<source>${java.source.version}</source>
<target>${java.source.version}</target>
<hotdeployOutputDirectory>${directory.hotdeployables}</hotdeployOutputDirectory>
<includes>
<include>**/session/**</include>
</includes>
<deployDirectory>
${directory.deploy.jboss}/${build.finalName}.${project.packaging}
</deployDirectory>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>

The main additions to a regular compiler plugin setup are:
  • This variant uses the common /src/main/java source folder and uses in- and excludes to distinguish the hot deployable sources. Alternatively you can set the sourceDirectory configuration value pointing to a dedicated source folder (similar as JBoss Tools does the setup for you). Don't forget that this requires then the Build Helper Maven plugin to add source folders to your regular build.
  • The deployDirectory is a reference to your exploded application directory inside the JBoss deploy folder. This is needed in order to remove outdated hot deployable classes.
  • You can specify the hotdeployOutputDirectory directory where the code should be compiled to. Note that this defaults to the value shown in the example - feel free to skip this part. The plugin will compile into this folder after appending a WEB-INF/dev to the path.
The rest of the setup we can do by simply reconfiguring existing plugins. Note the Google Code Wiki contains a complete sample POM ready for you to start your own Seam webapp. The details on the configuration are:
  • Reconfiguring the WAR plugin so the webappDirectory points inside our JBoss deploy folder. Maven uses this folder to assemble the WAR file, which perfectly corresponds to an exploded deployment. Additionally we define our hot deployment compilation folder as a webResource, which will copy our compilation exactly to the WEB-INF/dev folder in the exploded deployment.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<webResources>
<resource>
<directory>${directory.hotdeployables}</directory>
<filtering>false</filtering>
</resource>
</webResources>
<webappDirectory>
${directory.deploy.jboss}/${build.finalName}.${project.packaging}
</webappDirectory>
</configuration>
</plugin>

  • Similarly, we have to add our output folder to the test classpath. This is simplest done by adding it as a resource folder, which will copy the classes to the target/test-classes directory before the test classes are compiled:
<testResources>
<testResource>
<directory>${directory.hotdeployables}/WEB-INF/dev</directory>
<filtering>false</filtering>
</testResource>
...
</testResources>

If you want to run a similar luxury setup as you get from JBoss Tools, you can add a Maven builder to your project. Simply go to the Eclipse Project properties and click "New" on the "Builders" properties. The new Maven build should look like the following:



Make sure that the following conditions apply to your Eclipse setup:
  • The JRE you have configured is actually a JDK - otherwise the builder will fail. Once you see that the builder does not fail, you can also switch off the console allocation in the "Common" tab.

  • Also take care that you always build with your specific hot deploy profile - otherwise make sure to clean before using the build again.

  • Assert that Eclipse uses a dedicated output folder and not the Maven target/classes.

Unfortunately when activating the builder Eclipse might prompt you when editing files and (depending on the speed of your machine) hang for a second or two after saving a file. Still, this is much better than waiting a minute for your JBoss server to restart.

Happy coding!

Friday, September 26, 2008

Adding JCR support to your existing web application

In addition to the two recent technology posts (1, 2) that contained a product and technology overview about JCR, this post is guiding you through the practical steps in order to add JCR support to your web applications.

A new alternative to manage your application data is to store it in a content repository. The approach brings some advantages if compared to the most widespread persistence mechanism in use currently, the relational databases. The main advantage is the ability to have unstructured data. You can store your data first, and then define how it’s going to be organized and how the pieces of persistent information relate to each other. Besides the fact that not enforcing data integrity constraints, when they are not necessary, certainly helps in your application performance. This feature is especially useful when it’s necessary to enhance the data model. Relational databases are known for not having a very flexible structure. On the other hand, the JCR API was designed to target this need.
Suppose that you got a request to have a modification date added to some of your entities. In the relational model you’ll have to find out which tables should get the new field, and maybe provide an initial value for the column. Using JCR, you can simply have this modification date available only in the newly created entities. There is no need to concern about the existing data, because with JCR you can add and remove attributes on-the-fly. There is also no need to change any structure information, because it’s not required to declare any structure at all. If you would like to add a JCR repository to your existing web application, here is a walkthrough covering all the required steps.
The presented scenario assumes a Maven 2 web application, to be deployed in a Tomcat 5.5 server.
If you don’t have a web application to start with, or if you prefer to use a test project first, I suggest you to use Apache Maven to create a simple web project. To do so, run the following command in an empty directory:


mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-webapp \
-DgroupId=com.ctp.jcr.sample -DartifactId=webapp -Dversion=0.1 \
-Dpackage=com.ctp.jcr.sample.webapp


The “archetype:create” Maven goal will create an empty web project called “webapp”. Let’s import this project into Eclipse, so it will be easier to change it. Change to the project directory and run the following command to generate the Eclipse specific project configuration files:


mvn eclipse:eclipse -Dwtpversion=1.5


The project is ready to be imported by Eclipse (File > Import > Existing projects into workspace; no Maven for Eclipse plugin is required, just an environment variable needs to be configurated).
Another approach to create this project is to use a Maven plug-in for Eclipse called m2eclipse. After installing it, you can create a Maven project by opening the menu “File > New > Other…” and choosing “Maven Project”. In the “New Maven Project” wizard, click “Next”, Choose the “Internal” catalog and in the archetypes list, choose “maven-archetype-webapp”. Click “Next” and provide the group ID “com.ctp.jcr.sample” and the artifact ID “webapp”. To complete the project creation, click “Finish”.
The next step is to add the proper dependencies to the project’s POM. So change it to match the following dependencies:


<dependency>
<groupId>javax.jcr</groupId>
<artifactId>jcr</artifactId>
<version>1.0</version>
</dependency>
<dependency>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>jackrabbit-core</artifactId>
<version>1.4.5</version>
<scope></scope>
</dependency>
<dependency>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>jackrabbit-jcr-rmi</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>jackrabbit-jcr-server</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>jackrabbit-webapp</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>commons-collections</groupId>
<artifactId>commons-collections</artifactId>
<version>3.2.1</version>
</dependency>
<dependency>
<groupId>xerces</groupId>
<artifactId>xercesImpl</artifactId>
<version>2.8.1</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.4</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jsp-api</artifactId>
<version>2.0</version>
<scope>provided</scope>
</dependency>


After changing the POM file, run the “eclipse:eclipse” goal again, and refresh your Eclipse project. As the JCR API has a “provided” scope, the JAR file which can be found in your local Maven repository (~/.m2/repository/javax/jcr/jcr/1.0/jcr-1.0.jar) should be copied to the shared/lib Tomcat folder.
Using a context descriptor file (create the file webapp/src/main/webapp/META-INF/context.xml) a shared resource, the JCR repository, will be defined. This resource receives essentially two important parameters: “configFilePath”, which is the absolute path to the repository descriptor (the “repository.xml” file, to be explained in the next steps) and “repHomeDir”, the absolute path to the directory which will contain the repository data files.


<Context>
<Resource name="jcr/repository"
auth="Container"
type="javax.jcr.Repository"
factory="org.apache.jackrabbit.core.jndi.BindableRepositoryFactory"
configFilePath="c:/TEMP/webapp/repository/repository.xml"
repHomeDir="c:/TEMP/webapp/repository" />
</Context>


This shared resource needs to be declared in the web.xml file:


<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<display-name>Archetype Created Web Application</display-name>
<resource-ref>
<description>JCR Repository</description>
<res-ref-name>jcr/repository</res-ref-name>
<res-type>javax.jcr.Repository</res-type>
<res-auth>Container</res-auth>
</resource-ref>
</web-app>


Don’t forget to create the repository descriptor file, in the same path as specified in the context descriptor. If you don’t have your own descriptor, or if you don’t want to concern about it right now, simply copy and paste this one:


<?xml version="1.0"?>
<!DOCTYPE Repository PUBLIC "-//The Apache Software Foundation//DTD Jackrabbit 1.4//EN"
"http://jackrabbit.apache.org/dtd/repository-1.4.dtd">
<Repository>
<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
<param name="path" value="${rep.home}/repository" />
</FileSystem>
<Security appName="Jackrabbit">
<AccessManager class="org.apache.jackrabbit.core.security.SimpleAccessManager" />
<LoginModule class="org.apache.jackrabbit.core.security.SimpleLoginModule" />
</Security>
<Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="default" />
<Workspace name="${wsp.name}">
<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
<param name="path" value="${wsp.home}" />
</FileSystem>
<PersistenceManager
class="org.apache.jackrabbit.core.state.xml.XMLPersistenceManager" />
<SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
<param name="path" value="${wsp.home}/index" />
</SearchIndex>
</Workspace>
<Versioning rootPath="${rep.home}/versions">
<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
<param name="path" value="${rep.home}/versions" />
</FileSystem>
<PersistenceManager
class="org.apache.jackrabbit.core.state.xml.XMLPersistenceManager" />
</Versioning>
</Repository>


This simplified repository descriptor doesn’t depend on any kind of specific storage system. You can enhance it to store your data in a relational database, for example, but in our example it will store everything as XML files under the repository home directory.
Now let’s create a session factory class. This class will locate a repository instance and authenticate to it, to get a javax.jcr.Session instance. Create the directory ./webapp/src/main/java, and create the following class on it:


package com.ctp.jcr.sample.webapp;

import javax.jcr.Repository;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.jcr.SimpleCredentials;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public class SessionFactory {

public static Session getSession() throws RepositoryException, NamingException {
InitialContext ctx = new InitialContext();
Context env = (Context) ctx.lookup("java:comp/env");
Repository repo = (Repository) env.lookup("jcr/repository");
return repo.login(new SimpleCredentials("admin", "".toCharArray()));
}

}


With this setup, the JCR repository can be accessed through your web application. The following JSP shows how to use the service factory to list the repository contents:


<%@page import="javax.jcr.Node"%>
<%@page import="javax.jcr.Session"%>
<%@page import="com.ctp.jcr.sample.webapp.SessionFactory"%>
<%@page import="javax.jcr.NodeIterator"%>
<html>
<body>
<%!
private void printContents(Node n, JspWriter out, String padding) throws Exception {
out.println(padding + n.getPath() + "(" + n.getPrimaryNodeType().getName() + ")");
NodeIterator it = n.getNodes();
while (it.hasNext()) {
printContents(it.nextNode(), out, padding + " ");
}
}
%>
<%
Session jcrSession = SessionFactory.getSession();
Node root = jcrSession.getRootNode();
%>
<pre>
<%
printContents(root, out, "");
%>
</pre>
</body>
</html>


This is the result displayed by the page. Observe that even for an empty repository, the infrastructure nodes are displayed as well.

Optional step: exposing the repository through WebDAV



To access your repository through WebDAV, it’s necessary to declare a servlet, through which the repository will be exposed. Add the following servlet declarations to your web.xml file:


<servlet>
<description> This servlet provides other servlets and jsps a common way to
access the repository. The repository can be accessed via JNDI, RMI or
Webdav. </description>
<servlet-name>Repository</servlet-name>
<servlet-class>org.apache.jackrabbit.j2ee.RepositoryAccessServlet</servlet-class>
<init-param>
<description> Property file that hold the same initialization properties
than the init-params below. If a parameter is specified in both places
the one in the bootstrap-config wins. </description>
<param-name>bootstrap-config</param-name>
<param-value>WEB-INF/repository/bootstrap.properties</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>
<servlet>
<description> The webdav servlet that connects HTTP request to the
repository. </description>
<servlet-name>Webdav</servlet-name>
<servlet-class>org.apache.jackrabbit.j2ee.SimpleWebdavServlet</servlet-class>
<init-param>
<description> defines the prefix for spooling resources out of the
repository. </description>
<param-name>resource-path-prefix</param-name>
<param-value>/repository</param-value>
</init-param>
<init-param>
<description> Defines various dav-resource configuration parameters.
</description>
<param-name>resource-config</param-name>
<param-value>/WEB-INF/repository/config.xml</param-value>
</init-param>
<load-on-startup>4</load-on-startup>
</servlet>
<servlet>
<description> The webdav servlet that connects HTTP request to the
repository. </description>
<servlet-name>JCRWebdavServer</servlet-name>
<servlet-class>org.apache.jackrabbit.j2ee.JCRWebdavServerServlet</servlet-class>
<init-param>
<description> defines the prefix for spooling resources out of the
repository. </description>
<param-name>resource-path-prefix</param-name>
<param-value>/server</param-value>
</init-param>
<load-on-startup>5</load-on-startup>
</servlet>
<servlet>
<servlet-name>RMI</servlet-name>
<servlet-class>org.apache.jackrabbit.servlet.remote.RemoteBindingServlet</servlet-class>
</servlet>
<servlet>
<description>Downloads binary data from repository</description>
<display-name>Repository Download Servlet</display-name>
<servlet-name>RepositoryDownloadServlet</servlet-name>
<servlet-class>br.com.hapkidocontato.site.presentation.RepositoryDownloadServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Webdav</servlet-name>
<url-pattern>/repository/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JCRWebdavServer</servlet-name>
<url-pattern>/server/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RMI</servlet-name>
<url-pattern>/rmi</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RepositoryDownloadServlet</servlet-name>
<url-pattern>/content/*</url-pattern>
</servlet-mapping>


Other two configurations file are referenced by those servlets. Create the directory webapp/src/main/webapp/WEB-INF/repository/ and create the file bootstrap.properties with the following values:


repository.name=java:comp/env/jcr/repository
jndi.enabled=true
jndi.name=jcr/repository


In the same directory, create the file config.xml:


<?xml version="1.0" encoding="UTF-8"?>
<config>
<iomanager>
<class name="org.apache.jackrabbit.server.io.IOManagerImpl" />
<iohandler>
<class name="org.apache.jackrabbit.server.io.VersionHandler" />
</iohandler>
<iohandler>
<class name="org.apache.jackrabbit.server.io.VersionHistoryHandler" />
</iohandler>
<iohandler>
<class name="org.apache.jackrabbit.server.io.ZipHandler" />
</iohandler>
<iohandler>
<class name="org.apache.jackrabbit.server.io.XmlHandler" />
</iohandler>
<iohandler>
<class name="org.apache.jackrabbit.server.io.DirListingExportHandler" />
</iohandler>
<iohandler>
<class name="org.apache.jackrabbit.server.io.DefaultHandler" />
</iohandler>
</iomanager>
<propertymanager>
<class name="org.apache.jackrabbit.server.io.PropertyManagerImpl" />
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.VersionHandler" />
</propertyhandler>
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.VersionHistoryHandler" />
</propertyhandler>
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.ZipHandler" />
</propertyhandler>
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.XmlHandler" />
</propertyhandler>
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.DirListingExportHandler" />
</propertyhandler>
<propertyhandler>
<class name="org.apache.jackrabbit.server.io.DefaultHandler" />
</propertyhandler>
</propertymanager>
<noncollection>
<nodetypes>
<nodetype>nt:file</nodetype>
<nodetype>nt:resource</nodetype>
</nodetypes>
</noncollection>
<filter>
<class name="org.apache.jackrabbit.webdav.simple.DefaultItemFilter" />
<namespaces>
<prefix>rep</prefix>
<prefix>jcr</prefix>
</namespaces>
</filter>
</config>


And that’s all: the default workspace can be accessed through WebDAV in the following URL: http://localhost:8080/webapp/repository/default. On Windows, you can go to “My Network places” and “Add network place” to map the WebDAV location as a folder. When prompted by a username and password, just provide anything; the repository is configured to grant access to any user.
To find more about JCR, Jackrabbit and its related technologies, visit the dev.day.com weblog.

Thanks Douglas for this post! - [Tom & Balz]

Tuesday, June 10, 2008

Targeting JBoss Seam for Multiple Application Servers

Not all application servers are equal - something you realize quickly in a consultant's life working in different customer environments. The "developer friendliness" varies broadly here - I guess waiting for the container to deploy, go down and up again is a phenomenon many of the web developers out there know too well...

A stack that works for me very efficient is JBoss Seam on JBoss application server. Since its integration with JBoss Tools, the code-deploy cycle goes extremely smooth. But how can we leverage this while targeting other application servers?

After some experiments, I came up with a solution based on Maven. In general, the deployment of Seam distinguishes in library dependencies and some config files. For example is Hibernate the default persistence provider on JBoss, but not on WebLogic - but using Hibernate has the advantage of using Hibernate Validators, which integrates in Seam very comfortable with JSF validation. Maven allows to create different profiles, which contain different dependency sets tailored for another application server. The differences for running Seam in different containers are well described in the Seam documentation.

pom.xml:
<profiles>
<profile>
<id>weblogic10</id>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate</artifactId>
<version>${hibernate.version}</version>
<exclusions> ... </exclusions>

...

</profile>
</profiles>
Integrating this in JBoss Tools turnes out to be a little trickier. The best approach seemed to be to start with a Seam project wizard in the Maven source structure:
  • Java Source Directory: src/main/java
  • Content Directory: src/main/webapp
The project needs then to be 'mavenized' by adding the Eclipse Maven 2 plugin if not already installed and a POM to the project. Getting the dependencies correct can be a little tedious with all the exclusions - best is to add just one by one and compare with the Web App Libraries that come out of the wizard. Once this is done, the libraries in WEB-INF/lib can be deleted and the Maven dependencies added in the Project J2EE Dependencies dialog. As a nice side-effect, this Maven setup makes it extremely easy to upgrade your libraries. For example, upgrading RichFaces from 3.2.0 to 3.2.1 was just a 1-character change in the POM!

We have now a clean separation between dependencies, but still the config files need different treatments. I went for a solution on adding three subfolders to src/main/resources:
  • common for, well, common resource files like message bundles and Drools rule files
  • jboss and e.g. weblogic for the files requiring different versions for applications servers, namely the components.xml and persistence.xml files (using Hibernate on WebLogic 10 requires a different configuration - the transaction manager lookup and the query factory class need to be changed).
This works now fine in JBoss Tools and you can start coding. Still, to run the Maven build we need some additional fixes as we changed the Maven default structure on the source files (JBoss Tools uses src/main/java/action and src/main/java/model) and on the resources:

pom.xml:
<build>
<sourceDirectory>
${basedir}/src/main/java/model
</sourceDirectory>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${basedir}/src/main/java/action</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
This configures the two source folders in JBoss Tools - a little verbose, but Maven usually knows only one source folder. For the resource folders, we need to configure the build settings in the distinct Maven profiles:

pom.xml:
<build>
<resources>
<resource>
<directory>src/main/resources/common</directory>
</resource>
<resource>
<directory>src/main/resources/weblogic</directory>
</resource>
</resources>
</build>
We can now test for example the WebLogic profile in a continuous build, deploying the WAR file on an integration server.

The resulting project structure in Eclipse is shown in the screenshot below: