Chapter 3. Developing Jakarta XML Web Services Jakarta XML Web Services defines the mapping between WSDL and Java, as well as the classes to be used for accessing web services and publishing them. JBossWS implements Jakarta XML Web Services 2.3 , which users can reference for any vendor-agnostic web service usage need. 3.1. Using Jakarta XML Web Services Tools The following Jakarta XML Web Services command-line tools are included with the JBoss EAP distribution. These tools can be used in a variety of ways for server and client-side development. Table 3.1. Jakarta XML Web Services Command-Line Tools Command Description wsprovide Generates Jakarta XML Web Services portable artifacts, and provides the abstract contract. Used for bottom-up development. wsconsume Consumes the abstract contract (WSDL and Schema files), and produces artifacts for both a server and client. Used for top-down and client development. See Jakarta XML Web Services Tools for more details on the usage of these tools. 3.1.1. Server-side Development Strategies When developing a web service endpoint on the server side, you have the option of starting from Java code, known as bottom-up development , or from the WSDL that defines your service, known as top-down development . If this is a new service, meaning that there is no existing contract, then the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with a contract already defined, it is far simpler to use the top-down approach, since the tool can generate the annotated code for you. Bottom-up use cases: Exposing an already existing Jakarta Enterprise Beans 3 bean as a web service. Providing a new service, and you want the contract to be generated for you. Top-down use cases: Replacing the implementation of an existing web service, and you can not break compatibility with older clients. Exposing a service that conforms to a contract specified by a third party, for example, a vendor that calls you back using an already defined protocol. Creating a service that adheres to the XML Schema and WSDL you developed by hand up front. Bottom-Up Strategy Using wsprovide The bottom-up strategy involves developing the Java code for your service, and then annotating it using Jakarta XML Web Services annotations. These annotations can be used to customize the contract that is generated for your service. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required. This can be as simple as creating a single class: package echo; @javax.jws.WebService public class Echo { public String echo(String input) { return input; } } A deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called wrapper classes will be generated for you at deploy time. The primary purpose of the wsprovide tool is to generate portable Jakarta XML Web Services artifacts. Additionally, it can be used to provide the WSDL file for your service. This can be obtained by invoking wsprovide using the -w option: Inspecting the WSDL reveals a service named EchoService : <wsdl:service name="EchoService"> <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding"> <soap:address location="http://localhost:9090/EchoPort"/> </wsdl:port> </wsdl:service> As expected, this service defines an operation, echo : <wsdl:portType name="Echo"> <wsdl:operation name="echo"> <wsdl:input name="echo" message="tns:echo"> </wsdl:input> <wsdl:output name="echoResponse" message="tns:echoResponse"> </wsdl:output> </wsdl:operation> </wsdl:portType> When deploying you do not need to run this tool. You only need it for generating portable artifacts or the abstract contract for your service. A POJO endpoint for the deployment can be created in a simple web.xml file: <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <servlet> <servlet-name>Echo</servlet-name> <servlet-class>echo.Echo</servlet-class> </servlet> <servlet-mapping> <servlet-name>Echo</servlet-name> <url-pattern>/Echo</url-pattern> </servlet-mapping> </web-app> The web.xml and the single Java class can now be used to create a WAR: The WAR can then be deployed to JBoss EAP. This will internally invoke wsprovide , which will generate the WSDL. If the deployment was successful, and you are using the default settings, it should be available in the management console. Note For a portable Jakarta XML Web Services deployment, the wrapper classes generated earlier could be added to the deployment. Top-Down Strategy Using wsconsume The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The wsconsume tool is then used to consume this contract, and produce annotated Java classes, and optionally sources, that define it. Note wsconsume might have problems with symlinks on Unix systems. Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The -k option is passed to wsconsume to preserve the Java source files that are generated, instead of providing just Java classes: The following table shows the purpose of each generated file: Table 3.2. Generated Files File Purpose Echo.java Service Endpoint Interface EchoResponse.java Wrapper bean for response message EchoService.java Used only by Jakarta XML Web Services clients Echo_Type.java Wrapper bean for request message ObjectFactory.java Jakarta XML Binding XML Registry package-info.java Holder for Jakarta XML Binding package annotations Examining the service endpoint interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example, however, these evaluate to the same contract. @WebService(targetNamespace = "http://echo/", name = "Echo") @XmlSeeAlso({ObjectFactory.class}) public interface Echo { @WebMethod @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type") @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse") @WebResult(name = "return", targetNamespace = "") public java.lang.String echo( @WebParam(name = "arg0", targetNamespace = "") java.lang.String arg0 ); } The only missing piece, other than for packaging, is the implementation class, which can now be written using the above interface. package echo; @javax.jws.WebService(endpointInterface="echo.Echo") public class EchoImpl implements Echo { public String echo(String arg0) { return arg0; } } 3.1.2. Client-side Development Strategies Before going in to detail on the client side, it is important to understand the decoupling concept that is central to web services. Web services are not the best fit for internal RPC, even though they can be used in this way. There are much better technologies for this, such as CORBA and RMI. Web services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a web service interaction will be at any particular location, running on any particular operating system, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using web services. For the above reasons, the recommended methodology for developing a client is to follow the top-down approach, even if the client is running on the same server. Top-Down Strategy Using wsconsume This section repeats the process of the server-side top-down section, however, it uses a deployed WSDL. This is to retrieve the correct value for soap:address , shown below, which is computed at deploy time. This value can be edited manually in the WSDL if necessary, but you must take care to provide the correct path. Example: soap:address in a Deployed WSDL <wsdl:service name="EchoService"> <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding"> <soap:address location="http://localhost.localdomain:8080/echo/Echo"/> </wsdl:port> </wsdl:service> Use wsconsume to generate Java classes for the deployed WSDL. Notice how the EchoService.java class stores the location from which the WSDL was obtained. @WebServiceClient(name = "EchoService", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl", targetNamespace = "http://echo/") public class EchoService extends Service { public final static URL WSDL_LOCATION; public final static QName SERVICE = new QName("http://echo/", "EchoService"); public final static QName EchoPort = new QName("http://echo/", "EchoPort"); ... @WebEndpoint(name = "EchoPort") public Echo getEchoPort() { return super.getPort(EchoPort, Echo.class); } @WebEndpoint(name = "EchoPort") public Echo getEchoPort(WebServiceFeature... features) { return super.getPort(EchoPort, Echo.class, features); } } As you can see, this generated class extends the main client entry point in Jakarta XML Web Services, javax.xml.ws.Service . While you can use Service directly, this is far simpler since it provides the configuration information for you. Note the getEchoPort() method, which returns an instance of our service endpoint interface. Any web service operation can then be called by just invoking a method on the returned interface. Important Do not refer to a remote WSDL URL in a production application. This causes network I/O every time you instantiate the Service object. Instead, use the tool on a saved local copy, or use the URL version of the constructor to provide a new WSDL location. Write and compile the client: import echo.*; public class EchoClient { public static void main(String args[]) { if (args.length != 1) { System.err.println("usage: EchoClient <message>"); System.exit(1); } EchoService service = new EchoService(); Echo echo = service.getEchoPort(); System.out.println("Server said: " + echo.echo(args0)); } } You can change the endpoint address of your operation at runtime, by setting the ENDPOINT_ADDRESS_PROPERTY as shown below: EchoService service = new EchoService(); Echo echo = service.getEchoPort(); /* Set NEW Endpoint Location */ String endpointURL = "http://NEW_ENDPOINT_URL"; BindingProvider bp = (BindingProvider)echo; bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL); System.out.println("Server said: " + echo.echo(args0)); 3.2. Jakarta XML Web Services Web Service Endpoints 3.2.1. About Jakarta XML Web Services Web Service Endpoints A Jakarta XML Web Services web service endpoint is the server component of a web service. Clients and other web services communicate with it over the HTTP protocol using an XML language called Simple Object Access Protocol (SOAP). The endpoint itself is deployed into the JBoss EAP container. WSDL descriptors can be created in one of the following two ways: Writing WSDL descriptors manually. Using Jakarta XML Web Services annotations that create the WSDL descriptors automatically. This is the most common method for creating WSDL descriptors. An endpoint implementation bean is annotated with Jakarta XML Web Services annotations and deployed to the server. The server automatically generates and publishes the abstract contract in WSDL format for client consumption. All marshalling and unmarshalling is delegated to the Jakarta XML Binding service. The endpoint itself might be a Plain Old Java Object (POJO) or a Jakarta EE web application. You can also expose endpoints using a Jakarta Enterprise Beans 3 stateless session bean. It is packaged into a web archive (WAR) file. The specification for packaging the endpoint is defined in the Jakarta Web Services Metadata Specification 2.1 . Example: POJO Endpoint @WebService @SOAPBinding(style = SOAPBinding.Style.RPC) public class JSEBean { @WebMethod public String echo(String input) { ... } } Example: Web Services Endpoint <web-app ...> <servlet> <servlet-name>TestService</servlet-name> <servlet-class>org.jboss.quickstarts.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class> </servlet> <servlet-mapping> <servlet-name>TestService</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app> The following Jakarta Enterprise Beans 3 stateless session bean exposes the same method on the remote interface as well as an endpoint operation. @Stateless @Remote(EJB3RemoteInterface.class) @WebService @SOAPBinding(style = SOAPBinding.Style.RPC) public class EJB3Bean implements EJB3RemoteInterface { @WebMethod public String echo(String input) { ... } } Service Endpoint Interface Jakarta XML Web Services services typically implement a Java service endpoint interface (SEI), which might be mapped from a WSDL port type, either directly or using annotations. This SEI provides a high-level abstraction that hides the details between Java objects and their XML representations. Endpoint Provider Interface In some cases, Jakarta XML Web Services services need the ability to operate at the XML message level. The endpoint Provider interface provides this functionality to the web services that implement it. Consuming and Accessing the Endpoint After you deploy your web service, you can consume the WSDL to create the component stubs which will be the basis for your application. Your application can then access the endpoint to do its work. 3.2.2. Developing and Deploying Jakarta XML Web Services Web Service Endpoint A Jakarta XML Web Services service endpoint is a server-side component that responds to requests from Jakarta XML Web Services clients and publishes the WSDL definition for itself. See the following quickstarts that ship with JBoss EAP for working examples of how to develop Jakarta XML Web Services endpoint applications. jaxws-addressing jaxws-ejb jaxws-pojo jaxws-retail wsat-simple wsba-coordinator-completion-simple wsba-participant-completion-simple Development Requirements A web service must fulfill the requirements of the Jakarta XML Web Services API and Jakarta Web Services Metadata Specification 2.1 specification . It contains a javax.jws.WebService annotation. All method parameters and return types are compatible with Jakarta XML Binding 2.3 specification . The following is an example of a web service implementation that meets these requirements. Example: Web Service Implementation package org.jboss.quickstarts.ws.jaxws.samples.retail.profile; import javax.ejb.Stateless; import javax.jws.WebService; import javax.jws.WebMethod; import javax.jws.soap.SOAPBinding; @Stateless @WebService( name = "ProfileMgmt", targetNamespace = "http://org.jboss.ws/samples/retail/profile", serviceName = "ProfileMgmtService") @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) public class ProfileMgmtBean { @WebMethod public DiscountResponse getCustomerDiscount(DiscountRequest request) { DiscountResponse dResponse = new DiscountResponse(); dResponse.setCustomer(request.getCustomer()); dResponse.setDiscount(10.00); return dResponse; } } The following is an example of the DiscountRequest class that is used by the ProfileMgmtBean bean in the example. The annotations are included for verbosity. Typically, the Jakarta XML Binding defaults are reasonable and do not need to be specified. Example: DiscountRequest Class package org.jboss.test.ws.jaxws.samples.retail.profile; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlType; import org.jboss.test.ws.jaxws.samples.retail.Customer; @XmlAccessorType(XmlAccessType.FIELD) @XmlType( name = "discountRequest", namespace="http://org.jboss.ws/samples/retail/profile", propOrder = { "customer" } ) public class DiscountRequest { protected Customer customer; public DiscountRequest() { } public DiscountRequest(Customer customer) { this.customer = customer; } public Customer getCustomer() { return customer; } public void setCustomer(Customer value) { this.customer = value; } } Packaging Your Deployment The implementation class is wrapped in a JAR deployment. Any metadata required for deployment is taken from the annotations on the implementation class and the service endpoint interface. You can deploy the JAR using the management CLI or the management console, and the HTTP endpoint is created automatically. The following listing shows an example of the structure for a JAR deployment of a Jakarta Enterprise Beans web service. 3.3. Jakarta XML Web Services Web Service Clients 3.3.1. Consume and Access a Jakarta XML Web Services Web Service After creating a web service endpoint, either manually or using Jakarta XML Web Services annotations, you can access its WSDL. This WSDL can be used to create the basic client application that will communicate with the web service. The process of generating Java code from the published WSDL is called consuming the web service. This happens in the following phases: Create the client artifacts . Construct a service stub . Create the Client Artifacts Before you can create client artifacts, you need to create your WSDL contract. The following WSDL contract is used for the examples presented in the rest of this section. The examples below rely on having this WSDL contract in the ProfileMgmtService.wsdl file. <definitions name='ProfileMgmtService' targetNamespace='http://org.jboss.ws/samples/retail/profile' xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://org.jboss.ws/samples/retail' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://org.jboss.ws/samples/retail/profile' xmlns:xsd='http://www.w3.org/2001/XMLSchema'> <types> <xs:schema targetNamespace='http://org.jboss.ws/samples/retail' version='1.0' xmlns:xs='http://www.w3.org/2001/XMLSchema'> <xs:complexType name='customer'> <xs:sequence> <xs:element minOccurs='0' name='creditCardDetails' type='xs:string'/> <xs:element minOccurs='0' name='firstName' type='xs:string'/> <xs:element minOccurs='0' name='lastName' type='xs:string'/> </xs:sequence> </xs:complexType> </xs:schema> <xs:schema targetNamespace='http://org.jboss.ws/samples/retail/profile' version='1.0' xmlns:ns1='http://org.jboss.ws/samples/retail' xmlns:tns='http://org.jboss.ws/samples/retail/profile' xmlns:xs='http://www.w3.org/2001/XMLSchema'> <xs:import namespace='http://org.jboss.ws/samples/retail'/> <xs:element name='getCustomerDiscount' nillable='true' type='tns:discountRequest'/> <xs:element name='getCustomerDiscountResponse' nillable='true' type='tns:discountResponse'/> <xs:complexType name='discountRequest'> <xs:sequence> <xs:element minOccurs='0' name='customer' type='ns1:customer'/> </xs:sequence> </xs:complexType> <xs:complexType name='discountResponse'> <xs:sequence> <xs:element minOccurs='0' name='customer' type='ns1:customer'/> <xs:element name='discount' type='xs:double'/> </xs:sequence> </xs:complexType> </xs:schema> </types> <message name='ProfileMgmt_getCustomerDiscount'> <part element='tns:getCustomerDiscount' name='getCustomerDiscount'/> </message> <message name='ProfileMgmt_getCustomerDiscountResponse'> <part element='tns:getCustomerDiscountResponse' name='getCustomerDiscountResponse'/> </message> <portType name='ProfileMgmt'> <operation name='getCustomerDiscount' parameterOrder='getCustomerDiscount'> <input message='tns:ProfileMgmt_getCustomerDiscount'/> <output message='tns:ProfileMgmt_getCustomerDiscountResponse'/> </operation> </portType> <binding name='ProfileMgmtBinding' type='tns:ProfileMgmt'> <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/> <operation name='getCustomerDiscount'> <soap:operation soapAction=''/> <input> <soap:body use='literal'/> </input> <output> <soap:body use='literal'/> </output> </operation> </binding> <service name='ProfileMgmtService'> <port binding='tns:ProfileMgmtBinding' name='ProfileMgmtPort'> <!-- service address will be rewritten to actual one when WSDL is requested from running server --> <soap:address location='http://SERVER:PORT/jaxws-retail/ProfileMgmtBean'/> </port> </service> </definitions> Note If you use Jakarta XML Web Services annotations to create your web service endpoint, the WSDL contract is generated automatically, and you only need its URL. You can find this URL by navigating to Runtime , selecting the applicable server, selecting Webservices , then choosing the endpoint. The wsconsume.sh or wsconsume.bat tool is used to consume the abstract contract (WSDL) and produce annotated Java classes and optional sources that define it. The tool is located in the EAP_HOME /bin/ directory. The following command generates the source .java files listed in the output, from the ProfileMgmtService.wsdl file. The sources use the directory structure of the package, which is specified with the -p switch. Both .java source files and compiled .class files are generated into the output/ directory within the directory where you run the command. Table 3.3. Descriptions of Artifacts Created by wsconsume.sh File Description ProfileMgmt.java Service endpoint interface. Customer.java Custom data type. Discount.java Custom data types. ObjectFactory.java Jakarta XML Binding XML registry. package-info.java Jakarta XML Binding package annotations. ProfileMgmtService.java Service factory. The wsconsume command generates all custom data types (Jakarta XML Binding annotated classes), the service endpoint interface, and a service factory class. These artifacts are used to build web service client implementations. Construct a Service Stub Web service clients use service stubs to abstract the details of a remote web service invocation. To a client application, a web service invocation looks like an invocation of any other business component. In this case the service endpoint interface acts as the business interface, and a service factory class is not used to construct it as a service stub. The following example first creates a service factory using the WSDL location and the service name. , it uses the service endpoint interface created by wsconsume to build the service stub. Finally, the stub can be used just as any other business interface would be. You can find the WSDL URL for your endpoint in the JBoss EAP management console. You can find this URL by navigating to Runtime , selecting the applicable server, selecting Webservices , then choosing the endpoint. import javax.xml.ws.Service; [...] Service service = Service.create( new URL("http://example.org/service?wsdl"), new QName("MyService") ); ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); // Use the service stub in your application 3.3.2. Develop a Jakarta XML Web Services Client Application The client communicates with, and requests work from, the Jakarta XML Web Services endpoint, which is deployed in the Java Enterprise Edition 7 container. For detailed information about the classes, methods, and other implementation details mentioned below, see the relevant sections of the Javadocs bundle included with JBoss EAP. Overview A Service is an abstraction which represents a WSDL service. A WSDL service is a collection of related ports, each of which includes a port type bound to a particular protocol and a particular endpoint address. Usually, the Service is generated when the rest of the component stubs are generated from an existing WSDL contract. The WSDL contract is available via the WSDL URL of the deployed endpoint, or can be created from the endpoint source using the wsprovide tool in the EAP_HOME /bin/ directory. This type of usage is referred to as the static use case. In this case, you create instances of the Service class which is created as one of the component stubs. You can also create the service manually, using the Service.create method. This is referred to as the dynamic use case. Usage Static Use Case The static use case for a Jakarta XML Web Services client assumes that you already have a WSDL contract. This might be generated by an external tool or generated by using the correct Jakarta XML Web Services annotations when you create your Jakarta XML Web Services endpoint. To generate your component stubs, you use the wsconsume tool included in EAP_HOME /bin . The tool takes the WSDL URL or file as a parameter, and generates multiple files, structured in a directory tree. The source and class files representing your Service are named _Service.java and _Service.class , respectively. The generated implementation class has two public constructors, one with no arguments and one with two arguments. The two arguments represent the WSDL location (a java.net.URL ) and the service name (a javax.xml.namespace.QName ) respectively. The no-argument constructor is the one used most often. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the @WebServiceClient annotation that decorates the generated class. @WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl") public class StockQuoteService extends javax.xml.ws.Service { public StockQuoteService() { super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService")); } public StockQuoteService(String wsdlLocation, QName serviceName) { super(wsdlLocation, serviceName); } ... } For details about how to obtain a port from the service and how to invoke an operation on the port, see Dynamic Proxy . For details about how to work with the XML payload directly or with the XML representation of the entire SOAP message, see Dispatch . Dynamic Use Case In the dynamic case, no stubs are generated automatically. Instead, a web service client uses the Service.create method to create Service instances. The following code fragment illustrates this process. URL wsdlLocation = new URL("http://example.org/my.wsdl"); QName serviceName = new QName("http://example.org/sample", "MyService"); Service service = Service.create(wsdlLocation, serviceName); Handler Resolver Jakarta XML Web Services provides a flexible plug-in framework for message processing modules, known as handlers. These handlers extend the capabilities of a Jakarta XML Web Services runtime system. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver and setHandlerResolver methods that can configure a set of handlers on a per-service, per-port or per-protocol binding basis. When a Service instance creates a proxy or a Dispatch instance, the handler resolver currently registered with the service creates the required handler chain. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies or Dispatch instances. Executor Service instances can be configured with a java.util.concurrent.Executor . The Executor invokes any asynchronous callbacks requested by the application. The setExecutor and getExecutor methods of Service can modify and retrieve the Executor configured for a service. Dynamic Proxy A dynamic proxy is an instance of a client proxy using one of the getPort methods provided in the Service . The portName specifies the name of the WSDL port the service uses. The serviceEndpointInterface specifies the service endpoint interface supported by the created dynamic proxy instance. public <T> T getPort(QName portName, Class<T> serviceEndpointInterface) public <T> T getPort(Class<T> serviceEndpointInterface) The Service Endpoint Interface is usually generated using the wsconsume tool, which parses the WSDL and creates Java classes from it. A typed method, which returns a port, is also provided. These methods also return dynamic proxies that implement the SEI. See the following example. @WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref", wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl") public class TestEndpointService extends Service { ... public TestEndpointService(URL wsdlLocation, QName serviceName) { super(wsdlLocation, serviceName); } @WebEndpoint(name = "TestEndpointPort") public TestEndpoint getTestEndpointPort() { return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class); } } @WebServiceRef The @WebServiceRef annotation declares a reference to a web service. It follows the resource pattern shown by the javax.annotation.Resource annotation defined in JSR 250 . The Jakarta EE equivalent for these annotations is in the Jakarta Annotations 1.3 specification . You can use it to define a reference whose type is a generated Service class. In this case, the type and value element each refer to the generated Service class type. Moreover, if the reference type can be inferred by the field or method declaration the annotation is applied to, the type and value elements might, but are not required to, have the default value of Object.class . If the type cannot be inferred, then at least the type element must be present with a non-default value. You can use it to define a reference whose type is an SEI. In this case, the type element might (but is not required to) be present with its default value if the type of the reference can be inferred from the annotated field or method declaration. However, the value element must always be present and refer to a generated service class type, which is a subtype of javax.xml.ws.Service . The wsdlLocation element, if present, overrides the WSDL location information specified in the @WebService annotation of the referenced generated service class. public class EJB3Client implements EJB3Remote { @WebServiceRef public TestEndpointService service4; @WebServiceRef public TestEndpoint port3; } Dispatch XML web services use XML messages for communication between the endpoint, which is deployed in the Jakarta EE container, and any clients. The XML messages use an XML language called Simple Object Access Protocol (SOAP). The Jakarta XML Web Services API provides the mechanisms for the endpoint and clients to each be able to send and receive SOAP messages. Marshalling is the process of converting a Java Object into a SOAP XML message. Unmarshalling is the process of converting the SOAP XML message back into a Java Object. In some cases, you need access to the raw SOAP messages themselves, rather than the result of the conversion. The Dispatch class provides this functionality. Dispatch operates in one of two usage modes, which are identified by one of the following constants. javax.xml.ws.Service.Mode.MESSAGE - This mode directs client applications to work directly with protocol-specific message structures. When used with a SOAP protocol binding, a client application works directly with a SOAP message. javax.xml.ws.Service.Mode.PAYLOAD - This mode causes the client to work with the payload itself. For instance, if it is used with a SOAP protocol binding, a client application would work with the contents of the SOAP body rather than the entire SOAP message. Dispatch is a low-level API which requires clients to structure messages or payloads as XML, with strict adherence to the standards of the individual protocol and a detailed knowledge of message or payload structure. Dispatch is a generic class which supports input and output of messages or message payloads of any type. Service service = Service.create(wsdlURL, serviceName); Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD); String payload = "<ns1:ping xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>"; dispatch.invokeOneWay(new StreamSource(new StringReader(payload))); payload = "<ns1:feedback xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>"; Source retObj = (Source)dispatch.invoke(new StreamSource(new StringReader(payload))); Asynchronous Invocations The BindingProvider interface represents a component that provides a protocol binding which clients can use. It is implemented by proxies and is extended by the Dispatch interface. BindingProvider instances might provide asynchronous operation capabilities. Asynchronous operation invocations are decoupled from the BindingProvider instance at invocation time. The response context is not updated when the operation completes. Instead, a separate response context is made available using the Response interface. public void testInvokeAsync() throws Exception { URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl"); QName serviceName = new QName(targetNS, "TestEndpointService"); Service service = Service.create(wsdlURL, serviceName); TestEndpoint port = service.getPort(TestEndpoint.class); Response response = port.echoAsync("Async"); // access future String retStr = (String) response.get(); assertEquals("Async", retStr); } @Oneway Invocations The @Oneway annotation indicates that the given web method takes an input message but returns no output message. Usually, a @Oneway method returns the thread of control to the calling application before the business method is executed. @WebService (name="PingEndpoint") @SOAPBinding(style = SOAPBinding.Style.RPC) public class PingEndpointImpl { private static String feedback; @WebMethod @Oneway public void ping() { log.info("ping"); feedback = "ok"; } @WebMethod public String feedback() { log.info("feedback"); return feedback; } } Timeout Configuration Two different properties control the timeout behavior of the HTTP connection and the timeout of a client which is waiting to receive a message. The first is javax.xml.ws.client.connectionTimeout and the second is javax.xml.ws.client.receiveTimeout . Each is expressed in milliseconds, and the correct syntax is shown below. public void testConfigureTimeout() throws Exception { //Set timeout until a connection is established ((BindingProvider)port).getRequestContext().put("javax.xml.ws.client.connectionTimeout", "6000"); //Set timeout until the response is received ((BindingProvider) port).getRequestContext().put("javax.xml.ws.client.receiveTimeout", "1000"); port.echo("testTimeout"); } 3.4. Configuring the Web Services Subsystem JBossWS components handle the processing of web service endpoints and are provided to JBoss EAP through the webservices subsystem. The subsystem supports the configuration of published endpoint addresses and endpoint handler chains. A default webservices subsystem is provided in the server's domain and standalone configuration files. It contains several predefined endpoint and client configurations. <subsystem xmlns="urn:jboss:domain:webservices:2.0"> <wsdl-host>USD{jboss.bind.address:127.0.0.1}</wsdl-host> <endpoint-config name="Standard-Endpoint-Config"/> <endpoint-config name="Recording-Endpoint-Config"> <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"> <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/> </pre-handler-chain> </endpoint-config> <client-config name="Standard-Client-Config"/> </subsystem> 3.4.1. Endpoint Configurations JBossWS enables extra setup configuration data to be predefined and associated with an endpoint implementation. Predefined endpoint configurations can be used for Jakarta XML Web Services client and Jakarta XML Web Services endpoint setup. Endpoint configurations can include Jakarta XML Web Services handlers and key/value properties declarations. This feature provides a convenient way to add handlers to web service endpoints and to set key/value properties that control JBossWS and Apache CXF internals. The webservices subsystem allows you to define named sets of endpoint configuration data. Each endpoint configuration must have a unique name within the subsystem. The org.jboss.ws.api.annotation.EndpointConfig annotation can then be used to assign an endpoint configuration to a Jakarta XML Web Services implementation in a deployed application. See Assigning a Configuration for more information on assigning endpoint configurations. There are two predefined endpoint configurations in the default JBoss EAP configuration: Standard-Endpoint-Config is the endpoint configuration used for any endpoint that does not have an explicitly-assigned endpoint configuration. Recording-Endpoint-Config is an example of custom endpoint configuration that includes a recording handler. Add an Endpoint Configuration You can add a new endpoint configuration using the management CLI. Configure an Endpoint Configuration You can add key/value property declarations for the endpoint configuration using the management CLI. You can also configure handler chains and handlers for these endpoint configurations. Remove an Endpoint Configuration You can remove a endpoint configuration using the management CLI. 3.4.2. Handler Chains Each endpoint configuration can be associated with PRE or POST handler chains. Each handler chain may include Jakarta XML Web Services-compliant handlers to perform additional processing on messages. For outbound messages, PRE handler chain handlers are executed before any handler attached to the endpoints using standard Jakarta XML Web Services means, such as the @HandlerChain annotation. POST handler chain handlers are executed after usual endpoint handlers. For inbound messages, the opposite applies. Server Outbound Messages Server Inbound Messages Add a Handler Chain You can add a POST handler chain to an endpoint configuration using the following management CLI command. You can add a PRE handler chain to an endpoint configuration using the following management CLI command. Configure a Handler Chain Use the protocol-bindings attribute to set which protocols trigger the handler chain to start. See the handlers section for information on configuring handlers for a handler chain. Remove a Handler Chain You can remove a handler chain using the management CLI. 3.4.3. Handlers A Jakarta XML Web Services handler is added to a handler chain and specifies the fully-qualified name of the handler class. When the endpoint is deployed, an instance of that class is created for each referencing deployment. Either the deployment class loader or the class loader for the org.jboss.as.webservices.server.integration module must be able to load the handler class. See the Handler Javadocs for a listing of the available handlers. Add a Handler You can add a handler to a handler chain using the following management CLI command. You must provide the class name of the handler. Configure a Handler You can update the class for a handler using the management CLI. Remove a Handler You can remove a handler using the management CLI. 3.4.4. Published Endpoint Addresses The rewriting of the <soap:address> element of endpoints published in WSDL contracts is supported. This feature is useful for controlling the server address that is advertised to clients for each endpoint. The following table lists the attributes that can be configured for this feature. Name Description modify-wsdl-address This boolean enables and disables the address rewrite functionality. When modify-wsdl-address is set to true and the content of <soap:address> is a valid URL, JBossWS rewrites the URL using the values of wsdl-host and wsdl-port or wsdl-secure-port . When modify-wsdl-address is set to false and the content of <soap:address> is a valid URL, JBossWS does not rewrite the URL. The <soap:address> URL is used. When the content of <soap:address> is not a valid URL, JBossWS rewrites it no matter what the setting of modify-wsdl-address . If modify-wsdl-address is set to true and wsdl-host is not defined or explicitly set to jbossws.undefined.host , the content of <soap:address> URL is used. JBossWS uses the requester's host when rewriting the <soap:address> . When modify-wsdl-address is not defined JBossWS uses a default value of true . wsdl-host The host name or IP address to be used for rewriting <soap:address> . If wsdl-host is set to jbossws.undefined.host , JBossWS uses the requester's host when rewriting the <soap:address> . When wsdl-host is not defined JBossWS uses a default value of jbossws.undefined.host . wsdl-path-rewrite-rule This string defines a SED substitution command, for example s/regexp/replacement/g , that JBossWS executes against the path component of each <soap:address> URL published from the server. When wsdl-path-rewrite-rule is not defined, JBossWS retains the original path component of each <soap:address> URL. When modify-wsdl-address is set to false this element is ignored. wsdl-port Set this property to explicitly define the HTTP port that will be used for rewriting the SOAP address. Otherwise the HTTP port will be identified by querying the list of installed HTTP connectors. wsdl-secure-port Set this property to explicitly define the HTTPS port that will be used for rewriting the SOAP address. Otherwise the HTTPS port will be identified by querying the list of installed HTTPS connectors. wsdl-uri-scheme This property explicitly sets the URI scheme to use for rewriting <soap:address> . Valid values are http and https . This configuration overrides the scheme computed by processing the endpoint even if a transport guarantee is specified. The provided values for wsdl-port and wsdl-secure-port , or their default values, are used depending on the specified scheme. You can use the management CLI to update these attributes. For example: 3.4.5. Viewing Runtime Information Each web service endpoint is exposed through the deployment that provides the endpoint implementation. Each endpoint can be queried as a deployment resource. Each web service endpoint specifies a web context and a WSDL URL. You can access this runtime information using the management CLI or the management console. The following management CLI command shows the details of the TestService endpoint from the jaxws-samples-handlerchain.war deployment. Note Using the include-runtime=true flag on the read-resource operation returns runtime statistics in the result. However, the collection of statistics for web service endpoints is disabled by default. You can enable statistics for web service endpoints using the following management CLI command. You can also view runtime information for web services endpoints from the Runtime tab of the management console by selecting the applicable server, selecting Webservices , then choosing the endpoint. 3.5. Assigning Client and Endpoint Configurations Client and endpoint configurations can be assigned in the following ways: Explicit assignment through annotations, for endpoints, or API programmatic usage, for clients. Automatic assignment of configurations from default descriptors. Automatic assignment of configurations from the container. 3.5.1. Explicit Configuration Assignment The explicit configuration assignment is meant for developers that know in advance their endpoint or client has to be set up according to a specified configuration. The configuration is coming from either a descriptor that is included in the application deployment, or is included in the webservices subsystem. 3.5.1.1. Configuration Deployment Descriptor Jakarta EE archives that can contain Jakarta XML Web Services client and endpoint implementations may also contain predefined client and endpoint configuration declarations. All endpoint or client configuration definitions for a given archive must be provided in a single deployment descriptor file, which must be an implementation of the schema that can be found at EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd . Many endpoint or client configurations can be defined in the deployment descriptor file. Each configuration must have a name that is unique within the server on which the application is deployed. The configuration name cannot be referred to by endpoint or client implementations outside the application. Example: Descriptor with Two Endpoint Configurations <?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl</config-name> <pre-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Log Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.LogHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </pre-handler-chains> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.RoutingHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </endpoint-config> <endpoint-config> <config-name>EP6-config</config-name> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Authorization Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </endpoint-config> </jaxws-config> Similarly, a client configuration can be specified in descriptors, which is still implementing the schema mentioned above: <?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <client-config> <config-name>Custom Client Config</config-name> <pre-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class> </javaee:handler> <javaee:handler> <javaee:handler-name>Custom Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.CustomHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </pre-handler-chains> </client-config> <client-config> <config-name>Another Client Config</config-name> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </client-config> </jaxws-config> 3.5.1.2. Application Server Configuration JBoss EAP allows declaring JBossWS client and server predefined configurations in the webservices subsystem. As a result it is possible to declare server-wide handlers to be added to the chain of each endpoint or client assigned to a given configuration. Standard Configuration Clients running in the same JBoss EAP instance, as well as endpoints, are assigned standard configurations by default. The defaults are used unless different a configuration is set. This enables administrators to tune the default handler chains for client and endpoint configurations. The names of the default client and endpoint configurations used in the webservices subsystem are Standard-Client-Config and Standard-Endpoint-Config . Handlers Classloading When setting a server-wide handler, the handler class needs to be available through each ws deployment classloader. As a result proper module dependencies may need to be specified in the deployments that are going to use a given predefined configuration. One way to ensure the proper module dependencies are specified in the deployment is to add a dependency to the module containing the handler class in one of the modules which are already automatically set as dependencies to any deployment, for instance org.jboss.ws.spi . Example Configuration Example: Default Subsystem Configuration <subsystem xmlns="urn:jboss:domain:webservices:2.0"> <!-- ... --> <endpoint-config name="Standard-Endpoint-Config"/> <endpoint-config name="Recording-Endpoint-Config"> <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"> <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/> </pre-handler-chain> </endpoint-config> <client-config name="Standard-Client-Config"/> </subsystem> A configuration file for a deployment specific ws-security endpoint setup: <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>Custom WS-Security Endpoint</config-name> <property> <property-name>ws-security.signature.properties</property-name> <property-value>bob.properties</property-value> </property> <property> <property-name>ws-security.encryption.properties</property-name> <property-value>bob.properties</property-value> </property> <property> <property-name>ws-security.signature.username</property-name> <property-value>bob</property-value> </property> <property> <property-name>ws-security.encryption.username</property-name> <property-value>alice</property-value> </property> <property> <property-name>ws-security.callback-handler</property-name> <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value> </property> </endpoint-config> </jaxws-config> JBoss EAP default configuration modified to default to SOAP messages schema-validation on: <subsystem xmlns="urn:jboss:domain:webservices:2.0"> <!-- ... --> <endpoint-config name="Standard-Endpoint-Config"> <property name="schema-validation-enabled" value="true"/> </endpoint-config> <!-- ... --> <client-config name="Standard-Client-Config"> <property name="schema-validation-enabled" value="true"/> </client-config> </subsystem> 3.5.1.3. EndpointConfig Annotation Once a configuration is available to a given application, the org.jboss.ws.api.annotation.EndpointConfig annotation is used to assign an endpoint configuration to a Jakarta XML Web Services endpoint implementation. When you assign a configuration that is defined in the webservices subsystem, you only need to specify the configuration name. When you assign a configuration that is defined in the application, you need to specify the relative path to the deployment descriptor and the configuration name. Example: EndpointConfig Annotation @EndpointConfig(configFile = "WEB-INF/my-endpoint-config.xml", configName = "Custom WS-Security Endpoint") public class ServiceImpl implements ServiceIface { public String sayHello() { return "Secure Hello World!"; } } 3.5.1.4. Jakarta XML Web Services Feature You can also use org.jboss.ws.api.configuration.ClientConfigFeature to set a configuration that is a Jakarta XML Web Services Feature extension provided by JBossWS. import org.jboss.ws.api.configuration.ClientConfigFeature; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config")); port.echo("Kermit"); You can also set properties from the specified configuration by passing in true to the ClientConfigFeature constructor. Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true); JBossWS parses the specified configuration file, after having resolved it as a resource using the current thread context class loader. The EAP_HOME /docs/schema/jbossws-jaxws-config_4_0.xsd schema defines the descriptor contents and is included in the jbossws-spi artifact. If you pass in null for the configuration file, the configuration will be read from the current container configurations, if available. Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature(null, "Container Custom Client Config")); 3.5.1.5. Explicit Setup Through API Alternatively, the JBossWS API comes with facility classes that can be used for assigning configurations when building a client. Handlers Jakarta XML Web Services handlers are read from client configurations as follows. import org.jboss.ws.api.configuration.ClientConfigUtil; import org.jboss.ws.api.configuration.ClientConfigurer; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); BindingProvider bp = (BindingProvider)port; ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config"); port.echo("Kermit"); You can also use the ClientConfigUtil utility class to set up the handlers. ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config"); The default ClientConfigurer implementation parses the specified configuration file, after having resolved it as a resource using the current thread context class loader. The EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd schema defines the descriptor contents and is included in the jbossws-spi artifact. If you pass in null for the configuration file, the configuration will be read from the current container configurations, if available. ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigHandlers(bp, null, "Container Custom Client Config"); Properties Similarly, properties are read from client configurations as follows. import org.jboss.ws.api.configuration.ClientConfigUtil; import org.jboss.ws.api.configuration.ClientConfigurer; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config"); port.echo("Kermit"); You can also use the ClientConfigUtil utility class to set up the properties. ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config"); The default ClientConfigurer implementation parses the specified configuration file, after having resolved it as a resource using the current thread context class loader. The EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd schema defines the descriptor contents and is included in the jbossws-spi artifact. If you pass in null for the configuration file, the configuration will be read from the current container configurations, if available. ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigProperties(port, null, "Container Custom Client Config"); 3.5.2. Automatic Configuration from Default Descriptors In some cases, the application developer might not be aware of the configuration that will need to be used for its client and endpoint implementation. In other cases, explicit usage of the JBossWS API might not be accepted because it is a compile-time dependency. To cope with such scenarios, JBossWS allows including default client, jaxws-client-config.xml , and endpoint, jaxws-endpoint-config.xml , descriptors within the application in its root directory. These are parsed for getting configurations whenever a configuration file name is not specified. <config-file>WEB-INF/jaxws-endpoint-config.xml</config-file> If the configuration name is not specified, JBossWS automatically looks for a configuration named as: The fully qualified name (FQN) of the endpoint implementation class, in case of Jakarta XML Web Services endpoints. The FQN of the service endpoint interface, in case of Jakarta XML Web Services clients. No automatic configuration name is selected for Dispatch clients. For example, an endpoint implementation class org.foo.bar.EndpointImpl , for which no predefined configuration is explicitly set, will cause JBossWS to look for a org.foo.bar.EndpointImpl named configuration within a jaxws-endpoint-config.xml descriptor in the root of the application deployment. Similarly, on the client side, a client proxy implementing org.foo.bar.Endpoint interface will have the setup read from a org.foo.bar.Endpoint named configuration in the jaxws-client-config.xml descriptor. 3.5.3. Automatic Configuration Assignment from Container JBossWS falls back to getting predefined configurations from the container whenever no explicit configuration has been provided and the default descriptors are either not available or do not contain relevant configurations. This behavior gives additional control on the Jakarta XML Web Services client and endpoint setup to administrators since the container can be managed independently from the deployed applications. JBossWS accesses the webservices subsystem for an explicitly named configuration. The default configuration names used are: The fully qualified name of the endpoint implementation class, in case of Jakarta XML Web Services endpoints. The fully qualified name of the service endpoint interface, in case of Jakarta XML Web Services clients. Dispatch clients are not automatically configured. If no configuration is found using names computed as above, the Standard-Client-Config and Standard-Endpoint-Config configurations are used for clients and endpoints respectively. 3.6. Setting Module Dependencies for Web Service Applications JBoss EAP web services are delivered as a set of modules and libraries, including the org.jboss.as.webservices.* and org.jboss.ws.* modules. You should not need to change these modules. With JBoss EAP you cannot directly use JBossWS implementation classes unless you explicitly set a dependency to the corresponding module. You declare the module dependencies that you want to be added to the deployment. The JBossWS APIs are available by default whenever the webservices subsystem is available. You can use them without creating an explicit dependencies declaration for those modules. 3.6.1. Using MANIFEST.MF To configure deployment dependencies, add them to the MANIFEST.MF file. For example: This MANIFEST.MF file declares dependencies on the org.jboss.ws.cxf.jbossws-cxf-client and foo.bar modules. For more information on declaring dependencies in a MANIFEST.MF file, including the export and services options, see Add a Dependency Configuration to MANIFEST.MF in the JBoss EAP Development Guide . When using annotations on the endpoints and handlers, for example, Apache CXF endpoints and handlers, add the proper module dependency in your manifest file. If you skip this step, your annotations are not picked up and are completely, silently ignored. 3.6.1.1. Using Jakarta XML Binding To successfully and directly use Jakarta XML Binding contexts in your client or endpoint running in-container, set up a Jakarta XML Binding implementation. For example, set the following dependency: 3.6.1.2. Using Apache CXF To use Apache CXF APIs and implementation classes, add a dependency to the org.apache.cxf (API) module or org.apache.cxf.impl (implementation) module. For example: The dependency is purely Apache CXF without any JBossWS customizations or additional extensions. For this reason, a client-side aggregation module is available with all the web service dependencies that you might need. 3.6.1.3. Client-side Web Services Aggregation Module When you want to use all of the web services features and functionality, you can set a dependency to the convenient client module. For example: The services option is required to enable all JBossWS features by loading JBossWS specific classes. The services option is almost always needed when declaring dependencies on the org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf modules. The option affects the loading of classes through the Service API, which is what is used to wire most of the JBossWS components and the Apache CXF Bus extensions. 3.6.1.4. Annotation Scanning The application server uses an annotation index for detecting Jakarta XML Web Services endpoints in user deployments. When declaring web service endpoints for a class that belongs to a different module, for instance referring to it in the web.xml descriptor, use an annotations type dependency. Without that dependency your endpoints are ignored as they do not appear as annotated classes to the webservices subsystem. 3.6.2. Using jboss-deployment-structure.xml In some circumstances, the convenient approach of setting module dependencies in the MANIFEST.MF file might not work. For example, setting dependencies in the MANIFEST.MF file does not work when importing and exporting specific resources from a given module dependency. In these scenarios, add a jboss-deployment-structure.xml descriptor file to your deployment and set module dependencies in it. For more information on using jboss-deployment-structure.xml , see Add a Dependency Configuration to the jboss-deployment-structure.xml in the JBoss EAP Development Guide . 3.7. Configuring HTTP Timeout The HTTP session timeout defines the period after which an HTTP session is considered to have become invalid because there was no activity within the specified period. The HTTP session timeout can be configured, in order of precedence, in the following places: Application You can define the HTTP session timeout in the application's web.xml configuration file by adding the following configuration to the file. This value is in minutes. <session-config> <session-timeout>30</session-timeout> </session-config> If you modified the WAR file, redeploy the application. If you exploded the WAR file, no further action is required because JBoss EAP automatically undeploys and redeploys the application. Server You can use the following management CLI command to set the default HTTP session timeout in the undertow subsystem. This value is in minutes. Default The default HTTP session timeout is 30 minutes. 3.8. Securing Jakarta XML Web Services WS-Security provides the means to secure your services beyond transport level protocols such as HTTPS. Through a number of standards, such as headers defined in the WS-Security standard, you can: Pass authentication tokens between services. Encrypt messages or parts of messages. Sign messages. Timestamp messages. WS-Security makes use of public and private key cryptography. With public key cryptography, a user has a pair of public and private keys. These are generated using a large prime number and a key function. The keys are related mathematically, but cannot be derived from one another. With these keys we can encrypt messages. For example, if Scott wants to send a message to Adam, he can encrypt a message using his public key. Adam can then decrypt this message using his private key. Only Adam can decrypt this message as he is the only one with the private key. Messages can also be signed. This allows you to ensure the authenticity of the message. If Adam wants to send a message to Scott, and Scott wants to be sure that it is from Adam, Adam can sign the message using his private key. Scott can then verify that the message is from Adam by using his public key. 3.8.1. Applying Web Services Security (WS-Security) Web services support many real-world scenarios requiring WS-Security functionality. These scenarios include signature and encryption support through X509 certificates, authentication and authorization through username tokens, and all WS-Security configurations covered by the WS-SecurityPolicy specification. For other WS-* features, the core of WS-Security functionality is provided through the Apache CXF engine. In addition, the JBossWS integration adds a few configuration enhancements to simplify the setup of WS-Security enabled endpoints. 3.8.1.1. Apache CXF WS-Security Implementation Apache CXF features a WS-Security module that supports multiple configurations and is easily extendible. The system is based on interceptors that delegate to Apache WSS4J for the low-level security operations. Interceptors can be configured in different ways, either through Spring configuration files or directly using the Apache CXF client API. Recent versions of Apache CXF introduced support for WS-SecurityPolicy, which aims at moving most of the security configuration into the service contract, through policies, so that clients can be easily configured almost completely automatically from that. This way users do not need to manually deal with configuring and installing the required interceptors; the Apache CXF WS-Policy engine internally takes care of that instead. 3.8.1.2. WS-Security Policy Support WS-SecurityPolicy describes the actions that are required to securely communicate with a service advertised in a given WSDL contract. The WSDL bindings and operations reference WS-Policy fragments with the security requirements to interact with the service. The WS-SecurityPolicy specification allows for specifying things such as asymmetric and symmetric keys, using transports (HTTPS) for encryption, which parts or headers to encrypt or sign, whether to sign then encrypt or encrypt then sign, whether to include timestamps, whether to use derived keys, or something else. However some mandatory configuration elements are not covered by WS-SecurityPolicy because they are not meant to be public or part of the published endpoint contract. These include things such as keystore locations, and usernames and passwords. Apache CXF allows configuring these elements either through Spring XML descriptors or using the client API or annotations. Table 3.4. Supported Configuration Properties Configuration property Description ws-security.username The username used for UsernameToken policy assertions. ws-security.password The password used for UsernameToken policy assertions. If not specified, the callback handler will be called. ws-security.callback-handler The WSS4J security CallbackHandler that will be used to retrieve passwords for keystores and UsernameToken . ws-security.signature.properties The properties file/object that contains the WSS4J properties for configuring the signature keystore and crypto objects. ws-security.encryption.properties The properties file/object that contains the WSS4J properties for configuring the encryption keystore and crypto objects. ws-security.signature.username The username or alias for the key in the signature keystore that will be used. If not specified, it uses the default alias set in the properties file. If that is also not set, and the keystore only contains a single key, that key will be used. ws-security.encryption.username The username or alias for the key in the encryption keystore that will be used. If not specified, it uses the default alias set in the properties file. If that is also not set, and the keystore only contains a single key, that key will be used. For the web service provider, the useReqSigCert keyword can be used to accept (encrypt) any client whose public key is in the service's truststore (defined in ws-security.encryption.properties ). ws-security.signature.crypto Instead of specifying the signature properties, this can point to the full WSS4J Crypto object. This can allow easier programmatic configuration of the crypto information. ws-security.encryption.crypto Instead of specifying the encryption properties, this can point to the full WSS4J Crypto object. This can allow easier programmatic configuration of the crypto information. ws-security.enable.streaming Enable streaming (StAX based) processing of WS-Security messages. 3.8.2. WS-Trust WS-Trust is a web service specification that defines extensions to WS-Security. It is a general framework for implementing security in a distributed system. The standard is based on a centralized Security Token Service (STS), which is capable of authenticating clients and issuing tokens containing various types of authentication and authorization data. The specification describes a protocol used for issuance, exchange, and validation of security tokens. The following specifications play an important role in the WS-Trust architecture: WS-SecurityPolicy 1.2 SAML 2.0 Username Token Profile X.509 Token Profile SAML Token Profile Kerberos Token Profile The WS-Trust extensions address the needs of applications that span multiple domains and requires the sharing of security keys. This occurs by providing a standards-based trusted third party web service (STS) to broker trust relationships between a web service requester and a web service provider. This architecture also alleviates the pain of service updates that require credential changes by providing a common location for this information. The STS is the common access point from which both the requester and provider retrieves and verifies security tokens. There are three main components of the WS-Trust specification: The Security Token Service (STS) for issuing, renewing, and validating security tokens. The message formats for security token requests and responses. The mechanisms for key exchange. The following section explains a basic WS-Trust scenario. For advanced scenarios, see Advanced WS-Trust Scenarios . 3.8.2.1. Scenario: Basic WS-Trust In this section we provide an example of a basic WS-Trust scenario. It comprises a web service requester ( ws-requester ), a web service provider ( ws-provider ), and a Security Token Service (STS). The ws-provider requires SAML 2.0 token issued from a designated STS to be presented by the ws-requester using asymmetric binding. These communication requirements are declared in the WSDL of the ws-provider . STS requires ws-requester credentials to be provided in a WSS UsernameToken format request using symmetric binding. The response from STS is provided containing SAML 2.0 token. These communication requirements are declared in the WSDL of the STS. The ws-requester contacts the ws-provider and consumes its WSDL. On finding the security token issuer requirement, the ws-requester creates and configures the STSClient with the information required to generate a valid request. The STSClient contacts the STS and consumes its WSDL. The security policies are discovered. The STSClient creates and sends an authentication request with appropriate credentials. The STS verifies the credentials. In response, the STS issues a security token that provides proof that the ws-requester has authenticated with the STS. The STSClient presents a message with the security token to the ws-provider . The ws-provider verifies that the token was issued by the STS, and hence proves that the ws-requester has successfully authenticated with the STS. The ws-provider executes the requested service and returns the results to the ws-requester . 3.8.2.2. Apache CXF Support Apache CXF is an open-source, fully-featured web services framework. The JBossWS open source project integrates the JBoss Web Services (JBossWS) stack with the Apache CXF project modules to provide WS-Trust and other Jakarta XML Web Services functionality. This integration helps in easy deployment of Apache CXF STS implementations. The Apache CXF API also provides a STSClient utility to facilitate web service requester communication with its STS. 3.8.3. Security Token Service (STS) The Security Token Service (STS) is the core of the WS-Trust specification. It is a standards-based mechanism for authentication and authorization. The STS is an implementation of the WS-Trust specification's protocol for issuing, exchanging, and validating security tokens, based on token format, namespace, or trust boundaries. The STS is a web service that acts as a trusted third party to broker trust relationships between a web service requester and a web service provider. It is a common access point trusted by both requester and provider to provide interoperable security tokens. It removes the need for a direct relationship between the requestor and provider. The STS helps ensure interoperability across realms and between different platforms because it is a standards-based mechanism for authentication. The STS's WSDL contract defines how other applications and processes interact with it. In particular, the WSDL defines the WS-Trust and WS-Security policies that a requester must fulfill to successfully communicate with the STS's endpoints. A web service requester consumes the STS's WSDL and, with the aid of an STSClient utility, generates a message request compliant with the stated security policies and submits it to the STS endpoint. The STS validates the request and returns an appropriate response. 3.8.3.1. Configuring a PicketLink WS-Trust Security Token Service (STS) PicketLink STS provides options for building an alternative to the Apache CXF Security Token Service implementation. You can also use PicketLink to configure SAML SSO for web applications. For more details on configuring SAML SSO using PicketLink, see How To Set Up SSO with SAML v2 . To set up an application to serve as a PicketLink WS-Trust STS, the following steps must be performed: Create a security domain for the WS-Trust STS application. Configure the web.xml file for the WS-Trust STS application. Configure the authenticator for the WS-Trust STS application. Declare the necessary dependencies for the WS-Trust STS application. Configure the web-service portion of the WS-Trust STS application. Create and configure a picketlink.xml file for the WS-Trust STS application. Note The security domain should be created and configured before creating and deploying the application. 3.8.3.1.1. Create a Security Domain for the STS The STS handles authentication of a principal based on the credentials provided and issues the proper security token based on that result. This requires that an identity store be configured via a security domain. The only requirement around creating this security domain and identity store is that it has authentication and authorization mechanisms properly defined. This means that many different identity stores, for example properties files, database, and LDAP, and their associated login modules could be used to support an STS application. For more information on security domains, see the Security Domains section of the JBoss EAP Security Architecture documentation. In the below example, a simple UsersRoles login module using properties files for an identity store is used. CLI Commands for Creating a Security Domain Resulting XML <security-domain name="sts" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="USD{jboss.server.config.dir}/sts-users.properties"/> <module-option name="rolesProperties" value="USD{jboss.server.config.dir}/sts-roles.properties"/> </login-module> </authentication> </security-domain> Note The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, see the JBoss EAP Management CLI Guide . Property Files The UsersRoles login module utilizes properties files to store the user/password and user/role information. For more specifics of the UsersRoles module, please see the JBoss EAP Login Module Reference . In this example, the properties files contain the following: Example: sts-users.properties File Example: sts-roles.properties File Important You also need to create a keystore for signing and encrypting the security tokens. This keystore will be used when configuring the picketlink.xml file. 3.8.3.1.2. Configure the web.xml File for the STS The web.xml file for an STS should contain the following: A <servlet> to enable the STS functionality and a <servlet-mapping> to map its URL. A <security-constraint> with a <web-resource-collection> containing a <url-pattern> that maps to the URL pattern of the secured area. Optionally, <security-constraint> may also contain an <auth-constraint> stipulating the allowed roles. A <login-config> configured for BASIC authentication. If any roles were specified in the <auth-constraint> , those roles should be defined in a <security-role> . Example web.xml file: <web-app> <!-- Define STS servlet --> <servlet> <servlet-name>STS-servlet</servlet-name> <servlet-class>com.example.sts.PicketLinkSTService</servlet-class> </servlet> <servlet-mapping> <servlet-name>STS-servlet</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> <!-- Define a security constraint that requires the All role to access resources --> <security-constraint> <web-resource-collection> <web-resource-name>STS</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>All</role-name> </auth-constraint> </security-constraint> <!-- Define the Login Configuration for this Application --> <login-config> <auth-method>BASIC</auth-method> <realm-name>STS Realm</realm-name> </login-config> <!-- Security roles referenced by this web application --> <security-role> <description>The role that is required to log in to the IDP Application</description> <role-name>All</role-name> </security-role> </web-app> 3.8.3.1.3. Configure the Authenticator for the STS The authenticator is responsible for the authentication of users for issuing and validating security tokens. The authenticator is configured by defining the security domain to be used in authenticating and authorizing principals. The jboss-web.xml file should have the following: A <security-domain> to specify which security domain to use for authentication and authorization. Example: jboss-web.xml File <jboss-web> <security-domain>sts</security-domain> <context-root>SecureTokenService</context-root> </jboss-web> 3.8.3.1.4. Declare the Necessary Dependencies for the STS The web application serving as the STS requires a dependency to be defined in the jboss-deployment-structure.xml file so that the org.picketlink classes can be located. As JBoss EAP provides all necessary org.picketlink and related classes, the application just needs to declare them as dependencies to use them. Example: Using jboss-deployment-structure.xml to Declare Dependencies <jboss-deployment-structure> <deployment> <dependencies> <module name="org.picketlink"/> </dependencies> </deployment> </jboss-deployment-structure> 3.8.3.1.5. Configure the Web-Service Portion of the STS The web application serving as the STS requires that you define a web-service for clients to call to obtain their security tokens. This requires that you define in your WSDL a service name called PicketLinkSTS , and a port called PicketLinkSTSPort . You can, however, change the SOAP address to better reflect your target deployment environment. Example: PicketLinkSTS.wsdl File <?xml version="1.0"?> <wsdl:definitions name="PicketLinkSTS" targetNamespace="urn:picketlink:identity-federation:sts" xmlns:tns="urn:picketlink:identity-federation:sts" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"> <wsdl:types> <xs:schema targetNamespace="urn:picketlink:identity-federation:sts" xmlns:tns="urn:picketlink:identity-federation:sts" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0" elementFormDefault="qualified"> <xs:element name="MessageBody"> <xs:complexType> <xs:sequence> <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##any"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> </wsdl:types> <wsdl:message name="RequestSecurityToken"> <wsdl:part name="rstMessage" element="tns:MessageBody"/> </wsdl:message> <wsdl:message name="RequestSecurityTokenResponse"> <wsdl:part name="rstrMessage" element="tns:MessageBody"/> </wsdl:message> <wsdl:portType name="SecureTokenService"> <wsdl:operation name="IssueToken"> <wsdl:input wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" message="tns:RequestSecurityToken"/> <wsdl:output wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Issue" message="tns:RequestSecurityTokenResponse"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="STSBinding" type="tns:SecureTokenService"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="IssueToken"> <soap12:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="PicketLinkSTS"> <wsdl:port name="PicketLinkSTSPort" binding="tns:STSBinding"> <soap12:address location="http://localhost:8080/SecureTokenService/PicketLinkSTS"/> </wsdl:port> </wsdl:service> </wsdl:definitions> In addition, you need a class for your web-service to use your WSDL: Example: PicketLinkSTS Class @WebServiceProvider(serviceName = "PicketLinkSTS", portName = "PicketLinkSTSPort", targetNamespace = "urn:picketlink:identity-federation:sts", wsdlLocation = "WEB-INF/wsdl/PicketLinkSTS.wsdl") @ServiceMode(value = Service.Mode.MESSAGE) public class PicketLinkSTService extends PicketLinkSTS { private static Logger log = Logger.getLogger(PicketLinkSTService.class.getName()); @Resource public void setWSC(WebServiceContext wctx) { log.debug("Setting WebServiceContext = " + wctx); this.context = wctx; } } 3.8.3.1.6. Create and Configure a picketlink.xml File for the STS The picketlink.xml file is responsible for the behavior of the authenticator and is loaded at the application's startup. The JBoss EAP Security Token Service defines several interfaces that provide extension points. Implementations can be plugged in and the default values can be specified for some properties using configuration. Similar to the IDP and SP configuration in How To Set Up SSO with SAML v2 , all STS configurations are specified in the picketlink.xml file of the deployed application. The following are the elements that can be configured in the picketlink.xml file. Note In the following text, a service provider refers to the web service that requires a security token to be presented by its clients. <PicketLinkSTS> : This is the root element. It defines some properties that allow the STS administrator to set the following properties: STSName : A string representing the name of the security token service. If not specified, the default PicketLinkSTS value is used. TokenTimeout : The token lifetime value in seconds. If not specified, the default value of 3600 (one hour) is used. EncryptToken : A boolean specifying whether issued tokens are to be encrypted or not. The default value is false . <KeyProvider> : This element and all its subelements are used to configure the keystore that are used by PicketLink STS to sign and encrypt tokens. Properties like the keystore location, its password, and the signing (private key) alias and password are all configured in this section. <TokenProviders> : This section specifies the TokenProvider implementations that must be used to handle each type of security token. In the example we have two providers - one that handles tokens of type SAMLV1.1 and one that handles tokens of type SAMLV2.0 . The WSTrustRequestHandler calls the getProviderForTokenType(String type) method of STSConfiguration to obtain a reference to the appropriate TokenProvider . <ServiceProviders> : This section specifies the token types that must be used for each service provider, the web service that requires a security token. When a WS-Trust request does not contain the token type, the WSTrustRequestHandler must use the service provider endpoint to find out the type of the token that must be issued. Note When configuring PicketLink, POST binding is recommended as it provides enhanced security and does not pass the response within URL parameters. Example: picketlink.xml Configuration File <!DOCTYPE PicketLinkSTS> <PicketLinkSTS xmlns="urn:picketlink:federation:config:2.1" STSName="PicketLinkSTS" TokenTimeout="7200" EncryptToken="false"> <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager"> <Auth Key="KeyStoreURL" Value="sts_keystore.jks"/> <Auth Key="KeyStorePass" Value="testpass"/> <Auth Key="SigningKeyAlias" Value="sts"/> <Auth Key="SigningKeyPass" Value="keypass"/> <ValidatingAlias Key="http://services.testcorp.org/provider1" Value="service1"/> </KeyProvider> <TokenProviders> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML11TokenProvider" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:1.0:assertion"/> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML20TokenProvider" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion"/> </TokenProviders> <ServiceProviders> <ServiceProvider Endpoint="http://services.testcorp.org/provider1" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" TruststoreAlias="service1"/> </ServiceProviders> </PicketLinkSTS> By default, the picketlink.xml file is located in the WEB-INF/classes directory of the STS web application. The PicketLink configuration file can also be loaded from the file system. To load the PicketLink configuration file from the file system, it must be named picketlink-sts.xml and be located in the USD{user.home}/picketlink-store/sts/ directory. 3.8.3.2. Using a WS-Trust Security Token Service (STS) with a Client To configure a client to obtain a security token from the STS, you need to make use of the org.picketlink.identity.federation.api.wstrust.WSTrustClient class to connect to the STS and ask for a token to be issued. First you need to instantiate the client: Example: Creating a WSTrustClient WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort", "http://localhost:8080/SecureTokenService/PicketLinkSTS", new SecurityInfo(username, password)); you need to use the WSTrustClient to ask for a token, for example a SAML assertion, to be issued: Example: Obtaining an Assertion org.w3c.dom.Element assertion = null; try { assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE); } catch (WSTrustException wse) { System.out.println("Unable to issue assertion: " + wse.getMessage()); wse.printStackTrace(); } Once you have the assertion, there are two ways by which it can be included in and sent via the SOAP message: The client can push the SAML2 Assertion into the SOAP MessageContext under the key org.picketlink.trust.saml.assertion . For example: bindingProvider.getRequestContext().put(SAML2Constants.SAML2_ASSERTION_PROPERTY, assertion); The SAML2 Assertion is available as part of the JAAS subject on the security context. This can happen if there has been a JAAS interaction with the usage of PicketLink STS login modules. 3.8.3.3. STS Client Pooling Warning The STS client pooling feature is NOT supported in JBoss EAP. STS client pooling is a feature that allows you to configure a pool of STS clients on the server, thereby eliminating a possible bottleneck of STS client creation. Client pooling can be used for login modules that need an STS client to obtain SAML tickets. These include: org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule org.picketlink.trust.jbossws.jaas.JBWSTokenIssuingLoginModule The default number of clients in the pool for each login module is configured using the initialNumberOfClients login module option. The org.picketlink.identity.federation.bindings.stspool.STSClientPoolFactory class provides client pool functionality to applications. Using STSClientPoolFactory STS clients are inserted into subpools using their STSClientConfig configuration as a key. To insert an STS client into a subpool, you need to obtain the STSClientPool instance and then initialize a subpool based on the configuration. Optionally, you can specify the initial number of STS clients when initializing the pool, or you can rely on the default number. Example: Inserting an STS Client into a Subpool final STSClientPool pool = STSClientPoolFactory.getPoolInstance(); pool.createPool(20, stsClientConfig); final STSClient client = pool.getClient(stsClientConfig); When you are done with a client, you can return it to the pool by calling the returnClient() method. Example: Returning an STS Client to the Subpool pool.returnClient(); Example: Checking If a Subpool Exists with a Given Configuration if (! pool.configExists(stsClientConfig) { pool.createPool(stsClientConfig); } If the picketlink-federation subsystem is enabled, all client pools created for a deployment are destroyed automatically during the undeploy process. To manually destroy a pool: Example: Manually Destroying a Subpool pool.destroyPool(stsClientConfig); 3.8.4. Propagating Authenticated Identity to the Jakarta Enterprise Beans Subsystem The webservices subsystem contains an adapter that allows you to configure an Elytron security domain to secure web service endpoints using either annotations or deployment descriptors. When Elytron security is enabled, the JAAS subject or principal can be pushed to the Apache CXF endpoint's SecurityContext to propagate the authenticated identity to the Jakarta Enterprise Beans container. The following is an example of how to use an Apache CXF interceptor to propagate authenticated information to the Jakarta Enterprise Beans container. public class PropagateSecurityInterceptor extends WSS4JInInterceptor { public PropagateSecurityInterceptor() { super(); getAfter().add(PolicyBasedWSS4JInInterceptor.class.getName()); } @Override public void handleMessage(SoapMessage message) throws Fault { ... final Endpoint endpoint = message.getExchange().get(Endpoint.class); final SecurityDomainContext securityDomainContext = endpoint.getSecurityDomainContext(); //push subject principal retrieved from CXF to ElytronSecurityDomainContext securityDomainContext.pushSubjectContext(subject, principal, null) } } 3.9. Jakarta XML Web Services Logging You can handle logging for inbound and outbound messages using Jakarta XML Web Services handlers or Apache CXF logging interceptors . 3.9.1. Using Jakarta XML Web Services Handlers You can configure a Jakarta XML Web Services handler to log messages that are passed to it. This approach is portable as the handler can be added to the desired client and endpoints programatically by using the @HandlerChain Jakarta XML Web Services annotation. The predefined client and endpoint configuration mechanism allows you to add the logging handler to any client and endpoint combination, or to only some of the clients and endpoints. To add the logging handler to only some of the clients or endpoints, use the @EndpointConfig annotation and the JBossWS API. The org.jboss.ws.api.annotation.EndpointConfig annotation is used to assign an endpoint configuration to a Jakarta XML Web Services endpoint implementation. When assigning a configuration that is defined in the webservices subsystem, only the configuration name is specified. When assigning a configuration that is defined in the application, the relative path to the deployment descriptor and the configuration name must be specified. 3.9.2. Using Apache CXF Logging Interceptors Apache CXF also comes with logging interceptors that can be used to log messages to the console, client log files, or server log files. Those interceptors can be added to client, endpoint, and buses in multiple ways, including: System property Setting the org.apache.cxf.logging.enabled system property to true causes the logging interceptors to be added to any bus instance being created on the JVM. You can also set the system property to pretty to output nicely-formatted XML output. You can use the following management CLI command to set this system property. Manual interceptor addition Logging interceptors can be selectively added to endpoints using the Apache CXF annotations @org.apache.cxf.interceptor.InInterceptors and @org.apache.cxf.interceptor.OutInterceptors . The same outcome is achieved on the client side by programmatically adding new instances of the logging interceptors to the client or the bus. 3.10. Enabling Web Services Addressing (WS-Addressing) Web Services Addressing, or WS-Addressing, provides a transport-neutral mechanism to address web services and their associated messages. To enable WS-Addressing, you must add the @Addressing annotation to the web service endpoint and then configure the client to access it. The following examples assume your application has an existing Jakarta XML Web Services service and client configuration. See the jaxws-addressing quickstart that ships with JBoss EAP for a complete working example. Add the @Addressing annotation to the application's Jakarta XML Web Services endpoint code. Example: Jakarta XML Web Services Endpoint with @Addressing Annotation package org.jboss.quickstarts.ws.jaxws.samples.wsa; import org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface; import javax.jws.WebService; import javax.xml.ws.soap.Addressing; @WebService( portName = "AddressingServicePort", serviceName = "AddressingService", wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl", targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing", endpointInterface = "org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface") @Addressing(enabled = true, required = true) public class ServiceImpl implements ServiceIface { public String sayHello() { return "Hello World!"; } } Update the Jakarta XML Web Services client code to configure WS-Addressing. Example: Jakarta XML Web Services Client Configured for WS-Addressing package org.jboss.quickstarts.ws.jaxws.samples.wsa; import java.net.URL; import javax.xml.namespace.QName; import javax.xml.ws.Service; import javax.xml.ws.soap.AddressingFeature; public final class AddressingClient { private static final String serviceURL = "http://localhost:8080/jaxws-addressing/AddressingService"; public static void main(String[] args) throws Exception { // construct proxy QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService"); URL wsdlURL = new URL(serviceURL + "?wsdl"); Service service = Service.create(wsdlURL, serviceName); org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface proxy = (org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface) service.getPort(org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface.class, new AddressingFeature()); // invoke method System.out.println(proxy.sayHello()); } } The client and endpoint now communicate using WS-Addressing. 3.11. Enabling Web Services Reliable Messaging Web Services Reliable Messaging (WS-Reliable Messaging) is implemented internally in Apache CXF. A set of interceptors interacts with the low-level requirements of the reliable messaging protocol. To enable WS-Reliable Messaging, complete one of the following steps: Consume a WSDL contract that specifies proper WS-Reliable Messaging policies, assertions, or both. Manually add and configure the reliable messaging interceptors. Specify the reliable messaging policies in an optional CXF Spring XML descriptor. Specify the Apache CXF reliable messaging feature in an optional CXF Spring XML descriptor. The first approach, which is the only portable approach, relies on the Apache CXF WS-Policy engine. The other approaches, which are proprietary, allow for fine-grained configuration of the protocol aspects that are not covered by the WS-Reliable Messaging Policy. 3.12. Specifying Web Services Policies Web Services Policies (WS-Policy) rely on the Apache CXF WS-Policy framework. This framework is compliant with the following specifications: Web Services Policy 1.5 - Framework Web Services Policy 1.5 - Attachment You can work with the policies in different ways, including: Add policy assertions to WSDL contracts and let the runtime consume the assertions and behave accordingly. Specify endpoint policy attachments using either CXF annotations or features. Use the Apache CXF policy framework to define custom assertions and complete other tasks. 3.13. Apache CXF Integration All Jakarta XML Web Services functionality provided by JBossWS on top of JBoss EAP is currently served through a proper integration of the JBossWS stack with most of the Apache CXF project modules. Apache CXF is an open source services framework. It allows building and developing services using front-end programming APIs, including Jakarta XML Web Services, with services speaking a variety of protocols such as SOAP and XML/HTTP over a variety of transports such as HTTP and Jakarta Messaging. The integration layer between JBossWS and Apache CXF is mainly meant for: Allowing use of standard web services APIs, including Jakarta XML Web Services, on JBoss EAP; this is performed internally leveraging Apache CXF without requiring the user to deal with it; Allowing use of Apache CXF advanced features, including WS-*, on top of JBoss EAP without requiring the user to deal with, set up, or care about the required integration steps for running in such a container. In support of those goals, the JBossWS integration with Apache CXF supports the JBossWS endpoint deployment mechanism and comes with many internal customizations on top of Apache CXF. For more in-depth details on the Apache CXF architecture, refer to the Apache CXF official documentation . 3.13.1. Server-side Integration Customization The JBossWS server-side integration with Apache CXF takes care of internally creating proper Apache CXF structures for the provided web service deployment. If the deployment includes multiple endpoints, they will all exist within the same Apache CXF Bus, which is separate from other deployments' bus instances. While JBossWS sets sensible defaults for most of the Apache CXF configuration options on the server side, users might want to fine-tune the Bus instance that is created for their deployment; a jboss-webservices.xml descriptor can be used for deployment-level customizations. 3.13.1.1. Deployment Descriptor Properties The jboss-webservices.xml descriptor can be used to provide property values. <webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2"> ... <property> <name>...</name> <value>...</value> </property> ... </webservices> JBossWS integration with Apache CXF comes with a set of allowed property names to control Apache CXF internals. 3.13.1.2. WorkQueue Configuration Apache CXF uses WorkQueue instances for dealing with some operations, for example @Oneway request processing. A WorkQueueManager is installed in the Bus as an extension and allows for adding or removing queues as well as controlling the existing ones. On the server side, queues can be provided by using the cxf.queue.<queue-name>.* properties in jboss-webservices.xml . For example, you can use the cxf.queue.default.maxQueueSize property to configure the maximum queue size of the default WorkQueue . At the deployment time, the JBossWS integration can add new instances of AutomaticWorkQueueImpl to the currently configured WorkQueueManager . The properties below are used to fill in the AutomaticWorkQueueImpl constructor parameters: Table 3.5. AutomaticWorkQueueImpl Constructor Properties Property Default Value cxf.queue.<queue-name>.maxQueueSize 256 cxf.queue.<queue-name>.initialThreads 0 cxf.queue.<queue-name>.highWaterMark 25 cxf.queue.<queue-name>.lowWaterMark 5 cxf.queue.<queue-name>.dequeueTimeout 120000 3.13.1.3. Policy Alternative Selector The Apache CXF policy engine supports different strategies to deal with policy alternatives. JBossWS integration currently defaults to the MaximalAlternativeSelector , but still allows for setting different selector implementation using the cxf.policy.alternativeSelector property in the jboss-webservices.xml file. 3.13.1.4. MBean Management Apache CXF allows you to manage its MBean objects that are installed into the JBoss EAP MBean server. You can enable this feature on a deployment basis through the cxf.management.enabled property in the jboss-webservices.xml file. You can also use the cxf.management.installResponseTimeInterceptors property to control installation of the CXF response time interceptors. These interceptors are added by default when enabling the MBean management, but it might not be required in some cases. Example: MBean Management in the jboss-webservices.xml File <webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2"> <property> <name>cxf.management.enabled</name> <value>true</value> </property> <property> <name>cxf.management.installResponseTimeInterceptors</name> <value>false</value> </property> </webservices> 3.13.1.5. Schema Validation Apache CXF includes a feature for validating incoming and outgoing SOAP messages on both the client and the server side. The validation is performed against the relevant schema in the endpoint WSDL contract (server side) or the WSDL contract used for building up the service proxy (client side). You can enable schema validation in any of the following ways: In the JBoss EAP server configuration. For example, the management CLI command below enables schema validation for the default Standard-Endpoint-Config endpoint configuration. In a predefined client or endpoint configuration file. You can associate any endpoint or client running in-container to a JBossWS predefined configuration by setting the schema-validation-enabled property to true in the referenced configuration file. Programmatically on the client side. On the client side, you can enable schema validation programmatically. For example: ((BindingProvider)proxy).getRequestContext().put("schema-validation-enabled", true); Using the @org.apache.cxf.annotations.SchemaValidation annotation on the server side. On the server side, you can use the @org.apache.cxf.annotations.SchemaValidation annotation. For example: import javax.jws.WebService; import org.apache.cxf.annotations.SchemaValidation; @WebService(...) @SchemaValidation public class ValidatingHelloImpl implements Hello { ... } 3.13.1.6. Apache CXF Interceptors The jboss-webservices.xml descriptor enables specifying the cxf.interceptors.in and cxf.interceptors.out properties. These properties allow you to attach the declaring interceptors to the Bus instance that is created for serving the deployment. Example: jboss-webservices.xml File <?xml version="1.1" encoding="UTF-8"?> <webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"> <property> <name>cxf.interceptors.in</name> <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusInterceptor</value> </property> <property> <name>cxf.interceptors.out</name> <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusCounterInterceptor</value> </property> </webservices> You can declare interceptors using one of the following approaches: Annotation usage on endpoint classes, for example @org.apache.cxf.interceptor.InInterceptor or @org.apache.cxf.interceptor.OutInterceptor . Direct API usage on the client side through the org.apache.cxf.interceptor.InterceptorProvider interface. JBossWS descriptor usage. Because Spring integration is no longer supported in JBoss EAP, the JBossWS integration uses the jaxws-endpoint-config.xml descriptor file to avoid requiring modifications to the actual client or endpoint code. You can declare interceptors within predefined client and endpoint configurations by specifying a list of interceptor class names for the cxf.interceptors.in and cxf.interceptors.out properties. Example: jaxws-endpoint-config.xml File <?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name> <property> <property-name>cxf.interceptors.in</property-name> <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value> </property> <property> <property-name>cxf.interceptors.out</property-name> <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value> </property> </endpoint-config> </jaxws-config> Note A new instance of each specified interceptor class will be added to the client or endpoint to which the configuration is assigned. The interceptor classes must have a no-argument constructor. 3.13.1.7. Apache CXF Features The jboss-webservices.xml descriptor enables specifying the cxf.features property. This property allows you to declare features to be attached to any endpoint belonging to the Bus instance that is created for serving the deployment. Example: jboss-webservices.xml File <?xml version="1.1" encoding="UTF-8"?> <webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"> <property> <name>cxf.features</name> <value>org.apache.cxf.feature.FastInfosetFeature</value> </property> </webservices> You can declare features using one of the following approaches: Annotation usage on endpoint classes, for example @org.apache.cxf.feature.Features . Direct API usage on client side through extensions of the org.apache.cxf.feature.AbstractFeature class. JBossWS descriptor usage. Since Spring integration is no longer supported in JBoss EAP, the JBossWS integration adds an additional descriptor, a jaxws-endpoint-config.xml file-based approach to avoid requiring modifications to the actual client or endpoint code. You can declare features within predefined client and endpoint configurations by specifying a list of feature class names for the cxf.features property. Example: jaxws-endpoint-config.xml File <?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>Custom FI Config</config-name> <property> <property-name>cxf.features</property-name> <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value> </property> </endpoint-config> </jaxws-config> Note A new instance of each specified feature class will be added to the client or endpoint the configuration is assigned to. The feature classes must have a no-argument constructor. 3.13.1.8. Properties-Driven Bean Creation The Apache CXF Interceptors and Apache CXF Features sections explain how to declare CXF interceptors and features through properties either in a client or endpoint predefined configuration or in a jboss-webservices.xml descriptor. By only getting the feature or interceptor class name specified, the container tries to create a bean instance using the class default constructor. This sets a limitation on the feature or interceptor configuration, unless custom extensions of vanilla CXF classes are provided, with the default constructor setting properties before eventually using the super constructor. To address this issue, JBossWS integration comes with a mechanism for configuring simple bean hierarchies when building them up from properties. Properties can have bean reference values, which are strings starting with ## . Property reference keys are used to specify the bean class name and the value for each attribute. So for instance, the following properties result in the stack installing two feature instances: Key Value cxf.features ##foo, ##bar ##foo org.jboss.Foo ##foo.par 34 ##bar org.jboss.Bar ##bar.color blue The same result can be created by the following code: import org.Bar; import org.Foo; ... Foo foo = new Foo(); foo.setPar(34); Bar bar = new Bar(); bar.setColor("blue"); This mechanism assumes that the classes are valid beans with proper getter() and setter() methods. Value objects are cast to the correct primitive type by inspecting the class definition. Nested beans can also be configured.

Commands:
package echo; @javax.jws.WebService public class Echo { public String echo(String input) { return input; } }
javac -d . Echo.java EAP_HOME/bin/wsprovide.sh --classpath=. -w echo.Echo
<wsdl:service name="EchoService"> <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding"> <soap:address location="http://localhost:9090/EchoPort"/> </wsdl:port> </wsdl:service>
<wsdl:portType name="Echo"> <wsdl:operation name="echo"> <wsdl:input name="echo" message="tns:echo"> </wsdl:input> <wsdl:output name="echoResponse" message="tns:echoResponse"> </wsdl:output> </wsdl:operation> </wsdl:portType>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <servlet> <servlet-name>Echo</servlet-name> <servlet-class>echo.Echo</servlet-class> </servlet> <servlet-mapping> <servlet-name>Echo</servlet-name> <url-pattern>/Echo</url-pattern> </servlet-mapping> </web-app>
mkdir -p WEB-INF/classes cp -rp echo WEB-INF/classes/ cp web.xml WEB-INF jar cvf echo.war WEB-INF added manifest adding: WEB-INF/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%) adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
EAP_HOME/bin/wsconsume.sh -k EchoService.wsdl
@WebService(targetNamespace = "http://echo/", name = "Echo") @XmlSeeAlso({ObjectFactory.class}) public interface Echo { @WebMethod @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type") @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse") @WebResult(name = "return", targetNamespace = "") public java.lang.String echo( @WebParam(name = "arg0", targetNamespace = "") java.lang.String arg0 ); }
package echo; @javax.jws.WebService(endpointInterface="echo.Echo") public class EchoImpl implements Echo { public String echo(String arg0) { return arg0; } }
<wsdl:service name="EchoService"> <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding"> <soap:address location="http://localhost.localdomain:8080/echo/Echo"/> </wsdl:port> </wsdl:service>
EAP_HOME/bin/wsconsume.sh -k http://localhost:8080/echo/Echo?wsdl
@WebServiceClient(name = "EchoService", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl", targetNamespace = "http://echo/") public class EchoService extends Service { public final static URL WSDL_LOCATION; public final static QName SERVICE = new QName("http://echo/", "EchoService"); public final static QName EchoPort = new QName("http://echo/", "EchoPort"); @WebEndpoint(name = "EchoPort") public Echo getEchoPort() { return super.getPort(EchoPort, Echo.class); } @WebEndpoint(name = "EchoPort") public Echo getEchoPort(WebServiceFeature... features) { return super.getPort(EchoPort, Echo.class, features); } }
import echo.*; public class EchoClient { public static void main(String args[]) { if (args.length != 1) { System.err.println("usage: EchoClient <message>"); System.exit(1); } EchoService service = new EchoService(); Echo echo = service.getEchoPort(); System.out.println("Server said: " + echo.echo(args0)); } }
EchoService service = new EchoService(); Echo echo = service.getEchoPort(); /* Set NEW Endpoint Location */ String endpointURL = "http://NEW_ENDPOINT_URL"; BindingProvider bp = (BindingProvider)echo; bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL); System.out.println("Server said: " + echo.echo(args0));
@WebService @SOAPBinding(style = SOAPBinding.Style.RPC) public class JSEBean { @WebMethod public String echo(String input) { } }
<web-app ...> <servlet> <servlet-name>TestService</servlet-name> <servlet-class>org.jboss.quickstarts.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class> </servlet> <servlet-mapping> <servlet-name>TestService</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app>
@Stateless @Remote(EJB3RemoteInterface.class) @WebService @SOAPBinding(style = SOAPBinding.Style.RPC) public class EJB3Bean implements EJB3RemoteInterface { @WebMethod public String echo(String input) { } }
package org.jboss.quickstarts.ws.jaxws.samples.retail.profile; import javax.ejb.Stateless; import javax.jws.WebService; import javax.jws.WebMethod; import javax.jws.soap.SOAPBinding; @Stateless @WebService( name = "ProfileMgmt", targetNamespace = "http://org.jboss.ws/samples/retail/profile", serviceName = "ProfileMgmtService") @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) public class ProfileMgmtBean { @WebMethod public DiscountResponse getCustomerDiscount(DiscountRequest request) { DiscountResponse dResponse = new DiscountResponse(); dResponse.setCustomer(request.getCustomer()); dResponse.setDiscount(10.00); return dResponse; } }
package org.jboss.test.ws.jaxws.samples.retail.profile; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlType; import org.jboss.test.ws.jaxws.samples.retail.Customer; @XmlAccessorType(XmlAccessType.FIELD) @XmlType( name = "discountRequest", namespace="http://org.jboss.ws/samples/retail/profile", propOrder = { "customer" } ) public class DiscountRequest { protected Customer customer; public DiscountRequest() { } public DiscountRequest(Customer customer) { this.customer = customer; } public Customer getCustomer() { return customer; } public void setCustomer(Customer value) { this.customer = value; } }
jar -tf jaxws-samples-retail.jar org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtBean.class org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class
<definitions name='ProfileMgmtService' targetNamespace='http://org.jboss.ws/samples/retail/profile' xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://org.jboss.ws/samples/retail' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://org.jboss.ws/samples/retail/profile' xmlns:xsd='http://www.w3.org/2001/XMLSchema'> <types> <xs:schema targetNamespace='http://org.jboss.ws/samples/retail' version='1.0' xmlns:xs='http://www.w3.org/2001/XMLSchema'> <xs:complexType name='customer'> <xs:sequence> <xs:element minOccurs='0' name='creditCardDetails' type='xs:string'/> <xs:element minOccurs='0' name='firstName' type='xs:string'/> <xs:element minOccurs='0' name='lastName' type='xs:string'/> </xs:sequence> </xs:complexType> </xs:schema> <xs:schema targetNamespace='http://org.jboss.ws/samples/retail/profile' version='1.0' xmlns:ns1='http://org.jboss.ws/samples/retail' xmlns:tns='http://org.jboss.ws/samples/retail/profile' xmlns:xs='http://www.w3.org/2001/XMLSchema'> <xs:import namespace='http://org.jboss.ws/samples/retail'/> <xs:element name='getCustomerDiscount' nillable='true' type='tns:discountRequest'/> <xs:element name='getCustomerDiscountResponse' nillable='true' type='tns:discountResponse'/> <xs:complexType name='discountRequest'> <xs:sequence> <xs:element minOccurs='0' name='customer' type='ns1:customer'/> </xs:sequence> </xs:complexType> <xs:complexType name='discountResponse'> <xs:sequence> <xs:element minOccurs='0' name='customer' type='ns1:customer'/> <xs:element name='discount' type='xs:double'/> </xs:sequence> </xs:complexType> </xs:schema> </types> <message name='ProfileMgmt_getCustomerDiscount'> <part element='tns:getCustomerDiscount' name='getCustomerDiscount'/> </message> <message name='ProfileMgmt_getCustomerDiscountResponse'> <part element='tns:getCustomerDiscountResponse' name='getCustomerDiscountResponse'/> </message> <portType name='ProfileMgmt'> <operation name='getCustomerDiscount' parameterOrder='getCustomerDiscount'> <input message='tns:ProfileMgmt_getCustomerDiscount'/> <output message='tns:ProfileMgmt_getCustomerDiscountResponse'/> </operation> </portType> <binding name='ProfileMgmtBinding' type='tns:ProfileMgmt'> <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/> <operation name='getCustomerDiscount'> <soap:operation soapAction=''/> <input> <soap:body use='literal'/> </input> <output> <soap:body use='literal'/> </output> </operation> </binding> <service name='ProfileMgmtService'> <port binding='tns:ProfileMgmtBinding' name='ProfileMgmtPort'> <!-- service address will be rewritten to actual one when WSDL is requested from running server --> <soap:address location='http://SERVER:PORT/jaxws-retail/ProfileMgmtBean'/> </port> </service> </definitions>
./wsconsume.sh --help WSConsumeTask is a cmd line tool that generates portable JAX-WS artifacts from a WSDL file. usage: org.jboss.ws.tools.cmd.WSConsume [options] <wsdl-url> options: -h, --help Show this help message -b, --binding=<file> One or more JAX-WS or Java XML Binding files -k, --keep Keep/Generate Java source -c --catalog=<file> Oasis XML Catalog file for entity resolution -p --package=<name> The target package for generated source -w --wsdlLocation=<loc> Value to use for @WebService.wsdlLocation -o, --output=<directory> The directory to put generated artifacts -s, --source=<directory> The directory to put Java source -t, --target=<2.0|2.1|2.2> The JAX-WS target -q, --quiet Be somewhat more quiet -v, --verbose Show full exception stack traces -l, --load-consumer Load the consumer and exit (debug utility) -e, --extension Enable SOAP 1.2 binding extension -a, --additionalHeaders Enable processing of implicit SOAP headers -n, --nocompile Do not compile generated sources
[user@host bin]USD wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.retail.profile ProfileMgmtService.wsdl output/org/jboss/test/ws/jaxws/samples/retail/profile/Customer.java output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.java output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.java output/org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.java output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.java output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.java output/org/jboss/test/ws/jaxws/samples/retail/profile/package-info.java output/org/jboss/test/ws/jaxws/samples/retail/profile/Customer.class output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class output/org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class output/org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class
import javax.xml.ws.Service; [...] Service service = Service.create( new URL("http://example.org/service?wsdl"), new QName("MyService") ); ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); // Use the service stub in your application
@WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl") public class StockQuoteService extends javax.xml.ws.Service { public StockQuoteService() { super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService")); } public StockQuoteService(String wsdlLocation, QName serviceName) { super(wsdlLocation, serviceName); } }
URL wsdlLocation = new URL("http://example.org/my.wsdl"); QName serviceName = new QName("http://example.org/sample", "MyService"); Service service = Service.create(wsdlLocation, serviceName);
public <T> T getPort(QName portName, Class<T> serviceEndpointInterface) public <T> T getPort(Class<T> serviceEndpointInterface)
@WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref", wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl") public class TestEndpointService extends Service { public TestEndpointService(URL wsdlLocation, QName serviceName) { super(wsdlLocation, serviceName); } @WebEndpoint(name = "TestEndpointPort") public TestEndpoint getTestEndpointPort() { return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class); } }
public class EJB3Client implements EJB3Remote { @WebServiceRef public TestEndpointService service4; @WebServiceRef public TestEndpoint port3; }
Service service = Service.create(wsdlURL, serviceName); Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD); String payload = "<ns1:ping xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>"; dispatch.invokeOneWay(new StreamSource(new StringReader(payload))); payload = "<ns1:feedback xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>"; Source retObj = (Source)dispatch.invoke(new StreamSource(new StringReader(payload)));
public void testInvokeAsync() throws Exception { URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl"); QName serviceName = new QName(targetNS, "TestEndpointService"); Service service = Service.create(wsdlURL, serviceName); TestEndpoint port = service.getPort(TestEndpoint.class); Response response = port.echoAsync("Async"); // access future String retStr = (String) response.get(); assertEquals("Async", retStr); }
@WebService (name="PingEndpoint") @SOAPBinding(style = SOAPBinding.Style.RPC) public class PingEndpointImpl { private static String feedback; @WebMethod @Oneway public void ping() { log.info("ping"); feedback = "ok"; } @WebMethod public String feedback() { log.info("feedback"); return feedback; } }
public void testConfigureTimeout() throws Exception { //Set timeout until a connection is established ((BindingProvider)port).getRequestContext().put("javax.xml.ws.client.connectionTimeout", "6000"); //Set timeout until the response is received ((BindingProvider) port).getRequestContext().put("javax.xml.ws.client.receiveTimeout", "1000"); port.echo("testTimeout"); }
<subsystem xmlns="urn:jboss:domain:webservices:2.0"> <wsdl-host>USD{jboss.bind.address:127.0.0.1}</wsdl-host> <endpoint-config name="Standard-Endpoint-Config"/> <endpoint-config name="Recording-Endpoint-Config"> <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"> <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/> </pre-handler-chain> </endpoint-config> <client-config name="Standard-Client-Config"/> </subsystem>
/subsystem=webservices/endpoint-config=My-Endpoint-Config:add
/subsystem=webservices/endpoint-config=Standard-Endpoint-Config/property= PROPERTY_NAME :add(value= PROPERTY_VALUE )
/subsystem=webservices/endpoint-config=My-Endpoint-Config:remove
Endpoint --> PRE Handlers --> Endpoint Handlers --> POST Handlers --> ... --> Client
Client --> ... --> POST Handlers --> Endpoint Handlers --> PRE Handlers --> Endpoint
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:add
/subsystem=webservices/endpoint-config=My-Endpoint-Config/pre-handler-chain=my-pre-handler-chain:add
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:write-attribute(name=protocol-bindings,value=##SOAP11_HTTP)
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:remove
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:add(class="com.arjuna.webservices11.wsarj.handler.InstanceIdentifierInHandler")
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:add(class="org.jboss.ws.common.invocation.RecordingServerHandler")
/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:
/subsystem=webservices:write-attribute(name=wsdl-uri-scheme, value=https)
/deployment="jaxws-samples-handlerchain.war"/subsystem=webservices/endpoint="jaxws-samples-handlerchain:TestService":read-resource(include-runtime=true) { "outcome" => "success", "result" => { "average-processing-time" => 23L, "class" => "org.jboss.test.ws.jaxws.samples.handlerchain.EndpointImpl", "context" => "jaxws-samples-handlerchain", "fault-count" => 0L, "max-processing-time" => 23L, "min-processing-time" => 23L, "name" => "TestService", "request-count" => 1L, "response-count" => 1L, "total-processing-time" => 23L, "type" => "JAXWS_JSE", "wsdl-url" => "http://localhost:8080/jaxws-samples-handlerchain?wsdl" } }
/subsystem=webservices:write-attribute(name=statistics-enabled,value=true)
<?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl</config-name> <pre-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Log Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.LogHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </pre-handler-chains> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.RoutingHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </endpoint-config> <endpoint-config> <config-name>EP6-config</config-name> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Authorization Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </endpoint-config> </jaxws-config>
<?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <client-config> <config-name>Custom Client Config</config-name> <pre-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class> </javaee:handler> <javaee:handler> <javaee:handler-name>Custom Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.CustomHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </pre-handler-chains> </client-config> <client-config> <config-name>Another Client Config</config-name> <post-handler-chains> <javaee:handler-chain> <javaee:handler> <javaee:handler-name>Routing Handler</javaee:handler-name> <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class> </javaee:handler> </javaee:handler-chain> </post-handler-chains> </client-config> </jaxws-config>
<subsystem xmlns="urn:jboss:domain:webservices:2.0"> <!-- ... --> <endpoint-config name="Standard-Endpoint-Config"/> <endpoint-config name="Recording-Endpoint-Config"> <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"> <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/> </pre-handler-chain> </endpoint-config> <client-config name="Standard-Client-Config"/> </subsystem>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>Custom WS-Security Endpoint</config-name> <property> <property-name>ws-security.signature.properties</property-name> <property-value>bob.properties</property-value> </property> <property> <property-name>ws-security.encryption.properties</property-name> <property-value>bob.properties</property-value> </property> <property> <property-name>ws-security.signature.username</property-name> <property-value>bob</property-value> </property> <property> <property-name>ws-security.encryption.username</property-name> <property-value>alice</property-value> </property> <property> <property-name>ws-security.callback-handler</property-name> <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value> </property> </endpoint-config> </jaxws-config>
<subsystem xmlns="urn:jboss:domain:webservices:2.0"> <!-- ... --> <endpoint-config name="Standard-Endpoint-Config"> <property name="schema-validation-enabled" value="true"/> </endpoint-config> <!-- ... --> <client-config name="Standard-Client-Config"> <property name="schema-validation-enabled" value="true"/> </client-config> </subsystem>
@EndpointConfig(configFile = "WEB-INF/my-endpoint-config.xml", configName = "Custom WS-Security Endpoint") public class ServiceImpl implements ServiceIface { public String sayHello() { return "Secure Hello World!"; } }
import org.jboss.ws.api.configuration.ClientConfigFeature; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config")); port.echo("Kermit");
Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true);
Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature(null, "Container Custom Client Config"));
import org.jboss.ws.api.configuration.ClientConfigUtil; import org.jboss.ws.api.configuration.ClientConfigurer; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); BindingProvider bp = (BindingProvider)port; ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config"); port.echo("Kermit");
ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config");
ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigHandlers(bp, null, "Container Custom Client Config");
import org.jboss.ws.api.configuration.ClientConfigUtil; import org.jboss.ws.api.configuration.ClientConfigurer; Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config"); port.echo("Kermit");
ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config");
ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); configurer.setConfigProperties(port, null, "Container Custom Client Config");
<config-file>WEB-INF/jaxws-endpoint-config.xml</config-file>
Manifest-Version: 1.0 Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services export,foo.bar
Dependencies: com.sun.xml.bind services export
Dependencies: org.apache.cxf services
Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services
Dependencies: my.org annotations
<session-config> <session-timeout>30</session-timeout> </session-config>
/subsystem=undertow/servlet-container=default:write-attribute(name=default-session-timeout,value=30)
/subsystem=security/security-domain=sts:add(cache-type=default)
/subsystem=security/security-domain=sts/authentication=classic:add
/subsystem=security/security-domain=sts/authentication=classic/login-module=UsersRoles:add(code=UsersRoles,flag=required,module-options=[usersProperties=USD{jboss.server.config.dir}/sts-users.properties,rolesProperties=USD{jboss.server.config.dir}/sts-roles.properties])
reload
<security-domain name="sts" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="USD{jboss.server.config.dir}/sts-users.properties"/> <module-option name="rolesProperties" value="USD{jboss.server.config.dir}/sts-roles.properties"/> </login-module> </authentication> </security-domain>
Eric=samplePass Alan=samplePass
Eric=All Alan=
<web-app> <!-- Define STS servlet --> <servlet> <servlet-name>STS-servlet</servlet-name> <servlet-class>com.example.sts.PicketLinkSTService</servlet-class> </servlet> <servlet-mapping> <servlet-name>STS-servlet</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> <!-- Define a security constraint that requires the All role to access resources --> <security-constraint> <web-resource-collection> <web-resource-name>STS</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>All</role-name> </auth-constraint> </security-constraint> <!-- Define the Login Configuration for this Application --> <login-config> <auth-method>BASIC</auth-method> <realm-name>STS Realm</realm-name> </login-config> <!-- Security roles referenced by this web application --> <security-role> <description>The role that is required to log in to the IDP Application</description> <role-name>All</role-name> </security-role> </web-app>
<jboss-web> <security-domain>sts</security-domain> <context-root>SecureTokenService</context-root> </jboss-web>
<jboss-deployment-structure> <deployment> <dependencies> <module name="org.picketlink"/> </dependencies> </deployment> </jboss-deployment-structure>
<?xml version="1.0"?> <wsdl:definitions name="PicketLinkSTS" targetNamespace="urn:picketlink:identity-federation:sts" xmlns:tns="urn:picketlink:identity-federation:sts" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"> <wsdl:types> <xs:schema targetNamespace="urn:picketlink:identity-federation:sts" xmlns:tns="urn:picketlink:identity-federation:sts" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0" elementFormDefault="qualified"> <xs:element name="MessageBody"> <xs:complexType> <xs:sequence> <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##any"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> </wsdl:types> <wsdl:message name="RequestSecurityToken"> <wsdl:part name="rstMessage" element="tns:MessageBody"/> </wsdl:message> <wsdl:message name="RequestSecurityTokenResponse"> <wsdl:part name="rstrMessage" element="tns:MessageBody"/> </wsdl:message> <wsdl:portType name="SecureTokenService"> <wsdl:operation name="IssueToken"> <wsdl:input wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" message="tns:RequestSecurityToken"/> <wsdl:output wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Issue" message="tns:RequestSecurityTokenResponse"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="STSBinding" type="tns:SecureTokenService"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="IssueToken"> <soap12:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="PicketLinkSTS"> <wsdl:port name="PicketLinkSTSPort" binding="tns:STSBinding"> <soap12:address location="http://localhost:8080/SecureTokenService/PicketLinkSTS"/> </wsdl:port> </wsdl:service> </wsdl:definitions>
@WebServiceProvider(serviceName = "PicketLinkSTS", portName = "PicketLinkSTSPort", targetNamespace = "urn:picketlink:identity-federation:sts", wsdlLocation = "WEB-INF/wsdl/PicketLinkSTS.wsdl") @ServiceMode(value = Service.Mode.MESSAGE) public class PicketLinkSTService extends PicketLinkSTS { private static Logger log = Logger.getLogger(PicketLinkSTService.class.getName()); @Resource public void setWSC(WebServiceContext wctx) { log.debug("Setting WebServiceContext = " + wctx); this.context = wctx; } }
<!DOCTYPE PicketLinkSTS> <PicketLinkSTS xmlns="urn:picketlink:federation:config:2.1" STSName="PicketLinkSTS" TokenTimeout="7200" EncryptToken="false"> <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager"> <Auth Key="KeyStoreURL" Value="sts_keystore.jks"/> <Auth Key="KeyStorePass" Value="testpass"/> <Auth Key="SigningKeyAlias" Value="sts"/> <Auth Key="SigningKeyPass" Value="keypass"/> <ValidatingAlias Key="http://services.testcorp.org/provider1" Value="service1"/> </KeyProvider> <TokenProviders> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML11TokenProvider" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:1.0:assertion"/> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML20TokenProvider" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion"/> </TokenProviders> <ServiceProviders> <ServiceProvider Endpoint="http://services.testcorp.org/provider1" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" TruststoreAlias="service1"/> </ServiceProviders> </PicketLinkSTS>
WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort", "http://localhost:8080/SecureTokenService/PicketLinkSTS", new SecurityInfo(username, password));
org.w3c.dom.Element assertion = null; try { assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE); } catch (WSTrustException wse) { System.out.println("Unable to issue assertion: " + wse.getMessage()); wse.printStackTrace(); }
bindingProvider.getRequestContext().put(SAML2Constants.SAML2_ASSERTION_PROPERTY, assertion);
final STSClientPool pool = STSClientPoolFactory.getPoolInstance(); pool.createPool(20, stsClientConfig); final STSClient client = pool.getClient(stsClientConfig);
pool.returnClient();
if (! pool.configExists(stsClientConfig) { pool.createPool(stsClientConfig); }
pool.destroyPool(stsClientConfig);
public class PropagateSecurityInterceptor extends WSS4JInInterceptor { public PropagateSecurityInterceptor() { super(); getAfter().add(PolicyBasedWSS4JInInterceptor.class.getName()); } @Override public void handleMessage(SoapMessage message) throws Fault { final Endpoint endpoint = message.getExchange().get(Endpoint.class); final SecurityDomainContext securityDomainContext = endpoint.getSecurityDomainContext(); //push subject principal retrieved from CXF to ElytronSecurityDomainContext securityDomainContext.pushSubjectContext(subject, principal, null) } }
/system-property=org.apache.cxf.logging.enabled:add(value=true)
package org.jboss.quickstarts.ws.jaxws.samples.wsa; import org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface; import javax.jws.WebService; import javax.xml.ws.soap.Addressing; @WebService( portName = "AddressingServicePort", serviceName = "AddressingService", wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl", targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing", endpointInterface = "org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface") @Addressing(enabled = true, required = true) public class ServiceImpl implements ServiceIface { public String sayHello() { return "Hello World!"; } }
package org.jboss.quickstarts.ws.jaxws.samples.wsa; import java.net.URL; import javax.xml.namespace.QName; import javax.xml.ws.Service; import javax.xml.ws.soap.AddressingFeature; public final class AddressingClient { private static final String serviceURL = "http://localhost:8080/jaxws-addressing/AddressingService"; public static void main(String[] args) throws Exception { // construct proxy QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService"); URL wsdlURL = new URL(serviceURL + "?wsdl"); Service service = Service.create(wsdlURL, serviceName); org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface proxy = (org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface) service.getPort(org.jboss.quickstarts.ws.jaxws.samples.wsa.ServiceIface.class, new AddressingFeature()); // invoke method System.out.println(proxy.sayHello()); } }
<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2"> <property> <name>...</name> <value>...</value> </property> </webservices>
<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2"> <property> <name>cxf.management.enabled</name> <value>true</value> </property> <property> <name>cxf.management.installResponseTimeInterceptors</name> <value>false</value> </property> </webservices>
/subsystem=webservices/endpoint-config=Standard-Endpoint-Config/property=schema-validation-enabled:add(value=true)
((BindingProvider)proxy).getRequestContext().put("schema-validation-enabled", true);
import javax.jws.WebService; import org.apache.cxf.annotations.SchemaValidation; @WebService(...) @SchemaValidation public class ValidatingHelloImpl implements Hello { }
<?xml version="1.1" encoding="UTF-8"?> <webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"> <property> <name>cxf.interceptors.in</name> <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusInterceptor</value> </property> <property> <name>cxf.interceptors.out</name> <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusCounterInterceptor</value> </property> </webservices>
<?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name> <property> <property-name>cxf.interceptors.in</property-name> <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value> </property> <property> <property-name>cxf.interceptors.out</property-name> <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value> </property> </endpoint-config> </jaxws-config>
<?xml version="1.1" encoding="UTF-8"?> <webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"> <property> <name>cxf.features</name> <value>org.apache.cxf.feature.FastInfosetFeature</value> </property> </webservices>
<?xml version="1.0" encoding="UTF-8"?> <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"> <endpoint-config> <config-name>Custom FI Config</config-name> <property> <property-name>cxf.features</property-name> <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value> </property> </endpoint-config> </jaxws-config>
import org.Bar; import org.Foo; Foo foo = new Foo(); foo.setPar(34); Bar bar = new Bar(); bar.setColor("blue");