1/*
2 * Copyright (c) 1996, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.sql;
27
28import java.time.Instant;
29import java.time.LocalTime;
30import jdk.internal.misc.SharedSecrets;
31import jdk.internal.misc.JavaLangAccess;
32
33/**
34 * <P>A thin wrapper around the <code>java.util.Date</code> class that allows the JDBC
35 * API to identify this as an SQL <code>TIME</code> value. The <code>Time</code>
36 * class adds formatting and
37 * parsing operations to support the JDBC escape syntax for time
38 * values.
39 * <p>The date components should be set to the "zero epoch"
40 * value of January 1, 1970 and should not be accessed.
41 *
42 * @since 1.1
43 */
44public class Time extends java.util.Date {
45
46    private static final JavaLangAccess jla = SharedSecrets.getJavaLangAccess();
47
48    /**
49     * Constructs a <code>Time</code> object initialized with the
50     * given values for the hour, minute, and second.
51     * The driver sets the date components to January 1, 1970.
52     * Any method that attempts to access the date components of a
53     * <code>Time</code> object will throw a
54     * <code>java.lang.IllegalArgumentException</code>.
55     * <P>
56     * The result is undefined if a given argument is out of bounds.
57     *
58     * @param hour 0 to 23
59     * @param minute 0 to 59
60     * @param second 0 to 59
61     *
62     * @deprecated Use the constructor that takes a milliseconds value
63     *             in place of this constructor
64     */
65    @Deprecated(since="1.2")
66    public Time(int hour, int minute, int second) {
67        super(70, 0, 1, hour, minute, second);
68    }
69
70    /**
71     * Constructs a <code>Time</code> object using a milliseconds time value.
72     *
73     * @param time milliseconds since January 1, 1970, 00:00:00 GMT;
74     *             a negative number is milliseconds before
75     *               January 1, 1970, 00:00:00 GMT
76     */
77    public Time(long time) {
78        super(time);
79    }
80
81    /**
82     * Sets a <code>Time</code> object using a milliseconds time value.
83     *
84     * @param time milliseconds since January 1, 1970, 00:00:00 GMT;
85     *             a negative number is milliseconds before
86     *               January 1, 1970, 00:00:00 GMT
87     */
88    public void setTime(long time) {
89        super.setTime(time);
90    }
91
92    /**
93     * Converts a string in JDBC time escape format to a <code>Time</code> value.
94     *
95     * @param s time in format "hh:mm:ss"
96     * @return a corresponding <code>Time</code> object
97     */
98    public static Time valueOf(String s) {
99        if (s == null) throw new java.lang.IllegalArgumentException();
100
101        int hour;
102        int minute;
103        int second;
104        int firstColon = s.indexOf(':');
105        int secondColon = s.indexOf(':', firstColon + 1);
106        int len = s.length();
107        if (firstColon > 0 && secondColon > 0 &&
108                secondColon < len - 1) {
109            hour = Integer.parseInt(s, 0, firstColon, 10);
110            minute = Integer.parseInt(s, firstColon + 1, secondColon, 10);
111            second = Integer.parseInt(s, secondColon + 1, len, 10);
112        } else {
113            throw new java.lang.IllegalArgumentException();
114        }
115
116        return new Time(hour, minute, second);
117    }
118
119    /**
120     * Formats a time in JDBC time escape format.
121     *
122     * @return a <code>String</code> in hh:mm:ss format
123     */
124    @SuppressWarnings("deprecation")
125    public String toString () {
126        int hour = super.getHours();
127        int minute = super.getMinutes();
128        int second = super.getSeconds();
129
130        char[] buf = new char[8];
131        Date.formatDecimalInt(hour, buf, 0, 2);
132        buf[2] = ':';
133        Date.formatDecimalInt(minute, buf, 3, 2);
134        buf[5] = ':';
135        Date.formatDecimalInt(second, buf, 6, 2);
136
137        return jla.newStringUnsafe(buf);
138    }
139
140    // Override all the date operations inherited from java.util.Date;
141
142   /**
143    * This method is deprecated and should not be used because SQL <code>TIME</code>
144    * values do not have a year component.
145    *
146    * @deprecated
147    * @exception java.lang.IllegalArgumentException if this
148    *           method is invoked
149    * @see #setYear
150    */
151    @Deprecated(since="1.2")
152    public int getYear() {
153        throw new java.lang.IllegalArgumentException();
154    }
155
156   /**
157    * This method is deprecated and should not be used because SQL <code>TIME</code>
158    * values do not have a month component.
159    *
160    * @deprecated
161    * @exception java.lang.IllegalArgumentException if this
162    *           method is invoked
163    * @see #setMonth
164    */
165    @Deprecated(since="1.2")
166    public int getMonth() {
167        throw new java.lang.IllegalArgumentException();
168    }
169
170   /**
171    * This method is deprecated and should not be used because SQL <code>TIME</code>
172    * values do not have a day component.
173    *
174    * @deprecated
175    * @exception java.lang.IllegalArgumentException if this
176    *           method is invoked
177    */
178    @Deprecated(since="1.2")
179    public int getDay() {
180        throw new java.lang.IllegalArgumentException();
181    }
182
183   /**
184    * This method is deprecated and should not be used because SQL <code>TIME</code>
185    * values do not have a date component.
186    *
187    * @deprecated
188    * @exception java.lang.IllegalArgumentException if this
189    *           method is invoked
190    * @see #setDate
191    */
192    @Deprecated(since="1.2")
193    public int getDate() {
194        throw new java.lang.IllegalArgumentException();
195    }
196
197   /**
198    * This method is deprecated and should not be used because SQL <code>TIME</code>
199    * values do not have a year component.
200    *
201    * @deprecated
202    * @exception java.lang.IllegalArgumentException if this
203    *           method is invoked
204    * @see #getYear
205    */
206    @Deprecated(since="1.2")
207    public void setYear(int i) {
208        throw new java.lang.IllegalArgumentException();
209    }
210
211   /**
212    * This method is deprecated and should not be used because SQL <code>TIME</code>
213    * values do not have a month component.
214    *
215    * @deprecated
216    * @exception java.lang.IllegalArgumentException if this
217    *           method is invoked
218    * @see #getMonth
219    */
220    @Deprecated(since="1.2")
221    public void setMonth(int i) {
222        throw new java.lang.IllegalArgumentException();
223    }
224
225   /**
226    * This method is deprecated and should not be used because SQL <code>TIME</code>
227    * values do not have a date component.
228    *
229    * @deprecated
230    * @exception java.lang.IllegalArgumentException if this
231    *           method is invoked
232    * @see #getDate
233    */
234    @Deprecated(since="1.2")
235    public void setDate(int i) {
236        throw new java.lang.IllegalArgumentException();
237    }
238
239   /**
240    * Private serial version unique ID to ensure serialization
241    * compatibility.
242    */
243    static final long serialVersionUID = 8397324403548013681L;
244
245    /**
246     * Obtains an instance of {@code Time} from a {@link LocalTime} object
247     * with the same hour, minute and second time value as the given
248     * {@code LocalTime}. The nanosecond field from {@code LocalTime} is
249     * not part of the newly created {@code Time} object.
250     *
251     * @param time a {@code LocalTime} to convert
252     * @return a {@code Time} object
253     * @exception NullPointerException if {@code time} is null
254     * @since 1.8
255     */
256    @SuppressWarnings("deprecation")
257    public static Time valueOf(LocalTime time) {
258        return new Time(time.getHour(), time.getMinute(), time.getSecond());
259    }
260
261    /**
262     * Converts this {@code Time} object to a {@code LocalTime}.
263     * <p>
264     * The conversion creates a {@code LocalTime} that represents the same
265     * hour, minute, and second time value as this {@code Time}. The
266     * nanosecond {@code LocalTime} field will be set to zero.
267     *
268     * @return a {@code LocalTime} object representing the same time value
269     * @since 1.8
270     */
271    @SuppressWarnings("deprecation")
272    public LocalTime toLocalTime() {
273        return LocalTime.of(getHours(), getMinutes(), getSeconds());
274    }
275
276   /**
277    * This method always throws an UnsupportedOperationException and should
278    * not be used because SQL {@code Time} values do not have a date
279    * component.
280    *
281    * @exception java.lang.UnsupportedOperationException if this method is invoked
282    */
283    @Override
284    public Instant toInstant() {
285        throw new java.lang.UnsupportedOperationException();
286    }
287}
288