Package org.eclipse.jdt.core.compiler

# Class CompilationParticipant

java.lang.Object
org.eclipse.jdt.core.compiler.CompilationParticipant

public abstract class CompilationParticipant extends Object
A compilation participant is notified of events occurring during the compilation process. The compilation process not only involves generating .class files (i.e. building), it also involves cleaning the output directory, reconciling a working copy, etc. So the notified events are the result of a build action, a clean action, a reconcile operation (for a working copy), etc.

Code that participates in the build should in general be implemented with a separate Builder, rather than a CompilationParticipant. It is only necessary to use a CompilationParticipant if the build step needs to interact with the Java build, for instance by creating additional Java source files that must themselves in turn be compiled.

Clients wishing to participate in the compilation process must subclass this class, and implement `isActive(IJavaProject)`, `aboutToBuild(IJavaProject)`, `reconcile(ReconcileContext)`, etc.

If the "requires" attribute is not used for participant definition, there will be no specific order in which potential multiple compilation participants are called. If they have to be called in a specific order, the attribute "requires" can be set on the extension point entries.

This class is intended to be subclassed by clients.

Since:
  3.2

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`NEEDS_FULL_BUILD`
`static final int`
`READY_FOR_BUILD`

## Constructor Summary

Constructors
Constructor
Description
`CompilationParticipant()`

## Method Summary

Modifier and Type
Method
Description
`int`
`aboutToBuild(IJavaProject project)`
Notifies this participant that a build is about to start and provides it the opportunity to create missing source folders for generated source files.
`void`
`buildFinished(IJavaProject project)`
Notifies this participant that a build has finished for the project.
`void`
`buildStarting(BuildContext[] files, boolean isBatch)`
Notifies this participant that a compile operation is about to start and provides it the opportunity to generate source files based on the source files about to be compiled.
`void`
`cleanStarting(IJavaProject project)`
Notifies this participant that a clean is about to start and provides it the opportunity to delete generated source files.
`URI[]`
`getAnnotationProcessorPaths(IJavaProject project, boolean isTest)`
Requests the participant to supply the locations where to find annotation processors.
`org.eclipse.core.resources.IContainer[]`
`getGeneratedSourcePaths(IJavaProject project, boolean isTest)`
Requests the participant to supply the locations to place the generated source files.
`boolean`
`isActive(IJavaProject project)`
Returns whether this participant is active for a given project.
`boolean`
`isAnnotationProcessor()`
Returns whether this participant is interested in Annotations.
`boolean`
`isPostProcessor()`
Returns whether this participant is interested in post processing of generated bytecode.
`Optional<byte[]>`
`postProcess(BuildContext file, ByteArrayInputStream bytes)`
Notifies this participant about a finished class compilation.
`void`
`processAnnotations(BuildContext[] files)`
Notifies this participant that a compile operation has found source files using Annotations.
`void`
`reconcile(ReconcileContext context)`
Notifies this participant that a reconcile operation is happening.

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

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

## Field Details

### READY_FOR_BUILD

public static final int READY_FOR_BUILD

See Also:
  - Constant Field Values

### NEEDS_FULL_BUILD

public static final int NEEDS_FULL_BUILD

See Also:
  - Constant Field Values

## Constructor Details

### CompilationParticipant

public CompilationParticipant()

## Method Details

### aboutToBuild

public int aboutToBuild(IJavaProject project)
Notifies this participant that a build is about to start and provides it the opportunity to create missing source folders for generated source files. Additional source folders should be marked as optional so the project can be built when the folders do not exist. Only sent to participants interested in the project.

Default is to return `READY_FOR_BUILD`.

Parameters:
  `project` - the project about to build
Returns:
  READY_FOR_BUILD or NEEDS_FULL_BUILD
See Also:
  - `buildFinished(IJavaProject project)`

### buildFinished

public void buildFinished(IJavaProject project)
Notifies this participant that a build has finished for the project. This will be sent, even if buildStarting() was not sent when no source files needed to be compiled or the build failed. Only sent to participants interested in the project.

Parameters:
  `project` - the project about to build
Since:
  3.4

### buildStarting

public void buildStarting(BuildContext[] files, boolean isBatch)
Notifies this participant that a compile operation is about to start and provides it the opportunity to generate source files based on the source files about to be compiled. When isBatchBuild is true, then files contains all source files in the project. Only sent to participants interested in the current build project.

Parameters:
  `files` - is an array of BuildContext
  `isBatch` - identifies when the build is a batch build

### cleanStarting

public void cleanStarting(IJavaProject project)
Notifies this participant that a clean is about to start and provides it the opportunity to delete generated source files. Only sent to participants interested in the project.

Parameters:
  `project` - the project about to be cleaned

### isActive

public boolean isActive(IJavaProject project)
Returns whether this participant is active for a given project.

Default is to return `false`.

For efficiency, participants that are not interested in the given project should return `false` for that project.

Note: In `special cases`, the project may be closed and not exist. Participants typically return false when the underlying project is closed. I.e. when the following check returns false:

            javaProject.getProject().isOpen();

Parameters:
  `project` - the project to participate in
Returns:
  whether this participant is active for a given project

### isAnnotationProcessor

public boolean isAnnotationProcessor()
Returns whether this participant is interested in Annotations.

Returning `true` enables the callback `processAnnotations(BuildContext[])`, where this participant can influence build results.

Default is to return `false`.

Returns:
  whether this participant is interested in Annotations

### processAnnotations

public void processAnnotations(BuildContext[] files)
Notifies this participant that a compile operation has found source files using Annotations. Only sent to participants interested in the current build project that answer true to `isAnnotationProcessor()`. Each BuildContext was informed whether its source file currently hasAnnotations().

Parameters:
  `files` - is an array of BuildContext

### getAnnotationProcessorPaths

public URI[] getAnnotationProcessorPaths(IJavaProject project, boolean isTest)
Requests the participant to supply the locations where to find annotation processors. If this is not specified, then the class path is searched for processors.

Parameters:
  `project` - the project to participate in
  `isTest` - whether the annotation processor path is for test code
Returns:
  the annotation processor paths
Since:
  3.38
Restriction:
  Provisional API for experimental support for an alternative compiler. This method is not intended to be referenced by clients.

### getGeneratedSourcePaths

public org.eclipse.core.resources.IContainer[] getGeneratedSourcePaths(IJavaProject project, boolean isTest)
Requests the participant to supply the locations to place the generated source files.

Parameters:
  `project` - the project to participate in
  `isTest` - whether the generated source paths are for test code
Returns:
  the locations to place the generated source files
Since:
  3.38
Restriction:
  Provisional API for experimental support for an alternative compiler. This method is not intended to be referenced by clients.

### isPostProcessor

public boolean isPostProcessor()
Returns whether this participant is interested in post processing of generated bytecode.

Returning `true` enables the callback `postProcess(BuildContext,ByteArrayInputStream)`, where this participant can influence produced class file bytes.

Default is to return `false`.

Returns:
  whether this participant is interested in post processing
Since:
  3.34

### postProcess

public Optional<byte[]> postProcess(BuildContext file, ByteArrayInputStream bytes)
Notifies this participant about a finished class compilation. This notification occurs right before the compiled class is written out to disk. This allows to perform arbitrary byte code manipulation on the generated class.

Only sent to participants that answer true to `isPostProcessor()`.

- If additional dependencies to other classes are introduced by the modified class, these dependencies have to be recorded by calling `BuildContext.recordDependencies(String[])`.
- In case problems occur, they can be reported using `BuildContext.recordNewProblems(CategorizedProblem[])`.
- No other API's to record build state changes are supported during post-processing.

Note: the received class data could have already been transformed by another compilation participant. If the compilation participants have to be called in a specific order, the attribute "requires" can be used in the participant contribution entry.

Parameters:
  `file` - context of the generated class
  `bytes` - byte representation of the generated class
Returns:
  Optional containing byte array representing the modified class or empty Optional if no modification was applied. Default implementation returns empty Optional.
Since:
  3.34

### reconcile

public void reconcile(ReconcileContext context)
Notifies this participant that a reconcile operation is happening. The participant can act on this reconcile operation by using the given context. Other participant can then see the result of this participation on this context.

Note that a participant should not modify the buffer of the working copy that is being reconciled.

Default is to do nothing.

Parameters:
  `context` - the reconcile context to act on