Friday, December 4, 2015

GlassFish Jersey JAX-RS REST Service Client with Cookies and HTTP Proxy Example

Working with JAX-RS, I found most people tend to focus on the server side of things.  But there is a client side as well which doesn't involve JavaScript.  I found it difficult finding client-side examples which involved some more advanced, yet very common requirements, such as how to use an HTTP proxy for your client and how to send cookies to the server.  This article consolidates my research into one example.  As I bring in more requirements, I'll update this example.

System Requirements
This example was developed and run using the following system setup. If yours is different, it may work but no guarantees.
  • jdk1.8.0_65_x64
  • NetBeans 8.1 version 6.3
  • Maven 3.0.5 (Bundled with NetBeans)
  • Jersey 2.22.1 (From GlassFish)
The rest of the software dependencies can be found in this article.


Git code example from GitHub

One of the first challenges is trying to determine which version of JAX-RS you're working with. Jersey is the reference implementation of JAX-RS, and there are a lot of examples showing how to do things with Jersey.  But Jersey has gone through a lot of changes.  Version 1.x is "Sun Jersey" then version 2.x was completely repackaged as "GlassFish Jersey".  As Jersey has evolved, a lot of breaking changes have occurred, so examples may not work anymore.

This is my Maven dependency configuration for Jersey 2.22.1.

To create a JAX-RS client, the first thing you need is an instance of  Getting one of these is not as easy as you might think. I probably ran across a half dozen different ways of getting a Client instance, so it's very confusing.  Listing 1 shows my ClientFactory.  Let's take a look at it in more detail.

Listing 1: ClientFactory

import org.glassfish.jersey.apache.connector.ApacheConnectorProvider;
import org.glassfish.jersey.client.ClientConfig;
import org.glassfish.jersey.client.ClientProperties;

public class ClientFactory {
    public static Client create() 
        ClientConfig config = new ClientConfig();
  , "http://localhost:7777");        
        ApacheConnectorProvider provider = new ApacheConnectorProvider();
            config.connectorProvider(new ApacheConnectorProvider());        
        Client client 
            = ClientBuilder.newClient(config);
        return client;

Let's take a look at line 23 first. ClientBuilder.newClient(config) is a standard way to create a Client object.  Line 23 only uses classes from the JAX-RS API.  The config object however, created on line 12 is a Jersey-specific implementation of a JAX-RS interface.  Line 14 is where we set a property in the config object to specify the HTTP Proxy.  This configuration, however, doesn't do anything by itself because the default JAX-RS implementation doesn't understand HTTP Proxies.  This is why in the pom.xml we have a dependency on jersey-apache-connector.  This allows the defaults to be overridden with Apache HttpClient.  Lines 17-20 create an ApacheConnectorProvider and put it in the config object.  Without the ApacheConnectorProvider, the HTTP Proxy won't be used.  Now that we have a Client object, Let's see how to use it.

main(String [] args) 
Getting a  Client object was the first step. Now let's use the  Client object to make a REST-ful service call.  The main() application in listing 2 does this.

Listing 2: A main(String [] args) application


public class Main {
    public static void main(String[] args) throws Exception {
        Client client 
            = ClientFactory.create();
        WebTarget target = client
        Response response = target
            .header("User-Agent", "Java/1.8.0_65)
        System.out.printf("Response: %s%n%n", response);        
        System.out.printf("AllowdMethods: %s%n%n", response.getAllowedMethods());
        System.out.printf("Class: %s%n%n", response.getClass());
        System.out.printf("Cookies: %s%n%n", response.getCookies());
        System.out.printf("Date: %s%n%n", response.getDate());
        System.out.printf("Entity: %s%n%n", response.getEntity());
        System.out.printf("EntityTag: %s%n%n", response.getEntityTag());
        System.out.printf("Headers: %s%n%n", response.getHeaders());
        System.out.printf("Language: %s%n%n", response.getLanguage());
        System.out.printf("LastModified: %s%n%n", response.getLastModified());
        System.out.printf("Length: %s%n%n", response.getLength());
        System.out.printf("Links: %s%n%n", response.getLinks());
        System.out.printf("Location: %s%n%n", response.getLocation());
        System.out.printf("MediaType: %s%n%n", response.getMediaType());
        System.out.printf("Metadata: %s%n%n", response.getMetadata());
        System.out.printf("Status: %s%n%n", response.getStatus());
        System.out.printf("StatusInfo: %s%n%n", response.getStatusInfo());
        System.out.printf("StringHeaders: %s%n%n", response.getStringHeaders());
        System.out.printf("hasEntity: %b%n%n", response.hasEntity());
        System.out.printf("readEntity(String): %s%n%n", response.readEntity(String.class));

On lines 8-9 I use my custom ClientFactory to get a Client object.  From the Client object, the next step is to get a WebTarget.  Lines 11-14 show this.  The target() method call is typically the base URL and the path() method call adds path information to the base.  The WebTarget is then used to make the call and get the response, and this can be done in many different ways.  In my example, I make the call and get the response on lines 16-23.  First it uses the request() method to configure what type of data the request is being sent to the server, then the accept() method configures what type of data the server will be sending back to the client.  The header() method is then used to override the default value for "User-Agent". Proxies are usually sensitive to the "User-Agent" header and will reject requests from JAX-RS clients using the default value.  So change the "User-Agent" value to something your proxy will accept.  Next, the cookie() method calls add cookies to the request.  Finally the get(Response.class) method call makes an HTTP GET call to the server and wraps the response from the server into a Response object.  Fun!

The rest of the code is just logging what's in the Response object.

That's it, enjoy!

NGloom. (2015, May 15). How to add a http proxy for Jersey2 Client. Retrieved December 3, 2015 from

theotherian. (2013, August 11). setting up jersey client 2.0 to use httpclient, timeouts, and max connections. Retrieved December 3, 2015 from

Sunday, November 1, 2015

Payara/GlassFish DataSource JNDI Lookup Reference


This article is more of a reference than a how-to.  Setting up a JDBC Connection Pool and JDBC Resource in Payara/GlassFish is easy. However remembering how to do the JNDI lookups from your application is a little harder because, let's face it, we don't have to do it that often so its easy to forget.  So here is a reference.

Create "JDBC Connection Pool"

The first thing you'll need to do is create a "JDBC Connection Pool". As shown in Figure 1, Payara/GlassFish have a simple wizard for this. 

Figure 1: Wizard to start a new "JDBC Connection Pool"

PostgreSQL is my database of choice.  So during the setup I choose "Postgresql" and add the following configuration:

Datasource classname: org.postgresql.ds.PGSimpleDataSource

Remember, after creating a "JDBC Connection Pool", your application cannot use it because the pool has yet to be bound to JNDI.  To do the binding, let's look at the next step, which is to create a JDBC Resource.

Create "JDBC Resource"

This steps creates a JNDI binding for the "JDBC Connection Pool" so your application is able to perform a lookup and find it.  Payara/GlassFish again provides a nice simple wizard for you, and you start the wizard as shown in figure 2.

Figure 2: Wizard to start a new "JDBC Resource"

The Wizard can't get any simpler.  You need to supply a "JNDI Name"for the "JDBC Resource" and select a "JDBC Connection Pool" from the dropdown box.  That's it!  Well not quite.  Let's look at the "JNDI Name" value in a bit more detail.

JNDI can get really confusing.  In general, JNDI is a tree-like structure with a number of special contexts (java:global, java:app, java:module, java:comp) and some special paths (java:comp/env).  It gets even more confusing because in some cases a context - like java:comp/env - is assumed and prepended for you but in other cases it's not. So let's consider what "JNDI Name" really means for a "JDBC Resource" by looking at some examples.
JNDI Name@Resource(lookup = "%s")
"EmailDS""EmailDS"SUCCESSLookup and "JNDI Name" match!
"EmailDS""/EmailDS"FAILSLookup does not match "JNDI Name"!  Lookup name has a leading "/" character!
"EmailDS""java:global/EmailDS"FAILSLookup does not match "JNDI Name"! Payara/Glassfish does not prepend the global context when binding to JNDI.
"EmailDS""java:comp/env/EmailDS"FAILSLookup does not match "JNDI Name"! The "java:comp/env" context and path is application specific.  We'll cover how to do this application specific configuration below.
"jdbc/app/EmailDS""jdbc/app/EmailDS"SUCCESSLookup and JNDI Name match!
"jdbc/app/EmailDS""/jdbc/app/EmailDS"FAILSLookup does not match "JNDI Name"!  Lookup name has a leading "/" character!
"jdbc/app/EmailDS""java:global/jdbc/app/EmailDS"FAILSLookup does not match "JNDI Name". Payara/Glassfish does not pre-pend the global context when binding to JNDI.
"jdbc/app/EmailDS""java:comp/env/jdbc/app/EmailDS"FAILSLookup does not match "JNDI Name". The "java:comp/env" context and path is application specific.  We'll cover how to do this application specific configuration below.

So, if your application has a Payara/GlassFish "JDBC Resource" and your code is performing a direct JNDI lookup, the above table should give you enough information to figure out what will succeed and what will fail.  When you create the "JDBC Resource", Payara/GlassFish will use the "JNDI Name" you give as the exact path in the JNDI tree to make the binding.  Payara/GlassFish does not prepend any contexts or paths onto the name you give.  So your code needs to do a lookup on the exact "JNDI Name" value.

Now you may be asking yourself, what about JNDI redirection?  It's always good practice to have your application JNDI lookup names to be decoupled from the real JNDI locations of the resources.  In other words, I want my application to lookup "java:module/env/jdbc/MyDS" but I want that lookup to be redirected/mapped to the real JNDI location - "EmailDS" - which in Payara/GlassFish is the "JNDI Name" value of the "JNDI Resource".  We'll take a look at how to do this next.

Redirection with web.xml and glassfish-web.xml

The web.xml and glassfish-web.xml files are used to accomplish JNDI redirection.  In general, inside of web.xml you specify what JNDI lookup your application will use to lookup a resource and then inside of glassfish-web.xml you map your application's lookup with the "JNDI Name" of the "JDBC Resource".  But with multiple context rules and automatic prepending of contexts, this too can get confusing so let's take a look at some examples.

Listing 1 shows a fully-qualified example.  In this example, the web.xml says the JNDI lookup used in your application is fully-qualified to "java:comp/email/database".  The glassfish-web.xml says "java:comp/email/database" is mapped to the real JNDI resource "EmailDS".

Listing 1: Fully-qualified redirect example



For this example, let's consider some application lookups and see what happens.
@Resource(lookup = "%s")
"java:comp/email/database"SUCCESSLookup matches what's in web.xml.  Successful redirection to real JNDI resource "EmailDS"
"java:comp/env/email/database"FAILSLookup does not match what's in web.xml!  Lookup has an "/env/" path which is not in web.xml.  Redirection fails.
"java:module/email/database"SUCCESSLookup does not match what's in web.xml, however, lookup succeeds because in a WAR the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions. Successful redirection to real JNDI resource "EmailDS"
"EmailDS"SUCCESSRedirection avoided altogether, this is a direct lookup of the real JNDI resource.

Listing 2 shows a relative example.  In this example, the web.xml says the JNDI lookup used in your application is the relative name "Puppy".  The glassfish-web.xml says the relative name "Puppy" is mapped to the real JNDI resource "EmailDS".

Listing 2: Relative redirect example




Now the big question is, this JNDI lookup name is relative to what?  Well, in this case it is relative to "java:module/env" or "java:comp/env" because remember in a WAR file the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions.  These contexts are automatically prepended onto your relative name "Puppy".  Let's consider some application lookups and see what happens.
@Resource(lookup = "%s")
"java:comp/env/Puppy"SUCCESSThe web.xml says "Puppy" which get's automatically prepended with "java:comp/env/".  Successful redirection to real JNDI resource "EmailDS"
"Puppy"FAILSLookup matchs what's in web.xml, but lookup forgot about the automatic context prepending.  Redirection fails.
"java:module/env/Puppy"SUCCESSThe web.xml says "Puppy" which get's automatically prepended with "java:comp/env/".  But remember, in a WAR the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions. Successful redirection to real JNDI resource "EmailDS"
"EmailDS"SUCCESSRedirection avoided altogether, this is a direct lookup of the real JNDI resource.

So far, all these examples assume your application doing JNDI resource lookups itself.  However what if you are using a framework like JPA and the lookup of the JNDI resource is done for you?  What do you do then?  We'll look at this next.

A note about JPA persistence.xml
If you are using JPA, you specify the JNDI lookup using one of the "jta-data-source" tags like this:


However, the big question is what JNDI lookup string to use for this tag's value?  Well as far as I can make out, JPA does not use any of the redirection configured in web.xml and glassfish-web.xml.  Which means the value for <jta-data-source> must be the exact Payara/GlassFish "JNDI Name" value of the "JDBC Resource".  This of course couples the JPA configuration to the Payara/GlassFish EE server which may not be desirable.  Hopefully, this will be something the JPA expert group addresses in the next JPA spec update.

A note about @DataSourceDefinition
Java EE has the @DataSourceDefinition annotation which allows your application to create a data source by itself instead of relying on an EE server administrator to create the data source prior to your application's deployment.  This cuts down on some administration steps.  It has its advantages and disadvantages which I won't go into.  But what I do want to look at is how JNDI lookups work with a data source created by the @DataSourceDefinition annotation.

Redirection with web.xml and glassfish-web.xml
The @DataSourceDefinition annotation does not support redirection by web.xml and glassfish-web.xml.  If you think about it, this makes sense.  The @DataSourceDefinition is hard-coded in your source code so you know exactly what JNDI Name you used to create it so there is no need to redirect since the value is already in your code.
JPA data source 
There seemed to be a debate on whether or not @DataSourceDefinition support the JPA persistence.xml file.  The last word of the debate states it should be supported, that the JSR specification will be updated to make it more clear, and that a test will be added to the TCK to verify it. 
At this time (03 Nov 2015), in Payara/GlassFish, the @DataSourceDefinition annotation does not support the JPA persistence.xml file.  In other words, you cannot use the JNDI Name you used for the @DataSourceDefinition annotation in the JPA persistence.xml file.  I will continue to monitor this and will make an update to this article if anything changes.
Listing 3 shows a fully-qualified example.  In this example, the @DataSourceDefinition annotation has a JNDI Name which is fully qualified.  This exact, fully-qualified name, needs to be used in lookups in order for the lookup to succeed.

Listing 3: Fully-qualified @DataSourceDefinition example 
    className = "org.postgresql.ds.PGPoolingDataSource",
    url = "jdbc:postgresql://localhost:5432/email",
    user = "elephant",
    password = "jafj2r@#Rhh"

For this example, let's consider some application lookups and see what happens.
@Resource(lookup = "%s")
"java:global/jdbc/MyApplicationDS"SUCCESSLookup matches what's in the @DataSourceDefinition#name annotation.
"java:global/env/jdbc/MyApplicationDS"FAILSLookup does not exactly match what's in the @DataSourceDefinition#name annotation.  The lookup has an "/env/" path which is not in the annotation

Listing 4 shows a relative example.  In this example, the @DataSourceDefinition annotation has a JNDI Name which is relative path.

Listing 4: Relative @DataSourceDefinition example

    className = "org.postgresql.ds.PGPoolingDataSource",
    url = "jdbc:postgresql://localhost:5432/email",
    user = "elephant",
    password = "jafj2r@#Rhh"

Now the big question is, this JNDI lookup name is relative to what?  Well, in this case it is relative to "java:module/env" or "java:comp/env" because remember in a WAR file the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions.  These contexts are automatically prepended onto your relative name "MyApplicationDS".  Let's consider some application lookups and see what happens.
@Resource(lookup = "%s")
"java:comp/env/MyApplicationDS"SUCCESSThe @DataSourceDefinition says "MyApplicationDS" which get's automatically prepended with "java:comp/env/".  "
"MyApplicationDS"FAILSLookup matches what's in @DataSourceDefinition, but lookup forgot about the automatic context prepending.  So the lookup fails.
"java:module/env/MyApplicationDS"SUCCESSThe @DataSourceDefinition says "MyApplicationDS" which get's automatically prepended with "java:comp/env/".  But remember, in a WAR the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions.

Finaly, listing 5 shows a special condition of a fully-qualified example.  In this example, the @DataSourceDefinition annotation has a JNDI Name which is fully qualified, but to special "java:comp/env/" context and path.

Listing 5: Special case fully-qualified @DataSourceDefinition example 
    className = "org.postgresql.ds.PGPoolingDataSource",
    url = "jdbc:postgresql://localhost:5432/email",
    user = "elephant",
    password = "jafj2r@#Rhh"

For this example, let's consider some application lookups and see what happens.
@Resource(lookup = "%s")
"java:comp/env/jdbc/WebAppDS"SUCCESSLookup matches what's in the @DataSourceDefinition#name annotation.
"java:module/env/jdbc/WebAppDS"SUCCESSLookup does not exactly match what's in the @DataSourceDefinition#name annotation.  The lookup uses the "module" context which is not in the annotation.  But remember, in a WAR the "java:comp" and "java:module" contexts are treated as the same thing for backward compatibility with previous EE versions.

That's it,

Wednesday, July 15, 2015

Begin and end index of a regular expression pattern matched string

This is a quick tip on regular expressions.  Nothing too exciting, but something I use often enough but can never remember so I always have to look it up.

The String.indexOf("match me") method is handy for finding the beginning index of some pattern within a String you want to match.  Combine this beginning index with "match me".length() and you can get the ending index as well.  This works for finding simple substrings, but what if the pattern is more complicated and needs a regular expression?  Let's take a look at the code in listing 1.

Listing 1: Simple pattern matching.
package pattern.matching;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PatternMatching {

    public static void main(String[] args) throws Exception {
        StringBuilder searchMe = new StringBuilder();
        searchMe.append(" package doctor;  ").append("\n");
        searchMe.append("name // comment").append("\n");
        searchMe.append("/* continue */").append("\n");
        searchMe.append("int yesterday = 9;").append("\n");
        System.out.printf("BEFORE\n------\n%s", searchMe.toString());
        final Pattern pattern = Pattern.compile("^ *package .*; *$", Pattern.MULTILINE);
        final Matcher matcher = pattern.matcher(searchMe.toString());

        if (matcher.find()) {
            System.out.printf("Start index: %d\n", matcher.start());
            System.out.printf("End index:   %d\n", matcher.end());
            System.out.printf("Match found: [%s]\n",;            
            searchMe.replace(6, 24, "I've been sad :(");
        } else {
            System.out.println("Matcher matched nothing! ");
        System.out.printf("AFTER\n-----\n%s\n", searchMe.toString());       
Listing 2: Output
 package doctor;  
name // comment
/* continue */
int yesterday = 9;

Start index: 6
End index:   24
Match found: [ package doctor;  ]

I've been sad :(
name // comment
/* continue */
int yesterday = 9;
Listing 1 shows the code for a simple regular expression pattern matching of a String.  The Matcher is looking for a simple pattern.  If found, the Matcher.start and Matcher.end methods are used to get the beginning and ending indices within the String.  The StringBuilder.replace method is then used to replace the matched pattern with another String.  As you can see in Listing 2, the output of the application shows the before state, the matcher information, and the after state.

So pretty simple :)

Tuesday, June 23, 2015

Bamboo, maven-release-plugin, public/private key SSH access to SVN, password access to Nexus


Bamboo is great for performing builds.  The maven-release-plugin is great at releasing new versions of your software. SVN is a great source code repository. SSL public/private keys are great for keeping everything secure, and Nexus is great for Maven artifacts.  What's not so great is trying to get all these things working together!  What we'll look at in this blog is how to configure Bamboo build steps for both the repository host and the Maven configuration. Also, we'll look at how to configure your project's pom. Let's start with the Bamboo repository host build step.

Bamboo repository host build step

First, you need to configure the Bamboo repository host build step so Bamboo can checkout your source code:

Figure 1: Repository host build step

Looking at figure 1, the repository host setup is pretty easy: 

The URL.  It will need to be in the form "svn+ssh" instead of "https". 

The username.  It's a good idea to create an account specifically for bamboo to use. 

The authentication big deal. 

A variable reference to the fully-qualified location of the SSL key.

Next let's take a look at the Maven configuration build step.

Maven configuration build step

Figure 2: Maven configuration build step
Let's take a look at this configuration one field at a time.

The version of Maven to use for this build. I did this research using 3.0.5.  No guarantees other versions of Maven will work.

The Maven goal to perform along with some additional attributes.

--batch-mode release:clean release:prepare release:perform
This runs the release plugin in batch mode so there is no user interaction and all defaults are used.

-s /home/bamboo_builder/.m2/bamboo_builder-settings.xml
This configures Maven to use a specific settings file.  In most cases the same Maven settings will be used for all builds in your organization. But, if you have builds which require unique settings, this is how to configure which settings file to use.  The main purpose of this file is to contain the username and encrypted password to access Nexus  (Maven Encryption, 2015, June 21), which will look something like listing 1.

Listing 1: Nexus username & password in settings.xml


The version of Java to use.

The environment varibles for the build. This is most important field.  After much research, I found these values MUST BE CONFIGURED HERE (not in goals) otherwise the build will fail.

SVN_SSH="ssh -v -l bamboo_builder -i /home/bamboo_builder/.ssh/id_rsa"
This environment variable configures ssh to use the bamboo_builder user and the id_rsa private key when establishing an SSL connection with SVN.  Now, Maven itself has a number of different ways to configure a username and private key both within a settings.xml file and within the pom.xml for a project.  I tried them all and they all failed.  This was the only way I got it to work.

This configures Maven with a master password used to encrypt the other passwords in the settings.xml file (Maven Encryption, 2015, June 21).  Though not strictly necessary, it's good to have this file.  If you do have it, this is where you put the configuration for the build. Listing 2 shows what this looks like

Listing 2: Maven master password


If your project does not have unit tests, uncheck this box so the build won't fail.

Finally, your project's pom.xml needs a bit of special configuration so let's take a look at that next.

Project pom.xml

The project's pom.xml needs a couple configurations: The <scm> tag and the maven-release-plugin version.

First the <scm> tag needs to be configured so Maven knows where the project is located in SVN.  Listing 3 shows what this tag will look like. 

    NOTE: All 3 properties are needed...don't skip any!

Listing 3: The pom <scm> tag 


Next the maven-release-plugin version needs to be configured. The default version of the maven-release-plugin for Maven 3.0.4 has some bugs in it, most notibly when trying to use this configuration to perform mult-module reactor builds.  So your project pom.xml must be configured to use a more recent version of the maven-release-plugin.  Listing 4 shows this.

Listing 4: The maven-release-plugin version


Hopefully this fully documents everything that's needed.  Enjoy!

Maven Encryption. (2015, June 21). Retrieved June 23, 2015 from

Wednesday, June 10, 2015

Mocking properties of super classes in different packages for unit testing

Suppose I have the following reusable abstract class.
import org.apache.log4j.Logger;  
import javax.inject.Inject;
public abstract class AbstractPropertiesFile extends File {
  protected Logger log; 
  // . . .
Also suppose my application has a concrete implementation of this abstract class.
package org.ferris.application.preferences;
public class PreferencesPropertiesFile extends AbstractPropertiesFile{
// . . .
When unit testing PreferencesPropertiesFile, the challenge is to mock the protected Logger property of the super class.  It's a challenge because:
  1. The concrete class in in a different package than the abstract class
  2. The Logger property is being injected by CDI for you so there is no setter method.
Let's look at the first challenge.  A possible solution is to repackage my application and unit test to use the package, but this means moving the PreferencesPropertiesFile to a package which doesn't make much sense for it to be in. Now let's look at the second challenge.  Adding a setter method would solve it, but do you really want to add a method just for unit testing purposes?  Neither of these solutions seem right.

A better solution is for the unit test to set the property of the super class using reflection. Though I'm sure many would argue against this solution, I'm OK with it because let's face it, every framework nowadays is using reflection or byte code manipulation, or proxying.  So a little more won't hurt.

Here is how you would setup the unit test.
Logger logMock;
// . . .
public void someTest() {
    PreferencesPropertiesFile props = new PreferencesPropertiesFile ();
        Field logField = AbstractPropertiesFile.class.getDeclaredField("log");
        logField.set(props, logMock);
    // . . .

Wednesday, April 22, 2015

Apache 2 ProxyPassReverse URL Replacement

It is very common to use Apache virtual hosts as a proxy to get to other application servers running in your environment. I have such a setup with Jira for my open source projects.  I have Jira for my open source projects at this URL: This domain name gets resolved to my server, hits an Apache virtual host for that domain, then ProxyPasses the requests along to the Jira instance. The response from Jira gets ProxyPassReversed back through Apache and to the user's browser. This works fine, as long as links generated by the application are all relative.

Unfortunately, Jira generates some fully-qualified links which started with http://localhost:8080.  Once this fully-qualified link gets to the user's browser it obviously won't work.  To solve this problem I used a combination of different Apache directives to search through the response from Jira and replace any of the localhost URLs.  Let's take a look.

# Turn compression off in order for the Substitute to work.
RequestHeader unset Accept-Encoding
ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/
Substitute "s|http://localhost:8080||n"
# In order for the substitute module to work we have to add it to the filter chain.
FilterDeclare Substitute
FilterProvider Substitute SUBSTITUTE "%{REQUEST_URI} =~ m#^/#"
FilterChain +Substitute

The first thing we need to do is use RequestHeader and turn off compression (#2). If the response from Jira is zipped, we can't do any search and replace so the response needs to be plain text.  Next are the typical ProxyPass (#4)  and ProxyPassReverse (#5). These get the request to Jira and the response from Jira. Next we define a Subsitute (#6) for what we want to replace. You'll recognize this syntax from the sed command. Finally we have a filter chain to get the Substitute to run on the response (#8-10). The filter matches on the URI of the request made to Apache (#9), and is typically configured to the application's context.  In the example above, I have Jira running as the root context / which is why ProxyPass and ProxyPassReverse have http://localhost:8080/ and the FilterProvider matches the regular expression m#^/#.  If Jira was running on the "jira" context, the configuration would be ProxyPass and ProxyPassReverse with http://localhost:8080/jira and FilterProvider with the regular expression m#^/jira#.

So that's it.  put this into your Apache <VirtualHost>, restart Apache and you'll be good to go.

ArtemGr. (Oct 15, 2013). Apache 2.4 reverse proxy with URL substitution. Retrieved April 10, 2015 from


Unix find tip: Excluding files

Sometimes you want to find files on a Unix file system but exclude files either by specific name or by pattern.  The best way I found to do this is by using a combination of find and grep.  Let's take a look.

$ find . -type f | grep -P '^(.(?!Thumbs\.db))*$'

This example uses the find command in the current directory (.) and limits the search to just files (-type f) instead of both files and directories. The result is then piped to grep. The regular expression (-P '^(.(?!Thumbs\.db))*$')  filters out all results from the find command that end with Thumbs.db.

So this is a quick and easy way to exclud files by a specific name.  Next let's take a look at how to exclude files by pattern.

find . -type f | grep -P '^(.(?!\.ffs_db))*$'

This example uses a little more complicated regular expression (-P '^(.(?!\.ffs_db))*$') to filter all results from the find command that end with .ffs_db. This example is essentially exclude by file name extension.

Now what if you want to exclude multiple file names or file types?  Just pipe together more grep statements.

find . -type f | grep -P '^(.(?!Thumbs\.db))*$' | grep -P '^(.(?!\.ffs_db))*$' | grep -P '^(.(?!\.ffs_gui))*$'

In this final example, I am excluding files named Thumbs.db, files that end with .ffs_db and files that end with .ffs_gui.

Retrieved April 13, 2015 from


Wednesday, February 11, 2015

Determine JDK version from a *.class file

Sometimes you run into JVM class file compability issues and it's useful to know what JDK version the class file was compiled as.  Doing this is farily easy and involves using the javap command which comes bundled with the JDK. 

Suppose you have a class named org.ferris.util.CalendarTools. To determine the JDK version of this class you would do something like this:

$ cd $PROJECT_HOME/target/classes
$ javap -classpath . -verbose org.ferris.util.CalendarTools

The output from running javap will look something like this:

Compiled from ""
public class org.ferris.util.CalendarTools extends java.lang.Object
SourceFile: ""
. . .

minor version: 0
major version: 50

. . .
Constant pool:

The important part is "major version: 50".  Visit this wiki page - to translate what this number means.  You'll see that a version of 50 means "J2SE 6.0 = 50 (0x32 hex)".  So the CalendarTools class was compiled to a JDK 6 format.


Wednesday, January 21, 2015

Create Your Own Java Bean Validator with a Custom Element

The purpose of this article is to demonstrate how to do two things.  The first is how to create your own Java bean validator as specified by JSR 349: Bean Validation 1.1.  The second is adding your own custom element to this validator so as to effect or define the validator's behavior.

System Requirements
This example was developed and run using the following system setup. If yours is different, it may work but no guarantees.
  • JDK 1.7.0_11
  • Eclipse Luna
  • Maven 3.2.1 (Embedded with Eclipse)
Maven Dependencies
The following dependencies are needed in your pom.xml to work with bean validation:




What is Bean Validation
JSR 349: Bean Validation 1.1 is the Java standard allowing you to develop reusable constraints and validators to ensure your application's data meets its business requirements. This may sound complicated, but it's actually very simple. Suppose your application is required to get a user's email address before successfully registering them for a new account. Traditionally, a developer would need to manually code this business requirement. Using JSR 349, the same business requirement can be satisfied using a reusable @NotNull constraint from the bean validation framework. Listing 1 demonstrates this.

Listing 1: Validate user's email address is not null
public class User {
protected String email;
// class continues...

As you can see from listing 1 the @NotNull constraint and the JSR 349 Bean Validation framework are responsible for validating the email address.  Additionally, the @NotNull constraint has no specific ties to email address meaning it can be reused to validate a users first name, last name, date of birth, or whatever data your business requirements say the user must provide.

The bean validation framework is very powerful in that it's also extensible. @NotNull is a very common constraint and as such is provided by the framework. However your application will no doubt have very specific business requirements which the built-in constraints cannot handle. Let's look at an example of such a requirement and how we can build our own constraints and validators to handle it.

Specific Business Requirement
Suppose your application needs to interact with the computer's file system. The user must select a directory but in order to guarantee your application does not inadvertently modify any existing files, it's required that the directory the user selects must be completely empty. This is a good example of data validation that is very specific to your application and which the bean validation framework does not handle out of the box. Remember though the bean validation framework is extensible. It's possible to create a constraint and validator to satisfy this business requirement.  Let's first look at creating the constraint.

A bean validation constraint is a simple annotation. Listing 2 shows a @DirectoryIsEmpty validation constraint annotation we'll use to satisfy our application's business requirement.

Listing 2: DirectoryIsEmpty bean validation constraint
package org.ferris.validation.constraints;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import javax.validation.Constraint;
import javax.validation.Payload;
import org.ferris.validation.validator.DirectoryIsEmptyValidator;

   ElementType.TYPE, ElementType.ANNOTATION_TYPE
 , ElementType.METHOD, ElementType.FIELD
 , ElementType.PARAMETER, ElementType.CONSTRUCTOR })
@Constraint(validatedBy = { DirectoryIsEmptyValidator.class })
public @interface DirectoryIsEmpty {
    String message() default "{org.ferris.validation.constraints.DirectoryIsEmpty.message}";

    Class[] groups() default { };

    Class[] payload() default { };
    String[] excludes() default {};

Let's take a look at this constraint in detail.

#12 The @Target annotation defines what elements the @DirectoryIsEmpty can be put on.  In general, the annotation can either be put at the class-level, property-level, or parameter-level.  At the class-level, the validation occurs on the class as a whole. This is a way to validated properties which go together, like password and verifiedPassword properties need to be the same. At the property-level, the annotation can either go on the property or on the getter method for the property. At the parameter-level, the annotation goes on a constructor parameter or a method parameter. Typically the @Valid annotation is used at this level so the bean validation framework can validate properties before executing the constructor or method.

#17 The @Constraint annotation tells the bean validation framework which class is responsible for validating this constraint.  Here it defines the DirectoryIsEmptyValidator.class.

#19 @interface DirectoryIsEmpty is the standard way to define an annotation.

#20 The message element is required on bean validation constraint annotations. This element is used by the framework to determine what error message should be displayed if validation fails. You can hard code a plain text message, or, as is seen here, enter a resource bundle key as "{key_value}". By convention, the key value is the fully-qualified-class-name + ".message". The bean validation framework will look in the class path for a file.  This file is located at the root of the class path.

#22 The groups element is required on bean validation constraint annotations. This is used to group validation constraints together. For example, a field may have four validation constraints divided into three different groups. The @GroupSequence annotation can be used to define the sequence of the validation constraints.  This is helpful if a constraint validation needs to happen in a certain order.

#24 The payload element is required on bean validation constraint annotations, however it is not directly used by the bean validation framework itself. If a payload is present and a constraint violation occurs, the bean validation framework will put the payload into the ConstraintViolation#ConstraintDescriptor object for later use. If a payload is not present, the bean validation framework puts nothing into the object. A payload is a way to pass additional information about the constraint violation to the UI layer (or to any code) responsible for handling the violation. For example, a severity can be assigned to the payload to change the alerting level handling the violation.

#26 The excludes element is custom to this annotation. Just like any annotation, you are able to create your own custom elements in order to pass additional information to the validator to customize the validation. In this example, the excludes element is a String[] and it is used to define the names of directories which are excluded from the constraint validation. For example, suppose you have @DirectoryIsEmpty(excludes={"foo", "bar"}). At validation, the directory will NOT be checked if the name of the directory is either "foo" or "bar".

A constraint annotation is only the first part to creating your own bean validator. As seen on line #17, a class to do the validation is needed. In this example it is DirectoryIsEmptyValidator.class.  Let's take a look at this class next.

A validator class is the next piece you need to creating your own bean validation after creating the validation constraint annotation.  The annotation is used on whatever class, property, or parameter you want to validate. The validator class is responsible for doing the actual validation. Given our @DirectoryIsEmpty validation constraint annotation, listing 3 shows its validator

Listing 3: DirectoryIsEmptyValidator validator
package org.ferris.validation.validator;

import java.util.Arrays;
import java.util.List;
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import org.ferris.validation.constraints.DirectoryIsEmpty;

public class DirectoryIsEmptyValidator 
implements ConstraintValidator< DirectoryIsEmpty, File > {

 private List< String > excludes;
 public void initialize(DirectoryIsEmpty arg0) {
  String [] strarr = arg0.excludes();
  if (strarr == null) {
   strarr = new String[]{};
  excludes = Arrays.asList(strarr);

 public boolean isValid(File file, ConstraintValidatorContext context)
  if (excludes.contains(file.getName())) {
   return true;
  File [] files = file.listFiles();
  if (files != null && files.length > 0) {
   return false;
  } else {
   return true;

Let's take a look at this validator in more detail.

#11 Here we see the class implements the ConstraintValidator interface with the specific generics being DirectoryIsEmpty, and FileDirectoryIsEmpty obviously refers to the @DirectoryIsEmpty validation constraint annotation. File defines the @DirectoryIsEmpty annotation must be put on a class that extends File or on a File property or parameter. This of course make sense because our business requirement states the directory picked by the user must be empty if it is to be valid. Directories in Java are represented by the File object.

#13 This property will be used to hold a list of directory names excluded from the validator.

#16 The initialize method is part of the ConstraintValidator interface and can be overridden to do custom initialization of the validator.

#17 Here the excludes() method is called to get the String[] holding the names of the directories to exclude from validation. The excludes element may or may not be defined so the validator must handle both cases.  If the excludes element is defined and the excludes() method call returns a String[] of directory names to be excluded from validation, then the validator must ensure it does not validate those directories. If the excludes element is not defined and the excludes() method call returns nothing, then the validator should not exclude any directory from validation.

#25 The isValid method is part of the ConstraintValidator interface. This is where the magic happens. Code this method to perform any validation you need. Return true if valid, false otherwise.

#27 The code checks the excludes property to see if the list contains the name of the directory being validated. If the list does contain the name, then return true (#28) because that directory should be excluded from validation which means it is automatically valid.

#30 Use the File#listFiles method to get a list of all files and sub-directories. If there are files or sub-directories (#31) return false because the directory the user selected is not empty and fails the business requirement. Otherwise, return true (#34) because the directory the user selected is empty and this satisfies the business requirement.

You've learned how to create your own validation constraint annotation and its associated validator. You've also learned how easily the bean validation framework is extended and hopefully you recognize the great opportunities this gives you.

Bernard, Emmanuel. (2013, April). Bean Validation specification. Retrieved January 21, 2015, from

JSR 349: Bean Validation 1.1. (n.d.). Java Community Process. Retrieved January 21, 2015, from


Friday, January 9, 2015

Mocking System static void methods..config for Maven, JUnit, PowerMock, PowerMockito, and Mockito

I previously wrote about Mocking return values of static methods..config for Maven, JUnit, PowerMock, EasyMock, and Mockito. The previous article focused on the need to mock a static method which returns a value. This article is also about mocking static methods, but static void methods - methods that return no value. Why would you need to mock such a method? Well my unit test needs to verify that a static void method was being called.  Specifically I wanted to Mockito.times(1) verify my application was calling the following System static void method on the Thread class: 

My application's proper error handling depends on setting a default exception handler so it makes sense to have a unit test for it. Performing a Mockito.times(1) verify testing for this System static void method call however, has a number of challenges, including:
  1. It's a static method
  2. It's a static void method meaning it does not return a value
  3. It's a JVM System class
The purpose of this article is to show a simple JUnit code example to verify a call to a JVM System static void method such as Thread.setDefaultUncaughtExceptionHandler(eh).

System Requirements
This example was developed and run using the following system setup. If yours is different, it may work but no guarantees.
  • JDK 1.7.0_11
  • Eclipse Luna
  • Maven 3.2.1 (Embedded with Eclipse)
The rest of the software dependencies can be found in this article.

Maven POM dependencies
Listing 1 shows the Maven POM dependencies needed to run the unit test listed below.  From my research, these are the only dependencies you need.  

WARNING: If you do have JUnit or Mockito as direct dependencies, most likely you'll get at version mismatch and the unit tests will fail to run. They are pulled in as transitive dependencies of what's in Listing 1. 
Listing 1: Maven POM dependencies

Class Using a System static void method
Listing 2 shows a wrapper class which wraps the call to the System static void method Thread.setDefaultUncaughtExceptionHandler(eh). The reason for the wrapper class is described in the Mockito documentation which states such a wrapper class is required "If you need to mock classes loaded by the java system/bootstrap classloader (those defined in the java.lang or etc)." I called my wrapper class ThreadTools.

Listing 2: Java ThreadTools wrapper class
 * @author Michael Remijan @mjremijan
public class ThreadTools {
  public void setUncaughtExceptionHandler(UncaughtExceptionHandler handler) {

As you can see, ThreadTools is very simple. It doesn't add any overhead to your application to use this wrapper class and it is essential for the unit test to work properly. Now that we have a class to test, let's next take a look at what the unit test looks like.

Verifying a static void method in a unit test 
The goal of the unit test is to verify the System static void method Thread.setDefaultUncaughtExceptionHandler(eh)is actually called. In the Mockito world, verifing that a method has been called with certain parameter values is usually accomplished with code that looks like:

Mockito.verify(mockedObject, Mockito.times(1)).someMethod("param");

The above statement is used to verify that someMethod was called on the mockedObject only times(1) with exactly the "param" value passed to the method. We want to do something similary, only with a JVM System static void method, which makes it a little bit harder.
Listing 3 shows the Java source code for a very simple unit test which does exactly this. For this unit test you are going to be using a combination of PowerMockRunner, PowerMockito, and Mockito. Let's step through this unit test line by line.

NOTE: You'll be using PowerMockRunner, PowerMockito, and Mockito all at the same time, for sanity's sake, avoid using static imports! Static imports are a great convenience, but when mixing so many different technologies it get very hard to keep straight which methods are coming from which classes.

Listing 3: Java ThreadToolsTest class
import java.lang.Thread.UncaughtExceptionHandler;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.mockito.Mockito;
import org.powermock.api.mockito.PowerMockito;
import org.powermock.core.classloader.annotations.PrepareForTest;
import org.powermock.modules.junit4.PowerMockRunner;

public class ThreadToolsTest {
  public void testSetDefaultUncaughtExceptionHandleIsCalled() throws Exception {
    // Prepare

    // Mock
    UncaughtExceptionHandler handler
      = Mockito.mock(UncaughtExceptionHandler.class);
    // Test
    new ThreadTools().setUncaughtExceptionHandler(handler);
    // Verify

Let's take a look at this code in a bit more detail.

#9 @RunWith
We need to run the test with the PowerMockRunner, not the normal JUnit runner.

#10 @PrepareForTest
We need to prepare the wrapper class that uses the System static void method. This is important and easy to get confused. Do not prepare the System class, which in this example is Thread.class. You must prepare the wrapper class which is ThreadTools.class. To make the test easy, we created a wrapper class specifically for calling Thread.setDefaultUncaughtExceptionHandler(eh). In general, the class you must @PrepareForTest must be whatever class is making the System static void method call.

#12 PowerMockito.mockStatic(Thread.class)
Use PowerMockito to prepare the Thread.class for mocking.  Unlike normal mocking, this does not return a mock object, it just prepares Thread.class for mocking in the PowerMockito framework.

#18 Mockito.mock(UncaughtExceptionHandler.class)
This is a normal mock of the UncaughtExceptionHandler interface. Ultimately this mock should be passed to Thread.setUncaughtExceptionHander(eh) and  the goal of the unit test is to verify this has happened.

#22 new ThreadTools().setUncaughtExceptionHandler(handler)
This will now perform the test.  An instance of our wrapper class ThreadTools is created and its setUncaughtExceptionHandler(eh) method is called.  This in turn will call a "mocked" Thread.class.  After this test is performed, we should be able to verify the "mocked" Thread.class did get called.  We'll see this in the next lines.

#25 PowerMockito.verifyStatic(Mockito.times(1));
This tells the PowerMockito framework that it needs to verify that the class it statically mocked on line #15 (Thread.class) had a static void method called only 1 time.  But which method?  Look at the next like of code.

#26 Thread.setDefaultUncaughtExceptionHandler(handler);
The previously like, line #25 told PowerMockito to verify the static void method was called only 1 time. This line tells PowerMockito which method, which is setDefaultUncaughtExceptionHandler(eh).  Not only that, but it also tells PowerMockito that the parameter passed that to method should have been the handler object which is the mock of UncaughtExceptionHandler we create on line #18.

Mocking statics is not trivial, and mocking System static void method is even more tricky.  But PowerMockRunner, PowerMockito, and Mockito are powerful tools which make it possible. Put it all together with Maven and you have a good system to verifying your code base.

Using PowerMock with Mockito. (n.d.). Retrieved January 2015, from

Mocking system classes. (n.d.). Retrieved January 2015, from

Class Mockito. (n.d.). Retrieved January 2015, from

fatmind. (2014 May 4). powermock example. Retrieved January 2015, from