Package com.orchestranetworks.schema

# Class SchemaDocumentation

java.lang.Object
com.orchestranetworks.schema.SchemaDocumentation

public abstract class SchemaDocumentation extends Object
Abstract class for dynamically computing the label and description of a node in the context of a data model.

### Definition in the data model

The component must be declared under the element `xs:schema/xs:annotation/xs:appinfo`:

>      <xs:schema ...>
>       <xs:annotation>
>         <xs:appinfo>
>           <osd:documentation class="com.foo.MySchemaDocumentation"/>
>         </xs:appinfo>
>       </xs:annotation>
>       ...
>      </xs:schema ...>

where `com.foo.MySchemaDocumentation` is the fully qualified name of a class extending this abstract class. The declaration may also pass parameters, as follows:

>      <osd:documentation class="com.foo.MySchemaDocumentation">
>             <param1>...</param1>
>             <param2>...</param2>
>      </osd:documentation>

where `param1` and `param2` are JavaBean properties of `com.foo.MySchemaDocumentation` class.

For more information, see Specification of JavaBeans.

### Life cycle

1. When the data model is loaded:
   1. the specified class is instantiated through its default constructor and the setters of the JavaBean properties are called (based on the example above, `setParam1(...)` and `setParam2(...)`);
   2. the method `setup(SchemaDocumentationSetupContext)` is called for the new instance.
2. During the operational phase: the methods `getLabel(SchemaDocumentationContext)` and `getDescription(SchemaDocumentationContext)` are called each time a node from the data model is to be displayed in the user interface.

### Performance considerations

The methods `getLabel(SchemaDocumentationContext)` and `getDescription(SchemaDocumentationContext)` are called every time a node in the data model is displayed in the user interface, which means the code of these methods must be optimized as much as possible to avoid impacting performance. For example, given a table with N nodes, these methods will be called at least N times when accessing a table record in the user interface.

See Also:
  - `SchemaNode.getLabel(Session)`
  - `SchemaNode.getDescription(Session)`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SchemaDocumentation()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract String`
  `getDescription(SchemaDocumentationContext aContext)`
  Returns the localized description of the node in the specified context.
  `abstract String`
  `getLabel(SchemaDocumentationContext aContext)`
  Returns the localized label of the node in the specified context.
  `abstract void`
  `setup(SchemaDocumentationSetupContext aContext)`
  Checks and prepares this instance when the data model is loaded.

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

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

- ## Constructor Details

  - ### SchemaDocumentation

    public SchemaDocumentation()

- ## Method Details

  - ### getLabel

    public abstract String getLabel(SchemaDocumentationContext aContext)
    Returns the localized label of the node in the specified context. This method is invoked by `SchemaNode.getLabel(Session)` and `SchemaNode.getLabel(java.util.Locale)` to give the ability to dynamically compute a label depending on the session or the repository.

    If this method returns `null`, the displayed label will usually be the label statically defined in the data model, or the node name if no static label is defined.

    See Also:
      - `SchemaNode.getLabel(Session)`

  - ### getDescription

    public abstract String getDescription(SchemaDocumentationContext aContext)
    Returns the localized description of the node in the specified context. This method is invoked by `SchemaNode.getDescription(Session)` and `SchemaNode.getDescription(java.util.Locale)` to give the ability to dynamically compute a description depending on the session or the repository.

    If this method returns `null` the displayed description will usually be the description statically defined in the data model.

    See Also:
      - `SchemaNode.getDescription(Session)`

  - ### setup

    public abstract void setup(SchemaDocumentationSetupContext aContext)
    Checks and prepares this instance when the data model is loaded.

    Do note that during this step, all models may not be properly loaded. Thus, the repository should not be accessed during this step.