001 /* 002 * Copyright 2001-2006 Stephen Colebourne 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 package org.joda.time.convert; 017 018 import org.joda.time.Chronology; 019 import org.joda.time.DateTimeZone; 020 import org.joda.time.ReadablePartial; 021 import org.joda.time.format.DateTimeFormatter; 022 023 /** 024 * PartialConverter defines how an object is converted to a ReadablePartial. 025 * <p> 026 * The two methods in this interface must be called in order, as the 027 * <code>getPartialValues</code> method relies on the result of the 028 * <code>getChronology</code> method being passed in. 029 * 030 * @author Stephen Colebourne 031 * @since 1.0 032 */ 033 public interface PartialConverter extends Converter { 034 035 /** 036 * Extracts the chronology from an object of this converter's type 037 * where the time zone is specified. 038 * 039 * @param object the object to convert 040 * @param zone the specified zone to use, null means default zone 041 * @return the chronology, never null 042 * @throws ClassCastException if the object is invalid 043 * @since 1.3 044 */ 045 Chronology getChronology(Object object, DateTimeZone zone); 046 047 /** 048 * Extracts the chronology from an object of this converter's type 049 * where the chronology is specified. 050 * 051 * @param object the object to convert 052 * @param chrono the chronology to use, null usually means ISO 053 * @return the chronology, not converted to UTC/local time zone, must be non-null valid 054 * @throws ClassCastException if the object is invalid 055 */ 056 Chronology getChronology(Object object, Chronology chrono); 057 058 /** 059 * Extracts the values of the partial from an object of this converter's type. 060 * The chrono parameter is a hint to the converter, should it require a 061 * chronology to aid in conversion. 062 * 063 * @param fieldSource a partial that provides access to the fields. 064 * This partial may be incomplete and only getFieldType(int) should be used 065 * @param object the object to convert 066 * @param chrono the chronology to use, which is the non-null result of getChronology() 067 * @return the array of field values that match the fieldSource, must be non-null valid 068 * @throws ClassCastException if the object is invalid 069 */ 070 int[] getPartialValues(ReadablePartial fieldSource, Object object, Chronology chrono); 071 072 /** 073 * Extracts the values of the partial from an object of this converter's type. 074 * The chrono parameter is a hint to the converter, should it require a 075 * chronology to aid in conversion. 076 * 077 * @param fieldSource a partial that provides access to the fields. 078 * This partial may be incomplete and only getFieldType(int) should be used 079 * @param object the object to convert 080 * @param chrono the chronology to use, which is the non-null result of getChronology() 081 * @param parser if converting from a String, the given parser is preferred 082 * @return the array of field values that match the fieldSource, must be non-null valid 083 * @throws ClassCastException if the object is invalid 084 * @since 1.3 085 */ 086 int[] getPartialValues(ReadablePartial fieldSource, Object object, Chronology chrono, 087 DateTimeFormatter parser); 088 089 }