    001    // Copyright 2006, 2007, 2008, 2009, 2011 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.internal.services;
    016
    017    import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    018    import org.apache.tapestry5.ioc.services.ClassFactory;
    019    import org.apache.tapestry5.ioc.services.PlasticProxyFactory;
    020    import org.apache.tapestry5.services.transform.ControlledPackageType;
    021
    022    /**
    023     * Creates {@link org.apache.tapestry5.internal.services.Instantiator}s for components, based on component class name.
    024     * This will involve transforming the component's class before it is loaded.
    025     * <p/>
    026     * In addition, a source acts as an event hub for {@link org.apache.tapestry5.services.InvalidationListener}s, so that
    027     * any information derived from loaded classes can be discarded and rebuilt when classes change.
    028     * <p/>
    029     * The strategy used is that when <em>any</em> class (in a controlled package) changes, the entire class loader is
    030     * discarded, along with any instances derived from those classes. A new class loader is created, and then invalidation
    031     * events are fired to listeners.
    032     * <p/>
    033     * Starting in Tapestry 5.3, the packages that are loaded are controlled by a configuration that maps package names to
    034     * {@link ControlledPackageType}s.
    035     */
    036    @UsesMappedConfiguration(key = String.class, value = ControlledPackageType.class)
    037    public interface ComponentInstantiatorSource
    038    {
    039
    040        /**
    041         * Given the name of a component class, provides an instantiator for that component. Instantiators are cached, so
    042         * repeated calls to this method with the same class name will return the same instance; however, callers should
    043         * also be aware that the instantiators may lose validity after an invalidation (caused by changes to external Java
    044         * class files).
    045         *
    046         * @param classname FQCN to find (and perhaps transform and load)
    047         * @return an object which can instantiate an instance of the component
    048         */
    049        Instantiator getInstantiator(String classname);
    050
    051        /**
    052         * Checks to see if a fully qualified class name exists. This method appears to exist only for testing.
    053         *
    054         * @param className name of class to check
    055         * @return true if the class exists (there's a ".class" file), false otherwise
    056         */
    057        boolean exists(String className);
    058
    059        /**
    060         * Returns a class factory that can be used to generate additional classes around enhanced classes, or create
    061         * subclasses of enhanced classes.
    062         *
    063         * @deprecated Deprecated in 5.3, to be removed in 5.4
    064         */
    065        ClassFactory getClassFactory();
    066
    067        /**
    068         * Returns a proxy factory that can be used to generate additional classes around enhanced classes, or create
    069         * subclasses of enhanced classes.
    070         *
    071         * @since 5.3
    072         */
    073        PlasticProxyFactory getProxyFactory();
    074
    075        /**
    076         * Forces invalidation logic, as if a component class on the disk had changed, forcing a reload
    077         * of all pages and components.
    078         *
    079         * @since 5.3
    080         */
    081        void forceComponentInvalidation();
    082    }