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 */
016package org.joda.time.convert;
017
018import org.joda.time.Chronology;
019import 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 */
031public 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}