Installing Travis CLI on Mac

I recently had the need to install the Travis CI CLI tool on my Mac and it turned out to be harder then I would have expected.  The issue came from missing headers for libffi which is usually provided with XCode Command Line Tools...  but since I don't have XCode installed, that library was missing for me.  To resolve the issue I executed the following from a terminal window:

xcode-select --install

I was presented with a dialog to confirm that installation.  The install took a few minutes, when it was complete, I tried the Travis CLI installation again using:

gem install travis

which then completed without error.

Streaming WebSphere Liberty Profile Log Entries to Splunk

Log data is an important source of information containing insight into the operation and health of your application.  Being able to index, search and alert on events in near realtime increases your awareness of potential interruptions to service.  Ultimately log analytics can reduce Mean Time to Recovery (MTTR) and may give you the ability to correct an issue before it impacts your end users.

IBM's WebSphere Liberty Profile is a great option for running containerized Java EE micro-services.  IBM provides a fully compliant Java EE 7 runtime using a light weight application server along with a number of features (plugins) which can be added to provide additional functionality.  One of the features provided by the Liberty Profile streams log entries to Logstash.  In terms of end to end log aggregation and analytics, Logstash is a forwarding service which will gather log entries and forward them to a log analytics engine. You can read more about Logstash here.

The first question you might ask is why use this feature...  why not just use a standard Docker logging driver like syslog or journald... or even the Splunk driver directly?  Why do i need another layer in my log aggregation framework.  A Liberty Profile server produces four log files; console.log, messages.log, trace.log and the files emitted by the First Failure Data Capture (FFDC) service.  A Liberty Profile server can be configured to emit a large portion of the data from these different log files to stdout within the container which in turn could then be handled by a standard log driver provided by Docker.  The FFDC log files are the exception to this rule.  FFDC log files are written to their own directory and each file contains the details of a single error that occurred in the server or application.  The difficultly is in getting to the FFDC log files within the container.... which in my experience are very helpful in the first round of problem determination.

This is where the Logstash feature the Liberty Profile provides is beneficial.  Not only does the feature emit the logs normally printed to message.log and trace.log, but it will also emits the FFDC events.  As an added bonus it emits these log events in a JSON format so no additional log entry parsing is required before each entry is forwarded to your log analytics engine.  Logstash is available as an official Docker image on Dockerhub making the adoption in a containerized environment quick and easy.

Note: IBM provides detailed documentation on how to configure logging within a server instance as well as the Logstash feature to which I included links in the references section below.

What does the flow of log entries look like from the Liberty Profile to Splunk using the tools outlined above?  The diagram below is a simple illustration of the flow of data from one or more Liberty Profile containers to Splunk using Logstash.

The Logstash feature in the Liberty Profile sends the data to the Logstash container using Logstash's Lumberjack protocol.  Logstash then formats the log entry using the HTTP Output plugin and sends the entry to Splunk's HTTP Event Collector.  Once received, Splunk indexes the entry and makes it available for querying and visualization.

I've created a GitHub repository with a example of how to configure each component.  The instructions to run the example are in the read me file.  Once the container stack is running, you will see log entries in Spunk within a few seconds.  From there you can query and visualize the data into custom dashboards and alerts.  As an example, below is screen shot of a log entry that originated from a Liberty Profile server queried from Splunk.

The JSON format emitted by the Liberty Profile feature basically eliminations the need to parse the log entry into fields.  In addition environment variable can be set in the Liberty Profile containers to control the values of the hostName and serverName fields in each entry.  These fields can be used to denote the host machine the container is running on as well as the micro-service running within the container.

The entries emitted from the FFDC service are also provided in a JSON format easily consumed by Splunk.  As an example:

Using the the Liberty Profile Logstash feature and Logstash container in this way opens up the possibility of sending the data to other analytics services.  Logstash provides a number of output plugins for open source solutions like Elasticsearch a well as other SaaS solutions like New Relic, Datadog and Loggly.  As this example shows, the generic output plugins like the HTTP plugin can provide further integration to any service providing a HTTP based API.  While Logstash may look like an extra component, it provides a level of flexibility when choosing your analytics engine that a direct connection would greatly limit.

Below is a list of references I used to create the example application:

• Liberty Profile Log Configuration: http://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/rwlp_logging.html
• Liberty Profile Logstash Collector: http://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/twlp_analytics_logstash.html
• Logstash Lumberjack Input Plugin: https://www.elastic.co/guide/en/logstash/current/plugins-inputs-lumberjack.html
• Logstash HTTP Output Plugin: https://www.elastic.co/guide/en/logstash/current/plugins-outputs-http.html
• Splunk HTTP Event Collector: http://dev.splunk.com/view/event-collector/SP-CAAAE6P

Injecting EJBs into JAX-RS Resources using CDI

If you've ever tried to inject an EJB into a JAX-RS v1.x resource using the @EJB annotation, you know it doesn't work.  There are some implementations of JAX-RS that have provided this functionality, but it is implementation specific, not necessarily part of the JAX-RS specification.  It can be over come though by using Contexts and Dependency Injection (CDI).  The steps below are the bare minimum for CDI to inject an EJB into a JAX-RS resource running on the WebSphere Liberty profile.  The steps use the project structure I outlined in a previous post that can be found here.

Enabling CDI

The first step is to enable CDI for the JAX-RS and EJB projects.  This can be accomplished by adding a file called beans.xml to both projects in the standard locations.  For JAR projects (the EJB project in this case), the file is added to the META-INF folder.  In an Eclipse Maven project, this is located in src/main/resources.  For the JAX-RS project (or any WAR project) the file goes in to the WEB-INF directory.  In an Eclipse Maven project, this folder can be found in src/main/webapp.  The file can be left empty, but I like to add the basic CDI XML which is:

Annotating the JAX-RS Resource

The next step is to add the CDI @Inject annotation to the JAX-RS resource.  For example, lets assume we have a simple EJB that provides a single method that returns a String that represents a message.  The EJB interface and implementation may look something like this:

The EJB can then be injected into the JAX-RS resource using the @Inject annotation.  Lets assume the JAX-RS resource look like this:


Build and deploy the code to Liberty and at runtime, CDI will retrieve the EJB from JNDI and inject the EJB into the resource after it's created.

Common Project Structure for WebSphere Liberty using Maven and Eclipse

I find myself creating a lot of Java EE projects that focus on JAX-RS running on WebSphere Liberty.  I've created a common project structure that works well for me and helps me to get new development efforts up and running quickly.  I've documented the initial Eclipse / Maven / Liberty setup in this post and this post.  Below is an overview of the project structure and how to create each sub-project.

Overview

I always start with five basic Maven projects:

1. project-parent -> This is the parent project that contains the parent Maven pom.xml.  In Eclipse this is a simple Maven project (i.e. using no archetype).
2. project-ejb -> This is a Maven project that represents the Enterprise Java Bean (EJB) project.  In Eclipse, this project is created using the IBM provided Maven archetype for EJB projects running on the Liberty profile.
3. project-view -> This is a Maven project that contains the "view" of the Model View Controller (MVC) pattern.  In Eclipse, this project is a simple Maven project (i.e. using no archetype).
4. project-rest -> This is a Maven project that represents the JAX-RS project.  In Eclipse, this project is also created using the IBM provided Maven archetype for web applications running on the Liberty profile.
5. project-ear -> This project is a Maven project that represents the Enterprise Archive (EAR).  In Eclipse, this project is an Enterprise Application Project that has been converted to a Maven project.

I replace the word project in the name of each Eclipse project to better reflect the development effort's goal or scope.  I use project here just for demonstration purposes.  For example, if the development effort's goal was to persist user data, I may name the projects user-parent, user-ejb, user-view, user-rest and user-ear.

Why this Structure?

Why do I use this structure?  Why is the EJB project separate from the JAX-RS project?  Wouldn't the EAR project be unnecessary if the EJB, JAX-RS and view projects were combined?   These are good questions.  I've found this structure to be simple but also very adaptable to expanding the scope of the overall development effort.  

For example, if a new requirement calls out the need for web services or message queues for asynchronous processing, I can quickly add a new project to the list above that deals specifically with the implementation of JAX-WS and / or JMS as an additional access point to the business logic.  Since all of the business logic is contained in the EJB project, my components are already separated and I can quickly respond to this requirement.  If the EJBs and JAX-RS code were combined into a single project, then I would be forced to either refactor the project into two projects or add the new logic to the existing project.  Keeping each project focused on a specific aspect of the overall implementation is a cleaner approach in my view.

Step by Step Setup

The rest of this post goes through the step by step setup for each project and how to link each project to the parent project and each other in some cases.  The resulting projects are available in GitHub.  I'm continually tweaking the base projects as I run into issues or new feature become available.  Check GitHub for the most recent version of the file demonstrated below.

project-parent

As stated above, this project is a simple Maven project that contains the parent pom.xml.  This project is used to facilitate a single place to store common Maven configurations are well as providing a Maven reactor build.  To create this project in Eclipse:

1. Go to New > Project and select Maven > Maven Project from the options provided and click the Next button.
   
   
   
   
   
2. Select the Create a simple project (skip archetype selection) checkbox and click the Next button.
   
   
   
   
   
3. Provide the required Maven parameters in the dialog.  Make sure the Packaging selection is set to pom.
   
   
   
   
   
4. Click the Finish button.

The resulting project will be crest in the Eclipse workspace. I usually delete the src folder since it serves no purpose at the moment, but this is optional.

The next step is to update the pom.xml file in this project.  This pom will contain common build configurations, dependencies and properties as well as a list of modules representing the Maven sub-projects that should be built with this project.  At the bare minimum, this file should look like this (notice the Maven dependency for the Liberty runtime and the Java version settings in the compiler plugin):

Notice the Maven dependency for the Liberty runtime and the Java version settings in the compiler plugin.  These settings will automatically be applied to all of the sub projects linked to this parent.

project-ejb

The next project is the EJB project.  This project is created using an IBM provided Maven archetype for EJB projects running on the Liberty profile.  To create this project:

1. Go to New > Project and select Maven > Maven Project from the options provided and click the Next button
   
   
   
   
   
2. Click the Next button.
   
   
   
   
   
3. Filter the list of archetypes to just those provided by IBM using the selection box at the top of the dialog.  Select the ejb-jee6-liberty archetype from the list.  Click the Next button.
   
   
   
   
   
4. Provide the required Maven parameters in the dialog.  Click the Finish button.
   
   
   
   
   

A new project will be created in your workspace ready for EJB development with a Maven pom geared toward the building and packaging of EJBs.  Some changes are required to the project pom.xml to link to the parent project and remove the redundant configurations.  The EJB project's pom.xml should look like this initially and then can be further customized as development proceeds:

project-view

As stated above, this project is also simple Maven project.  This project will contain the view provided by the JAX-RS project. To create this project in Eclipse:

1. Go to New > Project and select Maven > Maven Project from the options provided and click the Next button.
   
   
   
2. Select the Create a simple project (skip archetype selection) checkbox and click the Next button.
   
   
   
3. Provide the required Maven parameters in the dialog.  Make sure the Packaging selection is set to jar.
   
   
   
   
   
4. Click the Finish button.

A new project will be created in your workspace ready for development.  Some changes are required to the project pom.xml to link to the parent project and remove the redundant configurations.  The project's pom.xml should look like this initially and then can be further customized as development proceeds:

project-rest

The JAX-RS project is also created using an IBM provided Maven archetype.  To create this project:

1. Go to New > Project and select Maven > Maven Project from the options provided and click the Next button
   
   
   
   
   
2. Click the Next button
   
   
   
   
   
   
3. Filter the list of archetypes to just those provided by IBM using the selection box at the top of the dialog.  Select the webapp-jee6-liberty archetype from the list.  Click the Next button.
   
   
   
   
   
   
   
   
4. Provide the required Maven data to the dialog.  Click the Finish button.
   
   
   
   
   
   

A new project will be created in your workspace setup in Eclipse for dynamic web development with a Maven pom geared toward the building and packaging of WAR files.  Some changes are required to the project pom.xml to link to the parent parent, remove the redundant configurations, configure the build of a skinny WAR file and link the EJB and view projects as dependencies.  Initially the JAX-RS project's pom.xml should look like this:

project-ear

The final project is the EAR project.  This project is created using the Enterprise Application Project provided by Eclipse and then it is converted to a Maven project using the Maven plugin.

1. Go to New > Project and select Java JEE > Enterprise Application Project from the options provided. Click the Next button
   
   
   
   
   
2. Provide the project details.  Make sure you choose Liberty for both the Target runtime and Configuration options. Click the Finish button.
   
   
   
   
   
3. Once the project is created and available in the workspace, right click the project and select Configure > Convert to Maven Project.
4. Provide the required Maven details.  Make sure the Packaging is set to ear.  Click the Finish button.
   
   
   
   
   

This process will create a Maven pom.xml for the project that is geared toward building and packaging EAR files.  This pom.xml file needs to be modified to link it to the parent project, remove redundant configurations, include the EJB, JAX-RS and view projects and dependencies.  Initially the resulting pom.xml should look like this:

Clean up

Eclipse might be reporting errors on the projects.  The most common error usually states that the Maven project configuration is out of date.  To fix this, right click on each project and select Maven > Update project...  Choose the project(s) reporting the error in the list at the top of the dialog and then click the OK button.

The other error you might see is from the EJB project reporting that it must contain at least 1 EJB.  This error will disappear once you start development.

Building

The final step is to run a test build.  This can be run from within Eclipse or using the Maven command line tool.  From within Eclipse, right click on the parent project and select Run As... > Maven Build...  This will open a dialog.  For the Maven goals enter clean install and then click the Run button.

From the Maven command line, open a command prompt or terminal window and make sure the current directory is the root folder of the parent project (project-parent in this example).  Execute mvn clean install.

The result of either method should be a successful build.  You should see the Maven Reactor Summary of the bottom of the build report stating that all 5 projects were build successfully

Using WebSphere Liberty Maven Archetypes

In a previous post I outlined how I setup Eclipse Luna and Maven for development with WebSphere Liberty.  In this post, I would like to explore the Maven Archetypes that are provided for the Liberty Profile by IBM.

When you install the WebSphere Liberty Profile Developer Tools from the Eclipse Marketplace, the location of the IBM provided Maven Archetypes is automatically added to the list of Archetype Catalogs in the Eclipse Maven preferences.  This can be verified by accessing Window > Preferences > Maven > Archetypes.  In this dialog, you should see something along the lines of this:

I have highlighted the IBM entry in the screen shot above.

IBM has provided three primary Archetypes; EJB, OSGi and WebApp (Portlet is there as well).  For each of these, there is a JEE 5 and JEE 6 version for both the Liberty Profile and WebSphere proper.  To use these Archetypes to create a new project, simply:

1. Access File > New > Project... and scroll down to and expand the Maven entry.  
2. Choose the Maven Project entry from the list.
3. Click the Next button.
4. On the New Maven Project dialog, click the Next button.
5. From the Catalog selection menu, select the IBM catalog.

At this point, the new project dialog should look something like this:

To complete the process, select the Archetype that best meets the need of the project and click the Next button.  On the final screen, enter the Maven specifics of the project and click Finish.

If you followed the instructions from my previous post, your project should be created successfully using the dependency created by the pom builder.

Using Eclipse Luna and Maven with WebSphere Liberty v8.5.5.3

I seem to have trouble getting the development tools that are available in the Eclipse Marketplace for WebSphere Liberty to work with Eclipse Luna and Maven on Fedora 20.  The issues and errors I'm seeing might exist on any OS, but I haven't tried on anything but Fedora.  The server management aspect of the development tools works great.  Creating servers, starting / stopping servers, deploying applications, etc...  all works without issue.  When I want to create a Maven project using the provided archetypes is where I start to run into trouble.  This post outlines the steps I've taken to get around these issues.

Tools

First, I installed the following:

• WebSphere Liberty Profile (v8.5.5.3)
• Eclipse Luna for JEE Developers (comes with the maven plugin)
• Maven (v3.2.3)

Maven Configuration

Next I configure Eclipse to use the version of Maven I just installed instead of the bundled version by:

1. Going to Window > Preferences > Maven > Installations.  
2. Clicking the Add... button.
3. Setting the Installation type to external.
4. Clicking the Directory button and browsing to the location where I installed Maven.
5. Clicking OK.

The resulting dialog should look something like this:

Click Finish to complete the configuration.  Back on the Maven Installation Preference dialog, I select the entry I just created.

Finally, I click OK to apply the changes and close the Preferences window.

WebSphere Liberty Profile Developer Tools

Next I install the WebSphere Liberty Profile Development Tools from the Eclipse Marketplace by:

1. Clicking on Help > Eclipse Marketplace...
2. Typing into the Find field a search of Liberty.
3. Scrolling down the result list to the entry titled IBM WebSphere Application Server Liberty Profile Developer Tools for Luna.
4. Clicking the Install button.
5. When enabled, clicking the Confirm button.
6. Accepting the license agreement and clicking Finish.

The plugin installs and prompts me to restart Eclipse and I click the Yes button to execute.  

Note: Sometime I get an error during the installation.  When this happens, I delete the artifacts.xml file from within the installation directory of Eclipse and restart Eclipse using the -clean command line argument.

Configuring JEE Maven Project Settings

I like to use the maven directory structure for all of my projects.  This structure is not the default structure used by Eclipse though and can cause issues with dynamic web projects.  This can be updated byt:

1. Accessing Windows > Java EE > Maven > Maven Project Settings.
2. Click the Set all Maven values button at the top of the screen.
3. Click the Apply button at the bottom of the screen.

New JEE projects will now be created using the default maven directory structure.

Configuring settings.xml for Maven

Update:  This feature now working with the latest release of the plugin.  Execute the following steps:

1. From within Eclipse, access Windows > Preferences > Java EE > Maven > Maven Repository Initialization.
2. Click on the configure button.

This will create / update your local setting.xml file to include the IBM Maven repository.

This is where I usually start running into issues.  The first step is to configure my Maven settings.xml file with the location of the IBM Maven repository for WebSphere.  I should be able to access Windows > Preferences > Java EE > Maven > Maven Repository Initialization and have the Liberty plugin configure my settings.xml for me, but this fails with the following error:

Since this steps fails in Eclipse, I do it manually by:

1. Coping the global settings.xml from the conf directory of the Maven installation directory to my user's .m2 directory.  (For example:  cp /opt/apache-maven-3.2.3/conf/settings.xml ~/.m2/.)
2. Opening my settings.xml is a text editor.
3. Add the following XML snippet to the <profiles> element:
   
4. Add was-dev-profile to the active profiles list:
   
5. Save the changes and close the text editor.

Populating My Local Repository

The Liberty plugin comes with Maven POM files that can be used to populate a user's local Maven repository with the libraries that are installed with the Liberty profile.  I use these POM files to populate my local repository by:

1. Using a terminal window to access the Liberty plugin's installation directory within the Eclipse installation directory (For example: /opt/eclipse/plugins/com.ibm.etools.maven.javaee.core_1.1.1.v20140602_0512).
2. Using the terminal window to locate the Liberty plugin installer pom.xml (For example: /opt/eclipse/plugins/com.ibm.etools.maven.javaee.core_1.1.1.v20140602_0512/resources/scripts/Liberty 8.5.5 Fix Pack 1 Plugins installer)
3. Using Maven to execute the pom.xml in this directory.  I have to pass a property containing the installation directory of Liberty to Maven. (For example: mvn install -DserverInstallationFolder=/opt/IBM/WebSphere/Liberty)

Unfortunately, pom files are only provide in support of v8.5.5.0 and v8.5.5.1.  The maven build resulted in an error for me with v8.5.5.3 because the names of the individual jars files provided by Liberty include the version number and that version number can change with each release.  To get around this issue, I created a simple Java program that will build POM files for me based on the installed version of Liberty.  I have the code for the tool available on GitHub with instructions on how to use it:

https://github.com/tglawless/jee/tree/master/was-pom-builder