1 Developing and Deploying Custom Steps

This chapter provides an overview of how to create custom policy steps, and it describes how to create, develop, and deploy custom policy steps.

This chapter contains the following topics:

• Policy Step Creation Overview

• Developing a Custom Step

• Deploying a Custom Step

Policy Step Creation Overview

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

• The Oracle WSM SDK

• A sample step template for developing a custom step

• The Oracle WSM step template schema

Complete the following tasks to develop a custom step:

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

• 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.

  
  

• Deploy the custom step.

Ensure that the custom steps you develop are compliant with Web services standards.

Developing a Custom Step

A custom step extends the com.cfluent.policysteps.sdk.AbstractStep class and implements the execute method. The following section contains information about 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

  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 IResult States

The custom step generates the result object using the createResult method. The int argument for the createResult method provides the states of the result. These states indicate the following about 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.

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.

The AbstractStep interface provides the following default methods:

public final void setEnabled(boolean);public final boolean getEnabled();public final void setStepName(java.lang.String);public final java.lang.String getStepName();public final com.cfluent.policysteps.sdk.AgentContext getAgentContext();public final void setAgentContext(com.cfluent.policysteps.sdk.AgentContext);public void init() throws java.lang.IllegalStateException;protected void generateFault(com.cfluent.policysteps.sdk.Fault) throws com.cfluent.policysteps.sdk.Fault;protected com.cfluent.policysteps.sdk.IResult createResult(int);

Defining a Step Template

The Oracle WSM policy steps 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. See "Sample Step Template" , when creating your XML sample step template. See "Step Template Schema", for the step template schema.

The following table contains descriptions of a set of 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 will throw an exception.
csw:Description	Provides a brief description of the step.
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.
Csw:Property name=?...? type=?...?	Defines the properties available for the name and the data type of a step property. Data types can be the following: boolean, string, boolean, int, long, float, short, string[], boolean[], int[], long[], short[], string[]
Property/Csw:Description	Provides a brief description of the property defined by the tag above. A Step developer is expected to provide a relevant description of the property being defined.
Property/csw:Value/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 environmental property, defined by ${<property_key>}.

Deploying a Custom Step

Complete the following tasks to deploy a custom step:

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

• Add the jar file containing the implementation classes for the step to the /lib directory. See "To add a jar file" for more information about adding or copying the jar file.

  
  

  Note: When you copy a new jar file, or make changes to an existing jar file, you must restart the Oracle Application Server.

  
  

• Add the custom step to the service pipeline as needed.

To add a custom step

1. Log in to the Web Services Manager Control, and select the Policy Manager from the navigation bar.

   The Web Services Manager Control displays the list of currently defined components.

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

   The Step Management window 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 screen updates the list of currently available steps, including the newly added step.

   
   

   Note: Each custom step shows a delete button; however, default steps cannot be deleted.

   
   

To add a jar file

You need to copy the Java Archive (jar) containing the implementation classes for the custom step to the machine where the gateway or agent component is installed. Copy the jar file to the following location:

ORACLE_HOME/owsm/lib/custom

To add a step to a policy enforcement point

1. From Web Services Manager Control, select Policy Manager.

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

2. Select the component whose policy you want to modify, and click Policies.

   Web Services Manager Control displays the default policy for the component.

3. In the policy row where you want to add a step, click 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 Service 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.