[threeten-dev] [threeten] Reinstate toLocalDate() and friends (#224)

[Roger Riggs]

Doing a pre-flight on this potential change, please take a look at the 
revised javadoc and comment.

     http://cr.openjdk.java.net/~rriggs/javadoc-tolocal-224/

The changes are:

  * rename ChronoLocalDateTime.getDate/getTime/getDateTime to 
    toLocalDate()/toLocalTime()/toLocalDateTime()
  * rename the corresponding methods in LocalDateTime, OffsetDateTime,
    ZonedDateTime


I note that some obviously meaningful methods on ChronoLocalDateTime
are missing in the javadoc, for example get(field); getLong(field), 
isSupported(field);
that's a factor of the javadoc not documenting inherited methods.



On 1/30/2013 5:06 PM, Stephen Colebourne wrote:
>
> I would leave the get methods you mentioned there alone.
>
> The model to follow is that "get" methods are used for those items 
> that get the state of the type you are working with. Thus, 
> OffsetDateTime has state of offset and the 8 fields, whereas LDT just 
> has the 8 fields.
>
> The "to" methods are for converting between the basic types ODT to LD, 
> LDT or LT.
>
> So, why draw the boundary there? Well, an offset is clearly part of 
> the state of an ODT, so a "get" method is definitely applicable, and 
> it would be wrong to be other. But the date and time is more interesting.
>
> If we didn't have any field-based methods on LDT/ODT/OT/ZDT, then it 
> would be correct to have getDate/getTime. But that isn't the model we 
> adopt in the API. Instead, we expose the fields as the primary 
> representation of date and time (with lots of get/with/plus/minus 
> methods). Thus, it is the field-based methods that stay as "get".
>
> (This is a Java language limitation. In 
> psuedo-other-wonderful-language, you would write zdt.{date.year = 6} 
> and it would return a ZDT, not a LD)
>
> The second part of the explanation is around how developers use the 
> types. Changing from using one type to using another type is an 
> important choice, and one we want to actively make developers aware 
> of. (These types we refer to here are LDT/LD/LT/ODT/OT/ZDT, not 
> Offset/ZoneId). As a developer if I have a ZDT and I want a LD, I'm 
> making a very specific conversion, where the LD object will be used 
> for a different purpose to the original ZDT. By contrast, the 
> Offset/Zone are just subsidiary parts of the whole, not carrying any 
> date-time informationto convert to.
>
> Finally, toMonth and toDayOfWeek could seem appealing, but they would 
> be out of place wrt the other getters. We need to actively encourage 
> developer to use the enums to make their code more readable, and 
> getters are needed for that.
>
> —
> Reply to this email directly or view it on GitHub 
> <https://github.com/ThreeTen/threeten/issues/224#issuecomment-12915284>.
>

-- 
Thanks, Roger

Oracle Java Platform Group

Green Oracle <http://www.oracle.com/commitment> Oracle is committed to 
developing practices and products that help protect the environment