Skip to content

Unit and Split Entries

Jump to bottom
inno-juanal edited this page Mar 9, 2017 · 8 revisions

Unit Entries

The common way to treat each document entry as a unit, with up to one entry associated to a given key. This is similar to how you'd store entries in a Java Map. All entries we've presented so far have this characteristic.

In this library, we refer to them as unit entries or, more precisely, unit entry references. There are two types unit entries: ItemEntry (where the value is a single item) and CollectionEntry (where the value is a collection of elements).

Consider the following example that shows information about M. Curie, a scientist that received the Nobel prize twice:

  • name: Marie Curie
  • birthYear: 1867
  • novelPrizeYears:
    • 1903
    • 1911

The document contains 3 entries: name, birthYear and novelPrizeYears.

novelPrizeYears contains a collection with 2 elements. It's still considered a unit entry because the key is associated to a single entry and the value in that entry is a single collection.

We could retrieve novelPrizeYears with code like this:

List<Integer> years = document.intsEntry("novelPrizeYears").getVal();

Note: get and put methods in webMethods' IDataUtil class treat entries as unit entries.

Split Entries

There certain types of documents that may contain more than one entry for a given key. Documents that result from parsing XML content with lists are one example.

In this library, a split entry has its value divided into multiple entries, all of them sharing the same key. Note that this structure resembles a multi-valued map (such as the one in Guava or the one in Apache Commons) more than a java.util.Map.

Let's consider the following document:

  • name: Marie Curie
  • birthYear: 1867
  • novelPrizeYear: 1903
  • novelPrizeYear: 1911

novelPrizeYear is a split entry. The entry values have been divided into two entries.

The following code retrieves its value as a list:

List<Integer> years = document.intsSplitEntry("novelPrizeYear").getValOrEmpty();

It would've been possible to call document.intsEntry("novelPrizeYear").getVal(), which would've returned only the the first year. Treating novelPrizeYear as a unit entry instead of a split entry in cases like this one is incorrect. Nevertheless, unit entries are appropriate for most other cases.

Clone this wiki locally