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 applications that work accurately at runtime. Java assertions present a comparatively straightforward method to confirm your programming logic is right.

What you may be taught on this Java tutorial

On this article, you may be taught what assertions are, learn how to write them, and learn how to use them in your Java applications:

• What are Java assertions?
• 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 truly assist us check and debug our assumptions. The compiler ignores feedback, so there isn’t any approach to make use of them for bug detection. Builders additionally continuously don’t replace feedback when altering code.  

In JDK 1.4, assertions had 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 possibly can program assertions to inform you of bugs the place the bugs happen, tremendously lowering the period of time you’d in any other case spend debugging a failing program.

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

write an assertion in Java

Assertions are applied through 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 major(String[] args)
   {
      int x = -1;
      assert x >= 0;
   }
}

The assertion in Itemizing 1 signifies the developer’s perception that variable x comprises a worth that’s better than or equal to 0. Nevertheless, that is clearly not the case; the assert assertion’s execution leads to 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 "major" java.lang.AssertionError
        at AssertDemo.major(AssertDemo.java:6)

This message is considerably cryptic in that it doesn’t establish what triggered the AssertionError to be thrown. If you would like 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 worth—you can’t invoke a way with a void return sort. A helpful expression is a string literal that describes the rationale for failure, as demonstrated in Itemizing 2.

Itemizing 2. Java assertions instance 2

public class AssertDemo
{
   public static void major(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 rationale for the thrown AssertionError:

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

For both instance, working AssertDemo with out the -ea (allow assertions) choice leads to no output. When assertions should not enabled, they aren’t 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 numerous 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 certain 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 certain that callees preserve their contracts with callers.

Writing preconditions

You possibly can implement preconditions on public constructors and strategies by making express checks and throwing exceptions when mandatory. For personal helper strategies, you’ll be able to implement preconditions by specifying assertions. Contemplate 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 constructions.
    *
    *  @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");
      strive (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 major(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 comprise null.

It’s not applicable 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 had been disabled. (In truth, it will be honored as a result of FileInputStream() would throw NullPointerException, however you shouldn’t rely on undocumented conduct.)

Nevertheless, assert is acceptable within the context of the non-public readHeader() helper technique, which might be accomplished ultimately 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 sometimes specified through assertions, no matter whether or not or not the tactic (or constructor) is public. Contemplate the instance in Itemizing 4.

Itemizing 4. Java assertions instance 4

public class AssertDemo
{
   public static void major(String[] args)
   {
      int[] array = { 20, 91, -6, 16, 0, 7, 51, 42, 3, 1 };
      kind(array);
      for (int factor: array)
         System.out.printf("%d ", factor);
      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 kind(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 better 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 bigger than
         // or equal to all values to its left.
         x[j] = a;
      }

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

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

The instance in Itemizing 4 demonstrates an essential attribute of assertions, which is that they’re sometimes costly to execute. For that reason, assertions are often disabled in manufacturing code. In Itemizing 4, isSorted() should scan by way of your entire array, which might be time-consuming within the case of a prolonged array.

Assertions vs. exceptions in Java

Builders use assertions to doc logically unimaginable 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 reply to non-fatal runtime errors akin to working out of reminiscence. Such errors could also be brought on by environmental components akin to a file not current, or by poorly written code, akin to an try and divide by 0. An exception handler is usually written to gracefully get better from the error in order that this system can proceed to run.

Assertions are not any substitute for exceptions. In contrast to exceptions, assertions don’t help error restoration (assertions sometimes halt program execution instantly—AssertionError isn’t meant to be caught); they’re typically disabled in manufacturing code; and so they sometimes don’t show user-friendly error messages (though this isn’t a difficulty with assert). It’s essential to know when to make use of exceptions moderately 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 unimaginable to take the sq. root of a detrimental quantity. Due to this fact, you employ an assertion to fail the tactic if the argument is detrimental. Contemplate the next code fragment:

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

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 inaccurate arguments. Apart from, if assertions are disabled, there isn’t any method to cope with the issue of a detrimental argument. It’s higher to throw an exception, as follows:

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

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 device working this system. After they learn the error message, the developer can repair no matter code led to the exception.

You may need seen a refined distinction between the assertion and the error-detection logic. The assertion assessments x >= 0, whereas the error-detection logic assessments 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 is just not okay. Assertions doc right logic, whereas exceptions doc incorrect runtime conduct.

Conclusion

On this tutorial you’ve discovered learn how to use assertions to doc right program logic. You’ve additionally discovered why assertions are not any alternative for exceptions, and also you’ve seen an instance the place utilizing an exception could be simpler.