Skip to content

Commit 7175d11

Browse files
mkurzmkurz
committed
Document explicit formatter locales
1 parent 10fa21d commit 7175d11

3 files changed

Lines changed: 13 additions & 3 deletions

File tree

‎web/play-java-forms/src/main/java/play/data/format/Formatters.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ public Formatters(MessagesApi messagesApi) {
3737
*
3838
* @param text the text to parse
3939
* @param clazz class representing the required type
40+
* @param locale the locale to use while parsing
4041
* @param <T> the type to parse out of the text
4142
* @return the parsed value
4243
*/
@@ -49,6 +50,7 @@ public <T> T parse(String text, Class<T> clazz, Locale locale) {
4950
*
5051
* @param field the related field (custom formatters are extracted from this field annotation)
5152
* @param text the text to parse
53+
* @param locale the locale to use while parsing
5254
* @param <T> the type to parse out of the text
5355
* @return the parsed value
5456
*/
@@ -61,6 +63,7 @@ public <T> T parse(Field field, String text, Locale locale) {
6163
* Computes the display string for any value.
6264
*
6365
* @param t the value to print
66+
* @param locale the locale to use while formatting
6467
* @param <T> the type to print
6568
* @return the formatted string
6669
*/
@@ -80,6 +83,7 @@ public <T> String print(T t, Locale locale) {
8083
*
8184
* @param field the related field - custom formatters are extracted from this field annotation
8285
* @param t the value to print
86+
* @param locale the locale to use while formatting
8387
* @param <T> the type to print
8488
* @return the formatted string
8589
*/
@@ -92,6 +96,7 @@ public <T> String print(Field field, T t, Locale locale) {
9296
*
9397
* @param desc the field descriptor - custom formatters are extracted from this descriptor.
9498
* @param t the value to print
99+
* @param locale the locale to use while formatting
95100
* @param <T> the type to print
96101
* @return the formatted string
97102
*/

‎web/play-java-forms/src/main/java/play/data/internal/binding/core/convert/ConversionService.java‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@
2424

2525
/**
2626
* A service interface for type conversion. This is the entry point into the convert system.
27-
* Call {@link #convert(Object, Class)} to perform a thread-safe type conversion using this system.
27+
* Call {@link #convert(Object, Class, Locale)} to perform a thread-safe type conversion using this
28+
* system.
2829
*
2930
* @author Keith Donald
3031
* @author Phillip Webb
@@ -51,7 +52,7 @@ public interface ConversionService {
5152
* Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}.
5253
* The TypeDescriptors provide additional context about the source and target locations
5354
* where conversion would occur, often object fields or property locations.
54-
* <p>If this method returns {@code true}, it means {@link #convert(Object, TypeDescriptor, TypeDescriptor)}
55+
* <p>If this method returns {@code true}, it means {@link #convert(Object, TypeDescriptor, TypeDescriptor, Locale)}
5556
* is capable of converting an instance of {@code sourceType} to {@code targetType}.
5657
* <p>Special note on collections, arrays, and maps types:
5758
* For conversion between collection, array, and map types, this method will return {@code true}
@@ -71,6 +72,7 @@ public interface ConversionService {
7172
* Convert the given {@code source} to the specified {@code targetType}.
7273
* @param source the source object to convert (may be {@code null})
7374
* @param targetType the target type to convert to (required)
75+
* @param locale the locale to use while converting
7476
* @return the converted object, an instance of targetType
7577
* @throws ConversionException if a conversion exception occurred
7678
* @throws IllegalArgumentException if targetType is {@code null}
@@ -79,11 +81,12 @@ public interface ConversionService {
7981

8082
/**
8183
* Convert the given {@code source} to the specified {@code targetType}.
82-
* <p>Delegates to {@link #convert(Object, TypeDescriptor, TypeDescriptor)}
84+
* <p>Delegates to {@link #convert(Object, TypeDescriptor, TypeDescriptor, Locale)}
8385
* and encapsulates the construction of the source type descriptor using
8486
* {@link TypeDescriptor#forObject(Object)}.
8587
* @param source the source object
8688
* @param targetType the target type
89+
* @param locale the locale to use while converting
8790
* @return the converted value
8891
* @throws ConversionException if a conversion exception occurred
8992
* @throws IllegalArgumentException if targetType is {@code null}
@@ -100,6 +103,7 @@ default Object convert(Object source, TypeDescriptor targetType, Locale locale)
100103
* @param sourceType context about the source type to convert from
101104
* (may be {@code null} if source is {@code null})
102105
* @param targetType context about the target type to convert to (required)
106+
* @param locale the locale to use while converting
103107
* @return the converted object, an instance of {@link TypeDescriptor#getObjectType() targetType}
104108
* @throws ConversionException if a conversion exception occurred
105109
* @throws IllegalArgumentException if targetType is {@code null},

‎web/play-java-forms/src/main/java/play/data/internal/binding/core/convert/converter/GenericConverter.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ public interface GenericConverter {
5555
* @param source the source object to convert (may be {@code null})
5656
* @param sourceType the type descriptor of the field we are converting from
5757
* @param targetType the type descriptor of the field we are converting to
58+
* @param locale the locale to use while converting
5859
* @return the converted object
5960
*/
6061
Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType, Locale locale);

0 commit comments

Comments
 (0)