ipworks
Class Rcp

java.lang.Object
  |
  +--ipworks.Rcp

public class Rcp

extends java.lang.Object

The RCP bean implements the popular UNIX Remote Copy Protocol, used to transfer files between systems.

Using the bean is as simple as specifying a LocalFile , a RemoteFile and RemoteHost , and calling the GetFile or the PutFile method.

The Remote Copy Protocol is implemented over either RSHELL or REXEC. The bean allows you to choose which protocol to use via the Protocol property.

Field Summary

static int	protRexec
static int	protRshell

Constructor Summary

Rcp()

Method Summary

void	addRcpEventListener(ipworks.RcpEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	doEvents() Processes events from the internal message queue.
void	getFile() Get File.
java.lang.String	getFileMode() The file mode for the RemoteFile .
ipworks.Firewall	getFirewall() A set of properties related to firewall access.
java.lang.String	getLocalFile() The file on the local host.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getLocalPort() The TCP port in the local host where the bean binds.
java.lang.String	getPassword() The password associated with User .
int	getProtocol() Sets the protocol to use for the transfer.
java.lang.String	getRemoteFile() The file on the remote host.
java.lang.String	getRemoteHost() The remote host to connect to.
int	getRemotePort() The port for the service (REXEC or RSHELL).
int	getTimeout() A timeout for the bean.
java.lang.String	getUser() The identification of the remote user for a transfer.
void	interrupt() Interrupt the current method.
boolean	isIdle() The current status of the component.
void	putFile() Put File
void	removeRcpEventListener(ipworks.RcpEventListener l)
void	setFileMode(java.lang.String fileMode) The file mode for the RemoteFile .
void	setFirewall(ipworks.Firewall firewall) A set of properties related to firewall access.
void	setLocalFile(java.lang.String localFile) The file on the local host.
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setLocalPort(int localPort) The TCP port in the local host where the bean binds.
void	setPassword(java.lang.String password) The password associated with User .
void	setProtocol(int protocol) Sets the protocol to use for the transfer.
void	setRemoteFile(java.lang.String remoteFile) The file on the remote host.
void	setRemoteHost(java.lang.String remoteHost) The remote host to connect to.
void	setRemotePort(int remotePort) The port for the service (REXEC or RSHELL).
void	setTimeout(int timeout) A timeout for the bean.
void	setUser(java.lang.String user) The identification of the remote user for a transfer.

Methods inherited from class java.lang.Object

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

Field Detail

protRexec

public static final int protRexec

See Also:

Constant Field Values

protRshell

public static final int protRshell

See Also:

Constant Field Values

Constructor Detail

Rcp

public Rcp()

Method Detail

getFileMode

public java.lang.String getFileMode()

The file mode for the RemoteFile .

The FileMode property is used together with the PutFile method. The default mode is "0600".

setFileMode

public void setFileMode(java.lang.String fileMode)
                 throws IPWorksException

The file mode for the RemoteFile .

The FileMode property is used together with the PutFile method. The default mode is "0600".

IPWorksException

getFirewall

public ipworks.Firewall getFirewall()

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect.

setFirewall

public void setFirewall(ipworks.Firewall firewall)
                 throws IPWorksException

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect.

IPWorksException

isIdle

public boolean isIdle()

The current status of the component.

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

getLocalFile

public java.lang.String getLocalFile()

The file on the local host.

When GetFile is called and the file already exists, it is overwritten.

When PutFile is called LocalFile must point to a valid file, or an error will be returned.

setLocalFile

public void setLocalFile(java.lang.String localFile)
                  throws IPWorksException

The file on the local host.

When GetFile is called and the file already exists, it is overwritten.

When PutFile is called LocalFile must point to a valid file, or an error will be returned.

IPWorksException

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksException

getLocalPort

public int getLocalPort()

The TCP port in the local host where the bean binds.

The LocalPort property must be set before a connection is attempted. It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the bean to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set the LocalPort property when a connection is active will generate an error.

Use this property with caution. If you supply a value, it must be an available port on the system, or an error will be returned. Furthermore, the bean always attempts to bind to a secure (sub 1000) port when the value of LocalPort is the default (0). If you supply your own value, make sure the remote system is configured to allow that particular value.

setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksException

The TCP port in the local host where the bean binds.

The LocalPort property must be set before a connection is attempted. It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the bean to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set the LocalPort property when a connection is active will generate an error.

Use this property with caution. If you supply a value, it must be an available port on the system, or an error will be returned. Furthermore, the bean always attempts to bind to a secure (sub 1000) port when the value of LocalPort is the default (0). If you supply your own value, make sure the remote system is configured to allow that particular value.

IPWorksException

getPassword

public java.lang.String getPassword()

The password associated with User .

This property needs to be set to the password that the RemoteHost has associated with the User . This property is needed only if the Protocol used is REXEC.

setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException

The password associated with User .

This property needs to be set to the password that the RemoteHost has associated with the User . This property is needed only if the Protocol used is REXEC.

IPWorksException

getProtocol

public int getProtocol()

Sets the protocol to use for the transfer.

The Protocol property determines the protocol mechanism used to communicate with the remote host. It has two possible values:

protRexec (0)

The bean uses the REXEC protocol is used for data transfer.

protRshell (1)

The bean uses the RSHELL protocol is used for data transfer.

The default value is protRexec . ( protRshell is not genereally recommended because of potential security issues.)

setProtocol

public void setProtocol(int protocol)
                 throws IPWorksException

Sets the protocol to use for the transfer.

The Protocol property determines the protocol mechanism used to communicate with the remote host. It has two possible values:

protRexec (0)

The bean uses the REXEC protocol is used for data transfer.

protRshell (1)

The bean uses the RSHELL protocol is used for data transfer.

The default value is protRexec . ( protRshell is not genereally recommended because of potential security issues.)

IPWorksException

getRemoteFile

public java.lang.String getRemoteFile()

The file on the remote host.

When GetFile is called, RemoteFile must be a valid file on the RemoteHost .

setRemoteFile

public void setRemoteFile(java.lang.String remoteFile)
                   throws IPWorksException

The file on the remote host.

When GetFile is called, RemoteFile must be a valid file on the RemoteHost .

IPWorksException

getRemoteHost

public java.lang.String getRemoteHost()

The remote host to connect to.

Set this property to a valid Internet address of a computer that is running REXEC or RSHELL services. If the computer is not running the service that the Protocol property is set to, then the connection will fail.

If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceeded with a "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws IPWorksException

The remote host to connect to.

Set this property to a valid Internet address of a computer that is running REXEC or RSHELL services. If the computer is not running the service that the Protocol property is set to, then the connection will fail.

If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceeded with a "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

IPWorksException

getRemotePort

public int getRemotePort()

The port for the service (REXEC or RSHELL).

The value of RemotePort is set automatically to 512 for REXEC or 514 for RSHELL every time the Protocol property is set. Please refer to the description of the Protocol property for more information.

setRemotePort

public void setRemotePort(int remotePort)
                   throws IPWorksException

The port for the service (REXEC or RSHELL).

The value of RemotePort is set automatically to 512 for REXEC or 514 for RSHELL every time the Protocol property is set. Please refer to the description of the Protocol property for more information.

IPWorksException

getTimeout

public int getTimeout()

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

setTimeout

public void setTimeout(int timeout)
                throws IPWorksException

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

IPWorksException

getUser

public java.lang.String getUser()

The identification of the remote user for a transfer.

This identification is necessary for use with the protocols REXEC and RSHELL.

setUser

public void setUser(java.lang.String user)
             throws IPWorksException

The identification of the remote user for a transfer.

This identification is necessary for use with the protocols REXEC and RSHELL.

IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksException

getFile

public void getFile()
             throws IPWorksException

Get File.

A connection is made with the RemoteHost using the specified Protocol , User , and Password , and a request is sent to read the file specified by RemoteFile .

Example (Get a File)

 RCPControl.RemoteHost = "MyServer"
 RCPControl.User = "username"
 RCPControl.Password = "password"
 RCPControl.Protocol = protRexec
 RCPControl.RemoteFile = "/remotefile.txt"
 RCPControl.LocalFile = "C:\\filename.txt"
 RCPControl.GetFile() 

IPWorksException

interrupt

public void interrupt()
               throws IPWorksException

Interrupt the current method.

If there is no method in progress, Interrupt simply returns doing nothing.

IPWorksException

putFile

public void putFile()
             throws IPWorksException

Put File

A connection is made and a request is sent to copy LocalFile to the file specified by RemoteFile .

Example (Put a File)

 RCPControl.RemoteHost = "MyServer"
 RCPControl.User = "username"
 RCPControl.Password = "password"
 RCPControl.Protocol = protRexec
 RCPControl.RemoteFile = "/remotefile.txt"
 RCPControl.LocalFile = "C:\\filename.txt"
 RCPControl.PutFile() 

IPWorksException

addRcpEventListener

public void addRcpEventListener(ipworks.RcpEventListener l)
                         throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeRcpEventListener

public void removeRcpEventListener(ipworks.RcpEventListener l)