001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.time;
018
019import java.text.ParseException;
020import java.text.ParsePosition;
021import java.util.Date;
022import java.util.Locale;
023import java.util.TimeZone;
024
025/**
026 * <p>DateParser is the "missing" interface for the parsing methods of 
027 * {@link java.text.DateFormat}.</p>
028 * 
029 * @since 3.2
030 */
031public interface DateParser {
032
033    /**
034     * Equivalent to DateFormat.parse(String). 
035     * 
036     * See {@link java.text.DateFormat#parse(String)} for more information. 
037     * @param source A <code>String</code> whose beginning should be parsed. 
038     * @return A <code>Date</code> parsed from the string
039     * @throws ParseException if the beginning of the specified string cannot be parsed.
040     */
041    Date parse(String source) throws ParseException;
042
043    /**
044     * Equivalent to DateFormat.parse(String, ParsePosition). 
045     * 
046     * See {@link java.text.DateFormat#parse(String, ParsePosition)} for more information. 
047     * 
048     * @param source A <code>String</code>, part of which should be parsed.
049     * @param pos A <code>ParsePosition</code> object with index and error index information 
050     * as described above. 
051     * @return A <code>Date</code> parsed from the string. In case of error, returns null. 
052     * @throws NullPointerException if text or pos is null.
053     */
054    Date parse(String source, ParsePosition pos);
055
056    // Accessors
057    //-----------------------------------------------------------------------
058    /**
059     * <p>Get the pattern used by this parser.</p>
060     * 
061     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
062     */
063    String getPattern();
064
065    /**
066     * <p>
067     * Get the time zone used by this parser.
068     * </p>
069     * 
070     * <p>
071     * The default {@link TimeZone} used to create a {@link Date} when the {@link TimeZone} is not specified by
072     * the format pattern.
073     * </p>
074     * 
075     * @return the time zone
076     */
077    TimeZone getTimeZone();
078
079    /**
080     * <p>Get the locale used by this parser.</p>
081     * 
082     * @return the locale
083     */
084    Locale getLocale();
085
086    /**
087     * Parses text from a string to produce a Date.
088     * 
089     * @param source A <code>String</code> whose beginning should be parsed.
090     * @return a <code>java.util.Date</code> object
091     * @throws ParseException if the beginning of the specified string cannot be parsed.
092     * @see java.text.DateFormat#parseObject(String) 
093     */
094    Object parseObject(String source) throws ParseException;
095
096    /**
097     * Parse a date/time string according to the given parse position.
098     * 
099     * @param source A <code>String</code> whose beginning should be parsed.
100     * @param pos the parse position
101     * @return a <code>java.util.Date</code> object
102     * @see java.text.DateFormat#parseObject(String, ParsePosition) 
103     */
104    Object parseObject(String source, ParsePosition pos);
105}