001/*
002 *  Copyright 2011 Christopher Pheby
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.jadira.bindings.core.binder;
017
018import java.lang.annotation.Annotation;
019import java.net.URL;
020
021import org.jadira.bindings.core.api.Binding;
022import org.jadira.bindings.core.api.Converter;
023import org.jadira.bindings.core.api.FromUnmarshaller;
024import org.jadira.bindings.core.api.ToMarshaller;
025
026public interface RegisterableBinder {
027
028    /**
029     * Register the configuration file (bindings.xml) at the given URL
030     * @param nextLocation The URL to register 
031     */    
032    void registerConfiguration(URL nextLocation);
033        
034        /**
035         * Register a Binding with the given source and target class.
036         * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
037         * 
038         * The source class is considered the owning class of the binding. The source can be marshalled
039         * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
040         * @param key The converter key
041         * @param converter The binding to be registered
042         * @param <S> Source type
043         * @param <T> Target type
044         */
045    <S, T> void registerBinding(ConverterKey<S,T> key, Binding<S, T> converter);
046    
047        /**
048         * Register an UnMarshaller with the given source and target class.
049         * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
050         * @param key The converter key
051         * @param converter The FromUnmarshaller to be registered
052         * @param <S> Source type
053         * @param <T> Target type  
054         */
055        <S, T> void registerUnmarshaller(ConverterKey<S,T> key, FromUnmarshaller<S, T> converter);
056        
057        /**
058         * Register a Marshaller with the given source and target class.
059         * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
060         * @param key The converter key
061         * @param converter The ToMarshaller to be registered
062         * @param <S> Source type
063         * @param <T> Target type 
064         */
065        <S, T> void registerMarshaller(ConverterKey<S,T> key, ToMarshaller<S, T> converter);
066    
067        /**
068         * Register a Converter with the given input and output classes. Instances of the input class can be converted into 
069         * instances of the output class
070         * @param key The converter key
071         * @param converter The Converter to be registered
072         * @param <S> Source type
073         * @param <T> Target type   
074         */
075    <S, T> void registerConverter(ConverterKey<S,T> key, Converter<S, T> converter);
076        
077        /**
078         * Register a Binding with the given source and target class.
079         * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
080         * 
081         * The source class is considered the owning class of the binding. The source can be marshalled
082         * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
083         * @param sourceClass The source (owning) class
084         * @param targetClass The target (foreign) class
085         * @param converter The binding to be registered
086         * @param <S> Source type
087         * @param <T> Target type
088         */
089    <S, T> void registerBinding(final Class<S> sourceClass, Class<T> targetClass, Binding<S, T> converter);
090
091        /**
092         * Register an UnMarshaller with the given source and target class.
093         * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
094         * @param sourceClass The source (input) class
095         * @param targetClass The target (output) class
096         * @param converter The FromUnmarshaller to be registered
097         * @param <S> Source type
098         * @param <T> Target type  
099         */
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}