1 /*
2  * Copyright 2011 the original author or authors.
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.modelmapper.spi;
17
18 import org.modelmapper.Converter;
19 import org.modelmapper.config.Configuration;
20
21 /**
22  * Conditionally converts matching source objects to instances of destination type {@code D}.
23  * 
24  * @param <S> source type
25  * @param <D> destination type
26  * @author Jonathan Halterman
27  */
28 public interface ConditionalConverter<S, D> extends Converter<S, D> {
29   public enum MatchResult {
30     /** Indicates that the source and destination types were matched. */
31     FULL,
32     /** Indicates that only the destination type was matched. */
33     PARTIAL,
34     /** Indicates that the destination type was not matched. */
35     NONE;
36   }
37
38   /**
39    * Determines whether the converter matches and supports conversion from {@code sourceType} to
40    * {@code destinationType}.
41    * <p>
42    * In the case of a partial match, the converter is indicating that it does not recognise the
43    * source type but that it may still be capable performing the conversion implicitly by parsing the
44    * result of calling {@link Object#toString()} or by some other means which similarly does not
45    * require knowledge of the type at compile time.
46    * <p>
47    * Implicit conversion may result in conversions which are susceptible to unexpected failure when
48    * property types or formats change. Conversion of properties with partially matched types can be
49    * disabled via {@link Configuration#setFullTypeMatchingRequired(boolean)}.
50    * 
51    * @param sourceType to match
52    * @param destinationType to match
53    * @return <ul>
54    *         <li>{@link MatchResult#FULL} if {@code sourceType} and {@code destinationType} are
55    *         matched</li>
56    *         <li>{@link MatchResult#PARTIAL} if {@code destinationType} is matched</li>
57    *         <li>{@link MatchResult#NONE} if {@code destinationType} is not matched</li>
58    *         </ul>
59    */
60   MatchResult match(Class<?> sourceType, Class<?> destinationType);
61 }
62