org.sadun.util
Class UnixLoginHandler

java.lang.Object
  org.sadun.util.UnixLoginHandler

public class UnixLoginHandler

extends java.lang.Object

This class handles typical Unix shell login sequences via telnet.

It is useful to programmatic conversations between a java client and a telnet host.

Login is performed by invoking doLogin(String, String)which consumes characters from a socket stream (polling it with a TelnetInputStreamConsumer) and recognizes both a login prompt character sequence(defaults to "ogin:") and a login incorrect character sequence (defaults to "ogin incorrect").

Recognition occurs by looking at the received input every n milliseconds, where n is the value of TelnetInputStreamConsumer.BASIC_CRITERIA_CHECK_TIME.

By default, if the "login incorrect" sequence is not found within a login incorrect verification time (defaulting to twice the TelnetInputStreamConsumer.BASIC_CRITERIA_CHECK_TIME), the login is assumed to be successful and control is relinquished to the caller, which receives a TelnetInputStream ready for use. Such stream can be passed to a TelnetInputStreamConsumer for further consumption-based processing.

If the "login incorrect" sequence is found, a UnixLoginHandler.LoginIncorrectException is raised.

However, if the CheckForIncorrectLogin property is set to false (defaults to true), no check for incorrect login is made and the stream is returned to the caller immediately after having send the login sequence, saving the time to wait for a possible "login incorrect" sequence.

Note that in this case the UnixLoginHandler.LoginIncorrectException is never raised.

A typical usage sequence is

 
     Socket s = new Socket(telnetHost, 23);
     UnixLoginHandler handler = new UnixLoginHandler UnixLoginHandler(s);
     TelnetInputStreamConsumer is = new TelnetInputStreamConsumer(handler.doLogin("user","password"));
  
 

Version:

1.0

Author:

Cristiano Sadun

Nested Class Summary

static class

UnixLoginHandler.LoginIncorrectException A class to signal an incorrect login by an UnixLoginHandler.

Constructor Summary

UnixLoginHandler(java.io.InputStream is, java.io.OutputStream os)
Construct an handler on the given input/output stream pair.

UnixLoginHandler(java.io.InputStream is, java.io.OutputStream os, boolean sendInitialCRLF)
Construct an handler on the given input/output stream pair, optionally sending an initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

UnixLoginHandler(java.net.Socket s)
Construct a handler on a connected socket.

UnixLoginHandler(java.net.Socket s, boolean sendInitialCRLF)
Construct an handler on a connected socket, optionally sending an initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

UnixLoginHandler(java.lang.String host, int port)
Construct an handler towards the given host/port.

Method Summary

void	disconnect() Disconnect the stream, if the stream is connected.
TelnetInputStreamConsumer	doLogin(java.lang.String user, java.lang.String pwd) Do the login.
void	doLogout() Close input and output stream.
void	doLogout(java.lang.String logoutSequence) Send a logout sequence and disconnect().
void	doLogout(java.lang.String logoutSequence, boolean appendCR) Send a logout sequence and disconnect().
TelnetInputStreamConsumer	getInputStream() Return the input stream used by this handler.
java.lang.String	getLoginIncorrectSequence() Return the character sequence currently used to recognize incorrect logins.
long	getLoginIncorrectVerificationTime() Return the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful.
java.lang.String	getLoginPromptSequence() Return the character sequence currently used to recognize the login prompt.
java.io.PrintStream	getOutputStream() Return the output stream used by this handler.
long	getTimeout() Get the timeout when waiting for prompt/results on login operation.
boolean	isCheckForIncorrectLogin() Return true if the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).
boolean	isSendInitialCRLF() Return true if an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.
void	registerTelnetCommandListener(TelnetInputStream.TelnetCommandListener tlh) Register a TelnetInputStream.TelnetCommandListenerto handle telnet commands.
void	removeTelnetCommandListener(TelnetInputStream.TelnetCommandListener tlh) Unregister a TelnetInputStream.TelnetCommandListenerto handle telnet commands.
void	setCheckForIncorrectLogin(boolean checkForIncorrectLogin) Set whether or not the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).
void	setLoginIncorrectSequence(java.lang.String loginIncorrectSequence) Setthe character sequence to use to recognize incorrect logins.
void	setLoginIncorrectVerificationTime(long loginIncorrectVerificationTime) Set the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful.
void	setLoginPromptSequence(java.lang.String loginPromptSequence) Set the character sequence to use to recognize the login prompt.
void	setSendInitialCRLF(boolean sendInitialCRLF) Set whether or not an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.
void	setTimeout(long timeout) Set the timeout when waiting for prompt/results on login operation.

Methods inherited from class java.lang.Object

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

Constructor Detail

UnixLoginHandler

public UnixLoginHandler(java.net.Socket s)
                 throws java.io.IOException

Construct a handler on a connected socket.

The handler will own the socket and attempt to close it on logout.

An initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

Parameters:

s - the socket

Throws:

java.io.IOException - if an exception occurs obtaining the input/output streams from the socket

UnixLoginHandler

public UnixLoginHandler(java.io.InputStream is,
                        java.io.OutputStream os)

Construct an handler on the given input/output stream pair.

An initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

Parameters:

is - the inputstream

os - the outputstream

UnixLoginHandler

public UnixLoginHandler(java.net.Socket s,
                        boolean sendInitialCRLF)
                 throws java.io.IOException

Construct an handler on a connected socket, optionally sending an initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

Parameters:

s - the socket

sendInitialCRLF - if true, an initial CRLF sequence will be sent to the host to trigger a login prompt

Throws:

java.io.IOException - if an exception occurs obtaining the input/output streams from the socket

UnixLoginHandler

public UnixLoginHandler(java.io.InputStream is,
                        java.io.OutputStream os,
                        boolean sendInitialCRLF)

Construct an handler on the given input/output stream pair, optionally sending an initial CRLF sequence will be sent to the host to trigger a login prompt (see setSendInitialCRLF(boolean).

Parameters:

is - the inputstream

os - the outputstream

sendInitialCRLF - if true, an initial CRLF sequence will be sent to the host to trigger a login prompt

Throws:

java.io.IOException - if an exception occurs obtaining the input/output streams from the socket

UnixLoginHandler

public UnixLoginHandler(java.lang.String host,
                        int port)
                 throws java.net.UnknownHostException,
                        java.io.IOException

Construct an handler towards the given host/port. A socket is created and connected to the host/port.

Parameters:

host - the telnet host name

port - the port to connect to

Throws:

java.io.IOException - if an exception occurs obtaining the input/output streams from the socket

java.net.UnknownHostException - if the host name cannot be resolved

Method Detail

registerTelnetCommandListener

public void registerTelnetCommandListener(TelnetInputStream.TelnetCommandListener tlh)

Register a TelnetInputStream.TelnetCommandListenerto handle telnet commands.

Parameters:

tlh - the TelnetInputStream.TelnetCommandListenerto register.

removeTelnetCommandListener

public void removeTelnetCommandListener(TelnetInputStream.TelnetCommandListener tlh)

Unregister a TelnetInputStream.TelnetCommandListenerto handle telnet commands.

Parameters:

tlh - the TelnetInputStream.TelnetCommandListenerto unregister.

doLogin

public TelnetInputStreamConsumer doLogin(java.lang.String user,
                                         java.lang.String pwd)
                                  throws java.io.IOException,
                                         OperationTimedoutException,
                                         UnixLoginHandler.LoginIncorrectException

Do the login. An initial CRLF is sent if isSendInitialCRLF()is true (as set at construction or by using setSendInitialCRLF(boolean).

Parameters:

user -

pwd -

Throws:

java.io.IOException

OperationTimedoutException

UnixLoginHandler.LoginIncorrectException

doLogout

public void doLogout()

Close input and output stream. If the originating socket is owned by this handler, it is closed as well.

The logout sequence used is CRLF exit CRLF.

doLogout

public void doLogout(java.lang.String logoutSequence)

Send a logout sequence and disconnect().

The given logout sequence used to attempt a graceful logout.

Parameters:

logoutSequence - the logout sequence to be sent to the host

doLogout

public void doLogout(java.lang.String logoutSequence,
                     boolean appendCR)

Send a logout sequence and disconnect().

The given logout sequence used to attempt a graceful logout.

Parameters:

logoutSequence - the logout sequence to be sent to the host

appendCR - if true, a CRLF is appended to the logout sequence.

disconnect

public void disconnect()

Disconnect the stream, if the stream is connected. No specific logout is performed, i.e. no logout sequence is sent to the connected host.

The input/output streams are closed. If the stream owns the socket (one of the #UnixLoginHandler(Socket), {@link #UnixLoginHandler(Socket, boolean)}or {@link #UnixLoginHandler(String, int)}constructors has been used to build the object), an attempt is made to close the socket object as well.

getInputStream

public TelnetInputStreamConsumer getInputStream()

Return the input stream used by this handler.

This method is not threadsafe, and it should be called only after doLogin(String, String).

Returns:

the input stream used by this handler.

getOutputStream

public java.io.PrintStream getOutputStream()

Return the output stream used by this handler.

This method is not threadsafe, and it should be called only after doLogin(String, String).

Returns:

the output stream used by this handler.

isSendInitialCRLF

public boolean isSendInitialCRLF()

Return true if an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.

Returns:

true if an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.

setSendInitialCRLF

public void setSendInitialCRLF(boolean sendInitialCRLF)

Set whether or not an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.

Parameters:

sendInitialCRLF - if true, an initial CRLF will be sent by doLogin(String, String)before initiating the login sequence proper.

getTimeout

public long getTimeout()

Get the timeout when waiting for prompt/results on login operation. Zero means indefinite wait.

Returns:

the timeout when waiting for prompt/results on login operation. Zero means indefinite wait.

setTimeout

public void setTimeout(long timeout)

Set the timeout when waiting for prompt/results on login operation. Zero means indefinite wait.

Parameters:

timeout - the timeout when waiting for prompt/results on login operation. Zero means indefinite wait.

getLoginIncorrectSequence

public java.lang.String getLoginIncorrectSequence()

Return the character sequence currently used to recognize incorrect logins. This is used only if the CheckForIncorrectLogin property is true.

Returns:

the character sequence currently used to recognize incorrect logins.

setLoginIncorrectSequence

public void setLoginIncorrectSequence(java.lang.String loginIncorrectSequence)

Setthe character sequence to use to recognize incorrect logins. This is used only if the CheckForIncorrectLogin property is true.

Parameters:

loginIncorrectSequence - the character sequence currently to use to recognize incorrect logins.

getLoginPromptSequence

public java.lang.String getLoginPromptSequence()

Return the character sequence currently used to recognize the login prompt.

Returns:

the character sequence currently used to recognize the login prompt.

setLoginPromptSequence

public void setLoginPromptSequence(java.lang.String loginPromptSequence)

Set the character sequence to use to recognize the login prompt.

Parameters:

loginPromptSequence - the character sequence currently to use to recognize the login prompt.

getLoginIncorrectVerificationTime

public long getLoginIncorrectVerificationTime()

Return the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful. This is used only if the CheckForIncorrectLogin property is true.

Returns:

the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful.

setLoginIncorrectVerificationTime

public void setLoginIncorrectVerificationTime(long loginIncorrectVerificationTime)

Set the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful. This is used only if the CheckForIncorrectLogin property is true.

Parameters:

loginIncorrectVerificationTime - the time the handler will wait for a "login incorrect" character sequence before assuming the login has been successful.

isCheckForIncorrectLogin

public boolean isCheckForIncorrectLogin()

Return true if the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).

Returns:

true if the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).

setCheckForIncorrectLogin

public void setCheckForIncorrectLogin(boolean checkForIncorrectLogin)

Set whether or not the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).

Parameters:

checkForIncorrectLogin - if true , the handler will wait for the "login incorrect" character sequence when executing doLogin(String, String).