classpathutils.java

Use the links below to download a source distribution of Ant from one of our mirrors. It is good pra

     *
     * @param className the full qualified class name to load.
     * @param userDefinedLoader the classloader to use.
     * @param expectedType the Class that the result should be assignment
     * compatible with. (No ClassCastException will be thrown in case
     * the result of this method is casted to the expectedType)
     * @return The fresh object instance
     * @throws BuildException when loading or instantiation failed.
     * @since Ant 1.7
     */
    public static Object newInstance(
        String className,
        ClassLoader userDefinedLoader,
        Class expectedType) {
        try {
            Class clazz = Class.forName(className, true, userDefinedLoader);
            Object o = clazz.newInstance();
            if (!expectedType.isInstance(o)) {
                throw new BuildException(
                    "Class of unexpected Type: "
                        + className
                        + " expected :"
                        + expectedType);
            }
            return o;
        } catch (ClassNotFoundException e) {
            throw new BuildException(
                "Class not found: "
                    + className,
                e);
        } catch (InstantiationException e) {
            throw new BuildException(
                "Could not instantiate "
                    + className
                    + ". Specified class should have a no "
                    + "argument constructor.",
                e);
        } catch (IllegalAccessException e) {
            throw new BuildException(
                "Could not instantiate "
                    + className
                    + ". Specified class should have a "
                    + "public constructor.",
                e);
        } catch (LinkageError e) {
            throw new BuildException(
                "Class "
                    + className
                    + " could not be loaded because of an invalid dependency.",
                e);
        }
    }

    /**
     * Obtains a delegate that helps out with classic classpath configuration.
     *
     * @param component your projectComponent that needs the assistence
     * @return the helper, delegate.
     * @see ClasspathUtils.Delegate
     */
    public static Delegate getDelegate(ProjectComponent component) {
        return new Delegate(component);
    }

    /**
     * Checks for the magic property that enables class loader reuse
     * for <taskdef> and <typedef> in Ant 1.5 and earlier.
     */
    private static boolean isMagicPropertySet(Project p) {
        return p.getProperty(REUSE_LOADER_REF) != null;
    }

    /**
     * Delegate that helps out any specific ProjectComponent that needs
     * dynamic classloading.
     *
     * <p>Ant ProjectComponents that need a to be able to dynamically load
     * Classes and instantiate them often expose the following ant syntax
     * sugar: </p>
     *
     * <ul><li> nested &lt;classpath&gt; </li>
     * <li> attribute @classpathref </li>
     * <li> attribute @classname </li></ul>
     *
     * <p> This class functions as a delegate handling the configuration
     * issues for this recurring pattern.  Its usage pattern, as the name
     * suggests, is delegation rather than inheritance. </p>
     *
     * @since Ant 1.6
     */
    public static class Delegate {
        private final ProjectComponent component;
        private Path classpath;
        private String classpathId;
        private String className;
        private String loaderId;
        private boolean reverseLoader = false;

        /**
         * Construct a Delegate
         * @param component the ProjectComponent this delegate is for.
         */
        Delegate(ProjectComponent component) {
            this.component = component;
        }

        /**
         * This method is a Delegate method handling the @classpath attribute.
         *
         * <p>This attribute can set a path to add to the classpath.</p>
         *
         * @param classpath the path to use for the classpath.
         */
        public void setClasspath(Path classpath) {
            if (this.classpath == null) {
                this.classpath = classpath;
            } else {
                this.classpath.append(classpath);
            }
        }

        /**
         * Delegate method handling the &lt;classpath&gt; tag.
         *
         * <p>This nested path-like structure can set a path to add to the
         * classpath.</p>
         *
         * @return the created path.
         */
        public Path createClasspath() {
            if (this.classpath == null) {
                this.classpath = new Path(component.getProject());
            }
            return this.classpath.createPath();
        }

        /**
         * Delegate method handling the @classname attribute.
         *
         * <p>This attribute sets the full qualified class name of the class
         * to load and instantiate.</p>
         *
         * @param fcqn the name of the class to load.
         */
        public void setClassname(String fcqn) {
            this.className = fcqn;
        }

        /**
         * Delegate method handling the @classpathref attribute.
         *
         * <p>This attribute can add a referenced path-like structure to the
         * classpath.</p>
         *
         * @param r the reference to the classpath.
         */
        public void setClasspathref(Reference r) {
            this.classpathId = r.getRefId();
            createClasspath().setRefid(r);
        }

        /**
         * Delegate method handling the @reverseLoader attribute.
         *
         * <p>This attribute can set a boolean indicating that the used
         * classloader should NOT follow the classical parent-first scheme.
         * </p>
         *
         * <p>By default this is supposed to be false.</p>
         *
         * <p>Caution: this behaviour is contradictory to the normal way
         * classloaders work.  Do not let your ProjectComponent use it if
         * you are not really sure.</p>
         *
         * @param reverseLoader if true reverse the order of looking up a class.
         */
        public void setReverseLoader(boolean reverseLoader) {
            this.reverseLoader = reverseLoader;
        }

        /**
         * Sets the loaderRef.
         * @param r the reference to the loader.
         */
        public void setLoaderRef(Reference r) {
            this.loaderId = r.getRefId();
        }


        /**
         * Finds or creates the classloader for this object.
         * @return The class loader.
         */
        public ClassLoader getClassLoader() {
            return getClassLoaderForPath(
                    getContextProject(),
                    this.classpath,
                    getClassLoadId(),
                    this.reverseLoader,
                    loaderId != null || isMagicPropertySet(getContextProject()));
        }

        /**
         * The project of the ProjectComponent we are working for.
         */
        private Project getContextProject() {
            return this.component.getProject();
        }

        /**
         * Computes the loaderId based on the configuration of the component.
         * @return a loader identifier.
         */
        public String getClassLoadId() {
            return this.loaderId == null && this.classpathId != null
                ? MagicNames.REFID_CLASSPATH_LOADER_PREFIX + this.classpathId
                : this.loaderId;
        }

        /**
         * Helper method obtaining a fresh instance of the class specified
         * in the @classname and using the specified classpath.
         *
         * @return the fresh instantiated object.
         */
        public Object newInstance() {
            return ClasspathUtils.newInstance(this.className, getClassLoader());
        }

        /**
         * The classpath.
         * @return the classpath.
         */
        public Path getClasspath() {
            return classpath;
        }

        /**
         * Get the reverseLoader setting.
         * @return true if looking up in reverse order.
         */
        public boolean isReverseLoader() {
            return reverseLoader;
        }

        //TODO no methods yet for getClassname
        //TODO no method for newInstance using a reverse-classloader
    }
}