5 Using Actions to Manage and Manipulate API Traffic

About Action Chains

You implement actions on API request or response traffic using the Actions tab for each API. You drag and drop individual actions into the Request or Response action chain to make them take effect. When you drop an action, a pane appears with the action parameters for you to configure. Every action has at least one optional Instance ID parameter that you can use to create an informal alphanumeric version number to identify the action. Some of these parameters are optional and some required. If you get a fail message when you try to save your changes, the problem can be a missing parameter. See "Understanding the Default Actions" for details about the parameters for individual actions.

You can use the actions provided by Services Gatekeeper, or create your own actions to act on the request (or response) traffic for an API. You can set up actions chains to take a wide range of real-time effect on the request or response messages, such as identity management, mapping to support data formats and protocol changes, authorization, logging, monitoring, and statistics. Some action parameters are optional and others required. If you get a fail message when you try to save your changes, the problem can be a missing parameter.

The sequence of actions in the action chain depends on the direction of the message flow. It is either application-initiated and traveling to the network, or server-initiated and traveling to the application. Some actions (such as identity management) are valid only in the request flow and some only in the response flow. Other actions (such as supporting protocol changes, validations) are common in that they are applicable in either direction. Services Gatekeeper does not allow you add an invalid action to an action chain.

When you position an action incorrectly in a chain, Partner and API Management Portal prompts you to ensure that the sequence of actions is valid for that direction.

Actions in Application-Initiated Flows

When an application sends a request that contains a call to an API subscribed to by the application, Services Gatekeeper processes it using all actions configured for it in order. Services Gatekeeper can receive and handle incoming HTTP requests such as SOAP, REST, or XML-RPC. Services Gatekeeper checks the incoming request and performs preconfigured tasks such as enforcing policy (associated with the service level agreement), translates the message as necessary (such as from JSON to XML format), and so on. In addition, it processes the action with any custom tasks you added to suit your requirements. Finally, Services Gatekeeper forwards the outbound request message to the server.

Actions in Server-Initiated Flows

Server-initiated flows occur when, for example, an application sets up a notification for an event. The server listens for the event and sends a notification to the application. The notification comes in to Services Gatekeeper as a request from the server and contains a call to an API subscribed to by the application. Services Gatekeeper receives the request from the server and processes it according to the response action chain. The final step in the action chain would be to forward the outbound request message to the application in the format required by that application.

When the application responds to this notification, the API proxy processes that response according to the tasks preconfigured for that sequence of the action chain. Finally, the response for the server-initiated request is sent back to the server.

Understanding Front and Middle Actions

Actions for both chains are divided into front actions and middle actions. Use front actions as major filters on the incoming requests. For example, you can use Throttling to regulate the usage of the API and regulate traffic based on specific partner groups. (API management already provides throttling based on the application and based on the network service.)

Use middle actions to act on the content of the request or response in real time. For example, use Callout to perform an HTTP GET operation against the Request URL and store the response as required.

About Action Statuses

You only change the action statuses if you create your own actions using the instructions in ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide.

An action can have one these statuses:

• ACTIVE

  The Oracle-supplied actions, and any new actions you create in Partner and API Management Portal have a state of the ACTIVE.

  Any API can use an action the ACTIVE state.

• DEPRECATED

  A deprecated action represents an older version of a current interface. When you update an existing action, the updated version becomes the active version and the previous version becomes deprecated. You can also deprecate an existing action in Partner and API Management Portal, by selecting the icon adjoining the trash can icon within the interface icon. Services Gatekeeper asks you to specify the date and time when the interface should be deprecated.

  Tip:

  Maintain backward compatibility when you update an active action.

  The data for a deprecated action cannot be modified, and deprecated actions are not available to new APIs.

  The service associated with a deprecated action is available to APIs that subscribed to the interface and only for a designated period. After that period, the network service supplier can remove the deprecated interface.

Setting Actions System Performance Settings

You use the Actions system performance settings to ensure that your actions do not inadvertently include code that adversely affects Services Gatekeeper performance. The Actions system performance settings are listed here with the default value in parenthesis:

• KeepNorthSession Boolean (false) - If true, this setting keeps the session open after the request is complete

• EnableSouthCookie Boolean (false) - If true, allows applications to communicate with backend servers using cookies. You must set this to true if your Actions use basic (text-based) authentication.

• UseSession Boolean (false) - If true, allows an application to use a session when communicating with backend servers.

• MaxTotalConnections Integer (4000) - Sets the maximum total allowed network connections. You can also set this option from the system WebLogic server start up script; see "Using the WebLogic Startup Script to Set Action System Performance Settings" for details.

• SocketTimeoutMs Integer (30000) - The time, in milliseconds, that socket waits for activity before closing down. You can also set this option from the system WebLogic server start up script; see "Using the WebLogic Startup Script to Set Action System Performance Settings" for details.

• ConnectTimeoutMs Integer (30000) - The time, in milliseconds, that a connection waits for activity before closing down. You can also set this option from the system WebLogic server start up script; see "Using the WebLogic Startup Script to Set Action System Performance Settings" for details.

• ReuseAddress Boolean (true) - If true, directs Services Gatekeeper to ignore the TCP time_wait state. This improves performance by allowing Services Gatekeeper to close the socket immediately after the connection is closed, instead of continuing to wait for late packets.

You have these options to change these settings:

• Edit the DafConfigurationsMBean directly. For details on DafConfigurationsMBean see the ”All Classes” section of the Actions Java API Reference documentation.

• Use the Services Gatekeeper Administration Console. See "Using the Administration Console to Set Action System Performance Settings" for details on using the Administration Console.

• See "Using the WebLogic Startup Script to Set Action System Performance Settings" for details on setting these Actions system performance parameters as startup script options.

% startWebLogic.sh -Doracle.sdp.daf.max_total_connections=3000

Setting Actions White and Black Lists

You use these ”white” and ”black” lists to control the individual methods and packages that software developers are allowed to use in actions. These are the default lists:

• Black list of methods: exit and setProperty.

• Black list of packages:

  • java.lang.Thread;java.lang.Runnable

  • java.lang.ClassLoader

  • java.lang.Class

  • java.io

  • java.net

  • groovy.lang.GroovyShell

  • groovy.util.Eva

  • groovy.io

  • groovy.net

• White list of methods: java.net.InetAddress.getLocalHost()

• White list of packages: null

To view or change the white and black lists using the Administration Console:

1. Start the Administration Console.

   See ”Starting and Using the Administration Console” in Services Gatekeeper System Administrator's Guide for details.

2. Click Lock & Edit.

3. Navigate to OCSG, then admin_server_name (Server1 by default), then Container Services, then DafGeneralInformation, then Operations.

   The Configuration and Provisioning on server_name page appears with the performance settings.

4. Select an operation from the Select An Operation menu. The choices are:

   • loadBlackListMethod - Add Java/Groovy methods to the black list.

   • loadBlackListPackage - Add Java/Groovy packages to add to the black list.

   • loadWhiteListMethod - Add Java/Groovy methods to the white list.

   • loadWhiteListPackage - Add Java/Groovy packages to the white list.

   • retrieveBlackListMethod - Show the list of the Java/Groovy methods on the black list.

   • retrieveBlackListPackage - Show the list of Java/Groovy packages on the black list.

   • retrieveListAll - Show the contents of all white and black lists.

   • retrievePerformanceSets - Show the Actions performance settings (set using Attributes).

   • retrieveWhiteListMethod - Show the list of all items on the white lists.

   • retrieveWhiteListPackage - Show the list of all packages on the white lists.

appKeyValidation

Authenticate an application and give it access to an API. Typically used when the application cannot identify itself by other means. Confirms that an application has permission to access a specific API using an application key. You identify the application key, and you can also test whether that key exists in a header, or in a query parameter inside the header.

This action probes the x-app-key parameter for the API key in the request/response (unless you specify a different parameter). Configure appKeyValidation with these parameters:

• Headerkey - (String) Specifies the header to check for the application key.

• QueryParameter - (String) Specifies the application key to check for.

• UseHeader - (Boolean) True directs the action to confirm that the application key exists on the header. False does not use this test. Can be used with UseQueryParameter.

• UseQueryParameter - (Boolean) True directs the action to confirm that the application key exists in the query parameter. False does not use this test. Can be used with UseHeader.

Callout

A REST Call-out. Performs an HTTP GET operation against the RequestUrl and puts the response into the value of the storeResponse field for use by another action. You can use Callout to change attributes of the incoming request. This feature is also available to use in a Groovy script or custom action.

Set up a proxy or business service callout by:

1. For the Request URL parameter, enter the remote URL for the callout in the Value column.

2. For the Store Response parameter, enter the name of variable on the context in which the response is stored in the Value column.

The content of the message is constructed using the values of variables in the message context. The message content for outbound messages is handled differently depending upon the type of the target service.

This example uses the createCallout method to obtain a value for myattribute at the myurl URI:

context.createCallout().withRequestUrl("http://myurl.com")
.withRequestMethod("GET").build().send("myattribute");

You can then use the value for myattribute in a consecutive action:

HttpResponse response = context.getAttribute("myattribute");
and response has getStatus(), getHeaders and getBodyAsType(...)

CORS

Web pages are free to imbed some resources, such as images, from outside their own domain. Exceptions to this are fonts and AJAX (XMLHttpRequest) requests, which are usually restricted to the same domain that the parent web page itself is in. The ”cross-domain” AJAX requests in particular are forbidden because they represent glaring security risks.

This is a security-based action, so put it as early in your middle action chain as you can. After you add this action to an action chain, configure it to process the CORS messages that your implementation uses.

Also, having this early in the action chain allows you to take advantage of the Allow Non Verified Requests option which cancels action chain processing if the action fails. This can prevent unnecessary processing if this action fails.

See the CORS specification at the W2C Cross-Origin Resource Sharing website:

https://www.w3.org/TR/2014/REC-cors-20140116/

The configuration parameters give you the options to:

• Allow preflight requests, simple requests, or both.

• Decide whether to require credentials when calling the API.

• Allow or disallow all origin URIs, resource headers, or methods to call the API.

• Create ”white lists” of origins URIs, resource headers, or methods that are allowed to call the API.

• Decide whether to support credentials in the request.

• Decide whether to continue action chain processing if the CORS action does not pass validation.

• The maximum time a user agent is allowed to cache results.

Table 5-1 lists the CORS configuration options.

*.us.mydomain.com

This example CORS configuration allows all CORS features and responds to the origin with any requests it receives:

<corsActionConfig>
  <allowAnyHeader>true</allowAnyHeader>
  <allowAnyMethod>true</allowAnyMethod>
  <allowAnyOrigin>true</allowAnyOrigin>
  <supportPreflightRequests>true</supportPreflightRequests>
  <supportSimpleRequests>true</supportSimpleRequests>
</corsActionConfig>

This example allows any header or method, supports both simple and preflight requests, but limits CORS requests to only the yourdomain.com and mydomain.com domains:

<corsActionConfig>
  <allowAnyHeader>true</allowAnyHeader>
  <allowAnyMethod>true</allowAnyMethod>
  <allowedOrigins>yourdomain.com</allowedOrigins>
  <allowedOrigins>mydomain.com</allowedOrigins>
  <supportPreflightRequests>true</supportPreflightRequests>
  <supportSimpleRequests>true</supportSimpleRequests>
</corsActionConfig>

This example allows any header or method, but only from a derivative of mydomain*.com, and that supports only simple requests.

<corsActionConfig>
  <allowAnyHeader>true</allowAnyHeader>
  <allowAnyMethod>true</allowAnyMethod>
  <returnWildCardAllowedOrigins>
  <allowedOrigins>mydomain*.com</allowedOrigins>
  <supportPreflightRequests>false</supportPreflightRequests>
  <supportSimpleRequests>true</supportSimpleRequests>
</corsActionConfig>

Groovy

Use a Groovy language script to change any aspect of a request or response message. You can add Groovy code to change the message content, destination, status, and so on. The script can be as simple or complex as your implementation requires. This option requires knowledge of the Groovy programming language.

You use the Actions Java API to obtain content from the API request and response traffic to act on in the Groovy action. Start by looking through the HttpContext class for information about extracting elements from messages.That class uses the HttpMessage, HttpRequest, and HttpResponse classes and some of its own methods to retrieve elements from messages that you can then manipulate. These classes are available from the ”All Classes” section of the Actions Java API Reference.

See "Common Actions Programming Tasks" and ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide for some Groovy code examples.

Json2Xml

This action takes text formatted for the JSON protocol from the body of the incoming request or response body, and translates it into XML format in the body of the outgoing request or response. Table 5-2 lists the parameters for this action:

For example, this JSON formatted text:

{
  "SendSms": { 
    "message":"my message 2",
    "senderName” : "senderName",
    "addresses” : "tel:123456",
    "@myattribute” : "foo”  }
}

Is translated in this XML format:

<SendSms myattribute="foo">
  <addresses>tel:123456</addresses>
  <senderName>senderName</senderName>
  <message>my message 2</message>
</SendSms>

See the "Xml2Json" action to translate XML input to JSON.

RateLimit

Restricts access to a URL for HTTP-to-HTTP communication. You set the allowable number of accesses for a configurable time period for a specific URL.

You set rate and timePeriodInMs (time period in milliseconds) parameters. rate sets the number of request messages that can be sent to the URL in the time period set by timePeriodInMs. For example, a rate of 100 and a timePeriodInMs of 60000, allows 100 request messages per minute.

You can further refine access to the URL by using multiple RateLimit actions. For example you can set an overall rate limit of 1000 messages per day, and also ensure that the URL is protected during peak hour by adding another RateLimit of 1 per minute.

SchemaValidation

Services Gatekeeper validates an incoming request or outgoing response that accesses a web service API, based on the schema provided by you for the API.

Provide values for the first XSD in the fields under the unit numbered 0. The first in the list is the main XSD/WADL/WSDL. The other entries are referenced from the first entry in the list.

1. For the Content parameter, enter the actual XML Schema XSD content. Paste in a Schema in the Value column.

2. For the Name parameter, enter the reference to the entry in Content. Use this name from another action or Groovy action to retrieve the schema you entered for Content.

To add more units, click the - sign next to Un.... and repeat.

Throttling

Change a partner group name, rate (requests/second), quota period (days), and quota (requests per quota period) specified in the message. The data you are changing comes from the appropriate SLA.

Provide values for the first partner group under the fields for the unit numbered 0:

1. For the Group Name parameter, enter the name of the partner group.

2. For the Quota parameter, enter the number of requests per quota period allowed.

3. For the Quota Period parameter, enter the number of days in the quota period allowed.

4. For the Rate parameter, enter the number limit for the number of requests per second allowed.

To add more throttle units, right-click the - sign next to Un.... and repeat.

Xml2Json

This action takes text formatted for the XML protocol from the body of the incoming request or response body, and translates it into JSON format in the body of the outgoing request or response. Table 5-3 lists the parameters for this action.

For example, this XML formatted text:

<SendSms myattribute="foo">
  <addresses>tel:123456</addresses>
  <senderName>senderName</senderName>
  <message>my message 2</message>
</SendSms>

Is translated into this JSON formatted text:

{
  "SendSms": { 
    "message":"my message 2",
    "senderName” : "senderName",
    "addresses” : "tel:123456",
    "@myattribute” : "foo”  }
}

See the "Json2Xml" action to translate JSON input into XML format.

XSLT

Use an Extensible Stylesheet Language script to change the XML-formatted body of the message.

Limitation

The implementation of the DAF Callout Callback assumes that DAF Action could contain only one asynchronous callout or send call. The presence of multiple asynchronous callouts or send() calls within the same DAF action could lead to unknown results.

Example of Callback

The following example demonstrates how to implement the callback class and also how to retrieve the response from a context attribute that was previously set in an asynchronous call.

package example;
 
public class MyCallback implements CalloutCallbackHandler {
  @Override
  public void process(HttpContext context) {
    System.out.println("---MyCallback process call");
    System.out.println("---MyCallback context.getAttribute(): " + context.getAttribute("TOKENADMIN_GET_RESPONSE"));
  }
}

The following example shows how it would be added in Groovy code using extra .withCallback(callback) syntax:

final String groovyCode1 =
  "try {\n"
  + "example.MyCallback callback = new example.MyCallback();\n"
  + "    String queryString = context.clientRequest.getQueryString();\n"
  + "    String apics_appkey = (String)context.clientRequest.queryParameters.apics_appkey\n" + "\n"
  + "System.out.println(\"Calling TokenAdmin with apics_appkey = \" + apics_appkey);\n"
  + "      // Get existing data from TokenAdmin\n"
  + "      context.setAttribute(\"CALLOUT_STATUS\", \"TOKENADMIN_GET\");\n"
  + "      ((oracle.sdp.daf.action.api.ExternalCalloutBuilder)(context.createCallout().withRequestUrl('"
  + "http://localhost:" + getPort() + ROOT_CONTEXT_PATH + "/callout/callouturl')"
  + ".withQueryParameter(\"apics_appkey\", apics_appkey).withRequestMethod(\"GET\").withHeader(\"Content-Type\","
  + "\"text/plain\").withCallback(callback))).build().send(\"TOKENADMIN_GET_RESPONSE\");\n"
  + "\n"
  + "}\n" + "catch (Exception e) {\n"
  + "    e.printStackTrace();\n"
  + "    throw e;\n" + "}";

Exception Handling

The following are exception handling considerations:

• The DAF Action interface provides the following entry point method

  void process(HttpContext context) throws ActionProcessingError;

  The method throws ActionProcessingError to indicate that the processing flow should be cancelled.

• CalloutCallback code, which is available to HTTP AsyncClient and implements FutureCallback<HttpResponse>), on request failure, at least for the case java.net.ConnectException:Connection refused, invokes public void failed(Exception e) method and through it a sendErrorResponseToApp(errorCode) call.

  The Javadoc output for sendErrorResponseToApp(errorCode)further illustrates:

  package oracle.sdp.daf;
  ...
  public final class CalloutCallback implements FutureCallback<HttpResponse> {
  ...
    /**
     * Send an error to the app - something went wrong. If this is within an
     * action, keep going, otherwise set the error flag on the utilcontext so   
     * that no actions will be processed.
     *
     * @param statusCode
     *          HTTP status code to return in the response
     */
    private void sendErrorResponseToApp(int statusCode) {
     ...
        internalHttpContext.getClientResponse().withStatus(statusCode);
        if (callback != null) {
          // this is the southbound call
          internalHttpContext.setInternalError(true);
        }
        internalSystemContext.getActionChainManager().continueActionChain(
            internalHttpContext.getSouthboundResponse(), internalHttpContext);
     ...
  

  In the case of a southbound call, the call above to internalHttpContext.setInternalError(true) is analyzed inside oracle.sdp.daf.ActionChainManager and it's doResponseChain(...) method, which are shown here:

  package oracle.sdp.daf;
  ...
  public final class ActionChainManager {
  ...
    private void doResponseChain(HttpResponse response,
        InternalHttpContext internalHttpContext) {
  ...
          if (!internalHttpContext.isInternalError()) {
  ...
  

• When doing an asynchronous send() and a long invocation on the south side leads to a timeout, an HTTP asynchronous client will potentially throw java.net.SocketTimeoutException. An example of a java.net.SocketTimeoutException stack trace for an HTTP asynchronous client is shown here:

  java.net.SocketTimeoutException
      at org.apache.http.nio.protocol.HttpAsyncRequestExecutor.timeout(HttpAsyncRequestExecutor.java:376)
      at org.apache.http.impl.nio.client.InternalIODispatch.onTimeout(InternalIODispatch.java:92)
      at org.apache.http.impl.nio.client.InternalIODispatch.onTimeout(InternalIODispatch.java:39)
      at org.apache.http.impl.nio.reactor.AbstractIODispatch.timeout(AbstractIODispatch.java:175)
      at org.apache.http.impl.nio.reactor.BaseIOReactor.sessionTimedOut(BaseIOReactor.java:263)
      at org.apache.http.impl.nio.reactor.AbstractIOReactor.timeoutCheck(AbstractIOReactor.java:492)
      at org.apache.http.impl.nio.reactor.BaseIOReactor.validate(BaseIOReactor.java:213)
      at org.apache.http.impl.nio.reactor.AbstractIOReactor.execute(AbstractIOReactor.java:280)
      at org.apache.http.impl.nio.reactor.BaseIOReactor.execute(BaseIOReactor.java:104)
      at org.apache.http.impl.nio.reactor.AbstractMultiworkerIOReactor$Worker.run(AbstractMultiworkerIOReactor.java:588)
      at java.lang.Thread.run(Thread.java:745)
  

  Some oracle.sdp.daf.CustomHttpRequestRetryHandler logic will attempt to retry:

  [INFO ] pRequestRetryHandler  The maximum number of retry times is 1, current execution count is 1
  [INFO ] pRequestRetryHandler  isRquestSent is false
  

  If it fails again, logic will route through the public void failed(Exception e) method mentioned above.

• As previously mentioned, the Callout callback handler interface has the same ability as DAF Action to throw ActionProcessingError and, in that case, action chain processing will be cancelled.

PATCH Method

You can use the PATCH method to update partial resources. For example, you might want to update only one field of a resource. Using PUT to update the complete representation of a resource could be cumbersome.

Supporting the PATCH method allows a PATCH request to pass through DAF. The Portal is updated with the new PATCH method in the resource table.

DAF treats the PATCH method the same as other HTTP methods like POST and PUT, meaning that the PATCH method is transparent to DAF. DAF treats a PATCH request as follows:

1. Transfers the request from the client to the backend service.

2. Transfers the response from the backend service to the client.

HEAD Method

The HTTP HEAD method corresponds to a GET request but without the response body. The HEAD method use cases are:

• Provides a faster way to check the headers

• Provides a LastModified / ContentLength check to decide whether to re-download a given resource

• Provides ability to log JavaScript-based content appearances

DAF treats the HEAD method the same as other HTTP methods like POST and PUT, meaning that the HEAD method is transparent to DAF. DAF treats a HEAD request as follows:

1. Transfers the request from the client to the backend service.

2. Transfers the response from the backend service to the client.

TRACE Method

The TRACE method, which is used for debugging, echoes input back to the user.

You must do the following to set up TRACE in your environment:

1. Enable TRACE support in WebLogic to avoid error 501. You can enable TRACE support in the following ways:

   1. To enable TRACE manually, in the WebLogic console, select your domain -> Configuration -> WebApplication, click the Http Trace Support Enabled box and select Save.

   2. To enable TRACE in Java, set the HttpTraceSupportEnabled flag in the WebAppContainerMBean.

   DAF treats the TRACE method the same as other HTTP methods like POST and PUT, meaning that the TRACE method is transparent to DAF. DAF treats a TRACE request as follows:

   1. Transfers the request from the client to the backend service.

   2. Transfers the response from the backend service to the client.

CONNECT Method

Use the CONNECT method to create an HTTP tunnel.

In this mechanism, the client sends an HTTP CONNECT request to the OCSG server to forward the TCP connection to the desired destination. The server proceeds to make the connection on behalf of the client. Once the server establishes the connection, an HTTP 200 response is sent to the client. The OCSG server continues to proxy the TCP stream by other HTTP methods to and from the client. Note that only the initial connection request is HTTP. After that, the server simply proxies the established TCP connection.

DAF treats the CONNECT method the same as other HTTP methods like POST and PUT, meaning that the CONNECT method is transparent to DAF. DAF treats a CONNECT request as follows:

1. Transfers the request from the client to the backend service.

2. Transfers the response from the backend service to the client.

OPTION Method

Use the OPTION method to list available interfaces.

You can make three types of OPTION requests:

1. Preflight request for CORS action. The CORS action responds directly. No change needed.

2. Request to list available interfaces for an API. You must add a ListResourcesAction object to the request to handle this.

3. Other types of requests are passed through DAF to the backend service.

Configure CORS parameters as shown in Table 5-4:

Printing and Changing Message Content

To print the contents of a message in the request action chain, you use the getClientRequest operation to the httpContext class, with the getBodyAsType operation to messageBuilder class. For example:

println httpContext.getClientRequest().getBodyAsType(String.class)

Assume that a RESTful request message contains:

{
  "test" : {
    "bob" : "123"
  }
}

You could use this Groovy script to return the value 123:

def body = context.clientRequest.getBodyAsType(org.codehaus.jackson.JsonNode.class);println body.get("test").get("bob").getTextValue()

To print the contents of a message in the response action chain, you use the getSouthBoundResponse operation to the httpContext class, with the getBodyAsType operation to the messageBuilder operation. For example:

println httpContext.getSouthboundResponse().getBodyAsType(String.class)

In a Groovy script you could use:

HttpResponse httpResponse = (HttpResponse) context.getAttribute("myattribute");

And then:

def responseBody = httpResponse.getBodyAsType(org.codehaus.jackson.JsonNode.class);

To change a request action chain message value, you use:

• The withBodyAsObject(Object) operation. Once changed, you then read only the changed value using the getBodyAsObject(Object) operation. Both are in the messageBuilder class.

• The withBodyAsStream(input stream) operation. Once changed, you then read only the changed value with the getBodyAsStream operation. Both are in the messageBuilder class.

See the "All Classes" section of the Actions Java API Reference for details on all of these operations and classes.

Using Actions to Manipulate HTTP Query Parameters

During processing by Services Gatekeeper, you can set encoded HTTP query parameters for a request message using any of these components. The components are processed in this order so the last in order makes the final changes:

1. The URL in the original request message.

2. The API Service URL that you specify when you create or update the API.

3. The API resource Path that you set in the Resources table when you create or update the API

4. An action. You can use either the default Groovy action, or a custom action that you create for this purpose. There are several purpose-built methods in the Actions Java API Reference for this purpose. See "Using a Groovy or Custom Action to Manipulate Query Parameters" for details on these methods. Also see ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide for information on how to create a custom action.

context.getSouthboundCallout().withQueryString("pathQueryStr=actionV3_1");

context.getSouthboundCallout().withoutQueryParameter("pathQueryStr3");
context.getSouthboundCallout().withQueryString("pathQueryStr3=actionV3_1");
context.getSouthboundCallout().withQueryParameter("reqQueryStr4=actionV4_2");
context.getSouthboundCallout().withoutQueryParameter("reqQueryStr4");

context.getSouthboundCallout().ignoreAllRequestQueryParametersb(true);

Using Actions to Translate Between REST and SOAP

This section explains how to map between SOAP and REST communication using the tools in an actions chain.

Original REST Input:
{
  "envelope": {
      "x":1,
      "y":2
  }
}
 
After Json2Xml action:
<envelope>
   <y>2</y>
   <x>1</x>
</envelope>

After XSLT action (final XML output):
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://www.parasoft.com/wsdl/calculator/">
<soapenv:Header/>
<soapenv:Body>
<cal:add>
<cal:x>1</cal:x>
<cal:y>2</cal:y>
</cal:add>
</soapenv:Body>
</soapenv:Envelope>

<?xml version="1.0" encoding="ISO-8859-1"?>
 
<xsl:stylesheet
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0">
 
  <xsl:output method="xml" indent="yes"/>
 
  <xsl:template match="/">
 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://www.parasoft.com/wsdl/calculator/">
      <soapenv:Header/>
      <soapenv:Body>
        <cal:add>
          <cal:x><xsl:value-of select="envelope/x"/></cal:x>
          <cal:y><xsl:value-of select="envelope/y"/></cal:y>
        </cal:add>
      </soapenv:Body>
    </soapenv:Envelope>
  </xsl:template>
 
</xsl:stylesheet>

Transfering Data from Request Chain to Response Chain

The following example shows you how you can transfer data from a request to a response, using a Request and a Response Groovy action (serializable is required on multi-tier):

Request:
Object obj = new Object();context.setAttribute("key", obj)

Response:
Object obj = (Object) context.sgetAttribute("key")

Converting JSON and XML

The Xml2Json action converts incoming XML body content to JSON body content. The following example illustrates:

XML Body Content In:
<SendSms myattribute="foo">
 <addresses>tel:123456</addresses>
 <senderName>senderName</senderName>
 <message>my message 2</message>
</SendSms>

JSON Body Content Out:
{
"SendSms": {
 "message":"my message 2",
 "senderName" : "senderName",
 "addresses" : "tel:123456",
 "@myattribute" : "foo"
 }
}

The Json2XML action transforms JSON to XML. The following example illustrates:

JSON Body Content In:
{
"SendSms": {
 "message":"my message 2",
 "senderName" : "senderName",
 "addresses" : "tel:123456",
 "@myattribute" : "foo"
 }
}

XML Body Content Out:
<SendSms myattribute="foo">
 <addresses>tel:123456</addresses>
 <senderName>senderName</senderName>
 <message>my message 2</message>
</SendSms>

Table 5-9 describes the three Json2XML optional configuration attributes:

Accessing the Customized Data Store

OCSG provides the ability to read and delete data from the customized data store, the database table PRM2_CUSTOMIZEDDATA shown in Figure 5-1:

Figure 5-1 PRM2_CUSTOMIZEDDATA Table

Currently, only a key that is a simple string and a value that is a string are supported.

The class oracle.ocsg.daf.store.CustomizedDataHelper enables you to easily perform create, retrieve, update, and delete (CRUD) operations on the data store. This class is contained in wlng.jar, which is under the directory {OCSG_INSTALL}/ocsg/server/lib/wlng.

This class includes the following Java APIs:

• public CustomizedDataHelper getInstance()

  Gets the singleton CustomizedDataHelper instance.

  Returns the singleton instance.

• public CustomizedData storeCustomizedData(CustomizedData data) throws StorageException

  Stores the CustomizedData instance.

  Parameters:

  • data The CustomizedData record to store.

  Returns:

  The previous value associated with theKey element. or null if there was no mapping for theKey.

  Throws:

  StorageException when storing the data fails

• public CustomizedData retrieveCustomizedData(final String key) throws StorageException

  Retrieves the CustomizedData specified by key.

  Parameters:

  • key A string to match theKey element of the CustomizedData record to be retrieved.

  Returns:

  The matched CustomizedData record, if found; otherwise, null.

  Throws:

  StorageException when retrieval fails

• public CustomizedData deleteCustomizedData(final String key) throws StorageException

  Deletes the CustomizedData record specified by key.

  Parameters:

  • key A string to match theKey element of the CustomizedData record to be deleted.

  Returns:

  The deleted CustomizedData instance, if found; otherwise null.

  Throws:

  StorageException - When failing to delete the record.

• public CustomizedData updateCustomizedData( String key, CustomizedData data) throws StorageException

  Updates the CustomizedData record specified by key.

  Parameters:

  • key A string to match theKey element of the CustomizedData record to be updated.

  • data The data to update.

  Returns:

  The old CustomizedData record.

  Throws:

  StorageException - When failing to update the record.

• public List<CustomizedData> retrieveCustomizedDataItems(String keySearchString, SearchStringOperation operation) throws StorageException

  Gets a list of stored CustomizedData items whose theKey element matches the search string.

  Parameters:

  keySearchString The search string to match theKey of CustomizedData records.

  SearchStringOperation One of the following enumerators that specify how the value of keySearchString should be evaluated:

  • SearchStringOperation.STARTSWITH: The key starts with the search string. Null or empty ("") matches all records.

  • SearchStringOperation.ENDSWITH: the key ends with the search string. Null or empty ("") matches all records.

  • SearchStringOperation.CONTAINS: the key contains the search string. Null or empty ("") matches all records.

  • SearchStringOperation.LIKES: the key likes the search string.

  Returns:

  A list of CustomizedData instances that match the search criteria. If no records match the search string, the list will be empty.

  Throws:

  StorageException - When an error occurs executing the query.

• public int deleteCustomizedDataItems(String keySearchString, SearchStringOperation operation) throws StorageException

  Deletes the list of stored CustomizedData items whose theKey element matches the search string.

  Parameters:

  keySearchString The search string to match theKey element of CustomizedData records.

  SearchStringOperation One of the following enumerators that specify how the value of keySearchString should be evaluated:

  • SearchStringOperation.STARTSWITH: The key starts with the search string. Null or empty ("") matches all records.

  • SearchStringOperation.ENDSWITH: the key ends with the search string. Null or empty ("") matches all records.

  • SearchStringOperation.CONTAINS: the key contains the search string. Null or empty ("") matches all records.

  • SearchStringOperation.LIKES: the key likes the search string.

  Returns:

  The list of CustomizedData instances that match the search criteria. If no records match the search string, the list will be empty.

  Throws:

  StorageException - When error occurs executing the query.

List<CustomizedData> dataList = CustomizedDataHelper.getInstance().retrieveCustomizedDatas("searchString", SearchStringOperation.STARTSWITH);

int deletedRowNum = CustomizedDataHelper.getInstance().deleteCustomizedDatas("String4", SearchStringOperation.ENDWITH);

List<CustomizedData> dataList = CustomizedDataHelper.getInstance().retrieveCustomizedDatas("String", SearchStringOperation.CONTAINS);

int deletedRowNum1 = CustomizedDataHelper.getInstance().deleteCustomizedDatas("searchString", SearchStringOperation.LIKES);

List<CustomizedData> allDataList1 = CustomizedDataHelper.getInstance().retrieveCustomizedDatas(null, SearchStringOperation.STARTSWITH);

int deletedRowNum1 = CustomizedDataHelper.getInstance().deleteCustomizedDatas("", SearchStringOperation.ENDSWITH);

Configuring Chunking for Back-end Services

You can control the chunked setting for southbound callout in Transfer-Encoding, regardless of the incoming request. You can configure the setting globally and also at the request or API level.

Per Request or Per API Configuration

You can also configure chunking on a per request or per API basis to obtain more granularity. You can set chunked either with a special header, ocsg-chunked-setting, in the incoming request or use a Groovy action to add a special header, also called ocsg-chunked-setting, for a specified API. In both cases, post-processing uses this header to override the global setting.

The order of precedence is the Groovy action, followed by the traffic request, and then the global MBean setting.

The ocsg-chunked-setting header takes the same three values as the SouthBoundChunkedSetting item in the DafGeneralInformation MBean: PassThrough, ForceChunk, and ForceNoChunk.

In Figure 5-2, the Groovy script uses the addHeader() method to add the header. You can also use the withHeader() method.

Figure 5-2 Groovy Script Adding Chunking Header

For the Groovy action, instead of using a String to set the special header, you can use the following predefined constant or enums in class oracle.sdp.daf.configurations.SouthBoundChunkedSetting:

• public static final String CHUNKED_HEADER = "ocsg-chunked-setting"

• enum

  • PassThrough

  • ForceChunk

  • ForceNoChunk

The following example illustrates a Groovy setting:

context.getSouthboundCallout().withHeader(oracle.sdp.daf.configurations.SouthBoundChunkedSetting.CHUNKED_HEADER, oracle.sdp.daf.configurations.SouthBoundChunkedSetting.ForceChunk.toString())