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 }