001 // Copyright 2006, 2007, 2009 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
015 package org.apache.tapestry5.ioc.def;
016
017 import org.apache.tapestry5.ioc.ModuleBuilderSource;
018 import org.apache.tapestry5.ioc.ServiceDecorator;
019 import org.apache.tapestry5.ioc.ServiceResources;
020
021 /**
022 * Definition of a service decorator, which (by default) is derived from a service decorator method.
023 * <p/>
024 * A note on decorator scheduling. The scheduling is based on the desired order of <em>behavior</em>. Thus, if logging
025 * should occur before security checks, and security checks should occur before transaction management, then the desired
026 * decorator order is Logging, Security, Transactions. This might be specified as having Security occur after Logging,
027 * and Transactions occur after Security. It might also be specified by having Logging ordered "before:*", and
028 * Transactions ordered "after:*" with no specified scheduling for Security.
029 * <p/>
030 * Once this order is established, decorators are <em>applied</em> in reverse order. Each decorator's job is to create
031 * an <em>interceptor</em> for the service, that delegates to the next implementation. This implies that the decorators
032 * are executed last to first. In the above example, the core service implementation would be passed to the Transaction
033 * decorator, resulting in the Transaction interceptor. The Transaction interceptor would be passed to the Security
034 * decorator, resulting in the Security interceptor. The Security interceptor would be passed to the Logging decorator,
035 * resulting in the Logging interceptor. Thus at runtime, the Logging interceptor will execute first, then delegate to
036 * the Security interceptor, which would delegate to the Transaction interceptor, which would finally delegate to the
037 * core service implementation.
038 * <p/>
039 * Service decorators are part of the initial version of Tapestry IoC. Starting in release 5.1, their use has been
040 * deprecated, in favor of {@link org.apache.tapestry5.ioc.AdvisorDef}, which is based on {@link
041 * org.apache.tapestry5.ioc.services.AspectInterceptorBuilder}.
042 * <p/>
043 * Note: service decorators are applied <em>around</em> the interceptor generated via any {@link
044 * org.apache.tapestry5.ioc.AdvisorDef}s (for compatibility with Tapestry 5.0). In general, you should use service
045 * decoration or service advice, not both.
046 */
047 public interface DecoratorDef
048 {
049 /**
050 * Returns the id of the decorator, which is derived from the decorator method name.
051 */
052 String getDecoratorId();
053
054 /**
055 * Returns zero or more ordering constraint strings, used to order the decorated relative to the other decorators.
056 */
057
058 String[] getConstraints();
059
060 /**
061 * Creates an object that can perform the decoration (in the default case, by invoking the decorator method on the
062 * module class or instance.
063 *
064 * @param moduleSource access to the the module instance associated with the module containing the decorator (not
065 * necessarily the module containing the service being decorated)
066 * @param resources the resources visible <em>to the decorator</em> (which may be in a different module than the
067 * service being decorated). Other resource properties (serviceId, serviceInterface, log, etc.)
068 * are for the service being decorated.
069 */
070 ServiceDecorator createDecorator(ModuleBuilderSource moduleSource,
071 ServiceResources resources);
072
073 /**
074 * Used to determine which services may be decorated by this decorator. When decorating a service, first the
075 * decorators that target the service are identified, then ordering occurs, then the {@link ServiceDecorator}s are
076 * invoked.
077 *
078 * @param serviceDef
079 * @return true if the decorator applies to the service
080 */
081 boolean matches(ServiceDef serviceDef);
082 }