Http

Moduleejs.io
Namespace"ejs.io"
Definition class Http
SpecifiedEjs-11.
InheritanceHttp inherit Object

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

QualifiersPropertyTypeDescription
public static const AcceptedNumberHTTP status code.
public static const BadGatewayNumberHTTP status code.
public static const BadMethodNumberHTTP status code.
public static const BadRequestNumberHTTP status code.
public static const ClientTimeoutNumberHTTP status code.
public static const ConflictNumberHTTP status code.
public static const ContinueNumberHTTP status code.
public static const CreatedNumberHTTP status code.
public static const EntityTooLargeNumberHTTP status code.
public static const ForbiddenNumberHTTP status code.
public static const GatewayTimeoutNumberHTTP status code.
public static const GoneNumberHTTP status code.
public static const LengthRequiredNumberHTTP status code.
public static const MovedPermanentlyNumberHTTP status code.
public static const MovedTemporarilyNumberHTTP status code.
public static const MultipleChoiceNumberHTTP status code.
public static const NoContentNumberHTTP status code.
public static const NotAcceptedNumberHTTP status code.
public static const NotAuthoritativeNumberHTTP status code.
public static const NotFoundNumberHTTP status code.
public static const NotImplementedNumberHTTP status code.
public static const NotModifiedNumberHTTP status code.
public static const OkNumberHTTP status code.
public static const PartialNumberHTTP status code.
public static const PaymentRequiredNumberHTTP status code.
public static const PrecondFailedNumberHTTP status code.
public static const ProxyAuthNumberHTTP status code.
public static const ReqTooLongNumberHTTP status code.
public static const ResetNumberHTTP status code.
public static const SeeOtherNumberHTTP status code.
public static const ServerErrorNumberHTTP status code.
public static const UnauthorizedNumberHTTP status code.
public static const UnavailableNumberHTTP status code.
public static const UnsupportedTypeNumberHTTP status code.
public static const UseProxyNumberHTTP status code.
public static const VersionNumberHTTP status code.

Http Methods

QualifiersMethod
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

public addRequestHeader(key: String, value: String, overwrite: Boolean): Void

Add a request header.

Description
Must be done before the Http request is issued.
Parameters
key: String The header keyword for the request, e.g. "accept".
value: String The value to associate with the header, e.g. "yes"
overwrite: Boolean If true, overwrite existing headers of the same key name. [default: true]

get public available(): Number

Get the number of data bytes that are currently available on this stream for reading.

Returns
The number of available bytes.

set public callback(cb: Function): Void

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.

get public callback(): Function

Hide.


get public certificateFile(): String

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 public certificateFile(certFile: String): Void

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.


public close(graceful: Boolean): Void

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 public code(): Number

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 public codeString(): String

Get the response code message from a Http message, e.

Description
G. OK.
Returns
The string message returned with the HTTP response status line.

public connect(): Void

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 public contentEncoding(): String

Get the value of the content encoding.

Returns
A string with the content type or null if not known.

get public contentLength(): Number

Get the response content length.

Returns
The integer value or -1 if not known.

get public contentType(): String

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 public date(): Date

Get the value of the content date header field.

Returns
The date the request was served.

public del(uri: String): Void

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 public expires(): Date

Get the value of the expires header field.

Returns
The date the content expires.

public flush(): Void

Flush any buffered data.


get public followRedirects(): Boolean

Get whether redirects should be automatically followed by this Http object.

Returns
True if redirects are automatically followed.

set public followRedirects(flag: Boolean): Void

Eanble or disable following redirects from the connection remove server.

Description
Default is true.
Parameters
flag: Boolean Set to true to follow redirects.

public form(uri: String, postData: Object): Void

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.


public get(uri: String): Void

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.


public head(uri: String): Void

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.


public header(key: String): String

Get the value of any response header field.

Returns
The header field value as a string or null if not known.

get public headers(): Object

Get all the response headers.

Returns
An object hash filled with all the headers.

Http(uri: String)

Create an Http object.

Description
The object is initialized with the URI, but no connection is done until one of the connection methods is called.
Parameters
uri: String The (optional) URI to initialize with.

Throws

IOError: if the URI is malformed.


get public isSecure(): Boolean

Get whether the connection is utilizing SSL.

Returns
True if the connection is using SSL.

get public keyFile(): String

Get the filename of the private key for this Https object.

Returns
The file name.

set public keyFile(keyFile: String): Void

Set or reset the filename where this Https object holds its private key.

Parameters
keyFile: String The name of the key file.

Throws

IOError: if the file does not exist.


get public lastModified(): Date

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 public method(): String

Get the request method for this Http object.

Returns
The request string or null if not set.

set public method(name: String)

Set or reset the Http object's request method.

Description
Default method is GET.
Parameters
name: String The method name as a string.

Throws

IOError: if the request is not GET, POST, HEAD, OPTIONS, PUT, DELETE or TRACE.


public post(uri: String, data: Array): Void

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 public postData(items: Object): Void

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 public postLength(length: Number): Void

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

get public postLength(): Number

public put(uri: String, putData: Array): Void

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.


public read(buffer: ByteArray, offset: Number, count: Number): Number

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.


public readLines(count: Number): Array

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.


public readString(count: Number): String

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.


public readXml(): XML

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.


get public requestStream(): Stream

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.

get public response(): String

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.


get public responseStream(): Stream

Return a stream connected to the response data.

Description
This will automatically call $connect if required.
Returns
A stream to read 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)

get public timeout(): Number

Get the request timeout.

Returns
Number of milliseconds for requests to block while attempting the request.

set public timeout(timeout: Number): Void

Set the request timeout.

Parameters
timeout: Number Number of milliseconds to block while attempting requests. -1 means no timeout.

public upload(uri: String, filename: String): Void

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 public uri(): String

Get the URI for this Http object.

Returns
The current uri string.

set public uri(uriString: String): Void

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.


public write(data: Array): Void

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.