## 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 XML build file. It'll rely on a plugin to do the actual processing of the xml file. This class also provide static wrappers for common introspection. All helper plugins must provide backward compatibility with the original ant patterns, unless a different behavior is explicitly specified. For example, if namespace is used on the <project> tag the helper can expect the entire build file to be namespace-enabled. Namespaces or helper-specific tags can provide meta-information to the helper, allowing it to use new ( or different policies ). However, if no namespace is used the behavior should be exactly identical with the default helper.

Author:
  duncan@x180.com

Field Summary
`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` `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` `SERVICE_ID` The service identifier in jars which provide Project Helper implementations.

Constructor Summary
`ProjectHelper()` Default constructor

Method Summary
`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.
`static void` `configure(java.lang.Object target, org.xml.sax.AttributeList attrs, Project project)` Deprecated. Use IntrospectionHelper for each property
`static void` `configureProject(Project project, java.io.File buildFile)` Deprecated. Use the non-static parse method
`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. Use LoaderUtils.getContextClassLoader()
`java.util.Vector` `getImportStack()` EXPERIMENTAL WILL_CHANGE Import stack.
`static ProjectHelper` `getProjectHelper()` Discovers a project helper instance.
`void` `parse(Project project, java.lang.Object source)` Parses the project file, configuring the project as it goes.
`static void` `parsePropertyString(java.lang.String value, java.util.Vector fragments, java.util.Vector propertyRefs)` Deprecated. Use PropertyHelper
`static java.lang.String` `replaceProperties(Project project, java.lang.String value)` Deprecated. Use project.replaceProperties()
`static java.lang.String` `replaceProperties(Project project, java.lang.String value, java.util.Hashtable keys)` Deprecated. Use PropertyHelper
`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

### 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

### 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

Constructor Detail

### ProjectHelper

    public ProjectHelper()

  Default constructor

Method Detail

### configureProject

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

  Deprecated. Use the non-static parse method

  Configures the project with the contents of the specified XML file.

  Parameters:
    `project` - The project to configure. Must not be `null`.
    `buildFile` - An XML 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 getImportStack()

  EXPERIMENTAL WILL_CHANGE Import stack. Used to keep track of imported files. Error reporting should display the import path.

  Returns:
    the stack of import source objects.

### 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()
                                          throws BuildException

  Discovers a project helper instance. Uses the same patterns as JAXP, commons-logging, etc: a system property, a JDK1.3 service discovery, default.

  Returns:
    a ProjectHelper, either a custom implementation if one is available and configured, or the default implementation otherwise.
  Throws:
    `BuildException` - if a specified helper class cannot be loaded/instantiated.

### getContextClassLoader

    public static java.lang.ClassLoader getContextClassLoader()

  Deprecated. 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

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

  Deprecated. 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

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

  Deprecated. 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

    public static java.lang.String replaceProperties(Project project,
                                                     java.lang.String value,
                                                     java.util.Hashtable keys)
                                              throws BuildException

  Deprecated. 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 String) 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

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

  Deprecated. 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.

  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 namepace 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

### 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

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.