Device

java.lang.Object
- com.tailf.jnc.Device

All Implemented Interfaces:

java.io.Serializable
```
public class Device
extends java.lang.Object
implements java.io.Serializable
```
This class provides features for managing a device with NETCONF. A device has a list of users DeviceUser which contain information about how to connect to the device.
Associated to a device is a list of named sessions, each session is a NetconfSession session inside an SSH channel. We can have several sessions to one device. It can for example make sense to have one session open to the configuration db(s) and another session open for NETCONF notifications Typical usage pattern is:
```
 String localUserName = "joe";
 DeviceUser duser = new DeviceUser(localUserName, "admin", "secret");
 Device dev = new Device("mydev", duser, "netconf.tail-f.com", 8023);
 dev.connect(localUserName);
 dev.newSession("cfg");
 Element someConfigTree = makeMyTree();
 dev.getSession("cfg").editConfig(someConfigTree);
 
```
Once we have a new session, we also get a configTree (Element) that we can use to accumulate changes in for the session. This usually handy since the manager code typically consists of bits and pieces that manipulate different parts of the configuration. Then it is convenient to let all manager code add Elements to the session specifig config tree. The tree can be accessed through the getConfig(String) method.

This class also provides basic backlog funtionality. If the device configuration is changed and the device is currently down for some reason, a backlog with the configuration change can be saved and run later when the device comes up again.
See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.ArrayList<Element>`	`backlog` A list of configuration changes.
`protected SSHConnection`	`con` An SSH Connection to this device.
`protected java.util.ArrayList<com.tailf.jnc.Device.SessionConnData>`	`connSessions` The NETCONF sessions (channels) for this device.
`protected int`	`defaultReadTimeout` Time to wait for read, in milliseconds.
`protected java.lang.String`	`mgmt_ip` ip address as string
`protected int`	`mgmt_port` port number
`java.lang.String`	`name` The name of the device, or its IP address.
`protected java.util.ArrayList<com.tailf.jnc.Device.SessionTree>`	`trees`
`protected java.util.ArrayList<DeviceUser>`	`users` A list of users.

Constructor Summary

Constructors
Constructor and Description
`Device(java.lang.String name, DeviceUser user, java.lang.String mgmt_ip, int mgmt_port)` Constructor for the Device with on initial user.
`Device(java.lang.String name, java.lang.String mgmt_ip, int mgmt_port)` Constructor for the Device with on initial user.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addBackLog(Element e)` Adds the given configuration tree to the list of backlogs.
`void`	`addUser(DeviceUser user)` Adds a user to the Device list of users.
`void`	`clearConfig(java.lang.String sessionName)` Clears the accumulation config tree for a named NETCONF session
`void`	`close()` end all NETCONF sessions and close the SSH socket associated to this device It also clears all accumulated config trees.
`void`	`closeSession(java.lang.String sessionName)` Close the named session associated with this device.
`void`	`connect(java.lang.String localUser)` This method finds the `DeviceUser` associated to the localUser user name and SSH connects to the device, this method must be called prior to establishing any sessions (channels)
`void`	`connect(java.lang.String localUser, int connectTimeout)` This connect() method has an additional timeout paramater.
`Element[]`	`getBacklog()` Return the backlog.
`Element`	`getConfig(java.lang.String sessionName)` Returns the accumulated config tree for a named NETCONF session.
`long`	`getReadTimeout(java.lang.String sessionName)` Gets the readTimeout associated to a named session
`NetconfSession`	`getSession(java.lang.String sessionName)` Returns a named NetconfSession for this NETCONF enabled device.
`SSHSession`	`getSSHSession(java.lang.String sessionName)` Returns a named SSHSession for this NETCONF enabled device.
`java.util.ArrayList<DeviceUser>`	`getUsers()` Return the list of users.
`boolean`	`hasBacklog()` Checks if a backlog is saved for this device.
`boolean`	`hasConfig(java.lang.String sessionName)` Check if the named session have a saved configuration tree.
`boolean`	`hasSession(java.lang.String name)` Checks if this device has any sessions with specified name.
`void`	`initTransients()` If Device is stored on disk as a serialized object, we need to init the transient variables after we read a Device from disk.
`void`	`newSession(IOSubscriber sub, java.lang.String sessionName)` Creates a new named NETCONF session We must not have an existing session with the same name.
`void`	`newSession(java.lang.String sessionName)` Creates a new named NETCONF session.
`void`	`newSessionConfigTree(java.lang.String sessionName)` This method is mostly interesting if we want to use the backlog functionality.
`void`	`runBacklog(java.lang.String sessionName)` Run the backlog.
`void`	`setConfig(java.lang.String sessionName, Element e)` Sets the accumulation config tree for a named session
`void`	`setDefaultReadTimeout(int defaultReadTimeout)` Whenever new NetconfSession objects are created through newSession() set this timeout value (milliseconds) as the readTimeout value
`void`	`setReadTimeout(java.lang.String sessionName, int readTimeout)` Sets the readTimeout associated to a named session
`java.lang.String`	`toString()` Returns a string with information about this device.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - name
```
public java.lang.String name
```
    The name of the device, or its IP address.
  - con
```
protected transient SSHConnection con
```
    An SSH Connection to this device.
  - connSessions
```
protected transient java.util.ArrayList<com.tailf.jnc.Device.SessionConnData> connSessions
```
    The NETCONF sessions (channels) for this device.
  - trees
```
protected transient java.util.ArrayList<com.tailf.jnc.Device.SessionTree> trees
```
  - backlog
```
protected java.util.ArrayList<Element> backlog
```
    A list of configuration changes. The backlog is saved when a configuration change is made and the device is down, so that it can be re-sent later when the device comes up again.
  - users
```
protected java.util.ArrayList<DeviceUser> users
```
    A list of users.
  - mgmt_ip
```
protected java.lang.String mgmt_ip
```
    ip address as string
  - mgmt_port
```
protected int mgmt_port
```
    port number
  - defaultReadTimeout
```
protected int defaultReadTimeout
```
    Time to wait for read, in milliseconds.
- Constructor Detail
  - Device
```
public Device(java.lang.String name,
              DeviceUser user,
              java.lang.String mgmt_ip,
              int mgmt_port)
```
    Constructor for the Device with on initial user. We need at least one DeviceUser in order to be able to connect.
  - Device
```
public Device(java.lang.String name,
              java.lang.String mgmt_ip,
              int mgmt_port)
```
    Constructor for the Device with on initial user. We need at least one DeviceUser in order to be able to connect. Thus if this constructor is used to create the Device we must use addUser() priot to connecting.
- Method Detail
  - initTransients
```
public void initTransients()
```
    If Device is stored on disk as a serialized object, we need to init the transient variables after we read a Device from disk.
  - addUser
```
public void addUser(DeviceUser user)
```
    Adds a user to the Device list of users.
  - getUsers
```
public java.util.ArrayList<DeviceUser> getUsers()
```
    Return the list of users.
  - clearConfig
```
public void clearConfig(java.lang.String sessionName)
```
    Clears the accumulation config tree for a named NETCONF session
    
    Parameters:
    
    sessionName - symbolic Name of the session
  - getConfig
```
public Element getConfig(java.lang.String sessionName)
```
    Returns the accumulated config tree for a named NETCONF session. This feature is a convenience feature. It makes sense to perform a series of changes towards a device and accumulate the changes in a single tree. A configuration tree is associated to a named session/ssh channel. If a session is closed, we may still have accumulated config data associated to the session. This method retieves this data although the ssh socket to the server may be dead.
    
    Parameters:
    
    sessionName - symbolic Name of the session
  - setReadTimeout
```
public void setReadTimeout(java.lang.String sessionName,
                           int readTimeout)
```
    Sets the readTimeout associated to a named session
    
    Parameters:
    
    sessionName - symbolic Name of the session
    
    readTimeout - timeout in milliseconds
  - getReadTimeout
```
public long getReadTimeout(java.lang.String sessionName)
```
    Gets the readTimeout associated to a named session
    
    Parameters:
    
    sessionName - symbolic Name of the session
    
    Returns:
    
    timeout in milliseconds
  - hasConfig
```
public boolean hasConfig(java.lang.String sessionName)
```
    Check if the named session have a saved configuration tree.
    
    Parameters:
    
    sessionName - symbolic Name of the session
  - setConfig
```
public void setConfig(java.lang.String sessionName,
                      Element e)
```
    Sets the accumulation config tree for a named session
    
    Parameters:
    
    sessionName - symbolic Name of the session
    
    e - The config tree to insert.
  - hasBacklog
```
public boolean hasBacklog()
```
    Checks if a backlog is saved for this device.
  - setDefaultReadTimeout
```
public void setDefaultReadTimeout(int defaultReadTimeout)
```
    Whenever new NetconfSession objects are created through newSession() set this timeout value (milliseconds) as the readTimeout value
  - closeSession
```
public void closeSession(java.lang.String sessionName)
```
    Close the named session associated with this device. Note, this does not close the socket, it closes the SSH channel which is a considerably cheaper operation. The method also clears any accumulated configuration data we have.
    
    Parameters:
    
    sessionName - symbolic Name of the session
  - close
```
public void close()
```
    end all NETCONF sessions and close the SSH socket associated to this device It also clears all accumulated config trees.
  - hasSession
```
public boolean hasSession(java.lang.String name)
```
    Checks if this device has any sessions with specified name.
  - getSession
```
public NetconfSession getSession(java.lang.String sessionName)
```
    Returns a named NetconfSession for this NETCONF enabled device. The NetconfSession implements (through it's subclass NetconfSession) the getTransport() method. Thus we can get to the underlying ganymed Session object as:
```
 Session s = ((SSHSession) d.getSession("cfg").getTransport()).getSession();
 
```
    This is required to monitor the ganymed Session object for EOF
  - getSSHSession
```
public SSHSession getSSHSession(java.lang.String sessionName)
```
    Returns a named SSHSession for this NETCONF enabled device. We need the SSHSession object if we for example wish to check if an ssh session is ready to read.
  - connect
```
public void connect(java.lang.String localUser)
             throws java.io.IOException,
                    JNCException
```
    This method finds the DeviceUser associated to the localUser user name and SSH connects to the device, this method must be called prior to establishing any sessions (channels)
    
    Throws:
    
    java.io.IOException
    
    JNCException
  - connect
```
public void connect(java.lang.String localUser,
                    int connectTimeout)
             throws java.io.IOException,
                    JNCException
```
    This connect() method has an additional timeout paramater. This is not the same thing as the readTimeout. The connectTimeout only applies to the actual connect.
    
    Parameters:
    
    localUser - The name of a local (for the EMS) user
    
    Throws:
    
    java.io.IOException
    
    JNCException
  - newSessionConfigTree
```
public void newSessionConfigTree(java.lang.String sessionName)
```
    This method is mostly interesting if we want to use the backlog functionality. A typical sequence towards a device is connect(), newSession(). If connect fails, because the device is down, we still might want to have a config tree to accumulate changes in although we have no connection to the device. The getConfig(String) method searches in a list of configTrees, thus we can have named configTrees although there is no existing session towards the device.
  - newSession
```
public void newSession(java.lang.String sessionName)
                throws JNCException,
                       java.io.IOException,
                       YangException
```
    Creates a new named NETCONF session. Each named session corresponds to one SSH channel towards the agent
    
    Parameters:
    
    sessionName - symbolic Name of the session
    
    Throws:
    
    JNCException
    
    java.io.IOException
    
    YangException
  - newSession
```
public void newSession(IOSubscriber sub,
                       java.lang.String sessionName)
                throws JNCException,
                       java.io.IOException
```
    Creates a new named NETCONF session We must not have an existing session with the same name. Thus when we reconnect a Device, we must first call closeSession(sessionName);
    
    Parameters:
    
    sub - IO subscriber for trace messages.
    
    sessionName - symbolic Name of the session
    
    Throws:
    
    JNCException
    
    java.io.IOException
  - addBackLog
```
public void addBackLog(Element e)
```
    Adds the given configuration tree to the list of backlogs.
    
    Parameters:
    
    e - Config tree to be saved.
  - getBacklog
```
public Element[] getBacklog()
```
    Return the backlog.
  - runBacklog
```
public void runBacklog(java.lang.String sessionName)
                throws java.io.IOException,
                       JNCException
```
    Run the backlog. A backlog is typically saved when a configuration change is made (for several devices) and the device is down. The backlog saves the configuration update so that it can be re-sent later. This method runs the saved backlog. It is automatically run whenever we succeeed in creating a new sesssion.
    
    Parameters:
    
    sessionName - symbolic Name of the session
    
    Throws:
    
    java.io.IOException
    
    JNCException
  - toString
```
public java.lang.String toString()
```
    Returns a string with information about this device.
    
    Overrides:
    
    toString in class java.lang.Object

Class Device

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

name

con

connSessions

trees

backlog

users

mgmt_ip

mgmt_port

defaultReadTimeout

Constructor Detail

Device

Device

Method Detail

initTransients

addUser

getUsers

clearConfig

getConfig

setReadTimeout

getReadTimeout

hasConfig

setConfig

hasBacklog

setDefaultReadTimeout

closeSession

close

hasSession

getSession

getSSHSession

connect

connect

newSessionConfigTree

newSession

newSession

addBackLog

getBacklog

runBacklog

toString