Package org.onosproject.netconf

Interface NetconfSession

  • All Known Implementing Classes:
    AbstractNetconfSession, NetconfSessionAdapter
    public interface NetconfSession
    NETCONF session object that allows NETCONF operations on top with the physical device on top of an SSH connection.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      void addDeviceOutputListener​(NetconfDeviceOutputEventListener listener)
      Add a listener to the underlying stream handler implementation.
      java.util.concurrent.CompletableFuture<java.lang.CharSequence> asyncGet()
      Retrieves running configuration and device state.
      java.util.concurrent.CompletableFuture<java.lang.CharSequence> asyncGetConfig​(DatastoreId datastore)
      Retrieves the specified configuration.
      default void checkAndReestablish()
      Checks the state of the underlying SSH session and connection and if necessary it reestablishes it.
      boolean close()
      Closes the Netconf session with the device.
      default boolean commit()
      Commits the candidate configuration the running configuration.
      boolean copyConfig​(java.lang.String netconfTargetConfig, java.lang.String newConfiguration)
      Copies the new configuration, an Url or a complete configuration xml tree to the target configuration.
      boolean copyConfig​(DatastoreId netconfTargetConfig, java.lang.String newConfiguration)
      Copies the new configuration, an Url or a complete configuration xml tree to the target configuration.
      boolean copyConfig​(DatastoreId destination, DatastoreId source)
      Copies the configuration between configuration datastores.
      boolean deleteConfig​(DatastoreId netconfTargetConfig)
      Deletes part of the specified configuration based on the filterSchema.
      java.lang.String doWrappedRpc​(java.lang.String request)
      Executes an synchronous RPC to the server and wrap the request in RPC header.
      boolean editConfig​(java.lang.String newConfiguration)
      Retrieves part of the specified configuration based on the filterSchema.
      boolean editConfig​(DatastoreId netconfTargetConfig, java.lang.String mode, java.lang.String newConfiguration)
      Retrieves part of the specified configuration based on the filterSchema.
      void endSubscription()
      Ends subscription to the device's notifications.
      java.lang.String get​(java.lang.String request)
      Retrieves the requested configuration, different from get-config.
      java.lang.String get​(java.lang.String filterSchema, java.lang.String withDefaultsMode)
      Retrieves the requested data.
      java.lang.String getConfig​(DatastoreId netconfTargetConfig)
      Deprecated.
      in 1.13.0 use async version instead.
      java.lang.String getConfig​(DatastoreId netconfTargetConfig, java.lang.String configurationFilterSchema)
      Retrieves part of the specified configuration based on the filterSchema.
      java.util.Set<java.lang.String> getDeviceCapabilitiesSet()
      Gets the capabilities of the remote Netconf device associated to this session.
      java.lang.String getSessionId()
      Gets the session ID of the Netconf session.
      default boolean lock()
      Locks the running configuration.
      boolean lock​(DatastoreId datastore)
      Locks the specified configuration.
      void removeDeviceOutputListener​(NetconfDeviceOutputEventListener listener)
      Remove a listener from the underlying stream handler implementation.
      java.util.concurrent.CompletableFuture<java.lang.String> request​(java.lang.String request)
      Deprecated.
      - 1.10.0 do not remove needs reworking
      java.lang.String requestSync​(java.lang.String request)
      Executes an synchronous RPC to the server.
      default java.lang.String requestSync​(java.lang.String request, int timeout)
      Executes an synchronous RPC to the server with specific reply TIMEOUT.
      java.util.concurrent.CompletableFuture<java.lang.String> rpc​(java.lang.String request)
      Executes an asynchronous RPC request to the server and obtains a future for it's response.
      default void setOnosCapabilities​(java.lang.Iterable<java.lang.String> capabilities)
      Sets the ONOS side capabilities.
      void startSubscription()
      Starts subscription to the device's notifications.
      void startSubscription​(java.lang.String filterSchema)
      Starts subscription to the device's notifications.
      default int timeoutConnectSec()
      Read the connect timeout that this session was created with.
      default int timeoutIdleSec()
      Read the idle timeout that this session was created with.
      default int timeoutReplySec()
      Read the reply timeout that this session was created with.
      default boolean unlock()
      Unlocks the running configuration.
      boolean unlock​(DatastoreId datastore)
      Unlocks the specified configuration.

    • Method Detail

      • request

        @Deprecated
java.util.concurrent.CompletableFuture<java.lang.String> request​(java.lang.String request)
                                                          throws NetconfException
        Deprecated.
        - 1.10.0 do not remove needs reworking
        Executes an asynchronous RPC to the server and obtains a future to be completed. The caller must ensure that the message-id in any request is unique for the session
        Parameters:
        request - the XML containing the RPC for the server.
        Returns:
        Server response or ERROR
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • rpc

        java.util.concurrent.CompletableFuture<java.lang.String> rpc​(java.lang.String request)
                                                      throws NetconfException
        Executes an asynchronous RPC request to the server and obtains a future for it's response.
        Parameters:
        request - the XML containing the RPC request for the server.
        Returns:
        Server response or ERROR
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection
        NetconfTransportException - on secure transport-layer error

      • asyncGetConfig

        java.util.concurrent.CompletableFuture<java.lang.CharSequence> asyncGetConfig​(DatastoreId datastore)
                                                                       throws NetconfException
        Retrieves the specified configuration.
        Parameters:
        datastore - to retrieve configuration from
        Returns:
        specified configuration
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • asyncGet

        java.util.concurrent.CompletableFuture<java.lang.CharSequence> asyncGet()
                                                                 throws NetconfException
        Retrieves running configuration and device state.
        Returns:
        running configuration and device state
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • get

        java.lang.String get​(java.lang.String request)
              throws NetconfException
        Retrieves the requested configuration, different from get-config.
        Parameters:
        request - the XML containing the request to the server.
        Returns:
        device running configuration
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • get

        java.lang.String get​(java.lang.String filterSchema,
                     java.lang.String withDefaultsMode)
              throws NetconfException
        Retrieves the requested data.
        Parameters:
        filterSchema - XML subtrees to include in the reply
        withDefaultsMode - with-defaults mode
        Returns:
        Server response
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • doWrappedRpc

        java.lang.String doWrappedRpc​(java.lang.String request)
                       throws NetconfException
        Executes an synchronous RPC to the server and wrap the request in RPC header.
        Parameters:
        request - the XML containing the request to the server.
        Returns:
        Server response or ERROR
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • requestSync

        java.lang.String requestSync​(java.lang.String request)
                      throws NetconfException
        Executes an synchronous RPC to the server.
        Parameters:
        request - the XML containing the RPC for the server.
        Returns:
        Server response or ERROR
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • requestSync

        default java.lang.String requestSync​(java.lang.String request,
                                     int timeout)
                              throws NetconfException
        Executes an synchronous RPC to the server with specific reply TIMEOUT.
        Parameters:
        request - the XML containing the RPC for the server.
        timeout - the reply timeout.
        Returns:
        Server response or ERROR
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • getConfig

        @Deprecated
java.lang.String getConfig​(DatastoreId netconfTargetConfig)
                    throws NetconfException
        Deprecated.
        in 1.13.0 use async version instead.
        Retrieves the specified configuration.
        Parameters:
        netconfTargetConfig - the type of configuration to retrieve.
        Returns:
        specified configuration.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • getConfig

        java.lang.String getConfig​(DatastoreId netconfTargetConfig,
                           java.lang.String configurationFilterSchema)
                    throws NetconfException
        Retrieves part of the specified configuration based on the filterSchema.
        Parameters:
        netconfTargetConfig - the type of configuration to retrieve.
        configurationFilterSchema - XML schema to filter the configuration elements we are interested in
        Returns:
        device running configuration.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • editConfig

        boolean editConfig​(java.lang.String newConfiguration)
            throws NetconfException
        Retrieves part of the specified configuration based on the filterSchema.
        Parameters:
        newConfiguration - configuration to set
        Returns:
        true if the configuration was edited correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • editConfig

        boolean editConfig​(DatastoreId netconfTargetConfig,
                   java.lang.String mode,
                   java.lang.String newConfiguration)
            throws NetconfException
        Retrieves part of the specified configuration based on the filterSchema.
        Parameters:
        netconfTargetConfig - the targetConfiguration to change
        mode - default-operation mode
        newConfiguration - configuration to set
        Returns:
        true if the configuration was edited correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • copyConfig

        boolean copyConfig​(DatastoreId destination,
                   DatastoreId source)
            throws NetconfException
        Copies the configuration between configuration datastores.

        The target configuration can't be the running one

        Parameters:
        destination - configuration datastore
        source - configuration datastore
        Returns:
        true if the configuration was copied correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • copyConfig

        boolean copyConfig​(DatastoreId netconfTargetConfig,
                   java.lang.String newConfiguration)
            throws NetconfException
        Copies the new configuration, an Url or a complete configuration xml tree to the target configuration. The target configuration can't be the running one
        Parameters:
        netconfTargetConfig - the type of configuration to retrieve.
        newConfiguration - configuration XML to set or URL tag to the configuration
        Returns:
        true if the configuration was copied correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • copyConfig

        boolean copyConfig​(java.lang.String netconfTargetConfig,
                   java.lang.String newConfiguration)
            throws NetconfException
        Copies the new configuration, an Url or a complete configuration xml tree to the target configuration. The target configuration can't be the running one
        Parameters:
        netconfTargetConfig - the type of configuration to retrieve.
        newConfiguration - configuration to set
        Returns:
        true if the configuration was copied correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • deleteConfig

        boolean deleteConfig​(DatastoreId netconfTargetConfig)
              throws NetconfException
        Deletes part of the specified configuration based on the filterSchema.
        Parameters:
        netconfTargetConfig - the name of the configuration to delete
        Returns:
        true if the configuration was copied correctly
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • startSubscription

        void startSubscription()
                throws NetconfException
        Starts subscription to the device's notifications.
        Throws:
        NetconfException - when there is a problem starting the subscription

      • startSubscription

        @Beta
void startSubscription​(java.lang.String filterSchema)
                throws NetconfException
        Starts subscription to the device's notifications.
        Parameters:
        filterSchema - XML subtrees to indicate specific notification
        Throws:
        NetconfException - when there is a problem starting the subscription

      • endSubscription

        void endSubscription()
              throws NetconfException
        Ends subscription to the device's notifications.
        Throws:
        NetconfException - when there is a problem ending the subscription

      • lock

        boolean lock​(DatastoreId datastore)
      throws NetconfException
        Locks the specified configuration.
        Parameters:
        datastore - configuration datastore to be locked
        Returns:
        true if successful.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • unlock

        boolean unlock​(DatastoreId datastore)
        throws NetconfException
        Unlocks the specified configuration.
        Parameters:
        datastore - configuration datastore to be unlocked
        Returns:
        true if successful.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • lock

        default boolean lock()
              throws NetconfException
        Locks the running configuration.
        Returns:
        true if successful.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • unlock

        default boolean unlock()
                throws NetconfException
        Unlocks the running configuration.
        Returns:
        true if successful.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • commit

        default boolean commit()
                throws NetconfException
        Commits the candidate configuration the running configuration.
        Returns:
        true if successful.
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • close

        boolean close()
       throws NetconfException
        Closes the Netconf session with the device. the first time it tries gracefully, then kills it forcefully
        Returns:
        true if closed
        Throws:
        NetconfException - when there is a problem in the communication process on the underlying connection

      • getSessionId

        java.lang.String getSessionId()
        Gets the session ID of the Netconf session.
        Returns:
        Session ID as a string.

      • getDeviceCapabilitiesSet

        java.util.Set<java.lang.String> getDeviceCapabilitiesSet()
        Gets the capabilities of the remote Netconf device associated to this session.
        Returns:
        Network capabilities as strings in a Set.
        Since:
        1.10.0

      • checkAndReestablish

        default void checkAndReestablish()
                          throws NetconfException
        Checks the state of the underlying SSH session and connection and if necessary it reestablishes it. Should be implemented, providing a default here for retrocompatibility.
        Throws:
        NetconfException - when there is a problem in reestablishing the connection or the session to the device.

      • setOnosCapabilities

        default void setOnosCapabilities​(java.lang.Iterable<java.lang.String> capabilities)
        Sets the ONOS side capabilities.
        Parameters:
        capabilities - list of capabilities ONOS has.
        Since:
        1.10.0

      • removeDeviceOutputListener

        void removeDeviceOutputListener​(NetconfDeviceOutputEventListener listener)
                         throws NetconfException
        Remove a listener from the underlying stream handler implementation.
        Parameters:
        listener - event listener.
        Throws:
        NetconfException - when this method will be called by STANDBY or NONE node.

      • timeoutConnectSec

        default int timeoutConnectSec()
        Read the connect timeout that this session was created with.
        Returns:
        timeout in seconds

      • timeoutReplySec

        default int timeoutReplySec()
        Read the reply timeout that this session was created with.
        Returns:
        timeout in seconds

      • timeoutIdleSec

        default int timeoutIdleSec()
        Read the idle timeout that this session was created with.
        Returns:
        timeout in seconds