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

public interface IWDNode

Application Interface implemented by context nodes. While this class is used when programming dynamically, more convenient, typed subinterfaces of this interface are generated for context nodes whose structure is declared within the Web Dynpro Development Workbench.

Each node holds a list of elements. If the list is not empty, one of the elements is the "current" element, the "lead selection". The lead selection can be changed by navigation (relative or absolute). Usually this list is held exclusively by the node and can only be manipulated via the node. You can share an ICMIObservableList with the node by binding such a list to it. See bind(Collection) for details.

The node can be filled by binding elements to it. You can add, remove, move or swap elements. Its content can be invalidated. Then, if it has a supply function (either generated or via IWDNodeCollectionSupplier), it will call this function upon further access to refill itself.

A node may have different cardinalities. At design time they are 0..1, 1..1, 0..n and 1..n. At run time there are the flags mandatory (minimum cardinality is 1) and multiple (maximum cardinality greater than 1).

If mandatory is false, the node is initially empty. Then all UI elements bound to this node are empty and read only. If mandatory is true, the node is guaranteed to be non-empty upon access. This is very convenient for value nodes, but take care with model nodes. Because model node elements require a model instance, the framework can not automatically create an element to achieve this guarantee (without a supply function) and throws an exception if the node is empty and you try to access an element.

If multiple is false you may only bind single element collections to the node. (You may find java.util.Collections.singletonList(Object) convenient in this case.)

Besides the lead selection, the node also has a (multiple) selection. You can add or remove elements from this selection via setSelected(int, boolean). You can query this selection via isMultiSelected(int).

You can dynamically add value attributes to a node by changing its metadata. You can add unmapped and mapped attributes.

A node may have child nodes. These child nodes are automatically maintained by the framework. Nevertheless you can dynamically add nodes by changing the metadata. See the several addChild methods in IWDNodeInfo.

Access to child nodes is possible through getChildNode(String, int).

For many of these methods, the Web Dynpro generator generates special type safe variants.

Version:

$Id: //tc/WebDynproRuntime/630_VAL_REL/src/_webdynpro_progmodel/java/com/sap/tc/webdynpro/progmodel/api/IWDNode.java#4 $

Field Summary

static int	LEAD_SELECTION Constant value indicating the use of the lead selection in some methods.
static int	NO_SELECTION Constant value indicating that no element is selected.

Method Summary

void	addElement(int index, IWDNodeElement element) Adds an element to the node collection at the given index.
void	addElement(IWDNodeElement element) Adds an element to the node collection.
void	bind(java.util.Collection items) With this method you can bind a new Collection to the Node.
void	clearSelection() Clears the Node's multiple selection; does not change the lead selection.
IWDNodeElement	createElement() Creates a new node element of the type used for this value node.
IWDNodeElement	createElement(java.lang.Object reference) Creates a new node element of the type used for this model node.
IWDNode	getChildNode(java.lang.String name, int index) Returns the child Node with the given name at the given index.
IWDContext	getContext() Returns the context, this node belongs to.
IWDNodeElement	getCurrentElement() Returns the current element (at the lead selection) or null if no element is selected.
IWDNodeElement	getElementAt(int index) Returns the element at the given index.
int	getLeadSelection() Returns the index of the lead selection or NO_SELECTION if the element list is empty.
IWDNodeInfo	getNodeInfo() Returns the meta data for this node.
IWDNodeElement	getParentElement() Returns the parent element.
void	invalidate() With this method the node will be invalidated.
boolean	isEmpty() Returns whether the element list is empty.
boolean	isMultiSelected(int index) Returns whether the element at the given index is selected.
boolean	isSelected(int index) Deprecated. This method always returns true if the lead selection is positioned at index. As a consequence it is not possible to determine if the element at the lead selection also is selected via multiple selection. Instead, compare index with getLeadSelection() or use isMultiSelected(int) depending on your needs. This method may be withdrawn with the first new NetWeaver release in 2006.
void	moveElement(int from, int to) Moves an element to another position within the node collection.
void	moveFirst() Moves the lead selection to the first element in the node collection, if the list is not empty.
void	moveLast() Moves the lead selection to the last element in the node collection, if the list is not empty.
IWDNodeElement	moveNext() Moves the lead selection to the next element in the node collection, if such an element exists.
IWDNodeElement	movePrevious() Moves the lead selection to the previous element in the node collection, if such an element exists.
void	moveTo(int index) Moves the lead selection to the element with the given index.
void	notifyAllMappedNodes(java.lang.Object payload) Notifies all (directly and indirectly) mapped Nodes.
boolean	removeElement(IWDNodeElement element) Removes an element from the node collection.
void	setLeadSelection(int index) Sets the lead selection to the given index.
void	setSelected(int index, boolean selected) Selects or unselects the element at the given index.
void	setTreeSelection(IWDNodeElement element) Sets the lead selections of the whole node's subtree such that the path to the given element is selected and all other nodes are unselected.
int	size() Returns the size of the element list.
void	sortElements(java.util.Comparator comparator) Sorts the elements according to the Comparator.
void	swapElements(int index1, int index2) Swaps two elements within the node collection.
boolean	validate() With this method the node will be validated.

Field Detail

NO_SELECTION

public static final int NO_SELECTION

Constant value indicating that no element is selected.

LEAD_SELECTION

public static final int LEAD_SELECTION

Constant value indicating the use of the lead selection in some methods.

Method Detail

getContext

public IWDContext getContext()

Returns the context, this node belongs to.

Returns:

the context, this node belongs to

bind

public void bind(java.util.Collection items)

With this method you can bind a new Collection to the Node. It is allowed to bind null; in that case the node is valid containing an empty list.

This collection may contain elements for this node, (in case of mapping) elements of any origin node of this or (for a model node) instances of the model class.

The node internally creates a List of NodeElements, either being the ones supplied or wrappers thereof. The collection itself is thrown away. The order of the elements in the List is the order of the Collection's Iterator.

The Collection must obey the cardinalities of the Node. It is not allowed to bind an empty collection to a Node of cardinality 1..1 or 1..n, and it is not allowed to bind more than one item to a Node of cardinality 0..1 or 1..1.

If the Collection is an ICMIObservableList, the Node behaves differently. In that case, the list is passed to the origin node (in case of mapped nodes). This node does not copy the elements and throw the list away, but uses the list itself to store the elements.

An ICMIObservableList is not accessed at all during bind, if cardinality is 0..n and the selection cardinality is is 0..1 or 0..n. Otherwise, isEmpty() or even size() (cardinality 0..1 or 1..1) is called.

Take care: If a node has an ICMIObservableList attached, modifications to the node (addElement(IWDNodeElement), removeElement(IWDNodeElement), sortElements(Comparator)...) change the list and vice versa!

Warning: Never use bind if the node has a supplying relation role. You effectively get the node and the underlying model out of sync. It is a bad practice to use bind outside the supply function, if there is one, too. Future releases will probably throw an exception in such cases, but old application will still be allowed to for compatibility reasons.

Parameters:

items - the collection of items, which should be bound to this node

Throws:

ContextException - if

• any of the items do not match the node
• the node is singleton and the parent node is empty or does not have a valid lead selection.

See Also:

ICMIObservableList

invalidate

public void invalidate()

With this method the node will be invalidated. It clears its element list and calls the supply function again when asked for an element.

Warning:This method is not allowed within a supply function.

Throws:

ContextException - when called from within a supply function.

validate

public boolean validate()

With this method the node will be validated. In detail, the method does one of the following (in the given order):

• If the node is valid, nothing is done
• If there is a supplying relation role or a supply function, it will be called.
• If the cardinality is 1..1 or 1..n, one empty element will be added.
• An empty collection is bound.

Returns:

true, if the node has been validated, i.e. has been invalid before

getNodeInfo

public IWDNodeInfo getNodeInfo()

Returns the meta data for this node.

Returns:

the meta data for this node

getElementAt

public IWDNodeElement getElementAt(int index)

Returns the element at the given index.

Parameters:

index - the index of the element

Returns:

the element at the given index

Throws:

IndexOutOfBoundsException - if the node does not have such an element.

size

public int size()

Returns the size of the element list.

Returns:

the size of the element list

isEmpty

public boolean isEmpty()

Returns whether the element list is empty.

Returns:

true if the list is empty false otherwise.

getLeadSelection

public int getLeadSelection()

Returns the index of the lead selection or NO_SELECTION if the element list is empty.

Returns:

the index of the lead selection or NO_SELECTION if the element list is empty.

See Also:

setLeadSelection(int)

setLeadSelection

public void setLeadSelection(int index)

Sets the lead selection to the given index. It may be called with NO_SELECTION to reset (clear) the lead selection.

Parameters:

index - the index of the element

Throws:

ContextException - if caller tries to reset the selection, but selection is mandatory

IndexOutOfBoundsException - if the given index is not within the element list

See Also:

getLeadSelection()

clearSelection

public void clearSelection()

Clears the Node's multiple selection; does not change the lead selection.

isSelected

public boolean isSelected(int index)

Deprecated. This method always returns true if the lead selection is positioned at index. As a consequence it is not possible to determine if the element at the lead selection also is selected via multiple selection. Instead, compare index with getLeadSelection() or use isMultiSelected(int) depending on your needs. This method may be withdrawn with the first new NetWeaver release in 2006.

Returns whether the element at the given index is selected.

Parameters:

index - the index of the element

Returns:

true if the element is selected.

isMultiSelected

public boolean isMultiSelected(int index)

Returns whether the element at the given index is selected. Does not look at the lead selection.

Parameters:

index - the index of the element

Returns:

true if the element is selected.

setSelected

public void setSelected(int index,
                        boolean selected)

Selects or unselects the element at the given index.

Parameters:

index - the index of the element

selected - flag, which indicates, whether the element should be selected or unselected

setTreeSelection

public void setTreeSelection(IWDNodeElement element)

Sets the lead selections of the whole node's subtree such that the path to the given element is selected and all other nodes are unselected. You may pass null to unselect the complete subtree.

Parameters:

element - The element that is to be selected in the subtree

Throws:

ContextException - if element is not in this node's subtree.

getCurrentElement

public IWDNodeElement getCurrentElement()

Returns the current element (at the lead selection) or null if no element is selected.

Returns:

the current element (at the lead selection) or null if no element is selected.

getParentElement

public IWDNodeElement getParentElement()

Returns the parent element. Returns null, if there is no such element. The parent element is the one element of the parent node that this node refers to. In case of the context root node, there is none. In case of independent nodes, it is the one element of the root node. In case of singleton nodes, it is the parent's lead selection element. In case of non-singleton, the node exists once for each element of the parent and this method returns exactly this element.

Returns:

the parent element or null if there is none

addElement

public void addElement(IWDNodeElement element)

Adds an element to the node collection. If an ICMIObservableList is bound to the node, this list is modified!

Parameters:

element - An element that matches the node.

Throws:

ContextException - if the element does not match the node or if the node is singleton and the parent node has no valid lead selection element.

addElement

public void addElement(int index,
                       IWDNodeElement element)

Adds an element to the node collection at the given index. If an ICMIObservableList is bound to the node, this list is modified!

Parameters:

element - An element that matches the node.

index - the index where the element shall be inserted

Throws:

ContextException - if the element does not match the node or if the node is singleton and the parent node has no valid lead selection element.

removeElement

public boolean removeElement(IWDNodeElement element)

Removes an element from the node collection. If an ICMIObservableList is bound to the node, this list is modified!

Parameters:

element - The element to be removed

Returns:

true if the element was in.

moveElement

public void moveElement(int from,
                        int to)

Moves an element to another position within the node collection. If an ICMIObservableList is bound to the node, this list is modified!

Parameters:

from - the index of the element to be moved.

to - the index it shall be moved to.

Throws:

java.lang.IllegalArgumentException - if either from or to are invalid indexes

swapElements

public void swapElements(int index1,
                         int index2)

Swaps two elements within the node collection. If an ICMIObservableList is bound to the node, this list is modified!

Parameters:

index1 - the index of the one element

index2 - the index of the other element

Throws:

java.lang.IllegalArgumentException - if either index1 or index2 are invalid indexes

moveFirst

public void moveFirst()

Moves the lead selection to the first element in the node collection, if the list is not empty. Otherwise the method returns silently.

moveLast

public void moveLast()

Moves the lead selection to the last element in the node collection, if the list is not empty. Otherwise the method returns silently.

movePrevious

public IWDNodeElement movePrevious()

Moves the lead selection to the previous element in the node collection, if such an element exists. Otherwise the method returns null and does not change the lead selection.

Returns:

the element at the previous position or null if there is none

moveNext

public IWDNodeElement moveNext()

Moves the lead selection to the next element in the node collection, if such an element exists. Otherwise the method returns null and does not change the lead selection.

Returns:

the element at the next position or null if there is none

moveTo

public void moveTo(int index)

Moves the lead selection to the element with the given index.

Parameters:

index - the index of the element

Throws:

IndexOutOfBoundsException - if index is within the range of the node collection

getChildNode

public IWDNode getChildNode(java.lang.String name,
                            int index)

Returns the child Node with the given name at the given index. An index of LEAD_SELECTION is allowed and means the lead selection. If the child Node is singleton, only the special value LEAD_SELECTION and the current value of getLeadSelection() are allowed. Returns null if no node with that name exist.

Parameters:

name - the name of the child node

index - the index of the element

Returns:

the child node with the given name at the given index

Throws:

java.lang.IllegalArgumentException - if index is not within the range of the node collection (all nodes) or if index doesn't represent the lead selection index (singleton nodes only)

createElement

public IWDNodeElement createElement()

Creates a new node element of the type used for this value node.

The element is not yet inserted in the node collection, its IWDNodeElement.node() method will return null.

Returns:

the created node element

createElement

public IWDNodeElement createElement(java.lang.Object reference)

Creates a new node element of the type used for this model node.

The element is not yet inserted in the node collection, its IWDNodeElement.node() method will return null.

Parameters:

reference - a reference to a model instance holding the data for this node element

Returns:

the created node element

sortElements

public void sortElements(java.util.Comparator comparator)

Sorts the elements according to the Comparator. The Comparator gets IWDNodeElements for this node. Since Collections.sort(List) is used, this sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

Note that the element list is only sorted once. Further adds will again be at the end of the list rendering it unsorted again.

If an ICMIObservableList is bound to the node, this list is sorted!

Parameters:

comparator - a Comparator for IWDNodeElements of this node.

notifyAllMappedNodes

public void notifyAllMappedNodes(java.lang.Object payload)

Notifies all (directly and indirectly) mapped Nodes. This notification is sent to an IWDNodeNotificationListener that is registered at the NodeInfo.

Warning: For technical reasons, this notification will only be sent to nodes that have been touched at least once. The reason is that the mapping links are set up upon first access. Before that an origin node does not even know that there is another node mapping to it.

Parameters:

payload - The payload is passed to all nodes with the notification.

See Also:

IWDNodeNotificationListener, IWDNodeInfo.addNotificationListener(IWDNodeNotificationListener), validate()