/* * 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.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. *
* 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 defined types/tasks - the format is antlib: May be set by <import>'s as attribute. May be set by <import>'s prefixSeperator attribute. 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. As of Ant 1.8.0 this method is never invoked by any code
* inside of Ant itself. 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 {@link #parseAntlibDescriptor
* parseAntlibDescriptor}. This implementation returns false.null
.
* @param buildFile A build file giving the project's configuration.
* Must not be null
.
*
* @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);
}
/** Default constructor */
public ProjectHelper() {
}
// -------------------- Common properties --------------------
// The following properties are required by import ( and other tasks
// that read build files using ProjectHelper ).
private Vector importStack = new Vector();
// ----- import / extension fix
private Vector extensionStack = new Vector();
/**
* 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 getImportStack() {
return importStack;
}
// ----- import / extension fix
public Vector getExtensionStack() {
return extensionStack;
}
private final static ThreadLocal targetPrefix = new ThreadLocal() {
protected Object initialValue() {
return (String) null;
}
};
/**
* The prefix to prepend to imported target names.
*
* null
.
* @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 null
* @see #getHelpers()
*/
public static ProjectHelper getProjectHelper() {
return (ProjectHelper) 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 null
* 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 null
.
* @param attrs A list of attributes to configure within the target.
* Must not be null
.
* @param project The project containing the target.
* Must not be null
.
*
* @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.US), 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 null
.
* @param target The target object to be configured.
* Must not be null
.
* @param buf A character array of the text within the element.
* Will not be null
.
* @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 null
.
* @param target The target object to be configured.
* Must not be null
.
* @param text Text to add to the target.
* May be null
, 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 null
.
* @param parent Parent object to add child to.
* Must not be null
.
* @param child Child object to store in parent.
* Should not be null
.
* @param tag Name of element which generated the child.
* May be null
, 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 ${xxx}
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 null
.
*
* @param value The string to be scanned for property references.
* May be null
.
*
* @exception BuildException if the string contains an opening
* ${
without a closing
* }
* @return the original string with the properties replaced, or
* null
if the original string is null
.
*
* @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 ${xxx}
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 null
.
* @param value The string to be scanned for property references.
* May be null
, in which case this
* method returns immediately with no effect.
* @param keys Mapping (String to String) of property names to their
* values. Must not be null
.
*
* @exception BuildException if the string contains an opening
* ${
without a closing
* }
* @return the original string with the properties replaced, or
* null
if the original string is null
.
* @deprecated since 1.6.x.
* Use PropertyHelper.
*/
public static String replaceProperties(Project project, String value, Hashtable keys)
throws BuildException {
PropertyHelper ph = PropertyHelper.getPropertyHelper(project);
return ph.replaceProperties(null, value, keys);
}
/**
* 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.
*
* null
.
* @param fragments List to add text fragments to.
* Must not be null
.
* @param propertyRefs List to add property names to.
* Must not be null
.
*
* @deprecated since 1.6.x.
* Use PropertyHelper.
* @exception BuildException if the string contains an opening
* ${
without a closing }
*/
public static void parsePropertyString(String value, Vector fragments, Vector 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 namepace URI
* @param name The localname
* @return The stringified form of the ns name
*/
public static String genComponentName(String uri, String name) {
if (uri == null || uri.equals("") || 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);
}
/**
* 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 (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.
*
* null
)
* @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 null
)
* @since Ant 1.8.0
*/
public String getDefaultBuildFile() {
return Main.DEFAULT_BUILD_FILENAME;
}
}