ballerina.net.http package
public struct Connection
Represents the HTTP server connector connection
Field Name | Data Type | Description | Default Value |
---|---|---|---|
remoteHost | string | The server host name | |
port | int | The server port |
-
< Connection > createSessionIfAbsent ( ) ( Session )
Gets the Session struct for a valid session cookie from the connection. Otherwise creates a new Session struct.
Return Variable Data Type Description Session -
< Connection > forward ( InResponse res ) ( HttpConnectorError )
Forwards inbound response to the caller
Parameter Name Data Type Description res InResponse The inbound response message Return Variable Data Type Description HttpConnectorError -
< Connection > getSession ( ) ( Session )
Gets the Session struct from the connection if it is present
Return Variable Data Type Description Session -
< Connection > respond ( OutResponse res ) ( HttpConnectorError )
Sends outbound response to the caller
Parameter Name Data Type Description res OutResponse The outbound response message Return Variable Data Type Description HttpConnectorError -
< Connection > respondContinue ( ) ( HttpConnectorError )
Sends a 100-continue response to the client.
Return Variable Data Type Description HttpConnectorError
public struct FollowRedirects
FollowRedirects struct represents HTTP redirect related options to be used for HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
enabled | boolean | Enable redirect | false |
maxCount | int | Maximun number of redirects to follow | 5 |
public struct HttpConnectorError
HttpConnectorError struct represents an error occured during the HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
msg | string | An error message explaining about the error | |
cause | error | The error that caused HttpConnectorError to get thrown | |
stackTrace | StackFrame[] | Represents the invocation stack when HttpConnectorError is thrown | |
statusCode | int | HTTP status code |
public struct InRequest
Represents an HTTP inbound request message
Field Name | Data Type | Description | Default Value |
---|---|---|---|
rawPath | string | path: Resource path of request URI | |
method | string | HTTP request method | |
httpVersion | string | The version of HTTP | |
userAgent | string | User-Agent request header | |
extraPathInfo | string | path: Resource path of request URI |
-
< InRequest > expects100Continue ( ) ( boolean )
Checks whether the client expects a 100-continue response.
Return Variable Data Type Description boolean -
< InRequest > getEntity ( ) ( Entity )
Get the entity from the inbound request with the body included
Return Variable Data Type Description Entity -
< InRequest > getHeader ( string headerName ) ( string )
Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string -
< InRequest > getHeaders ( string headerName ) ( string[] )
Gets transport headers from the inbound request
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string[] -
< InRequest > getMatrixParams ( string path ) ( map )
Get matrix parameters from the request
Parameter Name Data Type Description path string Path to the location of matrix parameters Return Variable Data Type Description map -
< InRequest > getProperty ( string propertyName ) ( string )
Retrieves the named property from the request
Parameter Name Data Type Description propertyName string The name of the property Return Variable Data Type Description string -
< InRequest > getQueryParams ( ) ( map )
Gets the query parameters from the HTTP request as a map
Return Variable Data Type Description map -
< InRequest > setEntity ( Entity entity )
Set the entity to inbound request
Parameter Name Data Type Description entity Entity -
< InRequest > getBinaryPayload ( ) ( blob )
Gets the inboundrequest payload in blob format
Return Variable Data Type Description blob -
< InRequest > getContentLength ( ) ( int )
Gets the Content-Length header from the inbound request
Return Variable Data Type Description int -
< InRequest > getFormParams ( ) ( map )
Gets the form parameters from the HTTP request as a map
Return Variable Data Type Description map -
< InRequest > getJsonPayload ( ) ( json )
Gets the inbound request payload in JSON format
Return Variable Data Type Description json -
< InRequest > getMultiparts ( ) ( Entity[] )
Get multiparts from inbound request
Return Variable Data Type Description Entity[] -
< InRequest > getStringPayload ( ) ( string )
Gets the inbound request payload as a string
Return Variable Data Type Description string -
< InRequest > getXmlPayload ( ) ( xml )
Gets the inbound request payload in XML format
Return Variable Data Type Description xml
public struct InResponse
Represents an HTTP Inbound response message
Field Name | Data Type | Description | Default Value |
---|---|---|---|
statusCode | int | The response status code | |
reasonPhrase | string | The status code reason phrase | |
server | string | The server header |
-
< InResponse > getEntity ( ) ( Entity )
Get the entity from the inbound response with the body
Return Variable Data Type Description Entity -
< InResponse > getHeader ( string headerName ) ( string )
Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string -
< InResponse > getHeaders ( string headerName ) ( string[] )
Gets the HTTP headers from the inbound response
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string[] -
< InResponse > getProperty ( string propertyName ) ( string )
Retrieve a response property
Parameter Name Data Type Description propertyName string The name of the property Return Variable Data Type Description string -
< InResponse > getBinaryPayload ( ) ( blob )
Gets the inbound response payload in blob format
Return Variable Data Type Description blob -
< InResponse > getContentLength ( ) ( int )
Gets the Content-Length header value from the inbound response
Return Variable Data Type Description int -
< InResponse > getJsonPayload ( ) ( json )
Gets the inbound response payload in JSON format
Return Variable Data Type Description json -
< InResponse > getStringPayload ( ) ( string )
Gets the inbound response payload as a string
Return Variable Data Type Description string -
< InResponse > getXmlPayload ( ) ( xml )
Gets the inbound response payload in XML format
Return Variable Data Type Description xml -
< InResponse > setEntity ( Entity entity )
Set the entity to inbound response
Parameter Name Data Type Description entity Entity
public struct Options
Options struct represents options to be used for HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
port | int | Port number of the remote service | |
endpointTimeout | int | Endpoint timeout value in millisecond (default value: 60000 milliseconds) | 60000 |
maxActiveConnections | int | The maximum number of active connections the connector can create (default value: -1, indicates that the number of connections is not restricted) | -1 |
keepAlive | boolean | Keep the connection or close it (default value: true) | true |
transferEncoding | string | The types of encoding applied to the request (default value: chunking) | chunking |
chunking | string | The chunking behaviour of the request | auto |
httpVersion | string | The version of HTTP outbound request | |
followRedirects | FollowRedirects | Redirect related options | |
ssl | SSL | SSL/TLS related options | |
retryConfig | Retry | Retry related options | |
proxy | Proxy | Proxy server related options |
public struct OutRequest
Represents an HTTP outbound request message
-
< OutRequest > addHeader ( string headerName , string headerValue )
Adds the specified key/value pair as an HTTP header to the outbound request
Parameter Name Data Type Description headerName string The header name headerValue string The header value -
< OutRequest > getEntity ( ) ( Entity )
Get the entity from the outbound request
Return Variable Data Type Description Entity -
< OutRequest > getHeader ( string headerName ) ( string )
Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string -
< OutRequest > getHeaders ( string headerName ) ( string[] )
Gets transport headers from the outbound request
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string[] -
< OutRequest > getProperty ( string propertyName ) ( string )
Retrieves the named property from the request
Parameter Name Data Type Description propertyName string The name of the property Return Variable Data Type Description string -
< OutRequest > removeAllHeaders ( )
Removes all transport headers from the message
-
< OutRequest > removeHeader ( string key )
Removes a transport header from the outbound request
Parameter Name Data Type Description key string The header name -
< OutRequest > setEntity ( Entity entity )
Set the entity to outbound request
Parameter Name Data Type Description entity Entity -
< OutRequest > setHeader ( string headerName , string headerValue )
Sets the value of a transport header
Parameter Name Data Type Description headerName string The header name headerValue string The header value -
< OutRequest > setProperty ( string propertyName , string propertyValue )
Sets a request property
Parameter Name Data Type Description propertyName string The name of the property propertyValue string The value of the property -
< OutRequest > getBinaryPayload ( ) ( blob )
Gets the outbound request payload in blob format
Return Variable Data Type Description blob -
< OutRequest > getContentLength ( ) ( int )
Gets the Content-Length header from the Outbound request
Return Variable Data Type Description int -
< OutRequest > getJsonPayload ( ) ( json )
Gets the outbound request payload in JSON format
Return Variable Data Type Description json -
< OutRequest > getMultiparts ( ) ( Entity[] )
Get multiparts from outbound request
Return Variable Data Type Description Entity[] -
< OutRequest > getStringPayload ( ) ( string )
Gets the outbound request payload as a string
Return Variable Data Type Description string -
< OutRequest > getXmlPayload ( ) ( xml )
Gets the outbound request payload in XML format
Return Variable Data Type Description xml -
< OutRequest > setBinaryPayload ( blob payload )
Sets a blob as the outbound request payload
Parameter Name Data Type Description payload blob The blob representation of the message payload -
< OutRequest > setEntityBody ( File content , string contentType )
Sets the entity body of the outbound request with the given file content
Parameter Name Data Type Description content File File containing the actual content contentType string Content-Type of the given data -
< OutRequest > setJsonPayload ( json payload )
Sets a JSON as the outbound request payload
Parameter Name Data Type Description payload json The JSON payload to be set to the request -
< OutRequest > setMultiparts ( Entity[] bodyParts )
Set multiparts as the request payload
Parameter Name Data Type Description bodyParts Entity[] Represent body parts that needs to be set to the request -
< OutRequest > setStringPayload ( string payload )
Sets a string as the outbound request payload
Parameter Name Data Type Description payload string The payload to be set to the request as a string -
< OutRequest > setXmlPayload ( xml payload )
Sets an XML as the payload
Parameter Name Data Type Description payload xml The XML payload object
public struct OutResponse
Represents an HTTP outbound response message
Field Name | Data Type | Description | Default Value |
---|---|---|---|
statusCode | int | The response status code | |
reasonPhrase | string | The status code reason phrase |
-
< OutResponse > addHeader ( string headerName , string headerValue )
Adds the specified key/value pair as an HTTP header to the outbound response
Parameter Name Data Type Description headerName string The header name headerValue string The header value -
< OutResponse > getEntity ( ) ( Entity )
Get the entity from the outbound response
Return Variable Data Type Description Entity -
< OutResponse > getHeader ( string headerName ) ( string )
Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string -
< OutResponse > getHeaders ( string headerName ) ( string[] )
Gets the HTTP headers from the outbound response
Parameter Name Data Type Description headerName string The header name Return Variable Data Type Description string[] -
< OutResponse > getProperty ( string propertyName ) ( string )
Retrieve a response property
Parameter Name Data Type Description propertyName string The name of the property Return Variable Data Type Description string -
< OutResponse > getBinaryPayload ( ) ( blob )
Gets the outbound response payload in blob format
Return Variable Data Type Description blob -
< OutResponse > getContentLength ( ) ( int )
Gets the Content-Length header value from the outbound response
Return Variable Data Type Description int -
< OutResponse > getJsonPayload ( ) ( json )
Gets the outbound response payload in JSON format
Return Variable Data Type Description json -
< OutResponse > getStringPayload ( ) ( string )
Gets the outbound response payload as a string
Return Variable Data Type Description string -
< OutResponse > getXmlPayload ( ) ( xml )
Gets the outbound response payload in XML format
Return Variable Data Type Description xml -
< OutResponse > setBinaryPayload ( blob payload )
Sets a blob as the outbound response payload
Parameter Name Data Type Description payload blob The blob representation of the message payload -
< OutResponse > setEntityBody ( File content , string contentType )
Sets the entity body of the outbound response with the given file content
Parameter Name Data Type Description content File File containing the actual content contentType string Content-Type of the given data -
< OutResponse > setJsonPayload ( json payload )
Sets a JSON as the outbound response payload
Parameter Name Data Type Description payload json The JSON payload object -
< OutResponse > setStringPayload ( string payload )
Sets a string as the outbound response payload
Parameter Name Data Type Description payload string The payload to be set to the response as a string -
< OutResponse > setXmlPayload ( xml payload )
Sets an XML as the outbound response payload
Parameter Name Data Type Description payload xml The XML payload object -
< OutResponse > removeAllHeaders ( )
Removes all transport headers from the response
-
< OutResponse > removeHeader ( string key )
Removes a transport header from the response
Parameter Name Data Type Description key string The header name -
< OutResponse > setEntity ( Entity entity )
Set the entity to outbound response
Parameter Name Data Type Description entity Entity -
< OutResponse > setHeader ( string headerName , string headerValue )
Sets the value of a transport header
Parameter Name Data Type Description headerName string The header name headerValue string The header value -
< OutResponse > setProperty ( string propertyName , string propertyValue )
Sets a response property
Parameter Name Data Type Description propertyName string The name of the property propertyValue string The value of the property
public struct Proxy
Proxy struct represents proxy server configurations to be used for HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
host | string | proxyHost: host name of the proxy server | |
port | int | proxyHost: host name of the proxy server | |
userName | string | proxyHost: host name of the proxy server | |
password | string | proxyHost: host name of the proxy server |
public struct Retry
Retry struct represents retry related options for HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
count | int | Number of retries | |
interval | int | Retry interval in millisecond |
public struct SSL
SSL struct represents SSL/TLS options to be used for HTTP client invocation
Field Name | Data Type | Description | Default Value |
---|---|---|---|
trustStoreFile | string | File path to trust store file | |
trustStorePassword | string | Trust store password | |
keyStoreFile | string | File path to key store file | |
keyStorePassword | string | Key store password | |
sslEnabledProtocols | string | SSL/TLS protocols to be enabled. eg: TLSv1,TLSv1.1,TLSv1.2 | |
ciphers | string | List of ciphers to be used. eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | |
sslProtocol | string | SSL Protocol to be used. eg: TLS1.2 |
public struct Session
Represents an HTTP Session
-
< Session > getAttribute ( string attributeKey ) ( any )
Gets the named session attribute
Parameter Name Data Type Description attributeKey string HTTP session attribute key Return Variable Data Type Description any -
< Session > getAttributeNames ( ) ( string[] )
Gets the session attribute names
Return Variable Data Type Description string[] -
< Session > getAttributes ( ) ( map )
Gets the session attribute key value pairs as a map
Return Variable Data Type Description map -
< Session > getCreationTime ( ) ( int )
Gets the session creation time
Return Variable Data Type Description int -
< Session > getId ( ) ( string )
Gets the session cookie ID
Return Variable Data Type Description string -
< Session > getLastAccessedTime ( ) ( int )
Gets the last time the sessions was accessed
Return Variable Data Type Description int -
< Session > getMaxInactiveInterval ( ) ( int )
Gets maximum inactive interval for the session. The session expires after this time period.
Return Variable Data Type Description int -
< Session > invalidate ( )
Invalidates the session and it will no longer be accessible from the request
-
< Session > isNew ( ) ( boolean )
Checks whether the given session is a newly created session or an existing session
Return Variable Data Type Description boolean -
< Session > removeAttribute ( string attributeKey )
Remove the named session attribute
Parameter Name Data Type Description attributeKey string Session attribute key -
< Session > setAttribute ( string attributeKey , any attributeValue )
Sets the specified key/value pair as a session attribute
Parameter Name Data Type Description attributeKey string Session attribute key attributeValue any Session attribute Value -
< Session > setMaxInactiveInterval ( int timeInterval )
Sets the maximum inactive interval for the session. The session expires after this time period.
Parameter Name Data Type Description timeInterval int Session max inactive interval
public function parseHeader ( string headerValue ) ( string , map , error )
Parse headerValue and return value with parameter map
Parameter Name | Data Type | Description |
---|---|---|
headerValue | string | The header value |
public connector HttpClient ( string serviceUri , Options connectorOptions )
HTTP client connector for outbound HTTP requests
Parameter Name | Data Type | Description |
---|---|---|
serviceUri | string | URI of the service |
connectorOptions | Options | connector options |
Actions:
-
< HttpClient > delete ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
The DELETE action implementation of the HTTP connector
Parameter Name Data Type Description path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > execute ( string httpVerb , string path , OutRequest req ) ( InResponse , HttpConnectorError )
Invokes an HTTP call with the specified HTTP verb.
Parameter Name Data Type Description httpVerb string HTTP verb value path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > forward ( string path , InRequest req ) ( InResponse , HttpConnectorError )
Forward action can be used to invoke an HTTP call with inbound request's HTTP verb
Parameter Name Data Type Description path string Request path req InRequest An HTTP inbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > get ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
GET action implementation of the HTTP Connector
Parameter Name Data Type Description path string Request path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > head ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
The HEAD action implementation of the HTTP Connector.
Parameter Name Data Type Description path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > options ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
OPTIONS action implementation of the HTTP Connector
Parameter Name Data Type Description path string Request path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > patch ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
The PATCH action implementation of the HTTP Connector.
Parameter Name Data Type Description path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > post ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
The POST action implementation of the HTTP Connector.
Parameter Name Data Type Description path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError -
< HttpClient > put ( string path , OutRequest req ) ( InResponse , HttpConnectorError )
The PUT action implementation of the HTTP Connector.
Parameter Name Data Type Description path string Resource path req OutRequest An HTTP outbound request message Return Variable Data Type Description InResponse HttpConnectorError
public annotation configuration
Configuration for HTTP service
Attribute Name | Data Type | Description |
---|---|---|
host | string | Host of the service |
port | int | Port number of the service |
httpsPort | int | HTTPS port number of service |
basePath | string | Service base path |
keyStoreFile | string | File path to keystore file |
keyStorePassword | string | The keystore password |
trustStoreFile | string | File path to truststore file |
trustStorePassword | string | The truststore password |
sslVerifyClient | string | The type of client certificate verification |
certPassword | string | The certificate password |
sslEnabledProtocols | string | SSL/TLS protocols to be enabled |
ciphers | string | List of ciphers to be used |
sslProtocol | string | The SSL protocol version |
allowOrigins | string[] | The array of origins with which the response is shared by the service |
allowCredentials | boolean | Specifies whether credentials are required to access the service |
allowMethods | string[] | The array of allowed methods by the service |
allowHeaders | string[] | The array of allowed headers by the service |
maxAge | int | The maximum duration to cache the preflight from client side |
exposeHeaders | string[] | The array of allowed headers which are exposed to the client |
keepAlive | boolean | |
transferEncoding | string | The types of encoding applied to the response |
chunking | string | The chunking behaviour of the response |
maxUriLength | int | Maximum length allowed for the URL |
maxHeaderSize | int | Maximum size allowed for the headers |
maxEntityBodySize | int | Maximum size allowed for the entity body |
webSocket | webSocket | Annotation to define HTTP to WebSocket upgrade |
public annotation resourceConfig
Configuration for HTTP resource
Attribute Name | Data Type | Description |
---|---|---|
methods | string[] | The array of allowed HTTP methods |
path | string | The path of resource |
consumes | string[] | The media types which are accepted by resource |
produces | string[] | The media types which are produced by resource |
allowOrigins | string[] | The array of origins with which the response is shared by the resource |
allowCredentials | boolean | Specifies whether credentials are required to access the resource |
allowMethods | string[] | The array of allowed methods by the resource |
allowHeaders | string[] | The array of allowed headers by the resource |
maxAge | int | The duration to cache the preflight from client side |
exposeHeaders | string[] | The array of allowed headers which are exposed to the client |
public annotation webSocket
Annotation to upgrade connection from HTTP to WS in the same base path.
Attribute Name | Data Type | Description |
---|---|---|
upgradePath | string | Upgrade path for the WebSocket service from HTTP to WS. |
serviceName | string | Name of the WebSocket service where the HTTP service should upgrade to. |
CONTENT_LENGTH
Attribute Name | Data Type | Description |
---|---|---|
CONTENT_LENGTH | string | Represent 'Content-Legth' header name |