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