T - Type of value being created.public interface BuilderRef<T>
BuilderRef manages the state of a mutable value contained in a builder. It ensures that things like arrays built up in a builder can be used directly in objects being built without copies, and it allows the builder to be reused without mutating previously built objects.
Smithy uses lots of builders to build up immutable objects. To make an immutable object in Java, you need to make defensive copies of things like lists, sets, and maps, but doing that for every single one of these types in builders results in lots of copies. One option is to just use the lists et al contained in builders directly in the built objects, but that runs the risk of the builder being further mutated and thus mutating the object. Another option is to clear out the state of the builder and give "ownership" of lists et al to built objects, but that means builders can't easily be used to build up multiple objects (and while that rare, it's a use case that probably *should* work, and always has worked in Smithy).
BuilderRef creates the value if needed when the builder needs to mutate
the wrapped value (see get(). It creates an immutable copy of the value
when copy() is called, and an immutable "borrowed" reference to the
copied value is maintained in the reference. This borrowed copy can be queried
using peek(), but it can't be mutated. If the reference only has a
borrowed value but attempts to call get(), then a copy of the borrowed
value is created and returned from get().
| Modifier and Type | Method and Description |
|---|---|
void |
clear()
Removes any borrowed or owned values from the reference.
|
T |
copy()
Creates an immutable copy of
T. |
static <T> BuilderRef<java.util.List<T>> |
forList()
Creates a builder reference to a list.
|
static <K,V> BuilderRef<java.util.Map<K,V>> |
forOrderedMap()
Creates a builder reference to a ordered map.
|
static <T> BuilderRef<java.util.Set<T>> |
forOrderedSet()
Creates a builder reference to an ordered set.
|
static <K,V> BuilderRef<java.util.Map<K,V>> |
forUnorderedMap()
Creates a builder reference to an unordered map.
|
static <T> BuilderRef<java.util.Set<T>> |
forUnorderedSet()
Creates a builder reference to an unordered set.
|
static <T> software.amazon.smithy.utils.CopyOnWriteRef<T> |
fromBorrowed(T borrowedValue,
java.util.function.Function<T,T> copyFunction)
Creates a reference to a value that is borrowed, and a copy needs to be
created in order to get a mutable reference.
|
static <T> software.amazon.smithy.utils.CopyOnWriteRef<T> |
fromOwned(T owned)
Creates a reference to a value that is mutable and does not need to be
copied when
get() is called. |
T |
get()
Gets a mutable
T from the reference, creating one if needed. |
boolean |
hasValue()
Checks if the reference currently has a borrowed or owned value.
|
T |
peek()
Gets an immutable
T from the reference, reusing borrowed
values if possible, and creating owned values if needed. |
T copy()
T.
Subsequent calls to hasValue() may or may not return true
after this method is called.
boolean hasValue()
This method does not check if the contained value is considered empty. This method only returns true if the reference contains any kind of previously built value. This might be useful for builder methods that attempt to remove values from the contained object. If there is no contained object, then there's no need to create one just to remove a value from an empty container.
void clear()
Subsequent calls to hasValue() will return false after
this method is called.
static <K,V> BuilderRef<java.util.Map<K,V>> forUnorderedMap()
K - Type of key of the map.V - Type of value of the map.static <K,V> BuilderRef<java.util.Map<K,V>> forOrderedMap()
K - Type of key of the map.V - Type of value of the map.static <T> BuilderRef<java.util.List<T>> forList()
T - Type of value in the list.static <T> BuilderRef<java.util.Set<T>> forUnorderedSet()
T - Type of value in the set.static <T> BuilderRef<java.util.Set<T>> forOrderedSet()
T - Type of value in the set.T get()
T from the reference, creating one if needed.T value.T peek()
T from the reference, reusing borrowed
values if possible, and creating owned values if needed.
Attempting to mutate the provided value should fail at runtime, but even if it doesn't, doing so could inadvertently mutate previously built objects.
T value.static <T> software.amazon.smithy.utils.CopyOnWriteRef<T> fromBorrowed(T borrowedValue,
java.util.function.Function<T,T> copyFunction)
T - The type of value being referenced.borrowedValue - The value being referenced.copyFunction - The function used to copy the value when a mutable
reference is requested via get().static <T> software.amazon.smithy.utils.CopyOnWriteRef<T> fromOwned(T owned)
get() is called.T - Type of value being referenced.owned - Value to reference.