JBoss Tools Litmus test(s) for project examples/archetypes

Version 4

    You have created you awesome project example or archetype which creates such example - now how do you know if it works well and especially works well with JBoss Tools ?

     

    Import + Run

     

    The basic litmus test for an example that is a web/ear applicaiton is the following steps:

     

    1) The project can be imported directly and without any errors and no serious warnings with either File > Import > Existing Projects into Workspace or File > Import > Existing Maven Projects *

     

    2) The project can be "Runned" on an Installed JBoss server in JBoss Tools by right clicking the project and choose Run As > Run On Server which should cause the server to get started, the project to be deployed and then be shown in a web browser (either internally inside Eclipse or externally dependent on your configuration)

     

    Note: For #1 if your project example/archetype is available from JBoss Central view then this is the basic operation JBoss Central does so using steps in #1 or from JBoss Central are equally good to test if the example works.

     

    If the project deploys and run after the two steps above there is a good chance you've at enabled users to easily try out the example, but there can be a few other good tests/validations to do to make sure the project is using things like Maven and JBoss Tools to the fullest and without encouraging bad practices.

     

    Here are a few of the ones we have noticed while trying out examples from various teams:

     

    Unnecessary/wrong Jar's being packaged / Missing proper dependency scope

    It's a common occurrence that when you use Maven you have a tendency to just add dependencies to the project until things start to work - unfortunately that can have the sideeffect of adding unnecessary jar's into the War or Ear which makes the deployment unnecessary heavy and might cause hard to understand/fix runtime issues.

     

    Adding the following to a pom.xml:

         

    <dependency>
             <groupId>javax.enterprise</groupId>
             <artifactId>cdi-api</artifactId>
     </dependency>
    

     

    will have such potential side effect.

     

    It will make the project compile if it uses CDI api's but it will also bundle the CDI jars into the project. For JBoss AS 7.x this probably will be fine at runtime since JBoss AS 7.x will choose its CDI classes over the bundled API's but it for sure makes your deployment too big and filled with jars that has no purpose.

     

    The proper solution is to remember to set the proper dependency scope, like this:

     

     

    <dependency>
             <groupId>javax.enterprise</groupId>
             <artifactId>cdi-api</artifactId>
             <scope>provided</scope>
     </dependency>
    

     

    Now the project will compile but will assume the jar's are provided in the runtime and thus not bundle the jars.

     

    Thus to fix this look at the actual generated war deployment from mvn command line AND JBoss Tools (since there might be subtle differences) and check if all the files (especially the jars) in the deployment actually deserves to be present.

     

    Note: this test is for some a great eyeopener how it affects users of runtimes if the runtimes pom.xml is way too greedy about adding dependencies that is not warranted.

     

    Not utilizing the IDE where it should or could

     

    The whole point of using pom.xml is so that tools (like Maven, Eclipse, IntelliJ, netbeans etc.) has a common set of metadata to read and from that do what it does best: provide tools for editing, navigating, building, deploying etc.

     

    Most runtime devs know what Maven does since they use it to build the runtime, but fewer actually realizes what an IDE does since many rutime devs does not actually try and use their runtime as a user, not realizing which features the IDE provides or could provide.

     

    An example is that JBoss Tools server adapter actually provides incrementally deployment of files, meaning there is no time spent on packaging/deployment - it just happens when you save the individual files.

     

    More to come...

     

    Having <repositories> in pom.xml

    <repositories> in examples pom.xml is a bad practice.

     

    It should be able to get everything it needs from Maven Central + EAP repositories.

     

    Compile fine on Community, but not against EAP

    This is tricky while both sides are moving, but its important we get identified where there are mismatches if any.

     

    i.e. if community is using JSF 2.0 but EAP is moving to JSF 2.1 how are these differences handled since here the version number is part of the artifact string.