httpPost

Home > Books > NetKernel API and Services Reference > Accessor Listing > HTTP Client Services > httpPost

Module

urn:org:ten60:netkernel:ext:http:client

The httpPost accessor is exported by the urn:org:ten60:netkernel:ext:http:client module. Import this module to gain access to the accessor.

Syntax

URI

active:httpPost

Argument	Rules	Description
url	Mandatory	the URL to issue the request to
config	Optional	an optional config resource
state	Optional	an optional state resource
arg	Optional	An argument to be POSTed in the request body
nvp	Optional	An NVP argument to be sent as URL-encoded form parameters

Example Usage

DPML

<instr>
  <type>httpPost</type>
  <url>http://www.1060research.com</url>
  <state>var:mystate</state>
  <arg>myMessage.xml</arg>
  <target>this:response</target>
</instr>

NetKernel Foundation API

    import org.ten60.netkernel.xml.representation.DOMAspect;
    
    req = context.createSubRequest("active:httpPost");
    req.addArgument("url","http://1060.org/example-service");
    doc-to-post = new DOMAspect( d );
    req.addArgument("arg",doc-to-post);
    representation=context.issueSubRequest(req);

Purpose

Issues an HTTP POST request for the given url.

The optional state argument is used to store client-side state information.

If an nvp argument is provided it will be treated as a Name-Value-Pair argument and sent as URL-encoded form parameters.

If an arg argument is provided it will be added to the request body and sent as the POST resource to the url.

Please note httpPost does not support multipart in the body at this time. Therefore nvp and arg are mutually exclusive - you can only use one or the other not both together.

If you are issuing SOAP requests, the NetKernel SOAP accessors might be a better choice of technology.

Client-Side State

Interactions with the remote server are stateless unless a resource is provided as the optional state argument. Please refer to the httpState guide for details.

Header field interpretation

See httpGet for more details.

Config

Configuration information is provided as the config argument. If this is missing the service will request configuration information from the address ffcpl:/etc/HTTPClientConfig.xml. If this is missing the following default is used:

<config>
  <proxyHost>proxy.mydomain.com</proxyHost>
  <proxyPort>80</proxyPort>
  <followRedirects>true</followRedirects>
  <retryAttempts>3</retryAttempts>
  <maxConnectionsPerHost>4</maxConnectionsPerHost>
  <maxTotalConnections>10</maxTotalConnections>
  <maxAcceptableContentLength>-1</maxAcceptableContentLength>
  <stateExpirationTime>600</stateExpirationTime>
  <connectTimeout>2000</connectTimeout>
  <timeout>5000</timeout>
</config>

Each configuration element is optional, if not specified the default values (above) will be used. The parameters are as follows:

proxyHost	hostname of proxy server
proxyPort	port of proxy server
followRedirects	follow HTTP redirect response codes
retryAttempts	number of attempts to make connection before failing
maxConnectionsPerHost	maximum simultaneous connections to make to a single host
maxTotalConneciton	max total connections
maxAcceptableConentLength	largest resource to handle in response, -1 indicates accept any size.
stateExpirationTime	time for client side state to be valid.
connectTimeout	time to allow for a connection to be established with server before failing
timeout	time to allow an established connection to remain idle before failing

Proxy settings will be taken from the global system proxy settings if they are not specified in the config.

HTTPResponseCodeAspect

If an error occurs issuing the request or you request to return an HTTPResponseCodeAspect aspect (see NKFRequest.setAspectClass()) then the accessor will return a HTTPResponseCodeAspect containing the HTTP code and body response - this can be valuable for testing purposes.

Examples

Posting a URI referenced XML document to a URL

<instr>
  <type>httpPost</type>
  <url>http://localhost:8081/test-http-client/server/echo.idoc</url>
  <arg>ffpl:/some/path/myXMLMessage.xml</arg>
  <target>this:response</target>
</instr>

Posting a literal XML document to a URL

<instr>
  <type>httpPost</type>
  <url>http://localhost:8081/test-http-client/server/echo.idoc</url>
  <arg>
    <myMessage>
      <element>value</element>
    </myMessage>
  </arg>
  <target>this:response</target>
</instr>

Literal NVP Arguments Posted as URL-form encoded.

<instr>
  <type>httpPost</type>
  <url>http://localhost:8081/test-http-client/server/echo.idoc</url>
  <nvp>
    <nvp>
      <hello>world</hello>
      <something>else</something>
    </nvp>
  </nvp>
  <target>this:response</target>
</instr>