Java Planet

JSP Considered Harmful

2009-11-30T14:30:00.001-06:00

Why JSPs aren't good in Model 2 web applications

Model 1 is a design approach for web applications. In this approach, one servlet is responsible for handling a browser request from beginning to end - it receives the request, runs the business logic that performs the necessary operations (which more often than not involves database access), and generates output in HTML (or possibly in other forms such as XML, PDF and image data; for the purposes of this article I'm concerned primarily with HTML).

Model 1 is okay for small web applications but it really isn't very well suited to larger ones; because the view - the part that generates the HTML - is embedded in the same servlet that performs the business logic, making modifications to the view risks damaging the business logic. Imagine that you have a fairly large application and you decide to update the look and feel of the whole website; you'd have to modify every servlet.

Early Model 1 applications written as servlets had another problem in that the generation of HTML was performed by Java code. That meant that the servlet developers had to write code to generate that HTML, usually working with a web designer who provided the HTML. Obviously this wasn't a very efficient way of working.

The answer to this was JSP, which has often been described as 'inside-out servlets'. The idea is simple: instead of writing servlets that perform business logic and embed the HTML, a JSP is essentially an HTML file that has the business logic embedded as 'scriptlets' of explicit Java code. At run time a JSP compiler translates the JSP to Java source then compiles that source to class binaries that are then loaded in the normal way. (In some systems the JSP compiler generates bytecodes directly, without the intermediate Java source). This means that HTML designers can produce basic JSPs then hand the result over to a Java developer who can add in the scriptlets to perform the business logic.

However the business logic and the view are still contained in one file, which can still lead to the same kinds of problems - if you change the page layout you risk damaging the business logic and vice-versa.

Model 2 is intended to solve this problem. Model 2 decouples the business logic from the view, minimising the dependencies and making it possible, at least in principle, to make changes to the business logic or to the view without requiring changes on the other side of the fence.

This is where the problems begin for JSP. It's very easy to embed business logic in a JSP - that's the whole point when you consider that JSP is a Model 1 technology. However it's this very same point that makes JSP a bad fit for Model 2; it's simply too easy to drop code that really belongs in the business logic into a JSP. As a result novice developers often do just that and even seasoned developers do it from time to time, especially when a quick'n'dirty fix is needed to cure a production problem in a hurry. The result is business logic that's split between the servlet where it belongs and the JSP that should really contain only view logic. Ideally the scriptlets in a JSP for a Model 2 application should be doing no more than pulling data from the model and formatting it for presentation; any more than that probably belongs in the business logic. Maintaining this separation is a matter of discipline on the part of the developer because there's nothing in JSP to enforce it.

Struts was probably the first Model 2 framework for Java web applications although it's difficult to be certain. According to an article I read a year or two ago (I don't remember where I read it or who wrote it, and I haven't been able to find it through Google, so I can't back any of this up...), the people who developed Struts recognised that this was a problem. However they released Struts and advocated JSP as the view layer, for a number of reasons: first, there was no other mature view technology available at the time. They could have developed a more suitable package as part of Struts but getting something like that into a stable condition would have delayed the release of Struts by close to a year. Further, it would have meant that web developers wanting to use Struts would have had to learn the new view technology, making Struts a less attractive package. By using JSP, Struts would allow Model 1 developers to continue using a technology they were familiar with - they'd just have to take a more disciplined approach to JSP development.

The way I understand it (and again, I can't substantiate this), the Struts developers expected a more suitable view layer to become available before too long after Struts was released. Unfortunately it didn't work out quite that way; the first really useful package to fit the need was probably Velocity and that wasn't on the scene until something like two years later. In the meantime the JSP snowball had been rolling down the hill and picking up speed. Thanks to that momentum, JSP is still being used even today for new applications using Struts 2, Spring MVC and others, regardless of the problems it continues to cause in Model 2 environments.

The Alternatives

If JSP isn't a good fit for Model 2 applications, then what is?

The answer is quite simple: templating software. The idea is that you create HTML templates which contain embedded markers that tell the templating engine how to get dynamic data from the data model produced by the business logic and format it for presentation. The templating engine merges the template with the data model to produce the HTML and deliver it to the client browser.

Velocity and FreeMarker are probably the two most commonly used templating packages in current use. Integrating Velocity and/or FreeMarker is pretty simple. Both packages include ready-to-use servlets that fit with Struts 1, so in both cases all you have to do is configure your application to forward the request/response to the relevant servlet instead of the JSP servlet. Struts 2 has "Results" classes to provide Velocity and FreeMarker views; similarly Spring MVC includes view resolvers and views for Velocity and FreeMarker.

Which is better, Velocity or FreeMarker? I'll probably be writing an in-depth article comparing the two quite soon, but as a short answer... both have their own advantages and drawbacks. Velocity is simpler to learn, but FreeMarker offers more built-in functionality. Velocity is a bit more forgiving than FreeMarker but that may not be such a good thing, especially for larger applications. If I were asked to lay my cards on the table right now, I'd have to say that while I've used Velocity extensively over the last few years, I will almost certainly be using FreeMarker in the future.

In Summary...

Don't use JSP for Model 2 applications.

Use Velocity or FreeMarker instead.

Once you've developed a web application with Velocity or FreeMarker, I can almost guarantee you'll never want to write another JSP again.

ClassLoaders and Web Applications

2008-06-27T10:54:00.003-05:00

This post has changed to correct some errors

In the previous posting I described the class loader heirarchy, and mentioned that you can use standard Java API classes and methods to create a branching tree structure of loaders. I also touched on the fact that Java EE application servers use this to ensure that each web application gets its own private load path for classes.

However, the loading rules as I described them don't quite apply to web applications, so this article is intended to cover the differences.

I'm describing the way things work in Tomcat; other servers should be doing something similar.

Tomcat Loader Heirarchy

As I mentioned in the previous post, ordinary Java applications have three loaders at run time: the Boot loader, which is usually native, platform-specific code built into the JVM and searches the standard class libraries; the Extension class loader, which searches JARs in the $JAVA_HOME/jre/lib/ext directory; and the System class loader, which searches directories and JARs specified in the CLASSPATH. The Extension loader is the parent of the System loader, and the Boot loader is (in practice) the parent of the Extension loader. Slight correction: some JVMs combine the Boot and Extension loaders into one.

Tomcat adds two more levels to this heirarchy for web applications: at the bottom, a WebappClassLoader (one for each deployed web application) with the application's WEB-INF/classes and all the archive files in the WEB-INF/lib directory set as the search path; and above that a StandardClassLoader (one only for the whole server), with its search path set as Tomcat's lib directory and all the archive files in it.

Tomcat's system class loader is the parent of this StandardClassLoader and has its search path set to include Tomcat's bootstrap.jar file and little else.

The StandardClassLoader class is a subclass of URLClassLoader but doesn't add or override anything from that class - it's functionally identical.

The WebappClassLoader class, on the other hand, subclasses URLClassLoader but reimplements most if not all of the methods. Here's why...

Servlet API loader rules

The Servlet API specification is the root of things here; it says that the loader search algorithm for web applications should ensure that classes and JARs packaged in the WAR should be searched before any of the servlet container's library JAR files, but should not allow the application to override any of the standard Java classes.

Tomcat's WebappClassLoader achieves the first part of this (searching the WAR contents first) by not delegating searches to its parent until after it has already searched its own repositories - the opposite of the usual procedure. (I'm not clear on how it ensures that standard classes don't get overridden - the code in that area is tricky to follow.) Major correction required here: In fact the WebAppClassLoader delegates directly to the System class loader first, then searches its own repositories, then finally delegates to its parent. This ensures that JRE classes can't be overridden (they get searched first) and that repositories are searched before Tomcat's lib contents.

That covers the important differences that apply to web applications. There is one other small aspect that I'd like to mention.

Getting Resources

The Servlet API specification also mandates that web applications must be able to locate their own resources using ClassLoader.getResource(). The heirarchy as described achieves this. However the specification says nothing about the static ClassLoader.getSystemResource() method and in fact this method is of little use in web applications because the System class loader doesn't know anything about the web application's resources (as you can see from where it is in the heirarchy as described).

Modifying the CLASSPATH at run time

2008-06-06T12:29:00.008-05:00

Here's a question that comes my way occasionally: How can you change the search path for class loading at run time?

For example, let's say I have an application that reads the name of a JAR file from an external source, and then needs to add that JAR to the classpath so that it can load classes from it. This is something that's more likely to come up in a server environment, where you need the server to be able to add plug-in classes dynamically. For example, application servers like Tomcat need to be able to unpack a WAR file when requested; after unpacking there will be a 'classes' directory and a 'lib' directory full of JARs, all of which have to be added to the loading path so that the application can be started.

The solution to this problem requires an understanding of how the ClassLoader heirarchy works, so I'm going to cover that in some detail first.

ClassLoaders

The JVM includes a loader, usually referred to as the Boot loader. The default search path that this loader uses includes the Java runtime classes - java.lang, java.util, etc.

When the JVM is started it creates a ClassLoader object (loaded by the boot loader), usually referred to as the Extension ClassLoader. Its search path includes several JAR files found in the JVM's jre/lib/ext/ directory.

Then, the System loader is created. The search path for this loader is initialized from the CLASSPATH environment variable or from the value passed as the -cp option on the command line. (The label 'System' is a bit confusing; personally I think 'Application' class loader would be a more accurate and descriptive name.)

ClassLoaders are arranged in a heirarchy; each loader has a parent loader. The extension loader is the parent of the system loader; the parent of the extension loader is usually set as null. The boot loader is something of an exception in this respect - it's technically the parent of the extension loader but because it's part of the native implementation of the JVM and hence not a Class in the usual sense, it normally can't be accessed as a Java object.

When the JVM recognizes that it needs to load a new class, it calls a loader to do that. The loader it chooses is the same loader that loaded the class where the new class is first referenced at run time - that means that by default, when your application code first references a class that hasn't yet been loaded, it will call the system loader (the one that loaded your application classes).

The first thing the loader does is to delegate the request to its parent if it has one. The result of this is that all requests for new class references get delegated all the way up to the boot loader. So, if your code has requested a class that's to be found in the Java runtime, such as java.util.Map or java.text.Format, the boot loader will find and load the class.

If the loader can't locate the class it tells the caller - so if the class you requested is not in the boot loader path, it tells the extension loader that called it so. If the class isn't in any of the extension JARs, it gets passed back to the system loader. The system loader then attempts to find the class and in the case of your application classes, this would be where those get resolved. (Of course, if the request makes it all the way back down the heirarchy without the class being found, you'll get a ClassNotFoundException.)

To expand slightly: when a loader is called to load a class, this is the sequence of actions:

1 - delegate to the parent loader if there is one. If the parent finds the class, the loader returns to its caller at this point.

2 - if the parent doesn't find the class, or if there is no parent, the loader checks its local data to see if it already loaded the class. If it finds it, the loader returns at this point.

3 - if the class definition isn't found in the local data, the loader attempts to find the class definition in its search path. If the class definition is found in the path, the class is loaded and added to the loader's local data, and the loader returns.

4 - if this point is reached, the class hasn't been found - the loader returns control to its caller indicating such.

The Answer

Back to the original question: How to add more places to the search? The way to do that is to create a new loader with the locations you want to search set as its search path, and add this new loader into the heirarchy.

ClassLoader is an abstract class, and so can't be instantiated. Instead you'd normally use a URLClassLoader, which is basically the class to use - it does everything you would usually need. You can create your own loader classes by extending ClassLoader, but normally this is unnecessary.

The search path for URLClassLoader is provided as an array of java.net.URL objects; each URL identifies a directory or an archive file (.jar or .zip) to be searched when loading.

Let's say I have a JAR named /tmp/my-jar.jar and it contains a class called com.example.MyClass. I need to create an instance of this class. This code should do the trick:

    // First, set the search path
    URL[] searchPath = new URL[1];
    searchPath[0] = new File("/tmp/my-jar.jar")
                            .toURI()
                            .toURL();

    // Now create a new loader
    ClassLoader cl = new URLClassLoader(searchPath);

    // Now we can load from the JAR:
    Object o = Class.forName("com.example.MyClass",
                             true,
                             cl)
                    .newInstance();

A few notes about this code:

First, the URL array can contain URLs for directories as well as JAR and ZIP files. The example here has only one entry but you could provide an array containing hundreds of entries if you needed to. Note that you can't use wildcards here - each entry must point to a single archive file or directory.

Second, the loader created by the URLClassLoader constructor will have the system loader as a parent by default. You can provide a different parent as a second parameter to the constructor - this allows you to build a full-blown heirarchical tree of loaders within your application if you so wish.

Third, note the three-parameter call to Class.forName() - the first parameter is the class name, of course, as in the one-parameter call. The third parameter specifies our new loader as the one to use to load our class; the default is to use the same loader that loaded the calling class (this.getClass().getClassLoader()). The second parameter determines whether or not the class should be initialized (i.e. have its static initializer called) and you'd normally set this to true (offhand I can't think of a circumstance where you wouldn't want to to this).

Lastly, note that the new loader becomes the default for classes referenced by the newly-loaded classes. This means that MyClass can reference other classes in my-jar.jar implicitly or explicitly (i.e. using the one-parameter Class.forName() method) and the classes will be loaded correctly.

Using this you can create a structure of loaders organized as you need to implement different search paths for different requirements (for example, Tomcat uses one branch of a loader tree for its own server classes and another as a connection point for loading web applications; each webapp gets its own subtree. That's how multiple webapps can exist even with conflicting class names or versions, and without being able to access the server's internal classes).

Where the Class definitions are kept

Each loader keeps the Class objects that it loads in its own local space.

This means that if you create two loaders, each with the system loader as parent but with common directories and/or archive files in their search paths, it becomes possible to load the same class twice by invoking both class loaders to load the same class.

Other things URLClassLoader can do

To finish up, here are a couple of other useful things that you can do:

First, there's a method URLClassLoader.getURLs() that returns the loader's current search path as an array of URLs. This can be useful for debugging.

Second, loaders aren't limited to finding .class files - you can use them to find other resources that are in the search path. This applies to all loaders (i.e. ClassLoader and all its subclasses, not just URLClassLoader). This is extremely useful because it allows you to, for example, read from a property file embedded inside a JAR. Some methods that are especially useful are:

ClassLoader.getResource() - returns the URL of a named resource;

ClassLoader.getResourceAsStream() - returns an InputStream allowing you to read a named resource directly (handy for loading .properties files);

ClassLoader.getSystemResource() and ClassLoader.getSystemResourceAsStream() - static methods that do the same as the above methods, but use the system loader rather than a specific one that you may have created.

Ginger 1.4 released

2008-03-02T00:46:00.001-06:00

I've just made the latest release of Ginger available on SourceForge.net. This version removes the code that was deprecated in version 1.3, cleans up a few comments (to fix references to the old "Point" classes and methods that got held over from Lynx, Ginger's predecessor). I've also replaced use of the StringBuffer class with the StringBuilder class that was introduced in Java 5, and done some other general code cleanup (nothing that affects the way it works, though - it's fully backward compatible with Ginger 1.3).

This is likely to be the final version of Ginger, as it appears to work just fine and I see no need to add or change anything more at this time. I want to change gears a bit and start working on one or two other small packages I have in mind for the Bohemia project.

How to set up a Derby server as a Tomcat application

2007-12-15T15:38:00.001-06:00

What is Derby?

Derby is a 100% pure Java database engine. Its main strength is that it's embeddable, so if you have a standalone application that could benefit from keeping persistent data in a database but you don't want to have to set up a separate database server just to support it, Derby may be the answer. In the embedded mode your application starts Derby during initialization and shuts it down during termination. In the meantime it can work with database tables using SQL statements through a JDBC driver in the usual way.

Why this article?

Derby can also run as a network server, like any other database. Not only that, you can install it as a web application in a server such as Tomcat so that your database server is available whenever your web server is. In fact, the Derby distribution includes a WAR file that you can deploy that makes this very easy.

The problem is that Derby's documentation seems to concentrate on the embedded mode of operation and it's not easy to find information about setting it up as a Tomcat application without quite a bit of digging. Since I've been through this particular loop I decided to write this, partially as a reference for myself in case I need to do it again, and also for others needing to do the same thing.

This article describes the setup with Tomcat 6 running on Windows (XP Pro, specifically). Unix/Linux setup is similar and it shouldn't be a problem for anyone familiar with those systems to adapt the steps as required.

Download and unpack the distribution

Derby is distributed as a .zip or .tar.gz archive. There are a couple of different downloads available depending on whether you just want the executable JAR files or the full package including documents and sample code. Download the appropriate one then simply unpack it into a convenient place. I used the 'bin' distribution which includes everything.

The archive unpacks such that everything is inside one directory (the current version puts itself into 'db-derby-10.3.2.1-bin' for example, for the 'bin' distribution). This is Derby's 'home' directory, which we'll need to know in a moment.

Setting the environment and Java system properties

Derby only really needs one environment setting: DERBY_HOME should be set to the path of the home directory as noted above. On a Windows system use 'Control Panel-> System' then open the Advanced tab. You can add the new environment setting as a System or User value in the dialog there. 'System' is probably better, especially if you run Tomcat as a service.

You may also want to add %DERBY_HOME%\bin to your PATH setting; this isn't required but it makes it easier to run the Derby command-line tools.

One Java system property really needs to be set, too: derby.system.home identifies a directory where Derby will keep all its databases. Without this, when you run Derby under Tomcat it will default to '.', which equates to the Tomcat installation directory - the place where it keeps its conf and WebApps directories. This is almost certainly not a good idea (imagine what might happen if an application tries to create a database called 'conf').

I created a "DerbyData" directory to hold all my databases. Setting the derby.system.home property is a little bit of a problem, but I found a solution that works fine; Tomcat 5 and 6 include a "Monitor" program that you can run, at least on Windows. You can use this to set up the system properties (run the monitor, right-click on the system tray icon that appears, then open the 'Configure' option and click the 'Java' tab). Add -Dderby.system.home=your-database-directory to the system properties and click OK. Tomcat doesn't need to be running to do this.

Deploying derby.war

Start Tomcat (if it's already running you should probably shut it down and restart). Start your browser, find the Tomcat Manager page and log in.

Deploy the Derby WAR file in the usual way. You'll find the WAR file (derby.war) in Derby's lib directory.

You should now be able to hit the Derby service in your browser - it'll be at /derby/derbynet. This starts the database running, and if everything's ok you'll see a status page.

Modifying Derby's web.xml

We're not quite done yet. With the default installation you have to hit the Derby URL as above to start the database running every time you restart Tomcat. What's happening is that the database is started by the servlet's init() method, and that isn't happening until Tomcat gets a request. This probably isn't what you want, especially if you're planning to create other web applications that use the service. You probably want the thing to come up on its own.

You'll find Derby's web.xml file under your Tomcat installation at WebApps/derby/WEB-INF/web.xml. Open the file in a text editor and add the following tag inside the <servlet> tag:

<load-on-startup>0</load-on-startup>

This will cause Tomcat to call the servlet's initialization during startup instead of waiting for a request.

Save your text change and restart Tomcat.

Testing

After restarting Tomcat you should see a 'derby.log' file appear in your database directory. It may take a few seconds for this to happen, so give it time - if it hasn't shown up after, say, a minute, you may want to check your Tomcat logs to see if anything bad happened. Also, check your Tomcat directory to make sure the log file didn't show up there - if it did, it means that the derby.system.home setting hasn't taken for some reason, in which case you should go back and check for misspellings, etc.

If the log file appears in the right place, that probably means everything's ok so far. You can test the installation using Derby's ij command-line tool. Open a command window and do this (this assumes that you set the PATH environment as suggested earlier):

> ij
ij version 10.3
> connect 'jdbc:derby://localhost/testdata;create=true';
> exit;
>

This tells ij to open a connection to the database named 'testdata', creating it if it doesn't exist (which it shouldn't, at this point).

Now check your database directory - there should be a subdirectory called 'testdata' if all went well. You can delete it manually, although I'd recommend shutting Derby down first - either shut down Tomcat or hit the Derby URL as above and click the Stop button.

Congratulations! You now have a database server that will be available whenever Tomcat is running.

Ginger 1.3 adds better handling of HTTP request methods

2007-12-15T12:17:00.000-06:00

No plans for more changes in the near future

I realized after some thought that up until now Ginger was written with a bad assumption in the back of my mind - the assumption that it would only ever have to deal with GET and POST requests. This is not a good assumption, because there are six other types of request that it may have to deal with depending on how your servlet mappings are set up in the deployment descriptor.

HttpServlet is designed to identify the request type for you and takes default actions for the ones you don't explicitly set up to handle in a subclass, but for several reasons Ginger couldn't subclass from that. In fact, Ginger isn't a subclass at all, really - it just implements the Servlet interface directly.

So, in Ginger 1.3 I've added a mechanism to give you control over which HTTP request methods will be handled. By default, it will deal with GET, POST, HEAD, OPTIONS and TRACE. If it receives a request with a type not in that set, it'll respond with a 405 error. That means that by default your subclass servlet won't have to worry about CONNECT, DELETE and PUT requests.

You can change the set in your servletInit(), to define the set of requests you want your servlet to accept. Note though that Ginger itself will handle OPTIONS and TRACE requests in a way you can't override; it will automatically create responses and never calls any command methods for these requests. Also, by default it handles HEAD requests by running your configured commands in the normal way and rendering output from your templates, but the rendered data is only used to generate the character count for the response header - it isn't sent back to the client. (A nice benefit of the code change that makes this work is that Ginger now buffers the output internally for GET and POST responses; this makes it possible to set the response length, which in turn makes it possible for the servlet container to use a persistent connection, which in turn improves response times.) It is possible for your command methods to modify their behaviour for HEAD requests, but doing that really isn't recommended.

Another fairly big change I've made is to deprecate the Context class and replace it with a new class called Dynamic which is otherwise identical. The reason for this is that the name 'Context' is used in several packages all related to web applications - it's used in JNDI, servlet containers use the name to refer to a web application (Tomcat does, anyway), Velocity uses it to mean something completely different again, and there are probably other places too. That means you may have to fully-qualify com.codexombie.bohemia.ginger.Context in every command method that also accesses a JNDI context, for example. That's messy and error-prone, which is why I decided to make the change. Dynamic is so named because it's intended to hold dynamic data for the template merge (among other things) and I couldn't think of a better name that wasn't already in common use. Existing code can still use the old Context class but you'll get deprecation warnings, and in any case I don't intend to leave the deprecated code in place forever - it'll be removed entirely in a future release.

On the subject of future releases, I'm not planning to make any more changes for a while; the 1.3 release is the fourth in just a few weeks, which is a bit rushed. Unless I find that there's a major problem that needs fixing, there won't be any new releases for at least a couple of months (and even then, the only change may be to remove that deprecated code I mentioned).

The new release is, of course, available for download at the usual place.

Ginger 1.2

2007-12-07T01:02:00.001-06:00

Adds basic JSP support

I've added very basic support for JSPs to Ginger through the addition of a new template processor. It's not intended to be a replacement for Velocity and doesn't indicate a shift in that direction - it's just to provide some level of support in case JSP is necessary for one or two pages in an application, and for some reason Velocity won't do what's needed. Check it out in the usual place.

I have no plans for further releases in the near future - I'm hoping it's stable enough to stand without more changes for a while to come.

New Ginger Version Released

2007-11-30T00:05:00.001-06:00

Version 1.1 is now available

The new version adds three new attributes to render command configuration; these allow control of content-type, character set encoding and also allow for a 'no-render' mode of operation in which the final rendering phase is not performed. This makes it possible for a render command to set up the HTTP response with a redirection URL or an error code return, without needing to specify a superfluous template to be rendered.

The demo application has also undergone a facelift and adds the ability to switch between HTTP and HTTPS protocols. The primary purpose of this isn't to make the demo any more functional; it's so that developers can read the source code to see how it's done under Ginger.

Last, the Quick Start manual has been updated to include the changes.

See the Bohemia home page for full details.

The Bohemia Project

2007-11-06T23:40:00.000-06:00

Lynx is renamed and moved to SourceForge.net

The last stable release of Lynx was version 5.4. For what was intended to be version 5.5, I decided on some rather far-reaching changes that stemmed from using the package to build some applications. As I was making the changes I thought of other changes to simplify the internal data structures and the API.

In the end, the changes would make 5.5 incompatible with applications developed for 5.4 and earlier. My first thought was to renumber the updated package as Lynx 6.0, but instead I decided to rename the package and make it available on SourceForge.net. Among other things, I have no way of knowing how many copies of Lynx were downloaded from the CodeXombie site because there were no tools to gather those stats; SourceForge includes those tools so I can keep tabs on how much interest there is.

I've had ideas for several lightweight packages that would help with developing web applications, and rather than setting up several separate SourceForge projects, I took a leaf from the Apache book; I've created one umbrella project to encompass all these related packages.

And so I'm pleased to announce the inception of The Bohemia Project, and as its first downloadable product what was going to be Lynx 6.0 is now Ginger 1.0.

There's also a downloadable demo that uses the new package - it's a functional application but its primary function is to show source code written to use the Ginger API, and how to set up the configuration XML file.

The older Lynx packages have been removed from the CodeXombie web site and the links have been updated to point to the new home on SourceForge.

I'll continue to post here about updates and new packages as they happen.

Another version of Lynx

2007-09-10T21:50:00.000-05:00

Another one so soon?

I've added a new feature - it's a simple one but possibly useful, so I went ahead and created a new version. I'd forgotten that the Properties class, as of Java 5, includes methods to load and store from XML files. I've added a new Points loader to handle XML format. Details are here.

New Lynx version available now

2007-09-05T00:32:00.000-05:00

Lynx 5.2 is available for download

A new version of Lynx is now available for download from my main site. The new version should be compatible with version 5.1, so if you have existing servlets written with the older version they should work without changes.

Version 5.2 adds support for forward references so it's no longer necessary to define the points in "reverse order", as it were. It also means that you can set up LogicPoints in a way that implements loops and branches.

The other major change is that you can now define your Points configuration in a Properties file instead of having to hard-code the calls. This makes it easier to see your configuration.

There are also a handful of smaller changes. For full details see the (new) third page of the Lynx tutorial, which describes the changes in detail together with examples of use.

New Lynx version coming soon/Page updates

2007-09-01T01:14:00.000-05:00

Lynx 5.2 is under test

I'm in the process of updating Lynx with a couple of relatively minor changes, and one fairly major change. None of these should impact any existing applications.

One change is purely internal: I've changed the key that's used in RenderPoints to identify the Velocity template for rendered pages. The old key was purely alphabetic and there was a small chance that a developer might use the same key for something else in the context. The new key adds some underscore characters to minimize the risk.

Another change is to allow forward references for Point names. This adds a little flexibility, but the main reason was that it makes the third change possible.

That third change is the addition of a new feature that will allow developers to use a Properties file to specify the Points and Mappings.

This last feature is still under development. The new version should be available from the CodeXombie.com web page in a week or two.

Page Updates

The CodeXombie.com web page has undergone a facelift. The old page was thrown together in a bit of a hurry, just to get something there. I've made some changes to the background and banner images. I think you'll agree it's a big improvement.

CodeXombie.com is alive!

2007-08-09T02:18:00.000-05:00

More Java content than I can post here

I've moved my domain, CodeXombie.com to new hosting and while I was at it I've completely rewritten the whole thing. The colours and images need some work, but it'll do for now and I'll be tidying the presentation up as time goes on.

Java Planet will continue to be the place I post code snippets, tricks and tips, while the new site will be the place for complete packages, lightweight frameworks and so on.

To start things off I've placed a link to JSpasm, which is a small but pretty complete package for developing applications based on state machines. Since JSpasm is hosted on SourgeForge.net I didn't see the point of having copies on the new site, so there's minimal information about that.

I've also put up my Lynx package. Lynx is a lightweight alternative to Struts and JSP that's designed for small web applications. It gives you complete Model/View separation, using Velocity for the presentation side. I've included a two-page tutorial to get you started. Take a look!

More of the same

2007-07-25T13:57:00.000-05:00

Another Example

Continuing from yesterday, here's another example of the quick-n-dirty development technique I was describing. Before I go too much further, I need to explain a couple of things:

Velocity

I mentioned Velocity yesterday. For those that don't know, Velocity is a text templating package. You create templates containing tags (marked with $ signs), and provide a Context, which is basically a Map. Velocity can then merge the template with the context to create output which is usually written directly to a Writer. As an example, I might have this template (let's call it MyTemplate.txt):

Dear $firstname,

Here is the list of books you have ordered:

#foreach( $book in $booklist )
$book
#end

Regards...

In my code, I can create the context and merge with the template:

// Create the Context
Map<String, Object> map = new HashMap<String, Object>();
map.put("firstname", "Fred");
List<String> books = new ArrayList<String>();
books.add
    ("Quidditch Through the Ages");
books.add
    ("Fantastic Beasts & Where to Find Them");
map.put("booklist", books);
VelocityContext ctx = new VelocityContext(map);

// Merge - assumes we already have a VelocityEngine
velocityEngine.mergeTemplate("MyTemplate.txt", ctx, writer);

The result would look like this:

Dear Fred,

Here is the list of books you have ordered:

Quidditch Through the Ages
Fantastic Beasts & Where to Find Them

Regards...

iText

iText is an open-source package that (among other things) makes it easy to create PDF documents. You use it by creating a Document object then calling API methods to add paragraphs, images, and tables, set fonts, colours, text alignments and so on.

Back to the plot...

Let's say you want to be able to use Velocity templates to generate PDF documents. As things stand there's an immediate problem: Velocity needs a Writer to deliver its output to, but iText doesn't include one - and even if it did, how would it know when to insert tables, text font/colour changes, page breaks and so on?

Here is one possible solution: create an ITextWriter class, subclassing Writer, which will bridge the gap. It makes the necessary calls to the iText API according to directives it finds embedded in its input data.

The way I did this was to add the input characters from the write() calls to a StringBuffer, then look at the buffer to see if I had a complete line of text. If the line starts with a '[' and ends with a ']', it's taken to be a directive line. All other lines are treated as text to be added to the document using the current style (font, colour, alignment etc.).

So let's say I have a Velocity template that looks like this:

Here is the report for
[bold]
[color red]
$date
[normal]
[newline]
at
[font verdana 16]
[bold]
[color blue]
$time
[normal]

Velocity processes this and directs the output into the ITextWriter:

Here is the report for
[bold]
[color red]
Wednesday, July 25 2007
[normal]
[newline]
at
[font verdana 16]
[bold]
[color blue]
12:47pm
[normal]

Now, here's where the technique I described yesterday comes into play. When a directive line is found the code breaks out the first keyword (color, for example) as the directive name and places the rest into a String[] array. Then it locates a method with the directive name that accepts a String[] argument and calls it, passing the array as the argument. The method makes the necessary calls to the iText API to take care of getting the data out to the PDF document in the specified format. The result:

Here is the report for Wednesday, July 25 2007
at 12:47pm

The great thing about this is that if I need some new formatting control, all I need to do is add a new method with a meaningful name - and the job's done:

void pagebreak(String[] args)
{
    ...
}

In fact, the first version of the writer only had perhaps half a dozen directive methods and I added new ones as I went along, as I found I needed them for the project I was working on. The current version has about twenty methods, and most of the new methods took only minutes to create and test.

A Technique for Faster Development

2007-07-24T16:53:00.000-05:00

Take a look at this:

import static java.lang.Integer.parseInt;
import static java.lang.System.out;

import java.lang.reflect.Method;

public class DynamicMethods
{
    public int operation(String op,
            int a,
            int b) throws Exception
    {
        Class<? extends DynamicMethods> c = this
                .getClass();
        Class<?>[] argtypes = {
                int.class, int.class};
        Method m = c
                .getDeclaredMethod(op,
                        argtypes);
        Object[] args = {a, b};
        int result = (Integer) m
                .invoke(this, args);
        return result;
    }

    int add(int a, int b)
    {
        return a + b;
    }

    public static void main(String[] args)
            throws Exception
    {
        DynamicMethods dm = new DynamicMethods();
        int c = dm.operation(args[0],
                parseInt(args[1]),
                parseInt(args[2]));
        out.println("Result = " + c);
    }
}

Look first at the operation() method. It takes a String ("op") and locates a Method within this class that has that name and takes two ints as arguments. It then calls that method, passing in the arguments it was given.

Now, look at the main(). The first argument is used as the op value, while the other two are parsed as integer values and passed as the other two arguments in a call to operation().

So, if we run this little program with the arguments "add 4 8", operation() calls add(), passing 4 and 8 as arguments. add() returns the sum (12), which is printed out by main().

This may seem trivial but it is the core of a powerful technique that I've found can reduce development time significantly on certain types of projects. Here's the important part: let's say I want to add a "multiply" operation. All I need to do is add the new method...

int multiply(int a, int b)
{
    return a * b;
}

...and I'm done. Now I can run the application again with "multiply 4 8" as arguments and it works right away. I don't need to add lookup table entries, or change some XML file to configure in the new function. I can add as many new operations as I like just as easily - all I have to do is make sure that the new methods have a signature that has this pattern:

int operationName(int a, int b)
{
    ...
}

Here's an example with a bit more meat. Recently I developed a small web application to run in Tomcat. It only needed about four different page layouts, so I didn't see the need to mess around with the complication of Struts, JSPs and Action Classes (in my opinion Struts introduces way more complication than is necessary to do what it does anyway, and this only gets worse as the projects get larger). Instead, the HTML is generated from Velocity templates.

Tomcat is configured to pass all URIs with pathnames ending in "*.do" to the application's one and only servlet. Here is the servlet's service() method (with try/catch blocks removed for clarity):

public void service(ServletRequest request,
            ServletResponse response)
            throws ServletException,
            IOException
    {
        // Cast req/resp to more useful types
        HttpServletRequest rq =
            (HttpServletRequest) request;
        HttpServletResponse rs =
            (HttpServletResponse) response;

        // Get the URI, strip off the leading '/'
        // and the ending ".do"
        String uri = rq.getServletPath();
        String methodName = uri.substring(1,
            uri.indexOf(".do"));

        // Find the right method
        Class<? extends MyServlet> c = this.getClass();
        Class<?>[] argTypes = {
                HttpServletRequest.class,
                HttpServletResponse.class};
        Method method = c.getDeclaredMethod(methodName,
                        argTypes);

        // Call the method, get back a Map
        Object[] args = {rq, rs};
        Map<String, Object> m =
          (Map<String, Object>) method.invoke(this, args);

        // The map contains the required Velocity
        // template name
        String templateName =
            (String) m.get("templateName");

        // Use the map as a Velocity Context and merge -
        // output streams to the client browser
        VelocityContext ctx = new VelocityContext(m);
        velocityEngine.mergeTemplate(templateName,
                        ctx,
                        response.getWriter());
    }
}

Let's say I need to add a "/menu.do" operation. All I need do in the servlet is add one method:

Map<String, Object> menu(HttpServletRequest request,
    HttpServletResponse response)
{
    ...
}

This method performs whatever business logic is required and returns a Map that can be used as a Velocity context. The map must also contain a key, "templateName" identifying the Velocity template that the context is to be merged with. service() takes care of the rest.

This isn't a 100% ideal solution because part of the presentation logic (building the map) is in the methods along with the business logic - but the actual rendering is controlled by the template, so the methods don't need to mess with that. But for small applications I've found this is an excellent approach.

Java Planet is on extended vacation

2005-11-03T22:10:00.000-06:00

No new posts for the foreseeable future, folks...

Sorry to say I don't really have the time any more to maintain two blogs. Many people evidently put blog-writing high on their priority lists, but I'm not one of those people; I write as and when I feel like it and have the time outside my other interests.

I'll leave the existing posts in place just in case anyone has them bookmarked for reference. And anyway, because I may still post occasionally as I come across interesting Java hints, tips and ideas, I have no intention of deleting the posts.

So, until such time as I have more to add, I will bid you all "Happy Java" :)

Taking a break

2005-09-23T15:07:00.000-05:00

No post last week because we were out of town. I'm working on this coming week's post now but I'm not feeling great so it may be delayed a day or two.

Java isn't just for applets

2005-09-07T10:28:00.000-05:00

How Java could change just about everything

This article is a little late because of the Labor Day holiday weekend. Also, this is not a technical article as such; instead this will be, in part, an answer to a question that was posted in a comment on my Augmented Reality blog. The question, from QiSoftware, was:

You write a lot of Java programs for non-internet use? Is there an audience for Java at this level?

The short answer that I gave was basically that Java is no longer just for Internet applications and web-page applets. The full answer is a little more involved. What follows is my opinion of the current Java landscape.

Most of the Java applications I develop these days are for Internet or intranet use - but in our networked world, the same is probably true of applications that C and C++ developers are creating. Java is also just as useful for creating stand-alone applications, including those with GUIs. The main advantage of Java over C/C++ for almost any application can be summed up in a single word: Portability. I can develop and test an application on a Windows system and be almost certain that I can move the compiled binary to any other platform and it will work.

Of course, it's not all wine and roses; Java has its drawbacks too. For one thing, because Java compiles to interpreted bytecodes it's not as efficient as a purely compiled language. Things are getting better all the time on that front, because the JVMs can translate bytecodes to native machine code and the result is that a Java application running on a modern JVM isn't much slower than a native-compiled equivalent. For anything but the most high-performance applications, Java is fast enough.

Other drawbacks aren't so much technical as, for want of better terms, legal and political. For example, because of Sun's licensing restrictions you can't guarantee that any target platform will have a Java runtime installed, which means that you can't just give a Java application to a non-technical user and have them install and use it as easily as a native application - they may have to go to Sun's Java website and download and install a JRE (making sure to sign the license agreements) before they can run any Java applications.

One day, I hope, we will see JVMs being packaged as part of all major operating systems so that it's there and usable right out of the box. You'll be able to install Java applications as easily as native Windows or Linux applications, and the OS will recognize executable JAR files as such and know when you click on an application icon that it needs to fire up the JVM to run it.

Static Initializers

2005-08-28T23:56:00.000-05:00

An extremely powerful feature

Here is a very simple class:

public class Sample
{
    public static int x = 6;
}

This is straightforward enough - any code that reads Sample.x will get the correct value. The question is, where is the value of x actually set?

The answer is that the Java compiler generates code to initialize the static data, and this code is included in the resulting class file. The JVM executes this code as soon as the class has been loaded into memory. In the case of our Sample class, the first reference to the class causes the JVM to locate the class file, load it into memory then run the initialization code. All of the initialization code for a given class is encapsulated into a single "method", called the static initializer.

Static initializers do not have names, arguments, or access modifiers and do not return any values - in other words, you can't call static initializers as if they were methods. A class's static initializer is run once and once only during the lifetime of an application, at the point where the class is loaded.

If initializing data fields were all that static initializers did, they wouldn't be particularly interesting. What makes them far more powerful is that you can write your own code to be added to the static initializers of your own classes. Here is an example:

public class Sample2
{
    public final static Properties props;
    static
    {
        props = new Properties();
        try
        {
            InputStream is = new FileInputStream(
                    "my.properties");
            props.load(is);
            is.close();
        }
        catch (Exception e)
        {
            e.printStackTrace();
        }
    }
}

The first thing to note is the static keyword followed by a block of code - this is how we tell the compiler that the code is to be added to the static initializer. In this case loading the class causes it to load the Properties object from a file.

Some other things to know about static initializers: first, you can include as many static{...} sections as you like in a class source; each section of compiled code is added to the static initializer in the order the static blocks appear in the source. Second, static initializer code can throw only uncaught exceptions (hence the try/catch block in the example). Third, note that any final static data must be initialized; in the example the final props field isn't initialized at the point where it's declared, which would normally be an error, but it's assigned in our static initializer so the compiler doesn't complain.

You can put pretty much any code you like into static initializers - this simple fact makes them surprisingly powerful.

For example, if you've ever used JDBC you may have wondered how it manages to select the correct driver for a given database URL when there is more than one driver loaded. The trick is that all JDBC drivers' static initializers include code that creates an instance of the driver and then passes this object to a static method in the DriverManager class, which adds the driver to an internal list; when your application passes a URL string to DriverManager.getConnection(), that method iterates through the list of drivers and passes the URL to each driver in turn, until one of them recognizes the URL format and opens and returns a database connection.

Another example is Log4J, whose Logger class has a static initializer that by default scans the directories in the classpath looking for a file named "log4j.xml" or "log4j.properties". If it finds such a file it reads the logging configuration from it. This means that you don't need to write a single line of configuration code - the configuration can be completely defined in a file, and this will be loaded automatically the first time your application references the Logger. Velocity - a templating package from the Apache Jakarta project - uses a similar technique to load its default configuration settings.

I leave it to you, adventurous reader, to think of more applications for static initializers.

Considering that static initializers are so powerful and also that it would be impossible to understand some commonly-used packages without having an understanding of them, it is strange and surprising that there are a number of (otherwise excellent) books about Java programming that that make no mention of them whatsoever. My recommendation, when choosing a book, is to check the index for mention of static initializers; if there's no reference, move on to the next book.

How to set up a simple LRU cache using LinkedHashMap

2005-08-21T14:27:00.000-05:00

Caches

Caches are a simple way to improve the performance of an application that reads data from a "slow" source such as files on disk or rows of data from a database table, but may need to re-read the same data multiple times. The idea is simple: instead of discarding the data after using it, keep it in memory so that it doesn't have to be re-read later.

For example, a simple way to organize this for files might be to create a HashMap that maps the file names to objects containing the file data. When your application needs a particular file it first checks the map to see if it already has the data; if it doesn't, it reads the file and places it in the map in case it needs it again later.

LRU caches

The problem with this simple method is that your application could use a vast amount of memory. Once read in, a file is in the cache for the lifetime of the application whether or not it is ever used again. For an application such as a server that is intended to stay up and running for weeks or months at a time, this is probably not acceptable.

What's needed is a cache that automatically discards entries that haven't been accessed for some time so as to limit the amount of space being used. Such as cache is called an LRU Cache. LRU stands for "Least Recently Used", which refers to the policy of removing the oldest, or least-recently used entries to make space for new data.

LRU caches have a maximum number of data items that they will hold and these items are usually arranged in a list. When an item is added to the cache, and every time it is accessed after that, it is automatically moved to the head of the list. If the cache is full and a slot is required for a new item, the cache makes room by discarding the entry at the tail of the list - the least-recently used item.

The java.util.LinkedHashMap class

LinkedHashMap is a subclass of java.util.HashMap that adds a couple of useful features. One is that by default the iteration order reflects the order that entries are added to the map, rather than the rather haphazard order of a HashMap.

The other feature - the one we're interested in here - is that LinkedHashMap has an option to use access-order instead of insertion order, and includes a way to remove the least-recently accessed entries automatically. This makes it well suited for creating LRU caches.

Creating a cache class

The simplest way to create a cache using LinkedHashMap is to extend it. Here is an example:

public class Cache extends
    LinkedHashMap
{
  private final int capacity;

  public Cache(int capacity)
  {
    super(capacity + 1, 1.1f, true);
    this.capacity = capacity;
  }

  protected boolean removeEldestEntry(Entry eldest)
  {
    return size() > capacity;
  }
}

Note that the constructor takes as an argument the maximum number of entries we want a Cache object to hold. The superclass constructor has three arguments: the initial capacity of the map, the load factor, and a boolean argument that tells the LinkedHashMap constructor to keep entries in access order instead of the default insertion order. (See the java.util.HashMap API documentation for a description of the initial capacity and load factor.) In this case we set the initial capacity to be one more than our required cache size - this is because new entries are added before any are removed, so for example if we want to hold 100 entries the cache will actually contain 101 for an instant when new data is added. Setting the load factor to 1.1 ensures that the rehashing mechanism of the underlying HashMap class isn't triggered - this isn't a vital point but helps a little with efficiency at run-time.

The removeEldestEntry() method overrides a default implementation in LinkedHashMap and is where we determine the policy for removing the oldest entry. In this case, we return true when the cache has more entries than our defined capacity.

Using the cache

Using the cache is simple - just use a suitable key to access the cache; if the data is in the cache we can read it from there. If it's not there we pull it from the slow medium and add it to the cache so that it's in place if needed later:

    Cache cache = new Cache(100);
    // ...

    String filename = "file.txt";
    String filedata = (String) cache
        .get(filename);
    if (filedata == null)
    {
      // Read filedata from file system here...
      cache.put(filename, filedata);
    }

How does it perform?

Our basic implementation should work just fine but we may need to know how effective it is in a given application. One measure of how well a cache is performing is Hit Rate, which tells us how many cache accesses are "hits" - that is, how many times the required data was found in the cache for a given number of accesses. Hit rate is usually expressed as a percentage - a hit rate above 80% is usually pretty good.

We can add a few things to our Cache class to make it possible to monitor performance so that we can tune the cache by setting an optimum size. We need a counter for the number of accesses and another for the number of hits. We will need getter methods to allow us to retrieve those values after the cache has been running for a time, and finally we must override the get() method to update the counts. Here is our Cache class complete with these new members:

public class Cache extends
    LinkedHashMap
{
  private final int capacity;
  private long accessCount = 0;
  private long hitCount = 0;

  public Cache(int capacity)
  {
    super(capacity + 1, 1.1f, true);
    this.capacity = capacity;
  }

  public Object get(Object key)
  {
    accessCount++;
    if (containsKey(key))
    {
      hitCount++;
    }
    Object value = super.get(key);
    return value;
  }

  protected boolean removeEldestEntry(Entry eldest)
  {
    return size() > capacity;
  }

  public long getAccessCount()
  {
    return accessCount;
  }

  public long getHitCount()
  {
    return hitCount;
  }
}

One point to note is that calls to the containsKey() method don't update the access counts; we may want to override that method also, so that the hit rate isn't skewed by code such as this:

    if (cache.containsKey(filename))
    {
      filedata = (String) cache
          .get(filename);
    }
    else
    {
      // Read filedata from file system here...
      cache.put(filename, filedata);
    }

Neat Trick #1

2005-08-11T22:44:00.000-05:00

How to log a message identifying the location in code

Consider this code:

public class Debug
{
    public static void debug(String message)
    {
        StackTraceElement ste =
            new Throwable().getStackTrace()[1]; // <==
        System.out.println("[" + ste.getFileName()
                + ":"
                + ste.getLineNumber()
                + "] "
                + message);
    }
}

Now we can call this from other code:

public class LoggerDemo
{
    public static void main(String[] args)
    {
        Debug.debug("Test Message");
    }
}

The output will look something like this - note that we get the source file name and line number where the call was made:

[LoggerDemo.java:16] Test Message

This can be an extremely useful trick. The secret to how this works is all in the line marked with the "<==" marker comment.

Whenever a Throwable object is created (or an Exception, which is a subclass of Throwable), the JVM creates a stack trace in the form of an array of StackTraceElement objects. (Note that you can create a Throwable object using new just like any other class, and just because it's Throwable doesn't mean that it must be thrown.) The getStackTrace() method returns the stack trace array.

The elements of the array are ordered starting at the point in the code where the Throwable was created, so element 0 would contain details about the line containing the new Throwable() call. Element 1 is the one we want because it tells us about where the debug() method was called from.

As you can see the StackTraceElement contains information about the source file and line number. It also contains the class and method name, so our debug() method could report that too if it was useful.

Character development

2005-08-05T13:33:00.000-05:00

Representing characters for global software

When we used to write in C, we didn't often concern ourselves with the character set we worked with. In general you can write a string constant in the usual way like this: "Hello, world" - and the compiler converts it to an array of encoded bytes using the character set of the underlying platform. Because most computers in the western world use ASCII or a compatible derivative, this works just fine most of the time for those of us working in ASCII-speaking regions such as Britain and the US.

Things start to go wrong when you start to get a little more adventurous. For example, to check that a character is an upper-case alphabetic you might do something like this:

  if ((c >= 'A') && (c <= 'Z'))
  {
    ...
  }

This will work fine on a PC and many other systems, but what if you try to run this on an IBM AS/400 system? That system didn't use ASCII - it used a different standard called EBCDIC instead (and may still do, if there are any of these machines still around today). On such a machine some characters, such as '}' and 'ü', will pass the test in that example code as if they were upper-case alphabetic characters.

Ok, that's a contrived example. But what about writing code that will work in German, with umlauts over some of the vowels? Or Danish, which has 29 characters in the alphabet? Or in Korean or Arabic, which don't even use the same alphabets?

Java handles this whole problem by working internally with Unicode no matter what the underlying platform uses. Unicode is a character encoding that's designed to allow any characters in use anywhere in the world to be represented. The problem from a developer perspective is how to get those Unicode characters in and out of your applications, because most systems as yet don't use Unicode as a native format for storing files or displaying text on the screen.

Mostly you don't have to worry about this. The InputStreamReader and OutputStreamWriter classes, for example, convert characters between Unicode and the platform's default character set without you needing to take explicit action.

But in today's networked world, many applications aren't designed to handle just one system - you may be developing client/server applications. What if your server is running on a system where the platform character set is Latin-9, and the client is on a Latin-1 system? The Unicode in the client application will be converted to Latin-1 and sent to the server, but the server will interpret the bytes as Latin-9. Since the mappings between Latin-1 and Latin-9 don't quite line up, some characters from the client will be wrong by the time they get into the server as Unicode.

As it happens this is quite easy to fix. InputStreamReader and OutputStreamWriter both have constructors that will let you specify the encoding you want to use. In this case you could set the encoding on both sides to be Latin-9 explicitly by putting something like this in the client and server sides:

  String charset = "ISO-8859-15"; // a.k.a. Latin-9
  reader = new BufferedReader(new InputStreamReader(socket
         .getInputStream(), charset));
  writer = new BufferedWriter(new OutputStreamWriter(socket
         .getOutputStream(), charset));

Now it doesn't matter what the default encoding of the client and server platforms are; your applications will communicate using Latin-9 regardless.

Should you use Latin-9? Probably not. For one thing, the Java specification defines a minimal set of encodings that all Java implementations must support, and Latin-9 isn't one of these. A better choice is probably UTF-8 - this is mandated in the specification so all Java runtimes must support it, and better still it allows all Unicode characters to be encoded and transferred so your application would be able to handle Russian, Greek and even Arabic and Japanese characters.

Waiting as fast as I can

2005-08-03T00:35:00.000-05:00

How to avoid an occasional problem with Thread.sleep()

Every so often you find that you need a background thread that runs at intervals to perform some background task. Of course the simplest way to do this is to use Thread.sleep():

  while (true)
  {
    // Perform essential task here...
    ...

    // Now wait for 10 seconds before continuing
    try
    {
      Thread.sleep(10000);
    }
    catch (InterruptedException ie)
    {
    }
  }

This will work fine - it will suspend the thread for ten seconds each time round the loop. However, if it takes two seconds to perform the "essential task", then the task will actually be performed once every twelve seconds instead of ten. What if it's important to run every ten seconds regardless of how long it takes to run the task? Well, that's easy enough to fix:

  while (true)
  {
    // Perform essential task here...
    ...

    // Now wait for next 10-second interval
    try
    {
      // This calculates how long to wait
      long interval = 10000 -
        (System.currentTimeMillis() % 10000);
      Thread.sleep(interval);
    }
    catch (InterruptedException ie)
    {
    }
  }

This calculates how many milliseconds have elapsed since the clock last showed a time which was a multiple of ten seconds ("System.currentTimeMillis() % 10000") then subtracts that from 10000, which tells us how many milliseconds until the next 10-second multiple. Now the code suspends for that many milliseconds before returning to the top of the loop and running the core task again. The task will therefore run when the system clock shows 0, 10, 20, 30, 40 and 50 seconds after each minute, regardless of how long the task takes (as long as it's less than ten seconds, of course).

There is just one slight problem with this code: it doesn't always work. I used code just like this in a server application and found that quite often it would run the core task twice in quick succession every ten seconds, instead of once. It turned out that the thread was coming out of the Thread.sleep() early by as much as fifteen or twenty milliseconds. It would then run the core task in just a couple of milliseconds, so when it recalculated the wait interval there was still ten milliseconds or so before the next clock "tick" - actually the same clock tick that it was waiting for on the previous call. The task would then be re-executed just a few milliseconds later.

I never did figure out the root cause, although it did seem that this problem never showed up on the Windows desktop box I develop on or the small Linux system I use as a test platform. It only happened when I moved the code to the 4-processor Sun server, and that makes me think that maybe this is something to do with concurrent thread synchronization on multiprocessor systems (although I think it's more likely that it's something to do with the clock granularity).

The final fix? I wrote this as a general method that can be used to synchronize on any millisecond interval:

  public static void syncSleep(long ms)
  throws InterruptedException
  {
    long now = System.currentTimeMillis();
    long interval = (ms - (now % ms));
    long expectedEndTime = now + interval;
    do
    {
      Thread.sleep(interval);
      now = System.currentTimeMillis();
      interval = expectedEndTime - now;
    }
    while (interval > 0);
  }

In this, if the Thread.sleep() returns early it doesn't matter - the code detects the fact and waits again. Now we can recode the original thread code like this:

  while (true)
  {
    // Perform essential task here...
    ...

    // Now wait for next 10-second interval
    try
    {
      syncSleep(10000);
    }
    catch (InterruptedException ie)
    {
    }
  }