Skip to content

Commit 43c262e

Browse files
committed
Updated spec for latest timestamp API changes.
1 parent a3ee283 commit 43c262e

File tree

1 file changed

+17
-16
lines changed

1 file changed

+17
-16
lines changed

src/main/asciidoc/JavaMoneySpecification.adoc

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -506,9 +506,10 @@ also to the section <<Boostrap>> for more details on possible EE/CDI integration
506506
+from(...)+
507507
.. parsing is explicitly named, as it is generally special, named +parse(...)+
508508
.. overall monetary API _feel_ should be similar to +java.math.BigDecimal+.
509-
. There are rare places where POSIX timestamps based on millisecond resolution as returned by
510-
+System.currentTimeMillis()+ are used. These timestamps are modelled as +long+. New date and time types introduced
511-
with Java 8 are supported similarly, but of course, will not be available in Java prior to version 8.
509+
. Queries and contexts may require adding additional time related data, such as POSIX timestamps based on millisecond
510+
resolution as returned by +System.currentTimeMillis()+ or other time types based on new Java 8 date/time API.
511+
These aspects are not explicitly modelled, since they depend on the capabilities of the corresponding providers
512+
and the <<MetadataModeling>> capabilities provide good flexibility to implement these things effectively.
512513
. This JSR will probably also be used also for (business) critical software like real time trading and similar systems.
513514
These systems and use cases require very specific parameters, which are impossible to model by this JSR and
514515
may vary for different use cases, provider and/or companies. As a solution attributable contexts and queries can be
@@ -674,7 +675,7 @@ Hereby
674675
details on contexts). It basically allows to evaluate the data provider of a currency unit, but can also contain
675676
additional data as useful, determined by the implementation that provided the currency instance. This context allows
676677
to support also more complex use cases for extended currency meta-data such as:
677-
** validity timestamps
678+
** validity range, e.g. modelled as from/to +LocalDate+
678679
** regional validity constraints
679680
** provider validity constraints, e.g. the target stock exchange
680681
** internal provider reference ids
@@ -790,8 +791,8 @@ Hereby
790791
* The rest of the methods model common arithmetic operations that are often used in financial applications. Adding
791792
and subtracting hereby is only possible with amounts that are of the same currency (aka being 'currency compatible'
792793
footnote:[Note that currency conversion is a complex aspect that can not be performed implicitly or automatically.
793-
E.g. a conversion rate is dependent from the timestamp, the currencies involved, the provider, the amount ...])
794-
with the amount, on which the operation is executed. The arithmetic methods should basically behave
794+
E.g. a conversion rate is dependent from the target date and time, the currencies involved, the provider, the
795+
amount ...]) with the amount, on which the operation is executed. The arithmetic methods should basically behave
795796
similar to +java.math.BigDecimal+, always returning amounts with the same +CurrencyUnit+.
796797
* The specification and interface do not define precisely how the amount is stored. Implementations could use a
797798
+BigDecimal+, +long+ or something else. The only constraint is that the numeric value can be exposed as +NumberValue+
@@ -1399,8 +1400,8 @@ cases:
13991400
. Access cash rounding for a +CurrencyUnit+, which may be different from the default rounding.
14001401
E.g. for +Swiss Francs+ the cash rounding will be in +5+ minor unit steps: +1.00, 1.05, 1.10+ etc. This can be
14011402
achieved by creating an instance of +RoundingContext+ with _currency unit_ and _cashRounding=true_ explicitly yet.
1402-
. Access to historic roundings can be achieved by setting +CurrencyUnit+ and the target timestamp. If the
1403-
provider also supports other time types instead of +long+, they can be set as attributes on the context.
1403+
. Access to historic roundings can be achieved by setting a +CurrencyUnit+ and an (optional) target +LocalDate+ (or
1404+
whatever time type is most appropriate).
14041405
. by setting the _rounding id_ to a non default value, custom roundings can be implemented, e.g. for support
14051406
of technical formats.
14061407
@@ -1411,17 +1412,18 @@ default currency rounding (e.g. for +CHF/Swiss Francs+), as follows:
14111412
[source,java]
14121413
.Example how a cash rounding could be accessed (not part of the API)
14131414
-------------------------------------------------------------------------------
1415+
LocalDate localDate = ...;
14141416
MonetaryRounding rounding = MonetaryRoundings.getRounding(
14151417
RoundingQueryBuilder.of() <1>
14161418
.setRoundingName("cashRounding") <2>
1417-
.setCurrencyUnit("USD") <3>
1418-
.setTimestamp(temporalAccessor) <4>
1419+
.setCurrencyUnit("CHF") <3>
1420+
.set(localDate) <4>
14191421
.build()); <5>
14201422
-------------------------------------------------------------------------------
14211423
<1> Access a rounding by passing a +RoundingQuery+
14221424
<2> Acquire a specific _named_ rounding.
14231425
<3> Set the target currency unit (predefined attribute).
1424-
<4> Access a rounding valid for the given timestamp.
1426+
<4> Access a rounding valid for the given +LocalDate+.
14251427
<5> Creates the new +RoundingQuery+ instance.
14261428
14271429
Finally the default rounding provider chain can be configured within +javamoney.properties+ added to the classpath:
@@ -1434,7 +1436,6 @@ Finally the default rounding provider chain can be configured within +javamoney.
14341436
javax.money.defaults.MonetaryRoundings.providerChain=provider1,provider2,provider3
14351437
-------------------------------------------------------------------------------
14361438
1437-
14381439
[[FunctionalSupport]]
14391440
==== Additional Functional Support
14401441
Additionally to monetary operators and monetary queries access the the numeric
@@ -1503,7 +1504,7 @@ concern, since
15031504
* conversion may be different based on the provider of the exchange rates
15041505
* conversion rates may vary based on the amount to be converted
15051506
* conversion rates may vary based on contract or business unit
1506-
* conversion rates are different related to the target timestamp
1507+
* conversion rates are different related to the target date/time
15071508
15081509
Hereby this list is not complete. Different companies may have further requirements and aspects to be considered.
15091510
The API focuses on the common aspects of currency conversion such as:
@@ -1608,7 +1609,7 @@ Hereby
16081609
* the +ConversionContext+ accessible from +getContext()+ allows to store additional meta data (refer also to
16091610
<<MetadataModeling>> for further details) about the rate instance, such as
16101611
** the rate's provider
1611-
** the rate's timestamp
1612+
** the rate's +LocalDateTime+ or +ZonedDateTime+
16121613
** any other data that may be relevant
16131614
* each instance of rate finally can easily be converted into an according +ExchangeRate.Builder+ instance, so
16141615
adaptations/changes on existing rates can be done easily.
@@ -2383,8 +2384,8 @@ Implementations of this JSR should also consider additional aspects:
23832384
instances, e.g. you can set a maximal scale of +1+ and a +RoundingMode+ as an additional attribute.
23842385
. Implementations should also support cash rounding. E.g. in Switzerland default rounding is done for a scale of +2+,
23852386
whereas when paying in cash, the minor units must be divisible by +5+, since +5+ is the smallest coin possible.
2386-
. Finally it may also possible to provide _historic_ roundings hereby considering an additional timestamp or
2387-
date given.
2387+
. Finally it may also possible to provide _historic_ roundings hereby considering an additional target date/time, e.g.
2388+
modelled as +LocalDate+.
23882389
23892390
23902391
[[CurrencyConversionSpi]]

0 commit comments

Comments
 (0)