1 /*
2 * Copyright (c) 1996, 2013, 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
26 package java.sql;
27
28 import java.time.Instant;
29 import java.time.LocalTime;
30
31 /**
32 * <P>A thin wrapper around the <code>java.util.Date</code> class that allows the JDBC
33 * API to identify this as an SQL <code>TIME</code> value. The <code>Time</code>
34 * class adds formatting and
35 * parsing operations to support the JDBC escape syntax for time
36 * values.
37 * <p>The date components should be set to the "zero epoch"
38 * value of January 1, 1970 and should not be accessed.
39 */
40 public class Time extends java.util.Date {
41
42 /**
43 * Constructs a <code>Time</code> object initialized with the
44 * given values for the hour, minute, and second.
45 * The driver sets the date components to January 1, 1970.
46 * Any method that attempts to access the date components of a
47 * <code>Time</code> object will throw a
48 * <code>java.lang.IllegalArgumentException</code>.
49 * <P>
50 * The result is undefined if a given argument is out of bounds.
51 *
52 * @param hour 0 to 23
53 * @param minute 0 to 59
54 * @param second 0 to 59
55 *
56 * @deprecated Use the constructor that takes a milliseconds value
57 * in place of this constructor
58 */
59 @Deprecated
60 public Time(int hour, int minute, int second) {
61 super(70, 0, 1, hour, minute, second);
62 }
63
64 /**
65 * Constructs a <code>Time</code> object using a milliseconds time value.
66 *
67 * @param time milliseconds since January 1, 1970, 00:00:00 GMT;
68 * a negative number is milliseconds before
69 * January 1, 1970, 00:00:00 GMT
70 */
71 public Time(long time) {
72 super(time);
73 }
74
75 /**
76 * Sets a <code>Time</code> object using a milliseconds time value.
77 *
78 * @param time milliseconds since January 1, 1970, 00:00:00 GMT;
79 * a negative number is milliseconds before
80 * January 1, 1970, 00:00:00 GMT
81 */
82 public void setTime(long time) {
83 super.setTime(time);
84 }
85
86 /**
87 * Converts a string in JDBC time escape format to a <code>Time</code> value.
88 *
89 * @param s time in format "hh:mm:ss"
90 * @return a corresponding <code>Time</code> object
91 */
92 public static Time valueOf(String s) {
93 int hour;
94 int minute;
95 int second;
96 int firstColon;
97 int secondColon;
98
99 if (s == null) throw new java.lang.IllegalArgumentException();
100
101 firstColon = s.indexOf(':');
102 secondColon = s.indexOf(':', firstColon+1);
103 if (firstColon > 0 && secondColon > 0 &&
104 secondColon < s.length() - 1) {
105 hour = Integer.parseInt(s, 10, 0, firstColon);
106 minute = Integer.parseInt(s, 10, firstColon + 1, secondColon);
107 second = Integer.parseInt(s, 10, secondColon + 1);
108 } else {
109 throw new java.lang.IllegalArgumentException();
110 }
111
112 return new Time(hour, minute, second);
113 }
114
115 /**
116 * Formats a time in JDBC time escape format.
117 *
118 * @return a <code>String</code> in hh:mm:ss format
119 */
120 @SuppressWarnings("deprecation")
121 public String toString () {
122 int hour = super.getHours();
123 int minute = super.getMinutes();
124 int second = super.getSeconds();
125 String hourString;
126 String minuteString;
127 String secondString;
128
129 if (hour < 10) {
130 hourString = "0" + hour;
131 } else {
132 hourString = Integer.toString(hour);
133 }
134 if (minute < 10) {
135 minuteString = "0" + minute;
136 } else {
137 minuteString = Integer.toString(minute);
138 }
139 if (second < 10) {
140 secondString = "0" + second;
141 } else {
142 secondString = Integer.toString(second);
143 }
144 return (hourString + ":" + minuteString + ":" + secondString);
145 }
146
147 // Override all the date operations inherited from java.util.Date;
148
149 /**
150 * This method is deprecated and should not be used because SQL <code>TIME</code>
151 * values do not have a year component.
152 *
153 * @deprecated
154 * @exception java.lang.IllegalArgumentException if this
155 * method is invoked
156 * @see #setYear
157 */
158 @Deprecated
159 public int getYear() {
160 throw new java.lang.IllegalArgumentException();
161 }
162
163 /**
164 * This method is deprecated and should not be used because SQL <code>TIME</code>
165 * values do not have a month component.
166 *
167 * @deprecated
168 * @exception java.lang.IllegalArgumentException if this
169 * method is invoked
170 * @see #setMonth
171 */
172 @Deprecated
173 public int getMonth() {
174 throw new java.lang.IllegalArgumentException();
175 }
176
177 /**
178 * This method is deprecated and should not be used because SQL <code>TIME</code>
179 * values do not have a day component.
180 *
181 * @deprecated
182 * @exception java.lang.IllegalArgumentException if this
183 * method is invoked
184 */
185 @Deprecated
186 public int getDay() {
187 throw new java.lang.IllegalArgumentException();
188 }
189
190 /**
191 * This method is deprecated and should not be used because SQL <code>TIME</code>
192 * values do not have a date component.
193 *
194 * @deprecated
195 * @exception java.lang.IllegalArgumentException if this
196 * method is invoked
197 * @see #setDate
198 */
199 @Deprecated
200 public int getDate() {
201 throw new java.lang.IllegalArgumentException();
202 }
203
204 /**
205 * This method is deprecated and should not be used because SQL <code>TIME</code>
206 * values do not have a year component.
207 *
208 * @deprecated
209 * @exception java.lang.IllegalArgumentException if this
210 * method is invoked
211 * @see #getYear
212 */
213 @Deprecated
214 public void setYear(int i) {
215 throw new java.lang.IllegalArgumentException();
216 }
217
218 /**
219 * This method is deprecated and should not be used because SQL <code>TIME</code>
220 * values do not have a month component.
221 *
222 * @deprecated
223 * @exception java.lang.IllegalArgumentException if this
224 * method is invoked
225 * @see #getMonth
226 */
227 @Deprecated
228 public void setMonth(int i) {
229 throw new java.lang.IllegalArgumentException();
230 }
231
232 /**
233 * This method is deprecated and should not be used because SQL <code>TIME</code>
234 * values do not have a date component.
235 *
236 * @deprecated
237 * @exception java.lang.IllegalArgumentException if this
238 * method is invoked
239 * @see #getDate
240 */
241 @Deprecated
242 public void setDate(int i) {
243 throw new java.lang.IllegalArgumentException();
244 }
245
246 /**
247 * Private serial version unique ID to ensure serialization
248 * compatibility.
249 */
250 static final long serialVersionUID = 8397324403548013681L;
251
252 /**
253 * Obtains an instance of {@code Time} from a {@link LocalTime} object
254 * with the same hour, minute and second time value as the given
255 * {@code LocalTime}. The nanosecond field from {@code LocalTime} is
256 * not part of the newly created {@code Time} object.
257 *
258 * @param time a {@code LocalTime} to convert
259 * @return a {@code Time} object
260 * @exception NullPointerException if {@code time} is null
261 * @since 1.8
262 */
263 @SuppressWarnings("deprecation")
264 public static Time valueOf(LocalTime time) {
265 return new Time(time.getHour(), time.getMinute(), time.getSecond());
266 }
267
268 /**
269 * Converts this {@code Time} object to a {@code LocalTime}.
270 * <p>
271 * The conversion creates a {@code LocalTime} that represents the same
272 * hour, minute, and second time value as this {@code Time}. The
273 * nanosecond {@code LocalTime} field will be set to zero.
274 *
275 * @return a {@code LocalTime} object representing the same time value
276 * @since 1.8
277 */
278 @SuppressWarnings("deprecation")
279 public LocalTime toLocalTime() {
280 return LocalTime.of(getHours(), getMinutes(), getSeconds());
281 }
282
283 /**
284 * This method always throws an UnsupportedOperationException and should
285 * not be used because SQL {@code Time} values do not have a date
286 * component.
287 *
288 * @exception java.lang.UnsupportedOperationException if this method is invoked
289 */
290 @Override
291 public Instant toInstant() {
292 throw new java.lang.UnsupportedOperationException();
293 }
294 }