01: // Copyright 2006, 2007 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // Unless required by applicable law or agreed to in writing, software
10: // distributed under the License is distributed on an "AS IS" BASIS,
11: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: // See the License for the specific language governing permissions and
13: // limitations under the License.
14:
15: package org.apache.tapestry.ioc.def;
16:
17: import org.apache.tapestry.ioc.ModuleBuilderSource;
18: import org.apache.tapestry.ioc.ServiceDecorator;
19: import org.apache.tapestry.ioc.ServiceResources;
20:
21: /**
22: * Definition of a service decorator, which (by default) is derived from a service decorator method.
23: * <p>
24: * A note on decorator scheduling. The scheduling is based on the desired order of <em>behavior</em>.
25: * Thus, if logging should occur before security checks, and security checks should occur before
26: * transaction management, then the desired decorator order is Logging, Security, Transactions. This
27: * might be specified as having Security occur after Logging, and Transactions occur after Security.
28: * It might also be specified by having Logging ordered "before:*", and Transactions ordered
29: * "after:*" with no specified scheduling for Security.
30: * <p>
31: * Once this order is established, decorators are <em>applied</em> in reverse order. Each
32: * decorator's job is to create an <em>interceptor</em> for the service, that delegates to the
33: * next implementation. This implies that the decorators are executed last to first. In the above
34: * example, the core service implementation would be passed to the Transaction decorator, resulting
35: * in the Transaction interceptor. The Transaction interceptor would be passed to the Security
36: * decorator, resulting in the Security interceptor. The Security interceptor would be passed to the
37: * Logging decorator, resulting in the Logging interceptor. Thus at runtime, the Logging interceptor
38: * will execute first, then delegate to the Security interceptor, which would delegate to the
39: * Transaction interceptor, which would finally delegate to the core service implementation.
40: */
41: public interface DecoratorDef {
42: /**
43: * Returns the id of the decorator, which is derived from the decorator method name.
44: */
45: String getDecoratorId();
46:
47: /**
48: * Returns zero or more ordering constraint strings, used to order the decorated relative to the
49: * other decorators.
50: */
51:
52: String[] getConstraints();
53:
54: /**
55: * Creates an object that can perform the decoration (in the default case, by invoking the
56: * decorator method on the module builder instance.
57: *
58: * @param moduleBuilderSource
59: * the module builder instance associated with the module containing the decorator
60: * (not necessarily the module containing the service being decorated)
61: * @param resources
62: * the resources visible <em>to the decorator</em> (which may be in a different
63: * module than the service being decorated). Other resource properties (serviceId,
64: * serviceInterface, log, etc.) are for the service being decorated.
65: */
66: ServiceDecorator createDecorator(
67: ModuleBuilderSource moduleBuilderSource,
68: ServiceResources resources);
69:
70: /**
71: * Used to determine which services may be decorated by this decorator. When decorating a
72: * service, first the decorators that target the service are identified, then ordering occurs,
73: * then the {@link ServiceDecorator}s are invoked.
74: *
75: * @param serviceDef
76: * @return true if the decorator applies to the service
77: */
78: boolean matches(ServiceDef serviceDef);
79: }
|