ProjectHelper (Apache Ant API)
Date: 2018-07-10

org.apache.tools.ant

## Class ProjectHelper

- java.lang.Object
- - org.apache.tools.ant.ProjectHelper

- Direct Known Subclasses:
    ProjectHelper2, ProjectHelperImpl

      public class ProjectHelper
      extends java.lang.Object

  Configures a Project (complete with Targets and Tasks) based on a build file. It'll rely on a plugin to do the actual processing of the file.

  This class also provide static wrappers for common introspection.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ProjectHelper.OnMissingExtensionPoint` Possible value for target's onMissingExtensionPoint attribute.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ANT_ATTRIBUTE_URI` The URI for ant specific attributes
    `static java.lang.String` | `ANT_CORE_URI` The URI for ant name space
    `static java.lang.String` | `ANT_CURRENT_URI` The URI for antlib current definitions
    `static java.lang.String` | `ANT_TYPE` Polymorphic attribute
    `static java.lang.String` | `ANTLIB_URI` The URI for defined types/tasks - the format is antlib:<package>
    `static java.lang.String` | `HELPER_PROPERTY` Name of JVM system property which provides the name of the ProjectHelper class to use.
    `static java.lang.String` | `PROJECTHELPER_REFERENCE` name of project helper reference that we add to a project
    `static java.lang.String` | `SERVICE_ID` The service identifier in jars which provide Project Helper implementations.
    `static java.lang.String` | `USE_PROJECT_NAME_AS_TARGET_PREFIX` constant to denote use project name as target prefix

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ProjectHelper()` Default constructor

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static BuildException` | `addLocationToBuildException(BuildException ex, Location newLocation)` Add location to build exception.
    `static void` | `addText(Project project, java.lang.Object target, char[] buf, int start, int count)` Adds the content of #PCDATA sections to an element.
    `static void` | `addText(Project project, java.lang.Object target, java.lang.String text)` Adds the content of #PCDATA sections to an element.
    `boolean` | `canParseAntlibDescriptor(Resource r)` Whether this instance of ProjectHelper can parse an Antlib descriptor given by the URL and return its content as an UnknownElement ready to be turned into an Antlib task.
    `boolean` | `canParseBuildFile(Resource buildFile)` Check if the helper supports the kind of file.
    `static void` | `configure(java.lang.Object target, org.xml.sax.AttributeList attrs, Project project)` Deprecated. since 1.6.x. Use IntrospectionHelper for each property.
    `static void` | `configureProject(Project project, java.io.File buildFile)` Configures the project with the contents of the specified build file.
    `static java.lang.String` | `extractNameFromComponentName(java.lang.String componentName)` extract the element name from a component name
    `static java.lang.String` | `extractUriFromComponentName(java.lang.String componentName)` extract a uri from a component name
    `static java.lang.String` | `genComponentName(java.lang.String uri, java.lang.String name)` Map a namespaced {uri,name} to an internal string format.
    `static java.lang.ClassLoader` | `getContextClassLoader()` Deprecated. since 1.6.x. Use LoaderUtils.getContextClassLoader()
    `static java.lang.String` | `getCurrentPrefixSeparator()` The separator between the prefix and the target name.
    `static java.lang.String` | `getCurrentTargetPrefix()` The prefix to prepend to imported target names.
    `java.lang.String` | `getDefaultBuildFile()` The file name of the build script to be parsed if none specified on the command line
    `java.util.List<java.lang.String[]>` | `getExtensionStack()` Extension stack.
    `java.util.Vector<java.lang.Object>` | `getImportStack()` Import stack.
    `static ProjectHelper` | `getProjectHelper()` Get the first project helper found in the classpath
    `static boolean` | `isInIncludeMode()` Whether the current file should be read in include as opposed to import mode.
    `static java.lang.String` | `nsToComponentName(java.lang.String ns)` Convert an attribute namespace to a "component name".
    `void` | `parse(Project project, java.lang.Object source)` Parses the project file, configuring the project as it goes.
    `UnknownElement` | `parseAntlibDescriptor(Project containingProject, Resource source)` Parse the given URL as an antlib descriptor and return the content as something that can be turned into an Antlib task.
    `static void` | `parsePropertyString(java.lang.String value, java.util.Vector<java.lang.String> fragments, java.util.Vector<java.lang.String> propertyRefs)` Deprecated. since 1.6.x. Use PropertyHelper.
    `static java.lang.String` | `replaceProperties(Project project, java.lang.String value)` Deprecated. since 1.6.x. Use project.replaceProperties().
    `static java.lang.String` | `replaceProperties(Project project, java.lang.String value, java.util.Hashtable<java.lang.String,java.lang.Object> keys)` Deprecated. since 1.6.x. Use PropertyHelper.
    `void` | `resolveExtensionOfAttributes(Project project)` Check extensionStack and inject all targets having extensionOf attributes into extensionPoint.
    `static void` | `setCurrentPrefixSeparator(java.lang.String sep)` Sets the separator between the prefix and the target name.
    `static void` | `setCurrentTargetPrefix(java.lang.String prefix)` Sets the prefix to prepend to imported target names.
    `static void` | `setInIncludeMode(boolean includeMode)` Sets whether the current file should be read in include as opposed to import mode.
    `static void` | `storeChild(Project project, java.lang.Object parent, java.lang.Object child, java.lang.String tag)` Stores a configured child element within its parent object.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### ANT_CORE_URI

          public static final java.lang.String ANT_CORE_URI

      The URI for ant name space
      See Also:
        Constant Field Values

    - #### ANT_CURRENT_URI

          public static final java.lang.String ANT_CURRENT_URI

      The URI for antlib current definitions
      See Also:
        Constant Field Values

    - #### ANT_ATTRIBUTE_URI

          public static final java.lang.String ANT_ATTRIBUTE_URI

      The URI for ant specific attributes
      Since:
        Ant 1.9.1
      See Also:
        Constant Field Values

    - #### ANTLIB_URI

          public static final java.lang.String ANTLIB_URI

      The URI for defined types/tasks - the format is antlib:<package>
      See Also:
        Constant Field Values

    - #### ANT_TYPE

          public static final java.lang.String ANT_TYPE

      Polymorphic attribute
      See Also:
        Constant Field Values

    - #### HELPER_PROPERTY

          public static final java.lang.String HELPER_PROPERTY

      Name of JVM system property which provides the name of the ProjectHelper class to use.
      See Also:
        Constant Field Values

    - #### SERVICE_ID

          public static final java.lang.String SERVICE_ID

      The service identifier in jars which provide Project Helper implementations.
      See Also:
        Constant Field Values

    - #### PROJECTHELPER_REFERENCE

          public static final java.lang.String PROJECTHELPER_REFERENCE

      name of project helper reference that we add to a project
      See Also:
        Constant Field Values

    - #### USE_PROJECT_NAME_AS_TARGET_PREFIX

          public static final java.lang.String USE_PROJECT_NAME_AS_TARGET_PREFIX

      constant to denote use project name as target prefix
      Since:
        Ant 1.9.1
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ProjectHelper

          public ProjectHelper()

      Default constructor

  - ### Method Detail

    - #### configureProject

          public static void configureProject(Project project,
                                              java.io.File buildFile)
                                       throws BuildException

      Configures the project with the contents of the specified build file.
      Parameters:
        `project` - The project to configure. Must not be `null`.
        `buildFile` - A build file giving the project's configuration. Must not be `null`.
      Throws:
        `BuildException` - if the configuration is invalid or cannot be read

    - #### getImportStack

          public java.util.Vector<java.lang.Object> getImportStack()

      Import stack. Used to keep track of imported files. Error reporting should display the import path.
      Returns:
        the stack of import source objects.

    - #### getExtensionStack

          public java.util.List<java.lang.String[]> getExtensionStack()

      Extension stack. Used to keep track of targets that extend extension points.
      Returns:
        a list of three element string arrays where the first element is the name of the extensionpoint, the second the name of the target and the third the name of the enum like class `ProjectHelper.OnMissingExtensionPoint`.

    - #### getCurrentTargetPrefix

          public static java.lang.String getCurrentTargetPrefix()

      The prefix to prepend to imported target names.

      May be set by <import>'s as attribute.

      Returns:
        the configured prefix or null
      Since:
        Ant 1.8.0

    - #### setCurrentTargetPrefix

          public static void setCurrentTargetPrefix(java.lang.String prefix)

      Sets the prefix to prepend to imported target names.
      Parameters:
        `prefix` - String
      Since:
        Ant 1.8.0

    - #### getCurrentPrefixSeparator

          public static java.lang.String getCurrentPrefixSeparator()

      The separator between the prefix and the target name.

      May be set by <import>'s prefixSeparator attribute.

      Returns:
        String
      Since:
        Ant 1.8.0

    - #### setCurrentPrefixSeparator

          public static void setCurrentPrefixSeparator(java.lang.String sep)

      Sets the separator between the prefix and the target name.
      Parameters:
        `sep` - String
      Since:
        Ant 1.8.0

    - #### isInIncludeMode

          public static boolean isInIncludeMode()

      Whether the current file should be read in include as opposed to import mode.

      In include mode included targets are only known by their prefixed names and their depends lists get rewritten so that all dependencies get the prefix as well.

      In import mode imported targets are known by an adorned as well as a prefixed name and the unadorned target may be overwritten in the importing build file. The depends list of the imported targets is not modified at all.

      Returns:
        boolean
      Since:
        Ant 1.8.0

    - #### setInIncludeMode

          public static void setInIncludeMode(boolean includeMode)

      Sets whether the current file should be read in include as opposed to import mode.
      Parameters:
        `includeMode` - boolean
      Since:
        Ant 1.8.0

    - #### parse

          public void parse(Project project,
                            java.lang.Object source)
                     throws BuildException

      Parses the project file, configuring the project as it goes.
      Parameters:
        `project` - The project for the resulting ProjectHelper to configure. Must not be `null`.
        `source` - The source for XML configuration. A helper must support at least File, for backward compatibility. Helpers may support URL, InputStream, etc or specialized types.
      Throws:
        `BuildException` - if the configuration is invalid or cannot be read
      Since:
        Ant1.5

    - #### getProjectHelper

          public static ProjectHelper getProjectHelper()

      Get the first project helper found in the classpath
      Returns:
        an project helper, never `null`
      See Also:
        `ProjectHelperRepository.getHelpers()`

    - #### getContextClassLoader

          @Deprecated
          public static java.lang.ClassLoader getContextClassLoader()

      Deprecated. since 1.6.x. Use LoaderUtils.getContextClassLoader()
      JDK1.1 compatible access to the context class loader. Cut & paste from JAXP.
      Returns:
        the current context class loader, or `null` if the context class loader is unavailable.

    - #### configure

          @Deprecated
          public static void configure(java.lang.Object target,
                                                   org.xml.sax.AttributeList attrs,
                                                   Project project)
                                            throws BuildException

      Deprecated. since 1.6.x. Use IntrospectionHelper for each property.
      Configures an object using an introspection handler.
      Parameters:
        `target` - The target object to be configured. Must not be `null`.
        `attrs` - A list of attributes to configure within the target. Must not be `null`.
        `project` - The project containing the target. Must not be `null`.
      Throws:
        `BuildException` - if any of the attributes can't be handled by the target

    - #### addText

          public static void addText(Project project,
                                     java.lang.Object target,
                                     char[] buf,
                                     int start,
                                     int count)
                              throws BuildException

      Adds the content of #PCDATA sections to an element.
      Parameters:
        `project` - The project containing the target. Must not be `null`.
        `target` - The target object to be configured. Must not be `null`.
        `buf` - A character array of the text within the element. Will not be `null`.
        `start` - The start element in the array.
        `count` - The number of characters to read from the array.
      Throws:
        `BuildException` - if the target object doesn't accept text

    - #### addText

          public static void addText(Project project,
                                     java.lang.Object target,
                                     java.lang.String text)
                              throws BuildException

      Adds the content of #PCDATA sections to an element.
      Parameters:
        `project` - The project containing the target. Must not be `null`.
        `target` - The target object to be configured. Must not be `null`.
        `text` - Text to add to the target. May be `null`, in which case this method call is a no-op.
      Throws:
        `BuildException` - if the target object doesn't accept text

    - #### storeChild

          public static void storeChild(Project project,
                                        java.lang.Object parent,
                                        java.lang.Object child,
                                        java.lang.String tag)

      Stores a configured child element within its parent object.
      Parameters:
        `project` - Project containing the objects. May be `null`.
        `parent` - Parent object to add child to. Must not be `null`.
        `child` - Child object to store in parent. Should not be `null`.
        `tag` - Name of element which generated the child. May be `null`, in which case the child is not stored.

    - #### replaceProperties

          @Deprecated
          public static java.lang.String replaceProperties(Project project,
                                                                       java.lang.String value)
                                                                throws BuildException

      Deprecated. since 1.6.x. Use project.replaceProperties().
      Replaces `${xxx}` style constructions in the given value with the string value of the corresponding properties.
      Parameters:
        `project` - The project containing the properties to replace. Must not be `null`.
        `value` - The string to be scanned for property references. May be `null`.
      Returns:
        the original string with the properties replaced, or `null` if the original string is `null`.
      Throws:
        `BuildException` - if the string contains an opening `${` without a closing `}`
      Since:
        1.5

    - #### replaceProperties

          @Deprecated
          public static java.lang.String replaceProperties(Project project,
                                                                       java.lang.String value,
                                                                       java.util.Hashtable<java.lang.String,java.lang.Object> keys)
                                                                throws BuildException

      Deprecated. since 1.6.x. Use PropertyHelper.
      Replaces `${xxx}` style constructions in the given value with the string value of the corresponding data types.
      Parameters:
        `project` - The container project. This is used solely for logging purposes. Must not be `null`.
        `value` - The string to be scanned for property references. May be `null`, in which case this method returns immediately with no effect.
        `keys` - Mapping (String to Object) of property names to their values. Must not be `null`.
      Returns:
        the original string with the properties replaced, or `null` if the original string is `null`.
      Throws:
        `BuildException` - if the string contains an opening `${` without a closing `}`

    - #### parsePropertyString

          @Deprecated
          public static void parsePropertyString(java.lang.String value,
                                                             java.util.Vector<java.lang.String> fragments,
                                                             java.util.Vector<java.lang.String> propertyRefs)
                                                      throws BuildException

      Deprecated. since 1.6.x. Use PropertyHelper.
      Parses a string containing `${xxx}` style property references into two lists. The first list is a collection of text fragments, while the other is a set of string property names. `null` entries in the first list indicate a property reference from the second list.

      As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.

      Parameters:
        `value` - Text to parse. Must not be `null`.
        `fragments` - List to add text fragments to. Must not be `null`.
        `propertyRefs` - List to add property names to. Must not be `null`.
      Throws:
        `BuildException` - if the string contains an opening `${` without a closing `}`

    - #### genComponentName

          public static java.lang.String genComponentName(java.lang.String uri,
                                                          java.lang.String name)

      Map a namespaced {uri,name} to an internal string format. For BC purposes the names from the ant core uri will be mapped to "name", other names will be mapped to uri + ":" + name.
      Parameters:
        `uri` - The namespace URI
        `name` - The localname
      Returns:
        The stringified form of the ns name

    - #### extractUriFromComponentName

          public static java.lang.String extractUriFromComponentName(java.lang.String componentName)

      extract a uri from a component name
      Parameters:
        `componentName` - The stringified form for {uri, name}
      Returns:
        The uri or "" if not present

    - #### extractNameFromComponentName

          public static java.lang.String extractNameFromComponentName(java.lang.String componentName)

      extract the element name from a component name
      Parameters:
        `componentName` - The stringified form for {uri, name}
      Returns:
        The element name of the component

    - #### nsToComponentName

          public static java.lang.String nsToComponentName(java.lang.String ns)

      Convert an attribute namespace to a "component name".
      Parameters:
        `ns` - the xml namespace uri.
      Returns:
        the converted value.
      Since:
        Ant 1.9.1

    - #### addLocationToBuildException

          public static BuildException addLocationToBuildException(BuildException ex,
                                                                   Location newLocation)

      Add location to build exception.
      Parameters:
        `ex` - the build exception, if the build exception does not include
        `newLocation` - the location of the calling task (may be null)
      Returns:
        a new build exception based in the build exception with location set to newLocation. If the original exception did not have a location, just return the build exception

    - #### canParseAntlibDescriptor

          public boolean canParseAntlibDescriptor(Resource r)

      Whether this instance of ProjectHelper can parse an Antlib descriptor given by the URL and return its content as an UnknownElement ready to be turned into an Antlib task.

      This method should not try to parse the content of the descriptor, the URL is only given as an argument to allow subclasses to decide whether they can support a given URL scheme or not.

      Subclasses that return true in this method must also override `parseAntlibDescriptor`.

      This implementation returns false.

      Parameters:
        `r` - Resource
      Returns:
        boolean
      Since:
        Ant 1.8.0

    - #### parseAntlibDescriptor

          public UnknownElement parseAntlibDescriptor(Project containingProject,
                                                      Resource source)

      Parse the given URL as an antlib descriptor and return the content as something that can be turned into an Antlib task.
      Parameters:
        `containingProject` - Project
        `source` - Resource
      Returns:
        UnknownElement
      Since:
        ant 1.8.0

    - #### canParseBuildFile

          public boolean canParseBuildFile(Resource buildFile)

      Check if the helper supports the kind of file. Some basic check on the extension's file should be done here.
      Parameters:
        `buildFile` - the file expected to be parsed (never `null`)
      Returns:
        true if the helper supports it
      Since:
        Ant 1.8.0

    - #### getDefaultBuildFile

          public java.lang.String getDefaultBuildFile()

      The file name of the build script to be parsed if none specified on the command line
      Returns:
        the name of the default file (never `null`)
      Since:
        Ant 1.8.0

    - #### resolveExtensionOfAttributes

          public void resolveExtensionOfAttributes(Project project)
                                            throws BuildException

      Check extensionStack and inject all targets having extensionOf attributes into extensionPoint.

      This method allow you to defer injection and have a powerful control of extensionPoint wiring.

      This should be invoked by each concrete implementation of ProjectHelper when the root "buildfile" and all imported/included buildfile are loaded.

      Parameters:
        `project` - The project containing the target. Must not be `null`.
      Throws:
        `BuildException` - if OnMissingExtensionPoint.FAIL and extensionPoint does not exist
      Since:
        1.9
      See Also:
        `ProjectHelper.OnMissingExtensionPoint`