NedConnectionBase (NCS Java API Version 5.6)

Object
- com.tailf.ned.NedConnectionBase

Direct Known Subclasses:

NedCliBase, NedGenericBase
```
public abstract class NedConnectionBase
extends Object
```
A NedConnection is the interface used by the NedMux for keeping track of connections to different devices. One instance of each type should be registered with the NedMux before the NedMux is started. Specific sub-classes are defined for cli and generic neds, see NedCli and NedGeneric. The life of a specific connection to a backend device is as follows. 1 Initially an instance is created through the invocation of the create method, and a connection to the backend device is set up. 2 a mix of prepare/abort/revert/commit/persist/show/getTransId/ showStatsPath, etc 3 possibly get invocations to the isAlive() method. This method is involved when the connection is pooled. 4 possibly get an invocation to the reconnect method, and start over at 2 5 finally one of the close() methods will be involved. The connection should close the connection to the device and release all resources. If the connection is poolable then it may live in the connection pool. The state of the connection is polled by the connection pool manager using the isAlive() method.

Constructor Summary

Constructors
Constructor and Description

NedConnectionBase()

Constructors
Constructor and Description
`NedConnectionBase()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`abstract void`	`close()` This method is invoked when a connection close is forced and no NedWorker is involved.
`abstract void`	`close(NedWorker w)` This method is invoked when the connection is terminated.
`abstract void`	`command(NedWorker w, String cmdName, ConfXMLParam[] params)` This is for any optional commands on the device that are not part of the yang files config data, but is modeled as tailf:actions or rpcs in the device yang files.
`abstract void`	`commit(NedWorker w, int timeout)` This indicates that the current set of operations should be committed to the running configuration.
`int`	`connection_id()`
`void`	`createSubscription(NedWorker w, String stream, String startTime, String filter, int filterType)` This method is invoked to create a notification subscription.
`abstract String`	`device_id()` The device_id is originally provided by NCS to properly identify the device.
`NedCapability[]`	`getCapas()`
`int`	`getConnectionId()`
`NedCapability[]`	`getStatsCapas()`
`ConfXMLParam[]`	`getSystemStateData()`
`long`	`getTimeInPool()`
`NedWorker.TransactionIdMode`	`getTransactionIdMode()`
`abstract void`	`getTransId(NedWorker w)` When this method is invoked the NED should produce a transaction id that must be changed if any changes has been made to the configuration since the last time the transaction id was requested.
`boolean`	`getUseStoredCapas()`
`boolean`	`getWantRevertDiff()`
`String`	`identity()` This should return the a unique (among registered NedConnection classes) identity.
`void`	`initialize(NedWorker w)` Used for initializing an transaction.
`boolean`	`isAlive()` Deprecated. Use the method `NedConnectionBase.isAlive(NedWorker)` instead. If the `NedConnectionBase.isAlive(NedWorker)` method is implemented in the NED, this method will not be invoked. The NED must implement one of these methods.
`boolean`	`isAlive(NedWorker w)` This method is invoked to check if a connection is still alive.
`boolean`	`keepAlive(NedWorker w)` This method is invoked periodically to keep an connection alive.
`abstract String[]`	`modules()` Which YANG modules are covered by the class instance.
`abstract void`	`persist(NedWorker w)` This method is invoked when the currently committed change set should be made permanent.
`abstract void`	`reconnect(NedWorker w)` Used for resuming a connection found in the connection pool.
`void`	`setCapabilities(NedCapability[] capas)` This function is used to set the capabilities for a specific NED.
`void`	`setConnectionData(NedCapability[] capas, NedCapability[] statscapas, boolean wantRevertDiff, NedWorker.TransactionIdMode transMode)` This function is used to set the parameters of NedConnection for a specific NED.
`void`	`setPlatformData(ConfXMLParam[] platformData)` This function is used to set the platform operational data for a specific NED.
`void`	`showStats(NedWorker w, int th, ConfPath path)` Deprecated.
`void`	`showStatsList(NedWorker w, int th, ConfPath path)` Deprecated.
`void`	`showStatsPath(NedWorker w, int th, ConfPath path)` When this method is invoked depending on the node type the NED should: * if the path points to the list node or leaf-list node without specifying the key, then the NED should populate the list keys.
`abstract String`	`type()` The type is one of "cli" and "generic".
`void`	`uninitialize(NedWorker w)` If the transaction is not completed and the NED has done initialize this method is called to undo the transaction preparations.
`void`	`useStoredCapabilities()` This function is used to set the same capabilities as stored in CDB for a particular device.

Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - NedConnectionBase
```
public NedConnectionBase()
```
- Method Detail
  - getTimeInPool
```
public long getTimeInPool()
```
  - setConnectionData
```
public void setConnectionData(NedCapability[] capas,
                              NedCapability[] statscapas,
                              boolean wantRevertDiff,
                              NedWorker.TransactionIdMode transMode)
```
    This function is used to set the parameters of NedConnection for a specific NED.
    
    Parameters:
    
    capas - an array of capabilities for config data
    
    statscapas - an array of capabilities for stats data
    
    wantRevertDiff - Indicates if the NED should be provided with the edit operations needed to undo the configuration changes done in the prepare method when a transaction is aborted.
    
    transMode - Indicates the mode of Transaction ID supported by the NED. NONE if not supported. If supported, then getTransId() should be implemented. Support for Transaction IDs is required for check-sync action.
  - setCapabilities
```
public void setCapabilities(NedCapability[] capas)
```
    This function is used to set the capabilities for a specific NED. It has the same functionality as setConnectionData, but only for config capabilities. This is useful when initializing a NED instance without establishing connection to the device because other connection parameters such as stats capabilities, reverse diff and transaction id mode are irrelevant in this case
    
    Parameters:
    
    capas - an array of capabilities for config data
  - useStoredCapabilities
```
public void useStoredCapabilities()
```
    This function is used to set the same capabilities as stored in CDB for a particular device. This method can only be used when initializing a NED instance without establishing connection to the device.
  - setPlatformData
```
public void setPlatformData(ConfXMLParam[] platformData)
```
    This function is used to set the platform operational data for a specific NED. This is optional data that can be retrieved and used for instance in service code. It is possible to augment NED specific data into the platform container in the NCS device model. This method is then used to set both standard and augmented data. The ConfXMLParam[] array is expected to start with the platform tag: The following is an example of how the platformData array would be structured in an example with both the NCS standard name, model and version leaves as well as a augmented inventory list with three list elements:
```
 ConfXMLParam[] platformData =
     new ConfXMLParam[] {
         new ConfXMLParamStart("ncs", "platform"),
         new ConfXMLParamValue("ncs", "name",
                               new ConfBuf("ios")),
         new ConfXMLParamValue("ncs", "version",
                               new ConfBuf("15.0M")),
         new ConfXMLParamValue("ncs", "model",
                               new ConfBuf("7200")),

         new ConfXMLParamStart("ginv", "inventory"),
         new ConfXMLParamValue("ginv", "name",
                               new ConfBuf("lx-345")),
         new ConfXMLParamValue("ginv", "value",
                               new ConfBuf("line-card")),
         new ConfXMLParamStop("ginv", "inventory"),
         new ConfXMLParamStart("ginv", "inventory"),
         new ConfXMLParamValue("ginv", nameStr,
                               new ConfBuf("lx-1001")),
         new ConfXMLParamValue("ginv", "value",
                               new ConfBuf("line-card")),
         new ConfXMLParamStop("ginv", "inventory"),
         new ConfXMLParamStart("ginv", "inventory"),
         new ConfXMLParamValue("ginv", "name",
                               new ConfBuf("FA1209A4E389")),
         new ConfXMLParamValue("ginv", "value",
                               new ConfBuf("licence")),
         new ConfXMLParamStop("ginv", "inventory"),

         new ConfXMLParamStop("ncs", "platform")
     };

      setPlatformData(platformData);

 
```
    Parameters:
    
    platformData - An ConfXMLParam array containing operational data to be set under the platform container in the device model. Expected to start with the platform tag. If the platform container is augmented with some user specific model such data should also be part of this array to be set at connection time.
  - connection_id
```
public int connection_id()
```
  - getConnectionId
```
public int getConnectionId()
```
  - getCapas
```
public NedCapability[] getCapas()
```
  - getStatsCapas
```
public NedCapability[] getStatsCapas()
```
  - getWantRevertDiff
```
public boolean getWantRevertDiff()
```
  - getTransactionIdMode
```
public NedWorker.TransactionIdMode getTransactionIdMode()
```
  - getSystemStateData
```
public ConfXMLParam[] getSystemStateData()
```
  - getUseStoredCapas
```
public boolean getUseStoredCapas()
```
  - device_id
```
public abstract String device_id()
```
    The device_id is originally provided by NCS to properly identify the device. It is the name used for the device by NCS in the list of devices.
  - type
```
public abstract String type()
```
    The type is one of "cli" and "generic". This information is sent to NCS when the NedMux is started to let NCS know how to communicate with each device.
  - modules
```
public abstract String[] modules()
```
    Which YANG modules are covered by the class instance. This information is defined by the setConnectionData() call and is sent to NCS after initiating a new connection, or when re-establishing a connection. The modules() method is not actually used.
  - identity
```
public String identity()
```
    This should return the a unique (among registered NedConnection classes) identity. It will be used by NCS when creating new connections to control which of the registered NedConnection classes to use.
  - commit
```
public abstract void commit(NedWorker w,
                            int timeout)
                     throws Exception
```
    This indicates that the current set of operations should be committed to the running configuration. When completed the w.commitResponse() method should be invoked. Devices that does not support commit() should invoke the w.commitResponse() method without delay. On error invoke the w.error(NedCmd.COMMIT, Error, Reason) method.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    timeout - If the commit operation does not complete within 'timeout' seconds the operation should be aborted.
    
    Throws:
    
    Exception
  - persist
```
public abstract void persist(NedWorker w)
                      throws Exception
```
    This method is invoked when the currently committed change set should be made permanent. This corresponds to copying the running configuration to the startup configuration, on a running/startup device, or issuing the confirming commit operation on a device that supports that. When completed the w.persistResponse() should be invoked. On error invoke the w.error(NedCmd.PERSIST,Error, Reason) method.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - close
```
public abstract void close(NedWorker w)
                    throws Exception
```
    This method is invoked when the connection is terminated. It is not invoked when placing the connection in the connection pool. No response is required, but trace messages may be generated during the close down.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - close
```
public abstract void close()
```
    This method is invoked when a connection close is forced and no NedWorker is involved. This typically occurs when a connection is removed from the connection pool. No response or trace messages can be sent during the operation.
  - isAlive
```
@Deprecated
public boolean isAlive()
```
    Deprecated. Use the method NedConnectionBase.isAlive(NedWorker) instead. If the NedConnectionBase.isAlive(NedWorker) method is implemented in the NED, this method will not be invoked. The NED must implement one of these methods.
  - isAlive
```
public boolean isAlive(NedWorker w)
```
    This method is invoked to check if a connection is still alive. When a connection is stored in the connection pool it will periodically be polled to see if it is alive. If false is returned the connection will be closed using the close() method invocation.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
  - keepAlive
```
public boolean keepAlive(NedWorker w)
```
    This method is invoked periodically to keep an connection alive. If false is returned the connection will be closed using the close() method invocation.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
  - command
```
public abstract void command(NedWorker w,
                             String cmdName,
                             ConfXMLParam[] params)
                      throws Exception
```
    This is for any optional commands on the device that are not part of the yang files config data, but is modeled as tailf:actions or rpcs in the device yang files.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    cmdName - Name of the command (path to action?)
    
    params -
    
    Throws:
    
    Exception
  - showStats
```
@Deprecated
public void showStats(NedWorker w,
                                  int th,
                                  ConfPath path)
                           throws Exception
```
    Deprecated.
    
    This method is deprecated. New implementations should implement showStatsPath() and announce http://tail-f.com/ns/ncs-ned/show-stats-path capability. When this method is invoked the NED should write the value of the leaf, indicated by the path, to the provided transaction handler (th) using MAAPI. The worker is free to write other values as well, for example, if a larger chunk of data is read from the backend device. NCS will then not request those paths but read them directly from the transaction. Different timeouts can be provided for different paths. Note however, that all data under a subtree will be removed from the cache once the timeout triggers. The only drawback of this approach is that there is no way for the NED to indicate that a leaf does not exist other than not providing the value when directly asked for its path. Consequently, if a NED writes a larger set of data then the path requested in the method, NCS may still ask for leafs in that data-set if no value has been provided for them (due to them not existing). This method will not invoked if the NED announced capability http://tail-f.com/ns/ncs-ned/show-stats-path The method should indicate its return status by invoking the method w.error() or w.showStatsResponse()
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    th - a transaction handler that can be used in Maapi
    
    path - a ConfPath indication which element is requested
    
    Throws:
    
    Exception
  - showStatsList
```
@Deprecated
public void showStatsList(NedWorker w,
                                      int th,
                                      ConfPath path)
                               throws Exception
```
    Deprecated.
    
    This method is deprecated. New implementations should implement showStatsPath() and announce http://tail-f.com/ns/ncs-ned/show-stats-path capability. When this method is invoked the NED should write the full list to the transaction (th), but it is not required to write any data for any of the the instances. It may, however, choose to write more than the requested list, if that is convenient. Often a larger chunk of data is provided by the backend and the NED may then write that to the cache (the transaction th provided). Note that even if the data for a list is written during another invocation, NCS will still invoke the showStatsList() method to make sure that the list instances are written in full. The NED may then just respond with a new timeout and does not have to write the data again to the transaction (but it is a good idea to make sure the data is still stored in the cache (transaction th) using MAAPI. This method will not invoked if the NED announced capability http://tail-f.com/ns/ncs-ned/show-stats-path The method should indicate its return status by invoking the method w.error() or w.showStatsResponse()
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    th - a transaction handler that can be used in Maapi
    
    path - a ConfPath indication which list is requested
    
    Throws:
    
    Exception
  - showStatsPath
```
public void showStatsPath(NedWorker w,
                          int th,
                          ConfPath path)
                   throws Exception
```
    When this method is invoked depending on the node type the NED should: * if the path points to the list node or leaf-list node without specifying the key, then the NED should populate the list keys. The NED should also set the TTL on the list node or individual list instances. It may choose to write more data into the list instances in which case it should populate TTL values for the values as well. * if the path indicates a list entry, presence container, empty leaf or a leaf-list instance, then the NED should indicate the existence of this node in the data tree and return the corresponding TTL value. It may populate more data into the list instance or presence container. * if the path points to a leaf, then the NED should write the value of the leaf and indicate its TTL This method will only be invoked if the NED announced capability http://tail-f.com/ns/ncs-ned/show-stats-path The abovementioned operations should be performed on the provided transaction th. The method should indicate its return status by invoking the method w.error() or w.showStatsPathResponse()
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    th - a transaction handler that can be used in Maapi
    
    path - a ConfPath indication which list is requested
    
    Throws:
    
    Exception
  - getTransId
```
public abstract void getTransId(NedWorker w)
                         throws Exception
```
    When this method is invoked the NED should produce a transaction id that must be changed if any changes has been made to the configuration since the last time the transaction id was requested. The transaction id can either be requested from the system, or calculated by the callback, for example by calculating an MD5 checksum of the configuration text. The method should indicate its return status by invoking the method w.error() or w.getTransIdResponse() The method should be implemented if the NED claimed a NedWorker.TransactionIdMode which is not NONE in setConnectionData().
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - reconnect
```
public abstract void reconnect(NedWorker w)
                        throws Exception
```
    Used for resuming a connection found in the connection pool.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - initialize
```
public void initialize(NedWorker w)
                throws Exception
```
    Used for initializing an transaction. For instance if locking or other transaction preparations are necessary, they should be performed here. Note, that this method has a proper implementation in the base class and is therefore not necessary to override if no NED specific transaction preparations are needed. The method should indicate its return status by invoking the method w.error() or w.initializeResponse() If the NED has claimed a NedWorker.TransactionIdMode other than not NONE a transaction id must be produced in the response same as for the getTransId() call.
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, ie for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - uninitialize
```
public void uninitialize(NedWorker w)
                  throws Exception
```
    If the transaction is not completed and the NED has done initialize this method is called to undo the transaction preparations. That is restoring the NED to the state before initialize. Note, that this method has a proper implementation in the base class and is therefore not necessary to override if no NED specific operations was performed in initialize. The method should indicate its return status by invoking the method w.error() or w.uninitializeResponse()
    
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    Throws:
    
    Exception
  - createSubscription
```
public void createSubscription(NedWorker w,
                               String stream,
                               String startTime,
                               String filter,
                               int filterType)
                        throws Exception
```
    This method is invoked to create a notification subscription. After the subscription has been created the NedWorker can send notifiction messages, in the NETCONF notification format, with the w.notification() method. The method should indicate its return status by invoking the method w.error() or w.createSubscriptionResponse()
    Parameters:
    
    w - The NedWorker instance currently responsible for driving the communication between NCS and the device. This NedWorker instance should be used when communicating with NCS, i.e, for sending responses, errors, and trace messages. It is also implements the NedTracer API and can be used in, for example, the SSHSession as a tracer.
    
    stream - The notification stream to establish the subscription on.
    
    startTime - Trigger the replay feature and indicate that the replay should start at the time specified. If null, this is not a replay subscription. It is not valid to specify start times that are later than the current time. If the time specified is earlier than the log can support, the replay will begin with the earliest available notification. This parameter is of dateTime XML schema type and compliant to RFC 3339. Implementations must support time zones.
    
    filter - Indicates which subset of all possible events is of interest. The format of this parameter is the same as that of the filter parameter in the NETCONF protocol operations. If not present, all events not precluded by other parameters will be sent.
    filterType - Indicates the type of filter if it is used:
    
    NedCmd.FILTER_NONE
    NedCmd.FILTER_XPATH
    NedCmd.FILTER_SUBTREE
    Throws:
    
    Exception
    
    See Also:
    
    RFC 3339, RFC 5277, XSD-TYPES: XML Schema Part 2: Datatypes Second Edition

Class NedConnectionBase

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

NedConnectionBase

Method Detail

getTimeInPool

setConnectionData

setCapabilities

useStoredCapabilities

setPlatformData

connection_id

getConnectionId

getCapas

getStatsCapas

getWantRevertDiff

getTransactionIdMode

getSystemStateData

getUseStoredCapas

device_id

type

modules

identity

commit

persist

close

close

isAlive

isAlive

keepAlive

command

showStats

showStatsList

showStatsPath

getTransId

reconnect

initialize

uninitialize

createSubscription