com.tailf.ned

Class NedConnectionBase

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()

Method Summary

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()
abstract String	device_id() The device_id is originally provided by the 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 the NCS to properly identify the device. It is the named used for the device by the NCS in the list of devices.

type

public abstract String type()

The type is one of "cli" and "generic". This information is sent to the NCS when the NedMux is started to let the 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 the 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 the 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 the 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.

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 the 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

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 the 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

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 the 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.

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 the 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.

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 the 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.

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 the 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.

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 the 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.

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 the 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.

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 the 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

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 the 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

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 the 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 the 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