com.tailf.cdb

Class CdbUpgradeSession

Object

com.tailf.cdb.CdbSession

com.tailf.cdb.CdbUpgradeSession

public class CdbUpgradeSession
extends CdbSession

The class CdbUpgradeSession represents a session against the Cdb database that can be used for accessing data models that are in the process of being deleted by a cdb upgrade. The operations supported by an upgrade session are the same as those of a normal session, the only difference being that keypaths on the format (fmt, arguments) will be treated as ConfCdbUpgradePaths rather than ConfPaths. For information on specific methods, refer to the CdbSession documentation.

Constructor Summary

Constructors

Constructor and Description
CdbUpgradeSession(Cdb cdb)
CdbUpgradeSession(Cdb cdb, CdbDBType dbtype)
CdbUpgradeSession(Cdb cdb, CdbDBType dbtype, EnumSet<CdbLockType> lockflags)

Method Summary

Modifier and Type	Method and Description
void	cd(ConfCdbUpgradePath path)
void	cd(String fmt, Object... arguments) Change working directory to container specified by path string
void	create(ConfCdbUpgradePath path)
void	create(String fmt, Object... arguments) similar to CdbSession.create(ConfPath) but specifies element using path string
void	delete(ConfCdbUpgradePath path)
void	delete(String fmt, Object... arguments) similar to CdbSession.delete(ConfPath) but specifies element using path string
boolean	exists(ConfCdbUpgradePath path)
boolean	exists(String fmt, Object... arguments) Checks whether an element exists.
ConfObject	getCase(String choice, ConfCdbUpgradePath path)
ConfObject	getCase(String choice, String fmt, Object... arguments) Retrieve the currently selected case.
ConfValue	getElem(ConfCdbUpgradePath path)
ConfValue	getElem(String fmt, Object... arguments) similar to CdbSession.getElem(ConfPath) but specifies element using path string
int	getNumberOfInstances(ConfCdbUpgradePath path)
int	getNumberOfInstances(String fmt, Object... arguments) similar to CdbSession.getNumberOfInstances(ConfPath) but specifies element using path string
ConfObject[]	getObject(int numOfObjects, ConfCdbUpgradePath path)
ConfObject[]	getObject(int numOfObjects, String fmt, Object... arguments) In some cases it can be motivated to read multiple values in one request - this will be more efficient since it only incurs a single round trip to the server, but usage is a bit more complex.
List<ConfObject[]>	getObjects(int numOfObjects, int instance, int numOfInstances, ConfCdbUpgradePath path)
List<ConfObject[]>	getObjects(int numOfObjects, int instance, int numOfInstances, String fmt, Object... arguments) Similar to cdb.getObject(), but reads multiple instances of a dynamic container based on the "instance integer" otherwise given within square brackets in the path - here the path must specify the dynamic container without the instance integer.
ConfXMLParam[]	getValues(ConfXMLParam[] params, ConfCdbUpgradePath path)
ConfXMLParam[]	getValues(ConfXMLParam[] params, String fmt, Object... arguments) Read an arbitrary set of sub-elements of a container element.
int	index(ConfCdbUpgradePath path)
int	index(String fmt, Object... arguments) similar to CdbSession.index(ConfPath) but specifies element using path string
boolean	isDefault(ConfCdbUpgradePath path)
boolean	isDefault(String fmt, Object... arguments) similar to CdbSession.isDefault(ConfPath) but specifies element using path string
int	nextIndex(ConfCdbUpgradePath path)
int	nextIndex(String fmt, Object... arguments) similar to CdbSession.nextIndex(ConfPath) but specifies element using path string
void	pushd(ConfCdbUpgradePath path)
void	pushd(String fmt, Object... arguments) similar to CdbSession.pushd(ConfPath) but specifies position using path string
void	setCase(String choice, String scase, ConfCdbUpgradePath path)
void	setCase(String choice, String scase, String fmt, Object... arguments) When we use the YANG choice construct in the data model, this function can be used to select the current case.
void	setElem(ConfValue value, ConfCdbUpgradePath path)
void	setElem(ConfValue value, String fmt, Object... arguments) similar to CdbSession.setElem(ConfValue, ConfPath) but specifies element using path string
void	setObject(ConfValue[] values, ConfCdbUpgradePath path)
void	setObject(ConfValue[] values, String fmt, Object... arguments) similar to CdbSession.setObject(ConfValue[], ConfPath) but specifies element using path string
void	setValues(ConfXMLParam[] params, ConfCdbUpgradePath path)
void	setValues(ConfXMLParam[] params, String fmt, Object... arguments) similar to CdbSession.setValues(ConfXMLParam[], ConfPath) but specifies element using path string
String	toString()

Methods inherited from class com.tailf.cdb.CdbSession

cd, create, delete, endSession, exists, getCase, getCdb, getcwd, getcwdPath, getDbType, getElem, getNumberOfInstances, getObject, getObjects, getValues, index, isDefault, nextIndex, numInstances, numInstances, popd, pushd, setCase, setElem, setNamespace, setObject, setValues, setValues

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CdbUpgradeSession

public CdbUpgradeSession(Cdb cdb)
                  throws IOException,
                         ConfException

Throws:

IOException

ConfException

CdbUpgradeSession

public CdbUpgradeSession(Cdb cdb,
                         CdbDBType dbtype)
                  throws ConfException,
                         IOException

Throws:

ConfException

IOException

CdbUpgradeSession

public CdbUpgradeSession(Cdb cdb,
                         CdbDBType dbtype,
                         EnumSet<CdbLockType> lockflags)
                  throws ConfException,
                         IOException

Throws:

ConfException

IOException

Method Detail

exists

public boolean exists(ConfCdbUpgradePath path)
               throws ConfException,
                      IOException

Throws:

ConfException

IOException

exists

public boolean exists(String fmt,
                      Object... arguments)
               throws ConfException,
                      IOException

Description copied from class: CdbSession

Checks whether an element exists. The element is specified using a path string and optionally string substitution parameters

Overrides:

exists in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

true if exists

Throws:

ConfException

IOException

cd

public void cd(ConfCdbUpgradePath path)
        throws ConfException,
               IOException

Throws:

ConfException

IOException

cd

public void cd(String fmt,
               Object... arguments)
        throws ConfException,
               IOException

Description copied from class: CdbSession

Change working directory to container specified by path string

Overrides:

cd in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

ConfException

IOException

pushd

public void pushd(ConfCdbUpgradePath path)
           throws ConfException,
                  IOException

Throws:

ConfException

IOException

pushd

public void pushd(String fmt,
                  Object... arguments)
           throws ConfException,
                  IOException

Description copied from class: CdbSession

similar to CdbSession.pushd(ConfPath) but specifies position using path string

Overrides:

pushd in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

ConfException

IOException

getNumberOfInstances

public int getNumberOfInstances(ConfCdbUpgradePath path)
                         throws ConfException,
                                IOException

Throws:

ConfException

IOException

getNumberOfInstances

public int getNumberOfInstances(String fmt,
                                Object... arguments)
                         throws ConfException,
                                IOException

Description copied from class: CdbSession

similar to CdbSession.getNumberOfInstances(ConfPath) but specifies element using path string

Overrides:

getNumberOfInstances in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

number of instances

Throws:

ConfException

IOException

nextIndex

public int nextIndex(ConfCdbUpgradePath path)
              throws ConfException,
                     IOException

Throws:

ConfException

IOException

nextIndex

public int nextIndex(String fmt,
                     Object... arguments)
              throws ConfException,
                     IOException

Description copied from class: CdbSession

similar to CdbSession.nextIndex(ConfPath) but specifies element using path string

Overrides:

nextIndex in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

position of next key

Throws:

ConfException

IOException

index

public int index(ConfCdbUpgradePath path)
          throws ConfException,
                 IOException

Throws:

ConfException

IOException

index

public int index(String fmt,
                 Object... arguments)
          throws ConfException,
                 IOException

Description copied from class: CdbSession

similar to CdbSession.index(ConfPath) but specifies element using path string

Overrides:

index in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

position of key

Throws:

ConfException

IOException

isDefault

public boolean isDefault(ConfCdbUpgradePath path)
                  throws ConfException,
                         IOException

Throws:

ConfException

IOException

isDefault

public boolean isDefault(String fmt,
                         Object... arguments)
                  throws ConfException,
                         IOException

Description copied from class: CdbSession

similar to CdbSession.isDefault(ConfPath) but specifies element using path string

Overrides:

isDefault in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

true/false if a leaf has a default value defined

Throws:

ConfException

IOException

getElem

public ConfValue getElem(ConfCdbUpgradePath path)
                  throws ConfException,
                         IOException

Throws:

ConfException

IOException

getElem

public ConfValue getElem(String fmt,
                         Object... arguments)
                  throws ConfException,
                         IOException

Description copied from class: CdbSession

similar to CdbSession.getElem(ConfPath) but specifies element using path string

Overrides:

getElem in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Returns:

element represented by a ConfValue

Throws:

ConfException

IOException

setElem

public void setElem(ConfValue value,
                    ConfCdbUpgradePath path)
             throws ConfException,
                    IOException

Throws:

ConfException

IOException

setElem

public void setElem(ConfValue value,
                    String fmt,
                    Object... arguments)
             throws ConfException,
                    IOException

Description copied from class: CdbSession

similar to CdbSession.setElem(ConfValue, ConfPath) but specifies element using path string

Overrides:

setElem in class CdbSession

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

ConfException

IOException

create

public void create(ConfCdbUpgradePath path)
            throws ConfException,
                   IOException

Throws:

ConfException

IOException

create

public void create(String fmt,
                   Object... arguments)
            throws ConfException,
                   IOException

Description copied from class: CdbSession

similar to CdbSession.create(ConfPath) but specifies element using path string

Overrides:

create in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

ConfException

IOException

delete

public void delete(ConfCdbUpgradePath path)
            throws IOException,
                   ConfException

Throws:

IOException

ConfException

delete

public void delete(String fmt,
                   Object... arguments)
            throws IOException,
                   ConfException

Description copied from class: CdbSession

similar to CdbSession.delete(ConfPath) but specifies element using path string

Overrides:

delete in class CdbSession

Parameters:

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

IOException

ConfException

getObject

public ConfObject[] getObject(int numOfObjects,
                              ConfCdbUpgradePath path)
                       throws IOException,
                              ConfException

Throws:

IOException

ConfException

getObject

public ConfObject[] getObject(int numOfObjects,
                              String fmt,
                              Object... arguments)
                       throws IOException,
                              ConfException

Description copied from class: CdbSession

In some cases it can be motivated to read multiple values in one request - this will be more efficient since it only incurs a single round trip to the server, but usage is a bit more complex. This function reads at most numOfObjects values from the container element specified by the path, and returns them in an array. When reading from a container with mixed configuration and operational data (i.e. a config container that has some number of operational elements), some elements will have the "wrong" type - i.e. operational data in a session for CDB_RUNNING/CDB_STARTUP, or config data in a session for CDB_OPERATIONAL. Leaf elements of the "wrong" type will have a "value" of ConfNoExists in the array, while static or (existing) optional sub-container elements will have ConfXMLTag in all cases. Sub-containers or leafs provided by external data providers will always be represented with ConfNoExists, whether config or not. On success, the function returns the actual number of elements in the container. I.e. if the return value is bigger than n, only the values for the first n elements are in the array, and the remaining values have been discarded. Note that given the specification of the array contents, there is always a fixed upper bound on the number of actual elements, and if there are no optional sub-containers, the number is constant. As an example, this code could be used to read the values for interface "eth0" on host "buzz":

 String path = "/mtest/servers/server{www}/interface{%s}";
 ConfObject[] objArr = cdbsess.getObject(4, path, "eth0");

 ConfBuf name = (ConfBuf) objArr[0];
 ConfInt64 mtu = (ConfInt64) objArr[1];
 

Overrides:

getObject in class CdbSession

Parameters:

numOfObjects - number of objects to retrieve

Returns:

ConfObject[]

Throws:

IOException

ConfException

getObjects

public List<ConfObject[]> getObjects(int numOfObjects,
                                     int instance,
                                     int numOfInstances,
                                     ConfCdbUpgradePath path)
                              throws IOException,
                                     ConfException

Throws:

IOException

ConfException

getObjects

public List<ConfObject[]> getObjects(int numOfObjects,
                                     int instance,
                                     int numOfInstances,
                                     String fmt,
                                     Object... arguments)
                              throws IOException,
                                     ConfException

Description copied from class: CdbSession

Similar to cdb.getObject(), but reads multiple instances of a dynamic container based on the "instance integer" otherwise given within square brackets in the path - here the path must specify the dynamic container without the instance integer. At most numOfObject values from each of numOfInstances instances, starting at instance instance, are read and placed in a List of arrays of objects. The List contains an array for each instance, to at most numOfInstances and the arrays are at most numOfObjects large. On success, the highest actual number of values in any of the instances read is returned. An exception with code ConfException.ERR_NOEXISTS will be returned if we attempt to read more instances than actually exist (i.e. if instance + nobj - 1 is outside the range of actually existing instances). Example - read the data for all interfaces on the host "buzz":

 String path = "/mtest/servers/server";
 int n = cdbsess.numInstances(path);
 List<ConfObject[]> objArrList = cdbsess.getObjects(4, 0, n, path);

 ConfBuf[] name = new ConfBuf[n];
 ConfIPv4[] ip = new ConfIPv4[n];
 ConfUInt16[] port = new ConfUInt16[n];
 for (int i = 0; i < objArrList.size(); i++) {
     ConfObject[] objArr = objArrList.get(i);
     name[i] = (ConfBuf) objArr[0];
     ip[i] = (ConfIPv4) objArr[1];
     port[i] = (ConfUInt16) objArr[2];
 }
 

Overrides:

getObjects in class CdbSession

Parameters:

numOfObjects - number of objects to retrieve

instance - instance integer

numOfInstances - number if instances to retrieve

Returns:

List<ConfObject[]>

Throws:

IOException

ConfException

setObject

public void setObject(ConfValue[] values,
                      ConfCdbUpgradePath path)
               throws IOException,
                      ConfException

Throws:

IOException

ConfException

setObject

public void setObject(ConfValue[] values,
                      String fmt,
                      Object... arguments)
               throws IOException,
                      ConfException

Description copied from class: CdbSession

similar to CdbSession.setObject(ConfValue[], ConfPath) but specifies element using path string

Overrides:

setObject in class CdbSession

fmt - path string

arguments - optional parameters for substitution in fmt

Throws:

IOException

ConfException

setValues

public void setValues(ConfXMLParam[] params,
                      ConfCdbUpgradePath path)
               throws IOException,
                      ConfException

Throws:

IOException

ConfException

setValues

public void setValues(ConfXMLParam[] params,
                      String fmt,
                      Object... arguments)
               throws IOException,
                      ConfException

Description copied from class: CdbSession

similar to CdbSession.setValues(ConfXMLParam[], ConfPath) but specifies element using path string

Overrides:

setValues in class CdbSession

Throws:

IOException

ConfException

getValues

public ConfXMLParam[] getValues(ConfXMLParam[] params,
                                ConfCdbUpgradePath path)
                         throws IOException,
                                ConfException

Throws:

IOException

ConfException

getValues

public ConfXMLParam[] getValues(ConfXMLParam[] params,
                                String fmt,
                                Object... arguments)
                         throws IOException,
                                ConfException

Description copied from class: CdbSession

Read an arbitrary set of sub-elements of a container element. The values array must be pre-populated with ConfXMLParam with or without an subArray of derived elements. The ConfXMLParam array can point to a location using a path or by the use of the derived element ConfXMLParamCdbStart carry the instance identification in it. All elements have the same position in the array after the call, in order to simplify extraction of the values - this means that optional elements that were requested but did not exist will have ConfNoExists value rather than being omitted from the array. However requesting a dynamic container that does not exist, or requesting non-CDB data, or operational vs config data, is an error. In this rather complex example we first read only the "name" and "enabled" values for all interfaces, and then read "ip" and "mask" for those that were enabled - a total of two requests. Note that since the "interface" container begin/end elements are in the array, the path must not include the "interface" component. When reading values from a single container, it is generally simpler to have the container component (and keys or instance integer) in the path instead.

  String path = "/mtest/servers/server";
  int n = cdbsess.getNumberOfInstances(path);
  List<ConfObject[]> objArrList = cdbsess.getObjects(4,0,n,path);

  //when reading ip/port, we need 5 elements per interface:
  //begin + name (key) + ip + port + end
  ConfXMLParam[] values = new ConfXMLParam[5*n];

  int j = 0;
  for (int i=0; i<n; i++) {
      values[j++] = new ConfXMLParamCdbStart(ns, "server", i);
      values[j++] = new ConfXMLParamLeaf(ns, "name");
      values[j++] = new ConfXMLParamLeaf(ns, "ip");
      values[j++] = new ConfXMLParamLeaf(ns, "port");
      values[j++] = new ConfXMLParamStop(ns, "server");
  }
  path = "/mtest/servers";
  ConfXMLParam[] resvalues = cdbsess.getValues(values, path);

  // extract name for enabled interfaces
  String name = null;
  int noOfInterfaces = 0;
  for (int i = 0; i < n; i++) {
      ConfIPv4 ip4 = (ConfIPv4) resvalues[i*5+2].getValue();
      name = resvalues[i*5+1].getValue().toString();
      path = "/mtest/servers/server{%s}/interface";
      noOfInterfaces = cdbsess.getNumberOfInstances(path, name);
      System.out.println("name = "+ name);
  }
  int n_if = j;
  j = 0;

  values = new ConfXMLParam[noOfInterfaces*4];
  for (int i=0; i<noOfInterfaces; i++) {
      values[j++] = new ConfXMLParamCdbStart(ns.hash(),
                                          ns.mtest_interface, i);
      values[j++] = new ConfXMLParamLeaf(ns.hash(),
                                         ns.mtest_name);
      values[j++] = new ConfXMLParamLeaf(ns.hash(),
                                         ns.mtest_mtu);
      values[j++] = new ConfXMLParamStop(ns.hash(),
                                        ns.mtest_interface);
   }
   path = "/mtest/servers/server{%s}";
   resvalues = cdbsess.getValues(values, path, name);

 ...

Overrides:

getValues in class CdbSession

Returns:

ConfXMLParam[]

Throws:

IOException

ConfException

getCase

public ConfObject getCase(String choice,
                          ConfCdbUpgradePath path)
                   throws IOException,
                          ConfException

Throws:

IOException

ConfException

getCase

public ConfObject getCase(String choice,
                          String fmt,
                          Object... arguments)
                   throws IOException,
                          ConfException

Description copied from class: CdbSession

Retrieve the currently selected case.

When we use the YANG choice construct in the data model, this method can be used to find the currently selected case, avoiding useless CdbSession.getElem(ConfPath) etc requests for elements that belong to other cases.

The fmt give the path to the container where the choice is defined,

The choice is the name of the choice. The case value is returned as type ConfTag.

If no case is currently selected (i.e. for an optional choice that does not have a default case), the function will fail with a an exception with code ConfException.ERR_NOEXISTS.

Overrides:

getCase in class CdbSession

Parameters:

choice - the name of the choice

fmt - format string pointing to the choice

arguments - replacement arguments for fmt string

Returns:

ConfObject case value as ConfTag

Throws:

IOException

ConfException

setCase

public void setCase(String choice,
                    String scase,
                    ConfCdbUpgradePath path)
             throws IOException,
                    ConfException

Throws:

IOException

ConfException

setCase

public void setCase(String choice,
                    String scase,
                    String fmt,
                    Object... arguments)
             throws IOException,
                    ConfException

Description copied from class: CdbSession

When we use the YANG choice construct in the data model, this function can be used to select the current case.

When configuration data is modified by northbound agents, the current case is implicitly selected (and elements for other cases potentially deleted) by the setting of elements in a choice.

For operational data in CDB however, this is under direct control of the application, which needs to explicitly set the current case. Setting the case will also automatically delete elements belonging to other cases, but it is up to the application to not set any elements in the "wrong" case. The fmt, ... arguments give the path to the container where the choice is defined, and choice and scase are the choice and case names. For an optional choice, it is possible to have no case at all selected. To indicate that the previously selected case should be deleted without selecting another case, we can pass NULL for the scase argument.

Overrides:

setCase in class CdbSession

Parameters:

choice - choice string

scase - case string

fmt - format string pointing to the choice

arguments - replacement arguments for fmt string

Throws:

IOException

ConfException

toString

public String toString()

Overrides:

toString in class CdbSession