org.openide.compiler
Class Compiler

java.lang.Object
  |
  +--org.openide.compiler.Compiler

All Implemented Interfaces:

Compilable

Direct Known Subclasses:

ExternalCompiler

public abstract class Compiler

extends Object

implements Compilable

Implementable object representing one task of compilation.

A module's implementation should typically be instantiated within an implementation of CompilerCookie.addToJob(org.openide.compiler.CompilerJob, org.openide.compiler.Compiler.Depth), or (preferably) CompilerType.prepareJob(org.openide.compiler.CompilerJob, java.lang.Class, org.openide.loaders.DataObject). It need not do much beyond keep track of the particular file (data object, ...) it is associated with and make sure the associated CompilerGroup implementation knows about it (via CompilerGroup.add(org.openide.compiler.Compiler)).

Important: Each compiler should implement equals (Object) and hashCode () methods to work correctly. That means to check whether the file (data object, ...) that should be compiled is the same or not. Two Compilers should be equal even if they have different set of dependencies, they do not matter. hashCode () must be consistent with equals (Object).

Inner Class Summary

static class

Compiler.Depth Depth of compilation.

Field Summary

static Compiler.Depth	DEPTH_INFINITE Infinite level of compilation--compile all folders recursively.
static Compiler.Depth	DEPTH_ONE Penultimate level of compilation--folder should compile just directly contained files, but not recursively.
static Compiler.Depth	DEPTH_ZERO Zero level of compilation--leaves should compile themself, but folders should do nothing.

Fields inherited from interface org.openide.compiler.Compilable

MUTEX

Constructor Summary

Compiler()
Default constructor.

Compiler(Compiler c)
Deprecated. use new Compiler ().dependsOn (c);

Compiler(Compiler[] dep)
Deprecated. use new Compiler ().dependsOn (Arrays.asList (dep));

Compiler(CompilerJob job)
Deprecated. use job.add (new Compiler ());

Method Summary

abstract Class	compilerGroupClass() Get the associated CompilerGroup container class.
Object	compilerGroupKey() Specify a unique key permitting division of a set of compilers into different compiler groups.
Collection	compilers() Returns itself.
Collection	dependsOn() A collection of other Compilable objects that have to be finished before the compilers of this Compilable can be started.
void	dependsOn(Collection compilables) Add dependency on a compilable object.
void	dependsOn(Compilable compilable) Add dependency on a compilable object.
protected abstract boolean	isUpToDate() Check whether the compiler is up to date.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.openide.compiler.Compilable

equals

Field Detail

DEPTH_ZERO

public static final Compiler.Depth DEPTH_ZERO

Zero level of compilation--leaves should compile themself, but folders should do nothing.

DEPTH_ONE

public static final Compiler.Depth DEPTH_ONE

Penultimate level of compilation--folder should compile just directly contained files, but not recursively.

DEPTH_INFINITE

public static final Compiler.Depth DEPTH_INFINITE

Infinite level of compilation--compile all folders recursively.

Constructor Detail

Compiler

public Compiler()

Default constructor.

Compiler

public Compiler(CompilerJob job)

Deprecated. use job.add (new Compiler ());

Create a new compiler belonging to a specified compiler job. This is the most commonly used constructor.

Parameters:

job - the job the compiler belongs to

Compiler

public Compiler(Compiler c)

Deprecated. use new Compiler ().dependsOn (c);

Create a new compiler that depends on another. The new compiler is put into the same job as the other compiler.

Parameters:

c - the compiler to depend on

Compiler

public Compiler(Compiler[] dep)

Deprecated. use new Compiler ().dependsOn (Arrays.asList (dep));

Create a new compiler that depends on several others. Placed in the same job as the others.

Parameters:

dep - compilers to depend on

Method Detail

isUpToDate

protected abstract boolean isUpToDate()

Check whether the compiler is up to date. This method is called from CompilerJob.isUpToDate() to skip a compilation when it is unnecessary.

Returns:

true if up-to-date; false if compilation is needed

compilerGroupClass

public abstract Class compilerGroupClass()

Get the associated CompilerGroup container class. The compiler and compiler group should typically be implemented in parallel, though it is possible to subclass a compiler without subclassing the compiler group. The compiler group must be "expecting" a compiler of this class (or a superclass), or else it is free to fail in an unspecified way. All instances of the same compiler class must return the same result from this method.

Returns:

a class assignable to CompilerGroup

compilerGroupKey

public Object compilerGroupKey()

Specify a unique key permitting division of a set of compilers into different compiler groups. The compilation engine, in CompilationEngine.createCompilerGroups(java.util.Collection), will always separate compilers within a given job into levels based on their stated dependencies; however, it will also split compilers into different groups within each level, based on this key. All compilers with the same key which can fit into the same level will be placed into a single group. No group will contain compilers with different values of the key.

This key should only be used for grouping; it is not available to the compiler group, as its content may be idiosyncratic. (Compiler groups requiring specific pieces of information from the compilers added to them must extract this information according to accessible methods or fields of the compilers, as they are added.) The key must obey the general Java language contract for object comparison, according to Object.equals(java.lang.Object) and Object.hashCode().

By default, only the compilerGroupClass() is used. It is required that each compiler class, if it needs to override this method, first call the super method and add distinctions to this result. I.e. a subclass may never produce a key less discriminating than the superclass. The suggested implementation is to call the super method, and then return a List containing both the super's result, as well as any information added by this subclass.

Additionally, in the unusual but possible case that a compiler is subclassing another compiler, while still using the same compiler group class as its superclass, the subclass compiler must include in the key (e.g. an additional vector element) the class object for the subclass (determined via a static class constant, not Object.getClass()!)--this will ensure that keys from unrelated subclasses of the same compiler superclass will not randomly conflict.

Returns:

the grouping key object for this compiler

dependsOn

public final void dependsOn(Compilable compilable)

Add dependency on a compilable object. That means that this compiler can be started only after all compilable objects has been finished.

Parameters:

compilable - any compilable object (Compiler, CompilerJob, etc.)

dependsOn

public void dependsOn(Collection compilables)

Add dependency on a compilable object. That means that this compiler can be started only after all compilable objects has been finished.

Parameters:

compilables - collection of Compilable

compilers

public final Collection compilers()

Returns itself.

Specified by:

compilers in interface Compilable

Returns:

java.util.Collections.singleton (this);

dependsOn

public final Collection dependsOn()

A collection of other Compilable objects that have to be finished before the compilers of this Compilable can be started.

Specified by:

dependsOn in interface Compilable

Returns:

collection of Compilable