org.netbeans.api.java.source

Class JavaSource

java.lang.Object

org.netbeans.api.java.source.JavaSource

public final class JavaSource
extends Object

Class representing Java source file opened in the editor.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JavaSource.InsufficientMemoryException This specialization of IOException signals that a JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean) or JavaSource.runModificationTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.WorkingCopy>) failed due to lack of memory.
static class	JavaSource.Phase
static class	JavaSource.Priority

Method Summary

Modifier and Type	Method and Description
static JavaSource	create(ClasspathInfo cpInfo, Collection<? extends FileObject> files) Returns a JavaSource instance representing given FileObjects and classpath represented by given ClasspathInfo.
static JavaSource	create(ClasspathInfo cpInfo, FileObject... files) Returns a JavaSource instance representing given FileObjects and classpath represented by given ClasspathInfo.
static JavaSource	forDocument(Document doc) Returns a JavaSource instance associated to the given Document, it returns null if the Document is not associated with data type providing the JavaSource.
static JavaSource	forFileObject(FileObject fileObject) Returns a JavaSource instance associated to given FileObject, it returns null if the Document is not associated with data type providing the JavaSource.
ClasspathInfo	getClasspathInfo() Returns the classpaths (ClasspathInfo) used by this JavaSource
Collection<FileObject>	getFileObjects() Returns unmodifiable Collection of FileObjects used by this JavaSource
ModificationResult	runModificationTask(Task<WorkingCopy> task) Runs a task which permits for modifying the sources.
void	runUserActionTask(Task<CompilationController> task, boolean shared) Runs a task which permits for controlling phases of the parsing process.
Future<Void>	runWhenScanFinished(Task<CompilationController> task, boolean shared) Performs the given task when the scan finished.

Methods inherited from class java.lang.Object

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

Method Detail

create

@NullUnknown
public static JavaSource create(@NonNull
                                             ClasspathInfo cpInfo,
                                             @NonNull
                                             FileObject... files)
                                      throws IllegalArgumentException

Returns a JavaSource instance representing given FileObjects and classpath represented by given ClasspathInfo.

Parameters:

cpInfo - the classpaths to be used.

files - for which the JavaSource should be created

Returns:

a new JavaSource

Throws:

IllegalArgumentException - if fileObject or cpInfo is null

create

@NullUnknown
public static JavaSource create(@NonNull
                                             ClasspathInfo cpInfo,
                                             @NonNull
                                             Collection<? extends FileObject> files)
                                      throws IllegalArgumentException

Returns a JavaSource instance representing given FileObjects and classpath represented by given ClasspathInfo.

Parameters:

cpInfo - the classpaths to be used.

files - for which the JavaSource should be created

Returns:

a new JavaSource or null if the essential infrastructure is missing

Throws:

IllegalArgumentException - if fileObject or cpInfo is null

forFileObject

@CheckForNull
public static JavaSource forFileObject(@NonNull
                                                     FileObject fileObject)
                                              throws IllegalArgumentException

Returns a JavaSource instance associated to given FileObject, it returns null if the Document is not associated with data type providing the JavaSource.

Parameters:

fileObject - for which the JavaSource should be found/created.

Returns:

JavaSource or null

Throws:

IllegalArgumentException - if fileObject is null

forDocument

@CheckForNull
public static JavaSource forDocument(@NonNull
                                                   Document doc)
                                            throws IllegalArgumentException

Returns a JavaSource instance associated to the given Document, it returns null if the Document is not associated with data type providing the JavaSource.

Parameters:

doc - Document for which the JavaSource should be found/created.

Returns:

JavaSource or null

Throws:

IllegalArgumentException - if doc is null

runUserActionTask

public void runUserActionTask(@NonNull
                              Task<CompilationController> task,
                              boolean shared)
                       throws IOException

Runs a task which permits for controlling phases of the parsing process. You probably do not want to call this method unless you are reacting to some user's GUI input which requires immediate action (e.g. code completion popup). In all other cases use JavaSourceTaskFactory.
Call to this method will cancel processing of all the phase completion tasks until this task does not finish.

Parameters:

task - The task which.

shared - if true the java compiler may be reused by other org.netbeans.api.java.source.CancellableTasks, the value false may have negative impact on the IDE performance.

It's legal to nest the JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean) into another JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean). It's also legal to nest the JavaSource.runModificationTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.WorkingCopy>) into JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean), the outer JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean) does not see changes caused by nested JavaSource.runModificationTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.WorkingCopy>), but the following nested task see them.

Throws:

IOException

See Also:

for information about implementation requirements

runWhenScanFinished

@NonNull
public Future<Void> runWhenScanFinished(@NonNull
                                                 Task<CompilationController> task,
                                                 boolean shared)
                                          throws IOException

Performs the given task when the scan finished. When no background scan is running it performs the given task synchronously. When the background scan is active it queues the given task and returns, the task is performed when the background scan completes by the thread doing the background scan.

Parameters:

task - to be performed

shared - if true the java compiler may be reused by other org.netbeans.api.java.source.CancellableTasks, the value false may have negative impact on the IDE performance.

Returns:

Future which can be used to find out the sate of the task Future.isDone() or Future.isCancelled(). The caller may cancel the task using Future.cancel(boolean) or wait until the task is performed Future.get().

Throws:

IOException - encapsulating the exception thrown by CancellableTasks#run

Since:

0.12

runModificationTask

@NonNull
public ModificationResult runModificationTask(@NonNull
                                                       Task<WorkingCopy> task)
                                                throws IOException

Runs a task which permits for modifying the sources. Call to this method will cancel processing of all the phase completion tasks until this task does not finish.

Parameters:

task - The task which.

Throws:

IOException

See Also:

for information about implementation requirements

getClasspathInfo

@NonNull
public ClasspathInfo getClasspathInfo()

Returns the classpaths (ClasspathInfo) used by this JavaSource

Returns:

ClasspathInfo, never returns null.

getFileObjects

@NonNull
public Collection<FileObject> getFileObjects()

Returns unmodifiable Collection of FileObjects used by this JavaSource

Returns:

the FileObjects