jdt core - build notes 3.6 stream |
Java development tools core |
Here are the build notes for the Eclipse JDT/Core plug-in project
org.eclipse.jdt.core,
describing bug resolution and substantial changes in the HEAD branch.
For more information on 3.6 planning, please refer to JDT/Core release plan,
the next milestone plan,
the overall official plan,
or the build schedule.
This present document covers all changes since Release 3.5 (also see a summary of API changes).
Maintenance of previous releases of JDT/Core is performed in parallel branches: R3.5.x, R3.4.x, R3.3.x, R3.2.x, R3.1.x, R3.0.x, R2.1.x, R2.0.x, R1.0.x. |
These new preferences are controlled with the options:
DefaultCodeFormatterConstants.FORMATTER_DISABLING_TAG
DefaultCodeFormatterConstants.FORMATTER_ENABLING_TAG
/** * FORMATTER / Option to define the tag to put in a comment to disable the formatting. * See the {@link #FORMATTER_ENABLING_TAG} option to re-enable it. * - option id: "org.eclipse.jdt.core.formatter.disabling_tag" * - possible values: String, with constraints mentioned below * - default: "" * * Note that: * * 1. The tag name will be trimmed. Hence if it does contain white spaces * at the beginning or at the end, they will not be taken into account while * searching for the tag in the comments * 2. If a tag is starting with a letter or digit, then it cannot be leaded by * another letter or digit to be recognized * ("ToDisableFormatter" will not be recognized as a disabling tag * "DisableFormatter", but "Re:DisableFormatter" * will be detected for either tag "DisableFormatter" or * ":DisableFormatter"). * Respectively, a tag ending with a letter or digit cannot be followed by a letter * or digit to be recognized ("DisableFormatter1" will not be * recognized as a disabling tag "DisableFormatter", but * "DisableFormatter:1" will be detected either for tag * "DisableFormatter" or "DisableFormatter:") * 3. As soon as the formatter encounters the defined disabling tag, it stops to * format the code from the beginning of the comment including this tag. If it * was already disabled, the tag has no special effect. * For example, the second defined enabling tag "disable-formatter" * in the following snippet is not necessary as the formatter was already disabled * since the first one: * class X { * // disable-formatter * void foo1() {} * // disable-formatter * void foo2() {} * void bar1() {} * void bar2() {} * } * * 4. If no enabling tag is found by the formatter after the disabling tag, then * the end of the snippet won't be formatted. * For example, when a disabling tag is put at the beginning of the code, then * the entire content of a compilation unit is not formatted: * // disable-formatter * class X { * void foo1() {} * void foo2() {} * void bar1() {} * void bar2() {} * } * * 5. If a mix of disabling and enabling tags is done in the same comment, then * the formatter will only take into account the last encountered tag in the * comment. * For example, in the following snippet, the formatter will be disabled after * the comment: * class X { * /* * * This is a comment with a mix of disabling and enabling tags: * * - disable-formatter * * - enable-formatter * * - disable-formatter * * The formatter will stop to format from the beginning of this comment... * */ * void foo() {} * void bar() {} * } * * 6. The tag cannot include newline character (i.e. '\n') but it can have white spaces. * E.g. "format: off" is a valid disabling tag * In the future, newlines may be used to support multiple disabling tags. * * @since 3.6 */ /** * FORMATTER / Option to define the tag to put in a comment to re-enable the * formatting after it has been disabled (see {@link #FORMATTER_DISABLING_TAG}) * - option id: "org.eclipse.jdt.core.formatter.enabling_tag" * - possible values: String, with constraints mentioned below * - default: "" * * Note that: * * 1. The tag name will be trimmed. Hence if it does contain white spaces * at the beginning or at the end, they will not be taken into account while * searching for the tag in the comments * 2. If a tag is starting with a letter or digit, then it cannot be leaded by * another letter or digit to be recognized * ("ReEnableFormatter" will not be recognized as an enabling tag * "EnableFormatter", but "Re:EnableFormatter" * will be detected for either tag "EnableFormatter" or * ":EnableFormatter"). * Respectively, a tag ending with a letter or digit cannot be followed by a letter * or digit to be recognized ("EnableFormatter1" will not be * recognized as an enabling tag "EnableFormatter", but * "EnableFormatter:1" will be detected either for tag * "EnableFormatter" or "EnableFormatter:") * 3. As soon as the formatter encounters the defined enabling tag, it re-starts * to format the code just after the comment including this tag. If it was already * active, i.e. already re-enabled or never disabled, the tag has no special effect. * For example, the defined enabling tag "enable-formatter" * in the following snippet is not necessary as the formatter has never been * disabled: * class X { * void foo1() {} * void foo2() {} * // enable-formatter * void bar1() {} * void bar2() {} * } * * Or, in the following other snippet, the second enabling tag is not necessary as * the formatting will have been re-enabled by the first one: * class X { * // disable-formatter * void foo1() {} * void foo2() {} * // enable-formatter * void bar1() {} * // enable-formatter * void bar2() {} * } * * 4. If a mix of disabling and enabling tags is done in the same comment, then * the formatter will only take into account the last encountered tag in the * comment. * For example, in the following snippet, the formatter will be re-enabled after * the comment: * // disable-formatter * class X { * /* * * This is a comment with a mix of disabling and enabling tags: * * - enable-formatter * * - disable-formatter * * - enable-formatter * * The formatter will restart to format after this comment... * */ * void foo() {} * void bar() {} * } * * 5. The tag cannot include newline character (i.e. '\n') but it can have white spaces. * E.g. "format: on" is a valid enabling tag * In the future, newlines may be used to support multiple enabling tags. * * @since 3.6 */
For example, the following snippet:
public class Test { /* disable-formatter */ void foo( ) { // unformatted area } /* enable-formatter */ void bar( ) { // formatted area } }formatted with disabling tags = "disable-formatter" and enabling tags = "enable-formatter" produces the following output:
public class Test { /* disable-formatter * void foo( ) { // unformatted area } /* enable-formatter * void bar() { // formatted area } }See bug 27079 for more details.
/** * Compiler option ID: Further Determining the Effect of @SuppressWarnings if also * COMPILER_PB_SUPPRESS_WARNINGS is enabled. * When enabled, the @SuppressWarnings annotation can additionally be used to suppress * optional compiler diagnostics that have been configured as ERROR. * When disabled, all @SuppressWarnings annotations only affects warnings. * * Option id: "org.eclipse.jdt.core.compiler.problem.suppressOptionalErrors" * Possible values: { "enabled", "disabled" } * Default: "disabled" * * @since 3.6 * @category CompilerOptionID */ public static final String COMPILER_PB_SUPPRESS_OPTIONAL_ERRORS = PLUGIN_ID + ".compiler.problem.suppressOptionalErrors";
This new preference is controlled with the option:
DefaultCodeFormatterConstants.FORMATTER_ALIGNMENT_FOR_METHOD_DECLARATION
/**
* FORMATTER / Option for alignment of method declaration
* - option id: "org.eclipse.jdt.core.formatter.alignment_for_method_declaration"
* - possible values: values returned by createAlignmentValue(boolean, int, int)
call
* - default: createAlignmentValue(false, WRAP_NO_SPLIT, INDENT_DEFAULT)
*
* @see #createAlignmentValue(boolean, int, int)
* @since 3.6
*/
For example, the following snippet:
public class Test { public final synchronized java.lang.String a_method_which_has_a_very_long_name() { return null; } }formatted with this preference activated as 'Wrap only when necessary', will produce the following output:
public class Test { public final synchronized java.lang.String a_method_which_has_a_very_long_name() { return null; } }See bug 284789 for more details.
/**
* Returns the signatures for this type parameter's bounds. The type parameter may have
* been declared as part of a type or a method. The signatures represent only the individual
* bounds and do not include the type variable name or the extends
keyword.
* The signatures may be either unresolved (for source types) or resolved (for binary types).
* See {@link Signature} for details.
*
* @return the signatures for the bounds of this formal type parameter
* @throws JavaModelException
* if this element does not exist or if an exception occurs while accessing its corresponding resource.
* @see Signature
* @since 3.6
*/
String[] getBoundsSignatures() throws JavaModelException;
The default is to format these comments to have a backward compatible behavior.
This new preferences is controlled with the options:
DefaultCodeFormatterConstants.FORMATTER_COMMENT_FORMAT_LINE_COMMENT_STARTING_ON_FIRST_COLUMN
/** * FORMATTER / Option to format line comments that start on the first column * - option id: "org.eclipse.jdt.core.formatter.format_line_comment_starting_on_first_column" * - possible values: { TRUE, FALSE } * - default: TRUE * * Note that this option is ignored if either the * {@link #FORMATTER_COMMENT_FORMAT_LINE_COMMENT} option has been set to * {@link #FALSE} or the formatter is created with the mode * {@link ToolFactory#M_FORMAT_NEW}. * * @see #TRUE * @see #FALSE * @see ToolFactory#createCodeFormatter(Map, int) * @since 3.6 */
For example, the following snippet:
public class X01 { // int a = 1; // int b = 2; }will be untouched by the formatter if both options are activated. See bug 251133 for more details.
org.eclipse.jdt.core.IClasspathEntry /** * Returns the classpath entry that is making a reference to this classpath entry. For entry kinds * {@link #CPE_LIBRARY}, the return value is the entry that is representing the JAR that includes *this
in the MANIFEST.MF file's Class-Path section. For entry kinds other than * {@link #CPE_LIBRARY}, this returnsnull
. For those entries that are on the raw classpath already, * this returnsnull
. * * It is possible that multiple library entries refer to the same entry * via the MANIFEST.MF file. In those cases, this method returns the first classpath entry * that appears in the raw classpath. However, this does not mean that the other referencing * entries do not relate to their referenced entries. * See {@link JavaCore#getReferencedClasspathEntries(IClasspathEntry, IJavaProject)} for * more details. * * @return the classpath entry that is referencing this entry ornull
if * not applicable. * @since 3.6 */ IClasspathEntry getReferencingEntry(); org.eclipse.jdt.core.IJavaProject /** * Works similar to {@link #setRawClasspath(IClasspathEntry[], IPath, IProgressMonitor)} and * additionally allows persisting the given array of referenced entries for this project. * The referenced entries and their attributes are stored in the .classpath file of this * project. For details on referenced entries, see * {@link JavaCore#getReferencedClasspathEntries(IClasspathEntry, IJavaProject)} * and {@link IClasspathEntry#getReferencingEntry()}. * * Since the referenced entries are stored in the .classpath file, clients can store additional * information that belong to these entries and retrieve them across sessions, though the referenced * entries themselves may not be present in the raw classpath. By passing anull
* referencedEntries, clients can choose not to modify the already persisted referenced entries, * which is fully equivalent to {@link #setRawClasspath(IClasspathEntry[], IPath, IProgressMonitor)}. * If an empty array is passed as referencedEntries, the already persisted referenced entries, * if any, will be cleared. * * If there are duplicates of a referenced entry or if any of thereferencedEntries
* is already present in the raw classpath(entries
) those referenced entries will * be excluded and not be persisted. * * @param entries a list of classpath entries * @param referencedEntries the list of referenced classpath entries to be persisted * @param outputLocation the default output location * @param monitor the given progress monitor * @exception JavaModelException if the classpath could not be set. Reasons include: * This Java element does not exist (ELEMENT_DOES_NOT_EXIST) * The classpath is being modified during resource change event notification (CORE_EXCEPTION) * The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)} * @see IClasspathEntry * @see #getReferencedClasspathEntries() * @since 3.6 */ void setRawClasspath(IClasspathEntry[] entries, IClasspathEntry[] referencedEntries, IPath outputLocation, IProgressMonitor monitor) throws JavaModelException; /** * Returns the list of referenced classpath entries stored in the .classpath file ofthis
* java project. Clients can store the referenced classpath entries using * {@link #setRawClasspath(IClasspathEntry[], IClasspathEntry[], IPath, IProgressMonitor)} * If the client has not stored any referenced entries for this project, an empty array is returned. * * @throws JavaModelException * @return an array of referenced classpath entries stored for this java project or an empty array if none * stored earlier. * @since 3.6 */ IClasspathEntry[] getReferencedClasspathEntries() throws JavaModelException; org.eclipse.jdt.core.IPackageFragmentRoot /** * Returns the first resolved classpath entry that corresponds to this package fragment root. * A resolved classpath entry is said to correspond to a root if the path of the resolved * entry is equal to the root's path. * * @return the first resolved classpath entry that corresponds to this package fragment root * @throws JavaModelException if this element does not exist or if an * exception occurs while accessing its corresponding resource. * @since 3.6 */ IClasspathEntry getResolvedClasspathEntry() throws JavaModelException; org.eclipse.jdt.core.JavaCore /** * Returns an array of classpath entries that are referenced directly or indirectly * by a given classpath entry. For the entry kind {@link IClasspathEntry#CPE_LIBRARY}, * the method returns the libraries that are included in the Class-Path section of * the MANIFEST.MF file. If a referenced JAR file has further references to other library * entries, they are processed recursively and added to the list. For entry kinds other * than {@link IClasspathEntry#CPE_LIBRARY}, this method returns an empty array. * * If a referenced entry has already been stored * in the given project's .classpath, the stored attributes are populated in the corresponding * referenced entry. For more details on storing referenced entries see * see {@link IJavaProject#setRawClasspath(IClasspathEntry[], IClasspathEntry[], IPath, * IProgressMonitor)}. * * @param libraryEntry the library entry whose referenced entries are sought * @param project project where the persisted referenced entries to be retrieved from * @return an array of classpath entries that are referenced directly or indirectly by the given entry. * If not applicable, returns an empty array. * @since 3.6 */ public static IClasspathEntry[] getReferencedClasspathEntries(IClasspathEntry libraryEntry, IJavaProject project);
This new preference is controlled with the option:
DefaultCodeFormatterConstants.FORMATTER_ALIGNMENT_FOR_ARGUMENTS_IN_ANNOTATION
/**
* FORMATTER / Option for alignment of arguments in annotation
* - option id: "org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation"
* - possible values: values returned by createAlignmentValue(boolean, int, int)
call
* - default: createAlignmentValue(false, WRAP_NO_SPLIT, INDENT_DEFAULT)
*
* @see #createAlignmentValue(boolean, int, int)
* @since 3.6
*/
For example, the following snippet:
@MyAnnot(value1 = "this is an example", value2 = "of an annotation", value3 = "with several arguments", value4 = "which may need to be wrapped") public class Test { }formatted with this preference activated, will produce the following output while using the
Eclipse [built-in]
profile:
@MyAnnot(value1 = "this is an example", value2 = "of an annotation", value3 = "with several arguments", value4 = "which may need to be wrapped") public class Test { }See bug 282030 for more details.
/** * Set the environment that can be used when no IJavaProject are available. * * The user has to be sure to include all required types on the classpaths for binary types * or on the sourcepaths for source types to resolve the given source code. * All classpath and sourcepath entries are absolute paths. * If sourcepaths contain units using a specific encoding (not the platform encoding), then the * given encodings must be set. If the given encodings is set, its length must * match the length of the sourcepaths parameter or an IllegalArgumentException will be thrown. * If encodings is not null, the given sourcepathEntries must not be null. * * @param classpathEntries the given classpath entries to be used to resolve bindings * @param sourcepathEntries the given sourcepath entries to be used to resolve bindings * @param encodings the encodings of the corresponding sourcepath entries or null if the platform encoding * can be used. * @param includeRunningVMBootclasspath true if the bootclasspath of the running VM must be prepended to the * given classpath and false if the bootclasspath of the running VM should be ignored. * @throws IllegalArgumentException if the size of the given encodings is not equals to the size of the given * sourcepathEntries * @since 3.6 */ public void setEnvironment(String[] classpathEntries, String[] sourcepathEntries, String[] encodings, boolean includeRunningVMBootclasspath);
These new preferences are controlled respectively with the options:
DefaultCodeFormatterConstants.FORMATTER_COMMENT_NEW_LINES_AT_BLOCK_BOUNDARIES
DefaultCodeFormatterConstants.FORMATTER_COMMENT_NEW_LINES_AT_JAVADOC_BOUNDARIES
/** * FORMATTER / Option to control whether block comments will have new lines at boundaries * - option id: "org.eclipse.jdt.core.formatter.comment.new_lines_at_block_boundaries" * - possible values: { TRUE, FALSE } * - default: TRUE * * @see #TRUE * @see #FALSE * @since 3.6 */ /** * FORMATTER / Option to control whether javadoc comments will have new lines at boundaries * - option id: "org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries" * - possible values: { TRUE, FALSE } * - default: TRUE * * @see #TRUE * @see #FALSE * @since 3.6 */
For example, when both of these options are used, the following snippet:
public class X { /* * This block comment after formatting will no longer use a new line * at the beginning and at the end of the comment... */ void foo() { } /** * This javadoc comment after formatting will no longer use a new line * at the beginning and at the end of the comment... */ void bar() { } }formatted with this preference activated, will produce the following output:
public class X { /* This block comment after formatting will no longer use a new line at the * beginning and at the end of the comment... */ void foo() { } /** This javadoc comment after formatting will no longer use a new line at * the beginning and at the end of the comment... */ void bar() { } }See bug 270209 for more details.
CodeFormatter.F_INCLUDE_COMMENT
flag now works for all kind
of snippet while using the formatter.This new preference is controlled with the option:
DefaultCodeFormatterConstants.FORMATTER_INSERT_NEW_LINE_AFTER_LABEL
/** * FORMATTER / Option to insert a new line after a label * - option id: "org.eclipse.jdt.core.formatter.insert_new_line_after_label" * - possible values: { INSERT, DO_NOT_INSERT } * - default: DO_NOT_INSERT * * @see JavaCore#INSERT * @see JavaCore#DO_NOT_INSERT * @since 3.6 */
For example, the following snippet:
public class X { void foo() { LABEL:for (int i = 0; i < 10; i++) { } } }formatted with this preference activated, will produce the following output:
public class X { void foo() { LABEL: for (int i = 0; i < 10; i++) { } } }See bug 150741 for more details.
/** * Sets whether a context should be used to properly filter implicit imports. * * By default, the option is disabled to preserve pre-3.6 behavior. * * * When this option is set, the context passed to the addImport*(...) methods is used to determine * whether an import can be filtered because the type is implicitly visible. Note that too many imports * may be kept if this option is set and addImport*(...) methods are called without a context. * * * @param useContextToFilterImplicitImports the given setting * * @see #setFilterImplicitImports(boolean) * @since 3.6 */ public void setUseContextToFilterImplicitImports(boolean useContextToFilterImplicitImports);
/** * Returns a Java search scope limited to the hierarchy of the given type and to a given project. * The Java elements resulting from a search with this scope will be types in this hierarchy. * * Unlike the createHierarchyScope methods, this method creates strict * scopes that only contain types that actually span the hierarchy of the focus * type, but do not include additional enclosing or member types. * * * By default, hierarchy scopes include all direct and indirect supertypes and subtypes of the * focus type. This method, however, allows to restrict the hierarchy to true subtypes, * not including supertypes. Also inclusion of the focus type itself is controled by a parameter. * * * @param project the project to which to constrain the search, or null if * search should consider all types in the workspace * @param type the focus of the hierarchy scope * @param onlySubtypes if true only subtypes of type are considered * @param includeFocusType if true the focus type type is included in the resulting scope, * otherwise it is excluded * @param owner the owner of working copies that take precedence over original compilation units, * or null if the primary working copy owner should be used * @return a new hierarchy scope * @exception JavaModelException if the hierarchy could not be computed on the given type * @since 3.6 */ public static IJavaSearchScope createStrictHierarchyScope(IJavaProject project, IType type, boolean onlySubtypes, boolean includeFocusType, WorkingCopyOwner owner) throws JavaModelException;
org.eclipse.jdt.core.compiler.IProblem.UnusedObjectAllocation /** * Compiler option ID: Reporting Allocation of an Unused Object. * When enabled, the compiler will issue an error or a warning if an object is allocated but never used, * neither by holding a reference nor by invoking one of the object's methods. * * Option id:"org.eclipse.jdt.core.compiler.problem.unusedObjectAllocation" * Possible values:{ "error", "warning", "ignore" } * Default:"ignore" * * @since 3.6 * @category CompilerOptionID */ public static final String COMPILER_PB_UNUSED_OBJECT_ALLOCATION = PLUGIN_ID + ".compiler.problem.unusedObjectAllocation";
/** * Returns the reconcile flag of this context. This flag is a bitwise value of the constant defined * in ICompilationUnit. * * @return the reconcile flag of this context * @since 3.6 * * @see ICompilationUnit#ENABLE_BINDINGS_RECOVERY * @see ICompilationUnit#ENABLE_STATEMENTS_RECOVERY * @see ICompilationUnit#IGNORE_METHOD_BODIES */ public int getReconcileFlags();
TypeNameMatch
:
/** * Returns the accessibility of the type name match * * @see IAccessRule * * @return the accessibility of the type name which may be * {@link IAccessRule#K_ACCESSIBLE}, {@link IAccessRule#K_DISCOURAGED} * or {@link IAccessRule#K_NON_ACCESSIBLE}. * The default returned value is {@link IAccessRule#K_ACCESSIBLE}. * * @since 3.6 */ public abstract int getAccessibility();See bug 296277 for more details.
org.eclipse.jdt.core.dom.ASTParser: /** * Requests an abstract syntax tree without method bodies. * * When ignore method bodies is enabled, all method bodies are discarded. * This has no impact on the binding resolution. * * If a method contains local types, its method body will be retained. * This settings is not used if the kind used in setKind(int) is either * K_EXPRESSION or K_STATEMENTS. * @since 3.5.2 */ public void setIgnoreMethodBodies(boolean enabled); org.eclipse.jdt.core.ICompilationUnit: /** * Constant indicating that a reconcile operation could ignore to parse the method bodies. * @see ASTParser#setIgnoreMethodBodies(boolean) * @since 3.5.2 */ public static final int IGNORE_METHOD_BODIES = 0x08;
org.eclipse.jdt.core.JavaCore
in order to fix bug 263564:
/** * Returns an immutable map of all known configurable options with their original default values * as defined by JDT/Core. * * The values of these options might be different from the values returned by getDefaultOptions() * as getDefaultOptions() returned the default options defined by an installation/product/configuration * (i.e. modified by the usage of a plugin_customization.ini file for example). * * These options allow to configure the behaviour of the underlying components. * If the map is being modified, an UnsupportedOperationException> exception is thrown. * Helper constants have been defined on JavaCore for each of the option IDs * (categorized in Code assist option ID, Compiler option ID and Core option ID) * and some of their acceptable values (categorized in Option value). Some * options accept open value sets beyond the documented constant values. * Note: each release may add new options. * * @return an immutable map of all known configurable options with their original default values * as defined by JDT/Core * @since 3.6 */ public static Map getOriginalDefaultOptions();
invokedynamic
bytecode:
org.eclipse.jdt.core.util.ByteCodeVisitorAdapter: public void _invokedynamic( int pc, int index, IConstantPoolEntry nameEntry, IConstantPoolEntry descriptorEntry) { // default behavior is to do nothing }
org.eclipse.jdt.core.util.IBytecodeVisitor#_invokedynamic(int, int, IConstantPoolEntry, IConstantPoolEntry)
org.eclipse.jdt.core.util.IOpcodeMnemonics#INVOKEDYNAMIC
For earlier build notes, also see build notes up to Release 3.5.