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

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