1 /*
2 * This file is part of Pease Plate Template Engine.
3 *
4 * Pease Plate Template Engine is free software: you can redistribute
5 * it and/or modify it under the terms of the GNU Lesser General
6 * Public License as published by the Free Software Foundation,
7 * either version 3 of the License, or any later version.
8 *
9 * Pease Plate Template Engine is distributed in the hope that it
10 * will be useful, but WITHOUT ANY WARRANTY; without even the implied
11 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
12 * See the GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with Pease Plate Template Engine. If not, see
16 * <http://www.gnu.org/licenses/>.
17 *
18 * Copyright (c) 2008 Manfred HANTSCHEL
19 */
20 package org.peaseplate.service;
21
22 import org.peaseplate.internal.conversion.ConversionException;
23 import org.peaseplate.lang.Conversion;
24
25 /**
26 * The conversion service is responsible for converting values from
27 * one data type to another.
28 *
29 * The service can be enhances by adding {@link ConversionInitializer}s to it.
30 *
31 * @author Manfred Hantschel
32 */
33 public interface ConversionService {
34
35 /**
36 * Scans the specified class loaders for conversion service definitions.
37 * The definitions are located in a resource with the name
38 * "META-INF/services/org.peaseplate.service.ConversionService".
39 * The file contains class names of {@link ConversionInitializer}s, one class name per line.
40 *
41 * @param classLoaders the class loaders
42 * @throws IllegalArgumentException if a class could not be instantiated
43 */
44 public void add(ClassLoader... classLoaders) throws IllegalArgumentException;
45
46 /**
47 * Adds the conversion initializer specified by its class name to the service.
48 * The instance will be created immediately, passed to the add(ConversionInitializer) method
49 * and then thrown away.
50 *
51 * @param initializerClass the class
52 * @throws IllegalArgumentException if the class could not be instantiated
53 */
54 public void add(Class<? extends ConversionInitializer> initializerClass) throws IllegalArgumentException;
55
56 /**
57 * Adds the conversions in the conversion initializer to the service.
58 * The initializer itself will not be stored and can be thrown away.
59 *
60 * @param initializer the initializer
61 */
62 public void add(ConversionInitializer initializer);
63
64 /**
65 * Adds a conversion from the specified source type to the specified target type
66 * to the service.
67 *
68 * @param <SOURCE> the source type
69 * @param <TARGET> the target type
70 * @param sourceType the source type
71 * @param targetType the target type
72 * @param conversion the conversion
73 */
74 public <SOURCE, TARGET> void add(Class<SOURCE> sourceType, Class<TARGET> targetType, Conversion<SOURCE, TARGET> conversion);
75
76 /**
77 * Converts the specified value to the specified target type.
78 * If the value is null, it converts this value according to the conversion rule.
79 *
80 * @param <SOURCE> the source type
81 * @param <TARGET> the target type
82 * @param value the value, may be null
83 * @param targetType the target type
84 * @return the converted value
85 * @throws ConversionException if something went wrong during converting
86 */
87 public <SOURCE, TARGET> TARGET convey(SOURCE value, Class<TARGET> targetType) throws ConversionException;
88
89 /**
90 * Converts the specified value to the specified target type.
91 * If the value is null, it returns null, and does not use the conversion rule.
92 *
93 * @param <SOURCE> the source type
94 * @param <TARGET> the target type
95 * @param value the value, may be null
96 * @param targetType the target type
97 * @return the converted value
98 * @throws ConversionException if something went wrong during converting
99 */
100 public <SOURCE, TARGET> TARGET convert(SOURCE value, Class<TARGET> targetType) throws ConversionException;
101
102 /**
103 * Returns true if there is a conversion rule defined for the specified
104 * source type and the specified target type.
105 *
106 * @param <SOURCE> the source type
107 * @param <TARGET> the target type
108 * @param sourceType the source type
109 * @param targetType the target type
110 * @return true if conversion rule is defined
111 */
112 public <SOURCE, TARGET> boolean isConvertable(Class<SOURCE> sourceType, Class<TARGET> targetType);
113
114 }