|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Ipport
public class Ipport
The IPPort Bean facilitates TCP/IP communications by providing an easy interface to system TCP/IP functions. It allows a client application to communicate with a server using stream sockets.
Our main goal in designing IPPort was ease of use.
The bean has a minimum of properties and five events: Connected
, DataIn
, Disconnected
, ReadyToSend
, and Error
.
The events are relatively self-explanatory.
The connection is attempted by calling the Connect
method or setting the Connected
property to True, and then waiting for the Connected
event. The destination is defined by setting RemoteHost
and RemotePort
. Data is sent by calling the Send
method
with Text as a parameter, or by assigning the data string to the DataToSend
property.
To disconnect, you just call the Disconnect
method or set the Connected
property to False. The Linger
property controls how the connection is
terminated.
The operation of the bean is almost completely asynchronous. All the calls except the ones that deal with domain name resolution operate through asynchronous messages (no blocking calls). The gain in performance is considerable when compared to using blocking calls.
Constructor Summary | |
---|---|
Ipport()
Creates an instance of Ipport Bean. |
|
Ipport(java.lang.String runtimeLicense)
Creates an instance of Ipport Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addIpportEventListener(IpportEventListener l)
|
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a configuration setting. |
void |
connect(java.lang.String host,
int port)
Connects to a remote host. |
void |
disconnect()
Disconnects from the remote host. |
void |
doEvents()
Processes events from the internal message queue. |
int |
getBytesSent()
The number of bytes actually sent after an assignment to DataToSend . |
byte[] |
getEOL()
Used to break the incoming data stream into chunks separated by EOL. |
Firewall |
getFirewall()
A set of properties related to firewall access. |
java.lang.String |
getLine()
Gets a line of text from the server. |
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 IPPort binds. |
java.lang.String |
getRemoteHost()
The address of the remote host. |
int |
getRemotePort()
The TCP port in the remote host. |
int |
getTimeout()
A timeout for the bean. |
void |
interrupt()
Interrupts the current action. |
boolean |
isAcceptData()
Enables or disables data reception (the DataIn event). |
boolean |
isConnected()
Triggers a connection or disconnection. |
boolean |
isKeepAlive()
When True, KEEPALIVE packets are enabled (for long connections). |
boolean |
isLinger()
When set to True, connections are terminated gracefully. |
boolean |
isSingleLineMode()
Special mode for line-oriented protocols. |
void |
removeIpportEventListener(IpportEventListener l)
|
void |
send(byte[] text)
Sends data to the remote host. |
void |
sendFile(java.lang.String fileName)
Sends file to the remote host. |
void |
sendLine(java.lang.String text)
Sends a string followed by a newline. |
void |
setAcceptData(boolean acceptData)
Enables or disables data reception (the DataIn event). |
void |
setConnected(boolean connected)
Triggers a connection or disconnection. |
void |
setDataToSend(byte[] dataToSend)
A string of data to be sent to the remote host. |
void |
setEOL(byte[] EOL)
Used to break the incoming data stream into chunks separated by EOL. |
void |
setFirewall(Firewall firewall)
A set of properties related to firewall access. |
void |
setKeepAlive(boolean keepAlive)
When True, KEEPALIVE packets are enabled (for long connections). |
void |
setLinger(boolean linger)
When set to True, connections are terminated gracefully. |
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 IPPort binds. |
void |
setReceiveStream(java.io.OutputStream receiveStream)
Sets the stream to which received data will be written. |
void |
setRemoteHost(java.lang.String remoteHost)
The address of the remote host. |
void |
setRemotePort(int remotePort)
The TCP port in the remote host. |
void |
setSendStream(java.io.InputStream sendStream)
Reads content from the stream and sends it to the server. |
void |
setSingleLineMode(boolean singleLineMode)
Special mode for line-oriented protocols. |
void |
setTimeout(int timeout)
A timeout for the bean. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Ipport()
public Ipport(java.lang.String runtimeLicense)
Method Detail |
---|
public boolean isAcceptData()
DataIn
event).
This property enables or disables data reception (the DataIn event). Setting this property to False, temporarily disables data reception
(and the DataIn
event). Setting this property to True, re-enables
data reception.
public void setAcceptData(boolean acceptData) throws IPWorksException
DataIn
event).
This property enables or disables data reception (the DataIn event). Setting this property to False, temporarily disables data reception
(and the DataIn
event). Setting this property to True, re-enables
data reception.
IPWorksException
public int getBytesSent()
DataToSend
.
This property indicates how many bytes were sent after the last
assignment to DataToSend
. Please check the DataToSend
property for more
information.
public boolean isConnected()
This property triggers a connection or disconnection. Setting this property to True makes the bean attempt
to connect to the host identified by the RemoteHost
property.
If successful, after the connection is achieved the value of the
property changes to True and the Connected
event is fired.
Setting this property to False closes the connection. How and when the
connection is closed is controlled by the Linger
property.
public void setConnected(boolean connected) throws IPWorksException
This property triggers a connection or disconnection. Setting this property to True makes the bean attempt
to connect to the host identified by the RemoteHost
property.
If successful, after the connection is achieved the value of the
property changes to True and the Connected
event is fired.
Setting this property to False closes the connection. How and when the
connection is closed is controlled by the Linger
property.
IPWorksException
public void setDataToSend(byte[] dataToSend) throws IPWorksException
Assigning a string to this property makes the bean send
the string to the remote host. The Send
method provides similar functionality.
When Timeout
is set to 0 the bean will behave asynchronously. If you are sending data to the remote host faster than it can
process it, or faster than the network's bandwidth allows, the outgoing
queue might fill up. When this happens, DataToSend
fails with exception 10035: "[10035] Operation would block" (WSAEWOULDBLOCK).
You can check this error, and then try to send the data again.
The BytesSent
property shows how many bytes were sent
(if any). If 0 bytes were sent, then you
can wait for the ReadyToSend
event before attempting to send data
again. (However, please note that ReadyToSend
is not fired when part
of the data is successfully sent).
IPWorksException
public byte[] getEOL()
This property is used to define boundaries in the input stream using the value of the property.
This property is especially useful with ASCII files. Setting it to CRLF ("\\r\\n") enables splitting of the incoming ASCII text stream into defined lines. In this case, one event is fired for each line received (as well as in packet boundaries). The CRLF ("\\r\\n") bytes are discarded.
This property is a binary string. In particular, this means that it can be more than one byte long, and it can contain NULL bytes.
public void setEOL(byte[] EOL) throws IPWorksException
This property is used to define boundaries in the input stream using the value of the property.
This property is especially useful with ASCII files. Setting it to CRLF ("\\r\\n") enables splitting of the incoming ASCII text stream into defined lines. In this case, one event is fired for each line received (as well as in packet boundaries). The CRLF ("\\r\\n") bytes are discarded.
This property is a binary string. In particular, this means that it can be more than one byte long, and it can contain NULL bytes.
IPWorksException
public Firewall getFirewall()
This is a Firewall
type property which
contains fields describing the firewall
through which the bean will attempt to connect.
public void setFirewall(Firewall firewall) throws IPWorksException
This is a Firewall
type property which
contains fields describing the firewall
through which the bean will attempt to connect.
IPWorksException
public boolean isKeepAlive()
The KeepAlive
enables the SO_KEEPALIVE option on the socket.
This option prevents long connections from timing out in case
of inactivity.
Please note that system TCP/IP stack implementations are not required to support SO_KEEPALIVE.
public void setKeepAlive(boolean keepAlive) throws IPWorksException
The KeepAlive
enables the SO_KEEPALIVE option on the socket.
This option prevents long connections from timing out in case
of inactivity.
Please note that system TCP/IP stack implementations are not required to support SO_KEEPALIVE.
IPWorksException
public boolean isLinger()
This property controls how a connection is closed. The default is True.
In the case that Linger is True (default), there are two scenarios for determining how
long the connection will linger. The first, if LingerTime
is 0 (default), the
system will attempt to send pending data for a connection until the default
IP protocol timeout expires.
In the second scenario, LingerTime
is a positive value, the system will
attempt to send pending data until the specified LingerTime
is reached.
If this attempt fails, then the system will reset the connection.
The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).
Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.
public void setLinger(boolean linger) throws IPWorksException
This property controls how a connection is closed. The default is True.
In the case that Linger is True (default), there are two scenarios for determining how
long the connection will linger. The first, if LingerTime
is 0 (default), the
system will attempt to send pending data for a connection until the default
IP protocol timeout expires.
In the second scenario, LingerTime
is a positive value, the system will
attempt to send pending data until the specified LingerTime
is reached.
If this attempt fails, then the system will reset the connection.
The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).
Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.
IPWorksException
public java.lang.String getLocalHost()
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 multi-homed 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 multi-homed
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.
public void setLocalHost(java.lang.String localHost) throws IPWorksException
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 multi-homed 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 multi-homed
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
public int getLocalPort()
This 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 this property to 0 (default) enables the system 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 this property when a connection
is active will generate an error.
This; property is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.
public void setLocalPort(int localPort) throws IPWorksException
This 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 this property to 0 (default) enables the system 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 this property when a connection
is active will generate an error.
This; property is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.
IPWorksException
public java.lang.String getRemoteHost()
This property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host. It is set before a connection is attempted and cannot be changed once a connection is established.
If this property is set to a Domain Name, a DNS request is initiated, and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.
If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.
Example (Connecting)
IPPortControl.RemoteHost = "MyHostNameOrIP"
IPPortControl.RemotePort = 777
IPPortControl.Connected = true
public void setRemoteHost(java.lang.String remoteHost) throws IPWorksException
This property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host. It is set before a connection is attempted and cannot be changed once a connection is established.
If this property is set to a Domain Name, a DNS request is initiated, and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.
If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.
Example (Connecting)
IPPortControl.RemoteHost = "MyHostNameOrIP"
IPPortControl.RemotePort = 777
IPPortControl.Connected = true
IPWorksException
public int getRemotePort()
This property specifies a service port on the remote host to connect to.
A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
public void setRemotePort(int remotePort) throws IPWorksException
This property specifies a service port on the remote host to connect to.
A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
IPWorksException
public boolean isSingleLineMode()
When this property is set to True, the bean treats the incoming
data stream as lines separated by CRLF, CR, or LF. The EOL
property is ignored.
AcceptData
will be automatically set to False when this property
is set to True. Please refer to the GetLine
method for more information.
public void setSingleLineMode(boolean singleLineMode) throws IPWorksException
When this property is set to True, the bean treats the incoming
data stream as lines separated by CRLF, CR, or LF. The EOL
property is ignored.
AcceptData
will be automatically set to False when this property
is set to True. Please refer to the GetLine
method for more information.
IPWorksException
public int getTimeout()
If the Timeout
property is set to 0, all operations return
immediately, potentially failing with an error if they can't be
completed immediately.
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 exception.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout
seconds when
any amount of data is successfully sent or received.
Optionally, the behavior 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 the AbsoluteTimeout
configuration setting.
The default value for the Timeout
property is 60 seconds.
public void setTimeout(int timeout) throws IPWorksException
If the Timeout
property is set to 0, all operations return
immediately, potentially failing with an error if they can't be
completed immediately.
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 exception.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout
seconds when
any amount of data is successfully sent or received.
Optionally, the behavior 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 the AbsoluteTimeout
configuration setting.
The default value for the Timeout
property is 60 seconds.
IPWorksException
public java.lang.String config(java.lang.String configurationString) throws IPWorksException
Config
is a generic method available in every bean.
It is used to set and retrieve configuration settings
for 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.
The bean accepts one or more of the following configuration settings .
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.
FirewallHost
is given, requested connections will be authenticated through the specified firewall
when connecting.If the FirewallHost
setting is set to a Domain Name, a DNS request is initiated. Upon successful termination
of the request, the FirewallHost
setting is set to the corresponding address. If the search is not successful,
an error is returned.
NOTE: This is the same as Host . This setting is provided for use by beans that do not directly expose Firewall properties.
RemoteHost
and RemotePort
are used to tell the SOCKS firewall
in which address and port to listen to. The firewall rules may ignore RemoteHost
, and it is recommended that RemoteHost
be set to empty string in this case.
RemotePort
is the port in which the firewall will listen to. If set to 0, the firewall will select a random port. The
binding (address and port) is provided through the ConnectionStatus
event.
The connection to the firewall is made by calling the Connect
method.
FirewallHost
is specified, the FirewallUser
and FirewallPassword
settings
are used to connect and authenticate to the given firewall. If the authentication fails, the bean throws an exception.NOTE: This is the same as Password . This setting is provided for use by beans that do not directly expose Firewall properties.
FirewallPort
is set automatically when FirewallType
is set to a valid value.NOTE: This is the same as Port . This setting is provided for use by beans that do not directly expose Firewall properties.
FirewallPort
is set to 80.
FirewallPort
is set to 1080.
FirewallPort
is set to 1080.
FirewallHost
is specified, the FirewallUser
and FirewallPassword
settings are used to connect and authenticate to the Firewall. If the authentication fails, the bean throws an exception.NOTE: This is the same as User . This setting is provided for use by beans that do not directly expose Firewall properties.
TCPKeepAlive
will automatically be set to true.
By default the operating system will determine the
time a connection is idle before a TCP keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many
cases a shorter interval is more useful. Set this value to the desired interval in milliseconds.Note: This value is not applicable in Java.
TCPKeepAlive
will automatically be set to true.
A TCP keep-alive packet will be sent after a period of inactivity as
defined by KeepAliveTime
. If no acknowledgement is received from the remote host the keep-alive packet
will be re-sent. This setting specifies the interval at which the successive keep-alive packets are sent in milliseconds.
This system default if this value is not specified here is 1 second.Note: This value is not applicable in Java or MAC.
LingerTime
is 0 (default), the
system will attempt to send pending data for a connection until the default
IP protocol timeout expires.
In the second scenario, LingerTime
is a positive value, the system will
attempt to send pending data until the specified LingerTime
is reached.
If this attempt fails, then the system will reset the connection.
The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).
Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.
LocalHost
setting 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 multi-homed 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
setting 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 multi-homed
hosts (machines with more than one IP interface).
LocalPort
after the connection is established.
LocalPort
cannot be changed once a connection is made.
Any attempt to set this when a connection is active will
generate an error.
This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.
MaxLineLength
is the size of an internal buffer, which holds received data while waiting for an EOL
string.If an EOL
string is found in the input stream before MaxLineLength
bytes are received, the DataIn
event is fired with the EOL parameter set to True, and the buffer is reset.
If no EOL
is found, and MaxLineLength
bytes are accumulated in the buffer, the DataIn
event is
fired with the EOL parameter set to False, and the buffer is reset.
The minimum value for MaxLineLength
is 256 bytes. The default value is 2048 bytes. The maximum value is 65536 bytes.
KeepAliveTime
and KeepAliveInterval
to
configure the timing of the keep-alive packets.Note: This value is not applicable in Java.
IPWorksException
public void connect(java.lang.String host, int port) throws IPWorksException
This method connects to a remote host. Calling this method is equivalent to setting the RemoteHost
property
to Host , setting RemotePort
to Port , and then setting
the Connected
property to True.
Example (Connecting)
IPPortControl.Connect("MyHostNameOrIP", 777)
IPWorksException
public void disconnect() throws IPWorksException
This method disconnects from the remote host. Calling this method is equivalent to setting the Connected
property
to False.
IPWorksException
public void doEvents() throws IPWorksException
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
public java.lang.String getLine() throws IPWorksException
This method gets a line of text from the server. This method is an alternative method of receiving data for line-oriented protocols.
The bean will block if necessary and then return the received line. AcceptData
will be automatically set to True when the method is called, and then back to False
after a line is received.
Please refer to the SingleLineMode
property for more information.
IPWorksException
public void interrupt() throws IPWorksException
This method interrupts the current action. If you use SendFile
to upload a file, the bean will run synchronously until the upload is completed. This method will
allow you to stop the file from uploading without disconnecting from the host.
IPWorksException
public void send(byte[] text) throws IPWorksException
This method sends data to the remote host. Calling this method is equivalent to setting the DataToSend
property
to Text .
IPWorksException
public void sendFile(java.lang.String fileName) throws IPWorksException
This method sends the specified file to the remote host the bean is connected to.
IPWorksException
public void sendLine(java.lang.String text) throws IPWorksException
This method sends a string followed by a newline. This method is used for sending data with line-oriented protocols. The line is followed by CRLF ("\\r\\n") .
Please refer to the GetLine
method and SingleLineMode
property
for more information.
IPWorksException
public void setReceiveStream(java.io.OutputStream receiveStream) throws IPWorksException
This method sets the stream to which received data will be written. The stream should be open and normally set to position 0. The bean will write all incoming data to this stream. The downloaded content will be written starting at the current position in the stream.
IPWorksException
public void setSendStream(java.io.InputStream sendStream) throws IPWorksException
This method reads content from the stream and sends it to the server. The stream should be open and normally set to position 0. The call will return only after the end of stream has been reached.
The bean will automatically close this stream if CloseStreamAfterTransfer
is set to true (default).
The content will be read starting at the current position in the stream.
IPWorksException
public void addIpportEventListener(IpportEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeIpportEventListener(IpportEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |