org.peace_tools.core.session
Class ServerSession

java.lang.Object
  org.peace_tools.core.session.ServerSession

Direct Known Subclasses:

LocalServerSession, RemoteServerSession

public abstract class ServerSession
extends java.lang.Object

A common base class for local and remote connections. This is an abstract (non-instantiable) base class that serves as a common interface for both local and remote server sessions. Sub-systems that exclusively operate with the ServerSession are guaranteed to be agnostic to local and remote servers and they would operate in a consistent manner. Local server sessions typically directly run the commands on the local machine using suitable JVM API calls. On the other hand remote sessions run the commands on a remote machine via a secure shell (SSH) protocol.

See Also:

LocalServerSession, RemoteServerSession

Nested Class Summary

static class

ServerSession.OSType Enumerations to provide a more convenient mechanism for referring to the actual type of the server that this server session has been connected to.

Field Summary

protected java.awt.Component	parent The parent component that visually owns this server session.
protected Server	server The server data entry that provides the necessary information to connect to the server.

Constructor Summary

ServerSession(Server server, java.awt.Component parent)
The constructor merely initializes the instance variables to the values supplied as parameters.

Method Summary

abstract void	connect() Connect to the server in order to perform various operations.
abstract void	copy(java.io.InputStream srcData, java.lang.String destDirectory, java.lang.String destFileName, java.lang.String mode) Copy given data from an input stream to a given file on the server.
abstract void	copy(java.io.OutputStream destData, java.lang.String srcDirectory, java.lang.String srcFileName, javax.swing.JProgressBar progBar) Copy file from a remote machine to a given output stream.
abstract void	disconnect() Disconnect and close connection to a server.
abstract int	exec(java.lang.String command, javax.swing.text.DefaultStyledDocument output) This method can be used to run a long running command that may produce verbose output.
abstract int	exec(java.lang.String command, java.lang.String[] outputs) This method can be used to run a brief command that produces succinct output.
abstract FileInfo	fstat(java.lang.String path) Obtain information about a given path on the server.
abstract ServerSession.OSType	getOSType() Determine the type of OS that this session is connected to.
abstract void	mkdir(java.lang.String directory) Creates a directory on the server.
abstract void	rmdir(java.lang.String directory) Remove an empty directory on the server.
abstract void	setPurpose(java.lang.String text) A simple method to set a purpose message for this session.

Methods inherited from class java.lang.Object

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

Field Detail

server

protected final Server server

The server data entry that provides the necessary information to connect to the server.

parent

protected final java.awt.Component parent

The parent component that visually owns this server session. This parent component is used to display dialog boxes used for prompting the user for password etc (as needed) by the derived sessions.

Constructor Detail

ServerSession

public ServerSession(Server server,
                     java.awt.Component parent)

The constructor merely initializes the instance variables to the values supplied as parameters.

Parameters:

server - The server data entry that provides the necessary information to connect to the server.

parent - The parent component that should be used to create GUI elements that may be needed for any interactive operations.

Method Detail

connect

public abstract void connect()
                      throws java.io.IOException

Connect to the server in order to perform various operations. This method must be used to establish a connection to a server before performing any tasks. This method is overridden in the derived class to perform the necessary connection operations. In the case of a remote session an actual network connection is established with the remote server which entails creating an SSH session and authenticating with the server.

In a single session, a connection needs to be established only once. After a connection has been established multiple commands and copy operations can be performed without requiring to connect and disconnect from the session.

Note: The process of establishing a connection can be a time consuming task. In some cases incorrect host names can cause long connection times (until the connection times out which can be in minutes). Consequently, it is best to call this method from a separate daemon thread.

Throws:

java.io.IOException - This method throws IO exceptions in the case of errors. If an error occurs, then a connection was not established and the caller will have to try again to establish a connection.

disconnect

public abstract void disconnect()

Disconnect and close connection to a server. This method must be used to disconnect an existing connection to a server. Invoking this method on session that is not connected has no side effects (and derived session classes do no special operations if a connection does not exist).

Note: Disconnecting from a server that may be performing a long running operation may have undesired side effects of the commands aborting and possibly leaving data files in an inconsistent state.

exec

public abstract int exec(java.lang.String command,
                         java.lang.String[] outputs)
                  throws java.lang.Exception

This method can be used to run a brief command that produces succinct output. This method provides a convenient API to execute a command on a server, buffer the output, and return the resulting output(s) as a string(s). Since this method buffers and returns the output, it must be used only for jobs that return small volumes of data. In addition, since the method returns the results only after the command has fully executed, it does not provide any interactive features to the user. Consequently, it should be used only for jobs that run for a short period of time.

Note: The connection to the remote server must have been established successfully via a call to connect method.

Parameters:

command - The command line to be executed. This command must be compatible with the target machine's OS. Otherwise this method will generate an exception.

outputs - The buffered results from the standard output and standard error streams of the remote process.

Returns:

The exit code from the remote command that was run.

Throws:

java.lang.Exception - If the execution produces an error then this method throws an exception.

exec

public abstract int exec(java.lang.String command,
                         javax.swing.text.DefaultStyledDocument output)
                  throws java.lang.Exception

This method can be used to run a long running command that may produce verbose output. This method provides a convenient API to execute a command on a server, stream the output, and return the exit code from the remote command. The outputs are streamed to a given StyledDocument. This method uses styles named "stdout", "stderr", and "warning" (if available in the given output document)

Note: The connection to the remote server must have been established successfully via a call to connect method.

Parameters:

command - The command line to be executed. This command must be compatible with the target machine's OS. Otherwise this method will generate an exception.

output - The styled document to which the standard output and standard error streams are to be written. This parameter cannot be null.

Returns:

The exit code from the remote command that was run.

Throws:

java.lang.Exception - If the execution produces an error then this method throws an exception.

getOSType

public abstract ServerSession.OSType getOSType()
                                        throws java.lang.Exception

Determine the type of OS that this session is connected to. This method can be used to determine the type of the OS that this session is connected to.

Note: The session must be connected prior to this call. Implementations must try to make this method as quick as possible, by caching the OS type, if necessary.

Returns:

The type of OS this session is associated with.

Throws:

java.lang.Exception - If the detection of OS fails or a connection does not exist then this method throws an exception.

copy

public abstract void copy(java.io.InputStream srcData,
                          java.lang.String destDirectory,
                          java.lang.String destFileName,
                          java.lang.String mode)
                   throws java.io.IOException

Copy given data from an input stream to a given file on the server.

Note: The connection to the server must have already been successfully established via a call to the connect method before invoking this method.

Parameters:

srcData - The source stream that provides the data to be copied.

destDirectory - The destination directory to which the data is to be copied. This method assumes that the remote directory has already been created.

destFileName - The name of the destination file to which the data is to be copied.

mode - The POSIX compliant mode string (such as: "0600" or "0777" to be used as the mode for the target file.

Throws:

java.io.IOException - This method throws exceptions on errors.

copy

public abstract void copy(java.io.OutputStream destData,
                          java.lang.String srcDirectory,
                          java.lang.String srcFileName,
                          javax.swing.JProgressBar progBar)
                   throws java.io.IOException

Copy file from a remote machine to a given output stream.

Note: The connection to the remote host must have already been established before invoking this method.

Parameters:

destData - The destination stream to which the data is to be written.

srcDirectory - The source directory from where the file is to be copied.

srcFileName - The name of the source file from where the data is to be copied.

progBar - The progress bar to be used indicate the file copy progress. This parameter can be null.

Throws:

java.io.IOException - This method throws exceptions on errors.

mkdir

public abstract void mkdir(java.lang.String directory)
                    throws java.lang.Exception

Creates a directory on the server. This method must be used to create a directory entry on the server.

Note: The connection to the server must have already been successfully established via a call to the connect method before invoking this method.

Parameters:

directory - The fully path to the directory to be created.

Throws:

java.io.IOException - This method throws an exception if the directory could not be created.

java.lang.Exception

rmdir

public abstract void rmdir(java.lang.String directory)
                    throws java.lang.Exception

Remove an empty directory on the server. This method must be used to remove a directory entry on the server. Note that the directory must be empty in order for this operation to succeed.

Note: The connection to the server must have already been successfully established via a call to the connect method before invoking this method.

Parameters:

directory - The fully path to the directory to be deleted.

Throws:

java.io.IOException - This method throws an exception if the directory could not be deleted.

java.lang.Exception

fstat

public abstract FileInfo fstat(java.lang.String path)
                        throws java.io.IOException

Obtain information about a given path on the server.

Note: This method uses SFTP to copy the data. The connection to the remote host must have already been established before invoking this method.

Parameters:

path - The path (absolute or relative to home directory) of the file whose meta data is to be retrieved.

Returns:

A FileInfo object containing the information about the path.

Throws:

java.io.IOException - This method throws exceptions on errors.

setPurpose

public abstract void setPurpose(java.lang.String text)

A simple method to set a purpose message for this session. This method can be used to set up a purpose message for a server session. The purpose message is typically displayed to the user when prompting for inputs from the user for credentials. The message serves the purpose of appraising the user about the purpose of the session.

Parameters:

text - This string is used to create a label (possibly with an icon on it). So it can be plain text or HTML. If the message is long, then ensure it is properly broken into multiple lines so that dialog boxes don't get too large.