01: /*
02: * Copyright 2001-2006 Stephen Colebourne
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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,
71: Chronology chrono);
72:
73: /**
74: * Extracts the values of the partial from an object of this converter's type.
75: * The chrono parameter is a hint to the converter, should it require a
76: * chronology to aid in conversion.
77: *
78: * @param fieldSource a partial that provides access to the fields.
79: * This partial may be incomplete and only getFieldType(int) should be used
80: * @param object the object to convert
81: * @param chrono the chronology to use, which is the non-null result of getChronology()
82: * @param parser if converting from a String, the given parser is preferred
83: * @return the array of field values that match the fieldSource, must be non-null valid
84: * @throws ClassCastException if the object is invalid
85: * @since 1.3
86: */
87: int[] getPartialValues(ReadablePartial fieldSource, Object object,
88: Chronology chrono, DateTimeFormatter parser);
89:
90: }
|