Use Jenkins and Apace Ant to compile, assemble, test, and deploy a RESTful web service to GlassFish. All source code for this post is available on GitHub. Note GitHub repo reflects updates to project on 10/31/2013.
Jenkins, formally Hudson, is the industry-standard, java-based open-source continuous integration server. According to their website, Jenkins provides over 400 plug-ins to support building and testing almost any type of project. According to Apache, Ant is a Java library and command-line tool whose mission is to drive processes described in build files as targets. This post demonstrates the use of Jenkins and Apache Ant to compile, assemble, unit test, and deploy a Java EE 6 RESTful web service to Oracle’s GlassFish open-source application server.
For the sake of brevity, I have chosen to use the HelloWorld RESTful web service example included with NetBeans. I will use NetBeans to create the project, write the unit tests, and produce an Ant target in the build file. I will not delve deeply into the inner workings of the web service itself since the focus of this post is automation.
System Configuration
This post assumes that you have current versions of NetBeans, JUnit, Jenkins, GlassFish, Ant and Java installed and configured on your Microsoft Windows-based computer. A full installation of NetBeans comes with JUnit, Ant, and GlassFish. At the time of the original post, I was using NetBeans 7.1.2, GlassFish 3.1.2, Jenkins 1.4.6.3, Ant 1.8.3, and JDK 1.7.0_02.
For simplicity, I am using a single development machine for this demonstration, on which all applications are installed. In a true production environment you would most likely have a distributed configuration with GlassFish installed on an application server, Jenkins on a build server, and NetBeans on your development machine. Also, for this post, I am also not using a source-code management (SCM) system, also called a version control system (VCS), such as Subversion or Mercurial, to house the project’s source code. Again, in a production environment, your source-code would be placed on SCM/VCS server.
Both GlassFish and Jenkins are configured by default to run on server port 8080. Since I have both applications installed on the same machine, I have changed Jenkins’ default port to another unused port, 9090. Changing Jenkins’ port is easy to do. If you don’t know how, consult this post or similar.
NetBeans
First, create a new project in NetBeans, by selecting the New Project -> Samples -> Java Web Services, REST: Hello World (Java EE 6), as shown below. Rename the project to HelloGlassFish. When complete, the project, in the Projects tab, should look like the screen-grab, below.
JUnit
Next create a unit-test using JUnit, the open-source unit-testing framework. Jenkins will eventually run this test each time the project is built. Creating unit-tests is easy in NetBeans. Select the ‘NameStorageBean.java’ class object, right-click, and select Tools -> Create JUnit Tests… This will create a default ‘NameStorageBeanTest.java’ class object in a new, ‘Test Packages’ directory. Overwrite NameStorageBeanTest.java contents with the follows code. This will create a single unit test we can use to demonstrate JUnit’s integration with Jenkins. You will also notice new test objects in the Project tab.
package helloworld; | |
import javax.ejb.embeddable.EJBContainer; | |
import javax.naming.NamingException; | |
import org.junit.*; | |
import static org.junit.Assert.assertEquals; | |
/** | |
* | |
* @author Gary A. Stafford | |
*/ | |
public class NameStorageBeanTest { | |
private NameStorageBean instance = null; | |
private EJBContainer container = null; | |
public NameStorageBeanTest() { | |
} | |
@BeforeClass | |
public static void setUpClass() throws Exception { | |
} | |
@AfterClass | |
public static void tearDownClass() throws Exception { | |
} | |
@Before | |
public void setUp() throws NamingException { | |
container = javax.ejb.embeddable.EJBContainer.createEJBContainer(); | |
instance = (NameStorageBean) container.getContext(). | |
lookup("java:global/classes/NameStorageBean"); | |
} | |
@After | |
public void tearDown() { | |
} | |
/** | |
* Test of getName method, of class NameStorageBean. | |
*/ | |
@Test | |
public void testGetName() throws Exception { | |
System.out.println("getName"); | |
String expResult = "Test"; | |
instance.setName(expResult); | |
String result = instance.getName(); | |
assertEquals(expResult, result); | |
container.close(); | |
} | |
} |
Build the project and run the ‘testGetName’ unit-test to make sure it works correctly and the test passes.
Apache Ant
Next, change to the Files tab. Open the ‘build.xml’ file, as shown below. Also, for later reference, note the contents of the ‘HelloGlassFish.war’ and the location of the ‘pwdfile_domain1’ password file.
Place the following Ant target, entitled ‘jenkins-glassfish-deploy’, into the build.xml file, between the end of the commented section and the closing <project/> tag, as shown below.
<!-- Older style. Not what is in repo on GitHub. --> | |
<target name="jenkins-glassfish-deploy" | |
description="Clean, build, test and deploy application to GlassFish"> | |
<antcall target="clean"> | |
<antcall target="default"> | |
<antcall target="test"> | |
<exec failonerror="true" executable="cmd" description="Deploy to GlassFish"> | |
<arg value="/c" /> | |
<arg value="asadmin --echo=true --host=localhost --port=4848 --user=admin | |
--passwordfile=pwdfile_domain1 --secure=false | |
deploy --force=true --name=HelloGlassFish --contextroot=/HelloGlassFish dist\HelloGlassFish.war" /> | |
</exec> | |
</target> |
This is the Ant target Jenkins will use to build, test, and deploy the project. The primary ‘jenkins-glassfish-deploy’ target calls three Ant targets using the
antcall
element. They include clean
, default
, and test
. Each of these Ant targets has dependencies on other Ant targets, which in turn depend on yet other targets – a dependency tree. For example, default
depends on dist
and javadoc
. The test
target depends on other targets to build the .war file. If you are not using test
to execute unit tests, you can call the test
target to build the .war file.
The last part of the ‘jenkins-glassfish-deploy’ target is a little different. It’s an exec
(execute) element, which calls asadmin
to deploy the project to GlassFish with a series of GlassFish domain-specific parameters. These parameters include the GlassFish domain’s URL and port, the domain’s administrative user and password account info (found in a password file), the location of the .war file to deploy, and destination of the .war within GlassFish. Calling asadmin deploy
gives you fine control over the details of how the project is deployed to GlassFish.
The password file, referenced in the target is a simple text file, which stores the password for the user account used to execute the asadmin deploy
call. The contents of the file look like:
AS_ADMIN_PASSWORD=Your_Password_Here
This target could be simplified with the depends
attribute. Instead of the three antcall
elements, you could simply add depends="clean, default, test"
to the target
element:
<!-- Older style. Not what is in repo on GitHub. --> | |
<target name="jenkins-glassfish-deploy-updated" depends="clean, default, test" | |
description="Clean, build, test and deploy application to GlassFish"> | |
<exec failonerror="true" executable="cmd" description="Deploy to GlassFish"> | |
<arg value="/c" /> | |
<arg value="asadmin --echo=true --host=localhost --port=4848 --user=admin | |
--passwordfile=pwdfile_domain1 --secure=false | |
deploy --force=true --name=HelloGlassFish --contextroot=/HelloGlassFish dist\HelloGlassFish.war" /> | |
</exec> | |
</target> |
According to Oracle, the asadmin utility is used to perform any administrative tasks for GlassFish from the command line. You can use this
asadmin
utility in place of using the GlassFish Administrator interface. I am able to call asadmin
directly because I have added the path to asadmin.bat to the Windows’ environmental variable, PATH
. The asadmin.bat file is in the GlassFish bin directory, similar to ‘C:\Program Files\glassfish-3.1.2\glassfish\bin\’.
Jenkins
Switching to Jenkins, create a new Job named HelloGlassFish. In the HelloGlassFish configuration, we need to add two Build steps and one post-build Action. For the first Build step, since we are not using SCM, we will copy the files from the project in the NetBeans workspace to the Jenkins workspace. To do this, add an ‘Execute Windows batch command’ action with code similar to code snippet below, but substituting your own project’s file path. Note, you can substitute the %WORKSPACE%
environmental variable for the xcopy
destination (see call-out 1 in the below screen-grab). This variable represents the absolute path of the directory assigned to the build as a workspace, according to Jenkins. Jenkins offers many useful variables, accessible to Windows batch scripts.
xcopy "C:\Users\gstaffor\Documents\NetBeansProjects\HelloGlassFish\HelloGlassFish" "%WORKSPACE%" /s /e /h /y
Next, add the second Build task, ‘Invoke Ant’. I assume you already have Ant configured for Jenkins. In the ‘Target’s text box, enter the Ant target we created in NetBeans build.xml file, entitled ‘jenkins-glassfish-deploy’ (see call-out 2 in the below screen-grab). If the name of your build file is anything other than the default ‘build.xml’, you will need to enter the Ant file name.
Lastly, add the single Post-build Action, ‘Publish JUnit test result report’. This will show us a visual representation of the results of our project’s unit-tests. Input the relative path to your reports from the workspace root. The path should be similar to call-out 3 in the screen-grab, below.
When complete, the HelloGlassFish Job’s configuration should resemble the screen-grab, below.
Save and close the configuration. Build the HelloGlassFish Job in Jenkins and make sure it succeeds with error.
GlassFish
Open GlassFish’s browser-based Domain Admin Console, usually on server port 4848, by default. On the left-hand side of the main window, under ‘Common Tasks’, tip the ‘Applications’ node. You should see the HelloGlassFish application is now deployed to GlassFish. You don’t have to do anything in GlassFish, Jenkins and Ant has taken care of everything.
To view the HelloGlassFish application, open a new browser window and direct it to ‘http://localhost:8080/HelloGlassFish/resources/helloWorld’. You should see a ‘Hello World!’ message displayed in your browser’s window. Note, since we only changed the name of the default HelloWorld NetBeans sample project to HelloGlassFish, not the web service’s URI, ‘helloWorld’ is still a required part of the URL path.
Redeploying the Project
Lastly, let’s demonstrate how easily changes to our project can be re-complied, re-tested, and re-deployed to GlassFish by Jenkins and Ant. Return to the HelloGlassFish project in NetBeans and open the NameStorageBean.java class. Change the value of the ‘name’ field from ‘World’ to ‘GlassFish’ and save the changes. Don’t build or do anything else in NetBeans. Instead, return to Jenkins and build the HelloGlassFish Job, again.
When the Job has finished building, re-direct your browser back to ‘http://localhost:8080/HelloGlassFish/resources/helloWorld’. You should now see a ‘Hello GlassFish!’ message displayed in your browser’s window instead of the earlier message, ‘Hello World!’. Jenkins has called the Ant target, which in turn re-compiled, re-tested, and re-deployed the modified HelloGlassFish application to GlassFish.
Helpful Links
- Apache Ant: ant.apache.org
- Apache Ant Tutorial: www.vogella.com/articles/ApacheAnt/article.html
- GlassFish: glassfish.java.net
- GlassFish asadmin deploy sub-command: docs.oracle.com/cd/E26576_01/doc.312/e24938/deploy.htm#deploy-1
- Jenkins: jenkins-ci.org
- NetBeans: netbeans.org
- Windows command line xcopy command: commandwindows.com/xcopy.htm
- Modifying PATH Environment Variable: www.java.com/en/download/help/path.xml
#1 by Gary A. Stafford on October 31, 2013 - 9:33 pm
The files on GitHub have been updated to use properties files for the Ant targets. The Ant targets are improved, using properties. The targets also now work on both Windows and Linux.
#2 by gebuh on March 11, 2014 - 3:06 pm
Hi, this works, but I’ve found that after a few deplos I get OOME’s from classLoader leaks – is there any way around this?
#3 by mauroprogram on October 10, 2014 - 12:11 pm
Reblogged this on mauroprogram's Blog and commented:
tutorial for use Jenkins witha web project on netbeans and Glassfish. Compiled with ant