Starting the tutorial

We start this tutorial with 3 Eclipse projects : an EAR, an EJB and a WAR project. These projects are showed in the following picture

The 3 projects are linked with the Eclipse configuration files which contains informations about EAR, EJB and WAR projects. In this article the projects are based on JBoss Seam, but all the tutorial could be used in any project type.

On the disk, the 3 projects are 3 directories in the workspace folders. Useless to say it’s not the Maven way to organize projects.

Creation of the parent Project

First step, we create a Maven parent project which will contain our EAR, EJB and WAR projects (that Maven call modules). In this parent project we can define global parameters for the modules. To create this project click on “File/New/Porject…”

Choose Maven Project in the Maven category and click on Next, this opens the “New Maven Project” wizard :

You can go to the next step after checking that “Create a simple project” is unchecked.

In this dialog box you have to choose an archetype (a template for your project). In Catalog choose Nexus Indexer which brings a richer list than the internal default one. In the filter field enter “pom” to reach the “pom-root” archetype”. Select it and click on “Next”.

In this last dialog box you choose the project name. click on “Finish”. Now you have a new project in your workspace. In my case it’s “pfm77-parent”

Creating the Maven modules

In the same way we created parent project, we’re going to create the children projects or modules. click on “File/New/Project…”

Choose “Maven Module” then click on “Next”. A new wizard opens :

Enter the name for the EAR module and the name of the parent project then click on “Next.

Don’t forget to choose “Nexus Indexer” in the catalog, enter “ear” in the filter field. Choose the “ear-jee5″ archetype then click on “finish”

To create the EJB and WAR modules, we’ll use the same wizard choosing archetypes “ejb-jee5″ and “webapp-jee5″.

After all those wizards and clicks, we have 4 new projects in the workspace :

The physical structure of these Eclipse projects are different. If you look on your disk, you’ll see a Maven hierarchy (a main project and modules in in the folder of the main project). It’s one of the m2eclipse benefits : supporting sub-projects in Eclipse. But it’s not the only advantage of the plugin.

Benefits of m2eclipse

1) Managing sub-projects in Eclipse

As we saw, you can have a Maven hierarchy that m2eclipse make look likes different Eclipse project in the IDE. This also works when you import existing maven project in the worskpace from the disk or versioning system.

2) Managing Maven dependencies

The plugin use the pom.xml files to download and add jar files in your project.

3) Maven build in Eclipse

The least we can wait for this plugin. A m2eclipse project has 2 builders : the standard Eclipse one and the maven one.

4) A nice user interface to manage pom.xml files

You can use this interface to look for dependencies or exclude a sub-dependency easily. It was rather bugy in the past but with version 0.99 of m2eclipse it starts to be very usefull.

5) Automatic management of Eclipse projects configuration

That’s an important benefit that is not very well documented on m2eclipse site. M2eclipse uses pom.xml information to generate and maintain Eclipse configuration files for the project. For instance the projects we just created are not Eclipse project. They were created from Maven Archetypes that have nothing to do with Eclipse. So the eclipse configuration files of these new project (.classpath, .project files and .settings folder) were generated by m2eclipse from the pom files. When pom files are modified, m2eclipse will change Eclipse configuration files automatically. For instance, let’s have a look at the Facets of the EJB project (right-click on the project, and choose properties/facets) :

M2eclipse have added this EJB3 facets by analyzing the pom.xml file. So if you change Eclipse configuration on the project there can be some chance that you touch a configuration driven by m2eclipse. So take care of your modification. To be sure you won’t go battle wth m2eclipse in the configuration you should check the m2eclipse documentation. This page show all the Maven parameters (with green checkboxes) that are used by m2eclipse to build and maintain Eclipse WTP configuration files.

To finish with this point, you’ll have to be extremely carrefull when you put those project under versioning system. The best solution is to ignore Eclipse configuration files and let m2eclipse do the job on the other systems (you’ll have to create local configuration on each IDE to configure information that are not in Maven files like deploying servers for instance).

Copying Files

Let’s go back to our tutorial : moving WTP projects to maven/WTP projects. The next step consist to copy files from our old WTP project to the newly created Maven/WTP projects. You can do this by dragging files from file system (Explorer, Finder, or whatever you use) to Eclipse using the “resources” perspective which is the more close to filesystem perspective. To keep it simple try to stick with the default Maven layout, It will make pom files lighter.

• For the EAR module you’ll put the content of META-INF in src/main/application/META-INF all the other files in te project will be build from pom.xml
• For the EJB module, all your classes should be put in src/main/java, resources files like properties or META-INF folder should be in src/main/resources.
• For the WAR module you’ll use the same folders as EJB for classes and resources. The site files will be copied in src/main/webapp folder (be carefull and don’t take the WEB-INF/lib folder)

You should ignore Manifest files in all the project because they can cause runtime errors.

Now we have to deal with our pom files

Pom pom pom pom

It’s not a symphony but almost (sorry for that). The setting of our 4 pom.xml files will ask some patience (it’s the Maven feng-shui side) but we will get trough.

Parent project

I won’t detail all my pom.xml files content : I want to keep my readers till the end. Instead I’ll show you the result and comment the main part of each file

• Introduction : here I tell Maven that it is a pom project that drive construction of sub-projects (modules).
• modules : here are the modules contained by this parent project.
• properties : here I define variables that will be used in configuration of all the modules (libraries version for instance)
• repositories : in this section I add Maven repositories used by my project. For me it’s JBoss repositories for Seam and java.net to get all Jee5 dependencies
• dependencyManagement : In this part, I declare all the dependencies used by my modules. Declaring them here, I can set their version once for all.
• build : in this final section I can set up compilation configuration once for all.

<?xml version="1.0" encoding="UTF-8"?>
<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>cos</groupId>
  <artifactId>pfm77-parent</artifactId>
  <packaging>pom</packaging>
  <version>0.0.1-SNAPSHOT</version>
  <name>pfm77-parent Multi Project</name>
  <url>http://maven.apache.org</url>
  <modules>
    <module>pfm77-ear</module>
    <module>pfm77-ejb</module>
    <module>pfm77-war</module>
  </modules>

  <properties>
    <seam.version>2.0.3.CR1</seam.version>
    <jsf.version>1.2_10</jsf.version>
    <richfaces.version>3.2.1.GA</richfaces.version>
  </properties>

  <repositories>
    <repository>
      <id>jboss</id>
      <name>JBoss Repository</name>
      <url>http://repository.jboss.org/maven2</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>jboss-snapshots</id>
      <name>JBoss Snapshot Repository</name>
      <url>http://snapshots.jboss.org/maven2</url>
      <releases>
        <enabled>false</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
    <repository>
          <id>java.net1</id>
          <name>Java.Net Maven1 Repository, hosts the javaee-api dependency</name>
          <url>http://download.java.net/maven/1</url>
          <layout>legacy</layout>
      </repository>
  </repositories>

 <dependencyManagement>
 <dependencies>

  <dependency>
      <groupId>commons-beanutils</groupId>
      <artifactId>commons-beanutils</artifactId>
      <version>1.8.0</version>
      <scope>compile</scope>
       </dependency>
        <dependency>
      <groupId>org.ostermiller</groupId>
      <artifactId>utils</artifactId>
      <version>1.07.00</version>
      <scope>compile</scope>
    </dependency>
    </dependencies>
 </dependencyManagement>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source>
          <target>1.5</target>
        </configuration>
      </plugin>

    </plugins>
  </build>

</project>

EAR project

In the pom file, we can get rid of compilation plug-in because we configured it in the parent project. But we’ll have to add all the depending jars and their version. The m2eclipse auto-completion tools are very usefull for this. Right-click on the project and choose “Maven/add Maven dependency”. The following dialog box opens

With this box you can search in Maven repositories the right jar and version for your project and add it the pom.xml file. With time some sub-depencies can appear in the project. You can exclude them by using the “Dependency graph” in pom editor. This view show a graph like this one :

If yo want to exclude a jar you can do it via the context menu and choosing “Exclude Maven Artefact…” (wasn’t working in version 0.98 of m2eclipse). Now, back to our pom file of EAR module here are its content

• header : I specify that it’s an EAR module and I don’t forget to point to the Parent project
• In the dependencies I don’t forget EJB and War modules
• In the build section I add the Maven EAR plugin. In the configuration of the plugin I give the directory where to put the lib and ask Maven to generate my application.xml file
• In the modules section of the plugin, I add my EJB and WAR modules that I defined at the beginning of the file as dependencies

<?xml version="1.0" encoding="UTF-8"?>
<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <artifactId>pfm77-parent</artifactId>
    <groupId>cos</groupId>
    <version>0.0.1-SNAPSHOT</version>
  </parent>
  <groupId>cos</groupId>
  <artifactId>pfm77-ear</artifactId>
  <packaging>ear</packaging>
  <version>0.0.1-SNAPSHOT</version>
  <name>pfm77-ear JEE5 Assembly</name>
  <url>http://maven.apache.org</url>

  <dependencies>
    <dependency>
      <groupId>cos</groupId>
      <artifactId>pfm77-ejb</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      <type>ejb</type>
      <scope>compile</scope>

    </dependency>
    <dependency>
      <groupId>cos</groupId>
      <artifactId>pfm77-war</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      <type>war</type>
      <scope>compile</scope>

    </dependency>

    <dependency>
      <groupId>org.jboss.seam</groupId>
      <artifactId>jboss-seam</artifactId>
      <version>${seam.version}</version>
      <type>ejb</type>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <groupId>javax.el</groupId>
          <artifactId>el-api</artifactId>
        </exclusion>
        <exclusion>
          <artifactId>javassist</artifactId>
          <groupId>javassist</groupId>
        </exclusion>
        <exclusion>
          <artifactId>dom4j</artifactId>
          <groupId>dom4j</groupId>
        </exclusion>
      </exclusions>
    </dependency>

    <dependency>
      <groupId>org.ostermiller</groupId>
      <artifactId>utils</artifactId>
    </dependency>

    <dependency>
      <groupId>org.richfaces.framework</groupId>
      <artifactId>richfaces-api</artifactId>
      <version>${richfaces.version}</version>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <artifactId>commons-collections</artifactId>
          <groupId>commons-collections</groupId>
        </exclusion>
        <exclusion>
          <artifactId>commons-logging</artifactId>
          <groupId>commons-logging</groupId>
        </exclusion>
      </exclusions>
    </dependency>

  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <version>2.3.2</version>
        <configuration>
          <version>5</version>
          <defaultLibBundleDir>lib</defaultLibBundleDir>
          <generateApplicationXml>true</generateApplicationXml>

          <modules>
            <ejbModule>
              <groupId>cos</groupId>
              <artifactId>pfm77-ejb</artifactId>
            </ejbModule>
            <ejbModule>
              <groupId>org.jboss.seam</groupId>
              <artifactId>jboss-seam</artifactId>
            </ejbModule>
            <webModule>
              <groupId>cos</groupId>
              <artifactId>pfm77-war</artifactId>
              <contextRoot>PFM77</contextRoot>
            </webModule>
          </modules>

        </configuration>
      </plugin>
    </plugins>
    <finalName>pfm77-ear</finalName>
  </build>

</project>

EJB project

Next step the EJB pom file. Not a lot of things to say about it except concerning the Maven EJB plugin which is used to set the EJB version.

<?xml version="1.0" encoding="UTF-8"?>
<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <artifactId>pfm77-parent</artifactId>
    <groupId>cos</groupId>
    <version>0.0.1-SNAPSHOT</version>
  </parent>
  <groupId>cos</groupId>
  <artifactId>pfm77-ejb</artifactId>
  <packaging>ejb</packaging>
  <version>0.0.1-SNAPSHOT</version>
  <name>pfm77-ejb JEE5 EJB</name>
  <url>http://maven.apache.org</url>
  <dependencies>

    <dependency>
      <groupId>javaee</groupId>
      <artifactId>javaee-api</artifactId>
      <version>5</version>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.jboss.seam</groupId>
      <artifactId>jboss-seam</artifactId>
      <version>${seam.version}</version>
      <scope>provided</scope>

    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-annotations</artifactId>
      <version>3.2.0.ga</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-beanutils</groupId>
      <artifactId>commons-beanutils</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.ostermiller</groupId>
      <artifactId>utils</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
    	<groupId>mysql</groupId>
    	<artifactId>mysql-connector-java</artifactId>
    	<version>5.1.6</version>
    	<scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ejb-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <ejbVersion>3.0</ejbVersion>

        </configuration>
      </plugin>
    </plugins>
    <finalName>pfm77-ejb</finalName>
  </build>
</project>

WAR project

Last but not least the WAR pom file. Notice that we’re not using Maven war plugin in this pom file, the default values of War packaging are enough.

<?xml version="1.0" encoding="UTF-8"?>
<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <artifactId>pfm77-parent</artifactId>
    <groupId>cos</groupId>
    <version>0.0.1-SNAPSHOT</version>
  </parent>
  <groupId>cos</groupId>
  <artifactId>pfm77-war</artifactId>
  <packaging>war</packaging>
  <version>0.0.1-SNAPSHOT</version>
  <name>pfm77-war JEE5 Webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>

    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>servlet-api</artifactId>
      <version>2.5</version>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>javax.servlet.jsp</groupId>
      <artifactId>jsp-api</artifactId>
      <version>2.1</version>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.jboss.seam</groupId>
      <artifactId>jboss-seam-ui</artifactId>
      <version>${seam.version}</version>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <groupId>org.jboss.seam</groupId>
          <artifactId>jboss-seam</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

    <dependency>
      <groupId>org.jboss.seam</groupId>
      <artifactId>jboss-seam-debug</artifactId>
      <version>${seam.version}</version>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <groupId>org.jboss.seam</groupId>
          <artifactId>jboss-seam</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

    <dependency>
      <groupId>org.jboss.seam</groupId>
      <artifactId>jboss-seam-pdf</artifactId>
      <version>${seam.version}</version>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <groupId>org.jboss.seam</groupId>
          <artifactId>jboss-seam</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

    <dependency>
      <groupId>org.richfaces.ui</groupId>
      <artifactId>richfaces-ui</artifactId>
      <version>${richfaces.version}</version>
    </dependency>

    <dependency>
      <groupId>org.richfaces.framework</groupId>
      <artifactId>richfaces-impl</artifactId>
      <version>${richfaces.version}</version>
      <exclusions>
        <exclusion>
          <groupId>commons-logging</groupId>
          <artifactId>commons-logging</artifactId>
        </exclusion>
        <exclusion>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
        </exclusion>
        <exclusion>
          <groupId>javax.faces</groupId>
          <artifactId>jsf-api</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.richfaces.framework</groupId>
          <artifactId>richfaces-api</artifactId>
        </exclusion>
        <exclusion>
          <groupId>javax.servlet</groupId>
          <artifactId>servlet-api</artifactId>
        </exclusion>
        <exclusion>
          <groupId>javax.faces</groupId>
          <artifactId>jsf-impl</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

  </dependencies>
  <build>

    <finalName>pfm77-war</finalName>
  </build>
</project>

Generating Eclipse configuration

Now that we have our pom files, we’ll ask m2eclipse to refresh eclipse config files by accessing the “Maven/update configuration file” in the context menu of each project. Doing this refresh .classpath, .project files and .settings folder of our projects.

First Maven build and first fix

From the context menu of the parent project (not the EAR), choose “Run as…/Maven install” or “Maven package”. Maven is launched but the build fails. Don’t panic this issue is caused by a conflict in Maven resolution and Workspace resolution. Disable Worksapce resolution in the parent project by choosing “Maven/Disable Workspace Resolution” in contextual menu of the parent project. Launch the build again and “voila”. You get an ear file in the target directory of the EAR project. In command line you’ll have to launch “mvn install” from parent project folder to have the same result.

What about WTP ?

Before using WTP to deploy your project you’ll have to copy the application.xml file from the target folder (of the EAR project) to the “src/main/application/META-INF” folder and do it again each time EAR modules change (which is not so often). And now ? Beleive it or not but it’s over and it works. In the server view choose your server (if you don’t have one you can create a “local deployer”). In the contextual menu choose “Add remove…” and add your project.

Then click on “publih” and tadaaa, your project is deployed with WTP (if it’s not, you just have to restart all this tutorial over ). The only issue is a WEB-INF directory in the root of the EAR which contains a copy of the lib directory of the good WEB-INF directory of the war module. This problem should be harmless for a local deployment and is caused by this Eclipse bug.

Conclusion

So m2eclipse is not working out of the box with WTP project. However it’s a powerfull tool even without this need. About Seam and Maven, JBoss is working on making developer life more simple. JBoss tools 3.1 should include extensions to ease the work with m2eclipse and Seam and Seam 3.0 should be totally mavenized, so easier to be build with Maven.

We’ll keep an eye on it…

See this code for instance :
@Name("registerHdl") @Scope(ScopeType.CONVERSATION) public class RegisterHandler implements Serializable{ @Out private Registrant registrant=new Registrant(); @Create public void create() { } } ... @Entity public class Registrant { private Long id; private String firstName; private String lastName; private String email; private String origine; (getters and setters skiped) }

It defines a component in the conversation scope with a private field containing an entity which is outjected with “registrant” name.

Later we’ll want to use this variable in a view :

pages.xml : ... <page view-id="/register.xhtml"> <begin-conversation join="true" /> <navigation> <rule if-outcome="ok"> <end-conversation /> <redirect view-id="/thanks.xhtml"></redirect> </rule> </navigation> </page> ...

register.xhtml : ... <span class="inputLabel">Your name : </span><br/> <h:inputText id="Name" styleClass="inputShort" required="true" value="#{registrant.lastName}"/> ...

But it doesn’t work (an exception occurs when the form is submitted). We started a conversation in pages.xml and called the outjected “registrant” variable from registerHdl without any success.
So what went wrong ?
The problem is that the “registerHdl” component is never created and the call we made to “registrant” didn’t trigger this creation.
To trigger this creation we could have called a method of registerHdl. We could have mapped the fields with #{registerHdl.registrant} in the view after having defined getter and setter for registrant in the component. But ther’s a better way.
That’s here that @Factory start to be useful.
@Name("registerHdl") @Scope(ScopeType.CONVERSATION) public class RegisterHandler implements Serializable{ private Registrant registrant=new Registrant(); @Factory public Registrant getRegistrant() { return registrant; } public void setRegistrant(Registrant registrant) { this.registrant = registrant; } @Create public void create() { } }

We deleted the @Out annotation and added a getter with the @Factory annotation. This new configuration triggers the creation of registerHdl component when we call #{registrant…} in our view.

To summarize @Out outjects a field as a context variable after the creation of the component and @Factory triggers if necessary the creation of the component to outject the return value of a method. @Out is only visible in the component life cycle and @Factory is visible in the whole application.
But that’s not the only difference between @Factory and @Out as we’ll see in part 2 of this article.