No Results
Request Context Object
Article Contents

AppRequest

An HTTP request to be issued by edgeWeb to a target application. This object has all the methods of ClientRequest – all getters – as well as methods to mutate properties of the request, thus allowing JavaScript rules to adjust the request to be sent to the target application.

Method Return Type Arguments Description 
getProtocol
 String Returns the name of the protocol to be used for the request: either HTTP or HTTPS. 
getMethod
 String Returns the HTTP method used for this request. 
getHost
 String Returns the host (name or address) for which this request is destined. Expected to be the name of the server for the proxied application. Includes a port if needed and returns the string from setHost (see below); 
setHost
 String Set the host (name or address); Includes a port if needed (for example, if the backend server URL is https://myserver.com:8443/, then setHost should be setHost(“myserver.com:8443”) and getHost() would return that string); Additionally, setHost is only required if you need to override the default value for the host that edgeCore sets (from the Connection endpoint); 
getRequestUri
 String Returns the request URI specified on the request line of this HTTP message. 
getQueryString
 String Returns the correctly escaped query string, as it would appear in the request message. 
getCookies
 List<Cookie> Returns the list of cookies that will be included in the request message. The default list of cookies will be determined according to what is in the cookie cache that matches the host/path to which the request is being sent. 
addCookie
 Cookie Add a cookie to be included in the request message. 
getBody
 String Returns the body/content to be sent with the request. 
setBody
 String body Set the body/content to be sent with the request. 
addQueryStringParameter
 String name

 

String value

 Add a query string parameter to the request. Both name and value should be unescaped; edgeWeb takes care of escaping before issuing the request. Passing a null value is allowed – the corresponding parameter will be encoded as just the name (no ‘=’). 
setQueryStringParameter
 String name

 

String value

 Replaces a string parameter from the request. Creates the parameter if it does not currently exist on the request. 
addFormParameter
 String name

 

String value

 Add a named parameter to be encoded as part of the form that will be the body of the request. Encoding will depend on how the content-type header has been set. 
addFormParameters
 LinkedHashMa p<String, String []> Add a map of parameters 
getParameterMap
 LinkedHashMap<Str ing, String[]> Returns the form parameters that are to be encoded as the body of the request. 
getHeaderNames
 String[] Returns an array of the names of all the headers to be included in the request. 
getHeader
 String Returns the header value corresponding to the specified name. If more than one such header exists, the first one encountered will be returned. 
getHeaders
 String[] Returns the values of all headers with the specified name. 
setHeader
 String name

 

String value

 Set the value of the named header. Overwrite the existing header if it exists. In the unusual case that more than one exists, any existing values will be removed before the new one is assigned. 
addHeader
 String name

 

String value

 Add another value for the named header. This allows multiple headers to exist for the same name, which is an often-used feature of HTTP headers (for example, Cookie).

 

AppResponse

An HTTP response that has been received by edgeWeb from a target application.  Like ClientRequest, this object should be treated as read-only.  This is the basis on which a ClientResponse will be created.

Method Return Type Arguments Description 
getProtocol
 String Returns the name of the protocol to be used for the request: either HTTP or HTTPS. 
getStatusCode
 int Returns the HTTP status code for the response message. 
getCookies
 List<Cookie> Returns the list of cookies that were included in the response message. This corresponds to the set of Set-Cookie headers that were in the response. 
getBody
 String Returns the body/content of the response. This is only available if the response has been buffered, which is only the case if this is a response to a sub-request. 
getHeaderNames
 String[] Returns an array of the names of all the headers that were included in the response. 
getHeader
 String Returns the header value corresponding to the specified name. If more than one such header exists, the first one encountered will be returned. 
getHeaders
 String[] Returns the values of all headers with the specified name.

 

AppSession

The AppSession interface is concerned with the state of edgeWeb’s login session with the target application.  Its primary purpose from JavaScript rules’ point of view is to facilitate callbacks being able to indicate completion of sign-on and sign-off sequences.  Outside of these processes, it also allows any other logic that might detect certain conditions to indicate session expiry or failure.

Method Return Type Arguments Description 
getSessionState
 SessionState Returns the current state of the session. 
sessionExpired
 Notify edgeWeb that the session has expired. Session will transition to the INACTIVE state. 
sessionFailed
 Notify edgeWeb that the session has failed. Session will transition to the FAILED state. 
signOnComplete
 boolean established Notify edgeWeb that sign-on is complete, and indicate whether or not a session was successfully established. Unless signOnAbort is called, this method must be called by the SSO handler at some point after its signOn method has been called, else all requests related to the session will be stalled. If true is passed, the session transitions to the ESTABLISHED state, else it transitions to the FAILED state. 
signOnAbort
 If for whatever reason the sign-on process is to be aborted, call this instead of signOnComplete. This is different from calling signOnComplete(false) because we revert back to the prior state, rather than ‘progressing’ to the FAILED state. 
signOffComplete
 boolean signedOff This method must be called by the SSO handler at some point after its signOff method has been called. The value of signedOff is actually ignored, as there is nothing edgeWeb can do to rectify the situation if sign-off fails.

 

SessionState

The SessionState enumeration can be accessed via AppSession which is imported by default, so code such as the following is possible:

if (ctx.appSession.getSessionState() == AppSession.SessionState.ESTABLISHED) {


    // we know that our sign-on logic was executed, so we can, for example,
    // act on session variables that were set then
    var authInfo = ctx.appSession.getVariable('authInfo');


	// TODO..
}

The enumeration values are as follows:

State Description 
INACTIVE
 No requests associated with the session have been made, so sign-on has not been triggered. 
ESTABLISHING
 Sign-on has been triggered, and the relevant SsoHandler is in the process of establishing a login session. 
ESTABLISHED
 A login session has been successfully established. 
FAILED
 Sign-on was attempted, but failed. 
SIGNING_OFF
 Sign-off has been triggered (normally when edgeCore user has logged out, or credentials configuration has been changed)

 

ClientRequest

An HTTP client request to edgeWeb.  This should be treated as read-only.  Generally speaking, modifications should be made to the corresponding AppRequest that will be forwarded to the target application.

Method Return Type Arguments Description 
getProtocol
 String Returns the name of the protocol to be used for the request: either HTTP or HTTPS. 
getMethod
 String Returns the HTTP method used for this request. 
getHost
 String Returns the host (name or address) for which this request is destined. Expected to be the name of the server on which the edgeCore server is running. 
getRequestUri
 String Returns the request URI specified on the request line of this HTTP message. Get at this more conveniently by using ctx.requestUri. 
getQueryString
 String Returns the correctly escaped query string, as it would appear in the request message. 
getCookies
 List<Cookie> Returns the list of cookies that will be included in the request message. The default list of cookies will be determined according to what is in the cookie cache that matches the host/path to which the request is being sent. 
getBody
 String Returns the body/content to be send with the request. 
getParameterMap
 Map<String, String[]> Returns the form parameters that are to be encoded as the body of the request. 
getHeaderNames
 String[] Returns an array of the names of all the headers to be included in the request. 
getHeader
 String Returns the header value corresponding to the specified name. If more than one such header exists, the first one encountered will be returned. 
getHeaders
 String[] Returns the values of all headers with the specified name.

 

ClientResponse

An HTTP request to be sent back to the client web browser by edgeWeb after a response has been received from the target application.  The properties of this object are effectively calculated from an AppResponse.

Method Return Type Arguments Description 
getProtocol
 String Returns the name of the protocol to be used for the request: either HTTP or HTTPS. 
getStatusCode
 int Returns the status code to be included in the status line of the response message. 
setStatusCode
 int Set the status code to be included in the status line of the response message. 
getCookies
 List<Cookie> Returns the list of cookies that will be included in the response message. By default, no cookies are included (not by edgeWeb anyway – depending on the configuration of edgeCore and/or Tomcat other cookies will be included, such as JSESSIONID). 
addCookie
 Cookie cookie Add a cookie to be included in the response message. 
getHeaderNames
 String[] Returns an array of the names of all the headers to be included in the response. 
getHeader
 String Returns the header value corresponding to the specified name. If more than one such header exists, the first one encountered will be returned. 
getHeaders
 String[] Returns the values of all headers with the specified name. 
setHeader
 String name

String value

 Set the value of the named header. Overwrite the existing header if it exists. In the unusual case that more than one exists, any existing values will be removed before the new one is assigned. 
addHeader
 String name

String value

 Add another value for the named header. This allows multiple headers to exist for the same name, which is an often-used feature of HTTP headers (for example, Cookie).

 

ConstructDO Objects

There are several ConstructDO – Java – types in the EdgeCore system.  These types relate to types of nodes in the configuration pipeline.  The ones of interest to web adapter rules are ConnectionDO and ProxyFeedDO.

When a content handler is run, it is always in the context of a web content feed.  This feed is represented in the rules by a ProxyFeedDO object.  The connection with which it is related is represented by a ConnectionDO object.  The primary purpose of these objects from the JavaScript rules point of view is to get access to their respective properties, which we may want to use as conditions for the execution of some logic.  The most common use is for us to access additional properties of application-specific feeds to control whether the features represented by those properties are active or not.

 

Cookie

An HTTP cookie. This interface simply defines some getters and setters for the various cookie properties.

CookieImpl (String name, String value, String domain, String path)
Note: domain must match that of cookies in a browser (e.g. “example.com”, not “https://example.com”);

Method Return Type Arguments Description 
getHost
 String Returns the host/domain to which this cookie applies. 
setHost
 String host Set the host/domain to which this cookie should apply. 
getName
 String Returns the name of this cookie. 
getPath
 String Returns the path to which this cookie should apply. 
setPath
 String path Set the host/domain to which this cookie should apply. 
getValue
 String Returns the value of the cookie. 
setValue
 String value Set the value of the cookie. 
getMaxAge
 long Returns the max-age of the cookie. This is the time in seconds that it should ‘live’. If the 
setMaxAge
 long maxAge Set the max-age value for the cookie. When this is called, this is used in preference to any previous call to setExpires (or setMaxAge for that matter). 
getExpires
 LocalDateTime Returns the expires date/time for the cookie. If max-age is specified, then this is calculated from the max-age value. 
setExpires
 LocalDateTime expires Set the expires date/time for the cookie. When this is called, this is used in preference to any previous call to setMaxAge (or setExpires for that matter). 
hasExpired
 boolean Compares the current date/time with the value currently returned by getExpires. 
getHttpOnly
 boolean Returns whether the httpOnly flag is set for this cookie. 
setHttpOnly
 boolean httpOnly Set whether the httpOnly flag should be for this cookie 
getSecure
 boolean Returns whether the secure flag is set for this cookie. 
setSecure
 boolean secure Set whether the secure flag should be set for this cookie.

 

CookieCache

A cookie cache is associated with each AppSession.  The cache behaves essentially as a user-agent cache, as per RFC 6265.

Method Return Type Arguments Description 
getCookies
 List<Cookie> String domain Returns the cookies cached for the given name. 
getCookies
 List<Cookie> String domain

String path

 Returns the cookies cached for the given name and path. 
getCookie
 Cookie String domain

String path

String name

 Returns the named cookie currently cached for the given domain and path. 
removeCookie
 String domain

String path

String name

 Remove the named cookie currently cached for the given domain and path. 
removeCookies
 String name Remove all cached cookies with the specified name. 
removeAllCookies
 Clear the cache. 
setCookie
 Cookie cookie Insert the supplied cookie into the cache.

 

AppRequestContext

The AppRequestContext associated with a ProxyRequestContext represents the state associated with the requests and responses being sent to and from the target application. A selection of the methods is described below. The supported method of calling other methods is via the Request Context Object.

Web Response Pipeline

There are two modes the response content pipeline runs in:

  • text – response from the target application is decoded, content transformations are applied, and then the result is encoded according to the configured character encoding before sending it to the client.
  • binary – response from the target application is streamed straight through to the client without any decoding, encoding, or other interpretation or alteration.

Note that it is normal to set the pipeline type to binary for some text content if no transformations are required to be performed on the content.

In JavaScript rules, use ResponsePipelineType.TEXT and ResponsePipelineType.BINARY when calling the methods in the following table.  These methods can be called against the ctx.appRequestContext object available in onResponse.

Method Return Type Arguments Description 
getResponsePipelineType
 ResponsePipelineType Returns an indication of the mode the response pipeline is currently set to operate in. 
setResponsePipelineType
 ResponsePipelineType Sets the mode the response pipeline is currently set to operate in. Once content starts streaming, this call has no effect.

 

Response Character Encoding

The AppRequestContext implements methods for configuring the way the response pipeline behaves in terms of decoding application response content and encoding the corresponding client response content.  The table below lists the methods and their effect on response processing.

Method Return Type Arguments Description 
getResponseCharset
 Charset Returns the currently configured response charset – this will be used when it is time to start streaming response content through to the client. The default value is based on a best effort at determining what the character encoding of the application response is. 
setResponseCharset
 Charset Set the character encoding to be used when streaming response content to the client. This value is used for creating the codecs for the incoming app response content and the outgoing client response content. It is not used necessarily used to populate the charset qualifier in the outgoing content-type header. 
getResponseContentType
 ContentType Returns the currently configured content type to be used for text response decoding and encoding. The default value for this is set from the content-type header of the application response. 
setResponseContentType
 String Configure the response pipeline as if the supplied value was used as the content-type header in the application response message. If a character encoding is included in the header value, this will be used to effectively call setResponseCharset and hence affect how the content is decoded and encoded. The pipeline type will be modified automatically based on the value supplied here. If you want to override it, then make sure the call to setResponsePipelineType is made after the call to this method.

 

ProxyRequestContext

The ProxyRequestContext is a Java interface, mostly for internal use by edgeWeb.  From the content and authentication rules point of view, the methods of this interface that we’re interested in are more conveniently accessible via the JavaScript request context object, which is the supported method of accessing those methods.  ProxyRequestContext extends VariableStore, through which we can store and retrieve request-scoped variables.  Rules may reference it when it is required to be passed as an argument to Java methods.

 

Server Information Object

Server information can be accessed via ctx.info, but calling ctx.info.get(key). Valid keys are:

Key Value Type Description 
login.username
 String Username of the currently logged-in EdgeCore user. 
login.domain
 String EdgeCore domain of the currently logged-in user. 
login.usernameWithDomain
 String A string of the form ‘username@domain’. Returns the equivalent of calling ctx.info.get(“login.username”) + “@” + ctx.info.get(“login.domain”) 
login.password
 String Plain-text password of currently logged-in user. 
login.role
 Array of Strings An array of roles assigned to the currently logged-in user. 
connection.remoteAddress
 String Address of the client browser (as far as the server knows) of the currently logged-in user 
serverInfo.serverInfo
 String Name and version of web server EdgeCore is running in – eg. “Apache Tomcat/8.0.41” 
serverInfo.endpoints
 Array of Strings An array of endpoints the server is listening on – eg. [“http://127.0.1.1:8080”]

 

Terms | Privacy
×