1 /*******************************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *******************************************************************************/
19 package org.apache.commons.convert;
20
21 import java.util.Locale;
22 import java.util.TimeZone;
23
24 /** Localized converter interface. Classes implement this interface
25 * to convert one object type to another. Methods are provided to
26 * localize the conversion.
27 * <p>Localized converters are necessary for things like dates, times, and numbers. Those
28 * conversions are dependent on a locale and/or time zone. Java's default conversions
29 * (<code>toString</code>, <code>valueOf</code>) use the JVM's default locale and
30 * time zone - which might not be what the application requires. Implementations of
31 * <code>LocalizedConverter</code> will use the specified locale and time zone instead of
32 * the JVM defaults.</p>
33 */
34 public interface LocalizedConverter<S, T> extends Converter<S, T> {
35 /** Converts <code>obj</code> to <code>T</code>.
36 *
37 * @param obj The source <code>Object</code> to convert
38 * @param locale The locale used for conversion - must not be <code>null</code>
39 * @param timeZone The time zone used for conversion - must not be <code>null</code>
40 * @return The converted <code>Object</code>
41 * @throws ConversionException
42 */
43 public T convert(S obj, Locale locale, TimeZone timeZone) throws ConversionException;
44
45 /** Converts <code>obj</code> to <code>T</code>.
46 *
47 * @param obj The source <code>Object</code> to convert
48 * @param locale The locale used for conversion - must not be <code>null</code>
49 * @param timeZone The time zone used for conversion - must not be <code>null</code>
50 * @param formatString Optional formatting string
51 * @return The converted <code>Object</code>
52 * @throws ConversionException
53 */
54 public T convert(S obj, Locale locale, TimeZone timeZone, String formatString) throws ConversionException;
55 }