Package org.eclipse.jdt.core.util

# Class ExternalAnnotationUtil

java.lang.Object
org.eclipse.jdt.core.util.ExternalAnnotationUtil

public final class ExternalAnnotationUtil extends Object
Utilities for accessing and manipulating text files that externally define annotations for a given Java type. Files are assumed to be in ".eea format", a textual representation of annotated signatures of members of a given type.

Since:
  3.11
Restriction:
  This class is not intended to be instantiated by clients.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`ExternalAnnotationUtil.MergeStrategy`
Strategy for merging a new signature with an existing (possibly annotated) signature.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final char`
`NO_ANNOTATION`
Represents absence of a null annotation.
`static final char`
`NONNULL`
Representation of a 'nonnull' annotation, independent of the concrete annotation name used in Java sources.
`static final char`
`NULLABLE`
Representation of a 'nullable' annotation, independent of the concrete annotation name used in Java sources.

## Constructor Summary

Constructors
Constructor
Description
`ExternalAnnotationUtil()`

## Method Summary

Modifier and Type
Method
Description
`static void`
`annotateMember(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedSignature, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor)`
Update the given external annotation file with details regarding annotations of one specific method or field.
`static void`
`annotateMethodParameterType(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedParameterType, int paramIdx, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor)`
Update the given external annotation file with details regarding annotations of a parameter type of a given method.
`static void`
`annotateMethodReturnType(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedReturnType, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor)`
Update the given external annotation file with details regarding annotations of the return type of a given method.
`static void`
`annotateMethodTypeParameter(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedTypeParameter, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor)`
Update the given external annotation file with details regarding annotations of a type parameter of a given method.
`static String[]`
`annotateParameterType(String originalSignature, String annotatedType, int paramIdx, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Apply the specified changes on a parameter within the given signature.
`static String[]`
`annotateReturnType(String originalSignature, String annotatedType, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Apply the specified changes on the return type of the given signature.
`static String[]`
`annotateType(String originalSignature, String annotatedType, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Apply the specified changes on the given type.
`static String[]`
`annotateTypeParameter(String originalSignature, String annotatedType, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Apply the specified changes on a type parameter within the given signature.
`static void`
`annotateTypeTypeParameter(String typeName, org.eclipse.core.resources.IFile file, String originalSignature, String annotatedTypeParameter, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor)`
Update the given external annotation file with details regarding annotations of a type parameter of the type itself.
`static String`
`extractGenericSignature(IMethodBinding methodBinding)`
Answer the give method's signature in class file format.
`static String`
`extractGenericTypeParametersSignature(ITypeBinding type)`
Answer the signature of all type parameters of this type in class file format.
`static String`
`extractGenericTypeSignature(ITypeBinding type)`
Answer the given types's signature in class file format.
`static String`
`getAnnotatedSignature(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature)`
Retrieve the annotated signature of a specified member as found in the given external annotation file, if any.
`static org.eclipse.core.resources.IFile`
`getAnnotationFile(IJavaProject project, ITypeBinding type, org.eclipse.core.runtime.IProgressMonitor monitor)`
Answer the external annotation file corresponding to the given type as seen from the given project.
`static String`
`insertParameterAnnotation(String methodSignature, int paramIdx, char annotation, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Insert an encoded annotation into the given methodSignature affecting one of its parameters.
`static String`
`insertReturnAnnotation(String methodSignature, char annotation, ExternalAnnotationUtil.MergeStrategy mergeStrategy)`
Insert an encoded annotation into the given methodSignature affecting its return type.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### NULLABLE

public static final char NULLABLE
Representation of a 'nullable' annotation, independent of the concrete annotation name used in Java sources.

See Also:
  - Constant Field Values

### NONNULL

public static final char NONNULL
Representation of a 'nonnull' annotation, independent of the concrete annotation name used in Java sources.

See Also:
  - Constant Field Values

### NO_ANNOTATION

public static final char NO_ANNOTATION
Represents absence of a null annotation. Useful for removing an existing null annotation. This character is used only internally, it is not part of the Eclipse External Annotation file format.

See Also:
  - Constant Field Values

## Constructor Details

### ExternalAnnotationUtil

public ExternalAnnotationUtil()

## Method Details

### extractGenericSignature

public static String extractGenericSignature(IMethodBinding methodBinding)
Answer the give method's signature in class file format.

Parameters:
  `methodBinding` - binding representing a method
Returns:
  a signature in class file format

### extractGenericTypeSignature

public static String extractGenericTypeSignature(ITypeBinding type)
Answer the given types's signature in class file format.

Parameters:
  `type` - binding representing a type
Returns:
  a signature in class file format

### extractGenericTypeParametersSignature

public static String extractGenericTypeParametersSignature(ITypeBinding type)
Answer the signature of all type parameters of this type in class file format.

Parameters:
  `type` - binding representing a type, required to have type parameters
Returns:
  a signature in class file format
Since:
  3.19

### insertReturnAnnotation

public static String insertReturnAnnotation(String methodSignature, char annotation, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Insert an encoded annotation into the given methodSignature affecting its return type.

This method is suitable for declaration annotations.

Parameters:
  `methodSignature` - a method signature in class file format
  `annotation` - one of `NULLABLE` and `NONNULL`.
  `mergeStrategy` - when passing `ExternalAnnotationUtil.MergeStrategy.ADD_ANNOTATIONS` this method will refuse to overwrite any existing annotation in the specified location
Returns:
  the modified method signature, or the original signature if modification would conflict with the given merge strategy.
Throws:
  `IllegalArgumentException` - if the method signature is malformed or its return type is not a reference type.

### insertParameterAnnotation

public static String insertParameterAnnotation(String methodSignature, int paramIdx, char annotation, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Insert an encoded annotation into the given methodSignature affecting one of its parameters.

This method is suitable for declaration annotations.

Parameters:
  `methodSignature` - a method signature in class file format
  `paramIdx` - 0-based index of the parameter to which the annotation should be attached
  `annotation` - one of `NULLABLE` and `NONNULL`.
  `mergeStrategy` - when passing `ExternalAnnotationUtil.MergeStrategy.ADD_ANNOTATIONS` this method will refuse to overwrite any existing annotation in the specified location
Returns:
  the modified method signature, or the original signature if modification would conflict with the given merge strategy.
Throws:
  `IllegalArgumentException` - if the method signature is malformed or its specified parameter type is not a reference type.

### getAnnotationFile

public static org.eclipse.core.resources.IFile getAnnotationFile(IJavaProject project, ITypeBinding type, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
Answer the external annotation file corresponding to the given type as seen from the given project. Note that manipulation of external annotations is only supported for annotation files in the workspace, and only in directory layout, not from zip files.

Parameters:
  `project` - current project that references the given type from a jar file.
  `type` - the type for which external annotations are sought
  `monitor` - progress monitor to be passed through into file operations
Returns:
  a file assumed (but not checked) to be in .eea format. The file may not "exist". Can be null if the given type is not contained in a jar file for which an external annotation path has been defined in the context of the given project.
Throws:
  `org.eclipse.core.runtime.CoreException` - Signals a problem in accessing any of the relevant elements: the project, the type, the containing jar file and finally the sought annotation file.

### annotateMember

public static void annotateMember(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedSignature, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException, IOException
Update the given external annotation file with details regarding annotations of one specific method or field. If the specified member already has external annotations, old and new annotations will be merged, with priorities controlled by the parameter 'mergeStrategy'.

This method is suitable for declaration annotations and type use annotations.

Parameters:
  `typeName` - binary name (slash separated) of the type being annotated
  `file` - a file assumed to be in .eea format, will be created if it doesn't exist.
  `selector` - selector of the method or field
  `originalSignature` - unannotated signature of the member, used for identification
  `annotatedSignature` - new signatures whose annotations should be superimposed on the member
  `mergeStrategy` - controls how old and new signatures should be merged
  `monitor` - progress monitor to be passed through into file operations, or null if no reporting is desired
Throws:
  `org.eclipse.core.runtime.CoreException` - if access to the file fails
  `IOException` - if reading file content fails

### annotateTypeTypeParameter

public static void annotateTypeTypeParameter(String typeName, org.eclipse.core.resources.IFile file, String originalSignature, String annotatedTypeParameter, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException, IOException, IllegalArgumentException
Update the given external annotation file with details regarding annotations of a type parameter of the type itself. If the type already has external annotations, old and new annotations will be merged, with priorities controlled by the parameter 'mergeStrategy'.

This method is suitable only for type use annotations.

Parameters:
  `typeName` - binary name (slash separated) of the type being annotated
  `file` - a file assumed to be in .eea format, will be created if it doesn't exist.
  `originalSignature` - unannotated signature of all type parameters of the type
  `annotatedTypeParameter` - signature of the new type parameter whose annotations should be superimposed on the method
  `rank` - rank of the type parameter to be annotated
  `mergeStrategy` - controls how old and new signatures should be merged
  `monitor` - progress monitor to be passed through into file operations, or null if no reporting is desired
Throws:
  `org.eclipse.core.runtime.CoreException` - if access to the file fails
  `IOException` - if reading file content fails
  `IllegalArgumentException` - if the annotatedTypeParameter does not structurally match to originalSignature
Since:
  3.19

### annotateMethodTypeParameter

public static void annotateMethodTypeParameter(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedTypeParameter, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException, IOException, IllegalArgumentException
Update the given external annotation file with details regarding annotations of a type parameter of a given method. If the specified method already has external annotations, old and new annotations will be merged, with priorities controlled by the parameter 'mergeStrategy'.

This method is suitable only for type use annotations.

Parameters:
  `typeName` - binary name (slash separated) of the type being annotated
  `file` - a file assumed to be in .eea format, will be created if it doesn't exist.
  `selector` - selector of the method
  `originalSignature` - unannotated signature of the member, used for identification
  `annotatedTypeParameter` - signature of the new type parameter whose annotations should be superimposed on the method
  `rank` - rank of the type parameter to be annotated
  `mergeStrategy` - controls how old and new signatures should be merged
  `monitor` - progress monitor to be passed through into file operations, or null if no reporting is desired
Throws:
  `org.eclipse.core.runtime.CoreException` - if access to the file fails
  `IOException` - if reading file content fails
  `IllegalArgumentException` - if the annotatedTypeParameter does not structurally match to originalSignature
Since:
  3.19

### annotateMethodReturnType

public static void annotateMethodReturnType(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedReturnType, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException, IOException, IllegalArgumentException
Update the given external annotation file with details regarding annotations of the return type of a given method. If the specified method already has external annotations, old and new annotations will be merged, with priorities controlled by the parameter 'mergeStrategy'.

This method is suitable for declaration annotations and type use annotations.

Parameters:
  `typeName` - binary name (slash separated) of the type being annotated
  `file` - a file assumed to be in .eea format, will be created if it doesn't exist.
  `selector` - selector of the method
  `originalSignature` - unannotated signature of the member, used for identification
  `annotatedReturnType` - signature of the new return type whose annotations should be superimposed on the method
  `mergeStrategy` - controls how old and new signatures should be merged
  `monitor` - progress monitor to be passed through into file operations, or null if no reporting is desired
Throws:
  `org.eclipse.core.runtime.CoreException` - if access to the file fails
  `IOException` - if reading file content fails
  `IllegalArgumentException` - if the annotatedReturnType does not structurally match to originalSignature

### annotateMethodParameterType

public static void annotateMethodParameterType(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature, String annotatedParameterType, int paramIdx, ExternalAnnotationUtil.MergeStrategy mergeStrategy, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException, IOException, IllegalArgumentException
Update the given external annotation file with details regarding annotations of a parameter type of a given method. If the specified method already has external annotations, old and new annotations will be merged, with priorities controlled by the parameter 'mergeStrategy'.

This method is suitable for declaration annotations and type use annotations.

Parameters:
  `typeName` - binary name (slash separated) of the type being annotated
  `file` - a file assumed to be in .eea format, will be created if it doesn't exist.
  `selector` - selector of the method
  `originalSignature` - unannotated signature of the member, used for identification
  `annotatedParameterType` - signature of the new parameter type whose annotations should be superimposed on the method
  `paramIdx` - 0-based index of the parameter to which the annotation should be attached
  `mergeStrategy` - controls how old and new signatures should be merged
  `monitor` - progress monitor to be passed through into file operations, or null if no reporting is desired
Throws:
  `org.eclipse.core.runtime.CoreException` - if access to the file fails
  `IOException` - if reading file content fails
  `IllegalArgumentException` - if the annotatedParameterType does not structurally match to originalSignature

### getAnnotatedSignature

public static String getAnnotatedSignature(String typeName, org.eclipse.core.resources.IFile file, String selector, String originalSignature)
Retrieve the annotated signature of a specified member as found in the given external annotation file, if any.

Parameters:
  `typeName` - fully qualified slash-separated name of the type for which the file defines external annotations
  `file` - a file assumed to be in .eea format, must not be null, but may not exist
  `selector` - name of the member whose annotation we are looking for, or null when annotating the type's type parameters
  `originalSignature` - the unannotated signature by which the member is identified
Returns:
  the annotated signature as found in the file, or null.

### annotateType

public static String[] annotateType(String originalSignature, String annotatedType, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Apply the specified changes on the given type. This method can be used as a dry run without modifying an annotation file.

Parameters:
  `originalSignature` - the original type signature, may be annotated already
  `annotatedType` - a type signature with additional annotations (incl. `NO_ANNOTATION`).
  `mergeStrategy` - controls how old and new signatures should be merged
Returns:
  an array of length four:
  - prefix up-to the changed type
  - original type
  - changed type
  - postfix after the changed type (here: empty string)

### annotateReturnType

public static String[] annotateReturnType(String originalSignature, String annotatedType, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Apply the specified changes on the return type of the given signature. This method can be used as a dry run without modifying an annotation file.

Parameters:
  `originalSignature` - the original full signature, may be annotated already
  `annotatedType` - a type signature with additional annotations (incl. `NO_ANNOTATION`).
  `mergeStrategy` - controls how old and new signatures should be merged
Returns:
  an array of length four:
  - prefix up-to the changed type
  - original type
  - changed type
  - postfix after the changed type (here: empty string)

### annotateParameterType

public static String[] annotateParameterType(String originalSignature, String annotatedType, int paramIdx, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Apply the specified changes on a parameter within the given signature. This method can be used as a dry run without modifying an annotation file.

Parameters:
  `originalSignature` - the original full signature, may be annotated already
  `annotatedType` - a type signature with additional annotations (incl. `NO_ANNOTATION`).
  `paramIdx` - the index of a parameter to annotate
  `mergeStrategy` - controls how old and new signatures should be merged
Returns:
  an array of length four:
  - prefix up-to the changed type
  - original type
  - changed type
  - postfix after the changed type

### annotateTypeParameter

public static String[] annotateTypeParameter(String originalSignature, String annotatedType, int rank, ExternalAnnotationUtil.MergeStrategy mergeStrategy)
Apply the specified changes on a type parameter within the given signature. This method can be used as a dry run without modifying an annotation file.

Parameters:
  `originalSignature` - the original full signature, may be annotated already
  `annotatedType` - a type signature with additional annotations (incl. `NO_ANNOTATION`).
  `rank` - the index of a type parameter to annotate
  `mergeStrategy` - controls how old and new signatures should be merged
Returns:
  an array of length four:
  - prefix up-to the changed type
  - original type
  - changed type
  - postfix after the changed type
Since:
  3.19