com.tailf.dp

Interface DpDataCallback

All Known Implementing Classes:

DataCallbackProxy

public interface DpDataCallback

This interface is used for the user data callbacks.

See Also:

Dp.registerAnnotatedCallbacks(Object)

Field Summary

Fields

Modifier and Type	Field and Description
static int	M_ALL Bit flag for all flags
static int	M_CREATE Bit flag for the create(DpTrans,ConfObject[]) method.
static int	M_EXISTS_OPTIONAL Bit flag for the existsOptional(DpTrans,ConfObject[]) method.
static int	M_GET_ATTRS Bit flag for the getAttrs(DpTrans, ConfObject[], List) method.
static int	M_GET_CASE Bit flag for the getCase(DpTrans, ConfObject[], ConfObject[]) method.
static int	M_GET_ELEM Bit flag for the getElem(DpTrans,ConfObject[]) method.
static int	M_GET_NEXT Bit flag for getting the next key for an element using an iterator retrieved from the iterator(DpTrans,ConfObject[]) method, and converting the Java object into a key with the getIteratorKey(DpTrans, ConfObject[], Object) method.
static int	M_GET_NEXT_OBJECT Bit flag for getting the next object using an iterator retrieved from the iterator(DpTrans,ConfObject[]) method, and converting the Java object into an array of ConfValues with the getIteratorObject(DpTrans, ConfObject[], Object) method.
static int	M_GET_OBJECT Bit flag for the getObject(DpTrans,ConfObject[]) method.
static int	M_MOVE_AFTER Bit flag for the moveAfter(DpTrans, ConfObject[], ConfKey) method.
static int	M_NUM_INSTANCES Bit flag for the numInstances(DpTrans,ConfObject[]) method.
static int	M_REMOVE Bit flag for the remove(DpTrans,ConfObject[]) method.
static int	M_SET_ATTR Bit flag for the setAttr(DpTrans, ConfObject[], ConfAttributeValue) method.
static int	M_SET_CASE Bit flag for the setCase(DpTrans, ConfObject[], ConfObject[], ConfTag) method.
static int	M_SET_ELEM Bit flag for the setElem(DpTrans,ConfObject[],ConfValue) method.
static int	M_WRITE_ALL Bit flag for the writeAll(DpTrans, ConfObject[]) method.

Method Summary

Methods

Modifier and Type	Method and Description
String	callpoint() The name of the callpoint
int	create(DpTrans trans, ConfObject[] kp) This callback creates a new presence container, list entry or empty leaf.
boolean	existsOptional(DpTrans trans, ConfObject[] kp) If we have presence containers or optional leafs (empty leafs) without a type, we cannot use the getElem() callback to read such a leaf - since the element is typeless.
int	getAttrs(DpTrans trans, ConfObject[] kp, List<ConfAttributeValue> attrList) This callback only needs to be implemented for callpoints specified for configuration data, and only if attributes are enabled in the server configuration (/confdConfig/enableAttributes set to true).
ConfObject	getCase(DpTrans trans, ConfObject[] kp, ConfObject[] choice) This callback method needs to return the currently chosen 'case' for a 'choice' construct.
ConfValue	getElem(DpTrans trans, ConfObject[] kp) This callback method needs to return a specific leaf value.
ConfKey	getIteratorKey(DpTrans trans, ConfObject[] kp, Object obj) The following callback is used with the iterator above.
ConfValue[]	getIteratorObject(DpTrans trans, ConfObject[] kp, Object obj) The following callback is used with the iterator above.
List<ConfValue[]>	getIteratorObjectList(DpTrans trans, ConfObject[] kp, Object obj, Iterator<? extends Object> iterator) The following callback is used as an replacement of the getIteratorObject when a List of objects should be sent instead of a single instance.
ConfObject[]	getObject(DpTrans trans, ConfObject[] kp) The purpose of the callback is to return an array of values, corresponding to a complete list entry in one swoop.
Iterator<? extends Object>	iterator(DpTrans trans, ConfObject[] kp) This callback makes it possible for ConfD/NCS to traverse a set of list entries.
DpDataFindNextIterator	iterator(DpTrans trans, ConfObject[] kp, ConfFindNextType type, ConfKey key) This iterator method is a specialization of iterator(DpTrans, ConfObject[]) in that it returns an extended iterator i.e.
int	mask() Mask of flags for each method that is supported by this callback: M_EXISTS_OPTIONAL M_GET_ELEM M_GET_NEXT M_SET_ELEM M_CREATE M_REMOVE M_NUM_INSTANCES M_GET_OBJECT M_GET_NEXT_OBJECT M_GET_CASE M_SET_CASE M_GET_ATTRS M_SET_ATTR M_MOVE_AFTER M_WRITE_ALL
int	moveAfter(DpTrans trans, ConfObject[] kp, ConfKey prevkey) This callback only needs to be implemented if we provide configuration data that has YANG lists with a ordered-by user statement.
int	numInstances(DpTrans trans, ConfObject[] kp) This callback can optionally be implemented.
int	remove(DpTrans trans, ConfObject[] kp) This callback is used to remove a presence container, list entry or empty leaf and all its sub elements.
int	setAttr(DpTrans trans, ConfObject[] kp, ConfAttributeValue attr) This callback also only needs to be implemented for callpoints specified for configuration data, and only if attributes are enabled in the server configuration (/confdConfig/enableAttributes set to true).
int	setCase(DpTrans trans, ConfObject[] kp, ConfObject[] choice, ConfTag caseval) This callback method sets the currently chosen 'case' for a 'choice' construct.
int	setElem(DpTrans trans, ConfObject[] kp, ConfValue newval) This callback writes a data leaf.
int	writeAll(DpTrans trans, ConfObject[] kp) This callback method sets the currently chosen 'case' for a 'choice' construct.

Field Detail

M_ALL

static final int M_ALL

Bit flag for all flags

See Also:

Constant Field Values

M_CREATE

static final int M_CREATE

Bit flag for the create(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_EXISTS_OPTIONAL

static final int M_EXISTS_OPTIONAL

Bit flag for the existsOptional(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_GET_ATTRS

static final int M_GET_ATTRS

Bit flag for the getAttrs(DpTrans, ConfObject[], List) method.

See Also:

Constant Field Values

M_GET_CASE

static final int M_GET_CASE

Bit flag for the getCase(DpTrans, ConfObject[], ConfObject[]) method.

See Also:

Constant Field Values

M_GET_ELEM

static final int M_GET_ELEM

Bit flag for the getElem(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_GET_NEXT

static final int M_GET_NEXT

Bit flag for getting the next key for an element using an iterator retrieved from the iterator(DpTrans,ConfObject[]) method, and converting the Java object into a key with the getIteratorKey(DpTrans, ConfObject[], Object) method.

See Also:

Constant Field Values

M_GET_NEXT_OBJECT

static final int M_GET_NEXT_OBJECT

Bit flag for getting the next object using an iterator retrieved from the iterator(DpTrans,ConfObject[]) method, and converting the Java object into an array of ConfValues with the getIteratorObject(DpTrans, ConfObject[], Object) method.

See Also:

Constant Field Values

M_GET_OBJECT

static final int M_GET_OBJECT

Bit flag for the getObject(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_MOVE_AFTER

static final int M_MOVE_AFTER

Bit flag for the moveAfter(DpTrans, ConfObject[], ConfKey) method.

See Also:

Constant Field Values

M_NUM_INSTANCES

static final int M_NUM_INSTANCES

Bit flag for the numInstances(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_REMOVE

static final int M_REMOVE

Bit flag for the remove(DpTrans,ConfObject[]) method.

See Also:

Constant Field Values

M_SET_ATTR

static final int M_SET_ATTR

Bit flag for the setAttr(DpTrans, ConfObject[], ConfAttributeValue) method.

See Also:

Constant Field Values

M_SET_CASE

static final int M_SET_CASE

Bit flag for the setCase(DpTrans, ConfObject[], ConfObject[], ConfTag) method.

See Also:

Constant Field Values

M_SET_ELEM

static final int M_SET_ELEM

Bit flag for the setElem(DpTrans,ConfObject[],ConfValue) method.

See Also:

Constant Field Values

M_WRITE_ALL

static final int M_WRITE_ALL

Bit flag for the writeAll(DpTrans, ConfObject[]) method.

See Also:

Constant Field Values

Method Detail

callpoint

String callpoint()

The name of the callpoint

create

int create(DpTrans trans,
         ConfObject[] kp)
           throws DpCallbackException

This callback creates a new presence container, list entry or empty leaf. In the case of the "servers" data model, this function need to create a new "server" list entry.

Parameters:

trans - Transaction

kp - The keypath

Returns:

Conf.REPLY_OK or Conf.REPLY_ACCUMULATE

Throws:

DpCallbackException - Callback method failed.

existsOptional

boolean existsOptional(DpTrans trans,
                     ConfObject[] kp)
                       throws DpCallbackException

If we have presence containers or optional leafs (empty leafs) without a type, we cannot use the getElem() callback to read such a leaf - since the element is typeless.

If we do not have any optional and typeless elements, we need not implement the existsOptional() callback method.

Parameters:

trans - Transaction

kp - The keypath

Returns:

true or false

Throws:

DpCallbackException - Callback method failed.

getAttrs

int getAttrs(DpTrans trans,
           ConfObject[] kp,
           List<ConfAttributeValue> attrList)
             throws DpCallbackException,
                    IllegalArgumentException

This callback only needs to be implemented for callpoints specified for configuration data, and only if attributes are enabled in the server configuration (/confdConfig/enableAttributes set to true). These are the currently supported attributes: ConfAttributeType.TAGS (values are ConfList of ConfBuf) ConfAttributeType.ANNOTATION (value is ConfBuf) ConfAttributeType.INACTIVE (not used) The attrs parameter is an list of ConfAttributeValue objects with attributeType set to requested attribute and attributeValue set to null. If the list is empty all attributes are requested. If the node given by kp does not exist, the callback should throw an IllegalArgumentException, otherwise it should set values to the elements of the attrs list, or even add attributes if the list was empty. Must return Conf.REPLY_OK on success or Conf.REPLY_DELAYED_RESPONSE. On error a DpCallbackException should be thrown

Parameters:

trans - current transaction

kp - keypath for node to set attributes on

attrList - list of ConfAttributeValue to populate as result

Returns:

Conf.REPLY_OK or Conf.REPLY_DELAYED_RESPONSE on successful call

Throws:

DpCallbackException - on unsuccessful call

IllegalArgumentException

getCase

ConfObject getCase(DpTrans trans,
                 ConfObject[] kp,
                 ConfObject[] choice)
                   throws DpCallbackException

This callback method needs to return the currently chosen 'case' for a 'choice' construct. The choice construct is an array of ConfTag values. The reason for this when nestled choice in choice definitions are addressed, for the "non-nestled" scenario the array is of length 1. The callback must return either a ConfTag containing the selected case or ConfDefault or ConfNoExist. A null return value is equivalent to ConfNoExist. success.

Parameters:

trans - Transaction

kp - The keypath

choice - The choice name(s) as an array of ConfTag

Returns:

The ConfTag, ConfDefault, ConfNoExist or null.

Throws:

DpCallbackException - Callback method failed.

getElem

ConfValue getElem(DpTrans trans,
                ConfObject[] kp)
                  throws DpCallbackException

This callback method needs to return a specific leaf value.

The callback must return a ConfValue on success. The implementation of getElem must be prepared to return all the leafs including the key(s).

When ConfD/NCS invokes getElem on a key leaf it is an existence test. The application should verify whether the object exists or not. If an object doesn't exists this method must return null.

Parameters:

trans - Transaction

kp - The keypath structured as a reversed array of ConfTag and/or ConfKey objects

Returns:

The value of the element

Throws:

DpCallbackException - Callback method failure.

getIteratorKey

ConfKey getIteratorKey(DpTrans trans,
                     ConfObject[] kp,
                     Object obj)
                       throws DpCallbackException

The following callback is used with the iterator above. For each object returned by the iterator the getKey method will be invoked which must return the ConfKey for the given object.

Parameters:

trans - Transaction

kp - The keypath

obj - The object returned by the iterator

Returns:

The configuration key of the provided object.

Throws:

DpCallbackException - Callback method failed.

getIteratorObject

ConfValue[] getIteratorObject(DpTrans trans,
                            ConfObject[] kp,
                            Object obj)
                              throws DpCallbackException

The following callback is used with the iterator above. For each object returned by the iterator the getIteratorObject method will be invoked which must return an array of the ConfValues for the object,

Parameters:

trans - Transaction

kp - The keypath

obj - The object returned by the iterator

Returns:

An array of all values.

Throws:

DpCallbackException - Callback method failed.

getIteratorObjectList

List<ConfValue[]> getIteratorObjectList(DpTrans trans,
                                      ConfObject[] kp,
                                      Object obj,
                                      Iterator<? extends Object> iterator)
                                        throws DpCallbackException

The following callback is used as an replacement of the getIteratorObject when a List of objects should be sent instead of a single instance. This is of interest when lists are big and performance require larger chunks to be sent at once. The first object form the iterator is already retrieved and delivered in the obj parameter. It is mandatory to put this object first in the list. A arbitrary number of additional objects can then be retrieved by using the iterator. Important is to deliver all objects retrieved by the iterator, otherwise these will be lost. To override the global object cache timeout for the response, return an object of type NextObjectList - for example an instance of NextObjectArrayList where you have set the desired timeout via the setTimeout(int) method. For backwards compatibility reasons, you can return a List instance of a class that doesn't implement the NextObjectList interface, in which case the default object cache timeout will be in effect for the response.

Parameters:

trans - Transaction

kp - The keypath

obj - The first object returned by the iterator

iterator - The iterator to optionally retrieve more objects from

Returns:

An List of objects where each object is represented as an array of ConfValues.

Throws:

DpCallbackException - Callback method fails

getObject

ConfObject[] getObject(DpTrans trans,
                     ConfObject[] kp)
                       throws DpCallbackException

The purpose of the callback is to return an array of values, corresponding to a complete list entry in one swoop. The callback will only be called for list entries (i.e. getElem() is still needed for elements that are not sub-elements of a list entry). If the returned array is also ConfValue[] the complete list of values in there defined order is expected. However, as an option, it is possible to return an array of type ConfXMLParam[] instead. The difference being that the values are tagged with the node names from the data model - this means that non-existing values can simply be omitted from the array. Additionally the key leafs can be omitted, since they are already known by the server. - if the key leafs are included, they will be ignored. Finally, in e.g. the case of a container with both config and non-config data, where the config data is in CDB and only the non-config data provided by the callback, the config elements can be omitted (for the ConfValue[] return type they must be included as ConfNoExists elements). However, although the ConfXMLParam array format can represent nested lists, these must not be passed via this function, since the get_object() callback only pertains to a single entry of one list. Nodes representing sub-lists must thus be omitted from the array, and the server will issue separate get_object() invocations to retrieve the data for those. If the requested entry does not exist this callback should return null.

Parameters:

trans - Transaction

kp - The keypath

Returns:

An array of all values.

Throws:

DpCallbackException - Callback method failed.

iterator

Iterator<? extends Object> iterator(DpTrans trans,
                                  ConfObject[] kp)
                                    throws DpCallbackException

This callback makes it possible for ConfD/NCS to traverse a set of list entries.

This method is a specific java construct which is actually not registered on the server side. Instead it is a mandatory tool for the GET_NEXT/GET_NEXT_OBJECT functionality to work. If either the getIteratorKey(DpTrans, ConfObject[], Object) or the getIteratorObject(DpTrans, ConfObject[], Object) is registered this method must also be registered.

The Iterator is stored internally by Dp and when a GET_NEXT/GET_NEXT_OBJECT request is issued the iterator is called to get the next element in the list.

Note that the iterator is free to return any POJO Object and it is instead the responsibility of the getIteratorKey or getIteratorObject to render the return values.

Parameters:

trans - DpTrans object for current transaction

kp - Keypath for the list that is subject for traversal

Returns:

An Java Iterator for traversing objects in the table.

Throws:

DpCallbackException - if Callback method failed.

iterator

DpDataFindNextIterator iterator(DpTrans trans,
                              ConfObject[] kp,
                              ConfFindNextType type,
                              ConfKey key)
                                throws DpCallbackException

This iterator method is a specialization of iterator(DpTrans, ConfObject[]) in that it returns an extended iterator i.e. DpFindNextIterator. This iterator does the same job as the normal Java Iterator but it also has a DpDataFindNextIterator.findNext(DpTrans, ConfObject[], ConfFindNextType, ConfKey) method that is called if FIND_NEXT/FIND_NEXT_OBJECT is called. Note that this iterator is expected to be able to traverse using next()/hasNext() functions after a initial findNext(...) has been called and it will override the .

Parameters:

trans - DpTrans object for current transaction

kp - Keypath for the list that is subject for traversal

type - ConfFindNextType describing the findNext behavior

key - ConfKey which constitutes the search criteria

Returns:

An Java Iterator subclass DpFindNextIterator.

Throws:

DpCallbackException - if Callback method failed.

DpCallbackException

mask

int mask()

Mask of flags for each method that is supported by this callback:

• M_EXISTS_OPTIONAL
• M_GET_ELEM
• M_GET_NEXT
• M_SET_ELEM
• M_CREATE
• M_REMOVE
• M_NUM_INSTANCES
• M_GET_OBJECT
• M_GET_NEXT_OBJECT
• M_GET_CASE
• M_SET_CASE
• M_GET_ATTRS
• M_SET_ATTR
• M_MOVE_AFTER
• M_WRITE_ALL

moveAfter

int moveAfter(DpTrans trans,
            ConfObject[] kp,
            ConfKey prevkey)
              throws DpCallbackException

This callback only needs to be implemented if we provide configuration data that has YANG lists with a ordered-by user statement. The callback moves the list entry given by kp. If prevkey is NULL, the entry is moved first in the list, otherwise it is moved after the entry given by prevkey. In this case prevkey identifies an entry in the list. The callback must return Conf.REPLY_OK on success, Conf.REPLY_DELAYED_RESPONSE or Conf.REPLY_ACCUMULATE. On error an DpCallbackException should be thrown.

Parameters:

trans - current transaction

kp - keypath for entry to move

prevkey - position to entry which should be before the entry to move

Returns:

Conf.REPLY_OK

Throws:

DpCallbackException

numInstances

int numInstances(DpTrans trans,
               ConfObject[] kp)
                 throws DpCallbackException

This callback can optionally be implemented. The purpose is to return the number of instances of a list. Must return number of list entries on success

Parameters:

trans - Transaction

kp - The keypath

Returns:

The number of instances

Throws:

DpCallbackException - Callback method failed.

remove

int remove(DpTrans trans,
         ConfObject[] kp)
           throws DpCallbackException

This callback is used to remove a presence container, list entry or empty leaf and all its sub elements.

Parameters:

trans - Transaction

kp - The keypath

Returns:

Conf.REPLY_OK or Conf.REPLY_ACCUMULATE

Throws:

DpCallbackException - Callback method failed.

setAttr

int setAttr(DpTrans trans,
          ConfObject[] kp,
          ConfAttributeValue attr)
            throws DpCallbackException

This callback also only needs to be implemented for callpoints specified for configuration data, and only if attributes are enabled in the server configuration (/confdConfig/enableAttributes set to true). See get_attrs() above for the supported attributes. The callback should set the attribute attr for the node given by kp to the value v. If the callback is invoked with NULL for the value argument, it means that the attribute should be deleted. The callback must return Conf.REPLY_OK on success, Conf.REPLY_DELAYED_RESPONSE or Conf.REPLY_ACCUMULATE. On error an DpCallbackException should be thrown.

Parameters:

trans - current transaction

kp - keypath for node to set attributes on

attr - ConfAttributeValue to set value

Returns:

int

Throws:

DpCallbackException

setCase

int setCase(DpTrans trans,
          ConfObject[] kp,
          ConfObject[] choice,
          ConfTag caseval)
            throws DpCallbackException

This callback method sets the currently chosen 'case' for a 'choice' construct. The choice construct is an array of ConfTag values. The reason for this when nestled choice in choice definitions are addressed, for the "non-nestled" scenario the array is of length 1.

Parameters:

trans - Transaction

kp - The keypath

choice - The choice name(s) as an array of ConfTag

caseval - The name of the case

Returns:

Conf.REPLY_OK

Throws:

DpCallbackException - Callback method failed.

setElem

int setElem(DpTrans trans,
          ConfObject[] kp,
          ConfValue newval)
            throws DpCallbackException

This callback writes a data leaf. Note that an optional leaf (i.e. a leaf "type empty;" is created by a call to this method.

Parameters:

trans - Transaction

kp - The keypath

newval - The new value to be set

Returns:

Conf.REPLY_OK or Conf.REPLY_ACCUMULATE

Throws:

DpCallbackException - Callback method failed.

writeAll

int writeAll(DpTrans trans,
           ConfObject[] kp)
             throws DpCallbackException

This callback method sets the currently chosen 'case' for a 'choice' construct.

Parameters:

trans - Transaction

kp - The keypath

Returns:

Conf.REPLY_OK

Throws:

DpCallbackException - Callback method failed.