View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.beanutils2;
19  
20  /**
21   * <p>
22   * Utility methods for converting String scalar values to objects of the specified Class, String arrays to arrays of the specified Class.
23   * </p>
24   *
25   * <p>
26   * For more details, see {@code ConvertUtilsBean} which provides the implementations for these methods.
27   * </p>
28   *
29   * @see ConvertUtilsBean
30   */
31  public final class ConvertUtils {
32  
33      /**
34       * <p>
35       * Converts the specified value into a String.
36       * </p>
37       *
38       * <p>
39       * For more details see {@code ConvertUtilsBean}.
40       * </p>
41       *
42       * @param value Value to be converted (may be null)
43       * @return The converted String value or null if value is null
44       * @see ConvertUtilsBean#convert(Object)
45       */
46      public static String convert(final Object value) {
47          return ConvertUtilsBean.getInstance().convert(value);
48      }
49  
50      /**
51       * <p>
52       * Converts the value to an object of the specified class (if possible).
53       * </p>
54       *
55       * @param value      Value to be converted (may be null)
56       * @param targetType Class of the value to be converted to (must not be null)
57       * @return The converted value
58       * @throws ConversionException if thrown by an underlying Converter
59       */
60      public static Object convert(final Object value, final Class<?> targetType) {
61          return ConvertUtilsBean.getInstance().convert(value, targetType);
62      }
63  
64      /**
65       * <p>
66       * Converts the specified value to an object of the specified class (if possible). Otherwise, return a String representation of the value.
67       * </p>
68       *
69       * <p>
70       * For more details see {@code ConvertUtilsBean}.
71       * </p>
72       *
73       * @param value Value to be converted (may be null)
74       * @param clazz Java class to be converted to (must not be null)
75       * @return The converted value
76       * @see ConvertUtilsBean#convert(String, Class)
77       */
78      public static Object convert(final String value, final Class<?> clazz) {
79          return ConvertUtilsBean.getInstance().convert(value, clazz);
80      }
81  
82      /**
83       * <p>
84       * Convert an array of specified values to an array of objects of the specified class (if possible).
85       * </p>
86       *
87       * <p>
88       * For more details see {@code ConvertUtilsBean}.
89       * </p>
90       *
91       * @param values Array of values to be converted
92       * @param clazz  Java array or element class to be converted to (must not be null)
93       * @return The converted value
94       * @see ConvertUtilsBean#convert(String[], Class)
95       */
96      public static Object convert(final String[] values, final Class<?> clazz) {
97          return ConvertUtilsBean.getInstance().convert(values, clazz);
98      }
99  
100     /**
101      * <p>
102      * Remove all registered {@link Converter}s, and re-establish the standard Converters.
103      * </p>
104      *
105      * <p>
106      * For more details see {@code ConvertUtilsBean}.
107      * </p>
108      *
109      * @see ConvertUtilsBean#deregister()
110      */
111     public static void deregister() {
112         ConvertUtilsBean.getInstance().deregister();
113     }
114 
115     /**
116      * <p>
117      * Remove any registered {@link Converter} for the specified destination {@code Class}.
118      * </p>
119      *
120      * <p>
121      * For more details see {@code ConvertUtilsBean}.
122      * </p>
123      *
124      * @param clazz Class for which to remove a registered Converter
125      * @see ConvertUtilsBean#deregister(Class)
126      */
127     public static void deregister(final Class<?> clazz) {
128         ConvertUtilsBean.getInstance().deregister(clazz);
129     }
130 
131     /**
132      * Look up and return any registered {@link Converter} for the specified source and destination class; if there is no registered Converter, return
133      * {@code null}.
134      *
135      * @param <T>        The converter type.
136      * @param sourceType Class of the value being converted
137      * @param targetType Class of the value to be converted to
138      * @return The registered {@link Converter} or {@code null} if not found
139      */
140     public static <T> Converter<T> lookup(final Class<?> sourceType, final Class<T> targetType) {
141         return ConvertUtilsBean.getInstance().lookup(sourceType, targetType);
142     }
143 
144     /**
145      * <p>
146      * Look up and return any registered {@link Converter} for the specified destination class; if there is no registered Converter, return {@code null}.
147      * </p>
148      *
149      * <p>
150      * For more details see {@code ConvertUtilsBean}.
151      * </p>
152      *
153      * @param <T>   The converter type.
154      * @param clazz Class for which to return a registered Converter
155      * @return The registered {@link Converter} or {@code null} if not found
156      * @see ConvertUtilsBean#lookup(Class)
157      */
158     public static <T> Converter<T> lookup(final Class<T> clazz) {
159         return ConvertUtilsBean.getInstance().lookup(clazz);
160     }
161 
162     /**
163      * Change primitive Class types to the associated wrapper class. This is useful for concrete converter implementations which typically treat primitive types
164      * like their corresponding wrapper types.
165      *
166      * @param <T>  The type to be checked.
167      * @param type The class type to check.
168      * @return The converted type.
169      * @since 1.9
170      */
171     // All type casts are safe because the TYPE members of the wrapper types
172     // return their own class.
173     @SuppressWarnings("unchecked")
174     public static <T> Class<T> primitiveToWrapper(final Class<T> type) {
175         if (type == null || !type.isPrimitive()) {
176             return type;
177         }
178 
179         if (type == Integer.TYPE) {
180             return (Class<T>) Integer.class;
181         }
182         if (type == Double.TYPE) {
183             return (Class<T>) Double.class;
184         }
185         if (type == Long.TYPE) {
186             return (Class<T>) Long.class;
187         }
188         if (type == Boolean.TYPE) {
189             return (Class<T>) Boolean.class;
190         }
191         if (type == Float.TYPE) {
192             return (Class<T>) Float.class;
193         }
194         if (type == Short.TYPE) {
195             return (Class<T>) Short.class;
196         }
197         if (type == Byte.TYPE) {
198             return (Class<T>) Byte.class;
199         }
200         if (type == Character.TYPE) {
201             return (Class<T>) Character.class;
202         }
203         return type;
204     }
205 
206     /**
207      * <p>
208      * Register a custom {@link Converter} for the specified destination {@code Class}, replacing any previously registered Converter.
209      * </p>
210      *
211      * <p>
212      * For more details see {@code ConvertUtilsBean}.
213      * </p>
214      *
215      * @param <T>       The converter type.
216      * @param converter Converter to be registered
217      * @param clazz     Destination class for conversions performed by this Converter
218      * @see ConvertUtilsBean#register(Converter, Class)
219      */
220     public static <T> void register(final Converter<T> converter, final Class<T> clazz) {
221         ConvertUtilsBean.getInstance().register(converter, clazz);
222     }
223 
224     private ConvertUtils() {
225         // empty
226     }
227 }