Table of Contents
This chapter describes the basic concepts and a simple scenario for configuring and managing the web service policy.
JEUS web services support the web service policy (WS-Policy). The web service policy is a standard specification that allows web service functions, such as WS-addressing, WS-RM, WSTX, and WS-security, to expose their policies.
The web service policy that JEUS web services support is divided into the server and client policies. A server can expose its policies through WSDL. When creating a web service client through the exposed policies, the client is automatically configured with the functions specified by the policies.
For more information about the web service policy setting, refer to "Chapter 14. Web Services Addressing", "Chapter 15. Reliable Messaging" , "Chapter 16. Web Service Transactions" , and "Chapter 17. Web Service Security".
This section introduces the general web service policy (WS-Policy).
The following are the features of the policy.
The web service policy specification is designed to be extensible and flexible in expression.
The web service policy is expressed through one or more policy assertion(s).
For more information about the schema of the standard web service policy, refer to http://schemas.xmlsoap.org/ws/2004/09/policy/ws-policy.xsd.
The following describes the web service policy framework.
A key component of the web service policy framework is the policy container expressed as the 'Policy' element. The element can be referred to or reused by others through the assigned ID. In addition, the element consists of an assertion or a group of assertions. The assertions are made up of policy operators.
The web service policy specification defines two operators and one attribute.
This operator is used to select one assertion or operator as a policy, when there are multiple assertions or operators in a child element.
The following is an example of using the operator.
<wsp:Policy>
<wsp:ExactlyOne>
<wsse:SecurityToken>
<wsse:Token
...
<wsse:
...
</wsp:Policy>
This operator is used to set a collection of all assertions or operators in the child element as a policy.
The following is an example of using the operator.
<wsp:Policy>
<wsp:All>
<wsse:SecurityToken>
<wsse:Token
...
</wsp:Policy>
This operator is used to selectively set some assertions or operators as a policy, when they are declared as the attributes of a child element.
The following is an example of using the operator.
<wsp:Policy>
<wsse:Integrity wsp:optional="true">
...
</wsp:Policy>
This section describes two scenarios for setting the web service policy, a scenario of creating a web service from WSDL and one for creating a web service from Java classes.
The following scenario shows how to create a web service configured with the web service policy setting by using a WSDL document.
Create a WSDL document.
Set the web service policy in the WSDL document.
Create Java bean objects by using the wsimport tool.
Create the service implementation classes.
Deploy the packaged service to JEUS server.
By using a WSDL document, create a web service configured with the web service policy setting. The following is the directory that is on the server where a web service is created from a WSDL document.
war_root
|- WEB-INF
|- classes
|- ... (SEI, JAX-WS artifacts, Handler, Validator)
|- wsdl
|- addnumbers.wsdl
To create a web service with the web service policy setting from Java classes, the wsit-endpoint.xml file must be generated by using the '-policy' option and wsgen tool, as shown in the following example.
$ wsgen fromjava.server.AddNumbersImpl -d web/WEB-INF -policy service-config.xml
The following is the service-config.xml file. This section will only cover the bolded parts of the following example.
[Example 13.1] << service-config.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web-services-config xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<policy>
<!-- To apply to the whole of the endpoint -->
<endpoint-policy-subject>
<addressing-policy>
<using-addressing>true</using-addressing>
</addressing-policy>
<!-- To apply to an operation(method) of the endpoint -->
<operation-policy-subject>
<!-- This setting applies to the below operation (method). -->
<operation-java-name>addNumbers</operation-java-name>
<!-- To apply to a request message from the client -->
<input-message-policy-subject>
......
</input-message-policy-subject>
<!-- To apply to a response message from the server -->
<output-message-policy-subject>
......
</output-message-policy-subject>
</operation-policy-subject>
</endpoint-policy-subject>
</policy>
</web-services-config>
The following scenario shows how to create a web service configured with the web service policy setting when the wsit-endpoint.xml file and Java classes for the web service are obtained by using wsgen with the '-policy' option.
Create the service implementation classes.
Create the service-config.xml file by using the 'jeus-webservices-config.xsd' schema.
Create the wsit-endpoint.xml file by using wsgen with the '-policy' option when creating a web service by using the created service implementation classes.
Save the wsit-endpoint.xml file in the 'WEB-INF' directory that will be packaged.
Deploy the packaged service to JEUS server.
By using Java classes, create a web service configured with the web service policy setting. The following is the directory that is on the server where a web service is created from Java classes.
war_root
|- WEB-INF
|- classes
|- ... (SEI, JAX-WS artifacts, Handler, Validator)
|- wsit-Endpoint.xml
In general, web service security scenario is used for the web service policy setting on clients. This is because a JEUS web service is exposed to the web service policy setting in WSDL of a remote web service at runtime, and automatically provides an appropriate environment for the policy. However, there may be some cases, such as in the web service security, where additional settings may be required.
The following is a scenario for creating a client when additional settings are required for the web service with the web service policy setting.
Create client Java bean objects through the wsimport tool.
Save a remote WSDL document in an accessible repository with the name 'wsit-client.xml'.
The web service policy setting in the remote WSDL can be deleted, since JEUS web service provides a client environment through the web service policy setting at runtime.
Set an additional web service policy for the client in 'wsit-client.xml'.
For JAR packaging, save 'wsit-client.xml' in the 'classes/META-INF' directory that will be packaged.
For WAR packaging, put 'wsit-client.xml' under the 'WEB-INF' directory that will be packaged.
Deploy the packaged service to JEUS server.
In general, a web service client executed on a container looks like the following example.
war_root
|- WEB-INF
|- classes
|- ... (client classes, JAX-WS artifacts, Handler, Validator)
|- META-INF
|- wsit-client.xml
|- index.jsp
A web service client executed on an EJB container or as an independent application looks like the following example.
jar_root
|- classes
|- ... (client classes, JAX-WS artifacts, Handler, Validator)
|- META-INF
|- wsit-client.xml