Web Dynpro API Documentation

com.sap.tc.webdynpro.progmodel.api
Interface IWDNodeInfo


public interface IWDNodeInfo

Represents the static structural aspect of a Node and its NodeElements at runtime keeping the meta data as defined at design time. Each Node has a reference to a NodeInfo holding its metadata.

The relevant meta data accessible through IWDNodeInfo are:

Node infos also provide a mean to dynamically add child nodes (there are different methods for unmapped, mapped and recursive nodes) or attributes (unmapped or mapped, several methods to add attributes automatically from external meta data). You cannot remove such nodes or attributes afterwards, you can only reset the whole context to its initial state via IWDContext.reset(boolean).

Version:
$Id: //tc/WebDynproRuntime/630_VAL_REL/src/_webdynpro_progmodel/java/com/sap/tc/webdynpro/progmodel/api/IWDNodeInfo.java#3 $

Method Summary
 IWDAttributeInfo addAttribute(java.lang.String name, IDataType dataType)
          Adds a new unmapped value attribute to the structure.
 IWDAttributeInfo addAttribute(java.lang.String name, java.lang.String dataType)
          Adds a new unmapped attribute to the structure.
 void addAttributesFromDataNode()
          Automatically adds all attributes from the data node.
 void addAttributesFromModelClassInfo()
          Automatically adds all attributes from the model metadata.
 IWDNodeInfo addChild(java.lang.String name, java.lang.Class elementClass, boolean singleton, boolean mandatory, boolean multiple, boolean mandatorySelection, boolean multipleSelection, boolean initializeLeadSelection, java.lang.Object dataType, IWDNodeCollectionSupplier supplier, IWDNodeCollectionDisposer disposer)
          Dynamically declares and adds an unmapped child NodeInfo with the given properties.
 IWDNodeInfo addChild(java.lang.String name, java.lang.Class elementClass, boolean singleton, boolean mandatory, boolean multiple, boolean mandatorySelection, boolean multipleSelection, boolean initializeLeadSelection, java.lang.String dataType, IWDNodeCollectionSupplier supplier, IWDNodeCollectionDisposer disposer)
          Dynamically declares and adds an unmapped child NodeInfo with the given properties.
 IWDAttributeInfo addMappedAttribute(java.lang.String name, java.lang.String mappedName)
          Adds a new mapped attribute to the structure.
 IWDNodeInfo addMappedChild(java.lang.String name, java.lang.Class elementClass, boolean singleton, boolean mandatorySelection, boolean multipleSelection, java.lang.String mappedPath, boolean selectionMapped, boolean initializeLeadSelection)
          Dynamically declares and adds a mapped child NodeInfo with the given properties.
 void addNotificationListener(IWDNodeNotificationListener listener)
          Adds a IWDNodeNotificationListener.
 IWDNodeInfo addRecursiveChild(IWDNodeInfo parent)
          Dynamically adds a recursive child NodeInfo having the same name as the referenced node.
 IWDNodeInfo addRecursiveChild(java.lang.String name, IWDNodeInfo parent)
          Dynamically adds a recursive child NodeInfo.
 IWDAttributeInfo addValueAttribute(java.lang.String name, java.lang.String dataType)
          Adds a new unmapped value attribute to the structure.
 IWDAttributeInfo getAttribute(java.lang.String name)
          Returns the AttributeInfo for the named attribute.
 IWDNodeInfo getChild(java.lang.String id)
          Returns the NodeInfo for the named child node.
 IWDContext getContext()
          Returns the IWDContext this node belongs to.
 IDataType getDataType()
          Returns the data type assigned to the Node.
 com.sap.tc.cmi.metadata.ICMIModelClassInfo getModelClassInfo()
          Returns the meta data for an ICMIGenericModelClass or null otherwise.
 java.lang.String getName()
          Returns the name as described in the meta data.
 IWDNodeInfo getParent()
          Returns the parent NodeInfo.
 java.lang.String getPathDescription()
          Returns the path to the NodeInfo in the form ContextName[.NodeName].NodeName.
 IStructure getStructureType()
          Returns the structured data type assigned to the Node.
 boolean isMandatory()
          Returns whether the described Node is guaranteed to have at least one element.
 boolean isMandatorySelection()
          Returns whether the selection of the described Node is guaranteed to have at least one element if the node is not empty.
 boolean isMultiple()
          Returns whether the described Node may contain more than one element.
 boolean isMultipleSelection()
          Returns whether the selection of the described Node may contain more than one element.
 boolean isSingleton()
          Returns whether the described Node is singleton relatively to its parent.
 java.util.Iterator iterateAttributes()
          Returns an Iterator to iterate over the attributes' IWDAttributeInfo.
 java.util.Iterator iterateChildren()
          Returns an Iterator to iterate over the child nodes' IWDNodeInfo.
 void removeNotificationListener(IWDNodeNotificationListener listener)
          Removes a IWDNodeNotificationListener.
 void setCollectionDisposer(IWDNodeCollectionDisposer disposer)
          Sets a new IWDNodeCollectionDisposer.
 void setCollectionSupplier(IWDNodeCollectionSupplier supplier)
          Sets a new IWDNodeCollectionSupplier.
 void setMapping(IWDContext mappedContext, java.lang.String mappedPath, boolean selectionMapped)
          Sets the mapping of a mapped node that has been declared before.
 void setMapping(IWDNodeInfo mappedNode, boolean selectionMapped)
          Sets the mapping of a mapped node that has been declared before.
 void setModelClassInfo(com.sap.tc.cmi.metadata.ICMIModelClassInfo info)
          Sets the meta data for an ICMIGenericModelClass.
 void setSupplyingRelationRole(java.lang.String supplyingRelationRole)
          Sets the supplyingRelationRole for an ICMIGenericModelClass.
 

Method Detail

getName

public java.lang.String getName()
Returns the name as described in the meta data.
Returns:
the name as described in the meta data

getContext

public IWDContext getContext()
Returns the IWDContext this node belongs to.
Returns:
the IWDContext this node belongs to.

isSingleton

public boolean isSingleton()
Returns whether the described Node is singleton relatively to its parent. A singleton Node exists exactly once per parent node and always keeps data relatively to the parent's lead selection. In contrast, a non-singleton node exists once for each element of the parent node and keeps data relatively to that element.

The root Node and independent Nodes (direct children of the root node) are always singletons.

Note: A singleton node always exists once per parent and keeps data relative to the parent's lead selection element. This is inconsistent if the parent node (or its lead selection) is empty. In this case, the node is empty whatever the cardinality tells and throws an exception if you try to add or bind elements.

Returns:
true if the described Node is singleton relatively to its parent or false otherwise.

isMandatory

public boolean isMandatory()
Returns whether the described Node is guaranteed to have at least one element. According to this property the Node may return null or throw a ContextException when asked for an element and having none.

This property together with isMultiple describes the element cardinality of the Node.

Note: A node may yet be empty, even if this property declares it mandatory. This can happen if the node is a singleton and does currently not have a valid parent element.

Returns:
true if the described Node is guaranteed to have at least one element or false otherwise.

isMultiple

public boolean isMultiple()
Returns whether the described Node may contain more than one element.

This property together with isMandatory describes the element cardinality of the Node.

Returns:
true if the described Node may contain more than one element or false otherwise.

isMandatorySelection

public boolean isMandatorySelection()
Returns whether the selection of the described Node is guaranteed to have at least one element if the node is not empty.

This property together with isMultipleSelection() describes the selection cardinality of the Node.

Note: A node's selection may yet be empty, even if this property declares it mandatory. This can happen if the node is empty.

Returns:
true if the selection of the described Node is guaranteed to have at least one element or false otherwise.

isMultipleSelection

public boolean isMultipleSelection()
Returns whether the selection of the described Node may contain more than one element.

This property together with isMandatorySelection() describes the selection cardinality of the Node.

Returns:
true if the selection of the described Node may contain more than one element or false otherwise.

getDataType

public IDataType getDataType()
Returns the data type assigned to the Node. Since this type always is a structure, it might be better to use getStructureType() directly.
Returns:
the data type assigned to the Node or null

getStructureType

public IStructure getStructureType()
Returns the structured data type assigned to the Node. This may be null. Then all attributes of the node must have a data type of their own.
Returns:
the structured data type assigned to the Node or null

getParent

public IWDNodeInfo getParent()
Returns the parent NodeInfo. Returns null for the root node.
Returns:
the parent NodeInfo

getChild

public IWDNodeInfo getChild(java.lang.String id)
Returns the NodeInfo for the named child node.
Parameters:
id - the ID of the child node
Returns:
the NodeInfo for the named child node or null if no child node of that name exists

getAttribute

public IWDAttributeInfo getAttribute(java.lang.String name)
Returns the AttributeInfo for the named attribute.
Parameters:
name - the name of the attribute
Returns:
the AttributeInfo for the named attribute or null if no attribute of that name exists

iterateAttributes

public java.util.Iterator iterateAttributes()
Returns an Iterator to iterate over the attributes' IWDAttributeInfo.
Returns:
an Iterator for the IWDAttributeInfo

iterateChildren

public java.util.Iterator iterateChildren()
Returns an Iterator to iterate over the child nodes' IWDNodeInfo.
Returns:
an Iterator for the IWDNodeInfo

getPathDescription

public java.lang.String getPathDescription()
Returns the path to the NodeInfo in the form ContextName[.NodeName].NodeName.
Returns:
the path.

addChild

public IWDNodeInfo addChild(java.lang.String name,
                            java.lang.Class elementClass,
                            boolean singleton,
                            boolean mandatory,
                            boolean multiple,
                            boolean mandatorySelection,
                            boolean multipleSelection,
                            boolean initializeLeadSelection,
                            java.lang.Object dataType,
                            IWDNodeCollectionSupplier supplier,
                            IWDNodeCollectionDisposer disposer)
Dynamically declares and adds an unmapped child NodeInfo with the given properties. The name must not be defined in this NodeInfo, neither for a node nor an attribute. Otherwise a ContextException will be thrown.

After a successful call to this method, an instance (or instances, in the case of non-singleton nodes) of the newly declared node can be retrieved with a call to IWDNode.getChildNode(String,int).

If dataType is not null, a structure of that name is searched in the dictionary and the returned NodeInfo automatically has attributes for all simple fields of that structure. Otherwise it does not contain any attribute yet and you must manually add attributes via addAttribute(String, String).

If you created a model node with element class ICMIModelClass meaning a special class described by a ICMIModelClassInfo, you can dynamically specify this class via

Parameters:
name - the name of the child NodeInfo. Must be unique all over the context. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
elementClass - The element class for a model node, null for a value node.
singleton - indicates, whether the described Node is singleton relatively to its parent
mandatory - indicates, whether the described Node is guaranteed to have at least one element
multiple - indicates, whether the described Node may contain more than one element
mandatorySelection - indicates, whether the selection of the described Node is guaranteed to have at least one element
multipleSelection - indicates, whether the selection of the described Node may contain more than one element.
initializeLeadSelection - true if this node's selection shall be initialized when the collection is initialized
dataType - the name of a data type, a data type (IStructure) or null.
supplier - A supply "function", see IWDNodeCollectionSupplier. May be null, in that case the elements remain empty and must be set manually during an event handler.
disposer - A dispose "function", see IWDNodeCollectionDisposer. May be null if no application code is needed before deletion of the node.
Returns:
the added NodeInfo
Throws:
ContextConfigurationException - when some of these properties are inconsistent (e. g. independent node is not singleton)

addChild

public IWDNodeInfo addChild(java.lang.String name,
                            java.lang.Class elementClass,
                            boolean singleton,
                            boolean mandatory,
                            boolean multiple,
                            boolean mandatorySelection,
                            boolean multipleSelection,
                            boolean initializeLeadSelection,
                            java.lang.String dataType,
                            IWDNodeCollectionSupplier supplier,
                            IWDNodeCollectionDisposer disposer)
Dynamically declares and adds an unmapped child NodeInfo with the given properties. Only existing for backward compatibility.
See Also:
addChild(String, Class, boolean, boolean, boolean, boolean, boolean, boolean, Object, IWDNodeCollectionSupplier, IWDNodeCollectionDisposer)

addMappedChild

public IWDNodeInfo addMappedChild(java.lang.String name,
                                  java.lang.Class elementClass,
                                  boolean singleton,
                                  boolean mandatorySelection,
                                  boolean multipleSelection,
                                  java.lang.String mappedPath,
                                  boolean selectionMapped,
                                  boolean initializeLeadSelection)
Dynamically declares and adds a mapped child NodeInfo with the given properties. The ID must not be defined in this NodeInfo, neither for a node nor an attribute. Otherwise an IllegalArgumentException will be thrown.

After a successful call to this method, an instance (or instances, in the case of non-singleton nodes) of the newly declared node can be retrieved with a call to IWDNode.getChildNode(String,int).

The properties mandatory, multiple and dataType cannot be defined, but are taken from the mapped node. The properties concerning the selection are only considered if the selection is not mapped.

mappedContext and mappedPath need not be defined here (i. e. may be null), you can set them later using setMapping(IWDContext, String, boolean).

The returned NodeInfo does not contain any attributes yet. You may add all attributes from the origin node via addAttributesFromDataNode().

Parameters:
name - the name of the child NodeInfo. Must be unique all over the context. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
elementClass - The element class for a model node, null for a value node.
singleton - indicates, whether the described Node is singleton relatively to its parent
mandatorySelection - indicates, whether the selection of the described Node is guaranteed to have at least one element
multipleSelection - indicates, whether the selection of the described Node may contain more than one element.
mappedPath - The path of the mapped node or null if you want to set the origin node later.
selectionMapped - indicates whether the selection is mapped
initializeLeadSelection - indicates whether the lead selection is to be set to 0 if the collection is filled
Returns:
the added NodeInfo
Throws:
ContextConfigurationException - when some of these properties are inconsistent (e. g. root node is not singleton)

setMapping

public void setMapping(IWDNodeInfo mappedNode,
                       boolean selectionMapped)
Sets the mapping of a mapped node that has been declared before. This is only allowed if no mapping had been given at declaration. (It has been created using addMappedChild(String, Class, boolean, boolean, boolean, String, boolean, boolean) with mappedPath set to null). In constrast to the immediate declaration, you can give the node instead of its name.

Parameters:
mappedNode - The NodeInfo of the mapped node.
selectionMapped - indicates whether the selection is mapped
Throws:
ContextConfigurationException - when some of these properties are inconsistent or if the NodeInfo already has a valid mapping

setMapping

public void setMapping(IWDContext mappedContext,
                       java.lang.String mappedPath,
                       boolean selectionMapped)
Sets the mapping of a mapped node that has been declared before. This is only allowed if no mapping had been given at declaration. (It has been created using addMappedChild(String, Class, boolean, boolean, boolean, String, boolean, boolean) with mappedPath set to null). In constrast to the immediate declaration, you can give the context instead of its name.

Parameters:
mappedContext - The context containing the mapped node.
mappedPath - The path of the mapped node.
selectionMapped - indicates whether the selection is mapped
Throws:
ContextConfigurationException - when some of these properties are inconsistent or if the NodeInfo already has a valid mapping

addRecursiveChild

public IWDNodeInfo addRecursiveChild(IWDNodeInfo parent)
Dynamically adds a recursive child NodeInfo having the same name as the referenced node. This is not supported in the metamodel and only possible dynamically.
Parameters:
parent - The parent node info where the recursion shall start. May be this.
Returns:
the added NodeInfo

addRecursiveChild

public IWDNodeInfo addRecursiveChild(java.lang.String name,
                                     IWDNodeInfo parent)
Dynamically adds a recursive child NodeInfo.
Parameters:
name - The name of this child. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
parent - The parent node info where the recursion shall start. May be this.
Returns:
the added NodeInfo

addAttribute

public IWDAttributeInfo addAttribute(java.lang.String name,
                                     java.lang.String dataType)
Adds a new unmapped attribute to the structure. At a value node, it is a value attribute. At a model node, it is a model attribute.
Parameters:
name - The name of the attribute within the node, must be unique. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
dataType - The name of the attribute's data type. It can be either a Java class (prefixed with "java:"), a type in the local Java DDIC (prefixed with "ddic:") or a type from a local dictionary (in that case the name is built "extern:name.of.logical.dictionary:name.of.type"). If you choose a Java class, no UI element can be bound to this attribute! A DDIC type may be either one that you defined within your application or one of the predefined types. Note, that the predefined types are in the package "com.sap.dictionary" at run time.
If the type is Model based, consider retrieving the type from the Model metadata and using addAttribute(String, IDataType), especially if it is a CMI model. Examples:
  • java:java.util.Map
  • ddic:com.sap.dictionary.string
  • extern:com.sap.test.types.Flight:com.sap.test.types.BAPIRET2
Returns:
The added attribute.

addValueAttribute

public IWDAttributeInfo addValueAttribute(java.lang.String name,
                                          java.lang.String dataType)
Adds a new unmapped value attribute to the structure.
Parameters:
name - The name of the attribute within the node, must be unique. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
dataType - The name of the attribute's data type. See addAttribute(String, String) for details.
Returns:
The added attribute.

addAttribute

public IWDAttributeInfo addAttribute(java.lang.String name,
                                     IDataType dataType)
Adds a new unmapped value attribute to the structure.
Parameters:
name - The name of the attribute within the node, must be unique. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
dataType - The already known data type, e.g. from a Model
Returns:
The added attribute.

addMappedAttribute

public IWDAttributeInfo addMappedAttribute(java.lang.String name,
                                           java.lang.String mappedName)
Adds a new mapped attribute to the structure.

Note, that there are three different ways of attribute mapping. One is working together with the node this attribute belongs to. In this case the mapped node has several elements pointing to elements of the origin node and the attribute is actually taken of this origin element.

The second one is mapped independently of the node. Then the mapping path is evaluated on each attribute access. The origin attribute is always accessed at the lead selection path. This is most probably only interesting for the context node, because even if a node contains several elements, the attribute value of each element is identical because they all map to the lead selection path and thus to the identical attribute. If the mapping path cannot be followed to its end because one of the nodes does not contain any element, a read access returns null (or 0 or false, depending on the attribute type) and a write access leads to a ContextException.

You distinguish between those two mappings via the mappedName. Node based mapping is achieved by simply giving the name of the attribute in the origin node without any path information. Pure attribute mapping is achieved by giving a complete path starting with the component name.

IWDNodeInfo chooses the second case if mappedPath contains a dot and the first case otherwise.

The third variant is a mixture of both. Technically it is the same as the second one. But as soon as the node containing this attribute is also mapped and the mapping path of the attribute is in the hierarchy below the mapping path of the node, the mapping at runtime starts at the element and only descends the rest of the path via the lead selection. See the example below.

Examples:

Parameters:
name - The name of the attribute within the node, must be unique. The name may only contain ascii letters, digits and underscore ('_'). It must start with a letter.
mappedName - The name of the attribute in the origin node
Returns:
The added attribute.

getModelClassInfo

public com.sap.tc.cmi.metadata.ICMIModelClassInfo getModelClassInfo()
Returns the meta data for an ICMIGenericModelClass or null otherwise.
Returns:
The model class info
See Also:
setModelClassInfo(ICMIModelClassInfo)

setModelClassInfo

public void setModelClassInfo(com.sap.tc.cmi.metadata.ICMIModelClassInfo info)
Sets the meta data for an ICMIGenericModelClass.
Parameters:
info - The model class info
See Also:
getModelClassInfo()

addAttributesFromModelClassInfo

public void addAttributesFromModelClassInfo()
Automatically adds all attributes from the model metadata. This only works if the elementClass is ICMIGenericModelClass and meta data have been set.
See Also:
ICMIGenericModelClass

addAttributesFromDataNode

public void addAttributesFromDataNode()
Automatically adds all attributes from the data node. This method can only be called on a mapped node.

setSupplyingRelationRole

public void setSupplyingRelationRole(java.lang.String supplyingRelationRole)
Sets the supplyingRelationRole for an ICMIGenericModelClass. The parent must be an ICMIGenericModelClass, too, and the role is the one leading from the parent node's class to this one.
Parameters:
supplyingRelationRole - The name of the supplyingRelationRole to set.
See Also:
ICMIGenericModelClass

setCollectionSupplier

public void setCollectionSupplier(IWDNodeCollectionSupplier supplier)
Sets a new IWDNodeCollectionSupplier. You can reset it by setting null.
Parameters:
supplier - The new collection supplier that will be used by every node based on this IWDNodeInfo to determine its collection.

setCollectionDisposer

public void setCollectionDisposer(IWDNodeCollectionDisposer disposer)
Sets a new IWDNodeCollectionDisposer. You can reset it by setting null.
Parameters:
disposer - The new collection disposer.

addNotificationListener

public void addNotificationListener(IWDNodeNotificationListener listener)
Adds a IWDNodeNotificationListener.
Parameters:
listener - the notification listener
See Also:
removeNotificationListener(IWDNodeNotificationListener)

removeNotificationListener

public void removeNotificationListener(IWDNodeNotificationListener listener)
Removes a IWDNodeNotificationListener.
Parameters:
listener - the notification listener
See Also:
addNotificationListener(IWDNodeNotificationListener)

Web Dynpro API Documentation

Copyright © 2004 SAP AG. Automatically generated Thu Mar 3 2005, 22:15