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.annotations;
014
015import org.apache.tapestry5.ioc.ServiceBinder;
016import org.apache.tapestry5.ioc.ServiceLifecycle;
017import org.apache.tapestry5.ioc.services.ServiceLifecycleSource;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.Retention;
021import java.lang.annotation.Target;
022
023import static java.lang.annotation.ElementType.METHOD;
024import static java.lang.annotation.ElementType.TYPE;
025import static java.lang.annotation.RetentionPolicy.RUNTIME;
026
027/**
028 * An optional annotation that may be placed on a service building method of a module, or on the implementation class
029 * (when using service binding). The annotation overrides the default scope for services (the default being a global
030 * singleton that is instantiated on demand) for an alternate lifecycle. Alternate lifecycles are typically used to bind
031 * a service implementation to a single thread or request. Modules may define new scopes. Each scope should have a
032 * corresponding {@link ServiceLifecycle} implementation. The linkage from scope name to service lifecycle occurs via a
033 * contribution to the {@link ServiceLifecycleSource} service configuration.
034 *
035 * The annotation may also be placed directly on a service implementation class, when using service binding (via
036 * the {@link ServiceBinder}).
037 *
038 * @see org.apache.tapestry5.ioc.ScopeConstants
039 */
040@Target(
041        {TYPE, METHOD})
042@Retention(RUNTIME)
043@Documented
044@UseWith({AnnotationUseContext.SERVICE, AnnotationUseContext.MODULE})
045public @interface Scope
046{
047    /**
048     * An identifier used to look up a non-default {@link ServiceLifecycle}.
049     */
050    String value();
051}