http://www.developer.com/

Back to article

Dynamic Error Notification and Construction with Java Swing


May 9, 2005

Any type of Graphical User Interface (GUI) application, designed based on any functional requirement, will assume user interaction as part of its standard functionality. Therefore, almost all GUIs allow users to enter data and manipulate it. After the information is gathered from the user, it typically needs to be either stored, locally or remotely, or used in the application in real time. But, before doing something with the data, applications usually need to check it for correctness. In this article, I will concentrate on form validation and dynamic creation of notification messages in Java Swing GUI applications. I will also go over a few useful tips for GUI developers such as adding listeners to multiple components and using regular expressions for easy validations.

Because Java/J2EE became de facto for enterprise rapid development and deployment environments, especially in the financial industry, the Java Swing framework became a favorite choice for desktop applications as well. With Swing, programmers can create extremely robust GUI applications in a short period of time and deploy them on any platform, without recompilation or any other changes for that matter. The applications will behave exactly the same on multiple platforms, and the only downside will be a need to have the Java Runtime Environment (JRE) installed on the target machines.

User Form

To demonstrate user form validation, I created a small application based on fictional requirements that entail a user entry screen that gathers rudimentary information, such as first and last name, and machine IP address. A form with several text fields takes user data and, after checking it, allows the user to proceed.

The fictional requirements also say that user may want to press the "Enter" key after entering data in any field to proceed, in addition to being able to click on the "Next" button. Moreover, the IP address needs to be checked for correct format (IPv4).

Dynamic Validation

Although the basics of creating the Swing GUI is beyond the scope of this article, you should be familiar with creating simple interfaces, using any layout manager either manually or with an IDE. For this article, I have used JBuilderX to create a frame with GridBagLayout and add all the required components. The form in the sample application is trivial because it contains only a few labels and text fields. Nevertheless, validation needs to be done on every component and the technique to do it can be applied to any GUI, no matter how complex. For instance, all fields need to be filled before the user can proceed and the IP field needs to have an additional check for the correct format.

The simplest way to check fields would be to add an action that listens to the "NEXT" button, and when a new action event is fired (on button press), check every field one by one for correctness and display an error message if something is wrong.

Ex. method checkFields () {    // pseudo code
   if (field1 is not right)
   show error
   if (field2 is not right)
   show new error
   ... etc ...
}

The problem with this approach is that when multiple fields are incorrect, the user would see a lot of error massages at the same time—several pop-ups, for instance. Another problem is that every field needs to have its own code to show the error message. Therefore, if the logic to display errors is not as simple as printing out to an output stream somewhere, it would have to be redundantly used to display every error statement.

In this case, the requirement is to show a pop-up dialog such as JOptionPane.showMessageDialog.

The solution to having multiple dialogs pop up at the same time could be breaking out of the check method after the first error was found, but this still does not solve the redundancy of implementing and showing a new dialog for every error condition. Redundancy can become abundant if the GUI is very complex.

So, what is the graceful solution?

An important, not well known, property of Java dialogs is that they can take an array of an object as a parameter to display multi-line messages. For example:

JOptionPane.showMessageDialog(this, new String[]{"Hello", "World"});

You can even pass in objects with different text properties color, font, and so forth. The solution, therefore, is to display only one dialog at the end of the validation routine and pass in an array of error messages. The array would be dynamically created based on errors found and the user would see all of them in one pop-up.

In the case of my simple application, the code looks like this; a new array list is initialized and, on every error condition, a string message is added to it. At the end, if array is empty, nothing is displayed; if it's not empty, it is passed to the dialog as a parameter, and a dynamic pop-up is shown.

private boolean checkFields() {
   // init array
   ArrayList msg = new ArrayList(0);
   // check if first name is blank
   if (getRoleNameTF().getText() == null ||
      getRoleNameTF().getText().equals("")) {
      msg.add("Please enter First Name Field - it is required!");
   }
   // check if last name is blank
   if (getRoleURNTF().getText() == null ||
      getRoleURNTF().getText().equals("")) {
      msg.add("Please enter Last Name Field - it is required!");
   }
   // check if ip is blank
   if (getRoleIPTF().getText() == null ||
      getRoleIPTF().getText().equals("")) {
      msg.add("Please check IP Field - format ###.###.###.###");
   // check if ip is correct format
   else if (!getRoleIPTF().getText().matches(
         "([\\d]{1,3}\\.){3}[\\d]{1,3}")) {
      msg.add("IP Field Incorrect - format ###.###.###.###");
   }
   // dynamic dialog
   if (!msg.isEmpty()) {
      JOptionPane.showMessageDialog(this, msg.toArray());
      return false;
   }
   return true;
}

public void actionPerformed(ActionEvent e) {
   if (checkFields()){
      // all ok do something
      JOptionPane.showMessageDialog(this, "All fields are ok!");
      parent.next();
   }
}

Note the IP is also checked for correctness with a regular expression. Because the message is dynamic, it will be different depending on the errors found:

Implementing this technique solved both problems of multi pop-ups and code reuse, and it can be applied to GUIs of any complexity and size. The resulting array of error massages can be passed or used in any context and not necessarily in JDialogs.

Adding Multiple Action Listeners

The validation was initialized when the user clicks on the "NEXT" button because it has an action listener associated with it. If the requirements say that the user needs to be able to simply press the Enter key while the focus is on any field, we need to add a key listener to every single text field. This would require adding some Key adapter or implementing a key listener interface and then checking whether the key pressed was indeed an "Enter" key. Besides, every text filed also would need to register to generate key events. Luckily, there is another way.

Java 2 provides an extremely useful feature built in specifically for capturing an Enter key press on the text fields. Simply attaching an action listener to any text field component would generate an action event if Enter was pressed on it. However, this still necessitates explicitly attaching an action listener to every field.

To solve this, I interrogated the parent component panel for the list of all text fields added to it and, as I traversed through them, I attached the listeners dynamically.

Component fields[] = this.getComponents();
   for (int i = 0; i < fields.length; i++) {
      if (fields[i] instanceof JTextField) {
         ((JTextField) fields[i]).addActionListener(this);
      }
   }

This method can also be used to add any kind of listeners to GUIs of any complexity—because you can recursively navigate down if the component in scope is in another container.

For instance, passing a top parent GUI container to this method will recursively add action listeners to all text fields, even those that are added to the child containers.

public void attachAnyListener(JComponent component){
   Component fields[] = component.getComponents();
      for (int i = 0; i < fields.length; i++) {
         if (fields[i] instanceof JComponent) {
            attachAnyListener(fields[i]);
         }
         if (fields[i] instanceof JTextField) {
               ((JTextField) fields[i]).addActionListener(this);
            }
         //other listener attachments here
      }
}
Note: The recursive mechanism also can be used to detect any changes to the user-entered information in large GUIs by using focus listeners or change listeners. Eventually, you prompt the user whether changes need to be saved on exit.

After attaching action listeners to the text fields, the application will start checking all fields. It doesn't just check the "NEXT" button press; it also checks on an "Enter" key press on any text field by calling checkFields() in the actionPerformed method.

The last validation check was for the IP address format. I used a regular expression feature available in the matches() String class method. The field is checked by a pattern of the simple IPv4 format that can be only 1 to 3 digits followed by a period, repeating 3 times, and followed by another set of 1 to 3 digits.

matches("([\\d]{1,3}\\.){3}[\\d]{1,3}"))

The regular expressions (regex) are built into Java and even have a separate package in JDK java.util.regex. The Sting class uses pattern matching capabilities of regular expressions in several methods (please see the JDK API documentation for more information). The regex are very powerful and can allow for very complex matching, such as "^(([^:/?#]+):)?((//([^/?#]*))?([^?#]*)(\\?([^#]*))?)?(#(.*))?" or something even worse looking.

Conclusion

In this article, I've shown how to dynamically generate notification/validation messages. The technique can be applied to any GUI developed in Swing. I have also described how to add action listeners to any component implicitly and validate data using regular expressions. Even though the validation and notification is specific to the Java Swing toolkit, the technique can be applied to the most modern GUI toolkits.

Download the Code

You can download the source code used in this article here.

References

Java Swing, 2nd Edition by Marc Loy, Robert Eckstein, Dave Wood, James Elliott, and Brian Cole. November 2002. ISBN: 0-596-00408-7.

The Java Developers Almanac 1.4: http://javaalmanac.com/egs/java.util.regex/pkg.html

About the Author

Vlad Kofman is a System Architect working on projects under government defense contracts. He has also been involved with enterprise-level projects for major Wall Street firms and the U.S. government. His main interests are object-oriented programming methodologies and design patterns.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date