Chapter 6 Wrapped Class Reference
6.4 Input/Output
The purpose of the Input/Output (IO) wrapped classes are to allow different operations that include file access, network access (ftp and http) and supports different notification of IOstreams. Documentation for the following classes appear in this section:
- Section 6.4.1, "IOactNotify" page 201
- Section 6.4.2, "IOnwNotify" page 201
- Section 6.4.3, "IOstream - Abstract" page 202
- Section 6.4.4, "IOfile" page 205
- Section 6.4.5, "IOfileSpec" page 206
- Section 6.4.6, "IOpipe" page 207
- Section 6.4.7, "IOurl" page 208
- Section 6.4.8, "IOweb - Abstract" page 211
- Section 6.4.9, "IOftp" page 212
- Section 6.4.10, "IOhttp" page 215
- Section 6.4.11, "IOwebRequest - Abstract" page 218
- Section 6.4.12, "IOftpRequest" page 219
- Section 6.4.13, "IOhttpRequest" page 220
- Section 6.4.14, "IOwebEntity - Abstract" page 221
- Section 6.4.15, "IOftpEntity" page 222
- Section 6.4.16, "IOhttpEntity" page 222
- Section 6.4.17, "IOwebStream - Abstract" page 223
- Section 6.4.18, "IOftpStream" page 225
- Section 6.4.19, "IOhttpStream" page 227
- Section 6.4.20, "XNstream" page 229
The class inheritance tree diagram for the Input/Output (IO) wrapped classes of AM2 appears in Figure 6.47.
Figure 6.47: Input/Output Wrapped Classes Inheritance Tree
6.4.1 IOactNotify
This class allows notification on file stream events. It is used in combination with the IOfile object. There must be one instance of this class for each activity.
Superclasses
Section 6.1.2, "Activity Manager - Abstract" page 116
Section 6.1.3, "Attribute Manager - Abstract" page 118
Methods
upon CreateFromStream: handle hStream
Creates an instance to monitor the specified stream (hStream should be a handle to an instance of class IOfile).
on IsValidActivity: string actName return boolean
Returns TRUE if actName is a valid activity, FALSE otherwise.
Attributes
None
Activities
IOactNotify Activities
Activity | Keys | Description |
ReadReady | none | data is ready for reading from port |
WriteReady | none | OK to send data to port |
ExceptionReady | none | exception encountered |
Example
None
6.4.2 IOnwNotify
This class allows notification on network stream events. It is used with a network stream object, such as XNstream. There needs to be one instance of this class for each activity.
Superclasses
Section 6.1.2, "Activity Manager - Abstract" page 116
Section 6.1.3, "Attribute Manager - Abstract" page 118
Methods
upon CreateFromPort: integer port
Creates an instance to monitor the specified network port. This constructor is used when you first waits for connection request from other AM2 application without blocking. This constructor is used in combination with ConnectReady activity. You cannot use this constructor for ReadReady activity.
upon CreateFromStream: handle hStream
Creates an instance to monitor the specified stream (hStream should be a handle to an instance of class XNstream). This constructor is used together with ReadReady activity.
on IsValidActivity: string actName return boolean
Returns TRUE if actName is a valid activity, FALSE otherwise.
on AcceptXN: return handle
Like Accept, but returns a handle to an instance of class XNstream instead.
Attributes
None
Activities
IOnwNotify Activities
Activity | Keys | Description |
ConnectReady | none | connection requested |
ReadReady | none | data is ready for reading from port (after connection established) |
WriteReady | none | OK to send data to port (after connection established) |
ExceptionReady | none | exception encountered |
Example
None
6.4.3 IOstream - Abstract
This abstract class serves as a foundation class which contributes to the functionality of the subclasses IOfile and IOpipe.
Superclasses
Section 6.1.2, "Activity Manager - Abstract" page 116
Section 6.1.3, "Attribute Manager - Abstract" page 118
Methods
on Good: return boolean
Returns true if the file is open and ready to be accessed. This returns false if the file was not opened successfully, has been closed, or an error has occurred.
on Bad: return boolean
Returns true if the object does not contain a valid open file reference.
on Fail: return boolean
Returns true if the previous action was not successful. If this returns true then all operations fail until Clear is called.
on Ready: return boolean
Returns true if an input or output operation (as appropriate for the type of file initially opened) does not block.
on Eof: return boolean
Returns true if the file was opened in an input mode and the end of the file has been reached.
on SendBoolean: boolean val
on SendInteger: integer val
on SendReal: real val
on SendString: string val
on SendList: list val
on SendInterval: interval val
on SendTime: time val
on SendAny: any val
Writes specified value to the stream. These methods also accessable via ADL << operator.
on ReceiveBoolean: return boolean
on ReceiveInteger: return integer
on ReceiveReal: return real
on ReceiveString: return string
on ReceiveList: return list
on ReceiveInterval: return interval
on ReceiveTime: return time
on ReceiveAny: return any
Reads a value of specified type from file. These methods also accessable via ADL>>operator.
on Oct /on Dec / on Hex
Sets output mode for numbers to the specified radix (octal, decimal, or hexadecimal, respectively).
on Endl
Writes an end-of-line character to the file.
on Flush
Flushes the output stream. This has no effect on read only files.
on Text
Sets the file to text mode. In this mode, all data is converted to text before being written and converted from text when read. If conversion cannot be performed (i.e., the following data in the file is not of the correct format for the type being read), the operation fails.
on Binary
Sets the file to binary mode. In this mode, all data is output in binary form, and input is assumed to be in binary form. This format is not recommended, as it is not portable. Sending and receiving lists and intervals in binary mode fails, as does ReceiveAny.
on Tagged
Sets the file to tagged mode. In this mode, data is written as in binary mode, but preceded by a single byte tag which determines the format of the data. Strings are proceeded by an additional length tag. Input data is assumed to be in tagged format. Any discrepancy between expected and received data is reported as an error.
on Word
On subsequent string input, whitespace is used as delimiters, and non-whitespace character sequences returned.
on Line
String output is followed by a platform dependent end of line sequence, and string input returns all characters until the next end of line, and discard the end of line sequence.
on NoDelim
String input returns all available text as a single string.
on WordDelim: string delim
Sets the whitespace characters for Word mode to the characters in delim.
on LineDelim: list delimseqs
Sets the end of line sequences for Line mode to the strings in the list given. The first string in the list is used as the line terminator in Line mode. The list must contain only strings.
Attributes
None
Activities
None
Example
None
6.4.4 IOfile
This class provides file input and output. It may be in either native or portable mode, written as text, binary, or tagged data.
Superclasses
Section 6.4.3, "IOstream - Abstract" page 202
Methods
upon OpenConstruct: string fName, string mode
Opens the file fName. All text written out is converted to a portable format (Unicode); binary data is not changed. The mode argument must be one of 'ReadOnly, 'ReadWrite, 'WriteTrunc, and 'WriteAppend.
upon OpenNativeConstruct: string fName, string mode
Opens the file fName. All text written out is in the machine's native encoding format. The mode argument must be one of 'ReadOnly, 'ReadWrite, 'WriteTrunc, and 'WriteAppend.
on Open: string fName, string mode
on OpenNative: string fName, string mode
Same as OpenConstruct and OpenNativeConstruct, except not constructors. To be used to open a different file once the initial one has been closed.
on Close
Flushes and closes the file. Any further reads or writes fail until another file is opened with Open or OpenNative.
Attributes
None
Activities
None
Example
- 1 anonymous : XFtop
- 2 {
- 3 IOfile file_stream;
- 4 string line;
- 5 upon Construct
- 6 {
- 7 {'OpenNative, "temp.txt", 'ReadOnly } => file_stream;
- 8 if ('Good => file_stream) {
- 9 'Line => file_stream;
- 10 while (! 'Eof => file_stream )
- 11 {
- 12 current_line = 'ReceiveString => file_stream;
- 13 echo (line + "\n\n");
- 14 }
- 15 'Close => file_stream;
- 16 }
- 17 else { echo("Invalid File \n"); }
- 18 }
- 19 } top;
6.4.5 IOfileSpec
This is a wrapped class for file name specification. Each AM2-supported platform specifies files in a different way: the syntax for using pathnames is different, or discouraged as on the Macintosh platform. IOfileSpec isolates these problems in one class and, to some extent, provides automatic conversion between different ways of specifying a file. There is no requirement that the specified file actually exist. IOfileSpec also performs some operations on closed files, like DeleteFile.
Superclasses
None
Methods
upon CreateFileSpec: string fName
Constructor with a file name, or a full or partial path.
on DeleteFile: return integer
Deletes the specified file.
on FileExists: return boolean
Returns TRUE if a file of this name exists, FALSE otherwise.
on GetName: return string
Returns the file name without a path.
on GetNameLength: return integer
Returns the length of the name that is being used in the path specification. If a path is used, the length of the path is included in the returned result. The result is not only platform-dependent, but also depends on how the file was specified to the constructor.
on GetPath: return string
Returns the file name together with the path with which the file was specified. On platforms that do not use pathnames internally, a full path name is created for this function and returned.
Attributes
None
Activities
None
Example
- 1 anonymous : XFtop
- 2 {
- 3 handle file_object;
- 4 string filename;
- 5 string path;
- 6
- 7 upon Construct
- 8 {
- 9 filename = "temp.txt";
- 10
- 11 file_object = new { 'CreateFileSpec, filename } =>
- 12 IOfileSpec;
- 13
- 14 if ('FileExists => file_object )
- 15 {path = 'GetPath => file_object;
- 16 echo("This is the path: " + path + " \n\n"); }
- 17
- 18 else
- 19 {echo("Filename: " + filename + " does not exist.\n\n"); }
- 20 }
- 21 } top;
6.4.6 IOpipe
This class represents an input stream from and an output stream to an external process. The interface is the same as that of the IOfile class (described on page 205) except that there are no public constructors and the Close method is as noted here.
Superclasses
Section 6.4.3, "IOstream - Abstract" page 202
Methods
On Close: return integer
Closes the pipe and waits for the external process to finish.
Note that this call can block indefinitely. Returns 0 if the process terminated normally, and a machine dependent non-zero value otherwise.
Attributes
None
Activities
None
Example
None
6.4.7 IOurl
This class provides a Uniform Resource Locator (URL) object for parsing and constructing URL strings formatted for the World-Wide Web.
Superclasses
None
Methods
upon Construct
Default constructor.
on ExtractAccessMethod: string url return string
Returns the access method in the url string. Example
access methods are http, ftp, etc.
on ExtractAnchorName: string url return string
Returns the anchor name in the url string. According to the URL format, the anchor name is marked by "#" in a URL string.
on IsAnchorReference: string url return boolean
Returns TRUE if this url string matches the format of a relative URL which references an internal anchor within an HTML document. According to the current URL format, an anchor reference URL begins with the "#" mark. This method does not verify the validity of the anchor reference.
on MakeAbsolute: string partial_url, string base_url return string
Expands partial_url into its full form in the context of base_url. Returns the expanded URL. The internal anchor in partial_url is kept in the returned full form. However, the anchor in base_url is not.
on Escape: string str return string
Returns the escaped str from unacceptable characters using%.
on UnEscape: string str return string
Returns the unescaped str which was previously escaped using%.
on ExtractHost: string url return string
Returns the hostname extracted from the url.
on ExtractPort: string url return integer
Returns the port number extracted from the URL. Returns -1 if no port was found. (Currently this method returns -1 if a default port was found in the URL).
on ExtractPath: string url return string
Returns the path string extracted from the url.
Attributes
None
Activities
None
Example
Given a Uniform Resource Locator, IOURL provides methods to extract different components in the URL string.
- 1 string url1;
- 2 string url2;
- 3 string base_url;
- 4 string canon_url;
- 5 handle hURL;
- 6 string str;
- 7 integer port;
- 8
- 9 upon Construct
- 10 {
- 11 //---------------------------------------
- 12 //Construct an IOurl
- 13 //---------------------------------------
- 14 hURL = new 'Construct => IOurl;
- 15 //---------------------------------------
- 16 //child_url is a relative URL to be interpolated
- 17 //using the base_url
- 18 //---------------------------------------
- 19 url1 = "cgi-bin/search?name=Dole department=CE";
- 20 url2 = " sipb/sipb.html#Students ";
- 21 base_url="http://www.mit.edu/mit-activities.html#Computers ";
- 22
- 23 url2 = {'StripWhiteSpace, url2 } => hURL;
- 24 base_url = {'StripWhiteSpace, base_url } => hURL;
- 25
- 26 echo ("\nPartial URL 1 is : " + url1 + "\n");
- 27 echo ("\nPartial URL 2 is : " + url2 + "\n");
- 28 echo ("Base URL is : " + base_url + "\n"); echo ("\n");
- 29 //---------------------------------------
- 30 //Given a parent url, expand the partial url to an
- 31 //absolute url using a base url.
- 32 //---------------------------------------
- 33 canon_url = {'MakeAbsolute, url1, base_url} => hURL;
- 34 echo ("Expanded URL1 is : " + canon_url + "\n");
- 35
- 36 canon_url = {'Escape, canon_url} => hURL;
- 37 echo ("Escaped URL1 is " + canon_url + "\n");
- 38
- 39 canon_url = {'MakeAbsolute, url2, base_url} => hURL;
- 40 echo ("Expanded URL2 is : " + canon_url + "\n");
- 41
- 42 echo ("Expanded URL2 has the following Components: \n");
- 43 echo ("------------------------------------------\n");
- 44 //---------------------------------------
- 45 //Extract different components in the parent URL
- 46 //---------------------------------------
- 47
- 48 str = {'ExtractAccessMethod, canon_url} => hURL;
- 49 echo ("ACCESS METHOD: " + str + "\n");
- 50 str = {'ExtractHost, canon_url} => hURL;
- 51 echo ("HOSTNAME: " + str + "\n");
- 52 port = {'ExtractPort, canon_url} => hURL;
- 53 echo ("PORT NUMBER: "); echo (port); echo ("\n");
- 54 str = {'ExtractPath, canon_url} => hURL;
- 55 echo ("PATH/OBJECT REFERENCE: " + str + "\n");
- 56 str = {'ExtractAnchorName, canon_url} => hURL;
- 57 echo ("ANCHOR: " + str + "\n\n");
- 58 echo ("Good-Bye.\n");
- 59 'Exit => theApp;
- 60 }
6.4.8 IOweb - Abstract
This abstract class provides client-side World-Wide Web protocol support. It manages a network connection to a Web server. Its subclasses include IOhttp and IOftp.
Superclasses
None
Methods
on Connect: string hostname, integer port
Establishes a connection with the server process on the specified host and port. You should call this method only after you use the default Constructor. You should call SendRequest to send a request.
on SendRequest: handle hRequest
Sends hRequest to the server. You should use this method if you had previously used the default Constructor and called Connect. "hRequest" must be a handle to an instance of an
IOwebRequest subclass.
on Request
Sends a request to the server. It is assumed that the request info was previously specified in a constructor such as ConstructFromURL or ConstructFromRequest.
on GetResponse: return integer
Waits for the server to return a response in blocking mode. It returns the server response status code, or -1 on failure.
on GetEntity: return handle
If the response contains a data entity, this method returns a handle to an instance of a
subclass of IOwebEntity. Otherwise, it returns a NULL handle. It should be noted that
IOwebEntity mainly allows you to access the entity headers (i.e., metainformation about a
data entity). If an entity body is returned from the server, you should construct an instance of
an IOwebstream subclass from the IOwebEntity in order to read the data body.
on Close
Closes the connection with the server. Note: If you had constructed an IOwebStream to extract data from this connection, you must not close this IOweb until you are done reading from the data stream.
on GetURL: return string
Returns the URL string associated with this Connection session. For HTTP connections, if
AutoRedirected is TRUE, this method returns the new URL used for this connection object.
on Good: return boolean
Returns TRUE if the connection is usable and that the last operation succeeded.
on Fail: return boolean
Returns TRUE if the last operation failed. The connection may still be ok.
on Bad: return boolean
Returns TRUE if something is wrong and the connection is unusable.
on Disconnected: return boolean
Returns TRUE if the connection is not active.
Attributes
None
Activities
None
Example
None
6.4.9 IOftp
This class provides client-side FTP protocol support. It manages a network connection to an FTP server. It is a subclass of IOweb.
Superclasses
Section 6.4.8, "IOweb - Abstract" page 211
Methods
upon Construct
Default constructor.You must call Connect, SendRequest, and GetResponse later.
upon ConstructFromURL: string url
Given a URL string, connects to the appropriate server. After this constructor, you can call Request to send a request to the server. It is assumed that the URL string contains sufficient information to send a request. The request defaults to GET. If you wish to specify methods other than GET in your request, use ConstructFromRequest.
upon ConstructFromRequest: handle hRequest
Given an HTTP request, connects to the appropriate server. After this constructor, you can call Request to send a request to the server. "hRequest" must be a handle to an instance of an
IOftpRequest or its subclass thereof.
on GetProtocolName: return string
Returns the string "FTP".
Attributes
None
Activities
None
Example
This program illustrates all FTP-related classes.
- 1 string url;
- 2 handle connection;
- 3 handle request;
- 4 handle entity;
- 5 handle stream;
- 6 string data;
- 7 string content_type;
- 8 integer content_len;
- 9 integer response_status;
- 10 string response_reason;
- 11 upon Construct
- 12 {
- 13 url = "ftp://ceci.mit.edu/pub/";
- 14 //-----------------------------------------------
- 15 //Construct an FTP request from the URL
- 16 //-----------------------------------------------
- 17 request = new {'Construct, url} => IOftpRequest;
- 18 //-----------------------------------------------
- 19 //Construct an IOftp and connects to the server
- 20 //-----------------------------------------------
- 21 connection = new {'ConstructFromRequest, request} => IOftp;
- 22 {'Check_Status, "connection"} => self;
- 23
- 24 {'GetIt, request} => self;
- 25 'Close => connection;
- 26 echo ("Closed FTP connection and stream. Good-Bye.\n");
- 27 'Exit => theApp;
- 28 }
- 29 on GetIt : handle aRequest
- 30 {
- 31 //-----------------------------------------------
- 32 //Send the request
- 33 //-----------------------------------------------
- 34 echo ("Connected!! Sending request...\n");
- 35 { 'SendRequest, aRequest} => connection;
- 36 {'Check_Status, "sent request"} => self;
- 37 //-----------------------------------------------
- 38 //Get the response
- 39 //-----------------------------------------------
- 40 echo ("Requst sent. Waiting for Response...\n");
- 41 response_status = 'GetResponse => connection;
- 42 {'Check_Status, "get response"} => self;
- 43 //-----------------------------------------------
- 44 //Get the Data Entity
- 45 //-----------------------------------------------
- 46 entity = 'GetEntity => connection;
- 47 if (entity == NULL)
- 48 { echo ("Sorry no data entity returned in the response.\n");
- 49 'Exit => theApp;
- 50 }
- 51 content_type = 'GetContentType => entity;
- 52 //-----------------------------------------------
- 53 //Get the Data Stream
- 54 //-----------------------------------------------
- 55 //Caution: connection object must be active for stream to work
- 56 stream = new {'ConstructFromConnection, connection, entity } =>
- 57 IOftpStream;
- 58 if ('Fail => stream)
- 59 {
- 60 echo ("Error opening FTP stream.\n");
- 61 }
- 62 else
- 63 {
- 64 //------------------------------------------------------
- 65 //If we have plaintext, directory, or HTML, get the data.
- 66 //------------------------------------------------------
- 67 if (content_type == "text/plain" ||
- 68 content_type == "text/ftp-directory" ||
- 69 content_type == "text/html")
- 70 { data = "";
- 71 while (! 'Eof => stream)
- 72 { data = data + 'ReceiveStringLine => stream + "\n"; }
- 73 echo("Received ftp Data is:\n"); echo(data); echo("\n");
- 74 }
- 75 else
- 76 { echo ("Ignore " + content_type +
- 77 " type in this test program.\n");
- 78 }
- 79 }
- 80 'Close => stream;
- 81 delete stream;
- 82 } //end of method GetIt
- 83 //-------------------------------------------------------------
- 84 //Check_Status
- 85 //--------------------------------------------------------------
- 86 on Check_Status : string where
- 87 {
- 88 if ('Fail => connection)
- 89 { echo ("Sorry " + where + " failed. Good-Bye.\n");
- 90 'Close => connection;
- 91 delete connection;
- 92 'Exit => theApp;
- 93 }
- 94 }
6.4.10 IOhttp
This class provides client-side HTTP/1.0 protocol support. It manages a network connection to an HTTP server. It is a subclass of IOweb.
Superclasses
Section 6.4.8, "IOweb - Abstract" page 211
Methods
upon Construct
Default constructor. You must call Connect, SendRequest, and GetResponse later.
upon ConstructFromURL: string url
Given a URL string, connects to the appropriate server. After this constructor, you can call
Request to send a request to the server. It is assumed that the URL string contains sufficient
information to send a request. The request defaults to GET. If you wish to specify methods
other than GET in your request, use ConstructFromRequest.
upon ConstructFromRequest: handle hRequest
Given an HTTP request, connects to the appropriate server. After this constructor,
you can call Request to send a request to the server. "hRequest" must be a handle
to an instance of an IOhttpRequest or its subclass thereof.
on AutoRedirected: return boolean
TRUE if we have been automatically redirected to another URL.
on ResponseReason: return string
Returns the response reason returned from the server. The reason string usually explains
why an HTTP request was not fulfilled by the server.
on GetProtocolName: return string
Returns the string "HTTP".
Attributes
None
Activities
None
Example
This program illustrates all HTTP-related classes.
- 1 string url;
- 2 handle connection;
- 3 handle request;
- 4 handle entity;
- 5 handle stream;
- 6 string data;
- 7 string content_type;
- 8 integer content_len;
- 9 integer response_status;
- 10 string response_reason;
- 11 //-------------------------------------------------------------
- 12 //Constructor
- 13 //-------------------------------------------------------------
- 14 upon Construct
- 15 {
- 16 //substitute this URL to your favorite http url for testing.
- 17 url = "http://abelard.mit.edu/";
- 18
- 19 //-----------------------------------------------
- 20 //Construct an HTTP request from the URL
- 21 //-----------------------------------------------
- 22 request = new {'Construct, url} => IOhttpRequest;
- 23
- 24 //The default method is GET, but you can set the
- 25 //method to something else, e.g. HEAD, by doing this:
- 26 //{'SetMethod, "HEAD"} => request;
- 27
- 28 //Let's see what our request line looks like...
- 29 echo ("Full HTTP Request line is \n");
- 30 echo ('RequestLine => request);
- 31
- 32 //-----------------------------------------------
- 33 //Construct an IOhttp and connects to the server
- 34 //-----------------------------------------------
- 35 connection = new {'ConstructFromRequest, request} => IOhttp;
- 36
- 37 //Check if we have successfully connected
- 38 {'Check_Status, "connection"} => self;
- 39
- 40 //-----------------------------------------------
- 41 //Send the request
- 42 //-----------------------------------------------
- 43 echo ("Connected!! Sending request...\n");
- 44 'Request => connection;
- 45
- 46 //Check if request has been sent successfully
- 47 {'Check_Status, "sent request"} => self;
- 48
- 49 //-----------------------------------------------
- 50 //Get the response
- 51 //-----------------------------------------------
- 52 echo ("Requst sent. Waiting for Response...\n");
- 53 response_status = 'GetResponse => connection;
- 54
- 55 {'Check_Status, "get response"} => self;
- 56
- 57 response_reason = 'ResponseReason => connection;
- 58 echo ("Response Status Code: " + response_status + " \n");
- 59 echo ("Response Reason: " + response_reason + " \n");
- 60
- 61 //-----------------------------------------------
- 62 //Get the Data Entity
- 63 //-----------------------------------------------
- 64 //If we got a response, get the Data Entity
- 65 entity = 'GetEntity => connection;
- 66
- 67 //it's possible that the response does not contain any entity
- 68 if (entity == NULL)
- 69 { echo ("Sorry no data entity returned in the response. \n");
- 70 'Exit => theApp;
- 71 }
- 72
- 73 //Get some metainformation on this data entity
- 74 content_type = 'GetContentType => entity;
- 75 content_len = 'GetContentLen => entity;
- 76
- 77 echo ("Content Type: " + content_type + " \n");
- 78 echo ("Content Length: "); echo (content_len); echo ("\n");
- 79
- 80 if (! ('HasBody => entity))
- 81 { echo ("Sorry, no data body included in the response.\n");
- 82 'Close => connection;
- 83 'Exit => theApp;
- 84 }
- 85
- 86 //-----------------------------------------------
- 87 //Get the Data Stream
- 88 //-----------------------------------------------
- 89 //Caution: connection object must be active for stream to work
- 90 stream = new {'ConstructFromConnection, connection, entity }
- 91 => IOhttpStream;
- 92
- 93 if ('Fail => stream)
- 94 {
- 95 echo ("Error opening HTTP stream.\n");
- 96 }
- 97 else
- 98 {
- 99 //-----------------------------------------------
- 100 //If we have plaintext or HTML, get the data.
- 101 //-----------------------------------------------
- 102 if (content_type == "text/plain" ||
- 103 content_type == "text/html")
- 104 { data = "";
- 105 while (! 'Eof => stream)
- 106 {
- 107 data = data + 'ReceiveStringLine => stream + "\n";
- 108
- 109 if ('Eof => stream)
- 110 { echo ("end of stream!\n"); break; }
- 111 }
- 112
- 113 echo("Received HTTP Data is:\n"); echo(data); echo("\n");
- 114 }
- 115 else //ignore any other types of data in this test program
- 116 {
- 117 echo ("Ignore data of " + content_type +
- 118 " type in this test program.\n");
- 119 }
- 120 }
- 121 'Close => stream;
- 122 'Close => connection;
- 123
- 124 echo ("Closed HTTP connection and stream. Good-Bye.\n");
- 125 'Exit => theApp;
- 126 }
- 127 //-------------------------------------------------------------
- 128 //Check_Status
- 129 //-------------------------------------------------------------
- 130 on Check_Status : string where
- 131 {
- 132 if ('Fail => connection)
- 133 { echo ("Sorry " + where + " failed. Good-Bye.\n");
- 134 'Close => connection;
- 135 'Exit => theApp;
- 136 }
- 137 }
6.4.11 IOwebRequest - Abstract
This abstract class represents a client-side request to a World-Wide Web server. Its subclasses include IOhttpRequest and IOftpRequest.
Superclasses
None
Methods
on SetMethod: string method
Use this method to specify the request operation. For HTTP request, the methods
may be GET, POST, or HEAD. For FTP, the only supported operation in this release
is GET, which is the default. No validity checking of the method is performed.
If not set, the default method is GET.
on GetMethod: return string
Returns the name of the request method contained in this request structure.
on SetEntity: handle hEntity
Use this method to specify the data Entity you wish to send to the server as
part of the request. This is necessary for HTTP method such as POST -- mostly
used for sending HTML fill-out form content to the server. "hEntity" should
be a handle to an instance of an IOwebEntity subclass.
on GetURL: return string
Returns the URL string used to construct this request object.
on GetHost: return string
Returns the hostname as specified in this request structure. The hostname is
usually extracted from the URL string from which this request was constructed.
on GetPort: return integer
Returns the port number specified in this request structure. The port number is
usually extracted from the URL string of this request. If no port number
is specified in the URL, a default port number (80 for HTTP) is used.
Attributes
None
Activities
None
Example
None
6.4.12 IOftpRequest
Represents an FTP request structure to an FTP server. This class is a subclass of IOwebRequest.
Superclasses
Section 6.4.11, "IOwebRequest - Abstract" page 218
Methods
upon Construct: string url
Default constructor which constructs an FTP request using the specified URL.
Attributes
None
Activities
None
Example
For a sample program using this IOftpRequest see "IOftp" on page 212.
6.4.13 IOhttpRequest
Represents an HTTP/1.0 request structure. This class allows you to construct an HTTP request based on a URL string. In particular, it allows you to specify various HTTP request header fields. A request header is not sent if its value is not set. This class is a subclass of IOwebRequest.
Note: If you want to send an HTTP POST request, you should construct an instance of this class, and set the method to POST. You should also construct an IOhttpEntity which contains the POST data, and then use SetEntity method in this class to enclose the Entity as part of the POST request.
Superclasses
Section 6.4.11, "IOwebRequest - Abstract" page 218
Methods
upon Construct: string url
Default constructor which constructs an HTTP request using the specified URL.
on SetUserAgent: string agentName
Use this method to specify the user agent originating the request. The default value for this
field is "Experimental-HTTP-Client". Please refer to HTTP/1.0 specification for detail.
on GetUserAgent: return string
Returns the value of the User Agent header field.
on SetFrom: string fromAddress
Sets the From header field which contains an Internet email address of the user who controls
the requesting user agent. Please refer to HTTP/1.0 specification for detail.
on GetFrom: return string
Returns the value of the From field.
on RequestLine: return string
Returns the full request line in HTTP/1.0 format. This method is mainly for debugging
purposes and is subject to changes by final release.
on RequestHeaders: return string
Returns the formatted request header fields (not including the Entity headers in HTTP/1.0
format. This method is mainly for debugging purposes and is subject to changes.
Attributes
None
Activities
None
Example
For an example using IOhttpRequest see "IOhttp" on page 215.
6.4.14 IOwebEntity - Abstract
Represents a World-Wide Web data entity. An IOwebEntity can be enclosed within a Web request as part of the request data. It can also be part of a Web response data returned from the server. Its subclasses include IOhttpEntity and IOftpEntity.
Superclasses
None
Methods
on SetContentType: string type
Use this method to specify the content type of this entity. This method is only meaningful if this entity is to be included as part of a Web request. The content type string should follow the MIME content type format, e.g., text/plaintext, text/html, and image/gif, and so forth. Note: For POST HTML form data, the content type is usually set to application/x-www-form-urlencoded.
on GetContentType: return string
Returns the content type of this entity.
Attributes
None
Activities
None
Example
None
6.4.15 IOftpEntity
Represents an FTP data entity. Currently, an IOftpEntity can only be part of the response data from the server. It cannot be part of a request structure, since we do not yet support "put" for FTP. This class is a subclass of IOwebEntity.
Superclasses
Section 6.4.14, "IOwebEntity - Abstract" page 221
Methods
upon Construct
Default constructor.
Attributes
None
Activities
None
Example
For a sample program using the IOftpEntity class, see "IOftp" on page 212.
6.4.16 IOhttpEntity
Represents an HTTP data entity. An entity consists of entity headers (metainformation) and entity body (content). An HTTP entity may be enclosed within an HTTP request or an HTTP response message. If the entity is to be part of an HTTP request, you can set both the entity headers and data content. If the entity is part of an HTTP response from a network connection, this class allows you to get the entity headers, but not the entity body. You must construct an IOhttpStream from this entity in order to retrieve data from the network connection. This class is a subclass of IOwebEntity.
Superclasses
Section 6.4.14, "IOwebEntity - Abstract" page 221
Methods
upon Construct
Default constructor.
on GetContentLen: return integer
Returns the content length of this Entity.
on SetContentString: string content
Use this method to specify the data content of this Entity. This method is only meaningful if
this Entity is to be included as part of an HTTP request. Use IOurl Escape method to encode
your data. This method is considered experimental, and is subject to changes by the final
release.
on HasBody: return boolean
Returns TRUE if this Entity has an Entity Body; otherwise, FALSE. (Use this method to check whether you should construct an IOhttpStream to access the Entity Body.)
Attributes
None
Activities
None
Example
For a sample program using IOhttpEntity, see "IOhttp" on page 215 .
6.4.17 IOwebStream - Abstract
This abstract class represents an input data stream from a World-Wide Web connection. Its subclasses include IOhttpStream and IOftpStream. Normally a Web stream contains media-specific data, and should be given to an appropriate media element to load the data. However, it is also possible to use the various receive methods below to get the data directly at the ADL level. (Note: these receive methods are experimental and are subject to changes.)
Superclasses
None
Methods
on OpenFromURL: string url
Given a URL, establishes a connection, sends a request, and gets a response from the server. The default request to the server is to "get" or "retrieve" the document referenced by the URL.
on OpenFromRequest: handle hRequest
The action of this method is equivalent to OpenFromURL, except that you can specify a more complicated request structure via "hRequest". For example, in the case of an HTTP request, it is possible to set the HTTP method to POST or HEAD in hRequest. "hRequest" must be a handle to an instance of an IOwebRequest subclass.
on OpenFromConnection: handle hConnection, handle hEntity
This method is used when you had previously established a connection and obtained a valid response from a server using an instance of IOweb subclass. "hConnection" must be a handle to an instance of an IOweb subclass. "hEntity" must be a handle to an IOwebEntity subclass.
on GetURL: return string
Returns the URL string associated with this data stream. If URL redirection was performed (HTTP only), this method returns the final URL used to retrieve the data at hand.
on Close
Closes this http data stream.
on Good: return boolean
Returns TRUE if the stream is usable and that the last operation on the stream succeeded.
on Fail: return boolean
Returns TRUE if the last operation on the stream failed. The stream may still be usable.
on Bad: return boolean
Returns TRUE if the stream is unusable.
on Eof: return boolean
Returns TRUE if end-of-file flag is set on the stream.
on ReceiveBoolean: return boolean
on ReceiveInteger: return integer
on ReceiveReal: return real
on ReceiveStringLine: return string
on ReceiveStringWord: return string
on ReceiveList: return list
on ReceiveAny: return any
Attributes
None
Activities
None
Example
None
6.4.18 IOftpStream
This class represents an input data stream from an FTP connection. It is a subclass of
IOwebStream.
Superclasses
Section 6.4.17, "IOwebStream - Abstract" page 223
Methods
upon Construct
Default constructor. Constructs an IOftpStream without opening the stream. You must call
OpenFromURL, OpenFromRequest, or OpenFromEntity to open the stream.
upon ConstructFromURL: string url
Given a URL string, constructs and opens an FTP data stream. This constructor is equivalent
to calling Construct and then OpenFromURL.
upon ConstructFromRequest: handle hRequest
Given a handle to an FTP request, constructs and open an FTP data stream. This constructor
is equivalent to calling Construct and then OpenFromRequest.hRequest must be a handle to
IOftpRequest or its subclass thereof.
upon ConstructFromConnection: handle hConnection, handle hEntity
Given a handle to an FTP connection and an FTP Entity, constructs an FTP data stream to access the body of the Entity from the connection. This constructor is equivalent to calling Construct and then OpenFromConnection. "hConnection" must be a handle to an instance of an IOftp or its subclass thereof. "hEntity" must be a handle to an instance of an IOftpEntity or its subclass thereof.
on GetContentType: return string
Returns the media type of the FTP data Entity contained in this stream. If the data at hand contains directory information, the content type is text/ftp-directory. This method is experimental and is subject to changes.
on ReceiveDirectory: return list
This method reads and parses the directory information contained in the FTP stream. I returns
the parsed directory listing as a list. The returned list consists of sublists, each of which represents an entry/item in directory listing. Each sublist contains the following components:
(1) a string to indicate the item type, which can be "dir", "link", or "file";
(2) a string to indicate item or file name; and (3) an integer to indicate item or file size.
Attributes
None
Activities
None
Example
- 1 string url;
- 2 handle stream;
- 3 string data;
- 4 string content_type;
- 5 integer content_len;
- 6
- 7 upon Construct
- 8 {
- 9 //substitute this url to your favorite ftp url for testing
- 10 url = "ftp://ceci.mit.edu/pub/";
- 11 //----------------------------------------------------------
- 12 //Construct an FTP stream without opening it
- 13 //----------------------------------------------------------
- 14 stream = new 'Construct => IOftpStream;
- 15
- 16 //----------------------------------------------------------
- 17 //Open the stream by giving it a URL. OpenFromURL will connect
- 18 //to the server, sends a request to, and gets a response back.
- 19 //----------------------------------------------------------
- 20 {'OpenFromURL, url} => stream;
- 21
- 22 //----------------------------------------------------------
- 23 //Check the status.
- 24 //----------------------------------------------------------
- 25 if ('Fail => stream)
- 26 {
- 27 echo ("Failed in opening FTP stream.\n");
- 28 'Exit => theApp;
- 29 }
- 30 content_type = 'GetContentType => stream;
- 31
- 32 //------------------------------------------
- 33 //if we have a plaintext or html, use
- 34 //ReceiveStringLine to get the data...
- 35 //------------------------------------------
- 36 if (content_type == "text/plain" ||
- 37 content_type == "text/ftp-directory" ||
- 38 content_type == "text/html")
- 39 { data = "";
- 40 while (! 'Eof => stream)
- 41 { data = data + 'ReceiveStringLine => stream + "\n"; }
- 42 echo ("Received FTP Data is:\n"); echo (data); echo (" \n");
- 43 }
- 44 'Close => stream;
- 45 echo ("Closed FTP stream. Good-Bye.\n");
- 46 'Exit => theApp;
- 47 }
6.4.19 IOhttpStream
This class represents an input data stream from an HTTP connection. It is a subclass of
IOwebStream.
Superclasses
Section 6.4.17, "IOwebStream - Abstract" page 223
Methods
upon Construct
Default constructor. Constructs an IOhttpStream without opening the stream. You must call
OpenFromURL, OpenFromRequest, or OpenFromEntity to open the stream.
upon ConstructFromURL: string url
Given a URL string, constructs and opens an HTTP data stream. This constructor is
equivalent to calling Construct and then OpenFromURL.
upon ConstructFromRequest: handle hRequest
Given a handle to an HTTP request, constructs and open an HTTP data stream. This constructor is equivalent to calling Construct and then OpenFromRequest. hRequest must be a handle to IOhttpRequest or its subclass thereof.
upon ConstructFromConnection: handle hConnection, handle hEntity
Given a handle to an HTTP connection and an HTTP Entity, constructs an HTTP data stream to access the body of the Entity from the connection. This constructor is equivalent to calling Construct and then OpenFromConnection. "hConnection" must be a handle to an instance of an IOhttp or its subclass thereof. "hEntity" must be a handle to an instance of an IOhttpEntity or its subclass thereof.
on GetContentType: return string
Returns the media type of the HTTP data Entity contained in this stream.
on GetContentLen: return integer
Returns the expected size of the Entity (or data) body contained in this stream. The return
result of this method should be used with caution, as not all HTTP data streams have the
content length field set. A return result of zero should be interpreted as either that the stream
is unavailable or that the content length field is not specified.
Attributes
None
Activities
None
Example
- 1 string url;
- 2 handle stream;
- 3 string data;
- 4 string content_type;
- 5 integer content_len;
- 6
- 7 upon Construct
- 8 {
- 9 //substitute this url to your favorite http url for testing
- 10 url = "http://abelard.mit.edu/";
- 11
- 12 //---------------------------------------------------------
- 13 //Construct an HTTP stream without opening it
- 14 //---------------------------------------------------------
- 15 stream = new 'Construct => IOhttpStream;
- 16
- 17 //---------------------------------------------------------
- 18 //Open the stream by giving it a URL. OpenFromURL will connect
- 19 //to the server, sends a request to, and gets a response from it.
- 20 //---------------------------------------------------------
- 21 {'OpenFromURL, url} => stream;
- 22
- 23 //---------------------------------------------------------
- 24 //Check the status. For HTTP streams, it is a failure if there is
- 25 //no data entity body in the response from the server.
- 26 //---------------------------------------------------------
- 27 if ('Fail => stream)
- 28 {
- 29 echo ("Failed in opening HTTP stream.\n");
- 30 'Exit => theApp;
- 31 }
- 32 //------------------------------------------
- 33 //Check the content type and content length
- 34 //of the data entity in this stream
- 35 //------------------------------------------
- 36 content_len = 'GetContentLen => stream;
- 37 content_type = 'GetContentType => stream;
- 38
- 39 echo ("Content-Type : " + content_type + "\n");
- 40 echo ("Content-Len : "); echo (content_len); echo (" \n");
- 41 //------------------------------------------
- 42 //if we have a plaintext or html, use
- 43 //ReceiveStringLine to get the data...
- 44 //------------------------------------------
- 45 if (content_type == "text/plain" ||
- 46 content_type == "text/html")
- 47 { data = "";
- 48 while (! 'Eof => stream)
- 49 {
- 50 data = data + 'ReceiveStringLine => stream + "\n";
- 51 if ('Eof => stream)
- 52 { echo ("end of stream!\n"); }
- 53 }
- 54 echo("Received HTTP Data is:\n"); echo(data); echo("\n");
- 55 }
- 56 'Close => stream;
- 57 echo ("Closed HTTP stream. Good-Bye.\n");
- 58 'Exit => theApp;
6.4.20 XNstream
This class is a network input/output stream object with XDR data representation.
Superclasses
None
Methods
upon Construct
Default constructor.
upon ListenConstruct: integer port
Waits for connection on specified port.
upon ConnectConstruct: string host, integer port
Attempts to make a connection to the specified port on the specified host.
on Listen: integer port
on Connect: integer port, string host
Same as ListenConstruct and ConnectConstruct, but not constructors.
on SendBoolean: boolean val
on SendInteger: integer val
on SendReal: real val
on SendString: string val
on SendList: list val
on SendAny: any val
Writes the specified value to the network connection.
on ReceiveBoolean: return boolean
on ReceiveInteger: return integer
on ReceiveReal: return real
on ReceiveString: return string
on ReceiveList: return list
on ReceiveAny: return any
Reads a value of the specified type from the network connection.
on Close
Closes connection.
on Good
Returns a status of stream. If TRUE, stream is healthy and connection is alive.
Attributes
None
Activities
None
Example 1
This program demonstrates receiving a list from a network stream. The applications ends when the list has been received.
- 1 uses "nro.adl"@"StdLib";
- 2 class Message : ActivityManager
- 3 {
- 4 integer portNumber;
- 5 vanillaNro {'Create, 'ConnectReady, self, 'GetMessage, FALSE} =>
- 6 connectNro;
- 7 //* used to notify object when message arrives
- 8 handle hNetNotify;
- 9 handle hMessageStream; /* used to send and receive messages */
- 10 list ActivityInfo = {{'ReceiveMessage, {"message"}}};
- 11
- 12 upon Construct: integer port
- 13 {
- 14 portNumber = port;
- 15 hNetNotify = new {'CreateFromPort, portNumber} => IOnwNotify;
- 16 {'Subscribe, &connectNro} => hNetNotify;
- 17 }
- 18
- 19 on GetMessage: boolean cd
- 20 {
- 21 any message;
- 22 hMessageStream = 'AcceptXN => hNetNotify;
- 23 {'Unsubscribe, &connectNro} => hNetNotify;
- 24 delete hNetNotify;
- 25 message = 'ReceiveAny => hMessageStream;
- 26 'Close => hMessageStream;
- 27 delete hMessageStream;
- 28 hNetNotify = new {'CreateFromPort, portNumber} => IOnwNotify;
- 29 {'Subscribe, &connectNro} => hNetNotify;
- 30 {'TriggerNotification, 'ReceiveMessage, {message}}=> self;
- 31 }
- 32
- 33 on Destroy
- 34 {
- 35 {'Unsubscribe, &connectNro} => hNetNotify;
- 36 delete hNetNotify;
- 37 }
- 38 };
- 39
- 40 upon Construct
- 41 {
- 42 integer portnum = 8900;
- 43 Message {'Construct, portnum} => myMessage;
- 44 nro{'Create, 'ReceiveMessage, self, 'GetMessage, TRUE}=> messNro;
- 45 {'Subscribe, &messNro} => myMessage;
- 46 {'GetMessage, TRUE} => myMessage;
- 47 }
- 48 on GetMessage: any cd, list names, list vals
- 49 {
- 50 echo (vals);}
Example 2
This program demonstrates sending a list over a network stream.
- 1 uses "nro.adl"@"StdLib";
- 2
- 3 class Message : ActivityManager
- 4 {
- 5 integer portNumber;
- 6 vanillaNro {'Create, 'ConnectReady, self, 'GetMessage, FALSE} =>
- 7 connectNro;
- 8 // used to notify object when message arrives
- 9 handle hNetNotify;
- 10 // used to send and receive messages
- 11 handle hMessageStream;
- 12 list ActivityInfo = {{'ReceiveMessage, {"message"}}};
- 13
- 14 upon Construct: integer port
- 15 {
- 16 portNumber = port;
- 17 hNetNotify = new {'CreateFromPort, portNumber} => IOnwNotify;
- 18 {'Subscribe, &connectNro} => hNetNotify;
- 19 }
- 20
- 21 on SendMessage: any message, string host, integer port
- 22 {
- 23 {'Unsubscribe, &connectNro} => hNetNotify;
- 24 delete hNetNotify;
- 25 hMessageStream = new {'ConnectConstruct, host, port}
- 26 => XNstream;
- 27 {'SendAny, message} => hMessageStream;
- 28 delete hMessageStream;
- 29 hNetNotify = new {'CreateFromPort, portNumber} => IOnwNotify;
- 30 {'Subscribe, &connectNro} => hNetNotify;
- 31 }
- 32
- 33 on Destroy
- 34 {
- 35 {'Unsubscribe, &connectNro} => hNetNotify;
- 36 delete hNetNotify;
- 37 }
- 38
- 39 };
- 40
- 41 upon Construct
- 42 {
- 43 /* Define the port number & host where receiving end is running */
- 44 integer portnum = 8900;
- 45 string tohost = "anyhost.your.domain";
- 46 string msgstring = "Hello from a remote AthenaMuse";
- 47
- 48 Message {'Construct, portnum} => myMessage;
- 49 nro{'Create, 'ReceiveMessage, self, 'GetFromPeer, FALSE}
- 50 =>messNro;
- 51 {'Subscribe, &messNro} => myMessage;
- 52 {'SendMessage, msgstring, tohost, portnum } => myMessage;}
- Figure 6.47: - Input/Output Wrapped Classes Inheritance Tree
-
- 6.4.1 - IOactNotify
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.2 - IOnwNotify
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.3 - IOstream - Abstract
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.4 - IOfile
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.5 - IOfileSpec
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.6 - IOpipe
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.7 - IOurl
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.8 - IOweb - Abstract
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.9 - IOftp
-
- Superclasses
-
- Methods
-
- Activities
-
- Example
-
- 6.4.10 - IOhttp
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.11 - IOwebRequest - Abstract
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.12 - IOftpRequest
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.13 - IOhttpRequest
-
- Superclasses
-
- Methods
-
- Activities
-
- Example
-
- 6.4.14 - IOwebEntity - Abstract
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.15 - IOftpEntity
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.16 - IOhttpEntity
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.17 - IOwebStream - Abstract
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.18 - IOftpStream
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.19 - IOhttpStream
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example
-
- 6.4.20 - XNstream
-
- Superclasses
-
- Methods
-
- Attributes
-
- Activities
-
- Example 1
-
- Example 2
-
AM2 Documentation - 19 NOV 1996
Generated with Harlequin WebMaker