com.tailf.jnc

Class NetconfSession

java.lang.Object

com.tailf.jnc.NetconfSession

public class NetconfSession
extends java.lang.Object

A NETCONF session class. It makes it possible to connect to a NETCONF agent using a preferred transport mechanism. After a successful connect all operations defined by the NETCONF configuration protocol [<a target="_top" href="ftp://ftp.rfc-editor.org/in-notes/rfc4741.txt">RFC 4741</a>] can be performed, e.g. get-config, edit-config and commit.

The NETCONF session class is data model agnostic. Manipulation of data is done via the Element class.

Example 1: Read and manipulate data locally

A get-config operation with an XPATH filter is sent to the agent (the agent must implement the :xpath capability). When the configuration tree is received it is edited locally and written back with an edit-config operation. The read and write is done towards the RUNNING datastore.

 // Start NETCONF session towards devices
 SSHConnection c = new SSHConnection("127.0.0.1", 5678);
 c.authenticateWithPassword("admin", "pass");
 SSHSession ssh = new SSHSession(c);
 NetconfSession dev1 = new NetconfSession(ssh);
 
 // Get system configuration from dev1 (RUNNING datastore)
 // Read is done using Xpath expression
 Element sys1 = dev1.getConfig("/system").first();
 
 // Manipulate the config tree locally
 sys1.setValue("dns", "83.100.1.1");
 sys1.setValue("gateway", "10.0.0.1");
 
 // Write back the updated element tree to the device
 dev1.editConfig(sys1);
 

Example 2: Read config using subtree filtering

A subtree filter is built using the Element.create method. The matching configuration is received and one of the elements is deleted. It is "marked" for deletion and an edit-config operation is used to actually delete the element on the agent.

 // Start NETCONF session toward our device
 SSHConnection c = new SSHConnection("127.0.0.1", 5678);
 c.authenticateWithPassword("admin", "pass");
 SSHSession ssh = new SSHSession(c);
 NetconfSession dev1 = new NetconfSession(ssh);
 
 // Create subtree filter
 Element filter = Element.create("/hosts/host[name='kalle']");
 // Read from RUNNING datastore
 Element hosts = dev1.getConfig(filter).first();
 
 // delete host 'kalle'
 // that is... mark the node for deletion
 sys1.markDelete("hosts/host[name='kalle']");
 
 // edit-config. The deleted node has the operation="delete"
 // marked on it.
 dev1.editConfig(sys1);
 

Example 3: Transaction using candidates

 try {
     // Start (NETCONF) sessions towards devices
     SSHConnection c1 = new SSHConnection("127.0.0.1", 3456);
     SSHConnection c2 = new SSHConnection("10.4.5.6", 3456);
     c1.authenticateWithPassword("admin", "pass");
     c2.authenticateWithPassword("admin", "pass");
     SSHSession ssh1 = new SSHSession(c1);
     SSHSession ssh2 = new SSHSession(c2);
     NetconfSession dev1 = new NetconfSession(ssh1);
     NetconfSession dev2 = new NetconfSession(ssh2);
 
     // take locks on CANDIDATE datastore so that we are not interrupted
     dev1.lock(NetconfSession.CANDIDATE);
     dev2.lock(NetconfSession.CANDIDATE);
 
     // reset candidates so that CANDIDATE is an exact copy of running
     dev1.copyConfig(NetconfSession.RUNNING, NetconfSession.CANDIDATE);
     dev2.copyConfig(NetconfSession.RUNNING, NetconfSession.CANDIDATE);
 
     // Get system configuration from dev1
     Element sys1 = dev1.getConfig("/system").first();
 
     // Manipulate element trees locally
     sys1.setValue("dns", "83.100.1.1");
     sys1.setValue("gateway", "10.0.0.1");
 
     // Write back the updated element tree to both devices
     dev1.editConfig(NetconfSession.CANDIDATE, sys1);
     dev2.editConfig(NetconfSession.CANDIDATE, sys1);
 
     // candidates are now updated
     dev1.confirmedCommit(60);
     dev2.confirmedCommit(60);
 
     // now commit them
     dev1.commit();
     dev2.commit();
 
     dev1.unlock(NetconfSession.CANDIDATE);
     dev2.unlock(NetconfSession.CANDIDATE);
 
 } catch (Exception e) {
     // Devices will rollback within 1 min
 
 }
 

See Also:

Element

Field Summary

Fields

Modifier and Type	Field and Description
static int	CANDIDATE The CANDIDATE datastore.
protected Capabilities	capabilities The capability elements for the session.
static java.lang.String	CONFIG_GT
static int	CONTINUE_ON_ERROR Value for error option.
static java.lang.String	COPY_CONFIG_GT
static java.lang.String	EDIT_CONFIG_GT
static java.lang.String	FILTER
static java.lang.String	FILTER_GT
static java.lang.String	GET_CONFIG_GT
static java.lang.String	GET_GT
static int	MERGE Value for default operation.
static int	NONE Value for default operation.
static int	NOT_SET Value is not set.
static int	REPLACE Value for default operation.
static int	ROLLBACK_ON_ERROR Value for error option.
static int	RUNNING The RUNNING datastore.
int	sessionId Session identifier.
static int	SET Value for test option.
static java.lang.String	SOURCE_GT
static java.lang.String	START_TIME_GT
static int	STARTUP The STARTUP datastore.
static int	STOP_ON_ERROR Value for error option.
static java.lang.String	STOP_TIME_GT
static java.lang.String	STREAM_GT
static java.lang.String	TARGET_GT
static int	TEST_ONLY Value for test option.
static int	TEST_THEN_SET Value for test option.
static java.lang.String	VALIDATE_GT

Constructor Summary

Constructors

Constructor and Description
NetconfSession() Creates a new session object.
NetconfSession(Transport transport) Creates a new session object using the given transport object.
NetconfSession(Transport transport, XMLParser parser) Creates a new session object using the given transport object.

Method Summary

Modifier and Type	Method and Description
Element	action(Element data) Action capability.
NodeSet	callRpc(Element data) Calls rpc method.
void	closeSession() Requests graceful termination of a NETCONF session.
void	commit() When a candidate configuration's content is complete, the configuration data can be committed, publishing the data set to the rest of the device and requesting the device to conform to the behavior described in the new configuration.
void	confirmedCommit(int timeout) The :confirmed-commit capability indicates that the server supports the confirmed commit.
void	copyConfig(Element sourceTree, int target) Creates or replace an entire configuration datastore with the contents of another complete configuration datastore.
void	copyConfig(Element sourceTree, java.lang.String targetUrl) Same as copyConfig(Element,int) but uses an url as target.
void	copyConfig(int source, int target) Creates or replace an entire configuration datastore with the contents of another complete configuration datastore.
void	copyConfig(int source, java.lang.String targetUrl) Same as copyConfig(int,int) but uses an url as target.
void	copyConfig(NodeSet sourceTrees, int target) variant of copyConfig() that takes a NodeSet as param
void	copyConfig(NodeSet sourceTrees, java.lang.String targetUrl)
void	copyConfig(java.lang.String sourceUrl, int target) Same as copyConfig(int,int) but uses an url as the source.
void	copyConfig(java.lang.String sourceUrl, java.lang.String targetUrl) Same as copyConfig(int,int) but uses an url as target and an url as a source.
void	createSubscription() The notification capability makes it possible to receive notifications specified in a subscription.
void	createSubscription(java.lang.String stream) The notification capability makes it possible to receive notifications specified in a subscription.
void	createSubscription(java.lang.String streamName, NodeSet eventFilter, java.lang.String startTime, java.lang.String stopTime) The notification capability makes it possible to receive notifications specified in a subscription.
void	createSubscription(java.lang.String streamName, java.lang.String eventFilter, java.lang.String startTime, java.lang.String stopTime) Same as createSubscription(String,NodeSet,String,String) except a filter in xpath format can be given instead of a subtree filter.
void	deleteConfig(int datastore) Deletes a configuration datastore.
void	deleteConfig(java.lang.String targetUrl) Deletes a configuration target url.
void	discardChanges() If the client decides that the candidate configuration should not be committed, the <discard-changes> operation can be used to revert the candidate configuration to the current running configuration.
void	editConfig(Element configTree) Edits the configuration.
void	editConfig(int datastore, Element configTree) Edits the configuration.
void	editConfig(int datastore, NodeSet configTrees)
void	editConfig(int datastore, java.lang.String url) Edits the configuration.
void	editConfig(NodeSet configTrees) Edits the configuration.
protected int	encode_rpc_begin(Transport out) Encodes the RPC header and writes it to the provided output transport.
protected int	encode_rpc_begin(Transport out, Attribute attr) Encodes the RPC header and writes it to the provided output transport.
protected void	encode_rpc_end(Transport out) Closes the rpc tag.
NodeSet	get() Retrieves running configuration and device state information.
NodeSet	get(Element subtreeFilter) Retrieves running configuration and device state information.
NodeSet	get(java.lang.String xpath) Retrieves running configuration and device state information.
Capabilities	getCapabilities() Return a Capabilities object with the NETCONF capabilities for this session.
NodeSet	getConfig() Gets the device configuration data.
NodeSet	getConfig(Element subtreeFilter) Gets the device configuration data specified by subtree filtering.
NodeSet	getConfig(int datastore) Gets the device configuration data.
NodeSet	getConfig(int datastore, Element subtreeFilter) Gets the device configuration data specified by subtree filtering.
NodeSet	getConfig(int datastore, java.lang.String xpath) Gets the device configuration data specified by an xpath filter.
NodeSet	getConfig(java.lang.String xpath) Gets the device configuration data specified by an xpath expression.
NodeSet	getStreams() Method to get the available streams from the agent.
Transport	getTransport() Returns the transport object used by this session.
boolean	hasCapability(java.lang.String uri) Check if a specific named capability is supported.
protected void	hello() Capabilities are advertised in messages sent by each peer during session establishment.
void	killSession(int sessionId) Force the termination of a NETCONF session.
void	lock(int datastore) The lock operation allows the client to lock the configuration system of a device.
int	lockPartial(java.lang.String select) Same as #lockPartial(int,String[]) except it only takes one selection as argument.
int	lockPartial(java.lang.String[] select) The partial-lock operation allows the client to lock a portion of a data store.
Element	readReply() Reads a rpc reply from NETCONF.
Element	receiveNotification() Receive one notification.
protected Element	recv_rpc_reply_ok(java.lang.String mid) Receive from session
Element	rpc(Element request) The NETCONF protocol uses a remote procedure call (RPC) paradigm.
Element	rpc(java.lang.String request) The NETCONF protocol uses a remote procedure call (RPC) paradigm.
int	sendRequest(Element request) Sends rpc request and return.
int	sendRequest(java.lang.String request) Sends rpc request and return.
protected void	setCapability(java.lang.String capability) Set a proprietary capability.
void	setDefaultOperation(int op) Specifies the default operation for all edit-config operations for the session.
void	setErrorOption(int erroroption) Specifies the error-option for the edit-config operations for the session.
void	setTestOption(int testoption) Specifies the test-option parameter for the edit-config operations for the session.
void	setTransport(Transport transport) Sets the transport used by this session.
void	unlock(int datastore) The unlock operation is used to release a configuration lock, previously obtained with the lock(int) operation.
void	unlockPartial(int lockId) The unlock operation is used to release a configuration lock, previously obtained with the lock(int) operation.
void	validate(Element configTree) This protocol operation validates the contents of the specified configuration.
void	validate(int datastore) This protocol operation validates the given datastore.
void	validate(java.lang.String url) This protocol operation validates the given URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GET_CONFIG_GT

public static final java.lang.String GET_CONFIG_GT

See Also:

Constant Field Values

SOURCE_GT

public static final java.lang.String SOURCE_GT

See Also:

Constant Field Values

FILTER_GT

public static final java.lang.String FILTER_GT

See Also:

Constant Field Values

FILTER

public static final java.lang.String FILTER

See Also:

Constant Field Values

GET_GT

public static final java.lang.String GET_GT

See Also:

Constant Field Values

EDIT_CONFIG_GT

public static final java.lang.String EDIT_CONFIG_GT

See Also:

Constant Field Values

TARGET_GT

public static final java.lang.String TARGET_GT

See Also:

Constant Field Values

CONFIG_GT

public static final java.lang.String CONFIG_GT

See Also:

Constant Field Values

COPY_CONFIG_GT

public static final java.lang.String COPY_CONFIG_GT

See Also:

Constant Field Values

VALIDATE_GT

public static final java.lang.String VALIDATE_GT

See Also:

Constant Field Values

STREAM_GT

public static final java.lang.String STREAM_GT

See Also:

Constant Field Values

START_TIME_GT

public static final java.lang.String START_TIME_GT

See Also:

Constant Field Values

STOP_TIME_GT

public static final java.lang.String STOP_TIME_GT

See Also:

Constant Field Values

RUNNING

public static final int RUNNING

The RUNNING datastore.

See Also:

Constant Field Values

STARTUP

public static final int STARTUP

The STARTUP datastore.

See Also:

Constant Field Values

CANDIDATE

public static final int CANDIDATE

The CANDIDATE datastore.

See Also:

Constant Field Values

sessionId

public int sessionId

Session identifier. Received from the initial hello message.

capabilities

protected Capabilities capabilities

The capability elements for the session. Retrieved from hello message upon connect.

NOT_SET

public static final int NOT_SET

Value is not set.

See Also:

Constant Field Values

MERGE

public static final int MERGE

Value for default operation.

See Also:

setDefaultOperation(int), Constant Field Values

REPLACE

public static final int REPLACE

Value for default operation.

See Also:

setDefaultOperation(int), Constant Field Values

NONE

public static final int NONE

Value for default operation.

See Also:

setDefaultOperation(int), Constant Field Values

SET

public static final int SET

Value for test option.

See Also:

setTestOption(int), Constant Field Values

TEST_THEN_SET

public static final int TEST_THEN_SET

Value for test option.

See Also:

setTestOption(int), Constant Field Values

TEST_ONLY

public static final int TEST_ONLY

Value for test option.

See Also:

setTestOption(int), Constant Field Values

STOP_ON_ERROR

public static final int STOP_ON_ERROR

Value for error option.

See Also:

setErrorOption(int), Constant Field Values

CONTINUE_ON_ERROR

public static final int CONTINUE_ON_ERROR

Value for error option.

See Also:

setErrorOption(int), Constant Field Values

ROLLBACK_ON_ERROR

public static final int ROLLBACK_ON_ERROR

Value for error option.

See Also:

setErrorOption(int), Constant Field Values

Constructor Detail

NetconfSession

public NetconfSession(Transport transport)
               throws JNCException,
                      java.io.IOException

Creates a new session object using the given transport object. This will initialize the transport and send out an initial hello message to the server.

Parameters:

transport - Transport object

Throws:

JNCException

java.io.IOException

See Also:

SSHSession

NetconfSession

public NetconfSession(Transport transport,
                      XMLParser parser)
               throws JNCException,
                      java.io.IOException

Creates a new session object using the given transport object. This will initialize the transport and send out an initial hello message to the server.

Parameters:

transport - Transport object

parser - XML parser object If we are using the confm package to create and manipulate objects we must instantiate the parser as an com.tailf.confm.XMLParser() If we fail to do that, we get the XMLParser class from the inm package which always only returns Element objects as opposed to the XMLParser from the confm package which can return objects matching the confm generated classes. If we use the confm Device class to create our netconf sessions, this is all done automatically, whereas if we create our netconf sessions ourselves, _and_ also want to retrieve real confm objects we must:

 SSHConnection ssh = new SSHConnection("127.0.0.1", 2022);
 ssh.authenticateWithPassword("admin", "admin");
 Transport tr = new SSHSession(ssh);
 NetconfSession sess = new NetconfSession(tr, new com.tailf.confm.XMLParser());
 

Throws:

JNCException

java.io.IOException

See Also:

SSHSession

NetconfSession

public NetconfSession()
               throws JNCException

Creates a new session object. The session need to be given a transport object with setTransport(Transport) and an initial hello needs to be sent to advertise capabilities.

Throws:

JNCException

Method Detail

getCapabilities

public Capabilities getCapabilities()

Return a Capabilities object with the NETCONF capabilities for this session. The capabilities are received from the hello message from the server.

hasCapability

public boolean hasCapability(java.lang.String uri)

Check if a specific named capability is supported.

Parameters:

uri - Name of capability to check

setTransport

public void setTransport(Transport transport)

Sets the transport used by this session.

Parameters:

transport - Transport object, for example SSHSession

getTransport

public Transport getTransport()

Returns the transport object used by this session.

See Also:

SSHSession

hello

protected void hello()
              throws JNCException,
                     java.io.IOException

Capabilities are advertised in messages sent by each peer during session establishment. When the NETCONF session is opened, each peer (both client and server) must send a hello element containing a list of that peer's capabilities. Each peer must send at least the base NETCONF capability, "urn:ietf:params:netconf:base:1.0".

This method will send an initial hello to the output stream and await the hello from the server.

Used from the constructor NetconfSession(Transport).

Throws:

JNCException

java.io.IOException

rpc

public Element rpc(java.lang.String request)
            throws java.io.IOException,
                   JNCException

The NETCONF protocol uses a remote procedure call (RPC) paradigm. A client encodes an RPC in XML and sends it to a server using a secure, connection-oriented session. The server responds with a reply encoded in XML.

This method may be used for sending an XML string over the connected session and receiving a reply.

The reply is parsed into an element tree.

Parameters:

request - XML encoded NETCONF request

Throws:

java.io.IOException

JNCException

rpc

public Element rpc(Element request)
            throws java.io.IOException,
                   JNCException

The NETCONF protocol uses a remote procedure call (RPC) paradigm. A client encodes an RPC in XML and sends it to a server using a secure, connection-oriented session. The server responds with a reply encoded in XML.

This method may be used for sending an XML element tree the connected session and receiving a reply.

The reply is parsed into an element tree.

Parameters:

request - XML element tree

Throws:

java.io.IOException

JNCException

sendRequest

public int sendRequest(java.lang.String request)
                throws java.io.IOException

Sends rpc request and return. This method may be used for sending an XML string over the connected session. To receive a reply the readReply() should be used.

Note that the return value reflects the last request-id generated by the NetconfSession methods, and is not checked against the request-id in the request parameter.

Parameters:

request - XML encoded NETCONF request

Throws:

java.io.IOException

sendRequest

public int sendRequest(Element request)
                throws java.io.IOException,
                       JNCException

Sends rpc request and return. This method may be used for sending an XML element tree over the connected session. To receive a reply the readReply() should be used.

Note that the return value reflects the last request-id generated by the NetconfSession methods, and is not checked against the request-id in the request parameter.

Parameters:

request - Element tree

Throws:

java.io.IOException

JNCException

readReply

public Element readReply()
                  throws java.io.IOException,
                         JNCException

Reads a rpc reply from NETCONF. Preforms a blocking read.

The reply is parsed into an element tree.

Throws:

java.io.IOException

JNCException

See Also:

sendRequest(Element)

getConfig

public NodeSet getConfig(Element subtreeFilter)
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data specified by subtree filtering.

Parameters:

subtreeFilter - A subtree filter

Throws:

JNCException

java.io.IOException

getConfig

public NodeSet getConfig()
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data.

Throws:

JNCException

java.io.IOException

getConfig

public NodeSet getConfig(int datastore)
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data.

Throws:

JNCException

java.io.IOException

callRpc

public NodeSet callRpc(Element data)
                throws JNCException,
                       java.io.IOException

Calls rpc method.

Throws:

JNCException

java.io.IOException

getConfig

public NodeSet getConfig(java.lang.String xpath)
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data specified by an xpath expression. The :xpath capability must be supported by the server.

Parameters:

xpath - XPath expression

Throws:

JNCException

java.io.IOException

getConfig

public NodeSet getConfig(int datastore,
                         Element subtreeFilter)
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data specified by subtree filtering.

Parameters:

datastore - The datastore. One of RUNNING, CANDIDATE, STARTUP

subtreeFilter - A subtree filter

Throws:

JNCException

java.io.IOException

getConfig

public NodeSet getConfig(int datastore,
                         java.lang.String xpath)
                  throws JNCException,
                         java.io.IOException

Gets the device configuration data specified by an xpath filter.

Parameters:

datastore - The datastore. One of RUNNING, CANDIDATE, STARTUP

xpath - XPath expression

Throws:

JNCException

java.io.IOException

get

public NodeSet get()
            throws JNCException,
                   java.io.IOException

Retrieves running configuration and device state information.

Throws:

JNCException

java.io.IOException

get

public NodeSet get(Element subtreeFilter)
            throws JNCException,
                   java.io.IOException

Retrieves running configuration and device state information.

Parameters:

subtreeFilter - A subtree filter

Throws:

JNCException

java.io.IOException

get

public NodeSet get(java.lang.String xpath)
            throws JNCException,
                   java.io.IOException

Retrieves running configuration and device state information. The :xpath capability must be supported by the server.

Parameters:

xpath - An xpath epxression.

Throws:

JNCException

java.io.IOException

editConfig

public void editConfig(Element configTree)
                throws JNCException,
                       java.io.IOException

Edits the configuration. The edit-config operation loads all or part of a specified configuration to the RUNNING target datatore.

Parameters:

configTree - Configuration tree

Throws:

JNCException

java.io.IOException

editConfig

public void editConfig(NodeSet configTrees)
                throws JNCException,
                       java.io.IOException

Edits the configuration. If we have multiple top elements in our configuration schema (YANG model) we must send a NodeSet as opposed to an Element to the device

Throws:

JNCException

java.io.IOException

editConfig

public void editConfig(int datastore,
                       Element configTree)
                throws JNCException,
                       java.io.IOException

Edits the configuration. The edit-config operation loads all or part of a specified configuration to the specified target configuration.

Parameters:

datastore - The target datastore. One of RUNNING, CANDIDATE, STARTUP

configTree - The config tree to edit.

Throws:

JNCException

java.io.IOException

editConfig

public void editConfig(int datastore,
                       NodeSet configTrees)
                throws JNCException,
                       java.io.IOException

Throws:

JNCException

java.io.IOException

editConfig

public void editConfig(int datastore,
                       java.lang.String url)
                throws JNCException,
                       java.io.IOException

Edits the configuration. The <edit-config> operation loads all or part of a specified configuration to the specified target configuration.

Parameters:

datastore - The target datastore. One of RUNNING, CANDIDATE, STARTUP

url - The source url.

Throws:

JNCException

java.io.IOException

setDefaultOperation

public void setDefaultOperation(int op)

Specifies the default operation for all edit-config operations for the session. The default value for the default-operation parameter is "merge", unless a value is set by invoking this method.

The default-operation parameter is optional, but if provided, it must have one of the following values:

• MERGE: The configuration data is merged with the configuration at the corresponding level in the target datastore.
• REPLACE: The configuration data completely replaces the configuration in the target datastore. This is useful for loading previously saved configuration data.
• NONE: The target datastore is unaffected by the configuration parameter, unless and until the incoming configuration data uses the "operation" attribute to request a different operation. If the configuration parameter contains data for which there is not a corresponding level in the target datastore, an "rpc-error" is returned with an "error-tag" value of data-missing. Using "none" allows operations like "delete" to avoid unintentionally creating the parent hierarchy of the element to be deleted.

Parameters:

op - One of MERGE, REPLACE, NONE.

setTestOption

public void setTestOption(int testoption)

Specifies the test-option parameter for the edit-config operations for the session. The test-option element may be specified only if the device advertises the :validate capability.

The test-option element has one of the following values:

• TEST_THEN_SET: Perform a validation test before attempting to set. If validation errors occur, do not perform the "edit-config" operation. This is the default test-option.
• SET: Perform a set without a validation test first.
• TEST_ONLY: Only test. (Option is not supported in the standard.)

Parameters:

testoption - One of SET, TEST_THEN_SET, TEST_ONLY

setErrorOption

public void setErrorOption(int erroroption)

Specifies the error-option for the edit-config operations for the session. The error-option element has one of the following values:

• STOP_ON_ERROR: Abort the edit-config operation on first error. This is the default error-option.
• CONTINUE_ON_ERROR: Continue to process configuration data on error; error is recorded, and negative response is generated if any errors occur.
• ROLLBACK_ON_ERROR: If an error condition occurs such that an error severity "rpc-error" element is generated, the server will stop processing the edit-config operation and restore the specified configuration to its complete state at the start of this edit-config operation. This option requires the server to support the :rollback-on-error capability.

Parameters:

erroroption - One of STOP_ON_ERROR, CONTINUE_ON_ERROR, ROLLBACK_ON_ERROR

copyConfig

public void copyConfig(Element sourceTree,
                       int target)
                throws JNCException,
                       java.io.IOException

Creates or replace an entire configuration datastore with the contents of another complete configuration datastore. If the target datastore exists, it is overwritten. Otherwise, a new one is created, if allowed.

Parameters:

sourceTree - A config tree

target - The target datastore

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(NodeSet sourceTrees,
                       int target)
                throws JNCException,
                       java.io.IOException

variant of copyConfig() that takes a NodeSet as param

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(Element sourceTree,
                       java.lang.String targetUrl)
                throws JNCException,
                       java.io.IOException

Same as copyConfig(Element,int) but uses an url as target. Only possible if :url capability is supported.

Parameters:

sourceTree - A config tree

targetUrl - The target URL.

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(NodeSet sourceTrees,
                       java.lang.String targetUrl)
                throws JNCException,
                       java.io.IOException

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(int source,
                       int target)
                throws JNCException,
                       java.io.IOException

Creates or replace an entire configuration datastore with the contents of another complete configuration datastore. If the target datastore exists, it is overwritten. Otherwise, a new one is created, if allowed.

Parameters:

source - The source datastore

target - The target datastore

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(int source,
                       java.lang.String targetUrl)
                throws JNCException,
                       java.io.IOException

Same as copyConfig(int,int) but uses an url as target. Only possible if :url capability is supported.

Parameters:

source - The datastore to be used as source

targetUrl - The target URL.

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(java.lang.String sourceUrl,
                       java.lang.String targetUrl)
                throws JNCException,
                       java.io.IOException

Same as copyConfig(int,int) but uses an url as target and an url as a source. Only possible if :url capability is supported.

Parameters:

sourceUrl - The source URL.

targetUrl - The target URL.

Throws:

JNCException

java.io.IOException

copyConfig

public void copyConfig(java.lang.String sourceUrl,
                       int target)
                throws JNCException,
                       java.io.IOException

Same as copyConfig(int,int) but uses an url as the source. Only possible if :url capability is supported.

Parameters:

sourceUrl - The source URL.

target - The target datastore

Throws:

JNCException

java.io.IOException

deleteConfig

public void deleteConfig(int datastore)
                  throws JNCException,
                         java.io.IOException

Deletes a configuration datastore. The <running> configuration datastore cannot be deleted.

Parameters:

datastore - Datastore to be deleted

Throws:

JNCException

java.io.IOException

deleteConfig

public void deleteConfig(java.lang.String targetUrl)
                  throws JNCException,
                         java.io.IOException

Deletes a configuration target url.

Parameters:

targetUrl - Name of configuration target url to be deleted.

Throws:

JNCException

java.io.IOException

lock

public void lock(int datastore)
          throws JNCException,
                 java.io.IOException

The lock operation allows the client to lock the configuration system of a device. Such locks are intended to be short-lived and allow a client to make a change without fear of interaction with other NETCONF clients, non-NETCONF clients (e.g., SNMP and command line interface (CLI) scripts), and human users.

An attempt to lock the configuration must fail if an existing session or other entity holds a lock on any portion of the lock target.

Parameters:

datastore - The datastore to lock

Throws:

JNCException

java.io.IOException

unlock

public void unlock(int datastore)
            throws JNCException,
                   java.io.IOException

The unlock operation is used to release a configuration lock, previously obtained with the lock(int) operation.

Parameters:

datastore - The target datastore to unlock

Throws:

JNCException

java.io.IOException

lockPartial

public int lockPartial(java.lang.String[] select)
                throws JNCException,
                       java.io.IOException

The partial-lock operation allows the client to lock a portion of a data store. The portion to lock is specified by an array of selection strings which can be XPath filters (if the server supports XPath) or a simple paths to instance idenfifiers.

If the selection filters are XPath expressions they are evaluated only once at lock time, thereafter the scope of the lock is maintained as a set of nodes. If the configuration data is later altered in a way that would make the original XPath filter expressions evaluate to a different set of nodes, this does not affect the scope of the partial lock. XPath is only used for the creation of the partial lock. Conceptually the scope of the lock is defined by the returned nodeset and not by the XPath expression.

If a node is locked by a session, only that same session will be able to modify that node or any node in the subtree underneath it.

If a top level node of a locked subtree is deleted, any other session can recreate it, as it is not covered by the lock anymore. The lock operation allows the client to lock the configuration system of a device. Such locks are intended to be short-lived and allow a client to make a change without fear of interaction with other NETCONF clients, non-NETCONF clients (e.g., SNMP and command line interface (CLI) scripts), and human users.

An attempt to lock the configuration must fail if an existing session or other entity holds a lock on any portion of the lock target.

Parameters:

datastore - datastore of which a part will be locked

select - An array of selection filters

Returns:

A unique lock reference which should be used to unlockPartial()

Throws:

JNCException

java.io.IOException

lockPartial

public int lockPartial(java.lang.String select)
                throws JNCException,
                       java.io.IOException

Same as #lockPartial(int,String[]) except it only takes one selection as argument.

Throws:

JNCException

java.io.IOException

See Also:

#lockPartial(int,String[])

unlockPartial

public void unlockPartial(int lockId)
                   throws JNCException,
                          java.io.IOException

The unlock operation is used to release a configuration lock, previously obtained with the lock(int) operation.

Parameters:

lockId - Previously received lock identifier from #lockPartial(int,String[])

Throws:

JNCException

java.io.IOException

commit

public void commit()
            throws JNCException,
                   java.io.IOException

When a candidate configuration's content is complete, the configuration data can be committed, publishing the data set to the rest of the device and requesting the device to conform to the behavior described in the new configuration.

To commit the candidate configuration as the device's new current configuration, use the commit operation.

The commit operation instructs the device to implement the configuration data contained in the candidate configuration. If the device is unable to commit all of the changes in the candidate configuration datastore, then the running configuration must remain unchanged. If the device does succeed in committing, the running configuration must be updated with the contents of the candidate configuration.

If the system does not have the :candidate capability, the commit operation is not available.

Throws:

JNCException

java.io.IOException

confirmedCommit

public void confirmedCommit(int timeout)
                     throws JNCException,
                            java.io.IOException

The :confirmed-commit capability indicates that the server supports the confirmed commit.

A confirmed commit operation must be reverted if a follow-up commit (called the "confirming commit") is not issued within 600 seconds (10 minutes). The timeout period can be adjusted with the timeout parameter.

If the session issuing the confirmed commit is terminated for any reason before the confirm timeout expires, the server must restore the configuration to its state before the confirmed commit was issued.

If the device reboots for any reason before the confirm timeout expires, the server must restore the configuration to its state before the confirmed commit was issued.

If a confirming commit is not issued, the device will revert its configuration to the state prior to the issuance of the confirmed commit. Note that any commit operation, including a commit which introduces additional changes to the configuration, will serve as a confirming commit. Thus to cancel a confirmed commit and revert changes without waiting for the confirm timeout to expire, the manager can explicitly restore the configuration to its state before the confirmed commit was issued.

For shared configurations, this feature can cause other configuration changes (for example, via other NETCONF sessions) to be inadvertently altered or removed, unless the configuration locking feature is used (in other words, the lock is obtained before the edit-config operation is started). Therefore, it is strongly suggested that in order to use this feature with shared configuration databases, configuration locking should also be used.

Parameters:

timeout - Time that server will wait for confirming commit before reverting config

Throws:

JNCException

java.io.IOException

discardChanges

public void discardChanges()
                    throws JNCException,
                           java.io.IOException

If the client decides that the candidate configuration should not be committed, the <discard-changes> operation can be used to revert the candidate configuration to the current running configuration.

Throws:

JNCException

java.io.IOException

closeSession

public void closeSession()
                  throws JNCException,
                         java.io.IOException

Requests graceful termination of a NETCONF session.

When a NETCONF server receives a close-session request, it will gracefully close the session. The server will release any locks and resources associated with the session and gracefully close any associated connections.

Throws:

JNCException

java.io.IOException

killSession

public void killSession(int sessionId)
                 throws JNCException,
                        java.io.IOException

Force the termination of a NETCONF session.

When a NETCONF entity receives a kill-session request for an open session, it will abort any operations currently in process, release any locks and resources associated with the session, and close any associated connections.

Session identifier of the NETCONF session to be terminated, if this value is the current session ID a JNCException will be thrown.

Parameters:

sessionId - The id of the session to terminate

Throws:

JNCException

java.io.IOException

validate

public void validate(Element configTree)
              throws JNCException,
                     java.io.IOException

This protocol operation validates the contents of the specified configuration.

Parameters:

configTree - configuration tree to validate

Throws:

JNCException

java.io.IOException

validate

public void validate(int datastore)
              throws java.io.IOException,
                     JNCException

This protocol operation validates the given datastore. For example the CANDIDATE datastore.

Parameters:

datastore - The datastore to validate

Throws:

java.io.IOException

JNCException

validate

public void validate(java.lang.String url)
              throws java.io.IOException,
                     JNCException

This protocol operation validates the given URL. The url may for example be a file "file://incoming.conf" then file must be supported by the :url capability.

Parameters:

url - The source url to validate

Throws:

java.io.IOException

JNCException

createSubscription

public void createSubscription()
                        throws java.io.IOException,
                               JNCException

The notification capability makes it possible to receive notifications specified in a subscription. The :notification capability must be supported by the server.

Throws:

java.io.IOException

JNCException

See Also:

createSubscription(String,String,String,String)

createSubscription

public void createSubscription(java.lang.String stream)
                        throws java.io.IOException,
                               JNCException

The notification capability makes it possible to receive notifications specified in a subscription. The :notification capability must be supported by the server.

Subscribe on specified stream name.

Parameters:

stream - The name of the stream or null if all streams of events are of interest.

Throws:

java.io.IOException

JNCException

See Also:

createSubscription(String,String,String,String)

createSubscription

public void createSubscription(java.lang.String streamName,
                               NodeSet eventFilter,
                               java.lang.String startTime,
                               java.lang.String stopTime)
                        throws java.io.IOException,
                               JNCException

The notification capability makes it possible to receive notifications specified in a subscription. The :notification capability must be supported by the server.

An optional parameter, stream, that indicates which stream of events is of interest. If not present, events in the default NETCONF stream will be sent.

An optional parameter, filter, that indicates which subset of all possible events is of interest. If not present, all events not precluded by other parameters will be sent.

A parameter, startTime, used to trigger the replay feature and indicate that the replay should start at the time specified. If startTime is not present, this is not a replay subscription. It is not valid to specify start times that are later than the current time. If the startTime specified is earlier than the log can support, the replay will begin with the earliest available notification. The time is specified in dateTime format.

An optional parameter, stopTime, used with the optional replay feature to indicate the newest notifications of interest. If stop time is not present, the notifications will continue until the subscription is terminated. Must be used with and be later than startTime. Values of stopTime in the future are valid. The time is specified in dateTime format.

Parameters:

streamName - The name of the stream or null

eventFilter - a subtree filter - list of events, or null

startTime - a dateTime string specifying the replay start, or null if the subscription is not a replay subscription

stopTime - a dateTime string specifying the stop of replay, or null if the subscription is not a replay subscription or infinite subscription is desired

Throws:

java.io.IOException

JNCException

See Also:

receiveNotification()

createSubscription

public void createSubscription(java.lang.String streamName,
                               java.lang.String eventFilter,
                               java.lang.String startTime,
                               java.lang.String stopTime)
                        throws java.io.IOException,
                               JNCException

Same as createSubscription(String,NodeSet,String,String) except a filter in xpath format can be given instead of a subtree filter.

Parameters:

streamName - The name of the stream or null

eventFilter - a filter xpath expression, or null

startTime - a dateTime string specifying the replay start, or null

stopTime - a dateTime string specifying the stop of replay, or null

Throws:

java.io.IOException

JNCException

See Also:

receiveNotification()

getStreams

public NodeSet getStreams()
                   throws JNCException,
                          java.io.IOException

Method to get the available streams from the agent. This will do:

 Element subtree = Element.create(
         "urn:ietf:params:xml:ns:netmod:notification", "netconf/streams");
 return session.get(subtree);
 

The available streams are returned.

Throws:

JNCException

java.io.IOException

receiveNotification

public Element receiveNotification()
                            throws java.io.IOException,
                                   JNCException

Receive one notification. This is a blocking call - it blocks the caller until an entire notifications messages has been received. It's possible to check if there is data to be read ahead using the ready() method on the SSHSession object.

Throws:

java.io.IOException

JNCException

action

public Element action(Element data)
               throws JNCException,
                      java.io.IOException

Action capability. An action that does not return any result value, replies with the standard 'ok' element. If a result value is returned, it is encapsulated within a returned 'data' element.

Parameters:

data - element tree with action-data

Throws:

JNCException

java.io.IOException

recv_rpc_reply_ok

protected Element recv_rpc_reply_ok(java.lang.String mid)
                             throws JNCException,
                                    java.io.IOException

Receive from session

Returns:

the reply element

Throws:

JNCException

java.io.IOException

setCapability

protected void setCapability(java.lang.String capability)

Set a proprietary capability. This capability will be advertised in the initial hello message so this method need to invoked before the hello() method to have any effect.

Parameters:

capability - Add a capablity string for this client session

encode_rpc_begin

protected int encode_rpc_begin(Transport out)

Encodes the RPC header and writes it to the provided output transport. This method is provided to be able extend this class with proprietary capabilities.

Parameters:

out - Transport output stream

encode_rpc_begin

protected int encode_rpc_begin(Transport out,
                               Attribute attr)

Encodes the RPC header and writes it to the provided output transport. This method is provided to be able to extend this class with proprietary capabilities. The extra attribute arguement makes it possible to add an extra attribute to the RPC header.

Parameters:

out - Transport output stream

attr - Extra attribute to be added to rpc header

encode_rpc_end

protected void encode_rpc_end(Transport out)

Closes the rpc tag.

Parameters:

out - Transport output stream