001/* 002 * Licensed under the Apache License, Version 2.0 (the "License"); 003 * you may not use this file except in compliance with the License. 004 * You may obtain a copy of the License at 005 * 006 * http://www.apache.org/licenses/LICENSE-2.0 007 * 008 * Unless required by applicable law or agreed to in writing, software 009 * distributed under the License is distributed on an "AS IS" BASIS, 010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 011 * See the License for the specific language governing permissions and 012 * limitations under the License. 013 */ 014package org.gbif.common.parsers.date; 015 016import org.gbif.common.parsers.core.Parsable; 017import org.gbif.common.parsers.core.ParseResult; 018 019import java.time.temporal.TemporalAccessor; 020 021import javax.annotation.Nullable; 022 023/** 024 * Main interface for date/time parsing based. 025 */ 026public interface TemporalParser extends Parsable<TemporalAccessor> { 027 028 /** 029 * Parse a date represented as a single String into a TemporalAccessor. 030 * 031 * @param input 032 * @return result, never null 033 */ 034 @Override 035 ParseResult<TemporalAccessor> parse(String input); 036 037 /** 038 * Parse a String date <em>restricted to the <code>ordering</code> provided</em>. 039 * 040 * Set a general date ordering for the parsing. For example, DMY will support both 14.08.2020 and 041 * 14/08/2020, but <em>not</em> 2020-08-14 or 08/14/2020. 042 * 043 * NOTE, this behaviour <strong>differs</strong> from {@link #parse(String, DateComponentOrdering[])}. 044 * 045 * @param ordering required date ordering. 046 * @return result, never null 047 */ 048 ParseResult<TemporalAccessor> parse(String input, @Nullable DateComponentOrdering ordering); 049 050 /** 051 * Parse a String date to a TemporalAccessor, attempting unambiguous formats and the 052 * <code>orderings</code> provided. 053 * 054 * The date 2020-08-14 will always parse. An <code>ordering</code> of DMY_FORMATS will also 055 * support 14.08.2020, 14/08/2020 and 14/08/2020 14:11:00, but not 08/14/2020. 056 * 057 * NOTE, this behaviour <strong>differs</strong> from {@link #parse(String, DateComponentOrdering)}. 058 * 059 * @param orderings required general date orderings 060 * @return result, never null 061 */ 062 ParseResult<TemporalAccessor> parse(String input, @Nullable DateComponentOrdering[] orderings); 063 064 /** 065 * Parse year, month, day strings as a TemporalAccessor. 066 * 067 * @param year numerical value of a year 068 * @param month value of the mont depending on the implementation, numerical value of a 069 * month (starting at 1 for January) or possibly text. 070 * @param day numerical value of a day 071 * @return result, never null 072 */ 073 ParseResult<TemporalAccessor> parse(@Nullable String year, @Nullable String month, @Nullable String day); 074 075 /** 076 * Parse year, month, day integers as a TemporalAccessor. 077 * 078 * @param year numerical value of a year 079 * @param month numerical value of a month (starting at 1 for January) 080 * @param day numerical value of a day 081 * @return result, never null 082 */ 083 ParseResult<TemporalAccessor> parse(@Nullable Integer year, @Nullable Integer month, @Nullable Integer day); 084 085 /** 086 * Parse year, dayOfYear strings as a TemporalAccessor. 087 * 088 * @param year numerical value of a year 089 * @param dayOfYear numerical value of a day of the year 090 * @return result, never null 091 */ 092 ParseResult<TemporalAccessor> parse(@Nullable String year, @Nullable String dayOfYear); 093 094 /** 095 * Parse year, dayOfYear integers as a TemporalAccessor. 096 * 097 * @param year numerical value of a year 098 * @param dayOfYear numerical value of a day of the year 099 * @return result, never null 100 */ 101 ParseResult<TemporalAccessor> parse(@Nullable Integer year, @Nullable Integer dayOfYear); 102}