Package 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
    Description
    static final int
    AUTOMATIC
    Constant for representing an automatic node in the tree.
    static final int
    CMD_ADD
    Constant for the ADD access type.
    static final int
    CMD_DELETE
    Constant for the DELETE access type.
    static final int
    CMD_EXECUTE
    Constant for the EXECUTE access type.
    static final int
    CMD_GET
    Constant for the GET access type.
    static final int
    CMD_REPLACE
    Constant for the REPLACE access type.
    static final int
    DYNAMIC
    Constant for representing a dynamic node in the tree.
    static final int
    PERMANENT
    Constant for representing a PERMANENT node in the tree.

  • Method Summary

    Modifier and Type
    Method
    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.
    String
    getDescription()
    Get the explanation string associated with this node.
    Object
    getExtensionProperty(String key)
    Returns the value for the specified extension property key.
    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.
    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.
    String[]
    getRawFormatNames()
    Get the format names for any raw formats supported by the node.
    int
    getScope()
    Return the scope of the node.
    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(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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

  • Method Details

    • 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

      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

      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

      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

      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(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

      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

      Object getExtensionProperty(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:
      IllegalArgumentException - if the specified key is not supported by this MetaNode