Rationale behind Instant.getEpochSecond vs Instant.toEpochMilli [closed]

Question

Can somebody explain the rationale behind the naming of Instant.getEpochSecond vs. Instant.toEpochMilli? The only reason I can think of is the internal representation of an instant as seconds relative to epoch and nano seconds relative to that second whereas the milli seconds are calculated from those two values.

But why would you let such an implementation detail leak into a new API?

Answer 1

I'd have to guess but I'd agree with you:

• getEpochSecond() indicates a mere getter, i.e. it just returns the value which is stored in that instance
• toEpochMilli() on the other hand would calculate its return value, much like toString() would not return a stored string but build in on-the-fly every time the method is called

That convention actually is documented here: http://docs.oracle.com/javase/tutorial/datetime/overview/naming.html

The reason for this convention probably is related to the JavaBeans specification, i.e. epochSecond would be a (readonly) property of Instant whereas epochMilli is a different representation but not a property.

Answer 2

The getters return parts of an Temporal object (like Instant), while the to* methods return a converted version of it:

• getEpochSecond() returns the gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.
• getNanos() returns the nanoseconds-of-second-part of the Instant
• toEpochMilli() returns the Instant converted into milliseconds (i.e. seconds * 1000 + nanoseconds / 1,000,000)