Getting Entry Values

Entries are associated to a type, such as String, Boolean or List. An important feature is the automatic type conversion while retrieving an entry's value. This example retrieves the value of active as a boolean:

boolean isActive = document.booleanEntry("active").getNonNullVal();

There are two steps in retrieving a value:

• An entry method retrieves a reference to an entry
• A get* method retrieves the entry's value. This is done through a conversion, if necessary

In the example, the entry could've been stored either as a string or a Boolean object. If it's stored as a Boolean object, the value is returned as is. If it's stored as a string, the value is converted to Boolean when the get* method is invoked. Possible (case-insensitive) values include: "true", "false", "yes", "no", "on", "off", "0" and "1". To make the behaviour predictable, an invalid string value such as hello throws a conversion exception. This exception automatically indicates the entry's key, which makes troubleshooting easier.

Entry Interfaces

The following entry methods are available:

• Scalar
  • stringEntry: for a String
  • booleanEntry: for a Boolean
  • intEntry: for an Integer. Convenience methods for other numerical types are provided.
  • some others convenience methods
  • entry: for the conversion of other classes
• docEntry: an entry containing a nested document
• Collections, which are similar to the scalar version but end in plural - with an "s" at the end of the type name
  • stringsEntry: for a String collection
  • booleansEntry: for a Boolean collection
  • intsEntry: for an Integer collection
  • docsEntry: for a Document collection
  • some other convenience methods
  • collectionEntry: similar to entry. An overloaded version allows you to specify the class of collection members.

The entry and collectionEntry methods allow specifying a class for which a convenience class is not provided. The following types are supported:

• Enums
• Other classes, such as BigInteger, AtomicLong and File
• For any other class, including domain classes such as Product or Customer, you may retrieve the value with the cast done automatically for you. However, no conversion is performed. If you need to support other types, you may change the default conversion service. Refer to the advanced section, [Document Factories](Document Factories) for more details.

The following example retrieves the value of an enum:

import java.math.RoundingMode;
// ...
RoundingMode mode = document.entry("roundingMode", RoundingMode.class).getNonNullVal();

Similarly to the boolean example, if the entry value is already an instance of RoundingMode, it's returned as is. If the entry is a String, the library attempts to convert the value. Values such "CEILING" and "FLOOR" would return the equivalent RoundingMode instance. A value such as "NOT_SURE" would throw a conversion exception.

Note: Internally, wm-boost-data leverages conversion functionality from Spring.

Options for Value Retrieval

The entry interfaces contain multiple get value methods:

Method	Entry Doesn't Exist	Entry Contains Null Value	Entry Contains Non-Null Value
getVal	exception thrown	null returned	entry value
getNonNullVal	exception thrown	exception thrown	entry value
getValOrNull	null returned	null returned	entry value
getValOrNull with nullValHandling	null returned	depends on nullValHandling arg.	entry value
getValOrDefault	default value returned	default value returne	entry value
getValOrDefault with nullValHandling	default value returned	depends on nullValHandling arg.	entry value

The nullValHandling argument allows you to specify the behaviour when a null value is found. Options are: throwing an exception, returning null or returning the default value. When using getValOrNull and specifying to return the default value, null is considered the default value.

String Values

Due to the prevalence of string-valued entries, there are more getters available when you use document.stringEntry:

• getNonEmptyVal: like getNonNullVal but also ensures that the string values is not empty
• getNonBlankVal: like getNonNullVal but also ensures that the string values is not blank, i.e., doesn't only contain blanks characters, such as spaces

Combining isAssigned and getVal

When you want to optionally retrieve values, you may use a combination of isAssigned() and getVal(). For example, the following code is a snippet of a transformer that takes a string and returns a lower-case version. If the string is not provided, the pipeline is not modified. If the value is null, null is returned:

DocEntry<String> originalEntry = pipelineDoc.stringEntry("original");
if (originalEntry.isAssigned()) {
    String originalString = originalEntry.getVal();
    String lowerString = (originalString != null) ? originalString.toLowerCase() : null;

    pipelineDoc.stringEntry("lower").put(lowerString);
}

You could achieve the same result with a call to pipelineDoc.containsKey("original") instead of originalEntry.isAssigned(). However, the advantage of the approach in the example is that it's more refactor-safe. If you decided to rename the input variable original to something like originalValue, you'd only need to change the string value "original" once, even though it's referenced in two places.