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