WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:http:request1
Description:
Id:http:request1
Category:accessor
Identifier Syntax

http:request1 is an accessor using a standard identifier grammar:

<grammar>
  <group>httpRequest:/
    <group name="type">
      <regex type="path-segment" />
    </group>
  </group>
</grammar>

with the following arguments: (for more details on argument passing details see here)

ArgumentRulesTypingDescription
typeString ()type of request resource
Request Verbs

The following verbs are supported:

Verbs
SOURCEEXISTS
Response

The response representation of this accessor for SOURCE requests is unknown.

This accessor throws no documented exceptions.

The HTTPBridge inserts a dynamic space into the request scope it uses when issuing its sub-request into the overlay's wrapped space. This space resolves requests for identifiers using the httpRequest: URI scheme. The httpRequest: address space provides information from the external HTTP request that may be retrieved by issuing requests with the SOURCE verb. The information is ultimately retrieved from the underlying HTTPRequest object issued by the HTTP transport.

Parameter Normalization

The httpRequest: space normalizes access to HTTP parameters. Regardless whether a parameter is provided as a URL query argument or as a url-encoded value in the POST body, it will be accessible using the httpRequest:/params, httpRequest:/param/xxxx spaces described below.

POST requests that mix url-encoded fields with URL query parameters are supported and are also unified into the normalized parameter space.

Matrix parameters are also parsed from the URL and may be requested with httpRequest:/matrixparams and httpRequest:/matrixparam/xxxx as described below.

Cachability

The httpRequest: scheme gives access to the information in the HTTP request and it's headers. However because this information is different in every request special consideration must be paid to cachability of services which use information the the HTTP request.

The HTTPRequestResponseSpace which hosts the httpRequest resources has an optimised implementation that allows caching to occur if only a limited set of the available information is accessed. These resources are:

  • httpRequest:/params
  • httpRequest:/param/*
  • httpRequest:/paramsHTMLEncoded
  • httpRequest:/paramHTMLEncoded/*
  • httpRequest:/matrixparams
  • httpRequest:/matrixparam/*
  • httpRequest:/matrixparamsHTMLEncoded
  • httpRequest:/matrixparamHTMLEncoded/*
  • httpRequest:/queryparam/*
  • httpRequest:/queryparamHTMLEncoded/*
  • httpRequest:/url
  • httpRequest:/url/path
  • httpRequest:/url/query
  • httpRequest:/url/relative
  • httpRequest:/query
  • httpRequest:/method
  • httpRequest:/collection

httpRequest:/params

Returns an instance of IHDSNode as the response representation which contains the complete set of HTTP request parameters includng QUERY, POST and matrix URI parameters.

For example, the following HTML will display a form for the user.

<html>
  <body>
    <p>This page contains various parameters that will be sent to NetKernel</p>
    <form method="POST" enctype="multipart/form-data" action="/test/upload/form"> Upload File:
      <input type="file" name="upfile" /> First Name:
      <input name="first-name" value="foo" /> Last Name:
      <input name="last-name" value="bar" />
      <input type="submit" value="send file" />
    </form>
  </body>
</html>

If the user selects the file download.png and enters the text "Johnson" in the last-name field and the text "Fred" in the first-name field, then the following code:

public void onSource(INKFRequestContext context) throws Exception
  {
  IHDSNode node = context.source("httpRequest:/params");
  ...   
  }

will retrieve and IHDSNode with the following information:

<root>
  <upfile>download.png</upfile>
  <last-name>Johnson</last-name>
  <first-name>Fred</first-name>
</root>

httpRequest:/paramsHTMLEncoded

Same as httpRequest:/params but the values in HDS tree are encoded to ensure any potential HTML characters in the param cannot be used in a Cross Site Scripting attack.

httpRequest:/param/...

Returns the HTTP parameter as a String representation - will find the first parameter in QUERY, POST and Matrix URI. The form of the identifier is:

httpRequest:/param/{parameter-name}

With the example form shown above, the following code retrieves the information the user entered into the field first-name:

public void onSource(INKFRequestContext context) throws Exception
  {
  String firstName = context.source("httpRequest:/param/first-name");
  ...
  }

httpRequest:/paramHTMLEncoded/...

Same as httpRequest:/param/... but the value is encoded to ensure any potential HTML characters in the param cannot be used in a Cross Site Scripting attack.

httpRequest:/postparam/...

This interface is a specialisation of httpRequest:/param/... space.

It provides strict enforcement and guarantees that the returned parameter value was specifically from a POSTed application/x-www-form-urlencoded form and not from any possible URL query parameters.

Returns a String representation. The form of the identifier is:

httpRequest:/postparam/{parameter-name}

With the example form shown above, the following code retrieves the information the user entered into the field first-name:

public void onSource(INKFRequestContext context) throws Exception
  {
  String firstName = context.source("httpRequest:/postParam/first-name");
  ...
  }

httpRequest:/matrixparams

Returns an instance of IHDSNode as the response representation which contains the complete set of matrix URL parameters.

httpRequest:/matrixparam/....

Returns the Matrix URL parameter as a String representation. The form of the identifier is:

httpRequest:/matrixparam/{parameter-name}

For an example matrix URL such as ...

http://www.foo.com/us/ma/cambridge;scale=50000;roads=main

the following code retrieves the value of the scale matrix parameter:

public void onSource(INKFRequestContext context) throws Exception
  {
  String scale = context.source("httpRequest:/matrixparam/scale");
  ...
  }

httpRequest:/matrixparamHTMLEncoded/...

Same as httpRequest:/matrixparam/... but the value is encoded to ensure any potential HTML characters in the param cannot be used in a Cross Site Scripting attack.

httpRequest:/queryparam/....

As with httpRequest:/postparam/... but this enforces strict access to a specific Query parameter.

httpRequest:/queryparamHTMLEncoded/...

Access a specific Query parameter in HTML encoded form.

httpRequest:/url

Returns the HTTP URL as a String representation. This URL does not contain the query string.

The following code retrieves the URL used in the external HTTP request:

public void onSource(INKFRequestContext context) throws Exception
  {
  String url = context.source("httpRequest:/url");
  ...
  }

httpRequest:/url/path

Returns the path part of the HTTP URL as a String representation. This does not contain the query string.

httpRequest:/url/query

Returns the HTTP URLs query String if available. Usually only GET requests will have a query string. The query string is unparsed but decoded, i.e. it is the original query string portion of the url but with any escaped characters unescaped.

The following code retrieves the URL used in the external HTTP request:

public void onSource(INKFRequestContext context) throws Exception
  {
  String url = context.source("httpRequest:/query");
  ...
  }

httpRequest:/query

Alias for httpRequest:/url/query for backwards compatibility

httpRequest:/url/full

Returns the full HTTP URL as a String representation. This includes any query string.

httpRequest:/url/relative

Returns the relative HTTP URL as a String representation. This includes any query string but removes any hostname/port details to provide a relative URI.

httpRequest:/header/...

Returns the specified HTTP header as a String representation. The form of the identifier is:

httpRequest:/header/{header-name}

For example, the following code retrieves the client's "User-Agent" header:

public void onSource(INKFRequestContext context) throws Exception
  {
  String userAgent = context.source("httpRequest:/header/User-Agent");
  ...
  }

httpRequest:/headerHTMLEncoded/...

Same as httpRequest:/header/... but the value is encoded to ensure any potential HTML characters in the header cannot be used in a Cross Site Scripting attack.

httpRequest:/headers

Returns a complete HDSNode list of all HTTP header name-value pairs.

httpRequest:/headersHTMLEncoded

Same as httpRequest:/headerss but the values in HDS tree are encoded to ensure any potential HTML characters in the header cannot be used in a Cross Site Scripting attack.

httpRequest:/method

Returns the HTTP method used in the external HTTP request as a String representation.

public void onSource(INKFRequestContext context) throws Exception
  {
  String method = context.source("httpRequest:/method");
  if ("POST".equals(method))
    {
    ...
    }
  ...
  }

httpRequest:/body

Returns the body of an HTTP POST or PUT request as a IReadableBinaryStreamRepresentation representation.

public void onSource(INKFRequestContext context) throws Exception
  {
  IReadablBinaryStreamRepresentation body = context.source("httpRequest:/body");
  ...
  }

httpRequest:/content-type

Returns the mimetype of the request entity (POST body) from the Content-Type header.

httpRequest:/content-type/params

Returns the parameter part of the Content-Type header of the request entity (POST body) as a String. For example this might include the specified encoding.

httpRequest:/upload/...

Returns an instance of IReadableBinaryStreamRepresentation as the response representation which is the binary contents of the file selected by the user. The form of the identifier is:

httpRequest:/upload/{input-name}

For example, the following HTML form allows a user to specify a local file and uploads it to NetKernel with the name upfile:

<html>
  <body>
    <form method="POST" enctype="multipart/form-data" action="/process-file-upload"> File to upload:
      <input type="file" name="upfile" />
      <input type="submit" value="send file" />
    </form>
  </body>
</html>

The following accessor endpoint code obtains the file as a binary stream:

public void onSource(INKFRequestContext context) throws Exception
  {
  IReadableBinaryStreamRepresentation file;
  file = context.source("httpRequest:/upload/upfile");
  ...
  }

httpRequest:/cookie/...

Returns an instance of javax.servlet.http.Cookie as the response representation; this object contains the information in the HTTP Cookie provided in the external HTTP request. The form of the identifier is:

httpRequest:/cookie/{cookie-name}

This endpoint code sets a cookie. The path is explicitly set to "/" so that the browser returns the cookie for all subsequent requests. The maximum age of the cookie is set to 60,000 seconds (if left unset the cookie will expire after the session ends):

public void onSource(INKFRequestContext context)
  {
  ...
  response = context.createResponseFrom(representation);
  ...
  Cookie cookie = new Cookie("rememberthis", "special-value");
  cookie.setPath("/");
  cookie.setMaxAge(60000);
  context.sink("httpResponse:/cookie", cookie);
  }

Once set, this same cookie can be retrieved in a subsequent HTTP request by the following accessor endpoint code:

public void onSource(INKFRequestContext context) throws Exception
  {
  cookie = context.source("httpRequest:/cookie/rememberthis");
  String value = cookie.getValue();
  if("special-value".equals(value)) 
    {
    ...
    }
  ...
  }

httpRequest:/remote-host

Returns the HTTP remote host name as a String representation.

public void onSource(INKFRequestContext context) throws Exception
  {
  String hostname = context.source("httpRequest:/remote-host");
  ...
  }

httpRequest:/accept

Returns a parsed representation of the HTTP Accept headers, include Accept, Accept-Language, Accept-Charset and Accept-Encoding.

IHDSNode acceptsHeaders = context.source("httpRequest:/accept",IHDSNode.class);
returns:
<headers>
  <Accept>
    <entry>
      <value>application/xhtml+xml</value>
      <q>1.0</q>
    </entry>
    <entry>
      <value>*/*</value>
      <q>0.8</q>
    </entry>...
  </Accept>
  <Accept-Charset>
    <entry>
      <value>ISO-8859-1</value>
      <q>1.0</q>
    </entry>
  </Accept-Charset> ...
</headers>

httpRequest:/accept/preferred

Returns the highest priority mimetype specified in the client HTTP request's Accept header. This is the mimetype that the client has highest preference to receive.

httpRequest:/accept/preferred/{mimetype,mimetype,mimetype}

Returns the highest priority mimetype specified in the client HTTP request's Accept header that conforms with the list of mimetype options. This is the mimetype that the client has highest preference to receive and which we are prepared to offer.

httpRequest:/acceptable/{mimetype}

Returns true if the specified mimetype is one which the client will accept based on the clients HTTP request Accept header.

httpRequest:/collection

Returns the set of all HTTP request parameters that are safe to access without incurring any caching side effects. The response is an IHDSNode with the following form...

<hds>
  <url>...</url>
  <urlPath>...</urlPath>
  <urlQuery>...</urlQuery>
  <urlRelative>..</urlRelative>
  <method>..</method>
  <params>
    <foo>baa</foo> ...
  </params>
  <matrixparams>
    <boo>baz</boo> ...
  </matrixparams>
</hds>

httpRequest:/advanced/HttpServletRequest

Returns the low-level javax.servlet.http.HttpServletRequest object as the response representation.