Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2004, 2011). All Rights Reserved.
   * 
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.dmt;

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 behaviour 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(java.lang.String) and isValidValue(org.osgi.service.dmt.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(org.osgi.service.dmt.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.

Version:
$Id: 3cc025f1da8c465b1d84cec5771f4bb0165f64ce $
 
 public interface MetaNode {

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.
 
 	int	CMD_ADD		= 0;

Constant for the DELETE access type. If can(int) returns true for this operation, the node can potentially be deleted.
 
 	int	CMD_DELETE	= 1;

Constant for the EXECUTE access type. If can(int) returns true for this operation, the node can potentially be executed.
 
 	int	CMD_EXECUTE	= 2;

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.
 
 	int	CMD_REPLACE	= 3;

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.
 
 	int	CMD_GET		= 4;

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.
	int	PERMANENT	= 0;

Constant for representing a dynamic node in the tree. This must be returned by getScope(). Dynamic nodes can be added and deleted.
	int	DYNAMIC		= 1;

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.
	int	AUTOMATIC	= 2;

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
	boolean can(int operation);

Check whether the node is a leaf node or an internal one.

Returns:
true if the node is a leaf node
	boolean isLeaf();

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
	int getScope();

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
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
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
Get the default value of this node if any.

Returns:
The default value or null if not defined
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(java.lang.String,java.lang.String) or DmtSession.createLeafNode(java.lang.String,org.osgi.service.dmt.DmtData,java.lang.String).

Returns:
the list of allowed MIME types for this node, starting with the default MIME type, or null if all types are allowed
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(org.osgi.service.dmt.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
	double getMax();

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(org.osgi.service.dmt.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
	double getMin();

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(org.osgi.service.dmt.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
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(org.osgi.service.dmt.DmtData) for checking the value, its behavior should be consistent with this method.

Returns:
the allowed format(s) of the node
	int getFormat();

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(org.osgi.service.dmt.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
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
	boolean isValidValue(DmtData value);

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(java.lang.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
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
	boolean isValidName(String name);

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
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
New to GrepCode? Check out our FAQ X