A
URL
is a type of
Stream
used by Yoix for I/O primarily with a web server.
A
URL
stream can be used to retrieve data and text, including Yoix scripts,
from a web server and for executing CGI scripts.
If the connection will be reading and writing, then writing must be done first
and completed before any reading is attempted.
Once reading has started, writing cannot be recommenced.
The complete set of fields in a
URL
are:
| autoready |
When set to a non-zero
int
value,
read attempts on the stream will return an end-of-input indication rather than
block when the stream has no input available.
An alternative to avoid a blocking read is to check the value of
ready before doing a read.
| | bufsize |
For efficiency, reading and writing is buffered up to the number of
characters indicated by this
int.
Changing
bufsize
after a stream is used to read or write is not allowed and will result in an
invalidaccess
error.
| | callback(int mode, [, Function func[, int trigger]]) |
A built-in for associating a user function with reading or writing activity.
The
mode
can be
READ,
WRITE
or
EOF.
When the mode is
READ
or
WRITE,
a
trigger
should also be supplied in addition to the user-defined function,
func.
Once a callback for a particular mode is defined, then the supplied values for
func
and
trigger
can be retrieved by omitting those arguments in the call to this built-in.
When the mode is
READ
or
WRITE,
the supplied user function is called whenever the byte count exceeds the
trigger
value.
When the mode is
EOF,
the user function is called when read operations reach the end of the stream.
The byte count of activity since the callbacks were set-up
is automatically supplied as the sole argument
to the user function when it is called.
Note that the byte count increments depend on the
Stream
buffer size.
Thus, a trigger value of 5000 with a buffer size of 4096 means that the first
function call occurs when the byte count is 8192, namely after the
stream buffer is filled for the second time.
This built-in is useful for providing
interactive feedback using, for example, a
JProgressBar.
| | checksum |
When a checksum filter is activated, the current checksum value can be
obtained from this
double.
Note that for BSD and SYSV checksums, the built-in
chkstr
can be used to convert the value here to the more familiar string format.
Writing any value to this field causes the checksum calculation to be reset.
| | cipher |
allows the assigning of a cipher to the stream when either reading or writing.
The cipher should be suitable for the encrypting or decrypting of a large number
of bytes as opposed to a small number as might occur in a signature.
When assigning to this field, the value can be one of the following: a
Cipher,
an
Array
or a
Dictionary.
When the value is a
Dictionary,
it should contain at least two
String
fields, one called
transformation
and the other called
keystring.
Optionally, there can be a
String
field called
provider.
These field names correspond to those found in the
Cipher
object and have the same meaning.
The same information can be supplied in shorthand via an
Array.
In that case, two array elements can provide
transformation and keystring information, respectively,
while three array elements can provide
transformation, provider and keystring information, respectively.
When either an
Array
or
Dictionary
is used, the mode of the cipher is automatically set to
ENCRYPT_MODE
for a stream that is writing and to
DECRYPT_MODE
for a stream that is reading.
Changing
cipher
after a stream is used to read or write is not allowed and will result in an
invalidaccess
error.
| | connecttimeout |
A
double
that specifies how long to wait, in seconds, before giving up on the attempt
to establish a connection to
name.
A zero value disables timeouts and means wait forever.
Writing is allowed, but does not affect an existing attempt to establish a
connection.
| | encoding |
A
String
that indicates the type of byte-to-char encoding used when reading or the
char-to-byte encoding used for writing.
Changing
encoding
after a stream is used to read or write is not allowed and will result in an
invalidaccess
error.
| | file |
A read-only
String
field giving the filename portion of this URL.
| | filters |
One or more
int
flags can be combined to indicate how the stream should be filtered either for
input or output.
The flags are:
| BSD |
Indicates that a BSD-style checksum should be calculated on the stream.
| | CRC32 |
Indicates that a CRC32-style checksum should be calculated on the stream.
| | GZIP |
Indicates that the stream should use gzip compression when writing or
gzip decompression when reading.
| | HEXCODER |
Indicates that the stream should use hex encoding when writing or
hex decoding when reading.
Hex coding converts each character into bytes using ISO-8859-1 encoding and
then converts each byte into a two character hexadecimal string
with the high nybble first.
| | IETFCODER |
Indicates that the stream should use
IETF RFC 2396
encoding when writing or
IETF RFC 2396
decoding when reading.
IETF RFC 2396
encoding is used, for example by perl's
uri_escape.
| | LINEDHEXCODER |
Indicates that the stream should use fixed line length hex encoding when writing or
hex decoding that ignores line breaks when reading.
Output in this case is limited to 60 hex characters before a line break is inserted.
| | MIMECODER |
Indicates that the stream should use
x-www-mime-urlencoded
encoding when writing or
x-www-mime-urlencoded
decoding when reading.
x-www-mime-urlencoded
encoding is used, for example by Java's
URLEncoder
class.
| | SYSV |
Indicates that a SYSV-style checksum should be calculated on the stream.
| | ZIPPED |
Indicates that the stream should create when writing or decode when reading a
stream of bytes consistent with the ZIP format (such as Java jar files or
PKZIP files).
|
If checksum flags are used in combination with other checksum flags, the
result is to default to a SYSV checksum.
Changing
filters
after a stream is used to read or write is not allowed and will result in an
invalidaccess
error.
| | flushmode |
An
int
value that indicates the flushing strategy to use when writing.
The value can be one of:
| FLUSHDISABLED |
Do not flush output automatically except when the output buffer is full.
| | FLUSHLINES |
Flush output after each line-at-a-time write request.
Note that
writing an end-of-line character will not automatically cause a flush.
| | FLUSHWRITES |
Flush output after each write request.
|
An alternative is to explicitly call
the
fflush
built-in.
| | fullname |
A read-only
String
field giving the full external form of this URL.
| | host |
A read-only
String
field giving the hostname portion of this URL.
| | ifmodifiedsince |
Setting the value of this
double
field indicates that if the target of this URL should only be retrieved if it
has been modified since the specified time, which is in the format of the
time
built-in.
This field is included to provide full access to the underlying Java
standard
URLConnection class, but it has not been observed to have any effect.
Changing
ifmodifiedsince
while a stream is open is not allowed and will result in an
invalidaccess
error.
| | interrupted |
An
int
that counts the number of times read operations on this URL are interrupted.
An interrupted read operation automatically increments
interrupted
before returning a value that indicates the end-of-input.
Writing is allowed and is the only way to reset
interrupted
to zero.
| | marksupported |
An
int
value indicating if the
mark
and
reset
built-ins are supported by this stream.
A non-zero value means that they are supported.
| | mode |
An
int
value describing the mode of access, which is either
READ,
WRITE
or both together.
If the flag
UPDATE
is also supplied, the result is that the underlying Java URLConnection will
set the connection to allow user interaction.
If
APPEND
is provided, it is ignored.
Changing
mode
while a stream is open is not allowed and will result in an
invalidaccess
error.
| | name |
A
String
value giving the URL for this connection.
Changing
name
while a stream is open is not allowed and will result in an
invalidaccess
error.
| | nextbuf |
If the stream is open for writing, then assigning a
String
to this field will write it to the stream.
If the stream is open for reading, then by requesting the value of
this field, up to
bufsize
characters will be read from the stream and returned.
When there is nothing to read,
NULL
is returned.
| | nextchar |
If the stream is open for writing, then assigning a
int
within the range 0 to 0xFFFF
to this field will write it to the stream as a character.
If the stream is open for reading, then by requesting the value of
this field, the next
character will be read from the stream and returned.
When there is nothing to read,
NULL
is returned.
| | nextentry |
When a
ZIPPED
filter is active and
the stream is open for writing, then assigning a
ZipEntry
to this field will write it to the stream, appropriately closing any
existing entry being written.
When a
ZIPPED
filter is active and
the stream is open for reading, then requesting the value of this field
causes the current entry being read, if any, to be closed and a
ZipEntry
describing the next entry int the stream to be returned.
When there is nothing to read,
NULL
is returned.
Accessing this field when a
ZIPPED
filter is not active causes an
invalidaccess
error.
| | nextline |
If the stream is open for writing, then assigning a
String
to this field will write it to the stream with a new-line appended.
If the stream is open for reading, then by requesting the value of
this field, all characters up to the next new-line will be returned
from the input stream.
The new-line itself is not returned.
When there is nothing to read,
NULL
is returned.
| | open |
An
int
value indicating the open/close status of the stream.
A non-zero value indicates the stream is open for access.
Setting this value causes the stream to be opened or closed.
| | port |
A read-only
String
field giving the port information for this URL.
| | protocol |
A read-only
String
field giving the protocol information for this URL.
| | readtimeout |
A
double
that specifies how long, in seconds, a read operation will wait for data
before giving up.
A zero value disables timeouts and means wait forever.
Writing is allowed, but does not affect a read operation that has already
started.
| | ready |
An
int
value indicating, when it is non-zero, that the stream can be read without
blocking.
| | requestheader |
A
Dictionary
or an
Array
of
String
pairs in
name/value
order that are the header fields sent from the client to the server
when the connection is established.
The default
User-Agent
field identifies itself as the Yoix interpreter, but an explicit
User-Agent
entry in
requestheader
can be used to override the default.
Changing
requestheader
while a stream is open is not allowed and will result in an
invalidaccess
error.
| | requestmethod |
A
String
that should be a case-independent variation of
"DELETE",
"GET",
"HEAD",
"OPTIONS",
"POST",
"PUT",
or
"TRACE",
that sets the request method for this
URL.
By default a
URL
opened for reading uses
"GET"
while one opened for reading and writing uses
"POST".
Writing is allowed, but does not affect an open
URL.
| | responsecode |
A read-only
int
that is the status code returned by the server.
| | responseerror |
A read-only
String
that represents the error messages that were received from the server.
Servers that handle http connections usually return HTML that describes
the error and could be displayed by a
JTextPane.
| | responseheader |
A read-only
Dictionary
that are the response header fields that were sent from the server
to the client.
Requesting this field causes the URL stream to stop writing to the connection,
if it had been in write mode, and start reading from the connection.
| | responsekeycase |
An
int
that determines the case of the key strings that appear in the
responseheader.
A negative value means lower-case, a positive value means upper-case, and
0,
which is the default,
means no changes will be made to the key strings.
| | size |
The content-length of the stream target, if that information has been
provided by the server.
Requesting this field causes the URL stream to stop writing to the connection,
if it had been in write mode, and start reading from the connection.
| | usecaches |
An
int
whose value, when non-zero, indicates that caching by the server is
permitted, if the capability exists.
Changing
usecaches
while a stream is open is not allowed and will result in an
invalidaccess
error.
|
Several permanent fields have not been documented and should not be
used in Yoix applications.
Certain
URL
fields, namely:
can have side-effects when accessed.
Therefore, they must be explicitly referenced for their value
to be retrieved.
Simply dumping the entire
File
will only display a default value for these fields.
| |
| Example: |
The program,
import yoix.*.*;
String isbn = argc > 1 ? argv[1] : "0201633574";
URL u = open("http://www.amazon.com/exec/obidos/ASIN/" + isbn, READ);
String line;
String title;
String price;
while (line = u.nextline) {
if (indexOf(line, "Amazon.com:") == 0)
sscanf(line, "Amazon.com: buying info: %[^\0]", &title);
else if (indexOf(line, "Our Price:") != -1) {
line = u.nextline;
sscanf(line, "%*[^$]%[^<]<", &price);
}
}
stdout.nextline = title + " => " + price;
searches for a book at Amazon.com using the ISBN number and print the
title and price on standard output,
which would look something like:
Firewalls and Internet Security => $36.95
| | |
| See Also: |
close,
File,
fopen,
open,
read,
readChar,
readLine,
readStream,
Stream,
StringStream,
urlDecode,
urlEncode,
write,
writeChar,
writeLine,
ZipEntry
|
|
