You can include the spec in your own project by adding the following to your pom.xml :

<dependency>
	<groupId>org.jboss.spec</groupId>
	<artifactId>jboss-javaee-6.0</artifactId>
	<version>1.0.0.Final</version>
	<type>pom</type>
</dependency>

You may also need to add the JBoss repository to your pom.xml which is defined as :

<repositories>
	<repository>
		<id>repository.jboss.org</id>
		<name>JBoss Repository</name>
		<url>http://repository.jboss.org/nexus/content/groups/public-jboss/</url>
	</repository>
</repositories>

I’ll be adding this pom to the Knappsack archetypes to resolve some of the issues people have been facing with the broken spec dependency.

First off, most of these issues are Windows related and while I would love to move to Linux and be rid of these problems, its impractical at the moment. Also, if you are a non-Windows user you can still get an idea of what is needed to deploy GitHub projects with Maven.

To avoid a disappointing end to the post, the one problem I couldn’t resolve was releasing multi-module projects with maven. I am still getting the StringIndexOutOfBounds error with msysgit. These instructions are still good for single module deployments though. If anyone has a solution to the string index issue, feel free to post in the comments or drop me a line.

My go to page for remembering how to do release a project with Maven is the Sonatype instructions which covers setting up a Sonatype account and tells you what you need to put in your pom.xml file for it to be released automatically.

If you have done maven releases before with subversion, you will know how easy it is. Once the SCM information is in your pom file, Maven will download the source, tag it to the version you select, commit the tag, build it, and deploy it which is really quite nice as well as updating your development code to the new snapshot version.
If you haven’t done a Maven release before, you will need to set up a PGP key on your machine and post it on a key server (see the Sonatype instructions for more info and links that help).

So at this point, lets assume you have a project ready for release in GitHub (or any other Git repository I guess). You have a PGP key set up on your local machine and added to a public key server. Windows users should also have mSysGit set up, which you probably have if you are developing with Git. Your project should also have the release and deployment information set up as defined in the Sonatype document.

I’ve seen a number of different ways of putting the SCM information in the pom file. Here’s what I used that worked for me. Obviously you’ll need to change the account name.

<scm>
   <connection>scm:git:git://github.com/andygibson/${project.artifactId}.git</connection>
   <url>http://github.com/andygibson/${project.artifactId}</url>   <developerConnection>scm:git:git@github.com:andygibson/${project.artifactId}.git</developerConnection>
 </scm>

Interestingly enough, when I was looking to see what other people were using, there are plenty of projects that still have subversion repositories in their scm information. I guess they probably haven’t changed it over yet because they haven’t done a release.

Roadblocks

There are two main problems that you will hit when releasing with Maven under Windows. The first is that when Maven tries to push the changes back to the Git repository it hangs waiting for the pass phrase for your GitHub SSH key. However, since it never displays a prompt for it, you are stuck waiting for it.

The second problem is exposing your pgp keys to your Git Bash shell. The shell expects the keys to be in a particular folder which doesn’t exist by default (/c/.gnugp).

Setting up SSH-Agent

Start up the Git Bash session (or as OSX and Linux users call it, a shell) and go to your project directory.
Windows users, you need to start up an SSH agent to provide your passkey when needed by the release process.

To do this, in your Git Shell type :

eval `ssh-agent`  //pay attention to the back tick quotes here

which should return a piece of text like Agent pid xyz. This command starts the agent and sets up a couple of environment variables relating to the SSH agent. If you type env | grep SSH you will see the environment variables :

$ env | grep SSH
SSH_AGENT_PID=1234
SSH_AUTH_SOCK=/tmp/ssh-abcdef1234/agent.5678

Windows users will need to manually create the directory c:/tmp/ssh-abcdef1234/agent.5678 otherwise you get and error saying could not open a connection to your authentication agent.
Create the new directory and then add your key to the agent using the following syntax which assumes your Github RSA key is in the c:\.ssh\ directory. If it isn’t then just substitute the directory for your key.

$ssh-add "/c/.ssh/id_rsa"
enter passphrase :

Once you enter the pass phrase, it will be stored for that particular key for the rest of the session. When Git requires the phrase as part of the release it will automatically receive it from the agent.

Note that this set up is only good for the current session. If you open another session and want to do a release in that session, you will need to repeat these steps. I also think it would be a bad idea (or at least pointless) to set up the SSH_AGENT_PID or the SSH_AUTH_SOCK environment variables in any global variables.

So now we have that set up, you should be able to run the mvn release:prepare part of the release. This will grab the source code, update the pom version and push the changes back to the repository.

Exposing your PGP keys

For the next step, (mvn release:perform) we need to do the actual release which involves building the artifacts, signing them and uploading them. I’m assuming that you already have a project and environment that is correctly configured for release (including the release servers in settings.xml). If not, again, take a look at the Sonatype instructions for info on this.

The problem we’ll encounter here is that when signing the artifacts, the maven gpg signing plugin can’t find the keys from the Git Shell. It is looking in the /c/..gnupg directory while the windows version of gpg puts it in the users Application Data folder in their profile. There are two ways to solve this problem, and both involve locating the directory containing the Gnugpg keys. This folder is likely to be My Documents\Application Data\ which happens to be a hidden folder for many and varies in location depending on the version of windows. However, in that folder is the gnupg folder that contains your keys. The other piece of the puzzle is the GNUPGHOME environment variable in both Windows and Bash which points to the folder containing the keys.

You can either move the windows folder to where the Bash shell expects it, and set the Windows environment variable to point to it which means that if you fix it now, it will be fixed for every session. Windows GPG will find the folder through the GNUPGHOME environment variable and Bash will find it because that is the default place it looks for it.

Alternatively, you can leave the folder alone and set the environment variable in the Git shell to point to the key folder where it is. The only problem with this is that the environment variable will need to be set up each time. However, it leaves the rest of your environment alone.

I guess the third option is if you don’t have a GPG key already set up and are using the Git shell to generate one, you might have to manually create the /c/.gnupg folder manually.

I wanted to move the folder anyway so I went for option one. The choice is up to you, but if you get a message like :

gpg: no default secret key:secret key not available
pgp: signing failed: secret key not available

Its because Gnupg can’t locate the keys you (should have) already set up.

Once I got that these two problems fixed things went fairly smoothly, well, very smoothly in fact, it just worked. Now, hopefully you won’t have the same problems I had!

Also with this latest release, all the archetypes are available in the Central Maven Repository which means you can dive straight in and create a new Maven project using these archetypes :

1. In the command line, or in a script file, issue the following :

   mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-servlet-minimal-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.4 -DgroupId=org.application -DartifactId=servletminimal -Dpackage=org.application
   

   This will create the new project based on the java ee 6 minimal servlet archetype.

2. Go into the directory using cd servletminimal
3. In the project directory, issue the command mvn clean jetty:run
4. Navigate to http://localhost:8080/servletminimal/
5. Tinker away with it

]]> http://www.andygibson.net/blog/news/try-java-ee-6-without-the-commitment/feed/ 0 http://www.andygibson.net/blog/article/knappsack-archetypes-part-2/ http://www.andygibson.net/blog/article/knappsack-archetypes-part-2/#comments Thu, 12 Aug 2010 15:03:07 +0000 Andy Gibson http://www.andygibson.net/blog/?p=1097 In part 1, we looked at the basic structure and configuration of the project that is common in all the archetypes. This time we’ll look at the minimal archetype that contains some more functionality and a number of different classes used to implement that functionality.

The Java EE 6 Minimal Archetype

While there is still only one web page in the project, there are now a few more classes provided. These have been grouped into packages off the main package folder.

Package	Description
bean	The bean package contains the EntityManager producer and also a dao object for fetching and persisting Person objects as a stateless EJB (and a local interface).
model	Contains the JPA model for ther application which in this case is just one Person class
qualifier	Contains the qualifier used to specify injection points for the EntityManager
view	Contains the backing beans for the JSF view. These beans provide server side logic for the JSF pages, usually by invoking functions on the service beans in the bean package. The HelloBean accepts a user entered name and returns a message. The PersonBean has a person entity that can be modified by a JSF page and then persisted to the database. There is also a method to return the list of previously saved people from the database.

Layered code

We have a fairly clear separation of concerns with the different packages. The EJBs in the bean and qualifier packages don’t have any dependency on JSF while the beans in the view package are for JSF support only. Such organization means that you could put the contents of the bean and qualifier packages into a separate jar and re-use them with a different view framework. Technically, because they are also POJOs you could use them in a non-EJB environment.

Producing Entity Managers

The EntityManager is produced in the DataRepositoryProducer bean by returning the persistence context that was injected into the stateless bean by the container. When an entity manager needs to be injected into an injection point, this method is used to produce one. It is marked as @ConversationScoped so it can participate in CDI conversations. The @DataRepository annotation is a qualifier annotation used to mark what kind of entity manager you are producing and therefore can only be injected into injection points with the same annotation. This is useful if there are multiple databases used to distinguish between different entity managers produced.

Service Beans

In the PersonDao we inject the EntityManager that is then used in the other methods to save and fetch objects. In EJB 3.1 the default transaction attribute is Required for EJB methods so we don’t need to specify any transaction handling on the methods.

The PersonDao is injected into the view/PersonBean class so as the view needs to fetch or update data, the dao can be used to provide those functions.

If there was a mechanism that we could use to provide transactions on CDI (non-EJB) beans, then we wouldn’t really need EJBs, but as it is, we do. Nothing is stopping us from later changing the EJBs to CDI Managed beans with sufficient transaction support.

JPA Model

The only model class we use is the Person class that has properties for first name, last name and an integer Id value. On the name fields, we have specified a number of validators as well as the column size using annotations. These validators check that the field is not empty, or null and does not have a length greater than 25 characters.

Now we’ve covered the server side code, let’s take a look at the JSF page that uses these beans in home.xhtml.

JSF Content

The single page in this archetype is split into three different sections that test different parts of the environment.

The first part is producing the hello message from the helloBean class. The class is annotated with @Named("helloBean") which lets us reference this bean from the JSF page. The method getHelloMessage() returns a fixed string which is displayed in the page by using the EL expression #{helloBean.helloMessage}. This tells JSF to get the helloMessage property from the bean called helloBean. The bean name is resolved using an EL expression resolver that looks up the bean name in the beans registered with CDI using the @Named annotation.

If you are using JBoss Developer Tools and have enabled CDI for this application (right click on project, click Configure->Add CDI Support, you can go into the JSF page and ctrl+click on the expression (either the bean name or the property name) and the IDE will go to the point in the code that the expression is defined.

You can interact with the CDI hello bean by entering your name and clicking the submit button which posts your name back to the backing bean and when the page is re-rendered, your name appears in the message below the submit button. Again, the control is bound to the name property of the helloBean bean which is then used to return the correct message to the user when the page is re-rendered.

The final section uses JSF and CDI to edit an instance of a Person object on the CDI backing bean, with JPA persisting the object and Bean Validation providing validation for the JSF page. JPA also returns a list of the people previously saved. The PersonBean class has the @Named annotation which gives it the name personBean and it is marked with a @RequestScoped annotation. The bean has a person instance that is used as the model for the JSF page input boxes. The text boxes are defined for the first and last names and bound to the person entity on the personBean bean. Each input has a h:message JSF tag that reports errors for that input value. This will report errors on the person bean based on the validators we specified on the model. In the JSF page, the Add button calls the savePerson method on the personBean backing bean which uses the person dao implementation to persist the person entity in the backing bean. JSF automatically includes validation specified on the JPA model and will report errors back to the user for invalid input.

Underneath the person data entry, there is a list of names that have already been entered. Just enter a new name and click add to see the new name appear.This is fetched from the backing bean using the dao that is injected into it.

Using the app for yourself

If you want to create a new application from this archetype, you will probably want to delete the following items.

/bean/PersonDao.java
/bean/PersonDaoLocal.java
/model/Person.java
/view/HelloBean.java
/view/PersonBean.java

While you may want to re-use the template, or a modified version of it, you won’t need the content in the home.xhtml file. You can remove the content surrounded by the <ui:define name="content"> tags. Alternatively, you can just create a new project using the jee6-basic-archetype which has none of this additional code.

In the next section we’ll start looking at the JPA model and pre-defined data in the sandbox archetype.

]]> http://www.andygibson.net/blog/article/knappsack-archetypes-part-2/feed/ 2 http://www.andygibson.net/blog/news/knappsack-archetypes-are-now-in-the-maven-central-repository/ http://www.andygibson.net/blog/news/knappsack-archetypes-are-now-in-the-maven-central-repository/#comments Thu, 12 Aug 2010 14:48:20 +0000 Andy Gibson http://www.andygibson.net/blog/?p=1329 I have finally got around to putting the Mavan Java EE 6 Archetypes into the Maven Central Repository. This means you no longer have to manually download and install the Archetypes, they should be available for you to use out of the box. In some cases, depending on how you are creating your projects, you may need to refresh or update your Repository indexes in the IDE before they are visible.

In Eclipse (with m2Eclipse installed), you open the Maven Repositories view, locate the Central Repository in the global repositories, and right click and select update index to make the archetypes available.

To create a new project from the command line, you can copy the following command into a script or batch file and edit it to setup your own group and archetype values.

mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-sandbox-demo-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.4 -DgroupId=org.application -DartifactId=sandboxdemo -Dpackage=org.application

The new version includes the archetypes for creating Java EE 6 applications in servlet containers which lets you play around with CDI, JSF, JPA, validation and other JEE 6 technologies using an embedded servlet container from the command line.

]]> http://www.andygibson.net/blog/news/knappsack-archetypes-are-now-in-the-maven-central-repository/feed/ 2 http://www.andygibson.net/blog/tutorial/getting-started-with-maven-archetypes/ http://www.andygibson.net/blog/tutorial/getting-started-with-maven-archetypes/#comments Sun, 01 Aug 2010 16:50:12 +0000 Andy Gibson http://www.andygibson.net/blog/?p=1076

Prerequisites
• Install Maven

In this tutorial, we will create a new project using the Knappsack Archetypes and compile and deploy it. For this example, we will use the jee6-basic-archetype. Before you begin, you will need to have installed Maven, but you no longer need to manually install the Knappsack Archetypes as they are in the Central Maven Repository now, so you just need to make sure your index is up to date. These instructions will work for any Maven Archetype you have installed and creating new maven projects in general.

Maven archetypes can be thought of as templates that are installed into the Maven environment and can be used to generate new applications from scratch that are pre-configured for certain environments, whether it is Java EE 6, Wicket or Spring. We can create our project using either the command line or an IDE and both Eclipse and Netbeans both have support for Maven. Netbeans has it out of the box while Eclipse requires m2Eclipse to be installed. This tutorial covers all three methods of creating projects from Maven.

New project from the Command Line

1. Start by opening up a command prompt and navigating to the directory your project will reside in
2. The easy way to create a project on the command line is to just type

   mvn archetype:generate
   

   We will use the easier version where we don’t have to specify long command lines that include the group and archetype Ids and versions.

3. You will be greeted with a long list of possible archetypes with a number next to them and a prompt at the bottom to enter the number of the archetype you want to use.

   4: local -> jee6-minimal-archetype (Minimal Java EE application with a single page demo of CDI, JSF, JPA and Validation to ...
   5: local -> jee6-basic-archetype (Basic Java EE application with just configuration for CDI, JSF, JPA and a sample empty page.)
   6: local -> jee6-sandbox-archetype (Sandbox project for Java EE 6 with CDI, JSF, JPA and a sample model and test data to play ....
   7: local -> jee6-sandbox-demo-archetype (Complete demo example using CDI, JSF, JPA and validation showcasing a number of ...
   8: remote -> docbkx-quickstart-archetype (null)
   9: remote -> j2me-simple (Maven 2 Archetype for midlet application using j2me-maven-plugin)
   10: remote -> vaadin-archetype-clean (This archetype generates a simple Vaadin application as a Maven project...
   ...
   ...
   ...
   ...
   Choose a number: 65:
   

   Hint : Your locally installed ones should be near the start of the list. The default number (in this case 65) is the quickstart archetype to produce and empty maven project.

4. Enter the number of the Knappsack archetype you want to use and press enter.
5. You will then be asked to enter a number of different properties for the project :

   Define value for property 'groupId': : com.yourcompany
   Define value for property 'artifactId': : yourprojectname
   Define value for property 'version': 1.0-SNAPSHOT:
   Define value for property 'package': com.yourcompany:
   Confirm properties configuration:
   groupId: com.yourcompany
   artifactId: yourprojectname
   version: 1.0-SNAPSHOT
   package: com.yourcompany
   Y:
   

   Here we assumed the version is the default SNAPSHOT version and that the default package is the same as the groupId value.

6. Once complete, if you look in the directory you will see a new directory called yourprojectname. Move into this directory and if you have JBOSS_HOME set up you can deploy the project straight away.

   mvn clean package jboss:hard-deploy
   

   Start up JBoss if it isn’t already and go to http://localhost:8080/yourprojectname/home.jsf.

7. You can now import this project into an IDE such as Eclipse or Netbeans as these IDEs recognize Maven projects

Alternatively, you can use the command line to enter one long command, or as I do, put it in a script or batch file that I can edit in a text editor and run it from there. Here’s an example to get you started which you can copy and paste:

mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-sandbox-demo-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.4 -DgroupId=org.application -DartifactId=sandboxdemo -Dpackage=org.application

Creating a project in an IDE

Creating a Maven project in an IDE is much easier, although sometimes not by much. Typically, you choose to create a new project in the IDE and select maven as the type of project you want to create.

Netbeans

1. Select File->New Project and in the first list, select Maven and on the right hand side, select Maven Project (not Maven Web Application). Click Next.
2. Here we will pick our archetype to create our application from. In the list, expand the Archetypes from Local Repository item in the list. If you don’t see the archetypes there, you might need to refresh the index in the IDE. Close the new project window to do this.
   1. Select Window->Other->Maven Repository Browser to open the repository browser.
   2. In the repository browser window, right click on the repository and select Update Index.

   Now you should be able to start the new project from scratch and see the missing archetypes.

   

   Once you have selected the archetype, click finish to setup the project properties.

3. The project properties are the group and archetype Id for the new project as well as the optional default package name.
   

   You will also configure the project location here and click Finish when done.

4. Once complete, Netbeans will create your project and open it up. To run it, click Run->Run Main Project and it will prompt you for a Java EE 6 server to use. Select one and click ok. Remember that you need to change the datasource name in persistence.xml so it is not looking for the JBoss default datasource name.

Eclipse

First make sure you have m2Eclipse installed and are running Eclipse under a JDK instead of a JRE. For more details see this Installing and configuring Eclipse tutorial.

1. In Eclipse, click on File->New->Other.. to bring up the dialog for new projects and start typing “maven” in the search box
   

   Select the maven project item from the list and click Next.

2. This page lets you determine where the project will reside. Leave the defaults, but make sure the “Create simple project” option is unchecked and click Next.
3. Here we will pick our archetype which in this case is our Knappsack jee6 minimal archetype. Start typing “knappsack” in the list and you will see the list of available Knappsack archetypes. Again, it is possible that the IDE’s index of the local repository is not up to date and needs a refresh. You will need to cancel the project creation window to do this.
   1. Select Window->Show View->Other and in the view selection , start typing “Maven” until you see the window “Maven Repositories”. Select this to open up the view.
   2. In the Maven Repositories view, expand the Local Repositories item and right click click on the Local Repository (pathname) item and select Rebuild Index. Confirm that you want to rebuild the index and wait a few moments.
   3. Restart the project creation and this time you should see the archetypes you are looking for.
   

   Select the archetype you want to create and click Next.

4. Now we need to enter the project configuration information, what our project is called, give it a group id, version and default package.
   

   Once the above information is entered you can click Finish and Eclipse will work away at creating your project

5. To run the project, the easiest way is to install a server in Eclipse (see Tutorial on adding servers in Eclipse) and add the new project to the server. Start the server and navigate to your main page to see it in action.

Updated – 12th August 2010

The archetypes are now in the Central Maven Repository so there is no need to manually install them.

1. Download the Knappsack Maven Archetypes from here
2. Unzip the downloaded file into a temporary directory
3. Open a command prompt and navigate to the directory you unzipped the archetypes to.
4. In the directory, type the command :

   mvn clean install
   

   The archetypes will then be installed and ready for creating new projects.

To learn more about the archetypes read this guide. To see all Knappsack related content, click here.

Once you have installed the Knappsack Maven Archetypes you can delete the original source since they have been compiled and installed into your Maven repository.

1. Open a command prompt and navigate to the directory where the Maven source code is. This is usually indicated by the presence of a pom.xml file in that directory.

   
   > cd dev\projects\myproject
   

2. Once in the maven project folder, there are a number of different commands you can use to install the project depending on what you need. The simplest form will compile, test, and install the artifacts into Maven.

   
   >mvn install
   

In some cases, you want to install the source and java doc files as well as the main jar file. This can be done by adding it onto the command line.

>mvn javadoc:jar source:jar install

There may be times you want to make sure your build is completely clean before you start. You can do this by adding the clean target onto the command. This deletes any current compiled sources so they will be regenerated from scratch.

>mvn clean javadoc:jar source:jar install

While we added it at the start of the command, you don’t need to, you can put it at the end and it will still be executed first.

Skipping Tests

If you need to skip tests, you can do so by setting a command line parameter on the command line depending on how you want to skip the tests. While skipping tests is not advised, there are many cases where you might need to do so.

-Dmaven.test.skip=true

This will skip the compilation and execution of the tests.

-DskipTests=true

This will compile the tests, but skip the execution of them.

See here for more information on controlling test skipping in the pom.xml file.

1. First, download the DataValve framework and place it into a temporary folder of your choice.
2. Open a command prompt and change directory to the <install-dir>\modules\ folder
3. in the modules folder, type the command :

   mvn clean javadoc:jar source:jar install
   

4. This will compile the code, source and javadocs and install them into the local maven repository for use in your local maven applications.

Once installed, to use DataValve in a Maven project you will need to add the necessary DataValvel modules as dependencies :

		<dependency>
			<groupId>org.fluttercode.datavalve</groupId>
			<artifactId>datavalve-dataset</artifactId>
			<version>0.9.0.CR2</version>
		</dependency>

Typically, adding the datavalve-dataset artifact pulls in the core module also. From there, you just need to add modules that your development environment will be dependent on (Wicket, JSF, Swing etc).

JEE, JSF, JPA and CDI demo

The archetypes are based on the Weld Maven Archetypes and have been extended to contain a project that comes complete with a sandbox data model and pre-populated data, and also a full demo application that makes use of a number of Java EE 6 features. The projects have been tested and works with Glassfish (with a Weld update) and JBoss 6 Milestone 3.