Tuesday, January 24, 2012

Debug java apps for beginners

Introduction

When posting in forums I often see people new to Java that don't know how to debug their applications. Which is a right shame as using the debugger can be an immense help to learning to program using Java. Hence I decided to write this simple article with many pictures, to be able to link to when I again run into such a case.

Of course debugging requires an IDE; this article is based on Eclipse. But the Netbeans debugger works nearly the same (they both operate on the same JVM debugging features after all).

Defining some test code


First we need something to debug. Create a regular java project in a fresh workspace, just to be sure you are in a "virgin state". Let us use some stupid code that is easy to follow. We require two classes: DebugTest and StepIntoTest.

package test;

public class DebugTest {

  private int classMember = 0;
  
  public DebugTest(){
    
    System.out.println("Breakpoint line");
    System.out.println("After breakpoint line");
  }
  
  public void myMethod(){
    System.out.println("In myMethod");
    classMember = 5;
    System.out.println("After classMember change (it is now " + classMember + ")");
  }
  
  public void stepIntoTest(){
    System.out.println("In stepIntoTest");
    
    int localvar = 0;
    StepIntoTest sit = new StepIntoTest();
    localvar = sit.stepIntoThis();
    System.out.println("localvar is now " + localvar);
  }
  
  public static void main(String[] args){
    
    DebugTest dt = new DebugTest();
    dt.myMethod();
    dt.stepIntoTest();
  }
}

package test;

public class StepIntoTest {

  public StepIntoTest(){
    System.out.println("StepIntoTest created.");
  }
  
  public int stepIntoThis(){
    System.out.println("Stepped into!");
    return 10;
  }
}

If you run DebugTest right now, you'll get the following output:

Breakpoint line
After breakpoint line
In myMethod
After classMember change (it is now 5)
In stepIntoTest
StepIntoTest created.
Stepped into!
localvar is now 10

The runtime output is not really important, what I do find important is that it will demonstrate a thing or two while we do some debugging runs.

Setting a breakpoint

The most important tool you have while debugging is the ability to set breakpoints. A breakpoint is exactly that - a break point, or a point to pause execution. Lets see that in action right now. To set a breakpoint easily, simply double click in front of the line where you want to set it. Lets set it in the DebugTest constructor, on the "breakpoint line".


A little blue dot appears in front of the line. That means a breakpoint is set on that line. Now we can run our application in debug mode. You can do that by either right clicking and then choosing debug as -> java application:




or you can do it by pressing that little bug icon.




Either way, Eclipse will run the application in debug mode. As soon as it reaches the line with the breakpoint, Eclipse will start to nag you with a question.




Eclipse will ask you to switch to the debug perspective, which you should do. In fact, I would recommend checking that remember my decision checkbox so Eclipse doesn't ask you again (for this workspace) because when debugging you really do want to work in the debug perspective.




After you click yes, the workspace will show a slightly different view with all kinds of useful information. First of all, in the source view you will see that the line with the breakpoint is now highlighted and there is a little arrow in front of that line. The output console is currently still empty. The debugger has paused the execution flow, waiting for you to do something. A visual indicator that you have hit a breakpoint is seen in the button bar:




These are the buttons that allow you to control what the debugger is to do next. I have labelled the buttons 1-4; these are the buttons we'll be exploring in this article. The remainder I hardly ever use myself, but perhaps I'll cover them eventually anyway.

The fact that button 1 & 2 are active means that the application is currently halted on a break point; if the application is running these buttons are greyed out. It may seem silly to explain this but believe me - there are going to be times when you are going to need that visual queue to understand what is going on. Eclipse isn't perfect :)


Button 1: continue execution


An important thing to note is that even though the breakpoint is on a line that does a system out, nothing is printed yet. The line on which you set the breakpoint is the line that is going to be executed next.

Lets explore the different buttons shall we. First, press the green arrow, button 1. You'll find that this makes the debugger continue execution of the program - the console now fills up with the system outs.

Lets try that again, but this time we are going to set a second breakpoint in myMethod, on the line that prints "In myMethod".




After doing that, run in debug mode again. The debugger halts on the first breakpoint. Press the green arrow (1) again. You'll see a change from the last time; in stead of completing the application, the debugger is now paused on the second breakpoint. Whatever code was between the two breakpoints is executed; you can see that in the console output.




That is exactly how you use the green button; to run from breakpoint to breakpoint until the code terminates.


Button 2: terminate prematurely

If everything is correct, the program is still paused on the second breakpoint. If it is not, make sure it is now.

At this point, press the red button (2). The result is immediate: the application terminates before finishing. When debugging new code you'll often cut the debug run short because you notice something is wrong. Stop debug, fix problem, restart debug is something you'll do often.

Button 4: step over

Skipping button 3 for the moment, lets go directly to button 4 which is the step over button. This button allows you to execute code one line at a time, a very powerful tool. You'll see just how powerful in a short moment.

At this point, lets remove the first breakpoint. There are multiple ways to do that of course, the two most useful are:

- double click the breakpoint again
- open up the breakpoints tab; from here you can remove or temporarily disable breakpoints




The breakpoints tab also allows you to remove or disable all breakpoints at once, which is quite useful after a heavy duty debugging session where you set dozens of them.

Whichever way you choose, make sure that the breakpoint in the constructor is gone. Now run the application in debug mode so it hits the breakpoint in myMethod(). As you can see, this method changes a class member. At this point, open up the variables tab. In the variables tab you can not only see the members of the current class (the one that this points too), but also all the local variables that are declared in the current method. That we'll see later.

Expand the this variable to see the classMember. Right now, the debugger will show you that it is 0.




Now press button 4, step over. You'll see that the debugger progresses to the next line and "in myMethod" is now printed to the console. classMember is at this point still 0, because as you now know the line is only executed once the 'debug cursor' moves out of it. Press step over again to move to the next line.

Bingo, the line that changes the classmember is now executed and you can check the variables view:




A thing of beauty isn't it? Debugging allows you to see exactly what is going on inside your classes! You no longer have to make assumptions about the content of class members or have to follow their progress in your head as you stare at the code, you can see first hand by stepping through your code what changes happen and why.

Lets see what happens when we continue to step over lines. Press the step over button two more times. The following will happen.




The cursor jumped from myMethod() back to the main()! Of course the debugger does not execute code linearly from the top to the bottom, the execution flow is exactly how the JVM executes it. So at the end of myMethod(), control is passed back to the main() method which will in turn invoke stepIntoTest(). You have to keep this in mind because while stepping through code the cursor will not only fly all over the place within the same source file, but also to other source files. It can get a bit disorienting if you don't keep an eye on things.

Okay, let the application finish or cut debugging short. Remove the breakpoint in myMethod() and set a new breakpoint in stepIntoTest(), on the line that prints "in stepIntoTest". Debug until that line.

This method declares a local variable, which will ultimately be changed by the stepIntoThis() method. If you check the variables tab, you'll see no variable declared there. This makes sense: the variable doesn't exist yet, it is declared two lines down. So step over until the line that constructs the StepIntoTest object.




I moved things around a bit in my IDE to be able to make this compact screenshot. Now the local variable appears in the variables view. Step over twice more to execute until after stepIntoThis() and see the variable value change.




Also note how the StepIntoTest object appears in the variables view. You can unfold it and inspect its members. Give it some properties to see how this looks in the variables view, if you are curious.


Button 3: step into


The button we skipped over, with step into we can step into a method. In the previous paragraph we stepped over the stepIntoThis() method to see the local variable change its value from 0 to 10. Now lets step into it to see which lines were executed when we stepped over the entire method.

Stop debugging if you have to, restart debugging until the breakpoint in stepIntoTest(). Step over until the cursor is on the line that invokes stepIntoThis(). In stead of pressing step over, now press the step into (3) button.




As expected, the cursor is now at the start of the stepIntoThis() method of the StepIntoTest class and you can continue stepping over lines. As soon as the method finishes, control goes back to the stepIntoTest() method of the DebugTest class. This allows you to intimately follow the flow of the code and see the current class and variable states.


Changing code on the fly

Java is a very powerful thing. One of its neat features is to, while debugging, swap in code changes into a running instance. That's right, you can make changes to your application while it is still running.

Lets take that for a spin. Run the application until the stepIntoTest() breakpoint. Step over that line so that in the console is printed "In stepIntoTest". I don't like that test. While still debugging, alter the line of code to in stead print "Hello World!".




As soon as you save the change, you'll notice that the cursor pops back to the beginning of the method! When you now step over the line again, hello world is printed in the console. Cool huh!




This hot swapping function is a really powerful debugging tool, but it will take some getting used to before you really learn to work with it. There are of course limitations to what you can do; for example changing the signature of a method cannot be hot swapped. Experiment and see what works and what doesn't, but now at least you know the possibility exists. This feature becomes increasingly powerful when you want to debug web applications by the way.

The importance of toString()

When debugging you'll learn to love the toString() method. Run until any breakpoint, then open the variables tab and click on the this variable. You'll see something like this:




That is the default output that Java generates for an object that has no toString() method of its own. Very much not helpful. Lets give the DebugTest class one:

public String toString(){
    return "DebugTest; classMember=" + classMember;
  }

Debug again and when you select the this object again, the output has changed:




Much more helpful. Just imagine when you start to debug code with people, addresses and what not. Implementing proper toString() methods can actually help you to quickly see what is going on without needing to go through the trouble of hunting through endless class members.

Debugging in a loop

Finally, an interesting element to encounter while debugging is a loop. Lets see that in action with this piece of code:

public void loopTest(){
    
    for(int i = 0; i < 5; i++){
      System.out.println("Loop " + (i+1));
    }
  }
Put a breakpoint on the println line in the loop and debug until that line (of course, make sure that loopTest() is actually invoked or else the debugger won't ever touch it). Now press the green arrow button. Loop 1. Press the green arrow button again. Loop 2. This will repeat until the code loops 5 times. So by putting a breakpoint inside a loop, the breakpoint will be triggered for as many times as the code actually loops. This may be a problem when the code loops 2000 times; you don't want to be clicking that green arrow button 2000 times. Of course you could simply disable the breakpoint, but lets say you want to see what is going on during iterator 1125 of the loop. Do you press the green button 1125 times? No, you create a conditional break point like this.
When debugging, sometimes you have to put some additional code in there just to help you narrow down problems. To illustrate, this is the output I got by running and then stepping through the code:
...
Loop 1121
Loop 1122
Loop 1123
Loop 1124
Temporary conditional breakpoint.
Loop 1125
Loop 1126
Loop 1127
Loop 1128
This is just one trick. When you become an expert debugger you'll pick up many more such tricks. Just don't forget to remove them again when you are done debugging :)

In closing


Yeah, I'm going to halt the article right here. There is much more to tell about debugging, but this article is for novice developers who want to learn how to use a debugger; lets let the more advanced features rest until you are comfortable with what you already know. Hope this helps someone.

But remember: debuggers are cool, but in some cases there is just nothing better than peppering your code with system.out statements to see what is really going on :)

Monday, January 23, 2012

Java web frameworks discussed

Introduction

Java has been around for a while. Soon after its initial inception, Sun started to push the platform towards the web with an eye on big enterprise environments, in the form of the Java Enterprise Edition specification. This gave birth to, among others, the epic Servlet specification - in most environments the heart of the Java web layer.

Now many years later, there are dozens of web frameworks that either extend the initial Servlet core or bypass it completely. There is for example Sun's own JSP technology which is a simple templating system on top of the Servlet specification. Next to that there is the Javaserver Faces technology, which is a stateful enterprise scale web framework designed to be used to build large backend systems and user interfaces for existing enterprise solutions (and less for, say, the next Facebook).

Having also visited the Sun/Oracle forums for many years now, the same question pops up again and again and again: which web framework is best. Let me address and demystify that question right here and right now:

the best does not exist.

Stop looking for it, it is not there. They all have their merits and they all have their breaking points. There is not a single web framework out there that will work for all requirements out there. JSF is a good example of this: you could attempt to create web 2.0 type webapps with it (blog, social website, twitter 2.0, etc.), but you'll only find it a rather grueling experience. JSF was not designed for that purpose. Neither was Spring framework. Struts and Play framework however are better candidates in this particular case. But if I would have to build a web application that ties into a JEE backend, I wouldn't want to use anything but JSF 2.1.

So what then!? Why is there no one tool for all jobs like in .NET and why is there no Microsoft telling you what to use and how to use it? Yep, that's the Java platform. You either love the freedom of choice, or you should run away now. As it is, you have a whole wonderful world of frameworks to examine and explore. I have done that too just for the fun of it and I like to discuss some of them with you, to perhaps save you some time or at least make you aware of their existence. This will most certainly not be a "JSF VS Spring" type comparison, because I am smart and experienced enough to know the futility in such discussions. Of course I cannot document what I don't know, so don't expect to find all frameworks in the world in this article.

Before we start I have to make the obvious crystal clear: these ramblings are of course my personal opinion and experiences which in some cases may have been resolved since the time of writing, or a better solution escaped me at the time. Your mileage may and probably will vary. If you keep it neutral I will be very glad to hear where you disagree with me!

Servlets and JSPs

The golden oldies. I have long called JSP technology seriously outdated, but I have recently changed my mind a little about that. The fact of the matter is that Servlets and JSPs do nothing for you; its you in charge, you do everything including mapping request parameters to objects and validating them.

Even with the big bad world of frameworks out there, is there still a place for Servlets & JSPs? Yes, certainly. Smaller web applications are still quickly and cleanly built using them and you don't need any external dependencies either. The only side note is that you do it properly, which means:

  • use Servlets to invoke business logic (which includes invoking database queries)
  • use JSPs to generate the view
  • JSPs contain no Java code, only JSTL tags and if you want custom tags

One 'page' will generally be bound to both a servlet and a JSP; the servlet for the backend business logic and the JSP for the view logic. This works by making the servlet the entry point (for example a form submission goes to the servlet) and when its time to show something, you forward control to the JSP. By setting appropriate objects in the request scope, you can share data between the servlet and the JSP.

If you want or need to stick to these bare basics, it would still benefit you to investigate the Stripes framework. Stripes is a lightweight framework on top of servlets & jsps, taking away many boilerplate tasks you would normally be very bored with yourself.

Want to learn Servlets & JSP technology? Read Core Servlets 2nd Edition, a free online e-book. It is old, but still the best book I know on the subject.

I would use this: when you have only a few pages/functions to implement, like for a simple management interface for a backend application or a webapp with very light dynamic needs.



Javaserver Faces

Javaserver Faces, or JSF, has had a rocky development cycle. It only became anything close to 'good' with the 1.2 release where many design flaws were fixed. Years later JSF 2.0 (and now JSF 2.1) made its appearance, which fixed even more design flaws and took away most if not all of the XML configuration necessity that made JSF 1.X clunky indeed.

Many hate it, many love it. The main reason most people hate it is because of its steep learning curve and the fact that people use it for all the wrong purposes. You have to accept one basic fact: you are not going to properly use JSF until you really know how it ticks under the hood. You have to understand how the request lifecycle works and how the statefulness of JSF works. And when you do, you can wield it like a magic wand. It is a powerful framework that can save you an immense amount of time... if used for the right purpose! The right purpose is found within the specification it is part of: the Java Enterprise Edition specification. JSF is primarily aimed at being used to build web components for enterprise applications. That is where it shines: creating complex user interfaces with bells and whistles while the framework takes care of wiring UI components to backend classes with automated validation and transformations going on. Due to its stateful nature you even have an object representation of the web UI available to you server side.

JSF itself is only the base actually. It is designed to be extended, and many third parties do just that. On top of JSF you also have JBoss Richfaces, Icefaces, Primefaces, Oracle ADF, Apache Tomahawk, JBoss Seam, Omnifaces, etc. They all share the fact that they extend core JSF with more functionality, which usually comes in the form of Ajax controlled "rich internet components". Jboss Seam is unique in that list in that it does not actually aim to extend, but "seamlessly wire together" many frameworks and technologies to the enterprise platform.

Since JSF 2.0 these extension frameworks integrate quite neatly, so you can even mix and mash them together and have an even richer component library available to you. Its all quite neat, but beware: this is not easy material. JSF is hard, and "they" want you to buy books to remedy that so don't expect rich online documentation either. What documentation there is, you can find as part 2 of the JavaEE tutorial - that's a good place to start to see if JSF is anything for you.


I would use this: For medium to complex enteprise webapps where full control over the front end is not a requirement. If the application is built and designed around a solid backend, JSF 2.1 is your friend. If your application aims around a rich and dynamic web 2.0 front end, JSF is not your friend.


EDIT 10-04-2013: Apparently JSF can now also be stateless, as reported by Balusc on his blog. That may help a lot of people to actually use the framework where previously they couldn't or it was very hard (session-size limited environment, load-balanced website)!

EDIT 14-06-2013: JSF 2.2 is going to bring some cool improvements, including the Wicket-way of binding HTML components into JSF so you can have 100% control over the front-end. Its amazing how slowly the boundaries and limitations of the framework are being broken down without turning it into a legacy mess.

Spring framework

Its a bit unfair to list Spring framework here, as it is actually not a 'web framework' but more like an alternative to Enterprise Javabean technology. But Spring is unique in that it does not want to be something specific; it is such a dynamic and open framework, it shares JBoss Seam's aim in wiring together many different technologies, both frontend and backend. It does not aim to replace Java Enterprise Edition technology, not at all. You can use it as an alternative, but you are just as free to wire Spring and JEE technologies into the same application. Spring helps you to do it. Want to use JSF as the front end? No problem. Want something simple but you don't want to lower yourself to JSPs? No problem, Spring has a built in front end layer.

So what does Spring add itself? Plenty!

  • a bean autowiring system to replace (or extend) the dependency injection model as it exists in the JEE specification. Spring does not limit itself to managed classes, you can autowire just about anything using Spring with either the right configuration or a few annotations, including in client side applications if you would want to go so far.
  • an incredibly strong security model (which can be uses separately from the Spring framework itself).
  • "Inversion of Control", or IOC. In stead of manually constructing objects, you "inject" them from a Spring managed context. You may be familiar with dependency injection schemes as they exist nowadays in the JEE6 specification; Spring offered such services for a long time already.
  • a strong emphasis on the Model View Controller pattern. Spring provides default controller types for example, but you can also implement your own. As for the model layer the framework can setup JDBC, Hibernate, JPA, etc. for you and it can even manage the sessions and transactions.
  • A built in web front end framework with easy to use annotations that is a very decent replacement for JSP technology and hooks nicely into Spring's MVC model.

And much, much more. Check out the reference manual to at least adopt the awe it deserves.


That also proves Spring's main disadvantage: it is huge and huge frameworks tend to be clunky. On top of that Spring has been around for a while now and has gone through three iterations already, which means that there is also a big amount of legacy that the framework has to drag around. All this makes it quite hard to start to use the framework as first you have to separate those pieces of corn from the cob that you really want to eat.

I would use this: when I have to build and maintain a large enterprise application that will also target other legacy systems and technologies. Spring is so flexible you'll have the least trouble adapting it to whatever you already have floating around. That doesn't mean it is going to be easy, but the people that built Spring already did a lot of the ground work for you. Also there is a huge community around Spring, which counters the startup troubles you'll likely have.

Struts 2

Struts is what existed "before Spring". It is one of the earliest Java web frameworks out there. As such, you don't want to use Struts 1 anymore. It is old, outdated and every framework released after it was aimed to do better than it.

Struts 2 is one of those frameworks that aims to do better than Struts 1; it is actually quite a clean and neat framework if you but dive into the documentation for a moment. If all you want to do is create simple web applications, "web 2.0" or otherwise, then it isn't a bad idea at all to consider Struts 2. But beware that it has limitations. For one, the security model is weak at best (the fact that the sales pitch on the home page doesn't even mention it is a good backup of that statement). In this world of web paranoia and heightened security demands, the framework does nothing to assist you or to help you prevent doing it wrong.

I would use this: for web applications that do not have high security demands but will be a mix of complex forms and dynamic frontend pages. Also good to get into the world of Java web development as it has such an incredibly low learning curve.


Wicket 6+

Another framework brought to us by Apache, Wicket is actually quite a cool alternative to its competitors. A Wicket application, although targeting the web, develops like a Swing application. You work with components in stead of a "backend and a frontend"; the separation between the two layers is almost taken away by Wicket. In stead you think in events. A user presses a button, what is supposed to happen? Where other frameworks tend to hide the interaction, Wicket bares it all - on the Java side. Unless you introduce the rich Ajax functionality of Wicket of course, then stuff starts to happen client side as well.

Wicket is also a framework that is friendly to the developer. It integrates nicely into IDEs and even has built in support for hot-deployment making it far easier to change and debug your applications. Also boring and cumbersome features like making your application multilingual is made incredibly easy. The framework really takes away most of the boring repetitive chores from you, leaving only the interesting stuff for you to do.

But, no framework is perfect. Wicket has some downsides in my opinion:

  • the available information is a bit weak and disorganized (but has grown since I first wrote this article). I found myself having to hunt through endless forums, blogs and even the source code to figure out how the more advanced features of Wicket not only really work - but also how they should be properly applied and what you absolutely should not do. Don't get me wrong, when you know how they work Wicket rules, but I wish someone would have written it all down in a coherent form in a single resource. A notable exception is "Wicket in Action"; that book tends to go a little bit further and actually provides useful examples you can use directly in your application. But in my opinion: still not enough and the book is aging and Wicket's evolution has not stopped since it was written.
  • Even if the framework takes away plenty of work, I found myself having to write lots of boilerplate code nonetheless because of the component oriented approach; in some cases it can even be a little counter intuitive. You really have to think about how you organize your project to not drown in the sea of pages, panels, components, validators, model objects, message files, etc. etc. It can be hard to manage large Wicket projects, take your time to keep your project well-structured and don't be afraid to move things around. Also don't fear inner and anonymous classes when you know you're not going to reuse something.
  • The framework may appear simple, in fact it shares the Javaserver Faces problem of being complex under the hood and yet again do you really need to know how the framework ticks, or you can get into big trouble later on. A notable problem is that of an exploding session for example; Wicket is by default stateful and uses the session to keep its state, including the component tree of pages being rendered. If you're not careful you can be cramming a lot of data into the session without even realizing it; the framework does not do enough to help you prevent that. You have to read the fine print to know what to do and what not to do. Be careful choosing and using Wicket in an environment were the session size is limited. There are more such examples, most of them boiling down to "Always use models!". Then why offer the possibility to not use them and send newcomers awry? :/
  • The framework has a rich history, which has also lead to feature creep. There are ALWAYS multiple Wicket classes and features to do the exact same thing, and you have to be experienced to know which way fits with what exact requirement. Keep the javadocs really close.


Regardless of those negative points, they are all to be circumvented by properly thinking about it, doing the necessary research and simply gaining experience. Rarely any framework can work without those basic attributes in your personal involvement. So now that you're aware of it, don't fear to use Wicket if you're interested.

I would use this: When you need the power of JSF but you hate JSF's design, or when you need more control over the front-end. Wicket also works really well in environments where web designers and developers share tasks, since there is no code and almost no special markup in the views. Finally: if you're a client software developer by heart and you want to get into web development, Wicket will make the transition easier than other frameworks given its component approach. Finally, if you anticipate your project will make use of lots of components or fragments of pages that you'll be reusing multiple times, definitely go for Wicket!

GWT

Google Web Toolkit is a strange beast. You write applications using the Java language - yet come time to deploy, it is mostly javascript. GWT offers incredibly powerful browser user interface capabilities that go far beyond what any other framework offers; using it you can create the coolest web front ends with relatively little work. You can see proof quite easily; Google creates most of its own online web services using GWT. JBoss also uses it for many projects, such as the JBoss 7 management interface and Drools Guvnor.

On top of GWT itself Google also provides you a wide range of tools, for example a rich set of plugins for Eclipse. This makes it a complete package that is completely carried by Google itself. This keeps it all tightly integrated and documented, which is a big plus for a web framework. It is of course also a good choice if you want to deploy into Google's App Engine - there are also tools to be able to do that from your IDE. These tools are a bit invasive however; I recommend installing a fresh copy of Eclipse specifically for GWT app development.

My main beef with GWT is that the framework is so vastly different from any other framework out there; you even need a specific GWT compiler. When you want to use it you start from scratch, even if you've been writing webapps for years already. That is not necessarily a bad thing of course, but it may make it hard to adopt it for a new project.

An added bonus of GWT that makes it a good choice in this day and age lies in its Java to Javascript conversion capabilities. The HTML 5 madness has begun and people are now actually writing whole applications in Javascript; you know, that scripting language that up to a few years ago was hated and feared and everyone needed to block it. Through GWT you don't actually have to write your stuff in Javascript itself; you can write Java code in stead and still end up with "HTML 5" components. For example LibGDX makes good use of that to be able to make Java games built with it deployable to the web!

I would use this: when you have the requirement to create highly complex and feature rich web user interfaces. This is especially true when you have to work with people that do not have widespread experience with Java enterprise development, as GWT only lightly touches upon the Java language.


Play Framework

Play framework is a relatively young framework that hasn't been given the attention that it deserves so far. I say that because when I started to experiment with it, it made one thing clear to me: this framework succeeds royally. What it does better than other frameworks:

  • stripping away the boring part of Java web development
  • fusing backend and front end development
  • being completely stateless and REST-enabled
  • providing perfect hot-deployment without need for JRebel; even JPA entities!
  • simplifying setup; you don't even need to configure anything in the web.xml
  • integrates with many popular and important web technologies
  • manages dependencies for you without needing to learn the complexities of Maven
  • consolidates web dev into a neat package. You don't have to make choices, Play has everything on board to get you going.
  • data is very easily shared as XML or JSON
  • incredibly easy ORM model based on Hibernate and JPA 2.0, with an additional layer that takes away the cumbersomeness. You don't even need a persistence.xml.
  • toolset inspired by that of Ruby and Groovy On Rails that allow you to manage most of anything you want to do with a Play project, including setting it up for a specific IDE.
  • not the least important: the maintainers are active and listen to you. Expect bugs you report to be fixed timely (if it is really a bug of course).
  • for easy administration, a CRUD module is available

Really, this framework is a breath of fresh air and will appeal to people that cannot work with for example the statefulness of a framework such as JSF or the confusingly open nature of Java enterprise development as a whole. Play lays down the rules, it brings the conventions and it provides you the foundation to allow you to quickly and painlessly develop web applications, without boilerplate, dependency conflicts or layer upon layer of configuration.

This is the first framework I know of that can utilize the benefits of the Scala language (but it is also built for the Java language). The same is true for Play 2.0 which is out right now, and more so. This is mostly because the framework is modeled almost entirely after Ruby on Rails 3 including the available tooling, which is a web framework stack that "just works". If you know which buttons to push and which levers to pull of course.

I've been incredibly positive so far, of course there are a few things to complain about.

  • the programming model is quite... counter-intuitive. You'll be creating lots of static classes and entities with public members for example
  • navigation is based on throwing exceptions :/
  • documentation is a bit shallow at the moment, although Play 2 will have some nice books written by people I have had the pleasure of conversing with and I respect a lot. The online documentation is of the "this is the easiest way to do it" type. Still with a bit of digging you can figure out anything you need, especially because you get a nice set of example programs.
  • deploying is a bit of a mess using Play as you don't deploy classes, you deploy the source files (which the framework instruments at runtime before compiling them for you). You can deploy as a war, but you are encouraged to deploy in exploded form. At least using Play 1.X I would advise you to just do that.
  • The (alternative) way you manage a Play project makes it difficult to integrate it in for example a JEE application in a way that is easy to maintain.
  • Play 2.0 still supports the Java language, but at its heart it is really designed for Scala. You'll see evidence of that every way you turn, starting with the template language which is Scala based.

I would use: if you are new to Java web development as it is really easy to pick up. Also if you are bothered by the incoherence that most popular Java web frameworks are prey to, Play may be the relief you need. Finally if you need to create a webapp that is highly front-end oriented but you don't want to dig into the complexities of for example GWT, Play is also a really good choice as you have total freedom there. The basic idea is that you use jquery and jquery-ui to create your rich internet components. Play's simple Java (or Scala) backend will help you take care of the rest. If you want to use Scala in stead of the Java language, the choice should be a no-brainer.


The unmentioned


As stated I did not use all frameworks out there so I can't comment on them, but readers of this article have seen fit to make recommendations and I respect their opinions. Hence let me summarize some things that you may glance from the comments; I encourage you to check them out before making a final decision on a framework to use.

2014 - How about NO Java web framework?

This article was written back in 2012, times have moved on a lot even since before then and for some time I was oblivious to it. This entire article focuses on web frameworks that live on the server side of things, where Java is king. But there is a trend to move away from those and to do more on the client side, using Javascript frameworks. Frameworks such as AngularJS and EmberJS, as well as the neat server-side component Node.js allow you to build your entire web application stack using the Javascript language - both client-side and server-side. With the help of tooling such as Grunt you have a build management tool that in my opinion is superior to anything the Java platform has to offer, including Gradle and Maven.

It may seem a little odd to mention such a thing in an article like this, but this article was aimed at giving you a good idea about what is out there and I can't ignore a very popular movement in this day and age. When you are considering a web framework, ask yourself if you really want to use server-side solution such as Java at all. You don't need to anymore. If you are completely new to all of this, you might want to reconsider and go the Javascript way to be directly working with the technology of today and tomorrow.

What about a compromise - a Javascript front-end and a Java back-end? That is certainly possible - you can relatively easily setup a Tomcat server and deploy a JAX-RS based RESTful webservice on it and use Servlets for some alternative features such as file uploads. If you have Java code already lying around that you need to use, then it is certainly a viable option to do and relatively painless too - using JSON as the main data format you can quite easily communicate information between the front-end and the back-end; it "just works". Just be aware that when you're using a Javascript front-end, you are likely to run into security restrictions you need to take care of in the form of CORS. My article on setting up a JAX-RS based service has a paragraph on how to configure that in Tomcat.

In the end it is a difficult to say whether you need to completely bypass Java (or some other server-side technology) and go Javascript only. If you do you'll enter a rich and fresh online community which is rapidly expanding and developing this technology; thus you'll always have plenty of people to talk to and get help from and you might even contribute to the technology stack yourself given that it is still growing. But there is a flip side to that coin; it is a rather young area of development even though Javascript has been around for ages. Thus the frameworks are still settling, the best practices are still being invented and the documentation is still being written; case in point, I have yet to find a good book that covers any framework in any kind of half-decent way. It is so bad that people have started actual documentation gathering projects to help you out.

So its really cutting edge technology which is not decently documented, versus aging technology that is rapidly becomes less commonly used, but is very solidly documented and thus easier to learn and adopt. Tough choice, really.

In closing

That was a quick overview of the web framework which I consider to be the most viable. There are many, many more, but most of them serve the same purpose as one I already named here. I couldn't end this article without at least passing out my personal recommendation. And that would be:

  • use Play framework for pure stateless webapps
  • use JSF 2.1 for JEE systems for highly data driven applications and/or that require tight integration between the web layer and the business logic layer. As an added bonus I would add Primefaces for a whole slew of easy to use rich internet components while keeping the webapp lightweight.
  • use a pure Javascript technology stack if you want to be as lightweight as possible, target multiple platforms easily and be as current-gen as you possibly can.

If you stick these three in your toolbox, you can basically tackle any problem IMO. Your mileage may vary.

Tuesday, January 3, 2012

JBoss 7: scheduling, messaging and jmx-console

Introduction


Please be aware that this article was aimed at JBoss 7.0 and is now old and obsolete. The JMS section has been migrated to the getting started article and expanded, use the link below.

If you have read my article on getting started with JBoss 7, you'll know I find JBoss 7 a very exciting piece of tech. Yet three services present in JBoss 4/5/6 that I have used and abused a lot are no longer available or not available by default: a scheduler, my beloved jmx-console and messaging support.

This can be explained away like this: JEE6 has vastly improved timer support with full scheduling services. Unfortunately this may not solve all your needs, so you may need to reach out to a fully fledged scheduler such as Quartz. Messaging is not enabled by default, but you can activate it yourself by using the standalone-full configuration in stead of the default standalone configuration, or copy over the relevant bits as I will show you later. The missing jmx-console is because of the greatly improved yet still evolving JBoss management interface. But I liked it a lot, so I want something like that anyway. Lets see what we can do.


Quartz: the replacement scheduler

We'll roll our own of course. Quartz has been around for some time now and provides all the scheduling support you might ever need. So what we'll do is plug Quartz into our application framework.

First of all we need Quartz deployed as part of our application. To do that, use the following maven dependency:

<dependency>
  <groupId>org.quartz-scheduler</groupId>
  <artifactId>quartz</artifactId>
  <version>2.1.0</version>
</dependency>

Now we need to bootstrap the scheduler. How depends on what type of application you are building.

EJB: we'll use a singleton EJB
WAR: you can use either a singleton EJB or a @WebListener annotated class

I'll demonstrate how to do it with a singleton EJB. JEE6 supports an annotation called @Startup, which forces the bean to be initialized upon application startup. We can use this fact in combination with a singleton EJB to get what we want.

@Startup
@Singleton
public class SchedulerBean {

  @PostConstruct
  void init() {
    
    try {
      Scheduler sched = new StdSchedulerFactory().getScheduler();
      
      // schedule jobs here

      sched.start();
    }
    catch (Throwable t) {
      // log exception
    }
  }
}

That will do it. The fact that the EJB is a singleton adds thread safety to the mix by the way.

Of course you need to be able to schedule jobs. The Quartz manual and example programs are your best example, but here is a job that prints a message every 10 seconds.

public class TestJob implements Job {

  @Override
  public void execute(JobExecutionContext context) throws JobExecutionException {
    System.out.println("Quartz test job executed!");
  }
}


And here is how you schedule it:

JobDetail testjob = JobBuilder.newJob(TestJob.class)
  .withIdentity("testjob", "testgroup")
  .build();
      
SimpleTrigger trigger = TriggerBuilder.newTrigger()
  .withIdentity("testtrigger", "testgroup")
  .withSchedule(SimpleScheduleBuilder.simpleSchedule()
     .withIntervalInSeconds(10)
     .repeatForever())
  .build();
      
sched.scheduleJob(testjob, trigger);

The SimpleTrigger/SimpleScheduleBuilder is what you'll probably use in most cases, it contains scheduling intervals of every X seconds, every X minutes, every X hours, every day at X.X hour, etc.

Of course a job is not a container managed resource, so you'll need to do manual JNDI lookups to use EJBs unfortunately. If you need to know how, see my article on creating a prototype webapp which demonstrates it.



Building your own jmx-console


The old jmx-console was a wonderfully powerful tool because it provided among other services the possibility to invoke services manually. With only a few annotations you could expose EJB calls through a simple auto-generated web interface.

That we no longer have, so we'll have to create something ourselves. Recreating the jmx-console is madness, what you want is a simple way to expose service methods through the web. Using JSF 2.1 for this task is just the ticket, especially when you have something you can copy/paste and adapt between applications.

So what do we need?

- a page listing all invocable service calls
- a page that displays the results of said service calls
- a backing bean which will actually invoke the service call for us

I'll define three dummy service calls I want to expose through the web.

- createReportingData; this is used to generate dummy data to test/demonstrate a reporting function in a webapp.
- optimizeDatabase; something which is normally invoked scheduled every night at 3AM and will invoke some wicked magic that optimizes the database.
- generateJobSummary; a special call that generates a report of running jobs (wherever they may come from).

The administration page will look something like this. I'm adapting this from an existing admin module I created, please excuse copy/paste/modify errors.

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
  xmlns:ui="http://java.sun.com/jsf/facelets"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:f="http://java.sun.com/jsf/core"
  xmlns:a4j="http://richfaces.org/a4j"
  xmlns:rich="http://richfaces.org/rich"
  template="template.xhtml">
  
  <ui:define name="content">
  <h:form>
  <h3>Services</h3>
  <table>
  <tr><th>Operation</th><th>actions</th></tr>
  <tr><td>optimize database</td><td><h:commandButton action="#{adminBean.optimizeDatabase}" value="Invoke"/></td></tr>
  <tr><td>Get job summary</td><td><h:commandButton action="#{adminBean.generateJobSummary}" value="Invoke"/></td></tr>
  </table>
  
  <h3>Mock Database management</h3>
  <table>
  <tr><th>Operation</th><th>actions</th></tr>
  <tr><td>create report data</td><td><h:commandButton action="#{adminBean.createReportData}" value="Invoke"/></td></tr>
  </table>
  </h:form>
  </ui:define>

</ui:composition>

Facelets page, I assume you have some facelets template that you can hook this in. I'm not going to pre-chew everything :)

We also need a page to show results. I'm making that as basic as you can possibly make it:

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
  xmlns:ui="http://java.sun.com/jsf/facelets"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:f="http://java.sun.com/jsf/core"
  xmlns:a4j="http://richfaces.org/a4j"
  xmlns:rich="http://richfaces.org/rich"
  template="template.xhtml">

  <ui:define name="content">
    
    <p>
    <h:outputText escape="false" rendered="#{not empty adminBean.output}" value="#{adminBean.output}"/>
    <h:outputText rendered="#{empty adminBean.output}" value="The operation completed with no results."/>
    </p>
    <p>
    <h:form>
      <h:commandButton action="admin" value="Back"/>
    </h:form>
    </p>
  </ui:define>
</ui:composition>

Notice the escape="false". The idea is that the services can generate output as if you could do in the original jmx-console, returning a String which would then be output in the result page. By not escaping you can even return HTML content if you see fit.

Now what remains is the actual backing bean.

@ManagedBean
@RequestScoped
public class AdminBean {

  @EJB
  private MyEjbBean myEjb;

  private String output;
  
  
  public String optimizeDatabase() {
    try{
     output = null;
     myEjb.optimizeDatabase();
   } catch(Throwable t){
     output = exceptionToString(t);
   }
   
    return "adminresult";
  }

  public String generateJobSummary {
    output = myEjb.generateJobSummary();
    return "adminresult";
  }

  public String createReportData() {
    output = "Report data in italic.";
    return "adminresult";
  }


  
  public String getOutput(){
    return output;
  }
  
  public void setOutput(String op){
    output = op;
  }
  
  private String exceptionToString(Throwable t){

    ByteArrayOutputStream baos = new ByteArrayOutputStream(); 
    PrintStream ps = new PrintStream(baos);
    t.printStackTrace(ps);
    
    String ret = String(baos.toByteArray());
    return "
" + ret + "
"; } }

The action method simply invoke the EJB, collect any output if necessary and then kick the user to the 'adminresult' page.

The exceptionToString() method is to mimic the jmx-console a bit. The exception stacktrace is transformed into a String and then will be generated as output in a <pre> so formatting is preserved (remember: the output is printed with escape="false").

Of course without the EJB this is not a working example, but I'm pretty sure you can whip something up yourself in a minute.



Adding messaging to the default configuration

I already altered standalone.xml and now I've figured out that I cannot use JMS this way because the required subsystem is not there. At this point you have two options.

- rename standalone-full.xml to standalone.xml and copy over all the configuration changes you made in the old file
- copy over the relevant parts from standalone-full.xml to standalone.xml


I decided to do the last. The following will activate HornetQ AND MDB support:

STEP 1: under extensions, copy over the org.jboss.as.messaging module
STEP 2: under the urn:jboss:domain:ejb3:1.1 subsystem, remove the "lite=true" attribute
STEP 3: copy over the <mdb> block under the same subsystem.
STEP 4: under the same subsystem, copy over the mdb-strict-max-pool instance pool.
STEP 5: copy over the entire urn:jboss:domain:messaging subsystem (under profile)
STEP 6: under socket-binding-group, copy over the messaging and messaging-throughput socket-binding elements.

That's it, your default standalone server now has HornetQ enabled. All configuration options you would normally look for in the hornetq-configuration.xml file can now be found in the messaging subsystem you just copied over (any missing configuration can be added here as if you would add them to the hornetq-configuration.xml file too).

Queues and topics can be defined inside the messaging subsystem, under jms-destinations. This is also the place where you define your own queues/topics, you do not deploy *-hornetq-jms.xml files like you would in JBoss 6. Example:
<subsystem xmlns="urn:jboss:domain:messaging:1.3">
  <hornetq-server>
  ...
     <jms-destinations>
        <jms-queue name="testQueue">
           <entry name="queue/test"/>
           <entry name="java:jboss/exported/jms/queue/test"/>
        </jms-queue>
        <jms-topic name="testTopic">
           <entry name="topic/test"/>
           <entry name="java:jboss/exported/jms/topic/test"/>
        </jms-topic>
        <jms-queue name="YourQueue">
           <entry name="queue/yourqueue"/>
           <entry name="java:jboss/exported/jms/queue/yourqueue"/>
        </jms-queue>
     </jms-destinations>
  </hornetq-server>
</subsystem>

If you need more information about HornetQ, I discovered this very useful blog that is dedicated to it. The linked article is what tipped me off to the fact that messaging was enabled in standalone-preview.xml. My Jboss 6 migration guide also contains some entries on HornetQ which were specific to JBoss 6; if you run into issues you may just find an answer there.

To test out that it works, you could use this simplistic code. To compile this code you need the JMS API on your classpath, using Maven:
        <dependency>
            <groupId>javax.jms</groupId>
            <artifactId>jms</artifactId>
            <version>1.1</version>
            <scope>provided</scope>
        </dependency>

First of all a test MDB listening on the test queue:

@MessageDriven(activationConfig = { @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
    @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/test") })
public class MyTestMDB implements MessageListener {

  protected Logger                      logger = LoggerFactory.getLogger(getClass());
  
  public void onMessage(Message msg) {
    
    ObjectMessage om = (ObjectMessage) msg;
    
    try{
      String text = (String) om.getObject();
      logger.info("Message received! : " + text);
    } catch(Throwable t){
      logger.error("Exception receiving message", t);
    }
  }
}

This simple MDB will consume messages on the test queue and print out a log each time it receives one.

Now an EJB that can send messages:

@Stateless
public class MyTestEjb {

  protected Logger                      logger = LoggerFactory.getLogger(getClass());
  
  @Resource(name = "QueueConnectionFactory", mappedName = "java:/ConnectionFactory")
  protected QueueConnectionFactory connectionFactory;
  
  public void sendMessage(){
    sendObjectMessage("java:/queue/test", "Test");
  }
  
  
  
  private void sendObjectMessage(String queueName, Serializable msgBody){
    
    QueueConnection connection = null;
    QueueSession session = null;
    MessageProducer producer;
    
    try {
      InitialContext context = new InitialContext();
      javax.jms.Queue queue = (javax.jms.Queue) context.lookup(queueName);

      connection = connectionFactory.createQueueConnection();
      session = connection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
      producer = session.createProducer(queue);
      producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);

      ObjectMessage omsg = session.createObjectMessage();
      omsg.setObject(msgBody);
      omsg.setJMSCorrelationID("1");
      omsg.setJMSDeliveryMode(DeliveryMode.NON_PERSISTENT);
      producer.send(omsg);
    }
    catch (Throwable e) {
      logger.error("Exception sending message", e);
      throw new IllegalStateException("Exception while trying to send JMS queue message!", e);
    }
    finally {
      
      try {
        if (session != null) { session.close(); }
        if (connection != null) { connection.close(); }
      }
      catch (JMSException jmse) {
        logger.error("Exception sending message: ", jmse);
      }
    }
  }
}

This code has been slightly simplified from what I normally use, for example the correlation ID is normally uniquely generated. Note the lookup of the connection factory by using the JNDI name "java:/ConnectionFactory". You can find this name configured in the messaging subsystem. You'll find that this is bound to the "in-vm" connector, which is enough for most use cases. If you want to send persistent messages that are part of a two-phase transaction you would use the connector configured under "java:/JmsXA".

For a discussion on connectors and transports I refer you to the HornetQ manual.


Finally we need a way to actually send the message. Our home-grown jmx-console can do the trick there. Simply add a new button the the admin.xhtml:

<tr><td>Test message</td><td><h:commandButton action="#{adminBean.sendTestMessage}" value="Invoke"/></td></tr>

And the action method to the AdminBean:

@EJB
  private MyTestEjb           testEjb;

  public String sendTestMessage() {
    output = null;
    testEjb.sendMessage();
    return "adminresult?faces-redirect=true";
  }


And voila, you can check out if you can send and receive messages through HornetQ. JMS is killer technology, if you know how and when to use it properly of course.

In closing


There you go; home grown replacements for the JBoss scheduler and the jmx-console. Of course our own versions are not as flexible, but they get the job done until you find a better alternative.

On top of that you have now activated messaging support in your JBoss 7 installation!

JBoss 7: creating a prototype webapp

Introduction

When I do a project, I do so using the "Scrum" methodology. Without going into details on what that exactly is, it means that I (or actually the whole team I'm part of) develop applications in iterations of 2 weeks each. At the end of each iteration I deliver something that is perhaps not complete, but it does work (at least that's the idea). The intent is to not have something that could be put in production, but something you can demonstrate.

When I have to do a web module, I generally do not start developing against a 'real' database like Oracle or MySQL. At that point in development the database design is probably still very much alive and will change from moment to moment; when you write application code you want the interface (which includes the database schema) to be nice and stable, or else you'll be modifying your code every time someone else in the team decides that things need to be totally different, probably with good reason.

But I still want to create something that works and can be demonstrated, so I need to be a little creative. Enter: embedded pure Java databases. They allow you to create a real database driven web module, without needing an actual physical database running anywhere. This makes them perfect to create prototypes, or to do that "iteration 1" web module.

Note that I assume you read the Jboss 7 getting started article before you read this one.


Choice of database

There are three basic pure Java database implementations that you could use.

Derby
Don't know much about it myself, but it is bundled with the JDK. I hope you use Maven, so the fact that it is bundled with the JDK should not be a reason to want to use it. The one thing I do know is that it doesn't perform very well compared to its two bigger brothers.

H2
A popular DBMS that even has a place in a 'real' application environment, especially because H2 has an XA datasource available but can also adhere to real life requirements like database encryption and SSL support. It is basically the good old HSQL with a feature set that allows you to use it in a production environment. If you want to do that, by all means use H2.

HSQL
My DBMS of choice for prototype applications and unit test environments. Probably because I learned to trick of the trade using it :) Since we'll be using JPA there isn't much of a difference, if you prefer H2 then by all means use it. A big advantage is of course that JBoss 7 comes with H2 already pre-installed and an example datasource is already setup, you have almost no work.


Setup

You don't need to do much to setup an in-memory HSQL database. Of course you need to install it as a module in JBoss 7. You do this by downloading the latest HSQL version (which is a JDBC 4 compliant driver). Create a directory modules/org/hsqldb/main. Copy the module.xml of the org.h2database.h2 module to your newly created directory. Put the HSQL jar you downloaded into this directory as well. Then modify the module.xml to the following:

<module xmlns="urn:jboss:module:1.0" name="org.hsqldb">
  <resources>
    <resource-root path="hsqldb-2.2.6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

Assuming the version you downloaded is 2.2.6; put whatever jar name you have.

Now we need to create the datasource. Open up standalone/configuration/standalone.xml and locate the drivers. Add the following driver:

<drivers>
  <driver name="hsqldb" module="org.hsqldb"/>
  ...
</drivers>

And add a datasource that is going to form our database:

<datasource jndi-name="TestappDS" pool-name="TESTAPPDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
  <connection-url>
    jdbc:hsqldb:mem:testapp
  </connection-url>
  <driver>
    hsqldb
  </driver>
  <pool>
    <prefill>false</prefill>
    <use-strict-min>false</use-strict-min>
    <flush-strategy>FailingConnectionOnly</flush-strategy>
  </pool>
  <security>
    <user-name>
      sa
    </user-name>
    <password>
    </password>
  </security>
</datasource>

Basically the H2 datasource but with a different url and password. Webapps generally do simple database transactions so we'll use a plain old local-tx datasource but we do enable JTA (if only because that works the best in combination with Hibernate 4). The url as you can find in the HSQL user manual will setup a database that exists purely in memory only. It is created when the database starts and it will be destroyed when the database (or JBoss) shuts down.

This has the advantage that whenever you reboot your server the database will be fresh again which is precisely what you want in a prototype or 'demonstration' iteration. Of course the main disadvantage is that you'll start with an empty database which is pretty much useless; we'll have to add a way of bootstrapping the database with some starting data. More on that later.


The persistence.xml

In order to properly work with an in-memory database we still need a way to actually create the database itself. Fortunately this task can be automated. Since we will be using Hibernate 4 we can use its auto-DDL generation features. We can set it up like this:

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
             version="2.0">
   <persistence-unit name="testapp" transaction-type="JTA">
      <jta-data-source>java:/TestappDS</jta-data-source>
      <properties>
        <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
        <property name="hibernate.hbm2ddl.auto" value="update"/>
        <property name="hibernate.format_sql" value="false" />
        <property name="hibernate.show_sql" value="false" />
      </properties>
   </persistence-unit>
</persistence>

'update' generation means create if it isn't there yet, or modify if something already exists. Of course our database being in-memory this means that the entire database will simply be created; I still use update because it gives more sane logging output than 'create-drop'.

Note the datasource JNDI name; the fact that the DS lives in the java context is because of the use-java-context="true" attribute of the datasource.

If you are not that familiar with Hibernate you may be wondering what will be used to generate the schema from? The answer is simple: from the JPA entities.

Adding some entities


To see Hibernate and HSQL in action we need some JPA entities. Create them wherever you want, in my case in a WAR I'll call testapp-web.war. As an example lets create a User entity which is bound to a UserGroup.

@Entity
@Table(name="app_user")
public class User implements Serializable {

  @Id
  @GeneratedValue
  private long id;
  
  private String name;
  private String username;
  private String password;
  private String email;
  
  private boolean admin;

  @ManyToOne
  private UserGroup group;
  
  public User(){
    
  }
  
  public User(String name, String username, String password, UserGroup group, boolean admin){
    this.name = name;
    this.username = username;
    this.password = password;
    this.group = group;
    this.admin = admin;
  }

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getUsername() {
    return username;
  }

  public void setUsername(String username) {
    this.username = username;
  }

  public String getPassword() {
    return password;
  }

  public void setPassword(String password) {
    this.password = password;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public UserGroup getGroup() {
    return group;
  }

  public void setGroup(UserGroup group) {
    this.group = group;
  }

  public boolean isAdmin() {
    return admin;
  }

  public void setAdmin(boolean admin) {
    this.admin = admin;
  }
}

@Entity
public class UserGroup implements Serializable {

  @Id
  @GeneratedValue
  private long id;
  private String name;
  
  public UserGroup(){
    
  }
  
  public UserGroup(String name){
    this.name = name;
  }

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}


Two simple entities with some properties and a 1:N relationship between the two. As you can see I kept the JPA annotations sparse; that is a rule of thumb when creating your prototype webapp; use as little JPA annotations as possible. The reason is simple: you have no guarantee yet what the end database is going to be at this point, any configuration items you might add are likely to need changing later on. Don't do it, the defaults chosen by Hibernate are more than adequate for your prototype. Design first, fill in the details when you know them for sure.

You may notice the table annotation on the User to alter the table name; this is simply because I have the habit of avoiding overly common identifier names. 'user' is just such an identifier. You could also name the entity AppUser of course, that's up to you.

At this point you can publish the application and start the server. If you did everything correctly you'll notice that Hibernate creates the two tables for you in the startup logging.


Bootstrapping the database

A web application is actually quite a difficult application to work with as it has a very muddy lifecycle. It doesn't have a clearly defined start point and end point; there is no main().

But what it does have is a servlet context which is at one point initialized. That is what we can treat as our main() and it makes a good point to bootstrap our database. In order to do so, we need to create a WebListener.


@WebListener
public class DbContextListener implements ServletContextListener {

  private static boolean initialized = false;
  private static Boolean lock = Boolean.FALSE;
  
  @Override
  public void contextDestroyed(ServletContextEvent ev) {
    
  }

  @Override
  public void contextInitialized(ServletContextEvent ev) {
    
    synchronized(lock){
      
      if(initialized == false){
        initialized = true;
        
        BootstrapDao bsDao = lookupBootstrapDao();
        bsDao.persistTestData();
      }
    }
  }

  private BootstrapDao lookupBootstrapDao(){
    
    try{
      InitialContext ic = new InitialContext();
      return (BootstrapDao) ic.lookup("java:/global/testapp-web/BootstrapDao");
    } catch(Throwable t){
    }
  }
}

BootstrapDao is a simple DAO EJB which will persist the data for us. We'll get to it in a moment. Normally I would inject the EJB using @EJB of course but this gives me a chance to demonstrate looking up a local EJB resource under JEE6 / EJB 3.1. I deploy my EJB in a war module called testapp-web.war that is not part of an EAR, hence the JNDI name.

To make it more complete, here are other conventions. In these conventions assume that the following is the case:

EAR name: myapp.ear
WAR name: testapp-web.war
Bean name: TestBean
Local interface: myapp.TestBeanLocal
Remote interface: myapp.TestBeanRemote

CaseJNDI name
Only war, no interfacejava:global/testapp-web/TestBean
Ear, war, no interfacejava:global/myapp/testapp-web/TestBean
Ear, war, both interfaces, local interface lookupjava:global/myapp/testapp-web/TestBean!myapp.TestBeanLocal
Ear, war, both interfaces, remote interface lookupjava:global/myapp/testapp-web/TestBean!myapp.TestBeanRemote


This list has two basic patterns.

- short notation, which is the JNDI name without the business interface part (!package.InterfaceClass). This JNDI name will be created if you have no business interface or only one.
- the full notation, which includes the business interface. Which one (local/remote) exists depends on if you have business interfaces bound to your EJB of course.

These bindings are according to the JEE6 specification; they should work and be the same on all JEE6 complaint servers (Glassfish 3+, JBoss 6+, Weblogic 12+, Websphere 8+, Geronimo 3+). If you keep the loglevel on INFO, JBoss 7 will actually log all the possible JNDI names of any given EJB in your project. You can also lookup the JNDI context through the server management interface though.

The @WebListener annotation is a new feature of the JEE6 specification. You no longer need to define such resources in the web.xml, oh glory. The same for filters (@WebFilter) and servlets (@WebServlet).

In any case, the code above also protects against the context being initialized multiple times for whatever reason. The database only needs to be initialized once.


Adding bootstrap data

This unfortunately is the (really) boring part of the job. To insert data you must do boring inserts. To do boring inserts in a pure Java database with entity relationships, the easiest way is to simply create objects and persist them. For that we need an active transaction, hence we do it in a DAO EJB.

public void persistTestData(){
  
  UserGroup group = new UserGroup("myusergroup");
  em.persist(group);

  User user1 = new User("gimby", "username", "password", group, "gimby@somewhere.cm", true);

  User user2 = new User("someone", "username", "password", group, "someone@somewhere.cm", false);

  em.persist(user1);
  em.persist(user2);

  // etc. etc.
}

As said, boring code. But you'll only need to maintain it for as long as you have your prototype setup, it won't haunt you forever. Given that fact I would just bite the bullet and do it the simple way.

The alternative is of course to be able to define your data in some simple format and let a piece of code stream it into your database. I like the way how Play framework does it for example; you define your test data objects in YAML format and the Play persistence layer can persist it all for you, including the entity relationships. But Play has a really nasty piece of code that wraps around Hibernate and JPA to be able to do that (as well as defining some hard conventions that make it possible for the code to make safe assumptions), you cannot easily get that done through plain old JPA code and a YAML parser.



In closing


A rather short article that if you look at it is quite simplistic. Lets review what the article describes:

- how to create a persistence unit around an in-memory database
- how to use a WebListener to bootstrap the database
- how to lookup an EJB under JEE6 without using injections

I'm not here to move mountains, sometimes having a pile of simple facts documented in a straightforward way can help to see the possibilities you would normally ignore. For example, given how the code is structured it shouldn't be too hard to use the exact same code to setup a unit test environment for your application, don't you think?