1 /*
2 * Copyright 2001-2006 Stephen Colebourne
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.joda.time.convert;
17
18 import org.joda.time.Chronology;
19 import org.joda.time.DateTimeZone;
20 import org.joda.time.ReadablePartial;
21 import org.joda.time.format.DateTimeFormatter;
22
23 /**
24 * PartialConverter defines how an object is converted to a ReadablePartial.
25 * <p>
26 * The two methods in this interface must be called in order, as the
27 * <code>getPartialValues</code> method relies on the result of the
28 * <code>getChronology</code> method being passed in.
29 *
30 * @author Stephen Colebourne
31 * @since 1.0
32 */
33 public interface PartialConverter extends Converter {
34
35 /**
36 * Extracts the chronology from an object of this converter's type
37 * where the time zone is specified.
38 *
39 * @param object the object to convert
40 * @param zone the specified zone to use, null means default zone
41 * @return the chronology, never null
42 * @throws ClassCastException if the object is invalid
43 * @since 1.3
44 */
45 Chronology getChronology(Object object, DateTimeZone zone);
46
47 /**
48 * Extracts the chronology from an object of this converter's type
49 * where the chronology is specified.
50 *
51 * @param object the object to convert
52 * @param chrono the chronology to use, null usually means ISO
53 * @return the chronology, not converted to UTC/local time zone, must be non-null valid
54 * @throws ClassCastException if the object is invalid
55 */
56 Chronology getChronology(Object object, Chronology chrono);
57
58 /**
59 * Extracts the values of the partial from an object of this converter's type.
60 * The chrono parameter is a hint to the converter, should it require a
61 * chronology to aid in conversion.
62 *
63 * @param fieldSource a partial that provides access to the fields.
64 * This partial may be incomplete and only getFieldType(int) should be used
65 * @param object the object to convert
66 * @param chrono the chronology to use, which is the non-null result of getChronology()
67 * @return the array of field values that match the fieldSource, must be non-null valid
68 * @throws ClassCastException if the object is invalid
69 */
70 int[] getPartialValues(ReadablePartial fieldSource, Object object, Chronology chrono);
71
72 /**
73 * Extracts the values of the partial from an object of this converter's type.
74 * The chrono parameter is a hint to the converter, should it require a
75 * chronology to aid in conversion.
76 *
77 * @param fieldSource a partial that provides access to the fields.
78 * This partial may be incomplete and only getFieldType(int) should be used
79 * @param object the object to convert
80 * @param chrono the chronology to use, which is the non-null result of getChronology()
81 * @param parser if converting from a String, the given parser is preferred
82 * @return the array of field values that match the fieldSource, must be non-null valid
83 * @throws ClassCastException if the object is invalid
84 * @since 1.3
85 */
86 int[] getPartialValues(ReadablePartial fieldSource, Object object, Chronology chrono,
87 DateTimeFormatter parser);
88
89 }