    001    // Copyright 2006, 2007, 2009, 2010 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.def;
    016
    017    import org.apache.tapestry5.ioc.ObjectCreator;
    018    import org.apache.tapestry5.ioc.ServiceBuilderResources;
    019    import org.apache.tapestry5.ioc.ServiceLifecycle;
    020    import org.apache.tapestry5.ioc.services.ServiceLifecycleSource;
    021
    022    import java.util.Set;
    023
    024    /**
    025     * Service definition derived, by default, from a service builder method. This has been extended in Tapestry 5.1 with
    026     * {@link org.apache.tapestry5.ioc.def.ServiceDef2}, which adds additional methods.
    027     */
    028    @SuppressWarnings("rawtypes")
    029    public interface ServiceDef
    030    {
    031        /**
    032         * Returns an {@link ObjectCreator} that can create the core service implementation.
    033         *
    034         * @param resources
    035         *            used to resolve dependencies of the service, or access its configuration
    036         * @return an object that can (later) be used to instantiate the service itself
    037         */
    038        ObjectCreator createServiceCreator(ServiceBuilderResources resources);
    039
    040        /**
    041         * Returns the service id, derived from the method name or the unqualified service interface name. Service ids must
    042         * be unique among <em>all</em> services in all modules. Service ids are used in a heavy handed way to support
    043         * ultimate disambiguation, but their primary purpose is to support service contribution methods.
    044         */
    045        String getServiceId();
    046
    047        /**
    048         * Returns an optional set of <em>marker annotations</em>. Marker annotations are used to disambiguate services; the
    049         * combination of a marker annotation and a service type is expected to be unique. The annotation is placed on the
    050         * field or method/constructor parameter and the service is located by combining the marker with service type (the
    051         * parameter or field type).
    052         *
    053         * @return the marker annotations for the service (possibly empty), including any default marker annotations
    054         *         from the containing module.
    055         */
    056        Set<Class> getMarkers();
    057
    058        /**
    059         * Returns the service interface associated with this service. This is the interface exposed to the outside world,
    060         * as well as the one used to build proxies. In cases where the service is <em>not</em> defined in terms of an
    061         * interface, this will return the actual implementation class of the service. Services without a true service
    062         * interface are <strong>not proxied</strong>, which has a number of ramifications (such as losing lazy
    063         * instantiation capabilities and other more interesting lifecycles).
    064         */
    065        Class getServiceInterface();
    066
    067        /**
    068         * Returns the lifecycle defined for the service. This is indicated by adding a
    069         * {@link org.apache.tapestry5.ioc.annotations.Scope} annotation to the service builder method for the service.
    070         * <p/>
    071         * Services that are not proxied will ignore their scope; such services are always treated as singletons.
    072         * @see ServiceLifecycle
    073         * @see ServiceLifecycleSource
    074         */
    075        String getServiceScope();
    076
    077        /**
    078         * Returns true if the service should be eagerly loaded at Registry startup.
    079         *
    080         * @see org.apache.tapestry5.ioc.annotations.EagerLoad
    081         */
    082        boolean isEagerLoad();
    083    }