io7m
com.io7m.jnull 1.1.0
com.io7m.jnull 1.1.0 Documentation
1
Package Information
1.1
Orientation
1.1.1
Overview
1
The com.io7m.jnull package implements implements a set of functions and annotations to improve the safety of Java code with regards to nullable references.
1.2
Installation
1.2.1
Source compilation
1
The project can be compiled and installed with Maven:
2
$ mvn -C clean install
1.2.2
Maven
1
Regular releases are made to the Central Repository, so it's possible to use the com.io7m.jnull package in your projects with the following Maven dependency:
2
<dependency>
  <groupId>com.io7m.jnull</groupId>
  <artifactId>com.io7m.jnull-core</artifactId>
  <version>1.1.0</version>
</dependency>
3
All io7m.com packages use Semantic Versioning [0], which implies that it is always safe to use version ranges with an exclusive upper bound equal to the next major version - the API of the package will not change in a backwards-incompatible manner before the next major version.
1.3
Platform Specific Issues
1
There are currently no known platform-specific issues.
1.4
License
1
All files distributed with the com.io7m.jnull package are placed under the following license: 
Copyright © 2014 <code@io7m.com> http://io7m.com

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
2
Usage
2.1
Annotations
1
Currently, there are at least six competing standards for annotating fields and variables as not allowing null values.
2.1.1. Non-null annotation standards
2
Each of the above have various problems with regards to their use in portable Java programs. Firstly, three of them are essentially proprietary program-specific annotations (Findbugs, Intellij IDEA, Eclipse). Some of them are standardized but are subject to availability problems (Java EE 6 annotations are only available on the Java EE 6 platform, and at the time of writing, JSR 305 is essentially abandoned). All of them differ in their retention semantics (JSR 305 and Java EE 6 annotations are retained at run-time, others may not be). At the time of writing, Java 8 has just been released and does not contain any definitions of @NotNull annotations, but has incorporated JSR 308 type annotations, which appears to subsume the intentions of JSR 305.
3
Given the lack of a single standard for these annotations, the com.io7m.jnull package provides yet another competing set of annotations intended for use in all io7m packages. The annotations attempt to combine all of the desirable qualities of the above standards whilst attempting to be compatible with most of them.
2.1.2. Annotations
  • @NonNull indicates that a field or variable is never null.
  • @Nullable indicates that a field or variable may be null.
  • @NullableByDefault indicates that all fields and variables in all classes of the annotated package are implicitly annotated @Nullable.
  • @NonNullByDefault indicates that all fields and variables in all classes of the annotated package are implicitly annotated @NonNull.
4
At the time of writing, the Eclipse IDE is capable of using the defined annotations in its static null reference checking. Project Lombok is capable of using the @Nullable and @NonNull annotations for code generation. The defined annotations are retained at run-time.
2.2
Checks
1
The NullCheck class provides functions for performing terse null-checks. The intention is to perform null checking inside constructors and on the boundaries of public interfaces. The rationale for the existence of the null checks at all is that although variables can be marked @NonNull and tools can statically indicate where a null value has been passed where a non-null value is expected, many programmers do not use these tools. If programmers are not using these tools, then they are free to pass null wherever they want - the language does not prevent it. It is better that checks occur on the boundaries of classes and interfaces where problems can be caught at an early stage rather than the code crashing at arbitrary locations because a null value worked its way into the program where one was not expected.
2
A typical pattern is to perform the null checks inside of constructors of immutable types:
2.2.1. Constructor checks
final class C
{
  private final @NonNull String name;
  
  public C(final @Nonnull String in_name)
  {
    this.name = NullCheck.notNull(in_name, "Name");
  }
  
  public @Nonnull String getName()
  {
    return this.name;
  }
}
3
If an abusive programmer attempts to construct a value of type C with a null name, they will be told: Null check failed: Expression evaluated to null: Name, along with a stack trace indicating that the check failed in the constructor of the type. Without the explicit check, the same programmer could sneak null into the program, and any code that called getName would encounter an unexpectedly null value - far away from where the cause of problem actually originated.
2.3
Complaints
1
Nullable references are a major design flaw that have infected almost all programming languages. Better languages rely on algebraic types and pattern matching to completely eliminate all classes of bugs related to nullable references.
3
API Reference
3.1
Javadoc
1
API documentation for the package is provided via the included Javadoc.
[0]
http://semver.org