DispatchHandler

When a request is handled, the first condition in the list of conditions is evaluated. If the condition expression yields true, the request is dispatched to the associated handler with no further processing. Otherwise, the next condition in the list is evaluated.

Usage

{
  "name": string,
  "type": "DispatchHandler",
  "config": {
    "bindings": [
      {
        "condition": runtime expression<boolean>,
        "handler": Handler reference,
        "baseURI": runtime expression<uri string>,
      }, ...
    ]
  }
}

Properties

"bindings": array of objects, required

A list of bindings of conditions and associated handlers to dispatch to.

"condition": runtime expression<boolean>, optional

An inline expression to define a condition based on the request, context, or IG runtime environment, such as system properties or environment variables.

Conditions are defined using IG expressions, as described in "Expressions", and are evaluated as follows:

  • If the condition evaluates to true, the request is dispatched to the associated handler.

  • If the condition evaluates to false, the next condition in the list is evaluated.

  • If no condition is specified, the request is dispatched unconditionally to the associated handler.

For example conditions and requests that match them, see "Example Conditions and Requests".

Default: No condition is specified.

"handler": Handler reference, required

A handler to dispatch the request to if the associated condition yields true, or if there is no associated condition.

Provide either the name of a handler object defined in the heap, or an inline handler configuration object.

See also Handlers.

"baseURI": runtime expression<uri string>, optional

A base URI that overrides the existing request URI. Only scheme, host, and port are used in the supplied URI.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

In the following example, the binding condition looks up the hostname of the request. If it finds a match, the value is used for the baseURI. Otherwise, the default value is used: 

{
  "properties": {
    "uris": {
      "app1.example.com": {
        "baseURI": "http://backend1:8080/"
      },
      "app2.example.com": {
        "baseURI": "http://backend2:8080/"
      },
      "default": {
        "baseURI": "http://backend3:8080/"
      }
    }
  },
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${not empty uris[contexts.router.originalUri.host]}",
          "baseURI": "${uris[contexts.router.originalUri.host].baseURI}",
          "handler": "ReverseProxyHandler"
        },
        {
          "baseURI": "${uris['default'].baseURI}",
          "handler": "ReverseProxyHandler"
        }
      ]
    }
  }
}

Default: No change to the base URI

Example

The following sample is from a SAML 2.0 federation configuration:

  • If the incoming URI matches /saml, then IG dispatches to a SamlFederationHandler without further processing.

  • If the previous condition is not met, and the user name is not set in the session context, then IG dispatches the request to a SPInitiatedSSORedirectHandler.

    In this case, the user has not authenticated with the SAML 2.0 Identity Provider, so the SPInitiatedSSORedirectHandler initiates SAML 2.0 SSO from the Service Provider, which is IG.

  • If neither of the previous conditions are met, the request goes through a LoginChain handler. 

{
    "name": "DispatchHandler",
    "type": "DispatchHandler",
    "config": {
        "bindings": [
            {
                "condition": "${matches(request.uri.path, '^/saml')}",
                "handler": "SamlFederationHandler"
            },
            {
                "condition": "${empty session.username}",
                "handler": "SPInitiatedSSORedirectHandler",
                "baseURI": "http://www.example.com:8081"
            },
            {
                "handler": "LoginChain",
                "baseURI": "http://www.example.com:8081"
            }
        ]
    }
}

Read a different version of :