001 /*
002 * Copyright 2001-2005 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
021 /**
022 * InstantConverter defines how an object is converted to milliseconds/chronology.
023 * <p>
024 * The two methods in this interface must be called in order, as the
025 * <code>getInstantMillis</code> method relies on the result of the
026 * <code>getChronology</code> method being passed in.
027 *
028 * @author Stephen Colebourne
029 * @since 1.0
030 */
031 public interface InstantConverter extends Converter {
032
033 /**
034 * Extracts the chronology from an object of this converter's type
035 * where the time zone is specified.
036 *
037 * @param object the object to convert
038 * @param zone the specified zone to use, null means default zone
039 * @return the chronology, never null
040 * @throws ClassCastException if the object is invalid
041 */
042 Chronology getChronology(Object object, DateTimeZone zone);
043
044 /**
045 * Extracts the chronology from an object of this converter's type
046 * where the chronology may be specified.
047 * <p>
048 * If the chronology is non-null it should be used. If it is null, then the
049 * object should be queried, and if it has no chronology then ISO default is used.
050 *
051 * @param object the object to convert
052 * @param chrono the chronology to use, null means use object
053 * @return the chronology, never null
054 * @throws ClassCastException if the object is invalid
055 */
056 Chronology getChronology(Object object, Chronology chrono);
057
058 //-----------------------------------------------------------------------
059 /**
060 * Extracts the millis from an object of this converter's type.
061 * <p>
062 * The chronology passed in is the result of the call to <code>getChronology</code>.
063 *
064 * @param object the object to convert
065 * @param chrono the chronology to use, which is the non-null result of getChronology()
066 * @return the millisecond instant
067 * @throws ClassCastException if the object is invalid
068 * @throws IllegalArgumentException if object conversion fails
069 */
070 long getInstantMillis(Object object, Chronology chrono);
071
072 }