Oracle® Web Services Manager Extensibility Guide 10g (10.1.3.3.0) Part Number E10300-01 |
|
|
View PDF |
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:
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:
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:
Theexecute
method is the only required method for implementing a custom step.Define a step template and provide a unique ID, name, and configurable parameters for the step.
Deploy the 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.
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
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 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 theexecute
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.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()
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):
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"); ... }
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.
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 |
---|---|
|
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. |
|
Defines the package name of the step implementing class. This is a required attribute. |
|
Defines the time stamp of the creation of the step. This is a required attribute. |
|
Defines the step template version. This is an optional attribute. |
|
Provides a brief description of the step. This is an optional element. |
|
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. |
|
Specifies the list of faults for the step. This is an optional element. |
|
Specifies the fault to be generated. |
|
Defines the list of all the property sets for the step. |
|
Defines each and every property set for the step. |
|
Defines the properties within a property set for the step. |
|
The name of the property. This is a required attribute. |
|
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. |
|
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Ó. |
|
Specifies if the property is required or optional. Possible values are "true" or "false". This is an optional attribute. The default value is ÒfalseÓ. |
|
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Ó. |
|
Displays a text box where the property value can be entered. |
|
Displays a text box where the property value can be entered, but the value entered is not visible to the user in clear text. |
|
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. |
|
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. |
|
Displays a drop-down list. Requires specifying enumeration values. If one condition fails, a text box is displayed. |
|
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. |
|
This property is not visible to the user. |
|
Specifies a property value that cannot be changed by the user. |
|
Specifies a property value that cannot be changed by the user. This value is not visible to the user in clear text. |
|
Specifies the name of the property to be displayed to the user. |
|
Provides a brief description of the property defined by the start tag. You can provide a description for the property being defined. |
|
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. |
|
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. |
|
Defines the name of the SimpleType. This is a required attribute. |
|
Restrictions are used to define acceptable values for elements or attributes. |
|
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. |
|
Specifies the exact number of characters or list items allowed. Must be equal to or greater than zero. |
|
Specifies the minimum number of characters or list items allowed. Must be equal to or greater than zero. |
|
Specifies the maximum number of characters or list items allowed. Must be equal to or greater than zero. |
|
Defines a list of acceptable values pattern and the exact sequence of characters that are acceptable. |
|
Specifies the exact number of digits allowed. Must be greater than zero. |
|
Specifies the maximum number of decimal places allowed. Must be equal to or greater than zero. |
|
Specifies the lower bounds for numeric values (the value must be greater than or equal to this value). |
|
Specifies the upper bounds for numeric values (the value must be less than or equal to this value). |
|
Specifies the lower bounds for numeric values (the value must be greater than this value). |
|
Specifies the upper bounds for numeric values (the value must be less than this value). |
|
Specifies how white space (line feeds, tabs, and carriage returns) is handled. |
Complete the following tasks to deploy a custom step:
Add the custom step to the Oracle WSM Policy Manager.
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.
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.
Add the custom step to the policy pipeline.
Add a help page for the custom step.
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.
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).
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
Click Browse and select the newly created XML step template.
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.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
From Web Services Manager Control, click Policy Management, then click Manage Policies.
Web Services Manager Control displays the list of registered Oracle WSM components.
Click Policies for the component whose policy you want to modify.
Web Services Manager Control displays the policies for the component.
Click the Edit icon for the policy you want to edit.
The page displays the existing policy pipeline.
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.
Select the new step and click Ok.
Configure the step.
Click Next.
The step is added to the policy pipeline.
Click Save.
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:
Navigate to the OC4J_HOME/owsm/lib/app/ccore/help/steps
directory.
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.
Start the OC4J server.
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.
Log in to the Web Services Manager Control and verify that help for your custom step is available.