As the web service area gets more mature beyond basic soap messaging, different specifications have been adopted to address QoS (Quality of Service) aspects such as security and reliable messaging for web services. There have been a slew of new specifications with different processing models and corresponding schema definitions in order to indicate such elements in the wsdl and to specify the wire-format of the messages. In an attemp to provide a more unified approach for different QoS requirements of web services, WS-Policy specification was proposed.
As the spec (http://www.w3.org/Submission/WS-Policy/) defines it, WS-Policy a framework that governs how to define Policies out of Policy Assertions representing capabilities or requirements of any services, and how to associate them with entities called Policy Subjects such as web service endpoints or messages. The process of this association is named Policy Attachment.
WS-Policy provides a flexible and extensible grammar for expressing the capabilities, requirements, and general characteristics of entities in an XML Web services-based system. WS-Policy defines a framework and a model for the expression of these properties as policies.
Oracle web service supports WS-Policy specification during the development as well as at the time of deployment with numerous Policies available out of the box, each of which consists of Policy Assertions for different domains such as security or messaging or management. Those Policies can be attached to services or clients through annotations or configuration files as described below.
Prerequisites
What
you need to know
In order to be able to follow this how-to, you whould be familiar with the following :
Following notations are used
throughout the document.
%ORACLE_HOME%
- The directory where you installed the Oracle Containers for Java EE (11.1.1.0.0)
Technology Preview.
%JAVA_HOME%
- The directory where your JDK is installed
%HOWTO_HOME% - The directory where this how-to example is to be unzipped
Building
the Application
The sample application demonstrates how to use policies when developing web services. Let's say you need to capture request and response soap messages and log them, and to authenticate the sender of the request messages using WS-Security Username Token Profie (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf)). For that purpose, following two policies are attached during development time and get enforced during runtime in this example. Please, bear in mind that it is possible to attach more policies or detach already attached ones through management console after deploying the application to OC4J.
management/Log_Msg_Policy for both service and client : This policy has no effect on the soap messages.
security/Simple_Username_Token_Service_Policy for service, or security/Simple_Username_Token_Client_Policy for client : This policy requires soap messages to comply with WS-Security Username Token Profile.
Understanding annotations
Per JAX-WS specification, using JSR-181(Web Services Metadata for Java Platform) style annotations is the primary way to specify web service related properties in the service implementation and in the client code. This greatly simplifies web service development because you do not have to deal with complicated deployment descriptors any more although it is still necessary to use deplopyment descriptors for some use cases. Unfortunately, there is no standard annotations yet for QoS parameters, and hence each vendor defines proprietary annotations in such cases.
Attaching policies to the service implementation
Using Oracle policy annotations, WS-Policy can be set easily as follows. Please, note that WebService and WebMethod are standard annotations available in javax.ws package whereas ManagementPolicy and SecurityPolicy in oracle.webservices.annotations package are Oracle-specific. Policy reference names are from %ORACLE_HOME%/j2ee/home/gmds/owsm/policies. Here is a code snippet from %HOWTO_HOME%/svc/src/test/svc/TestService.java.
@WebService(name="Test",portName="TestPort",serviceName="TestService")
@ManagementPolicy("management/Log_Msg_Policy")
@SecurityPolicy("security/Simple_Username_Token_Service_Policy")
public class TestService {
@WebMethod
public String hello( String name ) {
return "Hello " + name + "!";
}
}
Attaching policies to the client code
Policies can be attached and enforced on the client side as well. You can choose to use policy annotation whenever possible even though relying upon a client deployment descriptor file is the only way to configure policies for the client under certain circumstances.
Using Configuration file
In case of Java SE clients, client side policy information is given through a client deployment descriptor. You can set the policy reference values(reference URI and category) in the configuration file for the client proxy. Here is a code snippet from %HOWTO_HOME%/tst/src/test/Tests.java.
TestService ts = new TestService();
Test port = ts.getTestPort();
((BindingProvider)port).getRequestContext().put(
ClientConstants.CLIENT_CONFIG,
fileToElement(new File("./cli/dat/oracle-webservice-client.xml")));
((BindingProvider)port).getRequestContext().put(
BindingProvider.USERNAME_PROPERTY,"oc4jadmin");
And below is the content of the oracle-webservice-client.xml referenced in the code. Policy reference information comes from the local policy repository directory whose path is set by the "file.module.home" system property passed via a command line when running the client.
For Java EE clients, client side policy can be set via annotations. WebServiceRef annotation from javax.xml.ws package is used to define a reference to a web service endpoint and an injection target for it. Web service reference is a type of Jave EE resource. Just like service implementation, ManagementPolicy and SecurityPolicy annotations are Oracle-specific. This can be used when your EJB needs to invoke a web service with necessary policies in place..
Please check to make sure that the following properties or environment variables are configured
correctly in the env.bat file located in the root of the sample's distribution (NOTE:
Some
of these properties will default to the values of corresponding
environment variables as noted below. If you have these
variables
setup in your environment you may not have to alter the values in the
file). If necessary, modify these variable to the proper
values
for you environment:
ORACLE_HOME
- the root
directory of oracle installation. Defaults to ORACLE_HOME environment
variable.
JAVA_HOME/JDK_HOME -
the
root directory of JDK installation. Defaults to JAVA_HOME environment
variable.
HOST/J2EE_HOST
- the hostname
of the platform on which the OC4J instance is running.
Defaults
to localhost.
HTTP_PORT
- the port
on which the OC4J HTTP listener is listening. Defaults to
8888.
RMI_PORT
-
the port on which the OC4J administration processor is
listening.
Defaults to 23791.
ADMIN_USER
- the
name of the OC4J administrator. Defaults to "oc4jadmin".
ADMIN_PWD
- the
password for the OC4J administrator. Defaults to "welcome".
In addition, please make sure that the ant command associated with the
OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).
After setting correct values for the properties , type
the following command from the %HOWTO_HOME% directory:
./env.bat
Starting
the OC4J Instance
Start an OC4J 11g Technology Preview instance as follows:
Stand Alone Installation: %ORACLE_HOME%/bin/oc4j
start Note that the oc4j command
expects the JAVA_HOME environment variable to point to a full JDK
1.5 installation.
Generating,
and Compiling the Application
In order to build and deploy the sample web service application, type
the following command from the %HOWTO_HOME%
directory:
ant deploy
This command would attempt to deploy the application if the build is successful. Please, check whether deployment successful by accessing the web service application web page at http://localhost:8888/test-app/test-service. You can click the Service Definition link on the page to access the wsdl file of the service.
Running
the Application
Once the web service application is available on the target OC4J container, it is time to generate the client artifacts. Run the following command:
ant cli
You can and complie the demo application and run the sample application(test.Tests class) via the following command:
ant test
For Java SE client, it is necessary to specify the path of directory where policy defintion files are available via "file.module.home" system property as below.
In order to see if the policy is indeed effective, you can test after giving a wrong username or password in test.Tests.java or commenting out the security policy reference in oracle-webservice-client.xml. As the client does not comply with the policy in place on the server side, the invocation will fail. In other words, the service endpoint will reject the request message as it does not contain WS-Security header with username and password required by the security policy on the service side or has invalid credentials. However, invocation will still be successful if you comment out the logging policy instead. The reason for that is logging policy attached to the client applies to the client only without affecting the request messages being composed.
Summary
This how-to describes and demonstrates,
what WS-Policy is and how to attach policies on the service and client sides
how to use policy annotations in the service implementation
how to attach policies in the client through a configuration file
Bookmark
