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
015package org.apache.tapestry5.ioc.internal;
016
017import org.apache.tapestry5.commons.*;
018import org.apache.tapestry5.ioc.OperationTracker;
019import org.apache.tapestry5.ioc.Registry;
020import org.apache.tapestry5.ioc.ServiceAdvisor;
021import org.apache.tapestry5.ioc.ServiceDecorator;
022import org.apache.tapestry5.ioc.ServiceLifecycle2;
023import org.apache.tapestry5.ioc.def.ServiceDef3;
024import org.apache.tapestry5.ioc.services.RegistryShutdownHub;
025import org.slf4j.Logger;
026
027import java.util.Collection;
028import java.util.List;
029import java.util.Map;
030import java.util.Set;
031
032/**
033 * Internal view of the module registry, adding additional methods needed by modules.
034 */
035public interface InternalRegistry extends Registry, RegistryShutdownHub, OperationTracker
036{
037    /**
038     * As with {@link org.apache.tapestry5.ioc.Registry#getObject(Class, org.apache.tapestry5.commons.AnnotationProvider)},
039     * but handles the {@link org.apache.tapestry5.ioc.annotations.Local} annotation.
040     *
041     * @param objectType         type of object o be injected
042     * @param annotationProvider access to annotations at point of injection
043     * @param locator            used to resolve any subsequent injections
044     * @param localModule        module to limit services to, if Local annotaton present
045     * @return the service or object
046     */
047    <T> T getObject(Class<T> objectType, AnnotationProvider annotationProvider, ObjectLocator locator,
048                    Module localModule);
049
050    /**
051     * Returns a service lifecycle by service scope name.
052     *
053     * @param scope the name of the service scope (case insensitive)
054     * @return the lifecycle corresponding to the scope
055     * @throws RuntimeException if the lifecycle name does not match a known lifecycle
056     */
057    ServiceLifecycle2 getServiceLifecycle(String scope);
058
059    /**
060     * Searches for decorators for a particular service. The resulting {@link org.apache.tapestry5.ioc.def.DecoratorDef}
061     * s
062     * are ordered, then converted into {@link ServiceDecorator}s.
063     */
064    List<ServiceDecorator> findDecoratorsForService(ServiceDef3 serviceDef);
065
066    /**
067     * Searches for advisors for a particular service, returning them in order of application.
068     *
069     * @since 5.1.0.0
070     */
071    List<ServiceAdvisor> findAdvisorsForService(ServiceDef3 serviceDef);
072
073    /**
074     * Builds up an unordered collection by invoking service contributor methods that target the service (from any
075     * module, unless the service is private).
076     *
077     * @param <T>
078     * @param serviceDef defines the service for which configuration data is being assembled
079     * @param valueType  identifies the type of object allowed into the collection
080     * @return the final collection
081     */
082    <T> Collection<T> getUnorderedConfiguration(ServiceDef3 serviceDef, Class<T> valueType);
083
084    /**
085     * Builds up an ordered collection by invoking service contributor methods that target the service (from any module,
086     * unless the service is private). Once all values have been added (each with an id, and pre/post constraints), the
087     * values are ordered, null values dropped, and the final sorted list is returned.
088     *
089     * @param <T>
090     * @param serviceDef defines the service for which configuration data is being assembled
091     * @param valueType  identifies the type of object allowed into the collection
092     * @return the final ordered list
093     */
094    <T> List<T> getOrderedConfiguration(ServiceDef3 serviceDef, Class<T> valueType);
095
096    /**
097     * Builds up a map of key/value pairs by invoking service contribution methods that target the service (from any
098     * module, unless the service is private). Values and keys may not be null. Invalid values (keys or values that are
099     * the wrong type, or duplicate keys) result in warnings and are ignored.
100     *
101     * @param <K>
102     * @param <V>
103     * @param serviceDef defines the service for which configuration data is being assembled
104     * @param keyType    identifies the type of key object allowed into the map
105     * @param valueType  identifies the type of value object allowed into the map
106     * @return the final ordered list
107     */
108    <K, V> Map<K, V> getMappedConfiguration(ServiceDef3 serviceDef, Class<K> keyType, Class<V> valueType);
109
110
111    /**
112     * Given an input string that <em>may</em> contain symbols, returns the string with any and all symbols fully
113     * expanded.
114     *
115     * @param input
116     * @return expanded input
117     */
118    String expandSymbols(String input);
119
120    /**
121     * Returns a logger for the service, which consists of the Module's {@link Module#getLoggerName() log name} suffixed
122     * with a period and the service id.
123     *
124     * @param serviceId
125     * @return the logger for the service
126     */
127    Logger getServiceLogger(String serviceId);
128
129    /**
130     * Creates a just-in-time (and possibly, live reloading) proxy for the indicated class and interface, using the
131     * provided locator to autobuild the implementationClass (when necessary).
132     *
133     * @since 5.2.0
134     */
135    <T> T proxy(Class<T> interfaceClass, Class<? extends T> implementationClass, ObjectLocator locator);
136
137    /**
138     * Returns a Set of Annotation classes that are used as service markers.
139     *
140     * @since 5.2.0
141     */
142    Set<Class> getMarkerAnnotations();
143}