com.vhosting.netconf.transport
Class NetconfCatcher

java.lang.Object
  extended by com.vhosting.netconf.transport.NetconfCatcher
Direct Known Subclasses:
NetconfSshCather

public abstract class NetconfCatcher
extends java.lang.Object

This abstract class implements all the aspects that characterize a Netconf connection and through its protected methods you can create a subclass that implements directly a certain type of transport protocol.

 Examples include:
 
 1. Netconf over SSH2 (RFC 4742)
 2. Netconf over SOAP (RFC 4743)
 3. Netconf over BEEP (RFC 4744)
 ...
 

Version:
1.00, 02/11/2010
Author:
Giuseppe Palmeri

Nested Class Summary
static class NetconfCatcher.LogLevel
          This enumeration lists the possible levels of writing logs.
 
Constructor Summary
protected NetconfCatcher(java.lang.String labelConnection)
          It enables a subclass to be instantiated.
 
Method Summary
 void disconnect()
          Invoke this method if you want to end the connection at any point in your application, such as when the user wants to do it manually.
protected abstract  boolean doDisconnect()
          This method must necessarily be implemented with the code necessary to perform a disconnect with the server.
protected abstract  byte[] doReadDataFromServer()
          This method must necessarily be implemented when required to read the next message from the server.
protected abstract  void doSendDataToServer(byte[] bytes)
          This method must necessarily be implemented so that any type of message can be sent to the Netconf server.
static void enableLog(NetconfCatcher.LogLevel level)
          Enables the writing of the logs.
protected  void fireConnectionClosed()
          This method must necessarily be invoked at the end of the process when the server connection is lost to natural causes.
static NetconfCatcher.LogLevel getLogLevel()
          Get the log level set.
static java.io.PrintStream getLogStream()
          Get the log stream.
abstract  boolean isConnected()
          Check if the connection is alive or not.
protected  void sendHelloMsg()
          Packages the message hello with the abilities of this implementation of netconf and send the message to the server.
static void setLogStream(java.io.PrintStream stream)
          Set the stream on which the log will be reversed.
 void setNetconfCatcherListener(NetconfCatcherListener ncl)
          Set the NetconfCatcherListener in order to intercept transport events.
 void setSyncRequestsTimeout(int timeout)
          Allows you to specify a request timeout for synchronous RPC calls.
protected  void throwTransportException(java.lang.Exception e, NetconfTransportError.FailCause cause, boolean withClosedConnection)
          This method must be used into connection process when an exception occurs or a condition in which the connection can not be established.
protected  void whileRpcReplyCatching()
          This method must be called immediately following methods: sendHelloMsg(); checkServerHelloMsg(); The invocation of the method will generate an infinite loop on reading a message from the server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NetconfCatcher

protected NetconfCatcher(java.lang.String labelConnection)
It enables a subclass to be instantiated.

Parameters:
labelConnection - A label used to identify the connection.
Method Detail

setNetconfCatcherListener

public final void setNetconfCatcherListener(NetconfCatcherListener ncl)
Set the NetconfCatcherListener in order to intercept transport events. Only one listener is allowed.

Parameters:
ncl - A NetconfCatcherListener instance.
See Also:
NetconfCatcherListener

sendHelloMsg

protected final void sendHelloMsg()
                           throws java.io.IOException
Packages the message hello with the abilities of this implementation of netconf and send the message to the server. This method should be called immediately after the connection has been established with the server. This is usually the first method that is invoked in the process of connecting with the server That Will Be Implemented.

Throws:
java.io.IOException - throw if there are not a connection and the message sent can not exercise.

throwTransportException

protected final void throwTransportException(java.lang.Exception e,
                                             NetconfTransportError.FailCause cause,
                                             boolean withClosedConnection)
This method must be used into connection process when an exception occurs or a condition in which the connection can not be established. Which in a condition when the connection can not be established occurs, an exception will be created and passed as first argument.

Parameters:
e - The exception that occurred during the connection process or the exception is created when there is a condition in which the connection can not be established.
cause - The fail cause.
withClosedConnection - true if the connection is closed after it was opened in prior periods during the connection process; false if the connection was never opened before.

isConnected

public abstract boolean isConnected()
Check if the connection is alive or not.

Returns:
true if the connection is alive; false otherwise.

fireConnectionClosed

protected void fireConnectionClosed()
This method must necessarily be invoked at the end of the process when the server connection is lost to natural causes. This even though one of the methods:
 sendHelloMsg();
 checkServerHelloMsg();
 whileRpcReplyCatching();
 
fails for an exception, which means that the connection has been terminated by the server.


doSendDataToServer

protected abstract void doSendDataToServer(byte[] bytes)
                                    throws java.io.IOException
This method must necessarily be implemented so that any type of message can be sent to the Netconf server. This method must necessarily throw an exception when the server connection was lost. In particular, for the ssh protocol this method should be implemented by adding the string ']]>]]>' after the message. See the RFC 4742. Similarly, this method be overridden if necessary for other types of transport protocols.

Parameters:
bytes - The byte array containing the Netconf message.
Throws:
java.io.IOException - Throw this exception when the server connection was lost.

doReadDataFromServer

protected abstract byte[] doReadDataFromServer()
                                        throws java.io.IOException
This method must necessarily be implemented when required to read the next message from the server. This method must necessarily throw an exception when the server connection was lost. In particular, for the ssh protocol this method should be implemented by removing the string ']]>]]>' after the message. See the RFC 4742.

Returns:
The message read and made available.
Throws:
java.io.IOException - Throw this exception when the server connection was lost.

disconnect

public final void disconnect()
Invoke this method if you want to end the connection at any point in your application, such as when the user wants to do it manually.


doDisconnect

protected abstract boolean doDisconnect()
This method must necessarily be implemented with the code necessary to perform a disconnect with the server. Not have to worry about managing any exceptions, due to the disconnection.

Returns:
true se si è provveduto ad effettuare la disconnessione; false se non è stato necessario effettuare la disconnessione.

whileRpcReplyCatching

protected final void whileRpcReplyCatching()
                                    throws java.io.IOException
This method must be called immediately following methods:
 sendHelloMsg();
 checkServerHelloMsg();
 
The invocation of the method will generate an infinite loop on reading a message from the server. This infinite loop will end only by throwing an exception that indicates the end of the connection to the server.

Throws:
java.io.IOException - Throw this exception if the connection is closed for any reason.

setSyncRequestsTimeout

public final void setSyncRequestsTimeout(int timeout)
Allows you to specify a request timeout for synchronous RPC calls.

Parameters:
timeout - The timeout.

setLogStream

public static final void setLogStream(java.io.PrintStream stream)
Set the stream on which the log will be reversed. The default is System.out.

Parameters:
stream - The stream on which the log will be reversed.

enableLog

public static final void enableLog(NetconfCatcher.LogLevel level)
Enables the writing of the logs.

Parameters:
level - The log level flag.
See Also:
setLogStream(PrintStream stream), getLogLevel(), NetconfCatcher.LogLevel

getLogStream

public static final java.io.PrintStream getLogStream()
Get the log stream.

Returns:
The log stream.

getLogLevel

public static final NetconfCatcher.LogLevel getLogLevel()
Get the log level set.

Returns:
the log level set.
See Also:
enableLog(LogLevel level), NetconfCatcher.LogLevel