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