Maven is a project management framework hosted by the Apache Software Foundation (ASF) at http://maven.apache.org. The Maven project started as the result of build process needs inside ASF projects. Before Maven each Apache project had its own methods of compilation, distribution, web site generation, and etc. As a developer, one had to deal with each project’s build separately. In addition, people weren’t contributing enough to Apache projects since it was a hassle to get each one running on their locals.  So, there was a need for a uniform build system, and with the Apache Turbine project Maven took the scene.

Maven tries to make builds as easy as possible in a uniform way — if you know how to build one Maven project, you can build all of them. As Maven becomes more widely used, we believe that this will be the first thing that comes to mind any time someone mentions Maven.

Before You Start

You need to install Maven on your computer. You can either use the Maven that ships with IDEs / plugins, or you can download it from http://maven.apache.org/download.html.  Follow the installation instructions that are available for MacOs, Windows and Linux.

Meat & Potatoes

Probably the most important key concept of Maven is that it favors convention over configuration. With six lines of XML you can create a Maven project and build a jar file out of it. Maven offers common interfaces for building projects. You don’t need to deal with all the necessary libraries, the tasks to run to build the project, and etc.  There’s a good saying for this: before Maven, it was the era of build engineers.  Maven stops you from building the build, instead letting you focus on development to produce high quality code.  Maven has a detailed dependency management mechanism, so to get a project running on your local you don’t need to deal with jar files or the files that those jar files depend on — a la transitive dependency. Maven uses third-party public repositories for fetching all those artifacts, and there’s a good deal of them around.

Maven has a pluggable architecture, and the Maven core is actually very lightweight. It doesn’t even know about compiling code. It is just a matter of adding a compiler plugin. For Maven, a plugin is just another artifact to be fetched from a repository. Since the architecture is very pluggable, you can implement your own plugin and hook it into the build system easily.

In the sections below we’ll cover the core concepts of Maven in detail and discuss how you can begin using Maven in your own development projects.

The POM

POM stands for Project Object Model, and it’s what makes your project a Maven project. POM is an XML file that has the same declarative approach as in build.xml of Ant, or web.xml in Java web applications. POM describes the project with metadata for build processes, but it also contains data besides that which is needed for building, such as:

• the project’s relationship between Maven projects
• the list of team members, contributors, and developers
• source control management information
• the license of the project
• site generation information

So, it is a conceptual model that tries to cover nearly all the definitions of a software project. POM has a seamless integration with Java, but it is not just for Java projects. For instance, you can build FLEX distributable artifacts with israfil plugins, or you can create Microsoft binaries from C# codes, so it’s just a matter of plugins as we stated before. The best way to learn about the details of an XML file is to examine its XSD. Since XSD files are not human-readable, you can check out the XSD document of a Maven POM file that we shared at http://www.tinyurl.com/maven-xsddoc so you can easily see the tags that can be used inside POM.

Here is a sample skeleton for Project Object Model.

<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/maven-v4_0_0.xsd">
   <parent />
   <groupId />
   <artifactId />
   <version />
   <packaging />
   <developers /> <contributors />
   <scm>...</scm>
   <build>
      <plugins>...</plugins>
   </build>
   <dependencies>...</dependencies>
   <repositories>...</repositories>
   <pluginRepositories>...</pluginRepositories>
   <profiles>...</profiles>
</project>

As you can see, all tags reside inside the project tag of POM.  Let’s go through the tags briefly. With the parent tag you can create parent-child relationships between your Maven projects.  The groupId,  artifactId and the version tags uniquely define a project coordinate.  With the packaging tag, project-specific packaging can be determined such as jar, war, and ear bundling.  The list of developers and contributors can be found inside the developers and contributors tags.  The source control definitions can be provided with the SCM tag, and the build tag allows you can hook in plugins needed for execution and configure them according to your needs.  With the repositories and pluginRepositories definitions you can tell Maven where to look to download the needed dependencies and plugins.  And finally, the profile tag allows you to generate different builds of a project like development, staging or production.

Here is the simplest POM. It’s just six lines of XML to define a Maven project.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>myapp</artifactId>
    <version>1.0.0</version>
</project>

When we run the mvn install command on this project Maven will try to compile the code, run the tests against that code, package the project as a jar file, and deploy it to the local repository. You may ask how that’s possible with just six lines of XML — after all, we haven’t defined any source folders, test folders, or the target folder that will contain the compiled classes.  Well, those are all coming from the convention.  And they are all defined in the Super POM.

Super POM has the same analogy with Java as in java.lang.Object.  Every Maven project extends this super POM.  It resides under the Maven uber jar.  Super POM defines the standard directory layout.  With Maven 2.0.9, super POM also locks the versions of common plugins to have stable builds.  So it’s best to use the latest Maven in order to have stable and better builds.  Super POM also contains the central Maven repository definition, http://repo1.maven.org/maven2. Note that there could be more than one POM through your project hierarchy.  Your project can have a parent project, and that parent project will extend the super POM.  Inside the child project, the elements of parent POM are inherited.  So, if you want to see the merged version of the POM, just run the command mvn help:effective-pom goal.

Build LifeCycle

We declared the project with the model, but we need a process for building the project out of this metadata.  To achieve this, Maven introduces the concept of lifecycles.  A lifecycle is a process for building and distributing an artifact, and it is clearly defined.  There are three built-in lifecycles of Maven: the default, which handles project deployment; the clean, which handles the cleaning of all project files generated by a previous build; and the site, which generates the project’s site documentation.  Each lifecycle contains phases in a specific order, and zero or more goals are attached to each phase.  So the atomic part here is the goal, and when we gather goals together we have the phases, and when phases are registered in specific order we have the lifecycle.  The illustration below shows the list of phases for the default lifecycle.

The default lifecycle of Maven first validates the project, like checking the consistency of pom.xml file, and then it tries to compile the code. If the compile is successful, it then tries to run the test against the compiled code, package the project in the specified format, run the integration tests against that package, verify the package by checking for the validity, install the verified package to the local repository, and finally deploy the package in the specified environment.

To execute phases/goals we can follow the notation below in the command line:

mvn phase
mvn phase:goal

We can also invoke multiple phases/goals within one command line, like:

mvn phase phase:goal
mvn phase:goal phase:goal

When we invoke the mvn integration-test command, Maven executes all the phases that are registered before that phase.  So the validate, compile, and package phases get executed before the integration-test phase.

Dependency Management

Maven is very capable of handling dependencies as the build tool.  If you’re still using the old-fashioned method of copying the necessary artifacts by hand to your lib folder,  believe us — it’s the beginning of the end for your project. You will find yourself in jar hell very soon.  So how can you avoid this?  The answer is Maven and its dependency mechanism.

If you specify a dependency by giving the coordinates of some third party project, which is the group identifier, artifact identifier, and the version, Maven will look for that artifact inside the defined repositories and fetch to the local repository.  Since everything is a plugin to Maven in the ecosystem, Maven-dependency-plugin is responsible for those actions.

Here is a sample dependency declaration for the project JUnit.  The dependency is defined by its coordinates, groupId, artifactId, and version.

<dependency>
     <groupId>junit</groupId>
     <artifactId>junit</artifactId>
     <version>4.8.1</version>
     <scope>compile</scope>
</dependency>

Scopes can also be provided while defining the dependency. There are six kinds of scopes.  The default scope is the compile.  All dependencies scoped as compile are in the project’s compile, test, and runtime classpaths by default.  Provided is a similar scope to compile, but it is expected that the dependency should be provided by JDK or the container at runtime.  For instance, servlet.jar is one of the dependencies that is usually scoped like this.  Because it will be provided by the web container, provided scope affects the compile and test classpaths.  Runtime scope means that the dependency is not needed for compilation, but it is needed at test execution and runtime so it affects the test and runtime classpaths.  For instance we might need a JDBC driver implementation only at runtime, so artifact will be scoped as provided.  Test scope means that dependency is only needed for test compilation and execution and not for the application itself.  It affects the test classpath.  System scope is the same as provided, but the dependency should be explicitly specified since it won’t be looked up in the repository.  It affects the compile and test classpaths. To declare the path of the dependency there is the <systemPath> tag that you can use.  Actually, we don’t recommend using this, because in our opinion every dependency should be “Mavenized” and go into the repository.  The last scope is import, which is introduced with Maven 2.0.9.  With import scope it is stated that the specified POM should be replaced with the dependencies in that POM’s <dependencyManagement> section.

Versions and Ranges on Dependencies

Maven follows this notation for versioning artifacts:

<major>.<minor>.<incremental> - <qualifier>

It starts with a major version and follows up with a minor one, and then an incremental version comes up.  At the end you can also add a qualifier in free-text format.  For example, both of these examples are valid artifact versions:

1.2.3
1.2.3-alpha-01

Be careful about qualifier notation since Maven uses string comparison while comparing two artifacts.  For example, 1.2.3-alpha-2 would be a later version than 1.2.3-alpha-10.  Zero left padding is needed on the alpha-2 qualifier to make it the earlier version.  You can also define ranges on versions while adding dependencies to your project, and you can define exclusion or inclusion on the range with the bracket notation like this:

<dependency>
     <groupId>junit</groupId>
     <artifactId>junit</artifactId>
     <version>[3.8,4.0)</version>
</dependency>

The version tag here states that it should be 3.8 at least, and it should be below 4.0.

Snapshot Qualifier

Maven also has a special qualifier, the SNAPSHOT, which indicates the artifact is created while the project is under active development.  When you install/release an artifact or fetch one from a remote repository, Maven expands this SNAPSHOT suffix with a date (UTC format)-time-buildnumber pattern.  So for an artifact such as myjar-1.0.0-SNAPSHOT.jar the result would be something like myjar-1.0.0-20100219.141012-1.jar.  And if you install a SNAPSHOT artifact to your local repository, it will not get converted to the date-time format in order to avoid filling your hard disk with snapshot versions.

By default Maven will periodically (on a daily basis) attempt to download the latest version of the snapshot.  You can change it to “always” or an “interval” specified in minutes by adjusting the setting in your repository configuration.

<releases>
      <updatePolicy>interval:30</updatePolicy>
</releases>

Managing Projects and Dependencies

Maven supports parent-child relationships between projects.  To declare a project as a parent, add the parent tag in your project’s pom.xml like this:

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.openglogic.wazi</groupId>
        <artifactId>parentapp</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>sampleapp</artifactId>
</project>

Just add the groupId, artifactId, and version of your parent project.  Maven will look into the parent folder and the local repository to locate that parent project.  It’s not mandatory to define groupId and version in your subproject, as Maven could inherit those fields from the parent.  Your project will also inherit dependencies that are declared in the parent project’s POM.  To see the merged version of the child project’s POM we can use mvn help:effective-pom command.  Actually, the most likely problem that you might encounter here is this: if you have a good number of child projects extending one parent POM, changing one dependency in the parent causes all child projects to face the consequences of that change.  Thus, it might be better to use the dependencyManagement feature.  Here’s the parent POM of a project that defines Commons-Logging with dependencyManagement at version 1.1.1:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>parentapp</artifactId>
    <packaging>pom</packaging>
    <version>1.0</version>
    <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>commongs-logging</groupId>
               <artifactId>commongs-logging</artifactId>
               <version>1.1.1</version>
           </dependency>
       </dependencies>
    </dependencyManagement>
</project>

And here’s the POM of a child application.  As you can see, we didn’t define the version of Commons-Logging.  Instead, the version that we declared in the parent POM will be used.  And if we don’t define the Commons-Logging dependency in the child, it won’t be inherited from parent as in the previous case.

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.openlogic.wazi</groupId>
        <artifactId>parentapp</artifactId>
        <version>1.0</version>
    </parent>
    <artifactId>sampleapp</artifactId>
    <dependencies>
       <dependency>
           <groupId>commongs-logging</groupId>
           <artifactId>commongs-logging</artifactId>
       </dependency>
    </dependencies>
</project>

You may also have a project dependency hierarchy like this:

Here projectA depends on projectB and projectB depends on projectC.  So to compile projectA we need to compile projectB, but in order to compile projectB we need to compile projectC.  And that results to eight lines of Maven commands for just compiling projectA.

To overcome this, Maven supports a project modules approach.  We can create a modules project and have that project to point to the submodules. Here is the POM of modulesapp:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>modulesapp</artifactId>
    <packaging>pom</packaging>
    <version>1.0</version>
    <name>modulesapp</name>
    <modules>
        <module>projectA</module>
        <module>projectB</module>
        <module>projectC</module>
    </modules>
</project>

By just compiling the modulesapp, we’ll have three submodules compiled automatically since they’re declared as modules inside the project. Maven-reactor-plugin will take the stage here and analyze the dependency hierarchy to define the order of compile.

Repositories

At some point each Java project that we’ve been developing heavily depends on other artifacts. For instance, a simple web application using the stack JSF, PrimeFaces, Seam, JPA, and Hibernate will have 40 dependencies like:

REPO/javax/activation/activation/1.1/activation-1.1.jar
REPO/antlr/antlr/2.7.6/antlr-2.7.6.jar
REPO/asm/asm/3.1/asm-3.1.jar
REPO/cglib/cglib/2.2/cglib-2.2.jar
REPO/commons-beanutils/commons-beanutils/1.7.0/commons-beanutils-1.7.0.jar
REPO/commons-codec/commons-codec/1.3/commons-codec-1.3.jar
REPO/commons-collections/commons-collections/3.2.1/commons-collections-3.2.1.jar
REPO/commons-lang/commons-lang/2.4/commons-lang-2.4.jar
REPO/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1.jar
REPO/dom4j/dom4j/1.6.1/dom4j-1.6.1.jar
REPO/javax/el/el-api/1.0/el-api-1.0.jar
REPO/org/hibernate/hibernate-annotations/3.5.0-Beta-2/hibernate-annotations-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-commons-annotations/3.2.0.Beta1/hibernate-commons-annotations-3.2.0.Beta1.jar
REPO/org/hibernate/hibernate-core/3.5.0-Beta-2/hibernate-core-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-entitymanager/3.5.0-Beta-2/hibernate-entitymanager-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-validator-legacy/4.0.2.GA/hibernate-validator-legacy-4.0.2.GA.jar
REPO/hsqldb/hsqldb/1.8.0.2/hsqldb-1.8.0.2.jar
REPO/javassist/javassist/3.10.0.GA/javassist-3.10.0.GA.jar
REPO/org/jboss/el/jboss-el/1.0_02.CR4/jboss-el-1.0_02.CR4.jar
REPO/org/jboss/seam/jboss-seam/2.2.0.GA/jboss-seam-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-jul/2.2.0.GA/jboss-seam-jul-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-mail/2.2.0.GA/jboss-seam-mail-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-ui/2.2.0.GA/jboss-seam-ui-2.2.0.GA.jar
REPO/org/hibernate/java-persistence/jpa-api/2.0-cr-1/jpa-api-2.0-cr-1.jar
REPO/javax/faces/jsf-api/1.2_13/jsf-api-1.2_13.jar
REPO/com/sun/facelets/jsf-facelets/1.1.14/jsf-facelets-1.1.14.jar
REPO/javax/faces/jsf-impl/1.2_13/jsf-impl-1.2_13.jar
REPO/jstl/jstl/1.2/jstl-1.2.jar
REPO/javax/transaction/jta/1.1/jta-1.1.jar
REPO/junit/junit/3.8.1/junit-3.8.1.jar
REPO/javax/mail/mail/1.4.1/mail-1.4.1.jar
REPO/postgresql/postgresql/8.4-701.jdbc3/postgresql-8.4-701.jdbc3.jar
REPO/org/primefaces/primefaces/1.0.0/primefaces-1.0.0.jar
REPO/quartz/quartz/1.6.0/quartz-1.6.0.jar
REPO/javax/servlet/servlet-api/2.5/servlet-api-2.5.jar
REPO/org/slf4j/slf4j-api/1.5.8/slf4j-api-1.5.8.jar
REPO/org/slf4j/slf4j-nop/1.5.6/slf4j-nop-1.5.6.jar
REPO/org/testng/testng/5.9/testng-5.9.jar
REPO/xpp3/xpp3_min/1.1.3.4.O/xpp3_min-1.1.3.4.O.jar
REPO/xstream/xstream/1.1.3/xstream-1.1.3.jar

Of course, we can store those jars in source control, but it will:

• increase the storage
• make it dreadful to checkout the  project
• force us to version our jars, and we certainly don’t need that

To manage your project’s artifacts and dependencies Maven offers the repository mechanism. There are two types of repositories: a local one that caches the remote downloads your projects depends on and stores the build artifacts that you haven’t yet released; and the remote one that’s mostly hosted by a third party provider and is accessible with a variety of protocols like http. You can store artifacts with extensions like jars, wars, ears, ejbs, zips, and rar and resolve them through the Maven dependency management in your project. If there’s no external repository specified in the project’s POM, Maven looks for a local repository and the central Maven repository defined in the super POM. There are two types of repositories for hosting snapshot and release artifacts. Here’s a sample declaration for each. The first declaration is for a JBoss release repository. The id is uniquely identifying the repository, and it’s pointing to the given URL.

<repository>
    <id>jboss-repo</id>
    <name>The Release JBoss maven repo</name>
    <url>http://repository.jboss.org/maven2</url>
    <releases>
        <enabled>true</enabled>
    </releases>
</repository>

The second declaration is for snapshot artifacts. By default, Maven will not look into repositories for snapshot artifacts if the repository declaration is not tagged as snapshots with the enabled tag.

<repository>
    <id>jboss-snapshot-repo</id>
    <name>The Snapshot JBoss maven repo</name>
    <url>http://snapshots.jboss.org/maven2</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

Searching for Artifacts Online

Searching for artifacts to add as dependencies to your projects can be a problem from time to time. You know that you need a specific jar, such as the Apache Jackrabbit core jar file, but you don’t know about its groupId, artifactId, or the latest version that is available. With the sites listed below, you can easily search for your artifacts online.

http://repository.apache.org
http://www.jarvana.com
http://mvnrepository.com
http://www.artifact-repository.org
http://www.mvnbrowser.com
http://mavensearch.net

Apache runs a Nexus at repository.apache.org. You can find all the Apache-related stuff in there. Another one of the sites above, Jarvana, is actually one of our favorites. It gives you the ability to search for an artifact based on the project name or even a class file name. Suppose you’re developing a web application and you came across a class not found problem that occurred at runtime. With Jarvana you can search for those classes and find the related Maven artifact. It also lists the Javadocs and other cool stuff if applicable.

IDE Support

For popular JAVA IDEs like NetBeans Eclipse or IDEA, you can find first-class support for Maven inside the IDEs. NetBeans and Intellij IDEA support Maven out of the box and ship with the latest version, Maven 3. For Eclipse there are two incubation projects at the moment. One of them is Eclipse Integration for Apache Maven, Eclipse IAM, which is also formerly known as the Q4E project. The other one is the m2eclipse plugin and it’s being maintained by Sonatype. m2eclipse is a must-have plugin if you’re developing on Eclipse. With m2eclipse you can check out Maven projects directly from source control as Maven projects. It supports source controls like Subversion, CVS, Git and many others. You can also create new projects by selecting archetypes.  It’ll take 30 seconds to get you started, for instance, with web applications. There’s also a nice POM editor bundled with the plugin so you don’t need to deal with the XML directly. We’ve includes some screenshots of the plugin below.

To checkout projects from source control:

To create a project with archetypes:

The pom.xml editor – the dependencies:

The Dependency Graph:

Finishing up

There’s no better way to learn the benefits of Maven than to give it a try.  If you’re starting from scratch or have a greenfield project, now is the perfect time to get started with Maven! Maven will ease the build process of your project, and it will be much simpler to manage the project with well-defined metadata. If you’re part of a group of developers working on the same project, you could also use Maven to create your own repository manager. (Nexus, Arcihva and Artifactory are other open source alternatives you can use for that.) Another way to get started with Maven is to create a company or project-specific POM to easily manage dependencies across your sub-projects.

Regardless of how you get started with Maven, here are a few tips to keep in mind:

• Keep your POM simple and readable.
• Use property references to avoid any hard coding.
• Use profiles to create different builds out of your project. Make it so that you can release early and release often — it’s a MUST in the land of agile/extreme programming.
• Follow the rule for Seperation of Concerns, or SoC. Arrange your Maven projects so that you have one artifact per project.
• Use IDE integrations for Maven — there’s a good deal of first class support for popular Java IDEs. Move yourself from stone age to iron age on that matter.
• And finally, do not use parameters for ignoring your tests, they’re evil!

Should you need additional resources on Maven, try the following books that you can find online for free:

http://www.sonatype.com/book

• Maven:The Complete Reference
• Maven By Example
• m2eclipse Book
• Nexus Book

http://www.maestrodev.com/better-build-maven

• Better Builds with Maven

Before You Start

Our tutorial assumes that you’re familiar with the following technologies:

• JavaServer Faces (JSF) and Facelets
• Dependency Injection Mechanism
• Bean Validation

You’ll also need to install the following applications in order to build the demo application from scratch, or to run it on your local machine:

• Java 6 (Java SDK 1.6) or greater
• NetBeans 6.8 bundled with GlassFish 3
• Maven, preferably the latest version 2.2.1 (Netbeans ships with Maven 3.0-SNAPSHOT, so that can also be used)

Meat & Potatoes

What’s New with Java EE 6?

Java EE 6 specification was finalized in December of 2009, bringing new and updated features to the world of enterprise application development. It introduces the profile approach, meant to focus both developers and applications on particular parts of the Java EE 6 platform. The first profile defined by the expert group is the Java EE 6 web profile, which attempts to specify the minimal configuration targeted for the development of typical web applications. Here are the elements of the web profile, with a few that we’ve chosen to explain in detail.

1. Servlet 3.0
   In web frameworks, servlets are used as an entry point to handle all incoming requests, so it could be said that they are the core elements of web-based applications. The new 3.0 version (specification JSR-315) offers innovative features like ease of development with annotations (@Servlet, @ServletFilter, @ServletContextListener) and annotations for restful services like @GET, @POST and more. It also offers pluggability and extensibility. The main aim here is to attain zero-configuration when working with other frameworks and libraries. Toward this end, a  new xml tag definition called <web-fragment> can be used to apply this feature. The web fragments, which are to be stored inside the jars of their respective libraries, will be merged by the container — so there’s no need for the developer to set up any configurations on the web descriptor file. Speaking of pluggability and extensibility, Servlet 3.0 also has a new application programming interface (API) which can be used to add servlets and filters with coding.
2. JavaServer Pages (JSP) 2.2
3. ExpressionLanguage (EL) 2.2
4. Debugging Support for Other Languages (JSR-45) 1.0
5. Standard Tag Library for JavaServer Pages (JSTL) 1.2
6. JavaServer Faces (JSF) 2.0
   Ever since  the release of JSF’s 1.X version, its aim was to be the go-to framework for building user interfaces and web applications. As it gained popularity with many application developers around the world, there was a growing awareness of terrific features like componenting, validation, navigation, i18n and others. However, as with so many wonderful things, flaws and disadvantages became more evident over time — like how complicated it could be to accomplish even a simple task such as creating your own custom JSF component. JSF version 2.0 aims to remedy these flaws by simplifying and easing development and introducing new features, like built-in Ajax support, which will make standard some of what have until now been third party solutions. Here’s a quick summary of the improvements that are part of JSF 2.0.
   • Composite components
     Implementing custom JSF components in 1.x is a real burden. You have to implement a UI component and Tag class, with the option of a Renderer for the markup, and then configure all these within faces-config and tld files. JSF 2.0 simplifies the procedure with the composite component approach introduced in Facelets.
   • Native Ajax Support
     JSF 2.0 provides built-in support for Ajax with its API and infrastructure.  A good example of the useful new components is f:ajax.
   • State Saving
     Since JSF 2.0 aims to handle requests partially with classes like PartialViewContext and PartialStateHolder (among others), it also attempts to make use of a partial mechanism to handle state saving. This has been implemented before, by Apache Trinidad, but PartialStateHolder and StateHelper classes provide a more elegant solution. The goal is to have a lightweight version of the saved state going back and forth in response to requests.
   • Scopes
     In addition to the request, session and application scopes, 2.0 also introduces view and flash scopes. View-scoped beans have a life span that is longer than a request, but shorter than session-scoped beans. Flash scopes are like the view scopes that will live on a specified view, including the redirects, and will be removed if you’re moving another view.
   • Navigation
     In JSF 1.x every navigation rule should be added to faces-config.xml. With version 2.0 implicit navigation can also be used, as in whether or not an outcome corresponds to a view I.D. It’s also possible to perform conditional navigations on a navigation-case. The new tag <if> can be used in faces-config, with an el snippet for conditional navigation. Version 2.0 also makes it easy to retrieve view parameters and assign them to a given property, which in turn makes handling the parameters for GET requests easy. Two new components (h:link and h:button) also support the integration of view parameters. The key benefit of using these components will be bookmarkable URLs.
   • Configuration with Annotations
     With JSF 2.0 you can annotate your managed beans with the new @ManagedBean annotation, and you can specify the scope for your beans with @RequestScoped, @SessionScoped, @ViewScoped, @NoneScoped and more. Instead of those, we’ve chosen to use CDI and Weld annotations.
7. Common Annotations for Java Platform (JSR-250) 1.1
8. Enterprise JavaBeans (EJB) 3.1 Lite
9. Java Transaction API (JTA) 1.1
10. Java Persistence API (JPA) 2.0
    In our opinion, the main highlights of this release are the API for criteria queries and the support for validation. There are also some fancy new features like extended map support and ordered list mappings.

Java EE 6 Containers

There are currently two application servers that are compatible with the implementation of Java EE 6: GlassFish Enterprise Server v3 and TMAX JEUS 7. We’ve chosen to stick with GlassFish v3.

So – What’s Up with PrimeFaces?

PrimeFaces is an open source JSF component suite that bundles over 70 components with built-in Ajax support. It’s based on the YUI and jQuery javascripting libraries. It has a simple, lightweight design that is fully compatible with other JSF component libraries. PrimeFaces also supports Ajax Push with a Comet framework, and it has a mobile UI kit known as TouchFaces. Currently, PrimeFaces supports JSF 2.0 with its 2.0.0.RC and 2.0.0-SNAPSHOT releases.

The ability of Java EE 6 to merge web.xml fragments that originate from third-party frameworks makes it unnecessary (in the context of Java EE 6) to do servlet and mapping configurations for PrimeFaces. Primefaces ships with its own web-fragment.xml.

For more information, visit www.primefaces.org.

Contexts and Dependency Injection (CDI)

As stated in Java Specification Request JSR-299, the purpose of this specification is to unify the JSF-managed bean component model with the EJB component model, resulting in a significantly simplified programming model for web-based applications. CDI also makes it possible for JEE elements to interact with each other using the observer pattern, making it a lot easier to work with enterprise beans and transactional support, among other things.

Dependency Injection For Java

JSR 330 is also a part of Java EE 6, offering a set of standard annotations that can be used for dependency injection. In our demo application we’ll use some of these annotations, such as @Named, @Inject, @Qualifier and others.

WELD

Weld is the reference implementation of JSR-299, which is abbreviated as CDI.  Weld provides a complete SPI, allowing Java EE containers to use Weld as their built-in CDI implementation. GlassFish 3 (which we’ll use in our demo) ships with Weld.

Bean Validation and Hibernate Validator

The Bean Validation, JSR 303, defines a metadata model and an API for JavaBean validation. The Hibernate Validator is the reference implementation for this specification request. Hibernate Validator’s latest version adds some nice features — things like validation grouping, native integration with JPA v.2 and JSF v.2, an extended annotation set and more.

WallFriend, The Demo APP

Let’s start by creating the project. We’ll do it using the Maven archetype command. It has an interactive mode, so see below for the user input data (in bold).

mvn archetype:generate -DarchetypeCatalog=http://anonsvn.jboss.org
   /repos/weld/archetypes/tags/1.0.0-BETA1

DEV$ mvn archetype:generate -DarchetypeCatalog=http://anonsvn.jboss.org
   /repos/weld/archetypes/tags/1.0.0-BETA1
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class =>
'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart
(org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: remote -> weld-jsf-servlet-minimal (Weld archetype for creating an
application using JSF 2.0 and CDI 1.0 for Servlet Containers
(Tomcat 6 / Jetty 6))
2: remote -> weld-jsf-jee-minimal (Weld archetype for creating a minimal
Java EE 6 application using JSF 2.0, CDI 1.0 and EJB 3.1 (persistence unit
not included))
3: remote -> weld-jsf-jee (Weld archetype for creating a Java EE 6
application using JSF 2.0, CDI 1.0, EJB 3.1 and JPA 2.0 (persistence
unit included))
Choose a number:  (1/2/3): 2

Here enter 2, for weld-jsf-jee-minimal. And then specify the
groupId-artifactId-packaging for the project.

Define value for groupId: : com.openlogic.wazi
Define value for artifactId: : wallfriend
Define value for package: : war
Confirm properties configuration:
version: 1.0.0-SNAPSHOT
groupId: com.openlogic.wazi
artifactId: wallfriend
package: war
 Y: : Y
[INFO] -------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] -------------------------------------------------------------------
[INFO] Total time: 19 seconds
[INFO] Finished at: Tue Jan 12 21:58:35 EET 2010 [INFO]
Final Memory: 12M/79M [INFO]
-------------------------------------------------------------------

Since this is an archetype project, we can immediately run it from the command line with Maven on an embedded GlassFish:

DEV$ mvn package embedded-glassfish:run
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'embedded-glassfish'.
[INFO] org.apache.maven.plugins: checking for updates from glassfish
[INFO] org.codehaus.mojo: checking for updates from glassfish
[INFO] -------------------------------------------------------------------
[INFO] Building wallfriend
[INFO]    task-segment: [package, embedded-glassfish:run]
[INFO] -------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /DEV/wallfriend/target/classes
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Compiling 1 source file to /DEV/wallfriend/target/test-classes
[INFO] [surefire:test]
[INFO] Surefire report directory: /DEV/wallfriend/target/surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running TestSuite
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.369 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [war:war]
[INFO] Packaging webapp
[INFO] Assembling webapp[wallfriend] in [/DEV/wallfriend/target/wallfriend]
[INFO] Processing war project
[INFO] Webapp assembled in[162 msecs]
[INFO] Building war: /DEV/wallfriend/target/wallfriend.war
[INFO] [embedded-glassfish:run]
[WARNING] Attempting to build MavenProject instance for Artifact
(org.codehaus.mojo:jboss-maven-plugin:3.0) of type: maven-plugin;
constructing POM artifact instead.
Downloading: http://repository.jboss.org/maven2/org/codehaus/mojo
/jboss-maven-plugin/3.0/jboss-maven-plugin-3.0.pom
Downloading: http://repo1.maven.org/maven2/org/codehaus/mojo
/jboss-maven-plugin/3.0/jboss-maven-plugin-3.0.pom
[WARNING] Attempting to build MavenProject instance for Artifact
(org.apache.maven.plugins:maven-eclipse-plugin:3.0)  of type:
maven-plugin; constructing POM artifact instead.
Downloading: http://repository.jboss.org/maven2/org/apache/maven
/plugins/maven-eclipse-plugin/3.0/maven-eclipse-plugin-3.0.pom
Downloading: http://repo1.maven.org/maven2/org/apache/maven
/plugins/maven-eclipse-plugin/3.0/maven-eclipse-plugin-3.0.pom
Jan 13, 2010 10:36:39 PM com.sun.enterprise.v3.server.AppServerStartup run
INFO: GlassFish v3 (74.2) startup time : Embedded(1228ms)
startup services(1317ms) total(2545ms)
Jan 13, 2010 10:36:39 PM com.sun.enterprise.transaction
.JavaEETransactionManagerSimplified initDelegates
INFO: Using com.sun.enterprise.transaction.jts
.JavaEETransactionManagerJTSDelegate as the delegate
Jan 13, 2010 10:36:40 PM org.glassfish.admin.mbeanserver
.JMXStartupService$JMXConnectorsStarterThread run
INFO: JMXStartupService: JMXConnector system is disabled, skipping.
Jan 13, 2010 10:36:40 PM AppServerStartup run
INFO: [Thread[GlassFish Kernel Main Thread,5,main]] started
Jan 13, 2010 10:36:40 PM org.hibernate.validator.util.Version
INFO: Hibernate Validator null
Jan 13, 2010 10:36:40 PM org.hibernate.validator.engine.resolver
.DefaultTraversableResolver detectJPA
INFO: Instantiated an instance of org.hibernate.validator.engine.resolver
.JPATraversableResolver.
Jan 13, 2010 10:36:41 PM com.sun.enterprise.v3.services.impl
.GrizzlyProxy$2$1 onReady
INFO: Grizzly Framework 1.9.18-k started in: 434ms listening on port 7070
Jan 13, 2010 10:36:58 PM com.sun.common.util.logging
.LoggingConfigImpl openPropFile
INFO: Cannot read logging.properties file.
Jan 13, 2010 10:36:58 PM com.sun.enterprise.web.WebContainer
createHttpListener
INFO: Created HTTP listener embedded-listener on port 7070
Jan 13, 2010 10:36:58 PM com.sun.enterprise.web.WebContainer
configureHttpServiceProperties
WARNING: pewebcontainer.invalid_http_service_property
Jan 13, 2010 10:36:59 PM com.sun.enterprise.web.WebContainer createHosts
INFO: Created virtual server server
Jan 13, 2010 10:36:59 PM com.sun.enterprise.web.WebContainer
loadSystemDefaultWebModules
INFO: Virtual server server loaded system default web module
^[[BJan 13, 2010 10:37:08 PM com.sun.enterprise.security.SecurityLifecycle
INFO: security.secmgroff
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.ssl.SSLUtils
checkCertificateDates
SEVERE: java_security.expired_certificate
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.SecurityLifecycle
onInitialization
INFO: Security startup service called
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.PolicyLoader
loadPolicy
INFO: policy.loading
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.auth.realm.Realm
doInstantiate
INFO: Realm admin-realm of classtype com.sun.enterprise.security.auth
.realm.file.FileRealm successfully created.
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.auth.realm.Realm
doInstantiate
INFO: Realm file of classtype com.sun.enterprise.security.auth.realm.file
.FileRealm successfully created.
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.auth.realm.Realm
doInstantiate
INFO: Realm certificate of classtype com.sun.enterprise.security.auth
.realm.certificate.CertificateRealm successfully created.
Jan 13, 2010 10:37:09 PM com.sun.enterprise.security.SecurityLifecycle
onInitialization
INFO: Security service(s) started successfully....
classLoader = WebappClassLoader (delegate=true; repositories=WEB-INF/classes/)
SharedSecrets.getJavaNetAccess()=java.net.URLClassLoader$7@2d205042
Jan 13, 2010 10:37:09 PM org.jboss.weld.bootstrap.WeldBootstrap
INFO: WELD-000900 SNAPSHOT
Jan 13, 2010 10:37:09 PM org.hibernate.validator.engine.resolver
.DefaultTraversableResolver detectJPA
INFO: Instantiated an instance of org.hibernate.validator.engine
.resolver.JPATraversableResolver.
nullID: /DEV/wallfriend/gfembed6764346819525137279tmp/applications
/wallfriend/ CLASSES: [class war.HelloWorld]

Jan 13, 2010 10:37:10 PM com.sun.faces.config.ConfigureListener
contextInitialized
INFO: Initializing Mojarra 2.0.2 (FCS b10) for context '/wallfriend'
Jan 13, 2010 10:37:14 PM com.sun.enterprise.web.WebApplication start
INFO: Loading application wallfriend at /wallfriend
Hit ENTER to redeploy, X to exit

Once you see the line Hit ENTER to redeploy, X to exit, make a request for http://localhost:7070/wallfriend on your browser. You should get a first look at the archetype application like the one below:

Now, let’s open the project inside NetBeans 6.8. Open NetBeans and click File > New Project and then select Maven / Maven Project with Existing POM from the resulting wizard. This should put the Open Project menu on your screen. Select wallfriend from here and you should see the project in the projects tab:

To run wallfriend inside NetBeans 6.8, you need to make sure that you have Java 1.6 defined as a Java platform, and be sure that wallfriend is also using it. Also, from the Tools > Servers menu, you need to define the Java 1.6 executable for your GlassFish. Netbeans also comes with a Maven 3.0-SNAPSHOT version. So, if you want to use your own external Maven, you must declare it to the IDE from Preferences > Miscellaneous > Maven. After configuring it all, just make a request for http://localhost:8080/wallfriend on your browser. You should see the very same page as you did when you ran the project with the embedded GlassFish.

Adding PrimeFaces to the Project

In order to use the JSF components of PrimeFaces, we first have to add the repo and dependency definitions to the pom.xml of the project. Go ahead and open Project Files > pom.xml in NetBeans and add the following snippets, respectively:

<repository>
    <id>prime-repo</id>
    <name>Prime Technology Maven Repository</name>
    <url>http://repository.prime.com.tr</url>
    <layout>default</layout>
</repository>

<dependency>
    <groupId>org.primefaces</groupId>
    <artifactId>primefaces</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

Now namespace can be added inside the xhtml’s files for PrimeFaces, xmlns:p=”http://primefaces.prime.com.tr/ui”. As mentioned above, there is no configuration needed in web.xml since PrimeFaces ships with its own web fragment.

Wallfriend – The Implementation

As we said before, wallfriend is a simple write-to-wall application with a basic domain, managed beans, and some xhtml pages. You can check out the source from the Google Code project at http://wallfriend.googlecode.com/svn/trunk/wallfriend. A follow the wall mechanism as well as a restful expose of the wall will be added to the project in the near future.

Since the application was not created from scratch, we have some clean-up to do on the archetype-created application. Go ahead and delete the following folders, because they won’t be used:

• Web Pages/WEB-INF/templates
• Web Pages/resources
• Source Packages / war
• Test packages / war

Now let’s go through the parts of the project: The Model, The Managed Beans, and The Views.

The Model

For the domain, we have 3 classes: Wall, Brick and WallFriendContext. Wall and Brick are for defining a master-detail relationship between the posts and the wall. WallFriendContext is the application-scoped bean for storing created walls. It’s marked with the javax.enterprise.context.ApplicationScoped bean.

Wall.java

package com.openlogic.wazi.beans;

import java.util.LinkedList;
import java.util.List;

public class Wall {

    String wallName;

    List bricks = new LinkedList();

    public Wall(String wallName) {
        this.wallName = wallName;
    }

    public void addBrick(String graffiti) {
        bricks.add(0, new Brick(graffiti));
    }

    public String getWallName() {
        return wallName;
    }

    public List getBricks() {
        return bricks;
    }
}

Brick.java

package com.openlogic.wazi.beans;

import java.util.Date;

public class Brick {

    private String graffiti;
    private Date publishDate;

    public Brick(String graffiti) {
        this.graffiti = graffiti;
        this.publishDate = new Date();
    }

    public void init() {
    }

    public String getGraffiti() {
        return graffiti;
    }

    public void setGraffiti(String graffiti) {
        this.graffiti = graffiti;
    }

    public Date getPublishDate() {
        return publishDate;
    }

    public void setPublishDate(Date publishDate) {
        this.publishDate = publishDate;
    }
}

WallFriendContext.java

package com.openlogic.wazi.beans;

import java.util.HashMap;
import java.util.Map;
import javax.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class WallFriendContext {

    private Map walls = new HashMap();

    public void addWall(Wall wall) {
        walls.put(wall.getWallName(), wall);
    }

    public Map getWalls() {
        return walls;
    }
}

The Managed Beans (a.k.a. Contextual Beans)

The managed bean classes are defined by the CDI and implemented by Weld, which ships with the GlassFish server. CDI also needs an empty beans.xml file under the WEB-INF folder, since we’re going to use annotations to define our beans. That’s right — that means they can also be configured with good old fashioned XML.

LoginView is the managed bean of choice for handling wall management and creation/accessing. The annotation javax.enterprise.inject.Model identifies the LoginView as a bean of the model layer, as stated in the MVC pattern. We use javax.inject.Inject to identify injectable constructors, while methods and fields. org.hibernate.validator.constraints.NotEmpty is a validator annotation that specifies that the field wallName cannot be empty.

package com.openlogic.wazi.view;

import com.openlogic.wazi.beans.Wall;
import com.openlogic.wazi.beans.WallFriendContext;
import javax.enterprise.inject.Model;
import javax.faces.context.FacesContext;
import javax.inject.Inject;
import org.hibernate.validator.constraints.NotEmpty;

@Model
public class LoginView {

    @Inject
    private WallFriendContext wallFriendContext;

    @NotEmpty(message="Wall Name cannot be empty")
    private String wallName;

    public String doLogin() {
        Wall wall;
        if (wallFriendContext.getWalls().containsKey(wallName)) {
            wall = wallFriendContext.getWalls().get(wallName);
        }
        else {
            wall = new Wall(wallName);
            wallFriendContext.addWall(wall);
        }
        FacesContext.getCurrentInstance().getExternalContext()
.getRequestMap().put("wall", wall);

        return "myWall";
    }

    public String getWallName() {
        return wallName;
    }

    public void setWallName(String wallName) {
        this.wallName = wallName;
    }
}

MyWallView is the managed bean for handling the paint-a-graffiti on the wall action. The annotation javax.inject.Named, used here, allows you to access the bean using the bean name, with the first letter in lowercase. We use javax.annotation.PostConstruct to mark a method to be invoked after the Dependency Injection is done.

package com.openlogic.wazi.view;

import com.openlogic.wazi.beans.Wall;
import java.io.Serializable;
import javax.annotation.PostConstruct;
import javax.enterprise.context.SessionScoped;
import javax.faces.context.FacesContext;
import javax.inject.Named;
import org.hibernate.validator.constraints.NotEmpty;

@Named
@SessionScoped
public class MyWallView implements Serializable {

    private Wall wall;

    @PostConstruct
    public void init() {
        wall = (Wall) FacesContext.getCurrentInstance()
                  .getExternalContext().getRequestMap().get("wall");
    }

    @NotEmpty(message="Graffiti cannot be empty")
    private String graffiti;

    public String paint() {
        wall.addBrick(graffiti);
        graffiti = "";

        return null;
    }

    public Wall getWall() {
        return wall;
    }

    public void setWall(Wall wall) {
        this.wall = wall;
    }

    public String getGraffiti() {
        return graffiti;
    }

    public void setGraffiti(String graffiti) {
        this.graffiti = graffiti;
    }
}

The Pages

Facelets, JSF 2.0, and PrimeFaces projects are used for the development of views. JSF tags are also commonly used. One different component could be p:growl, which is for viewing the FacesMessages in a Mac-like growl. Also, there is no defined navigation-rule in the faces-config.xml file for navigating from login.xhtml to myWall.xhtml. This is with the implicit navigation mechanism that comes with JSF 2.0. The return string of LoginView#doLogin() method matches the name of the myWall.xhtml view.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://java.sun.com/jsf/html"
      xmlns:f="http://java.sun.com/jsf/core"
     xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:p="http://primefaces.prime.com.tr/ui">
      <h:head>
          <title>WallFriend - Java EE 6 Starter Application</title>
      </h:head>
      <h:body>
          <h:form>
              <p:growl showDetail="true" />
              <p:panel header="Access to your wall" style="width:400px">
                  <h:outputLabel value="Wall Name : " for="wallname" />
                  <h:inputText id="wallname" value="#{loginView.wallName}" />
                  <h:commandButton value="Paint it Now, Paint it Black"
                      action="#{loginView.doLogin}" />
              </p:panel>
          </h:form>
      </h:body>
</html>

myWall.xhtml page renders the wall posts for a wall, and the user can also write up to the wall.

 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:h="http://java.sun.com/jsf/html"
       xmlns:f="http://java.sun.com/jsf/core"
       xmlns:ui="http://java.sun.com/jsf/facelets"
       xmlns:p="http://primefaces.prime.com.tr/ui">
       <h:head>
          <title>WallFriend - Java EE 6 Starter Application</title>
       </h:head>
       <h:body>
          <h:form>
             <p:growl showDetail="true" />
                <p:panel header="#{myWallView.wall.wallName}'s WALL"
                    style="width:600px">
                   <h:panelGrid columns="1">
                   <h:panelGroup>
                      <h:inputTextarea value="#{myWallView.graffiti}"
                             cols="50" rows="3" />
                      <h:commandButton value="Paint"
                             action="#{myWallView.paint}" />
                   </h:panelGroup>
                   <p:dataTable value="#{myWallView.wall.bricks}"
                            var="brick">
                      <p:column>
                        #{brick.graffiti}
                        <br/>
                        <h:outputText value="#{brick.publishDate}">
                           <f:convertDateTime dateStyle="default"
                              type="both" pattern="dd.MM.yyyy HH:mm:ss" />
                        </h:outputText>
                     </p:column>
                  </p:dataTable>
               </h:panelGrid>
            </p:panel>
         </h:form>
      </h:body>
</html>

Finishing Up

Java EE 6 is hot, new, and pretty darn cool. In our opinion, as users begin to employ it for upcoming projects, the number of blogposts, samples, and other resources will eventually increase. And with its adoption by the Java Community, we’ll for sure see more Java EE 6-compliant application servers around. Java EE 6 really eases development with its “standardized” features, and the zero-configuration approach apparent in every part of the implementation is really nice, lending an out-of-the-box feeling that’s similar to the .NET environment.  It’s not just another java framework!

Before You Start

This particular configuration is perhaps best suited to a more advanced desktop configuration, else as the basis for a server-based resource where you may have multiple desktops and want to synchronize mail across devices.

If you want the quickest and simplest route to getting mail from OWA into your MUA of choice, and are fine with it being pulled down into the local folders of a MUA, you might be better off using Davmail in its desktop configuration and without the complexity of Postfix + Fetchmail + Courier IMAP.

This tutorial assumes that:

• You have the OWA service configured on your Exchange server, e.g. https://mail.acme.com/exchange/
• You have a Gmail account with POP enabled (this tutorial could be easily adapted to other service providers)
• You are running Ubuntu GNU/Linux. However, there should be few differences if you are running Debian, and it should be easy enough to adapt this configuration to accommodate RPM-based distributions
• You are capable of appropriately securing services, e.g. managing firewall configuration

Meat & Potatoes

Note: this tutorial uses acme.com as the example corporate mail domain (OWA) and Gmail as the non-corporate mail service. You could just as easily have multiple Exchange accounts and/or standards-based e-mail accounts.

Install Packages

Fetchmail, Postfix and Courier IMAP and dependencies can all be installed via the package management system:

$sudo apt-get install postfix fetchmail courier-imap sun-java6-jdk tomcat6
tomcat6-admin ant

Configure Certificates

To be sure that we are actually connecting to Gmail and to encrypt e-mail to and from the service we need to set up a few certificates.

Create a local certificate store:

$mkdir -p /etc/ssl/local/certs/

Install the Thawte root CA certificate (required for Gmail SMTPS):

• Go to Thawte and download their root CA certificates
• Unzip the ZIP archive and locate the file: Thawte Premium Server CA.cer
• Convert the CA certificate to PEM format and install:

$sudo openssl x509 -inform der -in 'Thawte Premium Server CA.cer' -out
/etc/ssl/local/certs/thawte.pem

Install the Equifax root CA certificate (required for Gmail POP3S):

$sudo wget -O /etc/ssl/local/certs/equifax.pem

https://www.geotrust.com/resources/root_certificates/certificates/

Equifax_Secure_Certificate_Authority.cer

Install the Gmail POP3S certificate:

$openssl s_client -connect pop.gmail.com:995 -showcerts

From the output of the command select the pop.gmail.com certificate (the first block to appear between and including lines “—–BEGIN CERTIFICATE—–” and “—–END CERTIFICATE—–”) and copy and paste this into a new file:

/etc/ssl/local/certs/googlepop.pem

Hash the certificates:

$sudo c_rehash /etc/ssl/local/certs

Build and Configure Davmail

Grab the latest Davmail code from SVN. For checkout details see the Sourceforge page. Then to build:

$cd davmail/trunk
$ant

If the build is successful proceed to configure the web application archive (WAR file) version of Davmail:

$cd dist
$jar xvf davmail-N.N.N-NNN.war

(replacing ‘N.N.N-NNN’ with the version number)

Edit the file WEB-INF/classes/davmail.properties as appropriate, for example:

davmail.url=https\://mail.acme.com/exchange/
davmail.popPort=1110
davmail.smtpPort=1025
davmail.ldapPort=1389
davmail.caldavPort=1080
davmail.keepDelay=60
davmail.sentKeepDelay=180
davmail.caldavPastDelay=60

davmail.enableProxy=false
davmail.proxyHost=
davmail.proxyPort=
davmail.proxyUser=
davmail.proxyPassword=

davmail.allowRemote=true
davmail.bindAddress=
davmail.server=true
davmail.disableUpdateCheck=false

log4j.logger.davmail=DEBUG
log4j.rootLogger=WARN
log4j.logger.httpclient.wire=WARN
log4j.logger.org.apache.commons.httpclient=WARN

You should really only need to update davmail.url with the URL of your OWA service, but you may also choose to adjust the davmail.*Delay settings which control things such as for how many days messages that have been retrieved should be left on the Exchange server. However, note that the Postfix and Fetchmail configuration that follows assumes that you have set the POP3 and SMTP port numbers as detailed above.

Re-package the web application archive:

$jar cvf davmail.war WEB-INF META-INF

Configure Tomcat and deploy Davmail

Grant all Java security permissions to Davmail by editing the file /etc/tomcat6/policy.d/50local.policy and adding to the bottom:

// Davmail
//grant codeBase "file:${catalina.base}/webapps/davmail/-" {
//        permission java.security.AllPermission;
//};

Create a user for the Tomcat admin application by editing the file /etc/tomcat6/tomcat-users.xml and adding to the bottom:

<tomcat-users>
<role rolename="tomcat"/>
<role rolename="manager"/>
<user username="yourusername" password="yourpassword" roles="manager"/>
</tomcat-users>

Substitute “yourusername” and “yourpassword” for the username and password you want to use for administering Tomcat.

Restart Tomcat:

$sudo /etc/init.d/tomcat6 restart

Deploy Davmail:

• Log in to the Tomcat admin application at http://yoursystem:8080/manager/html
• From the WAR file to deploy section browse to the davmail.war archive we created earlier, and then select Deploy.
• Davmail should now be listed in the Applications section. If Davmail is not showing as running select Start from the Commands column.

Configure Postfix

For security reasons it makes sense to keep mail on-system whenever possible. Or to put it another way: if I send mail from my Acme Inc account to another Acme Inc user why route it via a 3rd party mail system? So, we’ll be explicit when it comes to mail routing.

Edit the file /etc/postfix/main.cf and set the following options:

home_mailbox = Maildir/

smtp_tls_loglevel = 1
smtp_tls_per_site = hash:/etc/postfix/tls_per_site
smtp_tls_CAfile = /etc/ssl/local/certs/thawte.pem
smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache
smtp_use_tls = yes

smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_sasl_tls_security_options = noanonymous

relayhost = [smtp.gmail.com]:587

disable_dns_lookups = yes

smtp_generic_maps = hash:/etc/postfix/generic

sender_dependent_relayhost_maps = hash:/etc/postfix/bysender

Configure Postfix to route mail sent from the corporate account(s) to OWA via Davmail, by editing the file /etc/postfix/bysender and adding:

@acme.com         [localhost]:1025

Map any local users to routable mail addresses by editing the file /etc/postfix/generic and adding:

ausername@yoursystem		someuser@acme.com

Note: ‘yoursystem’ is the system we are configuring, ‘ausername’ is a Linux account on this system and the right hand address could be an Exchange or Google account. This configuration is optional and is only used where a MUA defaults to setting the originator address of a message to $LOGNAME@$HOSTNAME.

Store the authentication credentials for remote SMTP (and sending via OWA) by editing the file /etc/postfix/sasl_passwd and adding:

[smtp.gmail.com]:587    auser@gmail.com:gmailpassword
[localhost]:1025        DOMAIN\USER:domainpassword

Note: the 2nd line is specifying credentials that will be passed to OWA via Davmail, therefore “DOMAIN\USER” is the username half of Windows domain credentials. Ensure that this file is mode 640 and ownership root:postfix.

For security reasons force connections to Google’s SMTP service to use TLS by editing the file /etc/postfix/tls_per_site and adding:

smtp.gmail.com         MUST

Create the Postfix lookup tables:

$cd /etc/postfix
$sudo postmap bysender
$sudo postmap generic
$sudo postmap sasl_passwd
$sudo postmap tls_per_site

Restart Postfix:

$sudo /etc/init.d/postfix restart

Note: If you plan to use this configuration on a server you will likely want to configure Postfix to accept SMTP connections from remote MUAs over SSL. However, this is out of the scope of this tutorial.

Configuring Courier IMAP

Edit the file /etc/courier/imapd and ensure that the following variables are set (they should be found toward the bottom of the file):

IMAPDSTART=YES

MAILDIRPATH=Maildir

Edit the file /etc/courier/authdaemonrc and ensure that the following variable is set:

authmodulelist="authpam"

Note: If you plan to use this configuration on a server you will likely want to configure the Courier IMAP service to work over SSL. However, this is out of the scope of this tutorial.

Configure the Local User Environment

Create an initial maildir format mailbox:

$maildirmake ~/Maildir

Create a new file ~/.fetchmailrc to hold the Fetchmail configuration:

#
# ~/.fetchmailrc
#
# Check mail every 120 seconds
#
set daemon 120
set postmaster ausername
#
# Gmail
#
poll pop.gmail.com with proto POP3 and options no dns
        user 'auser@gmail.com' with pass "gmailpassword" is 'ausername'
        here options ssl sslcertck
sslcertpath '/etc/ssl/local/certs/'
        smtphost localhost
#
# ACME Inc
#
poll localhost with proto POP3 and options port 1110 no dns
        user "someuser@ACME" with pass "domainpassword" is 'ausername' here
        smtphost localhost
#

Note: “ausername” is the local Linux account. SSL is not needed when retrieving mail from Exchange as the fetchmail -> Davmail connection will be over localhost, and Davmail -> OWA over https (unless your Exchange administrators have configured the OWA service to run over http).

Manually start Fetchmail in verbose mode and check for errors:

$fetchmail -v

Fetchmail can be configured to automatically start via a number of different mechanisms. For example, with Gnome desktop you could create a new ‘Startup Application’ from System -> Preferences, and have ‘/usr/bin/fetchmail’ be executed on login. Or you could add fetchmail to your personal crontab, e.g.:

*/2 * * * * /usr/bin/fetchmail -s

When using cron you would remove the line starting set daemon from file .fetchmailrc.

Finishing Up

Mail Client Settings

If you are running a local MUA that supports the maildir mailbox format there should be nothing to configure other than the sending identities and application preferences. If you are using a local MUA that does not support maildir you should use IMAP and enter localhost for the server and use your Linux account credentials for authentication. If you are using this configuration on a server: for the MUA on the client you would use the server FQDN for the IMAP server and your Linux account credentials for authentication, and SMTP settings would depend on how you had configured SMTP authentication (incoming to the server).

Davmail also provides proxies for LDAP and CalDAV to OWA:

• LDAP: server: localhost:1389; bind dn: USER@DOMAIN; password: domainpassword; search base: ou=people; search field: sn
• CalDAV: URL: http://localhost:1080/users/someuser@acme.com/calendar/; password: domainpassword

USER@DOMAIN and domainpassword are the credentials associated with your Windows domain account.

Note: Whenever your Windows domain password or Gmail password changes you will need to update this in ~/.fetchmailrc and /etc/postfix/sasl_passwd, and execute $sudo postmap /etc/postfix/sasl_passwd.

Conclusion

The configuration detailed here is rather more complicated than ought to be and has wrinkles such as having to store user credentials in both Fetchmail and Postfix configuration. As such its appeal is likely limited to use with more complex mail requirements involving OWA and where there are few, if any, alternative options. Davmail could be used on its own for simple OWA access; however, the addition of Fetchmail and Postfix also means that e-mail is always stored in a standard format, maildir, and that where possible outbound e-mail is always kept on-system. The addition of Courier IMAP allows a greater number of local MUAs to be used (i.e. those that do not support maildir), and the configuration could be deployed to a server and the unified inbox synchronised across multiple desktops.

Finally, there is much room for improvement, and it would be great to see this configuration further developed such that user credentials were better handled and a practical, secure multi-user proxy server could be easily set up, thereby providing a shared service for Exchange OWA <—> standards-based (IMAP, SMTP, LDAP and CalDAV) MUA integration.

So why use Hudson to create a continuous integration server? There are certainly other CI engines out there, such as the primary open source rivals to Hudson: Apache Continuum and CruiseControl.  Some good commercial CI engines are also available, but those are beyond the scope of this article.

We’ve worked with both Continuum and CruiseControl in the past, and consider them to be functional – in an adequate sort of way. Continuum’s web-based front-end isn’t bad, and for the most part it does what it’s designed to do. We’ve found CruiseControl to be more competent than Continuum when it comes to stability, although we must admit that we have not tried any of Continuum’s newer builds. But when it comes to ease of configuration Hudson wins, hands down. If, like us, you’re visually-oriented, and if you find it painful to edit an XML file to configure CI (as is the case with CruiseControl), Hudson’s graphical user interface just makes perfect sense.

Interested readers should be able to find more detailed comparisons of CI engines (like this one) with a quick search, but our conclusion – based on a combination of first-hand experience and other people’s opinions – is that Hudson is the current front-runner among open source CI engines.

Before You Start

You’ll need to be proficient in  Maven and Subversion before you continue. The principle here is to have a mock application hosted in a Subversion repository. We’ll then download and configure Hudson to access the Subversion repository, and perform continuous integration builds from there. We’ll assume you already have Maven configured. If not, have a look at the tutorial titled Creating a Maven-Based Development Environment on Linux. You’ll also need to have an accessible Subversion server set up somewhere.  If you don’t, a good place to get started is at http://subversion.tigris.org/faq.html#repository.

Meat & Potatoes

Creating a Test Project

Let’s start with a software project for illustration purposes. For this, we’ll use Maven to generate a project with one simple command:

mvn archetype:generate

You’ll be asked to select an application type to generate. Let’s go with a simple web application. Choose option 18. Then enter the following information into the prompts:

Define value for groupId: : com.example
Define value for artifactId: : testWebApp
Define value for version:  1.0-SNAPSHOT: : [Press Enter]
Define value for package:  com.example: : [Press Enter]
Define value for package:  com.example: :
Confirm properties configuration:
groupId: com.example
artifactId: testWebApp
version: 1.0-SNAPSHOT
package: com.example
 Y: : [Press Enter]

Good job. You now have a fully functional web application that does very, very little indeed. You can compile and execute it for test purposes like this:

cd testWebApp/

mvn -Djetty.port=9999 org.mortbay.jetty:maven-jetty-plugin:6.1.18:run

The reason we use port 9999 is because we have other web applications already running on our machine. Point your favorite web browser to http://localhost:9999/testWebApp and you’ll be greeted by the now famous “Hello World!” greeting. Excited yet?

Importing the Test Project into Subversion

Next we need to import our new project into Subversion. We don’t want to import any generated artifacts so we first perform an mvn clean operation.

mvn clean

cd ..

su

# svnadmin create /var/lib/svn/repositories/testWebApp

# cd ..

# svn import testWebApp file:///var/lib/svn/repositories/testWebApp -m "initial import"

Now remove your existing webapp directory, and check it out from Subversion.

rm -rf testWebApp

svn checkout svn://armor.osdcorp.com/testWebApp

Your Subversion repository will obviously be different. Substitute the svn://armor.osdcorp.com part with your configuration.

In a normal team development environment, your team would now joyfully check out the source from Subversion, make changes, and check them back in. Let’s shift our focus to the role of Hudson, our continuous integration engine of choice.

Downloading and Installing Hudson

To download Hudson:

wget http://hudson-ci.org/latest/hudson.war

Simple as that. Now, to execute it you have two options. You can either drop it into a Servlet container like Tomcat, or you can simply start it up like this:

java -jar hudson.war --httpPort=8075

Again, due to our system already running certain web applications, we can specify an alternate port. Point your browser to http://localhost:8075 and you should be rewarded with the following:

We’ll need to do some basic configuration first. Essentially, we need to tell Hudson where the JDK and Maven reside. Click on “Manage Hudson”, then “Configure System”. In the resulting screen, configure the locations respectively. This is what it looks like on our server:

Next, make sure you have configured the “Hudson URL” at the bottom of this configuration screen. You need to change it from “localhost” to the actual hostname of your server. Something like this:

Excellent. Now click “Save”, and then click on the “New Job” link in top left corner of the page and fill out the resulting form as we have below:

Continuing from here, a more detailed page of your project is available:

Continued…

Some explanation is required here. Hudson has various methods of deciding when to perform a build. These are called build triggers. The method we have chosen here is to poll Subversion every minute. If anything has changed, we perform a build. Other trigger mechanisms exist internally to Hudson. We say internally because there is one other important method to trigger a build. An HTTP GET on http://localhost:8075/job/testWebApp/build will trigger a build from an external source. How is that useful? You could use the Wget utility to trigger that URL from the command line or a shell. It’s particularly handy if you use the Wget command on the URL from within a Subversion post-commit hook. So: every time someone commits a change to your source code repository, a build will be performed automatically. In this way we eliminate the wasteful polling of the Subversion repository by Hudson itself.

Let’s go ahead and set up the post-commit hook now. But first, go back into the testWebapp Hudson job configuration and uncheck the “Poll SCM” checkbox. Then click “Save”. Now we’re ready to configure the post commit hook. Our repository resides in /var/lib/svn/repositories/testWebApp (see above):

cd /var/lib/svn/repositories/testWebApp/hooks
cp post-commit.tmpl post-commit
chmod 755 post-commit

Now edit post-commit and ensure that the last three lines look like this:

REPOS="$1"
REV="$2"

wget http://localhost:8075/job/testWebApp/build

That’s it! From now on, every time someone commits code, the build is triggered.

Finishing Up

There’s a lot more you can do with Hudson. It supports multiple other source code control repositories, build triggers, build notifiers… even Twitter and IRC interfaces! It uses plugins to perform much of this functionality. Take a look here for the current list of plugins available. We hope this has been a useful introduction to Hudson. If you’re keen for more, there’s detailed information at the Hudson Website.

So what’s the answer to all that wasted Internet bandwidth? A local Maven proxy. The first time a developer requests a dependency, it is copied from the central repository to the local repository, which resides on the machine running the proxy. Subsequent requests by developers in the team are then fed the copy from the local repository, typically on the same local area network (LAN). That translates to quicker builds and — as long as no new dependencies are needed — no reliance on the corporate Internet link for builds.

Before You Start

This tutorial covers the setup of Maven on a Linux server, as well as the best free local proxy available today, Nexus. Nexus is available in both a GPL-licensed version (Nexus Community) and a commercially-licensed version (Nexus Pro) that provides additional functionality. We will, of course, focus on the open source version as it is sufficient for most requirements. Well, OK… also because we dig open source and free stuff!

Meat & Potatoes

Maven Setup

Let’s start off with Maven. Maven runs as a Java process, so we’ll need to make sure we have Java installed first. Download the latest JDK from OpenLogic Exchange (OLEX) or http://java.sun.com/javase/downloads/index.jsp.

You’ll be asked to select the platform and type of installation. We always download the .bin self-extracting archive, and extract it to /usr/local on the Linux host:

# cp <download_location>/jdk-6u16-linux-x64.bin /usr/local
# cd /usr/local
# sh ./jdk-6u16-linux-x64.bin

Follow the prompts and install the Java SDK. You’ll see that at the time of writing, the version of the SDK was 6u16, which will obviously change. Once everything has extracted, a browser window will open and nag you to register. This is optional — the SDK will function just fine, even if you choose not to register. Close the browser and look at the new directory under /usr/local. The JDK will be installed in a directory containing the name of the version of the software, in this instance /usr/local/jdk1.6.0_16. A good trick is to make a symbolic link for this directory to /usr/local/java. That way you can keep your $JAVA_HOME environment variable set to the symbolic link. Every time you upgrade Java, simply remove the old symlink and then relink to the new location:

# rm -f /usr/local/java

# ln -fs /usr/local/jdk1.6.0_16 /usr/local/java

If you don’t already have $JAVA_HOME set up, let’s do it now. Use your favorite editor to open /etc/profile, and add the following line near the top:

export JAVA_HOME=/usr/local/java

While we’re here, let’s also add a needed variable for Maven:

export MAVEN_HOME=/usr/local/maven

Now look a little further down in the file. You should see a line configuring the $PATH variable. We need to add to the $PATH to include the ./bin directories of both Java and Maven. It should end up looking something like this:

export PATH="$JAVA_HOME/bin:$PATH\
$MAVEN_HOME/bin:\
$SOME_OTHER_STUFF/bin"

Save /etc/profile and exit the editor. Now it’s time to install Maven. Download it from OpenLogic Exchange (OLEX) or http://maven.apache.org/download.html.

Get the latest .tar.gz distribution. In our case it was apache-maven-2.2.1-bin.tar.gz:

# cp <download_location>/apache-maven-2.2.1-bin.tar.gz /usr/local
# cd /usr/local
# tar xvzf ./apache-maven-2.2.1-bin.tar.gz

Now log out and back in again for the contents of /etc/profile to be read and for the environment variables and PATH to be updated. Verify both installations:

# java -version

java version "1.6.0_16"
Java(TM) SE Runtime Environment (build 1.6.0_16-b01)
Java HotSpot(TM) 64-Bit Server VM (build 14.2-b01, mixed mode)

#mvn -version
Apache Maven 2.2.1 (r801777; 2009-08-06 12:16:01-0700)
Java version: 1.6.0_16
Java home: /usr/local/jdk1.6.0_16/jre
Default locale: en_US, platform encoding: ISO-8859-1
OS name: "linux" version: "2.6.27.2" arch: "amd64" Family: "unix"

Good Job! Now on to the final part of our puzzle, the Nexus repository manager.

Nexus Setup

Nexus is deployed as a standard J2EE web archive or .war, as it is affectionately known. There are two download options: one as a .war, which you can install into a J2EE compliant server; or a standalone version which contains an embedded Jetty server. We’re going to focus on the standalone deployment.

Let’s start off by downloading and installing Nexus:

# cd /usr/local

# wget http://nexus.sonatype.org/downloads/nexus-webapp-1.3.6-bundle.tar.gz

# tar xvzf nexus-webapp-1.3.6-bundle.tar.gz

# ln -fs nexus-webapp-1.3.6 nexus

# cd nexus

# ls ./bin/jsw/

This will show you a list of directories for the supported architectures. In this case we’re running Linux x86-64, so to start the server we type:

#  ./bin/jsw/linux-x86-64/nexus start

You can install Nexus as a Linux service, too. Look for the link to the official documentation at the end of this article for details. To follow the log of the starting up server:

# tail -f logs/wrapper.log

If all runs correctly and you see no ominous-looking error messages, you should now have the proxy up and running. But we still have to tell Maven to look at the repository, instead of at the default central Maven servers. We do this by editing settings.xml, which resides in the .m2 directory under your home directory.

<settings>
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/nexus/content/groups/public</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>nexus</id>
      <!--Enable snapshots for the built in central repo to direct -->
      <!--all requests to nexus via the mirror -->
      <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <!--make the profile active all the time -->
    <activeProfile>nexus</activeProfile>
  </activeProfiles>
</settings>

Remember that each of the developers in your organization will have to do this on their local machines, but replace localhost in http://localhost:8081/nexus/content/groups/public with the name or IP address of your repository server.

We’re almost there. We still have to tell the repository proxy exactly what it has to proxy! For this task, Nexus has a really cool web-based interface for us to use. Fire up a browser on the machine and point it to http://localhost:8081/nexus.

Above: The Nexus Welcome Screen

Click on the Log In link at the top right hand side, and log in as admin with the password you configured during the setup process.

Above: The Repository View

Your screen may look slightly different. The Repository Path column will reflect either localhost, or the name of your server if you are administering from a remote machine. The next step is to download the Lucene indexes for all of the “proxy” pre-configured repositories. For example, click on the “Maven Central” proxy and select the Configuration tab below. Change “Download Remote Indexes” to True, and then click Save.

Above: Enabling Download of Remote Indexes

Then right-click on the same proxy, and select Re-Index. Repeat the process for each of the proxies.

Finishing Up

Well done! You now have a functioning proxy that will start building a repository as you use it from your Maven project builds. If something doesn’t work, or you’re confused about some of the Nexus functionality, Sonatype has extremely good online documentation at http://www.sonatype.com/books/nexus-book/reference/index.html, including instructions on how to install Nexus as a service. This is definitely worth doing. You can also add periodic tasks to download and re-index the proxies.

At this point, you should aim to become more familiar with the administration interface and understand all of its functionality. Reference the documentation and examine the system logs for any potential problems.

All your production applications should be under critical care with monitoring systems that continually look at key statistics and life signs. Thus, if an application becomes unresponsive, you just need to glance at the monitor on your office wall to see the statistics for your environment.

But what if somehow you find yourself in a position where you have a critical problem with an application but don’t have any monitoring infrastructure? How can you quickly check the following vital signs?

1. Pulse and respiration (data source usage, how many threads are used by HTTP, and AJP connector)
2. ID information (check server information like JVM, OS, and JBoss versions)
3. Signs of shock (high CPU usage, which threads took the most time on the server, and what threads are currently doing)

Before You Start

Ideally, you should never be in this position with production systems. There should always be some type of monitoring infrastructure in place to help you respond to these types of problems. Only development—and sometimes functional testing QA environments—should be routinely setup without monitoring in place. Monitoring is an essential part of production environments as well as very useful feature to have in load testing environments.

Having said that, if you’re experiencing application problems and don’t have monitoring in place, you’d undoubtedly prefer solutions to lectures about best practices that haven’t been followed. So, let’s cut to the chase and show one possible solution.

Meat & Potatoes

In most situations you should have a monitoring system setup to look at all the information covered below. This article is written for the rare situation in which you do not having a monitoring system.

If your JBoss installation is mostly unaltered from its defaults, it is likely you still have the JMX Console, Tomcat status and Admin Console enabled, and you can use them to get answers to key questions that will help you check your application’s vital signs. If you have them enabled, good for you. But if you leave them on in a production system, don’t forget to at least secure them—the mechanisms presented here should be at least secured if not disabled in production systems.

Note that there are many reasons why an application might hang, and also that there are many other things you can check (e.g. EJB pools) that are not covered here. This article is not intended to be a detailed course in JBoss and application brain surgery, but rather just a brief paramedic’s manual covering the most common signs and causes of unresponsive behavior. In other words, this article is intended to help you determine what’s wrong, not how to cure it – that might be a topic for subsequent articles.

Where Are Consoles Located?

To access the JMX Console go to http://localhost:8080/jmx-console, where localhost is your server’s name. Tomcat status is available at http://localhost:8080/status?full=true. And (if you’re using a JBoss version that includes it) the admin console is at http://localhost:8080/admin-console.

Note that there are differences between JBoss 4 and JBoss 5.1. We will first talk about methods that work in both JBoss 4 and JBoss 5, and then present a somewhat easier method that works only in JBoss 5.1.

Checking DataSource Usage

Investigating data source usage is useful when you’re unsure if you have enough data sources available for application. If you ran out of the available data source connections, your system is unresponsive because your queries are stuck.

To find statistics about data source usage, you need first to find the name of your data source. Let’s suppose that it’s named MyDataSource.

Go to the JMX console, and find the section called jboss.jca. You should see MBean there with the object name:

name=MyDataSource,service=ManagedConnectionPool

Note: There are multiple similarly named entries in the JMX console, so make sure that you use right one in the right section for the right data source!

Click on that link, and the following arguments are especially useful:

• MaxConnectionsInUseCount – displays the maximum number of connections that have ever been used since the server started or the data source was deployed.
• InUseConnectionCount – displays the number of connections currently used.
• MaxSize – displays the maximum number of connections available in the pool.

Another interesting operation here is listStatistics(). The example below shows the listing for one data source:

Checking Connector Thread Usage

Checking connector thread usage is useful when you want to find out how many of the available request threads are used. If all connector threads are blocked, your incoming requests are waiting on the current requests to proceed before their processing can be started.

To find statistics about connector usage, the best way is to look at http://localhost:8080/status?full=true. This will give you the following statistics:

• Max threads – displays the max number of threads the connector can spawn.
• Current thread busy – indicates how many threads are currently used by application users.

There are many other useful things available here, including a list of all currently-deployed applications and per-servlet statistics.

Be sure that you are looking at the statistics for the right connector for your setup – AJP connector if you are using AJP (e.g. setup with Apache HTTPD, mod_jk, and JBoss) or HTTP connector if your HTTP requests go directly to JBoss. The default configuration has AJP connector listening on port 8009 and HTTP connector on port 8080.

The picture below shows statistics for the HTTP connector on a recently-started server with only one user:

Obtaining Server Information

Server information is useful when your questions are:

• How do I get the thread dump?
• What’s the cumulative time spent in my threads?
• Which JVM, OS, and JBoss versions are used?
• How was the server configured? Which configuration (e.g., all, default, or minimal) am I working with?

This line of questioning is helpful to collect basic version information for the software you are using, as well as data about what is your server is currently doing.

You probably know the versions and configuration if you were the person who installed the system, and this information is always available in the JBoss boot.log file. You can also double-check this information with only browser access by finding the following three entries in the jboss.system section of the JMX Console.

These three beans provide answers to all of the questions listed above:

• Server – provides information about the version of JBoss server in use.
• ServerConfig – provides information about the server configuration in use.
• ServerInfo – provides information about the JVM and OS version you are using to run the server. Additionally, the listThreadCpuUtilization() method that you can call from this screen provides you with information about the CPU usage of your threads, and listThreadDump() allows you to execute a thread dump.

Is CPU Usage Going Crazy?

If your CPU usage is stuck at 100% all the time, it might be an indication of multiple problems such as pooling when you shouldn’t, memory leaks, and CPU-intensive code.

A thread dump can help you detect pooling or infinite loop types of problems. Do multiple thread dumps and compare the results to determine if you’re still stuck in the same place on some threads. If these threads have high CPU usage as well, they’re doubly suspicious. Both of these can be checked in the SystemInfo bean, as discussed in the previous section.

Memory leaks are slightly more complex. For additional details on fixing memory leaks please see the tutorial, How to Fix Memory Leaks in Java.

What About JBoss 5?

All of the techniques covered so far apply to both JBoss 4 and JBoss 5, but the JMX Console is somewhat intimidating and may provide the impression of a “big, difficult to navigate pile of MBeans.” JBoss 5.1 comes to the rescue here with an admin console that delivers a more user-friendly way of obtaining important information.

You can access the JBoss 5.1 admin console at http://localhost:8080/admin-console. All of the previously-mentioned information is readily available within the admin console. Look at the tree on the left side.

At the root of the tree you can get information about the OS version.

To get information about the JBoss version and configuration, click on the server in the left side tree view (e.g., JBoss AS 5, which is the default entry in the tree).

Information about the data source is located under JBossAS Servers/YourServer/Resources/Datasources in the tree on the left side. Find your data source, and then look at both the Summary and Metrics panels on the right side. The example above shows the DefaultDS data source, but your data source is probably different. Be sure to look at statistics for your own data source—not, for example, of DefaultDS!

To find connector statistics, look in the tree on the left side under JBossAS Servers/YourServer/Resources/JBoss Web/Connectors.

Can I Get This Information From A Command Line?

If you prefer to work from a command line, you can get the information covered above by using the twiddle.sh command line utility located in the $JBOSS_HOME/bin. The names of the MBeans that you should use in twiddle.sh are the same as the names of the MBeans you are using in JMX Console.

If Something is Maxed, I Just Increase It, Right?

Sometimes, but not always. A lot depends on the situation. What to do in each situation involves some degree of “it depends” and may be the subject of future articles.

Finishing Up

What if you don’t have monitoring installed, can’t get monitoring information from any application, and your consoles and twiddle.sh don’t work? Or if all of the vital signs covered above look normal but you are still stuck with a comatose application? Well, in this case there’s very little that JBoss paramedic techniques can do to help, and you might need to perform a little exploratory surgery to get more information.

You have couple of options here:

• You might try to dig out the information yourself (as a hint, you can change log levels in JBoss for a lot of things without necessarily needing to restart).
• You might reproduce the problem with more monitoring in place, and then try to dig out additional information.
• You might look at additional places that are outside of the scope of this article (e.g., EJB pools, JMS behavior, etc.).
• If all else fails, most JBoss consultants who are worth their salt should be able to do all of the above for you and have at least few more tricks that apply to your specific situation and are not mentioned in article.

References / For More Info

The JBoss Group: “JBoss 4.0 – The Official Guide”, Sams Publishing, April 30, 2005, ISBN 978-0672326486

Javid Jamae, Peter Johnson: “JBoss in Action: Configuring the JBoss Application Server”, Manning Publications, January 28, 2009, ISBN 978-1933988023

http://www.jboss.org/community/wiki/SecureTheJmxConsole

http://www.jboss.org/community/wiki/AccessControlForJMXConsole

Before You Start

This article assumes that you have Red Hat/CentOS Linux with a proper build environment setup. If you do not have GCC installed you can get this with all the required packages like this:

yum groupinstall “Development Libraries”

You should now be ready to install Apache!

Meat & Potatoes

When we install Apache HTTP Server either for ourselves a client — small or large — we follow a “standard” configuration setup that’s very easy to build on later. For the most part we use CentOS or Red Hat Enterprise edition servers, but these steps should work on any Unix system. This might not be true for AIX, which requires a little more hand-holding to make sure the compiler is installed correctly.

The steps we’ll cover in this article are:

• Download the source code for the latest version of Apache (currently 2.2.11) from OpenLogic Exchange (OLEX) or the Apache project website.
• Execute the configure, make, and make install installation steps (with a few custom switches).
• Setup the httpd.conf and associated files.
• Start your newly built Apache server.
• Done!

Download Apache

The first step is to download the Apache source code, not binaries or RPMs. We believe that using the source code gives the best performing, most flexible installation of Apache. If you follow a few simple steps the actual “installation” procedure is not difficult, and you’ll have a good foundation to add or remove features later.

To download the source source code, go to OpenLogic Exchange (OLEX) or the Apache downloads site and look for the latest ZIP, TGZ, or BZ2 file (currently version 2.2.11).

Compiling/Installing the Source for Apache

We like to keep our source downloads in ~/Software/ so it’s easy go back and re-compile and re-install the binaries if we need to add a module or two. With the source saved under ~/Software/httpd-2.2.11, compile Apache HTTP Server with the following configure string:

[root@coco ~]# cd ~/Software/httpd-2.2.11
[root@coco httpd-2.2.11]# "./configure"
"--enable-ssl"
"--enable-proxy"
"--enable-proxy-balancer"
"--enable-rewrite"
"--enable-headers"
"--enable-deflate"
"--enable-cache"
"--enable-expires"
"--enable-mem-cache"
"--enable-disk-cache"
"--enable-file-cache"
"--with-mpm=worker"
"--disable-cgi --disable-asis"
"--disable-autoindex"
"--disable-userdir"

Here’s a brief explanation of the configuration options shown above:

• enable-ssl: This will allow you to enable a secure port later.
• enable-proxy/enable-proxy-balancer: This will setup a connection to a back-end server like Tomcat or Mongrel
• enable-rewrite: We’re always going to need rewrite rules in the config file.
• enable-headers: We need this to enable monitoring of the server, and for mod_proxy we need to manipulate the header.
• enable-deflate: Enables the old gzip module, which will allow us to setup some content to be compressed with gzip.
• enable-cache/expires/mem-cache/disk-cache/file-cache: These are all included so we can enable the expires module.
• with-mpm=worker: We’re choosing to use the worker MPM as the default since most servers we work with have more than one CPU. Use the prefork MPM if you’re working on a server that has only one CPU.

Next, run the following to install Apache HTTP Server:

[root@coco httpd-2.2.11]# make && make install

The Apache server should now be installed in /usr/local/apache2, which is the default installation directory. To change the Apache installation directory you’ll need to add the –prefix=/my/directory/apache2 switch to the configure string, and then run the make && make install command as shown above.

Apache Startup Script

The easiest and fastest way to start Apache is to copy /usr/local/apache2/bin/apachectl to /etc/init.d/apache. This will allow you to do /etc/init.d/apache start|stop|restart.

If you want a script that has more feedback you can use the following:

#!/bin/bash
# httpd        Startup script for the Apache HTTP Server
# chkconfig: 2345 85 15
# description: Apache is a World Wide Web server.  It is used to serve
#              HTML files and CGI.
# processname: httpd
# config: /usr/local/apache2/conf/httpd.conf
# pidfile: /var/run/apache2.pid

# Source function library.
. /etc/rc.d/init.d/functions

# Start httpd in the C locale by default.
HTTPD_LANG=${HTTPD_LANG-"C"}

# This will prevent initlog from swallowing up a pass-phrase prompt if
# mod_ssl needs a pass-phrase from the user.
INITLOG_ARGS=""

# Path to the apachectl script, server binary, and short-form for messages.
apachectl=/usr/local/apache2/bin/apachectl
httpd=${HTTPD-/usr/local/apache2/bin/httpd}
prog=httpd
pidfile=${PIDFILE-/var/run/apache2.pid}
lockfile=${LOCKFILE-/var/lock/subsys/apache2}
RETVAL=0

start() {
 echo -n $"Starting $prog: "
 LANG=$HTTPD_LANG daemon $httpd $OPTIONS
 RETVAL=$?
 echo
 [ $RETVAL = 0 ] && touch ${lockfile}
 return $RETVAL
}
stop() {
 echo -n $"Stopping $prog: "
 killproc $httpd
 RETVAL=$?
 echo
 [ $RETVAL = 0 ] && rm -f ${lockfile} ${pidfile}
}
reload() {
 echo -n $"Reloading $prog: "
 if ! LANG=$HTTPD_LANG $httpd $OPTIONS -t >&/dev/null; then
 RETVAL=$?
 echo $"not reloading due to configuration syntax error"
 failure $"not reloading $httpd due to configuration syntax error"
 else
 killproc $httpd -HUP
 RETVAL=$?
 fi
 echo
}

# See how we were called.
case "$1" in
 start)
 start
 ;;
 stop)
 stop
 ;;
 status)
 status $httpd
 RETVAL=$?
 ;;
 restart)
 stop
 start
 ;;
 condrestart)
 if [ -f ${pidfile} ] ; then
 stop
 start
 fi
 ;;
 reload)
 reload
 ;;
 graceful|help|configtest|fullstatus)
 $apachectl $@
 RETVAL=$?
 ;;
 *)
 echo $"Usage: $prog {start|stop|restart|condrestart|reload|status|fullstatus|graceful|help|configtest}"
 exit 1
esac

exit $RETVAL

Apache configuration file

The main configuration file we use as a template for Apache servers has a few different sections that are important to understand.

# =================================================
# Basic Settings
# =================================================
ServerName %{SERVER_NAME}
ServerRoot "/usr/local/apache2"
PidFile "/var/run/apache2.pid"
# =================================================
# Performance Settings
# =================================================
Timeout 30
KeepAlive On
MaxKeepAliveRequests 500
KeepAliveTimeout 2
<IfModule mpm_prefork_module>
 StartServers            1
 MinSpareServers         1
 MaxSpareServers         10
 MaxClients              25
 MaxRequestsPerChild     1000
</IfModule>
<IfModule mpm_worker_module>
 ServerLimit             16
 StartServers             2
 MaxClients              40
 MinSpareThreads          5
 MaxSpareThreads         20
 ThreadsPerChild         20
 MaxRequestsPerChild   5000
</IfModule>

The Basic Settings section just defines the root directory of Apache, but the Performance Settings section has a few noteworthy options. We have a Timeout of 30 seconds, which is enough for most setups (the default of 300 is way too long). We enable KeepAlive, but the KeepAlive timeout is only 2 seconds. This allows each user to get their own connection, but the connection will close as soon as they download the page they requested (you can play with this timeout, but you’ll most likely want to have it set somewhere in the 1-5 sec range). Next, we setup prefork and worker based on the number of CPUs that are installed on the Apache server.

# =================================================
# General Settings
# =================================================
Listen 80
# Listen 443
User www
Group www
ServerAdmin webmaster@openlogic.com
UseCanonicalName Off
ServerTokens Prod
ServerSignature Off
HostnameLookups Off
ExtendedStatus On
# =================================================
# Modules
# =================================================
#LoadModule dummy_module /usr/lib/apache2/modules/mod_dummy.so

In the General Settings section we set Listen to port 80, but we also have port 443 as an option to choose from (we’ll show you how to setup a https/SSL/secure virtual host later). User and Group are set to the www user, which is a system user (note that on Red Hat you create a system user with the -r switch adduser -r www). We don’t want the server to look up hostname or show a signature to our users, so those options are disabled. The ExtendedStatus option is enabled for monitoring reasons. And in the Modules section, the dummy module is there in case we want to install PHP later on.

# =================================================
# Access Control
# =================================================
<Directory />
 Options FollowSymLinks
 AllowOverride None
 Order deny,allow
 Deny from all
</Directory>
<DirectoryMatch "^/.*/.svn/">
 ErrorDocument 403 /404.html
 Order allow,deny
 Deny from all
 Satisfy All
</DirectoryMatch>
<FilesMatch "^.ht">
 Order allow,deny
 Deny from all
 Satisfy All
</FilesMatch>
# =================================================
# MIME Encoding
# =================================================
DefaultType text/plain
TypesConfig conf/mime.types
AddType application/x-compress .Z
AddType application/x-gzip .gz .tgz
AddType application/x-x509-ca-cert .crt
AddType application/x-pkcs7-crl    .crl

Needless to say, the Access Control section contains some important options. Deny from all makes sure we have to allow access to any directory that’s used in the Apache configuration. Then, we make sure that users don’t have access to .svn directories or .ht files. In the MIME Encoding section we have a minimal mime.type setup for the deflate and SSL modules.

# =================================================
# Logs
# =================================================
LogLevel warn
LogFormat "%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"" combined
ErrorLog /usr/local/apache2/logs/error_log
# Mark requests for the robots.txt file
SetEnvIf Request_URI "^/robots.txt$" dontlog
SetEnvIf Request_URI "^/monit/token$" dontlog
# =================================================
# SSL Configuration
# =================================================
SSLPassPhraseDialog  builtin
SSLSessionCache        shmcb:/usr/local/apache2/logs/ssl_scache(512000)
SSLSessionCacheTimeout  300
SSLMutex  file:/usr/local/apache2/logs/ssl_mutex
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin

Next, we setup the LogFormat for use in our virtual hosts and the server error log file. We also have two dontlog Env settings to remove the robot.txt and monit/token hits from the log. (We’ll show how this is used when we create the virtual host.) We also setup a default SSL configuration for the server.

# =================================================
# Mod Status for Monitoring
# =================================================
<VirtualHost 127.0.0.1:80>
 <Location /server-status>
 SetHandler server-status
 Order Deny,Allow
 Deny from all
 Allow from localhost
 Allow from 127.0.0.1
 </Location>
</VirtualHost>
# =================================================
# Include Extra Configs
# =================================================
Include conf/extra/httpd-myblog.com.conf

In the Mod Status for Monitoring section we get to the server monitoring setup. We start by allowing only access from localhost, and we specify that it will only listen to the 127.0.0.1 IP. This is a good setup for tools like GroundWork and Hyperic. The last line includes a virtual host configuration file. Now let’s have a look at the virtual host.

Virtual Hosts Using a Name-Based Setup

We like to configure our httpd.conf with server-wide settings while keeping it free of actual content hosting elements or mod_proxy/mod_jk configurations. In this example we have a blog that’s running on a Ruby on Rails back-end with three Thin servers listening to ports 8000-8002 (Thin an application server that can be used for RoR as an alternative to Tomcat or Mongrel).

# --------------------------------------------------------
# Always Keep the Host Header
# --------------------------------------------------------
ProxyPreserveHost On
# --------------------------------------------------------
# Rails Cluster
# --------------------------------------------------------
<Proxy balancer://rails-cluster>
  BalancerMember http://127.0.0.1:8000
  BalancerMember http://127.0.0.1:8001
  BalancerMember http://127.0.0.1:8002
</Proxy>

This setup has three servers in a proxy_balancer cluster that you can access using balancer://rails-cluster/ just as though it was one server.

# --------------------------------------------------------
# Name-Based Virtual Hosting
# --------------------------------------------------------
NameVirtualHost *:80

<VirtualHost *:80>
 DocumentRoot "/var/www/myblog.com/current/public"
 ServerName www.myblog.com
 ServerAlias myblog.com

 # -------------------------------------------------
 # Rewrite Rules
 # -------------------------------------------------
 RewriteEngine on

 # Force www.myblog.com and make sure we use a 301 HTTP code for the
 # redirect. This is a SEO must.
 RewriteCond %{HTTP_HOST}   !^www.myblog.com [NC]
 RewriteCond %{HTTP_HOST}   !^$
 RewriteRule ^/(.*)         http://www.myblog.com/$1 [L,R=301]

 # --------------------------------------------------------
 # List of URLs Not to Proxy
 # --------------------------------------------------------
 ProxyPass /system !
 ProxyPass /images !
 ProxyPass /stylesheets !
 ProxyPass /javascripts !
 ProxyPass /monit/token !
 # Send everything else to the proxy_balancer cluster of rails servers
 ProxyPass / balancer://rails-cluster/
 ProxyPassReverse / balancer://rails-cluster/

 <Directory "/var/www/myblog.com/current/public">
  Options FollowSymLinks
  AllowOverride None
  Order allow,deny
  Allow from all
 </Directory>
 # Before you restart the server you need to create the logs/myblog.com
 # directory.
 # We are also adding the dontlog environment variable here to stop
 # logging the set entries. (This is configured in your httpd.conf)
 ErrorLog  "logs/myblog.com/error_log"
 CustomLog "logs/myblog.com/access_log" combined env=!dontlog

 # --------------------------------------------------------
 # Deflate Module Configuration
 # --------------------------------------------------------
 <IfModule deflate_module>
  AddOutputFilterByType DEFLATE text/plain
  AddOutputFilterByType DEFLATE text/xml
  AddOutputFilterByType DEFLATE application/xhtml+xml
  AddOutputFilterByType DEFLATE text/css
  AddOutputFilterByType DEFLATE application/xml
  AddOutputFilterByType DEFLATE image/svg+xml
  AddOutputFilterByType DEFLATE application/rss+xml
  AddOutputFilterByType DEFLATE application/atom_xml
  AddOutputFilterByType DEFLATE application/javascript
  AddOutputFilterByType DEFLATE application/x-javascript
  AddOutputFilterByType DEFLATE application/x-httpd-php
  AddOutputFilterByType DEFLATE application/x-httpd-fastphp
  AddOutputFilterByType DEFLATE application/x-httpd-eruby
  AddOutputFilterByType DEFLATE text/html
  BrowserMatch ^Mozilla/4 gzip-only-text/html
  BrowserMatch ^Mozilla/4.0[678] no-gzip
 </IfModule>
 # =============================================
 # Configure Expires Module
 # =============================================
 <IfModule mod_expires.c>
  ExpiresActive On
  ExpiresDefault "access plus 1 seconds"
  ExpiresByType text/html "access plus 1 seconds"
  ExpiresByType image/gif "access plus 1 week"
  ExpiresByType image/jpeg "access plus 1 week"
  ExpiresByType image/png "access plus 1 week"
  ExpiresByType text/css "access plus 1 week"
  ExpiresByType text/javascript "access plus 1 week"
  ExpiresByType application/x-javascript "access plus 1 week"
  ExpiresByType text/xml "access plus 1 seconds"
 </IfModule>
</VirtualHost>

There’s a lot of information here, so lets take it step by step. First, we setup a server with the name www.myblog.com that also listens to myblog.com, but by using mod_rewrite we force everyone to www.myblog.com with a 301 redirect. Next, we setup all of the static content that we want Apache to serve from the local file system using ProxyPass with a ! to say “do not proxypass” these directories, and then we send everything else to the balancer cluster. We setup the access rights to the static directory where our content (like images, JavaScript, uploaded files, and CSS) is stored. Then, we setup the virtualhosts log file in its own directory inside the logs directory. The mod_deflate and mod_expires configurations work for most setups, but this piece needs to be monitored and tuned to your setup. We’ve seen the mod_expires setup cause problems using Rails and authentication.

Now, off to a secure.myblog.com virtual host:

<VirtualHost _default_:443>
 DocumentRoot "/var/www/myblog.com/current/public"
 ServerName secure.myblog.com
 ServerAlias www.myblog.com myblog.com
 RewriteCond %{HTTP_HOST}   !^secure.myblog.com [NC]
 RewriteCond %{HTTP_HOST}   !^$
 RewriteRule ^/(.*)         https://secure.myblog.com/$1 [L,R=301]
 # --------------------------------------------------------
 # List of URLs Not to Proxy
 # --------------------------------------------------------
 ProxyPass /system !
 ProxyPass /images !
 ProxyPass /stylesheets !
 ProxyPass /javascripts !
 ProxyPass / balancer://rails-cluster/
 ProxyPassReverse / balancer://rails-cluster/

 ErrorLog  "logs/myblog.com/error_log"
 CustomLog "logs/myblog.com/access_log" combined env=!donlog

 # --------------------------------------------------------
 # SSL Certificates
 # --------------------------------------------------------
 SSLEngine on
 SSLCertificateFile    /usr/local/apache2/ssl/secure.myblog.com.crt
 SSLCertificateKeyFile /usr/local/apache2/ssl/secure.myblog.com.key
 # --------------------------------------------------------
 # Deflate Module Configuration
 # --------------------------------------------------------
 <IfModule deflate_module>
  AddOutputFilterByType DEFLATE text/plain
  AddOutputFilterByType DEFLATE text/xml
  AddOutputFilterByType DEFLATE application/xhtml+xml
  AddOutputFilterByType DEFLATE text/css
  AddOutputFilterByType DEFLATE application/xml
  AddOutputFilterByType DEFLATE image/svg+xml
  AddOutputFilterByType DEFLATE application/rss+xml
  AddOutputFilterByType DEFLATE application/atom_xml
  AddOutputFilterByType DEFLATE application/javascript
  AddOutputFilterByType DEFLATE application/x-javascript
  AddOutputFilterByType DEFLATE application/x-httpd-php
  AddOutputFilterByType DEFLATE application/x-httpd-fastphp
  AddOutputFilterByType DEFLATE application/x-httpd-eruby
  AddOutputFilterByType DEFLATE text/html
  BrowserMatch ^Mozilla/4 gzip-only-text/html
  BrowserMatch ^Mozilla/4.0[678] no-gzip
 </IfModule>
 # =============================================
 # Configure Expires Module
 # =============================================
 <IfModule mod_expires.c>
  ExpiresActive On
  ExpiresDefault "access plus 1 seconds"
  ExpiresByType text/html "access plus 1 seconds"
  ExpiresByType image/gif "access plus 1 week"
  ExpiresByType image/jpeg "access plus 1 week"
  ExpiresByType image/png "access plus 1 week"
  ExpiresByType text/css "access plus 1 week"
  ExpiresByType text/javascript "access plus 1 week"
  ExpiresByType application/x-javascript "access plus 1 week"
  ExpiresByType text/xml "access plus 1 seconds"
 </IfModule>
 # --------------------------------------------------------
 # Document Root /
 # --------------------------------------------------------
 <Directory "/var/www/myblog.com/current/public">
  Options FollowSymLinks
  AllowOverride None
  Order allow,deny
  Allow from all
 </Directory>
 # -------------------------------------------------
 # Fixing Yet Another IE 6 Bug
 # -------------------------------------------------
 BrowserMatch ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
 # -------------------------------------------------
 # Add this to the request header so that
 # Rails puts the correct redirect in place
 # -------------------------------------------------
 RequestHeader set X_FORWARDED_PROTO 'https'
</VirtualHost>

This is very similar to the port 80 virtual host of the same name. The biggest difference is with the SSL certificates and the bottom SSL/https settings to fix issues with Mongrel/Rails and IE6. You can’t configure mod_expires and mod_deflate in the main configuration file and have the virtual host inheret the configuration, so the best solution to be dry is to put these settings in their own mod_deflate.conf and mod_expires.conf and then include the named configuration files in each virtualhosts configuration file like so:

Include conf/mod_deflate.conf
Include conf/mod_expires.conf

Finishing Up

Apache with mod_proxy rocks. After working through the above steps we have an Apache installation that is ready to be expanded to a high performance web server or proxy server, or both. We like to start with this setup and then build from here. If you need to get more concurrent clients and throughput on your Apache server, take a look at your available memory and CPU cycles and consider doing something like this:

<IfModule mpm_worker_module>
  ThreadLimit 100
  StartServers 5
  MaxClients 1000
  MinSpareThreads 100
  MaxSpareThreads 1000
  ThreadsPerChild 100
  MaxRequestsPerChild 0
</IfModule>

This is a high threads and low processes setup, and to get the number of processes that Apache will use simply divide MaxClients by ThreadPerChild. So, this gives us 10 processes each with a maximum of 100 threads, with a maximum of 1000 clients total. Depending on the server and type of content that you are serving you can load test and increase these settings if you need more than 1000 concurrent users.

We’re very big fans of mod_proxy, and we use mod_proxy_ajp in place of mod_jk every chance we get. We also talk a lot of customers into using mod_proxy over mod_jk if they’re using Apache 2.2.x.

Using this setup to include the virtual hosts that the server runs, it’s easy to add and remove new websites. It also provides a good overview of what’s running on the server.

Since you are, of course, a strong advocate of open source solutions, you do some research and discover OpenSSH and the SSH File Transfer Protocol (also know as SFTP). SFTP looks like it’s just the ticket and puts a smile on the security chief’s face. The only problem is that your server room runs on Windows and OpenSSH doesn’t. After a little more research, you find that OpenSSH does run on Windows — it just needs a little help from the Cygwin project. Now if you could just find some instructions on how to get started. This is where we come in.

Before You Start

This is a bare bones guide to getting an OpenSSH Secure Shell (SSH) and SFTP (Secure File Transfer Protocol) server running under Windows. You will need a copy of the Cygwin installer, Internet access, and an Administrator account on your Windows server. You can download the Cygwin installer (setup.exe) from cygwin.com. At the time this tutorial was published, the Cygwin installer was at version 1.5.25-15.

Please note that the basic instructions covered in this tutorial should work on most versions of Windows and have been thoroughly tested on Windows XP and Vista. We have included version-specific notes where the instructions diverged.

Meat & Potatoes

Installation

Because OpenSSH is available as an optional component of Cygwin, the easiest way to get OpenSSH running under Windows is to employ a custom Cygwin install.

1. Login to Windows using an administrator account.
2. Copy the Cygwin installer somewhere convenient (like c:\, for example).
3. Run setup.exe.

   
   Cygwin installation type

4. Choose “Install from Internet”.
5. Select a directory for the installed Cygwin files (the “Root Directory”). The default c:\cygwin will work fine. Make sure “Install For” is set to “All Users” and “Default Text File Type” is set to “Unix/binary”.

   
   Cygwin install location

6. Select a directory for the downloaded installation files (the “Local Package Directory”). It’s better if this is not the same as the Root Directory. Something like c:\cygwin_packages works well.

   
   Cygwin packages location

7. For the Internet connection, “Direct Connection” will probably work. If not, check with your network administrator to see what’s most appropriate.

   
   Cygwin connection type

8. The download sites are mirrors of the central Cygwin package repository and should have essentially identical content. Choosing a site in your region will likely result in speedier downloads.

   
   Cygwin download site

9. Once the installer has downloaded and displayed the list of packages available on the repository, click on the “View” button until the text to the right of the button says “Full”. In the list of packages, scroll down until you see a package called “openssh: The OpenSSH server and client programs” in the Package column. Under the New column, click on the word “Skip”. This should display a version number for the installable OpenSSH package. Note that this may change the status on other packages, from “Skip” to a version. Don’t change those entries! They’re packages upon which OpenSSH depends.

   
   Cygwin OpenSSH package selection

10. The next screen will begin the installation process. Installation will take some time and may be a good opportunity to take a coffee break (or two).
11. Once the installation is complete, you can choose whether or not to add Cygwin shortcuts to the Start menu or Desktop.
12. Now launch the Cygwin shell (this is similar to a DOS/command window) by clicking on a shortcut (if you created one during the installation), or by running c:\cygwin\Cygwin.bat.

Vista vs. XP Note: on Windows XP you can simply run the Cygwin.bat. On Vista, you’ll need to run Cygwin.bat as an administrator.

13. On XP: At the prompt, run the following commands:
    export CYGWIN='ntsec tty'
chmod +rw /etc/group
chmod +rw /etc/passwd
chmod 0755 /var
ssh-host-config -y
net start sshd

    On Vista: At the prompt, run the following commands:
    export CYGWIN='ntsec tty'
chmod +rw /etc/group
chmod +rw /etc/passwd
chmod 0755 /var
ssh-host-config
    Answer yes to each question except “Do you want to use a different name?” and “Create new privileged user account ‘cyg_server’?” The answer to both of these is no.
    net start sshd

    This will configure, install and start the SSH/SFTP server as a Windows service.

14. Synchronize Cygwin user information with your Windows users by running:
    mkpasswd -cl > /etc/password
mkgroup --local > /etc/group
15. You can test the server by connecting from another system using an SFTP client such as FileZilla or an SSH client such as PuTTY.

Note: The default configuration we’ve gone through uses port 22 for SSH connections. You will need to open this port in your firewall in order for the SSH server to work.

Configuring A User’s Home Directory

For most Windows users and administrators, a user’s home directory is c:\Documents and Settings\[user name]. However, under Cygwin and OpenSSH, when remote users log in they may be surprised to find their (Cygwin) home is under c:\cygwin\home\[user name]. Fortunately, changing the Cygwin/OpenSSH behavior to match Windows standard behavior more closely is pretty straightforward, provided you understand the differences in the path conventions for Windows and Cygwin.

Translating Paths From Cygwin to Windows and Back

Since Cygwin is a Linux/Unix emulation that runs on top of Windows, the Cygwin shell does some things quite differently from Windows or a DOS command shell. Most notably, the paths in Cygwin follow a different, Linux-like convention.

Under Linux (and Cygwin), the file system has a single top level called the root and written “/”. The path delimiters are slashes, so, for example, the path to a directory called user inside a directory called home would be “/home/user”.

Windows, of course, supports multiple top levels on the file system: c:\, d:\, e:\ etc. The path delimiters are back-slashes and a similar path on the c drive would be “c:\home\user”.

In order for Cygwin to let Linux applications understand path information, Cygwin paths follow the Linux convention. However, the root directory in Cygwin points to the Windows directory in which Cygwin was installed.

To shoehorn the Windows path information in under the Linux convention, Cygwin puts the drive letters under a “cygdrive” directory. So, the path to the file “c:\home\user\myfile.txt” (Windows-speak) in Cygwin is “/cygdrive/c/home/user/myfile.txt”. The Cygwin path for something on, say, the g:\ drive, would be “/cygdrive/g/…”

Some general path examples for Windows:

Note the escaped space in the Cygwin path for the fourth example.

Default Directory for Users

Here’s why we need all this path information: when using the mkpasswd command to create Cygwin user accounts from local Windows user accounts, the user’s (Cygwin) home directory will default to “/home/[username]” (Cygwin path).

When that user logs in remotely through SFTP, he or she will start in that home directory; so in order to change the starting point for an SFTP session, the home directory setting for the user will need to be updated.

To change this, open the file /etc/passwd in a text editor that understands how to read Unix line endings.

Warning: Notepad doesn’t read Unix files correctly. Wordpad does, but if you use Wordpad, be very careful to save the passwd file in a text format. Saving in any non-text format will break the file which will have unfortunate effects on Cygwin.

Each line in the file corresponds to the Cygwin settings for a particular user. The entries are separated by colons, “:”. There are seven entries for each user:

1. Username.
2. Password: actually a placeholder.
3. User ID (UID): a unique number assigned to each users.
4. Group ID (GID): the unique number assigned to the user’s primary group.
5. User ID Information: A comment field, normally used for human readable information about a user.
6. Home Directory: the path of the user’s home directory.
7. User’s Default Shell: the path to the shell executable. In Cygwin, this is almost always /bin/bash.

Change the 6th field to the path you’d like as the SFTP entry point for each user. Note that this must be a Cygwin-style path, for example: /cygdrive/c/Documents\ and\ Settings/[user name].

Once the service has been restarted, the new home directories will take effect.

Finishing Up

Now that the server is set for secure transfers, the users have the right home directories, and all is right with the world, it might be a good time to mention that your big client is going to need some way of connecting with the new SFTP server. Since FTP and SFTP are entirely different under the hood, the client will need a new client. Fortunately, the open source community can help once again. WinSCP is an excellent, streamlined Windows SFTP client which also supports FTP and SCP file transfers. If you need a cross-platform client, you might also consider FileZilla, an SFTP, FTP, and FTPS client that runs on Windows, Linux, Mac OS X, the BSDs, and other platforms.

Not only is a revision control system considered an essential tool in software development, it can also be a valuable addition to any department that uses files. A revision control system allows you to archive your electronic files so that you have a copy of every saved version of a file as well as that file’s history and comments about its changes, which are recorded and can be viewed later. The ability to rollback means that any past version can become the current version. Rollback can come in mighty handy: imagine a system administrator who discovers a configuration error and needs to quickly return to a previously working configuration file, or an employee who discovers a spreadsheet error that was introduced several versions ago. How about a manager who prefers an earlier graphic in a promotional brochure? A revision control system also provides file locks, authentication mechanisms and permissions—all of which make it an ideal environment to manage multiple user edits.

Before You Start

There are two methods for providing secure (that is, encrypted) access to a Subversion repository. The first method is quite portable and easy to use, but the set-up process is fairly complex. In contrast, set-up’s a snap with our second method, but you’ll find that advantage offset by a steeper learning curve for users—as well as additional time spent installing client software. We suggest that you base your decision about which method best suits your environment on three main criteria: your operating system, the experience level of the administrator available for initial setup, and the experience level of the users who will be accessing the repository.

Method 1: Through Apache

This method is the easiest to use as well as the most portable (the Apache web server can be installed on most operating systems), but it’s also the most complex to setup. We recommend that you consider using this method if you already have an Apache web server and a system administrator experienced in WebDAV since users will not require any additional utilities or training to use the Subversion repository. They’ll be able to browse the repository using their web browser, and can use a WebDAV client to commit (upload) files to the repository. A list of WebDAV utilities includes Microsoft Office, Adobe Dreamweaver and Photoshop, Mac OSX (which has built-in support), Novell NetDrive, KDE Konqueror, and Gnome Nautilus.

Using this method also scores you some benefits provided by Apache to your Subversion repository.  You’ll take advantage of all of Apache’s authentication mechanisms as well as its logging, and you won’t need to reconfigure any firewall rules since it will use HTTPS and can take advantage of any existing caching, load balancing, or proxying servers. However, you’ll find that this method is slower than Method 2 because of the nature of the HTTP protocol.

Method 2: Through SSH

Compared to Method 1, set-up through SSH is trivial. You’ll save time, which is great—but that time will in turn be devoted to installing client software, educating your users on how to use a utility to interact with the Subversion repository, and teaching them to authenticate when they access the repository. Method 2  is better suited to BSD and Linux servers, which typically ship with an SSH server installed. Windows systems do not ship with an SSH server, which means that additional configuration will be required. Windows SSH servers are available from SSHWindows and freeSSHd.

Subversion provides a command line client that needs to be installed on each client. It might not be suitable for users familiar with a graphical environment. Fortunately, there are over a dozen free and commercial graphical clients available for Windows, Mac OS X, and Linux/BSD systems.

A Note on Certificates and Keys

If you’re using Method 1 and don’t have a certificate for Apache, instructions for generating the SSL certificate and configuring Apache for SSL can be found in the SSL FAQ. Modern browsers require user interaction to access a web server whose certificate authority is not recognized. You’ll lessen the confusion of your users by having the certificate signed by an authority from the browser’s certificate authorities list. Different browsers support different authorities, so be sure to choose a certificate authority supported by all the browsers that are in use.

If you’re using Method 2, the key pair used by the SSH server should have been generated during installation of the server. If you wish to use certificates for client authentication, you’ll find instructions for generating and distributing client keys here. This reference also describes agent forwarding, which will reduce the number of times the user has to enter their pass phrase when interacting with the Subversion repository.

Meat & Potatoes

Method 1: Configuring Subversion through Apache and WebDAV

We mentioned before that while this method is the most user-friendly, it is very complex to setup. Before beginning, it’s important that the administrator read, with attention,  the Apache configuration and WebDAV sections of the online Subversion book. The administrator will also need to be familiar with configuring Apache modules and directives.

Since the necessary steps, considerations, and gotchas are well covered in the online Subversion book, we will instead provide a checklist of the steps needed:

1. Make sure the system has Apache 2.x and Subversion installed. If installing Subversion from source, make sure Apache is already installed and include –enable-dav in the configure command.
2. Configure Apache for SSL.
3. Create the Subversion repository using svnadmin and svn import.
4. Modify httpd.conf to load the mod_dav_svn module.
5. Add a Location section to httpd.conf that points to the Subversion repository.
6. Configure the desired method of authentication.
7. Configure the desired access control.
8. Make sure Apache and Subversion permissions match up.
9. Configure MIME types for the types of files that will be saved in the repository.
10. Add a CustomLog directive.

Once Apache is configured, the administrator will want to spend time testing to ensure that authentication and access control work as expected. Testing should be performed from each operating system used by clients, as well as from each WebDAV application to be employed by end-users.

The Subversion book also explains how to configure write-through proxying, which allows one repository to be hosted on multiple Apache servers in a master/slave replication scenario. This allows several offices or geographically separated departments to use the same Subversion repository.

Method 2: Configuring Subversion through SSH

For this method, it’s best that the administrator be familiar with Unix permissions and the creation of users/groups, as well as the basic SSH concepts involved in configuring a Subversion repository to use SSH. When using Subversion through an SSH connection, access control is limited to Unix-style permissions and the umask, which sets the default permissions for new files.

You’ll need to create a user account and group for the Subversion server to employ as well as decide on a umask that is appropriate for the repository, as the default umask for a user account does not typically allow group write access. The default umask can be changed in the Subversion user’s shell file, as described in this how-to (which also explains how to create a wrapper script if you’re unsure of the umask compiled into your Subversion binary). Finally, every user requiring access to the repository will need a user account on the server so they can login over SSH. Make sure each user is added to the Subversion group so they have write access to the repository.

Once the repository and user accounts have been created, providing access to the repository through SSH is a simple matter of starting svnserve (the Subversion server) in tunnel mode, as seen in this how-to. When clients wish to connect, either through the command line or a GUI client, they preface the server address and repository path with “svn+ssh” just like in this example:

svn+ssh://192.168.1.100/home/svn/repository/sharedfiles

The administrator should test that users can connect and that permissions work as expected.  Users who are comfortable with command line connections can be provided with a cheat sheet of commonly used svn commands. An example cheat sheet includes:

svn checkout     #use this the first time you connect to download a working copy of
                 #the repository
svn update       #use this command EVERY time you access the repository and before
                 #making changes to ensure you have the latest copies of files and
                 #to avoid conflicts
svn add          #use this after you create a new file to add to the repository
svn commit       #use this whenever you make changes to a file
svn delete       #use this command to delete a file NEVER use rm
svn log          #use this to see the latest changes

A complete listing of all svn commands and their use is available in the Subversion Complete Reference.

In environments where users prefer a graphical utility, the administrator should spend some time trying out the various graphical clients in order to become familiar with their features. No graphical client provides access to every svn command, but any client should provide access to the most commonly used commands listed above. Being aware of the available features ahead of time will make educating users much easier and encourage them to actually use the repository.

Two examples of popular graphic clients are seen below:

TortoiseSVN Adds Menu Items to Windows Explorer

RapidSVN on Windows

Finishing Up

Regardless of the method implemented, education is key. Users will need to invest some time becoming familiar with the basic work cycle and selecting a client with which they’re comfortable accessing the repository and making changes. But soon enough your investment in user education will pay off in increased productivity and ease of collaboration, and users will wonder how they ever lived without a secure repository!

Sound familiar? If so, you may have a case of memory leak induced insomnia, but fortunately we’ve got a cure for what ails you. This tutorial will teach you everything you need to know to ease your suffering, including what memory leaks are, why they happen, and how to diagnose and fix ‘em.

In this article we’ll focus on techniques that will enable you to address memory leaks with any commercial or free/open source memory profiler; we’re not here to recommend one tool over another. After all, the most important thing is that you fix the problem and get some rest, not the tool you use to get it done.

Before You Start

Ever heard the story about how Java has “automatic memory management”—you know, the one that someone in marketing upgraded to an epic tale about how you’ll never have to worry about memory leaks ever again? As is often the case, the truth is more complex than the marketing department made it out to be. While it’s true that Java’s garbage collector (GC) helps to eliminate the most common memory leak issues from applications, it is unfortunately still possible to experience memory leaks in Java. However, they happen a lot less often than they used to in the C or C++ days.

Many people believe that black magic and complex tools are required to fix memory leaks. This undeserved reputation is caused by the lack of good explanations of what they are and what to do when you encounter them. But with the proper tools and knowledge to fix memory leaks, they aren’t nearly as intimidating.

Methodology

In this article we’ll cover everything from memory leak basics to analyzing heap dumps, so—whether you’re an experienced Java developer or encountering Java memory leaks for the first time—you’ll be better prepared to deal with memory leaks by the time you reach the conclusion. We won’t outline a series of steps, like “do ABC with commercial tool XYZ and don’t ask why,” as that approach doesn’t work and implies that remedies are more complex then they really are. Instead, we’ll give you the background information necessary to address memory leaks, with emphasis placed on particular steps you’ll need to execute. Similarly, we’ll assume that you can learn on your own how to use the memory profiler of your choice; what’s missing is an understanding of what the tool is trying to do and why, so that will be the focus of this article.

Java will be used for all examples, so all information in this article directly applies to Java applications running standalone or as a part of J2EE/JEE/Tomcat-based application server. But remember, although our primary focus is on Java, most of the process of diagnosing and fixing memory leaks described herein applies to other languages with garbage collectors. So even if you’re using Ruby, C#, or Python, there should be something for you in this article.

What Are Memory Leaks?

Let’s start by describing how memory leaks happen in Java. Java implements automatic garbage collection (GC), and once you stop using an object you can depend on the garbage collector to collect it. While additional details of the collection process are important when tuning GC performance, for the sole purpose of fixing a memory leak we can safely ignore them.

When is memory eligible for GC? Let’s take a look at an example:

We don’t have to do anything special to make an object eligible for GC—we just eliminate any references to it, and it “magically” disappears and stops using memory. That’s why we say that Java performs “automatic” GC.

Why “eligible” for GC? Because objects are not collected immediately. GC is not instantaneous and comes with some performance impacts. Consequently, Java doesn’t immediately collect every object that is eligible for collection; it typically postpones collection until a more convenient time later on. The way to think about GC in Java is that it’s a “lazy bachelor” that hates taking out the trash and typically postpones the process for some period of time. However, if the trash can begins to overflow, Java immediately takes it out. In other words, if memory becomes scarce, Java immediately runs GC to free memory.

Since we don’t need to do anything special in order to dispose of objects in Java, how do memory leaks happen in Java? Memory leaks occur when a program never stops using an object, thus keeping a permanent reference to it.

Let’s take a look at an example that helps illustrate this point. The following code will cause all available memory in the JVM to be exhausted:

When no more memory is remaining, an OutOfMemoryError alert will be thrown and generate an exception like this:

Exception in thread “main” java.lang.OutOfMemoryError: Java heap space at
MemoryLeakDemo.main(MemoryLeakDemo.java:14)

In the example above, we continue adding new elements to the list memoryLeakArea without ever removing them. In addition, we keep references to the memoryLeakArea, thereby preventing GC from collecting the list itself. So although there is GC available, it cannot help because we are still using memory. The more time passes the more memory we use, which in effect requires an infinite amount memory for this program to continue running.

This is an example of unbounded memory leak—the longer the program runs, the more memory it takes. So even if the memory size is increased, the application will still run out of memory at a later date.

Meat & Potatoes

Fixing Memory Leaks

As illustrated by the flowchart below, the process of fixing memory leaks is fairly simple:

Memory leaks are misunderstood creatures. Just getting an OutOfMemoryError alert doesn’t necessary mean that you’re suffering from a memory leak. So, before you dive into “fixing” the problem, you must first find out whether or not a memory leak actually exists. If a memory leak does in fact exist, the next step is to determine which objects are leaking and uncover the source of the memory leak. Then, you fix it.

We’ll skip past the initial steps and dive right into diagnosing whether or not the problem is a memory leak.

Is My Program Leaking Memory?

Not every OutOfMemoryError alert indicates that a program is suffering from a memory leak. Some programs simply need more memory to run. In other words, some OutOfMemoryError alerts are caused by the load, not by the passage of time, and as a result they indicate the need for more memory in a program rather than a memory leak.

To distinguish between a memory leak and an application that simply needs more memory, we need to look at the “peak load” concept. When program has just started no users have yet used it, and as a result it typically needs much less memory then when thousands of users are interacting with it. Thus, measuring memory usage immediately after a program starts is not the best way to gauge how much memory it needs! To measure how much memory an application needs, memory size measurements should be taken at the time of peak load—when it is most heavily used.

The graph below shows the memory usage in a healthy Java application that does not suffer from memory leaks, with the peak load occurring around 10 AM and application usage drastically decreasing at 5 PM. Naturally, the peak load on business applications often correlates with normal business hours.

The application illustrated by the chart above reaches its peak load around 10 AM and needs around 900MB of memory to run. This is normal behavior for an application suffering from no memory leaks; the difference in memory requirements throughout the day is caused solely by the user load.

Now, let’s suppose that we have a memory leak in the application. The primary characteristic of memory leaks is that memory requirements increase as a function of time, not as a function of the load. Let’s see how the application would look after running for a few days with a memory leak and the same peak user loads reached around 10 AM every day:

Because peak loads on the system are similar every morning but memory usage is growing over a period of a few days, this picture indicates a strong possibility of memory leaks. If the program eventually started suffering from OutOfMemory exceptions, it would be a very strong indication that there’s a problem with memory leaks. The picture above shows a memory leak of about 100MB per day.

Note that the key to this example is that the only thing changing is the amount of time the system is up—the system peak load doesn’t change over time. This is not the case for all businesses. For example, the peak load for a tax preparation service is seasonal, as there are likely more users on the system in April than July.

There is one special case that should be noted here: a program that needs to be restarted periodically in order to prevent it from crashing with an OutOfMemoryError alert. Imagine that on the previous graph the max memory size was 1100MB. If the program started with about 900MB of memory used, it would take about 48 hours to crash because it leaks about 100MB of memory per day. Similarly, if the max memory size was set to 1000MB, the program would crash every 24 hours. However, if the program was regularly restarted more often than this interval, it would appear that all is fine.

Regularly scheduled restarts may appear to help, but also might make “upward sloping memory use” (as shown in the previous graph) more difficult to notice because the graph is cut short before the pattern emerges. In a case like this, you’ll need to look more carefully at the memory usage, or try to increase the available memory so that it’s easier to see the pattern.

Monitoring Memory in Java

As you are already aware, you need to measure memory that is free and used inside of the JVM, not memory that the JVM process is using. In other words, the top/Task Manager/Activity Monitor will measure how much memory your Java process is using, but that’s not what you need. You need a tool that can look inside the JVM process and tell you how much memory is available for your program running inside the JVM.

In addition, keep in mind that Java GC is not a constant process—it runs in intervals. The memory usage that you see in the JVM is usually higher then what your program needs at the moment, as GC hasn’t yet run. Remember, lazy bachelors usually have some trash in their apartments waiting to be taken out.

So, what you need to investigate is not current memory usage, but rather the average usage over a long period of time. For example, if your program is currently using 100MB of memory and five seconds later it’s using 101MB, that’s not an indication of a memory leak because GC might free up memory when it eventually runs. But if your program’s memory usage increases over a long period of time under constant usage, you might have trouble on your hands.

There are a couple of options for measuring the amount of memory a program uses. The simplest one, which does not require any tools and works even with production systems, is the Verbose GC log.

Verbose GC Log

The Verbose GC log is defined when the JVM process is started. There are a couple of switches that can be used:

1. -verbose:gc — prints basic information about GC to the standard output
2. -XX:+PrintGCTimeStamps — prints the times that GC executes
3. -XX:+PrintGCDetails — prints statistics about different regions of memory in the JVM
4. -Xloggc:<file> — logs the results of GC in the given file

The following is an example of the output generated for Tomcat running in the default configuration with all of the previous switches enabled:

1.854: [GC 1.854: [DefNew: 570K->62K(576K), 0.0012355 secs] 2623K->2175K(3980K), 0.0012922 secs]
1.871: [GC 1.871: [DefNew: 574K->55K(576K), 0.0009810 secs] 2687K->2229K(3980K), 0.0010752 secs]
1.881: [GC 1.881: [DefNew: 567K->30K(576K), 0.0007417 secs] 2741K->2257K(3980K), 0.0007947 secs]
1.890: [GC 1.890: [DefNew: 542K->64K(576K), 0.0012155 secs] 2769K->2295K(3980K), 0.0012808 secs]

The most important set of numbers is located in the second column after the second -> (e.g., in the top line shown it is 2623K->2175K(3980K). These numbers indicate that as a result of GC, we are using around 2200K of memory at the end of each GC cycle.

This trace is not an indication of a memory leak—it shows a short-term trend with less then a second between samples, and that’s why we must observe long-term trends. However, if the Verbose GC log showed that the program was using around 2200K of memory after running for two days, and after running for 10 days it was using 2GB of memory (even after GC had just run), we could then conclude that there’s a memory leak.

All the information that needs to be collected in order to determine if a memory leak exists can be found in the results of the Verbose GC logs. The other memory monitoring tools we’ll cover in this article simply provide more information in a form that’s easier to interpret.

Monitoring the Java Process

The following approach works for any Java process, including standalone clients as well as application servers like JBoss and servlet containers like Tomcat. It is based on starting the Java process with JMX monitoring enabled and attaching with the JMX monitoring tools. We’ll use Tomcat in the following example.

To start Tomcat or the Java process with JMX monitoring enabled, use the following options when starting JVM:

• -Dcom.sun.management.jmxremote — enables JMX monitoring
• -Dcom.sun.management.jmxremote.port=<port> — controls the port for JMX monitoring

Note that if you’re on a production system, you’ll most likely want to secure your JVM before running it with these parameters. For that, you can specify these additional options:

• com.sun.management.jmxremote.ssl
• com.sun.management.jmxremote.authenticate

Once started, you can use JConsole or VisualVM to attach to the process. Note that later JDK 6 versions include VisualVM.

This is an example of the JConsole monitoring Tomcat. As shown in the example below, click on the Memory tab to get memory information:

Again, we’re interested in the long-term trends of heap memory usage, not trends from just a few minutes of running.

Finally, note that monitoring tools like Hyperic can typically show historical trends over longer periods of time than VisualVM or JConsole. In addition, tools like Hyperic allow for more fine-grained control over operations that are permitted by users. As a result, we recommend using monitoring tools for production systems use, while all the other tools discussed in this section are more appropriate for developers or “first aid” in the absence of the real monitoring tools.

Speed Kills

We now know how to find out whether or not a memory leak exists, and we can even determine the speed at which we’re leaking memory (e.g., 100MB per day). But are we better off with a “slow” leak (e.g., 1MB per day) or a “fast” leak (e.g., 500MB/hour)?

It depends. With a “slow” leak, it takes longer for the system to run out of memory. For example, if we have 256MB of free memory remaining at the peak load time, it can take quite a long time to run out of memory with a 1MB/day memory leak. On the other hand, a faster memory leak makes it easier to reproduce and fix the problem.

One of the best ways to quickly determine whether there’s a fast memory leak or you simply need more memory to run at the peak time is to allot more memory to the program and see what happens. If you increase the available heap in a Java program and the time between crashes increases, you are likely suffering from memory leak.

Let’s assume that we’re lucky enough to have a fast memory leak—on the order of 100MB per hour—on our hands, and that the initial memory picture looks like this:

In this example, we can expect to run out of memory after about five hours of running time.

How To Find Leaked Objects in a Fast Memory Leak

Somewhat surprisingly, it is much easier to debug large memory leaks than small memory leaks. The reason is that memory leaks present a sort of “needle in the haystack” type problem—you need to find the leaked objects amongst all the other objects in the program.

Suppose that the program we’re debugging just ran out of memory. If the program initially had 512MB of free memory and now has none, it is obvious that the leaked objects used about 512MB of memory. The figure below illustrates this example:

In this situation, half of the objects in memory have been leaked! If we randomly select an object, there’s a 50% chance that it has leaked. And as memory leaks usually consist of objects of a few classes, you can get a really good start on determining which objects are leaking memory by sorting memory usage based on aggregate memory use of all objects of the same class.

What if the ratio is less favorable (e.g., 512MB heap size, initially used memory 480MB, and 32MB of leaked objects at the end)? If you have an easy to reproduce memory leak, you can increase the heap size because an unbounded memory leak will eventually fill any amount of memory allotted to the program. So, you can increase the heap to 1GB, reproduce the memory leak, and get 544MB of leaked objects in a 1GB of heap.

If we had a way to look at the “complete picture” of memory, it would be fairly easy to pinpoint leaked objects. Fortunately, there’s a way to do exactly this: heap dump the process.

Dump me Gently

A heap dump is a list of objects in the memory of JVM as well as the content of the memory occupied by those objects. It preserves the value of any attributes of the objects, including references to other objects. In other words, a heap dump gives you a complete picture of the memory.

There are multiple tools that allow you to dump heap in a Java process:

• If you’re using JDK 6, you can use tool called jmap on any platform.
• If you’re using JDK 5, the situation is slightly more complex:
  • If you’re running UNIX (Linux, Solaris, OS X) with JDK 5 you can use jmap.
  • If you’re using JDK 5 update 14 or later, you can use the -XX:+HeapDumpOnCtrlBreak option when starting JVM, then use the CTRL+BREAK key combination on Windows (or CTRL + \ on UNIX) to dump the heap.
  • If you’re running Windows and using JDK 5 pre-update 14, you’ll soon wish you weren’t. Trying to reproduce the problem with a more recent JDK is probably the best bet here.

Some tools like VisualVM and memory profilers allow you to initiate a heap dump from the GUI, but you don’t need any fancy tools here—jmap will do just fine. As it provides the most general case, we’ll use jmap in the next example.

Before you dump heap, be sure to keep the following issues in mind:

• Programs in the JVM should be paused for the duration of the heap dump, which might take anywhere from ten seconds to several minutes. Many enterprise applications—and users of those applications—don’t take kindly to pauses that long, which may cause various timeouts to expire. So don’t try this at home or in production (unless the application is already a goner)!
• Heap dumps are saved on disk, and the files might be fairly large. A good rule is to make sure that you have at least twice the size of the physical memory free on the disk before you initiate a memory dump.

With those final words of caution out of the way, you should now be ready to run the following command:

jmap -heap:live,format=b,file=FILENAME PID

Note that the -F option, which will dump non-responsive programs, might be useful on UNIX systems, but is not available on Windows. Note also that JDK 6 includes the option +XX:+HeapDumpOnOutOfMemoryError that will dump heap whenever the OutOfMemoryError alert is encountered. This can be a useful option, but keep in mind that it has the potential to consume significant amounts of disk space.

You now have a heap dump in the file FILENAME and are ready to analyze it.

What’s In “Leaked” Memory?

With the heap dump complete, we can now take a look at the memory and find out what’s really causing the memory leak.

Suppose that objects are holding references to each other as illustrated by the picture below. For the sake of easy calculation, let’s assume that each object is 100 bytes, so that all of them together occupy 600 bytes of memory.

Now, suppose that the program holds reference to object A for a prolonged period of time. As a result, objects B, C, D, E, and F are all ineligible for garbage collection, and we have the following amount of memory leaking:

• 100 bytes for object A
• 500 bytes for objects B, C, D, E and F that are retained due to the retention of object A

So, holding reference to object A causes a memory leak of 600 bytes. The shallow heap of object A is 100 bytes (object A itself), and the retained heap of object A is 600 bytes.

Although objects A through F are all leaked, the real cause of the memory leak is the program holding reference to object A. So how can we fix the root cause of this leak? If we first identify that object F is leaked, we can follow the reference chain back through objects D, C and A to find the cause of the memory leak. However, there are some complications to this “follow the reference chain” process:

• Reference chains can be really long, so manually following them can be time consuming
• An object is sometimes retained by more then one object, and there can even be circles involved as shown in the picture below:

If we start following inbound references from object F in this example, we have to choose between following object C or object D. In addition, there’s the possibility of getting caught in a circle by repeatedly following the path between objects D, E and B. On this small diagram it’s easy to see that the root cause is holding object A, but when you’re dealing with a situation that involves hundreds of thousands of objects (as any self-respecting memory leak does) you quickly realize that manually following the reference chain be very complex and time consuming.

This is where some shortcuts can come in handy:

• If we had a tool that allowed us to play a “what would happen if I remove this reference” type of guessing game, we could run experiments that help locate the cause. For example, we could see that if we removed reference from “Cause of Leak” to A in the diagram above, objects A through F would all be freed. Some tools (like Quest’s JProbe) have this capability.
• If the memory leak is large and we have a tool that allows us to sort objects by retained heap, we’ll get an even greater head start because the objects with the largest retained heap are usually the cause of large memory leaks.

Now that we understand what memory leaks are and how they can be corrected, let’s find out how to fix them by analyzing heap dumps.

Tools for Dealing with Heap Dumps

Strictly speaking, you don’t need any tools that are not already part of the JDK. JDK ships with a tool called jhat, which you can use to inspect the heap dump. The process of fixing memory leaks is the same with all tools, and it’s our opinion that no single tool is “light years” ahead of the others when it comes to fixing memory leaks.

Although jhat will get the job done, better tools often provide a few extra helpful features:

• Present a better summary of heap statistics.
• Sort objects by retained heap. In other words, some tools can tell you the memory usage of an object and all other objects that are referenced by it, as well as list the objects referenced by other objects. This makes it much faster to diagnose the cause of a memory leak.
• Function on machines that have less memory then the size of the heap dump. For example, they’ll allow you to analyze a 16GB heap dump from your server on a machine with only 1GB of physical memory.

There are several free tools that are useful for analyzing heap dumps in Java. One that’s widely used and is even included with the later versions of the JVM 6 is VisualVM. VisualVM is nice tool that gives you just enough to resolve memory leaks, and it shows heap dumps and relations between objects in graphical form.

Feature-wise, one step above VisualVM is the Eclipse Memory Analyzer Tool (MAT), a free tool that includes a lot of additional options. Although it’s still in incubation phase as of publication of this article, MAT is free and we’ve found it to be extremely useful.

Commercial products like JProfiler, YourKit, and JProbe are also excellent tools for debugging memory leaks. These applications include a few options that go above and beyond VisualVM and MAT, but they’re certainly not necessary to successfully debug memory leaks. Unless you already have a license for one of these commercial tools, we recommend trying MAT first.

Analyzing the Heap Dump for Fast Memory Leaks

It’s usually easy to find a fast memory leak. A lot of memory is leaked, and you simply need to find the big hog that leaked all that memory.

Analyzing the heap dump is done in order to:

• Find objects that are “leaking”
• Find the root cause of the memory leak

If you have a fast memory leak and are able to reproduce it in such a way as to make the leaked objects a significant portion of the final memory picture, then determining which objects are leaked is simple because they occupy a significant portion of the memory. To determine which objects are leaked, sort the classes by total memory usage of all instances of each class. The objects near the top of the list are usually the leaked objects. Then, you can follow the reference chain to them until you find the cause of the memory leak.

A useful heuristic here is that if you sort all the objects by retained heap, you can find the objects that are likely the root cause of the memory leak. Again, an example:

If we assume that each instance of object C is 100 bytes, then holding object A resulted in a memory leak of almost 1GB! In other words, the retained heap of object A in this example is about 1GB. So, if we were investigating this memory leak, it would be fairly obvious that we should start there. Remember, the Eclipse Memory Analyzer Tool (MAT) allows you to sort the heap dump by the retained heap usage of the objects, so it would have been easy to use MAT to determine the retained heap of object A.

Slow and Small Memory Leaks

It always helps if you can easily reproduce the problem, but what if the memory leak is really small and slow? What should you do if after a few days you can reproduce only a 10MB leak in a heap that contains 2GB of objects? In situations like this, looking for the cause of the problem can feel like finding a needle in the haystack.

One solution in this case is the brute force approach—simply devote enough time looking at the objects to find the problem. While that will ultimately work, there’s another way to address the problem if you have an idea of which operations are leaking memory. If you know or suspect which operations leak memory, you can find even relatively slow memory leaks.

The secret here is to compare heap dumps, as this highlights objects that are present in one heap dump but not in another. For example, suppose that objects A, B, and C are present in the first heap dump, while objects A, B, C, D, and E are present in the second heap dump. In this case, objects D and E are the difference.

Comparing heap dumps makes it easier to find memory leaks because it effectively reduces the size of the “haystack” containing your needle. Comparing heap dumps can easily reduce the size of the objects for which you need to examine heaps from 2GBs to a few KB.

Many commercial profilers as well as Eclipse MAT can be used to compare heaps. Once you’ve selected a tool that can compare heaps, simply follow the process explained in the following diagram:

In effect, what you’re doing is creating two snapshots, one before and one after executing the use case that you know is leaking memory. That way, you significantly reduce the number of objects that you need to investigate to find leaked objects. After you find the objects that leaked, you can find the cause of the memory leak as described in the previous section.

Why perform garbage collection before taking a snapshot? Because some tools won’t automatically perform GC for you, and consequently the snapshots might include objects that are no longer reachable. Many modern tools will perform GC before taking the snapshot, but if you are unsure whether or not your tool performs full GC before taking a snapshot it is recommended that you do so yourself. That way you don’t have to worry about objects that are eligible for GC but have not yet been collected.

Among the objects that are created during the use case, some are supposed to be there because they are the result of the use case execution (e.g., we created a new customer, and that customer object should be retained), while other objects are the memory leak. However, since the only objects present in the difference between the snapshots are the ones that were created during the use case, the size of the haystack you need to look through is significantly reduced.

Practical Problems

Why do memory leaks sometimes take a long time to fix if the process is this simple? In our opinion, the main reasons are:

• There isn’t a sufficient amount of easily available information about fixing Java memory leaks. We hope this article will help improve the situation.
• It can be difficult to reliably reproduce an issue, and a lot of time is typically required to reproduce an issue before you can really start addressing it.
• People lack the right tools for the job—in particular, memory profilers. With many free profilers available and reasonably low prices for commercial profilers, there’s no reason you shouldn’t have good tools in your toolbox.
• There are a few practical issues with the use of tools and techniques that might be perceived as road blocks the first time someone tries them. We’ll address some of these issues below.

Fortunately, the practical issues most commonly encountered aren’t very difficult to solve. The most common problems are:

• You can’t load the snapshot because you don’t have enough memory in your development box. For example, this can easily happen if you have 64-bit servers with 8GB of memory allocated to the JVM. You might not have physical memory in your development box, or you might be using the 32-bit JVM on your development box, but the tool you’re using insists on loading most of the snapshot into memory. If you like the idea of having a really powerful development box, use this situation to your advantage and ask your boss for a new machine. Alternatively, try using a tool with less of an appetite for memory, like Eclipse MAT.
• You can’t increase your memory on the server to get a bigger set of leaked objects, yet you need a bigger set of leaked objects to speed up the process of finding the memory leak. This often happens with 32-bit JVMs. One option in this situation is to apply the techniques described above for finding slow memory leaks, although this approach requires a significant amount of time. Alternatively, you can try to reproduce problem on a 64-bit JVM, which will allow you to increase the memory. If the problem causing the memory leak is in your application, changing the JVM is extremely unlikely to “hide” the leak.
• The memory leak is not in objects of just one class—you’re leaking objects from thousands of classes, so it’s difficult to find leaked objects. Or, your graph of object relations is so complex that you can find the initially-leaked objects but can’t locate the cause. In either case, you’ve got quite a pickle on your hands. The only words of encouragement we can offer are that the situation will eventually improve, as the longer you track object references the better you’ll get at it. One other piece of advice: you should probably call your significant other and let him or her know that you won’t be home for dinner.
• You’re getting an OutOfMemoryError alert with a new, different format. For example, you might be looking at something like this:
  Exception in thread “pool-2-thread-1″ java.lang.OutOfMemoryError: GC overhead limit exceeded.
  This message can happen with some GC settings that limit the overhead of the GC. It often indicates a memory leak, although there are some corner cases in which problems with GC performance can cause it. The best way to distinguish the cause of this message (is it a GC misconfiguration or a memory leak?) is to examine the pattern of errors. If they happen with regularity (in other words, they’re a function of time the program is running), then it’s a memory leak. If they happen only occasionally under heavy loads and clear later (in other words, they’re not a function of running time), they might indicate a need to tweak the GC or increase available memory.
• 3rd party caching systems can be setup so that caches are allowed to expand and fill up the available memory the program doesn’t need. However, if the program no longer needs more memory, the cache automatically releases it. The point here is that in the absence of any OutOfMemoryError alerts, continually increasing memory usage does not necessary indicate a memory leak. Both “used memory grows as function of time” and “free memory eventually runs out” conditions are necessary in order to determine the presence of a memory leak.

Finishing Up

This article described the methodology and techniques necessary to fix memory leaks. These techniques are universal—they apply to any profiler, and some of them even apply to languages other than Java that use garbage collection. The information presented above should give you everything you need in order to use the tools of your choice to investigate and fix memory leaks.

The proper usage of specific tools will be discussed in future articles, which will focus primarily on free tools and problems in Java. However, if there’s enough interest we might tackle other languages as well. If you’re interested in follow-up articles related to memory leak resolution in a different environment or language, please leave a comment or contact us at docs-at-openlogic.com.

Additional Resources

The following links provide additional information on the behavior of GC in Java as well as different tools that you may find useful.

• http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html
• http://java.sun.com/j2se/1.5.0/docs/guide/management/jconsole.html
• http://java.sun.com/j2se/reference/whitepapers/memorymanagement_whitepaper.pdf
• http://java.sun.com/developer/technicalArticles/Programming/GCPortal/
• http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html
• http://www.eclipse.org/mat/
• https://visualvm.dev.java.net/
• http://www.ej-technologies.com/products/jprofiler/overview.html
• http://www.yourkit.com/
• http://www.quest.com/jprobe/
• http://java.sun.com/j2se/reference/whitepapers/memorymanagement_whitepaper.pdf
• http://java.sun.com/javase/6/docs/technotes/tools/share/jhat.html
• http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jmap.html
• http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jstat.html

Before You Start

We will use a RedHat ES 5 server for this tutorial. We’ve chosen the latest stable binary of JRuby 1.1.5 and we will use GlassFish v2. I think that’s all we need to know before we jump into the …

Meat & Potatoes

Installing JRuby

1. Download the latest JRuby release from OLEX.
2. Unzip and copy the JRuby directory to your /usr/local/ directory. (If you don’t like the /usr/local/ area but are more of a /opt sort, that’s fine, too, but this tutorial will reference /usr/local/ as the install location.)
3. Create a file /etc/profile.d/jruby.sh and add the following content:
4. Log-out and log-in to your system, this will make sure the environment for JRuby is correctly setup.
5. Test JRuby with the following command:
   export JRUBY_HOME=/usr/local/jruby
export PATH=$PATH:$JRUBY_HOME/bin
[freddy@wazi]# jruby -v
jruby 1.1.5 (ruby 1.8.6 patchlevel 114) (2008-11-03 rev 7996) [amd64-java]

That’s working great!

Install Rails

The recommended way to run these commands (known as system-level executable commands) in JRuby is to always use jruby -S.

[freddy@wazi]# jruby -S gem install rubygems-update
[freddy@wazi]# jruby -S update_rubygems
[freddy@wazi]# jruby -S gem install jruby-openssl
[freddy@wazi]# jruby -S gem install rails activerecord-jdbcmysql-adapter warbler


[freddy@wazi]# jruby -S rails -v Rails 2.2.2

We are going to use Radiant CMS for some simple testing, so let’s install and setup Radiant…

[freddy@wazi]# jruby -S gem install radiant
[freddy@wazi]# jruby -S radiant --database mysql /usr/local/wazi-radiant
[freddy@wazi]# mysqladmin create wazi-radiant_production

We are not going to set up any security for the MySQL instance; that’s a different topic altogether. For this reason, a local MySQL server in conjunction with the root user should work.

=> /usr/local/wazi-radiant/config/database.yml <=

production:
adapter: mysql
database: wazi-radiant_production
username: root
password:
host: localhost

That should do it for the configuration, now let’s bootstrap the application:

[freddy@wazi /usr/local/wazi-radiant]# jruby -S rake production db:bootstrap

This task will destroy any data in the database. Are you sure you want to
continue? [yn] y

= 1 CreateRadiantTables: migrating ==========================================Create the admin user (press enter for defaults).
Name (Administrator):
Username (admin):Password (radiant):
Select a database template:
1. Empty
2. Simple Blog
3. Styled Blog[1-3]: 3
Creating Pages....OK
Creating Layouts....OK
Creating Snippets....OKCreating Page parts....OK
Finished.

Now, let’s run a quick test to see if everything is where it should be. We will start WEBrick and open a test page:

jruby -S script/server -e production -p 4444

=> Booting WEBrick...
=> Rails application started on http://0.0.0.0:4444
=> Ctrl-C to shutdown server; call with --help for options
[2008-11-19 16:29:03] INFO  WEBrick 1.3.1
[2008-11-19 16:29:03] INFO  ruby 1.8.6 (2008-11-03) [java]
[2008-11-19 16:29:03] INFO  WEBrick::HTTPServer#start: pid=3359 port=4444

Pointing the browser to http://localhost:4444/ should now result in a nice looking blog interface, with an admin section available at http://localhost:4444/admin.

Now, let’s install and configure GlassFish so that we can deploy this application in a Java engine.

Installing GlassFish

To install and configure GlassFish, you need to have JDK v5 or JDK v6 installed on your system. For this demo we are using JDK1.6.0_02-b05.

You can download the Glassfish v2-ur1-b09d installer from OLEX here https://olex.openlogic.com/packages/glassfish. And here are the instructions for running the installer:

Make sure your JAVA_HOME is set to a JDK!

[freddy@wazi]# java -Xmx256m -jar filename.jar
[freddy@wazi]# mv glassfish /usr/local/
[freddy@wazi]# cd /usr/local/glassfish
[freddy@wazi]# chmod -R +x lib/ant/bin
[freddy@wazi]# lib/ant/bin/ant -f setup.xml
We are waiting for BUILD SUCCESSFUL

Now you can move the Glassfish directory where you would like your Glassfish installation to live. ( Like /usr/local/glassfish )

Now cd into the glassfish directory and start the server…

[freddy@wazi]# bin/asadmin start-domain

...

Domain listens on at least following ports for connections:
[8080 8181 4848 3700 3820 3920 8686 ].
Domain does not support application server clusters and other standalone instances.

You should now be able to access the GlassFish admin screen at http://localhost:4848, and the GlassFish landing page at http://localhost:8080/. The username/password for the admin console is admin/adminadmin.

We will now use Warbler to package our application into a war file, but we will need to setup the warble.rb configuration file first. First, we should create a generic configuration file for warbler. Strictly speaking, you don’t “need” a wrble.rb file, BUT it makes the process a lot easier, so we recommend it.

[freddy@wazi]# jruby -S warble config

The warble.rb file has a few issues with the Radiant gem, so we have to edit the file:

=> config/warble.rb <=

Warbler::Config.new do |config|
config.staging_dir = "tmp/war"
config.dirs = %w(config log vendor tmp)
config.gems += ["activerecord-jdbcmysql-adapter", "jruby-openssl"]
require "#{RAILS_ROOT}/config/boot"
BUILD_GEMS = %w(warbler rake rcov)
for gem in Gem.loaded_specs.values
next if BUILD_GEMS.include?(gem.name)
config.gems[gem.name] = gem.version.version
end
config.gem_dependencies = true
config.webxml.rails.env = ENV['RAILS_ENV'] || 'production'
end
[freddy@wazi /usr/local/wazi-radiant]# jruby -S warble
[freddy@wazi /usr/local/wazi-radiant]# ls *.war
wazi-radiant.war

We now have a .war file that is deployable, so let’s push that to our running GlassFish server:

[freddy@wazi /usr/local/wazi-radiant]# ../glassfish/bin/asadmin deploy --contextroot / wazi-radiant.war

Command deploy executed successfully.

Finishing Up

Now our Radiant application can be accessed via http://localhost:8080/.

This was a very high level tutorial geared to get you up and running fast using Glassfish as your production Ruby on Rails server. We used a ready-to-deploy Rails application, Radiant, that drops into this environment easily and shows something ‘real’ when the process is completed.

Before You Start

There’s some stuff you’ll need on your system:

• MacPorts installed and at version 1.6. (http://www.macports.org/install.php )
• Some diskspace.
• About 15min.

Meat & Potatoes

Installing JRuby

The latest JRuby port is 1.1.3 so that is what we will use today.

[freddy@wazi]# port list jruby
jruby           @1.1.3          lang/jruby

It’s as easy as entering:

[freddy@wazi]# sudo port install jruby
[freddy@wazi]# ruby -v
jruby 1.1.3 (ruby 1.8.6 patchlevel 114) (2008-11-17 rev 6586) [i386-java]

JRuby uses a separate area to store gems and the Ruby environment, so we will need to install the gems that are needed for our development. This includes the Rails gem.

Installing Rails and Friends

Install Rails and create a test application:

[freddy@wazi]# sudo jruby -S gem install jruby-openssl
[freddy@wazi]# sudo jruby -S gem install rails activerecord-jdbc-adapter
[freddy@wazi]# sudo jruby -S rails wazi_app

Now we need to download the latest MySQL Java (JDBC) driver from https://olex.openlogic.com/packages/mysql-connector. Copy mysql-connector-java-x.x.x-bin.jar to $JRUBY_HOME/lib (/opt/local/share/java/jruby).

Now let’s update the database.yml file to use the JDBC driver:

development:
adapter: jdbc
driver: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost/testapp_development
username: root
password:

We should also make sure the JDBC driver will load. To do this, we edit the environment.rb file with these changes:

# Bootstrap the Rails environment, frameworks, and default configuration
require File.join(File.dirname(__FILE__), 'boot')
if RUBY_PLATFORM =~ /java/
require 'rubygems'
RAILS_CONNECTION_ADAPTERS = %w(jdbc)
end

Now let’s boot the server in our JRuby environment:

[freddy@wazi]# jruby script/server
=> Booting WEBrick...
=> Rails 2.2.2 application started on http://0.0.0.0:4000
=> Ctrl-C to shutdown server; call with --help for options
[2008-11-17 16:40:34] INFO WEBrick 1.3.1
[2008-11-17 16:40:34] INFO ruby 1.8.6 (2008-11-17) [java]
[2008-11-17 16:40:34] INFO WEBrick::HTTPServer#start: pid=13484 port=4000

Installing the Glassfish gem

Having GlassFish fully installed on your development environment is not always the best thing. If you don’t need it then you don’t want either the hogging of memory, or the administration that comes with a running J2EE container, so I’m going to show you an alternative. Do this:

[freddy@wazi]# jruby -S install glassfish

Whew, wasn’t that easy! Now, let’s start the server using Glassfish rather than WEBrick:

[freddy@wazi]# jruby -S glassfish_rails
...
Nov 24, 2008 1:33:55 PM com.sun.enterprise.v3.services.impl.GrizzlyProxy start
INFO: Listening on port 3000
...
Nov 24, 2008 1:34:01 PM com.sun.enterprise.v3.server.AppServerStartup run
INFO: GlassFish v3 Prelude startup time : Felix(1813ms) startup services(6457ms) total(8270ms)

Nice job! The application is now available at http://localhost:3000/.

Finishing Up

You now have a working environment in which you can develop your Rails application, and test them on your local desktop using a J2EE (Glassfish) container. We also installed JRuby with all the required gems needed and this gives us the flexibility of either using JRuby or Ruby and/or Mongrel/Glassfish for different projects.

As an added bonus, here’s some more information about the Glassfish gem:

-c, --contextroot PATH: change the context root (default: '/')
-p, --port PORT: change server port (default: 3000)
-e, --environment ENV: change rails environment (default: development)
-n --runtimes NUMBER: Number of JRuby runtimes to crete initially
--runtimes-min NUMBER: Minimum JRuby runtimes to crete
--runtimes-max NUMBER: Maximum number of JRuby runtimes to crete
APPLICATION_PATH (optional): Path to the application to be run (default: current)

]]> http://olex.openlogic.com/wazi/2008/jruby-and-glassfish-as-a-rails-developer-environment/feed/ 2 http://olex.openlogic.com/wazi/2008/how-to-build-apache-22x-on-aix-53-platforms-part-ii-some-common-errors-and-pitfalls/ http://olex.openlogic.com/wazi/2008/how-to-build-apache-22x-on-aix-53-platforms-part-ii-some-common-errors-and-pitfalls/#comments Fri, 14 Nov 2008 15:48:14 +0000 Brad Reeves http://olex.openlogic.com/wazi/?p=1300 Purpose

Building the Apache Web server on AIX is generally a straightforward enterprise in which you:
obtain the code, run a few simple commands (configure, make, and make install) and then stop by your boss’s cube to ask if she’s got anything she’d like you to take off her plate.

You don’t know us very well yet, so we’ll be frank: we say “straightforward” with tongue firmly planted in cheek. A quick Google search on the topic will return a plethora of issues users encounter while building the code if they try anything beyond straight vanilla. In other words, if you need an install with any additional modules or capabilities, expect some issues.

We’ve already covered the vanilla installation, in the first installment of the Building Apache on AIX. This second part of the tutorial takes you beyond those basics. Before attempting any of these work arounds, we recommend that you have met all the requirements for a “basic” build.

Before You Start

Follow the setup from the first installment of this guide. Building Apache 2.2.X on AIX 5.3 platforms.

Meat & Potatoes

Common Problems

Neglecting to  clean between failed builds (or builds with numerous, particular errors)
During compilation phase of the build, if any errors are encountered, the subsequent build
must be preceded by a make clean. As Joe Biden would say “Let me repeat that”, make clean.
It is important that your build runs from start to finish without errors and that there is
not any artifacts from previous build attempts giving you false positive or false negative results.

Environment Issues
The most frequent issues with a build are ones that are encountered because the build environment
is not set up correctly. Incorrect gcc version, gcc library version, and not adding the
math library (libm.a) are the most common. Setup of these environment elements are covered in
the first installment of this guide.

Configuration options

The latest versions of Apache Web server have over 160 configuration options and flags, making for millions potential combinations. These options control exactly how the Web server is going to build and, more importantly, how it is going to run. On AIX, there are several options that we have found are either required, or particularly beneficial to complete the build.

--prefix=PATH
Setting this option is required. PATH is the exact path where the Web server will be installed and run from post compilation.

--with-included-apr
apr and apr-util are bundled with the Apache Web server source releases, and will be used without any problems in almost all circumstances. However, if apr or apr-util versions 1.0 or 1.1, are installed on your system (as is the case if you are using AIX 5.3), you must either upgrade your apr/apr-util installations to 1.2 and force the use of the bundled libraries, or have httpd use separate builds.

To use the bundled apr/apr-util sources, specify the --with-included-apr option added in version 2.2.3 of Apache Web server.

--enable-ssl=shared
If you choose to add ssl capabilities to your Web server, you must enable this option. This also means that you must have OpenSSL installed on your system. On AIX systems a typical install will litter OpenSSL elements across your file system, and this will cause issues as you compile. For instance, we have found complete or portions of OpenSSL installed in the following directories : /usr , /usr/bin, /opt/freeware/bin, /usr/include, /usr/linux. Most often, the correct OpenSSL to use is the libraries found in /usr.  To specify using this one, you must set the following options:

--with-ssl=/usr This tells the configuration step to bind to libraries found in and under /usr.

--enable-mods-shared=ssl This tells the system to create the ssl module as a shared object.

Other important configuration options include:

--enable-so: This configures apache for later installation of shared objects (modules).  Apache httpd can be built either with static, built-in modules, or be built so that modules can be stored outside of the httpd binary file, and may be compiled and added at a later time. Having the ability to add modules after the main build is accomplished using the Apache Extention Tool (apxs).  This dynamic build is enabled by the –enable-so option. The modules that are built as extentions to the main binary are called Dynamic Shared Objects (DSO).

Finally, here are a few optional modules you may include during your configuration:

Proxy Modules
--enable-proxy
--enable-proxy-ajp
--enable-proxy-balancer

Configuring Proxy

• Forward Proxy

ProxyRequests On
ProxyVia On

<Proxy *>
Order deny,allow
Deny from all
Allow from internal.example.com
</Proxy>

• Reverse Proxy

ProxyRequests Off

ProxyPass /path http://domainname.com/thing
ProxyPassReverse /path http://domainname.com/thing

• Proxy Access

<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
</Proxy>

Helper Modules
--enable-module=rewrite
--enable-module=log_referer

Common Error Messages

Openssl compilation error.
Sample error: /usr/include/openssl/pq_compat.h:1:3: error: invalid preprocessing directive #IBM_PROLOG_BEGIN_TAG

On AIX, it is not uncommon to encounter errors during compilation if ssl is enabled. This is because
IBM’s OpenSSL package contains a number of include files in /usr/include/openssl where a special “IBM Prolog” include line has been added, making the header files incompatible with gcc.
The fix is to edit pq_compat.h, and comment out any lines with IBM_PROLOG_BEGIN_TAG, as well as any associated lines with the Prolog include tag.

Linker errors
Sample error: 0711-317 ERROR: Undefined symbol: .BIO_clear_flags

On AIX, once you have satisfied the gcc requirements to build Apache two linkers will exist
on your system. Linker errors, like the one seen above, are a result of the pathing to libraries being
different for the compiler and the linker, and can be resolved by setting environment flags.

Now, on all UNIX systems there is a library path that is to be used during link phase, and runtime,
and on all UNIX systems this path is set via the LD_LIBRARY_PATH variable. All Unix systems, that is, except AIX. For this reason, we usually set the path using both the standard and the AIX variable as a safety precaution. The native AIX linker should use LIBPATH, while LD_LIBRARY_PATH will be used by the Gnu linker.

Example library path setup looks like this:

set LIBPATH=/usr/lib:/lib
set LD_LIBRARY_PATH=/usr/lib:/lib
export LIBPATH LD_LIBRARY_PATH

Finishing Up

Augmenting the basic build with additional modules will add complexity to the build process, but by following this tutorial and properly setting up your environment, most errors can be avoided. Of course, each system can have other libraries and packages installed that can cause additional error messages, or warnings. While we have built Apache on AIX many times, on many different systems, this guide does not claim to, and can’t possibly, anticipate every situation. Should you encounter other errors, please email them to us, and we’ll include them in a future revision.

We wish you good luck, and happy compiling.

Before You Start

Before customizing Firefox, avoid headaches by looking carefully at which extensions best suit your needs. You, or your IT team, should also thoroughly research the Firefox settings and create a list of those you wish to include.

Extensions

One of Firefox’s greatest strengths is its diverse collection of extensions. Extensions such as NoScript or CookieSafe can be used to secure Firefox, while AdBlock or one of its variants could help reduce unwanted traffic to ad servers. Before building a customized installer, you will need to decide which extensions best meet your needs and the needs of your users. With an eye toward security policies and customer requests, browse the Firefox Add-on Repository and download the (Firefox 3-compatible) add-ons that best meet your needs.

Settings

Firefox offers a large number of settings, many of which aren’t accessible through the standard preferences/options dialog window. To see the available options, enter “about:config” in Firefox’s location bar. This will display a list of all settings. While the list is intimidating, Mozilla publishes a reference to all of the settings. Review the  options and collect a list of settings for which you’d either like to set a custom default value or completely lock down to a specific value.

What You Will Need

Once you’ve decided what extensions and settings you’d like in your spiffy custom installer, there are a few components you’ll need.

For a custom Windows installer, grab

1. A current, standard Firefox 3 installer for Windows.
2. A current app.tag file from Mozilla’s site (copy the appropriate text from http://lxr.mozilla.org/mozilla/source/browser/installer/windows/app.tag into a text file called app.tag).
3. A 7zSD.sfx file from Mozilla’s site (download this from http://lxr.mozilla.org/mozilla/source/other-licenses/7zstub/firefox/7zSD.sfx?raw=1).
4. The 7zip command line utility (currently at http://downloads.sourceforge.net/sevenzip/7za457.zip).

For a custom Linux installer,you’ll need to

1. Grab a current standard Firefox 3 binary for Linux.
2. Have familiarity with tar and gzip.

You’ll also need copies of each extension you wish to include in the installer (the xpi files), and the list of settings and values.

Note for Mac users: I’m working on a version of this article for Firefox 3 on the Mac, but I’m still sorting out the details of repackaging a dmg file.

Meat & Potatoes

Creating Your Settings File

The settings file I’m going to describe is basically just a Javascript file with a set of calls to two Firefox-defined JS functions, defaultPref and lockPref. Unsurprisingly, the defaultPref function can be used to specify a default value for a setting and lockPref sets the value for the setting so that it cannot be changed by the user. Each has similar arguments:

function defaultPref(prefName, value)
function lockPref(prefName, value)

so, for example, you could set the default home page using

defaultPref("browser.startup.homepage","http://www.mycompany.com/portal");

or, you could require that the browser always check for updates

lockPref("app.update.enabled",true);

You can find additional information about these and other preference Javascript functions for Firefox in “MCD, Mission Control Desktop AKA AutoConfig” at the Mozilla Developer Center.

Use the list of settings you prepared to build a settings file. For the rest of the article, I’ll refer to this file as “firefox.cfg”, although you can use any name you prefer.

Note: Since the settings file is a Javascript file, there are many sophisticated and clever javascript tricks you can include, but I’m not going to cover any of them.

Making Your Extensions Manually Installable

The next step is to prepare your chosen extensions to be manually installed. For each extension,

1. Unzip the xpi file (using 7zip, WinZip, Zip-Info or your preferred tool). You’ll end up with a folder probably with the same name as the extension (for example, NoScript)
2. In the folder, find the file called install.rdf, open it in a text editor and find the <em:id> tag under the <Description> tag. This is the unique ID of the extension ({73a6fe31-595d-460b-a920-fcc0f8843232} for NoScript)
3. Change the name of the extension folder to the extension’s ID (e.g. Change the “NoScript” folder to “{73a6fe31-595d-460b-a920-fcc0f8843232}”)

On to the Installer

Now we’re ready to rebuild the installer.

Windows Installer

Let’s walk through the process for the Windows installer and then I’ll describe the somewhat simpler process on Linux.

1. The Firefox installer is basically a self-extracting 7zip archive. You can open the 3.0.3 installer into a directory called “firefox-win” using

   7za x -ofirefox-win "Firefox Setup 3.0.3.exe"

2. Copy each of the renamed extension folders into firefox-win\nonlocalized\extensions\ (assuming Windows path style). That’s all that needs to be done for a generic extension installations. If the extensions add new settings, the installer will use the default values for those settings. Those settings could also be added to the firefox.cfg file, if you needed to change them, but I won’t go into details here.
3. Create a file called firefox.cfg in firefox-win\nonlocalized\ where the firefox.exe file is located. Here’s an example firefox.cfg which provides some basic security settings (note that everything in the example config file is commented out so it can be tested without affecting any settings at all; uncomment the settings you’d like to try).
4. Open firefox-win\nonlocalized\greprefs\all.js in a text editor and add the following lines

pref('general.config.obscure_value', 0);
pref('general.config.filename', 'firefox.cfg');

This causes Firefox 3 to load the settings in the firefox.cfg file.

5. Build a new exe installer from the firefox-win folder: cd into firefox-win and execute the following commands
   1. 7za a -t7z ..\custom.7z
   2. cd ..
   3. copy /b 7zSD.sfx+app.tag+custom.7z FirefoxCustomInstall.exe

Linux Installer

When you download Firefox for Linux, instead of an installer, you’ll just have a tarball. This means you can untar it, walk through steps 2-4 in the Windows process and re-archive the directory.

Finishing Up

Distribute your newly created .exe to users and you’re set!

This is not an AIX administration guide, and any administration tasks suggested by this guide will need to be performed as a “root” user. If you’re unsure of whether or not you are a “root” user, then you should stop now, and find someone who knows for sure.

This tutorial will also assume that we’re building Apache with GCC (GNU Compiler Collection). The steps outlined here may work with other compilers, but have only been tested with GCC.

Before You Start

In order to properly prepare the system and the Apache build configuration, we need to make a checklist of where you want Apache and what use you wish to make of it.

1. Where will you install Apache? In order to compile Apache you’ll need ~250MB of free disk space in the following areas:
   • Build Directory – this is where you’ll build the code. It can be anywhere on the file system. Although many people choose to do this in their home directory, we recommend that you create a specific directory.  Something like /build in the root directory, or in a place where you have free space.
   • Prefix Directory – this is where you want Apache to be installed when you’re done. By default, Apache installs in the /usr partition.
   • Tmp Directory - It’s always a good idea to have some free space in /tmp during builds.
2. You’ll need the following tools :
   • Apache Source Code: Version 2.2.8 can be obtained here. Click on the download link.
   • GCC 4.0: GNU C compiler version 4 for AIX 5.3. You’ll find it here.
   • libgcc 4.0: the library for GCC for AIX 5.3. Go here to get it.
3. You’ll also need to install libm.a from the AIX 5.3 installation disk 1.  We recommend using “smitty installp” to accomplish this install.
4. Uncompress the Apache source code into a temporary location. We usually create a /hold/Apache-2.2.8 directory, but any directory where you have space is fine.
5. Change directory to /hold/Apache-2.2.8 ( cd /hold/Apache-2.2.8 )
6. Run the configure command with the prefix option.   ( ./configure --prefix=/usr/local/apache ). This command evaluates your system for its readiness to build Apache. You’ll notice that some things will be found, and others will not be found. As long as the configure completes without errors, you may continue the build process.

Note: Installing the RPMs (Red Hat Package Managers) for GCC should be done as the root user.

Meat & Potatoes

Building Apache

First you’ll want to uncompress the Apache source code into a temporary location. We usually create a /hold/Apache-2.2.8 directory, but any directory where you have space is fine.

This tutorial will assume that directory is /hold/Apache-2.2.8 and will assume that the answer to question 1 in the Prerequisites section above is /usr/local/apache.

1. Make the Apache project. ( make ) The make command reads the Makefile that was created in the configuration step. This will run for approximately 15 minutes. You may see some warnings, but again, as with the configuration step, if it completes without errors, it is fine.
2. Deploy the Apache Project.  ( make install )  Once more, this should be accomplished as the ‘root’ user.
3. Test the project. Change directory to /usr/local/apache/bin.  Run the Apache start-up script. (./apachectl start ) You may be warned that Apache can’t determine the server’s name, but no worries – that’s to be expected, as we have not configured Apache. The server will still start up.
4. In a web browser go to URL http://localhost.

Finishing Up

You should see the page load, and it will report “It Works!”