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