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.services;
16:
17: /**
18: * Makes use of {@link Coercion}s (via {@link CoercionTuple}s) to convert between an input value
19: * (of some specific type) and a desired output type. Smart about coercing, even if it requires
20: * multiple coercing steps (i.e., via an intermediate type, such as String).
21: */
22: public interface TypeCoercer {
23: /**
24: * Performs a coercion from an input type to a desired output type. When the target type is a
25: * primitive, the actual conversion will be to the equivalent wrapper type. In some cases, the
26: * TypeCoercer will need to search for an appropriate coercion, and may even combine existing
27: * coercions to form new ones; in those cases, the results of the search are cached.
28: *
29: * @param <S>
30: * source type (input)
31: * @param <T>
32: * target type (output)
33: * @param input
34: * @param targetType
35: * defines the target type
36: * @return the coerced value
37: */
38: <S, T> T coerce(S input, Class<T> targetType);
39:
40: /**
41: * Used primarily inside test suites, this method performs the same steps as
42: * {@link #coerce(Object, Class)}, but returns a string describing the series of coercision,
43: * such as "Object --> String --> Long --> Integer".
44: *
45: * @param <S>
46: * source type (input)
47: * @param <T>
48: * target type (output)
49: * @param inputType
50: * the source coercion type (use void.class for coercions from null)
51: * @param targetType
52: * defines the target type
53: * @return a string identifying the series of coercions, or the empty string if no coercion is
54: * necessary
55: */
56: <S, T> String explain(Class<S> inputType, Class<T> targetType);
57:
58: /** Clears cached information stored by the TypeCoercer. */
59: void clearCache();
60: }
|