From 3fea1eb10256e9a2c95fb48d406d6915f6122a75 Mon Sep 17 00:00:00 2001 From: keilw Date: Mon, 14 Oct 2013 20:46:27 +0200 Subject: [PATCH 1/7] Introducing subunit --- src/main/java/javax/money/MonetaryAmount.java | 15 ++++ src/main/java/javax/money/Subunit.java | 68 +++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 src/main/java/javax/money/Subunit.java diff --git a/src/main/java/javax/money/MonetaryAmount.java b/src/main/java/javax/money/MonetaryAmount.java index 7639353cb..2440ac0b8 100644 --- a/src/main/java/javax/money/MonetaryAmount.java +++ b/src/main/java/javax/money/MonetaryAmount.java @@ -13,6 +13,7 @@ package javax.money; import java.math.BigDecimal; +import java.util.List; /** * Interface defining a monetary amount. The effective internal representation @@ -233,5 +234,19 @@ public interface MonetaryAmount { * not null */ public MonetaryAmount with(MonetaryAdjuster adjuster); + + /** + * Returns the list of subunits uniquely defining the value of this MonetaryAmount. + * The list may be empty, but never {@code null} + * @return the list of currency units, never {@code null} + */ + public List getSubunits(); + + /** + * Returns the value of the requested unit. + * The units returned from getUnits() uniquely define the value of the TemporalAmount. + * A value must be returned for the main CurrencyUnit. If the unit listed in getUnits. + */ + public long get(CurrencyUnit unit); } diff --git a/src/main/java/javax/money/Subunit.java b/src/main/java/javax/money/Subunit.java new file mode 100644 index 000000000..d7b74464b --- /dev/null +++ b/src/main/java/javax/money/Subunit.java @@ -0,0 +1,68 @@ +/* + * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE + * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT. + * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY + * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE + * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE" + * BUTTON AT THE BOTTOM OF THIS PAGE. Specification: JSR-354 Money and Currency + * API ("Specification") Copyright (c) 2012-2013, Credit Suisse All rights + * reserved. + */ +package javax.money; + +/** + * A unit of currency. + *

+ * This interface represents a unit of currency such as the British Pound, Euro, + * US Dollar, Bitcoin or other. It is mainly defined to provide interoperability + * between different implementations. + *

+ * Currencies can be distinguished by separate {@link #getCurrencyCode()} codes, + * similar to {@link java.util.Currency}. + *

Implementation specification

+ * Implementation of this class + * + * + * @author Werner Keil + * + * @see Wikipedia: Denomination (currency) + */ +public interface Subunit extends CurrencyUnit { + + /** + * Gets the unique currency code, the effective code depends on the + * currency. + *

+ * Since each currency is identified by this code, the currency code is + * required to be defined for every {@link Subunit} and not + * {@code null} or empty. + *

+ * 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. + * However, alternate currencies can have different codes. Also + * there is no constraint about the formatting of alternate codes, + * despite they fact that the currency codes must be unique. + */ + public String getCurrencyCode(); + + /** + * Gets the number of fraction digits used with this subunit. + * For example, the default number of fraction digits for the Euro is 2, + * while for the Japanese Yen it's 0. + * In the case of pseudo-currencies, such as IMF Special Drawing Rights, + * -1 is returned. + * + * @return the number of fraction digits used with this subunit + */ + public int getFractionDigits(); + +} From 8ab01daa670e9312cf64ea33e112c908f4e93c7c Mon Sep 17 00:00:00 2001 From: keilw Date: Mon, 14 Oct 2013 21:35:57 +0200 Subject: [PATCH 2/7] Updated to Subunit --- pom.xml | 2 +- src/main/java/javax/money/Subunit.java | 29 +++++++------------------- 2 files changed, 9 insertions(+), 22 deletions(-) diff --git a/pom.xml b/pom.xml index 74f565430..bfa7d386b 100644 --- a/pom.xml +++ b/pom.xml @@ -15,7 +15,7 @@ jsr354-api jar - 0.7-SNAPSHOT + 0.7.1-SNAPSHOT JSR 354 (Money and Currency API) http://java.net/projects/javamoney diff --git a/src/main/java/javax/money/Subunit.java b/src/main/java/javax/money/Subunit.java index d7b74464b..8d4b76dad 100644 --- a/src/main/java/javax/money/Subunit.java +++ b/src/main/java/javax/money/Subunit.java @@ -11,11 +11,10 @@ package javax.money; /** - * A unit of currency. + * A subunit of currency. *

- * This interface represents a unit of currency such as the British Pound, Euro, - * US Dollar, Bitcoin or other. It is mainly defined to provide interoperability - * between different implementations. + * In a currency, there is usually a main unit (base), and a subunit that is a fraction of the main unit. + * In some countries, there are multiple levels of subunits. *

* Currencies can be distinguished by separate {@link #getCurrencyCode()} codes, * similar to {@link java.util.Currency}. @@ -34,26 +33,14 @@ * @see Wikipedia: Denomination (currency) */ public interface Subunit extends CurrencyUnit { - + /** - * Gets the unique currency code, the effective code depends on the - * currency. - *

- * Since each currency is identified by this code, the currency code is - * required to be defined for every {@link Subunit} and not - * {@code null} or empty. - *

- * For ISO codes the 3-letter ISO code should be returned. For non ISO - * currencies no constraints are defined. + * Get the identifier of this subunit. * - * @return the currency code, never {@code null}. For the ISO-4217 - * namespace, this this will be the three letter ISO-4217 code. - * However, alternate currencies can have different codes. Also - * there is no constraint about the formatting of alternate codes, - * despite they fact that the currency codes must be unique. + * @return The identifier, never null. */ - public String getCurrencyCode(); - + public String getId(); + /** * Gets the number of fraction digits used with this subunit. * For example, the default number of fraction digits for the Euro is 2, From 4fbbafff3164a02b691d2318337fa68a5fe63d77 Mon Sep 17 00:00:00 2001 From: keilw Date: Tue, 15 Oct 2013 01:57:05 +0200 Subject: [PATCH 3/7] Updated subunit --- src/main/java/javax/money/MonetaryAmount.java | 12 ++++++------ .../java/javax/money/{Subunit.java => SubUnit.java} | 7 ++++--- 2 files changed, 10 insertions(+), 9 deletions(-) rename src/main/java/javax/money/{Subunit.java => SubUnit.java} (85%) diff --git a/src/main/java/javax/money/MonetaryAmount.java b/src/main/java/javax/money/MonetaryAmount.java index 2440ac0b8..862a79e01 100644 --- a/src/main/java/javax/money/MonetaryAmount.java +++ b/src/main/java/javax/money/MonetaryAmount.java @@ -158,7 +158,7 @@ public interface MonetaryAmount { * * @return the fraction numerator */ - public long getAmountFractionNumerator(); + //public long getAmountFractionNumerator(); /** * Gets the denominator of the fractional amount of the currency. @@ -180,7 +180,7 @@ public interface MonetaryAmount { * * @return the fraction denominator */ - public long getAmountFractionDenominator(); + //public long getAmountFractionDenominator(); /** * Queries this monetary amount for a value. @@ -214,7 +214,7 @@ public interface MonetaryAmount { * date = date.with(amountRoundedToNearestWholeUnit()); * * - * Hereby also the method signatur on the implementation type must return + * Hereby also the method signature on the implementation type must return * the concrete type, to enable a fluent API, e.g. * * 

@@ -238,14 +238,14 @@ public interface MonetaryAmount {
 	/**
 	 * Returns the list of subunits uniquely defining the value of this MonetaryAmount.
 	 * The list may be empty, but never {@code null}
-	 * @return the list of currency units, never {@code null}
+	 * @return the list of subunits, never {@code null}
 	 */
-	public List getSubunits();
+	public List getSubUnits();
 
 	/**
 	 * Returns the value of the requested unit. 
 	 * The units returned from getUnits() uniquely define the value of the TemporalAmount.
-	 * A value must be returned for the main CurrencyUnit. If the unit listed in getUnits.
+	 * A value must be returned for the main CurrencyUnit. If the currency has subunits, each .
 	 */
 	public long get(CurrencyUnit unit);
 
diff --git a/src/main/java/javax/money/Subunit.java b/src/main/java/javax/money/SubUnit.java
similarity index 85%
rename from src/main/java/javax/money/Subunit.java
rename to src/main/java/javax/money/SubUnit.java
index 8d4b76dad..30adb1b38 100644
--- a/src/main/java/javax/money/Subunit.java
+++ b/src/main/java/javax/money/SubUnit.java
@@ -16,8 +16,7 @@
  * In a currency, there is usually a main unit (base), and a subunit that is a fraction of the main unit.
  * In some countries, there are multiple levels of subunits.
  * 

- * Currencies can be distinguished by separate {@link #getCurrencyCode()} codes,
- * similar to {@link java.util.Currency}.
+ * Currency subunits can be distinguished by separate {@link #getId()} Ids. Each Id is unique per currency.
  * 
Implementation specification

  * Implementation of this class
  * 
    
@@ -31,11 +30,13 @@
  * @author Werner Keil
  * 
  * @see Wikipedia: Denomination (currency)
+ * @see EU: Currency subunit
  */
-public interface Subunit extends CurrencyUnit {
+public interface SubUnit extends CurrencyUnit {
 	
 	/**
 	 * Get the identifier of this subunit.
+	 * This identifier is unique per currency.
 	 * 
 	 * @return The identifier, never null.
 	 */

From 7b6d176c8385fa609d079897d8239103b36b32d9 Mon Sep 17 00:00:00 2001
From: keilw 
Date: Tue, 15 Oct 2013 03:19:21 +0200
Subject: [PATCH 4/7] Updated subunits

---
 src/main/java/javax/money/MonetaryAmount.java | 3 +++
 src/main/java/javax/money/SubUnit.java        | 1 +
 2 files changed, 4 insertions(+)

diff --git a/src/main/java/javax/money/MonetaryAmount.java b/src/main/java/javax/money/MonetaryAmount.java
index 862a79e01..b0c9c1753 100644
--- a/src/main/java/javax/money/MonetaryAmount.java
+++ b/src/main/java/javax/money/MonetaryAmount.java
@@ -124,6 +124,9 @@ public interface MonetaryAmount {
 	/**
 	 * Gets the amount in terms of whole units of the currency.
 	 * 
    
+	 * This is a convenience method for {@code get(getCurrency())}
+	 * 
    
+	 * 
    
 	 * An amount is defined to consist of an amount of whole currency units plus
 	 * a fraction of the unit. This method returns the amount of whole units,
 	 * such as the number of complete US dollars represented.
diff --git a/src/main/java/javax/money/SubUnit.java b/src/main/java/javax/money/SubUnit.java
index 30adb1b38..bf9ae423a 100644
--- a/src/main/java/javax/money/SubUnit.java
+++ b/src/main/java/javax/money/SubUnit.java
@@ -28,6 +28,7 @@
  * 

  * 
  * @author Werner Keil
+ * @version 0.2
  * 
  * @see Wikipedia: Denomination (currency)
  * @see EU: Currency subunit

From 2761c5e7a4782a40e6f8e2b9df86de74f2c21f59 Mon Sep 17 00:00:00 2001
From: keilw 
Date: Thu, 17 Oct 2013 02:42:54 +0200
Subject: [PATCH 5/7] Updated JavaDoc

---
 src/main/java/javax/money/SubUnit.java | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/java/javax/money/SubUnit.java b/src/main/java/javax/money/SubUnit.java
index bf9ae423a..4cb42eb0c 100644
--- a/src/main/java/javax/money/SubUnit.java
+++ b/src/main/java/javax/money/SubUnit.java
@@ -15,6 +15,7 @@
  * 

  * In a currency, there is usually a main unit (base), and a subunit that is a fraction of the main unit.
  * In some countries, there are multiple levels of subunits.
+ * A few countries (at least Iran is documented) use subunits based on multiples of the main unit.
  * 

  * Currency subunits can be distinguished by separate {@link #getId()} Ids. Each Id is unique per currency.
  * 
Implementation specification

@@ -28,7 +29,7 @@
  * 
  * 
  * @author Werner Keil
- * @version 0.2
+ * @version 0.3
  * 
  * @see Wikipedia: Denomination (currency)
  * @see EU: Currency subunit

From c343a570ca2b707728f1b51d2bc76e86e664d5aa Mon Sep 17 00:00:00 2001
From: keilw 
Date: Sat, 19 Oct 2013 00:01:21 +0200
Subject: [PATCH 6/7] Updated JavaDoc

---
 src/main/java/javax/money/MonetaryAmount.java | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/src/main/java/javax/money/MonetaryAmount.java b/src/main/java/javax/money/MonetaryAmount.java
index b0c9c1753..c18491e53 100644
--- a/src/main/java/javax/money/MonetaryAmount.java
+++ b/src/main/java/javax/money/MonetaryAmount.java
@@ -12,9 +12,6 @@
  */
 package javax.money;
 
-import java.math.BigDecimal;
-import java.util.List;
-
 /**
  * Interface defining a monetary amount. The effective internal representation
  * of an amount may vary depending on the implementation used. JSR 354
@@ -145,7 +142,7 @@ public interface MonetaryAmount {
 	public long getAmountWhole();
 
 	/**
-	 * Gets the numerator of the fractional amount of the currency.
+	 * Gets the numerator of the currency's fractional amount.
 	 * 

 	 * An amount is defined to consist of an amount of whole currency units plus
 	 * a fraction of the unit. This method returns the numerator of the fraction
@@ -164,7 +161,7 @@ public interface MonetaryAmount {
 	//public long getAmountFractionNumerator();
 
 	/**
-	 * Gets the denominator of the fractional amount of the currency.
+	 * Gets the denominator of the currency's fractional amount.
 	 * 

 	 * An amount is defined to consist of an amount of whole currency units plus
 	 * a fraction of the unit. This method returns the denominator of the
@@ -177,8 +174,6 @@ public interface MonetaryAmount {
 	 * 
    
 	 * 
  • {@code fractionDenominator > 0}.
 	 * 
  • {@code fractionDenominator > abs(fractionNominator)}.
-	 * 
  • it is recommended that the denominator is a power of 10 (1, 10, 100,
-	 * 1000,...).
 	 * 

 	 * 
 	 * @return the fraction denominator
@@ -243,12 +238,15 @@ public interface MonetaryAmount {
 	 * The list may be empty, but never {@code null}
 	 * @return the list of subunits, never {@code null}
 	 */
-	public List getSubUnits();
+	//public List getSubUnits();
 
 	/**
 	 * Returns the value of the requested unit. 
-	 * The units returned from getUnits() uniquely define the value of the TemporalAmount.
-	 * A value must be returned for the main CurrencyUnit. If the currency has subunits, each .
+	 * A value must be returned for the main CurrencyUnit. 
+	 * If the currency has subunits, each subunit used by the amount returns a value, 
+	 * for subunits not used in this amount the value returned will be zero.
+	 * 
+	 * @return the amount's number for the given currency unit
 	 */
 	public long get(CurrencyUnit unit);
 

From 1ad18ab7ef6ec9b147dfba627cbfaf6068874067 Mon Sep 17 00:00:00 2001
From: keilw 
Date: Sat, 26 Oct 2013 20:30:04 +0200
Subject: [PATCH 7/7] Changed visibility of fraction methods

---
 src/main/java/javax/money/MonetaryAmount.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/java/javax/money/MonetaryAmount.java b/src/main/java/javax/money/MonetaryAmount.java
index c18491e53..43637a2e6 100644
--- a/src/main/java/javax/money/MonetaryAmount.java
+++ b/src/main/java/javax/money/MonetaryAmount.java
@@ -158,7 +158,7 @@ public interface MonetaryAmount {
 	 * 
 	 * @return the fraction numerator
 	 */
-	//public long getAmountFractionNumerator();
+	public long getAmountFractionNumerator();
 
 	/**
 	 * Gets the denominator of the currency's fractional amount.
@@ -178,7 +178,7 @@ public interface MonetaryAmount {
 	 * 
 	 * @return the fraction denominator
 	 */
-	//public long getAmountFractionDenominator();
+	public long getAmountFractionDenominator();
 
 	/**
 	 * Queries this monetary amount for a value.