Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## socket
Class TelnetWrapper

    java.lang.Object
      |
      +--socket.TelnetWrapper

public class TelnetWrapper
extends java.lang.Object

Wrapper for a Java Telnet call. To use, make a new TelnetWrapper() with the name or IP address of a host. Then, for most uses, the easiest way is to call setPrompt() with the expected prompt, then call login(), and a sequence of sendLine()'s until you get what you want done.

If you don't know the prompt ahead of time, you have to do a sequence of send() and wait() or receiveUntil() calls. send() sends a string across the telnet connection. Add a '\r' to the end if you want to complete a command. wait() waits for an exact string from the other side of the telnet connection, and returns nothing, receiveUntil() also waits for a string, but returns all the data that it received while waiting, including the string itself. Use this if you want the output from a command. Please note that the telnet connection will usually echo the sent command.

sendLine() is generally better, since it adds the '\r' automatically, waits for the prompt before returning, and returns all data received before the prompt, with the prompt itself cut off the end, and the sent command cut off the beginning. login() and sendLine() are implemented using send(), wait() and receiveUntil(). They can be freely mixed and matched.

Here is a simple example of the use of TelnetWrapper:

     // creates a new file in /tmp, lists the directory to prove it done
     {
       TelnetWrapper telnet = new TelnetWrapper("123.45.78.90");

       // setting the correct prompt ahead of time is very important
       // if you want to use login and sendLine
       telnet.setPrompt("$ ");
       telnet.login("loginname", "password");

       // this is how you have to do it otherwise
       telnet.send("touch /tmp/TELNET_WRAPPER" + "\r");
       telnet.wait("$ ");

       // sendLine 1: adds the \r automatically, 2: waits for the prompt
       // before returning 3: returns what was printed from the command
       String ls = telnet.sendLine("ls /tmp");
       System.out.println(ls);

       // clean up
       telnet.disconnect();
     }

Version:
  0.2 5/15/97 - added comments, replaced String += with StringBuffer.append() in receiveUntil(), added port constructor
Author:
  George Ruban 3/4/97
See Also:
  `TelnetIO`

Field Summary
`boolean` | `debug` Set to true for System.out.println debugging.

Constructor Summary
`TelnetWrapper(java.lang.String host)` Connects to the default telnet port on the given host.
`TelnetWrapper(java.lang.String host, int port)` Connects to a specific telnet port on the given host.

Method Summary
`int` | `available()` Returns bytes available to be read.
`void` | `disconnect()` Ends the telnet connection.
`void` | `finalize()` Ends the telnet connection.
`void` | `login(java.lang.String loginName, java.lang.String password)` Logs in as a particular user and password.
`static void` | `main(java.lang.String[] args)` Telnet test driver.
`java.lang.String` | `receive()` Returns a String from the telnet connection.
`byte[]` | `receiveBytes()` Returns a byte array.
`java.lang.String` | `receiveUntil(java.lang.String token)` Returns all data received up until a certain token.
`java.lang.String` | `receiveUntil(java.lang.String token, long timeout)` Returns all data received up until a certain token.
`void` | `send(byte[] buf)` Sends bytes over the telnet connection.
`void` | `send(java.lang.String s)` Sends a String to the remote host.
`java.lang.String` | `sendLine(java.lang.String command)` Sends a line to the remote host, returns all data before the prompt.
`static void` | `setDefaultPrompt(java.lang.String prompt)` Sets the default prompt used by all TelnetWrappers.
`static void` | `setLogin(java.lang.String login, java.lang.String password)` Sets the default login used by TelnetWrappers.
`void` | `setPrompt(java.lang.String prompt)` Sets the expected prompt.
`static void` | `unsetLogin()` Turns off the default login of TelnetWrappers.
`void` | `wait(java.lang.String token)` Skip any received data until the token appears.
`void` | `wait(java.lang.String token, long timeout)` Wait for a String or a timeout.

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

Field Detail

### debug

    public boolean debug

  Set to true for System.out.println debugging.

Constructor Detail

### TelnetWrapper

    public TelnetWrapper(java.lang.String host)
                  throws java.io.IOException

  Connects to the default telnet port on the given host. If the defaultLogin and defaultPassword are non-null, attempts login.

### TelnetWrapper

    public TelnetWrapper(java.lang.String host,
                         int port)
                  throws java.io.IOException

  Connects to a specific telnet port on the given host. If the defaultLogin and defaultPassword are non-null, attempts login.

Method Detail

### wait

    public void wait(java.lang.String token)
              throws java.io.IOException

  Skip any received data until the token appears. More efficient than receiveUntil, but liable to fail on large tokens that can be spread over several "send"s. In that case, consider using receiveUntil and ignoring the return value.
  Parameters:
    `token` - String to wait for
  Throws:
    java.io.IOException - on problems with the socket connection
  See Also:
    `receiveUntil(java.lang.String)`

### wait

    public void wait(java.lang.String token,
                     long timeout)
              throws java.io.IOException,
                     TimedOutException

  Wait for a String or a timeout. If time runs out, throws a TimedOutException. Sleeps in intervals of 100 milliseconds until either receiving the token or timeout.

  More efficient than receiveUntil, but liable to fail on large tokens that can be spread over several "send"s. In that case, consider using receiveUntil and ignoring the return value.

  Parameters:
    `token` - String to wait for
    `timeout` - time in milliseconds to wait (negative means wait forever)
  Throws:
    java.io.IOException - on problems with the socket connection
    TimedOutException - if time runs out before token received
  See Also:
    `receiveUntil(String, long)`

### available

    public int available()
                  throws java.io.IOException

  Returns bytes available to be read. Since they haven't been negotiated over, this could be misleading...

### receive

    public java.lang.String receive()
                             throws java.io.IOException

  Returns a String from the telnet connection. Blocks until one is available. No guarantees that the string is in any way complete. NOTE: uses Java 1.0.2 style String-bytes conversion.

### receiveBytes

    public byte[] receiveBytes()
                        throws java.io.IOException

  Returns a byte array. Blocks until data is available.

### receiveUntil

    public java.lang.String receiveUntil(java.lang.String token)
                                  throws java.io.IOException

  Returns all data received up until a certain token.
  Parameters:
    `token` - String to wait for
  Throws:
    java.io.IOException - on problems with the socket connection
  See Also:
    `wait(java.lang.String)`

### receiveUntil

    public java.lang.String receiveUntil(java.lang.String token,
                                         long timeout)
                                  throws java.io.IOException,
                                         TimedOutException

  Returns all data received up until a certain token.
  Parameters:
    `token` - String to wait for
    `timeout` - time in milliseconds to wait (negative means wait forever)
  Throws:
    java.io.IOException - on problems with the socket connection
    TimedOutException - if time runs out before token received
  See Also:
    `wait(String, long)`

### send

    public void send(java.lang.String s)
              throws java.io.IOException

  Sends a String to the remote host. NOTE: uses Java 1.0.2 style String-bytes conversion.
  Throws:
    java.io.IOException - on problems with the socket connection

### sendLine

    public java.lang.String sendLine(java.lang.String command)
                              throws java.io.IOException

  Sends a line to the remote host, returns all data before the prompt. Since telnet seems to rely on carriage returns ('\r'), one will be appended to the sent string, if necessary.
  Parameters:
    `command` - command line to send
  Returns:
    whatever data the command produced before the prompt.
  See Also:
    `setPrompt(java.lang.String)`

### send

    public void send(byte[] buf)
              throws java.io.IOException

  Sends bytes over the telnet connection.

### login

    public void login(java.lang.String loginName,
                      java.lang.String password)
               throws java.io.IOException

  Logs in as a particular user and password. Returns after receiving prompt.

### setPrompt

    public void setPrompt(java.lang.String prompt)

  Sets the expected prompt. If this function is not explicitly called, the default prompt is used.
  See Also:
    `setDefaultPrompt(java.lang.String)`

### setDefaultPrompt

    public static void setDefaultPrompt(java.lang.String prompt)

  Sets the default prompt used by all TelnetWrappers. This can be specifically overridden for a specific instance. The default prompt starts out as "$ " until this function is called.
  See Also:
    `setPrompt(java.lang.String)`

### setLogin

    public static void setLogin(java.lang.String login,
                                java.lang.String password)

  Sets the default login used by TelnetWrappers. If this method is called with non-null login and password, all TelnetWrappers will attempt to login when first created.
  Parameters:
    `login` - login name to use
    `password` - password to use
  See Also:
    `login(java.lang.String, java.lang.String)`, `unsetLogin()`

### unsetLogin

    public static void unsetLogin()

  Turns off the default login of TelnetWrappers. After this method is called, TelnetWrappers will not login until that method is explicitly called.
  See Also:
    `setLogin(java.lang.String, java.lang.String)`, `login(java.lang.String, java.lang.String)`

### disconnect

    public void disconnect()
                    throws java.io.IOException

  Ends the telnet connection.

### finalize

    public void finalize()

  Ends the telnet connection.
  Overrides:
    finalize in class java.lang.Object

### main

    public static void main(java.lang.String[] args)
                     throws java.io.IOException

  Telnet test driver. Modeled after the IOtest.java example in the Telnet Applet. Logs in to "host", creates a timestamped file in /tmp, lists the /tmp directory to System.out, disconnects. Shows off several TelnetWrapper methods.
  Parameters:
    `args` - host login password prompt

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD