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:

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
ActivityKeysDescription
ReadReadynonedata is ready for reading from port
WriteReadynoneOK to send data to port
ExceptionReadynoneexception 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
ActivityKeysDescription
ConnectReadynoneconnection requested
ReadReadynonedata is ready for reading from port (after connection established)
WriteReadynoneOK to send data to port (after connection established)
ExceptionReadynoneexception 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