Help

Those of you who keep up with Seam CVS will have noticed a lot of changes recently to the build system. I'm going to give a brief tour of them here, and discuss how they affect you when you use Seam.

Maven

We chose to use Maven to manage Seam dependencies as it offers reasonable support for transitive dependencies, it's emerging as the de-facto standard both in the Java Enterprise world and at JBoss.org, tools like Ant (using Maven Ant Tasks) and Ivy can consume Maven POMs and the 40 odd votes for publishing Seam to Maven pushed us somewhat ;)

Using Seam with Maven

For those Maven pro's among you, here's the essential information to get you started. If you are considering dabbling with Maven, then you might want to wait for a couple of weeks for Seam 2.0.0.GA which will include a brief tutorial on using Maven with Seam.

To checkout the support you'll need to add http://snapshots.jboss.org/maven2 as a snapshot repository to your POM; having done this, you can add Seam to your projects POM:

<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam</artifactId>
</dependency>
<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-ui</artifactId>
</dependency>
<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-pdf</artifactId>
</dependency>
<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-remoting</artifactId>
</dependency>
<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-ioc</artifactId>
</dependency>
<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-ioc</artifactId>
</dependency>

We'll shortly start publishing snapshots from our continuous integration server.

As Seam is an integration framework we spend a lot of time ensuring that the integrated libraries work well, both together and with Seam. If you want to always use the recommended library versions with Seam you may want to use the Seam root POM (which just declares repositories and dependencyManagement) as your parent POM:

<parent>
  <groupId>org.jboss.seam</groupId>
  <artifactId>root</artifactId>
  <version>2.0.0.SNAPSHOT</version>
</parent>

You can then just declare your dependencies versionless in your POM:

<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam</artifactId>
</dependency>

<dependency>
  <groupId>org.jboss.seam</groupId>
  <artifactId>jboss-seam-ui</artifactId>
</dependency>

<dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-jpdl</artifactId>
</dependency>

You'll then get the SNAPSHOT of Seam core and ui and jBPM jPDL 3.2.1.

Maven/Dependency Management Roadmap

So, what else is on the cards?

  • Write some documentation!
  • Release the next version of Seam to http://repository.jboss.org
  • Improve the handling of JBoss Embedded in the build scripts
  • Alter the seamdiscs example to use Maven for dependency management
  • Provide an option to use Maven-based dependency management in seam-gen

Feedback and Troubleshooting

Whilst this is a good start there a still some bumps to iron out! I'm really hoping for strong (and fast!) feedback on this one to get it just right for the GA.

I've got a couple of questions/discussion points for you maven experts out there:

  • Is there a way to read external properties into maven? As we're using Maven Ant Tasks we can't use -Dproperty=foo and we need to be able to specify the property file relative to the POM's location.
  • Is there a nice way to provide dependency profiles without putting empty jars all over the place?
  • Is using the Seam root POM as your parent POM an acceptable alternative?

If you are following Seam CVS and are having problems building Seam:

  1. Grab the latest CVS
  2. Make sure your build.properties file /doesn't/ contain any references to version or patchlevel
  3. Run ant clean build
  4. If the build fails due to
    The <urn:maven-artifact-ant:dependencies> type doesn't support the "versionsid" attribute.
    you probably have an older version of maven-ant-tasks.jar on your classpath. Try running ant -nouserlib or update Maven Ant Tasks to 2.0.7.
  5. Report your problem on the forum!

Maven in Seam

So, how did we use Seam and Maven Ant Tasks to build Seam?

Building Seam using Maven

However good Maven is at dependency management, we're not in love with using Maven for building software (it seems slow, and incredibly restrictive) so we decided on the half-way house of using Maven Ant Tasks - which are essentially a set of ant tasks that call into Maven. With this, we can use Ant to load dependencies from Maven POM files and publish artifacts to Maven.

In CVS the Seam build uses Maven POM files to declare dependencies. These pom files are stored in /build and, using some Ant substitution filters, are copied to /classes/poms. From these poms, we can build path's (to compile Seam), fileset's (using the Maven Ant Tasks) and can use the handy version mapper (which allows you to copy a dependency fileset stripping off the version information e.g. org/jboss/seam/jboss-el/2.0.0.BETA1/jboss-el-2.0.0.BETA1.jar is copied to /jboss-el.jar).

There is more information in /build/readme.txt

Examples and Seam-gen

For now we've stuck with using ant for building and declaring the dependencies in the build.xml. To do this we copy Seam and it's dependencies (resolved using Maven) to a staging area, and then building the deployable artifacts against this directory. This has the advantage of not having to write POM's for every example (non-trivial given the lack of dependency profiles in Maven).

24 comments:
 
26. Sep 2007, 05:36 CET | Link

Congratulations! I think it is a great idea to let Seam POM manage the exact dependency jar versions for Seam projects.

Even for people who cannot use the Seam root POM as their parent POM, they can still copy and paste individual dependencies. That is much better than trying to figure out jar versions in the Seam distro!

 
26. Sep 2007, 06:23 CET | Link

Would it make sense to follow Spring's convention by naming the primary jar file with a suffix just like the rest of the jar files?

<groupId>org.jboss.seam</groupId>
<artifactId>jboss-seam-core</artifactId>

Using the suffix on the artifactId takes out the ambiguity of what this jar file holds.

It also allows you to create a super jar without having to use the super lame -all suffix.

 
26. Sep 2007, 06:25 CET | Link

I doubt I would ever use the Seam POM as my parent POM. Parent POMs are a very important part of organizing a reactor (multi-module) build. Since you can only have one parent POM, it just doesn't make sense. However, I wouldn't rule out the possibility that people will use it for quick projects.

 
26. Sep 2007, 06:27 CET | Link

Dependency profiles may be available in Maven 2.1, but definitely not in Maven 2.0. Who knows what the status of that initiative is. It is hard to find since the word profile is overloaded in Maven 2.

 
26. Sep 2007, 06:34 CET | Link
Felix Hoßfeld

Dan Allen wrote:

 
26. Sep 2007, 09:56 CET | Link
Chris Jones

Don't go there. Maven is rubbish.

26. Sep 2007, 11:28 CET | Link

Ah, point taken. My parent POM could reference the Seam parent POM. I never thought of it that way. I think that is a good suggestion for others to consider.

26. Sep 2007, 11:29 CET | Link

As an ardent user of Maven 2, I will be the first to say that switching to it is a big time commitment and it can be a real bugger. However, I believe that the Maven 2 build system is powerful because it /is/ restrictive. The problem with Ant builds is that once they achieve a certain size, it becomes difficult to figure out who calls who...a rabbit hole, essentially. The Maven 2 POM, whilst incredibly verbose, is predictable.

To give point to my rambling, my hope is that whatever shortcomings prevent Maven 2 from becoming the build system in Seam can be communicated to the Maven 2 developers so that they can make Maven 2.1 more capable of handling real-world scenarios. Of course, this isn't going to happen before Seam 2.0.0.GA. However, I believe that if the goal of open source in general is to share feedback between projects, then we have an obligation to at least voice our opinion as where Maven 2 comes up short and encourage those developers to make it better.

26. Sep 2007, 18:47 CET | Link

Snapshots are now being published every 8 hours to http://snapshots.jboss.org/maven2

Don't go there. Maven is rubbish.

It's also becoming pretty popular!

 
26. Sep 2007, 19:58 CET | Link
Joshua

great move pete. I'm glad that seam is using maven now. keep up the good work

 
02. Oct 2007, 21:05 CET | Link

I've used maven2 for about a year. I haven't used the ant tasks. I wouldn't classify myself as a maven expert, but seeing that you have scant response to your questions, and because I really like maven, I'll pitch in. Take this for what its worth.

First, please don't require me to use a seam parent pom. This would make my project inflexible. For example, how would I be able to use my corporate parent pom in a seam project? Not possible.

I don't know much about this thing called 'dependency profiles'. I haven't run across them before I found softeu. I like this tool because it has seam-gen goals for maven. But softeu's 'dependency profiles' give me trouble: The facelets dependency profile includes myfaces into the built war which gave a warning when I loaded it into jboss 4.2.1. I don't know what the workaround is, so this may not be a real issue, but if this is an example of maven profile dependencies, I would prefer to have more control of dependencies in my own project pom.

I'm not certain about the need for such a thing as dependency profiles. This may be because I don't really know what they are.... I question these because I expect the transitive dependency mechanism to be enough to 'suck' in the dependencies of seam. What value does dependency profiles bring? Don't jboss-seam artifacts contain the pom that built them? If so, then my project has what it needs to build a seam project.

For your properties question, in maven, build time properties are specified in settings.xml or the pom.xml, not in files with the java properties format like in ant. I haven't used the ant tasks for maven, but looking at its documentation, it appears that all maven properties are made available for use in an ant build. Ant Tasks documentation shows how to access the maven properties that are defined in pom or settings.

The maven property ${basedir} is the directory containing the pom. So even if you choose to leave your properties in java format property files, you can use this property:

${basedir}/dir/build.properties

John

 
02. Oct 2007, 23:01 CET | Link

John, thanks for your comments :)

First, please don't require me to use a seam parent pom. This would make my project inflexible. For example, how would I be able to use my corporate parent pom in a seam project? Not possible.

I certainly wasn't envisioning this as a requirement but as more of a shortcut when protyping.

I'm not certain about the need for such a thing as dependency profiles. This may be because I don't really know what they are.... I question these because I expect the transitive dependency mechanism to be enough to 'suck' in the dependencies of seam. What value does dependency profiles bring? Don't jboss-seam artifacts contain the pom that built them? If so, then my project has what it needs to build a seam project.

They aren't necessary for many projects, but when you are dealing with a project like Seam which has many complex optional dependencies they become useful, or perhaps, necessary.

If you include jboss-seam in your list of dependencies you'll suck in the core dependencies of Seam. However you won't suck in Drools, Hibernate Search, Groovy... and I really doubt you want to!

With a dependency profile you could say something like seam-ejb3-jboss42, seam-security-drools (give the dependencies for running Seam with EJB3 on JBoss AS 4.2 with Seam security), which would give you drools-core, drools-compiler, hibernate-annotations, hibernate-entitymanager, hibernate, hibernate-validator, jboss-seam-security, commons-digest amongst other. Further, you having declared your dependency on jboss-seam-2.0.0.GA you really don't want, when you decide to add hibernate-entitymanager in, to have to specify the version (you want to keep the version in sync with that which Seam recommends) as then when you upgrade to jboss-seam-2.0.1.GA you'll have to alter all your dependencies.

I like this tool because it has seam-gen goals for maven. But softeu's 'dependency profiles' give me trouble:

This is another project, feel free to open an issue in Seam JIRA to request archetypes for Seam.

The facelets dependency profile includes myfaces into the built war which gave a warning when I loaded it into jboss 4.2.1. I don't know what the workaround is, so this may not be a real issue, but if this is an example of maven profile dependencies, I would prefer to have more control of dependencies in my own project pom

The Seam POMs aren't based on the softeu POMs - I'm really after proper dependency profiles as will be included in Maven 2.1.

I haven't used the ant tasks for maven, but looking at its documentation, it appears that all maven properties are made available for use in an ant build.

We want to go the other way - from properties files into Maven.

The maven property ${basedir} is the directory containing the pom. So even if you choose to leave your properties in java format property files, you can use this property: ${basedir}/dir/build.properties

Ah, this is more like it! So, how do I read this into Maven using a POM?

 
03. Oct 2007, 02:16 CET | Link
So, how do I read this into Maven using a POM?

Maven does not read properties format files into its properties like ant does. In maven, properties are defined by elements in settings.xml or pom.xml or command line.

As we're using Maven Ant Tasks we can't use \-Dproperty=foo and we need to be able to specify the property file relative to the POM's location

Maven has its own properties that can be merged into ant's when the artifact:pom task is run - So says the maven - ant task documentation.

If that works, then you can use the maven property basedir in subsequent ant statements to access the directory that the pom.xml is located. Use the normal ant task for loading properties from a file:

<property file="${basedir}/path/to/file">

Alternatively, if you set these properties in a maven pom.xml or settings.xml file, the artifact:pom task is would be enough to merge them into ant's properties.

Regards, John

 
03. Oct 2007, 02:16 CET | Link
Geoffrey De Smet

Great move of switching to maven 2.

It looks like you didn't lock down your plugin versions though? (I could be wrong.)

If you want to make a maven build portable and stable, you need to: - lock down your plugin versions - lock down your plugin versions - lock down all the plugin versions Yes, it's maintenance work, but it's the build guy who should test out the new compiler plugin version released today, not developer x, y and z who are doing other stuff.

The good news is, that maven 2.1 will enforce plugin version lock down and will probably make it a lot less configuration work - see their dev list.

Some examples of poms with locked down plugin versions: https://svn.labs.jboss.com/labs/jbossrules/trunk/pom.xml http://spring-rich-c.svn.sourceforge.net/viewvc/spring-rich-c/trunk/spring-richclient/pom.xml?revision=1794&view=markup

 
03. Oct 2007, 09:23 CET | Link

I have a correction. Please some ketchup for my crow?

Going over the maven documentation I found this: filter resource files

It explains how to read in a properties file, as you asked.

Sorry for prior misleading information.

Regards, John

 
04. Oct 2007, 04:27 CET | Link

Geoffrey - this is the first time I've seen plugin lockdown. Now, we don't use /any/ plugins inside the main Seam build as we use ant to actually build Seam (well, ok the ui build does use Maven to build so I can see the relevance there). So these plugin versions are transitive so that when someone uses a Seam artifact in their build they get pulled across?

Perhaps you could ping me by email to discuss this further?

 
04. Oct 2007, 04:56 CET | Link

John - thanks for the pointers. Unfortunately, as far as I can see, this is still discussing how to generate a properties file from Maven rather than how to read the properties into Maven.

I think we're best of sticking with filtering the POMs for now - at least it's reliable.

This to me is a lesson Maven needs to learn. When I alter the version of my project from 2.0.0 to 2.0.1 I don't want to have to update a file for every module but to just update it in one place. I can't see anyway to do that.

 
06. Oct 2007, 02:30 CET | Link
Matthew Lieder

Pete, I did some Google research and found a properties-maven-plugin that looks to do all that you're wanting:

Blog post
Plugin's site
 
07. Oct 2007, 18:28 CET | Link
Geoffrey De Smet

Pete, I 've send you an e-mail, with the basic tips for quality maven builds - thought they might not apply if you're using ant mainly:

1) Use dependencyManagement of the parent pom to declare versions of dependencies, don't use version in module poms. 2) Make sure all the optional dependencies are marked optional in the module poms. 3) Lock down the plugin versions in pluginManagement in the parent pom. 4) Less important: Lock down the maven build version in the parent pom (with prerequisites or the maven-enforcer-plugin) 5) Build test jars 6) Build the source jars

PS: plugin versions aren't transitive, they are only inherited from a parent pom.

 
15. Oct 2007, 00:46 CET | Link
Bruno

Hi,

Thanks for allowing the artifacts to be available through maven! I was lazy to test seam until today because of that...

However, I have just seen that the root POM is refering to versions of artifacts which do not exist in the jboss snapshots repository, such as:

 
15. Oct 2007, 00:49 CET | Link
Bruno

Mmm, my comment was truncated:

Hi,

Thanks for allowing the artifacts to be available through maven! I was lazy to test seam until today because of that...

However, I have just seen that the root POM is refering to versions of artifacts (2.0.0.CR2) which do not exist in the jboss snapshots repository, such as the jboss-seam-remoting, -pdf, -ui... etc

Is that version of the artifacts going to be deployed?

I guess in the meanwhile I can use the version 2.0.0-SNAPSHOT of the root POM. Thanks for the great work!

Bruno

 
17. Oct 2007, 01:27 CET | Link

Seam 2.0.0.CR2 is deployed in http://repository.jboss.org/maven2 not in http://snapshots.jboss.org/maven2 - we had a bit of a problem and some bad artifacts got deployed to snapshots which I've cleaned up now.

 
13. Nov 2007, 13:07 CET | Link

Just for documentation purposes, here is the plugin necessary to load properties from a build.properties file: http://jira.codehaus.org/browse/MOJO-535

Of course, it is still not accepted into Maven 2 because it is not pure enough.

 
10. Jan 2008, 18:32 CET | Link
Gordon DuQuesnay | gduquesnay(AT)gmail.com
wait for a couple of weeks for Seam 2.0.0.GA which will include a brief tutorial on using Maven with Seam.

Seam 2.0 GA has been out for awhile now. But I can't seem to find this tutorial.