# Class: Http

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

## Constructor

#### new Http()

Creates a new instance of helma.Http

Source:
  - helma/Http.js, line 44

##### Returns:

A newly created helma.Http instance

### Classes

Cookie

### Methods

#### getBinaryMode()

Returns the currently defined binary mode of this client

Source:
  - helma/Http.js, line 415
See:
  - #setBinaryMode

##### Returns:

The binary mode of this client

#### getCookie(name)

Returns the value of the cookie with the given name

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | The name of the cookie

Source:
  - helma/Http.js, line 283
See:
  - #setCookie

##### Returns:

The value of the cookie

#### getCookies()

Returns all cookies set for this client

Source:
  - helma/Http.js, line 308
See:
  - #setCookie

##### Returns:

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

#### getFollowRedirects()

Returns true if the client follows redirects

Source:
  - helma/Http.js, line 372
See:
  - #setFollowRedirects

##### Returns:

True if the client follows redirects, false otherwise.

#### getHeader(name)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | The name of the request header field

Source:
  - helma/Http.js, line 253
See:
  - #setHeader

##### Returns:

The value of the request header field

#### getMaxResponseSize()

Returns the currently set max response size

Source:
  - helma/Http.js, line 434
See:
  - #setMaxResponseSize

##### Returns:

The max responsesize

#### getMethod()

Returns the currently defined request method.

Source:
  - helma/Http.js, line 231
See:
  - #setMethod

##### Returns:

The method used

#### getProxy()

Returns the proxy in `host:port` format

Source:
  - helma/Http.js, line 152
See:
  - #setProxy

##### Returns:

The proxy defined for this request

#### getReadTimeout()

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

Source:
  - helma/Http.js, line 352
See:
  - #setReadTimeout

##### Returns:

The read timeout in milliseconds

#### getResponseHandler()

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

Source:
  - helma/Http.js, line 457

##### Returns:

The response handler function

#### getTimeout()

Returns the connection timeout

Source:
  - helma/Http.js, line 341
See:
  - #setTimeout

##### Returns:

The connection timeout in milliseconds

#### getUrl(url, opt)

Executes a http request

##### Parameters:

Name | Type | Description
--- | --- | ---
`url` | String | The url to request
`opt` | Date | String | 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.

Source:
  - helma/Http.js, line 486

##### 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`: (helma.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)

#### getUserAgent()

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

Source:
  - helma/Http.js, line 393
See:
  - #setUserAgent

##### Returns:

The value of the field

#### 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:

Name | Type | Description
--- | --- | ---
`mode` | Boolean | If true binary mode is activated

Source:
  - helma/Http.js, line 404
See:
  - #getBinaryMode

#### setContent(stringOrObject)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`stringOrObject` | String | Object | 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.

Source:
  - helma/Http.js, line 181

#### 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:

Name | Type | Description
--- | --- | ---
`name` | String | The name of the cookie
`value` | String | The value of the cookie

Source:
  - helma/Http.js, line 265
See:
  - #getCookie
  - #getCookies

#### setCookies(cookies)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`cookies` | Array | An array containing objects with the properties "name" (the name of the cookie) and "value" (the value of the cookie) set.

Source:
  - helma/Http.js, line 293

#### setCredentials(username, password)

Sets the credentials for basic http authentication

##### Parameters:

Name | Type | Description
--- | --- | ---
`username` | String | The username
`password` | String | The password

Source:
  - helma/Http.js, line 167

#### setFollowRedirects(value)

Enables or disables following redirects

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Boolean | If false this client won't follow redirects (the default is to follow them)

Source:
  - helma/Http.js, line 362
See:
  - #getFollowRedirects

#### setHeader(name, value)

Sets a single HTTP request header field

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | The name of the header field
`value` | String | The value of the header field

Source:
  - helma/Http.js, line 241
See:
  - #getHeader

#### setMaxResponseSize(Size)

Sets the max allowed size for the response stream

##### Parameters:

Name | Type | Description
--- | --- | ---
`Size` | Integer | in Byte

Source:
  - helma/Http.js, line 423

#### setMethod(m)

Sets the request method to use.

##### Parameters:

Name | Type | Description
--- | --- | ---
`m` | String | The method to use (`GET`, `POST` ...)

Source:
  - helma/Http.js, line 220
See:
  - #getMethod

#### 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:

Name | Type | Description
--- | --- | ---
`proxyString` | String | The proxy to use for this request

Source:
  - helma/Http.js, line 125
See:
  - #getProxy

#### 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:

Name | Type | Description
--- | --- | ---
`timeout` | Number | The read timeout in milliseconds

Source:
  - helma/Http.js, line 330
See:
  - #getReadTimeout

#### 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:

Name | Type | Description
--- | --- | ---
`Response` | function | handler function

Source:
  - helma/Http.js, line 448

#### setTimeout(timeout)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`timeout` | Number | The connection timeout in milliseconds

Source:
  - helma/Http.js, line 318
See:
  - #getTimeout

#### setUserAgent(agent)

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

##### Parameters:

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

Source:
  - helma/Http.js, line 382
See:
  - #getUserAgent

#### (static) evalUrl(url)

Evaluates the url passed as argument.

##### Parameters:

Name | Type | Description
--- | --- | ---
`url` | String | The url or uri string to evaluate

Source:
  - helma/Http.js, line 626

##### Returns:

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

#### (static) isAuthorized(name, pwd)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | The username to check req.username against
`pwd` | String | The password to check req.password against

Source:
  - helma/Http.js, line 698

##### 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").