/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.tools.ant;
import java.io.File;
import java.util.Hashtable;
import java.util.LinkedList;
import java.util.List;
import java.util.Locale;
import java.util.Vector;
import org.apache.tools.ant.types.Resource;
import org.apache.tools.ant.types.resources.FileResource;
import org.apache.tools.ant.util.LoaderUtils;
import org.xml.sax.AttributeList;
/**
* 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.
* <p>
* This class also provide static wrappers for common introspection.
*/
public class ProjectHelper {
/** The URI for ant name space */
public static final String ANT_CORE_URI = "antlib:org.apache.tools.ant";
/** The URI for antlib current definitions */
public static final String ANT_CURRENT_URI = "ant:current";
/** The URI for ant specific attributes
* @since Ant 1.9.1
* */
public static final String ANT_ATTRIBUTE_URI = "ant:attribute";
/** The URI for defined types/tasks - the format is antlib:<package> */
public static final String ANTLIB_URI = "antlib:";
/** Polymorphic attribute */
public static final String ANT_TYPE = "ant-type";
/**
* Name of JVM system property which provides the name of the
* ProjectHelper class to use.
*/
public static final String HELPER_PROPERTY = MagicNames.PROJECT_HELPER_CLASS;
/**
* The service identifier in jars which provide Project Helper
* implementations.
*/
public static final String SERVICE_ID = MagicNames.PROJECT_HELPER_SERVICE;
/**
* name of project helper reference that we add to a project
*/
public static final String PROJECTHELPER_REFERENCE = MagicNames.REFID_PROJECT_HELPER;
/**
* constant to denote use project name as target prefix
* @since Ant 1.9.1
*/
public static final String USE_PROJECT_NAME_AS_TARGET_PREFIX = "USE_PROJECT_NAME_AS_TARGET_PREFIX";
/**
* Configures the project with the contents of the specified build file.
*
* @param project The project to configure. Must not be <code>null</code>.
* @param buildFile A build file giving the project's configuration.
* Must not be <code>null</code>.
*
* @exception BuildException if the configuration is invalid or cannot be read
*/
public static void configureProject(Project project, File buildFile) throws BuildException {
FileResource resource = new FileResource(buildFile);
ProjectHelper helper = ProjectHelperRepository.getInstance().getProjectHelperForBuildFile(resource);
project.addReference(PROJECTHELPER_REFERENCE, helper);
helper.parse(project, buildFile);
}
/**
* Possible value for target's onMissingExtensionPoint attribute. It determines how to deal with
* targets that want to extend missing extension-points.
* <p>
* This class behaves like a Java 1.5 Enum class.
*
* @since 1.8.2
*/
public static final class OnMissingExtensionPoint {
/** fail if the extension-point is not defined */
public static final OnMissingExtensionPoint FAIL = new OnMissingExtensionPoint(
"fail");
/** warn if the extension-point is not defined */
public static final OnMissingExtensionPoint WARN = new OnMissingExtensionPoint(
"warn");
/** ignore the extensionOf attribute if the extension-point is not defined */
public static final OnMissingExtensionPoint IGNORE = new OnMissingExtensionPoint(
"ignore");
private static final OnMissingExtensionPoint[] values = new OnMissingExtensionPoint[] {
FAIL, WARN, IGNORE };
private final String name;
private OnMissingExtensionPoint(String name) {
this.name = name;
}
public String name() {
return name;
}
public String toString() {
return name;
}
public static OnMissingExtensionPoint valueOf(String name) {
if (name == null) {
throw new NullPointerException();
}
for (int i = 0; i < values.length; i++) {
if (name.equals(values[i].name())) {
return values[i];
}
}
throw new IllegalArgumentException(
"Unknown onMissingExtensionPoint " + name);
}
}
// -------------------- Common properties --------------------
// The following properties are required by import ( and other tasks
// that read build files using ProjectHelper ).
private Vector<Object> importStack = new Vector<>();
private List<String[]> extensionStack = new LinkedList<>();
/**
* Import stack.
* Used to keep track of imported files. Error reporting should
* display the import path.
*
* @return the stack of import source objects.
*/
public Vector<Object> getImportStack() {
return importStack;
}
/**
* Extension stack.
* Used to keep track of targets that extend extension points.
*
* @return 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
* {@link OnMissingExtensionPoint}.
*/
public List<String[]> getExtensionStack() {
return extensionStack;
}
private static final ThreadLocal<String> targetPrefix = new ThreadLocal<>();
/**
* The prefix to prepend to imported target names.
*
* <p>May be set by <import>'s as attribute.</p>
*
* @return the configured prefix or null
*
* @since Ant 1.8.0
*/
public static String getCurrentTargetPrefix() {
return targetPrefix.get();
}
/**
* Sets the prefix to prepend to imported target names.
*
* @since Ant 1.8.0
*/
public static void setCurrentTargetPrefix(String prefix) {
targetPrefix.set(prefix);
}
private static final ThreadLocal<String> prefixSeparator = new ThreadLocal<String>() {
protected String initialValue() {
return ".";
}
};
/**
* The separator between the prefix and the target name.
*
* <p>May be set by <import>'s prefixSeparator attribute.</p>
*
* @since Ant 1.8.0
*/
public static String getCurrentPrefixSeparator() {
return prefixSeparator.get();
}
/**
* Sets the separator between the prefix and the target name.
*
* @since Ant 1.8.0
*/
public static void setCurrentPrefixSeparator(String sep) {
prefixSeparator.set(sep);
}
private static final ThreadLocal<Boolean> inIncludeMode = new ThreadLocal<Boolean>() {
protected Boolean initialValue() {
return Boolean.FALSE;
}
};
/**
* Whether the current file should be read in include as opposed
* to import mode.
*
* <p>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.</p>
*
* <p>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.</p>
*
* @since Ant 1.8.0
*/
public static boolean isInIncludeMode() {
return Boolean.TRUE.equals(inIncludeMode.get());
}
/**
* Sets whether the current file should be read in include as
* opposed to import mode.
*
* @since Ant 1.8.0
*/
public static void setInIncludeMode(boolean includeMode) {
inIncludeMode.set(Boolean.valueOf(includeMode));
}
// -------------------- Parse method --------------------
/**
* Parses the project file, configuring the project as it goes.
*
* @param project The project for the resulting ProjectHelper to configure.
* Must not be <code>null</code>.
* @param 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.
*
* @since Ant1.5
* @exception BuildException if the configuration is invalid or cannot
* be read
*/
public void parse(Project project, Object source) throws BuildException {
throw new BuildException("ProjectHelper.parse() must be implemented "
+ "in a helper plugin " + this.getClass().getName());
}
/**
* Get the first project helper found in the classpath
*
* @return an project helper, never <code>null</code>
* @see org.apache.tools.ant.ProjectHelperRepository#getHelpers()
*/
public static ProjectHelper getProjectHelper() {
return ProjectHelperRepository.getInstance().getHelpers().next();
}
/**
* JDK1.1 compatible access to the context class loader. Cut & paste from JAXP.
*
* @deprecated since 1.6.x.
* Use LoaderUtils.getContextClassLoader()
*
* @return the current context class loader, or <code>null</code>
* if the context class loader is unavailable.
*/
public static ClassLoader getContextClassLoader() {
return LoaderUtils.isContextLoaderAvailable() ? LoaderUtils.getContextClassLoader() : null;
}
// -------------------- Static utils, used by most helpers ----------------
/**
* Configures an object using an introspection handler.
*
* @param target The target object to be configured.
* Must not be <code>null</code>.
* @param attrs A list of attributes to configure within the target.
* Must not be <code>null</code>.
* @param project The project containing the target.
* Must not be <code>null</code>.
*
* @deprecated since 1.6.x.
* Use IntrospectionHelper for each property.
*
* @exception BuildException if any of the attributes can't be handled by
* the target
*/
public static void configure(Object target, AttributeList attrs,
Project project) throws BuildException {
if (target instanceof TypeAdapter) {
target = ((TypeAdapter) target).getProxy();
}
IntrospectionHelper ih = IntrospectionHelper.getHelper(project, target.getClass());
for (int i = 0, length = attrs.getLength(); i < length; i++) {
// reflect these into the target
String value = replaceProperties(project, attrs.getValue(i), project.getProperties());
try {
ih.setAttribute(project, target, attrs.getName(i).toLowerCase(Locale.ENGLISH), value);
} catch (BuildException be) {
// id attribute must be set externally
if (!attrs.getName(i).equals("id")) {
throw be;
}
}
}
}
/**
* Adds the content of #PCDATA sections to an element.
*
* @param project The project containing the target.
* Must not be <code>null</code>.
* @param target The target object to be configured.
* Must not be <code>null</code>.
* @param buf A character array of the text within the element.
* Will not be <code>null</code>.
* @param start The start element in the array.
* @param count The number of characters to read from the array.
*
* @exception BuildException if the target object doesn't accept text
*/
public static void addText(Project project, Object target, char[] buf,
int start, int count) throws BuildException {
addText(project, target, new String(buf, start, count));
}
/**
* Adds the content of #PCDATA sections to an element.
*
* @param project The project containing the target.
* Must not be <code>null</code>.
* @param target The target object to be configured.
* Must not be <code>null</code>.
* @param text Text to add to the target.
* May be <code>null</code>, in which case this
* method call is a no-op.
*
* @exception BuildException if the target object doesn't accept text
*/
public static void addText(Project project, Object target, String text)
throws BuildException {
if (text == null) {
return;
}
if (target instanceof TypeAdapter) {
target = ((TypeAdapter) target).getProxy();
}
IntrospectionHelper.getHelper(project, target.getClass()).addText(project, target, text);
}
/**
* Stores a configured child element within its parent object.
*
* @param project Project containing the objects.
* May be <code>null</code>.
* @param parent Parent object to add child to.
* Must not be <code>null</code>.
* @param child Child object to store in parent.
* Should not be <code>null</code>.
* @param tag Name of element which generated the child.
* May be <code>null</code>, in which case
* the child is not stored.
*/
public static void storeChild(Project project, Object parent, Object child, String tag) {
IntrospectionHelper ih = IntrospectionHelper.getHelper(project, parent.getClass());
ih.storeElement(project, parent, child, tag);
}
/**
* Replaces <code>${xxx}</code> style constructions in the given value with
* the string value of the corresponding properties.
*
* @param project The project containing the properties to replace.
* Must not be <code>null</code>.
*
* @param value The string to be scanned for property references.
* May be <code>null</code>.
*
* @exception BuildException if the string contains an opening
* <code>${</code> without a closing
* <code>}</code>
* @return the original string with the properties replaced, or
* <code>null</code> if the original string is <code>null</code>.
*
* @deprecated since 1.6.x.
* Use project.replaceProperties().
* @since 1.5
*/
public static String replaceProperties(Project project, String value) throws BuildException {
// needed since project properties are not accessible
return project.replaceProperties(value);
}
/**
* Replaces <code>${xxx}</code> style constructions in the given value
* with the string value of the corresponding data types.
*
* @param project The container project. This is used solely for
* logging purposes. Must not be <code>null</code>.
* @param value The string to be scanned for property references.
* May be <code>null</code>, in which case this
* method returns immediately with no effect.
* @param keys Mapping (String to Object) of property names to their
* values. Must not be <code>null</code>.
*
* @exception BuildException if the string contains an opening
* <code>${</code> without a closing
* <code>}</code>
* @return the original string with the properties replaced, or
* <code>null</code> if the original string is <code>null</code>.
* @deprecated since 1.6.x.
* Use PropertyHelper.
*/
public static String replaceProperties(Project project, String value, Hashtable<String, Object> keys)
throws BuildException {
PropertyHelper ph = PropertyHelper.getPropertyHelper(project);
return ph.replaceProperties(null, value, keys);
}
/**
* Parses a string containing <code>${xxx}</code> 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.
* <code>null</code> entries in the first list indicate a property
* reference from the second list.
*
* <p>As of Ant 1.8.0 this method is never invoked by any code
* inside of Ant itself.</p>
*
* @param value Text to parse. Must not be <code>null</code>.
* @param fragments List to add text fragments to.
* Must not be <code>null</code>.
* @param propertyRefs List to add property names to.
* Must not be <code>null</code>.
*
* @deprecated since 1.6.x.
* Use PropertyHelper.
* @exception BuildException if the string contains an opening
* <code>${</code> without a closing <code>}</code>
*/
public static void parsePropertyString(String value, Vector<String> fragments, Vector<String> propertyRefs)
throws BuildException {
PropertyHelper.parsePropertyStringDefault(value, fragments, propertyRefs);
}
/**
* 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.
* @param uri The namespace URI
* @param name The localname
* @return The stringified form of the ns name
*/
public static String genComponentName(String uri, String name) {
if (uri == null || "".equals(uri) || uri.equals(ANT_CORE_URI)) {
return name;
}
return uri + ":" + name;
}
/**
* extract a uri from a component name
*
* @param componentName The stringified form for {uri, name}
* @return The uri or "" if not present
*/
public static String extractUriFromComponentName(String componentName) {
if (componentName == null) {
return "";
}
int index = componentName.lastIndexOf(':');
if (index == -1) {
return "";
}
return componentName.substring(0, index);
}
/**
* extract the element name from a component name
*
* @param componentName The stringified form for {uri, name}
* @return The element name of the component
*/
public static String extractNameFromComponentName(String componentName) {
int index = componentName.lastIndexOf(':');
if (index == -1) {
return componentName;
}
return componentName.substring(index + 1);
}
/**
* Convert an attribute namespace to a "component name".
* @param ns the xml namespace uri.
* @return the converted value.
* @since Ant 1.9.1
*/
public static String nsToComponentName(String ns) {
return "attribute namespace:" + ns;
}
/**
* Add location to build exception.
* @param ex the build exception, if the build exception
* does not include
* @param newLocation the location of the calling task (may be null)
* @return 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
*/
public static BuildException addLocationToBuildException(
BuildException ex, Location newLocation) {
if (ex.getLocation() == null || ex.getMessage() == null) {
return ex;
}
String errorMessage
= "The following error occurred while executing this line:"
+ System.getProperty("line.separator")
+ ex.getLocation().toString()
+ ex.getMessage();
if (ex instanceof ExitStatusException) {
int exitStatus = ((ExitStatusException) ex).getStatus();
if (newLocation == null) {
return new ExitStatusException(errorMessage, exitStatus);
}
return new ExitStatusException(errorMessage, exitStatus, newLocation);
}
if (newLocation == null) {
return new BuildException(errorMessage, ex);
}
return new BuildException(errorMessage, ex, newLocation);
}
/**
* 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.
*
* <p>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.</p>
*
* <p>Subclasses that return true in this method must also
* override {@link #parseAntlibDescriptor
* parseAntlibDescriptor}.</p>
*
* <p>This implementation returns false.</p>
*
* @since Ant 1.8.0
*/
public boolean canParseAntlibDescriptor(Resource r) {
return false;
}
/**
* Parse the given URL as an antlib descriptor and return the
* content as something that can be turned into an Antlib task.
*
* @since ant 1.8.0
*/
public UnknownElement parseAntlibDescriptor(Project containingProject,
Resource source) {
throw new BuildException("can't parse antlib descriptors");
}
/**
* Check if the helper supports the kind of file. Some basic check on the
* extension's file should be done here.
*
* @param buildFile
* the file expected to be parsed (never <code>null</code>)
* @return true if the helper supports it
* @since Ant 1.8.0
*/
public boolean canParseBuildFile(Resource buildFile) {
return true;
}
/**
* The file name of the build script to be parsed if none specified on the command line
*
* @return the name of the default file (never <code>null</code>)
* @since Ant 1.8.0
*/
public String getDefaultBuildFile() {
return Main.DEFAULT_BUILD_FILENAME;
}
/**
* Check extensionStack and inject all targets having extensionOf attributes
* into extensionPoint.
* <p>
* This method allow you to defer injection and have a powerful control of
* extensionPoint wiring.
* </p>
* <p>
* This should be invoked by each concrete implementation of ProjectHelper
* when the root "buildfile" and all imported/included buildfile are loaded.
* </p>
*
* @param project The project containing the target. Must not be
* <code>null</code>.
* @exception BuildException if OnMissingExtensionPoint.FAIL and
* extensionPoint does not exist
* @see OnMissingExtensionPoint
* @since 1.9
*/
public void resolveExtensionOfAttributes(Project project)
throws BuildException {
for (String[] extensionInfo : getExtensionStack()) {
String extPointName = extensionInfo[0];
String targetName = extensionInfo[1];
OnMissingExtensionPoint missingBehaviour = OnMissingExtensionPoint.valueOf(extensionInfo[2]);
// if the file has been included or imported, it may have a prefix
// we should consider when trying to resolve the target it is
// extending
String prefixAndSep = extensionInfo.length > 3 ? extensionInfo[3] : null;
// find the target we're extending
Hashtable<String, Target> projectTargets = project.getTargets();
Target extPoint = null;
if (prefixAndSep == null) {
// no prefix - not from an imported/included build file
extPoint = projectTargets.get(extPointName);
} else {
// we have a prefix, which means we came from an include/import
// FIXME: here we handle no particular level of include. We try
// the fully prefixed name, and then the non-prefixed name. But
// there might be intermediate project in the import stack,
// which prefix should be tested before testing the non-prefix
// root name.
extPoint = projectTargets.get(prefixAndSep + extPointName);
if (extPoint == null) {
extPoint = projectTargets.get(extPointName);
}
}
// make sure we found a point to extend on
if (extPoint == null) {
String message = "can't add target " + targetName
+ " to extension-point " + extPointName
+ " because the extension-point is unknown.";
if (missingBehaviour == OnMissingExtensionPoint.FAIL) {
throw new BuildException(message);
} else if (missingBehaviour == OnMissingExtensionPoint.WARN) {
Target t = projectTargets.get(targetName);
project.log(t, "Warning: " + message, Project.MSG_WARN);
}
} else {
if (!(extPoint instanceof ExtensionPoint)) {
throw new BuildException("referenced target " + extPointName
+ " is not an extension-point");
}
extPoint.addDependency(targetName);
}
}
}
}