Package com.orchestranetworks.rest.serialization

# Class ContentHolder

java.lang.Object
com.orchestranetworks.rest.serialization.ContentHolder

Direct Known Subclasses:
  `ContentHolderForInput`, `ContentHolderForOutput`

public abstract class ContentHolder extends Object
Provides a facade to a table record in EBX®.

A `ContentHolder` should be placed in a Data Transfer Object (DTO) like the following:

       public class CityDTO {
        @Table(
           dataModel = "urn:ebx:module:cities-module:/WEB-INF/ebx/schemas/person.xsd",
           tablePath = "/root/Person")
         public ContentHolder person;
       }

This same DTO is usable as an argument of REST operations or as a response object. When used as an argument, the `ContentHolder` will be automatically created (an `ContentHolderForInput` instance) and supplied with the appropriate part of information coming from the HTTP request. When used as a response, a `ContentHolder` must be created through the `ContentHolderForOutput.createForRecord(com.onwbp.adaptation.Adaptation)` method, providing the wished table record, and returned.

A JSON format, for a given `ContentHolder`, can be described by using the `ExtendedOutput` annotation.
Two formats are available:

- the compact format: used by default when no annotation is present over the DTO field.
- the extended format: which has multiple levels of configuration using different options from `Include`. This format can be activated by adding a `ExtendedOutput` annotation to the DTO field.

Since:
  6.0.0
See Also:
  - `Table`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract ContentHolderForInput`
  `asContentHolderForInput()`
  Unwraps this `ContentHolder` to get a `ContentHolderForInput` if it has been instantiated as so.
  `abstract Object`
  `get(Path aPath)`
  Returns the value of the specified path.
  `final Object`
  `get(SchemaNode aNode)`
  Returns the value of the local absolute path of specified node.
  `final boolean`
  `getBoolean(Path aPath)`
  Returns the `boolean` value of the path specified, or `false` if no value is defined.
  `final Date`
  `getDate(Path aPath)`
  Returns the `Date` value of the path specified, or `null` if no value is defined.
  `final int`
  `getInt(Path aPath)`
  Returns the `int` value of the specified path, or `0` if no value is defined.
  `final <T> List<T>`
  `getList(Path aPath)`
  Returns the `List` value of the specified path, or an empty `ArrayList` if no value is defined.
  `final String`
  `getString(Path aPath)`
  Returns the `String` value of the specified path or `null` if no value is defined.
  `abstract boolean`
  `isForInput()`
  Returns `true` if this content holder is for input, `false` otherwise.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isForInput

    public abstract boolean isForInput()
    Returns `true` if this content holder is for input, `false` otherwise.

  - ### asContentHolderForInput

    public abstract ContentHolderForInput asContentHolderForInput()
    Unwraps this `ContentHolder` to get a `ContentHolderForInput` if it has been instantiated as so.
    Returns:
      the unwrapped `ContentHolderForInput`.
    Throws:
      `IllegalStateException` - if this `ContentHolder` has not been instantiated for input.

  - ### get

    public abstract Object get(Path aPath) throws PathAccessException
    Returns the value of the specified path.

    The resolution of the value is done according to the following rules:

    1. If the specified node is a function, always returns the evaluation of the function.
    2. If the target node specifies a specific `osd:inheritance` inheritance property, returns the locally defined value if a local value is defined (or "overwritten"/`null`); if no local value is defined, looks up the first locally defined value, according to the `osd:inheritance` properties.
    3. Otherwise, the default inheritance mechanism is used: if the value is locally defined, it is returned (it can be `null`); otherwise, looks up the first locally defined value according to the built-in child-to-parent relationship of datasets; if no locally defined value is found, the data model default value is returned (`null` is returned if the data model does not define a default value).

    Access and mapping rules:

    The access and mapping rules between XML Schema and Java are described in the chapter Mapping to Java.

    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure, or the specified node is above a terminal node.
    See Also:
      - `Adaptation`
      - `Adaptation.get(Path)`

  - ### get

    public final Object get(SchemaNode aNode)
    Returns the value of the local absolute path of specified node.
    Throws:
      `IllegalArgumentException` -
      - if the specified node does not belong to the data model of the current content.
      - if the current content is a table record and the specified node is not in the same table as the one of the current record.
      - if the current content is a dataset and the specified node is a table record node.
    See Also:
      - `get(Path)`
      - `SchemaNode.getPathInAdaptation()`

  - ### getString

    public final String getString(Path aPath) throws PathAccessException
    Returns the `String` value of the specified path or `null` if no value is defined.
    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if the value of the node is not a `String`, that is, the underlying type node is not an XML Schema `string` type.
    See Also:
      - `get(Path)`

  - ### getInt

    public final int getInt(Path aPath) throws PathAccessException
    Returns the `int` value of the specified path, or `0` if no value is defined.
    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if the value of the node is not an `int`, that is, the underlying type node is not an XML Schema `integer` type.
    See Also:
      - `get(Path)`

  - ### getBoolean

    public final boolean getBoolean(Path aPath) throws PathAccessException
    Returns the `boolean` value of the path specified, or `false` if no value is defined.
    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if the value of the node is not a `boolean`, that is, the underlying type node is not an XML Schema `boolean` type.
    See Also:
      - `get(Path)`

  - ### getDate

    public final Date getDate(Path aPath) throws PathAccessException
    Returns the `Date` value of the path specified, or `null` if no value is defined.

    The mapping rules of the types `xs:date` and `xs:time` have some particularities that are described in Mapping to Java.

    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if the value of the node is not a `Date`, that is, the underlying type node is not an XML Schema `date` type.
    See Also:
      - `get(Path)`

  - ### getList

    public final <T> List<T> getList(Path aPath) throws PathAccessException
    Returns the `List` value of the specified path, or an empty `ArrayList` if no value is defined.

    A node contains a `List` when, in the XML Schema, the corresponding node has been declared with `maxOccurs > 1`. The complete access and mapping rules between XML Schema and Java are described in the chapter Mapping to Java.

    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if the value of the node is not a `List`, that is, the underlying type node does not have `maxOccurs > 1` in XML Schema.
    See Also:
      - `get(Path)`