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 .

Once a response instance has been created, it can be configured using methods on the INKFResponse instance. To gain access to these methods, create a response instance and save a reference to it in a local variable:

INKFResponse response = context.createResponseFrom(representation);

Then use the response methods to add or change the header information. The available methods are listed in the table below.

MethodUse
setMimeType(String)Indicate the MIME type of the returned representation
setExpiry(int)Sets the expiry type (see below)
setExpiry(int,long)Sets the type of expiry and the time for the representation to expire (see below)
setExpiry(int,INKFExpiryFunction)Sets an expiry function (see below)
setNoCache()Marks this response to not be cached. This doesn't effect the expiry of the response so dependencies may still be cached.
setCacheBoost(int)Boost the cacheability of response above it's default. This should be used as a tuning mechanism to aid the retention of key resource representations. Default is zero (0). Values less than zero are set to zero.
setMetaData(String aKey, Object aRepresentation)Add user defined header.

setMimeType(...)

The MIME type of the returned representation can be set with the setMimeType(...) method. For example, the following code sets the MIME type of the response to "text/html":

INKFResponse response = context.createResponseFrom(...);
response.setMimeType("text/html");

which is equivalent to the following code:

INKFResponse response = context.createResponseFrom(...);
response.setHeader("mime", "text/html");

A common use of this information is to signal transports the proper MIME type to be returned.

setExpiry(...)

The Golden Thread accessor allows a representation to be set dependent on a virtual resource.

The NetKernel cache can retain responses to eliminate computation. The expiry methods allow an endpoint to specify how its returned response should be considered by the cache. The set of possible expiry types is:

INKFResponse.EXPIRY_ALWAYS
INKFResponse.EXPIRY_CONSTANT
INKFResponse.EXPIRY_NEVER
INKFResponse.EXPIRY_DEPENDENT
INKFResponse.EXPIRY_MIN_CONSTANT_DEPENDENT
INKFResponse.EXPIRY_MAX_CONSTANT_DEPENDENT
INKFResponse.EXPIRY_FUNCTION
INKFResponse.EXPIRY_MIN_FUNCTION_DEPENDENT
INKFResponse.EXPIRY_POLLED_DEPENDENT

EXPIRY_ALWAYS - the response returned by the endpoint may be different each time it is requested. The cache will not retain the response. (Example: a time of day service will always return a different value).

EXPIRY_CONSTANT - the response will stay the same until the specified absolute time. The cache may retain this response until it expires. (Example: a service that returns the current date, which is valid until midnight)

EXPIRY_NEVER - the response will not change for the life of the space. If the space is de-commissioned and then re-commissioned the response may be different. (Example: This is rarely used; it will force something that might expire to never expire. Normally, rely on EXPIRY_DEPENDENT.)

EXPIRY_DEPENDENT - the response is dependent on the responses from sub-requests. If any sub-request response expires then this response expires. The cache may retain this response until it or something it depends on expires. (Example: this is the default)

EXPIRY_MIN_CONSTANT_DEPENDENT - the response will expire if a dependent response expires or at the specified absolute time, which ever occurs first. (Example: This is a safer alternative to EXPIRY_CONSTANT as an unexpected modification to a dependent resource will cause a response to expire. With EXPIRY_CONSTANT that resource change would go unnoticed.)

EXPIRY_MAX_CONSTANT_DEPENDENT - the response will not expire until the specified absolute time. Afterwards it still won't expire until a dependency expires. (Example: Used for response that must not expire under any circumstance before a certain time. Generally, this is an adjustment an architect can make to optimize a system if there is a tolerance for imprecision)

EXPIRY_FUNCTION - the response expires when a user supplied function says it does.

EXPIRY_MIN_FUNCTION_DEPENDENT - the response expires when a dependency expires or when a user supplied function signals expiration, whichever occurs first. (Example: Use this when you want an expiry function to be considered in the mix of resource dependencies.)

EXPIRY_POLLED_DEPENDENT - like dependent only we only look at the dependent resources every poll period so it is more performant for resources with a large number of dependencies

Time

The absolute system time (in milliseconds since midnight, January 1, 1970 UTC) of the representation's expiry may be set. If you need an relative time, use System.currentTimeMillis() as the base for the offset.

Function

An expiry function may be associated with a response. This is a powerful feature that supports sophisticated extensions to NetKernel. For example, a module providing the ftp scheme support could use an expiry function to test for remote resource changes and invalidate its previous responses.

It is critical that the isExpired(...) method not return false once it has returned true. It is also crticial that the implementation is thread-safe.

To set an expiry function, create a class that implements the INKFExpiryFunction interface and set it on the response. The isExpired(...) method will then be used to determine when the associated response has expired.

public interface INKFExpiryFunction extends IExpiry
  {
  /** 
  * Returns true when response is expired. 
  * Once this method returns true it must never return false.
  */
  boolean isExpired(long aNow);
  }

setNoCache()

This method indicates that the returned representation should not be cached but anything depending on it could be cached.

For example, a logging service, active:log, would call setNoCache() on its response to accomplish the following:

  • The response is not cached and subsequent calls to the service, even with the same arguments, would cause a subsequent log message to be written.
  • The response from the endpoint that calls the log service may have its response cached.

setHeader(...)

User-defined response headers provide a means of returning information about a representation to the requesting client endpoint. For example, a process control endpoint could invoke process steps and gather information from each, such as processing time, database rows updated, etc.

The setHeader(...) method is used to create user-defined response headers. A response header entry is a name-value pair; the name is a String and the value is Object.

Example

The following code illustrates a process control endpoint that issues requests for process steps and gathers header information:

public void onSource(INKFRequestContext context) throws Exception
  {
  INKFRequest request;
  Object representation;
  INKFResponse response;
  INKFResponseReadOnly returnedResponse;
  int processingTime = 0;
  int databaseRecords = 0;
  
  
  request = context.createRequest("active:processStep1");
  returnedResponse = context.issueRequestForResponse(request);
  processingTime = returnedResponse.getHeader("time") + processingTime;
  databaseRecords = returnedResponse.getHeader("records") + databaseRecords;
  representation = returnedResponse.getRepresentation();

  ...
    
  request = context.createRequest("active:processStep2");
  returnedResponse = context.issueRequestForResponse(request);
  processingTime = returnedResponse.getHeader("time") + processingTime;
  databaseRecords = returnedResponse.getHeader("records") + databaseRecords;
  representation = returnedResponse.getRepresentation();
  
  ...
  
  response = createResponseFrom(representation);
  response.setHeader("time", processingTime);
  response.setHeader("records", databaseRecords);
  }