True API with Interfaces?

[Jörg Hohwiller]

First of all thanks for putting your energy into this JSR. We all suffered with java.util.Date and Calendar and what you created is very promising. I cross fingers that it will make it into Java8.

However, what I am missing is a true API. In Java the most important and successful JSRs have standardized APIs such as JPA, CDI, etc.
JSRs that have not earned the right success have e.g. been the logging stuff that purely focused on the implementation and that is also the problem of java.util.Date and Calendar. The API was "designed" by the poor guys that hat to implement all these complicated stuff. If those days they had defined proper interfaces for date and time that are part of every JRE we could all happily use jodetime together with hibernate and all other frameworks.

Some time ago when I feelt that it took for this JSR to make its way, I quickly wrote some API for date and time (I dont want to actually release this and would love to see such API in JSR 310 - not my API, yours is fine but with interfaces - your enums are already fine). It is not really great but please have a look:
http://m-m-m.sourceforge.net/apidocs/net/sf/mmm/util/date/api/package-summary.html

Why dont you have such interfaces? Are you aware that Java is really huge and there are islands like GWT where java code gets compiled to java-script and there your work might not be available as you implementation is tight together with implementation details such as resources read from the classpath, etc.

Please believe me what we need at most is an API that is accepted by everybody. Your current API is fine from the signature point of view but please consider creating interfaces.

Thanks
Jörg

[Stephen Colebourne]

On 19 February 2013 20:16, "Jörg Hohwiller" hohwille@users.sf.net wrote:

First of all thanks for putting your energy into this JSR. We all suffered
with java.util.Date and Calendar and what you created is very promising. I
cross fingers that it will make it into Java8.

However, what I am missing is a true API. In Java the most important and
successful JSRs have standardized APIs such as JPA, CDI, etc.
JSRs that have not earned the right success have e.g. been the logging stuff
that purely focused on the implementation and that is also the problem of
java.util.Date and Calendar. The API was "designed" by the poor guys that
hat to implement all these complicated stuff. If those days they had defined
proper interfaces for date and time that are part of every JRE we could all
happily use jodetime together with hibernate and all other frameworks.

Some time ago when I feelt that it took for this JSR to make its way, I
quickly wrote some API for date and time (I dont want to actually release
this and would love to see such API in JSR 310 - not my API, yours is fine
but with interfaces - your enums are already fine). It is not really great
but please have a look:
http://m-m-m.sourceforge.net/apidocs/net/sf/mmm/util/date/api/package-summary.html

Why dont you have such interfaces? Are you aware that Java is really huge
and there are islands like GWT where java code gets compiled to java-script
and there your work might not be available as you implementation is tight
together with implementation details such as resources read from the
classpath, etc.

Please believe me what we need at most is an API that is accepted by
everybody. Your current API is fine from the signature point of view but
please consider creating interfaces.

The first point to note is that the "JSR" part of JSR-310 is not
comparable to those such as JPA or other JavaEE specs. JSR-310 is
simply a mechanism/process to get code into the JDK, nothing more.

Secondly, interfaces are not always the appropriate tool for design. A
method receiving an interface knows nothing about the implementing
class, thus it cannot rely on it being thread-safe or immutable, facts
which are becoming increasingly important. The date/time classes are
also "value types", similar to Integer, Character and String. All of
these are final and immutable classes.

However, there is a role for interfaces in interoperability. Thats why
JSR-310 provides the "temporal" package, where the interfaces
"TemporalAccessor", "Temporal" and "TemporalAmount" can be implemented
outside the JDK, and yet easily converted to JDK classes and used in
formatting/parsing. Thus, your library, or Joda-Time, could implement
the temporal interfaces.

thanks
Stephen

[Jörg Hohwiller]

Thanks for your response.

A method receiving an interface knows nothing
about the implementing class, thus it cannot rely
on it being thread-safe or immutable, facts
which are becoming increasingly important.

All true. But not an argument against adding the interfaces. The user can decide to use the interfaces or the classes as input in their own API. But if there are no interfaces abstraction from your specific implementation is not possible except by adding your own interfaces and wrapping. That is the same mistake what happend with java.util.logging and other stuff.
I am totally aware that a date is a datatype and should therefore be immutable. But if I want to have a client-server RPC interface the case is simply different. All I need is to express that I want to have a Date(Midnight) or a DateTime with according getters and here a standardized interface would help a lot. In a Web-Browser the implementation of the interface can be totally different if implemented with GWT.

Thats why JSR-310 provides the "temporal" package

Fine, but could you provide a link. I could not find this in 0.6.3 release nor in your code here at sf.net.

Regards
Jörg

[Stephen Colebourne]

This link is relatively up to date (refers to the backport)
http://threeten.github.com/threetenbp/apidocs/

[Jörg Hohwiller]

Thanks. Seems this all has a long history (java.net, sf.net, github, etc.) so not so easy to find the correct spot for the latest stuff...

[Jörg Hohwiller]

http://threeten.github.com/threetenbp/apidocs/org/threeten/bp/temporal/TemporalAccessor.html

Better than nothing. I have to get into this. A lot more complicated than what I hoped...
I am still hoping for an interface "Date" with

int getDayOfMonth();
Month getMonth();
int getYear();

and an interface "Time" with

int getHour();
int getMinute();
int getSecond();
int getNano();

This is an API that a normal thinking user would expect together with clear javadoc and that is want he wants to use.
You could also benefit from that as you currently have redundant declaration of the above methods in LocalDate, LocalDateTime and LocalTime.

A generic access like

int get(TemporalField field);

is also fine but more for generic/technical code. Having the above interfaces would not hurt your endeavor with threeten and would be helpful for end-users. You could add JavaDoc to those interfaces with all these suggestions about immutable classes and links to the according default implementations to use directly where abstraction is not required.

Thanks for thinking about it
Jörg

p.s. I would also provide a patch. But this would only make sense after I could really convince the project to go for adding this.

[Stephen Colebourne]

Adding such interfaces is certainly possible, but its not something I see as desirable, nor something that is going to happen. While "obvious", they are also quite limiting, only specifying a few methods that might or might not match the implementing class (you'd need the enum at least for example, and that might clash with a non-JDK implementation). Furthermore, the definition of those methods gets easily confused when dealing with non-ISO calendar systems. For example, the COptic system has 13 months and doesn't match the Month enum.

All in all, the best option is to provide for the interoperability, but at a lower level. I really want people to code to the implementation classes, not the interfaces in JSR-310.