Synchronized API with current spec.

Author: atsticks

src/main/java/javax/money/CurrencyUnit.java

@@ -19,14 +19,16 @@
  * <p>
  * Currencies can be distinguished by separate {@link #getCurrencyCode()} codes,
  * similar to {@link java.util.Currency}.
- * <p>
- * Implementation of this class are required to be
+ * <h4>Implementation specification</h4>
+ * Implementation of this class
  * <ul>
- * <li>thread-safe
- * <li>immutable
- * <li>serializable.
+ * <li>are required to be implement {@code equals/hashCode} considering the
+ * concrete implementation type and currency code.
+ * <li>are required to be thread-safe
+ * <li>are required to be immutable
+ * <li>are highly recommended to be serializable.
+ * </ul>
  * 
- * @version 0.4
  * @author Werner Keil
  * @author Stephen Colebourne
  * @author Anatole Tresch
@@ -42,6 +44,9 @@ public interface CurrencyUnit {
 	 * Since each currency is identified by this code, the currency code is
 	 * required to be defined for every {@link CurrencyUnit} and not
 	 * {@code null} or empty.
+	 * <p>
+	 * For ISO codes the 3-letter ISO code should be returned. For non ISO
+	 * currencies no constraints are defined.
 	 * 
 	 * @return the currency code, never {@code null}. For the ISO-4217
 	 *         namespace, this this will be the three letter ISO-4217 code.

src/main/java/javax/money/MonetaryAdjuster.java

@@ -37,7 +37,6 @@
  * 
  * It is recommended to use the second approach, {@code with(MonetaryAdjuster)},
  * as it is a lot clearer to read in code.
- * 
  * <h4>Implementation specification</h4>
  * This interface places no restrictions on the mutability of implementations,
  * however immutability is strongly recommended.

src/main/java/javax/money/MonetaryAmount.java

@@ -23,39 +23,83 @@
  * high precision and scale, whereas low latency order and trading systems
  * require high calculation performance for algorithmic operations.
  * <p>
- * This JSR additionally defines a couple of interoperability rules that each
- * implementation must follow:
+ * This JSR additionally recommends to consider the following aspects:
  * <ul>
- * <li>The numeric values on the MonetaryAmount interface are for
- * interoperability only. They should not used for calculations. Instead of each
- * implementation of this interface must provide a static method
- * {@code T from(MonetaryAmount)} to create an instance of a concrete
- * implementation type {@code T} based on a given amount instance.</li>
+ * <li>Arithmetic operations should throw an {@link ArithmeticException}, if
+ * performing arithmetic operations between amounts exceeds the capabilities of
+ * the numeric representation type used. Any implicit truncating, that would
+ * lead to complete invalid and useless results, should be avoided. This
+ * recommendation does not affect internal rounding, as required by the internal
+ * numeric representation of a monetary amount.
+ * <li>Monetary amounts should allow numbers as argument for arithmetic
+ * operations like division and multiplication additionally to a MonetaryAmount.
+ * Adding or subtracting of amounts must only be possible by passing instances
+ * of MonetaryAmount. Arguments of type {@link Number} should be avoided, since
+ * it does not allow to extract its numeric value in a feasible way.
  * <li>If the numeric representation of a {@code MonetaryAmount} exceeds the
- * numeric capabilities of the concrete type {@code T from(MonetaryAmount)} must
- * throw an {@code ArithemticOperationException}.</li>
+ * numeric capabilities of the concrete type {@code T from(MonetaryAmount)}, an
+ * implementation should throw an {@code ArithemticOperationException}.</li>
  * <li>On the other hand, when the numeric value can not be mapped into the
  * numeric exchange format defined by this interface, by default also an
- * {@code ArithmeticException} must be thrown. Never should truncation be
+ * {@code ArithmeticException} should be thrown. Never should truncation be
  * performed implicitly.</li>
- * <li>Nevertheless truncation is possible, but must be enabled explicitly by
- * passing an additional {@code boolean} parameter as {@code true} to allow it.</li>
- * <li>Rounding is never done automatically, exception internal rounding implied
- * by the numeric implementation type.</li>
- * <li>Since implementations are required to be immutable, an operation must
- * never change any internal state of an instance. Given an instance, all
+ * <li>Nevertheless truncation may be supported by passing additional parameters
+ * or using <i>exact</i> methods, similar to {@link BigDecimal#longValueExact()}.
+ * <li>Rounding should never be done automatically, exception internal rounding
+ * implied by the numeric implementation type.</li>
+ * <li>Since implementations are recommended to be immutable, an operation
+ * should never change any internal state of an instance. Given an instance, all
  * operations are required to be fully reproducible.</li>
- * <li>Finally the result of calling {@link #with(MonetaryAdjuster)} must be of
- * the same type as type on which {@code with} was called. The {@code with}
+ * <li>Finally the result of calling {@link #with(MonetaryAdjuster)} should be
+ * of the same type as type on which {@code with} was called. The {@code with}
  * method also defines additional interoperability requirements.</li>
+ * <li>To enable interoperability a static method {@code from(MonetaryAmount)}
+ * is recommended to be implemented, that allows conversion of a
+ * {@code MonetaryAmount} to a concrete type {@code T}:<br/>
+ * 
+ * <pre>
+ * public static T from(MonetaryAmount amount);}
+ * </pre>
+ * 
+ * This is particularly useful when implementing monetary adjusters or queries,
+ * since arithmetic operations are not available on the MonetaryAmount
+ * interface, which is defined for interoperability only.</li>
+ * <li>Finally implementations should not implement a method {@code getAmount()}
+ * . This methid is reserved for future integration into the JDK.</li>
  * </ul>
- * It is required that implementations of this interface are
+ * <h4>Implementation specification</h4>
+ * Implementations of this interface should be
  * <ul>
  * <li>immutable</li>
  * <li>thread-safe</li>
  * <li>final</li>
- * <li>serializable, hereby writing the numeric representation, e.g.
- * {@link BigDecimal} and a serialized {@link CurrencyUnit}.</li>
+ * <li>serializable, hereby writing the numeric value and a serialized
+ * {@link CurrencyUnit}.</li>
+ * </ul>
+ * Implementations of this interface must be
+ * <ul>
+ * <li>comparable</li>
+ * <li>must implement {@code equals/hashCode}, hereby considering
+ * <ul>
+ * <li>Implementation type
+ * <li>CurrencyUnit
+ * <li>Numeric value.
+ * </ul>
+ * This also means that two different implementations types with the same
+ * currency and numeric value are NOT equal.</li>
+ * <li>Additionally for the numeric representation of an amount,
+ * <pre>
+ * given w = getAmountWhole()
+ *       n = getFractionNominator()
+ *       d = getFractionDenominator()
+ *       
+ * the following must be always true:
+ * 
+ *       !(w<0 && n>0)  and
+ *       !(w>0 && n<0)  and
+ *       d>0            and
+ *       |n| < d        // || = absolute value
+ * </pre>
  * </ul>
  * <p>
  * Since {@link Number} is not an interface, this type is not extending
@@ -68,7 +112,9 @@
 public interface MonetaryAmount {
 
 	/**
-	 * Gets the amount's currency.
+	 * Returns the amount’s currency, modelled as {@link CurrencyUnit}.
+	 * Implementations may co-variantly change the return type to a more
+	 * specific implementation of {@link CurrencyUnit} if desired.
 	 * 
 	 * @return the currency, never {@code null}
 	 */
@@ -83,8 +129,14 @@ public interface MonetaryAmount {
 	 * <p>
 	 * For example, the amount of '12 dollars and 25 cents' would return 12 from
 	 * this method, as there are 12 whole US dollars in the amount.
+	 * <p>
+	 * Hereby it is always required that
+	 * <ul>
+	 * <li>{@code !(amountWhole<0 && fractionNumerator > 0) }
+	 * <li>{@code !(amountWhole>0 && fractionNumerator < 0) }
+	 * </ul>
 	 * 
-	 * @return the currency, not null
+	 * @return the amount's whole number
 	 */
 	public long getAmountWhole();
 
@@ -97,8 +149,13 @@ public interface MonetaryAmount {
 	 * <p>
 	 * For example, the amount of '12 dollars and 25 cents' would typically
 	 * return 25 from this method and 100 from the denominator method.
+	 * <p>
+	 * Hereby it is always required that
+	 * <ul>
+	 * <li>{@code fractionNumerator < fractionDenominator}
+	 * </ul>
 	 * 
-	 * @return the currency, not null
+	 * @return the fraction numerator
 	 */
 	public long getAmountFractionNumerator();
 
@@ -111,8 +168,16 @@ public interface MonetaryAmount {
 	 * <p>
 	 * For example, the amount of '12 dollars and 25 cents' would typically
 	 * return 100 from this method and 25 from the numerator method.
+	 * <p>
+	 * Hereby it is always required that
+	 * <ul>
+	 * <li>{@code fractionDenominator > 0}.
+	 * <li>{@code fractionDenominator > abs(fractionNominator)}.
+	 * <li>it is recommended that the denominator is a power of 10 (1, 10, 100,
+	 * 1000,...).
+	 * </ul>
 	 * 
-	 * @return the currency, not null
+	 * @return the fraction denominator
 	 */
 	public long getAmountFractionDenominator();
 

src/main/java/javax/money/MonetaryException.java

@@ -10,10 +10,6 @@
 
 /**
  * Exception thrown when an error occurs during monetary operations.
- * 
- * <h4>Implementation specification</h4>
- * This interface places no restrictions on the mutability of implementations,
- * however immutability is strongly recommended.
  */
 public class MonetaryException extends RuntimeException {
 

src/main/java/javax/money/MonetaryQuery.java

@@ -31,7 +31,6 @@
  * </pre>
  * It is recommended to use the second approach, {@code query(MonetaryQuery)},
  * as it is a lot clearer to read in code.
- * 
  * <h4>Implementation specification</h4>
  * This interface places no restrictions on the mutability of implementations,
  * however immutability is strongly recommended.

src/main/java/javax/money/package-info.java

@@ -9,7 +9,27 @@
  * reserved.
  */
 /**
- * Money and Currencies API.
+ * This package defines the Money and Currency API. In more detail:
+ * <ul>
+ * <li>JSR 354 defines a minimal set of interfaces for interoperability, since
+ * concrete usage scenarios do not allow to define an implementation that is
+ * capable of covering all aspects identified. Consequently it must be possible
+ * that implementations can provide several implementations for monetary
+ * amounts. <br/>
+ * Users should not reference the interfaces, instead the value types should be
+ * used.</li>
+ * <li>Implementations must provide value types for currencies and amounts,
+ * implementing {@link javax.money.CurrencyUnit} and
+ * {@link javax.money.MonetaryAmount}.</li>
+ * <li>Implementations must also provide a minimal set of roundings, modeled as
+ * {@link javax.money.MonetaryAdjuster}. This should include basic roundings for
+ * ISO currencies, roundings defined by {@link java.math.MathContext} or
+ * {@link java.math.RoundingMode}.</li>
+ * <li>This API must avoid restrictions that prevents its use in different
+ * runtime environments, such as EE or ME.</li>
+ * <li>Method naming and style for currency modelling should be in alignment
+ * with parts of the Java Collection API or {@code java.time} / [JodaMoney].</li>
+ * </ul>
  */
 package javax.money;