Package software.amazon.smithy.utils

Interface BuilderRef<T>

  • Type Parameters:
    T - Type of value being created.
    public interface BuilderRef<T>
    Manages the creation, copying, and reuse of values created by builders.

    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().

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.
      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.

    • Method Detail

      • copy

        T copy()
        Creates an immutable copy of T.

        Subsequent calls to hasValue() may or may not return true after this method is called.

        Returns:
        Returns the copied immutable value.

      • hasValue

        boolean hasValue()
        Checks if the reference currently has a borrowed or owned value.

        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.

        Returns:
        Returns true if the reference contains a value of any kind.

      • clear

        void clear()
        Removes any borrowed or owned values from the reference.

        Subsequent calls to hasValue() will return false after this method is called.

      • forUnorderedMap

        static <K,​V> BuilderRef<java.util.Map<K,​V>> forUnorderedMap()
        Creates a builder reference to an unordered map.
        Type Parameters:
        K - Type of key of the map.
        V - Type of value of the map.
        Returns:
        Returns the created map.

      • forOrderedMap

        static <K,​V> BuilderRef<java.util.Map<K,​V>> forOrderedMap()
        Creates a builder reference to a ordered map.
        Type Parameters:
        K - Type of key of the map.
        V - Type of value of the map.
        Returns:
        Returns the created map.

      • forList

        static <T> BuilderRef<java.util.List<T>> forList()
        Creates a builder reference to a list.
        Type Parameters:
        T - Type of value in the list.
        Returns:
        Returns the created list.

      • forUnorderedSet

        static <T> BuilderRef<java.util.Set<T>> forUnorderedSet()
        Creates a builder reference to an unordered set.
        Type Parameters:
        T - Type of value in the set.
        Returns:
        Returns the created set.

      • forOrderedSet

        static <T> BuilderRef<java.util.Set<T>> forOrderedSet()
        Creates a builder reference to an ordered set.
        Type Parameters:
        T - Type of value in the set.
        Returns:
        Returns the created set.

      • get

        T get()
        Gets a mutable T from the reference, creating one if needed.
        Returns:
        Returns a mutable T value.

      • peek

        T peek()
        Gets an immutable 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.

        Returns:
        Returns an immutable peeked T value.