Friday, July 18, 2008

Common Validation Module for Swing Application

I have been using swing for developing the rich client application for a long time. There are always so many things to do that I put all my time and soul on it. This year, with the release of Swing Application Framework and Beans binding, our life goes better. But you can not stop getting new issues. In this article I will try to use some frameworks/libraries and build them together to solve a very import issue which each swing application must face – the validation.

Validation plays a very important role in the modern application, because it can make your application more user friendly (always tells the user what he should do) and protect your system. In an n-tier system, the validation could be built on the server side or on the client side, while the second choice is always preferred. Today I will tell you how to use the beans binding, jxlayer, and hibernate validator to build validation module in a desktop application.

Since the hibernate validator does a great job for domain model validation and we should not reinvent the wheel. So, the goal of this module is trying to delegate all validation calls from the GUI to the hibernate validator. Each time the property of the bound bean is changed, the new value will be validated by the hibernate validator framework. Error icon will be shown when the validation failed.

Before going to the amazing validation code, I need some sample classes. For example a bean and some factories:

First, we need a bean. Open you IDE (I use here the Netbeans. actually I am a eclipse user, but for such a small project, Netbeans can really save much time), and create a Java application. Yes, “Java Application” not “Java Desktop Application”, because I want to keep it simple. The Swing Application Framework is great. I use it in my real project. But in this case, using it is not necessary, it will only make thing more complicated. So, just create a Java Application. In my example, the project calls “validation”.

Second, add the following jar files into the libraries:



All needed jar files can be got from the lib folder in the attached netbeans project.

Third, create a bean. I choose a sample bean for presenting a Country. The code looks like this:



package de.jingge.domain;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import org.hibernate.validator.Length;
import org.hibernate.validator.NotEmpty;

/**
*
* @author Jing Ge
*/
@Entity
public class Country extends AbstractBean {

private static final long serialVersionUID = 5341382564159667599L;
public static final String PROPERTYNAME_NAME = "name";
public static final String PROPERTYNAME_CODE = "code";
private String name;
private String code;
private Long id;

public Country() {
}

public Country(String code, String name) {
super();
setCode(code);
setName(name);
}

@Id
@GeneratedValue(strategy = GenerationType.AUTO)
public Long getId() {
return id;
}

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

@NotEmpty
public String getName() {
return name;
}

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

@Length(min=2, max= 2, message="Code length must be 2")
@NotEmpty
public String getCode() {
return code;
}

public void setCode(String code) {
firePropertyChange(PROPERTYNAME_CODE, this.code, this.code = code);
}
}



Nothing difficult, The Country class is just a java bean class. It has two properties: code and name. Each property has its own validation annotation. The code should be not empty and its length should be 2 and the name should not be empty. Since most applications are working with database, a persistence bean is used here, but it is not mandatory. Hibernate validator works pretty well with normal pojo class.

The parent class AbstractBean comes from the framework Swingx. Extending the AbstractBean will let the Country support property change event.

Now we can begin writing the code for our validation module.

In my validation module, I will use the jxlayer to show the icon when the validation failed. For understanding the following description better, you should understand the jxlayer first. You can find all information about the jxlayer here: http://weblogs.java.net/blog/alexfromsun/

The JXlayer is an amazing new JComponent built by Alexander Potochkin. All painting events that the JXLayer gets will be delegated to the UI class. That means what we should do is just creating a new UI class: HibernateValidationUI.java and call the hibernate validation when the gui component is (re)painted. This UI class is based on the TextValidationDemo from the jxlayer's demo package. The code looks like this (I will explain it step by step):


package de.jingge.view;

import java.awt.Graphics2D;
import java.awt.image.BufferedImage;

import javax.swing.BorderFactory;
import javax.swing.JComponent;
import javax.swing.text.JTextComponent;

import org.hibernate.validator.ClassValidator;
import org.hibernate.validator.InvalidValue;
import org.jdesktop.beansbinding.ELProperty;
import org.jdesktop.beansbinding.PropertyStateEvent;
import org.jdesktop.beansbinding.PropertyStateListener;
import org.jdesktop.jxlayer.JXLayer;
import org.jdesktop.jxlayer.plaf.AbstractLayerUI;

/**
* Header:
* Description: A layerUI which will validate the referenced property value of
* the object each time when the paint(...) method is called.

* The value of the given object property will be observed.
* Note: This UI works only with {@link JXLayer}. Any change of the property
* will force repainting the UI. The work process looks like: property changed ->
* jxlayer will be repainted -> the paint(...) method of this UI will be called.
* The logic of validation will be handled by the Hibernate validator
* framework.
*
* @author Jing Ge
*/
public class HibernateValidationUI extends AbstractLayerUI<jTextComponent> {

private Object object;
private String propertyName;
private ClassValidator validator;
private ELProperty elProperty;
private PropertyStateListener propertyChangeHandler;

public HibernateValidationUI(Object obj, String propertyName) {
this.object = obj;
this.propertyName = propertyName;
propertyChangeHandler = new PropertyChangeHandler();
validator = new ClassValidator(obj.getClass());

elProperty = ELProperty.create("${" + propertyName + "}");
}

public void installUI(JComponent c) {
super.installUI(c);
elProperty.addPropertyStateListener(object, propertyChangeHandler);
}

public void uninstallUI(JComponent c) {
super.uninstallUI(c);
elProperty.removePropertyStateListener(object, propertyChangeHandler);
}

protected void paintLayer(Graphics2D g2, JXLayer<jTextComponent> l) {
super.paintLayer(g2, l);
InvalidValue[] validationMessages = validator.getInvalidValues(object,
propertyName);
if (validationMessages.length > 0) {
BufferedImage image = Java2DIconFactory.createErrorIcon();
g2.drawImage(image, l.getWidth() - image.getWidth() - 1,
l.getHeight() - 8, null);
l.getView().setToolTipText(validationMessages[0].getMessage());

return;
}
l.getView().setToolTipText(null);
}

boolean isValid() {
return validator.getInvalidValues(object, propertyName).length == 0;
}

class PropertyChangeHandler implements PropertyStateListener {

@Override
public void propertyStateChanged(PropertyStateEvent pse) {
setDirty(true);
}
}
}



The HibernateValidationUI have only one constructor, which need two parameters. The first parameter obj means the source object that will be edited, i.e. the java bean. The second parameter propertyName is the name of the property which is bound to the gui component which is managed by the jxlayer (if you don’t understand the relationship between the gui component and the jxlayer, please read the jxlayer source code).

The propertyChangeHandler will call setDirty(true) of the UI class each time the property of the given object is changed. Calling the setDirty(true) method will change the state of the jxlayer(if the jxlayer was not dirty) and this will force jxlayer to repaint itself, which means the UI class will be repainted, because the call will be delegated from the jxlayer to the UI class.

The validator is a new instance of the hibernate ClassValidator. It will be used later for doing the real validation logic.

The elProperty will be used with the propertyChangeHandler together for observing the change of the property.

The installUI(JComponent c) method will be called when layer.setUI(ui) is called. Here
We add the propertyChangeHandler with the given source object into the elProperty. This means the change of the property will be observed after the jxlayer is instantiated.

To avoid adding more than one propertyChangHandler, we will call removing the propertyChangeHandler in the uninstallUI(JComponent c) method.

The paintLayer(Graphics2D g2, JXLayer<jTextComponent> l) method contains the most import code for this validation module. We will first call the validation logic of the hibernate validator and get the validation result: the validationMessages. After that, we will check whether the value of the property is valid, if not (the validationMessages is not empty), an error icon will be shown and the first validation message will be shown as tooltips. (Of cause, you can show all validation messages, if want).

The used class Java2DIconFactory looks like this:



package de.jingge.view;

import java.awt.Color;
import java.awt.Graphics2D;
import java.awt.RenderingHints;
import java.awt.image.BufferedImage;

/**
*
* @author
*/
public class Java2DIconFactory {

public static BufferedImage createErrorIcon() {
return createErrorIcon(7, 8);
}

public static BufferedImage createErrorIcon(int width, int height) {
BufferedImage icon = new BufferedImage(width, height,
BufferedImage.TYPE_INT_ARGB);
Graphics2D g2 = (Graphics2D) icon.getGraphics();
g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
RenderingHints.VALUE_ANTIALIAS_ON);
g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL,
RenderingHints.VALUE_STROKE_PURE);
g2.setColor(Color.RED);
g2.fillRect(0, 0, width, height);
g2.setColor(Color.WHITE);
g2.drawLine(0, 0, width, height);
g2.drawLine(0, height, width, 0);
g2.dispose();
return icon;
}
}


Now we need a new Factory for creating (or maybe better call it building) a gui component, which can be used in the application for editing the object. The factory looks like this:


package de.jingge.view;

import javax.swing.JTextField;
import javax.swing.text.JTextComponent;
import org.jdesktop.beansbinding.AutoBinding;
import org.jdesktop.beansbinding.BeanProperty;
import org.jdesktop.beansbinding.BindingGroup;
import org.jdesktop.beansbinding.Bindings;
import org.jdesktop.beansbinding.ELProperty;
import org.jdesktop.jxlayer.JXLayer;
import static org.jdesktop.beansbinding.AutoBinding.UpdateStrategy.*;

/**
*
* @author Jing Ge
*/

public class GuiComponentFactory {

public static JXLayer<jTextComponent> createTextField(
BindingGroup bindingGroup, Object sourceObject,
String sourceProperty) {
JTextField field = new JTextField();
AutoBinding binding = Bindings.createAutoBinding(READ_WRITE,
sourceObject, ELProperty.create("${" + sourceProperty + "}"),
field, BeanProperty.create("text"));
bindingGroup.addBinding(binding);
bindingGroup.bind();
return new JXLayer<jTextComponent>(field, new HibernateValidationUI(
sourceObject, sourceProperty));
}
}


In the craeteTextField() method, we create a JTextField, bind it with the property of the given object and return a jxlayer, which contains the HibernateValidationUI object and manage the created JTextField. You can find more information about beans binding here: http://weblogs.java.net/blog/shan_man/

Until now, we have finished all code what we need for a validation module. Now let’s build a demo application:



package de.jingge.main;

import de.jingge.domain.Country;
import java.awt.BorderLayout;
import java.awt.Dimension;
import java.awt.Toolkit;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.UIManager;
import javax.swing.UnsupportedLookAndFeelException;
import javax.swing.text.JTextComponent;
import net.miginfocom.swing.MigLayout;
import org.jdesktop.beansbinding.BindingGroup;
import org.jdesktop.jxlayer.JXLayer;
import static de.jingge.view.GuiComponentFactory.*;

/**
*
* @author Jing Ge
*/
public class ValidationApplicaton {

private BindingGroup bg;
private Country country;
private JXLayer<jTextComponent> codeField;
private JXLayer<jTextComponent> nameField;

/**
* @param args the command line arguments
*/
public static void main(String[] args) {
try {
UIManager.setLookAndFeel(
"com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel");
} catch (UnsupportedLookAndFeelException ex) {
System.err.println(
"Nimbus L&F does not support. Default L&F will be used.");
} catch (ClassNotFoundException e) {
// TODO Auto-generated catch block
e.printStackTrace();
} catch (InstantiationException e) {
// TODO Auto-generated catch block
e.printStackTrace();
} catch (IllegalAccessException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
ValidationApplicaton app = new ValidationApplicaton();
JFrame frame = new JFrame("Demo Validation Application");
frame.setPreferredSize(new Dimension(360, 150));
frame.getContentPane().add(app.buildPanel(), BorderLayout.CENTER);
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
setCenter(frame);
frame.setVisible(true);
frame.pack();

}

private static void setCenter(JFrame frame) {
Toolkit toolkit = Toolkit.getDefaultToolkit();
Dimension screenSize = toolkit.getScreenSize();

// Calculate the frame location
int x = (screenSize.width - (int) frame.getPreferredSize().getWidth()) / 2;
int y = (screenSize.height - (int) frame.getPreferredSize().getHeight()) / 2;

// Set the new frame location
frame.setLocation(x, y);
}

public ValidationApplicaton() {
country = new Country();
bg = new BindingGroup();
}

private JPanel buildPanel() {

codeField = createTextField(bg, country, Country.PROPERTYNAME_CODE);
nameField = createTextField(bg, country, Country.PROPERTYNAME_NAME);
JPanel panel = new JPanel(new MigLayout("",
"[50px, right]10[200px:250px:300px]", "[center]"));
panel.add(new JLabel("Code:"), "cell 0 0");
panel.add(codeField, "cell 1 0, w 200px:250px:300px");
panel.add(new JLabel("Name:"), "cell 0 1");
panel.add(nameField, "cell 1 1, w 200px:250px:300px");
return panel;
}
}


In the main() method, we create a new JFrame and add the panel to it.

The setCenter(JFrame frame) method will set the frame on the center of the screen.

In the constructor new Country and BindingGroup instances will be created.

In the buildPanel() method we use the MigLayout for building a panel, which contains two text field for edit the code and name of the country. You can get more information about MigLayout here: http://www.miglayout.com/

Run the application, a window will be shown likes this:




Since the Country class is annotated by the hibernate validation annotation, the empty code and name are invalid. The error icons are shown. If you move your mouse over the text field, you will get the validation message, which will tell your how to make it valid.




After enter correct information, all error icons will disappear, like the following picture shows:



The benefit of using this validation module:

  1. No code anymore for normal validation. Add the validation annotation like @NotEmpty, @Email etc. to you domain models, value objects, or some other POJOs. The properties will be validated in the GUI automatically. Developer does not need to write any code.
  2. If you use Hibernate as ORM, this should be one of the best solutions. The cost of writing validation will be reduced extraordinarily.
  3. For more complex validation you can follow the hibernate validator extension. It is incredible easy thanks to the hibernate validator. What you need to do is just writing two classes: One is the annotation and the other is the concrete validator. You can find a introduction about the extension here: http://www.hibernate.org/hib_docs/validator/reference/en/html/validator-defineconstraints.html#validator-defineconstraints-own


Oh, I can not upload the project! I will try another way later. Guy, who wants to get the netbeans project, please contact me.

20 comments:

Alexander said...

Hello JingGe

Thank you for your great blog, I really like it!

Here is some comments about the code:

- "jTextcomponent" looks like a format error, must be "JTextComponent"

- in the installUI() sets the empty border with the empty insets which is equal to the null border

- Is it possible to reduce the number of @SuppressWarnings("unchecked") annotations?
I don't see why they are necessary for the constructor, paintLayer(), isValid() methods and suspect the fields can be properly generified to make this annotation unnecessary

- The recommended Swing pattern is never change the state of a component in its paint() methods;
so tooltip should be set outside it (the propertyStateChanged() looks like a proper place)

- "The installUI(JComponent c) method will be called when the jxlayer is first instantiated."

I would say that installUI() is called when layer.setUI(ui) is called, in your code it happens indirectly when you pass the ui to the layer's constructor.

- existing frame.setLocationRelativeTo(null); is shorter than setCenter() method

- Could you add a note that HibernateValidationUI is based on the TextValidationDemo from the jxlayer's demo package

Thanks
alexp

JingGe said...

Hello Alexp,

Thank you for your comments. :-)))

I have changed the blog on your recommendation.

-"JTextcomponent". The blogger has ist own tag called also "jtextcomponent". I had some trouble while posting the blog. And I have change it manually......

- setBorder() is removed.

- @SuppressWarnings("unchecked"). I built this module firstly with eclipse. this annotation will remove the "warning" message in the eclipse. They are now removed from the code.

- If I set the tooltip in the propertyStateChanged() method, it will only work when the property is changed. That means, at the first time, when the domain object is instantiated, no tooltip is set. Which problem would I face, if the tooltip is set in the pain() method?

- The text is changed. I said that because I did not called the setUI() method and the setUI() will only be called when the JXLayer is first instantiated.

- I knew it, but calling frame.setLocationRelativeTo(null) will not (100%) set the window on the center of the screen.

- the reference of the TextValidationDemo is added.

Alexander said...

Hello JingGe

Changing the state of the component in the paint() methods is considered as a bad style, we follow this rule in the Swing team.

First, most of JComponent setters cause repaint() which is not desirable when you paint the component

Second, programmers don't expect the component changes after paint() is called, it may lead to a difficult-to-find bugs

So I'd recommend you to add a line of code and set the tooltip when domain object is instantiated

Thanks
alexp

JingGe said...

Hello Alexp,

How about calling it in the thread of the SwingUtilities.invokeLater(doRun)?

thanks
Jing

Alexander said...

Hello Jing

I missed that,you certainly should (I would even say must) create Swing Gui on the Event Dispatch Thread

SwingUtilities.invokeLater in the main method will work well

alexp

JingGe said...

Hello Alexp,

thank you! It's very nice of you. :-)

could I call SwingUtilities.invokeLater in the paint() method? Doing it like this will make sure that the tooltip will be set after the paint() is called. Is that right?

Alexander said...

Hello Jing

In your code, you should only use invokeLater in the main method, when you create your components
everything else is automatically called on EDT

alexp

JingGe said...

Hello Alexp,

In the main method? In the main method of the ValidationApplication?

I don't catch it. what should I call in the invokeLater() method in the main method? You mean the tooltip can be set in the paint() method, if the invokeLater() is used?

Jing

Alexander said...

Hello Jing

I meant that you should not change any component's properties in the paint method, including the tooltip

the setTooltip() should be placed outside the paint method

The main method of the ValidationApplicaton must create and use Swing components inside the invokeLater

that's it

Thanks
alexp

JingGe said...

Hello Alexp,

I got it. I mean setting the tooltip like this:

protected void paintLayer(Graphics2D g2, JXLayer<JTextComponent> l) {
super.paintLayer(g2, l);
InvalidValue[] validationMessages = validator.getInvalidValues(object,
propertyName);
if (validationMessages.length > 0) {
BufferedImage image = Java2DIconFactory.createErrorIcon();
g2.drawImage(image, l.getWidth() - image.getWidth() - 1,
l.getHeight() - 8, null);
setToolTipText(l.getView(), validationMessages[0].getMessage());
return;
}
setToolTipText(l.getView(), null);
}

private void setToolTipText(final JComponent c, final String text) {
SwingUtilities.invokeLater(new Runnable() {
public void run() {
c.setToolTipText(text);
}
});
}

does it make sure that setTooltip() is called outside the paint()?

Alexander said...

let me say it once again,
you need invokeLater only in the main() method of the ValidationApplicaton

don't set the tooltip in the paint() method, set it in the installUI(), propertyChangeListener, but not in paint()

alexp

JingGe said...

I understood what you mean. But doing it like you said, I have the following troubles:

1. A reference of the jxlayer should be saved in the UI class. because the propertyStateChange() method need it.
2. All code in the paint() method should be moved into the propertyStateChanged() method, otherwise, each property change will force calling the hibernate validator twice, one for painting the error icon in the paint() method and the other for setting the tooltip, since I can not make sure that paint() method is called before the setTooltip() method is called.
3. The benefit of the jxlayer (setDirty()) will not be used. I do not even need to override the paintlayer() method. Everything is done in the propertyStateChange() method.

thanks
Jing

Alexander said...

Hello Jing

1. Saving jxlayer reference is a good idea, this will also allow you to check that no one incorrectly sets an instance of the HibernateValidationUI to the multiple layer's

I think your HibernateValidationUI is not shareable by its nature

2. You'll need a paintLayer() at least to draw the error icon if message is invalid

3. Even for non-shareable layers, setDirty(true) is recommended technique to repaint the layer

alexp

JingGe said...

Hello Alexp,

I have read the JXLayer source code again. and find that I just set the tooltip of the managed JTextField not the JXlayer itself in the paintlayer() method. In another word: the tooltip of component A is set when the component B is (re)painted. There should be no such problems like you said.

Alexander said...

Hello Jing

As I mentioned, changing component's state in any paint() methods is considered a bad style in Swing team.

For example if in my fix I set a tooltip in a paint() method, it will never be approved by my colleagues.

Anyway, it is up to you to follow this rule or not

Thanks
alexp

JingGe said...

ok, got it. Thanks for the suggestion.

Jing

MethoD said...

Could you please give me the spring project?

Or built jar file with libraries (netbeans project dist folder)?

Miqdad said...

Find and download that you need at Rapidshare Search Engine.
Top Site Lists Free Proxy Site Free Download mp3 Michael Jackson song All Michael Jackson Lyrics Hollywood Celebrity Gossip Download Mp3 Gratis download naruto download naruto shippuuden windows 7 activator

w3c said...

Nice information, I really appreciate the way you presented.Thanks for sharing..

http://www.w3cvalidation.net/

Al-Ajweh said...

hi Jing
thank you for your perfect job
where i can found the source and the jar's ??