Interface DTOs

  • All Known Implementing Classes:
    DTOsImpl

    @ProviderType
    public interface DTOs
    This interface provides a number of utilities to make it easy to work with DTOs. It contains a number of utility functions.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  DTOs.Difference
      The details of a difference
      static class  DTOs.Reason
      The reason for a difference.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static DTOs INSTANCE  
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.Map<java.lang.String,​java.lang.Object> asMap​(java.lang.Object dto)
      Return a partially read only Map object that maps directly to a DTO.
      <T> T deepCopy​(T object)
      Create a deep copy of a DTO.
      boolean deepEquals​(java.lang.Object a, java.lang.Object b)
      Check if two DTOs fields are equal.
      java.util.List<DTOs.Difference> diff​(java.lang.Object older, java.lang.Object newer)
      Return a list of paths where the two objects differ.
      boolean equals​(java.lang.Object a, java.lang.Object b)
      Check if two dtos fields are equal.
      java.lang.String escape​(java.lang.String unescaped)
      Escape a string to be used in a path.
      java.lang.String[] fromPathToSegments​(java.lang.String path)
      Takes a path with escaped '.'and '\' and then turns it into an array of unescaped keys
      java.lang.String fromSegmentsToPath​(java.lang.String[] segments)
      Takes a path with unescaped keys and turns it into a string path where the \ and .
      java.util.Optional<java.lang.Object> get​(java.lang.Object dto, java.lang.String path)
      Access a DTO with a path.
      java.util.Optional<java.lang.Object> get​(java.lang.Object dto, java.lang.String... path)
      Access a DTO with a path that consists of an array with segments.
      int hashCode​(java.lang.Object dto)
      Calculate a hash Code for the fields in this DTO.
      boolean isComplex​(java.lang.Object object)
      Return true if the give dto is complex (either Map, Collection, Array, or has public fields.
      boolean isDTO​(java.lang.Object dto)
      An object with public non-static non-synthetic fields.
      <T> T shallowCopy​(T object)
      Create a shallow copy of a DTO.
      java.lang.String toString​(java.lang.Object dto)
      Convert a DTO to a human readable string presentation.
      java.lang.String unescape​(java.lang.String escaped)
      Unescapes a string to be used in a path.
    • Field Detail

      • INSTANCE

        static final DTOs INSTANCE
    • Method Detail

      • asMap

        java.util.Map<java.lang.String,​java.lang.Object> asMap​(java.lang.Object dto)
        Return a partially read only Map object that maps directly to a DTO. I.e. changes are reflected in the DTO. If a field is a DTO, then this field will also become a Map.
        Parameters:
        dto - the DTO
        Returns:
        a Map where the keys map to the field names and the values to the field values. This map is not modifiable.
      • toString

        java.lang.String toString​(java.lang.Object dto)
        Convert a DTO to a human readable string presentation. This is primarily for debugging since the toString can truncate fields. This method must print all public fields, also non primary. Output formats can vary (e.g. YAML like) so the actual output should NOT be treated as standard.
        Parameters:
        dto - the dto to turn into a string
        Returns:
        a human readable string (not json!)
      • equals

        boolean equals​(java.lang.Object a,
                       java.lang.Object b)
        Check if two dtos fields are equal. This is shallow equal, that is the fields of this DTO are using the equals() instance method.
        Parameters:
        a - the first object
        b - the second object
        Returns:
        true if both are null or the DTO's primary fields are equal
      • deepEquals

        boolean deepEquals​(java.lang.Object a,
                           java.lang.Object b)
        Check if two DTOs fields are equal. This is deep equal, that is the fields of this DTO are using this method is the object at a field is a DTO, recursively.
        Parameters:
        a - the first object
        b - the second object
        Returns:
        true if both are null or the DTO's primary fields are equal
      • hashCode

        int hashCode​(java.lang.Object dto)
        Calculate a hash Code for the fields in this DTO. The dto must have at least one public field.
        Parameters:
        dto - the object to calculate the hashcode for, must not be null .
        Returns:
        a hashcode
      • get

        java.util.Optional<java.lang.Object> get​(java.lang.Object dto,
                                                 java.lang.String path)
        Access a DTO with a path. A path is a '.' separated string. Each part in the path is either a field name, key in a map, or an index in a list. If the path segments contain dots or backslashes, then these must be escaped
        Parameters:
        dto - the root
        path - the path, should only contain dots as separators
        Returns:
        the value of the object or empty if not found.
      • get

        java.util.Optional<java.lang.Object> get​(java.lang.Object dto,
                                                 java.lang.String... path)
        Access a DTO with a path that consists of an array with segments. Each segment in the path is either a field name, key in a map, or an index in a list.
        Parameters:
        dto - the root
        path - the path
        Returns:
        the value of the object or empty if not found.
      • diff

        java.util.List<DTOs.Difference> diff​(java.lang.Object older,
                                             java.lang.Object newer)
        Return a list of paths where the two objects differ. The objects must be of the same class.
        Parameters:
        older - the older object
        newer - the newer object
        Returns:
        A list of differences, if there is no difference, the list is empty.
      • fromPathToSegments

        java.lang.String[] fromPathToSegments​(java.lang.String path)
        Takes a path with escaped '.'and '\' and then turns it into an array of unescaped keys
        Parameters:
        path - the path with escaped \ and .
        Returns:
        a path array with unescaped segments
      • fromSegmentsToPath

        java.lang.String fromSegmentsToPath​(java.lang.String[] segments)
        Takes a path with unescaped keys and turns it into a string path where the \ and . are escaped.
        Parameters:
        segments - The unescaped segments of the path
        Returns:
        a string path where the . and \ are escaped.
      • escape

        java.lang.String escape​(java.lang.String unescaped)
        Escape a string to be used in a path. This will put a backslash ('\') in front of full stops ('.') and the backslash ('\').
        Parameters:
        unescaped - the string to be escaped
        Returns:
        a string where all '.' and '\' are escaped with a '\'.
      • unescape

        java.lang.String unescape​(java.lang.String escaped)
        Unescapes a string to be used in a path. This will remove a backslash ('\') in front of full stops ('.') and the backslash ('\').
        Parameters:
        escaped - the string to be unescaped
        Returns:
        a string where all '\.' and '\\' have the preceding backslash removed with a '\'.
      • isComplex

        boolean isComplex​(java.lang.Object object)
        Return true if the give dto is complex (either Map, Collection, Array, or has public fields.
        Parameters:
        object - The DTO to check
        Returns:
        true if this is a DTO with fields or length.
      • isDTO

        boolean isDTO​(java.lang.Object dto)
        An object with public non-static non-synthetic fields.
        Parameters:
        dto - the object to check
        Returns:
        true if this object has public fields or extends DTO
      • shallowCopy

        <T> T shallowCopy​(T object)
        Create a shallow copy of a DTO. This will create a new object of the same type and copy the public fields of the source to the new copy. It will not create a copy for these values.
        Parameters:
        object - the source object
        Returns:
        a shallow copy of object
      • deepCopy

        <T> T deepCopy​(T object)
        Create a deep copy of a DTO. This will copy the fields of the DTO. Copied values will also be created anew if they are complex (Map, Collection, DTO, or Array). Other objects are assumed to be immutable unless they implement Cloneable.
        Parameters:
        object - the object to deep copy
        Returns:
        the deep copied object