Navigating the Mount Everest of Java information

Java 8 Overview: Lambdas

2014-10-07T14:03:00.002-07:00

Probably one of the most requested features and biggest time saver in Java 8 are lambdas. Essentially, a lambda is a short hand way to create an anonymous inner class. Let's look at how we used to have to do an anonymous comparator for comparing the lower case result of strings in a list:

    Collections.sort(comparison, new Comparator<String>() {
        @Override
        public int compare(String o1, String o2) {
            return o1.toLowerCase().compareTo(o2.toLowerCase());
        }
    });

Even with this simple example you can see quite a bit of extra code you have to write just to put in the logic of comparing two strings in lower case. Now, in Java 8 with lambdas you can compress the previous statement to the following:

Collections.sort(comparison, (o1, o2) -> o1.toLowerCase().compareTo(o2.toLowerCase()));

Much simpler right?

Lambda requirements

There is basically a single requirement for an interface to be used as a lambda expression. The interface needs to be annotated with the @FunctionalInterface annotation. This annotations requires a single non default, non static method in the interface. This way, with only a single method available it's obvious what method should be called and what the parameters and return type are for the method call. When it comes to creating lambdas there are essentially two types, what I call simple lambdas and standard lambdas.

Simple Lambdas

Simple lambdas consist of a single expression where the result of that expression is returned. They don't require braces and you can also omit the return keyword as well. The following is an example of what one would look like:

Collections.sort(comparison, (o1, o2) -> o1.toLowerCase().compareTo(o2.toLowerCase()));

In these cases even more of the code that is unnecessary is removed to make the result even cleaner.

Standard Lambdas

You would use a standard lambda when your implementation requires multiple statements. In these cases you would enclose the statements within braces and you need to include the return statement for all return points. If you were to compare a list of users based on their last name then first name then the expression would look something like the following:

        Collections.sort(comparison, (User o1, User o2) -> {
            int compare = o1.getLastName().compareTo(o2.getLastName());
            return compare != 0 ? compare : o1.getFirstName().compareTo(o2.getLastName());
        });

As you can see above, when items become more complex you have to specify the object types (User o1, User o2 instead of just o1, o2 like for the simple setup), you have to use braces and a return statement.

Extra information

To cut the code necessary for working with lambdas even further Java 8 includes a set of the most common types of operations you'd perform in the java.util.function package. In there you'll find operations such as Functions for processing one property and returning a result, predicates that take in an argument and return a boolean result, and a whole host of other standard operations. They're used heavily by streams (more on that in a future blog post) and can easily be integrated in your code base.

Conclusion

While lambdas don't introduce a new programming archetype in the language they do greatly simplify the code you need to write (and thus read as well). Like annotations before them they help to make the code more concise and easier for others to work with and understand. Finally, albeit to a lesser extent, it shows that Java can still move with the times and incorporate current programming paradigms to help coders in other languages to relate to the code.

Java 8 Overview: Exact numerical methods and negative floor/mod methods

2014-08-15T10:01:00.000-07:00

Exact Numerical Methods

One of the lesser known features added to Java 8 is the addition of exact numerical methods to deal with MAX_VALUE/MIN_VALUE situations. Normally when you do arithmetic with integers or longs (floats and doubles work the same but you don't do much addition with them right? You use BigDecimal right? right?) and you go beyond their max value they just wrap around to MIN_VALUE and increase from there or decrease from MIN_VALUE to MAX_VALUE and decrease from there due to the bit shift of the first bit in a word (which designates a positive number from a negative number). The following code example and output shows how this works for int (long, float, and double work the same).

System.out.println("Max Value: " + Integer.MAX_VALUE);
System.out.println("Max Value + 1: " + (Integer.MAX_VALUE + 1));

try {
  System.out.println("This won't print: " + Math.addExact(Integer.MAX_VALUE, 1));
} catch (ArithmeticException e) {
  System.out.println("Exception since we overflowed Integer.MAX_VALUE");
}

Max Value: 2147483647
Max Value + 1: -2147483648
Exception since we overflowed Integer.MAX_VALUE

Negative Floor and Mod

The other arithmetic "fix" in this release deals with negative division and negative mod values. The way java is supposed to work is when you use the '/' symbol with integers and the result isn't exact then it's supposed to give you the first number less than the exact number. So if I were to do (4/3) then I'd get 1 since the actual answer is 1.33. With negative numbers this is off slightly. Instead of the next number down it gives you the next number up (heading for 0), basically the negative version of the positive result. Look at the following example.

System.out.println("Divide with negative numerator: " + -4 / 3);
System.out.println("Math.floorDiv() with negative numerator: " + Math.floorDiv(-4, 3));

Divide with negative numerator: -1
Math.floorDiv() with negative numerator: -2

In this example the old value is -1 (the mirror value for the positive result) but that isn't quite right, it's the next integer GREATER than the correct answer, not the next integer LESS THAN the answer so now with the new method you get the correct answer of -2.
Similar to the floor the mod value with negative numbers is also incorrect with the new floorDiv() logic. Now, MOD with negative numbers is already screwy as may languages define it differently but with the new setup you'd get the following:

System.out.println("Mod with negative numerator: " + -4 % 3);
System.out.println("Math.floorMod() with negative numerator: " + Math.floorMod(-4, 3));

Mod with negative numerator: -1
Math.floorMod() with negative numerator: 2

So, what's happening with the new setup? Well, if you were to do a floorDiv of the same numbers you'd get a -2 and -2 * 3 is -6 so the difference between that result and the original numerator is 2. The floorMod result is always the same sign as the denominator (so if instead of Math.floorMod(-4, 3) we used Math.floorMod(4, -3) then the result would be -2).

Conclusion

While I would imagine the new mod methods will have limited usefulness, however, the exact numerical methods for int and long I would find very useful. Currently well written programs have to constantly check to see if a summation (it will also work in reverse below MIN_VALUE) exceeds the bounds of the variable type. Now, you can check for ArithmaticException (or not as it's a runtime exception so it will bubble up nicely) instead and devote your program to what it's intending to do and leave the bounds checks to the system.

Mockito Captors and verify(): How to check objects created and verify method calls within a method

2014-06-03T08:33:00.001-07:00

Like any good developer I'm sure you write unit tests for each line of your code. Now, you could simply write tests that will execute each line of your code and leave it at that and assume that if the line of code executed then it must be correct but what if you want to actually check that a specific method was called or that a specific method was NOT called because of your setup? What if you want to check the attributes of an object created within the method your testing? Well, with a couple quick calls through Mockito you can easily verify that a method was called and even get objects passed into these method calls.

Example

To keep it simple lets say you have a DAO class that has three methods, a get, an insert, and an update for your domain object.

public interface Dao {
    Domain getDomain(int id);
    void insertDomain(Domain domain);
    void updateDomain(Domain domain);
}

You also have a service class that takes in a web form, translates it to a domain object and inserts or updates the object depending on if the object is found in the database.

public class Service {
    private Dao dao;

    public void processWebForm(WebForm webForm) {
        Domain domain = dao.getDomain(webForm.getId());
        if (domain != null) {
            domain.setField1(webForm.getField1());
            dao.updateDomain(domain);
        } else {
            domain = new Domain();
            domain.setId(webForm.getId());
            domain.setField1(webForm.getField1());
            dao.insertDomain(domain);
        }
    }

    public Dao getDao() {
        return dao;
    }

    public void setDao(Dao dao) {
        this.dao = dao;
    }
}

One quick note, I'm not showing the domain or webform objects here but you can click here to get all the source code for this example. Also, I realize this isn't the most perfectly written code with all the best programming practices but for the purpose of this example it's sufficient.
Now, for testing I could simply call the processWebForm method to ensure that it doesn't fail. I could even call it twice with two different WebForm objects where one should be inserted and one should be updated but what if I want to make sure each of the calls do what I expect? Enter Mockito. The following code snippet will test that the submitted WebForm will result in a Domain object being created and inserted into the database.

@RunWith(MockitoJUnitRunner.class)
public class ServiceTest {
    @Test
    public void testInsertWebForm() throws Exception {
        Dao dao = Mockito.mock(Dao.class);
        Domain d = new Domain();
        d.setId(1);
        d.setField1("field1");
        Mockito.when(dao.getDomain(Matchers.eq(1))).thenReturn(d);
        Service s = new Service();
        s.setDao(dao);
        WebForm wf = new WebForm();
        wf.setField1("testValue");
        s.processWebForm(wf);
        Mockito.verify(dao, Mockito.never()).updateDomain(Matchers.anyObject());
        ArgumentCaptor domainCaptor = ArgumentCaptor.forClass(Domain.class);
        Mockito.verify(dao, Mockito.times(1)).insertDomain(domainCaptor.capture());
        Domain testDomain = domainCaptor.getValue();
        Assert.assertNotNull(testDomain);
        Assert.assertEquals(0, testDomain.getId());
        Assert.assertEquals("testValue", testDomain.getField2());
    }
}

Now, let's go through the important code sections one by one to explain what each of them do.

@RunWith(MockitoJUnitRunner.class)

To use any Mockito classes in your JUnit tests you have to use the Mockito JUnit Test Runner

Dao dao = Mockito.mock(Dao.class);

Verification methods can only be used on Mocked classes.

Mockito.when(dao.getDomain(Matchers.eq(1))).thenReturn(d);

Not strictly necessary since the default setup for a mocked method is to return null but it would be necessary for testing the update method.

Mockito.verify(dao, Mockito.never()).updateDomain(Matchers.anyObject());

This is the first part of the verification that this call does exactly what we want. Since I should be doing an insert then the update method shouldn't ever be called. This method call ensures that the method wasn't called.

ArgumentCaptor domainCaptor = ArgumentCaptor.forClass(Domain.class);

ArgumentCaptors are how you can retrieve objects that were passed into a method call (checking the return value would be silly since you would have set what the return value would be when setting up the mock object to begin with.)

Mockito.verify(dao, Mockito.times(1)).insertDomain(domainCaptor.capture());

This is the second part of the verification where you do two things:

Verify that the insert method was called and only called once
capture the object that was passed into the Dao.insertDomain() method

Domain testDomain = domainCaptor.getValue();

ArgumentCaptor is type sensitive so the getValue() method will return the appropriate type of object you captured. This is how you retrieve the object to check.

Issues

The main thing you need to watch out for when doing verify checks is that the call counts are cumulative from when you create the mock object. If I were to test the update method after my last Assert statement and I tried to do a verify on the insert method with a Mockito.never() for the number of calls it would throw an error saying that it was called once because of the last call. To fix this I generally suggest you test each of the states in separate test methods but if you have to do it in a single test method you'll have to either re-create the mock object or use the Mockito.reset() method which does the same thing (you'll have to re-set all the setup either way)

Conclusion

Using Mockito to mock out objects you're not directly testing makes writing unit tests much easier and more suscient. Using the verify() method with captors is a very handy way to tighten the tests to ensure the exact code flow you want to test was the code flow that ran. There are a few issues you have to look out for but it gives you a powerful tool for ensuring tests are complete.

BigDecimal and equals(); the hidden trap

2014-05-15T10:23:00.000-07:00

On my last project we were using BigDecimal for calculations (you don't still use double, or god forbid float, do you?). Like a good programmer I created a helper function for doing the divide to do the checks for things like the numerator or denominator being null and for the denominator equal to 0.
You can imagine my surprise when we started getting divide by 0 errors in the app. I checked my unit tests (you do have unit tests for all your code, right?) and sure enough there was a test for divide by 0 so what gives?

    public static BigDecimal divide(BigDecimal numerator, BigDecimal denominator) {

        if (numerator == null || denominator == null || denominator.equals(BigDecimal.ZERO)) {

            return BigDecimal.ZERO;

        }

        return numerator.divide(denominator, RoundingMode.HALF_UP);

    }

Well, not only does BigDecimal keep more accurate calcs when you do things like divide two floating point numbers but it keeps track of something called precision. Now, for the non-technical out there, precision is used to determine how accurate a number is; let's look at pi to determine what we're talking about.
Since pi is infinite you need to cut it off somewhere for your calculation. For something that doesn't need to be accurate to a small degree (such as the area of a crop circle down to the square foot) you could just use 3 whereas the area of a machined screw may need to go all the way to 3.1415. In these cases the precision of pi for the crop area is 1 and the precision for the machine screw is 5. I won't get into the full definition of precision but as a rule the number of digits shown past the decimal point determine what the precision is for that number. So, if you have something like 5.25000 then the precision is 6 (5.25 makes 3 and the 3 0's make it 6).
Now, back to my issue above; I determined that I was checking the constant BigDecimal.ZERO (with a precision of 1) to an input value of 0.00 (a precision of 3) and was getting back a value of false for equals() (0 != 0.00). Problem.
Technically, these numbers aren't equal but logically I don't care about the extra precision stored in the second BigDecimal. So, whats a programmer to do? Well, if I were to compare these two numbers the extra precision isn't taken into account (0 is still 0 no matter how accurate you measure it) so if I were to change my equals to check to a compare to:

    public static BigDecimal divide(BigDecimal numerator, BigDecimal denominator) {

        if (numerator == null || denominator == null || denominator.compareTo(BigDecimal.ZERO) == 0) {

            return BigDecimal.ZERO;

        }

        return numerator.divide(denominator, RoundingMode.HALF_UP);

    }

you can now check two numbers for logical equality and my issue of divide by 0 goes away. Now, if you're doing highly scientific calcs this won't work and equals is the better choice but if you're just checking to see if two numbers are the same (especially if you're comparing them to some kind of constant) then precision is more than likely going to get into the way so you compareTo() == 0 instead.

Java 8 Overview: Default and Static Interface Methods

2014-04-30T06:14:00.000-07:00

Introduction

With the release of Java 8 I thought a series of posts on the new features of Java 8 would be appropriate. Probably the simplest of the new concepts is the idea of default and static methods for interfaces. Basically, what you can now do is define a default set of functionality you want for a given interface. Before, you'd have to define an interface and then immediately define an abstract class that implements the interface where you could put the default implementation (Swing event adapter classes anyone?) To use default methods you simply need to put the keyword default before the method signature and implement the method.
Another inclusion with Java 8 are static methods in interfaces. Like default methods, you can declare any number of static methods inside the interface as well.

Example

Source

public class Main {
    public interface ContainsDefault {
        String greeting1();
        default String greeting2() {
            return "My Second Greeting";
        }
        static String greeting3() {
            return "My Third Greeting";
        }
    }

    public static class Override implements ContainsDefault {
        public String greeting1() {
            return "Alternate Override1";
        }

        public String greeting2() {
            return "Alternate Override2";
        }
    }

    public static class NoOverride implements ContainsDefault {
        public String greeting1() {
            return "My First Greeting";
        }
    }

    public static void main(String[] args) {
        ContainsDefault noOverride = new NoOverride();
        ContainsDefault override = new Override();
        System.out.println("noOverride,greeting1: " + noOverride.greeting1());
        System.out.println("noOverride,greeting2: " + noOverride.greeting2());
        System.out.println("override,greeting1: " + override.greeting1());
        System.out.println("override,greeting2: " + override.greeting2());
        System.out.println("containsDefault,greeting3: " + ContainsDefault.greeting3());
    }
}

Results

noOverride,greeting1: My First Greeting
noOverride,greeting2: My Second Greeting
override,greeting1: Alternate Override1
override,greeting2: Alternate Override2
containsDefault,greeting3: My Third Greeting

Advantages

This has a few advantages:

Less classes (you only need the interface, not that plus another abstract class with the default implementations, such as swing event adapter classes)
Moving the default implementations to the interface allows classes that use it that need the default implementation to still extend from another class.
You can now add new methods to existing interfaces and if you add a default method you won't need to go to each implementation to implement the method, where appropriate

Concerns

There are a few things you need to look out for when using default and static methods:

since there is a default implementation, implementing classes aren't required to implement the method at all so you should be careful with putting in defaults for methods that are central to the operation of your system
You still cannot define variables, even if they're public (static and final variables are still OK; but since they're public the outside world can already access them anyway) so the usefulness of the methods are limited

Conclusion

While default methods can provide an easier path for setting up interfaces to make them more useful programmers need to be careful not to apply them indiscriminately. They can render default adapters, like the swing event adapters, irrelevant and free up classes to extend others instead of the adapter class; but they can also hide issues when used for core methods that don't really have a default. At the end of the day they're just another arrow in a programmer's quiver that, if used with skill, will make their programs more concise and understandable.

Setting up and accessing a remote maven repository

2012-06-05T11:32:00.000-07:00

Now that we've reviewed the basics for maven it's time to explore one of the more common situations in a maven project, setting up and accessing a remote repository. For any team greater than one person (which I'm guessing covers a slim portion of projects out there) and projects with more than a single executable (I'm guessing there is one or two of these types out there) you'll need a place to build the building blocks for more advanced projects (such as a utility package or a database entity project).

Creating a remote repository

While many people will say finding a place to store your repository would be the first thing you should consider I say that is the second thing you should do, the first thing is decide how you want users to access the repository and how you want contributors to upload content to the repository. Do you want to make it available over http? Will you need to use the SCP protocol to upload content? Are all your machines the same (Windows vs Linux vs Mac) and only internal access is necessary so a file:// protocol would work? These all will make a difference where you put the repository. After these questions are answered you can pick a server that fits these parameters.

Adding a deployment destination to a project

Now that you've decided where to place your project you'll need a way to add it to your project. Deployment locations are handled in the distributionManagement section of the pom file. It goes at the end of the file after the dependencies section and a sample distribution section appears below:

<distributionManagement>
  <repository>
    <id>serverId</id>
    <name>Example Upload Location</name>
    <url>scp://server/srv/maven/repository</url>
  </repository>
</distributionManagement>

Pretty simple right? There are really two important parts of this snippet, first is the id of the server and second is the URL. The URL's significance should be obvious so I'll focus on the id field. The reason the id field is important is because that is the link between the pom file and this server setup and the personal field setup for this server in the settings.xml file. Depending on what type of URL you use, such as scp, you need additional information, like authentication and directory/file permissions, to perform the task so without further ado lets look at:

Settings.xml

Up until now we haven't had to worry about maven's other configuration file as nearly all tasks handled through the pom file don't need any additional configuration. Technically, if you were to use a file protocol for the deployment you still wouldn't need to configure a server in settings.xml but I have yet to see a system that could use that effectively. While you can configure many different things, such as a proxy or different profiles, through the settings.xml file the only major one that most people will need to use is the servers section. However, if you want to to learn more about the settings.xml file you can do so here. The entire file isn't all that big so reviewing it is quick. For a final note about the settings.xml file is where to find it; the file is located in each user's home directory (on linux it would usually be at /home/<userName>/.m2 and in windows usually C:\Users\<userName>\.m2, your mileage may vary).

servers

The important part of the settings file for distribution management is the server section. In this section you can define personal information about connecting to various servers. In the pom file you define the URL (some would ask why this wouldn't also be here but you can use the same server for multiple functions so the URL needs to be in the pom for different setups) but the rest of the information is here in settings (I'm guessing you may not want your user information broadcast to the rest of the world). A typical server setup looks like the following:

<servers>
  <server>
    <id>serverId</id>
    <username>my_login</username>
    <password>my_password</password>
    <privateKey>${user.home}/.ssh/id_dsa</privateKey>
    <passphrase>some_passphrase</passphrase>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
</servers>

First, if you go back up to our distributionManagement example you'll notice that the id fields match. That would tell maven to use the credential and permissions here when uploading content to the remote repository. You should either enter a password here or is private key/passphrase entry. You should not use both. The permissions are used for the directories and files created on the remote system. If you need an explanation on what the numbers mean you can search for unix file permissions or click here.

A quick bit on security

Starting with Maven 2.1 you can encrypt your password so even if someone managed to get a hold of your settings file (I'm assuming here that you don't give access to this to anyone other than yourself) they still couldn't see your password. Plus, administrators always get nervous when passwords are available in plane sight. If you want/need to encrypt your password I would just follow the instructions on the maven site to set it up here.

Adding a remote repository to a project

There are a plethora of reasons you may need to add a repository to your project.

Your company has a policy that prohibits downloading software packages directly from the web so you need to connect to a mirrored main repository inside the company
You need to connect to a third party vendor for additional software packages
You need to connect to an internal repository to use internal software APIs

Whatever the reason, there is a simple way to connect a maven project to one of these repositories. First, you need to add a repository to the repositories section of the pom (just before the dependencies section. The entry would look like the following:

<repositories>
  <repository>
    <id>java.net.maven1</id>
    <name>java.net</name>
    <url>http://download.java.net/maven/2</url>
   </repository>
</repositories>

Like the distribution management element above the name is just a name you want to see. For the id, it only matters if you need additional authentication information for the server you're connecting to. Since most access is over http and unauthenticated it usually doesn't matter. However, if you needed to lock down even the pull and ended up using something like scp then you'd want to make sure the id matches a server defined in settings.xml (see above).

Getting started with Maven

2012-05-10T07:24:00.001-07:00

What is Maven

Maven is quickly becoming, if it isn't already, the most popular build tool for java projects. With plugins you can do pretty much anything but at its heart Maven is a project management tool that handles dependency management, building and testing a java project. By default it can handle all the default java project types, jar, war, ejb-jar and ear.

The purpose of this article is to get familiar with the Maven setup so items like plugins and site development won't be covered here. There will be other articles that will cover those topics.

Application Setup

"Installing" Maven consists of downloading the package from the Maven site and unzipping the contents into a directory. If you're using an IDE such as Netbeans, Intellij or Eclipse you can usually skip this step as they already have an install built into the IDE. The important file for command line execution is the mvn.bat (windows) or mvn (linux) file in the bin/ directory. This file starts the maven process. Additional instructions and specialty builds of Maven are available on the Maven download page.

pom.xml

Aside from the application install the only other required file for maven is the pom.xml file. The pom file is the basis for a specific Maven project (such as a jar or a war). The pom file also contains information about other projects this project depends on (dependencies) the version to be built and deployment information.

Build information

At the start of the pom file is information about the name, version and type of the artifact to build. This information is summed up in four elements:

groupId--this is like a package for your project, usually in the form com.<company name>.<group area> such as com.tigereye.examples
artifactId--This is usually the name of the project
version
packaging--this tells Maven what type of artifact the project is. (Such as jar or war, it also tells maven how to package the artifact and any additional steps necessary for the specific project type)

Dependencies

While not strictly required for a project only the most basic projects don't depend on external sources. Whether it's hibernate for database access, the JEE API files for building an enterprise applications or an internal utility package pretty much all but the most basic applications require some kind of external resource to function.

Personally, this is where I believe Maven proves its worth. When setting up your project you only need to define programs your program directly depends on. Maven handles pulling in all the dependencies that project depends on that you don't so you don't have to worry about it. Let's say that you need to use hibernate but you don't specifically need to use antlr, you just have to add the dependency for hibernate and Maven will pick up antlr when you need to use hibernate (such as building a war or an ear). This way, you can focus on what your project needs and not worry about the rest of the jars necessary to actually run, Maven will ensure you have everything you need when it comes time to use them.

The dependency section starts with a dependencies element with one or more dependency elements. The content of each of the dependency element is as follows:

groupId -- analogous to the groupId at the top of the file except this is the group id of the artifact you want to import
artifactId -- like groupId, this is the artifact id of the artifact you want to use
version -- the version of the artifact you want to use
scope -- an optional attribute (defaults to compile) that has one of four values:

compile -- this package is necessary for compiling your code and all other steps
runtime -- this package isn't directly referenced in the code but needed to properly run
test -- this package is necessary for the testing tree but not necessary for running the main project (useful for packages like junit or testng)
provided -- this package is necessary to compile the project but will be provided for running the application later (such as servlet-api when writing a web app since it's provided by the web container)

Sample File

Below is a sample of a very basic pom file.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.psc.example</groupId>
  <artifactId>jax-ws</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>jax-ws Maven Webapp</name>
  <dependencies>
    <dependency>
      <groupId>javax.persistence</groupId>
      <artifactId>jpa-api</artifactId>
      <version>2.1</version>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>3.6.7.Final</version>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.sun.faces</groupId>
      <artifactId>jsf-api</artifactId>
      <version>2.1.1-b02</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

The above sample is a basic web project. It uses JPA for its persistence which requires a compile time dependency with hibernate as the implementing persistence framework. Since we're using JPA in our code the hibernate dependency is specified as runtime (it won't appear on the compile classpath but it will be included in the WAR. We also have the JSF api package that is necessary for the presentation pages but that package is already a part of the container so we mark it as provided (it's used for compiling but won't be included in the WAR). Finally, for testing we need junit but we don't want it on the compile classpath or in the WAR so we mark it as test.

Project Structure

While you can override the folders for things like source if you want, unless there's a good reason it just makes good sense, not to mention a smaller pom file, to use the default directory layout for your project. The standard setup for files is as follows:

<project directory>
src
main
java
resources
webapp (if your app is a web-app)
test
java
resources
pom.xml

If you aren't using your IDE to generate the project structure and you don't want to hand code the directory names you can execute the following maven script in the directory ABOVE the project directory:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Substitute groupId and artifactId with appropriate names for your project. After it finishes executing a directory matching your artifactId.

Once you start compiling classes and running tests one more directory will be created by maven for storing the compiled classes called target. This directory is at the same level as src and will have sub directories under it for the compiled classes, web content and test resources, just like src has.

Execution

Once you have the rest of the maven setup complete you'll need to be able to perform actions on your project. In maven speak an action is called a phase. Maven has a very rich set of phases you can perform. In keeping with the theme of this article I'm only going to go over the basic ones here to get you up and running but the linked site has all of them and examples of what they do and how to use them correctly.

The main phases you'll be needed for day-to-day use are:

compile -- This compiles all source java files and copies any resources to the target directory
test -- runs all tests found in the system (if you add -DskipTests it will compile the tests but not run them or -Dmaven.test.skip=true to not even compile them. I'm sure I don't need to tell you how dangerous this can be)
package -- builds the output file (jar for standard projects, war, ear, ejb jars, etc. for other project types)
install -- copies the package to your local maven repository.

One thing to note, each phase builds on the previous one so if you execute the package phase it will execute compile, test and any other defined phase before the package phase. This becomes important as you move down the phase chain since a failure in a previous phase will halt the execution.

Local Repository

Finally, while not something neophytes to maven will care about knowing about your local repository will help understand some features of maven. The idea of your local repository is a place on your machine where dependent packages (both for your projects and for maven itself) can be stored so yo don't have to go out to the internet each time you need to check something. In fact, the first time you run maven and, in general, the first time you use a new package you'll most likely notice a slowdown in the initial phases as maven downloads updated or new dependencies. Under your home directory (Windows: C:\Users\<username> or linux: /home/<username>) is a .m2 directory. Under there is the repository. It's essentially a network of first group ids, then artifact ids and finally version number directories where jars, poms and additional information for maven are stored for use by both maven and you projects. As a general rule (even for more advanced things) you shouldn't need to mess with this much other than occasionally removing entries.

Conclusion

I can hear you now, "but what about the settings.xml file?", "what about plugins?", "what about deployments?" and any number of other things that maven can do. While I do agree that they're all important they really aren't necessary for getting started with maven and setting up an initial maven project. I'm sure I'll be covering them in additional posts but if you don't have a good foundation then the rest will fall apart.

The Web Container in a nutshell

2012-03-26T08:35:00.000-07:00

General Overview

This topic is a discussion of the general JEE web container components. While useful, this isn't a discussion of any of the frameworks built upon the JEE web container such as struts, JSF, Spring MVC or others. Each of these frameworks have their own sites with a plethora of examples and other information. Each of the following sections contain a component or piece of the web container setup. This paper also does not get into other Enterprise components such as JMS or EJB, although there are ways for the web container to use these components and those places will be mentioned.

Web Contexts

There are 4 different contexts in the web container, in parentheses would be their object variable equivelant:

Application (static)
Session (class)
Request (method)
Page (Only applicable on the JSP) (sub-method)

Application scoped variables are available to every web piece. They're available within a given servlet/jsp request, they're available to the session and any setup for a servlet, listener, filter or any other web component, just like static properties are available to any method in a class and all instances all can see the same static parameter. Just like static variables, any change to an application scoped variable will be seen by the rest of the application.
Session scoped variables are tied to a specific user that span multiple requests. This would be like creating a configuration object in a general project to store information about a specific process for the length of the process. Any sub process that originates from this process will get the same data in this configuration object. Once the process is done the object is discarded, just like a session when a user leaves the system (or a timeout occurs before the nest request from a specific user).
Request scoped variables are tied to a specific request on the server. The parameters only live for the length of the request and are reset with the next request. In object speak these would be just like parameters created within a request. Variables within request don't require a visibility modifier (such as public) because once the method is done the variables are cleaned up and rest for the next request.
Page scope is a special case of the request scope used only for JSPs. Many custom tags will create properties and, in most cases, store them in the page scope for use on that specific page. If you were to be redirected to another page (an extremely unlikely thing but still possible) these variables are wiped clean which makes this scope a perfect place to store this temporary information.

Servlets

Servlets are the primary way to execute logic in a web application. While you do have direct access to the output stream that is returned to the client it is generally considered proper form for the servlet to execute the logic (such as accessing a database, interacting with a web service or an EJB), set parameters in one of the web contexts and then forward to a JSP to implement the actual rendering logic. One usual deviation from this would be if you have to return some kind of non-viewable content (such as an excel, PDF or other file) for the user to save outside the HTML viewing process.
You can chain servlets together using the HttpServletRequest.forward() and the HttpServletResponse.sendRedirect() to chain logic (or, generally using the former) to use a JSP to render the result back to the user. One thing to note on the sendRedirect() method, it sends a response back to the browser and tells the browser to go to the page so any request variables that were set will be reset when accessing the redirected resource. Usually, instead of directly chaining servlets, filters would be used. These components are covered in a later section.

JSP

JSPs are actually special servlets that are intended to just render content for the user. The web server will actually compile the JSP on the back-end into a servlet for quicker access. They're intended to be very light weight and just take properties set in a servlet and render them to the user.

Scriptlets

Scriptlets are defined as anything between <% and %>. Everything between the braces must be valid java. A special cased where the output is rendered directly to the screen is the <%= %>. Whatever is between the braces is evaluated and the result is rendered to the screen, you shouldn't put a semi-colon at the end of this expression. In general a mature project should not use these as they're generally reserved for lightweight projects that don't use servlets at all. If you find yourself using scriptlets you most likely should be doing more work in the servlet or creating a custom tag to keep from cluttering the page.

Expression Language

JSPs have their own expression language for quick and easy access to scoped variables. The format of the expression is ${..} where the first word inside the braces is a variable name in a scope. After the variable name you can access properties based on dot notation. So, if you had an expression like the following ${foo.bar} the jsp would look in the all the contexts (more on the order in a minute) for a property called 'foo', and once it finds the object it will try to access the property getBar() (or isBar() if the property is a Boolean). You can chain this down to any level you wish, as long as the chain is valid. You can also access indexed or mapped properties using brackets so an expression like the following: ${foo[0].bar} would try to find a list in a context called foo, retrieve the first element and access the bar property of that object. As a convenience for a map property you can use the dot notation to access a entry of the map so ${foo.bar} would be the same as ${foo['bar']} if 'foo' is a map.

Tag Libraries

Tag libraries are self contained pieces of rendering logic that an be accessed just like any other tag. There are standard tag libraries (generally called JSTL) and nearly every framework has a set of tag libraries for use with the framework. You define them at the top of the JSP file using the format <%@ taglib uri=”uri” prefix=”x”>. With the preceding tag declaration to use the taglib you'd start your tags with <x:....> where the colon is followed by the tag definition. Think of a definition as a method call to render some kind of element. Now, there are standard tag libraries for things like database connections but most mature projects won't use them as they're targeted at stand alone JSPs. The most common tag libraries used are core as <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %> and format as <%@ taglib prefix="f" uri="http://java.sun.com/jstl/fmt" %>. There are additional tag libraries like sql and xml but most of these are covered by a framework.

Custom Tag libraries

If the standard tag libraries and your framework's tag libraries aren't sufficient for your needs you can roll your own tag library. To do this you create an XML file called <name>.tld and place it in your WEB-INF/tld directory. The XML file has to implement the http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd schema. You can view a tutorial on Oracle's site for exactly how to write a TLD but essentially there are two types of tags:

Static function calls you want to expose in your application to the JSPs. These are defined using the <function> tag with the function-class and function-signature elements
The <tag> class to define the traditional tag setup where you define the tag class with tag-class and body-content to define how to handle sub tags or sub html elements.

Filters

Filters are a command pattern for usage with Servlets. Filters can operate before the servlet call on the request and after the servlet call on the response. For the request side they can be useful for things like verifying a user has logged in (assuming you aren't using container managed security defined below) and forwarding to a login page before secured sections of the app. You can also perform actions like retrieving necessary information or instantiating objects needed by the servlet (such as data access objects or common lookups) since filters can be shared across multiple servlets. On the outbound side they're useful for things like encrypting output when necessary any other cleanup tasks necessary after a servlet is done executing its tasks.

Listeners

There are two different kind of listeners in a standard web application:

SessionListeners
ApplicationContextListeners

Both listeners are essentially the same thing but targeted at different levels of the web container. They both have two methods to implement, one for when an object is created and one for when that object is destroyed.
For the Session listener it's targeted (not surprisingly) at when each session is created or destroyed. While not extreemly useful, it can be used to track when a particular user has logged in (which can also be done through a filter for each request) or useage statistics. When sessions are destroyed you could go through the session and serialize items for retrieval upon re-creation or closing resources that were stored in the session but these are generally fringe cases.
The application context listener is called twice during the life of a web app, once when the application starts up and once when it shuts down. In it, you can run anything that you need to manually set up or tear down.
One thing to note about both these listeners, tread lightly on the closing of resources when things stop. While you're guaranteed to see things start up the app could crash and the shutdown methods may not be called (a general problem anyway but something to remember)

WAR packaging and web.xml

The WAR file is a standard JAR file with a .war extension that can be decompressed and used by an application server.
The web.xml file is the configuation file for a web application. In this file you define all listeners, servlets, servlet mappings and all other less common web application components. As you'll see below, it's located under the WEB-INF directory and is required to deploy a web application.

Directory layout
/ (all jsps go at this level for standard access through the browser)
/WEB-INF (in here you put any other configuration file (other than classes and jars)
/web.xml
/classes (all classes for the web app go here)
/lib (any dependent libraries for your web ap)
/scripts (standard but configurable location for javascript files)
/images (standard but configurable location for images)

Security

While there is no standard way for an application server to set up security there are standard ways to interact and set up restricted access in the web app. There are two prominent ways to deal with security. Neither way is definitively better than the other and they can easily be used together.
The first way is declarative through the web.xml config file using the <security-constraint> tag. Inside this tag you define what url patterns you want to secure (they can be hard paths referenced by a jsp or virtual paths defined in a servlet mapping) and the roles necessary to access these resources. When a request is made the server will check if the request has an authenticated user and if not then redirect them to a login page for authentication. Once authenticated, it will check the roles assigned to that user to see if one matches what is necessary to access the page. Both the page and the user can have multiple roles and only one matching role is necessary. If no roles match then a forbidden page (403) is returned to the user.
The other authentication mechanism is progromatic security (which relies on the user being authenticated on the system). There are two methods on the HttpServletRequest object that deal with authentication:

getUserPrinciple()
isUserInRole(String)

getUserPrinciple() returns a UserPrinciple object if the user is logged in with information about the logged in user, otherwise it's null. The isUserInRole takes in a role as a string and returns true if the user has that role. These are available in both the servlet and on jsp pages to conditionally render JSP elements or conditional business logic on the server.

Resources

Resource-ref

Resource-ref is used to define connection factories for enterprise components. Some of the standard enterprise factories are:

DataSource
QueueConnectionFactory
TopicConnectionFactory
Session (for JavaMail)

The declaration includes a JNDI location where to find the resource.

Env-entry

The env-entry tag is used to define a property (similar to a jvm property) for use by the web application. The following types are possible:

java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.String

These properties are useful for values that change based on the environment. One example would be if you have to store report files you can make the directory where they're stored an environment property so you can put the same WAR file in each environment and update the environment value on the server.