001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005// http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012
013package org.apache.tapestry5.ioc;
014
015import org.apache.tapestry5.ioc.annotations.EagerLoad;
016import org.apache.tapestry5.ioc.annotations.Scope;
017
018import java.lang.annotation.Annotation;
019
020/**
021 * Allows additional options for a service to be specified, overriding hard coded defaults or defaults from annotations
022 * on the service.
023 *
024 * @see org.apache.tapestry5.ioc.def.ServiceDef2
025 */
026public interface ServiceBindingOptions
027{
028    /**
029     * Allows a specific service id for the service to be provided, rather than the default (from the service
030     * interface). This is useful when multiple services implement the same interface, since service ids must be
031     * unique.
032     *
033     * @param id
034     * @return this binding options, for further configuration
035     */
036    ServiceBindingOptions withId(String id);
037
038    /**
039     * Uses the the simple (unqualified) class name of the implementation class as the id of the service.
040     *
041     * @return this binding options, for further configuration
042     * @throws IllegalStateException if the class name was not defined (via {@link ServiceBinder#bind(Class, Class)} or
043     *                               {@link ServiceBinder#bind(Class)}).
044     * @since 5.3
045     */
046    ServiceBindingOptions withSimpleId();
047
048    /**
049     * Sets the scope of the service, overriding the {@link Scope} annotation on the service implementation class.
050     *
051     * @param scope
052     * @return this binding options, for further configuration
053     * @see org.apache.tapestry5.ioc.ScopeConstants
054     */
055    ServiceBindingOptions scope(String scope);
056
057    /**
058     * Turns eager loading on for this service. This may also be accomplished using the {@link EagerLoad} annotation on
059     * the service implementation class.
060     *
061     * @return this binding options, for further configuration
062     */
063    ServiceBindingOptions eagerLoad();
064
065    /**
066     * Disallows service decoration for this service.
067     *
068     * @return this binding options, for further configuration
069     */
070    ServiceBindingOptions preventDecoration();
071
072    /**
073     * Identifies a service for which live class reloading is not desired. This primarily applies to certain
074     * internal Tapestry services, and is necessary during the development of Tapestry itself. In user applications,
075     * services defined in library modules are not subject to reloading because the class files are stored in JARs, not
076     * as local file system files.
077     *
078     * @since 5.2.0
079     */
080    ServiceBindingOptions preventReloading();
081
082    /**
083     * Defines the marker interface(s) for the service, used to connect injections by type at the point of injection
084     * with a particular service implementation, based on the intersection of type and marker interface. The containing
085     * module will sometimes provide a set of default marker annotations for all services within the module, this method
086     * allows that default to be extended.
087     *
088     * @param marker one or more markers to add
089     * @return this binding options, for further configuration
090     */
091    ServiceBindingOptions withMarker(Class<? extends Annotation>... marker);
092}