The way to use assertions in Java

Builders make assumptions about how our code will behave when executed, however we’re not all the time proper. With out certainty, it’s difficult to put in writing packages that work appropriately at runtime. Java assertions present a comparatively straightforward approach to confirm your programming logic is appropriate.

What you will be taught on this Java tutorial

On this article, you will be taught what assertions are, the right way to write them, and the right way to use them in your Java packages:

• What are Java assertions?
• The way to write an assertion in Java
• Assertions with preconditions and postconditions
• The distinction between Java assertions and Java exceptions

What are Java assertions?

Earlier than JDK 1.4, builders typically used feedback to doc assumptions about program correctness. However feedback do not really assist us check and debug our assumptions. The compiler ignores feedback, so there is not any approach to make use of them for bug detection. Builders additionally incessantly don’t replace feedback when altering code.  

In JDK 1.4, assertions have been launched as a brand new mechanism for testing and debugging assumptions about Java code. In essence, assertions are compilable entities that execute at runtime, assuming you’ve enabled them for program testing. You may program assertions to inform you of bugs the place the bugs happen, enormously lowering the period of time you’ll in any other case spend debugging a failing program.

Assertions are used to codify the necessities that render a program appropriate or not by testing situations (Boolean expressions) for true values, and notifying the developer when such situations are false. Utilizing assertions can enormously enhance your confidence within the correctness of your code.

The way to write an assertion in Java

Assertions are applied by way of the assert assertion and java.lang.AssertionError class. This assertion begins with the key phrase assert and continues with a Boolean expression. It’s expressed syntactically as follows:

assert BooleanExpr;

If BooleanExpr evaluates to true, nothing occurs and execution continues. If the expression evaluates to false, nonetheless, AssertionError is instantiated and thrown, as demonstrated in Itemizing 1.

Itemizing 1. Java assertions instance 1

public class AssertDemo
{
   public static void essential(String[] args)
   {
      int x = -1;
      assert x >= 0;
   }
}

The assertion in Itemizing 1 signifies the developer’s perception that variable x comprises a price that’s higher than or equal to 0. Nevertheless, that is clearly not the case; the assert assertion’s execution ends in a thrown AssertionError.

Compile Itemizing 1 (javac AssertDemo.java) and run it with assertions enabled (java -ea AssertDemo). It is best to observe the next output:

Exception in thread "essential" java.lang.AssertionError
        at AssertDemo.essential(AssertDemo.java:6)

This message is considerably cryptic in that it doesn’t establish what induced the AssertionError to be thrown. In order for you a extra informative message, use the assert assertion under:

assert BooleanExpr : expr;

Right here, expr is any expression (together with a way invocation) that may return a price—you can’t invoke a way with a void return sort. A helpful expression is a string literal that describes the explanation for failure, as demonstrated in Itemizing 2.

Itemizing 2. Java assertions instance 2

public class AssertDemo
{
   public static void essential(String[] args)
   {
      int x = -1;
      assert x >= 0: "x < 0";
   }
}

Compile Itemizing 2 (javac AssertDemo.java) and run it with assertions enabled (java -ea AssertDemo). This time, it’s best to observe the next barely expanded output, which incorporates the explanation for the thrown AssertionError:

Exception in thread "essential" java.lang.AssertionError: x < 0
        at AssertDemo.essential(AssertDemo.java:6)

For both instance, operating AssertDemo with out the -ea (allow assertions) choice ends in no output. When assertions will not be enabled, they don’t seem to be executed, though they’re nonetheless current within the class file.

Assertions with preconditions and postconditions

Assertions check a program’s assumptions by verifying that its varied preconditions and postconditions aren’t violated, alerting the developer when a violation happens:

• A precondition is a situation that should consider to true earlier than the execution of some code sequence. Preconditions be sure that callers preserve their contracts with callees.
• A postcondition is a situation that should consider to true after the execution of some code sequence. Postconditions be sure that callees preserve their contracts with callers.

Writing preconditions

You may implement preconditions on public constructors and strategies by making express checks and throwing exceptions when obligatory. For personal helper strategies, you’ll be able to implement preconditions by specifying assertions. Think about the instance in Itemizing 3.

Itemizing 3. Java assertions instance 3

import java.io.FileInputStream;
import java.io.InputStream;
import java.io.IOException;

class PNG
{
   /**
    *  Create a PNG occasion, learn specified PNG file, and decode
    *  it into appropriate buildings.
    *
    *  @param filespec path and title of PNG file to learn
    *
    *  @throws NullPointerException when <code>filespec</code> is
    *          <code>null</code>
    */
   PNG(String filespec) throws IOException
   {
      // Implement preconditions in non-private constructors and
      // strategies.

      if (filespec == null)
         throw new NullPointerException("filespec is null");
      attempt (FileInputStream fis = new FileInputStream(filespec))
      {
         readHeader(fis);
      }
   }

   non-public void readHeader(InputStream is) throws IOException
   {
      // Affirm that precondition is glad in non-public
      // helper strategies.

      assert is != null : "null handed to is";
   }
}

public class AssertDemo
{
   public static void essential(String[] args) throws IOException
   {
      PNG png = new PNG((args.size == 0) ? null : args[0]);
   }
}

The PNG class in Itemizing 3 is the minimal starting of a library for studying and decoding PNG picture recordsdata. The constructor explicitly compares filespec with null, throwing NullPointerException when this parameter comprises null. The purpose is to implement the precondition that filespec not include null.

It’s not acceptable to specify assert filespec != null; as a result of the precondition talked about within the constructor’s Javadoc wouldn’t (technically) be honored when assertions have been disabled. (Actually, it could be honored as a result of FileInputStream() would throw NullPointerException, however you shouldn’t depend upon undocumented conduct.)

Nevertheless, assert is acceptable within the context of the non-public readHeader() helper technique, which will probably be accomplished finally to learn and decode a PNG file’s 8-byte header. The precondition that is all the time be handed a non-null worth will all the time maintain.

Writing postconditions

Postconditions are usually specified by way of assertions, no matter whether or not or not the tactic (or constructor) is public. Think about the instance in Itemizing 4.

Itemizing 4. Java assertions instance 4

public class AssertDemo
{
   public static void essential(String[] args)
   {
      int[] array = { 20, 91, -6, 16, 0, 7, 51, 42, 3, 1 };
      type(array);
      for (int ingredient: array)
         System.out.printf("%d ", ingredient);
      System.out.println();
   }

   non-public static boolean isSorted(int[] x)
   {
      for (int i = 0; i < x.size - 1; i++)
         if (x[i] > x[i + 1])
            return false;
      return true;
   }

   non-public static void type(int[] x)
   {
      int j, a;
      // For all integer values besides the leftmost worth ...
      for (int i = 1; i < x.size; i++)
      {
         // Get integer worth a.
         a = x[i];
         // Get index of a. That is the preliminary insert place, which is
         // used if a is bigger than all values within the sorted part.
         j = i;
         // Whereas values exist to the left of a's insert place and the
         // worth instantly to the left of that insert place is
         // numerically higher than a's worth ...
         whereas (j > 0 && x[j - 1] > a)
         {
            // Shift left worth -- x[j - 1] -- one place to its proper --
            // x[j].
            x[j] = x[j - 1];
            // Replace insert place to shifted worth's authentic place
            // (one place to the left).
            j--;
         }
         // Insert a at insert place (which is both the preliminary insert
         // place or the ultimate insert place), the place a is larger than
         // or equal to all values to its left.
         x[j] = a;
      }

      assert isSorted(x): "array not sorted";
   }
}

Itemizing 4 presents a type() helper technique that makes use of the insertion type algorithm to type an array of integer values. I’ve used assert to examine the postcondition of x being sorted earlier than type() returns to its caller.

The instance in Itemizing 4 demonstrates an vital attribute of assertions, which is that they’re usually costly to execute. Because of this, assertions are often disabled in manufacturing code. In Itemizing 4, isSorted() should scan by way of all the array, which could be time-consuming within the case of a prolonged array.

Assertions vs. exceptions in Java

Builders use assertions to doc logically unattainable conditions and detect errors of their programming logic. At runtime, an enabled assertion alerts a developer to a logic error. The developer refactors the supply code to repair the logic error after which recompiles this code.

Builders use Java’s exception mechanism to answer non-fatal runtime errors reminiscent of operating out of reminiscence. Such errors could also be attributable to environmental components reminiscent of a file not present, or by poorly written code, reminiscent of an try to divide by 0. An exception handler is commonly written to gracefully get better from the error in order that this system can proceed to run.

Assertions aren’t any substitute for exceptions. In contrast to exceptions, assertions don’t assist error restoration (assertions usually halt program execution instantly—AssertionError isn’t meant to be caught); they’re typically disabled in manufacturing code; they usually usually don’t show user-friendly error messages (though this isn’t a difficulty with assert). It’s vital to know when to make use of exceptions fairly than assertions.

When to make use of exceptions

Suppose you’ve written a sqrt() technique that calculates the sq. root of its argument. In a non-complex quantity context, it’s unattainable to take the sq. root of a damaging quantity. Due to this fact, you utilize an assertion to fail the tactic if the argument is damaging. Think about the next code fragment:

public double sqrt(double x)
{
   assert x >= 0 : "x is damaging";
   // ...
}

It’s inappropriate to make use of an assertion to validate an argument on this public technique. An assertion is meant to detect errors in programming logic and to not safeguard a way from faulty arguments. Apart from, if assertions are disabled, there is no such thing as a approach to cope with the issue of a damaging argument. It’s higher to throw an exception, as follows:

public double sqrt(double x)
{
   if (x < 0)
      throw new IllegalArgumentException("x is damaging");
   // ...
}

The developer may select to have this system deal with the unlawful argument exception, or just propagate it out of this system the place an error message is displayed by the software operating this system. Once they learn the error message, the developer can repair no matter code led to the exception.

You may need observed a refined distinction between the assertion and the error-detection logic. The assertion checks x >= 0, whereas the error-detection logic checks x < 0. The assertion is optimistic: We assume that the argument is okay. In distinction, the error-detection logic is pessimistic: We assume that the argument shouldn’t be okay. Assertions doc appropriate logic, whereas exceptions doc incorrect runtime conduct.

Conclusion

On this tutorial you’ve discovered the right way to use assertions to doc appropriate program logic. You’ve additionally discovered why assertions aren’t any substitute for exceptions, and also you’ve seen an instance the place utilizing an exception could be more practical.