osgi.enroute.dto.api

Interface DTOs

All Known Implementing Classes:

DTOsProvider

public interface DTOs

This service provides a number of utilities to make it easy to work with DTOs. It contains a number of utility functions.

DTOs recognize primary fields (annotated with PrimaryKey). If none of the fields is annotated, all fields are primary.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	DTOs.Converter Converts an object to another type
static interface	DTOs.Dec<T> An interface to control the building of a JSON decoder.
static class	DTOs.Difference The details of a difference
static interface	DTOs.Enc This interface is a builder for encoding a DTO to JSON.
static class	DTOs.LiteralMap<K,V> A map that is to set inline like a builder.
static class	DTOs.Reason The reason for a difference.
static class	DTOs.Retrieve The DTO that contains the result of a path traversal.

Method Summary

Modifier and Type	Method and 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.
DTOs.Converter	convert(java.lang.Object source) Create a converter on an object.
<T> DTOs.Dec<T>	decoder(java.lang.Class<T> type) Return a JSON decoder that uses the type to control the parsing.
DTOs.Dec<?>	decoder(java.lang.reflect.Type type, java.io.InputStream source) Return a JSON decoder on an input stream that uses the type to control the parsing.
<T> DTOs.Dec<T>	decoder(TypeReference<T> type) Return a JSON decoder that uses the type to control the parsing.
<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.
DTOs.Enc	encoder(java.lang.Object source) Return encoder builder for JSON
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 .
DTOs.Retrieve	get(java.lang.Object dto, java.lang.String... path) Access a DTO with a path that consists of an array with segments.
DTOs.Retrieve	get(java.lang.Object dto, java.lang.String path) Access a DTO with a path.
<T> java.util.Comparator<T>	getComparator(java.lang.Class<T> dtoClass) Return a comparator who works on the primary fields of a DTO class.
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 fields.
boolean	isValidDTO(java.lang.Object o) Verify that the object is a DTO and has no cycles.
default <K,V> DTOs.LiteralMap<K,V>	map(K key, V value) Convenience method to create a map that returns itself when set so it can be used as a builder.
DTOs.Retrieve	set(java.lang.Object dto, java.lang.Object value, java.lang.String... path) Set a value in a DTO with a path that consists of an array with segments.
DTOs.Retrieve	set(java.lang.Object dto, java.lang.Object value, java.lang.String path) Access a DTO with a path.
<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.

Method Detail

convert

DTOs.Converter convert(java.lang.Object source)
                throws java.lang.Exception

Create a converter on an object.

Parameters:

source - The source to convert, null is allowed

Returns:

a converter for the given source

Throws:

java.lang.Exception

asMap

java.util.Map<java.lang.String,java.lang.Object> asMap(java.lang.Object dto)
                                                throws java.lang.Exception

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.

Throws:

java.lang.Exception

encoder

DTOs.Enc encoder(java.lang.Object source)
          throws java.lang.Exception

Return encoder builder for JSON

Parameters:

source - the object to encode

Returns:

a builder to control the encoding

Throws:

java.lang.Exception

decoder

<T> DTOs.Dec<T> decoder(java.lang.Class<T> type)
                 throws java.lang.Exception

Return a JSON decoder that uses the type to control the parsing.

Parameters:

type - the type that controls actual types for parsing

Returns:

a decoder

Throws:

java.lang.Exception

decoder

<T> DTOs.Dec<T> decoder(TypeReference<T> type)
                 throws java.lang.Exception

Return a JSON decoder that uses the type to control the parsing.

Parameters:

type - the type that controls actual types for parsing

Returns:

a decoder

Throws:

java.lang.Exception

decoder

DTOs.Dec<?> decoder(java.lang.reflect.Type type,
                    java.io.InputStream source)
             throws java.lang.Exception

Return a JSON decoder on an input stream that uses the type to control the parsing.

Parameters:

type - the type that controls actual types for parsing

source - the source of the JSON

Returns:

a decoder

Throws:

java.lang.Exception

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

DTOs.Retrieve get(java.lang.Object dto,
                  java.lang.String path)
           throws java.lang.Exception

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 null if not found.

Throws:

java.lang.Exception

get

DTOs.Retrieve get(java.lang.Object dto,
                  java.lang.String... path)
           throws java.lang.Exception

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 null if not found.

Throws:

java.lang.Exception

set

DTOs.Retrieve set(java.lang.Object dto,
                  java.lang.Object value,
                  java.lang.String path)
           throws java.lang.Exception

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. Maps and Lists are extended to hold the new value. This method does not support dots in the path. For paths with dots in the keys, use get(Object, String...).

Parameters:

dto - the root

value - the value to set

path - the path, should only contain dots as separators

Returns:

the value of the object or null if not found.

Throws:

java.lang.Exception

set

DTOs.Retrieve set(java.lang.Object dto,
                  java.lang.Object value,
                  java.lang.String... path)
           throws java.lang.Exception

Set a value in 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

value - the value to set

path - the path

Returns:

the value of the object or null if not found.

Throws:

java.lang.Exception

getComparator

<T> java.util.Comparator<T> getComparator(java.lang.Class<T> dtoClass)

Return a comparator who works on the primary fields of a DTO class.

Parameters:

dtoClass - the dto class

Returns:

a comparator for the given DTO or null if the dtoClass has no fields of a comparable type. If a field has public fields and these are comparable then they are also included recursively.

diff

java.util.List<DTOs.Difference> diff(java.lang.Object older,
                                     java.lang.Object newer)
                              throws java.lang.Exception

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.

Throws:

java.lang.Exception

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 fields.

Parameters:

dto - the object to check

Returns:

true if this object has public fields or extends DTO

isValidDTO

boolean isValidDTO(java.lang.Object o)
            throws java.lang.Exception

Verify that the object is a DTO and has no cycles.

Parameters:

o - The object to check for no cycles

Returns:

true if this DTO has no cycles and is further ok

Throws:

java.lang.Exception

shallowCopy

<T> T shallowCopy(T object)
           throws java.lang.Exception

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

Throws:

java.lang.Exception

deepCopy

<T> T deepCopy(T object)
        throws java.lang.Exception

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 immutable unless they implement Cloneable.

Parameters:

object - the object to deep copy

Returns:

the deep copied object

Throws:

java.lang.Exception

map

default <K,V> DTOs.LiteralMap<K,V> map(K key,
                                       V value)

Convenience method to create a map that returns itself when set so it can be used as a builder.

Parameters:

key - the initial key

value - the initial value

Returns:

the map