    001// Copyright 2007, 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;
    016
    017import org.apache.tapestry5.ioc.annotations.EagerLoad;
    018import org.apache.tapestry5.ioc.annotations.Scope;
    019
    020import java.lang.annotation.Annotation;
    021
    022/**
    023 * Allows additional options for a service to be specified, overriding hard coded defaults or defaults from annotations
    024 * on the service.
    025 *
    026 * @see org.apache.tapestry5.ioc.def.ServiceDef2
    027 */
    028public interface ServiceBindingOptions
    029{
    030    /**
    031     * Allows a specific service id for the service to be provided, rather than the default (from the service
    032     * interface). This is useful when multiple services implement the same interface, since service ids must be
    033     * unique.
    034     *
    035     * @param id
    036     * @return this binding options, for further configuration
    037     */
    038    ServiceBindingOptions withId(String id);
    039
    040    /**
    041     * Uses the the simple (unqualified) class name of the implementation class as the id of the service.
    042     *
    043     * @return this binding options, for further configuration
    044     * @throws IllegalStateException if the class name was not defined (via {@link ServiceBinder#bind(Class, Class)} or
    045     *                               {@link ServiceBinder#bind(Class)}).
    046     * @since 5.3
    047     */
    048    ServiceBindingOptions withSimpleId();
    049
    050    /**
    051     * Sets the scope of the service, overriding the {@link Scope} annotation on the service implementation class.
    052     *
    053     * @param scope
    054     * @return this binding options, for further configuration
    055     * @see org.apache.tapestry5.ioc.ScopeConstants
    056     */
    057    ServiceBindingOptions scope(String scope);
    058
    059    /**
    060     * Turns eager loading on for this service. This may also be accomplished using the {@link EagerLoad} annotation on
    061     * the service implementation class.
    062     *
    063     * @return this binding options, for further configuration
    064     */
    065    ServiceBindingOptions eagerLoad();
    066
    067    /**
    068     * Disallows service decoration for this service.
    069     *
    070     * @return this binding options, for further configuration
    071     */
    072    ServiceBindingOptions preventDecoration();
    073
    074    /**
    075     * Identifies a service for which live class reloading is not desired. This primarily applies to certain
    076     * internal Tapestry services, and is necessary during the development of Tapestry itself. In user applications,
    077     * services defined in library modules are not subject to reloading because the class files are stored in JARs, not
    078     * as local file system files.
    079     *
    080     * @since 5.2.0
    081     */
    082    ServiceBindingOptions preventReloading();
    083
    084    /**
    085     * Defines the marker interface(s) for the service, used to connect injections by type at the point of injection
    086     * with a particular service implementation, based on the intersection of type and marker interface. The containing
    087     * module will sometimes provide a set of default marker annotations for all services within the module, this method
    088     * allows that default to be extended.
    089     *
    090     * @param <T>
    091     * @param marker one or more markers to add
    092     * @return this binding options, for further configuration
    093     */
    094    ServiceBindingOptions withMarker(Class<? extends Annotation>... marker);
    095}