Wednesday 19 December 2012

When you need to do some serious work with dates

In the Java course, which will hopefully be available on VirtualPairProgrammers.com at around the end of March, we do some basic date manipulation using the GregorianCalendar class. I explain that the Date class within java has problems, which is why many of the methods are depreciated. I don't go into detail about what is wrong with it, but there's a great post about that here:

http://stackoverflow.com/questions/1969442/whats-wrong-with-java-date-time-api

GregorianCalendar is acceptable for basic date usage although it's not completely intuitive and doesn't really cut the mustard if you need to do some serious date manipulation.

Something we do within the course is work out a date in the future by adding a fixed number of days to today's date - we want to create a variable called DueDate and set it's value to, say, 14 days after today. So if today is the 4th March, then DueDate should be equal to 18th March.

Programatically the code to do this, using the GregorianCalendar class looks like this:

public void CalculateDueDate() {
GregorianCalendar gc = new GregorianCalendar();
gc.add(Calendar.DAY_OF_MONTH, 14);
Date dueDate = gc.getTime();
System.out.println(dueDate);
}


This code is reasonably straight forward - we create a new instance of the GregorianCalendar class (which by default will have an initial value of the date and time when it is instantiated) and then call it's add method to move it's value on by 14 days.

What's odd about this code, at least to me, is the use of DAY_OF_MONTH to specify that it is 14 days we want to day (days as opposed to months or years). It's odd because DAY_OF_MONTH has a specific meaning - and yet we could use this code to validly add 41 days, even though no month has more than 41. Interestingly DAY_OF_WEEK will also work in it's place, as will DAY_OF_YEAR. Now these three field values are definitely NOT the same, but the GregorianCalendar class is "clever enough" to know how to perform an add correctly, when any one of these fields is provided as the first parameter.

This leaves most programmers feeling a little uncomfortable - surely it would make more sense for the add function to take a value of calendar.DAY - but this field doesn't exist. There are fields for year, month, hour, minute and second, so this missing DAY field really doesn't feel comfortable.

Now this isn't the only reason to dump the GregorianCalendar class in favour of a nicer alternative - in fact most people would say I have gone off on a tangent, and some of the bigger issues include the lack of methods like .getMonth(). But this is a good enough one for me to say it's worth spending some time looking at JodaTime.

Now JodaTime isn't the only alternative set of date and time classes available for Java but I believe it's one of the most popular - and for good reason. The documentation for JodaTime library which can be found at http://joda-time.sourceforge.net/index.html is simply first class. If you want to see what I mean, take a look at their chronology pages. The detail they go into about the Gregorian and Julian calendars, their combination into GregorianJulian and the ISO8601 format is fascinating.

So before we can use JodaTime we need to install it - the process is straightforward - download one of the distribution files, unzip the contents, and then add the joda-time-version.jar file as an external file to you project's build path.

Using JodaTime our example above becomes:
public void CalculateDueDate() {
DateTime dt = new DateTime();
DateTime dueDate = dt.plusDays(14);
System.out.println(dueDate);
}


The .plusDays function is really nice - it's completely clear what it does, and straight forward to use.

I'll finish this blog post with one exceptionally nice feature of Joda time -the ease in formatting dates for output. In the UK it's normal to display dates in the format day/month/year. To amend my code to do that, I can specify a format in the .toString method of the DateTime class. All I need to do is amend my final line to:

System.out.println(dueDate.toString("dd/MM/yyyy"));


There's lots more to the JodaTime class but I hope you'll see that it really is an easy to use, reliable, time and date management library. Just play with it for half an hour and you'll wonder how you ever managed without it!

Tuesday 13 November 2012

Automatic Resource Management - how Java 7 makes coding neater

This is my second post on Automatic Resource Management. Actually that's not quite true - in the first post, I talked through an example of how to do "manual" resource management, as you would in Java 6. In that post I built up to a reasonable, but unpleasant, piece of code which used a nested try...finally block within a try...catch block to ensure that any resources we had used within our code where correctly closed, even if an exception occurred.

In this follow-up post, we'll look at how Java 7's Automatic Resource Management features simplify our code, and then we'll understand how it works, and when you can use it.

So let's first look at the code. The syntax is quite straight forward - we can remove our nested try blocks, and instead place the lines of code that open resources within parenthesis on the try line. This structure is known as "try with resources". The code will look something like this:


public void InsertRowWithARM()
{
     try (//code to open the resource goes here)
     {
           //code to run if the resource was opened
     }
     catch (ExceptionType1 e)
     {
           //handle the exceptions
     }
     catch (ExceptionType2 e)
     {
           //handle the exceptions
     }
}

So the code that we wrote in the last post now looks like this:

 public static void InsertRowWithARM()
{
     String sql = "INSERT INTO testTable (id,title) values(?,?)";
 
     try
     {
          Class.forName("org.apache.derby.jdbc.ClientDriver");
     }
     catch (ClassNotFoundException e)
     {
          System.out.println("Could not load database driver");
          return;
     }
  
     try (Connection conn = DriverManager.getConnection("jdbc:derby://localhost/testDB");
    PreparedStatement stm = conn.prepareStatement(sql);)
     {
     stm.setInt(1, 1);
     stm.setString(2, "The Best Java Course Ever");
     int results = stm.executeUpdate(); 
     System.out.println("Records added: " + results);
     }
     catch (SQLException e)
     {
        System.out.println("Something went wrong with the database");
     }
}

Note here that I have moved the code to load the database driver into its' own try...catch block - This is not just my preference... we can't put that line in the try with resources brackets (we'll see why shortly).  However I think it's neater this way as if this line fails we will want to exit the whole method, and this line doesn't actually open any resources so it sits more nicely by itself.

More importantly, we no longer have the finally block or nesting of try blocks, and we also have lost the stm.close() and conn.close() commands - the point of automatic resource management is that any resources which are opened in the try with resources statement are closed automatically so we don't need to call their close methods.

This is much neater and easy to write.

So how does it work? Firstly, any object which is created within the try with resources brackets must implement the java.lang.AutoCloseable interface. You can't instantiate any other kind of object, such as a string, within the brackets - if you try to do so, the code won't compile and the error will be "The resource type YourObjectType does not implement java.lang.AutoCloseable". This is the reason why we can't load the database driver in our example above within the try with resources brackets - it needs its own separate, standard, try catch block, as there are no resources here to worry about.

This need for objects to implement the AutoCloseable interface gives us some sense of security when we are writing our code - if a resource object hasn't been updated to make use of the facility within Java 7, we won't find ourselves misguidingly instantiating it within the try with resources brackets, thinking that it will get closed neatly.

For an object to implement the AutoCloseable interface it must implement a single method with method signature

public void close() throws Exception;

When our method with the try with resources brackets is exited, whether that is gracefully upon expected completion, or as a result of hitting a catch block because an exception occurred  the close() method of each and every object that was instantiated will be called.

If you are going to write your own code that will implement the AutoCloseable Interface then I'd suggest you take a look at the second part of this post which talks about the order in which things work, and what to bear in mind when writing your own resource components:

http://www.oracle.com/technetwork/articles/java/trywithresources-401775.html

Thursday 8 November 2012

Automatic Resource Management - understanding the pre ARM mess

One of the topics that I touch on in the new introductory Java course that I have been writing for Virtual Pair Programmers is Automatic Resource Management (ARM). This is a new feature in Java 7 that attempts to make it easier for the developer to write code that uses external resources safely.

I only give this a light touch in the course as for people new to Java, a basic understanding of the syntax is all that is really needed. However I do think it’s worth spending a little more time on ARM, and so this is the first of two blog posts on the topic. In this post, we'll look at why code pre-ARM is so messy.

Suppose we want to do something relatively simple like connect to a database, and insert a row in a table. In this example, I’ve set up a database using derby, called testDB, which has one table, called testTable. The table has 2 fields, an integer called id, and a varchar called title.

The task ahead of us is to write some code which runs a prepared statement to insert a new row into our testTable - our starting point will be something like:

public void InsertRow()
{
     Class.forName("org.apache.derby.jdbc.ClientDriver");
     Connection conn = DriverManager.getConnection("jdbc:derby://localhost/testDB");
     String sql = "INSERT INTO testTable (id,title) values(?,?)";
     PreparedStatement stm = conn.prepareStatement(sql);
     stm.setInt(1, 1);
     stm.setString(2, "The Best Java Course Ever");
     int results = stm.executeUpdate(); 
     System.out.println("Records added: " + results);
     stm.close();
     conn.close();
 }

If you haven't written database access code in Java before then this code might need some explanation. We first load the driver for our database, in this case Derby, on line 3. We then create a connection object and open a connection to the database on line 4. Line 5 defines an SQL string, using question marks where parameter values will be placed. We use this string to set up a prepared statement on line 6, and then supply the values for each parameter on lines 7 and 8. We then execute the prepared statement on line 9, and finally close the prepared statement and the connection to the database on lines 11 and 12.

Now this code as it stands won't compile as there are exceptions which need to be handed. The Class.forName command could throw a ClassNotFoundException, and lines 4,6,7,8,10,11 and 12 could each throw a SQLException.

Lets handle these exceptions with a simple try catch block which output a message to the console. Our code will now look something like this:


public void InsertRow()
{
     try
     {
          Class.forName("org.apache.derby.jdbc.ClientDriver");
          Connection conn = DriverManager.getConnection("jdbc:derby://localhost/testDB");
          String sql = "INSERT INTO testTable (id,title) values(?,?)";
          PreparedStatement stm = conn.prepareStatement(sql);
          stm.setInt(1, 1);
          stm.setString(2, "The Best Java Course Ever");
          int results = stm.executeUpdate(); 
          System.out.println("Records added: " + results);
          stm.close();
          conn.close();
     }
     catch (ClassNotFoundException e)
     {
           System.out.println("Could not load database driver");
     }
     catch (SQLException e)
     {
           System.out.println("Something went wrong with the database");
     }
}

We now have code that compiles, and even if errors occur, the inexperienced developer may think that the job is complete.

The reality, however, is that we have something rather dangerous. Suppose there is an error in our SQL statement - for example if the field name was actually booktitle rather than title, then the main part of our function would fall over at line 11.  Our SQLException catch block would run, displaying a nice friendly message on the console, and lines 12, 13 and 14 never get executed.

This is the crux of the problem - because we don't execute lines 13 and 14 we potentially leave open connections to the database. In more generic terms, the database resource remains open. The same sort of problem can occur when we write code that accesses other resources, such as accessing files, printer streams or  communication sockets.

So why is leaving resources open a problem? If you've used a computer running Microsoft Windows for any length of time, you will almost certainly have come across the situation where you can't delete a file because Windows complains it is currently in use, and yet there are no apparent applications accessing that file. This is an example of a resource left open - something has probably been accessing the file and has crashed without closing down the connection. With multi user databases,  you could see the issue occur when there are no free connections available for the next user. In even the most simple production systems, avoiding such situations is important.

So how do we get around this problem? Well in our example, we want to ensure that the stm.close() command and the conn.close() command run every time, even if an exception occurs. We might try and achieve this by putting these two lines into our SQLException catch block like so:


catch (SQLException e)
{
     System.out.println("Something went wrong with the database");
     stm.close();
     conn.close();
}

Of course that code won't compile, because the 2 new lines we have added might themselves throw a SQLException which needs to be caught. If the stm.close() throws an exception we still need to try and close the conn object's connection, so we could have some really nasty looking nested try catch blocks which would look like this:


catch (SQLException e)
{
     System.out.println("Something went wrong with the database");
     try
     {
          stm.close();
     }
     catch(SQLException e1)
     {
         //stm.close has failed but we still need to close the connection if that's open
         try
         {
              conn.close();
         }
         catch (SQLException e2)
         {
              //we can ignore this exception as it means the connection wasn't established
         }
    }
    try
    {
         conn.close();
    }
    catch (SQLException e3)
    {
         //we can ignore this exception as it means the connection wasn't established
    }
}

There's still one more job to do here to get the code to compile - we need to move the declaration to the conn and stm objects outside the initial try block, so that their scope becomes method-wide, and they are then available to the catch blocks. Our current code block now looks like this:


public void InsertRow()
{
     Connection conn = null;
     PreparedStatement stm = null;
     try
     {
          Class.forName("org.apache.derby.jdbc.ClientDriver");
          conn = DriverManager.getConnection("jdbc:derby://localhost/testDB");
          String sql = "INSERT INTO testTable (id,title) values(?,?)";
          stm = conn.prepareStatement(sql);
          stm.setInt(1, 1);
          stm.setString(2, "The Best Java Course Ever");
          int results = stm.executeUpdate(); 
          System.out.println("Records added: " + results);
          stm.close();
          conn.close();    }
     catch (ClassNotFoundException e)
     {
          System.out.println("Could not load database driver");
     }
     catch (SQLException e)
     {
          System.out.println("Something went wrong with the database");
          try
          {
               stm.close();
          }
          catch(SQLException e1)
          {
               //stm.close has failed but we still need to close the connection if that's open
               try
               {
                    conn.close();
               }
               catch (SQLException e2)
               {
                    //we can ignore this exception as it means the connection wasn't established
               }
          }
          try
          {
               conn.close();
          }
          catch (SQLException e3)
          {
                //we can ignore this exception as it means the connection wasn't established
          }
     }
}

So I hope you agree that this code works, will close the required resources, but is absolutely horrible. Imagine how complex writing code like this would get with more complex starting code.

Thankfully Java gives us a way around this problem by using the try...finally construct nested within a try...catch block. Here, the finally block will always run, and we can put our code to close our resources within that finally block. The generic syntax looks like this:

public void ExampleOfResourceManagedCode {

     //declare resources

     try
     {
          try 
          {
               //resource access code goes here
          }
          finally
          {
               //close all resources here
          }
     }
     catch (ExceptionType1 e)
     {
          // handle the exception
     }
     catch (ExceptionType2 e)
     {
          //handle the exception
     }
}

So let's see what our code looks like in this neater format.
public void InsertRow()
{
     Connection conn = null;
     PreparedStatement stm = null;
     try
     {
          try 
          {
               Class.forName("org.apache.derby.jdbc.ClientDriver");
               conn = DriverManager.getConnection("jdbc:derby://localhost/testDB");
               String sql = "INSERT INTO testTable (id,title) values(?,?)";
               stm = conn.prepareStatement(sql);
               stm.setInt(1, 1);
               stm.setString(2, "The Best Java Course Ever");
               int results = stm.executeUpdate(); 
               System.out.println("Records added: " + results);
          }
          finally 
          {
               if (stm!=null) stm.close();
               if (conn!=null) conn.close();
          }
     }
     catch (ClassNotFoundException e)
     {
          System.out.println("Could not load database driver");
     }
     catch (SQLException e)
     {
          System.out.println("Something went wrong with the database");
     }
}
So this is certainly neater, but it's not completely intuitive, and unless you write resource access code a lot, you'll probably need to refresh your memory about how this construct works each time you need it.

So we now understand the problem, and the nicer construct within Java to get around it... in the next post we'll convert this code to the ARM version and see if it really is that much nicer!

Tuesday 30 October 2012

First steps in Java


I’m currently writing a video based training course for VirtualPairProgrammers.com. At the moment their courses are aimed at existing Java developers, covering topics such as the Spring Framework, Java Messaging, Enterprise Java and Web Development. As Richard Chesterwood, their existing trainer, continues to develop more courses, they wanted a new course to complement the existing library, that would work for people new to Java.  

The course, which should be available to buy early next year, will be aimed at anyone who has programmed before in any major programming language (including C, Visual Basic, Pascal, PHP, Javascript or any of the .net languages). It will be a conversion course into Java, teaching both how to do in Java those things you know about in another language, and how to do things that you may not have come across before. For some people this will be all they need to get started writing Java programs, but for most it will be a stepping stone on the journey to advanced Java development – and the other VPP courses will provide those next steps.

It’s quite a daunting prospect as VPP have a reputation for really high quality products that genuinely help developers get their next job / promotion or project. 

But VPP also had another requirement – there are plenty of introductory Java programming courses available, but none of them really seem to focus on building “real world” software, and this is something that people new to Java really want to get to grips with. Many courses use abstract examples – I’ve seen one that talked about varieties of apples in one chapter, and then went on to talk about seeds, trees, blooms and fruit in another… something that you just don’t actually program. It reminded me of when I first learned about inheritance – I’m sure the example was insects, where there were different species and each insect might have a different number of legs, wings, etc. Again it might help explain the concept but it doesn’t help the programmer use it in a real life example.

So as writing the course progresses, I’m working out how to cover key topics such as syntax, application structure, exceptions, collections, JUnit, and of course object orientation, but at the same time using a sensible real-world example application that we’ll build from scratch. A lot of thought goes into this – it’s not like any kind of teaching I’ve done before, but I’m really pleased with the results so far!