# Java API Overview The NSO Java library contains a variety of APIs for different purposes. In this section, we introduce these and explain their usage. The Java library deliverables are found as two jar files (`ncs.jar` and `conf-api.jar`). The jar files and their dependencies can be found under `$NCS_DIR/java/jar/`. For convenience, the Java build tool Apache ant () is used to run all of the examples. However, this tool is not a requirement for NSO. General for all APIs is that they communicate with NSO using TCP sockets. This makes it possible to use all APIs from a remote location. The following APIs are included in the library:


MAAPI (Management Agent API) Northbound interface that is transactional and user session-based. Using this interface both configuration and operational data can be read. Configuration data can be written and committed as one transaction. The API is complete in the way that it is possible to write a new northbound agent using only this interface. It is also possible to attach to ongoing transactions in order to read uncommitted changes and/or modify data in these transactions.
CDB API The southbound interface provides access to the CDB configuration database. Using this interface configuration data can be read. In addition, operational data that is stored in CDB can be read and written. This interface has a subscription mechanism to subscribe to changes. A subscription is specified on a path that points to an element in a YANG model or an instance in the instance tree. Any change under this point will trigger the subscription. CDB has also functions to iterate through the configuration changes when a subscription has been triggered.
DP API Southbound interface that enables callbacks, hooks, and transforms. This API makes it possible to provide the service callbacks that handle service-to-device mapping logic. Other usual cases are external data providers for operational data or action callback implementations. There are also transaction and validation callbacks, etc. Hooks are callbacks that are fired when certain data is written and the hook is expected to do additional modifications of data. Transforms are callbacks that are used when complete mediation between two different models is necessary.
NED API (Network Element Driver) Southbound interface that mediates communication for devices that do not speak either NETCONF or SNMP. All prepackaged NEDs for different devices are written using this interface. It is possible to use the same interface to write your own NED. There are two types of NEDs, CLI NEDs and Generic NEDs. CLI NEDs can be used for devices that can be controlled by a Cisco-style CLI syntax, in this case the NED is developed primarily by building a YANG model and a relatively small part in Java. In other cases the Generic NED can be used for any type of communication protocol.
NAVU API (Navigation Utilities) API that resides on top of the Maapi and Cdb APIs. It provides schema model navigation and instance data handling (read/write). Uses either a Maapi or Cdb context as data access and incorporates a subset of functionality from these (navigational and data read/write calls). Its major use is in service implementations which normally is about navigating device models and setting device data.
ALARM API Eastbound API that is used both to consume and produce alarms in alignment with the NSO Alarm model. To consume alarms the AlarmSource interface is used. To produce a new alarm the AlarmSink interface is used. There is also a possibility to buffer produced alarms and make asynchronous writes to CDB to improve alarm performance.
NOTIF API Northbound API that is used to subscribe to system events from NSO. These events are generated for audit log events, for different transaction states, for HA state changes, upgrade events, user sessions, etc.
HA API (High Availability) Northbound api used to manage a High Availability cluster of NSO instances. An NSO instance can be in one of three states NONE, PRIMARY or SECONDARY. With the HA API the state can be queried and changed for NSO instances in the cluster.

In addition, the Conf API framework contains utility classes for data types, keypaths, etc. ## MAAPI The Management Agent API (MAAPI) provides an interface to the Transaction engine in NSO. As such it is very versatile. Here are some examples of how the MAAPI interface can be used. * Read and write configuration data stored by NSO or in an external database. * Write our own northbound interface. * We could access data inside a not yet committed transaction, e.g. as validation logic where our Java code can attach itself to a running transaction and read through the not yet committed transaction, and validate the proposed configuration change. * During database upgrade we can access and write data to a special upgrade transaction. The first step of a typical sequence of MAAPI API calls when writing a management application would be to create a user session. Creating a user session is the equivalent of establishing an SSH connection from a NETCONF manager. It is up to the MAAPI application to authenticate users. The TCP connection between MAAPI and NSO is neither encrypted, nor authenticated. The Maapi Java package does however include an `authenticate()` method that can be used by the application to hook into the AAA framework of NSO and let NSO authenticate the user. {% code title="Example: Establish a MAAPI Connection" %} ``` Socket socket = new Socket("localhost",Conf.NCS_PORT); Maapi maapi = new Maapi(socket); ``` {% endcode %} When a Maapi socket has been created the next step is to create a user session and supply the relevant information about the user for authentication. {% code title="Example: Starting a User Session" %} ``` maapi.startUserSession("admin", InetAddress.getByName("localhost"), "maapi", new String[] {"admin"}, MaapiUserSessionFlag.PROTO_TCP); ``` {% endcode %} When the user has been authenticated and a user session has been created the Maapi reference is now ready to establish a new transaction toward a data store. The following code snippet starts a read/write transaction towards the running data store. {% code title="Example: Start a Read/Write transaction Towards Running" %} ``` int th = maapi.startTrans(Conf.DB_RUNNING, Conf.MODE_READ_WRITE); ``` {% endcode %} \\ The `startTrans(int db,int mode)` method of the Maapi class returns an integer that represents a transaction handler. This transaction handler is used when invoking the various Maapi methods. An example of a typical transactional method is the `getElem()` method: {% code title="Example: Maapi.getElem()" %} ```java public ConfValue getElem(int tid, String fmt, Object... arguments) ``` {% endcode %} The `getElem(int th, String fmt, Object ... arguments)` first parameter is the transaction handle which is the integer that was returned by the `startTrans()` method. The *`fmt`* is a path that leads to a leaf in the data model. The path is expressed as a format string that contain fixed text with zero to many embedded format specifiers. For each specifier, one argument in the variable argument list is expected. The currently supported format specifiers in the Java API are: * `%d` - requiring an integer parameter (type int) to be substituted. * `%s` - requiring a `java.lang.String` parameter to be substituted. * `%x` - requiring subclasses of type `com.tailf.conf.ConfValue` to be substituted. ``` ConfValue val = maapi.getElem(th, "/hosts/host{%x}/interfaces{%x}/ip", new ConfBuf("host1"), new ConfBuf("eth0")); ``` The return value *`val`* contains a reference to a `ConfValue` which is a superclass of all the `ConfValues` that maps to the specific yang data type. If the Yang data type `ip` in the Yang model is `ietf-inet-types:ipv4-address`, we can narrow it to the subclass which is the corresponding `com.tailf.conf.ConfIPv4`. ``` ConfIPv4 ipv4addr = (ConfIPv4)val; ``` The opposite operation of the `getElem()` is the `setElem()` method which set a leaf with a specific value. ``` maapi.setElem(th , new ConfUInt16(1500), "/hosts/host{%x}/interfaces{%x}/ip/mtu", new ConfBuf("host1"), new ConfBuf("eth0")); ``` We have not yet committed the transaction so no modification is permanent. The data is only visible inside the current transaction. To commit the transaction we call: ``` maapi.applyTrans(th) ``` The method `applyTrans()` commits the current transaction to the running datastore. {% code title="Example: Commit a Transaction" %} ``` int th = maapi.startTrans(Conf.DB_RUNNING, Conf.MODE_READ_WRITE); try { maapi.lock(Conf.DB_RUNNING); /// make modifications to th maapi.setElem(th, .....); maapi.applyTrans(th); maapi.finishTrans(th); } catch(Exception e) { maapi.finishTrans(th); } finally { maapi.unLock(Conf.DB_RUNNING); } ``` {% endcode %} It is also possible to run the code above without `lock(Conf.DB_RUNNING)`. Calling the `applyTrans()` method also performs additional validation of the new data as required by the data model and may fail if the validation fails. You can perform the validation beforehand, using the `validateTrans()` method. Additionally, applying transaction can fail in case of a conflict with another, concurrent transaction. The best course of action in this case is to retry the transaction. Please see [Handling Conflicts](https://nso-docs.cisco.com/guides/nso-6.3/development/nso-concurrency-model#ncs.development.concurrency.handling) for details. The MAAPI is also intended to attach to already existing NSO transaction to inspect not yet committed data for example if we want to implement validation logic in Java. See the example below (Attach Maapi to the Current Transaction). ## CDB API This API provides an interface to the CDB Configuration database which stores all configuration data. With this API the user can: * Start a CDB Session to read configuration data. * Subscribe to changes in CDB - The subscription functionality makes it possible to receive events/notifications when changes occur in CDB. CDB can also be used to store operational data, i.e., data which is designated with a "config false" statement in the YANG data model. Operational data is read/write trough the CDB API. NETCONF and the other northbound agents can only read operational data. Java CDB API is intended to be fast and lightweight and the CDB read Sessions are expected to be short lived and fast. The NSO transaction manager is surpassed by CDB and therefore write operations on configurational data is prohibited. If operational data is stored in CDB both read and write operations on this data is allowed. CDB is always locked for the duration of the session. It is therefore the responsibility of the programmer to make CDB interactions short in time and assure that all CDB sessions are closed when interaction has finished. To initialize the CDB API a CDB socket has to be created and passed into the API base class `com.tailf.cdb.Cdb`: {% code title="Example: Establish a Connection to CDB" %} ``` Socket socket = new Socket("localhost", Conf.NCS_PORT); Cdb cdb = new Cdb("MyCdbSock",socket); ``` {% endcode %} After the `cdb` socket has been established, a user could either start a CDB Session or start a subscription of changes in CDB: {% code title="Example: Establish a CDB Session" %} ``` CdbSession session = cdb.startSession(CdbDBType.RUNNING); /* * Retrieve the number of children in the list and * loop over these children */ for(int i = 0; i < session.numInstances("/servers/server"); i++) { ConfBuf name = (ConfBuf) session.getElem("/servers/server[%d]/hostname", i); ConfIPv4 ip = (ConfIPv4) session.getElem("/servers/server[%d]/ip", i); } ``` {% endcode %} We can refer to an element in a model with an expression like `/servers/server`. This type of string reference to an element is called keypath or just path. To refer to element underneath a list, we need to identify which instance of the list elements that is of interest. This can be performed either by pinpointing the sequence number in the ordered list, starting from 0. For instance the path: `/servers/server[2]/port` refers to the `port` leaf of the third server in the configuration. This numbering is only valid during the current CDB session. Note, the database is locked during this session. We can also refer to list instances using the key values for the list. Remember that we specify in the data model which leaf or leafs in list that constitute the key. In our case, a server has the `name` leaf as key. The syntax for keys is a space-separated list of key values enclosed within curly brackets: `{ Key1 Key2 ...}`. So, `/servers/server{www}/ip` refers to the `ip` leaf of the server whose name is `www`. A YANG list may have more than one key for example the keypath: `/dhcp/subNets/subNet{192.168.128.0 255.255.255.0}/routers` refers to the routers list of the subnet which has key `192.168.128.0`, `255.255.255.0`. The keypath syntax allows for formatting characters and accompanying substitution arguments. For example, `getElem("server[%d]/ifc{%s}/mtu",2,"eth0")` is using a keypath with a mix of sequence number and keyvalues with formatting characters and argument. Expressed in text the path will reference the MTU of the third server instance's interface named `eth0`. The `CdbSession` Java class have a number of methods to control current position in the model. * `CdbSession.cwd()` to get current position. * `CdbSession.cd()` to change current position. * `CdbSession.pushd()` to change and push a new position to a stack. * `CdbSession.popd()` to change back to an stacked position. Using relative paths and e.g. `CdbSession.pushd()`, it is possible to write code that can be re-used for common sub-trees. The current position also includes the namespace. If an element of another namespace should be read, then the prefix of that namespace should be set in the first tag of the keypath, like: `/smp:servers/server` where `smp` is the prefix of the namespace. It is also possible to set the default namespace for the CDB session with the method `CdbSession.setNamespace(ConfNamespace)`. {% code title="Example: Establish a CDB Subscription" %} ``` CdbSubscription sub = cdb.newSubscription(); int subid = sub.subscribe(1, new servers(), "/servers/server/"); // tell CDB we are ready for notifications sub.subscribeDone(); // now do the blocking read while (true) { int[] points = sub.read(); // now do something here like diffIterate ..... } ``` {% endcode %} The CDB subscription mechanism allows an external Java program to be notified when different parts of the configuration changes. For such a notification, it is also possible to iterate through the change set in CDB for that notification. Subscriptions are primarily to the running data store. Subscriptions towards the operational data store in CDB is possible, but the mechanism is slightly different see below. The first thing to do is to register in CDB which paths should be subscribed to. This is accomplished with the `CdbSubscription.subscribe(...)` method. Each registered path returns a subscription point identifier. Each subscriber can have multiple subscription points, and there can be many different subscribers. Every point is defined through a path - similar to the paths we use for read operations, with the difference that instead of fully instantiated paths to list instances we can choose to use tag paths i.e. leave out key value parts to be able to subscribe on all instances. We can subscribe either to specific leaves, or entire sub trees. Assume a YANG data model on the form of: ```yang container servers { list server { key name; leaf name { type string;} leaf ip { type inet:ip-address; } leaf port type inet:port-number; } ..... ``` Explaining this by example we get: ``` /servers/server/port ``` A subscription on a leaf. Only changes to this leaf will generate a notification. ``` /servers ``` Means that we subscribe to any changes in the subtree rooted at `/servers`. This includes additions or removals of server instances, as well as changes to already existing server instances. ``` /servers/server{www}/ip ``` Means that we only want to be notified when the server "www" changes its ip address. ``` /servers/server/ip ``` Means we want to be notified when the leaf ip is changed in any server instance. When adding a subscription point the client must also provide a priority, which is an integer. As CDB is changed, the change is part of a transaction. For example, the transaction is initiated by a commit operation from the CLI or an edit-config operation in NETCONF resulting in the running database being modified. As the last part of the transaction, CDB will generate notifications in lock-step priority order. First, all subscribers at the lowest numbered priority are handled; once they all have replied and synchronized by calling `sync(CdbSubscriptionSyncType synctype)`, the next set - at the next priority level - is handled by CDB. Not until all subscription points have been acknowledged, is the transaction complete. This implies that if the initiator of the transaction was, for example, a commit command in the CLI, the command will hang until notifications have been acknowledged. Note that even though the notifications are delivered within the transaction, a subscriber can't reject the changes (since this would break the two-phase commit protocol used by the NSO backplane towards all data providers). When a client is done subscribing, it needs to inform NSO it is ready to receive notifications. This is done by first calling `subscribeDone()`, after which the subscription socket is ready to be polled. As a subscriber has read its subscription notifications using `read()`, it can iterate through the changes that caused the particular subscription notification using the `diffIterate()` method. It is also possible to start a new read-session to the `CDB_PRE_COMMIT_RUNNING` database to read the running database as it was before the pending transaction. Subscriptions towards the operational data in CDB are similar to the above, but because the operational data store is designed for light-weight access (and thus, does not have transactions and normally avoids the use of any locks), there are several differences, in particular: * Subscription notifications are only generated if the writer obtains the subscription lock, by using the `startSession()` with the `CdbLockType.LOCKREQUEST`. In addition, when starting a session towards the operation data, we need to pass the `CdbDBType.CDB_OPERATIONAL` when starting a CDB session:\\ ``` CdbSession sess = cdb.startSession(CdbDBType.CDB_OPERATIONAL, EnumSet.of(CdbLockType.LOCK_REQUEST)); ``` * No priorities are used. * Neither the writer that generated the subscription notifications nor other writers to the same data are blocked while notifications are being delivered. However, the subscription lock remains in effect until notification delivery is complete. * The previous value for modified leaf is not available when using the `diffIterate()` method. Essentially a write operation towards the operational data store, combined with the subscription lock, takes on the role of a transaction for configuration data as far as subscription notifications are concerned. This means that if operational data updates are done with many single-element write operations, this can potentially result in a lot of subscription notifications. Thus, it is a good idea to use the multi-element `setObject()` taking an array of ConfValues which sets a complete container or `setValues()` taking an array of `ConfXMLParam` and potent of setting an arbitrary part of the model. This to keep down notifications to subscribers when updating operational data. Write operations that do not attempt to obtain the subscription lock, are allowed to proceed even during notification delivery. Therefore, it is the responsibility of the programmer to obtain the lock as needed when writing to the operational data store. E.g. if subscribers should be able to reliably read the exact data that resulted from the write that triggered their subscription, the subscription lock must always be obtained when writing that particular set of data elements. One possibility is of course to obtain the lock for all writes to operational data, but this may have an unacceptable performance impact. To view registered subscribers, use the `ncs --status` command. For details on how to use the different subscription functions, see the Javadoc for NSO Java API. The code in the example `${NCS_DIR}/examples.ncs/getting-started/developing-with-ncs/1-cdb`. illustrates three different types of CDB subscribers. * A simple Cdb config subscriber that utilizes the low-level Cdb API directly to subscribe to changes in the subtree of the configuration. * Two Navu Cdb subscribers, one subscribing to configuration changes, and one subscribing to changes in operational data. ## DP API The DP API makes it possible to create callbacks which are called when certain events occur in NSO. As the name of the API indicates, it is possible to write data provider callbacks that provide data to NSO that is stored externally. However, this is only one of several callback types provided by this API. There exist callback interfaces for the following types: * Service Callbacks - invoked for service callpoints in the YANG model. Implements service to device information mappings. See for example `${NCS_DIR}/examples.ncs/getting-started/developing-with-ncs/4-rfs-service` * Action Callbacks - invoked for a certain action in the YANG model which is defined with a callpoint directive. * Authentication Callbacks - invoked for external authentication functions. * Authorization Callbacks - invoked for external authorization of operations and data. Note, avoid this callback if possible since performance will otherwise be affected. * Data Callbacks - invoked for data provision and manipulation for certain data elements in the YANG model which is defined with a callpoint directive. * DB Callbacks - invoked for external database stores. * Range Action Callbacks - A variant of action callback where ranges are defined for the key values. * Range Data Callbacks - A variant of data callback where ranges are defined for the data values. * Snmp Inform Response Callbacks - invoked for response on Snmp inform requests on a certain element in the Yang model which is defined by a callpoint directive. * Transaction Callbacks - invoked for external participants in the two-phase commit protocol. * Transaction Validation Callbacks - invoked for external transaction validation in the validation phase of a two-phase commit. * Validation Callbacks - invoked for validation of certain elements in the YANG Model which is designed with a callpoint directive. The callbacks are methods in ordinary java POJOs. These methods are adorned with a specific Java Annotations syntax for that callback type. The annotation makes it possible to add metadata information to NSO about the supplied method. The annotation includes information about which `callType` and, when necessary, which `callpoint` the method should be invoked for. {% hint style="info" %} Only one Java object can be registered on one and the same `callpoint`. Therefore, when a new Java object registers on a `callpoint` that already has been registered, the earlier registration (and Java object) will be silently removed. {% endhint %} ### Transaction and Data Callbacks By default, NSO stores all configuration data in its CDB data store. We may wish to store and configure other data in NSO than what is defined by the NSO built-in YANG models, alternatively, we may wish to store parts of the NSO tree outside NSO (CDB) i.e. in an external database. Say, for example, that we have our customer database stored in a relational database disjunct from NSO. To implement this, we must do a number of things: We must define a callpoint somewhere in the configuration tree, and we must implement what is referred to as a data provider. Also, NSO executes all configuration changes inside transactions and if we want NSO (CDB) and our external database to participate in the same two-phase commit transactions, we must also implement a transaction callback. Altogether, it will appear as if the external data is part of the overall NSO configuration, thus the service model data can refer directly to this external data - typically to validate service instances. The basic idea for a data provider is that it participates entirely in each NSO transaction, and it is also responsible for reading and writing all data in the configuration tree below the callpoint. Before explaining how to write a data provider and what the responsibilities of a data provider are, we must explain how the NSO transaction manager drives all participants in a lock-step manner through the phases of a transaction. A transaction has a number of phases, the external data provider gets called in all the different phases. This is done by implementing a transaction callback class and then registering that class. We have the following distinct phases of an NSO transaction: * `init()`: In this phase, the transaction callback class `init()` methods get invoked. We use annotation on the method to indicate that it's the `init()` method as in:\\ ```java public class MyTransCb { @TransCallback(callType=TransCBType.INIT) public void init(DpTrans trans) throws DpCallbackException { return; } ``` \ Each different callback method we wish to register must be annotated with an annotation from `TransCBType`. \ The callback is invoked when a transaction starts, but NSO delays the actual invocation as an optimization. For a data provider providing configuration data, `init()` is invoked just before the first data-reading callback, or just before the `transLock()` callback (see below), whichever comes first. When a transaction has started, it is in a state we refer to as `READ`. NSO will, while the transaction is in the `READ` state, execute a series of read operations towards (possibly) different callpoints in the data provider. \ Any write operations performed by the management station are accumulated by NSO and the data provider doesn't see them while in the `READ` state. * `transLock()`: This callback gets invoked by NSO at the end of the transaction. NSO has accumulated a number of write operations and will now initiate the final write phases. Once the `transLock()` callback has returned, the transaction is in the `VALIDATE`state. In the `VALIDATE` state, NSO will (possibly) execute a number of read operations to validate the new configuration. Following the read operations for validations comes the invocation of one of the `writeStart()` or `transUnlock()` callbacks. * `transUnlock()`: This callback gets invoked by NSO if the validation fails or if the validation was done separately from the commit (e.g. by giving a `validate` command in the CLI). Depending on where the transaction originated, the behavior after a call to `transUnlock()` differs. If the transaction originated from the CLI, the CLI reports to the user that the configuration is invalid and the transaction remains in the `READ` state whereas if the transaction originated from a NETCONF client, the NETCONF operation fails and a NETCONF `rpc` error is reported to the NETCONF client/manager. * `writeStart()`: If the validation succeeded, the `writeStart()` callback will be called and the transaction will enter the `WRITE` state. While in `WRITE` state, a number of calls to the write data callbacks `setElem()`, `create()` and `remove()` will be performed. \ If the underlying database supports real atomic transactions, this is a good place to start such a transaction. \ The application should not modify the real running data here. If, later, the `abort()` callback is called, all write operations performed in this state must be undone. * `prepare()`: Once all write operations are executed, the `prepare()` callback is executed. This callback ensures that all participants have succeeded in writing all elements. The purpose of the callback is merely to indicate to NSO that the data provider is ok, and has not yet encountered any errors. * `abort()`: If any of the participants die or fail to reply in the `prepare()` callback, the remaining participants all get invoked in the `abort()` callback. All data written so far in this transaction should be disposed of. * `commit()`: If all participants successfully replied in their respective `prepare()` callbacks, all participants get invoked in their respective `commit()` callbacks. This is the place to make all data written by the write callbacks in `WRITE` state permanent. * `finish()`: And finally, the `finish()` callback gets invoked at the end. This is a good place to deallocate any local resources for the transaction. The `finish()` callback can be called from several different states. The following picture illustrates the conceptual state machine an NSO transaction goes through.

All callback methods are optional. If a callback method is not implemented, it is the same as having an empty callback which simply returns. Similar to how we have to register transaction callbacks, we must also register data callbacks. The transaction callbacks cover the life span of the transaction, and the data callbacks are used to read and write data inside a transaction. The data callbacks have access to what is referred to as the transaction context in the form of a `DpTrans` object. We have the following data callbacks: * `getElem()`: This callback is invoked by NSO when NSO needs to read the actual value of a leaf element. We must also implement the `getElem()` callback for the keys. NSO invokes `getElem()` on a key as an existence test.\\ We define the `getElem` callback inside a class as:\\ ```java public static class DataCb { @DataCallback(callPoint="foo", callType=DataCBType.GET_ELEM) public ConfValue getElem(DpTrans trans, ConfObject[] kp) throws DpCallbackException { ..... ``` * `existsOptional()`: This callback is called for all type less and optional elements, i.e. `presence` containers and leafs of type `empty` (unless in a union). If we have presence containers or leafs of type `empty` (unless in a union), we cannot use the `getElem()` callback to read the value of such a node, since it does not have a type. Type `empty` leafs in a union are instead read using `getElem()` callback. * An example of a data model could be:\\ ```yang container bs { presence ""; tailf:callpoint bcp; list b { key name; max-elements 64; leaf name { type string; } container opt { presence ""; leaf ii { type int32; } } leaf foo { type empty; } } } ``` The above YANG fragment has three nodes that may or may not exist and that do not have a type. If we do not have any such elements, nor any operational data lists without keys (see below), we do not need to implement the `existsOptional()` callback. \ If we have the above data model, we must implement the `existsOptional()`, and our implementation must be prepared to reply to calls of the function for the paths `/bs`, `/bs/b/opt`, and `/bs/b/foo`. The leaf `/bs/b/opt/ii` is not mandatory, but it does have a type namely `int32`, and thus the existence of that leaf will be determined through a call to the `getElem()` callback. \ The `existsOptional()` callback may also be invoked by NSO as an "existence test" for an entry in an operational data list without keys. Normally this existence test is done with a `getElem()` request for the first key, but since there are no keys, this callback is used instead. Thus, if we have such lists, we must also implement this callback, and handle a request where the keypath identifies a list entry. * `iterator()` and `getKey()`: This pair of callbacks is used when NSO wants to traverse a YANG list. The job of the `iterator()` callback is to return an `Iterator` object that is invoked by the library. For each `Object` returned by the `iterator`, the NSO library will invoke the `getKey()` callback on the returned object. The `getkey` callback shall return a `ConfKey` value. \ An alternative to the `getKey()` callback is to register the optional `getObject()` callback whose job it is to return not just the key, but the entire YANG list entry. It is possible to register both `getKey()` and `getObject()` or either. If the `getObject()` is registered, NSO will attempt to use it only when bulk retrieval is executed. We also have two additional optional callbacks that may be implemented for efficiency reasons. * `getObject()`: If this optional callback is implemented, the work of the callback is to return an entire `object`, i.e., a list instance. This is not the same `getObject()` as the one that is used in combination with the `iterator()` * `numInstances()`: When NSO needs to figure out how many instances we have of a certain element, by default NSO will repeatedly invoke the `iterator()` callback. If this callback is installed, it will be called instead. The following example illustrates an external data provider. The example is possible to run from the examples collection. It resides under `${NCS_DIR}/examples.ncs/getting-started/developing-with-ncs/6-extern-db`. The example comes with a tailor-made database - `MyDb`. That source code is provided with the example but not shown here. However, the functionality will be obvious from the method names like `newItem()`, `lock()`, `save()`, etc. Two classes are implemented, one for the transaction callbacks and another for the data callbacks. The data model we wish to incorporate into NSO is a trivial list of work items. It looks like: {% code title="Example: work.yang" %} ```yang module work { namespace "http://example.com/work"; prefix w; import ietf-yang-types { prefix yang; } import tailf-common { prefix tailf; } description "This model is used as a simple example model illustrating how to have NCS configuration data that is stored outside of NCS - i.e not in CDB"; revision 2010-04-26 { description "Initial revision."; } container work { tailf:callpoint workPoint; list item { key key; leaf key { type int32; } leaf title { type string; } leaf responsible { type string; } leaf comment { type string; } } } } ``` {% endcode %} Note the callpoint directive in the model, it indicates that an external Java callback must register itself using that name. That callback will be responsible for all data below the callpoint. To compile the `work.yang` data model and then also to generate Java code for the data model, we invoke `make all` in the example package src directory. The Makefile will compile the yang files in the package, generate Java code for those data models, and then also invoke ant in the Java src directory. The Data callback class looks as follows: {% code title="Example: DataCb Class" %} ```java @DataCallback(callPoint=work.callpoint_workPoint, callType=DataCBType.ITERATOR) public Iterator