Package com.onwbp.adaptation

# Interface ReadContext

All Known Subinterfaces:
  `Adaptation`

public interface ReadContext
Provides a read-access facade to objects in a tree structure conforming to an underlying data model.

See data model.

### Accessing a node

Any node in the structure can be accessed using its path from the root node of the structure.

### Node value

If defined, the value of a node exists as:

- an instance of the corresponding XML Schema type, and
- an instance of the Java class that maps to the XML Schema type. It is a JavaBean, if the XML Schema type is a terminal "complex content".

See Also:
  - XML Schema part 1

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `get(Path aPath)`
  Returns the value of the specified node.
  `Object`
  `get(SchemaNode aNode)`
  Returns the value of the specified node.
  `boolean`
  `get_boolean(Path aPath)`
  Returns the `boolean` value of the node specified.
  `int`
  `get_int(Path aPath)`
  Returns the `int` value of the specified node.
  `Date`
  `getDate(Path aPath)`
  Returns the `Date` value of the node specified.
  `<T> List<T>`
  `getList(Path aPath)`
  Returns the `List` value of the specified node.
  `String`
  `getResourcePathInModule(Path aPath)`
  Returns the path to the resource that is contained in the specified node.
  `String`
  `getResourcePathWithModule(Path aPath)`
  Returns the path (including the path of the module) to the resource that is contained by the node specified.
  `String`
  `getString(Path aPath)`
  Returns the `String` value of the node specified.
  `AdaptationTable`
  `getTable(Path aPath)`
  Returns the table object at the specified path, never `null`.
  `boolean`
  `isEndUserDebug()`
  Returns `true` if debug mode is activated for the current module.
  `void`
  `toHtmlString(Writer aWriter)`
  For debugging purposes, adds an HTML representation to the writer specified.

- ## Method Details

  - ### get

    Object get(Path aPath) throws PathAccessException
    Returns the value of the specified node. Returns `null` if the value of the node is undefined.

    If this method is called on an `Adaptation`, a lookup mechanism is used to retrieve the value (see Inheritance and value resolution).

    ##### 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.
      `UnavailableContentError` - If the associated data model has errors, or when some inter-dataset links have errors in the context of the current dataspace.
    See Also:
      - `Adaptation.getValueWithoutResolution(Path)`

  - ### get

    Object get(SchemaNode aNode) throws PathAccessException
    Returns the value of the specified node.

    This method is equivalent to `get(aNode.getPathInAdaptation())`, but is slightly more efficient.

    Throws:
      `UnavailableContentError` - If the associated data model has errors or when some inter-dataset links have errors in the context of the current dataspace.
      `IllegalArgumentException` - if the specified node is `null` or does not belong to the same table as the current one if this instance is a record.
      `PathAccessException`

  - ### get_boolean

    boolean get_boolean(Path aPath) throws PathAccessException
    Returns the `boolean` value of the node specified. Returns `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)`

  - ### get_int

    int get_int(Path aPath) throws PathAccessException
    Returns the `int` value of the specified node. Returns `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`, i.e. the underlying type node is not an XML Schema `integer` type.
    See Also:
      - `get(Path)`

  - ### getDate

    Date getDate(Path aPath) throws PathAccessException
    Returns the `Date` value of the node specified. Returns `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

    <T> List<T> getList(Path aPath) throws PathAccessException
    Returns the `List` value of the specified node. Returns a new 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)`

  - ### getResourcePathInModule

    String getResourcePathInModule(Path aPath) throws PathAccessException
    Returns the path to the resource that is contained in the specified node. Returns `null` if no value is defined.

    The returned path can be passed as an argument to `ServletContext.getResource(java.lang.String)` methods: the path begins with a "/", after the specific path of the web application (non-inclusive).

    For example:

                 /www/images/logos/sample1.gif

    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 external resource, that is, the underlying type node is not an XML Schema `resource` type.
    See Also:
      - `get(Path)`

  - ### getResourcePathWithModule

    String getResourcePathWithModule(Path aPath) throws PathAccessException
    Returns the path (including the path of the module) to the resource that is contained by the node specified. Returns `null` if no value is defined.

    The path starts with a "/" and includes the web application's specific path.

    For example:

                 /myWebAppPublicPath/www/fr_FR/images/logos/sample1.gif

    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 external resource, that is, the underlying type node is not an XML Schema `resource` type.
    See Also:
      - `get(Path)`
      - `ServletContext.getResource(String)`

  - ### getString

    String getString(Path aPath) throws PathAccessException
    Returns the `String` value of the node specified. Returns `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)`

  - ### getTable

    AdaptationTable getTable(Path aPath) throws PathAccessException
    Returns the table object at the specified path, never `null`.
    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
      `ClassCastException` - if value of the node is not an instance of `AdaptationTable`, that is, the underlying type node is not declared as a table.
    See Also:
      - `get(Path)`

  - ### isEndUserDebug

    boolean isEndUserDebug()
    Returns `true` if debug mode is activated for the current module. This mode is configured using property `frontEnd.debugMode` in the file `module.properties` (default is defined in `ebx.properties`).

  - ### toHtmlString

    void toHtmlString(Writer aWriter)
    For debugging purposes, adds an HTML representation to the writer specified. The table hierarchically displays the values in this context.