1 /*
2 * Copyright 2011 Christopher Pheby
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.jadira.bindings.core.binder;
17
18 import java.lang.annotation.Annotation;
19 import java.net.URL;
20
21 import org.jadira.bindings.core.api.Binding;
22 import org.jadira.bindings.core.api.Converter;
23 import org.jadira.bindings.core.api.FromUnmarshaller;
24 import org.jadira.bindings.core.api.ToMarshaller;
25
26 public interface RegisterableBinder {
27
28 /**
29 * Register the configuration file (bindings.xml) at the given URL
30 * @param nextLocation The URL to register
31 */
32 void registerConfiguration(URL nextLocation);
33
34 /**
35 * Register a Binding with the given source and target class.
36 * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
37 *
38 * The source class is considered the owning class of the binding. The source can be marshalled
39 * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
40 * @param key The converter key
41 * @param converter The binding to be registered
42 * @param <S> Source type
43 * @param <T> Target type
44 */
45 <S, T> void registerBinding(ConverterKey<S,T> key, Binding<S, T> converter);
46
47 /**
48 * Register an UnMarshaller with the given source and target class.
49 * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
50 * @param key The converter key
51 * @param converter The FromUnmarshaller to be registered
52 * @param <S> Source type
53 * @param <T> Target type
54 */
55 <S, T> void registerUnmarshaller(ConverterKey<S,T> key, FromUnmarshaller<S, T> converter);
56
57 /**
58 * Register a Marshaller with the given source and target class.
59 * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
60 * @param key The converter key
61 * @param converter The ToMarshaller to be registered
62 * @param <S> Source type
63 * @param <T> Target type
64 */
65 <S, T> void registerMarshaller(ConverterKey<S,T> key, ToMarshaller<S, T> converter);
66
67 /**
68 * Register a Converter with the given input and output classes. Instances of the input class can be converted into
69 * instances of the output class
70 * @param key The converter key
71 * @param converter The Converter to be registered
72 * @param <S> Source type
73 * @param <T> Target type
74 */
75 <S, T> void registerConverter(ConverterKey<S,T> key, Converter<S, T> converter);
76
77 /**
78 * Register a Binding with the given source and target class.
79 * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
80 *
81 * The source class is considered the owning class of the binding. The source can be marshalled
82 * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
83 * @param sourceClass The source (owning) class
84 * @param targetClass The target (foreign) class
85 * @param converter The binding to be registered
86 * @param <S> Source type
87 * @param <T> Target type
88 */
89 <S, T> void registerBinding(final Class<S> sourceClass, Class<T> targetClass, Binding<S, T> converter);
90
91 /**
92 * Register an UnMarshaller with the given source and target class.
93 * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
94 * @param sourceClass The source (input) class
95 * @param targetClass The target (output) class
96 * @param converter The FromUnmarshaller to be registered
97 * @param <S> Source type
98 * @param <T> Target type
99 */
100 <S, T> void registerUnmarshaller(Class<S> sourceClass, Class<T> targetClass, FromUnmarshaller<S, T> converter);
101
102 /**
103 * Register a Marshaller with the given source and target class.
104 * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
105 * @param sourceClass The source (input) class
106 * @param targetClass The target (output) class
107 * @param converter The ToMarshaller to be registered
108 * @param <S> Source type
109 * @param <T> Target type
110 */
111 <S, T> void registerMarshaller(Class<S> sourceClass, Class<T> targetClass, ToMarshaller<S, T> converter);
112
113 /**
114 * Register a Converter with the given input and output classes. Instances of the input class can be converted into
115 * instances of the output class
116 * @param sourceClass The source (input) class
117 * @param targetClass The target (output) class
118 * @param converter The Converter to be registered
119 * @param <S> Source type
120 * @param <T> Target type
121 */
122 <S, T> void registerConverter(final Class<S> sourceClass, Class<T> targetClass, Converter<S, T> converter);
123
124 /**
125 * Register a Binding with the given source and target class.
126 * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
127 *
128 * The source class is considered the owning class of the binding. The source can be marshalled
129 * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
130 * @param sourceClass The source (owning) class
131 * @param targetClass The target (foreign) class
132 * @param converter The binding to be registered
133 * @param qualifier The qualifier for which the binding must be registered
134 * @param <S> Source type
135 * @param <T> Target type
136 */
137 <S, T> void registerBinding(final Class<S> sourceClass, Class<T> targetClass, Binding<S, T> converter, Class<? extends Annotation> qualifier);
138
139 /**
140 * Register an UnMarshaller with the given source and target class.
141 * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
142 * @param sourceClass The source (input) class
143 * @param targetClass The target (output) class
144 * @param converter The FromUnmarshaller to be registered
145 * @param qualifier The qualifier for which the unmarshaller must be registered
146 * @param <S> Source type
147 * @param <T> Target type
148 */
149 <S, T> void registerUnmarshaller(Class<S> sourceClass, Class<T> targetClass, FromUnmarshaller<S, T> converter, Class<? extends Annotation> qualifier);
150
151 /**
152 * Register a Marshaller with the given source and target class.
153 * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
154 * @param sourceClass The source (input) class
155 * @param targetClass The target (output) class
156 * @param converter The ToMarshaller to be registered
157 * @param qualifier The qualifier for which the marshaller must be registered
158 * @param <S> Source type
159 * @param <T> Target type
160 */
161 <S, T> void registerMarshaller(Class<S> sourceClass, Class<T> targetClass, ToMarshaller<S, T> converter, Class<? extends Annotation> qualifier);
162
163 /**
164 * Register a Converter with the given input and output classes. Instances of the input class can be converted into
165 * instances of the output class
166 * @param sourceClass The source (input) class
167 * @param targetClass The target (output) class
168 * @param converter The Converter to be registered
169 * @param qualifier The qualifier for which the converter must be registered
170 * @param <S> Source type
171 * @param <T> Target type
172 */
173 <S, T> void registerConverter(final Class<S> sourceClass, Class<T> targetClass, Converter<S, T> converter, Class<? extends Annotation> qualifier);
174
175 /**
176 * Inspect each of the supplied classes, processing any of the annotated methods found
177 * @param classesToInspect
178 */
179 void registerAnnotatedClasses(Class<?>... classesToInspect);
180
181 /**
182 * Return an iterable collection of ConverterKeys, one for each currently registered conversion
183 */
184 Iterable<ConverterKey<?, ?>> getConverterEntries();
185 }