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