View Javadoc
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.substring(0, firstColon));
106             minute =
107                 Integer.parseInt(s.substring(firstColon+1, secondColon));
108             second = Integer.parseInt(s.substring(secondColon+1));
109         } else {
110             throw new java.lang.IllegalArgumentException();
111         }
112 
113         return new Time(hour, minute, second);
114     }
115 
116     /**
117      * Formats a time in JDBC time escape format.
118      *
119      * @return a <code>String</code> in hh:mm:ss format
120      */
121     @SuppressWarnings("deprecation")
122     public String toString () {
123         int hour = super.getHours();
124         int minute = super.getMinutes();
125         int second = super.getSeconds();
126         String hourString;
127         String minuteString;
128         String secondString;
129 
130         if (hour < 10) {
131             hourString = "0" + hour;
132         } else {
133             hourString = Integer.toString(hour);
134         }
135         if (minute < 10) {
136             minuteString = "0" + minute;
137         } else {
138             minuteString = Integer.toString(minute);
139         }
140         if (second < 10) {
141             secondString = "0" + second;
142         } else {
143             secondString = Integer.toString(second);
144         }
145         return (hourString + ":" + minuteString + ":" + secondString);
146     }
147 
148     // Override all the date operations inherited from java.util.Date;
149 
150    /**
151     * This method is deprecated and should not be used because SQL <code>TIME</code>
152     * values do not have a year component.
153     *
154     * @deprecated
155     * @exception java.lang.IllegalArgumentException if this
156     *           method is invoked
157     * @see #setYear
158     */
159     @Deprecated
160     public int getYear() {
161         throw new java.lang.IllegalArgumentException();
162     }
163 
164    /**
165     * This method is deprecated and should not be used because SQL <code>TIME</code>
166     * values do not have a month component.
167     *
168     * @deprecated
169     * @exception java.lang.IllegalArgumentException if this
170     *           method is invoked
171     * @see #setMonth
172     */
173     @Deprecated
174     public int getMonth() {
175         throw new java.lang.IllegalArgumentException();
176     }
177 
178    /**
179     * This method is deprecated and should not be used because SQL <code>TIME</code>
180     * values do not have a day component.
181     *
182     * @deprecated
183     * @exception java.lang.IllegalArgumentException if this
184     *           method is invoked
185     */
186     @Deprecated
187     public int getDay() {
188         throw new java.lang.IllegalArgumentException();
189     }
190 
191    /**
192     * This method is deprecated and should not be used because SQL <code>TIME</code>
193     * values do not have a date component.
194     *
195     * @deprecated
196     * @exception java.lang.IllegalArgumentException if this
197     *           method is invoked
198     * @see #setDate
199     */
200     @Deprecated
201     public int getDate() {
202         throw new java.lang.IllegalArgumentException();
203     }
204 
205    /**
206     * This method is deprecated and should not be used because SQL <code>TIME</code>
207     * values do not have a year component.
208     *
209     * @deprecated
210     * @exception java.lang.IllegalArgumentException if this
211     *           method is invoked
212     * @see #getYear
213     */
214     @Deprecated
215     public void setYear(int i) {
216         throw new java.lang.IllegalArgumentException();
217     }
218 
219    /**
220     * This method is deprecated and should not be used because SQL <code>TIME</code>
221     * values do not have a month component.
222     *
223     * @deprecated
224     * @exception java.lang.IllegalArgumentException if this
225     *           method is invoked
226     * @see #getMonth
227     */
228     @Deprecated
229     public void setMonth(int i) {
230         throw new java.lang.IllegalArgumentException();
231     }
232 
233    /**
234     * This method is deprecated and should not be used because SQL <code>TIME</code>
235     * values do not have a date component.
236     *
237     * @deprecated
238     * @exception java.lang.IllegalArgumentException if this
239     *           method is invoked
240     * @see #getDate
241     */
242     @Deprecated
243     public void setDate(int i) {
244         throw new java.lang.IllegalArgumentException();
245     }
246 
247    /**
248     * Private serial version unique ID to ensure serialization
249     * compatibility.
250     */
251     static final long serialVersionUID = 8397324403548013681L;
252 
253     /**
254      * Obtains an instance of {@code Time} from a {@link LocalTime} object
255      * with the same hour, minute and second time value as the given
256      * {@code LocalTime}.
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}.
273      *
274      * @return a {@code LocalTime} object representing the same time value
275      * @since 1.8
276      */
277     @SuppressWarnings("deprecation")
278     public LocalTime toLocalTime() {
279         return LocalTime.of(getHours(), getMinutes(), getSeconds());
280     }
281 
282    /**
283     * This method always throws an UnsupportedOperationException and should
284     * not be used because SQL {@code Time} values do not have a date
285     * component.
286     *
287     * @exception java.lang.UnsupportedOperationException if this method is invoked
288     */
289     @Override
290     public Instant toInstant() {
291         throw new java.lang.UnsupportedOperationException();
292     }
293 }