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;
019
020import org.jadira.bindings.core.api.Binding;
021import org.jadira.bindings.core.api.Converter;
022import org.jadira.bindings.core.api.FromUnmarshaller;
023import org.jadira.bindings.core.api.ToMarshaller;
024
025public interface SearchableBinder {
026
027        /**
028         * Resolve a Binding with the given source and target class.
029         * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
030         * 
031         * The source class is considered the owning class of the binding. The source can be marshalled
032         * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
033         * @param key The converter key
034         * @param <S> The Source type
035         * @param <T> The Target type
036         * @return The found Binding
037         */
038    <S, T> Binding<S, T> findBinding(ConverterKey<S,T> key);
039    
040        /**
041         * Resolve a Marshaller with the given source and target class.
042         * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
043         * @param key The converter key
044         * @param <S> The Source type
045         * @param <T> The Target type
046         * @return The found Marshaller
047         */
048    <S, T> ToMarshaller<S, T> findMarshaller(ConverterKey<S,T> key);
049    
050        /**
051         * Resolve a Converter with the given input and output classes. Instances of the input class can be converted into 
052         * instances of the output class
053         * @param key The converter key
054         * @param <S> The Source type
055         * @param <T> The Target type  
056         * @return The found Converter
057         */
058    <S, T> Converter<S, T> findConverter(ConverterKey<S,T> key);
059    
060        /**
061         * Resolve an UnMarshaller with the given source and target class.
062         * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
063         * @param key The converter key
064         * @param <S> The Source type
065         * @param <T> The Target type 
066         * @return The found Unmarshaller
067         */
068    <S, T> FromUnmarshaller<S, T> findUnmarshaller(ConverterKey<S,T> key);
069
070        /**
071         * Resolve a Binding with the given source and target class.
072         * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
073         * <br>
074         * The source class is considered the owning class of the binding. The source can be marshalled
075         * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
076         * @param source The source (owning) class
077         * @param target The target (foreign) class
078         * @param <S> The Source type
079         * @param <T> The Target type
080         * @return The found Binding
081         */
082    <S, T> Binding<S, T> findBinding(final Class<S> source, final Class<T> target);
083    
084        /**
085         * Resolve a Marshaller with the given source and target class.
086         * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
087         * @param source The source (input) class
088         * @param target The target (output) class
089         * @param <S> The Source type
090         * @param <T> The Target type
091         * @return The found Marshaller
092         */
093    <S, T> ToMarshaller<S, T> findMarshaller(final Class<S> source, final Class<T> target);
094    
095        /**
096         * Resolve a Converter with the given input and output classes. Instances of the input class can be converted into 
097         * instances of the output class
098         * @param source The input class
099         * @param target The output class
100         * @param <S> The Source type
101         * @param <T> The Target type  
102         * @return The found Converter
103         */
104    <S, T> Converter<S, T> findConverter(final Class<S> source, final Class<T> target);
105    
106        /**
107         * Resolve an UnMarshaller with the given source and target class.
108         * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
109         * @param source The source (input) class
110         * @param target The target (output) class
111         * @param <S> The Source type
112         * @param <T> The Target type 
113         * @return The found Unmarshaller
114         */
115    <S, T> FromUnmarshaller<S, T> findUnmarshaller(final Class<S> source, final Class<T> target);
116    
117        /**
118         * Resolve a Binding with the given source and target class.
119         * A binding unifies a marshaller and an unmarshaller and both must be available to resolve a binding.
120         * <br>
121         * The source class is considered the owning class of the binding. The source can be marshalled
122         * into the target class. Similarly, the target can be unmarshalled to produce an instance of the source type.
123         * @param source The source (owning) class
124         * @param target The target (foreign) class
125         * @param qualifier The qualifier for which the binding must be registered
126         * @param <S> The Source type
127         * @param <T> The Target type
128         * @return The found Binding
129         */
130    <S, T> Binding<S, T> findBinding(final Class<S> source, final Class<T> target, final Class<? extends Annotation> qualifier);
131    
132        /**
133         * Resolve a Marshaller with the given source and target class.
134         * The marshaller is used as follows: Instances of the source can be marshalled into the target class.
135         * @param source The source (input) class
136         * @param target The target (output) class
137         * @param qualifier The qualifier for which the marshaller must be registered
138         * @param <S> The Source type
139         * @param <T> The Target type
140         * @return The found Marshaller 
141         */
142    <S, T> ToMarshaller<S, T> findMarshaller(final Class<S> source, final Class<T> target, final Class<? extends Annotation> qualifier);
143    
144        /**
145         * Resolve a Converter with the given input and output classes. Instances of the input class can be converted into 
146         * instances of the output class
147         * @param source The input class
148         * @param target The output class
149         * @param qualifier The qualifier for which the marshaller must be registered
150         * @param <S> The Source type
151         * @param <T> The Target type  
152         * @return The found Converter 
153         */
154    <S, T> Converter<S, T> findConverter(final Class<S> source, final Class<T> target, final Class<? extends Annotation> qualifier);
155    
156        /**
157         * Resolve an UnMarshaller with the given source and target class.
158         * The unmarshaller is used as follows: Instances of the source can be marshalled into the target class.
159         * @param source The source (input) class
160         * @param target The target (output) class 
161         * @param qualifier The qualifier for which the unmarshaller must be registered
162         * @param <S> The Source type
163         * @param <T> The Target type 
164         * @return The found Unmarshaller
165         */
166    <S, T> FromUnmarshaller<S, T> findUnmarshaller(final Class<S> source, final Class<T> target, final Class<? extends Annotation> qualifier);
167}