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 java.util.Collection;
018import java.util.Set;
019
020import org.apache.tapestry5.ioc.AdvisorDef;
021import org.apache.tapestry5.ioc.ModuleBuilderSource;
022import org.apache.tapestry5.ioc.def.ContributionDef2;
023import org.apache.tapestry5.ioc.def.DecoratorDef;
024import org.apache.tapestry5.ioc.def.ServiceDef;
025import 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 */
031public 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}