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