Merge branch 'master' of https://github.com/JavaMoney/jsr354-api.git

Author: keilw

README.txt

@@ -5,3 +5,7 @@ See the home page for more details:
 http://jcp.org/en/jsr/detail?id=354
 
 This is the API module of JSR 354.
+
+See also:
+http://javamoney.github.io/jsr354-api/
+

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

@@ -15,20 +15,26 @@
 /**
  * Strategy for adjusting a monetary amount.
  * <p>
- * Adjusters are a key tool for modifying monetary amounts.
- * They match the strategy design pattern, allowing different types of
- * adjustment to be easily captured.
- * Examples might be an adjuster that rounds the amount to the nearest 1000,
- * or one that performs currency conversion.
+ * Adjusters are a key tool for modifying monetary amounts. They match the
+ * strategy design pattern, allowing different types of adjustment to be easily
+ * captured. Examples might be an adjuster that rounds the amount to the nearest
+ * 1000, or one that performs currency conversion.
  * <p>
- * There are two equivalent ways of using a {@code MonetaryAdjuster}.
- * The first is to invoke the method on this interface.
- * The second is to use {@link MonetaryAmount#with(MonetaryAdjuster)}:
+ * There are two equivalent ways of using a {@code MonetaryAdjuster}. The first
+ * is to invoke the method on this interface. The second is to use
+ * {@link MonetaryAmount#with(MonetaryAdjuster)}, whereas implementations of
+ * {@link MonetaryAmount#with(MonetaryAdjuster)} must return the concrete type,
+ * instead of the interface to support a fluent style:
+ * 
  * <pre>
- *   // these two lines are equivalent, but the second approach is recommended
- *   monetary = thisAdjuster.adjustInto(monetary);
- *   monetary = monetary.with(thisAdjuster);
+ * // these two lines are equivalent, but the second approach is recommended
+ * monetary = thisAdjuster.adjustInto(monetary);
+ * monetary = anotherAdjuster.adjustInto(monetary);
+ * 
+ * // second approach, using a fluent API
+ * monetary = monetary.with(thisAdjuster).with(anotherAdjuster);
  * </pre>
+ * 
  * It is recommended to use the second approach, {@code with(MonetaryAdjuster)},
  * as it is a lot clearer to read in code.
  * 
@@ -40,42 +46,46 @@
 public interface MonetaryAdjuster {
 
 	/**
-     * Adjusts the specified monetary object.
-     * <p>
-     * This adjusts the specified monetary object using the logic
-     * encapsulated in the implementing class.
-     * Examples might be an adjuster that rounds the amount to the nearest 1000,
-     * or one that performs currency conversion.
-     * <p>
-     * There are two equivalent ways of using a {@code MonetaryAdjuster}.
-     * The first is to invoke the method on this interface.
-     * The second is to use {@link MonetaryAmount#with(MonetaryAdjuster)}:
-     * <pre>
-     *   // these two lines are equivalent, but the second approach is recommended
-     *   monetary = thisAdjuster.adjustInto(monetary);
-     *   monetary = monetary.with(thisAdjuster);
-     * </pre>
-     * 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>
-     * The implementation must take the input object and adjust it.
-     * The implementation defines the logic of the adjustment and is responsible for
-     * documenting that logic.
-     * It may use any method on {@code MonetaryAmount} to determine the result.
-     * <p>
-     * The input object must not be altered.
-     * Instead, an adjusted copy of the original must be returned.
-     * This provides equivalent, safe behavior for immutable and mutable monetary amounts.
-     * <p>
-     * This method may be called from multiple threads in parallel.
-     * It must be thread-safe when invoked.
-     *
-     * @param amount  the amount to adjust, not null
-     * @return a monetary amount with the adjustment made, not null
-     * @throws MonetaryException if unable to make the adjustment
-     * @throws ArithmeticException if numeric overflow occurs
-     */
+	 * Adjusts the specified monetary object.
+	 * <p>
+	 * This adjusts the specified monetary object using the logic encapsulated
+	 * in the implementing class. Examples might be an adjuster that rounds the
+	 * amount to the nearest 1000, or one that performs currency conversion.
+	 * <p>
+	 * There are two equivalent ways of using a {@code MonetaryAdjuster}. The
+	 * first is to invoke the method on this interface. The second is to use
+	 * {@link MonetaryAmount#with(MonetaryAdjuster)}:
+	 * 
+	 * <pre>
+	 * // these two lines are equivalent, but the second approach is recommended
+	 * monetary = thisAdjuster.adjustInto(monetary);
+	 * monetary = monetary.with(thisAdjuster);
+	 * </pre>
+	 * 
+	 * 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>
+	 * The implementation must take the input object and adjust it. The
+	 * implementation defines the logic of the adjustment and is responsible for
+	 * documenting that logic. It may use any method on {@code MonetaryAmount}
+	 * to determine the result.
+	 * <p>
+	 * The input object must not be altered. Instead, an adjusted copy of the
+	 * original must be returned. This provides equivalent, safe behavior for
+	 * immutable and mutable monetary amounts.
+	 * <p>
+	 * This method may be called from multiple threads in parallel. It must be
+	 * thread-safe when invoked.
+	 * 
+	 * @param amount
+	 *            the amount to adjust, not null
+	 * @return a monetary amount with the adjustment made, not null
+	 * @throws MonetaryException
+	 *             if unable to make the adjustment
+	 * @throws ArithmeticException
+	 *             if numeric overflow occurs
+	 */
 	public MonetaryAmount adjustInto(MonetaryAmount amount);
 
 }

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

@@ -26,27 +26,30 @@
  * This JSR additionally defines a couple of interoperability rules that each
  * implementation must follow:
  * <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>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>
+ * <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
+ * 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>Each implementation must at least provide two constructors, one taking
- * {@code (BigDecimal, CurrencyUnit)}, one taking
- * {@code (BigDecimal, CurrencyUnit)}.</li>
- * <li>External rounding must be applied, when accessing the numeric part of an
- * amount, if implied by the required target type. E.g. externalizing to a
- * double may truncate precision. If the target type supports the current
- * scale/precision, it is required that no external rounding is performed.</li>
- * <li>It is required that each implementation supports externalization to
- * {@link BigDecimal}.</li>
  * <li>Since implementations are required to be immutable, an operation must
  * 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}
  * method also defines additional interoperability requirements.</li>
  * </ul>
- * Nevertheless basically an amount provides a functionality similar to
- * {@link BigDecimal}. Also it is required that implementations of this
- * interface are
+ * It is required that implementations of this interface are
  * <ul>
  * <li>immutable</li>
  * <li>thread-safe</li>
@@ -130,8 +133,8 @@ public interface MonetaryAmount {
 	public <R> R query(MonetaryQuery<R> query);
 
 	/**
-	 * Returns an adjusted object of the same type as this object with the
-	 * adjustment made.
+	 * Returns an adjusted object <b>of the same type</b> as this object with
+	 * the adjustment made.
 	 * <p>
 	 * This adjusts this monetary amount according to the rules of the specified
 	 * adjuster. A typical adjuster will change the amount and leave the
@@ -145,11 +148,25 @@ public interface MonetaryAmount {
 	 * date = date.with(amountRoundedToNearestWholeUnit());
 	 * </pre>
 	 * 
+	 * Hereby also the method signatur on the implementation type must return
+	 * the concrete type, to enable a fluent API, e.g.
+	 * 
+	 * <pre>
+	 * public final class MM implements MonetaryAmount{
+	 *   ...
+	 *   public MM with(MonetaryAdjuster adjuster){
+	 *     ... 
+	 *   }
+	 *   
+	 *   ...
+	 * }
+	 * </pre>
+	 * 
 	 * @param adjuster
 	 *            the adjuster to use, not null
 	 * @return an object of the same type with the specified adjustment made,
 	 *         not null
 	 */
 	public MonetaryAmount with(MonetaryAdjuster adjuster);
-	
+
 }