Skip to content

Commit d978e3f

Browse files
NonSwagNonSwag
committed
Added Currency interface and improved currency handling
Introduced `Currency` interface to define currency properties and formatting. Deprecated older `EconomyController` methods in favor of `Currency` methods for better consistency and multi-currency support.
1 parent 91e4172 commit d978e3f

File tree

2 files changed

+206
-4
lines changed

2 files changed

+206
-4
lines changed

‎src/main/java/net/thenextlvl/service/api/economy/EconomyController.java‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
package net.thenextlvl.service.api.economy;
22

3+
import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;
34
import net.thenextlvl.service.api.Controller;
5+
import net.thenextlvl.service.api.economy.currency.Currency;
46
import net.thenextlvl.service.api.economy.currency.CurrencyHolder;
57
import org.bukkit.OfflinePlayer;
68
import org.bukkit.World;
@@ -14,7 +16,8 @@
1416
import java.util.concurrent.CompletableFuture;
1517

1618
/**
17-
* The AccountController interface provides methods to create, retrieve and delete accounts.
19+
* EconomyController is an interface that provides methods for managing and interacting
20+
* with economic systems, such as currency formatting, account retrieval, and multi-currency support.
1821
*/
1922
@NullMarked
2023
public interface EconomyController extends Controller, CurrencyHolder {
@@ -23,23 +26,35 @@ public interface EconomyController extends Controller, CurrencyHolder {
2326
*
2427
* @param locale the locale for which to retrieve the plural currency name
2528
* @return the plural form of the currency name as a string
29+
* @deprecated use {@link Currency#getDisplayNamePlural(Locale)}
2630
*/
27-
String getCurrencyNamePlural(Locale locale);
31+
@Deprecated(forRemoval = true, since = "2.4.0")
32+
default String getCurrencyNamePlural(Locale locale) {
33+
return PlainTextComponentSerializer.plainText().serialize(getDefaultCurrency().getDisplayNamePlural(locale));
34+
}
2835

2936
/**
3037
* Retrieves the name of the currency associated with the specified locale.
3138
*
3239
* @param locale the locale for which to retrieve the currency name
3340
* @return the name of the currency as a string
41+
* @deprecated use {@link Currency#getDisplayNameSingular(Locale)}
3442
*/
35-
String getCurrencyNameSingular(Locale locale);
43+
@Deprecated(forRemoval = true, since = "2.4.0")
44+
default String getCurrencyNameSingular(Locale locale) {
45+
return PlainTextComponentSerializer.plainText().serialize(getDefaultCurrency().getDisplayNameSingular(locale));
46+
}
3647

3748
/**
3849
* Retrieves the currency symbol associated with the economy controller.
3950
*
4051
* @return the currency symbol as a string
52+
* @deprecated use {@link Currency#getSymbol()}
4153
*/
42-
String getCurrencySymbol();
54+
@Deprecated(forRemoval = true, since = "2.4.0")
55+
default String getCurrencySymbol() {
56+
return PlainTextComponentSerializer.plainText().serialize(getDefaultCurrency().getSymbol());
57+
}
4358

4459
/**
4560
* Loads all accounts asynchronously.

‎src/main/java/net/thenextlvl/service/api/economy/currency/Currency.java‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
package net.thenextlvl.service.api.economy.currency;
2+
3+
import net.kyori.adventure.audience.Audience;
4+
import net.kyori.adventure.identity.Identity;
5+
import net.kyori.adventure.text.Component;
6+
import org.jetbrains.annotations.ApiStatus;
7+
import org.jspecify.annotations.NullMarked;
8+
9+
import java.util.Locale;
10+
import java.util.Optional;
11+
import java.util.OptionalInt;
12+
13+
@NullMarked
14+
public interface Currency {
15+
/**
16+
* Retrieves the name of the currency.
17+
*
18+
* @return the name of the currency as a string
19+
*/
20+
String getName();
21+
22+
/**
23+
* Retrieves the singular display name component of the currency based on the audience's locale.
24+
* <p>
25+
* If the audience does not specify a locale, {@link Locale#US} is used.
26+
*
27+
* @param audience the audience whose locale is used to determine the singular display name
28+
* @return the singular display name as a {@code Component} for the audience's locale
29+
*/
30+
@ApiStatus.NonExtendable
31+
default Component getDisplayNameSingular(Audience audience) {
32+
return getDisplayNameSingular(audience.getOrDefault(Identity.LOCALE, Locale.US));
33+
}
34+
35+
/**
36+
* Retrieves the singular display name component of the currency for the specified locale.
37+
*
38+
* @param locale the locale for which the singular display name should be retrieved
39+
* @return the singular display name as a {@code Component} for the specified locale
40+
*/
41+
Component getDisplayNameSingular(Locale locale);
42+
43+
44+
/**
45+
* Retrieves the plural display name component of the currency based on the audience's locale.
46+
* <p>
47+
* If the audience does not specify a locale, {@link Locale#US} is used.
48+
*
49+
* @param audience the audience whose locale is used to determine the plural display name
50+
* @return the plural display name as a {@code Component} for the audience's locale
51+
*/
52+
@ApiStatus.NonExtendable
53+
default Component getDisplayNamePlural(Audience audience) {
54+
return getDisplayNamePlural(audience.getOrDefault(Identity.LOCALE, Locale.US));
55+
}
56+
57+
/**
58+
* Retrieves the plural display name component of the currency for the specified locale.
59+
*
60+
* @param locale the locale for which the plural display name should be retrieved
61+
* @return the plural display name as a {@code Component} for the specified locale
62+
*/
63+
Component getDisplayNamePlural(Locale locale);
64+
65+
/**
66+
* Retrieves the currency symbol.
67+
*
68+
* @return the currency symbol as a component
69+
*/
70+
Component getSymbol();
71+
72+
/**
73+
* Formats the specified amount as a component.
74+
*
75+
* @param amount the amount to be formatted
76+
* @param audience the audience to format the amount for
77+
* @return the formatted amount as a component
78+
* @see #format(Number, Locale)
79+
*/
80+
@ApiStatus.NonExtendable
81+
default Component format(Number amount, Audience audience) {
82+
return format(amount, audience.getOrDefault(Identity.LOCALE, Locale.US));
83+
}
84+
85+
/**
86+
* Formats the specified amount as a component.
87+
*
88+
* @param amount the amount to be formatted
89+
* @param locale the locale to format the amount in
90+
* @return the formatted amount as a component
91+
* @see #format(Number, Audience)
92+
*/
93+
Component format(Number amount, Locale locale);
94+
95+
/**
96+
* Retrieves the number of fractional digits used for formatting currency amounts.
97+
*
98+
* @return the number of fractional digits used for formatting currency amounts
99+
*/
100+
int getFractionalDigits();
101+
102+
/**
103+
* A builder interface for constructing instances of {@link Currency}.
104+
* The {@code Builder} allows for the configuration of currency properties such as
105+
* singular and plural display names, currency symbol, and fractional digits.
106+
*/
107+
interface Builder {
108+
/**
109+
* Sets the singular display name of the currency for a specific locale.
110+
*
111+
* @param name the singular display name component of the currency
112+
* @param locale the locale for which the singular display name is being set
113+
* @return the builder instance for chaining
114+
*/
115+
Builder displayNameSingular(Component name, Locale locale);
116+
117+
/**
118+
* Retrieves the singular display name component of the currency for the specified locale.
119+
*
120+
* @param locale the locale for which the singular display name should be retrieved
121+
* @return an {@code Optional} containing the singular display name as a {@code Component}, or empty
122+
*/
123+
Optional<Component> displayNameSingular(Locale locale);
124+
125+
/**
126+
* Sets the plural display name of the currency for a specific locale.
127+
*
128+
* @param name the plural display name component of the currency
129+
* @param locale the locale for which the plural display name is being set
130+
* @return the builder instance for chaining
131+
*/
132+
Builder displayNamePlural(Component name, Locale locale);
133+
134+
/**
135+
* Retrieves the plural display name component of the currency for the specified locale.
136+
*
137+
* @param locale the locale for which the plural display name should be retrieved
138+
* @return an {@code Optional} containing the plural display name as a {@code Component}, or empty
139+
*/
140+
Optional<Component> displayNamePlural(Locale locale);
141+
142+
/**
143+
* Sets the currency symbol as a {@code Component}.
144+
*
145+
* @param symbol the symbol component to represent the currency
146+
* @return the builder instance for chaining
147+
*/
148+
Builder symbol(Component symbol);
149+
150+
/**
151+
* Retrieves the currency symbol set on the {@code Builder}.
152+
*
153+
* @return an {@code Optional} containing the symbol as a {@code Component}, or empty
154+
*/
155+
Optional<Component> symbol();
156+
157+
/**
158+
* Sets the number of fractional digits to be used for the currency.
159+
* <p>
160+
* Fractional digits are generally used to specify the precision of the currency values,
161+
* for example, 2 fractional digits for most currencies such as USD (representing cents).
162+
*
163+
* @param fractionalDigits the number of fractional digits to set (must be a non-negative integer)
164+
* @return the builder instance for chaining
165+
* @throws IllegalArgumentException if {@code fractionalDigits} is negative
166+
*/
167+
Builder fractionalDigits(int fractionalDigits) throws IllegalArgumentException;
168+
169+
/**
170+
* Retrieves the number of fractional digits set for the currency.
171+
* <p>
172+
* Fractional digits represent the precision of the currency,
173+
* such as 2 for most currencies like USD (representing cents).
174+
*
175+
* @return an {@code OptionalInt} containing the number of fractional digits, or empty
176+
*/
177+
OptionalInt fractionalDigits();
178+
179+
/**
180+
* Builds and returns a {@link Currency} instance based on the properties set on the {@code Builder}.
181+
*
182+
* @return the constructed {@link Currency} instance
183+
*/
184+
@ApiStatus.OverrideOnly
185+
Currency build();
186+
}
187+
}

0 commit comments

Comments
 (0)