Supported operations - gkresic/commons-fields GitHub Wiki

Here we'll, on very high level, describe operations that HasFields and HasEntityFields interfaces add to objects implementing them.

For more detailed descriptions, see javadocs.

ref

Returns copy of this object stripped down to own 'reference' - all attributes managed by fields are cleared, but ID (if object has it) and other non-field-related attributes will remain.

Example usage: when passing HasEntityFields object to calling function to force callee to re-evaluate (via expand) its attributes.

getFields / setFields

Access initialized fields.

Example usage: inspect which fields object has initialized

hasFields / hasGraph

Checks if the object has all requested fields or complete field graph initialized.

Example usage: in toString methods, to calculate whether to include certain attribute or not

fieldGet / fieldSet

Helper methods for retrieving and initializing object attributes. fieldGet throws FieldUnavailableException when trying to read uninitialized attribute which greatly helps debugging wrongly initialized objects during development. On the other hand, fieldSet makes sure that the field describing the attribute being initialized is also properly set.

Example usage: in object's getters and setters (see example in Getting started )

getIfPresent / getOptional

Safe way of reading object's attributes for which we are not sure whether they are initialized or not. For uninitialized attributes getIfPresent defaults to null while getOptional returns empty Optional. Note that neither method is suitable for detecting "empty" attributes (ones that are initialized, but to null value).

Example usage: whenever accessing objects of unknown origin

clearFields

Clears (sets to null) object's attributes referenced by requested fields.

Example usage: clear volatile fields before extend-ing object to force their re-evaluation

clone / cloneAll / cloneFlat

Clones object with various degrees of depth.

Example usage: wherever you would need "regular" clone()

flatten

Strips sub-objects to references (objects with only IDs set).

Example usage: before storing object to any form of long-term storage when sub-objects can't (or doesn't have to) be kept updated (like in cache)

pull

Copies ("pulls") values from other instances of the same type.

Example usage: when detecting that object was modified (e.g. by listening for 'modify' event on some kind of event bus) one may pull changed attributes from modified instance to locally stored one

extend

Extending from another instance is a low level operation similar to pull, but extending using Fields(Async)Service is one of the cornerstone features of commons-fields which enables extending existing instance by requesting from backing store only attributes that existing object lacks in comparison to requested graph. In other words: it enables for any code segment which receives HasEntityFields object to ensure it has initialized all attributes which that segment needs by extend-ing received object with field graph needed to work with object in that part of application. This enables workflow in which objects are initially resolved with minimal set of attributes initialized (whatever is needed in that initial part of application that resolved object) and then to "grow" that one instance with additional attributes as the object travels from one function to another, each extend-ing it with attributes it needs.

Note that there is not necessary to check which attributes are initialized before extending object using service - extend will calculate if there's anything that needs extending and default to no-op if object already has complete field graph initialized.

There are both synchronous and asynchronous version of extend, using either synchronous FieldsService or asynchronous FieldsAsyncService.

Example usage: ensure all needed attributes are initialized after object is received as parameter into function

intersect

"Strips" object from any fields not covered by given graph.

Example usage: after object traveled through various parts of your app it may get extend-ed with additional attributes that are not suitable to return from current function (for example, to prevent internal attributes to leak in API response) - in that case, simply intersect object with "whitelisted" field graph to strip any extra attributes initialized