All Packages Class Hierarchy This Package Previous Next Index
Class com.extropia.net.JavaCGIBridge
java.lang.Object
|
+----java.util.Observable
|
+----com.extropia.net.JavaCGIBridge
- public class JavaCGIBridge
- extends Observable
- implements Runnable
This is a class that POSTS and GETS data from URLs using various
helper methods. This class also provides the capability of
timing out if the connection takes too long to transfer data
by using threads to monitor whether the data is taking too long
to transfer (implements Runnable).
Helper methods allow you to set up form variables, get setup
information over a URL, get raw or pre-parsed HTML data, and more.
The getParsedData method relies on instance variables which
tell the parser where the data begins and ends (top and bottom
separators respectively). The field and row separators inform
the parser where records and fields end.
The default start of data separator is <!--start of data-->\n
The default end of data separator is <!--end of data-->\n
The default field separator is | (pipe).
The default record separator is \n (newline).
If the data you are sending is likely to contain special characters
such as newlines in database fields or | symbols, you can expand
the record and field separators to be more restrictive. For example,
you might consider making the field seperator ~|~ (tilde + pipe + tilde)
if you think a stray pipe might appear somewhere.
Another strategy is to follow a MIME like strategy where you make
very long separators that are very unlikely to appear randomly in
binary or large database field data. An example separator string
might be "__CabbageNeck_Peter_Joe_Erik_Mark_Anthony_David_987XxX".
However, be aware that although longer separator strings provide
more security against random stray characters matching, they will
also increase the parsing time.
- Version:
- 2.00, 18 Jul 1998
- Author:
- Gunther Birznieks, Marty Hall
-
IDLE
- IDLE indicates that the JavaCGIBridge object
has finished processing and can move on to do
something else.
-
PROCESSING
- PROCESSING indicates that the JavaCGIBridge
object is in the middle of processing a request.
-
SETUP
- SETUP indicates that the processing status is
in setup mode.
-
JavaCGIBridge()
- Constructs the object with no initialization.
-
JavaCGIBridge(String, String, String, String)
- Constructs the object with new separator values
-
addFormValue(Hashtable, String, String)
- Adds a form variable, value pair to the passed Hashtable.
-
callOneWay(URL)
- Calls the URL but returns immediately.
-
callOneWay(URL, boolean)
- Calls the URL but returns immediately.
-
callOneWay(URL, Hashtable)
- Calls the URL but returns immediately.
-
callOneWay(URL, Hashtable, boolean)
- Calls the URL but returns immediately.
-
getEndDataSeparator()
- Returns the end of data separator for the object.
-
getFieldSeparator()
- Returns the field separator for the object.
-
getKeyValuePairs(Vector)
-
Takes the parsed data returned from the getParsedData method
and changes it to a Hashtable of key, value pairs where the first
Vector entry of each Vector record is the key and the rest of the
second Vector entry for each record is the value of the Hashtable.
-
getParseAsRaw()
- Returns true or false depending on
whether the JavaCGIBridge will parse the fields
in the HTTP response as Strings (default) or
as raw data byte arrays.
-
getParsedData(URL)
- Returns parsed data in the form of a Vector of Vectors containing
the returned fields inside of a Vector of returned rows.
-
getParsedData(URL, Hashtable)
- Returns parsed data in the form of a Vector of Vectors containing
the returned fields inside of a Vector of returned rows.
-
getParsedNotifyInterval()
- Returns an integer indicating the number of records which will
trigger a notification to observers with the contents of what
has been parsed so far.
-
getRawData(URL)
- Returns raw HTML data as a String from the passed URL.
-
getRawData(URL, Hashtable)
- Returns raw HTML data as a String from the passed URL and list
of Form variable/value pairs stored in a Hashtable.
-
getRawNotifyInterval()
- Returns an integer indicating the number of raw content bytes
from the HTTP response which will
trigger a notification to observers with the contents of what
has been read so far.
-
getRecordSeparator()
- Returns the record separator for the object.
-
getStartDataSeparator()
- Returns the start of data separator for the object.
-
getStatus()
- Returns the processing status of the JavaCGIBridge
objects.
-
getTimeOut()
- Returns the actual communication time out in milliseconds
for the object.
-
getURLEncodedHashtable(Hashtable)
-
Returns the form variables inside the hashtable as a
URL encoded string of parameters for a CGI based program
to process.
-
run()
- This run thread asynchronously POSTs and GETs data from
a URL and places the contents into the _threadRawData variable.
-
setEndDataSeparator(String)
- Sets the end of data separator for the object.
-
setFieldSeparator(String)
- Sets the field separator for the object.
-
setParseAsRaw(boolean)
-
Sets the flag that indicates whether the
JavaCGIBridge will parse the HTTP response
data as raw byte array or as String (default).
-
setParsedNotifyInterval(int)
- Sets an integer indicating the number of records which will
trigger a notification to observers with the contents of what
has been parsed so far.
-
setRawNotifyInterval(int)
- Sets an integer indicating the number of raw content bytes
from the HTTP response which will
trigger a notification to observers with the contents of what
has been read so far.
-
setRecordSeparator(String)
- Sets the record separator for the object.
-
setStartDataSeparator(String)
- Sets the start of data separator for the object.
-
setStatus(int)
-
Sets the processing status of the JavaCGIBridge
object.
-
setTimeOut(int)
- Sets the actual communication time out in milliseconds
for the object.
SETUP
public static final int SETUP
- SETUP indicates that the processing status is
in setup mode. This means that no communications
have been established yet. In otherwords, the programmer
is still setting up defaults.
- See Also:
- getStatus, setStatus
PROCESSING
public static final int PROCESSING
- PROCESSING indicates that the JavaCGIBridge
object is in the middle of processing a request.
- See Also:
- getStatus, setStatus
IDLE
public static final int IDLE
- IDLE indicates that the JavaCGIBridge object
has finished processing and can move on to do
something else. Usually this means that the
JavaCGIBridgePool object can give this instance
to another consumer now that it is done with
the request.
- See Also:
- getStatus, setStatus
JavaCGIBridge
public JavaCGIBridge(String field,
String record,
String startData,
String endData)
- Constructs the object with new separator values
JavaCGIBridge
public JavaCGIBridge()
- Constructs the object with no initialization. This is the default
(empty) constructor.
addFormValue
public void addFormValue(Hashtable ht,
String formKey,
String formValue)
- Adds a form variable, value pair to the passed Hashtable.
- Parameters:
- ht - the Hashtable that contains the form variable/value pairs
- formKey - the String that contains the form variable to add
- formValue - the String that contains the form value to add
getKeyValuePairs
public Hashtable getKeyValuePairs(Vector vectorOfVectors)
- Takes the parsed data returned from the getParsedData method
and changes it to a Hashtable of key, value pairs where the first
Vector entry of each Vector record is the key and the rest of the
second Vector entry for each record is the value of the Hashtable.
- Parameters:
- vectorOfVectors - the Vector of Vectors for the parsed data
- Returns:
- Hashtable containing converted variable/value pairs
- See Also:
- getParsedData
getParsedData
public Vector getParsedData(URL u) throws JavaCGIBridgeTimeOutException
- Returns parsed data in the form of a Vector of Vectors containing
the returned fields inside of a Vector of returned rows.
- Parameters:
- u - URL to get parsed data from.
- Returns:
- Vector (records) of vectors (fields) of parsed data
- Throws: JavaCGIBridgeTimeOutException
- If the retrieval times out
- See Also:
- getRawData, callOneWay, getParseAsRaw, setParseAsRaw, getParsedNotifyInterval, setParsedNotifyInterval
getParsedData
public Vector getParsedData(URL u,
Hashtable ht) throws JavaCGIBridgeTimeOutException
- Returns parsed data in the form of a Vector of Vectors containing
the returned fields inside of a Vector of returned rows. This form
POSTs the HTML Form variable data to the URL.
- Parameters:
- u - URL to get parsed data from.
- ht - Hashtable contains form variables to POST
- Returns:
- Vector (records) of vectors (fields) of parsed data
- Throws: JavaCGIBridgeTimeOutException
- If the retrieval times out
- See Also:
- getRawData, callOneWay, getParseAsRaw, setParseAsRaw, getParsedNotifyInterval, setParsedNotifyInterval
getRawData
public byte[] getRawData(URL u) throws JavaCGIBridgeTimeOutException
- Returns raw HTML data as a String from the passed URL.
- Parameters:
- u - URL to get raw HTML from.
- Returns:
- String containing plain HTML text
- Throws: JavaCGIBridgeTimeOutException
- If the retrieval times out
- See Also:
- getParsedData, callOneWay, getRawNotifyInterval, setRawNotifyInterval
getRawData
public byte[] getRawData(URL u,
Hashtable ht) throws JavaCGIBridgeTimeOutException
- Returns raw HTML data as a String from the passed URL and list
of Form variable/value pairs stored in a Hashtable. This form
POSTs the HTML Form variable data to the URL.
- Parameters:
- u - URL to get raw HTML from.
- ht - Hashtable contains form variables to POST
- Returns:
- String containing plain HTML text
- Throws: JavaCGIBridgeTimeOutException
- If the retrieval times out
- See Also:
- getParsedData, callOneWay, getRawNotifyInterval, setRawNotifyInterval
callOneWay
public void callOneWay(URL u)
- Calls the URL but returns immediately. This is
called a ONEWAY operation. This method is used
in one of three circumstances.
[1] You want to "fire and forget" an operation such
as an update to a file or database on the web server
without worrying about a return code or whether the
operation even succedded.
[2] You want to set up an observer interface to
the bridge to notify yourself as data comes in
instead of blocking the whole program while waiting
for the data.
[3] You want to call fetchNextRecord method in
the JavaCGIBridgeExtension class. Basically, the
callOneWay() operation returns immediately so that
it leaves your program free to loop through the
fetchNextRecord() method. Note that if you use
callOneWay for this purpose, it is recommended that
you call the version where you set "fetchData" equal
to true so that the Object is not set to the IDLE
state prematurely. This is discussed in further
detail in the documentation for fetchNextRecord()
in the JavaCGIBridgeExtension class.
- Parameters:
- u - URL to get raw HTML from.
- See Also:
- getRawData, getParsedData, getRawNotifyInterval, setRawNotifyInterval, getParsedNotifyInterval, setParsedNotifyInterval
callOneWay
public void callOneWay(URL u,
boolean fetchData)
- Calls the URL but returns immediately. This is
called a ONEWAY operation. This method is used
in one of three circumstances.
[1] You want to "fire and forget" an operation such
as an update to a file or database on the web server
without worrying about a return code or whether the
operation even succedded.
[2] You want to set up an observer interface to
the bridge to notify yourself as data comes in
instead of blocking the whole program while waiting
for the data.
[3] You want to call fetchNextRecord method in
the JavaCGIBridgeExtension class. Basically, the
callOneWay() operation returns immediately so that
it leaves your program free to loop through the
fetchNextRecord() method. Note that if you use
callOneWay for this purpose, it is recommended that
you call the version where you set "fetchData" equal
to true so that the Object is not set to the IDLE
state prematurely. This is discussed in further
detail in the documentation for fetchNextRecord()
in the JavaCGIBridgeExtension class.
- Parameters:
- u - URL to get raw HTML from.
- fetchData - Set to true if you intend to
use the fetchNextRecord() method.
This avoids the thread automatically
setting the state of the object to
IDLE when the thread completes. This
is necessary because it is possible that
fetchNextRecord has not completed
fetching all the records by the time
the communications thread ends.
- See Also:
- getRawData, getParsedData, getRawNotifyInterval, setRawNotifyInterval, getParsedNotifyInterval, setParsedNotifyInterval
callOneWay
public void callOneWay(URL u,
Hashtable ht)
- Calls the URL but returns immediately. This is
called a ONEWAY operation. This method is used
in one of three circumstances.
[1] You want to "fire and forget" an operation such
as an update to a file or database on the web server
without worrying about a return code or whether the
operation even succedded.
[2] You want to set up an observer interface to
the bridge to notify yourself as data comes in
instead of blocking the whole program while waiting
for the data.
[3] You want to call fetchNextRecord method in
the JavaCGIBridgeExtension class. Basically, the
callOneWay() operation returns immediately so that
it leaves your program free to loop through the
fetchNextRecord() method. Note that if you use
callOneWay for this purpose, it is recommended that
you call the version where you set "fetchData" equal
to true so that the Object is not set to the IDLE
state prematurely. This is discussed in further
detail in the documentation for fetchNextRecord()
in the JavaCGIBridgeExtension class.
- Parameters:
- u - URL to get raw HTML from.
- ht - Hashtable contains form variables to POST
- See Also:
- getRawData, getParsedData, getRawNotifyInterval, setRawNotifyInterval, getParsedNotifyInterval, setParsedNotifyInterval
callOneWay
public void callOneWay(URL u,
Hashtable ht,
boolean fetchData)
- Calls the URL but returns immediately. This is
called a ONEWAY operation. This method is used
in one of three circumstances.
[1] You want to "fire and forget" an operation such
as an update to a file or database on the web server
without worrying about a return code or whether the
operation even succedded.
[2] You want to set up an observer interface to
the bridge to notify yourself as data comes in
instead of blocking the whole program while waiting
for the data.
[3] You want to call fetchNextRecord method in
the JavaCGIBridgeExtension class. Basically, the
callOneWay() operation returns immediately so that
it leaves your program free to loop through the
fetchNextRecord() method. Note that if you use
callOneWay for this purpose, it is recommended that
you call the version where you set "fetchData" equal
to true so that the Object is not set to the IDLE
state prematurely. This is discussed in further
detail in the documentation for fetchNextRecord()
in the JavaCGIBridgeExtension class.
- Parameters:
- u - URL to get raw HTML from.
- ht - Hashtable contains form variables to POST
- fetchData - Set to true if you intend to
use the fetchNextRecord() method.
This avoids the thread automatically
setting the state of the object to
IDLE when the thread completes. This
is necessary because it is possible that
fetchNextRecord has not completed
fetching all the records by the time
the communications thread ends.
- See Also:
- getRawData, getParsedData, getRawNotifyInterval, setRawNotifyInterval, getParsedNotifyInterval, setParsedNotifyInterval
getTimeOut
public int getTimeOut()
- Returns the actual communication time out in milliseconds
for the object. The default is 10 seconds.
When the object retrieves data from a URL, it must get
the data within timeout milliseconds or a
JavaCGIBridgeTimeOutException is thrown.
- Returns:
- communication time out in milliseconds
- See Also:
- setTimeOut
setTimeOut
public void setTimeOut(int t)
- Sets the actual communication time out in milliseconds
for the object. The default is 10 seconds.
When the object retrieves data from a URL, it must get
the data within timeout milliseconds or a
JavaCGIBridgeTimeOutException is thrown.
- Parameters:
- t - communication time out in milliseconds
- See Also:
- getTimeOut
setFieldSeparator
public void setFieldSeparator(String s)
- Sets the field separator for the object. When getParsedData
method is called, the object uses the field separator to determine
where fields in a returned record of the raw HTML result set
begin and end.
- Parameters:
- s - String containing new delimiting separator
- See Also:
- getParsedData, getFieldSeparator
getFieldSeparator
public String getFieldSeparator()
- Returns the field separator for the object. When getParsedData
method is called, the object uses the field separator to determine
where fields in a returned record of the raw HTML result set
begin and end.
- Returns:
- Separator string
- See Also:
- getParsedData, setFieldSeparator
setRecordSeparator
public void setRecordSeparator(String s)
- Sets the record separator for the object. When getParsedData
method is called, the object uses the record separator to determine
where records/rows of the raw HTML result set
begin and end.
- Parameters:
- s - String containing new delimiting separator
- See Also:
- getParsedData, getRecordSeparator
getRecordSeparator
public String getRecordSeparator()
- Returns the record separator for the object. When getParsedData
method is called, the object uses the record separator to determine
where records/rows of the raw HTML result set
begin and end.
- Returns:
- Separator string
- See Also:
- getParsedData, setRecordSeparator
setStartDataSeparator
public void setStartDataSeparator(String s)
- Sets the start of data separator for the object. When getParsedData
method is called, the object uses the start of data separator to determine
where the rows of data inside the raw HTML output actually begin.
- Parameters:
- s - String containing new delimiting separator
- See Also:
- getParsedData, getStartDataSeparator
getStartDataSeparator
public String getStartDataSeparator()
- Returns the start of data separator for the object. When getParsedData
method is called, the object uses the start of data separator to determine
where the rows of data inside the raw HTML output actually begin.
- Returns:
- Separator string
- See Also:
- getParsedData, setStartDataSeparator
setEndDataSeparator
public void setEndDataSeparator(String s)
- Sets the end of data separator for the object. When getParsedData
method is called, the object uses the end of data separator to determine
where the rows of data inside the raw HTML output actually end.
- Parameters:
- s - String containing new delimiting separator
- See Also:
- getParsedData, getEndDataSeparator
getEndDataSeparator
public String getEndDataSeparator()
- Returns the end of data separator for the object. When getParsedData
method is called, the object uses the end of data separator to determine
where the rows of data inside the raw HTML output actually end.
- Returns:
- Separator string
- See Also:
- getParsedData, setEndDataSeparator
getParsedNotifyInterval
public int getParsedNotifyInterval()
- Returns an integer indicating the number of records which will
trigger a notification to observers with the contents of what
has been parsed so far. When this is set to a positive number,
it will also notify when the records have finished being parsed
at the end of the HTTP response. When this is set to a negative
number, no periodic notifications will be sent, however one will
be sent at the end of the HTTP response.
- Returns:
- int Number of records between parse notifications. Set to 0
to turn off parsing notification,
Set to a negative number to
only send notifications at the end.
- See Also:
- setParsedNotifyInterval
setParsedNotifyInterval
public void setParsedNotifyInterval(int n)
- Sets an integer indicating the number of records which will
trigger a notification to observers with the contents of what
has been parsed so far. When this is set to a positive number,
it will also notify when the records have finished being parsed
at the end of the HTTP response. When this is set to a negative
number, no periodic notifications will be sent, however one will
be sent at the end of the HTTP response.
- Parameters:
- n - Number of records between parse notifications. Set to 0
to turn off parsing notification,
Set to a negative number to
only send notifications at the end.
- See Also:
- getParsedNotifyInterval
getRawNotifyInterval
public int getRawNotifyInterval()
- Returns an integer indicating the number of raw content bytes
from the HTTP response which will
trigger a notification to observers with the contents of what
has been read so far. When this is set to a positive number,
it will also notify when the HTTP response has finished.
When this is set to a negative
number, no periodic notifications will be sent, however one will
be sent at the end of the HTTP response.
- Returns:
- int Number of bytes between notifications. Set to 0
to turn off notification after lines of HTML
sent in the HTTP response,
Set to a negative number to
only send notifications at the end.
- See Also:
- setRawNotifyInterval
setRawNotifyInterval
public void setRawNotifyInterval(int n)
- Sets an integer indicating the number of raw content bytes
from the HTTP response which will
trigger a notification to observers with the contents of what
has been read so far. When this is set to a positive number,
it will also notify when the HTTP response has finished.
When this is set to a negative
number, no periodic notifications will be sent, however one will
be sent at the end of the HTTP response.
- Parameters:
- n - Number of bytes between notifications. Set to 0
to turn off notification after bytes of HTML
sent in the HTTP response,
Set to a negative number to
only send notifications at the end.
- See Also:
- getRawNotifyInterval
getParseAsRaw
public boolean getParseAsRaw()
- Returns true or false depending on
whether the JavaCGIBridge will parse the fields
in the HTTP response as Strings (default) or
as raw data byte arrays. Use byte arrays if you
public void setRawNotifyInterval(int n) {
_rawNotifyInterval = n;
}
/**
Returns true or false depending on
whether the JavaCGIBridge will parse the fields
in the HTTP response as Strings (default) or
as raw data byte arrays. Use byte arrays if you
will be transferring binary data such as a jpeg
or gif image.
- Returns:
- boolean Flag indicating parsing as
raw byte array or as Strings
- See Also:
- setParseAsRaw
setParseAsRaw
public void setParseAsRaw(boolean b)
- Sets the flag that indicates whether the
JavaCGIBridge will parse the HTTP response
data as raw byte array or as String (default).
- Parameters:
- b - Flag indicating true or false
- See Also:
- getParseAsRaw
getStatus
public int getStatus()
- Returns the processing status of the JavaCGIBridge
objects. It will be equal to SETUP (1), PROCESSING (2),
or IDLE (3) public static class variables.
- Returns:
- int Status code
- See Also:
- setStatus
setStatus
public void setStatus(int status)
- Sets the processing status of the JavaCGIBridge
object. You will set it to SETUP (1), PROCESSING (2),
or IDLE (3) public static class variables.
- Parameters:
- status - Status code
- See Also:
- getStatus
run
public void run()
- This run thread asynchronously POSTs and GETs data from
a URL and places the contents into the _threadRawData variable.
Since Threads do not return or pass parameter values, instance
variables in this object are used to maintain state. This method
is only public so that the Thread class can launch the thread.
- See Also:
- getRawData
getURLEncodedHashtable
public String getURLEncodedHashtable(Hashtable ht)
- Returns the form variables inside the hashtable as a
URL encoded string of parameters for a CGI based program
to process.
- Parameters:
- ht - Hashtable containing form variables
- Returns:
- URLencoded string of HTML form variables & values
- See Also:
- addFormValue
All Packages Class Hierarchy This Package Previous Next Index