Class AptConfig


  • public class AptConfig
    extends Object
    Accesses configuration data for APT. Note that some of the code in org.eclipse.jdt.ui reads and writes settings data directly, rather than calling into the methods of this class. This class is static. Instances should not be constructed. Helpful information about the Eclipse preferences mechanism can be found at: http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/user_settings/faq.html
    Since:
    3.5
    • Method Detail

      • addProcessorOption

        public static void addProcessorOption​(IJavaProject jproj,
                                              String key,
                                              String val)
        Add the equivalent of -Akey=val to the list of processor options.
        Parameters:
        key - must be a nonempty string. It should only include the key; that is, it should not start with "-A".
        jproj - a project, or null to set the option workspace-wide.
        val - can be null (equivalent to -Akey). This does not mean remove the key; for that functionality, @see #removeProcessorOption(IJavaProject, String).
      • removeProcessorOption

        public static void removeProcessorOption​(IJavaProject jproj,
                                                 String key)
        Remove an option from the list of processor options.
        Parameters:
        jproj - a project, or null to remove the option workspace-wide.
        key - must be a nonempty string. It should only include the key; that is, it should not start with "-A".
      • getProcessorOptions

        public static Map<String,​String> getProcessorOptions​(IJavaProject jproj,
                                                                   boolean isTestCode)
        Get the options that are presented to annotation processors by the AnnotationProcessorEnvironment. Options are key/value pairs which are set in the project properties. Option values can begin with a percent-delimited token representing a classpath variable or one of several predefined values. The token must either be followed by a path delimiter, or be the entire value. Such tokens will be replaced with their resolved value. The predefined values are %ROOT%, which is replaced by the absolute pathname of the workspace root directory, and %PROJECT.DIR%, which will be replaced by the absolute pathname of the project root directory. For example, a value of %ECLIPSE_HOME%/configuration/config.ini might be resolved to d:/eclipse/configuration/config.ini. This method returns some options which are set programmatically but are not directly editable, are not displayed in the configuration GUI, and are not persisted to the preference store. This is meant to emulate the behavior of Sun's apt command-line tool, which passes most of its command line options to the processor environment. The programmatically set options are: -classpath [set to Java build path] -sourcepath [set to Java source path] -s [set to generated src dir] -d [set to binary output dir] -target [set to compiler target version] -source [set to compiler source version] There are some slight differences between the options returned by this method and the options returned from this implementation of @see AnnotationProcessorEnvironment#getOptions(). First, that method returns additional options which are only meaningful during a build, such as phase. Second, that method also adds alternate encodings of each option, to be compatible with a bug in Sun's apt implementation: specifically, for each option key="k", value="v", an additional option is created with key="-Ak=v", value=null. This includes the user-created options, but does not include the programmatically defined options listed above.
        Parameters:
        jproj - a project, or null to query the workspace-wide setting.
        isTestCode - if true, the programmatically set options are computed for test code compilation
        Returns:
        a mutable, possibly empty, map of (key, value) pairs. The value part of a pair may be null (equivalent to "-Akey" on the Sun apt command line). The value part may contain spaces.
        Since:
        3.6
      • setProcessorOptions

        public static void setProcessorOptions​(Map<String,​String> options,
                                               IJavaProject jproj)
        Set all the processor options in one call. This will delete any options that are not passed in, so callers who do not wish to destroy pre-existing options should use addProcessorOption() instead.
        Parameters:
        options - a map of keys to values. The keys should not include any automatic options (@see #isAutomaticProcessorOption(String)), and the "-A" should not be included. That is, to perform the equivalent of the apt command line "-Afoo=bar", use the key "foo" and the value "bar". Keys cannot contain spaces; values can contain anything at all. Keys cannot be null, but values can be.
      • isAutomaticProcessorOption

        public static boolean isAutomaticProcessorOption​(String key)
        Is the named option automatically generated in getProcessorOptions(), or did it come from somewhere else, such as a -A processor option?
        Parameters:
        key - the name of an AnnotationProcessorEnvironment option
        Returns:
        true if the option is automatically set.
      • getRawProcessorOptions

        public static Map<String,​String> getRawProcessorOptions​(IJavaProject jproj)
        Get the options that are presented to annotation processors by the AnnotationProcessorEnvironment. The -A and = are stripped out, so (key, value) is the equivalent of -Akey=value. This method differs from getProcessorOptions in that the options returned by this method do NOT include any programmatically set options. This method returns only the options that are persisted to the preference store and that are displayed in the configuration GUI.
        Parameters:
        jproj - a project, or null to query the workspace-wide setting. If jproj is not null, but the project has no per-project settings, this method will fall back to the workspace-wide settings.
        Returns:
        a mutable, possibly empty, map of (key, value) pairs. The value part of a pair may be null (equivalent to "-Akey"). The value part can contain spaces, if it is quoted: -Afoo="bar baz".
      • dispose

        public static void dispose()
        Flush unsaved preferences and perform any other config-related shutdown. This is called once, from AptPlugin.shutdown().
      • initialize

        public static void initialize()
        Initialize preferences lookups, and register change listeners. This is called once, from AptPlugin.startup().
      • isEnabled

        public static boolean isEnabled​(IJavaProject jproject)
        Is annotation processing turned on for this project?

        Prior to Eclipse 3.3, this read the org.eclipse.jdt.apt.aptEnabled setting. In Eclipse 3.3, it reads the org.eclipse.jdt.core.compiler.processingEnabled setting; the result is logically or-ed with value of the older setting in order to preserve backward compatibility.

        Parameters:
        jproject - an IJavaProject, or null to request workspace preferences.
        Returns:
        true if annotation processing is turned on.
      • setEnabled

        public static void setEnabled​(IJavaProject jproject,
                                      boolean enabled)
        Turn annotation processing on or off for this project.

        Prior to Eclipse 3.3, this affected the org.eclipse.jdt.apt.aptEnabled setting. In Eclipse 3.3, it affects the org.eclipse.jdt.core.compiler.processingEnabled setting; the older setting is still set (and read) in order to preserve backward compatibility.

        Parameters:
        jproject - an IJavaProject, or null to set workspace preferences.
        enabled -
      • shouldProcessDuringReconcile

        public static boolean shouldProcessDuringReconcile​(IJavaProject jproject)
        Is annotation processing turned on during reconcile, or only during build? Note that if isEnabled() is false, processing will not occur at all; the two settings are independent.
        Parameters:
        jproject - an IJavaProject to query, or null to get the default value.
        Returns:
        true if processing is enabled during both reconcile and build
      • setProcessDuringReconcile

        public static void setProcessDuringReconcile​(IJavaProject jproject,
                                                     boolean enabled)
        Turn processing during reconcile on or off. Processing during build is unaffected. Note that if isEnabled() is false, processing will not occur at all; the two settings are independent.
        Parameters:
        jproject - the IJavaProject to modify. This setting is only valid on individual projects.
      • getDefaultFactoryPath

        public static IFactoryPath getDefaultFactoryPath​(IJavaProject jproj)
        Get a factory path corresponding to the default values: if jproj is non-null, return the current workspace factory path (workspace prefs are the default for a project); if jproj is null, return the default list of plugin factories (which is the "factory default").
      • getFactoryPath

        public static IFactoryPath getFactoryPath​(IJavaProject jproj)
        Get the factory path for a given project or for the workspace.
        Parameters:
        jproj - the project, or null to get the factory path for the workspace.
        Returns:
        a FactoryPath representing the current state of the specified project. Note that changes made to the project after this call will not affect the returned object - that is, it behaves like a value, not like a live link to the project state.
      • setFactoryPath

        public static void setFactoryPath​(IJavaProject jproj,
                                          IFactoryPath path)
                                   throws CoreException
        Set the factory path for a given project or for the workspace. Does not perform any validation on the path.
        Parameters:
        jproj - the project, or null to set the factory path for the workspace.
        path - a factory path, or null to reset the factory path to the default.
        Throws:
        CoreException
      • hasProjectSpecificFactoryPath

        public static boolean hasProjectSpecificFactoryPath​(IJavaProject jproj)
        Does this project have a factory path that is different from the workspace default?
        Returns:
        true if there is a project-specific factory path.
      • getString

        public static String getString​(IJavaProject jproj,
                                       String optionName)
        Helper method to get a single preference setting, e.g., APT_GENSRCDIR. This is a different level of abstraction than the processor -A settings! The -A settings are all contained under one single preference node, APT_PROCESSOROPTIONS. Use @see #getProcessorOptions(IJavaProject) to get the -A settings; use @see #getOptions(IJavaProject) to get all the preference settings as a map; and use this helper method to get a single preference setting.
        Parameters:
        jproj - the project, or null for workspace.
        optionName - a preference constant from @see AptPreferenceConstants.
        Returns:
        the string value of the setting.
      • setGenSrcDir

        public static void setGenSrcDir​(IJavaProject jproject,
                                        String dirString)
      • getGenTestSrcDir

        public static String getGenTestSrcDir​(IJavaProject jproject)
        Since:
        3.6
      • setGenTestSrcDir

        public static void setGenTestSrcDir​(IJavaProject jproject,
                                            String dirString)
        Since:
        3.6
      • validateGenSrcDir

        public static boolean validateGenSrcDir​(IJavaProject jproject,
                                                String dirName)