/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3.time;

import java.text.ParseException;
import java.text.ParsePosition;
import java.util.Calendar;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;

/**
 * <p>DateParser is the "missing" interface for the parsing methods of 
 * {@link java.text.DateFormat}.</p>
 * 
 * @since 3.2
 */
public interface DateParser {

    /**
     * Equivalent to DateFormat.parse(String). 
     * 
     * See {@link java.text.DateFormat#parse(String)} for more information. 
     * @param source A <code>String</code> whose beginning should be parsed. 
     * @return A <code>Date</code> parsed from the string
     * @throws ParseException if the beginning of the specified string cannot be parsed.
     */
    public Date parse(String source) throws ParseException;

    /**
     * Equivalent to DateFormat.parse(String, ParsePosition). 
     * 
     * See {@link java.text.DateFormat#parse(String, ParsePosition)} for more information. 
     * 
     * @param source A <code>String</code>, part of which should be parsed.
     * @param pos A <code>ParsePosition</code> object with index and error index information 
     * as described above. 
     * @return A <code>Date</code> parsed from the string. In case of error, returns null. 
     * @throws NullPointerException if text or pos is null.
     */
    public Date parse(String source, ParsePosition pos);

    // Accessors
    //-----------------------------------------------------------------------
    /**
     * <p>Get the pattern used by this parser.</p>
     * 
     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
     */
    public String getPattern();

    /**
     * <p>Get the time zone used by this parser.</p>
     *
     * <p>This zone is always used for <code>Date</code> formatting.
     * If a <code>Calendar</code> is passed in to be formatted, the
     * time zone on that may be used depending on {@link Calendar#getTimeZone()}.
     * </p>
     * 
     * @return the time zone
     */
    public TimeZone getTimeZone();

    /**
     * <p>Get the locale used by this parser.</p>
     * 
     * @return the locale
     */
    public Locale getLocale();

    /**
     * Parses text from a string to produce a Date.
     * See {@link java.text.DateFormat#parseObject(String)} 
     */
    Object parseObject(String source) throws ParseException;

    /**
     * Parse a date/time string according to the given parse position. 
     * See {@link java.text.DateFormat#parseObject(String, ParsePosition)} 
     */
    public Object parseObject(String source, ParsePosition pos);
}

@@ -2487,32 +2487,40 @@
   /**%0A     * %3Cp%3E
+%0A     * 
 Get the time zon
@@ -2533,32 +2533,40 @@
  by this parser.
+%0A     * 
 %3C/p%3E%0A     *%0A    
@@ -2560,16 +2560,17 @@
 %3E%0A     *
+ 
 %0A     * 
@@ -2576,215 +2576,146 @@
  %3Cp%3E
-This zone is always used for %3Ccode%3EDate%3C/code%3E formatting.%0A     * If a %3Ccode%3ECalendar%3C/code%3E is passed in to be formatted, the%0A     * time zone on that may be used depending on %7B@link Calendar#getTimeZone()%7D
+%0A     * The default %7B@link TimeZone%7D used to create a %7B@link Date%7D when the %7B@link TimeZone%7D is not specified by%0A     * the format pattern
 .%0A  

Fix Javdoc.