diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/ProjectHelper.java')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/ProjectHelper.java | 698 |
1 files changed, 698 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/ProjectHelper.java b/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/ProjectHelper.java new file mode 100644 index 00000000..c6eaa077 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/ProjectHelper.java @@ -0,0 +1,698 @@ +/* + * 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); + } + } + + /** Default constructor */ + public ProjectHelper() { + } + + // -------------------- Common properties -------------------- + // The following properties are required by import ( and other tasks + // that read build files using ProjectHelper ). + + private Vector<Object> importStack = new Vector<Object>(); + private List<String[]> extensionStack = new LinkedList<String[]>(); + + /** + * 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<String>(); + + /** + * 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 (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 <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 || 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); + } + + /** + * 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 (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); + } + } + } +} |