Timestamp Utilities

/**
 * Minimum valid Timestamp: 0001-01-01T00:00:00Z
 */
public static final Timestamp MIN_VALUE;

/**
 * Maximum valid Timestamp: 9999-12-31T23:59:59.999999999Z  
 */
public static final Timestamp MAX_VALUE;

/**
 * Epoch timestamp: 1970-01-01T00:00:00.000000000Z
 */
public static final Timestamp EPOCH;

/**
 * Creates a Timestamp using the best-available system clock.
 * Uses nanosecond precision when available, falls back to millisecond precision.
 * 
 * @return Timestamp representing the current time
 */
public static Timestamp now();

/**
 * Creates a Timestamp from seconds since epoch.
 * 
 * @param seconds Number of seconds since Unix epoch
 * @return Timestamp representing the specified time
 */
public static Timestamp fromSeconds(long seconds);

/**
 * Creates a Timestamp from milliseconds since epoch.
 * 
 * @param milliseconds Number of milliseconds since Unix epoch
 * @return Timestamp representing the specified time
 */
public static Timestamp fromMillis(long milliseconds);

/**
 * Creates a Timestamp from microseconds since epoch.
 * 
 * @param microseconds Number of microseconds since Unix epoch
 * @return Timestamp representing the specified time
 */
public static Timestamp fromMicros(long microseconds);

/**
 * Creates a Timestamp from nanoseconds since epoch.
 * 
 * @param nanoseconds Number of nanoseconds since Unix epoch
 * @return Timestamp representing the specified time
 */
public static Timestamp fromNanos(long nanoseconds);

/**
 * Creates a Timestamp from a Date object.
 * Preserves full nanosecond precision if input is java.sql.Timestamp.
 * 
 * @param date Date object to convert
 * @return Timestamp representing the date
 * @throws IllegalArgumentException if year is before 1 CE or after 9999 CE
 */
public static Timestamp fromDate(Date date);

/**
 * Converts Timestamp to seconds since epoch.
 * Result is rounded down to nearest second.
 * 
 * @param timestamp Timestamp to convert
 * @return Number of seconds since Unix epoch
 */
public static long toSeconds(Timestamp timestamp);

/**
 * Converts Timestamp to milliseconds since epoch.
 * Result is rounded down to nearest millisecond.
 * 
 * @param timestamp Timestamp to convert
 * @return Number of milliseconds since Unix epoch  
 */
public static long toMillis(Timestamp timestamp);

/**
 * Converts Timestamp to microseconds since epoch.
 * Result is rounded down to nearest microsecond.
 * 
 * @param timestamp Timestamp to convert
 * @return Number of microseconds since Unix epoch
 */
public static long toMicros(Timestamp timestamp);

/**
 * Converts Timestamp to nanoseconds since epoch.
 * 
 * @param timestamp Timestamp to convert
 * @return Number of nanoseconds since Unix epoch
 */
public static long toNanos(Timestamp timestamp);

/**
 * Converts Timestamp to RFC 3339 date string format.
 * Output is Z-normalized and uses 0, 3, 6, or 9 fractional digits as needed.
 * 
 * @param timestamp Timestamp to convert
 * @return RFC 3339 formatted string (e.g., "1972-01-01T10:00:20.021Z")
 * @throws IllegalArgumentException if timestamp is not in valid range
 */
public static String toString(Timestamp timestamp);

/**
 * Parses RFC 3339 date string to Timestamp.
 * Accepts any fractional digits and any timezone offset.
 * 
 * @param value RFC 3339 formatted string (e.g., "1972-01-01T10:00:20.021-05:00")
 * @return Timestamp parsed from the string
 * @throws ParseException if parsing fails
 */
public static Timestamp parse(String value) throws ParseException;

/**
 * Parses RFC 3339 string to Timestamp.
 * Same as parse() but throws IllegalArgumentException instead of ParseException.
 * 
 * @param value RFC 3339 formatted string
 * @return Timestamp parsed from the string
 * @throws IllegalArgumentException if parsing fails
 */
public static Timestamp parseUnchecked(String value);

/**
 * Checks if the given Timestamp is valid.
 * Seconds must be in range [-62,135,596,800, +253,402,300,799].
 * Nanos must be in range [0, +999,999,999].
 * 
 * @param timestamp Timestamp to validate
 * @return true if timestamp is valid, false otherwise
 */
public static boolean isValid(Timestamp timestamp);

/**
 * Checks if the given seconds and nanos form a valid Timestamp.
 * 
 * @param seconds Seconds component
 * @param nanos Nanoseconds component
 * @return true if combination is valid, false otherwise
 */
public static boolean isValid(long seconds, int nanos);

/**
 * Validates a Timestamp and throws exception if invalid.
 * 
 * @param timestamp Timestamp to validate
 * @return The same timestamp if valid
 * @throws IllegalArgumentException if timestamp is invalid
 */
public static Timestamp checkValid(Timestamp timestamp);

/**
 * Builds and validates a Timestamp from builder.
 * 
 * @param timestampBuilder Timestamp builder to build and validate
 * @return Valid built Timestamp
 * @throws IllegalArgumentException if resulting timestamp is invalid
 */
public static Timestamp checkValid(Timestamp.Builder timestampBuilder);

/**
 * Returns a Comparator for Timestamps in increasing chronological order.
 * The comparator is serializable and validates inputs.
 * 
 * @return Comparator for Timestamp objects
 */
public static Comparator<Timestamp> comparator();

/**
 * Compares two timestamps.
 * 
 * @param x First timestamp
 * @param y Second timestamp
 * @return 0 if equal, negative if x < y, positive if x > y
 * @throws IllegalArgumentException if either timestamp is invalid
 */
public static int compare(Timestamp x, Timestamp y);

/**
 * Calculates the duration between two timestamps.
 * 
 * @param from Start timestamp
 * @param to End timestamp
 * @return Duration representing the time difference
 * @throws IllegalArgumentException if either timestamp is invalid
 */
public static Duration between(Timestamp from, Timestamp to);

/**
 * Adds a duration to a timestamp.
 * 
 * @param start Starting timestamp
 * @param length Duration to add
 * @return New timestamp representing start + length
 * @throws IllegalArgumentException if timestamp or duration is invalid
 */
public static Timestamp add(Timestamp start, Duration length);

/**
 * Subtracts a duration from a timestamp.
 * 
 * @param start Starting timestamp
 * @param length Duration to subtract
 * @return New timestamp representing start - length
 * @throws IllegalArgumentException if timestamp or duration is invalid
 */
public static Timestamp subtract(Timestamp start, Duration length);

import com.google.protobuf.util.Timestamps;
import com.google.protobuf.util.Durations;
import com.google.protobuf.Timestamp;
import com.google.protobuf.Duration;
import java.text.ParseException;

// Get current time
Timestamp now = Timestamps.now();

// Create timestamps from various time units
Timestamp fromEpoch = Timestamps.fromSeconds(0); // Unix epoch
Timestamp fromMillis = Timestamps.fromMillis(System.currentTimeMillis());
Timestamp fromDate = Timestamps.fromDate(new Date());

// Convert to string format
String timeString = Timestamps.toString(now);
System.out.println(timeString); // "2024-01-15T10:30:45.123456789Z"

// Parse from string
try {
    Timestamp parsed = Timestamps.parse("2024-01-15T10:30:45.123Z");
    System.out.println("Parsed: " + Timestamps.toString(parsed));
} catch (ParseException e) {
    System.err.println("Parse error: " + e.getMessage());
}

// Validation
if (Timestamps.isValid(now)) {
    System.out.println("Timestamp is valid");
}

// Comparison
Timestamp earlier = Timestamps.fromSeconds(1000);
Timestamp later = Timestamps.fromSeconds(2000);
int comparison = Timestamps.compare(earlier, later); // negative value

// Arithmetic operations
Duration oneHour = Durations.fromHours(1);
Timestamp oneHourLater = Timestamps.add(now, oneHour);
Timestamp oneHourEarlier = Timestamps.subtract(now, oneHour);

// Calculate duration between timestamps
Duration elapsed = Timestamps.between(earlier, later);
System.out.println("Elapsed: " + Durations.toString(elapsed));

// Convert to various time units
long epochSeconds = Timestamps.toSeconds(now);
long epochMillis = Timestamps.toMillis(now);
long epochMicros = Timestamps.toMicros(now);
long epochNanos = Timestamps.toNanos(now);

// Use constants
System.out.println("Min: " + Timestamps.toString(Timestamps.MIN_VALUE));
System.out.println("Max: " + Timestamps.toString(Timestamps.MAX_VALUE));
System.out.println("Epoch: " + Timestamps.toString(Timestamps.EPOCH));