Thank you all.

Now in part 3 I will show how to execute Selenium tests under a Continuous Integration process with Maven, Cargo and Jenkins, and how to gather code coverage metrics for those tests using Sonar and JaCoCo.

Adding Selenium WebDriver tests to a Continuous Integration process is easy if you know how. When Maven is used for build automation and life-cycle management, having the tests executed is as easy as adding a few configuration lines to the project’s pom.xml. Actually most of what I am going to show in this post is already published in some previous posts about HtmlUnit (read them here and here) – the approach is precisely the same. No matter what tool is used to write and execute the tests as long as they run on top of JUnit.

Reasons for Having Independent Tests

If you stop to think what are the weakest points about running Selenium tests, as shown in previous posts in the series, most probably you will agree with me that there are two: the Selenium Grid should exist and the application under test should be deployed on an application server, accessible to the test nodes.

Let’s focus on the second one – Maven and Cargo will come to the rescue. Things that need to be done are:

• Configure Maven Failsafe plug-in to automate the execution of the integration tests.
• Configure Maven Cargo plug-in to automate the application server provisioning for the tests and to automate the deployment of the application under test. The application server will exist only during the Maven process (embedded runtime).
• Optionally, leverage an embedded database. This is out of the scope of this post and actually a subject for another one. In short, use Spring JDBC embedded database support (you can read about this nice feature here).

First step is useful to separate unit tests, that run without a container or database, from integration tests, that may need (or not, depending on the integration scope) an existing runtime. Second and third steps are useful to build an integration test suite that is independent from an existing runtime.

Independence is critical to ensure a smooth workflow across the development team and the continuous integration engine. If integration tests require an existing application server and database, two developers (or one developer and the CI engine) would clash if running tests at the same time. Independence is also useful to create tests that do not rely on the previous one to finish successfully. Each test may leverage its own clean database, with the input data that is required to test different code branches and achieve reasonable code coverage. Thus, no matter if a previous test failed and left the database in an inconsistent state. This state is discarded, a new input data set is loaded and thus the feedback from subsequent tests will remain meaningful.

Configuring Failsafe

Let’s start by configuring Maven Failsafe plug-in. Failsafe is no more than a fork to the well known Surefire plug-in that provides a mechanism for differentiating unit tests from integration tests.

Although there is people that prefer having integration tests in a separate Maven artifact, I prefer, if the project is not big or has a simple layout, having them in the same artifact and just differentiate both types of tests with a different name pattern.

A possible configuration would be like this:

<project...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.8.1</version>
        <configuration>
          <includes>
            <include>**/test/*TestCase.java</include>
          </includes>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>2.8.1</version>
        <configuration>
          <includes>
            <include>**/integrationtest/*IntegrationTestCase.java</include>
          </includes>
        </configuration>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>integration-test</goal>
            </goals>
          </execution>
          <execution>
            <id>verify</id>
            <goals>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

This configuration will trigger the following actions in a Maven build:

• Surefire will execute, during unit test phase (default binding), only those test classes which are located in *.test packages and which name ends with TestCase.
• Failsafe will execute, during integration-test and verify phase (defined bindings), only those test classes which are located in *.integrationtest packages and which name ends with IntegrationTestCase.

Configuring an Embedded Server with Cargo

Next step is to configure Cargo for provisioning an embedded server that will be used to host the application under test. Cargo is capable of remotely deploy artifacts to a server, or download and install one locally for the test session if we do not have one available. Cargo can also automatically start and stop the servers (both remote and local). With the appropriate bindings, the star-deploy-test-stop flow can be achieved automatically.

A possible configuration, that provisions a Tomcat 7.0.22 runtime, would be like this:

<project...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <version>1.1.4</version>
        <configuration>
          <container>
            <containerId>tomcat7x</containerId>
            <zipUrlInstaller>
              <url>http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.22/bin/apache-tomcat-7.0.22.zip</url>
            </zipUrlInstaller>
          </container>
          <configuration>
            <properties>
              <cargo.servlet.port>8180</cargo.servlet.port>
              <cargo.tomcat.ajp.port>8109</cargo.tomcat.ajp.port>
            </properties>
          </configuration>
        </configuration>
        <executions>
          <!-- start server before integration tests -->
          <execution>
            <id>start-container</id>
            <phase>pre-integration-test</phase>
            <goals>
              <goal>start</goal>
            </goals>
          </execution>
          <!-- stop server after integration tests -->
          <execution>
            <id>stop-container</id>
            <phase>post-integration-test</phase>
            <goals>
              <goal>stop</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

This configuration will trigger the following actions in a Maven build:

• Cargo start goal is bound to pre-integration-test phase. During this phase, Cargo will download a Tomcat 7.0.22 server an configure it to run on ports 8180 and 8109 (not using the default ports is a good idea to prevent clashing another server process, i.e. Jenkins). After that the application under test is deployed.
• Cargo stop goal is bound to post-integration-test phase. During this phase, that runs once Failsafe finishes executing the integration tests, Cargo will stop the Tomcat server.

At this point we can execute a Maven build up to verify phase that will run the integration tests against the application hosted in the embedded server. Obviously, the Tomcat server process listening at port 8180 should be visible from test nodes, so watch carefully firewall or proxy settings if nodes cannot connect to the application server.

Only one thing is left: we need to pass the hub and target server URLs into the JUnit processes spawned by Failsafe. If you remember from part 2, when we were to execute the tests from the IDE, we added some system properties to the launcher configuration:

-Dtest.selenium.hub.url=http://xxxxx:4444/wd/hub
-Dtest.target.server.url=http://xxxxx:8080/sdc.samples.selenium

If we proceed the same way it will not work – Failsafe does not propagates system properties to the spawned JUnit processes. To get the job done, we need to leverage the argLine parameter:

mvn verify -DargLine="
\ -Dtest.selenium.hub.url=http://xxxxx:4444/wd/hub
\ -Dtest.target.server.url=http://xxxxx:8180/sdc.samples.selenium"

Failsafe will take the argLine parameter value and propagate it to each JUnit process. The application will be packaged and deployed and tests will be executed from the nodes available in our test grid.

Configuring the Build Job in Jenkins

To configure the build job in Jenkins no special setup is needed. Just add the verify phase to the Maven goals and add Failsafe’s argLine parameter (either as a regular option or as part of MAVEN_OPTS definition):

Validate the job configuration by running it from Jenkins dashboard: integration tests should be executed and results shown in Jenkins’ build results page.

Gathering Code Coverage Metrics with Sonar and JaCoCo

At this point, gathering code coverage metrics is a simple task:

• In pom.xml, add a dependency to JaCoCo agent.
• In pom.xml, add a command line argument to Tomcat startup to attach JaCoCo agent to it.
• In pom.xml, add sonar.jacoco.itReportPath property telling Sonar where the coverage report can be found.
• In Jenkins job configuration, be sure the Sonar’s post build action is enabled.

The dependency entry is added to the project’s pom:

<project...>
  ...
  <dependencies>
    ... 
    <dependency>
      <groupId>org.jacoco</groupId>
      <artifactId>org.jacoco.agent</artifactId>
      <version>0.5.5.201112152213</version>
      <type>jar</type>
      <classifier>runtime</classifier>
      <scope>test</scope>
    </dependency>
    ...
  </dependencies>
  ...
</project>

The command line argument is added to Tomcat startup:

<project...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        ...
          <configuration>
            <properties>
              <cargo.servlet.port>8180</cargo.servlet.port>
              <cargo.tomcat.ajp.port>8109</cargo.tomcat.ajp.port>
              <cargo.jvmargs>-javaagent:${settings.localRepository}/org/jacoco/org.jacoco.agent/0.5.5.201112152213/org.jacoco.agent-0.5.5.201112152213-runtime.jar=destfile=${project.build.directory}/itest.jacoco</cargo.jvmargs>
            </properties>
          </configuration>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

JaCoCo’s code coverage report is passed into Sonar:

<project...>
  ...
  <properties>
    <sonar.jacoco.itReportPath>
      ${project.build.directory}/itest.jacoco
    </sonar.jacoco.itReportPath>
  </properties>
  ...
</project>

And finally, enable Sonar’s post build action in Jenkins job configuration page:

Once changes in configuration are done, launch the Jenkins job again and after a few minutes you should see the project analyzed in Sonar dashboard, including code coverage for Selenium integration tests. Awesome!

Conclusion

Praise for Selenium is well deserved. Selenium, through WebDriver and Grid components, provides a powerful mechanism to automate browser tests. Tests can be easily distributed across a grid allowing multi-browser, multi-OS testing. Tests can be easily created and executed within our favorite IDEs and added to a Continuous Integration process, including code coverage metrics for Selenium tests.

Selenium helps to achieve important productivity improvements. The time invested in writing an automated test is rapidly returned by the fact that no effort is needed to re-execute them. Moreover, being automated, it is likely that they will be execute more often that if they were manual, contributing to increase the quality and predictability of our software releases.

Starting with Selenium 2, the most important components from the suite are Selenium WebDriver and Selenium Grid. In part 1 I showed how easy is to setup a testing grid with multiple OS and browsers. Now in part 2 I will show how to leverage WebDriver API to create and execute tests.

A Brief History of WebDriver

WebDriver was born under Google sponsorship around 2009 as a totally separated framework from what it was Selenium at the time. WebDriver’s raison d’être was to prevent some issues that Selenium 1 and other browser test automation tools had, because of their JavaScript based approach. The sandbox model of JavaScript engines usually limits what stuff can be automated from a script, just to secure the browser and the underlying OS from malicious scripts.

WebDriver is based on different ‘drivers’, understood as components to interact as close as possible with each different browser, may it be an automation interface or a browser extension.

This approach allows better interaction with the browser, closer to how a human being would interact with it. For example, instead of changing the text on a field with JavaScript, the driver is capable of simulating key press events, exactly as it would be if a human was typing the text in the field.

In addition to that, WebDriver API is probably cleaner, simpler to use.

With all of that in mind, both communities decided to merge efforts.

Preparing the Environment

Our playground will consist of a simple web application built with JSP, JSTL, Spring Framework/MVC and Hibernate. The IDE in use is Eclipse Indigo SR1 with SpringSource plug-ins and other stuff installed. Apache Maven 2 is used for build automation and dependency management.

If using Maven, preparation is immediate, just add the dependency with selenium-java artifact:

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>2.16.1</version>
    <scope>test</scope>
</dependency>

This artifact contains the WebDriver API for Java, along with Selenium 1 API for backwards compatibility. This API exists for other languages as C#, Ruby or Python as well.

Configuring Test Parameters

Each test will follow a similar process: connect to the hub, tell it where the target application is, what browser to use and the actual test commands. As a best practice I recommend that both the hub connection information and the target application location are configurable and externally provided. If not, the test code or test configuration (i.e. a properties file) should be updated if the hub or the test server changes. Moreover, it is critical for a successful deployment of a test suite across the team and continuous integration to provide these settings externally.

A pattern suggested is to provide both settings as environment variables or system properties. Code could be like this:

public class CodesIntegrationTestCase {
    private static final Logger logger =
        LoggerFactory.getLogger(CodesIntegrationTestCase.class);
    private static String SELENIUM_HUB_URL;
    private static String TARGET_SERVER_URL;

    @BeforeClass
    public static void initEnvironment() {
        SELENIUM_HUB_URL = getConfigurationProperty(
           "SELENIUM_HUB_URL",
           "test.selenium.hub.url",
           "http://localhost:4444/wd/hub");
        logger.info("using Selenium hub at: " + SELENIUM_HUB_URL);

        TARGET_SERVER_URL = getConfigurationProperty(
            "TARGET_SERVER_URL",
            "test.target.server.url",
            "http://localhost:8080/sdc.samples.selenium");
        logger.info("using target server at: " + TARGET_SERVER_URL);
    }

    private static String getConfigurationProperty(
            String envKey, String sysKey, String defValue) {
        String retValue = defValue;
        String envValue = System.getenv(envKey);
        String sysValue = System.getProperty(sysKey);
        // system property prevails over environment variable
        if (sysValue != null) {
            retValue = sysValue;
        } else if (envValue != null) {
            retValue = envValue;
        }
        return retValue;
    }

Configuring the Browsers

Next step to write the tests is to decide in which browsers each test will run. Election can be as detailed as needed. You can just decide on the browser family or be precise and request and specific browser version in a certain operating system. Either the case, when the test reaches the hub, it will find an available node with the requested capabilities and delegate the test execution to it.

To do that, just leverage the org.openqa.selenium.remote.DesiredCapabilities class or even better its factory methods.

If a test would need to be executed in a Mozilla Firefox browser, just use this statement:

DesiredCapabilities browser = DesiredCapabilities.firefox();

If you need to test inside a Microsoft Internet Explorer browser:

DesiredCapabilities browser = DesiredCapabilities.internetExplorer();

In the case you need more control, you can be more specific. For example to request an Opera 11 browser in a Linux OS, you could use:

DesiredCapabilities browser = DesiredCapabilities.opera();
browser.setVersion("11");
browser.setPlatform(Platform.LINUX);

Reusing Test Code for Cross-Browser Compatibility Tests

In many situations it is desirable that the same test is executed in different browsers and OS mixes. If that is the case, it is a best practice to reuse the test code and provide the browser as a parameter. It is also a best practice to use different test methods for each browser. Thus, in case of test error or failure, you will have immediate feedback on which is browser where the test failed.

A suggested code pattern could be like this:

    @Test
    public void testIE()
            throws MalformedURLException, IOException {
        DesiredCapabilities browser =
            DesiredCapabilities.internetExplorer();
        testCodesCrud(browser);
    }

    @Test
    public void testFirefox()
            throws MalformedURLException, IOException {
        DesiredCapabilities browser =
            DesiredCapabilities.firefox();
        testCodesCrud(browser);
    }

    @Test
    public void testChrome()
            throws MalformedURLException, IOException {
        DesiredCapabilities browser =
            DesiredCapabilities.chrome();
        testCodesCrud(browser);
    }

    @Test
    public void testOpera()
            throws MalformedURLException, IOException {
        DesiredCapabilities browser =
            DesiredCapabilities.opera();
        testCodesCrud(browser);
    }

The four test methods, one for a different browser family, is effectively reusing the same test code inside the testCodesCrud() method. The browser is passed as a parameter to the test.

Contacting the Hub and Initiating the Test

Next step in the test code is to instantiate a WebDriver to contact with the hub, ask for a browser and initiate the test commands by accessing the application under test in the URL where it is available. It is best practice to always close the driver, for example using a finally block to do that. Closing the driver will, among other things, close the browser process in the remote node.

A suggested pattern for writing the test code would be like this:

    public void testCodesCrud(DesiredCapabilities browser)
            throws MalformedURLException, IOException {
        WebDriver driver = null;
        try {
            driver = new RemoteWebDriver(
                new URL(SELENIUM_HUB_URL), browser);

            // test starts in Codes entity list page
            driver.get(TARGET_SERVER_URL + "/CodesView.do");

            // rest of test commands come here
        } finally {
            if (driver != null) {
                driver.quit();
            }
        }
    }

Interacting with the Browser

Although the WebDriver API is rich, most of the times the test code will just find elements and interact with them using simple methods as sendKeys() or click(). Elements on a page can be located by name, id, class, tag or XPath expression.

Let’s imagine that our test would like to verify that the initial listing on the Codes entity contains three values and that those three are “A”, “C” and “D”. The test code would be like this:

    // confirm initial data list
    List<WebElement> codeElems = driver.findElements(By.name("code"));
    List<String> codes = new ArrayList<String>();
    for (WebElement codeElem : codeElems) {
        codes.add(codeElem.getAttribute("value"));
    }

    assertEquals(3, codes.size());
    assertTrue(codes.contains("A"));
    assertTrue(codes.contains("C"));
    assertTrue(codes.contains("D"));

To interact with form controls, as buttons, the process is analogous: find the element and issue a simple command to it:

    // get add button
    WebElement addForm = driver.findElement(By.name("add"));
    WebElement addButton = addForm.findElement(By.name("add"));

    // submit to add a new record
    addButton.click();

It is a best practice to add some delay time when loading a new page. With this approach, the test is protected from failing if the new page does not load immediately while ensuring that the right page is loaded in a timely manner using a time out:

    // wait up to 10 seconds for the Codes detail page to load
    (new WebDriverWait(driver, 10)).until(
        new ExpectedCondition<Boolean>() {
            public Boolean apply(WebDriver d) {
                // the expected condition in this case
                // is the new page title 
                return d.getTitle().equals("Codes Detail Page");
            }
        });

Once the detail page is loaded, there is an empty form to add a new Codes entity. Interacting with this form is easy with the WebElement interface:

    WebElement detailForm = driver.findElement(By.name("detail"));
    WebElement codeField = detailForm.findElement(By.name("code"));
    codeField.sendKeys("P");
    WebElement valueField = detailForm.findElement(By.name("value"));
    valueField.sendKeys("postponed");
    // confirm add and return to view page
    WebElement okButton = detailForm.findElement(By.name("ok"));
    okButton.click();

Alternatively, the submit() method from WebElement interface can be used. This method will just submit the form in which the element is located. Thus, the final two statements could be replaced with:

    ...
    valueField.sendKeys("postponed");
    // confirm add and return to view page
    valueField.submit();

For the rest of the test code I just combined what is shown before to verify that new Codes entities can be added, updated and deleted, and each time the listed values are consistent.

Executing the Test

Once the test is finished, deploy the application into a local Tomcat server using Eclipse WTP. Once the application is up, the unit test can be executed as usual. Don’t forget to add the hub and target server URLs as environment variables or system properties to the test launcher configuration:

-Dtest.selenium.hub.url=http://xxxxx:4444/wd/hub
-Dtest.target.server.url=http://xxxxx:8080/sdc.samples.selenium

Once the test is executed, if the node boxes are visible you may see how each browser shows, the application is tested and the browser is closed. Like an automated piano, pages will show, text will be entered and buttons will be pressed, just like if someone were interacting with the mouse and keyboard:

At the end, test results will be shown in JUnit view inside Eclipse IDE:

Recap

In this post I’ve shown how to write and execute browser tests using Selenium WebDriver and Selenium Grid. Test execution is distributed across nodes in the grid, depending on the available browsers while results are collated by the hub process. Test is launched from Eclipse IDE and results are shown in JUnit view, as with any other regular unit test.

In part 3 (read it here), I will show how to execute the Selenium test just created under Continuous Integration using Maven, Cargo and Jenkins and how to get insights on the code coverage for those tests with Sonar and JaCoCo.

Selenium is, in short, an open source tool to automate web browser interactions. A primary use case is, of course, browser test automation.

Selenium has greatly evolved with time, specially since the 2.0 release when the legacy Selenium project merged with Google’s WebDriver. Nowadays, Selenium offers a wide range of programming languages supported to write the tests, an impressive browser compatibility list, the ability to record tests from user interactions and, above it all in my opinion, the ability to re-execute tests across a grid of machines with various operating systems, browser families and versions.

Although Selenium seems to be primarily chosen for functional/regression test automation, it’s also a great choice – precisely because of the grid feature – for cross-browser compatibility testing: ensuring in an easy, cost-effective way, that our web applications are usable in all sorts of operating systems and browsers.

In this and forthcoming posts in a short series I will share my experiences setting up a Selenium Grid, building some automated tests for a simple Spring application, re-executing them from Eclipse IDE and finally re-executing them in continuous integration (including code coverage) with Maven, Cargo, Jenkins, Sonar and JaCoCo.

Setting Up the Grid

First of all I wanted to start by building the grid: a number of virtual machines with different operating systems and browsers ready to be used to re-execute Selenium tests. Yes, you can re-execute the tests locally but then it would be limited to your OS and the browsers installed in your PC. Thinking on mid-to-large projects, it makes more sense to have some spare capacities that can be shared across developers, with a wider coverage of OS-browser mixes.

A Selenium Grid is very easy to create and configure. In my case, I took an old dual-core PC upgraded to 4 GB of RAM and Oracle VirtualBox. Running as ‘headless’ virtual machines with remote display activated, I created three virtual machines:

1. Selenium Slave1. Windows XP 32-bit box, 1 GB RAM. This box has IE 8 and Chrome 16 browsers installed on it and will act as a node for test execution.
2. Selenium Slave2. Ubuntu 11.10 32-bit box, 1 GB RAM. This box has Firefox 9 and Opera 11.61 browsers installed on it and will act as a node for test execution.
3. Selenium Hub. Ubuntu 11.10 32-bit box, 1 GB RAM. This box will act as the hub, the controller of the grid.

Once I installed all chosen browsers, I downloaded the Selenium Server component from their website, exactly the file selenium-server-standalone-2.16.1.jar, and saved it in a handy place, as c:\selenium-2.16.1 or $HOME/selenium-2.16.1. I also downloaded and installed JDK 7 update 2 32-bit in each box.

For the Windows box I also needed to download the chromedriver component. chromedriver is a standalone executable needed to automate interactions with Google’s browser that is developed separately in another project hosted in Google Code here: code.google.com/p/chromedriver/. I downloaded the latest release at chromedriver_win_18.0.1022.0.zip and extracted it under c:\selenium-2.16.1 as well. Finally I added c:\selenium-2.16.1 to the box PATH (it should be accessible to the server process).

Launching the Hub

Once the three boxes were ready, I launched the hub process. Our tests will interact with the hub, asking for available capabilities in a certain OS, browser and version. The different nodes (even the hub itself if it has spare capacity and browsers available) will register with this hub and will be available for future test executions. Capabilities can be optimized for parallel processing, for example 5 Chrome browsers, 2 Firefox browsers on some box and 2 Safari browsers on some other.

To launch the hub process simply issue a command like this (or place it in a shell/batch script for later):

java -jar selenium-2.16.1/selenium-server-standalone-2.16.1.jar
\ -role hub -port 4444

The port parameter is optional and actually 4444 is the default port for the hub role. After a few seconds, the process will start the daemon and will wait for the nodes to register and tests to come.

Registering the Nodes

For the nodes, the process is quite similar but you will need to pass the hub URL and what browsers are available.

In our environment, the Windows XP box has IE 8 and Chrome installed. Therefore the launch command would be like this:

java -jar selenium-2.16.1\selenium-server-standalone-2.16.1.jar
\ -role node -port 5555 -hub http://xxxxx.61:4444/grid/register
\ -browser "browserName=internet explorer,version=8,platform=WINDOWS"
\ -browser browserName=chrome,platform=WINDOWS

The port parameter is again optional and 5555 is the default port for the node role.

Note how the browser parameter is used (more than once if needed) to tell the hub about the available browsers. Note as well that you may need to ‘escape’ the browser string value if there are spaces. Also noteworthy, you may add version information but it is not required. In my opinion IE version is really critical for cross-browser matters but in other browsers it is not so important.

Now it’s the turn for the second node. In this case the command will look like this:

java -jar selenium-2.16.1/selenium-server-standalone-2.16.1.jar
\ -role node -port 5555 -hub http://xxxxx.61:4444/grid/register
\ -browser browserName=firefox,platform=LINUX
\ -browser browserName=opera,platform=LINUX

Finally, I verified that the nodes were properly registered. The hub has a simple console with basic information about the available nodes at the URL:

http://xxxxx.61:4444/grid/console

The console output will look like this:

And that’s all. We’re done setting up the grid!

Recap

In this post I’ve discussed a bit about Selenium and shown how easy is to set up a grid for test execution with Selenium Grid. In part 2 (read it here) I will explore Selenium WebDriver for writing and launching web UI automated tests.

With Micro Cloud Foundry you can work locally in your applications and test how they work integratedly with Cloud Foundry services.

Using Micro Cloud Foundry during development is highly recommended for any serious work. It is not practical to have multiple people working on the same application and constantly deploying to the same public or private Cloud Foundry instance (e.g. hosted in Amazon EC2 or hosted in a VMware vSphere environment). Instead, developers would use local Micro Cloud Foundry instances for build and test and then a dedicated Micro Cloud Foundry or Cloud Foundry instance for integration testing.

In this post I will show how to get, configure and start to work with Micro Cloud Foundry.

How to Obtain a Micro Cloud Foundry

Micro Cloud Foundry instances are free but their distribution is controlled. The process starts by applying for a Micro Cloud Foundry instance at:

http://cloudfoundry.com/micro

You  will need to provide a unique domain name in the form:

<my-domain>.cloudfoundry.me

If the name for the domain is available, you will get it assigned to your account along with a configuration token that will be needed to configure the Micro Cloud Foundry instance.

Configuring Micro Cloud Foundry

Next step is to download Micro Cloud Foundry and start it.

Micro Cloud Foundry comes ready to be used with VMware products but can be used as well with other virtualization tools. In my case I prefer to work with Oracle VirtualBox, so I just created a new empty VM with these settings:

• OS Ubuntu 64-bits
• 1 GB RAM
• 2 CPU
• Bridged Adapter (Intel/PRO 1000 MT Desktop)

Then, attach the Micro Cloud Foundry hard disk from the downloaded file (it has the VMDK extension) to the VM and start it. After a few seconds, Micro Cloud Foundry will show its configuration screen.

Configuration steps are:

• Select 1 to start configuration
• Enter the administrator password twice (it will be assigned to the “root” and “vcap” users in the underlying Ubuntu)
• Select 1 to configure DHCP
• Enter the proxy configuration (if needed)
• Enter the configuration token that you received a moment ago to confirm the domain name

After finishing configuration, DNS settings are propagated. DNS settings are needed for the clients to connect to this Micro Cloud Foundry instance.

Pay attention if using NAT and also to firewall software because the clients may not be able to connect to Micro Cloud Foundry. Also pay attention to DHCP’s with short lease time. If the instance IP is changing too quickly, DNS settings may not get properly updated.

After DNS finishes, Micro Cloud Foundry individual services are installed and started. Ready to go!

If you feel curious, issuing a ’12′ command into Micro Cloud Foundry console will allow you access to the underlying Ubuntu server. Lots of possibilities in there, right?

Deployment to Micro Cloud Foundry

Deployment process to Micro Cloud Foundry mirrors the process for the public Cloud Foundry instance. The only real difference is in the target API:

>vmc target http://api.sdcassets.cloudfoundry.me
>vmc register
>vmc login
>vmc create-service mysql vmcfirst-db
>vmc push vmcfirst

The ‘register’ command is needed because we are not a registered user in this Micro Cloud Foundry instance. We may register as many users as needed in our instance.

The process can be done using the Eclipse plug-in as shown in my previous post for the public Cloud Foundry instance here.

If using the command line, remember to issue the push command from the directory where you have your exploded WAR, for example as generated by Maven package goal.

In a few seconds, the application should be up and running in your Micro Cloud Foundry. Enjoy!

Conclusion

As easy as it gets. All the power of the Cloud Foundry platform at your hands to play with.

With Micro Cloud Foundry, you can successfully build a development team targeting Cloud Foundry. Privacy and security concerns relax as you may have it running concealed in your own premises or just live in your PC.

It’s so easy that is hard to say ‘no’ and don’t give it a try. What are you waiting for? Chuck Norris’ “I-approve-this-cloud” ad?

———-

Nuevo año, y estrenamos nuevo look. Este es más claro y sencillo, creo. ¡Espero que os guste!

Here’s an excerpt:

A San Francisco cable car holds 60 people. This blog was viewed about 3,500 times in 2011. If it were a cable car, it would take about 58 trips to carry that many people.

Click here to see the complete report.

After we finished writing the post on VMware Cloud Foundry platform, it seemed natural to write a follow-up on Red Hat OpenShift. OpenShift is a Java-based Platform-as-a-Service (PaaS) offering from Red Hat, the ‘giant’ of Open Source Software with a well-deserved reputation that comes from a wide range of products including operating systems (Fedora, Red Hat Enterprise Linux), application servers / middleware (JBoss AS, JBoss ESB), frameworks (Hibernate, Seam) and tools (JBoss Tools, Arquillian).

As a PaaS offering, the ultimate goal of OpenShift is to reduce the effort needed to write and deploy highly scalable and highly available Java applications. Under your dedicated “application space” the platform components run to ensure your application is able to respond to user’s requests, but isolating your application code from the infrastructure and all the complexity usually associated with complex, distributed deployments.

Let’s jump into OpenShift!

OpenShift was born after Red Hat’s acquisition of Makara in 2010. Makara is a state-of-the-art technology for building highly scalable solutions that was integrated with Red Hat flagships RHEL and JBoss to become the core of the OpenShift platform.

The first fact that really got our attention and positively increased our interest in the platform – above the usual PaaS stuff – is the statement used as the title for the post: Freedom of choice. No matter if you are a Java developer and your favorite framework is Spring, Seam or just the Java EE specification; no matter if you prefer Ruby, PHP, Perl or Python. OpenShift supports all these technologies.

OpenShift as an offering comes in three flavors: Express, Flex and Power. Express is a free to use platform for Java, Ruby, PHP, Perl or Python technologies, easy to setup and easy to use. Flex is a full cloud management solution that operates on top of Amazon EC2, dynamically managing clusters and applications, scaling up and down as needed. Power is the most flexible solution in which you can go down to the OS level and build up cloud services on any Linux-based solution.

For the rest of this post we will show how to start working with OpenShift Express, prepare an existing Java with Spring application and deploy it to the cloud. We will be using Eclipse IDE Java EE bundle on a Windows workstation to work on the application and test it locally, plus OpenShift command-line tools to configure and manage the cloud deployment.

OpenShift client tools are a collection of Ruby-based scripts. With them you can interact with OpenShift and with your application.

According to Express setup instructions page here, you need to install Cygwin (http://www.cygwin.com/), some Cygwin packages (including Ruby and Git) plus RubyGems and then, finally, install Red Hat OpenShift gems.

But we are Windows geeks, so there is no point in going through Cygwin to interact with OpenShift. Actually, this is one of the many advantages of Ruby: The same Ruby script can be executed from a Linux shell, Windows shell or inside the Java Virtual Machine.

So, first step, if you do not have a Ruby runtime already installed, is to go to http://www.rubyinstaller.org/ and download the Ruby Zipped distribution. Then, decompress it to a folder that I will refer as %RUBY_HOME%. From a command prompt, move to %RUBY_HOME%/bin directory and issue the following commands:

>set http_proxy=<your-proxy-info>
          Needed if you are behind a proxy, use the right one for your network or skip this command
>gem install rhc
          Install the Red Hat OpenShift gem

You will also need a Git client to upload changes to your OpenShift application space. Git is a popular software configuration management tool and it is used by OpenShift to track changes on artifacts uploaded to the application space. Go to http://code.google.com/p/msysgit/ and download the Git Zipped distribution. Then, decompress it to a folder that I will refer as %GIT_HOME%. I recommend reading a bit about Git and basic commands so you are in good shape to interact with your remote repository at OpenShift.

I also recommend adding both %RUBY_HOME%/bin and %GIT_HOME%/bin to the path.

Once we have installed the needed tools, it’s time to create a domain and an application space. A domain is a unique identifier for all your applications. Inside the domain we will have one or many application spaces, and each one will have an associated Git repository to where we will push our updates to the deployed application. Each push will trigger the necessary actions for doing so automatically.

Both the domain and application identifiers are part of the application URL, so choose wisely. The format is:

http://<app-name>-<domain-name>.rhcloud.com

To create the domain issue the following command:

>rhc-create-domain -n <domain-name> -l <login-email-address>

The login email address identifies you and you will be prompted to enter your password. Once introduced, the console will show your SSH key identification. It will be saved in your %HOME%/.ssh folder and used from now on to secure communications to your domain. The default login information is saved in %HOME%/.openshift/ express.conf so you do not need to provide your login email address each time you issue a command to control your domain.

Next step is to create the application space. For that, issue the following commands:

>cd <project-home-directory>
          You will need to create a directory where the application will be locally stored
>rhc-create-app -a <app-name> -t jbossas-7.0
          Provide the application name and the type of the application

This command will create the remote Git repository and add the application URL to the DNS so users may access it from the Internet. The remote Git repository URL is showed in the command output, in the case you need to supply it to another tool.

With this we have created a JBoss AS 7.0 Java application. OpenShift is taking care of provisioning the server runtime and needed resources. Other types include Ruby (rack-1.1) or PHP (php-5.3) applications. In all cases the platform provides everything needed to start running the application. You can check the list of available types in OpenShift documentation here.

Now that our environment is ready, let’s discuss about what changes need to be done on an existing Java with Spring application to be deployed there.

The reference application is a very simple one: web interface using JSP and JSTL, plus Spring 3 and Hibernate. It is currently configured to use an embedded HSQLDB database for data persistent storage. The application is working locally deployed in a JBoss AS 7.0.2 runtime.

5.1        Adding Support for MySQL

The first adaptation that we are going to do is to add support for MySQL to our application.

Each application in OpenShift may have services associated to it. Each service is named a Cartridge. For our needs we are going to add a MySQL database cartridge to the application. To do that, remember the given application name and issue the following command:

>rhc-ctl-app -a <app-name> -e add-mysql-5.1

The console will show a message confirming the creation of the MySQL database, the root user credentials, the database name (should be the same as the application name) and the connection URL.

5.2        Updating Spring configuration

Our next step is to update the Spring configuration thus the application can make use of the MySQL database. To do that, you may replace the existing data source configuration with the URL and credentials received when the MySQL cartridge was created or rely on some environment variables that are created by OpenShift platform. Using environment variables is the recommended way to configure database access. This way it is easy to test the application locally just by providing values to a locally available MySQL database:

The environment variables used are self-explanatory:

OPENSHIFT_DB_HOST
OPENSHIFT_DB_PORT
OPENSHIFT_APP_NAME
OPENSHIFT_DB_USERNAME
OPENSHIFT_DB_PASSWORD

5.3        Running the Application

Once the changes have been made it is time to commit all the files and make our first push to OpenShift.

Assuming that you’ve placed all application files in the project home directory used when the application was created, just issue the following commands to commit all files and push them to the remote Git repository:

>git commit -a -m “initial version”
>git push

The contents will be uploaded and then a Maven build process will trigger. Sources will be compiled, packaged and deployed in a few seconds and after that, the application is ready to be used!

5.4        Useful Commands to Control your Applications

These are some useful command that will allow you to control your applications:

>rhc-user-info
          Show basic information about applications available in your domain:
names, types, Git URL, application URL and cartridges
>rhc-ctl-app -a <app-name> -c status
          Show the application status, including a tail from its log
>rhc-ctl-app -a <app-name> -c start|stop|reload|restart
          Starts, stops, reloads and restarts the application
>rhc-snapshot -a <app-name> -s <file-name>.tgz
          Downloads the application files, including full logs, for troubleshooting

Recently Red Hat announced a new release of their popular JBoss Tools suite for Eclipse that included support for OpenShift. If you do not feel comfortable while working with command line tools or just prefer the improved experience of having everything at one click distance in your favorite IDE, then this section is for you.

Let’s assume that we already have an application deployed to OpenShift and a blank Eclipse workspace. First, let’s install the OpenShift support from JBoss Tools. For example, for Indigo, add the following Eclipse update site and add JBoss OpenShift Express Tools feature:

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

Once installed, we will have available a new wizard named OpenShift Express Application. Let’s create a new project of this type:

Next, enter your OpenShift credentials and select the domain and application to import it into Eclipse.

Then, review the application details and specify, if desired, the target folder for the project. You may as well create a new JBoss server runtime if you do not have already one in your workspace. Once done, the Git remote repository for the application will be cloned into your workspace:

Now, to verify that everything is working fine, let’s make a trivial change, commit it and push it to OpenShift for deployment:

Once the push is finished the updated application will be redeployed:

Easy, right?

Red Hat OpenShift is a Cloud platform based on Red Hat Enterprise Linux and JBoss Application Server that allows Java, Ruby, PHP or Python web applications run on Cloud premises with high flexibility and scalability. Existing applications will need only minor configuration changes to be ready for OpenShift. Moreover, OpenShift can be easily integrated with the popular Eclipse IDE for developers productivity increase.

In the forthcoming months we will surely have confirmation on enterprise-ready commercial offerings sitting on this great platform, and hopefully it will make the jump to private infrastructures as well.

It’s cloudy, today. But I’m not speaking about the weather in northern hemisphere autumn. Cloud Computing, two words that cannot be explained with just a sentence, is now a reality, born to change our (digital) lives.

Cloud Computing may mean different things to different people. For some, it would be having their personal documents, photos and music synchronized “in the cloud” and accessible through their PC or mobile device. For others, it would be being able to run their favorite games and to do their favorite stuff anywhere, anytime. It may be a cost-effective, agile hosting solution, an elastic production environment for databases and application servers, and many, many other things. Google Docs, Picasa, iCloud, Facebook, Twitter, Foursquare, Amazon EC2…

In this article, though, we will be discussing about Cloud Computing as a platform where developers can deploy their highly scalable, highly available solutions. We call this Platform-as-a-Service, or PaaS for short. PaaS also means a lot of things but for us is forgetting about dealing with the OS, the application server, the disc or the memory in the server. You just have your “application space”, where you can upload your solutions, execute them, monitor how they behave and control the amount of resources available to them.

You don’t know where your application physically is, the type of host server, operating system configuration or even how the application server is configured at all. You may certainly know about some or all of this, but it is really not needed to achieve your targets: develop your idea and make it available to your clients (no matter how much or where they are) in a hassle.

VMware Cloud Foundry is one of such platforms.

Cloud Foundry, www.cloudfoundry.com, is an open platform sponsored by VMware, born to support multiple frameworks, application servers and even multiple cloud providers. You may think on it as a core product that may be used as a foundation for more advanced cloud services.

Cloud Foundry is open source. This means that you can get and contribute to the platform, build it and run it in your own host. As an open source project it lives at www.cloudfoundry.org.

From Cloud Foundry site you may download a virtual machine with the live platform (the Micro Cloud Foundry) for your own use or request an account in the public, Internet-wide Cloud Foundry platform. Either one or the other, you will get the ability to run Java with Spring, Ruby on Rails and Sinatra, Groovy, Grails or Scala applications and leverage MySQL, Redis or MongoDB data services.

For the rest of this article we will show how to start working with Cloud Foundry, prepare an existing Java with Spring application and deploy it to the cloud. We will be using Eclipse IDE Java EE bundle with Spring IDE installed on it and the public Cloud Foundry instance, so really no special setup is needed to start working on it.

The first step is to request an account in Cloud Foundry site. Currently Cloud Foundry is in beta status and in theory access is granted as soon as VMware grows the existing public premises, thus the ‘request an invite’ label. In practice, access is granted quickly and you will receive an initial password by mail.

3.1        Changing the Initial Password with Cloud Foundry Ruby gems

My recommendation is to change that password. Cloud Foundry can be controlled through Ruby gems or through Eclipse plug-ins. Although the Eclipse plug-ins are the easiest way to work on the code, deploy and test applications, some tasks needs the Ruby scripts, so let’s start by installing them.

As I use Windows, I downloaded the Zipped distribution from http://www.rubyinstaller.org/ and place it in a folder that I will refer as %RUBY_HOME%. From a command prompt, move to %RUBY_HOME%/bin directory (yes, it’s Windows, but you can use forward slashes as well) and issue the following commands:

>set http_proxy=<your-proxy-info>
     Needed if you are behind a proxy, use the right one for your network or skip this command
>gem install vmc
     Install the VMware Cloud Foundry gem
>vmc target api.cloudfoundry.com
     This is the public Cloud Foundry instance
>vmc login
     Enter the credentials received by mail
>vmc password
     Enter the new password twice and it’s done!

3.2        Install the Cloud Foundry support into Eclipse IDE

Next step is to install the Cloud Foundry plug-ins to control our application space from Eclipse IDE. To do that, the easiest way is, inside the IDE, go to Eclipse Marketplace (Help -> Eclipse Marketplace menu), search for “Cloud Foundry” and install the feature appropriate for the Eclipse version (Helios or Indigo are supported):

Once installed, create a new server inside Eclipse. You will now have a new server type available:

Enter your credentials (don’t forget the new password) and keep selected the public Cloud Foundry instance:

You can at this moment select the applications to be deployed into your application space, but for now we will not add anything there. Click the Finish button to save the server and return to the workbench.

Now that our environment is ready to support Cloud Foundry, let’s discuss about what changes need to be done on an existing Java with Spring application to be deployed there.

The reference application is a very simple one: web interface using JSP and JSTL, plus Spring MVC and Hibernate. It is currently configured to use an embedded HSQLDB database for data persistent storage.

4.1        Adding Support for MySQL

The first adaptation that we are going to do is to add support for MySQL to our application. Open the server configuration page in Eclipse (double-click on server name, this is the server created before in 3.2) and move to the Applications tab:

To add the application, click the button on the Application header, select the application from the available list and click Finish. In the next dialog, you will need to assign a name to the application. This name should not be in use in the public instance. You may as well select the memory assigned to the application. In our case the default 512 MB are Ok:

Now we have the application ready to be deployed, but still not services are associated to it:

Now click the button on the Services header. Give a name to the service and select “MySQL database service” in the drop-down list:

Finally, drag the service from the Services header to the Application Services header to bind it to the application:

4.2        Updating Spring configuration

Our next step is to update the Spring configuration thus the application can make use of the MySQL database. This is a very simple step, as actually the platform is able to inject the data source at runtime. To do that, replace the data source bean definition for the following:

<cloud:data-source id="dataSource"/>

And add this schema to the XML:

xmlns:cloud="http://schema.cloudfoundry.org/spring"
 xsi:schemaLocation="…<your existing schemas>…http://schema.cloudfoundry.org/spring http://schema.cloudfoundry.org/spring/cloudfoundry-spring-0.6.xsd”

4.3        Running the Application

Surprisingly, that’s all. We are ready to deploy the application into Cloud Foundry. Just run the application as you would do with any regular server and after a few seconds you will see your application living in the cloud!

4.4        Basic Monitoring

The deployed application can be monitored, at least up to some extent, from the server page in Eclipse. The page will get updated with some basic metrics as instances in use, CPU usage, memory usage, disk usage and live time:

It is very easy to start working with Cloud Foundry platform. Your existing code would run there with little or no changes at all. Configuration is also very straightforward.

Although in their current beta status, Cloud Foundry is a very interesting platform, powerful and flexible. It is difficult to say how much time will be needed until it is ready for enterprise-wide deployments with thousands of users and wide geographical dispersion, but surely we will see commercial offerings based on the platform in the following months.

Jump into the cloud! Are you ready?

Now, in part 3, we are going to show how an Annotation Processor can be used to generate source code.

Code Generation using Annotation Processors in the Java language – part 3: Generating Source Code

Generating source code is easy. Generating the right code is not. And doing it in an elegant and efficient way can be a cumbersome task!

Fortunately, in the last years Model-Driven Engineering (1) (MDE, sometimes referred also as Model-Driven Development or Model-Driven Architecture) has helped to evolve a practice that was more art than science – task for ninja coders – into a mature methodology strongly based on proven processes and tools.

Model-Drive Engineering is much more than generating source code, although we can think of it as a natural entry point to MDE methodologies.

Annotation Processors is one of the many tools that we may use to generate source code.

Model and Meta-model in MDE

Before going into the details on how to generate source code using Annotation Processors, there is a couple of concepts that we would like to present, as we will be referring to them in the following slides: models and meta-models.

One of the pillars of MDE is the construction of abstractions. We model the software system that we intent to build at different levels of detail and with different approaches. When one level of abstraction is modeled, we can start to model the next one and the next, ending with a complete, deployable product.

In this context, a model is no more than the abstraction that we use to represent our system, whatever level of detail we are using.

The meta-model, then, are the rules that we use to write our models. You can think of it as the schema or semantics of models.

Generating source code with Annotation Processors

From what we have seen until now, Annotations are an excellent way for defining a meta-model and creating models. Annotation Types will act as meta-models, while a set of Annotations in a given piece of code will act as a model.

We can leverage this model to generate configuration files or to write new source files that are derived from one existing. For example, create a remoting proxy or a data access object from an annotated bean.

The central piece in this approach is the Annotation Processor. A processor will be able to read annotations found in source code – that is, extract the model – and do whatever we need to do with it – open a file, put contents on it. The Java Compiler will take care of validating the model (annotations should match the defined types).

The Filer

As discussed in part 2, every processor have access to a processing environment that points to some interesting utilities. One of them is the Filer.

The javax.annotation.processing.Filer (2) interface contract defines some methods for creating source files, class files or generic resources. By using the Filer we can be sure of using the right directories and that we are not losing valuable generated items in our file system.

This concern is critical if we want to write generators that honors -d and -s options in javac or directories defined in a Maven POM.

The following example shows how to create a Java source file inside an Annotation Processor. The generated class name will be the same as the annotated class name plus the string “BeanInfo”, as if we were generating a Bean information class:

 if (e.getKind() == ElementKind.CLASS) {
     TypeElement classElement = (TypeElement) e;
     PackageElement packageElement =
         (PackageElement) classElement.getEnclosingElement();

     JavaFileObject jfo = processingEnv.getFiler().createSourceFile(
         classElement.getQualifiedName() + "BeanInfo");

     BufferedWriter bw = new BufferedWriter(jfo.openWriter());
     bw.append("package ");
     bw.append(packageElement.getQualifiedName());
     bw.append(";");
     bw.newLine();
     bw.newLine();
     // rest of generated class contents

Don’t Generate Like my Brother

The previous example is simple, interesting, but a mess!

We are mixing the logic of getting the information we need from annotations (the model) with the logic that writes the generated file (the view).

It is very difficult to write a decent generator in that way. If we need something more complex the task can be cumbersome, error prone and hard to maintain.

We need, therefore, a more elegant approach:

Let’s see as an example of this approach how to leverage Apache Velocity to build generators the way we want.

A Brief History of Velocity

Velocity, a project from the Apache Software Foundation, is a template engine written in Java that produces all types of text files by mixing a template with data from Java objects.

Velocity has been used historically to render views following the popular MVC pattern, or as a substitute to XSLT to transform data in XML files.

Velocity has its own language named the Velocity Template Language (VTL) that is key to produce rich and easy to read templates. In VTL we can define variables, control flow and iterations and access information contained in Java objects in a simple and intuitive way.

Below you can see a fragment of a Velocity Template:

 #foreach($field in $fields)
     /**
      * Returns the ${field.simpleName} property descriptor.
      *
      * @return the property descriptor
      */
     public PropertyDescriptor ${field.simpleName}PropertyDescriptor() {
         PropertyDescriptor theDescriptor = null;
         return theDescriptor;
     }
 #end
 #foreach($method in $methods)
     /**
      * Returns the ${method.simpleName}() method descriptor.
      *
      * @return the method descriptor
      */
     public MethodDescriptor ${method.simpleName}MethodDescriptor() {
         MethodDescriptor descriptor = null;

As you can see, VTL is very straightforward and easy to understand. Highlighted in bold, you can see two typical VTL constructs: iterating a collection of objects and print some property from each element found in the collection.

The Velocity Generator Approach

Now that we have decided to use Velocity to enhance our generator, we have to redesign it to follow this schema:

By following this approach you will find that the processor/generator code is clear, well structured and easy to understand and maintain.

Let’s proceed step by step.

Step 1: Write the Template

For the sake of simplicity we are not going to show a full BeanInfo generator, just a subset of the fields and methods that are actually required will be built with our Processor.

Let’s create a file named beaninfo.vm and place it under the src/main/resources of the Maven processor artifact. An example of the contents for the template are:

package ${packageName};

import java.beans.MethodDescriptor;
import java.beans.ParameterDescriptor;
import java.beans.PropertyDescriptor;
import java.lang.reflect.Method;

public class ${className}BeanInfo
    extends java.beans.SimpleBeanInfo {

    /**
     * Gets the bean class object.
     *
     * @return the bean class
     */
    public static Class getBeanClass() {

        return ${packageName}.${className}.class;
    }

    /**
     * Gets the bean class name.
     *
     * @return the bean class name
     */
    public static String getBeanClassName() {

        return "${packageName}.${className}";
    }

    /**
     * Finds the right method by comparing name & number of parameters in the class
     * method list.
     *
     * @param classObject the class object
     * @param methodName the method name
     * @param parameterCount the number of parameters
     *
     * @return the method if found, <code>null</code> otherwise
     */
    public static Method findMethod(Class classObject, String methodName, int parameterCount) {

        try {
            // since this method attempts to find a method by getting all
            // methods from the class, this method should only be called if
            // getMethod cannot find the method
            Method[] methods = classObject.getMethods();
            for (Method method : methods) {
                if (method.getParameterTypes().length == parameterCount
                    && method.getName().equals(methodName)) {
                    return method;
                }
            }
        } catch (Throwable t) {
            return null;
        }
        return null;
    }
#foreach($field in $fields)

    /**
     * Returns the ${field.simpleName} property descriptor.
     *
     * @return the property descriptor
     */
    public PropertyDescriptor ${field.simpleName}PropertyDescriptor() {

        PropertyDescriptor theDescriptor = null;
        return theDescriptor;
    }
#end
#foreach($method in $methods)

    /**
     * Returns the ${method.simpleName}() method descriptor.
     *
     * @return the method descriptor
     */
    public MethodDescriptor ${method.simpleName}MethodDescriptor() {

        MethodDescriptor descriptor = null;

        Method method = null;
        try {
            // finds the method using getMethod with parameter types
            // TODO parameterize parameter types
            Class[] parameterTypes = {java.beans.PropertyChangeListener.class};
            method = getBeanClass().getMethod("${method.simpleName}", parameterTypes);

        } catch (Throwable t) {
            // alternative: use findMethod
            // TODO parameterize number of parameters
            method = findMethod(getBeanClass(), "${method.simpleName}", 1);
        }

        try {
            // creates the method descriptor with parameter descriptors
            // TODO parameterize parameter descriptors
            ParameterDescriptor parameterDescriptor1 = new ParameterDescriptor();
            parameterDescriptor1.setName("listener");
            parameterDescriptor1.setDisplayName("listener");
            ParameterDescriptor[] parameterDescriptors = {parameterDescriptor1};
            descriptor = new MethodDescriptor(method, parameterDescriptors);

        } catch (Throwable t) {
            // alternative: create a plain method descriptor
            descriptor = new MethodDescriptor(method);
        }

        // TODO parameterize descriptor properties
        descriptor.setDisplayName("${method.simpleName}(java.beans.PropertyChangeListener)");
        descriptor.setShortDescription("Adds a property change listener.");
        descriptor.setExpert(false);
        descriptor.setHidden(false);
        descriptor.setValue("preferred", false);

        return descriptor;
    }
#end
}

Note that for this template to work, we will need to pass to Velocity the following information:

• packageName: the full package name of the generated class
• className: the name of the generated class
• fields: a collection containing the fields in the source class; for each field we will need:
• simpleName: the name of the field
• type: the type (not used in the example)
• description: self-explanatory (not used in the example)
• …
• methods: a collection containing the methods in the source class; for each method we will need:
• simpleName: the name of the method
• arguments: the method arguments (not used in the example)
• returnType: the method return type (not used in the example)
• description: self-explanatory (not used in the example)
• …

All this information (the model) will be extracted from annotations found in the source class and stored in JavaBeans to be passed to Velocity.

Step 2: The Processor Reads the Model

Let’s create the Processor and don’t forget to annotate it to process a BeanInfo annotation type, as explained in part 2:

@SupportedAnnotationTypes("example.annotations.beaninfo.BeanInfo")
@SupportedSourceVersion(SourceVersion.RELEASE_6)
public class BeanInfoProcessor
    extends AbstractProcessor {

The process method will need to extract information needed to build the model from the annotations and the source class itself. You can use JavaBeans to store as much information as needed, but in this example we will leverage javax.lang.model.element types as we are not planning to send too much details to Velocity (but would need, in the case we were going to build a full BeanInfo generator):

            String fqClassName = null;
            String className = null;
            String packageName = null;
            Map<String, VariableElement> fields = new HashMap<String, VariableElement>();
            Map<String, ExecutableElement> methods = new HashMap<String, ExecutableElement>();

            for (Element e : roundEnv.getElementsAnnotatedWith(BeanInfo.class)) {

                if (e.getKind() == ElementKind.CLASS) {

                    TypeElement classElement = (TypeElement) e;
                    PackageElement packageElement = (PackageElement) classElement.getEnclosingElement();

                    processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.NOTE,
                        "annotated class: " + classElement.getQualifiedName(), e);

                    fqClassName = classElement.getQualifiedName().toString();
                    className = classElement.getSimpleName().toString();
                    packageName = packageElement.getQualifiedName().toString();

                } else if (e.getKind() == ElementKind.FIELD) {

                    VariableElement varElement = (VariableElement) e;

                    processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.NOTE,
                        "annotated field: " + varElement.getSimpleName(), e);

                    fields.put(varElement.getSimpleName().toString(), varElement);

                } else if (e.getKind() == ElementKind.METHOD) {

                    ExecutableElement exeElement = (ExecutableElement) e;

                    processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.NOTE,
                        "annotated method: " + exeElement.getSimpleName(), e);

                    methods.put(exeElement.getSimpleName().toString(), exeElement);
                }
            }

Step 3: Initialize the Velocity Context and Load the Template

The following code snippet show how to initialize the Velocity context and load the template:

            if (fqClassName != null) {

                Properties props = new Properties();
                URL url = this.getClass().getClassLoader().getResource("velocity.properties");
                props.load(url.openStream());

                VelocityEngine ve = new VelocityEngine(props);
                ve.init();

                VelocityContext vc = new VelocityContext();

                vc.put("className", className);
                vc.put("packageName", packageName);
                vc.put("fields", fields);
                vc.put("methods", methods);

                Template vt = ve.getTemplate("beaninfo.vm");

The velocity configuration file, named in this example velocity.properties, should be placed under src/main/resources folder. An example of its contents is below:

runtime.log.logsystem.class = org.apache.velocity.runtime.log.SystemLogChute

resource.loader = classpath
classpath.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader

This set of properties configures a log for Velocity and a classpath-based resource loader to find the template.

Step 4: Create the New Source and Generate the Contents

Finally, let’s create a new source file and run the template using this new file as the target. The following code snippet shows how to do it:

                JavaFileObject jfo = processingEnv.getFiler().createSourceFile(
                    fqClassName + "BeanInfo");

                processingEnv.getMessager().printMessage(
                    Diagnostic.Kind.NOTE,
                    "creating source file: " + jfo.toUri());

                Writer writer = jfo.openWriter();

                processingEnv.getMessager().printMessage(
                    Diagnostic.Kind.NOTE,
                    "applying velocity template: " + vt.getName());

                vt.merge(vc, writer);

                writer.close();

Step 5: Package and run

Finally, register the processor (remember the service configuration file shown in part 2) package it and invoke it from a client project compilation command, Eclipse or Maven build.

Assuming the following client class:

package example.velocity.client;
import example.annotations.beaninfo.BeanInfo;
@BeanInfo public class Article {
    @BeanInfo private String id;
    @BeanInfo private int department;
    @BeanInfo private String status;
    public Article() {
        super();
    }
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public int getDepartment() {
        return department;
    }
    public void setDepartment(int department) {
        this.department = department;
    }
    public String getStatus() {
        return status;
    }
    public void setStatus(String status) {
        this.status = status;
    }
    @BeanInfo public void activate() {
        setStatus("active");
    }
    @BeanInfo public void deactivate() {
        setStatus("inactive");
    }
}

When we issue the javac command, we can see in the console that annotated elements are found and the BeanInfo class is generated:

Article.java:6: Note: annotated class: example.annotations.velocity.client.Article
public class Article {
       ^
Article.java:9: Note: annotated field: id
    private String id;
                   ^
Article.java:12: Note: annotated field: department
    private int department;
                ^
Article.java:15: Note: annotated field: status
    private String status;
                   ^
Article.java:53: Note: annotated method: activate
    public void activate() {
                ^
Article.java:59: Note: annotated method: deactivate
    public void deactivate() {
                ^
Note: creating source file: file:/c:/projects/example.annotations.velocity.client/src/main/java/example/annotations/velocity/client/ArticleBeanInfo.java
Note: applying velocity template: beaninfo.vm
Note: example\annotations\velocity\client\ArticleBeanInfo.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

If we check in the sources directory we will find there the BeanInfo class as expected. Mission accomplished!

Conclusion

During this series we have learned the basis about how to generate source code by leveraging the Annotation Processor framework in Java 6:

Now it is time to apply this to your projects. Think Generate!

—

(1) If you want to know more about MDE, visit this article in Wikipedia and follow the references.

(2) The Filer API documentation can be reviewed online here.