This chapter explains how to create a custom action to use with your Oracle Communications Services Gatekeeper APIs.
Services Gatekeeper provides the default actions listed in "Actions Provided by Services Gatekeeper" in API Management Guide that you use to manipulate request and response messages for the APIs you host.
The Groovy action is specifically is available for you to add any level of sophistication required to API traffic. However manually adding a Groovy action means that you need to replicated it for each API. If you want to make custom action code available to more than one API, create a custom action for it. Once created and added to the externalactions library and you restart the network tier, the custom action is available for you to use with your APIs. You can use it with the Actions Java API or by using the API and Partner Management Portal user interface. The Portal is generated dynamically, so your custom actions appear automatically on the Actions tab of the API and Partner Management Portal.
You can use any methods in the Actions Java API Reference in the Java code you use to create a custom action.
Simply put, you create a custom action by creating and compiling the Java code, adding it to externalactions, and then restarting the Services Gatekeeper network tier. The custom action is then available for you to use alongside the default actions.
To create a custom action:
Add Gatekeeper_home/ocsg/modules/oracle.sdp.daf-6.0.0.0.jar to your CLASSPATH.
Create and compile the Java code that adds the functionality that your implementation requires into config.java and action.java files. See the "Example Black List Action" section for examples for these files.
Add the DafAction class to your action.java file. See "Defining DafAction Annotation in Your Action File" for details.
Add the class name of action to the oracle.sdp.daf.actions file in the Gatekeeper_home/ocsg/applications/oracle.sdp.daf.externalaction-6.0.0.0.jar. Add each classname to a separate line.
This example uses the Linux concatenate command to add the HeaderValidtionAction and BlackListAction new example custom actions:
$ cat oracle.sdp.daf.actions oracle.sdp.daf.action.HeaderValidationAction oracle.sdp.daf.action.BlackListAction
Also add your config and actions compiled class files to the Gatekeeper_home/ocsg/applications/oracle.sdp.daf.externalaction-6.0.0.0.jar file.
For example:
$ jar tvf oracle.sdp.daf.externalaction-6.0.0.0.jar
0 Mon Sep 28 17:04:54 PDT 2015 META-INF/
370 Mon Sep 28 17:04:52 PDT 2015 META-INF/MANIFEST.MF
83 Wed Sep 30 13:47:52 PDT 2015 oracle.sdp.daf.actions
2005 Wed Sep 30 13:47:54 PDT 2015 oracle/sdp/daf/action/BlackListAction.class
779 Wed Sep 30 13:47:54 PDT 2015 oracle/sdp/daf/action/BlackListActionConfig.class
1026 Wed Sep 30 13:47:54 PDT 2015 oracle/sdp/daf/action/HeaderValidationActionConfig.class
2167 Wed Sep 30 13:47:54 PDT 2015 oracle/sdp/daf/action/HeaderValidationAction.class
Note:
Modifying the MANIFEST.FM file after compiling will corrupt it.Copy the oracle.sdp.daf.externalaction-6.0.0.0.jar to all network tier servers in your implementation.
Stop all network tier servers.
For all network tiers servers, remove all directories under domain_home/servers/WLNG_NTX/stage/DafExternalActions.
Restart the NT servers.
Your new custom action is displayed and available for use in the API and Partner Management Portal, or by the Actions API Management REST-based API. See "Discovering Actions Chains Schemas" for information on how to obtain the action schemas.
You must add the oracle.sdp.daf.action.DafAction class to the Java code in your *Actions.java file. See "Example Header Validation Example" and "Example Black List Action" for examples. This example adds a new action called MyAction.
@DafAction(
name = "MyAction,
configBean = MyActionConfig.class,
description = "description.") public final class MyAction implements Action<MyActionConfig.class>{ ...
The DafAction uses these parameters to defines how the new action (MyAction) is presented and used in Services Gatekeeper:
name (String) - The name that identifies the action. Must be unique.
configBean (Class)- Defines the Java Bean class that holds the configuration for this class. The Action class must be included the class as a Generic in the Action interface that it implements, as well as have it as the first parameter in the init() method.
description (String) - And informal description of the action. Can be used by PRM API clients.
flowRestriction (FlowRestriction ENUM) - Defines where this Action can be used:
NONE - The default. Does not restrict the action, so it can be used in either the request or response flow.
REQUEST - Restricts the action to use on the request flow.
RESPONSE Restricts the action to use on the response flow.
Use the loadActionSchema method in the API Actions Management REST-based API documentation to return the schemas for all actions available to a Services Gatekeeper implementation. This allows you to discover action details, such as required fields, without using the API and Partner Management Portal.
This section explains the custom actions that illustrate the types of custom actions that you can create.
This example action allows you to add name/value pair test for a header/value as a requirement for manipulating traffic for an API.
The HeaderValidationAction.java file:
/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
package oracle.sdp.daf.action;
import oracle.sdp.daf.action.api.Action;
import oracle.sdp.daf.action.DafAction;
import oracle.sdp.daf.action.FlowRestriction;
import oracle.sdp.daf.action.api.ActionConfigurationException;
import oracle.sdp.daf.action.api.ActionProcessingError;
import oracle.sdp.daf.action.api.HttpContext;
import oracle.sdp.daf.config.ApiConfiguration;
/**
* My custom action.
*/
@DafAction(name = "HeaderValidation", configBean = HeaderValidationActionConfig.class)
public final class HeaderValidationAction implements Action<HeaderValidationActionConfig> {
private static final int HTTP_INTERNAL_ERROR = 500;
private HeaderValidationActionConfig configuration;
@Override
public void init(HeaderValidationActionConfig pConfiguration, ApiConfiguration apiConfiguration)
throws ActionConfigurationException {
configuration = pConfiguration;
}
@Override
public void process(HttpContext context) throws ActionProcessingError {
if (!configuration.getHeaderValue().equals(context.getClientRequest().getHeader(configuration.getHeaderKey()))) {
throw new ActionProcessingError(HTTP_INTERNAL_ERROR, "Required Header value not matching value");
}
}
}
The HeaderValidationActionConfig.java file:
/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
package oracle.sdp.daf.action;
import javax.xml.bind.annotation.XmlRootElement;
import java.io.Serializable;
/**
* The configuration file for the action.
*/
@XmlRootElement
public final class HeaderValidationActionConfig implements Serializable {
/**
* UUID.
*/
private static final long serialVersionUID = 1L;
private String headerKey;
private String headerValue;
public void setHeaderKey(String pHeaderKey) {
headerKey = pHeaderKey;
}
public String getHeaderKey() {
return headerKey;
}
public void setHeaderValue(String pHeaderValue) {
headerValue = pHeaderValue;
}
public String getHeaderValue() {
return headerValue;
}
}
This example action allows you to create a list of IP addresses that are prohibited from sending requests to an API.
The BlackListAction.java file:
/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
package oracle.sdp.daf.action;
import oracle.sdp.daf.action.api.Action;
import oracle.sdp.daf.action.DafAction;
import oracle.sdp.daf.action.FlowRestriction;
import oracle.sdp.daf.action.api.ActionConfigurationException;
import oracle.sdp.daf.action.api.ActionProcessingError;
import oracle.sdp.daf.action.api.HttpContext;
import oracle.sdp.daf.config.ApiConfiguration;
/**
* BlackList action.
*/
@DafAction(name = "BlackList", configBean = BlackListActionConfig.class)
public final class BlackListAction implements Action<BlackListActionConfig> {
private static final int HTTP_FORBIDDEN = 403;
private BlackListActionConfig configuration;
@Override
public void init(BlackListActionConfig pConfiguration, ApiConfiguration apiConfiguration)
throws ActionConfigurationException {
configuration = pConfiguration;
}
@Override
public void process(HttpContext context) throws ActionProcessingError {
if (configuration.getAddress().equals(context.getClientRequest().getRemoteHost())) {
throw new ActionProcessingError(HTTP_FORBIDDEN, "BlackListed!");
}
}
}
The BlacklistActionConfig.java file:
/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
package oracle.sdp.daf.action;
import javax.xml.bind.annotation.XmlRootElement;
import java.io.Serializable;
/**
* The configuration file for the action.
*/
@XmlRootElement
public final class BlackListActionConfig implements Serializable {
/**
* UUID.
*/
private static final long serialVersionUID = 1L;
private String address;
public void setAddress(String pAddress) {
address = pAddress;
}
public String getAddress() {
return address;
}
}