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.ioc.internal;
016
017 import java.util.Collection;
018 import java.util.Set;
019
020 import org.apache.tapestry5.ioc.AdvisorDef;
021 import org.apache.tapestry5.ioc.ModuleBuilderSource;
022 import org.apache.tapestry5.ioc.def.ContributionDef2;
023 import org.apache.tapestry5.ioc.def.DecoratorDef;
024 import org.apache.tapestry5.ioc.def.ServiceDef;
025 import org.apache.tapestry5.ioc.def.ServiceDef3;
026
027 /**
028 * A module within the Tapestry IoC registry. Each Module is constructed around a corresponding module builder instance;
029 * the methods and annotations of that instance define the services provided by the module.
030 */
031 public interface Module extends ModuleBuilderSource
032 {
033 /**
034 * Locates a service given a service id and the corresponding service interface type.
035 *
036 * @param <T>
037 * @param serviceId
038 * identifies the service to access
039 * @param serviceInterface
040 * the interface the service implements
041 * @return the service's proxy
042 * @throws RuntimeException
043 * if there is an error instantiating the service proxy
044 */
045 <T> T getService(String serviceId, Class<T> serviceInterface);
046
047 /**
048 * Locates the ids of all services that implement the provided service interface, or whose service interface is
049 * assignable to the provided service interface (is a super-class or super-interface).
050 *
051 * @param serviceInterface
052 * the interface to search for
053 * @return a collection of service ids
054 */
055 Collection<String> findServiceIdsForInterface(Class serviceInterface);
056
057 /**
058 * Iterates over any decorator definitions defined by the module and returns those that apply to the provided
059 * service definition.
060 *
061 * @param serviceDef
062 * for which decorators are being assembled
063 * @return set of decorators, possibly empty (but not null)
064 */
065 Set<DecoratorDef> findMatchingDecoratorDefs(ServiceDef serviceDef);
066
067 /**
068 * Iterates over any advisor definitions defined by the module and returns those that apply to the provided service
069 * definition.
070 *
071 * @param serviceDef
072 * for which advisors are being assembled
073 * @return set of advisors, possibly empty but not null
074 * @since 5.1.0.0
075 */
076 Set<AdvisorDef> findMatchingServiceAdvisors(ServiceDef serviceDef);
077
078 /**
079 * Finds any contributions that are targeted at the indicated service.
080 */
081 Set<ContributionDef2> getContributorDefsForService(ServiceDef serviceDef);
082
083 /**
084 * Locates services with the {@link org.apache.tapestry5.ioc.annotations.EagerLoad} annotation and generates proxies
085 * for them, then adds them to the proxies list for instantiation.
086 *
087 * @param proxies
088 * collection of proxies to which any eager load services in the module should be added
089 */
090 void collectEagerLoadServices(Collection<EagerLoadServiceProxy> proxies);
091
092 /**
093 * Returns the service definition for the given service id.
094 *
095 * @param serviceId
096 * unique id for the service (caseless)
097 * @return the service definition or null
098 */
099 ServiceDef3 getServiceDef(String serviceId);
100
101 /**
102 * Returns the name used to obtain a logger for the module. Services within the module suffix this with a period and
103 * the service id.
104 *
105 * @return module logger name
106 */
107 String getLoggerName();
108 }