    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    }