Http
Module | ejs.io |
Namespace | "ejs.io" |
Definition | class Http |
Specified | Ejs-11. |
Inheritance | Http ![]() |
The Http object represents a Hypertext Transfer Protocol version 1.
1 client connection. It is used to issue HTTP requests and capture responses. It supports the HTTP/1.1 standard including methods for GET, POST, PUT, DELETE, OPTIONS, and TRACE. It also supports Keep-Alive and SSL connections.
Properties
Qualifiers | Property | Type | Description |
---|---|---|---|
public static const | Accepted | Number | HTTP status code. |
public static const | BadGateway | Number | HTTP status code. |
public static const | BadMethod | Number | HTTP status code. |
public static const | BadRequest | Number | HTTP status code. |
public static const | ClientTimeout | Number | HTTP status code. |
public static const | Conflict | Number | HTTP status code. |
public static const | Continue | Number | HTTP status code. |
public static const | Created | Number | HTTP status code. |
public static const | EntityTooLarge | Number | HTTP status code. |
public static const | Forbidden | Number | HTTP status code. |
public static const | GatewayTimeout | Number | HTTP status code. |
public static const | Gone | Number | HTTP status code. |
public static const | LengthRequired | Number | HTTP status code. |
public static const | MovedPermanently | Number | HTTP status code. |
public static const | MovedTemporarily | Number | HTTP status code. |
public static const | MultipleChoice | Number | HTTP status code. |
public static const | NoContent | Number | HTTP status code. |
public static const | NotAccepted | Number | HTTP status code. |
public static const | NotAuthoritative | Number | HTTP status code. |
public static const | NotFound | Number | HTTP status code. |
public static const | NotImplemented | Number | HTTP status code. |
public static const | NotModified | Number | HTTP status code. |
public static const | Ok | Number | HTTP status code. |
public static const | Partial | Number | HTTP status code. |
public static const | PaymentRequired | Number | HTTP status code. |
public static const | PrecondFailed | Number | HTTP status code. |
public static const | ProxyAuth | Number | HTTP status code. |
public static const | ReqTooLong | Number | HTTP status code. |
public static const | Reset | Number | HTTP status code. |
public static const | SeeOther | Number | HTTP status code. |
public static const | ServerError | Number | HTTP status code. |
public static const | Unauthorized | Number | HTTP status code. |
public static const | Unavailable | Number | HTTP status code. |
public static const | UnsupportedType | Number | HTTP status code. |
public static const | UseProxy | Number | HTTP status code. |
public static const | Version | Number | HTTP status code. |
Http Methods
Qualifiers | Method |
---|---|
public | addRequestHeader(key: String, value: String, overwrite: Boolean): Void |
Add a request header. | |
public get | available(): Number |
Get the number of data bytes that are currently available on this stream for reading. | |
public set | callback(cb: Function): Void |
Define a request callback and put the Http object into async mode. | |
public get | callback(): Function |
Hide. | |
public get | certificateFile(): String |
Get the name of the file holding the certificate for this HTTP object. | |
public set | certificateFile(certFile: String): Void |
Set or reset the file name where this Https object holds its certificate. | |
public | close(graceful: Boolean): Void |
Close the connection to the server and free up all associated resources. | |
public get | code(): Number |
Get the response code from a Http message, e. | |
public get | codeString(): String |
Get the response code message from a Http message, e. | |
public | connect(): Void |
Issue a HTTP request for the current method and uri. | |
public get | contentEncoding(): String |
Get the value of the content encoding. | |
public get | contentLength(): Number |
Get the response content length. | |
public get | contentType(): String |
Get the response content type. | |
public get | date(): Date |
Get the value of the content date header field. | |
public | del(uri: String): Void |
Issue a DELETE request for the current uri. | |
public get | expires(): Date |
Get the value of the expires header field. | |
public | flush(): Void |
Flush any buffered data. | |
public get | followRedirects(): Boolean |
Get whether redirects should be automatically followed by this Http object. | |
public set | followRedirects(flag: Boolean): Void |
Eanble or disable following redirects from the connection remove server. | |
public | form(uri: String, postData: Object): Void |
Issue a POST request with form data the current uri. | |
public | get(uri: String): Void |
Issue a GET request for the current uri. | |
public | head(uri: String): Void |
Issue a HEAD request for the current uri. | |
public | header(key: String): String |
Get the value of any response header field. | |
public get | headers(): Object |
Get all the response headers. | |
Http(uri: String) | |
Create an Http object. | |
public get | isSecure(): Boolean |
Get whether the connection is utilizing SSL. | |
public get | keyFile(): String |
Get the filename of the private key for this Https object. | |
public set | keyFile(keyFile: String): Void |
Set or reset the filename where this Https object holds its private key. | |
public get | lastModified(): Date |
Get the value of the response's last modified header field. | |
public get | method(): String |
Get the request method for this Http object. | |
public set | method(name: String) |
Set or reset the Http object's request method. | |
public | post(uri: String, data: Array): Void |
Issue a POST request for the current uri. | |
public set | postData(items: Object): Void |
Set the post data to send with a post request. | |
public set | postLength(length: Number): Void |
Set the post request length. | |
public get | postLength(): Number |
public | put(uri: String, putData: Array): Void |
Issue a PUT request for the current uri. | |
public | read(buffer: ByteArray, offset: Number, count: Number): Number |
Read a block of response content data from the connection. | |
public | readLines(count: Number): Array |
Read the request response as an array of lines. | |
public | readString(count: Number): String |
Read the request response as a string. | |
public | readXml(): XML |
Read the request response as an XML document. | |
public get | requestStream(): Stream |
Return a stream connected to the request post/put data stream. | |
public get | response(): String |
Return the response data. | |
public get | responseStream(): Stream |
Return a stream connected to the response data. | |
public | setCredentials(username: String, password: String): Void |
Set the user credentials to use if the request requires authentication. | |
public | skip(n: Number) |
public get | timeout(): Number |
Get the request timeout. | |
public set | timeout(timeout: Number): Void |
Set the request timeout. | |
public | upload(uri: String, filename: String): Void |
Issue a HTTP get request for the current uri. | |
public get | uri(): String |
Get the URI for this Http object. | |
public set | uri(uriString: String): Void |
Set or reset the Http object's URI. | |
public | write(data: Array): Void |
Write post data to the request stream. |
Method Detail
Add a request header.
- Description
- Must be done before the Http request is issued.
Get the number of data bytes that are currently available on this stream for reading.
- Returns
- The number of available bytes.
Define a request callback and put the Http object into async mode.
- Description
- The specified function will be invoked as response data is received on request completion and on any errors. After the callback has been called, the After response data will be discarded. The callback function may call $available to see what data is ready for reading or may simply call $read to retrieve available data. In this mode, calls to $connect, $get, $post, $del, $head, $options or $trace will not block.
- Parameters
cb: Function Callback function to invoke when the HTTP request is complete and some response data is available to read. The callback is invoked with the signature: function callback(e: Event): Void
Where e.data == http. The even arg may be either a HttpDataEvent Issued when there is response data to read or on end of request ($available == 0). The HttpError event will be passed on any request processing errors. Does not include remote server errors.
Hide.
Get the name of the file holding the certificate for this HTTP object.
- Description
- This method applies only if secure communications are in use and if setCertificationFile has been called.
- Returns
- The file name.
Set or reset the file name where this Https object holds its certificate.
- Description
- If defined and secure communications are used, then the client connection will supply this certification during its connection request.
- Parameters
certFile: String The name of the certificate file.
Throws
IOError: if the file does not exist.
Close the connection to the server and free up all associated resources.
- Parameters
graceful: Boolean if true, then close the socket gracefully after writing all pending data. [default: true]
Get the response code from a Http message, e.
- Description
- G. 200.
- Returns
- The integer value of the response code or -1 if not known.
Get the response code message from a Http message, e.
- Description
- G. OK.
- Returns
- The string message returned with the HTTP response status line.
Issue a HTTP request for the current method and uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately. The HTTP method should be defined via the $method property and uri via the $uri property.
Throws
IOError: if the request was cannot be issued to the remote server.
Get the value of the content encoding.
- Returns
- A string with the content type or null if not known.
Get the response content length.
- Returns
- The integer value or -1 if not known.
Get the response content type.
- Description
- Call content() to get the resonse content.
- Returns
- A string with the content type or null if not known.
Get the value of the content date header field.
- Returns
- The date the request was served.
Issue a DELETE request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String The uri to delete. This overrides any previously defined uri for the Http object.
Throws
IOError: if the request was cannot be issued to the remote server.
Get the value of the expires header field.
- Returns
- The date the content expires.
Flush any buffered data.
Get whether redirects should be automatically followed by this Http object.
- Returns
- True if redirects are automatically followed.
Eanble or disable following redirects from the connection remove server.
- Description
- Default is true.
- Parameters
flag: Boolean Set to true to follow redirects.
Issue a POST request with form data the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String Optional request uri. If non-null, this overrides any previously defined uri for the Http object. postData: Object Optional object hash of key value pairs to use as the post data. These are www-url-encoded and the content mime type is set to "application/x-www-form-urlencoded".
Throws
IOError: if the request was cannot be issued to the remote server.
Issue a GET request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String The uri to delete. This overrides any previously defined uri for the Http object.
Throws
IOError: if the request was cannot be issued to the remote server.
Issue a HEAD request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String The request uri. This overrides any previously defined uri for the Http object.
Throws
IOError: if the request was cannot be issued to the remote server.
Get the value of any response header field.
- Returns
- The header field value as a string or null if not known.
Get all the response headers.
- Returns
- An object hash filled with all the headers.
Get whether the connection is utilizing SSL.
- Returns
- True if the connection is using SSL.
Get the filename of the private key for this Https object.
- Returns
- The file name.
Get the value of the response's last modified header field.
- Returns
- The number of milliseconds since January 1, 1970 GMT or -1 if not known.
Get the request method for this Http object.
- Returns
- The request string or null if not set.
Issue a POST request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately. NOTE: the posted data is NOT URL encoded. If you want to post data to a form, consider using the $form method.
- Parameters
uri: String Optional request uri. If non-null, this overrides any previously defined uri for the Http object. data: Array Optional data to send with the post request. data: Array Data objects to send with the post request. Data is written raw and is not encoded or converted. However, post intelligently handles arrays such that, each element of the array will be written. If posting to a form, consider the $form method.
Throws
IOError: if the request was cannot be issued to the remote server.
Set the post data to send with a post request.
- Parameters
items: Object An object hash of key value pairs to use as the post data
Set the post request length.
- Description
- This sets the Content-Length header value and is used when using $write to emit the post data.
- Parameters
length: Number The length of post data that will be written via writePostData
Issue a PUT request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String The uri to delete. This overrides any previously defined uri for the Http object. putData: Array Optional object hash of key value pairs to use as the post data.
Throws
IOError: if the request was cannot be issued to the remote server.
Read a block of response content data from the connection.
- Description
- This will automatically call $connect if required.
- Parameters
buffer: ByteArray Destination byte array for the read data. offset: Number Offset in the byte array to place the data. If offset is not supplied, data is appended at the current byte array write position. count: Number Number of bytes to read.
- Returns
- A count of the bytes actually read. Returns zero if no data is available. Returns -1 when the end of response data has been reached.
Throws
IOError: if an I/O error occurs.
Read the request response as an array of lines.
- Description
- This will automatically call $connect if required.
- Parameters
count: Number of linese to read. Returns the entire response contents if count is -1.
- Returns
- A string containing count lines of data starting with the first line of response data.
Throws
IOError: if an I/O error occurs.
Read the request response as a string.
- Description
- This will automatically call $connect if required.
- Parameters
count: Number of bytes to read. Returns the entire response contents if count is -1.
- Returns
- A string of $count characters beginning at the start of the response data.
Throws
IOError: if an I/O error occurs.
Read the request response as an XML document.
- Description
- This will automatically call $connect if required.
- Returns
- The response content as an XML object.
Throws
IOError: if an I/O error occurs.
Return a stream connected to the request post/put data stream.
- Description
- This will automatically call $connect if required.
- Returns
- A stream to write the request post or put data.
Return the response data.
- Description
- This is an alias for $readString(). This will automatically call $connect if required.
- Returns
- The response as a string of characters.
Throws
IOError: if an I/O error occurs.
Return a stream connected to the response data.
- Description
- This will automatically call $connect if required.
- Returns
- A stream to read the response data.
Set the user credentials to use if the request requires authentication.
Get the request timeout.
- Returns
- Number of milliseconds for requests to block while attempting the request.
Set the request timeout.
- Parameters
timeout: Number Number of milliseconds to block while attempting requests. -1 means no timeout.
Issue a HTTP get request for the current uri.
- Description
- This function will block until the the request completes or fails, unless a callback function has been defined. If a callback has been specified, this function will initiate the request and return immediately.
- Parameters
uri: String Request uri. If not null, this will override any previously defined uri for the Http object. filename: String File to upload.
Throws
IOError: if the request was cannot be issued to the remote server.
Get the URI for this Http object.
- Returns
- The current uri string.
Set or reset the Http object's URI.
- Description
- If the Http object is already connected the connection is first closed.
- Parameters
Throws
IOError: if the URI is malformed.
Write post data to the request stream.
- Description
- The http object must be in async mode by previously defining a $callback. The write call blocks while writing data. The Http.postLength should normally be set prior to writing any data to define the post data Content-length header value. If it is not defined, the content-length header will not be defined and the remote server will have to close the underling HTTP connection at the completion of the request. This will prevent HTTP keep-alive for subsequent requests. This call will automatically call $connect if required.
- Parameters
data: Array Data objects to write to the request stream. Data is written raw and is not encoded or converted. However, write intelligently handles arrays such that, each element of the array will be written. If encoding of write data is required, use the BinaryStream filter.
Throws
StateError: if the Http method is not set to POST., IOError: if more post data is written than specified via the setPostDataLength function.