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}