1 Developing and Deploying Custom Steps

Extensibility provides a developer with the ability to create custom steps. Custom steps are necessary when specific functionality is not provided with the standard policy steps that come with the product. For example, an application may require the use of a type of authentication that is not available in the Oracle WSM product. In this situation, a custom authentication step needs to be created. This manual provides information on how to develop, deploy, and test custom steps.

This chapter contains the following topics:

• Custom Step Creation Overview

• Developing a Custom Step

• Deploying a Custom Step

Custom Step Creation Overview

Oracle Web Services Manager (Oracle WSM) provides the following for creating a custom step:

• The Oracle WSM SDK

• A sample step template for developing a custom step

• The Oracle WSM step template schema

The Oracle WSM custom steps are supported by Java Development Kit (JDK) version 5.0 which comes bundled with the Oracle WSM product.

Complete the following tasks to develop a custom step:

1. Extend the AbstractStep class by writing the implementation of the init, execute, and destroy methods, and adding the set and get methods for the step properties.

   Note:

   The execute method is the only required method for implementing a custom step.

2. Define a step template and provide a unique ID, name, and configurable parameters for the step.

3. Deploy the custom step.

Developing a Custom Step

A custom step extends the com.cfluent.policysteps.sdk.AbstractStep class, implements the execute method, and may override the init and destroy methods. The following sections contain information about the Abstract step; the execute, init, and destroy methods; and the IResult states returned by the execute method.

About the execute Method

The basic characteristics and functionality of the execute method are as follows:

• Provides the program entry point for the custom step

• Can throw an exception of type com.cfluent.policysteps.sdk.Fault

  If a Fault is thrown by the execute method during exception processing, this Fault is cascaded back to the client application.

• Returns an object of type IResult

About Init and Destroy

To override the default init method, add initialization code specific to that custom step. You can also add code to the destroy method to ensure a clean end to the lifecycle of the custom step.

About IResult States

The custom step generates the result object using the createResult method. The int argument for the createResult method provides the state of the result. These are the possible states for the execute method:

• IResult.FAILED – The execute method failed.

• IResult.SUCCEEDED – The execute method succeeded.

• IResult.SUSPENDED – The execute method suspended execution.

Note:

Because the execute method is multithreaded (that is, it can be executed by multiple threads simultaneously), you should ensure that the implementation of the execute method is thread safe.

About the AbstractStep Class

The AbstractStep class provides the following default methods:

public final void setEnabled(boolean enabled)public final boolean getEnabled()public final void setStepName(String stepName)public final String getStepName()
public void setFaultCodes(String[] faultCodes)
public String[] getFaultCodes()
public final AgentContext getAgentContext()public final void setAgentContext(AgentContext context)
public abstract IResult execute(IMessageContext messageContext)
public void init()protected void generateFault(String message, String qualifier, String actor, Detail detail)
protected void generateFault (Fault fault)
protected IResult createResult (int status)
public void destroy()

Setting Outgoing HTTP Headers in a Custom Step

Oracle WSM allows you to configure a custom step to set outgoing custom HTTP headers in a gateway. You can perform this configuration by adding the following code to your custom step (Example 1-1):

Example 1-1 Setting Outgoing HTTP Headers in a Custom Step

HashMap httpHeaders = new HashMap();
httpHeaders.put("myheader1", "headervalue1");
httpHeaders.put("myheader2", "headervalue2");
messageContext.setProperty("customHttpHeaders", httpHeaders); 

Modifying the Content of SOAP Messages in a Custom Step

Oracle WSM allows you to add, delete, or modify the contents of SOAP messages in a custom step. You can perform this configuration by adding the following code to your custom step (Example 1-2):

Example 1-2 Modifying the Content of SOAP Messages in a Custom Step

public IResult execute(IMessageContext messageContext) throws Fault {
    MessageContext msgCtxt = (MessageContext) messageContext;
    SOAPEnvelope senv = msgCtxt.getRequest().getAxisMessage().getSOAPEnvelope();
    ((org.apache.axis.message.SOAPEnvelope)senv).setDirty(true);
    Name header = factory.createName("CustomHeader", "http://foo.com/custom/header");
    SOAPHeaderElement headerElement = senv.getHeader().addHeaderElement(header);
    headerElement.addTextNode("My custom header data");
    ...
}

Adding Logs to a Custom Step

To add logs to a custom step that are written to the log file of the gateway or the agent, add the following code to your custom step (Example 1-3):

Example 1-3 Adding Logs to a Custom Step

import com.cfluent.ccore.util.logging.*;
 
public class MyCustomStep {
  private static String CLASSNAME = MyCustomStep.class.getName();
  private static ILogger LOGGER = LogManager.getLogger(CLASSNAME);
 
  public IResult execute(IMessageContext messageContext) throws Fault {
    LOGGER.entering(CLASSNAME, "execute");
    ...
    LOGGER.log(Level.SEVERE, "This is a {0} log", "severe");
    if(LOGGER.isLoggable(Level.FINEST))
      LOGGER.log(Level.FINEST, "This is a {0} log", "finest");
    ...
  }
}

Log levels can be Level.SEVERE, Level.WARNING, Level.INFO, Level.FINE, Level.FINER, or Level.FINEST, which are listed in order from most severe to trace.

Defining a Custom Step Template

The Oracle WSM policy step framework requires that each Oracle WSM step refer to a step template. The step template defines the step ID and the step properties, and provides a brief description of each property.

To add a step template to the Oracle WSM framework, you must create a well-formed XML document. Refer to Example A-2 in Appendix A, "Custom Step Source Code and Step Template", when creating your XML sample step template. Refer to Appendix B, "Step Template Schema", for the step template schema.

Also refer to the POLICY_MANAGER_OBJECTS.xml and POLICY_MANAGER_OBJECTS_4.0.xml samples that come with the product. These sample files can be found in the following location: ORACLE_HOME/config/db/common/PolicyRespository

Table 1-1 contains descriptions of the tags for a typical step template:

Table 1-1 Step Template Tags

Tags	Description
csw:StepTemplate name=Step_Name id=XYZA123	Start tag of the XML document that defines the step name and a unique ID. The Oracle WSM system does not assign a unique ID—you must assign one. If the ID you assign is not unique to the system, Oracle WSM throws an exception.
csw:StepTemplate package=?	Defines the package name of the step implementing class. This is a required attribute.
csw:StepTemplate timestamp=?	Defines the time stamp of the creation of the step. This is a required attribute.
csw:StepTemplate version=?	Defines the step template version. This is an optional attribute.
StepTemplate /csw:Description	Provides a brief description of the step. This is an optional element.
StepTemplate/csw:Implementation	Identifies which class contains the implementation of the step. The framework loads the class defined by this step when the step is invoked, at runtime, by reflection. This is a required element.
StepTemplate/csw:Faults	Specifies the list of faults for the step. This is an optional element.
StepTemplate/Faults/csw:Fault/	Specifies the fault to be generated.
StepTemplate/csw:PropertyDefinitions	Defines the list of all the property sets for the step.
StepTemplate/PropertyDefinitions/csw:PropertyDefinitionSet	Defines each and every property set for the step.
StepTemplate /PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition	Defines the properties within a property set for the step.
StepTemplate /PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition name=?	The name of the property. This is a required attribute.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/ csw:PropertyDefinition type=?	Defines the data type of a step property. Data types can be any of the following: boolean, string, boolean, int, long, float, short, string[], boolean[], int[], long[], short[], string[]. This is a required attribute.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinitionisMultivalued=?	Specifies if the property can hold multiple values or not. Possible values are "true" or "false".This is an optional attribute. The default value is ÒfalseÓ.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinitionisRequired=?	Specifies if the property is required or optional. Possible values are "true" or "false". This is an optional attribute. The default value is ÒfalseÓ.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=?	Specifies how the property is to be displayed to the user in the graphical user interface (GUI). This is an optional field. The default value is ÒtextÓ.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓtextÓ	Displays a text box where the property value can be entered.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓpasswordÓ	Displays a text box where the property value can be entered, but the value entered is not visible to the user in clear text.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓcheckboxÓ	Requires providing enumeration values. Multivalue property should be set to true; if nothing is specified it is set, by default, to false. If one of these conditions is not met, a text box is displayed.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓradioÓ	Requires providing enumeration values. Multivalue property if specified should be set to false, if nothing specified it is set by default to false. If one of these conditions are not met a text box is displayed.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓdropdownÓ	Displays a drop-down list. Requires specifying enumeration values. If one condition fails, a text box is displayed.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓtextareaÓ	Displays a text area where the property value can be specified. You can also specify the number of rows that span this text area. For example: textarea(rows=5) creates a text area spanning 5 rows. If the rows parameter is not specified, a text area spanning 3 rows is created by default.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓhiddenÓ	This property is not visible to the user.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinition displayType=ÓimmutableÓ	Specifies a property value that cannot be changed by the user.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/csw:PropertyDefinitiondisplayType=ÓimmutablePasswordÓ	Specifies a property value that cannot be changed by the user. This value is not visible to the user in clear text.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/csw:DisplayName	Specifies the name of the property to be displayed to the user.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/csw:Description	Provides a brief description of the property defined by the start tag. You can provide a description for the property being defined.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/DefaultValue/csw:Absolute	Defines the default value(s) for the property being defined. The value may be Absolute or PropertyRef. A PropertyRef indicates to the framework to carry over an environment property, defined by ${<property_key>}. Currently only Absolute type is supported.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/csw:SimpleType	Defines a simple type that determines the constraints on and information about the values of attributes or elements with text-only content. This is an optional element. Only one such element can be specified.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/csw:SimpleType name=?	Defines the name of the SimpleType. This is a required attribute.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/csw:Restriction	Restrictions are used to define acceptable values for elements or attributes.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/csw:Restriction base=?	Defines the data type of the restriction values. This is a required attribute. Data types can be any of the following: boolean, string, boolean, int, long, float, short, string[], boolean[], int[], long[], short[], string[]. This is a required attribute.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:length	Specifies the exact number of characters or list items allowed. Must be equal to or greater than zero.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:minLength	Specifies the minimum number of characters or list items allowed. Must be equal to or greater than zero.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:maxLength	Specifies the maximum number of characters or list items allowed. Must be equal to or greater than zero.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:enumeration	Defines a list of acceptable values pattern and the exact sequence of characters that are acceptable.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:totalDigits	Specifies the exact number of digits allowed. Must be greater than zero.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:fractionDigits	Specifies the maximum number of decimal places allowed. Must be equal to or greater than zero.
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:minInclusive	Specifies the lower bounds for numeric values (the value must be greater than or equal to this value).
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:maxInclusive	Specifies the upper bounds for numeric values (the value must be less than or equal to this value).
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:minExclusive	Specifies the lower bounds for numeric values (the value must be greater than this value).
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:maxExclusive	Specifies the upper bounds for numeric values (the value must be less than this value).
StepTemplate/PropertyDefinitions/PropertyDefinitionSet/PropertyDefinition/SimpleType/Restriction/ csw:whiteSpace	Specifies how white space (line feeds, tabs, and carriage returns) is handled.

Deploying a Custom Step

Complete the following tasks to deploy a custom step:

1. Add the custom step to the Oracle WSM Policy Manager.

2. Add the minimum Java Archive (JAR) files required to compile the custom step. See "To add the JAR files" for more information about adding or copying the JAR files.

3. Add the JAR files containing the implementation classes for the step to the /lib/custom/ directory. See "To add the JAR files" for more information about adding or copying the JAR files.

   Note:

   When you copy a new JAR file, or make changes to an existing JAR file, you must restart Oracle Application Server.

4. Add the custom step to the policy pipeline.

5. Add a help page for the custom step.

To add a custom step

1. Log in to the Web Services Manager Control and select Policy Management, then select Manage Policies.

   The Web Services Manager Control displays the list of registered components.

2. In the row for the component where you want to add a custom step, click Steps.

   The Step Management page displays a list of existing steps (Figure 1-1).

   Figure 1-1 List of Policy Steps

   
   Description of "Figure 1-1 List of Policy Steps"
   
   

3. Click Add New Step.

   The Web Services Manager Control displays the Step Management/Add Step page (Figure 1-2).

   Figure 1-2 Step Management/ Add Step Page

   
   Description of "Figure 1-2 Step Management/ Add Step Page"
   
   

4. Click Browse and select the newly created XML step template.

5. Click Upload.

   The Step Management page updates the list of currently available steps, including the newly added step.

   Note:

   There is a delete button for each custom step; however, default steps cannot be deleted.

To add the JAR files

The following two Java Archive (JAR) files are required to compile the custom step java code. Copy the files to the following locations:

ORACLE_HOME/owsm/lib/extlib/saaj.jar

ORACLE_HOME/owsm/lib/coresv-4.0.jar

Additionally, you need to copy the Java Archive (JAR) containing the implementation classes for the custom step to the computer where the gateway or agent component is installed. Copy the JAR files to the following location:

ORACLE_HOME/owsm/lib/custom

To add a step to a policy pipeline

1. From Web Services Manager Control, click Policy Management, then click Manage Policies.

   Web Services Manager Control displays the list of registered Oracle WSM components.

2. Click Policies for the component whose policy you want to modify.

   Web Services Manager Control displays the policies for the component.

3. Click the Edit icon for the policy you want to edit.

   The page displays the existing policy pipeline.

4. In the section of the pipeline immediately above where you want to add a step, click Add Step Below.

   A list displays the steps available for the selected component, including your new custom step.

5. Select the new step and click Ok.

6. Configure the step.

7. Click Next.

   The step is added to the policy pipeline.

8. Click Save.

9. Commit the changes to the policy by clicking Commit Policy.

   Note:

   The new policies go into effect in 10 seconds, if you use the default polling frequency. The gateway and agent components automatically retrieve the updated policies from the Oracle WSM Policy Manager.

To add a help page for a custom step

If you have created a custom step and want to add a help page for it, perform the following steps:

1. Navigate to the OC4J_HOME/owsm/lib/app/ccore/help/steps directory.

2. Create the HTML help page for the custom page in this directory. Name the file with the step name, replacing any spaces with underscores.

   For example, if the step name is "My Custom Step" then name the help page "My_Custom_Step.html."

   You can optionally create help pages in other languages. Place these help pages in directories according to the predefined language abbreviations, such as es (Spanish), fr (French), de (German), it (Italian), and jp (Japanese). These abbreviations can be located in the language preference settings of a Web browser client.

3. Start the OC4J server.

4. Navigate to the OC4J_HOME/owsm/bin directory and perform the following command from the command prompt:

   wsmadmin deploy control

   This command repackages the Web Services Manager application with the newly created help page, and redeploys it to the OC4J container.

5. Log in to the Web Services Manager Control and verify that help for your custom step is available.