Wednesday, November 23, 2016

Bash on Windows 10

Because I work with Linux and Windows based machines for development, I often find myself wishing that I had some of the handy command-line Linux tools available in my Windows environments. Cygwin, PowerShell, and custom Groovy scripts written to emulate Linux tools have helped, but I was pleasantly surprised to recently learn that Bash on Ubuntu on Windows 10 is available. In this post, I briefly summarize some of the steps to make bash available on Windows. More detailed instructions with helpful screen snapshots can be found in the Installation Guide.

The Windows Subsystem for Linux (WSL) is described in the Frequently Asked Questions page as "a new Windows 10 feature that enables you to run native Linux command-line tools directly on Windows, alongside your traditional Windows desktop and modern store apps." This same FAQ page states that enabling WSL "downloads a genuine Ubuntu user-mode image, created by Canonical."

The following are the high-level steps for getting Windows 10 ready to use WSL bash.

  1. Verify that Windows 10 installation is 64-bit "system type" and has an "OS Build" of at least 14393.0.
  2. Turn on "Developer Mode"
  3. Enable Windows Subsystem for Linux (WSL) ["Turn Windows Features On or Off" GUI]
  4. Enable Windows Subsystem for Linux (WSL) [PowerShell Command-line]
  5. Restart Computer as Directed
  6. Run bash from Command Prompt (Downloads Canonical's Ubuntu on Windows)
  7. Create a Unix User

Once the steps described above have been executed, bash can be easily used in the Windows 10 environment. A few basic commands are shown in the next screen snapshot. It shows running bash in the Command Prompt and running a few common Linux commands while in that bash shell.

As a developer who uses both Windows and Linux, having bash available in Windows 10 is a welcome addition.

Related Online Resources

Monday, November 21, 2016

Inheriting Javadoc Method Comments

Although the JDK Tools and Utilities pages for the javadoc tool describe the rules of Javadoc method comment reuse by implementing and inheriting methods, it is easy to unnecessarily explicitly describe comment inheritance with {@inheritDoc} when it's not really needed because the same comments would be implicitly inherited. The Java 8 javadoc tool page describes the rules of inherited method Javadoc comments under the section "Method Common Inheritance" and the Java 7 javadoc tool page similarly describes these rules under the section "Automatic Copying of Method Comments." This post uses simple code examples to illustrate some of the key rules of Javadoc method comment inheritance.

The following interfaces and classes are contrived examples that will be used in this post to illustrate inheritance of Javadoc comments on methods. Some inherited/implementing methods include their own Javadoc comments that override parent's/interface's methods comments fully or partially and other simply reuse the parent's/interface's methods' documentation.

Herbivorous Interface

package dustin.examples.inheritance;

/**
 * Marks animals that eat plants.
 */
public interface Herbivorous
{
   /**
    * Eat the provided plant.
    *
    * @param plantToBeEaten Plant that will be eaten.
    */
   void eat(Plant plantToBeEaten);
}

Carnivorous Interface

package dustin.examples.inheritance;

/**
 * Marks an Animal that eats other animals.
 */
public interface Carnivorous
{
   /**
    * Eat the provided animal.
    *
    * @param animalBeingEaten Animal that will be eaten.
    */
   void eat(Animal animalBeingEaten);
}

Omnivorous Interface

package dustin.examples.inheritance;

/**
 * Eats plants and animals.
 */
public interface Omnivorous extends Carnivorous, Herbivorous
{
}

Viviparous Interface

package dustin.examples.inheritance;

/**
 * Mammals that give birth to young that develop within
 * the mother's body.
 */
public interface Viviparous
{
   /**
    * Give birth to indicated number of offspring.
    *
    * @param numberOfOffspring Number of offspring being born.
    */
   void giveBirth(int numberOfOffspring);
}

Animal Class

package dustin.examples.inheritance;

/**
 * Animal.
 */
public abstract class Animal
{
   /**
    * Breathe.
    */
   public void breathe()
   {
   }

   /**
    * Communicate verbally.
    */
   public abstract void verballyCommunicate();
}

Mammal Class

package dustin.examples.inheritance;

/**
 * Mammal.
 */
public abstract class Mammal extends Animal
{
}

MammalWithHair Class

package dustin.examples.inheritance;

import java.awt.*;

/**
 * Mammal with hair (most mammals other than dolphins and whales).
 */
public abstract class MammalWithHair extends Mammal
{
   /** Provide mammal's hair color. */
   public abstract Color getHairColor();
}

Dog Class

package dustin.examples.inheritance;

import java.awt.Color;

import static java.lang.System.out;

/**
 * Canine and man's best friend.
 */
public class Dog extends MammalWithHair implements Omnivorous, Viviparous
{
   private final Color hairColor = null;

   /**
    * {@inheritDoc}
    * @param otherAnimal Tasty treat.
    */
   @Override
   public void eat(final Animal otherAnimal)
   {
   }

   /**
    * {@inheritDoc}
    * @param plantToBeEaten Plant that this dog will eat.
    */
   @Override
   public void eat(final Plant plantToBeEaten)
   {
   }

   /**
    * {@inheritDoc}
    * Bark.
    */
   public void verballyCommunicate()
   {
      out.println("Woof!");
   }

   /**
    * {@inheritDoc}
    * @param numberPuppies Number of puppies being born.
    */
   @Override
   public void giveBirth(final int numberPuppies)
   {
   }

   /**
    * Provide the color of the dog's hair.
    *
    * @return Color of the dog's fur.
    */
   @Override
   public Color getHairColor()
   {
      return hairColor;
   }
}

Cat Class

package dustin.examples.inheritance;

import java.awt.Color;

import static java.lang.System.out;

/**
 * Feline.
 */
public class Cat extends MammalWithHair implements Carnivorous, Viviparous
{
   private final Color hairColor = null;

   /**
    * {@inheritDoc}
    */
   @Override
   public void eat(final Animal otherAnimal)
   {
   }

   @Override
   public void verballyCommunicate()
   {
      out.println("Meow");
   }

   @Override
   public void giveBirth(int numberKittens)
   {
   }

   @Override
   public Color getHairColor()
   {
      return hairColor;
   }
}

Horse Class

package dustin.examples.inheritance;

import java.awt.Color;

import static java.lang.System.out;

/**
 * Equine.
 */
public class Horse extends MammalWithHair implements Herbivorous, Viviparous
{
   private final Color hairColor = null;

   /**
    * @param plant Plant to be eaten by this horse.
    */
   @Override
   public void eat(final Plant plant)
   {
   }

   /**
    *
    */
   @Override
   public void verballyCommunicate()
   {
      out.println("Neigh");
   }

   /**
    * @param numberColts Number of colts to be born to horse.
    */
   @Override
   public void giveBirth(int numberColts)
   {
   }

   @Override
   public Color getHairColor()
   {
      return hairColor;
   }
}

The next screen snapshot shows the contents of the package that includes the interfaces and classes whose code listings are shown above (not all the classes and interfaces in the package had their code listings shown).

The three classes of most interest here from methods' Javadoc perspective are the classes Dog, Cat, and Horse because they implement several interfaces and extend MamalWithHair, which extends Mammal, which extends Animal.

The next screen snapshot is of the Javadoc for the Animal class rendered in a web browser.

The Animal class doesn't inherit any methods from a superclass and doesn't implement any methods from an interface and is not very interesting for this blog post's topic. However, other classes shown here extend this class and so it is interesting to see how its method comments affect the inheriting classes' methods' descriptions.

The next two screen snapshots are of the Javadoc for the Mammal and MammalWithHair classes as rendered in a web browser. There are no Javadoc comments on any significance on Mammal, but there is one method comment for a new method introduced by MammalWithHair.

The next three screen snapshots are of subsets of Javadoc documentation in a web browser for the interfaces Herbivorous, Carnivorous, and Omnivorous. These interfaces provide documentation for methods that will be inherited by classes that implement these methods.

With the generated Javadoc methods documentation for the parent classes and the interfaces shown, it's now time to look at the generated documentation for the methods of the classes extending those classes and implementing those interfaces.

The methods in the Dog class shown earlier generally used {@inheritDoc} in conjunction with additional text. The results of inheriting method Javadoc comments from extended classes and implemented interfaces combined with additional test provided in Dog's comments are shown in the next screen snapshots.

The last set of screen snapshots demonstrates that the Dog class's documentation mixes the documentation of its "parents" with its own specific documentation. This is not surprising. The Dog class's methods generally explicitly inherited Javadoc documentation from the parents (base classes and interfaces), but the Cat class mostly has no Javadoc comments on its methods, except for the eat method, which simply uses {@inheritDoc}. The generated web browser output from this class is shown in the next screen snapshots.

The methods in Cat that had no Javadoc comments applied show up in the generated web browser documentation with documentation inherited from their base classes or interfaces and the documentation on these methods includes the phrase "Description copied from class:" or "Description copied from interface:" as appropriate. The one Cat method that does explicitly include the documentation tag {@inheritDoc} does copy the parent's method's documentation, but does not include the "Description copied from" message.

The Horse class's methods are generally not documented at all and so their generated documentation includes the message "Description copied from...". The eat() and giveBirth() methods of the Horse class override the @param portion and so the parameter documentation for these two methods in the generated web browser documentation (shown in the next set of screen snapshots) is specific to Horse.

From the above code listings and screen snapshots of generated documentation from that code, some observations can be made regarding the inheritance of methods' Javadoc comments by extending and implementing classes. These observations are also described in the javadoc tool documentation:

  • Javadoc comments are inherited from parent class's methods and from implemented interface methods either implicitly when no text is specified (no Javadoc at all or empty Javadoc /** */).
    • javadoc documentation: "The javadoc command allows method comment inheritance in classes and interfaces to fill in missing text or to explicitly inherit method comments."
  • Use {@inheritDoc} explicitly states that comments should be inherited.
    • javadoc documentation: "Insert the {@inheritDoc} inline tag in a method main description or @return, @param, or @throws tag comment. The corresponding inherited main description or tag comment is copied into that spot."
  • Implicit and explicit inheritance of method documentation can be achieved in combination by using {@inheritDoc} tags in different locations within the method comment.

Given the above observations and given the advertised "Method Comments Algorithm", a good rule of thumb for writing Javadoc from the perspective of the HTML generated from the Javadoc is to define general comments at as high a level as possible and allow automatic inheritance of the extended classes's and implemented interfaces' methods' Javadoc documentation to take place, adding or overriding only portions of a method's Javadoc text that are necessary to clarify or enhance the description for a lower-level method. This is better than copying and pasting the same comment on all methods in an inheritance or implementation hierarchy and needing to then keep them all updated together.

This post has focused on the web browser presentation of generated Javadoc methods' documentation. Fortunately, the most commonly used Java IDEs (NetBeans [CTRL+hover], IntelliJ IDEA [CTRL+Q / Settings], Eclipse [F2 / hover / Javadoc View], and JDeveloper [CTRL-D]) support presentation of Javadoc that generally follows the same rules of method documentation inheritance. This means that Java developers can often write less documentation and almost entirely avoid repeated documentation in inheritance and implementation hierarchies.

Monday, November 7, 2016

Fixed-Point and Floating-Point: Two Things That Don't Go Well Together

One of the more challenging aspects of software development can be dealing with floating-point numbers. David Goldberg's 1991 Computing Surveys paper What Every Computer Scientist Should Know About Floating-Point Arithmetic is a recognized classic treatise on this subject. This paper not only provides an in-depth look at how floating-point arithmetic is implemented in most programming languages and computer systems, but also, through its length and detail, provides evidence of the nuances and difficulties of this subject. The nuances of dealing with floating-point numbers in Java and tactics to overcome these challenges are well documented in sources such as JavaWorld's Floating-point Arithmetic, IBM DeveloperWorks's Java's new math, Part 2: Floating-point numbers and Java theory and practice: Where's your point?, Dr. Dobb's Java's Floating-Point (Im)Precision and Fixed, Floating, and Exact Computation with Java's Bigdecimal, Java Glossary's Floating Point, Java Tutorial's Primitive Data Types, and NUM04-J. Do not use floating-point numbers if precise computation is required.

Most of the issues encountered and discussed in Java related to floating-point representation and arithmetic are caused by the inability to precisely represent (usually) decimal (base ten) floating point numbers with an underlying binary (base two) representation. In this post, I focus on similar consequences that can result from mixing fixed-point numbers (as stored in a database) with floating-point numbers (as represented in Java).

The Oracle database allows numeric columns of the NUMBER data type to be expressed with two integers that represent "precision" and "scale". The PostgreSQL implementation of the numeric data type is very similar. Both Oracle's NUMBER(p,s) and PostgreSQL's numeric(p,s) allow the same datatype to represent essentially an integral value (precision specified but scale not specified), a fixed-point number (precision and scale specified), or a floating-point number (neither precision nor scale specified). Simple Java/JDBC-based examples in this post will demonstrate this.

For the examples in this post, a simple table named DOUBLES in Oracle and doubles in PostgreSQL will be created. The DDL statements for defining these simple tables in the two database are shown next.

createOracleTable.sql

CREATE TABLE doubles
(
   int NUMBER(5),
   fixed NUMBER(3,2),
   floating NUMBER
);

createPgTable.sql

CREATE TABLE doubles
(
   int numeric(5),
   fixed numeric(3,2),
   floating numeric
);

With the DOUBLES table created in Oracle database and PostgreSQL database, I'll next use a simple JDBC PreparedStatement to insert the value of java.lang.Math.PI into each table for all three columns. The following Java code snippet demonstrates this insertion.

Inserting Math.PI into DOUBLES Columns

/** SQL syntax for insertion statement with placeholders. */
private static final String INSERT_STRING =
   "INSERT INTO doubles (int, floating, fixed) VALUES (?, ?, ?)";


final Connection connection = getDatabaseConnection(databaseVendor);
try (final PreparedStatement insert = connection.prepareStatement(INSERT_STRING))
{
   insert.setDouble(1, Math.PI);
   insert.setDouble(2, Math.PI);
   insert.setDouble(3, Math.PI);
   insert.execute();
}
catch (SQLException sqlEx)
{
   err.println("Unable to insert data - " + sqlEx);
}

Querying DOUBLES Columns

/** SQL syntax for querying statement. */
private static final String QUERY_STRING =
   "SELECT int, fixed, floating FROM doubles";

final Connection connection = getDatabaseConnection(databaseVendor);
try (final Statement query = connection.createStatement();
     final ResultSet rs = query.executeQuery(QUERY_STRING))
{
   out.println("\n\nResults for Database " + databaseVendor + ":\n");
   out.println("Math.PI :        " + Math.PI);
   while (rs.next())
   {
      final double integer = rs.getDouble(1);
      final double fixed = rs.getDouble(2);
      final double floating = rs.getDouble(3);
      out.println("Integer NUMBER:  " + integer);
      out.println("Fixed NUMBER:    " + fixed);
      out.println("Floating NUMBER: " + floating);
   }
   out.println("\n");
}
catch (SQLException sqlEx)
{
   err.println("Unable to query data - " + sqlEx);
}

The output of running the above Java insertion and querying code against the Oracle and PostgreSQL databases respectively is shown in the next two screen snapshots.

Comparing Math.PI to Oracle's NUMBER Columns

Comparing Math.PI to PostgreSQL's numeric Columns

The simple examples using Java and Oracle and PostgreSQL demonstrate issues that might arise when specifying precision and scale on the Oracle NUMBER and PostgreSQL numeric column types. Although there are situations when fixed-point numbers are desirable, it is important to recognize that Java does not have a fixed-point primitive data type and use BigDecimal or a fixed-point Java library (such as decimal4j or Java Math Fixed Point Library) to appropriately deal with the fixed-point numbers retrieved from database columns expressed as fixed points. In the examples demonstrated in this post, nothing is really "wrong", but it is important to recognize the distinction between fixed-point numbers in the database and floating-point numbers in Java because arithmetic that brings the two together may not have the results one would expect.

In Java and other programming languages, one needs to not only be concerned about the effect of arithmetic operations and available precision on the "correctness" of floating-point numbers. The developer also needs to be aware of how these numbers are stored in relational database columns in the Oracle and PostgreSQL databases to understand how precision and scale designations on those columns can affect the representation of the stored floating-point number. This is especially applicable if the representations queried from the database are to be used in floating-point calculations. This is another (of many) examples where it is important for the Java developer to understand the database schema being used.