Package org.eclipse.jdt.annotation

Annotation Interface Owning

@Retention(CLASS) @Documented @Target({PARAMETER,METHOD,FIELD,TYPE_USE}) public @interface Owning
This annotation allows to specify responsibility for certain objects as they are passed from one method to another.

Based on this annotation, flow oriented analysis tools can be made more precise without the need to perform full-system analysis, as the @Owning annotation describes a contract, consisting of two sides that can be checked independently.

The Eclipse Compiler for Java™ (version 3.37 and greater) interprets this annotation when placed on a value of type AutoCloseable or any subtype. This annotation is interpreted specifically in these locations:

Method parameter (ElementType.PARAMETER):
Here @Owning denotes that the responsibility to close a resource passed into this parameter will lie with the receiving method, on this particular flow.
Method (ElementType.METHOD) - as a way to refer to the method return value:
Here @Owning denotes that responsibility to close a resource received from a call to this method will lie with the receiving code.
Field (ElementType.FIELD)
This annotation marks that the lifecycle of a resource stored in the field is tied to the lifecycle of the enclosing object. In order to allow for precise analysis in this situation, it is recommended that the enclosing class of such a field implements AutoCloseable. In that case, it will be the responsibility of the class's close() implementation to also close all resources stored in @Owning fields.
Method receiver (via ElementType.TYPE_USE)
Annotating a method receiver (explicit this parameter) as owning signals that the method is responsible for closing all contained resources. The method will be treated as a "custom close method".
The annotation is not evaluated in any other TYPE_USE locations.

Responsibility to close a resource may initially arise from these situations:

  • Instantiating a class that is a subtype of AutoCloseable.
  • Receiving a method argument via a parameter of type AutoCloseable (or subtype) that is marked as @Owning.
  • Receiving a result from a call to method that is marked as @Owning and returns AutoCloseable (or a subtype).
    • If the @Owning annotation is absent in this situation, the receiving method is potentially responsible.
  • Within the close() method of a class implementing AutoCloseable, and within each "custom close method", each resource field annotated as @Owning must be closed.

Responsibility to close a resource may be fulfilled by ensuring any of these measures on every possible path:

  • Invoking AutoCloseable.close() or a "custom close method".
  • Passing the resource into a method where the receiving parameter has type AutoCloseable (or subtype) and is marked as @Owning.
  • Returning the resource to the caller, provided that the current method is marked as @Owning and has a declared return type of AutoCloseable (or a subtype).
  • Assigning the resource to a field annotated as @Owning.
  • Within the close() method of a class implementing AutoCloseable and within a "custom close method" closing the resource held by a field tagged as @Owning can happen either directly, or for inherited fields by invoking super.close(), or the super version of a "custom close method".
Since:
2.3