java.sql.Time Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.sql;
import java.util.Date;
/**
* Java representation of an SQL {@code TIME} value. Provides utilities to
* format and parse the time's representation as a String in JDBC escape format.
*/
public class Time extends Date {
private static final long serialVersionUID = 8397324403548013681L;
/**
* Constructs a {@code Time} object using the supplied values for Hour,
* Minute and Second. The Year, Month and
* Day elements of the {@code Time} object are set to the date
* of the Epoch (January 1, 1970).
*
* Any attempt to access the Year, Month or Day
* elements of a {@code Time} object will result in an {@code
* IllegalArgumentException}.
*
* The result is undefined if any argument is out of bounds.
*
* @deprecated Use the constructor {@link #Time(long)} instead.
* @param theHour
* a value in the range {@code [0,23]}.
* @param theMinute
* a value in the range {@code [0,59]}.
* @param theSecond
* a value in the range {@code [0,59]}.
*/
@SuppressWarnings("deprecation")
@Deprecated
public Time(int theHour, int theMinute, int theSecond) {
super(70, 0, 1, theHour, theMinute, theSecond);
}
/**
* Constructs a {@code Time} object using a supplied time specified in
* milliseconds.
*
* @param theTime
* a {@code Time} specified in milliseconds since the
* Epoch (January 1st 1970, 00:00:00.000).
*/
public Time(long theTime) {
super(theTime);
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a date component.
* @return does not return anything.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public int getDate() {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a day component.
* @return does not return anything.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public int getDay() {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a month component.
* @return does not return anything.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public int getMonth() {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a year component.
* @return does not return anything.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public int getYear() {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a date component.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public void setDate(int i) {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a month component.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public void setMonth(int i) {
throw new IllegalArgumentException("unimplemented");
}
/**
* @deprecated This method is deprecated and must not be used. An SQL
* {@code Time} object does not have a year component.
* @throws IllegalArgumentException
* if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@Override
public void setYear(int i) {
throw new IllegalArgumentException("unimplemented");
}
/**
* Sets the time for this {@code Time} object to the supplied milliseconds
* value.
*
* @param time
* A time value expressed as milliseconds since the Epoch.
* Negative values are milliseconds before the Epoch. The Epoch
* is January 1 1970, 00:00:00.000.
*/
@Override
public void setTime(long time) {
super.setTime(time);
}
/**
* Formats the {@code Time} as a String in JDBC escape format: {@code
* hh:mm:ss}.
*
* @return A String representing the {@code Time} value in JDBC escape
* format: {@code HH:mm:ss}
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder(8);
format(getHours(), 2, sb);
sb.append(':');
format(getMinutes(), 2, sb);
sb.append(':');
format(getSeconds(), 2, sb);
return sb.toString();
}
private static final String PADDING = "00";
/*
* Private method to format the time
*/
private void format(int date, int digits, StringBuilder sb) {
String str = String.valueOf(date);
if (digits - str.length() > 0) {
sb.append(PADDING.substring(0, digits - str.length()));
}
sb.append(str);
}
/**
* Creates a {@code Time} object from a string holding a time represented in
* JDBC escape format: {@code hh:mm:ss}.
*
* An exception occurs if the input string does not comply with this format.
*
* @param timeString
* A String representing the time value in JDBC escape format:
* {@code hh:mm:ss}.
* @return The {@code Time} object set to a time corresponding to the given
* time.
* @throws IllegalArgumentException
* if the supplied time string is not in JDBC escape format.
*/
public static Time valueOf(String timeString) {
if (timeString == null) {
throw new IllegalArgumentException("timeString == null");
}
int firstIndex = timeString.indexOf(':');
int secondIndex = timeString.indexOf(':', firstIndex + 1);
// secondIndex == -1 means none or only one separator '-' has been
// found.
// The string is separated into three parts by two separator characters,
// if the first or the third part is null string, we should throw
// IllegalArgumentException to follow RI
if (secondIndex == -1 || firstIndex == 0
|| secondIndex + 1 == timeString.length()) {
throw new IllegalArgumentException();
}
// parse each part of the string
int hour = Integer.parseInt(timeString.substring(0, firstIndex));
int minute = Integer.parseInt(timeString.substring(firstIndex + 1,
secondIndex));
int second = Integer.parseInt(timeString.substring(secondIndex + 1,
timeString.length()));
return new Time(hour, minute, second);
}
}