Introduction

This document lists changes made to the Java Source API.

Index of APIs

Java Source API

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

(Nov 12 '10) DisjointTypeTree renamed to DisjunctiveTypeTree, AnnotationTypeTree has been removed
(Aug 6 '09) Removing the binary compatibility methods (using bytecode patching) from JavaSource
(Jun 15 '07) Removal of obsolete, duplicated and deprecated methods from java/source
(Jun 13 '07) ClassIndex methods are cancellable

All changes by date

(Apr 26 '11) TreePathHandle can be created from ElementHandle
(Jan 21 '11) JavaSource.runModificationTask can run on source-less JavaSources
(Dec 10 '10) Added a method for checking the existence of the main method using index only
(Nov 12 '10) DisjointTypeTree renamed to DisjunctiveTypeTree, AnnotationTypeTree has been removed
(Oct 12 '10) Added several methods to support new API for modeling JDK7 features.
(Sep 27 '10) Added TreeMaker.CompilationUnit(List<AnnotationTree>, ...), TreeMaker.addPackageAnnotation, TreeMaker.insertPackageAnnotation, TreeMaker.removePackageAnnotation methods.
(Sep 16 '10) Added TreeMaker.QualIdent(String) and TreeMaker.Type(String) method.
(Sep 8 '10) Added TreeUtilities.translate method.
(Jul 13 '10) Added TypeUtilities.getTypeName method.
(Mar 2 '10) Added SourceUtils.getAttributeValueCompletions method.
(Feb 24 '10) Added support for encoding/decoding exotic identifiers to TreeUtilities.
(Oct 27 '09) Added GeneratorUtilities.copyComments method.
(Aug 14 '09) Added TreeUtilities.isEnumConstant() method.
(Aug 12 '09) Added CompilationInfo.getSourceVersion() method.
(Aug 6 '09) Removing the binary compatibility methods (using bytecode patching) from JavaSource
(May 7 '09) Added new Method allowing creating varargs methods.
(Mar 31 '09) Changed Comment API
(Nov 24 '08) Migrated to the parsing.api
(Aug 13 '08) Better ways of getting CodeStyle instance
(Jul 7 '08) Added BuildArtifactMapper
(Jun 25 '08) Added ModificationResult.getSpan and WorkingCopy.tag
(May 6 '08) Added TypeUtilities.substitute
(Mar 25 '08) Added GeneratorUtilities.createMethod
(Mar 15 '08) Added ModificationResult.Difference.setCommitToGuards(boolean) and isCommitToGuards() methods permitting to write modifications even to guarded sections
(Jan 25 '08) Added CompilationInfo.getChangedTree method returning the reparsed subtree
(Dec 21 '07) Added CancellableTreePathScanner(AtomicBoolean) and CancellableTreeScanner(AtomicBoolean)
(Dec 14 '07) Added a method to obtain ElementHandles from TypeMirrorHandles representing DeclaredTypes
(Nov 26 '07) Added ClassIndex.NameKind.CAMEL_CASE_INSENSITIVE
(Jun 15 '07) Support for JSPs and dialogs
(Jun 15 '07) Adding GeneratorUtilities
(Jun 15 '07) Removal of obsolete, duplicated and deprecated methods from java/source
(Jun 15 '07) CancellableTask split into Task and CancellableTask.
(Jun 13 '07) ClassIndex methods are cancellable
(Jun 5 '07) Added a method to obtain top level elements defined in the source/class file.
(Apr 24 '07) Added factory method which returns a new TreePathHandle for given Element and CompilationInfo.
(Apr 19 '07) Added a method to run a CancellableTask when the backgound scan is finished.
(Apr 13 '07) Added a method which returns all the project source roots depending on a given source root.
(Apr 4 '07) Added a listener for listening on changes in the ClassIndex.
(Mar 26 '07) Adding template attribute package
(Mar 18 '07) Removing CommentUtilities, adjusting TreeMaker and introducing TypeUtilities

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.java.source > 1.20

(0.79) TreePathHandle can be created from ElementHandle
(0.74) JavaSource.runModificationTask can run on source-less JavaSources
(0.71) Added a method for checking the existence of the main method using index only
(0.70) DisjointTypeTree renamed to DisjunctiveTypeTree, AnnotationTypeTree has been removed
(0.67) Added several methods to support new API for modeling JDK7 features.
(0.66) Added TreeMaker.CompilationUnit(List<AnnotationTree>, ...), TreeMaker.addPackageAnnotation, TreeMaker.insertPackageAnnotation, TreeMaker.removePackageAnnotation methods.
(0.65) Added TreeMaker.QualIdent(String) and TreeMaker.Type(String) method.
(0.64) Added TreeUtilities.translate method.
(0.62) Added TypeUtilities.getTypeName method.
(0.57) Added SourceUtils.getAttributeValueCompletions method.
(0.56) Added support for encoding/decoding exotic identifiers to TreeUtilities.
(0.51) Added GeneratorUtilities.copyComments method.
(0.48) Added TreeUtilities.isEnumConstant() method.
(0.47) Added CompilationInfo.getSourceVersion() method.
(0.46) Removing the binary compatibility methods (using bytecode patching) from JavaSource
(0.44) Added new Method allowing creating varargs methods.
(0.43) Changed Comment API
(0.42) Migrated to the parsing.api
(0.39) Better ways of getting CodeStyle instance
(0.38) Added BuildArtifactMapper
(0.37) Added ModificationResult.getSpan and WorkingCopy.tag
(0.36) Added TypeUtilities.substitute
(0.34) Added GeneratorUtilities.createMethod
(0.33) Added ModificationResult.Difference.setCommitToGuards(boolean) and isCommitToGuards() methods permitting to write modifications even to guarded sections
(0.31) Added CompilationInfo.getChangedTree method returning the reparsed subtree
(0.30) Added CancellableTreePathScanner(AtomicBoolean) and CancellableTreeScanner(AtomicBoolean)
(0.29) Added a method to obtain ElementHandles from TypeMirrorHandles representing DeclaredTypes
(0.28) Added ClassIndex.NameKind.CAMEL_CASE_INSENSITIVE
(0.21) Support for JSPs and dialogs
(0.20) Adding GeneratorUtilities
(0.19) Removal of obsolete, duplicated and deprecated methods from java/source
(0.18) CancellableTask split into Task and CancellableTask.
(0.16) ClassIndex methods are cancellable
(0.14) Added a method to obtain top level elements defined in the source/class file.
(0.13) Added factory method which returns a new TreePathHandle for given Element and CompilationInfo.
(0.12) Added a method to run a CancellableTask when the backgound scan is finished.
(0.10) Added a method which returns all the project source roots depending on a given source root.
(0.8) Added a listener for listening on changes in the ClassIndex.
(0.7) Adding template attribute package
(0.6) Removing CommentUtilities, adjusting TreeMaker and introducing TypeUtilities

Changes by affected class

`org.netbeans.api.java.source.BuildArtifactMapper`

(Jul 7 '08) Added BuildArtifactMapper

`org.netbeans.api.java.source.ClasspathInfo`

(Nov 24 '08) Migrated to the parsing.api

`org.netbeans.api.java.source.CodeStyle`

(Aug 13 '08) Better ways of getting CodeStyle instance

`org.netbeans.api.java.source.Comment`

(Mar 31 '09) Changed Comment API

`org.netbeans.api.java.source.CompilationController`

(Nov 24 '08) Migrated to the parsing.api

`org.netbeans.api.java.source.CompilationInfo`

(Aug 12 '09) Added CompilationInfo.getSourceVersion() method.
(Nov 24 '08) Migrated to the parsing.api

`org.netbeans.api.java.source.GeneratorUtilities`

(Oct 27 '09) Added GeneratorUtilities.copyComments method.

`org.netbeans.api.java.source.JavaParserResultTask`

(Nov 24 '08) Migrated to the parsing.api

`org.netbeans.api.java.source.JavaSource`

(Jan 21 '11) JavaSource.runModificationTask can run on source-less JavaSources
(Aug 6 '09) Removing the binary compatibility methods (using bytecode patching) from JavaSource

`org.netbeans.api.java.source.ModificationResult`

(Nov 24 '08) Migrated to the parsing.api

`org.netbeans.api.java.source.SourceUtils`

(Dec 10 '10) Added a method for checking the existence of the main method using index only
(Mar 2 '10) Added SourceUtils.getAttributeValueCompletions method.

`org.netbeans.api.java.source.TreeMaker`

(Nov 12 '10) DisjointTypeTree renamed to DisjunctiveTypeTree, AnnotationTypeTree has been removed
(Sep 27 '10) Added TreeMaker.CompilationUnit(List<AnnotationTree>, ...), TreeMaker.addPackageAnnotation, TreeMaker.insertPackageAnnotation, TreeMaker.removePackageAnnotation methods.
(Sep 16 '10) Added TreeMaker.QualIdent(String) and TreeMaker.Type(String) method.
(May 7 '09) Added new Method allowing creating varargs methods.

`org.netbeans.api.java.source.TreePathHandle`

(Apr 26 '11) TreePathHandle can be created from ElementHandle

`org.netbeans.api.java.source.TreeUtilities`

(Sep 8 '10) Added TreeUtilities.translate method.
(Feb 24 '10) Added support for encoding/decoding exotic identifiers to TreeUtilities.
(Aug 14 '09) Added TreeUtilities.isEnumConstant() method.

`org.netbeans.api.java.source.TypeUtilities`

(Jul 13 '10) Added TypeUtilities.getTypeName method.
(May 6 '08) Added TypeUtilities.substitute
(Mar 18 '07) Removing CommentUtilities, adjusting TreeMaker and introducing TypeUtilities

`org.netbeans.api.java.source.WorkingCopy`

(Nov 24 '08) Migrated to the parsing.api

Details of all changes by API and date

Java Source API

TreePathHandle can be created from ElementHandle

Apr 26 '11; API spec. version: 0.79; affected top-level classes: TreePathHandle; made by: jlahoda; issues: #197848
TreePathHandle has a new from(ElementHandle) method.

JavaSource.runModificationTask can run on source-less JavaSources

Jan 21 '11; API spec. version: 0.74; affected top-level classes: JavaSource; made by: jlahoda; issues: #119887
JavaSource.runModificationTask method works on source-less JavaSources.

Added a method for checking the existence of the main method using index only

Dec 10 '10; API spec. version: 0.71; affected top-level classes: SourceUtils; made by: tzezula; issues: #191648
Added a new version of the isMain method into org.netbeans.api.java.source.SourceUtils which allows check based only on index information.

DisjointTypeTree renamed to DisjunctiveTypeTree, AnnotationTypeTree has been removed

Nov 12 '10; API spec. version: 0.70; affected top-level classes: TreeMaker; made by: jlahoda
com.sun.source.tree.DisjointTypeTree renamed to com.sun.source.tree.DisjunctiveTypeTree from javac, so adjusting TreeMaker to it. com.sun.source.tree.AnnotationTypeTree has been removed from javac and is no longer available.

Added several methods to support new API for modeling JDK7 features.

Oct 12 '10; API spec. version: 0.67; made by: jlahoda; issues: #190767
Added CodeStyle.alignMultilineTryResources, CodeStyle.spaceBeforeTryParen, CodeStyle.spaceWithinTryParens, CodeStyle.wrapTryResources TreeMaker.DisjointType, CodeStyle.Try and TreeUtilities.CLASS_TREE_KINDS to support new language features in JDK7.

Added TreeMaker.CompilationUnit(List<AnnotationTree>, ...), TreeMaker.addPackageAnnotation, TreeMaker.insertPackageAnnotation, TreeMaker.removePackageAnnotation methods.

Sep 27 '10; API spec. version: 0.66; affected top-level classes: TreeMaker; made by: jlahoda; issues: #157760
Added TreeMaker.CompilationUnit(List<AnnotationTree>, ...), TreeMaker.addPackageAnnotation, TreeMaker.insertPackageAnnotation, TreeMaker.removePackageAnnotation to allow modification of the list of package annotations.

Added TreeMaker.QualIdent(String) and TreeMaker.Type(String) method.

Sep 16 '10; API spec. version: 0.65; affected top-level classes: TreeMaker; made by: jlahoda; issues: #190123
Added TreeMaker.QualIdent(String) and TreeMaker.Type(String) method, which allow to construct QualIdents and Types from String specification.

Added TreeUtilities.translate method.

Sep 8 '10; API spec. version: 0.64; affected top-level classes: TreeUtilities; made by: jlahoda; issues: #190019
Added TreeUtilities.translate method, which allows to construct new tree based on a given set of changes.

Added TypeUtilities.getTypeName method.

Jul 13 '10; API spec. version: 0.62; affected top-level classes: TypeUtilities; made by: jlahoda; issues: #104194
Added TypeUtilities.getTypeName method, which allows to print type to string.

Added SourceUtils.getAttributeValueCompletions method.

Mar 2 '10; API spec. version: 0.57; affected top-level classes: SourceUtils; made by: dbalek; issues: #111292
Added SourceUtils.getAttributeValueCompletions method, which returns a list of completions for an annotation attribute value suggested by annotation processors.

Added support for encoding/decoding exotic identifiers to TreeUtilities.

Feb 24 '10; API spec. version: 0.56; affected top-level classes: TreeUtilities; made by: jlahoda; issues: #180842
Added support for encoding/decoding exotic identifiers to TreeUtilities.

Added GeneratorUtilities.copyComments method.

Oct 27 '09; API spec. version: 0.51; affected top-level classes: GeneratorUtilities; made by: jlahoda; issues: #175020
Added GeneratorUtilities.copyComments method, which copies comments from one tree to another tree.

Added TreeUtilities.isEnumConstant() method.

Aug 14 '09; API spec. version: 0.48; affected top-level classes: TreeUtilities; made by: msauer; issues: #170373
Added TreeUtilities.isEnumConstant() method, which determines whether tree represents an enum constant.

Added CompilationInfo.getSourceVersion() method.

Aug 12 '09; API spec. version: 0.47; affected top-level classes: CompilationInfo; made by: dbalek; issues: #169970
Added CompilationInfo.getSourceVersion() to return the SourceVersion used by the javac compiler.

Removing the binary compatibility methods (using bytecode patching) from JavaSource

Aug 6 '09; API spec. version: 0.46; affected top-level classes: JavaSource; made by: tzezula; issues: #169974
The JavaSource class contains methods introduced to keep binary compatibility among milestones of NB 6.0. These methods are not needed anymore and will be removed.

Added new Method allowing creating varargs methods.

May 7 '09; API spec. version: 0.44; affected top-level classes: TreeMaker; made by: moonko
Adding TreeMake.Method(..., boolean isVarArg) to allow creation of methods with variable lenght of arguments.

Changed Comment API

Mar 31 '09; API spec. version: 0.43; affected top-level classes: Comment; made by: moonko
Adding Comment.create(Comment.Style, String) to create new comment of any style from string.

Migrated to the parsing.api

Nov 24 '08; API spec. version: 0.42; affected top-level classes: JavaParserResultTask ClasspathInfo CompilationInfo CompilationController ModificationResult WorkingCopy; made by: tzezula
The java source module migrated to use the common parsing api.

Better ways of getting CodeStyle instance

Aug 13 '08; API spec. version: 0.39; affected top-level classes: CodeStyle; made by: vstejskal
Added CodeStyle.getDefault(FileObject), CodeStyle.getDefault(Document). Deprecated CodeStyle.getDefault(Project).

Added BuildArtifactMapper

Jul 7 '08; API spec. version: 0.38; affected top-level classes: BuildArtifactMapper; made by: jlahoda
Added BuildArtifactMapper.

Added ModificationResult.getSpan and WorkingCopy.tag

Jun 25 '08; API spec. version: 0.37; made by: msauer
Added Methods allowing tagging of trees and getting their span inside modified document.

Added TypeUtilities.substitute

May 6 '08; API spec. version: 0.36; affected top-level classes: TypeUtilities; made by: jlahoda
Added TypeUtilities.substitute.

Added GeneratorUtilities.createMethod

Mar 25 '08; API spec. version: 0.34; made by: jlahoda; issues: #130240
Added method to create a new method tree for given method element.

Added ModificationResult.Difference.setCommitToGuards(boolean) and isCommitToGuards() methods permitting to write modifications even to guarded sections

Mar 15 '08; API spec. version: 0.33; made by: jpokorsky
Added methods to allow ModificationResult to write changes into guarded sections of a document in case the API client is aware of what he does.

Added CompilationInfo.getChangedTree method returning the reparsed subtree

Jan 25 '08; API spec. version: 0.31; made by: tzezula
Added method to return the reparsed subtree of the CompilationUnit tree, the result of this method should be used as a hint for the registered tasks to update model only for the changed subtree rather than for the whole CompilationUnit tree.

Added CancellableTreePathScanner(AtomicBoolean) and CancellableTreeScanner(AtomicBoolean)

Dec 21 '07; API spec. version: 0.30; made by: jlahoda; issues: #123762
Added constructors taking AtomicBoolean to the CancellableTreePathScanner and CancellableTreeScanner.

Added a method to obtain ElementHandles from TypeMirrorHandles representing DeclaredTypes

Dec 14 '07; API spec. version: 0.29; made by: dbalek; issues: #123971
Added a method to obtain ElementHandles from TypeMirrorHandles representing DeclaredTypes.

Added ClassIndex.NameKind.CAMEL_CASE_INSENSITIVE

Nov 26 '07; API spec. version: 0.28; made by: tzezula; issues: #122864
Added ClassIndex.NameKind.CAMEL_CASE_INSENSITIVE used by code completion for getting camel case names.

Support for JSPs and dialogs

Jun 15 '07; API spec. version: 0.21; made by: jlahoda; issues: #106629
Adding ability to use Java infrastructure for non-Java file (eg. JSP files) and inside dialogs.

Adding GeneratorUtilities

Jun 15 '07; API spec. version: 0.20; made by: jlahoda; issues: #106678
A utility class, org.netbeans.api.java.source.GeneratorUtilities has been added.

Removal of obsolete, duplicated and deprecated methods from java/source

Jun 15 '07; API spec. version: 0.19; made by: jlahoda; issues: #106719
Removal of a few obsolete, duplicated and deprecated methods from java/source.

CancellableTask split into Task and CancellableTask.

Jun 15 '07; API spec. version: 0.18; made by: tzezula
The JavaSource.runModificationTask(), runWhenScanFinished() and runUserActionTask() never call the cancel method of the CancellableTask, the implementor of such a CancellableTask just writes an empty cancel method. The compatible API change splits the CancellableTask into Task with run method and CancellableTask which extends the Task by cancel method. The JavaSource methods mentioned above take Task rather than CancellableTask. The CancellableTask is used only for tasks registered by factories.

ClassIndex methods are cancellable

Jun 13 '07; API spec. version: 0.16; made by: tzezula
The ClassIndex methods called from the CancellableTask are cancellable. In case when they are cancelled by the JavaSource infrastructure they return null instead of the Set to allow client to determine this state. The incompatible semantic change is that tasks registered by factories have to check if the value returned from class index is null.

Added a method to obtain top level elements defined in the source/class file.

Jun 5 '07; API spec. version: 0.14; made by: tzezula; issues: #93100
Added a method to obtain top level elements defined in the given source or class file.

Added factory method which returns a new TreePathHandle for given Element and CompilationInfo.

Apr 24 '07; API spec. version: 0.13; made by: jbecicka; issues: #102333
There is no simple way how to weakly reference all elements from javac. For instance local variables cannot be referenced by ElementHandles while source-less Elements cannot be referenced by TreePathHandles. This fix allows to create TreePathHandles for any javac Element (both local and source less).

Added a method to run a CancellableTask when the backgound scan is finished.

Apr 19 '07; API spec. version: 0.12; made by: tzezula; issues: #91117 #99923
The JavaSource.runWhenScanFinished performs the given task either synchronously when no background scan is running. When the background scan is running the task is performed asynchronously when the scan completes.

Added a method which returns all the project source roots depending on a given source root.

Apr 13 '07; API spec. version: 0.10; made by: tzezula; issues: #92030
The refactoring and find usages need to find the dependent roots of a project root in which the refactored type is declared, but finding such an information using the project API may be very expensive especially when lots of projects is opened. The goal of this API is to provide and cache this information.

Added a listener for listening on changes in the `ClassIndex`.

Apr 4 '07; API spec. version: 0.8; made by: tzezula; issues: #91763
The listener for listening on changes in the ClassIndex was added. The listener fires events when a declared type was removed, added, changed in the ClassIndex oe when the underlaying ClassPath was changed.

Adding template attribute `package`

Mar 26 '07; API spec. version: 0.7; made by: jpokorsky; issues: #95399
Added the template attribute package for templates using scripting language.

Removing CommentUtilities, adjusting TreeMaker and introducing TypeUtilities

Mar 18 '07; API spec. version: 0.6; affected top-level classes: TypeUtilities; made by: jlahoda; issues: #97542

removed org.netbeans.api.java.source.CommentUtilities
removed org.netbeans.api.java.source.TreeMaker.Variable(..., TypeElement)
removed org.netbeans.api.java.source.TreeMaker.Method(..., TypeElement)
added org.netbeans.api.java.source.TypeUtilities

Compatibility: