info.dmtree.MetaNode Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2004, 2008). 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 info.dmtree;
/**
* 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, {@link #isValidName} and {@link #isValidValue}. 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. {@link #getFormat} or {@link #getValidNames})
* can be substituted with the validating methods. For example,
* {@link #isValidValue} can be expected to check the format, minimum, maximum,
* etc. of a given value, making it unnecessary for the DmtAdmin to call
* {@link #getFormat()}, {@link #getMin()}, {@link #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 $Revision: 5673 $
*/
public interface MetaNode {
/**
* Constant for the ADD access type. If {@link #can(int)} returns
* true for this operation, this node can potentially be
* added to its parent. Nodes with {@link #PERMANENT} or {@link #AUTOMATIC}
* scope typically do not have this access type.
*/
int CMD_ADD = 0;
/**
* Constant for the DELETE access type. If {@link #can(int)} returns
* true for this operation, the node can potentially be
* deleted.
*/
int CMD_DELETE = 1;
/**
* Constant for the EXECUTE access type. If {@link #can(int)} returns
* true for this operation, the node can potentially be
* executed.
*/
int CMD_EXECUTE = 2;
/**
* Constant for the REPLACE access type. If {@link #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 {@link #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 {@link #getScope} if the node cannot be added, deleted or
* modified in any way through tree operations. Permanent nodes cannot have
* non-permanent nodes as parents.
*/
int PERMANENT = 0;
/**
* Constant for representing a dynamic node in the tree. This must be
* returned by {@link #getScope} for all nodes that are not permanent and
* are not created automatically by the management object.
*/
int DYNAMIC = 1;
/**
* Constant for representing an automatic node in the tree. This must be
* returned by {@link #getScope()} for all nodes that are created
* automatically by the management object. Automatic nodes represent a
* special case of dynamic nodes, so this scope should be mapped to
* {@link #DYNAMIC} when used in an OMA DM context.
*
* An automatic node is usually created instantly when its parent is
* created, but it is also valid if it only appears later, triggered by some
* other condition. The exact behaviour must be defined by the Management
* Object.
*/
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.
*
* @param operation One of the MetaNode.CMD_... constants.
* @return 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.
*
* @return true if the node is a leaf node
*/
boolean isLeaf();
/**
* Return the scope of the node. Valid values are
* {@link #PERMANENT MetaNode.PERMANENT}, {@link #DYNAMIC MetaNode.DYNAMIC}
* and {@link #AUTOMATIC 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.
*
* @return {@link #PERMANENT} for permanent nodes, {@link #AUTOMATIC} for
* nodes that are automatically created, and {@link #DYNAMIC}
* otherwise
*/
int getScope();
/**
* Get the explanation string associated with this node. Can be
* null if no description is provided for this node.
*
* @return node description string or null for no description
*/
String getDescription();
/**
* 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.
*
* @return The maximum allowed occurrence of this node type
*/
int getMaxOccurrence();
/**
* Check whether zero occurrence of this node is valid. If no meta-data is
* returned for a node, zero occurrences are allowed.
*
* @return true if zero occurrence of this node is valid
*/
boolean isZeroOccurrenceAllowed();
/**
* Get the default value of this node if any.
*
* @return The default value or null if not defined
*/
DmtData getDefault();
/**
* 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
* {@link DmtSession#setNodeType(String, String)} or
* {@link DmtSession#createLeafNode(String, DmtData, String)}.
*
* @return the list of allowed MIME types for this node, starting with the
* default MIME type, or null if all types are
* allowed
*/
String[] getMimeTypes();
/**
* 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 integer or float
* format. The returned limit has double type, as this can be
* used to denote both integer and float limits with full precision. The
* actual maximum should be the largest integer or float 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 {@link #isValidValue} for checking the value, its behaviour should
* be consistent with this method.
*
* @return the allowed maximum, or Double.MAX_VALUE if there
* is no upper limit defined or the node's format is not integer or
* float
*/
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 integer or float
* 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 or float number that is
* 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 {@link #isValidValue} for checking the value, its behaviour should
* be consistent with this method.
*
* @return the allowed minimum, or Double.MIN_VALUE if there
* is no lower limit defined or the node's format is not integer or
* float
*/
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 {@link #isValidValue} for checking the value, its behaviour should
* be consistent with this method.
*
* @return the valid values for this node, or null if not
* defined
*/
DmtData[] getValidValues();
/**
* Get the node's format, expressed in terms of type constants defined in
* {@link DmtData}. If there are multiple formats allowed for the node then
* the format constants are OR-ed. Interior nodes must have
* {@link 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 {@link #isValidValue} for checking the value, its behaviour should
* be consistent with this method.
*
* @return 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
* {@link #getFormat()} contains {@link DmtData#FORMAT_RAW_STRING} or
* {@link 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 {@link #isValidValue} for checking the value, its behaviour
* should be consistent with this method.
*
* @return the allowed format name(s) of raw data stored by the node, or
* null if raw formats are not supported
*/
String[] getRawFormatNames();
/**
* 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 {@link #getFormat}, {@link #getValidValues},
* {@link #getMin} and {@link #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.
*
* @param value the value to check for validity
* @return 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 {@link #isValidName} for checking the name, its behaviour should be
* consistent with this method.
*
* @return the valid values for this node name, or null if
* not defined
*/
String[] getValidNames();
/**
* 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
* {@link #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.
*
* @param name the node name to check for validity
* @return 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.
*
* @return the array of supported extension property keys
*/
String[] getExtensionPropertyKeys();
/**
* 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.
*
* @param key the key for the extension property
* @return the value of the requested property, cannot be null
* @throws IllegalArgumentException if the specified key is not supported by
* this MetaNode
*/
Object getExtensionProperty(String key);
}