org.peace_tools.core.session
Class LocalServerSession

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

public class LocalServerSession
extends ServerSession

A local server session to run jobs on the local host.

This class provides an implementation of the ServerSession API. Specifically, this class provides a session that can be used to interact with the local PC using the same API as that used for remote hosts. The consistent API eases development of the core GUI modules.

Nested Class Summary

Nested classes/interfaces inherited from class org.peace_tools.core.session.ServerSession

ServerSession.OSType

Field Summary

private java.lang.String

purpose A simple textual information indicating the purpose for this session.

Fields inherited from class org.peace_tools.core.session.ServerSession

parent, server

Constructor Summary

protected

LocalServerSession(java.awt.Component parent, Server server) The constructor merely passes parameters to the base class that initializes the instance variables.

Method Summary

void	connect() Connect to the server in order to perform various operations.
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 local machine.
void	copy(java.io.OutputStream destData, java.lang.String srcDirectory, java.lang.String srcFileName, javax.swing.JProgressBar progBar) Copy file from one directory to a given output stream.
void	disconnect() Method to disconnect from a remote server.
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.
int	exec(java.lang.String command, java.lang.String[] outputs) This method can be used to run a brief command that produces succinct output.
FileInfo	fstat(java.lang.String path) Obtain information about a given path on the server.
ServerSession.OSType	getOSType() Determine the type of OS that this session is connected to.
java.lang.String	getPurpose() Obtain the purpose set for this session.
void	mkdir(java.lang.String directory) Creates a directory on the server.
void	rmdir(java.lang.String directory) Deletes an empty directory on the server.
private void	setPerms(java.io.File file, char permDigit, boolean owner) Set up the permissions for a given file.
void	setPurpose(java.lang.String text) A simple method to set a purpose message for this session.
private java.lang.Process	startProcess(java.lang.String command) Helper method to start process to execute command via OS-specific command processor.

Methods inherited from class java.lang.Object

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

Field Detail

purpose

private java.lang.String purpose

A simple textual information indicating the purpose for this session. This string is more meanigful to the user and is merely used to provide additional information when prompting for inputs from the user.

Constructor Detail

LocalServerSession

protected LocalServerSession(java.awt.Component parent,
                             Server server)

The constructor merely passes parameters to the base class that initializes the instance variables. No special operations are performed in the constructor.

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 void connect()
             throws java.io.IOException

Connect to the server in order to perform various operations. This method is really meaningful only for a remote server session that requires connections to be established. For a local server there is absolutely nothing to do and this method is empty.

Specified by:

connect in class ServerSession

Throws:

java.io.IOException - The exception signature is only for API compliance. This method does not really throw any exceptions

disconnect

public void disconnect()

Method to disconnect from a remote server. Similar to the connect method, this method is blank because there isn't a physical connection to tear down.

Specified by:

disconnect in class ServerSession

exec

public 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 the local machine, buffer the output, and return the resulting output as a string. 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.

Specified by:

exec in class ServerSession

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.

startProcess

private java.lang.Process startProcess(java.lang.String command)
                                throws java.lang.Exception

Helper method to start process to execute command via OS-specific command processor.

Parameters:

command - The command to be run.

Returns:

The process object created by running the command via OS-specific command processor.

Throws:

java.lang.Exception

exec

public 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 local server, stream the output, and return the exit code from the process. 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: This method waits for the process to complete before returning control. Consequently, this method must be called from a separate thread if the GUI should not block.

Specified by:

exec in class ServerSession

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.

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 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.

Specified by:

getOSType in class ServerSession

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 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 local machine.

Specified by:

copy in class ServerSession

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 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 one directory to a given output stream.

Specified by:

copy in class ServerSession

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.

Throws:

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

mkdir

public 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.

Specified by:

mkdir in class ServerSession

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 void rmdir(java.lang.String directory)
           throws java.lang.Exception

Deletes an empty directory on the server. This method must be used to delete a directory entry on the server. The directory must be empty.

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

Specified by:

rmdir in class ServerSession

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 FileInfo fstat(java.lang.String path)
               throws java.io.IOException

Obtain information about a given path on the server.

Specified by:

fstat in class ServerSession

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.

setPerms

private void setPerms(java.io.File file,
                      char permDigit,
                      boolean owner)

Set up the permissions for a given file. This is a helper method that uses a given digit in the permission string to setup the read, write, and execute information for a given file.

Parameters:

file - The file whose permissions are to be set.

permDigit - A POSIX compliant digit (0-7) that indicates the flags for read (4), write (2), and execute (1) values.

owner - Flag to indicate if the status is for the owner (true) or others (false).

setPurpose

public 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 displayed to the user when prompting for inputs from the user.

Specified by:

setPurpose in class ServerSession

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.

getPurpose

public java.lang.String getPurpose()

Obtain the purpose set for this session.

Returns:

The purpose set for this session. If a purpose is not set then this method returns null.