net.sf.sshapi

Interface SshClient

All Known Implementing Classes:

AbstractClient, LibsshClient

public interface SshClient

Client implementations are responsible for maintaining the connection with the server, authentication, and access to the sub-systems

Method Summary

Modifier and Type	Method and Description
void	addChannelHandler(SshChannelHandler channelHandler) Adds a channel handler to those invoked when custom channel creation requests are received.
void	addPortForwardListener(SshPortForwardListener listener) Add a listener that is notified when channels are opened on this port forward.
boolean	authenticate(SshAuthenticator authenticator) Authenticate using a single authenticator.
boolean	authenticate(SshAuthenticator[] authenticators) Authenticate.
void	connect(java.lang.String username, java.lang.String hostname, int port) Connect to specified host and port using the provided username.
SshExtendedStreamChannel	createCommand(java.lang.String command) Execute a command on the remote server.
SshPortForward	createLocalForward(java.lang.String localBindAddress, int localBindPort, java.lang.String targetAddress, int targetPort) Create a local forward.
SshPublicKeySubsystem	createPublicKeySubsystem() Create an instance of a SshPublicKeySubsystem, if the provider supports it.
SshPortForward	createRemoteForward(java.lang.String remoteBindAddress, int remoteBindPort, java.lang.String targetAddress, int targetPort) Create a remote forward.
SshSCPClient	createSCPClient() Create a new SCP client.
SftpClient	createSftpClient() Create a new SFTP client that may be used to perform file operations.
SshShell	createShell(java.lang.String termType, int cols, int rows, int pixWidth, int pixHeight, byte[] terminalModes) Create a new shell.
javax.net.SocketFactory	createTunneledSocketFactory() Create a SocketFactory whose connections are actually tunneled over this SSH connection and made from the remote machine.
void	disconnect() Disconnect this client.
int	getChannelCount() Get the number of channels that are currently open.
SshConfiguration	getConfiguration() Get the configuration this client is using
SshProvider	getProvider() Get the provider that created this client.
java.lang.String	getRemoteIdentification() Get the remote server identification string.
int	getRemoteProtocolVersion() Get the protocol version.
int	getTimeout() Get the timeout on the underlying transport (usually a Socket, if supported).
java.lang.String	getUsername() Get the currently authenticated user.
void	init(SshProvider provider) Called after instantiation to initialise the client and supply the provider that created it.
boolean	isAuthenticated() Get if the client is currently authenticated.
boolean	isConnected() Get if the client is currently connected.
void	removeChannelHandler(SshChannelHandler channelHandler) Remove a channel handler from the list of those invoked when custom channel creation requests are received.
void	removePortForwardListener(SshPortForwardListener listener) Remove a listener that is notified when channels are opened on this port forward.
void	setTimeout(int timeout) Set the timeout on the underlying transport (usually a Socket, if supported).

Method Detail

getConfiguration

SshConfiguration getConfiguration()

Get the configuration this client is using

Returns:

configuration

init

void init(SshProvider provider)

Called after instantiation to initialise the client and supply the provider that created it. This method should not be be called directly.

Parameters:

provider - provider

getProvider

SshProvider getProvider()

Get the provider that created this client.

Returns:

provider

connect

void connect(java.lang.String username,
             java.lang.String hostname,
             int port)
      throws SshException

Connect to specified host and port using the provided username.

Parameters:

username - user name

hostname - host name

port - port

Throws:

SshException - on any error

authenticate

boolean authenticate(SshAuthenticator[] authenticators)
              throws SshException

Authenticate. An authenticator should be provided for each type supported. This method may be called multiple times until true is return or an exception is thrown.

Parameters:

authenticators - authenticators.

Returns:

true when full authenticated, or false if more authentication is required

Throws:

SshException

authenticate

boolean authenticate(SshAuthenticator authenticator)
              throws SshException

Authenticate using a single authenticator. In practice, will most likely just call authenticate(SshAuthenticator[]).

Parameters:

authenticator - authenticator.

Returns:

authenticated authenticated

Throws:

SshException

See Also:

#authenticate(SshAuthenticator[])}

createShell

SshShell createShell(java.lang.String termType,
                     int cols,
                     int rows,
                     int pixWidth,
                     int pixHeight,
                     byte[] terminalModes)
              throws SshException

Create a new shell.

Note, this method does not actually start the shell, you must call SshLifecycleComponent.open() to do that.

Remember to close the shell when you are finished with it using SshLifecycleComponent.close().

Parameters:

termType - terminal type, or use null to NOT request a pseudo terminal

cols - width of terminal in characters (use zero if not pseudo terminal should be requested)

rows - height of terminal in characters (use zero if not pseudo terminal should be requested)

pixWidth - width of terminal in pixels (if known, otherwise use zero)

pixHeight - height of terminal in pixels (if known, otherwise use zero)

terminalModes - terminal modes (or null or empty array)

Returns:

shell

Throws:

SshException

createLocalForward

SshPortForward createLocalForward(java.lang.String localBindAddress,
                                  int localBindPort,
                                  java.lang.String targetAddress,
                                  int targetPort)
                           throws SshException

Create a local forward. Local forwards create a listening socket on the client that is tunneled through to the remote server which then makes the connection to the target.

Once you have created the SshPortForward object, you must start tunnel using SshPortForward.open(). When you have finished with the tunnel, call SshPortForward.close() (closed tunnels may be re-opened by calling the SshPortForward.open() method again).

Parameters:

localBindAddress - local address to bind to. Use null to bind to all addresses. Note, this may not be supported by all implementations.

localBindPort - local port to listen on

targetAddress - remote host to tunnel to

targetPort - remote port to tunnel to

Returns:

local forward

Throws:

SshException - on any error

createRemoteForward

SshPortForward createRemoteForward(java.lang.String remoteBindAddress,
                                   int remoteBindPort,
                                   java.lang.String targetAddress,
                                   int targetPort)
                            throws SshException

Create a remote forward. Remote forwards create a listening socket on the SSH server you are connected to, and tunnel connections back to the client end and then on to the target.

Once you have created the SshPortForward object, you must start tunnel using SshPortForward.open(). When you have finished with the tunnel, call SshPortForward.close() (closed tunnels may be re-opened by calling the SshPortForward.open() method again).

Parameters:

remoteBindAddress - the address on the remote server to listen. This must either be null to bind to all address on that server, or a single address that exists on that server (including 127.0.0.1).

remoteBindPort - remote port to tunnel to

targetAddress - local address to bind to. Use null to bind to all addresses. Note, this may not be supported by all implementations.

targetPort - local port to listen on

Returns:

local forward

Throws:

SshException - on any error

createCommand

SshExtendedStreamChannel createCommand(java.lang.String command)
                                throws SshException

Execute a command on the remote server.

Note, this method does not actually start the command, you must call SshLifecycleComponent.open() to do that.

Remember to close the channel when you are finished with it using SshLifecycleComponent.close().

Parameters:

command - command to execute

Returns:

channel

Throws:

SshException - on any error

createTunneledSocketFactory

javax.net.SocketFactory createTunneledSocketFactory()
                                             throws SshException

Create a SocketFactory whose connections are actually tunneled over this SSH connection and made from the remote machine. This actually makes use of local port forward, but instead of setting up a local server socket, the tunnels are accessable as Socket objects.

Returns:

tunneled socket factory

Throws:

SshException

createSCPClient

SshSCPClient createSCPClient()
                      throws SshException

Create a new SCP client. This may be used for simple file transfer. For a more fully featured file-system like approach, use createSftpClient().

Returns:

scp client

Throws:

SshException - on any error

createSftpClient

SftpClient createSftpClient()
                     throws SshException

Create a new SFTP client that may be used to perform file operations.

Note, this method does not actually start the client, you must call SshLifecycleComponent.open() to do that.

Remember to close the client when you are finished with it using SshLifecycleComponent.close().

Returns:

SFTP client

Throws:

SshException

createPublicKeySubsystem

SshPublicKeySubsystem createPublicKeySubsystem()
                                        throws SshException

Create an instance of a SshPublicKeySubsystem, if the provider supports it.

Note, this method does not actually start the subsystems, you must call SshLifecycleComponent.open() to do that.

Remember to close the subsystem when you are finished with it using SshLifecycleComponent.close().

Returns:

public key subsystem instance.

Throws:

SshException

java.lang.UnsupportedOperationException - if no supported

disconnect

void disconnect()
         throws SshException

Disconnect this client.

Throws:

SshException

isConnected

boolean isConnected()

Get if the client is currently connected. A client may be connected, but not yet authenticated.

Returns:

connected

See Also:

isAuthenticated()

isAuthenticated

boolean isAuthenticated()

Get if the client is currently authenticated. This implies the client is connected.

Returns:

authenticated

See Also:

isConnected()

getRemoteIdentification

java.lang.String getRemoteIdentification()

Get the remote server identification string. Client must be connected.

Returns:

remote identification

Throws:

java.lang.IllegalStateException - if not connected

getRemoteProtocolVersion

int getRemoteProtocolVersion()

Get the protocol version. Will be one of SshConfiguration.SSH1_ONLY or SshConfiguration.SSH2_ONLY.

Returns:

protocol version

Throws:

java.lang.IllegalStateException - if not connected

getUsername

java.lang.String getUsername()

Get the currently authenticated user.

Returns:

user

getChannelCount

int getChannelCount()

Get the number of channels that are currently open.

Returns:

open channels

Throws:

java.lang.IllegalStateException - if not connected

addPortForwardListener

void addPortForwardListener(SshPortForwardListener listener)

Add a listener that is notified when channels are opened on this port forward.

Parameters:

listener - listener to add

removePortForwardListener

void removePortForwardListener(SshPortForwardListener listener)

Remove a listener that is notified when channels are opened on this port forward.

Parameters:

listener - listener to remove

setTimeout

void setTimeout(int timeout)
         throws java.io.IOException

Set the timeout on the underlying transport (usually a Socket, if supported). A timeout of zero indicates infinite timeout

Parameters:

timeout - timeout

Throws:

java.io.IOException

getTimeout

int getTimeout()
        throws java.io.IOException

Get the timeout on the underlying transport (usually a Socket, if supported). A timeout of zero indicates infinite timeout

Returns:

timeout

Throws:

java.io.IOException

addChannelHandler

void addChannelHandler(SshChannelHandler channelHandler)
                throws SshException

Adds a channel handler to those invoked when custom channel creation requests are received.

Parameters:

channelHandler - channel handler to add

Throws:

SshException

removeChannelHandler

void removeChannelHandler(SshChannelHandler channelHandler)
                   throws SshException

Remove a channel handler from the list of those invoked when custom channel creation requests are received.

Parameters:

channelHandler - channel handler to remove

Throws:

SshException