01: // Copyright 2006 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.services;
16:
17: import java.util.List;
18:
19: import org.apache.commons.logging.Log;
20:
21: /**
22: * Creates a pipeline from a service inteface and an ordered list of filters. Each filter is defined
23: * in terms of a filter interface: the filter interface is a variant of the service interface, where
24: * each method has an additional parameter that is an instance of the service interface. Typically,
25: * this service parameter (often named "delegate") is either the first or the last parameter of each
26: * method.
27: * <p>
28: * The implementation of a filter method is expected to pass all of its parameters to the service
29: * instance passed into it.
30: * <p>
31: * The interesting thing is that there may be multiple filters in the pipeline. A fabricated
32: * "bridge" object (that implements the service interface) is created to let each filter invoke
33: * methods on the next filter down the pipeline. This simplifies the model for creating pipelines,
34: * as each filter is coded as if it was directly "in front of" the terminator. In fact, it may be
35: * indirectly invoking methods on the next filter in the pipeline via a bridge instance.
36: * <p>
37: * The builder is fairly smart about matching up service interface methods to filter interface
38: * methods, but keeping it simple is also a good idea.
39: *
40: *
41: */
42: public interface PipelineBuilder {
43: /**
44: * Creates a pipeline from the filters and a terminator.
45: *
46: * @param <S>
47: * service type
48: * @param <F>
49: * filter type
50: * @param log
51: * logs any warnings generated when constructing the pipeline
52: * @param serviceInterface
53: * @param filterInterface
54: * @param filters
55: * sorted list of filters
56: * @param terminator
57: * end of the pipeline
58: * @return an object that encapsulates the filters and the terminator
59: */
60: <S, F> S build(Log log, Class<S> serviceInterface,
61: Class<F> filterInterface, List<F> filters, S terminator);
62:
63: /**
64: * Creates a pipeline from just the filters. A
65: * {@link DefaultImplementationBuilder default implementation} is created as the terminator.
66: *
67: * @param <S>
68: * @param <F>
69: * @param log
70: * @param serviceInterface
71: * @param filterInterface
72: * @param filters
73: * @return
74: */
75: <S, F> S build(Log log, Class<S> serviceInterface,
76: Class<F> filterInterface, List<F> filters);
77:
78: }
|