001// Copyright 2007, 2008, 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.services; 016 017import org.apache.tapestry5.ioc.AnnotationProvider; 018import org.apache.tapestry5.ioc.ObjectLocator; 019import org.apache.tapestry5.ioc.ObjectProvider; 020import org.apache.tapestry5.ioc.annotations.UsesOrderedConfiguration; 021 022/** 023 * A service that acts as a chain-of-command over a number of {@link org.apache.tapestry5.ioc.ObjectProvider}, but 024 * allows for the case where no object may be provided. 025 * <p/> 026 * This service is itself a key part of Tapestry's general injection mechanism; it is used when instantiating a service 027 * implementation instance, invoking module methods (service builder, decorator, or contribution methods), when 028 * {@linkplain ObjectLocator#autobuild(Class) autobuilding} objects of any type. 029 * <p/> 030 * As of Tapestry 5.3, the MasterObjectProvider allows injection of {@link org.apache.tapestry5.ioc.OperationTracker} as a 031 * special case (not based on a contributed ObjectProvider). 032 */ 033@UsesOrderedConfiguration(ObjectProvider.class) 034public interface MasterObjectProvider 035{ 036 /** 037 * Provides an object based on an expression. The process of providing objects occurs within a particular 038 * <em>context</em>, which will typically be a service builder method, service contributor method, or service 039 * decorator method. The locator parameter provides access to the services visible <em>to that context</em>. 040 * <p/> 041 * When the value is required and no {@link ObjectProvider} provided a non-null value, then {@link 042 * ObjectLocator#getService(Class, Class[])} is invoked (with no marker annotations), 043 * to provide a uniquely matching service, or throw a failure exception 044 * if no <em>single</em> service can be found. 045 * 046 * @param objectType the expected object type 047 * @param annotationProvider provides access to annotations (typically, the field or parameter to which an 048 * injection-related annotation is attached); annotations on the field or parameter may 049 * also be used when resolving the desired object 050 * @param locator locator for the <em>context</em> in which the provider is being used 051 * @param required if true (normal case) a value must be provided; if false then it is allowed for no 052 * ObjectProvider to provide a value, and this method may return null to indicate the 053 * failure 054 * @param <T> 055 * @return the requested object, or null if this object provider can not supply an object 056 * @throws RuntimeException if the expression can not be evaluated, or the type of object identified is not 057 * assignable to the type specified by the objectType parameter 058 */ 059 <T> T provide(Class<T> objectType, AnnotationProvider annotationProvider, ObjectLocator locator, boolean required); 060}