1 package net.sourceforge.jparam.conversion.converters;
2
3 import net.sourceforge.jparam.JParamException;
4 import net.sourceforge.jparam.conversion.weights.ScalarConversionWeight;
5
6 /***
7 * This interface is used to convert an object between two given class
8 * <p>
9 * Each converter can convert ONLY object of the source class (or subclasses, to
10 * support chaining since there are no static types in Java) to the target class
11 *
12 * @author Ron_Sidi
13 *
14 */
15 public interface IConverter {
16
17 /***
18 * Return the <code>Class</code> object the target object will be instanceof
19 *
20 * @return expected target <code>Class</code>
21 */
22 Class getTargetClass();
23
24 /***
25 * Return the <code>Class</code> object the converter expects the source to
26 * be instanceof
27 *
28 * @return expected source <code>Class</code>
29 */
30 Class getSourceClass();
31
32 /***
33 * Perform the conversion of the given object to the expected target class,
34 * if for some reason the conversion fails (or if the source/target objects
35 * do not match the expected classes), an exception should be thrown
36 *
37 * @param o
38 * the source object (should be instance of getSourceClass)
39 * @return the converted object (instance of getTargetClass)
40 * @throws JParamException
41 * if for some reason the conversion failed
42 */
43 Object convert(Object o) throws JParamException;
44
45 /***
46 * Return the scalar weight of this converter, if this is a concatenated
47 * converter, its weight should include the weight of all of its
48 * subconverters
49 *
50 * @return conversion weight
51 */
52 ScalarConversionWeight getWeight();
53
54 /***
55 * Return a string representation of the conversion process only, no
56 * additional data, this output will be used when ambiguity is detected in
57 * order to give the user meaningfull error messages
58 *
59 * An ambiguity output would be:
60 * <p><blockquote><pre>
61 * duckling -> duck -> short -> int
62 * duckling -> duck -> char -> int
63 * </pre></blockquote><p>
64 *
65 * Note that there is no additional text or info here
66 *
67 * @return a String representation of the conversion process
68 */
69 String toConversionString();
70
71 /***
72 * A more programatically meaningfull description of the conversion, it
73 * should show at least the weight of the conversion and possibly more data
74 * for example:
75 * A path conversion string could look like:
76 * <p><blockquote><pre>
77 * duck --> archduck --> ducky(USER + TO_PARENT)
78 * </pre></blockquote><p>
79 *
80 * An ambigous conversion could look like:
81 * <p><blockquote><pre>
82 * AMBIGOUS(
83 * duck -> short -> double
84 * duck -> uchar -> double)(USER + PROMOTION)
85 * </pre></blockquote><p>
86 *
87 * @return an informative representation of the conversion, used for
88 * debugging
89 */
90 String toString();
91
92 /***
93 * This method is used to inform the converter of a new available converter
94 * if the new converter affects in any way on the current converter, a new
95 * converter that reflects the change should be return.
96 *
97 * This will have no affect on atomic converters, but might affect compound
98 * converters (it could affect their weight, and could make them ambigous or
99 * change an ambigous converter to a valid one)
100 *
101 * @param updatedConverter the newly supported converter
102 * @return IConverter <code>this</code> if nothing changed or a new
103 * converter representing the change
104 */
105 IConverter update(IConverter updatedConverter);
106 }