Following the release of JBoss Tools 3.3M2 that was announced yesterday, this article highlights the main features provided by the new JAX-RS tooling which is part of this new milestone.

Installing the plugin

As explained in the announcement, the fastest and easiest way to get started with JBoss Tools is to download & install the Eclipse 3.7 (Indigo) JEE bundle. Once you have installed Eclipse, you use our update site directly.

The updatesite URL to use from Help > Install New Software... is:

http://download.jboss.org/jbosstools/updates/development/indigo/

Then, go to the "All JBoss Tools 3.3" section and select "JBoss JAX-RS Tools"

Using a sample project

A quick way to get started with the tooling is to download the JBoss AS7 Quickstarts from their download page. Once you've unzipped the archive, import the "KitchenSink" project into your workspace using the Import > Existing Maven Project menu.

You'll need to install the m2eclipse plugin to import the project.

Activating the support for JAX-RS

One way to activate support for JAX-RS in your project is to click on "Configure > Add JAX-RS 1.1 support..." in the project's contextual menu, which in turn will add the "JAX-RS Nature" to it.

If the project you're working on is a "Dynamic Web Project", you can also install the standard Eclipse "JAX-RS (REST Web Services)" Facet, which will in turn will add the "JAX-RS Nature" as described in the previous case.

In both cases, a "JAX-RS Builder" will be added to your project.

Current features

In this milestone, the JAX-RS Builder offers the features described below.

Mapping of JAX-RS elements to the source

The JAX-RS Builder computes and keeps in sync' an im-memory metamodel of the JAX-RS elements of your project. The metamodel is reinitialized during a clean/full build of your project, and all kinds of changes to compilation units are applied to the metamodel.     

RESTful Web Services explorer

The RESTful Web Services outline in the the Project Explorer view is certainly the most attractive feature of this plugin, as it displays the resolved URI Path Templates based on the metamodel described above.

The URI Path Templates resolution works with both Methods and Submethods of Root Resources and Subresources. In addition, each node in the outline indicates the consumed and produced media-types and the Java method that would be called when a request matching the combo {HTTP Method + URI Path Template + Content Negociation}. Double-clicking on the elements of the outline opens the Java Editor to the associated location in the source code.

Event tough the classes annotated with the @javax.ws.rs.ext.Provider are not shown on the Project Explorer's view yet, they are already taken into account by the JAX-RS Builder, so you can expect further features around those elements in the next releases.

Code completion for JAX-RS annotation values

Code completion for @javax.ws.rs.PathParam annotation value is available. The completion processor analyses the source of the Java Type to return proposals based on the @javax.ws.rs.PathParam annotations values both at the method and at the type levels. The additional information of each proposal highlights the part of the code from which the proposal was computed.

Those completion proposals support the regular expressions, too.

Validation of JAX-RS constructs

The plugin currently validates that a method parameter annotated with @javax.ws.rs.PathParam annotation matches with the @javax.ws.rs.Path annotation value on the same method.

That's it for now. Remember that the tooling is not yet complete but is very functional and we are looking forward to get feedback on its current functionality and what you would like to see in the future !

Have fun !

PS : as an individual contributor, I'd also like to thank the JBoss Tools team for the support and confidence they've put in the work I've done so far. As Max Andersen says, it's the way OSS works, and it's really great !

Embracing Indigo

So, Eclipse 3.7 a.k.a. Indigo has been released. This year, 62 Eclipse projects were  made available on the same day. Part of the release train is M2E 1.0.0, which succesfully graduated from the Eclipse incubator. Congrats to all the teams involved!

m2e-wtp 0.13.0 is finally available as well. Last minute bugs prevented an earlier release and made our lives a bit difficult, but thanks to Igor Fedorenko, we made it. As you will discover, the WTP integration with Maven is thighter than ever! The complete release notes are available here, but let's take a quick look at what's new and noteworthy :

Discovery / installation

Once m2e is installed, there are several ways to install m2e-wtp. First you need to wipe the m2eclipse-extras update site from your memory (and eclipse), it only contains m2e 0.12.0 compatible plugins :

IMPORTANT UPDATE : m2e-wtp has been temporarily removed from the m2e marketplace (http://dev.eclipse.org/mhonarc/lists/m2e-users/msg00938.html). Please consider option #3 while we're working on fixing the problem.

IMPORTANT UPDATE (02/08/2011) :the m2e marketplace issue is fixed with m2e-wtp 0.13.1 : http://community.jboss.org/en/tools/blog/2011/08/01/m2eclipse-wtp-0131-back-to-the-m2e-marketplace

1) Import existing Java EE projects into the workspace; You'll be proposed to install the m2e-wtp plugin :

click on Finish and the installation will proceed. Your projects will be imported but the workspace will have to be restarted.

2) Go to Window > Preferences > Maven > Discovery and click on "Open catalog". Select m2e and proceed with the installation.

3) Old school installation : Use this update site : https://repository.sonatype.org/content/sites/forge-sites/m2eclipse-wtp/0.13.0/S/0.13.0.20110623-0455/ 

IMPORTANT UPDATE 2 : m2e-wtp 0.13.1 is available from a new update site url (http://download.jboss.org/jbosstools/updates/m2eclipse-wtp/).

Experimental war overlay support

Finally, after all these years, m2e-wtp offers support for maven war overlays. The idea is to share common resources between several web applications. One use case could be to easily share logos, style sheets etc... in a corporate environment. All you need to do is declare in your web application pom.xml a dependency to another war artifact.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>foo.bar</groupId>
    <artifactId>war</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>
    <dependencies>
        <dependency>
            <groupId>foo.bar</groupId>
            <artifactId>overlaid</artifactId>
            <version>0.0.1-SNAPSHOT</version>
            <type>war</type>
        </dependency>
    </dependencies>
</project>

By default, all the contents of the overlaid artifact will be copied to the deployment directory of the web application, minus the MANIFEST.MF. The resources of the web application take precedence, in case of duplicate files.

If your project depends on a war archive (from your local repository), that dependency will be unzipped under target/m2e-wtp/overlays/<dependency>/ before being deployed to your server, according to the overlay configuration (you can select what files are included/excluded). For instance :

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.1.1</version>
        <configuration>
            <overlays>
               <overlay>
                  <groupId>foo.bar</groupId>
                  <artifactId>overlaid</artifactId>
                   <excludes>
                       <exclude>WEB-INF/lib/*</exclude>
                    </excludes>
                 </overlay>
            </overlays>
    </configuration>
</plugin>

... won't deploy the jars from overlaid (project or archive)/WEB-INF/lib

If the dependency is another web project in your workspace, the deployed resources will be dynamically determined from the overlay configuration and any file changed in the overlaid project will be automatically redeployed to the target server.

Below is an example where the "war" project depends on an "overlaid" war project and hudson-war-2.0.1.war(before you asked, it's because this one is available in central). The images/hudson.png file is present in both overlay artifacts. The file is picked from "overlaid", since it's declared first in the pom. The deployed "war" project is a fully fledged CI server

As of now, unsupported features of war overlays are :

- filtering

- exclusions of resources from the main project (defined as <overlay></overlay>)

There's plenty of room for performance optimizations, and it still needs to be tested "on the field" so please, please, do not consider this feature as production ready, it's still experimental.

Also note that the WTP overlay metadata format (in .settings/org.eclipse.wst.common.component) has changed and is incompatible with older development builds of m2e-wtp 0.13.0. So if you used previous nightly builds, you should reimport your projects without their eclipse metadata (.project, .classpath, .settings/)

Removal of WTP classpath libraries

Since its infancy, m2e-wtp suffered from outstanding classpath resolution issues when unit tests were being run. It turned out some dependencies were being leaked by the WebApp and EAR classpath libraries, installed by default on Java EE projects. Having these libraries also required extra code complexity to move workspace dependencies from one library to the other. In m2e-wtp 0.13.0, a rather radical solution was taken : remove these WTP libraries after they're being automatically added by WTP. Guess what? it solved all the classpath issues occurring during tests and simplified the code. So from now on, you will just see the following libraries in the project explorer

:

'Deployed Resources' node in the Project View

Previous m2-wtp versions displayed a Web Resources node, for Web projects, or Application Resources for EARs, in the Project View. These nodes aggregate the content that must be deployed on the server / packaged in the final archive. A Web Resources node is already provided by JBoss Tools for projects having the JSF Facet installed. So, in order to avoid confusion, the nodes contributed by m2e-wtp have been renamed more appropriately to Deployed Resources :

Maven-generated MANIFEST.MF

Up until now, in m2e-wtp, the manifest was generated "manually" using WTP's API, for web projects only. In the process, the man

ifest kinda fixed some maven shortcomings in order to handle skinny wars (didn't add a classpath prefix for EJBs, contrary to maven). Now, for Web, EAR, EJB, Utility and Connector projects, the manifest is generated via a call to the Maven's archiver.

That means no more impedance mismatch between Maven and Eclipse manifests. Manifest customization is reflected on the fly in the generated file.

For jar, ejb and connector projects, it is generated under target/classes. For web projects, it goes under

target/m2e-wtp/web-resources/ and for EARs, goes under target/m2e-wtp/ear-resources/

Since the EAR library is gone, the manifest is no longer used to reflect compile classpath within Eclipse and is only used for runtime classpath resolution.

Since it now follows the same rules as Maven, how do you handle skinny wars with EJBs and classpath prefix? One solution is to use your own Class-Path entry, which will be appended with the classpath computed by the maven archiver. So, for instance :

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.1.1</version>
      <configuration>
        <warSourceExcludes>WEB-INF/lib/*.jar</warSourceExcludes>
        <archive>
            <manifest>
                <addClasspath>true</addClasspath>
                <classpathPrefix>lib/</classpathPrefix>
            </manifest>
            <manifestEntries>
                <Class-Path>sample-ejb-${pom.version}.jar</Class-Path>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>

will generate something like :

Manifest-Version: 1.0
Built-By: fbricon
Build-Jdk: 1.6.0_24
Class-Path: sample-ejb-0.0.1-SNAPSHOT.jar lib/sample-util-0.0.1-SNAPSH
OT.jar
Created-By: Maven Integration for Eclipse

Of course, the "Created-By: Maven Integration for Eclipse" entry can be overwritten using your own value :

<manifestEntries>
  <Created-By>My kick-ass IDE</Created-By>
 </manifestEntries>

Finally, we tried to delete all MANIFESTS.MFs automatically generated by WTP. So hopefully, your source control shouldn't be polluted anymore.

Support for EAR Resource filtering

m2e-wtp now supports EAR resource filtering, pretty much the same way Web projects do. Just add the filtering attribute to your maven-ear-plugin configuration :

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ear-plugin</artifactId>
    <version>2.6</version>
    <configuration>
        <filtering>true</filtering>
        ...
    </configuration>
  </plugin>
</plugins>

Filtered resources are generated under target/m2e-wtp/ear-resources/

Dropped support for Eclipse 3.5 and older versions

In order to support war overlays, m2e-wtp 0.13.0 is taking advantage of several APIs that were made available in Eclipse 3.6 ( Helios). The direct consequence is it's not longer compatible with Eclipse 3.5 (Galileo) based platforms and of course older versions. However it's been tested against Eclipse 3.6 and 3.7 on the continuous integration server at JBoss.

Now, what next?

Well, we're gonna see how the overlay support stands in the wild. If necessary, one or more 0.13.x bugfixes can be made available "quickly". One of the problem that delayed this release is a conflict between m2e-wtp and the pom properties configurator. This lead us to remove the latter from m2e marketplace catalog to avoid confusion. I hope we can find a solution quickly in order to restore that plugin in the marketplace.

Next version (0.14.) should include Dali support, Application Client packaging support, bug fixes and more...

As always, if you find any issue or would like to see new useful features in m2e-wtp, please open a ticket at https://issues.sonatype.org/browse/MECLIPSEWTP

Enjoy,

Fred.

https://twitter.com/#!/fbricon

PS: Again, special kudos to Igor Fedorenko who supported me during this not-so-trivial release.