Java 11 is the target Java version for Apache Ignite 3 development. The project's Java code style is based on Google Java Style Guide. But Apache Ignite community could introduce additional rules in order to address some issues, contradictions, etc.

All rules, listed in this document, supplement or override the rules of the Google Java Style Guide.

Appendix A: Code Style

1 Formatting

1.1 Block indentation: +4 spaces

This rule overrides section 4.2 of Google Java Style Guide (only indentation size).

Each time a new block or block-like construct is opened, the indent increases by 4 spaces.

1.2 Column limit: 140

This rule overrides section 4.4 of Google Java Style Guide (only limit size).

Java code has a column limit of 140 characters.

1.3 Horizontal alignment is disallowed

This rule overrides section 4.6.3 of Google Java Style Guide.

Alignment can aid readability, but it creates problems for future maintenance. So horizontal alignment is disallowed.

1.4 Punctuation

All natural language sentences must follow generally accepted punctuation rules. It also means that every sentence must end with dot (.), exclamation point (!) or question mark (?) depending on sentence semantics. This requirement applies to:

  • Code comments (JavaDoc and regular comments).
  • Any descriptive messages (for example metrics or JMX properties description).
  • Exception messages.
  • Log messages.
  • Console output.

Exclusions:

  • Titles of table rows/columns.
  • Content of table cells if this cell contains status enum-like value (e.g. status), numeric value, named value (e.g. entity name).
  • Header titles at any level (for example, documentation/comments).

2 Nullability annotation usages

These rules supplement section 4.8.5 of Google Java Style Guide.

2.1 Common annotating rules

Ignite 3 uses JetBrains nullability annotations. For the sake of code clarity, it is prohibited to use @NotNull annotation, even if it compromises the completeness of the static analysis. However, it is required to use @Nullable in the following places:

  • On a function's return type, if the function can return null;
  • On a function's parameter, if passing null as this parameter will not end in throwing an exception;
  • On a class field, if it can be null.

2.2 Annotating arrays

There are multiple ways to annotate a Java array, which lead to different interpretations by the static analysis tool:

@Nullable Object[] x;            // x array can *contain* null values
Object @Nullable [] x;           // x itself can be null 
@Nullable Object @Nullable [] x; // x array can contain null values *and* be null itself

2.3 Intellij IDEA settings

It is recommended to enable all inspections, related to this topic. Please note, that all nested options should also be enabled:

All these options will be set automatically when importing inspections settings from the repository.

3 Using var keyword

The local variable type inference is the powerful feature of Java language. Nevertheless, one of the main goals of the code style guide is to ensure readability for developers, not for the compiler.

Based on this statement there are limited uses cases where var keyword is allowed. The var keyword is allowed only in cases where a right part of an assignment expression contains an explicit type of variable, that is for assignments of literals and the result of constructor invocation.

Allowed only for assignments of literals, result of constructor invocation and explicit casts:

var i = 42;
var l = 42L;
var s = "Hello";
var list = new ArrayList<Integer>();
var t = (long) l;


Disallowed for all other cases:

var i = Integer.parseInt("42");
var s = "Hello".substring(0, 3);
var list = Arrays.asList(1, 2, 3);        
var map = getMapping(); // some method invocation
var val = map.get(42);

4 Async API Guidelines

4.1 All async methods should have async  suffix

Async method is a method that returns Future , CompletableFuture , or CompletionStage .

In some cases, both sync and async variants exist, and async  suffix is used to distinguish between them:

void upsert(@Nullable Transaction tx, R rec);

CompletableFuture<Void> upsertAsync(@Nullable Transaction tx, R rec);

In other cases, only async variant may be present, but it should have the async  suffix anyway.

4.2 Public APIs should return CompletableFuture - not CompletionStage 

Appendix B: Practices

1 Using Stream API

Historically Apache Ignite developers try to avoid redundant Java object instantiations due to the additional GC pressure. Of course, escape analysis exists but we can't trust this feature and should keep objects instantiation under control where it is possible and justified.

So it is recommended to avoid usage of Stream API at least on the hot code path.

2 Using 3rd party libraries

Using of 3rd party libraries in production code is prohibited. But there are some exceptions to this rule:

  • JUnit for tests
  • Netty
  • ScaleCube
  • Swagger annotations for Open API spec 
  • Micronaut as a REST implementation
  • No labels

Apache Ignite