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: */
017:
018: package java.sql;
019:
020: import java.text.SimpleDateFormat;
021:
022: /**
023: * A Date class which can consume and produce dates in SQL Date format.
024: * <p>
025: * The SQL date format represents a date as yyyy-mm-dd. Note that this date
026: * format only deals with year, month and day values. There are no values for
027: * hours, minutes, seconds.
028: * <p>
029: * This contrasts with regular java.util.Date values, which include time values
030: * for hours, minutes, seconds, milliseconds.
031: * <p>
032: * Time points are handled as millisecond values - milliseconds since the epoch,
033: * January 1st 1970, 00:00:00.000 GMT. Time values passed to the java.sql.Date
034: * class are "normalized" to the time 00:00:00.000 GMT on the date implied by
035: * the time value.
036: */
037: public class Date extends java.util.Date {
038:
039: private static final long serialVersionUID = 1511598038487230103L;
040:
041: /**
042: * @deprecated Please use the constructor Date( long ) Constructs a Date
043: * object corresponding to the supplied Year, Month and Day.
044: * @param theYear
045: * the year, specified as the year minus 1900. Must be in the
046: * range 0 to 8099.
047: * @param theMonth
048: * the month, specified as a number with 0 = January. Must be in
049: * the range 0 to 11.
050: * @param theDay
051: * the day in the month. Must be in the range 1 to 31.
052: */
053: @Deprecated
054: public Date(int theYear, int theMonth, int theDay) {
055: super (theYear, theMonth, theDay);
056: }
057:
058: /**
059: * Creates a Date which corresponds to the day implied by the supplied
060: * theDate milliseconds time value.
061: *
062: * @param theDate -
063: * a time value in milliseconds since the epoch - January 1 1970
064: * 00:00:00 GMT. The time value (hours, minutes, seconds,
065: * milliseconds) stored in the Date object is adjusted to
066: * correspond to 00:00:00 GMT on the day implied by the supplied
067: * time value.
068: */
069: public Date(long theDate) {
070: super (normalizeTime(theDate));
071: }
072:
073: /**
074: * @deprecated This method is deprecated and must not be used. SQL Date
075: * values do not have an hours component.
076: * @return does not return
077: * @throws IllegalArgumentException
078: * if this method is called
079: */
080: @Deprecated
081: @Override
082: public int getHours() {
083: throw new IllegalArgumentException();
084: }
085:
086: /**
087: * @deprecated This method is deprecated and must not be used. SQL Date
088: * values do not have a minutes component.
089: * @return does not return
090: * @throws IllegalArgumentException
091: * if this method is called
092: */
093: @Deprecated
094: @Override
095: public int getMinutes() {
096: throw new IllegalArgumentException();
097: }
098:
099: /**
100: * @deprecated This method is deprecated and must not be used. SQL Date
101: * values do not have a seconds component.
102: * @return does not return
103: * @throws IllegalArgumentException
104: * if this method is called
105: */
106: @Deprecated
107: @Override
108: public int getSeconds() {
109: throw new IllegalArgumentException();
110: }
111:
112: /**
113: * @deprecated This method is deprecated and must not be used. SQL Date
114: * values do not have an hours component.
115: * @param theHours
116: * the number of hours to set
117: * @throws IllegalArgumentException
118: * if this method is called
119: */
120: @Deprecated
121: @Override
122: public void setHours(int theHours) {
123: throw new IllegalArgumentException();
124: }
125:
126: /**
127: * @deprecated This method is deprecated and must not be used. SQL Date
128: * values do not have a minutes component.
129: * @param theMinutes
130: * the number of minutes to set
131: * @throws IllegalArgumentException
132: * if this method is called
133: */
134: @Deprecated
135: @Override
136: public void setMinutes(int theMinutes) {
137: throw new IllegalArgumentException();
138: }
139:
140: /**
141: * @deprecated This method is deprecated and must not be used. SQL Date
142: * values do not have a seconds component.
143: * @param theSeconds
144: * the number of seconds to set
145: * @throws IllegalArgumentException
146: * if this method is called
147: */
148: @Deprecated
149: @Override
150: public void setSeconds(int theSeconds) {
151: throw new IllegalArgumentException();
152: }
153:
154: /**
155: * Sets this date to a date supplied as a milliseconds value. The date is
156: * set based on the supplied time value after removing any time elements
157: * finer than a day, based on zero GMT for that day.
158: *
159: * @param theTime
160: * the time in milliseconds since the Epoch
161: */
162: @Override
163: public void setTime(long theTime) {
164: /*
165: * Store the Date based on the supplied time after removing any time
166: * elements finer than the day based on zero GMT
167: */
168: super .setTime(normalizeTime(theTime));
169: }
170:
171: /**
172: * Produces a string representation of the Date in SQL format
173: *
174: * @return a string representation of the Date in SQL format - "yyyy-mm-dd".
175: */
176: @Override
177: public String toString() {
178: SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); //$NON-NLS-1$
179: return dateFormat.format(this );
180: }
181:
182: /**
183: * Creates a Date from a string representation of a date in SQL format.
184: *
185: * @param dateString
186: * the string representation of a date in SQL format -
187: * "yyyy-mm-dd".
188: * @return the Date object
189: * @throws IllegalArgumentException
190: * if the format of the supplied string does not match the SQL
191: * format.
192: */
193: public static Date valueOf(String dateString) {
194: if (dateString == null) {
195: throw new IllegalArgumentException();
196: }
197: int firstIndex = dateString.indexOf('-');
198: int secondIndex = dateString.indexOf('-', firstIndex + 1);
199: // secondIndex == -1 means none or only one separator '-' has been
200: // found.
201: // The string is separated into three parts by two separator characters,
202: // if the first or the third part is null string, we should throw
203: // IllegalArgumentException to follow RI
204: if (secondIndex == -1 || firstIndex == 0
205: || secondIndex + 1 == dateString.length()) {
206: throw new IllegalArgumentException();
207: }
208: // parse each part of the string
209: int year = Integer
210: .parseInt(dateString.substring(0, firstIndex));
211: int month = Integer.parseInt(dateString.substring(
212: firstIndex + 1, secondIndex));
213: int day = Integer.parseInt(dateString.substring(
214: secondIndex + 1, dateString.length()));
215: return new Date(year - 1900, month - 1, day);
216: }
217:
218: /*
219: * Private method which normalizes a Time value, removing all low
220: * significance digits corresponding to milliseconds, seconds, minutes and
221: * hours, so that the returned Time value corresponds to 00:00:00 GMT on a
222: * particular day.
223: */
224: private static long normalizeTime(long theTime) {
225: return theTime;
226: }
227: }
|