MetaNode
Date: 2016-06-25

org.osgi.service.dmt

## Interface MetaNode

-     public interface MetaNode

  The MetaNode contains meta data as standardized by OMA DM but extends it (without breaking the compatibility) to provide for better DMT data quality in an environment where many software components manipulate this data.

  The interface has several types of functions to describe the nodes in the DMT. Some methods can be used to retrieve standard OMA DM metadata such as access type, cardinality, default, etc., others are for data extensions such as valid names and values. In some cases the standard behavior has been extended, for example it is possible to provide several valid MIME types, or to differentiate between normal and automatic dynamic nodes.

  Most methods in this interface receive no input, just return information about some aspect of the node. However, there are two methods that behave differently, `isValidName(String)` and `isValidValue(DmtData)`. These validation methods are given a potential node name or value (respectively), and can decide whether it is valid for the given node. Passing the validation methods is a necessary condition for a name or value to be used, but it is not necessarily sufficient: the plugin may carry out more thorough (more expensive) checks when the node is actually created or set.

  If a `MetaNode` is available for a node, the DmtAdmin must use the information provided by it to filter out invalid requests on that node. However, not all methods on this interface are actually used for this purpose, as many of them (e.g. `getFormat()` or `getValidNames()`) can be substituted with the validating methods. For example, `isValidValue(DmtData)` can be expected to check the format, minimum, maximum, etc. of a given value, making it unnecessary for the DmtAdmin to call `getFormat()`, `getMin()`, `getMax()` etc. separately. It is indicated in the description of each method if the DmtAdmin does not enforce the constraints defined by it - such methods are only for external use, for example in user interfaces.

  Most of the methods of this class return `null` if a certain piece of meta information is not defined for the node or providing this information is not supported. Methods of this class do not throw exceptions.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `AUTOMATIC` Constant for representing an automatic node in the tree.
    `static int` | `CMD_ADD` Constant for the ADD access type.
    `static int` | `CMD_DELETE` Constant for the DELETE access type.
    `static int` | `CMD_EXECUTE` Constant for the EXECUTE access type.
    `static int` | `CMD_GET` Constant for the GET access type.
    `static int` | `CMD_REPLACE` Constant for the REPLACE access type.
    `static int` | `DYNAMIC` Constant for representing a dynamic node in the tree.
    `static int` | `PERMANENT` Constant for representing a `PERMANENT` node in the tree.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `can(int operation)` Check whether the given operation is valid for this node.
    `DmtData` | `getDefault()` Get the default value of this node if any.
    `java.lang.String` | `getDescription()` Get the explanation string associated with this node.
    `java.lang.Object` | `getExtensionProperty(java.lang.String key)` Returns the value for the specified extension property key.
    `java.lang.String[]` | `getExtensionPropertyKeys()` Returns the list of extension property keys, if the provider of this `MetaNode` provides proprietary extensions to node meta data.
    `int` | `getFormat()` Get the node's format, expressed in terms of type constants defined in `DmtData`.
    `double` | `getMax()` Get the maximum allowed value associated with a node of numeric format.
    `int` | `getMaxOccurrence()` Get the number of maximum occurrences of this type of nodes on the same level in the DMT.
    `java.lang.String[]` | `getMimeTypes()` Get the list of MIME types this node can hold.
    `double` | `getMin()` Get the minimum allowed value associated with a node of numeric format.
    `java.lang.String[]` | `getRawFormatNames()` Get the format names for any raw formats supported by the node.
    `int` | `getScope()` Return the scope of the node.
    `java.lang.String[]` | `getValidNames()` Return an array of Strings if valid names are defined for the node, or `null` if no valid name list is defined or if this piece of meta info is not supported.
    `DmtData[]` | `getValidValues()` Return an array of DmtData objects if valid values are defined for the node, or `null` otherwise.
    `boolean` | `isLeaf()` Check whether the node is a leaf node or an internal one.
    `boolean` | `isValidName(java.lang.String name)` Checks whether the given name is a valid name for this node.
    `boolean` | `isValidValue(DmtData value)` Checks whether the given value is valid for this node.
    `boolean` | `isZeroOccurrenceAllowed()` Check whether zero occurrence of this node is valid.

- - ### Field Detail

    - #### CMD_ADD

          static final int CMD_ADD

      Constant for the ADD access type. If `can(int)` returns `true` for this operation, this node can potentially be added to its parent. Nodes with `PERMANENT` or `AUTOMATIC` scope typically do not have this access type.
      See Also:
        Constant Field Values

    - #### CMD_DELETE

          static final int CMD_DELETE

      Constant for the DELETE access type. If `can(int)` returns `true` for this operation, the node can potentially be deleted.
      See Also:
        Constant Field Values

    - #### CMD_EXECUTE

          static final int CMD_EXECUTE

      Constant for the EXECUTE access type. If `can(int)` returns `true` for this operation, the node can potentially be executed.
      See Also:
        Constant Field Values

    - #### CMD_REPLACE

          static final int CMD_REPLACE

      Constant for the REPLACE access type. If `can(int)` returns `true` for this operation, the value and other properties of the node can potentially be modified.
      See Also:
        Constant Field Values

    - #### CMD_GET

          static final int CMD_GET

      Constant for the GET access type. If `can(int)` returns `true` for this operation, the value, the list of child nodes (in case of interior nodes) and the properties of the node can potentially be retrieved.
      See Also:
        Constant Field Values

    - #### PERMANENT

          static final int PERMANENT

      Constant for representing a `PERMANENT` node in the tree. This must be returned by `getScope()` if the node cannot be added, deleted or modified in any way through tree operations. `PERMANENT` nodes in general map to the roots of Plugins.
      See Also:
        Constant Field Values

    - #### DYNAMIC

          static final int DYNAMIC

      Constant for representing a dynamic node in the tree. This must be returned by `getScope()`. Dynamic nodes can be added and deleted.
      See Also:
        Constant Field Values

    - #### AUTOMATIC

          static final int AUTOMATIC

      Constant for representing an automatic node in the tree. This must be returned by `getScope()`. `AUTOMATIC` nodes are part of the life cycle of their parent node, they usually describe attributes/properties of the parent.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### can

          boolean can(int operation)

      Check whether the given operation is valid for this node. If no meta-data is provided for a node, all operations are valid.
      Parameters:
        `operation` - One of the `MetaNode.CMD_...` constants.
      Returns:
        `false` if the operation is not valid for this node or the operation code is not one of the allowed constants

    - #### isLeaf

          boolean isLeaf()

      Check whether the node is a leaf node or an internal one.
      Returns:
        `true` if the node is a leaf node

    - #### getScope

          int getScope()

      Return the scope of the node. Valid values are `MetaNode.PERMANENT`, `MetaNode.DYNAMIC` and `MetaNode.AUTOMATIC`. Note that a permanent node is not the same as a node where the DELETE operation is not allowed. Permanent nodes never can be deleted, whereas a non-deletable node can disappear in a recursive DELETE operation issued on one of its parents. If no meta-data is provided for a node, it can be assumed to be a dynamic node.
      Returns:
        `PERMANENT` for permanent nodes, `AUTOMATIC` for nodes that are automatically created, and `DYNAMIC` otherwise

    - #### getDescription

          java.lang.String getDescription()

      Get the explanation string associated with this node. Can be `null` if no description is provided for this node.
      Returns:
        node description string or `null` for no description

    - #### getMaxOccurrence

          int getMaxOccurrence()

      Get the number of maximum occurrences of this type of nodes on the same level in the DMT. Returns `Integer.MAX_VALUE` if there is no upper limit. Note that if the occurrence is greater than 1 then this node can not have siblings with different metadata. In other words, if different types of nodes coexist on the same level, their occurrence can not be greater than 1. If no meta-data is provided for a node, there is no upper limit on the number of occurrences.
      Returns:
        The maximum allowed occurrence of this node type

    - #### isZeroOccurrenceAllowed

          boolean isZeroOccurrenceAllowed()

      Check whether zero occurrence of this node is valid. If no meta-data is returned for a node, zero occurrences are allowed.
      Returns:
        `true` if zero occurrence of this node is valid

    - #### getDefault

          DmtData getDefault()

      Get the default value of this node if any.
      Returns:
        The default value or `null` if not defined

    - #### getMimeTypes

          java.lang.String[] getMimeTypes()

      Get the list of MIME types this node can hold. The first element of the returned list must be the default MIME type.

      All MIME types are considered valid if no meta-data is provided for a node or if `null` is returned by this method. In this case the default MIME type cannot be retrieved from the meta-data, but the node may still have a default. This hidden default (if it exists) can be utilized by passing `null` as the type parameter of `DmtSession.setNodeType(String, String)` or `DmtSession.createLeafNode(String, DmtData, String)`.

      Returns:
        the list of allowed MIME types for this node, starting with the default MIME type, or `null` if all types are allowed

    - #### getMax

          double getMax()

      Get the maximum allowed value associated with a node of numeric format. If no meta-data is provided for a node, there is no upper limit to its value. This method is only meaningful if the node has one of the numeric formats: integer, float, or long format. The returned limit has `double` type, as this can be used to denote all numeric limits with full precision. The actual maximum should be the largest integer, float or long number that does not exceed the returned value.

      The information returned by this method is not checked by DmtAdmin, it is only for external use, for example in user interfaces. DmtAdmin only calls `isValidValue(DmtData)` for checking the value, its behavior should be consistent with this method.

      Returns:
        the allowed maximum, or `Double.MAX_VALUE` if there is no upper limit defined or the node's format is not one of the numeric formats integer, float, or long

    - #### getMin

          double getMin()

      Get the minimum allowed value associated with a node of numeric format. If no meta-data is provided for a node, there is no lower limit to its value. This method is only meaningful if the node has one of the numeric formats: integer, float, or long format. The returned limit has `double` type, as this can be used to denote both integer and float limits with full precision. The actual minimum should be the smallest integer, float or long value that is equal or larger than the returned value.

      The information returned by this method is not checked by DmtAdmin, it is only for external use, for example in user interfaces. DmtAdmin only calls `isValidValue(DmtData)` for checking the value, its behavior should be consistent with this method.

      Returns:
        the allowed minimum, or `Double.MIN_VALUE` if there is no lower limit defined or the node's format is not one of the numeric formats integer, float, or long

    - #### getValidValues

          DmtData[] getValidValues()

      Return an array of DmtData objects if valid values are defined for the node, or `null` otherwise. If no meta-data is provided for a node, all values are considered valid.

      The information returned by this method is not checked by DmtAdmin, it is only for external use, for example in user interfaces. DmtAdmin only calls `isValidValue(DmtData)` for checking the value, its behavior should be consistent with this method.

      Returns:
        the valid values for this node, or `null` if not defined

    - #### getFormat

          int getFormat()

      Get the node's format, expressed in terms of type constants defined in `DmtData`. If there are multiple formats allowed for the node then the format constants are OR-ed. Interior nodes must have `DmtData.FORMAT_NODE` format, and this code must not be returned for leaf nodes. If no meta-data is provided for a node, all applicable formats are considered valid (with the above constraints regarding interior and leaf nodes).

      Note that the 'format' term is a legacy from OMA DM, it is more customary to think of this as 'type'.

      The formats returned by this method are not checked by DmtAdmin, they are only for external use, for example in user interfaces. DmtAdmin only calls `isValidValue(DmtData)` for checking the value, its behavior should be consistent with this method.

      Returns:
        the allowed format(s) of the node

    - #### getRawFormatNames

          java.lang.String[] getRawFormatNames()

      Get the format names for any raw formats supported by the node. This method is only meaningful if the list of supported formats returned by `getFormat()` contains `DmtData.FORMAT_RAW_STRING` or `DmtData.FORMAT_RAW_BINARY`: it specifies precisely which raw format(s) are actually supported. If the node cannot contain data in one of the raw types, this method must return `null`.

      The format names returned by this method are not checked by DmtAdmin, they are only for external use, for example in user interfaces. DmtAdmin only calls `isValidValue(DmtData)` for checking the value, its behavior should be consistent with this method.

      Returns:
        the allowed format name(s) of raw data stored by the node, or `null` if raw formats are not supported

    - #### isValidValue

          boolean isValidValue(DmtData value)

      Checks whether the given value is valid for this node. This method can be used to ensure that the value has the correct format and range, that it is well formed, etc. This method should be consistent with the constraints defined by the `getFormat()`, `getValidValues()`, `getMin()` and `getMax()` methods (if applicable), as the Dmt Admin only calls this method for value validation.

      This method may return `true` even if not all aspects of the value have been checked, expensive operations (for example those that require external resources) need not be performed here. The actual value setting method may still indicate that the value is invalid.

      Parameters:
        `value` - the value to check for validity
      Returns:
        `false` if the specified value is found to be invalid for the node described by this meta-node, `true` otherwise

    - #### getValidNames

          java.lang.String[] getValidNames()

      Return an array of Strings if valid names are defined for the node, or `null` if no valid name list is defined or if this piece of meta info is not supported. If no meta-data is provided for a node, all names are considered valid.

      The information returned by this method is not checked by DmtAdmin, it is only for external use, for example in user interfaces. DmtAdmin only calls `isValidName(String)` for checking the name, its behavior should be consistent with this method.

      Returns:
        the valid values for this node name, or `null` if not defined

    - #### isValidName

          boolean isValidName(java.lang.String name)

      Checks whether the given name is a valid name for this node. This method can be used for example to ensure that the node name is always one of a predefined set of valid names, or that it matches a specific pattern. This method should be consistent with the values returned by `getValidNames()` (if any), the DmtAdmin only calls this method for name validation.

      This method may return `true` even if not all aspects of the name have been checked, expensive operations (for example those that require external resources) need not be performed here. The actual node creation may still indicate that the node name is invalid.

      Parameters:
        `name` - the node name to check for validity
      Returns:
        `false` if the specified name is found to be invalid for the node described by this meta-node, `true` otherwise

    - #### getExtensionPropertyKeys

          java.lang.String[] getExtensionPropertyKeys()

      Returns the list of extension property keys, if the provider of this `MetaNode` provides proprietary extensions to node meta data. The method returns `null` if the node doesn't provide such extensions.
      Returns:
        the array of supported extension property keys

    - #### getExtensionProperty

          java.lang.Object getExtensionProperty(java.lang.String key)

      Returns the value for the specified extension property key. This method only works if the provider of this `MetaNode` provides proprietary extensions to node meta data.
      Parameters:
        `key` - the key for the extension property
      Returns:
        the value of the requested property, cannot be `null`
      Throws:
        `java.lang.IllegalArgumentException` - if the specified key is not supported by this `MetaNode`