    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}