| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry5.ioc; |
| |
| import org.apache.tapestry5.ioc.annotations.Inject; |
| |
| import java.lang.annotation.Annotation; |
| |
| /** |
| * Defines an object which can provide access to services defined within a {@link org.apache.tapestry5.ioc.Registry}, or |
| * to objects or object instances available by other means. Services are accessed via service id, or |
| * (when appropriate) |
| * by just service interface. The Registry itself implements this interface, as does |
| * {@link org.apache.tapestry5.ioc.ServiceResources}. |
| */ |
| public interface ObjectLocator |
| { |
| /** |
| * Obtains a service via its unique service id. Returns the service's proxy. The service proxy |
| * implements the same |
| * interface as the actual service, and is used to instantiate the actual service only as needed |
| * (this is |
| * transparent to the application). |
| * |
| * @param <T> |
| * @param serviceId unique Service id used to locate the service object (may contain <em>symbols</em>, |
| * which |
| * will be expanded), case is ignored |
| * @param serviceInterface the interface implemented by the service (or an interface extended by the service |
| * interface) |
| * @return the service instance |
| * @throws RuntimeException if the service is not defined, or if an error occurs instantiating it |
| */ |
| <T> T getService(String serviceId, Class<T> serviceInterface); |
| |
| /** |
| * Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service |
| * interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface |
| * (not the service <em>implementation</em>), which may result in a failure due to extra |
| * matches. |
| * |
| * @param serviceInterface the interface the service implements |
| * @return the service's proxy |
| * @throws RuntimeException if the service does not exist (this is considered programmer error), or multiple |
| * services directly implement, or extend from, the service interface |
| * @see org.apache.tapestry5.ioc.annotations.Marker |
| */ |
| <T> T getService(Class<T> serviceInterface); |
| |
| /** |
| * Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service |
| * interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface |
| * (not the service <em>implementation</em>), which may result in a failure due to extra |
| * matches. The ability to specify marker annotation types was added in 5.3 |
| * |
| * @param serviceInterface the interface the service implements |
| * @param markerTypes Markers used to select a specific service that implements the interface |
| * @return the service's proxy |
| * @throws RuntimeException if the service does not exist (this is considered programmer error), or multiple |
| * services directly implement, or extend from, the service interface |
| * @see org.apache.tapestry5.ioc.annotations.Marker |
| * @since 5.3 |
| */ |
| <T> T getService(Class<T> serviceInterface, Class<? extends Annotation>... markerTypes); |
| |
| /** |
| * Obtains an object indirectly, using the {@link org.apache.tapestry5.ioc.services.MasterObjectProvider} service. |
| * |
| * @param objectType the type of object to be returned |
| * @param annotationProvider provides access to annotations on the field or parameter for which a value is to |
| * be |
| * obtained, which may be utilized in selecting an appropriate object, use |
| * <strong>null</strong> when annotations are not available (in which case, selection |
| * will |
| * be based only on the object type) |
| * @param <T> |
| * @return the requested object |
| * @see ObjectProvider |
| */ |
| <T> T getObject(Class<T> objectType, AnnotationProvider annotationProvider); |
| |
| /** |
| * Autobuilds a class by finding the public constructor with the most parameters. Services and other resources or |
| * dependencies will be injected into the parameters of the constructor and into private fields marked with the |
| * {@link Inject} annotation. There are two cases: constructing a service implementation, and constructing |
| * an arbitrary object. In the former case, many <em>service resources</em> are also available for injection, not |
| * just dependencies or objects provided via the MasterObjectProvider service. |
| * |
| * @param <T> |
| * @param clazz the type of object to instantiate |
| * @return the instantiated instance |
| * @throws RuntimeException if the autobuild fails |
| */ |
| <T> T autobuild(Class<T> clazz); |
| |
| /** |
| * Preferred version of {@link #autobuild(Class)} that tracks the operation using |
| * {@link org.apache.tapestry5.ioc.OperationTracker#invoke(String, org.apache.tapestry5.ioc.Invokable)}. |
| * |
| * @param <T> |
| * @param description description used with {@link org.apache.tapestry5.ioc.OperationTracker} |
| * @param clazz the type of object to instantiate |
| * @return the instantiated instance |
| * @throws RuntimeException if the autobuild fails |
| * @since 5.2.0 |
| */ |
| <T> T autobuild(String description, Class<T> clazz); |
| |
| /** |
| * Creates a proxy. The proxy will defer invocation of {@link #autobuild(Class)} until |
| * just-in-time (that is, first method invocation). In a limited number of cases, it is necessary to use such a |
| * proxy to prevent service construction cycles, particularly when contributing (directly or indirectly) to the |
| * {@link org.apache.tapestry5.ioc.services.MasterObjectProvider} (which is itself at the heart |
| * of autobuilding). |
| * |
| * If the class file for the class is a file on the file system (not a file packaged in a JAR), then the proxy will |
| * <em>autoreload</em>: changing the class file will result in the new class being reloaded and re-instantiated |
| * (with dependencies). |
| * |
| * @param <T> |
| * @param interfaceClass the interface implemented by the proxy |
| * @param implementationClass a concrete class that implements the interface |
| * @return a proxy |
| * @see #autobuild(Class) |
| */ |
| <T> T proxy(Class<T> interfaceClass, Class<? extends T> implementationClass); |
| } |