Fork me on GitHub

Module ringo/httpclient

Fields and methods of the ringo.http module.

Class Client

Class Cookie

Instance Methods

Instance Properties

Static Methods

Static Properties

Client ()

Creates a new instance of ringo.http.Client

Returns

A newly created ringo.http.Client instance

Client.prototype.getBinaryMode ()

Returns the currently defined binary mode of this client

Returns

Boolean The binary mode of this client

Client.prototype.getCookie (name)

Returns the value of the cookie with the given name

Parameters

String name The name of the cookie

Returns

String The value of the cookie

See

setCookie

Client.prototype.getCookies ()

Returns all cookies set for this client

Returns

An object containing all cookies, where the property name is the name of the cookie, and the value is the cookie value

See

setCookie

Client.prototype.getFollowRedirects ()

Returns true if the client follows redirects

Returns

True if the client follows redirects, false otherwise.

Client.prototype.getHeader (name)

Returns the value of the request header field with the given name

Parameters

String name The name of the request header field

Returns

String The value of the request header field

See

setHeader

Client.prototype.getMaxResponseSize ()

Returns the currently set max response size

Returns

Integer The max responsesize

Client.prototype.getMethod ()

Returns the currently defined request method.

Returns

String The method used

See

setMethod

Client.prototype.getProxy ()

Returns the proxy in host:port format

Returns

String The proxy defined for this request

See

setProxy

Client.prototype.getReadTimeout ()

Returns the read timeout (the maximum time a request may take after the connection has been successfully established).

Returns

Number The read timeout in milliseconds

Client.prototype.getResponseHandler ()

Get the response handler. This is the function used to read the HTTP response body.

Returns

The response handler function

Client.prototype.getTimeout ()

Returns the connection timeout

Returns

Number The connection timeout in milliseconds

Client.prototype.getUrl (url, opt)

Executes a http request

Parameters

String url The url to request
Date|String opt If this argument is a string, it is used as value for the "If-None-Match" request header field. If it is a Date instance it is used as "IfModifiedSince" condition for this request.

Returns

A result object containing the following properties:
  • url: (String) The Url of the request
  • location: (String) The value of the location header field
  • code: (Number) The HTTP response code
  • message: (String) An optional HTTP response message
  • length: (Number) The content length of the response
  • type: (String) The mimetype of the response
  • charset: (String) The character set of the response
  • encoding: (String) An optional encoding to use with the response
  • lastModified: (String) The value of the lastModified response header field
  • eTag: (String) The eTag as received from the remote server
  • cookie: (ringo.http.Cookie) An object containing the cookie parameters, if the remote server has set the "Set-Cookie" header field
  • headers: (java.util.Map) A map object containing the headers, access them using get("headername")
  • content: (String|ByteArray) The response received from the server. Can be either a string or a byte array (see #setBinaryMode)

Client.prototype.getUserAgent ()

Returns the value of the HTTP "User-Agent" header field

Returns

String The value of the field

Client.prototype.setBinaryMode (mode)

Switches content text encoding on or off. Depending on this the content received from the remote server will be either a string or a byte array.

Parameters

Boolean mode If true binary mode is activated

Client.prototype.setContent (stringOrObject)

Sets the content to send to the remote server within this request.

Parameters

String|Object stringOrObject The content of the request, which can be either a string or an object. In the latter case all properties and their values are concatenated into a single string. If a property is an array, then for each value the propertyname and value pair is added. If the name of an array property ends with "_array" then the _array part is removed.

Client.prototype.setCookie (name, value)

Adds a cookie with the name and value passed as arguments to the list of cookies to send to the remote server.

Parameters

String name The name of the cookie
String value The value of the cookie

Client.prototype.setCookies (cookies)

Adds the cookies passed as argument to the list of cookies to send to the remote server.

Parameters

Array cookies An array containing objects with the properties "name" (the name of the cookie) and "value" (the value of the cookie) set.

Client.prototype.setCredentials (username, password)

Sets the credentials for basic http authentication

Parameters

String username The username
String password The password

Client.prototype.setFollowRedirects (value)

Enables or disables following redirects

Parameters

Boolean value If false this client won't follow redirects (the default is to follow them)

Client.prototype.setHeader (name, value)

Sets a single HTTP request header field

Parameters

String name The name of the header field
String value The value of the header field

See

getHeader

Client.prototype.setMaxResponseSize (Size)

Sets the max allowed size for the response stream

Parameters

Integer Size in Byte

Client.prototype.setMethod (m)

Sets the request method to use.

Parameters

String m The method to use (GET, POST ...)

See

getMethod

Client.prototype.setProxy (proxyString)

Sets the proxy host and port for later use. The argument must be in host:port format (eg. "proxy.example.com:3128").

Parameters

String proxyString The proxy to use for this request

See

getProxy

Client.prototype.setReadTimeout (timeout)

Sets the read timeout (the maximum time a request may take after the connection has been successfully established) to the amount of milliseconds passed as argument.

Parameters

Number timeout The read timeout in milliseconds

Client.prototype.setResponseHandler (Response)

Overloads the default response handler. Use this do implement your own response handling, like storing the response directly to the harddisk The handler function gets two parameter, first is the java.net.URLConnection and second is the result object. Note that custom response handler functions should check the HTTP status code before reading the response. The status code for successful requests is 200. Response bodies for requests with status codes less than 400 can be read from the connection's input stream, while response bodies with 4xx or 5xx status codes must be read using the error stream.

Parameters

function Response handler function

Client.prototype.setTimeout (timeout)

Sets the connection timeout to the amount of milliseconds passed as argument

Parameters

Number timeout The connection timeout in milliseconds

Client.prototype.setUserAgent (agent)

Sets the HTTP "User-Agent" header field to the string passed as argument

Parameters

String agent The string to use as value of the "User-Agent" header field (defaults to "RingoJS Http Client")

Cookie (name, value)

Creates a new instance of ringo.http.Cookie

Parameters

String name The name of the cookie
String value The value of the cookie

Returns

A newly created Cookie instance

Cookie.DATEFORMAT

An instance of java.text.SimpleDateFormat used for both parsing an "expires" string into a date and vice versa

Cookie.PATTERN

A regular expression used for parsing cookie strings

Cookie.prototype.domain

An optional domain where this cookie is valid

Cookie.prototype.expires

An optional date defining the lifetime of this cookie

Cookie.prototype.name

The name of the Cookie

Cookie.prototype.path

An optional path where this cookie is valid

Cookie.prototype.value

The value of the Cookie

Cookie.parse (cookieStr)

Parses the cookie string passed as argument into an instance of ringo.http

Parameters

String cookieStr The cookie string as received from the remote server

Returns

Cookie An instance of Cookie containing the cookie parameters

Cookie.prototype.getFieldValue ()

Returns this cookie in a format useable to set the HTTP header field "Cookie"

Returns

String This cookie formatted as HTTP header field value