Start of Content Area

Background documentation Supply Functions  Locate the document in its SAP Library structure

the Web Dynpro programming model provides the concept of supply functions to fill context nodes (or more precisely – their node collections). They can be defined for all value nodes (both dependent as well as independent ones), by assigning a method name to the node property supplyFunction in a controller context at design time. The Web Dynpro tools also automatically enhance the corresponding controller class with a supply function including the user coding area contained in it

Supply functions are implemented as methods of type

public void supplyChildNodeElements(SomeChildNode node,

                                    SomeParentNodeElement)

in a Web Dynpro controller (view controller or custom controller). Supply functions and context nodes have a 1..1 relationship, that is, supply functions are specific for individual context nodes. Under certain conditions, supply functions are called by pages in the Web Dynpro runtime environment. On the one hand a reference is passed to the current lead selection of the parent node (parentElement) and to the node instance of the singleton child node (node) to be filled on the other.

Supply functions are used in particular to fill dependent context nodes of type Singleton automatically.

Invalid Context Nodes and Validation by Supply Functions

A supply function is called by the Web Dynpro runtime environment if node elements of an invalid context node are accessed. The Web Dynpro runtime environment executes a node validation.

Context nodes are set to invalid status under the following conditions:

·        Initialization: Contexts are initialized by the Web Dynpro runtime environment as required. This means they only contain empty object instances.

·        Changing the lead selection in the parent node: If the lead selection of the parent node changes, child nodes of type Singleton are invalidated by the Web Dynpro runtime environment.

·        Invalidation using controller coding: The application developer can place context nodes into an invalid state directly using interface method IWDNode.invalidate(). The invalidation for child nodes takes place implicitly after the invalidation of parent nodes.

A context node is validated by the Web Dynpro runtime environment according to the following sequence of steps. If a condition is fulfilled, the check is terminated:

·        The node is already valid: nothing happens.

·        A supply function was defined for the node: the supply function is called

·        Cardinality of the node is 1..1 or 1..n: a node element is added.

·        An empty list of node elements is added.

As an application developer you can also force the validation of a context node using method IWDNode.validate().

Access to a context node requires its validation. The following forms of access are available:

·        Data binding: UI elements are bound to context elements in context nodes and have to be supplied with data by the Web Dynpro runtime environment. Context nodes are validated for this by the Web Dynpro runtime environment.

·        API access: The application developer access node elements using interface methods such as getCurrentElement(), getElementAt(index). If these node elements are located in invalid context nodes, they are validated before the actual method call.

Requirements for Implementing Supply Functions

The implementation of supply functions has to meet the following condition:

·        Node elements of the suitable type have to be added to the node collection, either using node.bind() or node.addElement().

·        The supply function has to add sufficient node elements to satisfy the defined cardinality of the node. For 0..1 nodes at least one, for 1..1 nodes exactly one and for 1..n at least one node element has to be added.

·        The data that is stored in a supply function should merely depend on the node and parentElement parameters in the method signature of the supply function signature. As long as these two parameters each refer to the same object instance, the Web Dynpro runtime environment does not call the supply function again, even across several server roundtrips.
In this case, a supply function is called again before node elements are accessed only if the context node was invalidated explicitly using IWDNode.invalidate().

·        Within supply functions, there should be no write access to context data that does not belong to the node node (or its children).

·        Child nodes of the node node instance should not be accessed if they use a separate supply function. This leads to the supply function of the child node being called before its parent node is valid, which in turn results in an endless loop.

Example

This graphic is explained in the accompanying text

The independent Customers context node should be filled using a supply function called supplyCustomers. After defining this supply function, the Web Dynpro tools add a corresponding method to the view controller.

The Web Dynpro runtime environment passes the two parameters node and parentElement when the method is called. The node parameter is of type IPrivateDataView.ICustomersNode, as the node elements (that is, Smith, Miller and Adams) have to be added to the Customers code of the controllers in the DataView view.

To determine the node elements that have to be added to a child node, the reference to the node element parentElement that is currently selected in the parent node is usually required. If for independent nodes a supply function is defined, then the parentElement variable refers to the only node element that exists in the context’s root node. This root element is always of type I<Controller Interface>.IContextElement.

Generated supply function in the controller of the DataView view:

...

//@@begin javadoc:supplyOrders(IWDNode,IWDNodeElement)

/**

 * Declared supply function for IPrivateContextsView.IOrdersNode.

 * This method is called when the node is invalid and the collection is

 * requested. This may occur during any phase, even at the beginning to

 * initialize the node. The method is expected to fill the node

 * collection using IWDNode.bind(Collection) or

 * IWDNode.addElement(IWDNodeElement).

 *

 * @param node the node that is to be filled

 * @param parentElement The element that this node is a child of. May be

 *        <code>null</code> if there is none.

 * @see com.sap.tc.webdynpro.progmodel.api.IWDNode#bind(Collection)

 * @see com.sap.tc.webdynpro.progmodel.api.IWDNode#bind(IWDNodeElement)

 */

//@@end

public void supplyCustomers(IPrivateDataView.ICustomersNode node,

                            IPrivateDataView.IContextElement parentElement)

{

  //@@begin supplyCustomers(IWDNode,IWDNodeElement)

  PrivateDataView.ICustomersElement newCustomersNodeElement; 

  for (Iterator iter = SomeBOL.getNewCustomersIter(); iter.hasNext();) {

    customer = (SomeBOL.Customer) iter.next();

    newCustomersNodeElement = wdContext.createCustomersElement();

    newCustomersNodeElement.setName(customer.getName());

    node.addElement(newCustomersNodeElement);

  }

  //@@end

}

...

 

For more information about using supply functions, see Application for Context Programming and Data Binding.

  

  

 

End of Content Area