com.maverick.ssh
Class ShellProcess

java.lang.Object
  extended bycom.maverick.ssh.ShellProcess

public class ShellProcess
extends java.lang.Object

Captures a single command and allows expect type functionality to be performed on the output. You capture a command using the Shell.execute(String) method which returns an instance of this class which can then be used to parse the commands output.

The following example demonstrates how to automate setting a users password as root with the passwd command.

 // Assumes variable ssh is a connected and authenticated SshClient
 Shell shell = new Shell(ssh);
 ShellProcess process = shell.execute("passwd lee");
 try {
      process.expect("password:", 10000, true);
      Thread.sleep(200);
      process.typeAndReturn("123defs");

      process.expect("password:", 10000, true);
      Thread.sleep(200);
      process.typeAndReturn("123defs");

      process.expect("successfully", 10000, true);
 } catch (ShellTimeoutException ex) {
      System.out.println("Expect operation timed out. Sending interrupt to kill the process");
      process.interrupt();
 } finally {
      process.close();
 }
 

Note the use of Thread.sleep(200) to create a pause between the receiving of the password prompt and sending of the password. We pause because the passwd command may reset the input buffer, and sending the password too quickly may cause some or all of the password to be lost or echo'd back to the screen. This IS NOT normally required with regular command input.

Also if an expect operation times out the process is most likely still active and blocking further output from the shell, so its always good practice to send an interrupt to stop the process.

The expect operation is performed using the ShellProcess.Matcher interface and by default performs a simple line.indexOf(pattern) matching operation. Alternative methods could include performing a match using regular expressions, for example in Java 1.4 you could use the following implementation to use the String.matches method.

 public class RegExMatcher implements ShellProcess.Matcher {
    public boolean matches(String line, String pattern) {
       return line.matches(pattern);
    }
 }
 

Author:
Lee David Painter

Nested Class Summary
static interface ShellProcess.Matcher
          This interface defines the contract for a matching operation.
 
Method Summary
 void carriageReturn()
          Send a carriage return to the remote command.
 void close()
          Close this command.
 int expect(java.lang.String pattern)
          Wait for the pattern to be found in the commands output.
 int expect(java.lang.String pattern, boolean consumeUnmatchedLines)
          Wait for the pattern to be found in the commands output.
 int expect(java.lang.String pattern, long timeout)
          Wait for the pattern to be found in the commands output with an optional timeout.
 int expect(java.lang.String pattern, long timeout, boolean consumeUnmatchedLines)
          Wait for the pattern to be found in the commands output.
 java.lang.String getCommandLine()
          Get the command line for this command.
 java.lang.String getLine(int lineNumber)
          Get the content of a single line.
 int getLineCount()
          Get the number of lines sitting in the command buffer.
 boolean hasCompletedLines()
          Has the command output any lines of data
 void interrupt()
          Interrupt the process by sending a Ctrl+C to the process.
 java.lang.String readLine()
          Read a line from the commands output.
 java.lang.String readLine(int timeout)
          Read a line from the commands output.
static void setMatcher(ShellProcess.Matcher matcher)
          Set the matching operation implementation.
 java.lang.String toString()
          Outputs all of the commands output.
 void type(java.lang.String string)
          Send data to the remote command just like the user had typed it.
 void typeAndReturn(java.lang.String string)
          Send data to the remote command and finish with a carriage return.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

expect

public int expect(java.lang.String pattern,
                  long timeout)
           throws ShellTimeoutException

Wait for the pattern to be found in the commands output with an optional timeout.

The actual matching operation is performed by an implementation of the ShellProcess.Matcher interface.

Parameters:
pattern - the pattern to match
timeout - a timeout in milliseconds
Returns:
int the line number which contains the match.
Throws:
TimeoutException
ShellTimeoutException

expect

public int expect(java.lang.String pattern)
           throws ShellTimeoutException

Wait for the pattern to be found in the commands output.

The actual matching operation is performed by an implementation of the ShellProcess.Matcher interface.

Parameters:
pattern - the pattern to match.
Returns:
int the line number which contains the match.
Throws:
TimeoutException
ShellTimeoutException

expect

public int expect(java.lang.String pattern,
                  boolean consumeUnmatchedLines)
           throws ShellTimeoutException

Wait for the pattern to be found in the commands output.

The actual matching operation is performed by an implementation of the ShellProcess.Matcher interface.

Parameters:
pattern - the pattern to match.
consumeUnmatchedLines - should the operation consume output that does not match?
Returns:
int the line number which contains the match.
Throws:
TimeoutException
ShellTimeoutException

getCommandLine

public java.lang.String getCommandLine()
Get the command line for this command.

Returns:
String

getLine

public java.lang.String getLine(int lineNumber)
Get the content of a single line.

Parameters:
lineNumber - int
Returns:
String

expect

public int expect(java.lang.String pattern,
                  long timeout,
                  boolean consumeUnmatchedLines)
           throws ShellTimeoutException

Wait for the pattern to be found in the commands output.

The actual matching operation is performed by an implementation of the ShellProcess.Matcher interface.

Parameters:
pattern - the pattern to match
timeout - the timeout in milliseconds
consumeUnmatchedLines - should the operation consume output that does not match?
Returns:
int the line number which contains the match.
Throws:
TimeoutException
ShellTimeoutException

type

public void type(java.lang.String string)
          throws java.io.IOException
Send data to the remote command just like the user had typed it.

Parameters:
string - the typed key data
Throws:
java.io.IOException

carriageReturn

public void carriageReturn()
                    throws java.io.IOException
Send a carriage return to the remote command.

Throws:
java.io.IOException

typeAndReturn

public void typeAndReturn(java.lang.String string)
                   throws java.io.IOException
Send data to the remote command and finish with a carriage return.

Parameters:
string - String
Throws:
java.io.IOException

close

public void close()
Close this command.


readLine

public java.lang.String readLine()
                          throws ShellTimeoutException
Read a line from the commands output. This method will block until a complete line of output is available.

Returns:
String
Throws:
ShellTimeoutException

readLine

public java.lang.String readLine(int timeout)
                          throws ShellTimeoutException
Read a line from the commands output. This method will wait up to the timeout value provided for a complete line of output.

Parameters:
timeout - int
Returns:
String
Throws:
TimeoutException
ShellTimeoutException

hasCompletedLines

public boolean hasCompletedLines()
Has the command output any lines of data

Returns:
boolean

getLineCount

public int getLineCount()
Get the number of lines sitting in the command buffer.

Returns:
int

interrupt

public void interrupt()
               throws java.io.IOException
Interrupt the process by sending a Ctrl+C to the process.

Throws:
java.io.IOException

setMatcher

public static void setMatcher(ShellProcess.Matcher matcher)
Set the matching operation implementation.

Parameters:
matcher - Matcher

toString

public java.lang.String toString()
Outputs all of the commands output.

Returns:
String


Copyright © 2003 3SP LTD. All Rights Reserved.