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