Tuesday, January 31, 2012

Book Review: JBoss AS 7: Configuration, Deployment, and Administration

I eagerly accepted Packt Publishing's invitation to review JBoss AS 7: Configuration, Deployment, and Administration because it has been several years since I last used JBoss and I was curious to learn more about JBoss AS 7. I have already written about my First Impressions of Book 'JBoss AS 7 Configuration, Deployment and Administration' and in this post I review the book in greater detail while attempting to minimize how much I repeat from that post. My review is based on an electronic (PDF) copy of JBoss AS 7: Configuration, Deployment, and Administration.

General Features

JBoss AS 7: Configuration, Deployment, and Administration highlights particularly important notes and warnings within boxing that makes them obvious and with an icon representing a pencil and paper. Similarly, tips and tricks also attract special attention with similar boxing and with a light bulb icon. It is helpful to have the most important notes and tips and tricks highlighted like this.

It didn't take much reading of this book to realize how significantly new JBoss AS 7's architecture is. One of the strengths of JBoss AS 7: Configuration, Deployment, and Administration is its comparisons of previous versions of JBoss AS to JBoss AS 7. These comparisons help to understand how changed JBoss AS 7 is and should be especially helpful to anyone migrating to JBoss AS 7 from a previous version.

This book provides several tables of various configuration options and their descriptions. These tables provide easy reference for various configuration options. Although I mostly just skimmed these as I read this book, I noted their existence for future reference when configuring various parts of JBoss AS 7.

Command line interfaces and script-based configuration and administration are emphasized throughout the book. I appreciate this because I tend to use command line approaches far more frequently than I use graphical tools, but some books focus almost exclusively on the graphical tools.

Perhaps the greatest strength of JBoss AS 7: Configuration, Deployment, and Administration is its focus on what its title promises: configuration, deployment, and administration. Although this book does provide brief introductory details about Java EE, the book assumes that the reader will look to focused books or tutorials for detailed information on Java EE. This allows the book to focus on administration and configuration of and deployment to JBoss AS 7.

Although examples in the book specifically use Eclipse, MySQL, and Windows, the descriptions and explanations are broad enough to cover other choices of IDE, database, and operating system respectively. The illustrations assuming one of these are relatively rare and most of the discussion is more general to JBoss AS 7 rather than to any of these supporting products. In many of these cases, alternatives (and how to use those alternatives) are mentioned. The final chapter (cloud computing with OpenShift) and the Appendix (common commands and operations) provide Linux-based examples.

There is a small number of typos and a few instances of questionable sentence structure, but the author's writing style generally flows easily and is easy to follow. There are numerous drawings, tables, and screen snapshots to illustrate points and highlight the more important details. I like the significant white space and the call outs for special notes and observations.

Chapter 1: Installing JBoss AS 7

Because I have not used JBoss for several years, I needed to install JBoss AS 7 and this chapter provides an easy guide to doing that. The chapter begins with brief coverage of the usefulness of Java EE application servers and of JBoss AS 7's high-level design. It then moves into the practical steps necessary for installing JBoss AS 7. The author recommends in one of the "important notes" that readers download and use the Java 6 SDK, but does acknowledge that Java SE 7 SDK is available and should work fine with JBoss AS 7. The chapter discusses installation on Windows and Linux/Unix and even includes a "tip/trick" highlighting of installation on Windows Vista. The chapter goes beyond basic installation (which amounts to uncompressing archive files) to discuss starting and stopping JBoss AS 7 and using Command Line Interface (CLI) to connect to it locally and remotely.

The initial chapter also discusses installation of Eclipse ("the development environment used in this book"). Besides downloading and installing Eclipse (Indigo), the chapter also discusses installation of the JBoss AS plugins (part of JBoss Tools) for Eclipse.

One of my favorite parts of this initial chapter is its coverage of the application server's directory structure and differentiation of JBoss AS 7's "standalone servers and domain servers." This was an important distinction for me coming back to JBoss after such a long period of time, but was an easy one to grasp because of my familiarity with GlassFish. After differentiating between the types of servers supported in JBoss AS 7, the section concludes with coverage of several significant directories/folders in the JBoss AS 7 installation.

Chapter 2: Configuring the Application Server

With JBoss AS 7 and tools (Eclipse) installed, it is natural to move onto configuring the JBoss AS 7 instance. This chapter had some surprises for me, including starting with this: "The application configuration has also been renewed, moving from a large set of XML files to a single monolithic file." The chapter discusses this single file and covers its default names (depending on server configuration). It goes through the configuration file one major section at a time, detailing how to configure the server in each area. There is quite a bit in this chapter on configuring logging. Another thing I learned here that has changed in JBoss in recent years is default use of its own logging framework.

Chapter 3: Configuring Enterprise Services

The third chapter is on configuring enterprise services. This chapter specifically focuses on configuring database connectivity, EJB container, messaging service, and transaction service.

The section of Chapter 3 on configuring database connectivity mentions that JBoss AS 7 comes with the H2 open source database server built in, but then uses MySQL for its examples. I liked how this chapter compared and contrasted how database configuration was performed in previous versions of JBoss AS to how it is now done in JBoss AS 7. The chapter demonstrates XML-based configuration of a data source (and how it was similar to that used in previous versions of the JBoss application server), but then also shows how to use the Java EE 6 annotation @DataSourceDefinition to programmatically configure the data source in conjunction with an EJB 3.1 Singleton EJB.

Chapter 3's section on configuring the EJB container starts by introducing the basics of EJBs with specific introductory focus on the "new EJB 3.1 variants introduced by Java EE 6": Singleton EJB, No-Interface EJB, and Asynchronous EJB. The chapter discusses in detail how to configure the different types of EJBs. It also points out the built-in JMS support in JBoss AS 7 provided by HornetQ. It also covers configuration related to JBoss AS 7's/HornetQ's use of Netty.

The section of Chapter 3 on configuring transactions introduces the Java Transaction API. It then explains how to configure the JTA support for timeouts and statistics gathering.

Chapter 4: JBoss Web Server Configuration

The focus of the fourth chapter of JBoss AS 7: Configuration, Deployment, and Administration is on configuration of the JBoss web server (JBoss Web), which is based on a fork of Tomcat 7. The chapter discusses HTTP connectors, including JBoss Web's built-in Coyote HTTP 1.1 connector and the Apache Portable Runtime (APR) connector. The chapter shows how to separately download and use the ARP connector with JBoss AS 7.

The chapter of JBoss Web server covers configuration of static (HTML/images) and dynamic (JSP) resources and then moves onto discussion of deploying JavaServer Faces (JSF)-based applications on JBoss AS 7. The author points out: "Currently, JBoss AS 7 supports the JSF release 2.1 using the Mojarra implementation, although there are plans for supporting MyFaces implementation too." The chapter then demonstrates using Eclipse to create a JSF project and adding an EJB layer to that application. The chapter also demonstrates adding JPA-based persistence (including how to switch the JPA provider from default Hibernate 4), setting a custom web context, and deploying the web application.

Chapter 5: Configuring a JBoss AS Domain

The fifth chapter concludes the chapters on configuration by providing a more detailed look at configuring JBoss AS 7 domains. Of particular interest to me is the sections on configuring the JVM and providing JVM options. I also found the author's use of VisualVM to be helpful. This detailed chapter introduces domain terminology, explains what a domain is, and explains why a domain does not provide the same functionality or purpose as node clustering. It provides thorough detail on configuring domains.

Chapter 6: Deploying Applications on JBoss AS 7

Deployment to JBoss AS 7 is the focus of Chapter 6. The chapter begins with an introduction to JAR, WAR, EAR, RAR, and SAR files and then goes onto more detailed (but still thankfully brief) coverage of the first three types of archive files.

After covering JAR, WAR, and EAR, the chapter moves onto coverage of manual and automatic deployments to JBoss AS 7. I was happy to see coverage of using CLI to deploy from the command line, but fans of deploying via web page will be happy to know that there is also coverage of deploying from the web administration console. The chapter also demonstrates deploying from the Eclipse IDE.

The most significant bane of my Java development experience has probably been classloaders, which become tricky when application servers, IDEs, and frameworks like Spring are involved. With this in mind, I was happy to see a section in the sixth chapter called "JBoss AS 7 classloading explained." Several pages are devoted to using JBoss's provided mechanism for appropriately dealing with classes used by the application server as well as the deployed applications. The chapter also talks about using Java EE's standard approach of specifying Class-Path in the MANIFEST.MF file.

Chapter 7: Managing the Application Server

The seventh chapter focuses on managing JBoss AS 7 via the command line-based CLI tool and the web-based Web admin console. Differentiation is made between CLI commands and CLI operations. I find the sections "Executing CLI scripts in batch" and "Executing scripts in a file" to be particularly interesting from a CLI perspective. The first section talks about CLI support for a group of commands as an atomic unit and the second section talks about writing file-based administration scripts. The book further peaks my interest in CLI by explaining how to take snapshots in CLI and how to display CLI history.

Although I find that I use command line-based tools for configuration, administration, and deployment of an application server in the long-run, web-based or other graphically-oriented tools are often nice when first using an application server or when trying to figure new things out. In other words, I prefer command line scripting for routine tasks and prefer graphically-oriented administrative tools for new or unusual tasks. The second half of Chapter 7 covers using "The new Web admin console."

Chapter 7's coverage of the history of JBoss's web administrative consoles is a good example of how the overall book does a nice job of comparing and contrasting different versions of JBoss tools. The chapter points out the advantages and limitations of the jmx-console approach (versions of JBoss up to JBoss 4.x) and the Seam-based Web admin console (JBoss 5.x and 6.x) before covering JBoss AS 7's GWT-based Web admin console. As one would expect, the section on Web admin console is filled with screen snapshots demonstrating the Web admin console in action.

Chapter 8: Clustering

One of the things many of us want from our application server is clustering functionality, which is the theme of Chapter 8 (load balancing of web applications is covered in the next chapter). The chapter points out several facets of clustering that have changed in JBoss AS 7. It also covers how JGroups and Infinispan are used to implement JBoss clustering. This is an information--packed chapter that I will be sure to read again before using JBoss AS 7 clustering.

Chapter 9: Load-balancing Web Applications

Chapter 9 covers load-balancing of web applications. The chapter only briefly covers installation of Tomcat's mod_jk and Apache's mod_proxy to connect the Apache web server to JBoss AS 7 because "the installation of either mod_jk or mod_proxy does not differ from earlier AS releases." The remainder of the chapter focused on load balancing covers mod_cluster (new to JBoss AS 7). The chapter concludes by returning to discussion of clustering. The author references the JBoss AS 7.1 High Availability Guide for continuing developments related to JBoss AS 7's clustering support.

Chapter 10: Securing JBoss AS 7

Chapter 10 of JBoss AS 7: Configuration, Deployment, and Administration is focused on security, an increasingly popular topic. Reading about security is often my best cure for insomnia, but there were some interesting nuggets in this chapter that kept my attention.

The chapter introduces PicketBox (formerly known as JBoss Security), the security framework upon which JBoss AS 7's security is built. It then provides a basic overview of Java's security API and provide definitions of key security terms in a Java EE context. This thorough chapter covers a wide range of security-related topics as they pertain to JBoss AS 7.

Chapter 11: Taking JBoss AS 7 in the Cloud

The final chapter is devoted to the trendiest topic of them all: cloud computing. The central focus of this chapter is Red Hat's OpenShift (PaaS). The author does as good a job as I have seen of describing cloud computing and I particularly liked the contrasting of cloud computing to grid computing. The majority of the chapter discusses starting with OpenShift Express and then transitioning to OpenShift Flex.

Appendix

The Appendix is six pages of "common commands and operations" that provides an easy access reference. Although the shown commands use Linux script jboss-admin.sh, the alternative for Windows (jboss-admin.bat) is shown at the beginning of the appendix. The subsections of the appendix are Startup Options, General Commands, Domain Mode, JMS, Data sources, mod_cluster, Batch, and Snapshots.

Conclusion

JBoss AS 7: Configuration, Deployment, and Administration delivers what it's title promises: an introduction and in-depth coverage of configuring and administrating and deploying to JBoss AS 7. Along the way, the book manages to provide differences in JBoss AS 7 from previous versions and to provide introductory details about aspects of Java EE supported in JBoss AS 7. This is not the book one would learn how to write JavaServer Pages, JavaServer Faces applications, EJBs, or other Java EE code from. However, it is the book one would learn how to deploy a Java EE application to JBoss AS 7 and how to maintain and configure JBoss AS 7 to most efficiently support Java EE applications.

Other Reviews

Other reviews of JBoss AS 7: Configuration, Deployment, and Administration are available. These include Markus Eisele's Review: "JBoss AS7 Configuration, Deployment and Administration" by Francesco Marchioni, Rick Wagner's Book Review for "JBoss AS 7 Configuration Deployment and Administration" (unfinished version of the book), Maksim Sorokin's [PACKT] JBoss AS 7 Configuration, Deployment and Administration (announcing review coming), and David Salter's Forthcoming Book Review (announcing review coming).

Monday, January 30, 2012

JavaFX 2 Presents the Quadratic Formula

I recently needed to check some homework answers related to use of the quadratic formula. After realizing that it was getting tedious to do these by hand, I thought of using my calculator to solve them. However, I realized that I could write a simple application using JavaFX to calculate the results and that approach seemed more interesting than using the calculator. This post demonstrates that simple application and provides the relatively straightforward code required to make it happen.

The next couple of screen snapshots demonstrate the simple application in example. They include the initial appearance of the application followed by a couple images showing different values calculated by the application.

The last screen snapshot shows the output when one of the coefficients provided does not allow the quadratic formula to be applied. To provide this application slightly broader application than solely quadratic equation solving, I have added code to detect when the 'a' coefficient is zero and the 'b' coefficient is non-zero. This is a linear equation and the simple application solves it as well as the quadratic equations provided. The next screen snapshot demonstrates the output when coefficients for a linear equation are provided.

The first code listing has nothing to do with the JavaFX presentation layer, but is instead a simple call that provides the basic back-end quadratic formula calculations. I include it here because it is use by the JavaFX example application. It is somewhat interesting in its own right because there are so many ways to calculate a square root in Java. The best-known approach is to use Math.sqrt(double), but the choices are often more varied when using BigDecimal instead of double. Because the purpose of my post is to focus on the JavaFX aspect of this and because my chosen approach is accurate enough for its purposes, I've taken the "easy way" out here and simply use Math.sqrt(double).

SimplisticQuadraticFormula.java
package dustin.examples;

import java.math.BigDecimal;
import java.math.MathContext;
import java.math.RoundingMode;
import java.util.ArrayList;
import java.util.List;

/**
 * Class encapsulating quadratic formula implementation.
 * 
 * @author Dustin
 */
public class SimplisticQuadraticFormula
{
   /** Default precision used for specifying scale. */
   private static final int DEFAULT_PRECISION = MathContext.DECIMAL64.getPrecision();

   /** Convenient representation of zero as BigDecimal. */
   private static final BigDecimal ZERO = new BigDecimal("0");

   /** Convenient representation of two as BigDecimal. */
   private static final BigDecimal TWO = new BigDecimal("2");

   /** Convenient representation of four as BigDecimal. */
   private static final BigDecimal FOUR = new BigDecimal("4");

   /**
    * Calculate intercepts with x-axis.
    * 
    * @param a Coefficient 'a' from a quadratic equation to be solved.
    * @param b Coefficient 'b' from a quadratic equation to be solved.
    * @param c Coefficient 'c' from a quadratic equation to be solved.
    * @return The x-intercepts or solutions to the quadratic equation (two values)
    *     or a single value if solution to a linear equation. Note that two
    *     solutions are always provided for quadratic equations even if they are
    *     the same.
    * @throws NumberFormatException Thrown when x-intercepts cannot be calculated.
    */
   public static List<BigDecimal> calculateXIntercepts(
      final BigDecimal a, final BigDecimal b, final BigDecimal c)
   {
      final List<BigDecimal> intercepts = new ArrayList<BigDecimal>();
      if (a.compareTo(ZERO) == 0 && b.compareTo(ZERO) == 0)
      {
         // neither quadratic nor linear
         throw new NumberFormatException("Must have coefficient for one of x terms.");       
      }
      else if (a.compareTo(ZERO) == 0)  // linear equation
      {
         intercepts.add(c.setScale(DEFAULT_PRECISION).negate().divide(b, RoundingMode.HALF_UP));
      }
      else
      {
         final BigDecimal intercept1 =
            calculateNumeratorWithAddition(a, b, c)
               .divide(calculateDenominator(a), RoundingMode.HALF_UP);
         intercepts.add(intercept1);
         final BigDecimal intercept2 =
            calculateNumeratorWithSubtraction(a, b, c)
               .divide(calculateDenominator(a), RoundingMode.HALF_DOWN);
         intercepts.add(intercept2);
      }
      return intercepts;
   }

   /**
    * Calculate axis of symmetry, if applicable.
    * 
    * @param a Coefficient 'a' from a quadratic equation to be solved.
    * @param b Coefficient 'b' from a quadratic equation to be solved.
    * @return The "x" axis of symmetry.
    * @throws NumberFormatException Thrown if the provided 'a' coefficient is
    *    zero because cannot divide by zero.
    */
   public static BigDecimal calculateAxisOfSymmetry(final BigDecimal a, final BigDecimal b)
   {
      if (a.compareTo(ZERO) == 0)
      {
         throw new NumberFormatException(
            "Cannot calculate axis of symmetry based on x-intercepts when a is zero.");
      }
      return b.setScale(DEFAULT_PRECISION).negate().divide(a.multiply(TWO), RoundingMode.HALF_UP);
   }

   /**
    * Calculate numerator of quadratic formula where the terms are added.
    * 
    * @param a Coefficient 'a' from a quadratic equation to be solved.
    * @param b Coefficient 'b' from a quadratic equation to be solved.
    * @param c Coefficient 'c' from a quadratic equation to be solved.
    * @return Value of numerator in quadratic formula where terms are added.
    * @throws NumberFormatException Thrown if no real solution is available.
    */
   private static BigDecimal calculateNumeratorWithAddition(
      final BigDecimal a, final BigDecimal b, final BigDecimal c)
   {
      return b.negate().add(calculateSquareRootPortion(a, b, c));
   }

   /**
    * Calculate numerator of quadratic formula where the terms are subtracted.
    * 
    * @param a Coefficient 'a' from a quadratic equation to be solved.
    * @param b Coefficient 'b' from a quadratic equation to be solved.
    * @param c Coefficient 'c' from a quadratic equation to be solved.
    * @return Value of numerator in quadratic formula where terms are subtracted.
    * @throws NumberFormatException Thrown if no real solution is available.
    */
   private static BigDecimal calculateNumeratorWithSubtraction(
      final BigDecimal a, final BigDecimal b, final BigDecimal c)
   {
      return b.negate().subtract(calculateSquareRootPortion(a, b, c));
   }

   /**
    * Calculate denominator of quadratic formula.
    * 
    * @param a Coefficient of 'a' from a quadratic equation to be solved.
    * @return Value of denominator in quadratic formula.
    * @throws NumberFormatException Thrown in 0 is provided for coefficient 'a'
    *    because denominator cannot be zero.
    */
   private static BigDecimal calculateDenominator(final BigDecimal a)
   {
      if (a.compareTo(ZERO) == 0)
      {
         throw new NumberFormatException("Denominator cannot be zero.");
      }
      return a.multiply(TWO);
   }

   /**
    * Calculates value of square root portion of quadratic formula.
    * 
    * @param a Coefficient 'a' from a quadratic equation to be solved.
    * @param b Coefficient 'b' from a quadratic equation to be solved.
    * @param c Coefficient 'c' from a quadratic equation to be solved.
    * @return The square root portion of the quadratic formula applied with
    *    the three provided co-efficients.
    * @throws NumberFormatException Thrown if there is no solution (no
    *    intersection of the x-axis) or if a number is encountered that cannot
    *    be handled with BigDecmal return type.
    */
   private static BigDecimal calculateSquareRootPortion(
      final BigDecimal a, final BigDecimal b, final BigDecimal c)
   {
      BigDecimal sqrt;
      final BigDecimal subtrahend = a.multiply(c).multiply(FOUR);
      final BigDecimal insideSqrt = b.pow(2).subtract(subtrahend);
      if (insideSqrt.compareTo(ZERO) < 0)
      {
         throw new NumberFormatException("Cannot be solved: no x-intercepts.");
      }
      else
      {
         final double value = insideSqrt.doubleValue();
         final double sqrtDouble = Math.sqrt(value);
         sqrt = new BigDecimal(sqrtDouble);  // may throw NumberFormatException
      }
      return sqrt;
   }
}

With the calculations portion in place, it is time to move to the focus of this post (the presentation via JavaFX 2). The following code listing provides the JavaFX 2 class (written in pure Java) used for the application. Note that much of this presentation layer code could have been written using FXML.

QuadraticCalculator.java
package dustin.examples;

import java.math.BigDecimal;
import java.util.List;
import javafx.application.Application;
import javafx.event.ActionEvent;
import javafx.event.EventHandler;
import javafx.geometry.Pos;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.control.TextField;
import javafx.scene.control.TextFieldBuilder;
import javafx.scene.image.Image;
import javafx.scene.image.ImageView;
import javafx.scene.layout.HBox;
import javafx.scene.layout.VBox;
import javafx.scene.paint.Color;
import javafx.stage.Stage;

/**
 * JavaFX-based application for solving quadratic equations.
 * 
 * @author Dustin
 */
public class QuadraticCalculator extends Application
{
   /** Coefficient A used in quadratic formula. */
   private TextField coefficientA =
      TextFieldBuilder.create().promptText("Enter Coefficient A").build();

   /** Coeffecient B used in quadratic forumal. */
   private TextField coefficientB =
      TextFieldBuilder.create().promptText("Enter Coefficient B").build();

   /** Coeffecient C (constant) used in quadratic formula. */
   private TextField coefficientC =
      TextFieldBuilder.create().promptText("Enter Coefficient C").build();

   /** First x-intercept. */
   private TextField xIntercept1 =
      TextFieldBuilder.create().disable(true).editable(false).build();

   /** Second x-intercept. */
   private TextField xIntercept2 =
      TextFieldBuilder.create().disable(true).editable(false).build();

   /** Axis of symmetry. */
   private TextField symmetryAxis =
      TextFieldBuilder.create().disable(true).editable(false).build();

   /**
    * Extract Image with provided name.
    * 
    * @param imageName Name of image to be provided.
    * @return Loaded image.
    */
   private Image getImage(final String imageName)
   {
      final String jarFileUrl =
         this.getClass().getProtectionDomain().getCodeSource().getLocation().toString();
      final String url = "jar:" + jarFileUrl + "!/" + imageName;
      System.out.println(url);
      return new Image(url, true);
   }

   /**
    * Provide a read-only horizontal box with quadratic equation and quadratic
    * formula and with a button that can be clicked to calculate solution to
    * quadration equation with provided coefficients.
    * 
    * @return Horizontal box with quadratic equation and quadratic formula.
    */
   private HBox buildEquationsBox()
   {
      final HBox equationsBox = new HBox();
      equationsBox.setAlignment(Pos.CENTER);
      equationsBox.setSpacing(50);
      final Image quadraticEquation = getImage("quadraticEquation-transparent.png");
      final ImageView equationView = new ImageView(quadraticEquation);
      equationsBox.getChildren().add(equationView);
      final Image quadraticFormula = getImage("quadraticFormula-transparent.png");
      final ImageView formulaView = new ImageView(quadraticFormula);
      equationsBox.getChildren().add(formulaView);
      final Button calculateButton = new Button("Calculate");
      calculateButton.setOnAction(
         new EventHandler<ActionEvent>()
         {
            public void handle(ActionEvent t)
            {
               final BigDecimal a = extractBigDecimal(coefficientA.getText());
               final BigDecimal b = extractBigDecimal(coefficientB.getText());
               final BigDecimal c = extractBigDecimal(coefficientC.getText());
               try
               {
                  final List<BigDecimal> intercepts =
                     SimplisticQuadraticFormula.calculateXIntercepts(a, b, c);
                  xIntercept1.setText(intercepts.get(0).toPlainString());
                  xIntercept1.setDisable(false);
                  if (intercepts.size() > 1)
                  {
                     xIntercept2.setText(intercepts.get(1).toEngineeringString());
                     xIntercept2.setDisable(false);
                  }
                  else
                  {
                     xIntercept2.setText("-");
                     xIntercept2.setDisable(true);
                  }
                  if (a.compareTo(new BigDecimal("0")) != 0)
                  {
                     final BigDecimal axis =
                        SimplisticQuadraticFormula.calculateAxisOfSymmetry(a, b);
                     symmetryAxis.setText(axis.toPlainString());
                     symmetryAxis.setDisable(false);
                  }
                  else
                  {
                     symmetryAxis.setText("-");
                     symmetryAxis.setDisable(true);
                  }
               }
               catch (NumberFormatException nfe)
               {
                  xIntercept1.setText("-");
                  xIntercept1.setDisable(true);
                  xIntercept2.setText("-");
                  xIntercept2.setDisable(true);
                  symmetryAxis.setText("-");
                  symmetryAxis.setDisable(true);
               }
            }
         });
      equationsBox.getChildren().add(calculateButton);
      return equationsBox;
   }

   /**
    * Converts provided String to BigDecimal.
    * 
    * @param possibleNumber String to be converted to an instance of BigDecimal.
    * @return The BigDecimal corresponding to the provided String or Double.NaN
    *     if the conversion cannot be performed.
    */
   private BigDecimal extractBigDecimal(final String possibleNumber)
   {
      BigDecimal extractedNumber;
      try
      {
         extractedNumber = new BigDecimal(possibleNumber);
      }
      catch (NumberFormatException nfe)
      {
         extractedNumber = null;
      }
      return extractedNumber;
   }

   /**
    * Provide horizontal box with labels of coefficients and fields to enter
    * coefficient values.
    * 
    * @return Horizontal box for entering coefficients.
    */
   private HBox buildEntryBox()
   {
      final HBox entryBox = new HBox();
      entryBox.setSpacing(10);
      final Label aCoeff = new Label("a = ");
      entryBox.getChildren().add(aCoeff);
      entryBox.getChildren().add(this.coefficientA);
      final Label bCoeff = new Label("b = ");
      entryBox.getChildren().add(bCoeff);
      entryBox.getChildren().add(this.coefficientB);
      final Label cCoeff = new Label("c = ");
      entryBox.getChildren().add(cCoeff);
      entryBox.getChildren().add(this.coefficientC);
      return entryBox;
   }

   /**
    * Construct the output box with solutions based on quadratic formula.
    * 
    * @return Output box with solutions of applying quadratic formula given
    *    provided input coefficients.
    */
   private HBox buildOutputBox()
   {
      final HBox outputBox = new HBox();
      outputBox.setSpacing(10);
      final Label x1 = new Label("x1 = ");
      outputBox.getChildren().add(x1);
      outputBox.getChildren().add(this.xIntercept1);
      final Label x2 = new Label("x2 = ");
      outputBox.getChildren().add(x2);
      outputBox.getChildren().add(this.xIntercept2);
      final Label axis = new Label("axis = ");
      outputBox.getChildren().add(axis);
      outputBox.getChildren().add(this.symmetryAxis);
      return outputBox;
   }

   /**
    * Build overall presentation of application.
    * 
    * @return Vertical box representing input and output of application.
    */
   private VBox buildOverallVerticalLayout()
   {
      final VBox vbox = new VBox();
      vbox.setSpacing(25);
      vbox.getChildren().add(buildEquationsBox());
      vbox.getChildren().add(buildEntryBox());
      vbox.getChildren().add(buildOutputBox());
      vbox.setAlignment(Pos.CENTER);
      return vbox;
   }

   /**
    * Start the JavaFX application for solving quadratic equations.
    * 
    * @param stage Primary stage.
    * @throws Exception JavaFX-related exception.
    */
   @Override
   public void start(final Stage stage) throws Exception
   {
      final Group groupRoot = new Group();
      groupRoot.getChildren().add(buildOverallVerticalLayout());
      final Scene scene = new Scene(groupRoot, 600, 150, Color.LIGHTGRAY);
      stage.setTitle("Quadratic Formula: JavaFX Style");
      stage.setScene(scene);
      stage.show();
   }

   /**
    * Main function for running the JavaFX-based quadratic equation solver.
    * 
    * @param arguments 
    */
   public static void main(final String[] arguments)
   {
      Application.launch(arguments);
   }
}

The JavaFX 2 code above loads two images with transparent backgrounds to display the standard form of a quadratic equation and to display the quadratic formula. In a previous post, I loaded these images from an external URL, but I loaded them from the application's JAR in this example. These images are shown next independent of the application.

quadraticEquation-transparent.png
quadraticFormula-transparent.png

There are several ways this simplistic application could be improved. One improvement would be to make sizes adjustable and bound to one another so the window could be dragged larger or smaller and still look good. Another improvement would be to provide some type of status message on the interface, especially for situations where solutions could not be calculated. A third improvement that would be to present a graph of the quadratic equation specified with the provided coefficients to visually indicate the x-intercepts and axis of symmetry.

JavaFX 2 makes it fairly straight-forward to write simple, user-friendly applications.

Thursday, January 26, 2012

JavaFX 2.1: JavaFX 2's @DefaultProperty Annotation with FXML

The JavaLobby/DZone syndicated version of my blog post Focus on JavaFX 2 FXML with NetBeans 7.1 was recently published and Mihai Dinca-panaitescu (author of DZone article Tuning Your Java VM) added an interesting and useful feedback comment. Specifically, he stated:
I needed to put <children> tag in JavaFx2Menus.fxml

before MenuBar tag.

otherwise an Exception is raised:

javafx.fxml.LoadException: javafx.scene.layout.VBox does not have a default property.

I'm glad that Mihai posted this response for several reasons. First, it will help anyone else reading my post to be aware of that issue. Second, it has allowed me to speculate on the cause of this message in this blog post.

My first thought at reading Mihai's comment was that perhaps the difference was that I was using JavaFX 2.1 (still beta) when I ran the example and perhaps Mihai was using production-ready JavaFX 2.0. Assuming this is the case, the next question was, "What changed in JavaFX 2.1 to make this example work without the children element? Feeling that I need to balance out recent cogitations on my blog with rampant speculation, I decided to do some of that speculation in this post. I speculate that JavaFX 2.1 has applied @DefaultProperty to more controls than in JavaFX 2.0 and that VBox was one of these which now has it applied.

The Javadoc description of the DefaultProperty annotation states, "Specifies a property to which child elements will be added or set when an explicit property is not given." The "Default Properties" section of the highly useful Introducing FXML adds:

A class may define a "default property" using the @DefaultProperty annotation defined in the javafx.fxml package. If present, the sub-element representing the default property can be omitted from the markup.

For example, if the Group class were to define a default property of "children", the <children> element would no longer be required.

My speculation was that JavaFX 2.1 had added @DefaultProperty annotation to the VBox (among others) control. Although the Javadoc for JavaFX 2.1's VBox does not show this annotation applied, the JavaFX 2.1 Javadoc documentation for its parent class, Pane, does indicate the presence of the annotation (and the @DefaultProperty annotation is itself marked @Inherited). The next image shows Pane JavaFX 2.0 and JavaFX 2.1 Javadoc versions side-by-side.

The circled portion of the JavaFX 2.1 API documentation for Pane shows that this control (and controls inheriting from it such as VBox) have children as the component's default property. This explains why children must be explicitly specified in JavaFX 2.0, but is optional for VBox in JavaFX 2.1.

The @DefaultProperty annotation has also been applied to the MenuBar control in JavaFX 2.1. Comparing Javadoc for MenuBar in JavaFX 2.0 to the Javadoc for MenuBar in 2.1 proves this. The next screen snapshot shows them side-by-side.

The circled portion of the JavaFX 2.1 API documentation shows that an annotation has been added in JavaFX 2.1 to the MenuBar class to specify that the default sub-element for MenuBar is now "menus" in JavaFX 2.1. Incidentally, Menu also has a new @DefaultProperty with "items" as its default property. With the @DefaultProperty annotation of MenuBar, I decided to try removing the <menus> elements from my FXML and this appeared to work fine, removing a couple lines of XML from my source FXML and allowing many lines to be less indented. It worked and I had a little more concise of an FXML representation of the same menus application layout.

The more widespread use of the @DefaultProperty annotation is a small, but very welcome addition to JavaFX 2.1. Although adding opening and closing "children" tags adds only two lines per use, it does increase the indentation as well for a well-formatted FXML file. FXML can be appealing because of its visual similarity to the presentation itself and having fewer "extra" lines for common cases can make it even more readable. Although the @DefaultProperty annotation itself was available in JavaFX 2.0, it's much more widely applied and can be more widely used in FXML when using JavaFX 2.1.

Monday, January 23, 2012

Recent Java-Related Posts Worthy of Special Notice

In this blog post, I reference and summarize recent Java-related posts that I have found to be particularly interesting and well worth the time spent reading them.

JDK 8 and Unsigned Integer Arithmetic

Joe Darcy's post Unsigned Integer Arithmetic API now in JDK 8 states that "initial API support for unsigned integer arithmetic" has been pushed into Java 8. Darcy explains that this is implemented largely via static methods on classes java.lang.Integer and java.lang.Long.

Although Darcy's post is not very long, he manages to talk about the specific unsigned arithmetic functionality that is supported (conversion of Strings to unsigned integers, conversion of unsigned integers to Strings, comparing unsigned values, and calculation of unsigned division and remainder) as well as why it was decided to not implement new types such as UnsignedInt. A consequence of not implementing specific unsigned types is that it is easier to inadvertently mix signed and unsigned values and Darcy suggests some ideas built on naming conventions or new built-in annotations to address this concern.

Versions, Code Names, and Features of Java Releases

Speaking of new versions of Java, another Joe (Joseph Kulandai) started 2012 off with a nice post on Java Versions, Features and History. In this post, Kulandai lists the versions of Java in backwards chronological order (Java SE 7 listed first and JDK Version 1.0 at the bottom of the post). Under each major version of Java, Kulandai provides bullet lists of new features in that release and provides the code name of each release.

Java 8 Status Updates

Continuing the theme of Java 8 updates, another post of interest is Johannes Thönes's Java 8 Status Updates. This post looks at the status of "the two big new language features of the upcoming Java SE 8" (Project Lambda and Project Jigsaw).

Java 7 Concurrency

Niklas Schlimm has written two recent posts on using Java 7 concurrency features. He introduces "a flexible thread synchronization mechanism called Phaser" in the post Java 7: Understanding the Phaser and looks in detail at ThreadLocalRandom in the post Java 7: How to write really fast Java code.

OutOfMemoryError: Using Command-line Tools

Vladimir Šor's Solving OutOfMemoryError (part 5) - JDK Tools is, as its title suggests, the fifth in a series on Java memory issues available on that blog ("Solving OutOfMemoryError blog post series"). This post provides a brief summary description and usage information for three command-line tools bundled with the Oracle Java SDK (jps, jmap, and jhat).

The previous entries in this series are written by Nikita Salnikov-Tarnovski: Solving OutOfMemoryError (part 1) - story of a developer, Solving OutOfMemoryError (part 2)- why didn’t operations solve it?, Solving OutOfMemoryError (part 3) - where do you start?, and Solving OutOfMemoryError (part 4) - memory profilers.

Debugging the JVM

Attila Balazs's post Debugging the JVM provides interesting insight on something that we don't seem to have to do as often these days as in the earlier days of the JVM, but could be a very useful resource on the occasions this does occur. Balazs talks about "crashing the JVM itself" via null thread group name and then goes onto explain using gdb in Linux to debug the issue with the JVM.

Groovy Introduction

Alex's post provides an introduction to Groovy including coverage of XML with Groovy, regular expressions with Groovy, and SQL with Groovy.

A New Java Blog With Two JavaFX Posts

I've posted before on why more developers should write blogs. One of the reasons is the variety of opinions and ideas that are generated that way. With this in mind, I have been interested to read the first two posts of new blog Experiments with Java. Both of the blog's current posts have been written in January 2012 and are on JavaFX 2. The posts are Percent Width for TableColumn in JavaFX 2.x TableView and Sliding in JavaFX (It’s all about clipping).

Conclusion

There have been several good Java-related posts in recent weeks and a sample of them are highlighted in this post.

Monday, January 16, 2012

Book Review: JavaFX 2.0: Introduction by Example

Although Oracle's changes to JavaFX at JavaOne 2010 and JavaOne 2011 have converted me from a skeptic to a believer when it comes to JavaFX, the shift in JavaFX vision has not been without its downsides. In particular, the JavaFX book market has been tricky because nearly all available JavaFX books have been about version 1.x. In this post, I review the only book that I'm aware of at time of this writing that is completely focused on JavaFX 2.0: Carl Dea's JavaFX 2.0: Introduction by Example.

I'll start my review by stating the most important observation about JavaFX 2.0: Introduction by Example: it provided me exactly what I was looking for exactly when I needed it. There are some attributes of the book that might be considered negative by some readers that I felt were positives in my use of the book. I'll attempt in this post to articulate the finer points of these attributes so that prospective readers can make up their own minds.

JavaFX 2.0 Introduction by Example does exactly what the title implies: it introduces JavaFX 2.0 via numerous and varied examples. This code-heavy book is roughly similar to a "recipes" or "cookbook" with individual item covered (AKA a "recipe" in a recipes or cookbook) featuring subsections on the problem to be solved, the solution or solutions to that problem, and how those solutions work. Like the best recipes-oriented or cookbook-oriented software development books, this one is constructed so that Chapter 1 ("JavaFX Fundamentals") covers some of the basics of JavaFX early on. In other words, the reader is not dropped into JavaFX without first getting some examples of how to write and deploy basic "Hello World" style JavaFX applications.

Although JavaFX 2.0: Introduction by Example does provide introductory examples early on, I really appreciated the author not spending significant time discussing esoteric features of the language or delving into the history of JavaFX in tedious detail or providing pages worth of explanation on why JavaFX is the greatest thing since sliced bread. I'm usually in a hurry and I have come to resent books wasting my time on such things and this book doesn't do that. In this case, I was already familiar with these aspects of JavaFX (at least its history and why I might be interested in learning more about it), so I was especially appreciative of Dea not wasting paper and my time on that subject. In the book's concise "Introduction," Dea covers in a page and a half some advantages of JavaFX and "some history" of JavaFX along with a simple table articulating features of each release of JavaFX. It's a thing of beauty to be able to read all of this in less than two pages and in the introduction!

Dea covers some more background on JavaFX in the first chapter, but again limits that discussion to a single page. This page is more detailed than the introductory section and is a nice, brief segue into the technical meat of the book. This first page also contains the sentences that I think best sum up the value of this book:

Although this book doesn't go through an exhaustive study of all of JavaFX 2.0's capabilities, you will find common use cases that can help you build richer applications. Hopefully, these recipes can lead you in the right direction by providing practical and real-world examples.

This is exactly what JavaFX 2.0: Introduction by Example has done for me. It has provided me with a fast start into the world of JavaFX. Although I have since used several aspects of JavaFX not covered in this book, the book gave me the start that I needed and I was able to use JavaFX documentation for the areas not covered in this book.

JavaFX 2.0: Introduction by Example gets to the point quickly. Besides common things like the very brief introduction and the index, the book contains four chapters (32 "recipes") spanning 174 pages of text, images, and code. Dea doesn't even waste time with a conclusion, but ends the book with "recipe" 4.5 ("Displaying Content from the Database"). Although some readers may need a conclusion to bring closure to their reading experience, I usually little value in this for me as a reader and I didn't miss it here. I typically don't read these types of book cover-to-cover anyway (instead focusing on sections or recipes I am most interested in), so the conclusion is often unnecessary. Lack of a conclusion is another example of how Dea's book focuses most on what I want: the technical meat.

The four chapters in JavaFX 2.0: Introduction by Example are "JavaFX Fundamentals," "Graphics with JavaFX," "Media with JavaFX," and "JavaFX on the Web." The first chapter was most useful for quickly immersing myself into the basics of JavaFX and how to apply it. The examples in that chapter tend to be simple and easy to follow. The examples in the other three chapters tend to be more sophisticated because the functionality being covered tends to be more sophisticated. There are numerous lengthy code listings in the book. Although code listings may not be the easiest to read, I like to see actual code in any book on a language. Dea typically follows each code sample with descriptive text on any new feature shown in the code sample that had not been covered previously in the book. The code samples can be downloaded from Apress's site. The book also features numerous screen snapshots, which I consider a must for a book focused on user interfaces.

The concise and introductory approach of JavaFX 2.0: Introduction by Example that appealed to me may not appeal to everyone. This book, as advertised in the above cited quotation from the first chapter, is intended to be introductory (hence the title) and not to be exhaustive. Some topics that I have not seen covered in this book include subjects such as FXML, the JavaFX charting functionality, GroovyFX, and ScalaFX. Deployment is only lightly covered (and mostly via NetBeans), but Dea does reference Deploying JavaFX Applications for more details on JavaFX deployment. All of these areas, however, are fairly approachable given the JavaFX basics provided in this book. Dea recommends that readers reference forthcoming (mid-February 2012, Apress) Pro JavaFX 2.0 Platform for an "invaluable resource" that provides "further insight into JavaFX."

Although a small number of the items/recipes covered in JavaFX 2.0: Introduction by Example are based on and assume use of NetBeans, most examples in no way specific to any tool or IDE. Rather, most examples provide "raw" code that can be used in any IDE or favorite text editor. Indeed, many of the examples can be compiled with the javac compiler and executed with the java application launcher. I appreciated that in at least one NetBeans-oriented recipe, Dea took the page or two necessary to provide the code listing for code generated by NetBeans. This is invaluable for those who do not use NetBeans or who want to understand the code itself rather than simply understanding how to use NetBeans to generate the code.

JavaFX 2.0: Introduction by Example was exactly what I needed for an efficient and effective start to my investigation of JavaFX. It may not provide quite the level of soft introduction someone completely unfamiliar with JavaFX might want (especially if that person's basic Java skills are a little rusty) and it isn't an "exhaustive" JavaFX 2.0 reference either. It falls in between these extremes and seems to be a fast start example-based introduction to JavaFX for those who want to get into the core of JavaFX as quickly as possible. That's what I wanted when I purchased this book and I was happy to find out that's exactly what this book provides. It's completely JavaFX 2.x-oriented and there is no sign of deprecated JavaFX Script in any of the code examples.

Focus on JavaFX 2 FXML with NetBeans 7.1

In October 2011, I used the post Hello JavaFX 2.0: Introduction by NetBeans 7.1 beta to look at using NetBeans 7.1 beta to build a simple Hello, World style of JavaFX 2.0 application. In this post, I look at using NetBeans 7.1 (no longer in beta) to build a slightly more sophisticated JavaFX 2 application that makes heavy use of FXML.

Most of my posts on JavaFX 2 up to this point have emphasized the "pure Java" nature of JavaFX 2. The examples in these posts have been written in standard Java using JavaFX 2 APIs directly from the Java source code. These examples have also been built with the javac compiler and executed with the java application launcher. In this post, I take one of those examples [(Pure Java) JavaFX 2.0 Menus] and "port" it to use FXML for presentation layout.

For convenience, I include the entire Java listing for the "pure Java" implementation of the JavaFX 2 menus demonstration.

JavaFX 2.0 Menus Demonstration (Pure Java)
package dustin.examples;

import static java.lang.System.out;

import javafx.application.Application;
import javafx.beans.property.ReadOnlyDoubleProperty;
import javafx.event.ActionEvent;
import javafx.event.EventHandler;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.*;
import javafx.scene.input.KeyCode;
import javafx.scene.input.KeyCodeCombination;
import javafx.scene.input.KeyCombination;
import javafx.scene.paint.Color;
import javafx.stage.Stage;

/**
 * Example of creating menus in JavaFX.
 * 
 * @author Dustin
 */
public class JavaFxMenus extends Application
{
   /**
    * Build menu bar with included menus for this demonstration.
    * 
    * @param menuWidthProperty Width to be bound to menu bar width.
    * @return Menu Bar with menus included.
    */
   private MenuBar buildMenuBarWithMenus(final ReadOnlyDoubleProperty menuWidthProperty)
   {
      final MenuBar menuBar = new MenuBar();

      // Prepare left-most 'File' drop-down menu
      final Menu fileMenu = new Menu("File");
      fileMenu.getItems().add(new MenuItem("New"));
      fileMenu.getItems().add(new MenuItem("Open"));
      fileMenu.getItems().add(new MenuItem("Save"));
      fileMenu.getItems().add(new MenuItem("Save As"));
      fileMenu.getItems().add(new SeparatorMenuItem());
      fileMenu.getItems().add(new MenuItem("Exit"));
      menuBar.getMenus().add(fileMenu);

      // Prepare 'Examples' drop-down menu
      final Menu examplesMenu = new Menu("JavaFX 2.0 Examples");
      examplesMenu.getItems().add(new MenuItem("Text Example"));
      examplesMenu.getItems().add(new MenuItem("Objects Example"));
      examplesMenu.getItems().add(new MenuItem("Animation Example"));
      menuBar.getMenus().add(examplesMenu);

      // Prepare 'Help' drop-down menu
      final Menu helpMenu = new Menu("Help");
      final MenuItem searchMenuItem = new MenuItem("Search");
      searchMenuItem.setDisable(true);
      helpMenu.getItems().add(searchMenuItem);
      final MenuItem onlineManualMenuItem = new MenuItem("Online Manual");
      onlineManualMenuItem.setVisible(false);
      helpMenu.getItems().add(onlineManualMenuItem);
      helpMenu.getItems().add(new SeparatorMenuItem());
      final MenuItem aboutMenuItem =
         MenuItemBuilder.create()
                        .text("About")
                        .onAction(
                            new EventHandler<ActionEvent>()
                            {
                               @Override public void handle(ActionEvent e)
                               {
                                  out.println("You clicked on About!");
                               }
                            })
                        .accelerator(
                            new KeyCodeCombination(
                               KeyCode.A, KeyCombination.CONTROL_DOWN))
                        .build();             
      helpMenu.getItems().add(aboutMenuItem);
      menuBar.getMenus().add(helpMenu);

      // bind width of menu bar to width of associated stage
      menuBar.prefWidthProperty().bind(menuWidthProperty);

      return menuBar;
   }

   /**
    * Start of JavaFX application demonstrating menu support.
    * 
    * @param stage Primary stage.
    */
   @Override
   public void start(final Stage stage)
   {
      stage.setTitle("Creating Menus with JavaFX 2.0");
      final Group rootGroup = new Group();
      final Scene scene = new Scene(rootGroup, 800, 400, Color.WHEAT);
      final MenuBar menuBar = buildMenuBarWithMenus(stage.widthProperty());
      rootGroup.getChildren().add(menuBar);
      stage.setScene(scene);
      stage.show();
   }

   /**
    * Main executable function for running examples.
    * 
    * @param arguments Command-line arguments: none expected.
    */
   public static void main(final String[] arguments)
   {
      Application.launch(arguments);
   }
}

Besides adding the ability to write JavaFX applications in "pure Java" as implemented in the last code listing, JavaFX 2 also provides FXML, an XML grammar for specifying a JavaFX application's layout. This approach is very similar to that provided by Flex's MXML, by OpenLaszlo's LZX, and by Mozilla's XUL. This approach works well with JavaFX's hierarchical Scene Graph.

The ported FXML code is shown next. It is easy to see the presentation structure in this XML.

JavaFx2Menus.fxml
<?xml version="1.0" encoding="UTF-8"?>

<?import java.lang.*?>
<?import javafx.scene.*?>
<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

<VBox id="vbox" prefHeight="400" prefWidth="800"
      xmlns:fx="http://javafx.com/fxml"
      fx:controller="dustin.examples.MenuController">
   <MenuBar fx:id="menuBar" onKeyPressed="#handleKeyInput">
      <menus>
         <Menu text="File">
            <items>
               <MenuItem text="New"/>
               <MenuItem text="Open"/>
               <MenuItem text="Save"/>
               <MenuItem text="Save As"/>
               <SeparatorMenuItem  />
               <MenuItem text="Exit"/>
            </items>
         </Menu>
         <Menu text="JavaFX 2.0 Examples">
            <items>
               <MenuItem text="Text Example"/>
               <MenuItem text="Objects Example"/>
               <MenuItem text="Animation Example"/>
            </items>
         </Menu>
         <Menu text="Help">
            <items>
               <MenuItem text="Search" disable="true"/>
               <MenuItem text="Online Manual" visible="false"/>
               <SeparatorMenuItem />
               <MenuItem text="About" onAction="#handleAboutAction"/>
            </items>
         </Menu>
      </menus>
   </MenuBar>
</VBox>

The important portion of this simple FXML can be viewed on a single page within NetBeans 7.1 as shown in the next screen snapshot.

Besides the conciseness of the FXML and the aesthetically pleasing hierarchical presentation, the FXML also should look familiar to anyone who has worked with Flex, OpenLaszlo, or XUL. Most of the presentation structure is easily identified in the FXML document. This example includes an onAction handler that responds to the "About" menu item and there is an onKeyPressed action associated with the menu bar as well (I could not figure out a way to easily associate this handler with the menu item itself). Both of these actions reference names that start with the # symbol. The names following the # are names of methods on the controller class (defined by the fx:controller attribute of the VBox as the class named dustin.examples.MenuController). The source for this controller class is shown next.

MenuController.java
package dustin.examples;

import static java.lang.System.out;
import java.net.URL;
import java.util.ResourceBundle;
import javafx.event.ActionEvent;
import javafx.fxml.FXML;
import javafx.fxml.Initializable;
import javafx.scene.control.MenuBar;
import javafx.scene.input.InputEvent;
import javafx.scene.input.KeyCode;
import javafx.scene.input.KeyEvent;

/**
 * Controller class for JavaFX 2 Menus with FXML post and demonstration.
 * 
 * @author Dustin
 */
public class MenuController implements Initializable
{
   @FXML
   private MenuBar menuBar;

   /**
    * Handle action related to "About" menu item.
    * 
    * @param event Event on "About" menu item.
    */
   @FXML
   private void handleAboutAction(final ActionEvent event)
   {
      provideAboutFunctionality();
   }

   /**
    * Handle action related to input (in this case specifically only responds to
    * keyboard event CTRL-A).
    * 
    * @param event Input event.
    */
   @FXML
   private void handleKeyInput(final InputEvent event)
   {
      if (event instanceof KeyEvent)
      {
         final KeyEvent keyEvent = (KeyEvent) event;
         if (keyEvent.isControlDown() && keyEvent.getCode() == KeyCode.A)
         {
            provideAboutFunctionality();
         }
      }
   }

   /**
    * Perform functionality associated with "About" menu selection or CTRL-A.
    */
   private void provideAboutFunctionality()
   {
      out.println("You clicked on About!");      
   }

   @Override
   public void initialize(final URL url, final ResourceBundle rb)
   {
      menuBar.setFocusTraversable(true);
   }   
}

The above code from the controller class includes the two methods referenced as action handlers in the FXML with the # prefixes. These two methods are private and normally would not be visible to the FXML loader, but the use of the annotation @FXML gets around this problem. The menuBar attribute is also private but visible to the FXML loader thanks to its own @FXML annotation.

To get the application to respond to CTRL-A before any initial access of the menu bar, I found that I needed to have a reference to the menu bar in the controller and call setFocusTraversable(true) on that instance. Without doing that, the CTRL-A would only be responded to if I had first clicked on the menu bar once. The hook from the FXML to this attribute in the controller is the fx:id attribute used in the FXML. That attribute references the name "menuBar", which is (not coincidentally) also the name of the attribute in the controller class. In other words, the attribute fx:id="menuBar" ties the XML element that attribute is on in the FXML to the attribute with the same name in the controller.

I did not show much in this post specific to NetBeans 7.1, but it is worth noting that I had all the pertinent files created in a new project using NetBeans 7.1's New Project wizard and selecting a JavaFX FXML Application as the project type. This created a basic FXML file, a basic controller file, and a main class for loading the FXML and running the application. I modified these to the examples above for the FXML and for the controller class. The modified class that loads the FXML and starts the JavaFX application is shown next. (There's not a lot to it!)

JavaFxMenusWithFxmlDemo.java
package dustin.examples;

import javafx.application.Application;
import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.stage.Stage;

/**
 * Simple example of JavaFX 2 FXML used to demonstrate JavaFX 2 menus. This is a
 * "port" of the example featured using "pure Java" (no FXML) in the post
 * "(Pure Java) JavaFX 2.0 Menus"
 * (http://marxsoftware.blogspot.com/2011/12/pure-java-javafx-20-menus.html).
 * 
 * @author Dustin
 */
public class JavaFxMenusWithFxmlDemo extends Application
{
   /**
    * Main function for running this application.
    * 
    * @param arguments Command-line arguments: none expected.
    */
   public static void main(String[] arguments)
   {
      Application.launch(JavaFxMenusWithFxmlDemo.class, arguments);
   }

   /**
    * Overridden Application.start(Stage) method.
    * 
    * @param stage Primary stage.
    * @throws Exception JavaFX application exception.
    */
   @Override
   public void start(final Stage stage) throws Exception
   {
      final Parent fxmlRoot = FXMLLoader.load(getClass().getResource("JavaFx2Menus.fxml"));
      stage.setScene(new Scene(fxmlRoot));
      stage.show();
   }
}

I won't show the output here because it's essentially what the "pure Java" version produced, which is shown in my post on that approach. Besides generating the files that I adapted for my application, NetBeans 7.1's new project wizard for a JavaFX FXML application also created a project that automatically packages up what I need for my JavaFX application in an executable JAR. The contents of the JAR in this case are shown in the next screen snapshot.

The trickiest part about using FXML is the relatively less available documentation. The pure Java APIs have the strong Javadoc API documentation, but I know of no such thing for FXML (including no documentation or schema for the namespace http://javafx.com/fxml). There are some great resources of FXML such as Getting Started with FXML and Introduction to FXML. Perhaps the best document for figuring out what elements and attributes FXML provides is Introducing FXML: A Markup Language for JavaFX, which explains the "mapping" of JavaFX standard Java API classes to JavaFX FXML elements and attributes.

FXML appears to be a fairly attractive approach for building a JavaFX application because it nicely separates presentation (FXML) from business logic (controller class and classes that would be called by controller methods). This can make it easier to visually see the GUI layout in the hierarchical XML and keep the logic and presentation from cluttering each other.

Thursday, January 12, 2012

Revealing Project Naughtiness with Tattletale

Tattletale is a highly useful development tool that not only has a catchy name, but also has a clever slogan: "Betraying your project's naughty little secrets." Tattletale scours JAR files to find various naught little secrets about dependencies, multiple versions, extraneous versions of classes, JARs in multiple locations, and so forth. It is a simple tool that can be run from the command-line to generate simple HTML reports of multiple characteristics about JARs and classes.

To demonstrate Tattletale, I will execute it against a Spring Framework 2.5.6 installation. It is simple to run Tattletale and this is demonstrated in the next screen snapshot.

The tattletale.jar is an executable JAR and so is run with java -jar tattletale.jar. The first argument passed to it is the directory to be recursively searched (Spring 2.5.6 distribution in this case) and the second argument is the directory to which the HTML reports should be written (spring-output in this example). The directory listing of the spring-output directory is shown next.

As the two previous snapshots indicate, it is very straightforward to run Tattletale against a desired directory. A web browser can be used to open the index.html page as the starting page. This is shown in the next screen snapshot.

Only a subset of the available reports are shown in the above snapshot. Clicking on links brings up the individual reports. I show portions of select reports (circular dependencies, class locations, multiple copies of JARs, transitive dependencies, and transitive dependents) next.

Tattletale is so easy to use, very little documentation is necessary. However, there is a slide presentation and a User's Guide with introductory information. The 32-page User Guide covers running Tattletale (similar to this post) along with providing details on how to configure the tool via jboss-tattletale.properties and providing an overview of the many reports that Tattletale provides about one's project.

To address and correct a project's naughtiest little secrets, one must know what they are. Tattletale is an easy-to-use tool that exposes these naughty secrets so that they can be addressed.

Wednesday, January 11, 2012

NetBeans 7.1's Unused Assignment and Dead Branch Hints

One of the new code hints provided by NetBeans 7.1 is the Unused Assignment hint. A simple code sample that will cause this hint to be displayed in NetBeans 7.1 is shown next.

Demonstrating Unused Assignment
   /**
    * Demonstrate NetBeans 7.1 code hint for situation in which variable
    * assignment is made but never used.
    * 
    * @return Integer.
    */
   private static int demoUnusedAssignment()
   {
      int i = 2;
      // ... do some good stuff, but without changing i's assignment or
      //     accessing i's value ...
      i = 3;
      return i;
   }

In the code above, the local variable "i" is initialized to 2, but is never used and then is initialized again, making the first initialization unnecessary. The next image is a screen snapshot that shows NetBeans 7.1 displaying a warning code hint for the unused assignment.

As the above image indicates, NetBeans 7.1 warns of "The assigned value is never used."

The New And Noteworthy in NetBeans IDE 7.1 page mentions this hint among others and states:

Unused Assignment

A new pair of hints, Unused Assignment and Dead Branch, was introduced. The Unused Assignment finds values that are computed and assigned to a variable, but never used by reading the variable. The Dead Branch hint searches for branches of code that can never be executed.

Oh Dead Branch Hint, Where Art Thou?

The Unused Assignment Hint seems to work as suggested based on the example shown above. However, I have not been able to generate code that demonstrates the "Dead Branch" hint. I wonder if the Dead Branch hint is not yet supported and text related to it is not supposed to be under the "Unused Assignment" heading.

The following code contains a listing with several methods that I would expect might potentially lead to a warning about a dead code branch. None of these cause this code hint to appear in any form (warning or error) in my installation of NetBeans 7.1.

Methods With Compilable Dead Code Branches
package dustin.examples;

import static java.lang.System.out;

/**
 * Class demonstrating NetBeans 7.1's hint for dead code.
 * 
 * @author Dustin
 */
public class DeadCode
{
   /**
    * Nonsense method that includes an "else" clause that can never be executed.
    * 
    * @param someInt Any primitive int.
    */
   private static void neverExecutedElse(final int someInt)
   {
      if (someInt < 0)
      {
         out.println("The integer you provided is less than zero.");
      }
      else if (someInt > 0)
      {
         out.println("The integer you provided is greater than zero.");
      }
      else if (someInt == 0)
      {
         out.println("The integer is equal to zero.");
      }
      else
      {
         out.println("Unable to categorize provided integer.");
      }
   }

   /**
    * Nonsense method that has executable code following conditions that are
    * always true and always lead to premature termination of the method.
    */
   private static void codeAfterAlwaysTrueConditional()
   {
      if (true)
      {
         throw new RuntimeException("Ouch!");
      }
      final String nothingHere = "Nothing here.";
      out.println(nothingHere);

      if (true)
      {
         return;
      }
      final String nothingHereEither = "Nothing here either.";
      out.println(nothingHereEither);
   }

   /**
    * Nonsense method that prints text to standard output only if the provided
    * boolean can be both {@code true} and {@code false} at the same time.
    * 
    * @param boolValue Boolean value of no consequence.
    */
   private static void cannotHaveItBothWays(final boolean boolValue)
   {
      if (boolValue)
      {
         if (!boolValue)
         {
            out.println("Make up your mind (true or false)!");
         }
      }
      else
      {
         if (boolValue)
         {
            out.println("Make up your mind (false or true)!");
         }
      }
   }

   /**
    * Runs else-if that is same as previous if such that one conditonal
    * prevents the second conditional's implementation from ever being executed.
    * 
    * @param boolValue A boolean value of no consequence.
    */
   private static void pesterUntilItWorks(boolean boolValue)
   {
      boolValue = true;
      if (boolValue)
      {
         out.println("It matches once.");
      }
      else if (boolValue)
      {
         out.println("It matches twice.");
      }
      else if (!boolValue)
      {
         out.println("No match once.");
      }
      else if (!boolValue)
      {
         out.println("No match twice!");
      }
   }

   /**
    * Cover all conditions in first conditional and include a never-can-happen
    * else portion of conditional.
    */
   private static void completeConditionalCoverage()
   {
      boolean boolValue = true;
      if (boolValue || !boolValue)
      {
         out.println("I'm always going to happen.");
      }
      else
      {
         out.println("I'm never going to happen.");
      }

      if (boolValue && !boolValue)
      {
         out.println("I'll never happen either.");
      }
      else
      {
         out.println("I'll also always happen.");
      }
   }

   /**
    * Main executable function.
    * 
    * @param arguments Command-line arguments: none expected.
    */
   public static void main(final String[] arguments)
   {
      if (false)
      {
         neverExecutedElse(5);
         codeAfterAlwaysTrueConditional();
         cannotHaveItBothWays(true);
         pesterUntilItWorks(true);
         demoUnusedAssignment();
         completeConditionalCoverage();
      }
   }
}

Although none of the methods in the directly previous code listing lead to the Dead Branch code hint, NetBeans 7.1 does include configuration options for the Dead Branch hint. This is shown in the next screen snapshot (selecting Tools->Options followed by the "Editor" tab and then selecting "Hints").

The NetBeans 7.1 News and Noteworthy page shows examples of other new hints, but does not show an example of the Dead Branch hint. Also, the text talking about Dead Branch is mixed with the section on Unused Assignment and under a heading that only talks about Unused Assignment. As my previous code listing demonstrates, I attempted to come up with a code sample to demonstrate the Dead Branch hint, but have not been able to do so. The purpose of this hint ("search[ing] for branches of code that can never be executed") sounds like a nice complement to compiler errors such as "unreachable statement" and "exception already caught" and other NetBeans "green" warnings such as "variable such-and-such is not used."

I have blogged about NetBeans hints before and the addition of new hints in NetBeans 7.1 is welcome. If anyone knows of a code sample that will demonstrate the Dead Branch hint in NetBeans 7.1, please share!