## helma.Http

    Object
       |
       +--helma.Http

This class provides functionality to programatically issue an Http request based on java.net.HttpUrlConnection. By default the request will use method `GET`.
Defined in Http.js

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Constructor Summary
`helma.Http()` Creates a new instance of helma.Http

Methods Summary
`Boolean` | `getBinaryMode()` Returns the currently defined binary mode of this client
`String` | `getCookie(<String> name)` Returns the value of the cookie with the given name
`Object` | `getCookies()` Returns all cookies set for this client
`Object` | `getFollowRedirects()` Returns true if the client follows redirects
`String` | `getHeader(<String> name)` Returns the value of the request header field with the given name
`String` | `getMethod()` Returns the currently defined request method.
`String` | `getProxy()` Returns the proxy in `host:port` format
`Number` | `getReadTimeout()` Returns the read timeout (the maximum time a request may take after the connection has been successfully established).
`Number` | `getTimeout()` Returns the connection timeout
`Object` | `getUrl(<String> url, <Date|String> opt)` Executes a http request
`String` | `getUserAgent()` Returns the value of the HTTP "User-Agent" header field
`void` | `setBinaryMode(<Boolean> mode)` Switches content text encoding on or off.
`void` | `setContent(<String|Object> stringOrObject)` Sets the content to send to the remote server within this request.
`void` | `setCookie(<String> name, <String> value)` Adds a cookie with the name and value passed as arguments to the list of cookies to send to the remote server.
`void` | `setCredentials(<String> username, <String> password)` Sets the credentials for basic http authentication
`void` | `setFollowRedirects(<Boolean> value)` Enables or disables following redirects
`void` | `setHeader(<String> name, <String> value)` Sets a single HTTP request header field
`void` | `setMethod(<String> m)` Sets the request method to use.
`void` | `setProxy(<String> proxyString)` Sets the proxy host and port for later use.
`Object` | `setReadTimeout(<Number> 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.
`void` | `setTimeout(<Number> timeout)` Sets the connection timeout to the amount of milliseconds passed as argument
`void` | `setUserAgent(<String> agent)` Sets the HTTP "User-Agent" header field to the string passed as argument
`<static> java.net.URL` | `evalUrl(<String> url)` Evaluates the url passed as argument.
`<static> Boolean` | `isAuthorized(<String> name, <String> pwd)` Static helper method to check if a request issued agains a Helma application is authorized or not.

Constructor Detail

### helma.Http

    helma.Http()

Creates a new instance of helma.Http

Returns:

A newly created helma.Http instance

Method Detail

### getBinaryMode

    Boolean getBinaryMode()

Returns the currently defined binary mode of this client

Returns:

The binary mode of this client

See:

- setBinaryMode()

### getCookie

    String getCookie(<String> name)

Returns the value of the cookie with the given name

Parameters:

`name` - The name of the cookie

Returns:

The value of the cookie

See:

- setCookie()

### getCookies

    Object 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()

### getFollowRedirects

    Object getFollowRedirects()

Returns true if the client follows redirects

Returns:

True if the client follows redirects, false otherwise.

See:

- setFollowRedirects()

### getHeader

    String getHeader(<String> name)

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

Parameters:

`name` - The name of the request header field

Returns:

The value of the request header field

See:

- setHeader()

### getMethod

    String getMethod()

Returns the currently defined request method.

Returns:

The method used

See:

- setMethod()

### getProxy

    String getProxy()

Returns the proxy in `host:port` format

Returns:

The proxy defined for this request

See:

- setProxy()

### getReadTimeout

    Number getReadTimeout()

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

Returns:

The read timeout in milliseconds

See:

- setReadTimeout()

### getTimeout

    Number getTimeout()

Returns the connection timeout

Returns:

The connection timeout in milliseconds

See:

- setTimeout()

### getUrl

    Object getUrl(<String> url, <Date|String> opt)

Executes a http request

Parameters:

`url` - The url to request

`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
- `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`: (helma.Http.Cookie) An object containing the cookie parameters, if the remote server has set the "Set-Cookie" header field
- `content`: (String|ByteArray) The response received from the server. Can be either a string or a byte array (see #setBinaryMode)

### getUserAgent

    String getUserAgent()

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

Returns:

The value of the field

See:

- setUserAgent()

### setBinaryMode

    void setBinaryMode(<Boolean> 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:

`mode` - If true binary mode is activated

See:

- getBinaryMode()

### setContent

    void setContent(<String|Object> stringOrObject)

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

Parameters:

`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.

### setCookie

    void setCookie(<String> name, <String> value)

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

Parameters:

`name` - The name of the cookie

`value` - The value of the cookie

See:

- getCookie()
- getCookies()

### setCredentials

    void setCredentials(<String> username, <String> password)

Sets the credentials for basic http authentication

Parameters:

`username` - The username

`password` - The password

### setFollowRedirects

    void setFollowRedirects(<Boolean> value)

Enables or disables following redirects

Parameters:

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

See:

- getFollowRedirects()

### setHeader

    void setHeader(<String> name, <String> value)

Sets a single HTTP request header field

Parameters:

`name` - The name of the header field

`value` - The value of the header field

See:

- getHeader()

### setMethod

    void setMethod(<String> m)

Sets the request method to use.

Parameters:

`m` - The method to use (`GET`, `POST` ...)

See:

- getMethod()

### setProxy

    void setProxy(<String> proxyString)

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

Parameters:

`proxyString` - The proxy to use for this request

See:

- getProxy()

### setReadTimeout

    Object setReadTimeout(<Number> 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:

`timeout` - The read timeout in milliseconds

See:

- getReadTimeout()

### setTimeout

    void setTimeout(<Number> timeout)

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

Parameters:

`timeout` - The connection timeout in milliseconds

See:

- getTimeout()

### setUserAgent

    void setUserAgent(<String> agent)

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

Parameters:

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

See:

- getUserAgent()

### evalUrl

    <static> java.net.URL evalUrl(<String> url)

Evaluates the url passed as argument.

Parameters:

`url` - The url or uri string to evaluate

Returns:

If the argument is a valid url, this method returns a new instance of java.net.URL, otherwise it returns null.

### isAuthorized

    <static> Boolean isAuthorized(<String> name, <String> pwd)

Static helper method to check if a request issued agains a Helma application is authorized or not.

Parameters:

`name` - The username to check req.username against

`pwd` - The password to check req.password against

Returns:

True if the request is authorized, false otherwise. In the latter case the current response is reset and the response code is set to "401" ("Authentication required").

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Documentation generated by JSDoc on Thu Apr 5 01:59:00 2007