Package 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 Details

    • NedConnectionBase

      public NedConnectionBase()

  • Method Details

    • 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 isAlive(NedWorker) instead. If the 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

    • 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 may populate TTL values for this data 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 in which case it may populate TTL values for this data as well. * If the path points to a leaf, then the NED should write the value of the leaf and indicate its TTL. * If the NED chooses to populate the entire subtree below the path and has nothing more to fetch, it should indicate so in the TTL value. The TTL value for this path will act as the default TTL. 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

    • showStatsFilter

      public void showStatsFilter(NedWorker w, int th, ConfPath[] paths) throws Exception
      When this method is invoked the NED should populate the provided transaction th with the data corresponding to the filter. This method will be invoked if the NED announces the http://tail-f.com/ns/ncs-ned/show-stats?format=path capability. The method should indicate its return status by invoking the method w.error() or w.showStatsFilterResponse()
      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
      paths - an array of ConfPath objects indicating what is requested
      Throws:
      Exception

    • showStatsFilter

      public void showStatsFilter(NedWorker w, int th, String[] xpaths) throws Exception
      When this method is invoked the NED should populate the provided transaction th with the data corresponding to the filter. This method will be invoked if the NED announces the http://tail-f.com/ns/ncs-ned/show-stats?format=xpath capability. The method should indicate its return status by invoking the method w.error() or w.showStatsFilterResponse()
      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
      xpaths - an array of xpath strings indicating what is requested
      Throws:
      Exception

    • showStatsFilter

      public void showStatsFilter(NedWorker w, int th, NedShowFilter[] filters) throws Exception
      When this method is invoked the NED should populate the provided transaction th with the data corresponding to the filter. This method will be invoked if the NED announces the http://tail-f.com/ns/ncs-ned/show-stats?format=filter capability. The method should indicate its return status by invoking the method w.error() or w.showStatsFilterResponse()
      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
      filters - an array of NedShowFilter indicating what 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() Errors like these are non-recoverable, meaning NCS will not attempt to re-establish the notification stream: w.error(NedCmd.CREATE_SUBSCRIPTION, NedErrorCode.NED_EXTERNAL_ERROR, "..."); When NedErrorCode.CONNECT_CONNECTION_REFUSED error code is provided NCS will retry to re-establish the notification stream every /devices/device/notifications/subscription/reconnect-interval seconds. w.error(NedCmd.CREATE_SUBSCRIPTION, NedErrorCode.CONNECT_CONNECTION_REFUSED, "");
      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:
      Throws:
      Exception
      See Also: