A selector is a special syntax that enables API Gateway configuration settings to be evaluated and expanded at runtime based on metadata values (for example, from message attributes, a Key Property Store (KPS), or environment variables). The selector syntax uses the Java Unified Expression Language (JUEL) to evaluate and expand the specified values. Selectors provide powerful a feature when integrating with other systems or when customizing and extending the API Gateway.
When you press the Shift key and open a filter, you can edit all filter settings using text values in the advanced filter view. This means that you can specify all filter fields using the API Gateway selector syntax. For more details on the advanced view, see Advanced Filter View.
The API Gateway selector syntax uses JUEL to evaluate and expand the following types of values at runtime:
-
Message attribute properties configured in message filters, for example:
${authentication.subject.id}
-
Environment variables specified in
envSettings.props
andsystem.properties
files, for example:${env.PORT.MANAGEMENT}
-
Values specified in a configured Key Property Store, for example:
${kps.CustomerProfiles[JoeBloggs].age}
![]() |
Important |
---|---|
Do not use hyphens ( |
A message attribute selector can refer to a field of that message (for example
certificate
), and you can use .
characters to access subfields.
For example, the following selector expands to the username
field of the
object stored in the profile
attribute in the message:
${profile.username}
You can also access fields indirectly using square brackets ([
and ]
).
For example, the following selector is equivalent to the previous example:
${profile[field]}
You can specify literal strings as follows:
${profile[“a field name with spaces”]}
For example, the following selector gets a certificate from a Keyed Property Store by specifying its Distinguished Name:
${kps.certsByDName[“CN=Joe, O=Vordel”].certificate}
![]() |
Note |
---|---|
For backwards compatibility with the |
The following top-level keys are resolved specially:
Key | Description |
---|---|
kps
|
Subfields of the kps key reflect the alias names of Keyed Property
Store objects configured for the local API Gateway. Further indexes represent objects
looked up in that KPS (for example,
${kps.certsByDName[“CN=Joe, O=Vordel”].certificate} ).
|
env , system
|
In previous versions, fields from the envSettings.props and
system.properties files had restrictions on the prefixes used.
The selector syntax does not require the env and system
prefixes in these files. For example, conceptually ${env. selects
the settings from envSettings.props , and the rest of the selector
chooses any properties in it. For compatibility, if a setting in either file
starts with this prefix, it is stripped away so the selectors still behave
correctly with previous installations.
|
Each ${...}
selector string is resolved step-by-step, passing an initial context object
(for example, Message
). The top-level key is offered to the context object, and if it
resolves the field (for example, the message contains the named attribute), the resolved object is
indexed with the next level of key. At each step, the following rules apply:
-
At the top level, test the key for the global values (for example,
kps
,system
, andenv
) and resolve those specially. -
If the object being indexed is a Dictionary, KPS, or Map, use the index as a key for the item’s normal indexing mechanism, and return the resulting lookup.
-
If all else fails, attempt Java reflection on the indexed object.
![]() |
Note |
---|---|
Method calls are currently only supported using Java reflection. There are currently no
supported functions as specified by the Unified Expression Language (EL) standard. For
more details on JUEL, see |
This section lists some example selectors that use expressions to evaluate and expand their values at runtime.
The following message attribute selector returns the HTTP User-Agent
header:
${http.headers["User-Agent"]}
For example, this might expand to the following value:
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
In a default configuration, the following environment variable selector returns port 8091:
${env.PORT.MANAGEMENT + 1}
The following KPS selector returns the certificate for the entry in the Certificate Store with
the Joe Soap
alias:
${kps.certsByAlias[“Joe Soap”].certificate}
This returns the Distinguished Name in that certificate:
${kps.certsByAlias[“Joe Soap”].certificate.getSubjectDN()}
This returns the certificate identified by the alias stored in the
authentication.subject.id
attribute:
${kps.certsByAlias[authentication.subject.id]}
The following message attribute selector returns the CGI argument from an HTTP URL (for example,
returns bar
for http://localhost/request.cgi?foo=bar
):
${http.client.getCgiArgument("foo")}
This returns the name of the top-level element in an XML document:
${content.body.getDocument().getDocumentElement().getNodeName()}
This returns true if the HTTP response code lies between 200 and 299:
${http.response.status / 200 == 2}
![]() |
Tip |
---|---|
You can use the Trace filter to determine the appropriate selector expressions to
use for specific message attributes. When configured after another filter, the Trace
filter outputs the available message attributes and their Java type (for example, <install-dir>/apigateway/docs/javadoc/index.html
For example, for the |
There are a number of API Gateway filters that extract message attribute values (for example, Extract Certificate Attributes and Retrieve from HTTP Header). Using selectors to extract message attributes offers a more flexible alternative to using such filters. For more details on using selectors instead of these filters, contact Oracle Support.