Skip to main content

[JSR-354] Re: Static Factory Methods and EDR

  • From: Stephen Colebourne <scolebourne@...>
  • To: jcurrency_mail@...
  • Subject: [JSR-354] Re: Static Factory Methods and EDR
  • Date: Mon, 8 Apr 2013 15:22:05 +0100

The choice to use of() based factory methods rather than valueOf() in 310 was deliberate.

The first aspect is length. valueOf() is much longer and really rather verbose.
 LocalDate.of(2012, 6, 30)
 LocalDate.valueOf(2012, 6, 30)
This matters with shorter class names (where the extra is more obvious). It also matters when these are likely to be used a lot, as they are with important value types like date/time/money.

The second (more important) aspect is that of() can act as a prefix more effectively.
 LocalDate.ofEpochDay(54247)
 LocalDate.valueOfEpochDay(54247)
The second makes less sense as a phrase, and is more obviously long. The "value" part distracts from the important part of the name, which is "EpochDay".

I'd also note that the JDK is already very inconsistent in factory names.
 Currency.getInstance()
 TimeZone.getTimeZone()
 BigDecimal construcors (and valueOf)
 FileTime.fromMillis()
 EnumSet.of()

Using from() rather than of() isn't something I support either. "from" has a much stronger notion of conversion, wheras "of" is much closer to implying creation of an object using the information already to hand.

So, the 310 rules are:
- basic creational factory methods with little/no conversion are named of(...)
- more complex factory methods, with some conversion, or requiring a specific name for clarity are named ofXxx(...)
- factories that extract/convert from a broadly specified input (where there is a good chance of error) are named from(...)
- parsing is explicitly named, as it is generally special, named parse(...)

More generally, 310 focuses very particularly on method prefixes as a technique to aid learning. IDEs will group similarly prefixed methods, allowing users to more easily see related methods.

For this JSR, I would design as follows:
 Money.of(123, USD)
 Money.ofZero(USD)
 Money.from(monetaryAmount)

Stephen



On 8 April 2013 14:42, Werner Keil <werner.keil@...> wrote:
Dear All,

The Spec Document and API are rapidly heading towards EDR 1. Some of you may have reviewed and also placed comments, others commented here, while others may prefer to watch it from the sidelines for now.

Although the balance between the Standalone JSR we voted to go for at this point and preparing it as good as it gets for a possible later addition to OpenJDK required a bit of re-factoring or -structuring of modules, I think it looks good, especially for a first EDR now.

After taking a peek at the latest JDK 8 snapshot including the java.time package, Anatole feels comfortable to try those static factory methods of() instead of a widely accepted de facto naming standard from the "Old Testament" of Java written mainly by folks like Josh Bloch in his books:

While I heard a few comments the Java Architects at Oracle wished java.time and some of its static methods to be simplified or redundant functionally equal duplicates removed, I haven't heard their recommendation about that, so unless I overlooked it or they overlooked that, I'd say it is at least tolerated. 

Other Date/Time APIs not only inside the JDK, where JavaFX sticks to the established naming standards and method signatures of e.g. BigDecimal, or Fantom, a language written by a former JSR 275 EG Member which inspired many aspects of JSR 310 has things like

Duration.fromStr("4ns")
A counterpart of toStr() is a slightly shorter version of the Java method toString(), so it handles parsing and formatting in a slightly more consistent way than Java, not just in the Duration class. to* and from* are somewhat widely used factory method naming patterns in Fantom, where 310 did something a bit similar to valueOf() as Fantom did with toString(), cutting a few characters

While valueOf() is most widely used all across the JDK and e.g. every enum, even those in 310 can't but use and expose it (hence that makes the API a bit inconsistent by using of() in many final classes while valueOf() is used by all enums, themselves final classes, too) the only notable example for newInstance() would be java.util.Currency. If we happen to improve the existing java.util.Currency class by implementing CurrencyUnit from Java 9 on, for backward-compatibility we must stick to this existing method signature, too. I don't know, if Oracle tolerated a duality by adding of() there, most likely they won't. Should the java.time like approach of a completely new package e.g. "java.money" inside the JDK, implementing key elements of the JSR like MonetaryAmount, CurrencyUnit or Rounding be preferred by OpenJDK and Oracle, then we'd be free to do whatever 310 did within the scope and sense of   Monetary operations of course.

If you have your own suggestions here or feel either direction was more in your taste, please feel free to reply. Unless Oracle sanctions or mandates either of the two, we might hold a doodle poll later, or wait, what others using the EDR think. As of now, the EDR may start about a week from now, it's too late to do it today, though PMO told us, it may be started any day of the week. A start date near April 15 also means, the next EC F2F meeting in Zurich at CS shall conclude the 30 day usual EDR period, so we'd be in a place where Spec Lead, selected EG Members, the EC and PMO gather and I also asked to present a summary at this meeting. So without voting, EC Members have a chance to see what happened since the Renewal Ballot and what they feel comfortable with or what they may want to change, especially if it's something that could influence their vote in subsequent ballots

Kind Regards,
-- 

Werner Keil | JCP Executive Committee Member | Eclipse UOMo Lead, Babel Language Champion | Java Godfather

Twitter @wernerkeil | @JSR354 | #Java_Social | #EclipseUOMo | #OpenDDR

Skype werner.keil | Google+ gplus.to/wernerkeil

* JavaOne Russia: April 23-24 2013, Moscow, Russia. Werner Keil, JCP Executive Committee Member, JSR 354/360 EG Member will present "JSR 321, JSR 354, Standards for the Future of Java Embedded"

* Eclipse Stammtisch: May 15 2013, Zurich, Switzerland. Werner Keil, UOMo Lead, JSR 360 EG Member will present "M4M 2 the Rescue of M2M"

* GeeCON: May 16-17 2013, Krakow, Poland. Werner Keil, JCP Executive Committee Member, JSR 360 EG Member will present "Standards for the Future of Java Embedded"



[JSR-354] Static Factory Methods and EDR

Werner Keil 04/08/2013

[JSR-354] Re: Static Factory Methods and EDR

Stephen Colebourne 04/08/2013

[JSR-354] Re: Static Factory Methods and EDR

Werner Keil 04/08/2013

[JSR-354] Re: Static Factory Methods and EDR

Tresch Anatole (KFSC 225) 04/08/2013

[JSR-354] Re: Static Factory Methods and EDR

Werner Keil 04/08/2013

[JSR-354] Re: Static Factory Methods and EDR

Werner Keil 04/08/2013
 
 
Close
loading
Please Confirm
Close