From jbossws-commits at lists.jboss.org Tue Feb 5 05:02:34 2008 Content-Type: multipart/mixed; boundary="===============1171134869176104408==" MIME-Version: 1.0 From: jbossws-commits at lists.jboss.org To: jbossws-commits at lists.jboss.org Subject: [jbossws-commits] JBossWS SVN: r5563 - stack/native/tags/jbossws-native-2.0.3.GA. Date: Tue, 05 Feb 2008 05:02:32 -0500 Message-ID: --===============1171134869176104408== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: alessio.soldano(a)jboss.com Date: 2008-02-05 05:02:32 -0500 (Tue, 05 Feb 2008) New Revision: 5563 Added: stack/native/tags/jbossws-native-2.0.3.GA/JBossWS-2.0.3.GA-doc_export.xml Log: Adding docbook xml documentation export Added: stack/native/tags/jbossws-native-2.0.3.GA/JBossWS-2.0.3.GA-doc_expor= t.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- stack/native/tags/jbossws-native-2.0.3.GA/JBossWS-2.0.3.GA-doc_export.x= ml (rev 0) +++ stack/native/tags/jbossws-native-2.0.3.GA/JBossWS-2.0.3.GA-doc_export.x= ml 2008-02-05 10:02:32 UTC (rev 5563) @@ -0,0 +1,5047 @@ + + + +JBossWS 2.0.3.GA documentation= Permission to use, copy, modify and distribute this document under the GNU = Free Documentation License (GFDL).
+User Guide + +Category:Development (User Guide) + + + + + +This guide does cover JAX-WS functional= ity only, if you are looking for J2EE-1-4 compliant web services (i.e. the = JSR-109 programming model) please goto the JAX-RPC_User_Guide. + + +To get started you need to download jbo= ssws and install JBossWS on your preferr= ed target container. Also consider running and looking at the source code o= f the JAX-WS samples available in every JBossWS binary distribution. + + +This user guide applies to jbossws-1.2.0 and higher. For older versions, please consult the JBossWS User Guide on JBoss.ORG. + + +Since 1.2 + +
Web Service Concept= s +
Document/Literal</tit= le> +<para> +With document style web services two business partners agree on the exchan= ge of complex business documents that are well defined in XML schema. For e= xample, one party sends a document describing a purchase order, the other r= esponds (immediately or later) with a document that describes the status of= the purchase order. No need to agree on such low level details as operatio= n names and their associated parameters. +</para> +<para> +The payload of the SOAP message is an XML document that can be validated a= gainst XML schema. +</para> +<para> +Document is defined by the style attribute on the SOAP binding. +</para> +<para> +<programlisting><binding name=3D'EndpointInterfaceBinding' type=3D'tns:= EndpointInterface'><soap:binding style=3D'document' transport=3D'http= ://schemas.xmlsoap.org/soap/http'/><operation name=3D'concat'><= soap:operation soapAction=3D''/><input><soap:body use=3D'litera= l'/></input><output><soap:body use=3D'literal'/></o= utput></operation></binding></programlisting> +</para> +<para> +With document style web services the payload of every message is defined b= y a complex type in XML schema. +</para> +<para> +<programlisting><complexType name=3D'concatType'><sequence><= ;element name=3D'String_1' nillable=3D'true' type=3D'string'/><elemen= t name=3D'long_1' type=3D'long'/></sequence></complexType>&l= t;element name=3D'concat' type=3D'tns:concatType'/></programlisting> +</para> +<para> +Therefore, message parts <emphasis role=3D"bold">must</emphasis> refer to = an <emphasis role=3D"bold">element</emphasis> from the schema. +</para> +<para> +<programlisting><message name=3D'EndpointInterface_concat'><part = name=3D'parameters' element=3D'tns:concat'/></message></programlis= ting> +</para> +<para> +The following message definition <emphasis role=3D"bold">is invalid</empha= sis>. +</para> +<para> +<programlisting><message name=3D'EndpointInterface_concat'><part = name=3D'parameters' type=3D'tns:concatType'/></message></programli= sting> +</para> +<section id=3D"User_Guide_Document_2FLiteral__28Bare_29"><title>Document/L= iteral (Bare) + +Bare is an implementation detail from the Java domain. Neither in the abst= ract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare en= dpoint recognizable. + + +A bare endpoint or client uses a Java bean that represents the entire docu= ment payload. + + + +(a)WebService +(a)SOAPBinding(parameterStyle =3D SOAPBinding.ParameterStyle.BARE) +public class DocBareServiceImpl +{ + @WebMethod + public SubmitBareResponse submitPO(SubmitBareRequest poRequest) + { + ... + } +} + + + +The trick is that the Java beans representing the payload contain JAXB ann= otations that define how the payload is represented on the wire. + + + +(a)XmlAccessorType(XmlAccessType.FIELD) +(a)XmlType(name =3D "SubmitBareRequest", namespace=3D"http://soapbinding.s= amples.jaxws.ws.test.jboss.org/", propOrder =3D { "product" }) +(a)XmlRootElement(namespace=3D"http://soapbinding.samples.jaxws.ws.test.jb= oss.org/", name =3D "SubmitPO") +public class SubmitBareRequest +{ + @XmlElement(namespace=3D"http://soapbinding.samples.jaxws.ws.test.jboss.o= rg/", required =3D true) + private String product; + = + ... +} + + + +
+
Documen= t/Literal (Wrapped) + +Wrapped is an implementation detail from the Java domain. Neither in the a= bstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrap= ped endpoint recognizable. + + +A wrapped endpoint or client uses the individual document payload properti= es. Wrapped is the default and does not have to be declared explicitly. + + + +(a)WebService +public class DocWrappedServiceImpl +{ + @WebMethod + @RequestWrapper (className=3D"org.somepackage.SubmitPO") + @ResponseWrapper (className=3D"org.somepackage.SubmitPOResponse") + public String submitPO(String product, int quantity) + { + ... + } +} + + + +Note, that with JBossWS the request/response wrapper annotations are not required, they will be generated on deman= d using sensible defaults. + + +
+ +
+
RPC/Literal + +With RPC there is a wrapper element that names the endpoint operation. Chi= ld elements of the RPC parent are the individual parameters. = + + +The SOAP body is constructed based on some simple rules: + + + +The port type operation name defines the endpoint method name + + + + +Message parts are endpoint method parameters + + + + +RPC is defined by the style attribute on the SOAP binding. + + +<binding name=3D'EndpointInterfaceBinding' type=3D'tns:= EndpointInterface'><soap:binding style=3D'rpc' transport=3D'http://sc= hemas.xmlsoap.org/soap/http'/><operation name=3D'echo'><soap:op= eration soapAction=3D''/><input><soap:body namespace=3D'http://= org.jboss.ws/samples/jsr181pojo' use=3D'literal'/></input><outp= ut><soap:body namespace=3D'http://org.jboss.ws/samples/jsr181pojo' us= e=3D'literal'/></output></operation></binding> + + +With rpc style web services the portType names the operation (i.e. the jav= a method on the endpoint) + + +<portType name=3D'EndpointInterface'><operation n= ame=3D'echo' parameterOrder=3D'String_1'><input message=3D'tns:Endpoi= ntInterface_echo'/><output message=3D'tns:EndpointInterface_echoRespo= nse'/></operation></portType> + + +Operation parameters are defined by individual message parts. + + +<message name=3D'EndpointInterface_echo'><part na= me=3D'String_1' type=3D'xsd:string'/></message><message name=3D= 'EndpointInterface_echoResponse'><part name=3D'result' type=3D'xsd:st= ring'/></message> + + +Note, there is no complex type in XML schema that could validate the entir= e SOAP message payload. + + + +(a)WebService +(a)SOAPBinding(style =3D SOAPBinding.Style.RPC) +public class JSEBean01 +{ + @WebMethod + @WebResult(name=3D"result") + public String echo(@WebParam(name=3D"String_1") String input) + { + ... + } +} + + + +The element names of RPC parameters/return values may be defined using the= JAX-WS WebParam and WebResult= annotations respectively. + + +
+
RPC/Encoded + +SOAP encodeding style is defined by the infamous chapter 5 of the SOAP-1.1 specification. It has inherent interoperability issues that cannot = be fixed. The Basic Profile-1.0 prohibits = this encoding style in 4.1.7 SOAP encodingS= tyle Attribute. + + +JBossWS has basic support for rpc/encoded that is = provided as is for simple interop scenarios with SOAP stacks tha= t do not support literal encoding. + + +Specifically, JBossWS does not support + + + +element references + + + + +soap arrays as bean properties + + + + +
+ + +
Web Service Endpoi= nts + +JAX-WS simplifies the development model for a web service endpoint a great= deal. In short, an endpoint implementation bean is annotated with JAX-WS a= nnotations and deployed to the server. The server automatically generates a= nd publishes the abstract contract (i.e. wsdl+schema) for client consumptio= n. All marshalling/unmarshalling is delegated to JAXB [2]. = + +
Plain o= ld Java Object (POJO) + +Let's take a look at simple POJO endpoint implementation. All endpoint ass= ociated metadata is provided via JSR-181 annotations + + + + @WebService + @SOAPBinding(style =3D SOAPBinding.Style.RPC) + public class JSEBean01 + { + @WebMethod + public String echo(String input) + { + ... + } + } + + + +The endpoint as a web application + + +A JAX-WS java service endpoint (JSE) is deployed as a web application. + + +<web-app ...><servlet><servlet-name>Test= Service</servlet-name><servlet-class>org.jboss.test.ws.jaxws.sa= mples.jsr181pojo.JSEBean01</servlet-class></servlet><servlet= -mapping><servlet-name>TestService</servlet-name><url-pat= tern>/*</url-pattern></servlet-mapping></web-app> + + +Packaging the endpoint + + +A JSR-181 java service endpoint (JSE) is packaged as a web application in = a *.war file. + + +<war warfile=3D"${build.dir}/libs/jbossws-samples-jsr18= 1pojo.war" webxml=3D"${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.= xml"><classes dir=3D"${build.dir}/classes"><include name=3D"org= /jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/></classes><= /war> + + +Note, only the endpoint implementation bean and web.xml are required. + + +Accessing the generated WSDL + + +A successfully deployed service endpoint will show up in the service endpo= int manager. This is also where you find the links to the generated wsdl. + + + + http://yourhost:8080/jbossws/services + + + +Note, it is also possible to generate the abstract contract off line using= jbossw tools. For details of that please see Bottom-Up (Java to WSDL) + + +
+
E= JB3 Stateless Session Bean (SLSB) + +The JAX-WS programming model support the same set of annotations on EJB3 s= tateless session beans as on Plain old Java Object (POJO) endpoints. EJB-2.1 endpoint= s are supported using the JAX-RPC progamming model. + + + + @Stateless + @Remote(EJB3RemoteInterface.class) + @RemoteBinding(jndiBinding =3D "/ejb3/EJB3EndpointInterface") + + @WebService + @SOAPBinding(style =3D SOAPBinding.Style.RPC) + public class EJB3Bean01 implements EJB3RemoteInterface + { + @WebMethod + public String echo(String input) + { + ... + } + } + + + +Above you see an EJB-3.0 stateless session bean that exposes one method bo= th on the remote interface and on and as an endpoint operation. + + +Packaging the endpoint + + +A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment. + + +<jar jarfile=3D"${build.dir}/libs/jbossws-samples-jsr18= 1ejb.jar"><fileset dir=3D"${build.dir}/classes"><include name= =3D"org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/><include n= ame=3D"org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/>&= lt;/fileset></jar> + + +Accessing the generated WSDL + + +A successfully deployed service endpoint will show up in the service endpo= int manager. This is also where you find the links to the generated wsdl. + + + + http://yourhost:8080/jbossws/services + + + +Note, it is also possible to generate the abstract contract off line using= jbossw tools. For details of that please see Bottom-Up (Java to WSDL) + + +
+
Endpoint Provider</tit= le> +<para> +JAX-WS services typically implement a native Java service endpoint interfa= ce (SEI), perhaps mapped froma WSDL port type, either directly or via the u= se of annotations. = +</para> +<para> +Java SEIs provide a high level Java-centric abstraction that hides the det= ails of converting between Javaobjects and their XML representations for us= e in XML-based messages. However, in some cases it isdesirable for services= to be able to operate at the XML message level. The Provider interface off= ers analternative to SEIs and may be implemented by services wishing to wor= k at the XML message level. +</para> +<para> +A Provider based service instance?s invoke method is called for each messa= ge received for the service. +</para> +<para> +<programlisting> + @WebServiceProvider(wsdlLocation =3D "WEB-INF/wsdl/Provider.wsdl") + @ServiceMode(value =3D Service.Mode.PAYLOAD) + public class ProviderBeanPayload implements Provider<Source> + { + public Source invoke(Source req) + { + // Access the entire request PAYLOAD and return the response PAYLOAD + } + } +</programlisting> +</para> +<para> +Note, Service.Mode.PAYLOAD is the default and does not have to be declared= explicitly. You can also use Service.Mode.MESSAGE to access the entire SOA= P message (i.e. with MESSAGE the Provider can also see SOAP Headers) +</para> +<para> +The abstract contract for a provider endpoint cannot be derived/generated = automatically. Therefore it is necessary to specify the wsdlLocation with t= he @WebServiceProvider annotation. +</para> + +</section> +<section id=3D"User_Guide_WebServiceContext"><title>WebServiceContext</tit= le> +<para> +The WebServiceContext is treated as an injectable resource that can be set= at the time an endpoint isinitialized. The WebServiceContext object will t= hen use thread-local information to return the correctinformation regardles= s of how many threads are concurrently being used to serve requests address= ed to thesame endpoint object. +</para> +<para> +<programlisting> + @WebService + public class EndpointJSE + { + @Resource + WebServiceContext wsCtx; + = + @WebMethod + public String testGetMessageContext() + { + SOAPMessageContext jaxwsContext =3D (SOAPMessageContext)wsCtx.getMessageC= ontext(); + return jaxwsContext !=3D null ? "pass" : "fail"; + } + = + @WebMethod + public String testGetUserPrincipal() + { + Principal principal =3D wsCtx.getUserPrincipal(); + return principal.getName(); + } + = + @WebMethod + public boolean testIsUserInRole(String role) + { + return wsCtx.isUserInRole(role); + } + } +</programlisting> +</para> + +</section> +<section id=3D"User_Guide_Secure_endpoints"><title>Secure endpoints + +Securing an endpoint requires you to set = the authentication configuration. + + +Then you might want to secure the communication between service provider a= nd consumer. This can be done at different levels: + + + +Secure the HTTP transport + + + + + +WS-Security + + + + +
+ +
+
Web Service Clients<= /title> +<section id=3D"User_Guide_Service"><title>Service + +Service is an abstraction that represents a WSDL servic= e. A WSDL service is a collection of related ports, each of which consists = of a port type bound to a particular protocol and available at a particular= endpoint address. + + +For most clients, you will start with a set of stubs generated from the WS= DL. One of these will be the service, and you will create objects of that c= lass in order to work with the service (see "static case" below). + +
Service Usage + +Static case + + +Most clients will start with a WSDL file, and generate some stubs using jb= ossws tools like wsconsume. This usually gives a mass = of files, one of which is the top of the tree. This is the service implemen= tation class. + + +The generated implementation class can be recognised as it will have two p= ublic constructors, one with no arguments and one with two arguments, repre= senting the wsdl location (a java.net.URL) and the servicename (a javax.xml= .namespace.QName) respectively. + + +Usually you will use the no-argument constructor. In this case the WSDL lo= cation and service name are those found in the WSDL. These are set implicit= ly from the WebServiceClient annotation that decorates the generated class. + + +The following code snippet shows the generated constructors from the gener= ated class: + + + + // Generated Service Class + + @WebServiceClient(name=3D"StockQuoteService", targetNamespace=3D"http://e= xample.com/stocks", wsdlLocation=3D"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://exampl= e.com/stocks", "StockQuoteService")); + } + + public StockQuoteService(String wsdlLocation, QName serviceName) = + { + super(wsdlLocation, serviceName); + } + + ... +} + + + +Section Dynamic Proxy ex= plains how to obtain a port from the service and how to invoke an operation= on the port. If you need to work with the XML payload directly or with the= XML representation of the entire SOAP message, have a look at Dispatch. + + +Dynamic case + + +In the dynamic case, when nothing is generated, a web service client uses = Service.create to createService instances, the following= code illustrates this process. + + + + URL wsdlLocation =3D new URL("http://example.org/my.wsdl"); + QName serviceName =3D new QName("http://example.org/sample", "MyService"); + Service service =3D Service.create(wsdlLocation, serviceName); + + + +This is the nastiest way to work with JBossWs. Older versions have extensi= ve details on DII as it was then known. + + +
+
Handler Resolver + +JAX-WS provides a flexible plug-in framework for message processing module= s, known as handlers, that may be used to extend the capabilities of a JAX-= WS runtime system. Handler F= ramework describes the handler framework in detail. A Service instan= ce provides access to a HandlerResolver via a pair of getHandlerResolver/se= tHandlerResolver methods that may be used to configure a set of handlers on= a per-service, per-port or per-protocol binding basis. + + +When a Service instance is used to create a proxy or a Dispatch instance t= hen the handler resolver currently registered with the service is used to c= reate the required handler chain. Subsequent changes to the handler resolve= r configured for a Service instance do not affect the handlers on previousl= y created proxies, or Dispatch instances. + + +[TODO] (JBWS-1512) Provide a sample for Service HandlerResolver + + +
+
Executor + +Service instances can be configured with a java.util.concurrent.Executor. = The executor willthen be used to invoke any asynchronous callbacks requeste= d by the application. The setExecutor andgetExecutor methods of Service can= be used to modify and retrieve the executor configured for aservice. + + +[TODO] (JBWS-1513) Provide a sample for Service Executor + + +
+ +
+
Dynamic Proxy + +You can create an instance of a client proxy using one of getPort methods = on the Service. + + + + /** = + * The getPort method returns a proxy. A service client + * uses this proxy to invoke operations on the target + * service endpoint. The <code>serviceEndpointInterface</code> + * specifies the service endpoint interface that is supported by + * the created dynamic proxy instance. + **/ + public <T> T getPort(QName portName, Class<T> serviceEndpoint= Interface) + { + ... + } + + /** = + * The getPort method returns a proxy. The parameter + * <code>serviceEndpointInterface</code> specifies the service + * endpoint interface that is supported by the returned proxy. + * In the implementation of this method, the JAX-WS + * runtime system takes the responsibility of selecting a protocol + * binding (and a port) and configuring the proxy accordingly. + * The returned proxy should not be reconfigured by the client. + * + **/ + public <T> T getPort(Class<T> serviceEndpointInterface) + { + ... + } + + + +The service endpoint interface (SEI) is usually generated using tools. For= details see Top Down (WSDL to Java) + + +A generated static Service usu= ally also offers typed methods to get ports. These methods also return dyna= mic proxies that implement the SEI. + + + +(a)WebServiceClient(name =3D "TestEndpointService", targetNamespace =3D "h= ttp://org.jboss.ws/wsref", = + wsdlLocation =3D "http://localhost.localdomain:8080/jaxws-samples-webserv= iceref?wsdl") + +public class TestEndpointService extends Service +{ + ... + + public TestEndpointService(URL wsdlLocation, QName serviceName) { + super(wsdlLocation, serviceName); + } + + @WebEndpoint(name =3D "TestEndpointPort") + public TestEndpoint getTestEndpointPort() = + { + return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class); + } +} + + + +
+
WebServiceRef + +The WebServiceRef annotation is used to declare a reference to a Web servi= ce. It follows the resource pattern exemplified by the javax.annotation.Res= ource annotation in JSR-250 [5] + + +There are two uses to the WebServiceRef annotation: + + + +To define a reference whose type is a generated service class. In this cas= e, the type and value element will both refer to the generated service clas= s type. Moreover, if the reference type can be inferred by the field/method= declaration the annotation is applied to, the type and value elements MAY = have the default value (Object.class, that is). If the type cannot be infer= red, then at least the type element MUST be present with a non-default valu= e. + + + + +To define a reference whose type is a SEI. In this case, the type element = MAY be present with its default value if the type of the reference can be i= nferred from the annotated field/method declaration, but the value element = MUST always be present and refer to a generated service class type (a subty= pe of javax.xml.ws.Service). The wsdlLocation element, if present, override= s theWSDL location information specified in the WebService annotation of th= e referenced generated service class. + + + + + +public class EJB3Client implements EJB3Remote +{ + @WebServiceRef + public TestEndpointService service4; + + @WebServiceRef + public TestEndpoint port3; + + + +WebServiceRef Customization + + +In jboss-5.0.x we offer a number of overrides and extensions to the WebSer= viceRef annotation. These include + + + +define the port that should be used to resolve a container-managed port + + + + +define default Stub property settings for Stub objects + + + + +define the URL of a final WSDL document to be used + + + + +Example: + + +<service-ref><service-ref-name>OrganizationSer= vice</service-ref-name><wsdl-override>file:/wsdlRepository/orga= nization-service.wsdl</wsdl-override></service-ref><service-= ref><service-ref-name>OrganizationService</service-ref-name>= <config-name>Secure Client Config</config-name><config-file&= gt;META-INF/jbossws-client-config.xml</config-file><handler-chain&= gt;META-INF/jbossws-client-handlers.xml</handler-chain></service-r= ef><service-ref><service-ref-name>SecureService</service-= ref-name><service-class-name>org.jboss.tests.ws.jaxws.webservicere= f.SecureEndpointService</service-class-name><service-qname>{htt= p://org.jboss.ws/wsref}SecureEndpointService</service-qname><port-= info><service-endpoint-interface>org.jboss.tests.ws.jaxws.webservi= ceref.SecureEndpoint</service-endpoint-interface><port-qname>{h= ttp://org.jbos! s.ws/wsref}SecureEndpointPort</port-qname><stub-property><n= ame>javax.xml.ws.security.auth.username</name><value>kermit&= lt;/value></stub-property><stub-property><name>javax.x= ml.ws.security.auth.password</name><value>thefrog</value>= </stub-property></port-info></service-ref> + + +For details please see service-ref_5_0.dtd in the jboss docs directory. + + +
+
Dispatch + +XMLWeb Services use XML messages for communication between services and se= rvice clients. The higher level JAX-WS APIs are designed to hide the detail= s of converting between Java method invocations and the corresponding XML m= essages, but in some cases operating at the XML message level is desirable.= The Dispatch interface provides support for this mode of interaction. + + +Dispatch supports two usage modes, identified by the constants javax.xml.w= s.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively: + + +Message In this mode, client applicatio= ns work directly with protocol-specific message structures. E.g., when used= with a SOAP protocol binding, a client application would work directly wit= h a SOAP message. + + +Message Payload In this mode, client ap= plications work with the payload of messages rather than the messages thems= elves. E.g., when used with a SOAP protocol binding, a client application w= ould work with the contents of the SOAP Body rather than the SOAP message a= s a whole. + + +Dispatch is a low level API that requires clients to construct messages or= message payloads as XML and requires an intimate knowledge of the desired = message or payload structure. Dispatch is a generic class that supports inp= ut and output of messages or message payloads of any type. + + + + Service service =3D Service.create(wsdlURL, serviceName); + Dispatch dispatch =3D service.createDispatch(portName, StreamSource.class= , Mode.PAYLOAD); + + String payload =3D "<ns1:ping xmlns:ns1=3D'http://oneway.samples.jaxws= .ws.test.jboss.org/'/>"; + dispatch.invokeOneWay(new StreamSource(new StringReader(payload))); + + payload =3D "<ns1:feedback xmlns:ns1=3D'http://oneway.samples.jaxws.ws= .test.jboss.org/'/>"; + Source retObj =3D (Source)dispatch.invoke(new StreamSource(new StringRead= er(payload))); + + + +
+
Asynchronous In= vocations + +The BindingProvider interface represents a component that provides a proto= col binding for use by clients, it is implemented by proxies and is extende= d by the Dispatch interface. + + + + + + + +Binding Provider Class Relationships + + + + + +BindingProvider instances may provide asynchronous operation capabilities.= When used, asynchronous operation invocations are decoupled from the Bindi= ngProvider instance at invocation time such that the response context is no= t updated when the operation completes. Instead a separate response context= is made available using the Response interface. + + + + public void testInvokeAsync() throws Exception + { + URL wsdlURL =3D new URL("http://" + getServerHost() + ":8080/jaxws-sample= s-asynchronous?wsdl"); + QName serviceName =3D new QName(targetNS, "TestEndpointService"); + Service service =3D Service.create(wsdlURL, serviceName); + TestEndpoint port =3D service.getPort(TestEndpoint.class); + + Response response =3D port.echoAsync("Async"); + + // access future + String retStr =3D (String) response.get(); + assertEquals("Async", retStr); + } + + + +
+
Oneway Invocations</t= itle> +<para> +(a)Oneway indicates that the given web method has only an input message an= d no output. Typically, a oneway method returns the thread of control to th= e calling application prior to executing the actual business method. = +</para> +<para> +<programlisting> +(a)WebService (name=3D"PingEndpoint") +(a)SOAPBinding(style =3D SOAPBinding.Style.RPC) +public class PingEndpointImpl +{ + private static String feedback; + = + @WebMethod + @Oneway + public void ping() + { + log.info("ping"); + feedback =3D "ok"; + } + = + @WebMethod + public String feedback() + { + log.info("feedback"); + return feedback; + } +} +</programlisting> +</para> + +</section> +<section id=3D"User_Guide_JMS_Transport_Clients"><title>JMS Transport Clie= nts + +Since 2.0.3 + + +Since jbossws-2.0.3 we support JAX-WS clients that use JMS transport. + + +JMS transport is activated on the client side when the endpoint location u= ses the 'jms' URL schema + + +<binding name=3D'JMSBinding' type=3D'tns:OrganizationJM= SEndpoint'><soap:binding style=3D'rpc' transport=3D'http://www.exampl= e.org/2006/06/soap/bindings/JMS/'/><operation name=3D'getContactInfo'= ><soap:operation soapAction=3D''/><input><soap:body names= pace=3D'http://org.jboss.ws/samples/jmstransport' use=3D'literal'/></= input><output><soap:body namespace=3D'http://org.jboss.ws/sampl= es/jmstransport' use=3D'literal'/></output></operation></= binding><service name=3D'OrganizationJMSEndpointService'><port = binding=3D'tns:JMSBinding' name=3D'JMSEndpointPort'><soap:address loc= ation=3D'jms://queue/RequestQueue?replyToName=3Dqueue/ResponseQueue'/>&l= t;/port></service> + + +The service that implements the JMS remote connection is loaded using the = key + + + + org.jboss.ws.core.client.RemoteConnection.jms + + + +Like any other service, this can be overwritten using a system property. + + +The JAX-WS client code is essentially no different from a client using HTT= P as transport + + + + public void testJMSEndpointPort() throws Exception + { + URL wsdlURL =3D new File("resources/jaxws/samples/jmstransport/jmsservice= .wsdl").toURL(); + QName serviceName =3D new QName("http://org.jboss.ws/samples/jmstransport= ", "OrganizationJMSEndpointService"); + QName portName =3D new QName("http://org.jboss.ws/samples/jmstransport", = "JMSEndpointPort"); + = + Service service =3D Service.create(wsdlURL, serviceName); + Organization port =3D service.getPort(portName, Organization.class); + = + String res =3D port.getContactInfo("mafia"); + assertEquals("The 'mafia' boss is currently out of office, please call ag= ain.", res); + } + + + +
+ + +
Common API + +This sections describes concepts that apply equally to Web Service Endpoints and Web Service Clients + +
Handler Framework</tit= le> +<para> +The handler framework is implemented by a JAX-WS protocol binding in both = client and server side runtimes. Proxies, and Dispatch instances, known col= lectively as binding providers, each use protocol bindings to bind their ab= stract functionality to specific protocols. +</para> +<para> +Client and server-side handlers are organized into an ordered list known a= s a handler chain. The handlers within a handler chain are invoked each tim= e a message is sent or received. Inbound messages are processed by handlers= prior to binding provider processing. Outbound messages are processed by h= andlers after any binding provider processing. +</para> +<para> +Handlers are invoked with a message context that provides methods to acces= s and modify inbound and outbound messages and to manage a set of propertie= s. Message context properties may be used to facilitate communication betwe= en individual handlers and between handlers and client and service implemen= tations. Different types of handlers are invoked with different types of me= ssage context. +</para> +<para> +<mediaobject> +<imageobject> +<imagedata fileref=3D"http://jbws.dyndns.org/mediawiki/images/0/07/Binding= -handler.gif"/> +</imageobject> +<textobject> +<phrase/> +</textobject> +</mediaobject> + +</para> +<section id=3D"User_Guide_Logical_Handler"><title>Logical Handler + +Handlers that only operate on message context properties and message paylo= ads. Logical handlersare protocol agnostic and are unable to affect protoco= l specific parts of a message. Logical handlersare handlers that implement = javax.xml.ws.handler.LogicalHandler. + + +
+
Protocol Handler + +Handlers that operate on message context properties and protocol specific = messages. Protocol handlers are specific to a particular protocol and may a= ccess and change protocol specific aspects of a message. Protocol handlers = are handlers that implement any interface derived from javax.xml.ws.handler= .Handler except javax.xml.ws.handler.LogicalHandler. + + +
+
Service endpoi= nt handlers + +On the service endpoint, handlers are defined using the @HandlerChain anno= tation. + + + +(a)WebService +(a)HandlerChain(file =3D "jaxws-server-source-handlers.xml") +public class SOAPEndpointSourceImpl +{ + ... +} + + + +The location of the handler chain file supports 2 formats + + +1. An absolute java.net.URL in externalForm.(ex: http://myhandlers.foo.com= /handlerfile1.xml) + + +2. A relative path from the source file or class file.(ex: bar/handlerfile= 1.xml) + + +
+
Service client h= andlers + +On the client side, handler can be configured using the @HandlerChain anno= tation on the SEI or dynamically using the API. + + + + Service service =3D Service.create(wsdlURL, serviceName); + Endpoint port =3D (Endpoint)service.getPort(Endpoint.class); + = + BindingProvider bindingProvider =3D (BindingProvider)port; + List<Handler> handlerChain =3D new ArrayList<Handler>(); + handlerChain.add(new LogHandler()); + handlerChain.add(new AuthorizationHandler()); + handlerChain.add(new RoutingHandler()); + bindingProvider.getBinding().setHandlerChain(handlerChain); // important! + + + +
+ +
+
Message Context + +MessageContext is the super interface for all JAX-WS message contexts. It = extends Map<String,Object> with additional methods and constants to m= anage a set of properties that enable handlers in a handler chain to share = processing related state. For example, a handler may use the put method to = insert a property in the message context that one or more other handlers in= the handler chain may subsequently obtain via the get method. + + +Properties are scoped as either APPLICATION or HANDLER. All properties are= available to all handlers for an instance of an MEP on a particular endpoi= nt. E.g., if a logical handler puts a property in the message context, that= property will also be available to any protocol handlers in the chain duri= ng the execution of an MEP instance. APPLICATION scoped properties are also= made available to client applications (see section 4.2.1) and service endp= oint implementations. The defaultscope for a property is HANDLER. + +
Accessing = the message context + +There is currently no portable way of doing this in 4.0.5. @WebSe= rviceContext injection will be available with 4.2. In the meantim= e you can access the message context like this: = + + + +CommonMessageContext msgContext =3D MessageContextAssociation.peekMessageC= ontext(); = +msgContext.setProperty(<Name>, <Value>); + + + +
+
Logical Message = Context + +Logical handlers are p= assed a message context of type LogicalMessageContext when invoked. Logical= MessageContext extends MessageContext with methods to obtain and modify the= message payload, it does not provide access to the protocol specific aspec= ts of amessage. A protocol binding defines what component of a message are = available via a logical message context. The SOAP binding defines that a lo= gical handler deployed in a SOAP binding can access the contents of the SOA= P body but not the SOAP headers whereas the XML/HTTP binding defines that a= logical handler can access the entire XML payload of a message. + + +
+
SOAP Message Contex= t + +SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageCon= text extends MessageContext with methods to obtain and modify the SOAP mess= age payload. + + +
+ +
+
Fault Handling + +An implementation may thow a SOAPFaultException + + + + public void throwSoapFaultException() + { + SOAPFactory factory =3D SOAPFactory.newInstance(); + SOAPFault fault =3D factory.createFault("this is a fault string!", new QN= ame("http://foo", "FooCode")); + fault.setFaultActor("mr.actor"); + fault.addDetail().addChildElement("test"); + throw new SOAPFaultException(fault); + } + + + +or an application specific user exception + + + + public void throwApplicationException() throws UserException + { + throw new UserException("validation", 123, "Some validation error"); + } + + + +Note + + +In case of the latter JBossWS generates the required fault wrapper beans a= t runtime if they are not part of the deployment + + +
+ + +
DataBinding +
Us= ing JAXB with non annotated classes + +Since 2.0.2 + + +JAXB is heavily driven by Java Annotations on the Java Bindings. It curren= tly doesn't support an external binding configuration. This recently became= an issue for us on JBossESB since the JBossWS 2.0.0 native SOAP stack uses= JAXB to perform the SOAP to Java bindings (see 1, 2). It's an issue for JB= ossESB simply because it needs to be able to support user definition of JBo= ssWS native Webservice Endpoints (e.g. JSR 181) using Java typesets that ha= ve not been "JAXB Annotated" (see JAXB Introductions On JBossWS). + + +In order to support this, we built on a JAXB RI feature whereby it allows = you to specify a RuntimeInlineAnnotationReader implementation during JAXBCo= ntext creation (see JAXBRIContext). + + +We call this feature "JAXB Annotation Introduction" and we've made it avai= lable for general consumption i.e. it can be checked out, built and used fr= om SVN: + + + +http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/ + + + + +Complete documentation can be found here: = + + + +http://wiki.jboss.org/wiki/Wiki.jsp?page=3DJAXBIntroductions + + + + +
+ +
+
Attachments +
MTOM/XOP + +This chapter describes Message Transmission Optimization Mechanism (MTOM) = and XML-binary Optimized Packaging (XOP), a means of more efficiently seria= lizing XML Infosets that have certain types of content. The related specifi= cations are = + + + +SOAP Message T= ransmission Optimization Mechanism (MTOM) + + + + +XML-binary Optimized= Packaging (XOP) + + + +
Supported= MTOM parameter types + +<tgroup cols=3D"2"><tbody><row> +<entry> +image/jpeg +</entry> +<entry> +java.awt.Image +</entry> + +</row> +<row> +<entry> +text/xml +</entry> +<entry> +javax.xml.transform.Source +</entry> + +</row> +<row> +<entry> +application/xml +</entry> +<entry> +javax.xml.transform.Source +</entry> + +</row> +<row> +<entry> +application/octet-stream +</entry> +<entry> +javax.activation.DataHandler +</entry> + +</row> +</tbody></tgroup> +</table> +<para> +<programlisting/> +</para> +<para> +The above table shows a list of supported endpoint parameter types. The re= commended approach is to use the <ulink url=3D"http://java.sun.com/j2ee/1.4= /docs/api/javax/activation/DataHandler.html"><citetitle>javax.activation.Da= taHandler</citetitle></ulink> classes to represent binary data as service e= ndpoint parameters. +</para> +<para> +<emphasis role=3D"bold">Note</emphasis> +</para> +<para> +Microsoft endpoints tend to send any data as application/octet-stream. The= only Java type that can easily cope with this ambiguity is javax.activatio= n.DataHandler +</para> + +</section> +<section id=3D"User_Guide_Enabling_MTOM_per_endpoint"><title>Enabling MTOM= per endpoint + +On the server side MTOM processing is enabled through the @Bindin= gType annotation.JBossWS does handle SOAP1.1 and SOAP1.2. Both co= me with or without MTOM flavours: + + + MTOM enabled service implementations + + + +package org.jboss.test.ws.jaxws.samples.xop.doclit; + +import javax.ejb.Remote; +import javax.jws.WebService; +import javax.jws.soap.SOAPBinding; +import javax.xml.ws.BindingType; + +(a)Remote +(a)WebService(targetNamespace =3D "http://org.jboss.ws/xop/doclit") +(a)SOAPBinding(style =3D SOAPBinding.Style.DOCUMENT, parameterStyle =3D SO= APBinding.ParameterStyle.BARE) +(a)BindingType(value=3D"http://schemas.xmlsoap.org/wsdl/soap/http?mtom=3Dt= rue") (1) +public interface MTOMEndpoint { + + [...] +} + + + + +The MTOM enabled SOAP 1.1 binding ID + + + + + MTOM enabled clients + + +Web service clients can use the same approach described above or rely on t= he Binding API to enable MTOM(Excerpt taken from the org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase): + + + +[...] +Service service =3D Service.create(wsdlURL, serviceName); +port =3D service.getPort(MTOMEndpoint.class); + +// enable MTOM +binding =3D (SOAPBinding)((BindingProvider)port).getBinding(); +binding.setMTOMEnabled(true); + + + + +Note + + +You might as well use the JBossWS configuration templates to setup deploym= ent defaults. + + + + + +
SwaRef + +Since 2.0 + + +WS-I Attachment Profile 1.0 defines= mechanism to reference MIME attachment parts using swaRef. In t= his mechanism the content of XML element of type wsi:swaRef is sent as MIME= attachment and the element inside SOAP Body holds the reference to this at= tachment in the CID URI scheme as defined by RFC 2111. + +
Using= SwaRef with JAX-WS endpoints + +JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. T= he most simple way to enable SwaRef encoding for DataHandler types is to annotate a payload bean with the @XmlAttachmentRe= f annotation as shown below: + + + +/** +* Payload bean that will use SwaRef encoding +*/ +(a)XmlRootElement +public class DocumentPayload +{ + private DataHandler data; + + public DocumentPayload() + { + } + + public DocumentPayload(DataHandler data) + { + this.data =3D data; + } + = + @XmlElement + @XmlAttachmentRef + public DataHandler getData() + { + return data; + } + + public void setData(DataHandler data) + { + this.data =3D data; + } +} + + + +With document wrapped endpoints you may even specify the @XmlAtta= chmentRef annotation on the service endpoint interface: + + + +(a)WebService +public interface DocWrappedEndpoint +{ + @WebMethod + DocumentPayload beanAnnotation(DocumentPayload dhw, String test); + + @WebMethod + @XmlAttachmentRef + DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, Strin= g test); + +} + + + +The message would then refer to the attachment part by CID: + + +<env:Envelope xmlns:env=3D'http://schemas.xmlsoap.org/s= oap/envelope/'><env:Header/><env:Body><ns2:parameterAnnot= ation xmlns:ns2=3D'http://swaref.samples.jaxws.ws.test.jboss.org/'><a= rg0>cid:0-1180017772935-32455963(a)ws.jboss.org</arg0><arg1>= Wrapped test</arg1></ns2:parameterAnnotation></env:Body>&= lt;/env:Envelope> + + +
+
Starting from WSDL</t= itle> +<para> +If you chose the contract first approach then you need to ensure that any = element declaration that should use SwaRef encoding simply refers to wsi:sw= aRef schema type: +</para> +<para> +<programlisting><element name=3D"data" type=3D"wsi:swaRef" = +xmlns:wsi=3D"http://ws-i.org/profiles/basic/1.1/xsd"/></programlisting> +</para> +<para> +Any wsi:swaRef schema type would then be mapped to DataHandler. +</para> + +</section> + +</section> + +</section> +<section id=3D"User_Guide_Tools"><title>Tools +
JAX-WS tools + +Please refer to JBossWS_JAX-WS_Tool= s for details. This covers directions on web service contract genera= tion (bottom-up development) and consumption (top-down and client developme= nt). + + +
+
Management tools + +JBoss and its web service framework come with some tools allowing WS endpo= int management. + + +Please refer the Endpoint management= page for an overview of the available tools. In particular the Records management system gives adm= inistrators a means of performing custom analysis of their web service traf= fic as well as exporting communication logs. + + +
+ +
+
Web Service Exten= sions +
WS-Addressing + +This section describes how WS-Addressing can be used to provide a sta= teful service endpoint. + +
Specifications + +WS-Addressing is defined by a combination of the following specifications = from the W3C Candidate Recommendation 17 August 2005. The WS-Addressing API= is standardized by JSR-261 - Java API for XML Web Services Addressing= + + + +Web Services A= ddressing 1.0 - Core + + + + +Web Services A= ddressing 1.0 - SOAP Binding + + + + +
+
Addressing Endpoint<= /title> +<para> +The following endpoint implementation has a set of operation for a typical= stateful shopping chart application. +</para> +<para> +<programlisting> + @WebService(name =3D "StatefulEndpoint", targetNamespace =3D "http://org.= jboss.ws/samples/wsaddressing", serviceName =3D "TestService") + @EndpointConfig(configName =3D "Standard WSAddressing Endpoint") + @HandlerChain(file =3D "WEB-INF/jaxws-handlers.xml") + @SOAPBinding(style =3D SOAPBinding.Style.RPC) + public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLif= ecycle + { + @WebMethod + public void addItem(String item) + { ... } + = + @WebMethod + public void checkout() + { ... } + = + @WebMethod + public String getItems() + { ... } + } +</programlisting> +</para> +<para> +It uses the <link linkend=3D"JAX_WS_Endpoint_Configuration_Standard_WSAddr= essing_Endpoint">Standard WSAddressing Endpoint</link> to enable the server= side addressing handler. It processes the incomming WS-Addressing header e= lements and provides access to them through the JSR-261 API. +</para> +<para> +The endpoint handler chain +</para> +<para> +<programlisting><handler-chains xmlns=3D"http://java.sun.com/xml/ns/jav= aee" xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://java.sun.com/xml/ns/javaee javaee_web_servic= es_1_2.xsd"><handler-chain><protocol-bindings>##SOAP11_HTTP&= lt;/protocol-bindings><handler><handler-name>Application Ser= ver Handler</handler-name><handler-class>org.jboss.test.ws.jaxw= s.samples.wsaddressing.ServerHandler</handler-class></handler>&= lt;/handler-chain></handler-chains></programlisting> +</para> +<para> +defines an application specific hander that assignes/processes stateful cl= ient ids. +</para> + +</section> +<section id=3D"User_Guide_Addressing_Client"><title>Addressing Client</tit= le> +<para> +On the client side there are simmilar handlers that does the reverse. It u= ses the JSR-261 API to add WS-Addressing header elements including the clie= ntid association.<programlisting> </programlisting> +</para> +<para> +The client sets a custom handler chain in the binding<programlisting> </pr= ogramlisting> +</para> +<para> +<programlisting> + Service service =3D Service.create(wsdlURL, serviceName); + port1 =3D (StatefulEndpoint)service.getPort(StatefulEndpoint.class); + BindingProvider bindingProvider =3D (BindingProvider)port1; + + List<Handler> customHandlerChain =3D new ArrayList<Handler>(); + customHandlerChain.add(new ClientHandler()); + customHandlerChain.add(new WSAddressingClientHandler()); + bindingProvider.getBinding().setHandlerChain(customHandlerChain); +</programlisting><programlisting> </programlisting> +</para> +<para> +The WSAddressingClientHandler is provided by JBossWS and reads/writes the = addressing properties and puts then into the message context. +</para> +<para> +<emphasis role=3D"bold">A client connecting to the stateful endpoint</emph= asis> +</para> +<para> +<programlisting> + public class AddressingStatefulTestCase extends JBossWSTest + { + public void testAddItem() throws Exception + { + port1.addItem("Ice Cream"); + port1.addItem("Ferrari"); + = + port2.addItem("Mars Bar"); + port2.addItem("Porsche"); + } + = + public void testGetItems() throws Exception + { + String items1 =3D port1.getItems(); + assertEquals("[Ice Cream, Ferrari]", items1); + = + String items2 =3D port2.getItems(); + assertEquals("[Mars Bar, Porsche]", items2); + } + } +</programlisting> +</para> +<para> +<emphasis role=3D"bold">SOAP message exchange</emphasis> +</para> +<para> +Below you see the SOAP messages that are beeing exchanged. = +</para> +<para> +<programlisting><env:Envelope xmlns:env=3D'http://schemas.xmlsoap.org/s= oap/envelope/'><env:Header xmlns:wsa=3D'http://schemas.xmlsoap.org/ws= /2004/08/addressing'><wsa:To>uri:jbossws-samples-wsaddr/TestServic= e</wsa:To><wsa:Action>http://org.jboss.ws/addressing/stateful/a= ction</wsa:Action><wsa:ReferenceParameters><ns1:clientid xml= ns:ns1=3D'http://somens'>clientid-1</ns1:clientid></wsa:Referen= ceParameters></env:Header><env:Body><ns1:addItem xmlns:ns= 1=3D'http://org.jboss.ws/samples/wsaddr'><String_1>Ice Cream</S= tring_1></ns1:addItem></env:Body></env:Envelope><en= v:Envelope xmlns:env=3D'http://schemas.xmlsoap.org/soap/envelope/'><e= nv:Header xmlns:wsa=3D'http://schemas.xmlsoap.org/ws/2004/08/addressing'>= ;<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>= ;<wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</= wsa:Action><ns1:clie! ntid xmlns:ns1=3D'http://somens'>clientid-1</ns1:clientid></en= v:Header><env:Body><ns1:addItemResponse xmlns:ns1=3D'http://org= .jboss.ws/samples/wsaddr'/></env:Body></env:Envelope> + = + ... + = +<env:Envelope xmlns:env=3D'http://schemas.xmlsoap.org/soap/envelope/'&g= t;<env:Header xmlns:wsa=3D'http://schemas.xmlsoap.org/ws/2004/08/address= ing'><wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>= <wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Ac= tion><wsa:ReferenceParameters><ns1:clientid xmlns:ns1=3D'http:/= /somens'>clientid-1</ns1:clientid></wsa:ReferenceParameters>= </env:Header><env:Body><ns1:getItems xmlns:ns1=3D'http://org= .jboss.ws/samples/wsaddr'/></env:Body></env:Envelope><env= :Envelope xmlns:env=3D'http://schemas.xmlsoap.org/soap/envelope/'><en= v:Header xmlns:wsa=3D'http://schemas.xmlsoap.org/ws/2004/08/addressing'>= <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>= <wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</w= sa:Action><ns1:clientid xmlns:ns1=3D'http://somens'>clientid-1<= /ns1:clientid></env:He! ader><env:Body><ns1:getItemsResponse xmlns:ns1=3D'http://org.j= boss.ws/samples/wsaddr'><result>[Ice Cream, Ferrari]</result>= ;</ns1:getItemsResponse></env:Body></env:Envelope></progr= amlisting> +</para> + +</section> + +</section> +<section id=3D"User_Guide_WS_BPEL"><title>WS-BPEL + +WS-BPEL is not supported with JAX-WS, please refer to JAX-RPC User Guide#W= S-BPEL. + + +
+
WS-Eventing + +WS-Eventing specifies a set of operations that allow an event consumer to = register (subscribe) with an event producer (source) to receive events (not= ifications) in an asynchronous fashion. = + +
Specifications + +WS-Eventing is defined by the combination of the following specifications: + + + +WS-Eventing specification + + + + +WS-Addressing = Specifications + + + + +The following section will introduce the main eventing actors and their re= sponsiblities. = + + +Note + + +The original eventing specification builds upon WS-Addressing 2004/08. JBo= ssWS however decided to stick to the latest version, which is the W3C candi= date release. + + +
+
Collaboration + + + + + + +Eventing collaboration + + + + + + +An event sink (web service client) sends a subscribtion request to the eve= nt source endpoint. This includes the event sink endpoint address where not= ifications should delivered. Upon successful subscription the sink receives= a leased subscription ID that can be used to identify the client in subseq= uent requests. = + + + + +A successfully registered event sink directs management requests (Renew, G= etStatus, Unsubscribe) to the subscription manager endpoint using the previ= ously received subscription ID. The subscription manager endpoint address w= as returned as part of the subscription response in the first place. = + + + + +The actual event sink (application) emits notification messages through th= e JBossWS-Eventing module. JBossWS-Eventing dispatches the notification to = any subscriber endpoint that is registered with a particular event source.s = + + + + +Besides notifications JBossWS-Eventing may emit lifecycle events at any ti= me, i.e. to inform an event sink that a subscription was canceled. This can= be the case when the subscription expired or the event source was undeploy= ed. = + + + + +It is the users responsibilty to supply the web service endpoints (EventSo= urceEndpoint, SubscriptionManagerEndpoint) that are required for a complete= event source deployment. Fortunatly JBossWS-Eventing already ships with a = implementation that can be used right away. All that's left todo is packagi= ng of standard JSR-109 deployment archive that includes the event source sp= ecific WSDL and points to the JBossWS-Eventing endpoint implementations. = + + +The relevant steps are: = + + + +Create a custom WSDL that describes your event source, in respect to the n= otification schema (1) and the fact that is actually contains an event sour= ce port (2) + + + + +Use the JBossWS SEI (3) and endpoint (4) implementations (webservices.xml,= web.xml). + + + + +
+
Setup an = event source endpoint + +With JAX-WS the event source setup has actually become quiet easy. All you= need to do is to subclass your endpoint implementation from Abstr= actEventSourceEndpoint and a subscription manager from A= bstractSubscriptionManagerEndpoint and finally point that impleme= ntation to a event source specific WSDL. + + + +package org.jboss.test.ws.jaxws.samples.wseventing; + +import javax.jws.WebService; + +import org.jboss.logging.Logger; +import org.jboss.ws.annotation.EndpointConfig; +import org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint; + +/** + * @author Heiko.Braun(a)jboss.org + * @version $Id$ + * @since 18.01.2007 + */ +(a)WebService( (1) + name =3D "EventSource", + portName =3D "EventSourcePort", + targetNamespace =3D "http://schemas.xmlsoap.org/ws/2004/08/eventing", + wsdlLocation =3D "/WEB-INF/wsdl/sysmon.wsdl", (2) + endpointInterface =3D "org.jboss.ws.extensions.eventing.jaxws.EventSource= Endpoint") +(a)EndpointConfig(configName =3D "Standard WSAddressing Endpoint") (3) +public class SysmonRegistrationEndpoint extends AbstractEventSourceEndpoin= t { (4) + + private static final Logger log =3D Logger.getLogger(SysmonRegistrationEn= dpoint.class); + + protected Logger getLogger() + { + return log; + } +} + + + + + +Of course we need a @WebService annotation + + + + +It's important to override the WSDL here = + + + + +You need to tell JBossWS that it requires WS-Addressing for this endpoint + + + + +Subclass a predefined implementation that knows how to delegate to the act= ual eventing service implementation + + + + +
+
= The WSDL that describes an event source + +Even though we are already using the annotation driven approach, JBossWS e= venting still requires an event source specific WSDL. = + + +The following excerpt shows the relevant WSDL details that describe an eve= nt source. = + + +<?xml version=3D"1.0" encoding=3D"UTF-8"?><wsdl:d= efinitions + targetNamespace=3D"http://www.jboss.org/sysmon" + xmlns:tns=3D"http://www.jboss.org/sysmon" + xmlns:wse=3D'http://schemas.xmlsoap.org/ws/2004/08/eventing' + xmlns:wsdl=3D'http://schemas.xmlsoap.org/wsdl/' + xmlns:wsa10=3D'http://www.w3.org/2005/08/addressing' + xmlns:xs=3D'http://www.w3.org/2001/XMLSchema' + xmlns:soap=3D"http://schemas.xmlsoap.org/wsdl/soap/"><wsdl:import +(1) namespace=3D'http://schemas.xmlsoap.org/ws/2004/08/eventing' + location=3D'jbwse.wsdl' /><wsdl:types><xs:schema targetNamesp= ace=3D'http://schemas.xmlsoap.org/ws/2004/08/eventing'> +(2) <xs:include schemaLocation=3D'jbwse.xsd'/></xs:schema> + +(3) <xs:schema + targetNamespace=3D"http://www.jboss.org/sysmon" + elementFormDefault=3D"qualified" + blockDefault=3D"#all"><xs:element name=3D"SystemStatus"><xs:c= omplexType><xs:sequence><xs:element name=3D"Time " type=3D"xs:d= ateTime"/><xs:element name=3D"HostName" type=3D"xs:string"/><xs= :element name=3D"HostAddress" type=3D"xs:string"/><xs:element name=3D= "ActiveThreadCount" type=3D"xs:int"/><xs:element name=3D"FreeMemory" = type=3D"xs:string"/><xs:element name=3D"MaxMemory" type=3D"xs:string"= /></xs:sequence></xs:complexType></xs:element></xs:= schema></wsdl:types><wsdl:message name=3D'SystemInfoMsg'><= ;wsdl:part name=3D'body' element=3D'tns:SystemStatus'/></wsdl:message= > + +(4) <wsdl:portType name=3D'SystemInfo' wse:EventSource=3D'true'><= wsdl:operation name=3D'SysmonOp'><wsdl:output message=3D'tns:SystemIn= foMsg'/></wsdl:operation></wsdl:portType><wsdl:binding na= me=3D"SystemInfoBinding" type=3D"tns:SystemInfo"><soap:binding style= =3D"document" transport=3D"http://schemas.xmlsoap.org/soap/http"/><ws= dl:operation name=3D"SysmonOp"><soap:operation soapAction=3D""/>&l= t;wsdl:output><soap:body use=3D"literal"/></wsdl:output><= /wsdl:operation></wsdl:binding></wsdl:definitions> + + + +Import the default eventing WSDL, that includes service and port declarati= ons. + + + + +Include the default eventing Types + + + + +Specifiy the notitification message schema. + + + + +Declare a port type, attributed "wse:EventSource=3D'true'" that points to = your notification message schema. + + + + +
+
Emitting notifica= tions + +JBossWS-Eventing registeres a event dispatcher within local JNDI tree that= can be used to emit notifications from applications. + java:/EventDispatcher + + + +The event dispatcher interface: + public interface EventDispatcher + { + void dispatch(URI eventSourceNS, Element payload); + } + + + + Example notification + + + + +(1) URI eventSourceURI =3D new URI("http://http://www.jboss.org/sysmon/Sys= temInfo"); +(2) Element payload =3D DOMUtils.parse("SOME XML STRING"); + try + { + InitialContext iniCtx =3D getInitialContext(); +(3) EventDispatcher delegate =3D (EventDispatcher) + iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME); +(4) delegate.dispatch(eventSourceURI, payload); + } + catch (Exception e) + { + // + } + + + + + +Address your event source correctly (TargetNamespace+PortTypeName) + + + + +Create your payload + + + + +Lookup dispatcher from JNDI + + + + +Dispatch notification. + + + + +The SubscriptionManager MBean is the actual core component that drives the= JBossWS-Eventing implementation. It can be accessed through the jmx-consol= e. + jboss.ws.eventing:service=3DSubscriptionManager + + + +Management operations exist to monitor and maintain active subscritions an= d deployed event sources. The current implementation is backed by a ThreadP= oolExecutor, that asynchronously delivers messages to event sink endpoints.= It can be configured through the following attributes: = + + + +corePoolSize - average number of idle threads + + + + +maximumPoolSize - maximum number of threads + + + + +eventKeepAlive - keep alive before an undelivered event message is discard= ed. + + + + +
+ +
+
WS-Security + +WS-Security addresses message level security. It standardizes authorizatio= n, encryption, and digital signature processing of web services. Unlike tra= nsport security models, such as SSL, WS-Security applies security directly = to the elements of the web service message. This increases the flexibility = of your web services, by allowing any message model to be used (point to po= int, multi-hop relay, etc). = + + +This chapter describes how to use WS-Security to sign and encrypt a simple= SOAP message. + + +Specifications + + +WS-Security is defined by the combination of the following specifications: + + + +SOAP Message Security 1.0= + + + + +Username Token Profile 1.0 + + + + +X.509 Token Profile 1.0 + + + + +W3C XML Encrypt= ion + + + + +W3C XML Signat= ure + + + + += Basic Security Profile 1.0 (Still in Draft) + + + +
Endpoint configur= ation + +JBossWS uses handlers to identify ws-security encoded requests and invoke = the security components to sign and encrypt messages. In order to enable se= curity processing, the client and server side need to include a correspondi= ng handler configuration. The preferred way is to reference a predefined JAX-WS_Endpoint_Configuration= or JAX-WS_Client_Conf= iguration respectively. + + +Note + + +You need to setup both the endpoint configuration and the WSSE declaration= s.That's two separate steps. + + +
+
Server side WSSE declaration (jboss-wsse-server.xml)</titl= e> +<para> +In this example we configure both the client and the server to sign the me= ssage body. Both also require this from each other. So, if you remove eithe= r the client or the server security deployment descriptor, you will notice = that the other party will throw a fault explaining that the message did not= conform to the proper security requirements. +</para> +<para> +<programlisting><jboss-ws-security xmlns=3D"http://www.jboss.com/ws-sec= urity/config" = + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://www.jboss.com/ws-security/config = + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> + (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file> + (2) <key-store-password>jbossws</key-store-password> + (3) <trust-store-file>WEB-INF/wsse.truststore</trust-store-file&= gt; + (4) <trust-store-password>jbossws</trust-store-password> + (5) <config> + (6) <sign type=3D"x509v3" alias=3D"wsse"/> + (7) <requires> + (8) <signature/></requires></config></jboss-ws-secur= ity></programlisting> +</para> +<orderedlist numeration=3D"arabic"><listitem> +<para> +This specifies that the key store we wish to use is WEB-INF/wsse.keystore,= which is located in our war file. +</para> +</listitem> +<listitem> +<para> +This specifies that the store password is "jbossws". Password can be encyp= ted using the {EXT} and {CLASS} commands. Please see samples for their usag= e. +</para> +</listitem> +<listitem> +<para> +This specifies that the trust store we wish to use is WEB-INF/wsse.trustst= ore, which is located in our war file. +</para> +</listitem> +<listitem> +<para> +This specifies that the trust store password is also "jbossws". Password c= an be encrypted using the {EXT} and {CLASS} commands. Please see samples fo= r their usage. +</para> +</listitem> +<listitem> +<para> +Here we start our root config block. The root config block is the default = configuration for all services in this war file. +</para> +</listitem> +<listitem> +<para> +This means that the server must sign the message body of all responses. Ty= pe means that we are to use a X.509v3 certificate (a standard certificate).= The alias option says that the certificate/key pair to use for signing is = in the key store under the "wsse" alias +</para> +</listitem> +<listitem> +<para> +Here we start our optional requires block. This block specifies all securi= ty requirements that must be met when the server receives a message. +</para> +</listitem> +<listitem> +<para> +This means that all web services in this war file require the message body= to be signed. +</para> +</listitem> +</orderedlist> +<para> +By default an endpoint does not use the WS-Security configuration. Use the= proprietary @EndpointConfig annotation to set the config name. See <link l= inkend=3D"JAX_WS_Endpoint_Configuration">JAX-WS_Endpoint_Configuration</lin= k> for the list of available config names. +</para> +<para> +<programlisting> +(a)WebService +(a)EndpointConfig(configName =3D "Standard WSSecurity Endpoint") +public class HelloJavaBean +{ + ... +} +</programlisting> +</para> + +</section> +<section id=3D"User_Guide_Client_side_WSSE_declaration__28jboss_wsse_clien= t_xml_29"><title>Client side WSSE declaration (jboss-wsse-client.xml)</titl= e> +<para> +<programlisting><jboss-ws-security xmlns=3D"http://www.jboss.com/ws-sec= urity/config" = + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://www.jboss.com/ws-security/config = + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> + (1) <config> + (2) <sign type=3D"x509v3" alias=3D"wsse"/> + (3) <requires> + (4) <signature/></requires></config></jboss-ws-secur= ity></programlisting> +</para> +<orderedlist numeration=3D"arabic"><listitem> +<para> +Here we start our root config block. The root config block is the default = configuration for all web service clients (Call, Proxy objects). +</para> +</listitem> +<listitem> +<para> +This means that the client must sign the message body of all requests it s= ends. Type means that we are to use a X.509v3 certificate (a standard certi= ficate). The alias option says that the certificate/key pair to use for sig= ning is in the key store under the "wsse" alias +</para> +</listitem> +<listitem> +<para> +Here we start our optional requires block. This block specifies all securi= ty requirements that must be met when the client receives a response. +</para> +</listitem> +<listitem> +<para> +This means that all web service clients must receive signed response messa= ges. +</para> +</listitem> +</orderedlist> +<section id=3D"User_Guide_Client_side_key_store_configuration"><title>Clie= nt side key store configuration + +We did not specify a key store or trust store, because client apps instead= use the wsse System properties instead. If this was a web or ejb client (m= eaning a webservice client in a war or ejb jar file), then we would have sp= ecified them in the client descriptor. + + +Here is an excerpt from the JBossWS samples: + + +<sysproperty key=3D"org.jboss.ws.wsse.keyStore" + value=3D"${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.key= store"/><sysproperty key=3D"org.jboss.ws.wsse.trustStore" = + value=3D"${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.tru= ststore"/><sysproperty key=3D"org.jboss.ws.wsse.keyStorePassword" val= ue=3D"jbossws"/><sysproperty key=3D"org.jboss.ws.wsse.trustStorePassw= ord" value=3D"jbossws"/><sysproperty key=3D"org.jboss.ws.wsse.keyStor= eType" value=3D"jks"/><sysproperty key=3D"org.jboss.ws.wsse.trustStor= eType" value=3D"jks"/> + + +SOAP message exchange + + +Below you see the incomming SOAP message with the details of the security = headers ommited. The idea is, that the SOAP body is still plain text, but i= t is signed in the security header and can therefore not manipulated in tra= nsit. + + +Incomming SOAPMessage<env:Envelope xmlns:env=3D"http://= schemas.xmlsoap.org/soap/envelope/"><env:Header><wsse:Security = env:mustUnderstand=3D"1" ...><wsu:Timestamp wsu:Id=3D"timestamp">.= ..</wsu:Timestamp><wsse:BinarySecurityToken ...> + ... + </wsse:BinarySecurityToken><ds:Signature xmlns:ds=3D"http://www.= w3.org/2000/09/xmldsig#"> + ... + </ds:Signature></wsse:Security></env:Header><env:Bod= y wsu:Id=3D"element-1-1140197309843-12388840" ...><ns1:echoUserType x= mlns:ns1=3D"http://org.jboss.ws/samples/wssecurity"><UserType_1 xmlns= :xsi=3D"http://www.w3.org/2001/XMLSchema-instance"><msg>Kermit<= /msg></UserType_1></ns1:echoUserType></env:Body></e= nv:Envelope> + + +
+ +
+
Installing the BouncyCastle JCE provider (JDK 1.4) + +The information below has originaly been provided by The Legion of = the Bouncy Castle. = + + +The provider can be configured as part of your environment via static regi= stration by adding an entry to the java.security properties file (found in = $JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location= of your JDK/JRE distribution). You'll find detailed instructions in the fi= le but basically it comes down to adding a line: = + + + + security.provider.<n>=3Dorg.bouncycastle.jce.provider.BouncyCastleP= rovider + + + +Where <n> is the preference you want the provider at. = + + +Note + + +Issues may arise if the Sun providers are not first. + + +Where you put the jar is mostly up to you, although with jdk1.4 the best (= and in some cases only) place to have it is in $JAVA_HOME/jre/lib/ext. Unde= r Windows there will normally be a JRE and a JDK install of Java if you thi= nk you have installed it correctly and it still doesn't work chances are yo= u have added the provider to the installation not being used. + + +
+
Keystor= e, truststore - What? + +Note + + +If you having a hard time understanding how the different trust- and keyst= ore configurationsare used for signature and encryption, then read this thr= ead first:http://www.jboss.org/index.html?module + + +
+
Advanced configur= ation + +Further information and examples covering advanced WS-Security configuration options are available. Thos= e might help when specific settings are required to obtain interoperability= with other vendors' WS-Security implementation. + + +
+ +
+
WS-Transaction + +Support for the WS-Coordination, WS-AtomicTransaction and WS-BusinessActiv= ity specifications will be provided by technology recently acquired from Ar= juna Technologies Ltd. This technology will be present within the JBoss Tra= nsactions 4.2.1 release. Further information can be obtained from the JBoss Transaction= s Project + + +
+
XML Registries + +J2EE 1.4 mandates support for Java API for XML Registries (JAXR). Inclusio= n of a XML Registry with the J2EE 1.4 certified Application Server is optio= nal. Starting jboss-4.0.2, JBoss ships a UDDI v2.0 compliant registry, the = Apache jUDDI registry. We also provide support for JAXR Capability Level 0 = (UDDI Registries) via integration of Apache Scout. + + +This chapter describes how to configure the jUDDI registry in JBoss and so= me sample code outlines for using JAXR API to publish and query the jUDDI r= egistry. + +
Apache jUDDI = Configuration + +Configuration of the jUDDI registry happens via an MBean Service that is d= eployed in the juddi-service.sar archive in the "all" configuration. The co= nfiguration of this service can be done in the jboss-service.xml of the MET= A-INF directory in the juddi-service.sar + + +Let us look at the individual configuration items that can be changed. + + +DataSources configuration + + +<attribute name=3D"DataSourceUrl">java:/DefaultDS<= ;/attribute> + + +Database Tables (Should they be created on start, Should they be dropped o= n stop, Should they be dropped on start etc) + + +<attribute name=3D"CreateOnStart">false</attribut= e><attribute name=3D"DropOnStop">true</attribute><attribu= te name=3D"DropOnStart">false</attribute> + + +JAXR Connection Factory to be bound in JNDI. (Should it be bound? and unde= r what name?) + + +<attribute name=3D"ShouldBindJaxr">true</attribut= e><attribute name=3D"BindJaxr">JAXR</attribute> + + +Other common configuration: + + +Add authorized users to access the jUDDI registry. (Add a sql insert state= ment in a single line) + + + + Look at the script META-INF/ddl/juddi_data.ddl for more details. Example = for a user 'jboss' + + INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME, + EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN) = + VALUES ('jboss','JBoss User','jboss(a)xxx','true','true'); + + + +
+
JBoss JAXR Conf= iguration + +In this section, we will discuss the configuration needed to run the JAXR = API. The JAXR configuration relies on System properties passed to the JVM. = The System properties that are needed are: + + + + javax.xml.registry.ConnectionFactoryClass=3Dorg.apache.ws.scout.registry.= ConnectionFactoryImpl = + jaxr.query.url=3Dhttp://localhost:8080/juddi/inquiry = + jaxr.publish.url=3Dhttp://localhost:8080/juddi/publish + juddi.proxy.transportClass=3Dorg.jboss.jaxr.juddi.transport.SaajTransport + + + +Please remember to change the hostname from "localhost" to the hostname of= the UDDI service/JBoss Server. + + +You can pass the System Properties to the JVM in the following ways: + + + +When the client code is running inside JBoss (maybe a servlet or an EJB). = Then you will need to pass the System properties in the run.sh/run.bat scri= pts to the java process via the "-D" option. + + + + +When the client code is running in an external JVM. Then you can pass the = properties either as "-D" options to the java process or explicitly set the= m in the client code(not recommended). + + + + + + System.setProperty(propertyname, propertyvalue); + + + +
+
JAXR Sample Code + +There are two categories of API: JAXR Publish API and JAXR Inquiry API. Th= e important JAXR interfaces that any JAXR client code will use are the foll= owing. + + + +javax.xml.registry.RegistryService From J2EE 1.4 JavaDoc: "This is the principal interface implement= ed by a JAXR provider. A registry client can get this interface from a Conn= ection to a registry. It provides the methods that are used by the client t= o discover various capability specific interfaces implemented by the JAXR p= rovider." + + + + +javax.xml.registry.BusinessLifeCycle= Manager From J2EE 1.4 JavaDoc: "The BusinessLifeCycleMa= nager interface, which is exposed by the Registry Service, implements the l= ife cycle management functionality of the Registry as part of a business le= vel API. Note that there is no authentication information provided, because= the Connection interface keeps that state and context on behalf of the cli= ent." + + + + +javax.xml.registry.BusinessQueryManager<= /citetitle> From J2EE 1.4 JavaDoc: "The BusinessQueryManager interf= ace, which is exposed by the Registry Service, implements the business styl= e query interface. It is also referred to as the focused query interface." + + + + +Let us now look at some of the common programming tasks performed while us= ing the JAXR API: + + +Getting a JAXR Connection to the registry. + + + + String queryurl =3D System.getProperty("jaxr.query.url", "http://localhos= t:8080/juddi/inquiry"); + String puburl =3D System.getProperty("jaxr.publish.url", "http://localhos= t:8080/juddi/publish"); + + Properties props =3D new Properties(); + props.setProperty("javax.xml.registry.queryManagerURL", queryurl); + props.setProperty("javax.xml.registry.lifeCycleManagerURL", puburl); + + String transportClass =3D System.getProperty("juddi.proxy.transportClass"= , "org.jboss.jaxr.juddi.transport.SaajTransport"); + System.setProperty("juddi.proxy.transportClass", transportClass); + + // Create the connection, passing it the configuration properties + factory =3D ConnectionFactory.newInstance(); + factory.setProperties(props); + connection =3D factory.createConnection(); + + + +Authentication with the registry. + + + + /** + * Does authentication with the uddi registry + */ + protected void login() throws JAXRException + { + PasswordAuthentication passwdAuth =3D new PasswordAuthentication(userid, = passwd.toCharArray()); + Set creds =3D new HashSet(); + creds.add(passwdAuth); + + connection.setCredentials(creds); + } + + + +Save a Business + + + + /** + * Creates a Jaxr Organization with 1 or more services + */ + protected Organization createOrganization(String orgname) throws JAXRExce= ption + { + Organization org =3D blm.createOrganization(getIString(orgname)); + org.setDescription(getIString("JBoss Inc")); + Service service =3D blm.createService(getIString("JBOSS JAXR Service")); + service.setDescription(getIString("Services of XML Registry")); + //Create serviceBinding + ServiceBinding serviceBinding =3D blm.createServiceBinding(); + serviceBinding.setDescription(blm.createInternationalString("Test Service= Binding")); + + //Turn validation of URI off + serviceBinding.setValidateURI(false); + serviceBinding.setAccessURI("http://testjboss.org"); + + // Add the serviceBinding to the service + service.addServiceBinding(serviceBinding); + + User user =3D blm.createUser(); + org.setPrimaryContact(user); + PersonName personName =3D blm.createPersonName("Anil S"); + TelephoneNumber telephoneNumber =3D blm.createTelephoneNumber(); + telephoneNumber.setNumber("111-111-7777"); + telephoneNumber.setType(null); + PostalAddress address =3D blm.createPostalAddress("111", "My Drive", "Buc= kHead", "GA", "USA", "1111-111", ""); + Collection postalAddresses =3D new ArrayList(); + postalAddresses.add(address); + Collection emailAddresses =3D new ArrayList(); + EmailAddress emailAddress =3D blm.createEmailAddress("anil(a)apache.org"); + emailAddresses.add(emailAddress); + + Collection numbers =3D new ArrayList(); + numbers.add(telephoneNumber); + user.setPersonName(personName); + user.setPostalAddresses(postalAddresses); + user.setEmailAddresses(emailAddresses); + user.setTelephoneNumbers(numbers); + + ClassificationScheme cScheme =3D getClassificationScheme("ntis-gov:naics"= , ""); + Key cKey =3D blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2"); + cScheme.setKey(cKey); + Classification classification =3D blm.createClassification(cScheme, "Comp= uter Systems Design and Related Services", "5415"); + org.addClassification(classification); + ClassificationScheme cScheme1 =3D getClassificationScheme("D-U-N-S", ""); + Key cKey1 =3D blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423"); + cScheme1.setKey(cKey1); + ExternalIdentifier ei =3D blm.createExternalIdentifier(cScheme1, "D-U-N-S= number", "08-146-6849"); + org.addExternalIdentifier(ei); + org.addService(service); + return org; + } + + + +Query a Business + + + + /** + * Locale aware Search a business in the registry + */ + public void searchBusiness(String bizname) throws JAXRException + { + try + { + // Get registry service and business query manager + this.getJAXREssentials(); + + // Define find qualifiers and name patterns + Collection findQualifiers =3D new ArrayList(); + findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC); + Collection namePatterns =3D new ArrayList(); + String pattern =3D "%" + bizname + "%"; + LocalizedString ls =3D blm.createLocalizedString(Locale.getDefault(), pat= tern); + namePatterns.add(ls); + + // Find based upon qualifier type and values + BulkResponse response =3D bqm.findOrganizations(findQualifiers, namePatte= rns, null, null, null, null); + + // check how many organisation we have matched + Collection orgs =3D response.getCollection(); + if (orgs =3D=3D null) + { + log.debug(" -- Matched 0 orgs"); + + } + else + { + log.debug(" -- Matched " + orgs.size() + " organizations -- "); + + // then step through them + for (Iterator orgIter =3D orgs.iterator(); orgIter.hasNext();) + { + Organization org =3D (Organization)orgIter.next(); + log.debug("Org name: " + getName(org)); + log.debug("Org description: " + getDescription(org)); + log.debug("Org key id: " + getKey(org)); + checkUser(org); + checkServices(org); + } + } + } + finally + { + connection.close(); + } + } + + + +For more examples of code using the JAXR API, please refer to the resource= s in the Resources Section. + + +
+
Trouble Shooting + + +I cannot connect to the registry from JAXR. Please check the inquiry and p= ublish url passed to the JAXR ConnectionFactory. + + + + +I cannot connect to the jUDDI registry. Please check the jUDDI configurati= on and see if there are any errors in the server.log. And also remember tha= t the jUDDI registry is available only in the "all" configuration. + + + + +I cannot authenticate to the jUDDI registry. Have you added an authorized = user to the jUDDI database, as described earlier in the chapter? + + + + +I would like to view the SOAP messages in transit between the client and t= he UDDI Registry. Please use the tcpmon tool to view the messages in transi= t. TCPMon= + + + + +
+
Resources + + +JAXR Tutorial and Code Camps + + + + += J2EE 1.4 Tutorial + + + + +J2EE Web Services by Richard Monson-Haefel + + + + +
+ +
+
WS-Policy + +Since 2.1 + + +The Web Services Policy Framework (WS-Policy) provides a general purpose m= odel and corresponding syntax to describe the policies of a Web Service. + + +WS-Policy defines a base set of constructs that can be used and extended b= y other Web services specifications to describe a broad range of service re= quirements and capabilities. + + +Current JBoss implementation can instrument a webservice with policies att= ached at endpoint, port or port-type scope level only.There are two differe= nt methods to attach policies: providing a wsdl decorated with policies and= policy attachments as defined by specifications, or using JBoss proprietar= y annotations. The first way has the advantage of being standard, while the= second one is much more simple to implement. Of course the wsdl generated = by these annotations conforms to standard defined in specifications and can= be used with any ws-policy compliant client. + + +Please note that ws-policy specifications only define policy requirements = and their attachment method to wsdl through specific extensions. It is out = of the scope of ws-policy specifications and thus implementation to define = and use the content of assertions. The way these assertions (called domain = assertions or domain policies) have to be deployed and used is left to othe= r specification like WS-Security-Policy or more generally to domain specifi= c implementation. + +
Specification + +WS-Policy is defined by the combination of the following specifications: * <= citetitle>WS-Policy specification * WS-Policy-Attachment specification + + +
+
U= sing policies in a user provided wsdl + +To attach policies in this manner, the only thing you have to do in a webs= ervice class is to provide a custom wsdl. This will cause JBossws to skip w= sdl generation at deploy time, since the wsdl file you provided will be pub= lished. Please refer to specification (WS-Policy-Attachment) to learn how t= o modify wsdl to attach a policy. + + +Here you find an example of a webservice class and provided wsdl with a po= licy containing a domain assertion for JBoss wssecurity. + + + +(a)WebService(name =3D "Hello", = +targetNamespace =3D "http://org.jboss.ws/samples/wssecuritypolicy", +wsdlLocation=3D"WEB-INF/wsdl/HelloService.wsdl") +(a)SOAPBinding(style =3D SOAPBinding.Style.RPC) +public class HelloJavaBean +{ + private Logger log =3D Logger.getLogger(HelloJavaBean.class); + + @WebMethod + public UserType echoUserType(@WebParam(name =3D "user") UserType in0) + { + log.info(in0); + return in0; + } +} + + + +<?xml version=3D"1.0" encoding=3D"UTF-8"?><defini= tions name=3D'HelloService' targetNamespace=3D'http://org.jboss.ws/samples/= wssecuritypolicy' xmlns=3D'http://schemas.xmlsoap.org/wsdl/' xmlns:ns1=3D'h= ttp://org.jboss.ws/samples/wssecurity' xmlns:soap=3D'http://schemas.xmlsoap= .org/wsdl/soap/' xmlns:tns=3D'http://org.jboss.ws/samples/wssecuritypolicy'= xmlns:wsp=3D'http://schemas.xmlsoap.org/ws/2004/09/policy' xmlns:xsd=3D'ht= tp://www.w3.org/2001/XMLSchema'><types><xs:schema targetNamespa= ce=3D'http://org.jboss.ws/samples/wssecurity' version=3D'1.0' xmlns:xs=3D'h= ttp://www.w3.org/2001/XMLSchema'><xs:complexType name=3D'UserType'>= ;<xs:sequence><xs:element minOccurs=3D'0' name=3D'msg' type=3D'xs:= string'/></xs:sequence></xs:complexType></xs:schema>&l= t;/types><wsp:Policy wsu:Id=3D'X509EndpointPolicy' xmlns:wsu=3D'http:= //docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.x= sd'><wsp:All><sp:jboss-ws-security xmlns! :sp=3D'http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd'&= gt;<sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file>= <sp:key-store-password>jbossws</sp:key-store-password><sp:tr= ust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file><sp= :trust-store-password>jbossws</sp:trust-store-password><sp:conf= ig><sp:encrypt alias=3D'wsse' type=3D'x509v3'/><sp:requires>= <sp:encryption/></sp:requires></sp:config></sp:jboss-w= s-security></wsp:All></wsp:Policy><message name=3D'Hello_= echoUserType'><part name=3D'user' type=3D'ns1:UserType'/></mess= age><message name=3D'Hello_echoUserTypeResponse'><part name=3D'= return' type=3D'ns1:UserType'/></message><portType name=3D'Hell= o'><operation name=3D'echoUserType' parameterOrder=3D'user'><in= put message=3D'tns:Hello_echoUserType'/><output message=3D'tns:Hello_= echoUserTypeResponse'/></operation&g! t;</portType><binding name=3D'HelloBinding' type=3D'tns:Hello'> ;<wsp:PolicyReference URI=3D'#X509EndpointPolicy'/><soap:binding s= tyle=3D'rpc' transport=3D'http://schemas.xmlsoap.org/soap/http'/><ope= ration name=3D'echoUserType'><soap:operation soapAction=3D''/><= input><soap:body namespace=3D'http://org.jboss.ws/samples/wssecurityp= olicy' use=3D'literal'/></input><output><soap:body namesp= ace=3D'http://org.jboss.ws/samples/wssecuritypolicy' use=3D'literal'/>&l= t;/output></operation></binding><service name=3D'HelloSer= vice'><port binding=3D'tns:HelloBinding' name=3D'HelloPort'><so= ap:address location=3D'REPLACE_WITH_ACTUAL_URL'/></port></servi= ce></definitions> + + +Please note in the wsdl file the wsp:Policy element and the wsp:PolicyRefe= rence in 'HelloBinding' binding Element. + + +
+
Us= ing policies with JBoss annotations + +Using JBoss proprietary annotation you only have to provide the policy xml= , leaving wsdl generation to the JBossWS deployer. + + +There are two annotations to use, the first one (@PolicyAttachment) contai= ning an array of the second one (@Policy): this lets you have many policies= attached to a class or method.In future domain policy implementations migh= t ship domain annotations extending the @Policy annotation to provide neede= d metadata directly as annotation parameters. The current @Policy annotatio= n takes a reference to a xml file containing a generic policy description w= ritten respecting ws-policy specification rules. = + + + +/** + +(a)Target(ElementType.TYPE) = +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PolicyAttachment { + Policy[] value(); +} + + + + + +(a)Retention(RetentionPolicy.RUNTIME) +public @interface Policy { + = + public String policyFileLocation(); + = + public PolicyScopeLevel scope(); +} + + + +And here you have the previous section example re-implemented using annota= tions and xml policy file: + + + +(a)WebService(name =3D "Hello", targetNamespace =3D "http://org.jboss.ws/s= amples/wssecurityAnnotatedpolicy") +(a)PolicyAttachment({@Policy( policyFileLocation=3D"WEB-INF/Policy.xml", s= cope =3D PolicyScopeLevel.WSDL_PORT ) }) +(a)SOAPBinding(style =3D SOAPBinding.Style.RPC) +public class HelloJavaBean +{ + private Logger log =3D Logger.getLogger(HelloJavaBean.class); + + @WebMethod + public UserType echoUserType(@WebParam(name =3D "user") UserType in0) + { + log.info(in0); + return in0; + } +} + + + +<?xml version=3D"1.0" encoding=3D"UTF-8"?><wsp:Po= licy wsu:Id=3D"X509EndpointPolicy" xmlns:wsp=3D"http://schemas.xmlsoap.org/= ws/2004/09/policy" = + xmlns:wsu=3D"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wss= ecurity-utility-1.0.xsd"><wsp:ExactlyOne><wsp:All><sp:jbo= ss-ws-security xmlns:sp=3D"http://www.jboss.com/ws-security/schema/jboss-ws= -security_1_0.xsd"><sp:key-store-file>WEB-INF/wsse.keystore</sp= :key-store-file><sp:key-store-password>jbossws</sp:key-store-pa= ssword><sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-s= tore-file><sp:trust-store-password>jbossws</sp:trust-store-pass= word><sp:config><sp:encrypt type=3D"x509v3" alias=3D"wsse"/>= <sp:requires><sp:encryption/></sp:requires></sp:config= ></sp:jboss-ws-security></wsp:All></wsp:ExactlyOne><= ;/wsp:Policy> + + +
+ +
+ +
+
JBossWS Extenstions<= /title> +<para> +This section describes propriatary JBoss extensions to JAX-WS. +</para> +<section id=3D"User_Guide_Proprietary_Annotations"><title>Proprietary Anno= tations + +For the set of standard annotations, please have a look at JAX-WS_Annotations + +
EndpointConfig + + +/** + * Defines an endpoint or client configuration. = + * This annotation is valid on an endpoint implementaion bean or a SEI. + * = + * @author Heiko.Braun(a)jboss.org + * @since 16.01.2007 + */ +(a)Retention(value =3D RetentionPolicy.RUNTIME) +(a)Target(value =3D { ElementType.TYPE }) +public @interface EndpointConfig { + + /** + * The optional config-name element gives the configuration name that must= be present in + * the configuration given by element config-file. + * + * Server side default: Standard Endpoint + * Client side default: Standard Client + */ + String configName() default ""; + + /** + * The optional config-file element is a URL or resource name for the conf= iguration. + * + * Server side default: standard-jaxws-endpoint-config.xml + * Client side default: standard-jaxws-client-config.xml + */ + String configFile() default ""; +} + + + +
+
WebContext + + +/** + * Provides web context specific meta data to EJB based web service endpoi= nts. + * + * @author thomas.diesler(a)jboss.org + * @since 26-Apr-2005 + */ +(a)Retention(value =3D RetentionPolicy.RUNTIME) +(a)Target(value =3D { ElementType.TYPE }) +public @interface WebContext { + + /** = + * The contextRoot element specifies the context root that the web service= endpoint is deployed to. + * If it is not specified it will be derived from the deployment short nam= e. + * = + * Applies to server side port components only. = + */ + String contextRoot() default ""; + = + /** = + * The virtual hosts that the web service endpoint is deployed to. + * = + * Applies to server side port components only. + */ + String[] virtualHosts() default {}; + = + /** = + * Relative path that is appended to the contextRoot to form fully qualifi= ed + * endpoint address for the web service endpoint. + * = + * Applies to server side port components only. = + */ + String urlPattern() default ""; + + /** + * The authMethod is used to configure the authentication mechanism for th= e web service. = + * As a prerequisite to gaining access to any web service which are protec= ted by an authorization + * constraint, a user must have authenticated using the configured mechani= sm. + * + * Legal values for this element are "BASIC", or "CLIENT-CERT". + */ + String authMethod() default ""; + + /** + * The transportGuarantee specifies that the communication + * between client and server should be NONE, INTEGRAL, or + * CONFIDENTIAL. NONE means that the application does not require any + * transport guarantees. A value of INTEGRAL means that the application + * requires that the data sent between the client and server be sent in + * such a way that it can't be changed in transit. CONFIDENTIAL means + * that the application requires that the data be transmitted in a + * fashion that prevents other entities from observing the contents of + * the transmission. In most cases, the presence of the INTEGRAL or + * CONFIDENTIAL flag will indicate that the use of SSL is required. + */ + String transportGuarantee() default ""; + + /** + * A secure endpoint does not by default publish it's wsdl on an unsecure = transport. + * You can override this behaviour by explicitly setting the secureWSDLAcc= ess flag to false. + * = + * Protect access to WSDL. See http://jira.jboss.org/jira/browse/JBWS-723 = + */ + boolean secureWSDLAccess() default true; +} + + + +
+
SecurityDomain + + +/** + * Annotation for specifying the JBoss security domain for an EJB + * = + * @author <a href=3D"mailto:bill(a)jboss.org">Bill Burke</a> + **/ +(a)Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) +public @interface SecurityDomain +{ + /** + * The required name for the security domain. + * = + * Do not use the JNDI name + * = + * Good: "MyDomain" + * Bad: "java:/jaas/MyDomain" + */ + String value(); + = + /** + * The name for the unauthenticated pricipal + */ + String unauthenticatedPrincipal() default ""; +} + + + +Since 2.0.3 + + +
+
Documentation + + +package org.jboss.ws.annotation; + +/** + * Annotation to be used to add wsdl:documentation elements to the generat= ed wsdl. + * + * @author alessio.soldano(a)jboss.org + * @since 15-Jan-2008 + */ +(a)Target({ElementType.TYPE, ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface Documentation +{ + public String content(); +} + + + +
+ +
+
Deploym= ent descriptor attributes +
JSE Endpoints + +The following is taken from http://anonsvn.jboss.org/repos/jbossas/project= s/metadata/trunk/src/main/resources/dtd/jboss-web_5_0.dtdand shows an excer= pt of the jboss-web_5_0.dtdThe most important bits are: + + + +config-name: JBossWS endpoint config name (see JAX-WS_Endpoint_Configuration) + + + + +config-file: JBossWS endpoint config file + + + + +wsdl-publish-location: Where to publish the runtime gne= rated WSDL + + + + +<!ELEMENT webservice-description ( webservice-descripti= on-name, config-name?, + config-file?, wsdl-publish-location? )><!ELEMENT webservice-descrip= tion-name ( #PCDATA )><!ELEMENT wsdl-publish-location ( #PCDATA )>= + + +
+
EJB3 endpoints + +EJB deployment descriptor attributes are quiet the same. You can specify a= top level webservices element along with you ejb declar= ation that allows you to override certain deployment aspects. The following= excerpt is taken from https://anonsvn.jboss.org/repos/jbossas/projects/met= adata/trunk/src/main/resources/dtd/jboss_5_0.dtd + + +In addition to the default properties that are customizable like in JSE de= ployments, the EJB descriptor allows you to specify: + + + +context-root: A custom web context root. Applies to all= beans in this deployment unit + + + + +<!ELEMENT webservices (context-root?, webservice-descri= ption*)><!ELEMENT context-root (#PCDATA)><!ELEMENT webservice-d= escription ( webservice-description-name, config-name?, + config-file?, wsdl-publish-location? )> + + +
+ +
+ +
+
Appendix A + +JAX-WS Endpoint Configurat= ion + + +JAX-WS Client Configuration<= /link> + + +JAX-WS Annotations + + +
+
References + +[1] JS= R-224 - Java API for XML-Based Web Services (JAX-WS) 2.0 + + +[2] JSR 222 - Java Arch= itecture for XML Binding (JAXB) 2.0 + + +[3] JS= R-261 - Java API for XML Web Services Addressing + + +[4] SOAP-1.2 -= Messaging Framework + + +[5] JSR-25= 0 - Common Annotations for the Java Platform + + +[6] JSR 18= 1 - Web Services Metadata for the Java Platform + +
+
+JBossWS JAX-WS Tools + +The JAX-WS tools provided by JBossWS can be used in a variety of ways. Fir= st we will look at server-side development strategies, and then proceed to = the client. = + +
Server side + +When developing a Web Service Endpoint (the server-side) you have the opti= on of starting from Java (bottom-up development), or from the abstact contr= act (WSDL) that defines your service (top-down development). If this is a n= ew service (no existing contract), the bottom-up approach is the fastest ro= ute; you only need to add a few annotations to your classes to get a servic= e up and running. However, if you are developing a service with an already = defined contract, it is far simpler to use the top-down approach, since the= provided tool will generate the annotated code for you. + + +Bottom-up use cases: + + + +Exposing an already existing EJB3 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't bre= ak compatibility with older clients + + + + +Exposing a service that conforms to a contract specified by a third party = (e.g. a vender that calls you back using an already defined protocol). + + + + +Creating a service that adheres to the XML Schema and WSDL you developed b= y hand up front + + + + +The following JAX-WS command line tools are included in JBossWS:
+<tgroup cols=3D"2"><tbody><row> +<entry> +Command +</entry> +<entry> +Description +</entry> + +</row> +<row> +<entry> +<link linkend=3D"Wsprovide">wsprovide</link> +</entry> +<entry> +Generates JAX-WS portable artifacts, and provides the abstract contract. U= sed for bottom-up development. +</entry> + +</row> +<row> +<entry> +<link linkend=3D"Wsconsume">wsconsume</link> +</entry> +<entry> +Consumes the abstract contract (WSDL and Schema files), and produces artif= acts for both a server and client. Used for top-down and client development +</entry> + +</row> +<row> +<entry> +<link linkend=3D"Wsrunclient">wsrunclient</link> +</entry> +<entry> +Executes a Java client (has a main method) using the JBossWS classpath. +</entry> + +</row> +</tbody></tgroup> +</table> + +</para> +<section id=3D"JBossWS_JAX_WS_Tools_Bottom_Up__28Using_wsprovide_29"><titl= e>Bottom-Up (Using wsprovide) + +The bottom-up strategy involves developing the Java code for your service,= and then annotating it using JAX-WS annotations. These annotations can be = used to customize the contract that is generated for your service. For exam= ple, you can change the operation name to map to anything you like. However= , all of the annotations have sensible defaults, so only the @WebService an= notation is required. = + + +This can be as simple as creating a single class: +package echo; + +(a)javax.jws.WebService +public class Echo +{ + public String echo(String input) + { + return input; + } +} + + + +A JSE or EJB3 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 artifa= cts called "wrapper classes" will be generated for you at deploy time. This= actually goes beyond the JAX-WS specification, which requires that wrapper= classes be generated using an offline tool. The reason for this requiremen= t is purely a vender implementation problem, and since we do not believe in= burdening a developer with a bunch of additional steps, we generate these = as well. However, if you want your deployment to be portable to other appli= cation servers, you will unfortunately need to use a tool and add the gener= ated classes to your deployment. = + + +This is the primary purpose of the wsprovide tool, to generate portable JAX-WS artifacts. Additionally, it can be = used to "provide" the abstract contract (WSDL file) for your service. This = can be obtained by invoking wsprovide us= ing the "-w" option: + + + +$ javac -d . -classpath jboss-jaxws.jar Echo.java +$ wsprovide -w echo.Echo +Generating WSDL: +EchoService.wsdl +Writing Classes: +echo/jaxws/Echo.class +echo/jaxws/EchoResponse.class + + + +Inspecting the WSDL reveals a service called EchoService:&= lt;service name=3D'EchoService'><port binding=3D'tns:EchoBinding' nam= e=3D'EchoPort'><soap:address location=3D'REPLACE_WITH_ACTUAL_URL'/>= ;</port></service> + + +As expected, this service defines one operation, "echo":&l= t;portType name=3D'Echo'><operation name=3D'echo' parameterOrder=3D'e= cho'><input message=3D'tns:Echo_echo'/><output message=3D'tns:E= cho_echoResponse'/></operation></portType> + + +Note + + +Remember that when deploying on JBossWS you do not= need to run this tool. You only need it for generating portable= artifacts and/or the abstract contract for your service. + + +Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml = needs to be created:<web-app xmlns=3D"http://java.sun.co= m/xml/ns/j2ee" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://java.sun.com/xml/ns/j2ee http://java.sun.com= /xml/ns/j2ee/web-app_2_4.xsd" + version=3D"2.4"><servlet><servlet-name>Echo</servlet-na= me><servlet-class>echo.Echo</servlet-class></servlet>&= lt;servlet-mapping><servlet-name>Echo</servlet-name><url-= pattern>/Echo</url-pattern></servlet-mapping></web-app>= ; + + +The web.xml and the single class can now be used to create a war: +$ 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 =3D 0) (out=3D 0)(stored 0%) +adding: WEB-INF/classes/(in =3D 0) (out=3D 0)(stored 0%) +adding: WEB-INF/classes/echo/(in =3D 0) (out=3D 0)(stored 0%) +adding: WEB-INF/classes/echo/Echo.class(in =3D 340) (out=3D 247)(deflated = 27%) +adding: WEB-INF/web.xml(in =3D 576) (out=3D 271)(deflated 52%) + + + +The war can then be deployed: +cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy + + + +This will internally invoke wsprovide, = which will generate the WSDL. If deployment was successful, and you are usi= ng the default settings, it should be available here: http://localhost:8080= /echo/Echo?wsdl + + +For a portable JAX-WS deployment, the wrapper classes generated earlier co= uld be added to the deployment. + + + +
Top-Down (Using wsconsume) + +The top-down development strategy begins with the abstract contract for th= e service, which includes the WSDL file and zero or more schema files. The = wsconsume tool is then used to consume t= his contract, and produce annotated Java classes (and optionally sources) t= hat define it. + + +Note + + +wsconsume seems to have a problem 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 f= iles that are generated, instead of providing just classes: + + + = +$ wsconsume -k EchoService.wsdl +echo/Echo.java +echo/EchoResponse.java +echo/EchoService.java +echo/Echo_Type.java +echo/ObjectFactory.java +echo/package-info.java +echo/Echo.java +echo/EchoResponse.java +echo/EchoService.java +echo/Echo_Type.java +echo/ObjectFactory.java +echo/package-info.java + + + +The following table shows the purpose of each generated file:
+<tgroup cols=3D"2"><tbody><row> +<entry> +File +</entry> +<entry> +Purpose +</entry> + +</row> +<row> +<entry> +Echo.java +</entry> +<entry> +Service Endpoint Interface +</entry> + +</row> +<row> +<entry> +Echo_Type.java +</entry> +<entry> +Wrapper bean for request message +</entry> + +</row> +<row> +<entry> +EchoResponse.java +</entry> +<entry> +Wrapper bean for response message +</entry> + +</row> +<row> +<entry> +ObjectFactory.java +</entry> +<entry> +JAXB XML Registry +</entry> + +</row> +<row> +<entry> +package-info.java +</entry> +<entry> +Holder for JAXB package annotations +</entry> + +</row> +<row> +<entry> +EchoService.java +</entry> +<entry> +Used only by JAX-WS clients +</entry> + +</row> +</tbody></tgroup> +</table> + +</para> +<para> +Examining the Service Endpoint Interface reveals annotations that are more= explicit than in the class written by hand in the bottom-up example, howev= er, these evaluate to the same contract:<programlisting> +(a)WebService(name =3D "Echo", targetNamespace =3D "http://echo/") +public interface Echo { + @WebMethod + @WebResult(targetNamespace =3D "") + @RequestWrapper(localName =3D "echo", targetNamespace =3D "http://echo/",= className =3D "echo.Echo_Type") + @ResponseWrapper(localName =3D "echoResponse", targetNamespace =3D "http:= //echo/", className =3D "echo.EchoResponse") + public String echo( + @WebParam(name =3D "arg0", targetNamespace =3D "") + String arg0); + +} +</programlisting> +</para> +<para> +The only missing piece (besides the packaging) is the implementation class= , which can now be written, using the above interface.<programlisting> +package echo; + +(a)javax.jws.WebService(endpointInterface=3D"echo.Echo") +public class EchoImpl implements Echo +{ + public String echo(String arg0) + { + return arg0; + } +} +</programlisting> +</para> + +</section> + +</section> +<section id=3D"JBossWS_JAX_WS_Tools_Client_Side"><title>Client Side + +Before going to detail on the client-side it is important to understand th= e 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. Th= ere are much better technologies for this (CORBA, and RMI for example). Web= Services were designed specifically for interoperable coarse-grained corre= spondence. There is no expectation or guarantee that any party participatin= g in a Web Service interaction will be at any particular location, running = on any particular OS, or written in any particular programming language. So= because of this, it is important to clearly separate client and server imp= lementations. The only thing they should have in common is the abstract con= tract definition. If, for whatever reason, your software does not adhere to= this principal, then you should not be using Web Services. For the above r= easons, the recommended methodology for d= eveloping a clie! nt is to follow th= e top-down approach, even if the client is running on= the same server. + + +Let's repeat the process of the top-down section, although using the deplo= yed WSDL, instead of the one generated offline by wsprovide. The reason why we do this is just to get the right val= ue for soap:address. This value must be computed at deploy time, since it i= s based on container configuration specifics. You could of course edit the = WSDL file yourself, although you need to ensure that the path is correct. + + +Offline version:<service name=3D'EchoService'><po= rt binding=3D'tns:EchoBinding' name=3D'EchoPort'><soap:address locati= on=3D'REPLACE_WITH_ACTUAL_URL'/></port></service> + + +Online version:<service name=3D"EchoService"><por= t binding=3D"tns:EchoBinding" name=3D"EchoPort"><soap:address locatio= n=3D"http://localhost.localdomain:8080/echo/Echo"/></port></ser= vice> + + +Using the online deployed version with wsconsu= me: +$ wsconsume -k http://localhost:8080/echo/Echo?wsdl +echo/Echo.java +echo/EchoResponse.java +echo/EchoService.java +echo/Echo_Type.java +echo/ObjectFactory.java +echo/package-info.java +echo/Echo.java +echo/EchoResponse.java +echo/EchoService.java +echo/Echo_Type.java +echo/ObjectFactory.java +echo/package-info.java + + + +The one class that was not examined in the top-down section, was EchoServi= ce.java. Notice how it stores the location the WSDL was obtained from. +(a)WebServiceClient(name =3D "EchoService", targetNamespace =3D "http://ec= ho/", wsdlLocation =3D "http://localhost:8080/echo/Echo?wsdl") +public class EchoService extends Service +{ + private final static URL ECHOSERVICE_WSDL_LOCATION; + + static { + URL url =3D null; + try { + url =3D new URL("http://localhost:8080/echo/Echo?wsdl"); + } catch (MalformedURLException e) { + e.printStackTrace(); + } + ECHOSERVICE_WSDL_LOCATION =3D url; + } + + public EchoService(URL wsdlLocation, QName serviceName) { + super(wsdlLocation, serviceName); + } + + public EchoService() { + super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/", "EchoService")= ); + } + + @WebEndpoint(name =3D "EchoPort") + public Echo getEchoPort() { + return (Echo)super.getPort(new QName("http://echo/", "EchoPort"), Echo.cl= ass); + } +} + + + +As you can see, this generated class extends the main client entry point i= n JAX-WS, javax.xml.ws.Service. While you can use Service directly, this is= far simpler since it provides the configuration info for you. The only met= hod we really care about is the getEchoPort() method, which returns an inst= ance of our Service Endpoint Interface. Any WS operation can then be called= by just invoking a method on the returned interface. + + +Note + + +It's not recommended to refer to a remote WSDL URL in a production applica= tion. 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 th= e constructor to provide a new WSDL location. + + +All that is left to do, is write and compile the client: +import echo.*; + +public class EchoClient +{ + public static void main(String args[]) + { + if (args.length !=3D 1) + { + System.err.println("usage: EchoClient <message>"); + System.exit(1); + } + = + EchoService service =3D new EchoService(); + Echo echo =3D service.getEchoPort(); + System.out.println("Server said: " + echo.echo(args[0])); + } = +} + + + +It can then be easily executed using the wsr= unclient tool. This is just a convenience tool that invokes java wit= h the needed classpath: +$ wsrunclient EchoClient 'Hello World!' +Server said: Hello World! + + + +It is easy to change the endpoint address of your operation at runtime, se= tting the ENDPOINT_ADDRESS_PROPERTY as shown below: +... + EchoService service =3D new EchoService(); + Echo echo =3D service.getEchoPort(); + + /* Set NEW Endpoint Location */ + String endpointURL =3D "http://NEW_ENDPOINT_URL"; + BindingProvider bp =3D (BindingProvider)echo; + bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, end= pointURL); + + System.out.println("Server said: " + echo.echo(args[0])); +... + + + + +
Command-line &am= p; Ant Task Reference + + +wsconsume reference page + + + + +wsprovide reference page + + + + +wsrunclient reference page + + + + +
+
J= AX-WS binding customization + +An introduction to binding customizations: + + + +http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html + + + + +The schema for the binding customization files can be found here: + + + +https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiza= tion.xsd?rev=3D1.2&view=3Dlog + + + + +Category:Tools (Category:Tools)Category:Start from scratch (Category:Start= from scratch) + +
+
+Authentication + +Category:Transition / staging (Category:Transition / staging)This page exp= lains the simplest way to authenticate a web service user with JBossWS. + + +First we secure the access to the SLSB as we would do for normal (non web = service) invocations: this can be easily done through the @RolesAllowed, @P= ermitAll, @DenyAll annotation. The allowed user roles can be set with these= annotations both on the bean class and on any of its business methods. + + + +(a)Stateless +(a)RolesAllowed("friend") +public class EndpointEJB implements EndpointInterface +{ + ... +} + + + +Similarly POJO endpoints are secured the same way as we do for normal web = applications in web.xml: + + +<security-constraint><web-resource-collection>= <web-resource-name>All resources</web-resource-name><url-pat= tern>/*</url-pattern></web-resource-collection><auth-cons= traint><role-name>friend</role-name></auth-constraint>= </security-constraint><security-role><role-name>friend<= ;/role-name></security-role> + +
Define th= e security domain + +Next, define the security domain for this deployment. This is performed us= ing the @SecurityDomain = annotation for EJB3 endpoints + + + +(a)Stateless +(a)SecurityDomain("JBossWS") +(a)RolesAllowed("friend") +public class EndpointEJB implements EndpointInterface +{ + ... +} + + + +or modifying the jboss-web.xml for POJO endpoints + + +<jboss-web><security-domain>java:/jaas/JBossWS= </security-domain></jboss-web> + + +The JBossWS security context is configured in login-config.xml and uses th= e UsersRolesLoginModule. As a matter of= fact login-config.xml, that lives in the server config dir, contains this = security domain definition: + + +<application-policy name=3D"JBossWS"><authenticat= ion><login-module code=3D"org.jboss.security.auth.spi.UsersRolesLogin= Module" + flag=3D"required"><module-option name=3D"usersProperties">props/= jbossws-users.properties</module-option><module-option name=3D"rol= esProperties">props/jbossws-roles.properties</module-option><mo= dule-option name=3D"unauthenticatedIdentity">anonymous</module-option= ></login-module></authentication></application-policy>= + + +Of course you can define and use your own security domain as well as your = login module (in order to check for users' identity querying a database for= example). + + +
+
Use BindingProvider to set principal/credential + +A web service client may use the javax.xml.ws.BindingProvider interface to= set the username/password combination + + + +URL wsdlURL =3D new File("resources/jaxws/samples/context/WEB-INF/wsdl/Tes= tEndpoint.wsdl").toURL(); +QName qname =3D new QName("http://org.jboss.ws/jaxws/context", "TestEndpoi= ntService"); +Service service =3D Service.create(wsdlURL, qname); +port =3D (TestEndpoint)service.getPort(TestEndpoint.class); + +BindingProvider bp =3D (BindingProvider)port; +bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit"); +bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "thefrog"); + + + +
+
U= sing HTTP Basic Auth for security + +To enable HTTP Basic authentication you use the @WebContext annotation on the bean class + + + +(a)Stateless +(a)SecurityDomain("JBossWS") +(a)RolesAllowed("friend") +(a)WebContext(contextRoot=3D"/my-cxt", urlPattern=3D"/*", authMethod=3D"BA= SIC", transportGuarantee=3D"NONE", secureWSDLAccess=3Dfalse) +public class EndpointEJB implements EndpointInterface +{ + ... +} + + + +For POJO endpoints, we modify the web.xml adding the auth-method element: + + +<login-config><auth-method>BASIC</auth-meth= od><realm-name>Test Realm</realm-name></login-config><= /programlisting> + +
+
+Secure transport + +Category:Transition / staging (Category:Transition / staging)JBossWS allow= s you to require that requests to a given endpoint use SSL by specifying th= e transportGuarantee attribute in the @WebContext annotation. + + +Here is an example using a SLSB endpoint: +(a)Stateless +(a)SecurityDomain("JBossWS") +(a)RolesAllowed("friend") +(a)WebContext(contextRoot=3D"/my-cxt", urlPattern=3D"/*", authMethod=3D"BA= SIC", transportGuarantee=3D"CONFIDENTIAL", secureWSDLAccess=3Dfalse) +public class EndpointEJB implements EndpointInterface +{ + ... +} + + + +Similarly to enforce the same requirement on POJO endpoints, you need to e= dit web.xml and add a user-data-constraint element to your security-constra= int element: + + +<security-constraint><web-resource-collection>= <web-resource-name>All resources</web-resource-name><url-pat= tern>/*</url-pattern></web-resource-collection><auth-cons= traint><role-name>friend</role-name></auth-constraint>= <user-data-constraint><transport-guarantee>CONFIDENTIAL</tra= nsport-guarantee></user-data-constraint></security-constraint&g= t;<security-role><role-name>friend</role-name></securi= ty-role> + + +If you're manually creating your service contract, make sure that the endp= oint address in your WSDL file uses a secure protocol. The easiest way is t= o add "https://" to the SOAP Address entry: + + +<service name=3D"MyService"><port name=3D"BasicSe= curedPort" binding=3D"tns:MyBinding"><soap:address location=3D"https:= //localhost:8443/my-ctx/SecureEndpoint"/></port></service> + + +For this to work the Tomcat+SSL connector must be enabled: + + +<Connector port=3D"8443" address=3D"${jboss.bind.addres= s}" + maxThreads=3D"100" minSpareThreads=3D"5" maxSpareThreads=3D"15" + scheme=3D"https" secure=3D"true" clientAuth=3D"want" + keystoreFile=3D"${jboss.server.home.dir}/conf/keystores/wsse.keystore" = + keystorePass=3D"jbossws" + truststoreFile=3D"${jboss.server.home.dir}/conf/keystores/wsse.keystore" = + truststorePass=3D"jbossws" + sslProtocol =3D "TLS" /> + + +Please refer the Tomcat-5.5 SSL Configuration HOWTO for further details. + +
Client side + +On the client side the truststore must be installed: + + +<sysproperty key=3D"javax.net.ssl.keyStore" value=3D"${= test.resources.dir}/wsse/wsse.keystore"/><sysproperty key=3D"javax.ne= t.ssl.trustStore" value=3D"${test.resources.dir}/wsse/wsse.truststore"/>= <sysproperty key=3D"javax.net.ssl.keyStorePassword" value=3D"jbossws"/&g= t;<sysproperty key=3D"javax.net.ssl.trustStorePassword" value=3D"jbossws= "/><sysproperty key=3D"javax.net.ssl.keyStoreType" value=3D"jks"/>= <sysproperty key=3D"javax.net.ssl.trustStoreType" value=3D"jks"/> + + +As you can see, this requires you to setup the environment specifying both= the location and type of your truststore. + + +Finally, in case you see the following exception: + + + + java.io.IOException: HTTPS hostname wrong: should be <localhost> + at sun.net.www.protocol.https.HttpsClient.checkURLSpoofing(HttpsClient.ja= va:493) + at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:4= 18) + + + +you should disable URL checking on the client side: + + +<sysproperty key=3D"org.jboss.security.ignoreHttpsHost"= value=3D"true"/> + +
+
+JAX-WS Endpoint Configuration + +Category:Development (Category:Development)The standard endpoint configura= tion is defined in standard-jaxws-endpoint-config.x= ml + +
Using @EndpointConfig + +On the server side you proabably use the @EndpointConfig annotation to specify one of the available (might be custom as well) conf= igurations: + + + +(a)WebService(name =3D "Hello", serviceName =3D "HelloService", targetName= space =3D "http://org.jboss.ws/samples/wssecurity") +(a)EndpointConfig(configName =3D "Standard WSSecurity Endpoint") (1) +(a)SOAPBinding(style =3D SOAPBinding.Style.RPC) +public class HelloJavaBean +{ + private Logger log =3D Logger.getLogger(HelloJavaBean.class); + + @WebMethod + public UserType echoUserType(@WebParam(name =3D "user") UserType in0) + { + log.info(in0); + return in0; + } +} + + + + + +(a)EndpointConfig(configName =3D "Standard WSSecurity Endpoint") + + + + +
+
Configuration presets +
Sta= ndard Endpoint + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<endpoint-config><config-name>Standard Endpoint</config-nam= e></endpoint-config></jaxws-config> + + +
+
Standard WSAddressing Endpoint + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<endpoint-config><config-name>Standard WSAddressing Endpoint&l= t;/config-name><pre-handler-chains><javaee:handler-chain><= ;javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>= <javaee:handler><javaee:handler-name>WSAddressing Handler</j= avaee:handler-name><javaee:handler-class>org.jboss.ws.extensions.a= ddressing.jaxws.WSAddressingServerHandler</javaee:handler-class></= javaee:handler></javaee:handler-chain></pre-handler-chains>&= lt;/endpoint-config></jaxws-config> + + +Since 2.0.3 + + +
+
Standard SOAP 1.2 WSAddressing Endpoint + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<endpoint-config><config-name>Standard SOAP 1.2 WSAddressing E= ndpoint</config-name><post-handler-chains><javaee:handler-ch= ain><javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bi= ndings><javaee:handler><javaee:handler-name>WSAddressing Han= dler</javaee:handler-name><javaee:handler-class>org.jboss.ws.ex= tensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-clas= s></javaee:handler></javaee:handler-chain></post-handler-= chains></endpoint-config></jaxws-config> + + +
+
Standard WSSecurity Endpoint + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<endpoint-config><config-name>Standard WSSecurity Endpoint<= /config-name><pre-handler-chains><javaee:handler-chain><j= avaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>&l= t;javaee:handler><javaee:handler-name>WSSecurity Handler</javae= e:handler-name><javaee:handler-class>org.jboss.ws.extensions.secur= ity.jaxws.WSSecurityHandlerServer</javaee:handler-class></javaee:h= andler></javaee:handler-chain></pre-handler-chains></endp= oint-config></jaxws-config> + +
+ +
+
+JAX-WS Client Configuration + +Category:Development (Category:Development)The standard client configurati= on is defined in standard-jaxws-client-config.xml + +
Client side port configuration + +You can use stub properties on the client side to chose from one of the co= nfiguration presets: + + + + Hello endpoint =3D service.getPort(Hello.class); +((StubExt) endpoint).setConfigName("Standard WSSecurity Client"); + + + +
+
Available configuration +
Standar= d Client + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<client-config><config-name>Standard Client</config-name>= ;</client-config></jaxws-config> + + +
+
<= title>Standard WSAddressing Client + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<client-config><config-name>Standard WSAddressing Client</c= onfig-name><post-handler-chains><javaee:handler-chain><ja= vaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings><= ;javaee:handler><javaee:handler-name>WSAddressing Handler</java= ee:handler-name><javaee:handler-class>org.jboss.ws.extensions.addr= essing.jaxws.WSAddressingClientHandler</javaee:handler-class></jav= aee:handler></javaee:handler-chain></post-handler-chains><= ;/client-config></jaxws-config> + + +Since 2.0.3 + + +
+
Standard SOAP 1.2 WSAddressing Client + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<client-config><config-name>Standard SOAP 1.2 WSAddressing Cli= ent</config-name><post-handler-chains><javaee:handler-chain&= gt;<javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bindin= gs><javaee:handler><javaee:handler-name>WSAddressing Handler= </javaee:handler-name><javaee:handler-class>org.jboss.ws.extens= ions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>= ;</javaee:handler></javaee:handler-chain></post-handler-chai= ns></client-config></jaxws-config> + + +
+
Standard WSSecurity Client + +<jaxws-config xmlns=3D"urn:jboss:jaxws-config:2.0" xmln= s:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee=3D"http://= java.sun.com/xml/ns/javaee" + xsi:schemaLocation=3D"urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">= ;<client-config><config-name>Standard WSSecurity Client</con= fig-name><post-handler-chains><javaee:handler-chain><java= ee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings><j= avaee:handler><javaee:handler-name>WSSecurityHandlerOutbound</j= avaee:handler-name><javaee:handler-class>org.jboss.ws.extensions.s= ecurity.jaxws.WSSecurityHandlerClient</javaee:handler-class></java= ee:handler></javaee:handler-chain></post-handler-chains><= /client-config></jaxws-config> + +
+ +
+
+Endpoint management + +Category:Production (Category:Production)JBossWS registers MBeans that use= rs can leverage to manage every webservice endpoint. Apart from the obvious= start/stop functionalities, they provide valuable information and statisti= cs about messages processed by the endpoints. + +
Getting= the information + +JBoss ships with a JMX-Console with all the application server MBeans. It = is usually available at URL http://localhost:8080/jmx-console. For endpoint= management you might be interested in the MBeans belonging to the jboss.ws= domain. + + +The application server also has an applet based web-console which basicall= y has the same data as the JMX-Console plus some advanced features includin= g snapshot graphics. + + +Of course you can access an MBean programmatically too. Please refer to th= e JBoss JMX faq for further details; here is a br= ief code snippet you might want to start from in order to access a ManagedE= ndpointMBean from the same virtual machine: +try +{ + MBeanServer server =3D MBeanServerLocator.locate(); + ManagedEndpointMBean mep =3D (ManagedEndpointMBean)MBeanProxyExt.create( + ManagedEndpointMBean.class, + "jboss.ws:context=3Dmy-ctx,endpoint=3DMyEndpoit", + server); + ... +} +catch (Exception e) +{ + e.printStackTrace(); +} + + + +
+
Metrics + +For each deployed endpoint you'll find an org.jboss.wsf.framewor= k.management.ManagedEndpoint MBean providing basic start/stop fu= nctionalities and metrics. Calling a stopped endpoint will always result in= a SOAP fault message. + + +The metrics available for each managed endpoint are: + + + +Min, max, average and total processing time: processing includes both the = WS stack plus application server work and the user business logic + + + + +Last start and stop time + + + + +Request, response and fault count + + + + +
+
Records + +Since 2.0.3JBossWS features a highly configurable records' collection and = management system. Each record is basically composed of a message plus addi= tional information (for example the caller address and the called endpoint = operation).Endpoints can be configured with record processors that are invo= ked whenever a message flow is detected and records are thus created. + + +Every deployed endpoint is configured with default record processors. Howe= ver custom processors as well as record filters can be easily plugged in an= d managed at any time through JMX. This gives users the chance of performin= g advanced analysis of the webservice traffic according to their business r= equirements. + + +Please refer to the records managemen= t page for further details. + + +
+
Snapshots and threshold monitors + +As previously said, the JBoss Web Console has int= eresting features including snapshots and= threshold monitors. = + + +Snapshots allow users to record changes of a given MBean attribute within = a defined time interval. Data are sampled at a given rate and may be plotte= d to graphs with a few clicks. Snapshots are listed in the Web console and = can be created simply browsing to http://localhost:8080/web-console/createS= napshot.jsp . + + +Threshold monitors allow users to be notified whenever a given MBean attri= bute exceed a certain range of values. The threshold monitor's creation and= management processes are similar to those mentioned above for the snapshot= s. Simply browse to http://localhost:8080/web-console/createThresholdMonito= r.jsp . + + +Speaking of WS availability and SLA, this all becomes interesting because = users can monitor and take snapshots of critical attributes like the averag= e/max processing time of a managed endpoint. Moreover, advanced analysis ca= n be performed leveraging ad-hoc attributes of custom record processors. + +
+
+Records management + +Category:Production (Category:Production)Since 2.0.3JBossWS records' colle= ction and management system gives administrators a means of performing cust= om analysis of their webservice traffic as well as exporting communication = logs. + +
What is recorde= d + +Each record is basically composed of a message plus additional information= ; here are the current record attributes: + + + +Creation date + + + + +Source host + + + + +Destination host + + + + +Message type (in/out) + + + + +Invoked endpoint operation + + + + +Message envelope (including both soap:header and soap:body for SOAP messag= es) + + + + +Http headers + + + + +Record group ID (allowing records belonging to the same message flow to be= linked together) + + + + +Of course records may also have meaningful values for a subset of the afor= e mentioned record attributes. + + +
+
Use cases + +What are records useful for? In spite of endpoint metrics that provide response time information= and counts of invocations, records provide users with rich data about the = content of the exchanged messages and their sender/receiver. The record sys= tem allows fine grained management and is customizable according to the use= rs need; some of the use cases supported by the default configuration are: + + + +Logging request and response messages: being able to record messages recei= ved from and sent to a given service consumer without stopping the provider= may be really useful. You just need to set the recording attribute of their endpoint's LogRecorder to true. The added value of t= his logging solution comes from the use of filters through which messages c= oming from a given address and related to a given wsdl operation only can b= e logged. + + + + +Accountability: service providers may want to know which consumers are act= ually hitting a given service. This can be done for example using the getClientHosts functionality of the MemoryBufferRecorder on= ce it has been switched to recording state. + + + + +Getting statistics, filtering records: service administrators might want t= o see the last records related to a given endpoint or operation, the last r= ecords related to messages coming from a given customer and the response th= e system gave them, etc. These information can be obtained using the getRecordsByOperation, getRecordsByClientHost or the more general getMatchingRecords function= ality of the MemoryBufferRecorder. + + + + +
+
H= ow it works and how to use it + +The recording system is composed of + + + +JAX-WS handlers intercepting inbound and outbound communication + + + + +Record processors plugged into deployed endpoints; handlers collect record= s and send them to every processors through the current endpoint. Processor= s may store records, convert them, log them, ... + + + + +MBean views of processors that can be used to configure and fine tune reco= rding at runtime + + + + +Record filters allowing selection of information to be recorded as well as= providing means of performing custom queries on the saved records. + + + +
Server side + +On server side records are collected by JAX-WS handlers and passed to the = configured processors. JBossWS comes with two default record processors tha= t are plugged into every endpoint during the deployment: + + + +LogRecorder: a simple record processor that writes records to the configur= ed log. + + + + +MemoryBufferRecorder: a record processor that keeps the last received reco= rds in memory and allows user to search / get statistics on them. + + + + +Every processors can be fine tuned to process some record attributes only = according to the user and/or performance requirements. Default processors a= re not in recording mode upon creation, thus you need to switch them to rec= ording mode through their MBean interfaces (see the Recording flag in the jmx-console). + + +Common processor properties and their respective defaults values are: + + + +processDestinationHost (true) + + + + +processSourceHost (true) + + + + +processHeaders (true) + + + + +processEnvelope (true) + + + + +processMessageType (true) + + + + +processOperation (true) + + + + +processDate (true) + + + + +recording (false) + + + + +The recorders can be configured in the stacks bean configuration + + +<bean name=3D"WSMemoryBufferRecorder" class=3D"org.jbos= s.wsf.framework.management.recording.MemoryBufferRecorder"><property = name=3D"recording">false</property></bean><bean name=3D"W= SLogRecorder" class=3D"org.jboss.wsf.framework.management.recording.LogReco= rder"><property name=3D"recording">false</property></bean= >The recording system is available for all the JBossWS = supported stacks. However slightly different procedure is required to enabl= e it depending on the used stack. + + + +Native stack + + + + +Native stack comes with pr= eset endpoint configurations. The default standard endpoint already = has the server side recording handler:<endpoint-config&g= t;<config-name>Standard Endpoint</config-name><pre-handler-c= hains><javaee:handler-chain><javaee:protocol-bindings>##SOAP= 11_HTTP</javaee:protocol-bindings><javaee:handler><javaee:ha= ndler-name>Recording Handler</javaee:handler-name><javaee:handl= er-class>org.jboss.wsf.framework.invocation.RecordingServerHandler</j= avaee:handler-class></javaee:handler></javaee:handler-chain>= </pre-handler-chains></endpoint-config>thus no= thing is required to use it since it is automatically installed in the pre-= handler-chain. Of course you might want to add it to other endpoint configu= rations you're using. + + + +Metro and CXF stacks + + + + +Other stacks require users to manually add the org.jboss.wsf.fra= mework.invocation.RecordingServerHandler to their endpoint handl= er chain. This can be done t= he same way common user handlers are added. + + +Once the handler is properly added to the chain, log recording configurati= on is agnostic to the used stack. Users just need to tune the processors pa= rameters though their MBean interfaces. + + +
+
Client side + +JMX management of processors is of course available on server side only. H= owever users might also be interested in collecting and processing records = on client side. Since handlers can be set on client side too, customer hand= lers could be configured to capture messages almost like the Reco= rdingServerHandler does. This is left to the users since it is d= irectly linked to their custom needs. For instance a common use could be to= pass client side collected records to the LogRecorder. + + +
+ +
+
Advanced hints</t= itle> +<section id=3D"Records_management_Adding_custom_recorders"><title>Adding c= ustom recorders + +As previously said, the recording system is extensible: JBossWS users can = write their own processors and plug them at runtime into their deployed end= points through the addRecordProcessor functionality of= the ManagedEndpoint MBean. Every processor needs to implement the org.jboss.wsf.spi.management.recording.RecordProcessor interfa= ce. Then you can choose one of the two following options: + + + +Give you record processor an MBean interface declaring the manageable attr= ibutes: the recording system will plug your processor to the endpoint and r= egister a management MBean for it using your interface. This allows you to = create highly configurable custom processors. For an example of this develo= pment option, take a look at the org.jboss.wsf.framework.manageme= nt.recording.MemoryBufferRecorder. + + + + +Add your record processor to the managed endpoint as is: the recording sys= tem will plug it to the endpoint and register a standard management MBean f= or its basic processing configuration. The org.jboss.wsf.framewor= k.management.recording.LogRecorder is an example of this develop= ment option. + + + + +A code snippet showing how to get the MBeanProxy instance which you can in= voke MBean with can be found here. + + +
+
Handler's p= osition + +Of course the recording handler's position in the handler chain influences= the collected records. As a matter of fact some information may or may not= be available at a given point of the handler chain execution. The standard= endpoint configuration declares the RecordingServerHandler into the pre-ha= ndler-chain. Speaking of the native stack, this means for example that you'= ll get the invoked operation data and that decrypted messages will be recor= ded if using WS-Security, since the WS-Security handler runs in the post-ha= ndler-chain. Users might want to change the recording handler's position in= the chain according to their requirements. + + +
+
Multiple handl= ers + +Records attributes include a record group ID that is meant to link records= whose messages belong to the same message flow (a request-response for exa= mple). In order to set the right group ID to the records, the current ID is= associated to the thread that is processing the endpoint invocation. This = means that multiple related records can be linked together and extracted to= gether from a processor. + + +For this reason, you might want to install multiple recording handlers int= o different points of the handler chain. For instance, it could make sense = to record messages both before and after encryption/decryption when using W= S-Security. + + +
+ + +
Future extensi= ons + +This paragraph covers eventual future extensions and/or idea JBossWS users= may want to leverage for their own business. + +
Database recor= der + +The MemoryBufferRecorder provides interesting functionalities to query the= collected records set. For obvious reasons, records are discarded once a g= iven size of the buffer is reached. + + +A DB based recorder could be developed; it should work the same way the Me= moryBufferRecorder does, except for records that should be saved through a = given datasource. This will provide persistence of data even in case of app= lication server reboot and webservice application redeploy. It will also al= low records coming from different node of a cluster to be stored together. = Finally this would allow administrators to directly query the database, whi= ch might be far more efficient. + + +
+
Custom log wri= ter + +The idea of getting statistics from collected records could be further exp= loited getting custom logs from the records. These logs could be outputted = by a custom processor in standard or proprietary formats allowing them to b= e imported into eventual third-party log processing tools which might offer= complex/funky graphic or statistic functionalities and so on. + + +
+ +
+
References + +You might want to take a look at the org.jboss.wsf.framework.man= agement.recording and org.jboss.wsf.spi.management.rec= ording packages in the source code to better understand how all = this works and can be used. + +
+
+WS-Security options + +Category:Production (Category:Production)Category:Transition / staging (Ca= tegory:Transition / staging)JBossWS implements WS-Security 1.0 specificatio= ns to provide users with message level security. The user guide explains how to configure WS-Security = through declaration files and annotations; for this aim, a simple example s= hows how to sign (and require signature of) messages. + + +This page instead goes deeper into the JBossWS WS-Security configuration d= etails, covering more advanced topics. + +
U= sername Token Authentication + +The following configuration allows clients to authenticate through a Usern= ame Token (1). Thanks to the JAAS integration, the received token will auto= matically be verified against the configured JBoss JAAS Security Domain.<jboss-ws-security xmlns=3D"http://www.jboss.com/ws-securit= y/config" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://www.jboss.com/ws-security/config = + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> + <config> +(1) <username/> +(2) <timestamp ttl=3D"300"/> + </config> + </jboss-ws-security> +Line (2) states that a timestamp element must be present = in the message and that the message can not be older than 300 seconds; this= is used to prevent replay attacks. + + +On the server side you should have:<jboss-ws-security x= mlns=3D"http://www.jboss.com/ws-security/config" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://www.jboss.com/ws-security/config + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"><= ;config><timestamp ttl=3D"300"/><requires> +(3) <username/></requires></config></jboss-ws-securi= ty>Line (3) sets the requirement of a Username Token fo= r authentication. + + +Please note that this way username and password appear as simple text in t= he SOAP header. Thus it is strongly suggested to use a secure transport. + + +
+
X509 Cer= tificate Token +
Encryption + +Using X509v3 certificates you can both sign and encrypt messages. <jboss-ws-security xmlns=3D"http://www.jboss.com/ws-security/con= fig" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://www.jboss.com/ws-security/config + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> +(1) <key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>&= lt;key-store-password>password</key-store-password><key-store-t= ype>jks</key-store-type><trust-store-file>WEB-INF/wsse10.tru= ststore</trust-store-file><trust-store-password>password</tr= ust-store-password><config><timestamp ttl=3D"300"/> +(2) <sign type=3D"x509v3" alias=3D"1" includeTimestamp=3D"true"/> +(3) <encrypt type=3D"x509v3" + alias=3D"alice" + algorithm=3D"aes-256" + keyWrapAlgorithm=3D"rsa_oaep" + tokenReference=3D"keyIdentifier" /> +(4) <requires><signature/><encryption/></requires>= ;</config></jboss-ws-security>The server confi= guration shown above includes: + + + +Keystore and truststore information: location, password and type. + + + + +Signature configuration: you need to provide the certificate/key pair alia= s to use. includeTimestamp specifies whether the times= tamp is to be signed too to prevent tampering. + + + + +Encryption configuration: you need to provide the certificate/key pair ali= as to use. = + + + + +Optional security requirements: incoming messages should be both signed an= d encrypted. + + + + +Client side configuration works the same way. + +
Algorithms + +Asymmetric + symmetric encryption is performed whenever the encr= ypt element is found. Thus message data are encrypted using a ge= nerated symmetric secret key. This is written in the SOAP header after bein= g encrypted (wrapped) with the receiver public key. You can set both the en= cryption and key wrap algorithms. + + + +Supported encryption algorithms + + + + + +AES 128 (aes-128) (default) + + + + +AES 192 (aes-192) + + + + +AES 256 (aes-256) + + + + +Triple DES (triple-des) + + + + + +Supported key wrap algorithms + + + + + +RSA v.1.5 (rsa_15) (default) + + + + +RSA OAEP (rsa_oaep) + + + + +The Unlimited Strength Java(TM) Cryptography Extension installation might be required to run some strong algorithms (like AES-= 256). Please note that your country might have limits on allowed crypto str= ength. + + +
+
Token referenc= es + +For interoperability reason you might want to configure the type of refere= nce to encryption token to be used. For instance, Microsoft Indigo doesn't = support direct reference to local binary security tokens that is the JBossW= S default reference type choice.Allowed values for tokenReference= attribute are: + + + +directReference (default) + + + + +keyIdentifier + + + + +x509IssuerSerial + + + + +Please refer to the X.509 Token Profile = 1.0 specification for further details on token referenc= es. + + +
+ +
+
Targets c= onfiguration + +JBossWS gives you a fine grained control over the elements that have to be= signed or encrypted. + + +This allows you to encrypt important data only (like credit card numbers) = without waisting time on other information exchanged by the same service (e= mail addresses, for example).To configure this, you just need to specify th= e QName of the SOAP elements to encrypt. The default behavior is to encrypt= the whole SOAP body.<encrypt type=3D"x509v3" alias=3D"a= lice"><targets><target type=3D"qname">{http://www.my-company= .com/cc}CardNumber</target><target type=3D"qname">{http://www.m= y-company.com/cc}CardExpiration</target><target type=3D"qname" con= tentOnly=3D"true">{http://www.my-company.com/cc}CustomerData</target&= gt;</targets></encrypt>?The contentO= nly attribute states whether the content of the element is to be= encrypted as opposed to the entire element (default behavior). Target can = be specified also for requirements upon message receipt. + + +
+ +
+
Further inf= ormation + + +The complete wsse configuration is specified in the src/main/res= ources/schema/jboss-ws-security_1_0.xsd schema that is available= in the source code base. + + + + +The advanced examples described above are covered by the interoperability = scenarios described here. + + + + +If you have doubts on the keystore/truststore content requirements for sig= ning/encrypting messages, read here. Moreover you can find a text file in the sources showing = the store configuration used for the interoperability tests (src/= test/resources/interop/nov2007/wsse/shared/META-INF/readme.txt). + + + + +
+
+FAQ + +Category:Documentation (Category:Documentation) + + + + +
General +
Which version of JBoss Application Server do I need = to use JBossWS? + +JBossWS integrates with most current JBoss Application Server releases as = well as earlier ones, that did implement the J2EE 1.4 specifications. Event= though JAX-RPC, the web service specification for J2EE 1.4, is still suppo= rted JBossWS does put a clear focus on JAX-WS. + + +Currently, JBossWS has integration layers for the JBossAS-5.0, JBossAS-4.2= , JBossAS-4.0.5 and above; download and installation instructions are avail= able on this WIKI. + + +Finally, if you need to use web services with previous AS releases, please= refer to the Legacy Documentation + + +
+
What are the benefits of using J2EE web services? + +JBossWS ships both a J2EE-1.4 compliant and a JavaEE5 compliant web servic= e stacks; the first one is based on the JSR-109 programming model, while th= e second one is based on the JAX-WS programming model. + + +Both stacks come with a great number of advantages for our users. + + +Here are a few: + + + +Portable web service endpoints and clients that do not need to have a depe= ndency on a proprietary stack + + + + +Secure your investment and learn a standard rather than a proprietary solu= tion + + + + +Achieve good interoperability by beeing BasicProfile-1.1 compliant + + + + +Take advantage of test coverage that comes with Sun's Compatibility Test S= uite (>2300 WS tests) + + + + +Good integration with the overall JBoss architecture i.e. hot deployment/r= edeployment, management interface + + + + +Our support offering covers our own stack and the JBossWS team is dedicate= d full time to improve that constantly. + + +However, starting from release 2.1.0, JBossWS will also provide an integra= tion framework supporting other open source and specification compliant web= service stacks, including Sun Metro and Apache CXF. Since each stack comes= with its own specific functional feature set and performance characteristi= cs users will be able to deploy the stack that best suits their needs. Ther= e will be a common deployment model and management interface to all deploya= ble stacks. + + +
+
How do the various web service stacks compare? + +JBossWSStackComparison + + +
+
What= version of the specs are supported? + +JBossWSSpecStatus + + +
+
Whe= re is the authoritative documentation? + +'''JavaEE5 compliant web services + + + +JAX-WS User guide + + + + +'''J2EE-1.4 compliant web services + + + +JAX-RPC User guide + + + + +
+
Why are my forum posts not answered more quickly? + +Posts to the user forum will be dealt with at the community's leisure. If your business is such= that you need to rely on qualified answers within a known time frame<= /ulink>, the forum might not be your preferred support channel. + + +
+
Are ther= e any samples I can look at? + +Yes, samples are available from the JBossWS download page. + + +
+
Is JAXW= S, JSR181, EJB3 supported? + +Yes, JAXWS, JSR181 and EJB3 are supported all together starting from JBoss= WS-1.2.0.GA. Please refer the JAX-WS user guide for further details and usa= ge informations. + + +In JBossWS-1.0.x we provided a preview implementation for JSR-181 that wor= ked for basic usecases, namely + + + +rpc/literal, document/literal operations with primitive types + + + + +JAXRPC handlers using @HandlerChain + + + + +One way invocations + + + + +JAXWS, which JSR181 is part of, delegates all marshalling concerns to JAXB= . For this to work, complex beans must be annotated with JAXB annotations. = Basically, the type mapping that was contained in JSR109 jaxrpc-mapping.xml= is now in JAXB annotations. + + +With JBossWS-1.0.x all marshalling is done through JBossXB, which does not= understand JAXB annotations. + + +Marshalling concerns that rely on JAXB functionality are not supported in = JBossWS-1.0.x. In JBossWS-1.0.x JSR181 is provided as is and will not be ex= tended. + + +
+
What are the advantages of JAX-WS over JAX-RPC? + +JAX-WS_vs_JAX-RPC + + +
+ +
+
Installation +
How do I install JBossWS on jboss-4.0.x non EJB3? + +Please refer to the installation guide. + + +
+
How do I = install JBossWS on tomcat? + +JBossWS came with a Tomcat porting layer up to release 1.2.1.GA. Recently = this has been dropped because of too little community interest. + + +For installation instructions of old JBossWS releases on Tomcat please ref= er to the Legacy documentation. + + +
+ +
+
Development +
What = do I do if I think there is a bug? + + +Check if it works with the latest sources. + + + + +Checkout the Road = Map if you are using the latest release or the Change Log if you are using another one. + + + + +Finally, if your bug hasn't been reported yet, please create a JBossWS JIRA issue and attach a sample deployment that allows us to reproduce what = you are seeing. Idealy, the sample deployment is a webapp packaged as a war= that shows the issue when we click on a link. The war should also contain = the sources. + + + + +
+
Where= is the JBossWS source repository? + +Please refer to Subversion. + + +
+
How c= an I build and install the latest? + +Please refer to the development guide: Building_From_Source + + +
+ +
+
Server + +see al + +
How does rewriting of the soap address in WSDL work? + +Have a look at jbossws.sar/jbossws.beans/META-INF/jboss-beans.xml + + +<bean name=3D"WSServerConfig" class=3D"org.jboss.wsf.sp= i.management.BasicServerConfig"><property name=3D"webServiceHost">= ${jboss.bind.address}</property><property name=3D"modifySOAPAddres= s">true</property></bean> + + +If instead of a folder jbossws.sar/jbossws.beans you = have a file you will need to extract the jbossws.beans= (It is just a normal archive) and convert it into an exploded deployment. + + +Instead of hardcoding the correct <soap:address> in the WSDL on the = client side, you can use jboss-client.xml to point to the server side gener= ated WSDL + + +<jboss-client><jndi-name>jbossws-client</jn= di-name><service-ref><service-ref-name>service/MyService<= /service-ref-name><wsdl-override>http://@jboss.bind.address@:8080/= jaxws-test/MyService?wsdl</wsdl-override></service-ref></jbo= ss-client> + + +This of course has the disadvantage that the client has to do an HTTP GET = when the Service is constructed. + + +
+
<= title>How do I know what endpoint address is being used? + +The endpoint context root is computed as follows + + +1.) Use the explicit context root from the web meta data + + +Can be set in jboss-web.xml and is only relevant for JSE endpoints. + + +2.) Use the explicit context root from @WebContext.contextRoot + + +Can only be set on EJB endpoints. + + +3.) Use the explicit context root from webservices/context-root + + +Can be set in jboss.xml and is only relevant for EJB endpoints. + + +4.) Use the explicit context root from port-component/port-component-uri + + +For backward compatibility, this uses the first token from port-component-= uri in jboss.xml.It is only relevant for legacy EJB endpoints and should no= t be used. = + + +5.) Use the implicit context root derived from the deployment name + + +If the context root is not explicitly set we fall back to the simple deplo= yment name for both JSE and EJB endpoints. If the endpoint is deployed as p= art of an EAR, the context root is prepended by simple EAR name. + + +The URL pattern is computed as follows + + +1) Use the explicit url-pattern from the servlet mappings = + + +Must be set in web.xml and is only relevant for JSE endpoints. + + +2) Use the explicit url-pattern from port-component/port-component-uri + + +Can be set in jboss.xml and is only relevant for EJB endpoints. + + +3) Use the explicit url-pattern from @WebContext.urlPattern = + + +Can only be set on EJB endpoints. + + +4) Use the implicit url-pattern from ejb-name + + +If the url-pattern for an EJB endpoint is not explicitly set, we fall back= to the ejb-name. + + +Examples + + + +(a)Stateless +(a)WebService +(a)WebContext( contextRoot =3D "/webservices" ) +(a)Remote( UserService.class ) +public class ExampleServiceBean implements ExampleService { + ... +} + + + +Will bind to http://localhost:8080/webservices/ExampleServiceBean + + + +(a)Stateless +(a)WebService +(a)WebContext( contextRoot =3D "/webservices" , urlPattern=3D"/ExampleServ= ice" ) +(a)Remote( UserService.class ) +public class ExampleServiceBean implements ExampleService { + ... +} + + + +Will bind to http://localhost:8080/webservices/ExampleService + + +The default behavior in jboss 4.0.5 was to use the jar file name followed = by the ejb name. This can be replicated by using the WebContext annotation = e.g. + + + +(a)WebService +(a)WebContext( contextRoot =3D "/jar-file-name" , urlPattern=3D"/ejb-name"= ) + + + +
+
What are the advantages and disadvantages of using T= omcat embedded? + +What are the advantages and disadvantages of using Tomcat embedded inside = of JBoss Application Server versus running Tomcat independently? + + +If you are using advanced J2EE features (JMS, JAAS, EJB, etc.), then you n= eed a complete J2EE application server (JBoss AS) and one question to consi= der is whether you need to separate the JSP/Servlet tier from the applicati= on server. In this scenario, you should consider using Apache Tomcat inside= of JBoss AS for significant performance improvements (ex. JSPs can call EJ= Bs via pass-by-reference), unless your architecture or corporate security p= olicies dictate otherwise. + + +If you are using Tomcat for basic JSPs and servlets then read below. + + +Advantages of Tomcat inside JBoss AS : + + + +Easily grow and enhance your applications when other J2EE requirements ari= se (EJB, JMS, JAAS, etc.) + + + + +JDBC connection pooling + + + + +Advanced clustering + + + +Simple method of deploying/undeploying applications to entire cluster (far= m deployment) + + + + +Improved performance through HttpSession replica= tion via JBossCache + + + + + + +Simplified Hot Deployment & Hot Redeployment + + + + +AOP enablement of JSPs & Servlets + + + + +Ability to easily upgrade to using J2EE services such as JMS, JTA, JNDI, e= tc. + + + + +Ability to centrally manage and monitor Tomcat with other JBoss services + + + + +Write access to JNDI at runtime (Tomcat's is read-only at runtime) + + + + +If you run the JBoss AS 4.0.3 (or higher) installer at http://labs.jboss.c= om/jbossas/downloads, you can choose from a variety of install profiles inc= luding a profile that installs Tomcat along with additional JMX JTA, JNDI, = Security, and deployment services pre-configured. + + +Advantages of Tomcat Standalone: + + + +Maybe simplicity of administration? (although this may be of little value = because JBoss allows you to strip down the application server so there is l= ittle else running) + + + + +Defaults to isolated classloading for WARs (however, there is a simple con= figuration in JBoss AS called "UseJBossWebLoader" which does the same thing) + + + + +
+
How= to use JDK JMX JConsole with JBossWS? + +You must use JDK 5 or above on JBoss server sidewith the following JVM pro= perties set on the commandline: + + + +JAVA_OPTS=3D"$JAVA_OPTS -Djavax.management.builder.initial=3Dorg.jboss.sys= tem.server.jmx.MBeanServerBuilderImpl" +JAVA_OPTS=3D"$JAVA_OPTS -Djboss.platform.mbeanserver" +JAVA_OPTS=3D"$JAVA_OPTS -Dcom.sun.management.jmxremote" + + +Running the jconsole against this configuration will bring up a console th= at incorporates both the JBoss and JVM MBeans. + + +For further information follow this link: http://wiki.jboss.org/wiki/Wiki.= jsp?page=3DJBossMBeansInJConsole + + +For JMX information in JBoss AS in general follow this link: http://wiki.j= boss.org/wiki/Wiki.jsp?page=3DFAQJBossJMX + + +
+
Why I'm getting "propertynam= e is not valid property on class mypackage.jaxws.Propertyname"? + +If you are getting the following exception: + + + +org.jboss.ws.WSException: propertyname is not a valid property on class my= package.jaxws.Propertyname + at com.sun.xml.bind.v2.runtime.JAXBContextImpl.getElementPropertyAccessor= (JAXBContextImpl.java) + at org.jboss.ws.metadata.acessor.JAXBAccessor$1$1.create(JAXBAccessor.jav= a) + + + +then you are facing the JAX-WS defaults problem. JAX-WS specification give= s these requirements on Document Wrapped: + + + +From JAX-WS 2.0 19. April 2006: + +3.6.2.1 Document Wrapped: + +* Conformance (Default wrapper bean names): In the absence of customizatio= ns, the wrapper request bean + class MUST be named the same as the method and the wrapper response bean = class MUST be named the + same as the method with a "Response" suffix. The first letter of each bea= n name is capitalized to follow + Java class naming conventions. +* Conformance (Default wrapper bean package): In the absence of customizat= ions, + the wrapper beans package UST be a generated jaxws subpackage of the SEI = package. +* Conformance (Wrapper bean name clash): Generated bean classes must have = unique names within a pack- + age and MUST NOT clash with other classes in that package. Clashes during= generation MUST be reported + as an error and require user intervention via name customization to corre= ct. Note that some platforms = + do not distiguish filenames based on case so comparisons MUST ignore case. + + + +That means when you are using JBossWS with Document Wrapped you can't have= two methods with same nameinside the package without specifying customizat= ions. Thus to solve your problem you have to specify at least: + + + + @javax.xml.ws.RequestWrapper(className=3D"package.UniqueClassName") + @javax.xml.ws.ResponseWrapper(className=3D"package.UniqueClassNameRespons= e") = + + + +method annotations on all overloaded methods (overloaded here means notove= rloaded in class but overloaded in package). + + +
+
How can I access the HttpServletReques= t and HttpServletResponse from my endpoint? + +
+ +
+
Client +
How= do I generate the required artifacts? + +JBossWS ships with a set of tools to generate the required JAX-WS artefact= s to build client implementations. The wsconsum= e tool is used to consume the abstract contract (WSDL) and produce a= nnotated Java classes (and optionally sources) that define it. You can run = wsconsume from the command line and from an Apache Ant target. + + +To run wsconsume from the command line, use the scripts available in the <= emphasis>bin dir of your JBoss AS installation. + + +Here is an example of how to run wsconsume from the command line, generati= ng source and class files in the org.foo package, in a custom directory. + + +wsconsume -k -o custom -p org.foo Example.wsdl + + +For further informations and examples, also check the top-down development stra= tegy in the user guide. + + +Finally, if you need JAX-RPC artifacts generation, please refer to the leg= acy JBossWS tools documentation. + + +
+
How can I leverage the client deployment model? + +The WS client deployment model has many advantages over DII. Most Java app= lications (except the most trivial ones) have a need for registry lookup (J= NDI) and management (JMX). A very minimal jboss configuration has a tiny fo= otprint and provides just that. Therefore, you might want to consider runni= ng your client app on jboss and manage it through jmx-console and have a la= yer of indirection for resource lookup through JNDI. Additionally, you coul= d then use the WS client programming model and obtain preconfigured WS clie= nts form JNDI. + + +
+
How= can I setup my client to use a proxy? + +http://labs.jboss.com/jbossremoting/docs/guide/ch05.html 5.4.10. HTTP(S) C= lient Invoker - proxy and basic authentication + + +
+
What c= lient artifacts are thread safe? + +javax.xml.rpc.ServiceFactory - Just a factory so yes it is thread safe. + + +javax.xml.rpc.Service - A factory for calls and stubs so it is thread safe. + + +javax.xml.rpc.Call - Not thread safe, the API allows for multiple method i= nvocations for a single WS call. + + +javax.xml.rpc.Stub - Contains properties that may be thread specific. Stub= is the interface implemented by the dynamic proxy which delegatesto an imp= lementation of Call. So, whatever is true for Call also holds for the dynam= ic proxy implementing Stub. + + +
+
What client jars = do I need? + +Have a look at wsrunclient.sh. + + +
+
What XML parser do= I need? + +You should use xerces. -Djava.endorsed.dirs=3D$JBOSS_HOME= /lib/endorsed + + +
+ +
+
Tools +
Why do I get a NullPointerException when using wstools? + + +[wstools] java.lang.NullPointerException +[wstools] at java.lang.System.arraycopy(Native Method) +[wstools] at org.apache.xerces.impl.xs.XSModelImpl.getAnnotations(Unknown = Source) +[wstools] at org.jboss.ws.metadata.wsdl.xmlschema.WSSchemaUtils.copyXSMode= l(WSSchemaUtils.java:737) +[wstools] at org.jboss.ws.tools.JavaToXSD.parseSchema(JavaToXSD.java:201) +[wstools] at org.jboss.ws.metadata.wsdl.WSDL11Reader.processTypes(WSDL11Re= ader.java:227) +[wstools] at org.jboss.ws.metadata.wsdl.WSDL11Reader.processDefinition(WSD= L11Reader.java:118) +[wstools] at org.jboss.ws.metadata.wsdl.WSDLDefinitionsFactory.parse(WSDLD= efinitionsFactory.java:145) +[wstools] at org.jboss.ws.tools.WSDLToJava.convertWSDL2Java(WSDLToJava.jav= a:121) +[wstools] at org.jboss.ws.tools.helpers.ToolsHelper.handleWSDLToJavaGenera= tion(ToolsHelper.java:323) +[wstools] at org.jboss.ws.tools.WSTools.process(WSTools.java:138) +[wstools] at org.jboss.ws.tools.WSTools.generate(WSTools.java:120) +[wstools] at org.jboss.ws.tools.ant.wstools.execute(wstools.java:103) + ... + + + +This is a xerces bug that was fixed in 2.7.0. Unfortunately, the latest ve= rsion of ant comes with 2.6.2. You need to update the xerces jars in your A= NT_HOME/lib directory to be at least 2.7.0. + + +
+
How = can I configure RPC parameter names? + +Parameter and result names can be configured using the JSR-181 @WebParam and @WebResult annotatio= ns: +(a)WebMethod(operationName =3D "SecurePing") +(a)WebResult(name =3D "Result") +public String ping( + @WebParam(name =3D "Ping") PingDocument p, = + @WebParam(name =3D "SecHeader", header =3D true) SecurityHeader secHdr) +{ + log.info("ping: " + p + "," + secHdr); + return "pong"; +} + + + +
+
Customizing = WSDL Schema Generation + + + + +Both JBossWS runtime and WSProvide tool use JAXB (concretely JAXBRIContext.generateSchema() method) for WSDL schema generation thus the onlypossible way of sch= ema customization is through javax.xml.bind.annotat= ion.*annotations. + + + Therefore users that want to customize WSDL schema gener= ation process should + + +be familiar with these annotations. We suggest everyone interested in to t= akea look to Java Types To XML chapter o= f JAXB specification. + + +In the case user want to customize the generated WSDL schema and he is not= able to achievethat through javax.xml.bind.annotat= ion.* annotations he have always the possibilityto customize the= generated WSDL contract and force JBossWS runtime<= /emphasis> to use it viajavax.jws.WebService.wsdlLo= cation annotation field. + +
+ +
+
+JAX-WS Annotations + +Category:Development (Category:Development) + +
JAX-WS Annota= tions + +For details, see = JSR-224 - Java API for XML-Based Web Services (JAX-WS) 2.0 + +
javax.x= ml.ws.ServiceMode + +The ServiceMode annotation is used to specify the mode for a provider clas= s, i.e. whether a provider wantsto have access to protocol message payloads= (e.g. a SOAP body) or the entire protocol messages (e.g. aSOAP envelope). + + +
+
javax.xml.= ws.WebFault + +The WebFault annotation is used when mappingWSDL faults to Java exceptions= , see section 2.5. It is usedto capture the name of the fault element used = when marshalling the JAXB type generated from the globalelement referenced = by the WSDL fault message. It can also be used to customize the mapping of = servicespecific exceptions to WSDL faults. + + +
+
java= x.xml.ws.RequestWrapper + +The RequestWrapper annotation is applied to the methods of an SEI. It is u= sed to capture the JAXB generatedrequest wrapper bean and the element name = and namespace for marshalling / unmarshalling the bean.The default value of= localName element is the operationName as defined in WebMethod annotation = andthe default value for the targetNamespace element is the target namespac= e of the SEI.When starting fromJava, this annotation is used to resolve ove= rloading conflicts in document literal mode. Only the classNameelement is r= equired in this case. + + +
+
jav= ax.xml.ws.ResponseWrapper + +The ResponseWrapper annotation is applied to the methods of an SEI. It is = used to capture the JAXBgenerated response wrapper bean and the element nam= e and namespace for marshalling / unmarshalling thebean. The default value = of the localName element is the operationName as defined in the WebMethodap= pended with ?Response? and the default value of the targetNamespace element= is the target namespaceof the SEI. When starting from Java, this annotatio= n is used to resolve overloading conflicts in documentliteral mode. Only th= e className element is required in this case. + + +
+
ja= vax.xml.ws.WebServiceClient + +The WebServiceClient annotation is specified on a generated service class = (see 2.7). It is used to associatea class with a specific Web service, iden= tify by a URL to a WSDL document and the qualified nameof a wsdl:service el= ement. + + +
+
javax.x= ml.ws.WebEndpoint + +The WebEndpoint annotation is specified on the getPortName() methods of a = generated service class(see 2.7). It is used to associate a get method with= a specific wsdl:port, identified by its local name (aNCName). + + +
+
= javax.xml.ws.WebServiceProvider + +The WebServiceProvider annotation is specified on classes that implement a= strongly typed javax-.xml.ws.Provider. It is used to declare that a class = that satisfies the requirements for a provider (see5.1) does indeed define = a Web service endpoint, much like the WebService annotation does for SEI-ba= sedendpoints. + + +The WebServiceProvider and WebService annotations are mutually exclusive. + + +
+
javax.x= ml.ws.BindingType + +The BindingType annotation is applied to an endpoint implementation class.= It specifies the binding touse when publishing an endpoint of this type. + + +The default binding for an endpoint is the SOAP 1.1/HTTP one + + +
+
javax= .xml.ws.WebServiceRef + +The WebServiceRef annotation is used to declare a reference to a Web servi= ce. It follows the resourcepattern exemplified by the javax.annotation.Reso= urce annotation in JSR-250 [32].The WebServiceRef annotation is required to= be honored when running on the Java EE 5 platform, whereit is subject to t= he common resource injection rules described by the platform specification = [33]. + + +
+
java= x.xml.ws.WebServiceRefs + +The WebServiceRefs annotation is used to declare multiple references to We= b services on a single class.It is necessary to work around the limition ag= ainst specifying repeated annotations of the same type onany given class, w= hich prevents listing multiple javax.ws.WebServiceRef annotations one after= theother. This annotation follows the resource pattern exemplified by the = javax.annotation.Resourcesannotation in JSR-250. + + +Since no name and type can be inferred in this case, each WebServiceRef an= notation inside a WebServiceRefsMUST contain name and type elements with no= n-default values.The WebServiceRef annotation is required to be honored whe= n running on the Java EE 5 platform, whereit is subject to the common resou= rce injection rules described by the platform specification. + + +
+
javax.xml.ws= .Action + +The Action annotation is applied to themethods of a SEI. It used to genera= te the wsa:Action on wsdl:inputand wsdl:output of each wsdl:operation mappe= d from the annotated methods. + + +
+
javax.x= ml.ws.FaultAction + +The FaultAction annotation is used within the Action annotation to generat= e the wsa:Action elementon the wsdl:fault element of each wsdl:operation ma= pped from the annotated methods. + + +
+
A= nnotations Defined by JSR-181 + +JSR-181 defines the syntax and semantics of Java Web Service (JWS) metadat= a and default values. = + + +For details, see JSR 181 - Web Services Metadata for the Java Platform + +
javax.jws.W= ebService + +Marks a Java class as implementing a Web Service, or a Java interface as d= efining a Web Service interface. + + +
+
javax.jws.We= bMethod + +Customizes a method that is exposed as a Web Service operation. + + +
+
javax.jws.OneWa= y + +Indicates that the given web method has only an input message and no outpu= t. Typically, a oneway method returns the thread of control to the calling = application prior to executing the actual business method. A JSR-181 proces= sor is REQUIRED to report an error if an operation marked @Oneway has a ret= urn value, declares any checked exceptions or has any INOUT or OUT paramete= rs. + + +
+
javax.jws.Web= Param + +Customizes the mapping of an individual parameter to a Web Service message= part andXML element. + + +
+
javax.jws.We= bResult + +Customizes the mapping of the return value to a WSDL part and XML element. + + +
+
javax.jws.= SOAPBinding + +Specifies the mapping of the Web Service onto the SOAP message protocol. = + + +The SOAPBinding annotation has a target of TYPE and METHOD. The annotation= may be placed on a method if and only if the SOAPBinding.style is DOCUMENT= . Implementations MUST report an error if the SOAPBinding annotation is pla= ced on a method with a SOAPBinding.style of RPC. Methods that do not have a= SOAPBinding annotation accept the SOAPBinding behavior defined on the type. + + +
+
javax.jws= .HandlerChain + +The @HandlerChain annotation associates the Web Service with an externally= defined handler chain. = + + +It is an error to combine this annotation with the @SOAPMessageHandlers an= notation. = + + +The @HandlerChain annotation MAY be present on the endpoint interface and = service implementation bean. The service implementation bean?s @HandlerChai= n is used if @HandlerChain is present on both. + + +The @HandlerChain annotation MAY be specified on the type only. The annota= tion target includes METHOD and FIELD for use by JAX-WS-2.0. + +
+ +
+ +
+
+Wsconsume + +wsconsume is a command line tool and ant task that "consumes" the abstract= contract (WSDL file) and produces portable JAX-WS service and client artif= acts. For a more detailed overview, see "Using wsconsume". + +
Command Line Tool</titl= e> +<para> +The command line tool has the following usage:<programlisting> +usage: wsconsume [options] <wsdl-url> +options: = + -h, --help Show this help message + -b, --binding=3D<file> One or more JAX-WS or JAXB binding files + -k, --keep Keep/Generate Java source + -c --catalog=3D<file> Oasis XML Catalog file for entity resolution + -p --package=3D<name> The target package for generated source + -w --wsdlLocation=3D<loc> Value to use for @WebService.wsdlLocation + -o, --output=3D<directory> The directory to put generated artifacts + -s, --source=3D<directory> The directory to put Java source + -q, --quiet Be somewhat more quiet + -t, --show-traces Show full exception stack traces +</programlisting> +</para> +<section id=3D"Wsconsume_Examples"><title>Examples + +Generate artifacts in Java class form only: +wsconsume Example.wsdl + + + +Generate source and class files: +wsconsume -k Example.wsdl + + + +Generate source and class files in a custom directory: +wsconsume -k -o custom Example.wsdl + + + +Generate source and class files in the org.foo package: +wsconsume -k -p org.foo Example.wsdl + + + +Generate source and class files using multiple binding files: +wsconsume -k -b wsdl-binding.xml -b schema1-binding.xml -b schema2-binding= .xml + + + +
+ + +
Ant Task + +Note + + +With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSConsumeT= ask + + +The wsconsume ant task has the following attributes:
+<tgroup cols=3D"3"><tbody><row> +<entry> +Attribute +</entry> +<entry> +Description +</entry> +<entry> +Default +</entry> + +</row> +<row> +<entry> +fork +</entry> +<entry> +Whether or not to run the generation task in a separate VM. +</entry> +<entry> +true +</entry> + +</row> +<row> +<entry> +keep +</entry> +<entry> +Keep/Enable Java source code generation. +</entry> +<entry> +false +</entry> + +</row> +<row> +<entry> +catalog +</entry> +<entry> +Oasis XML Catalog file for entity resolution +</entry> +<entry> +none +</entry> + +</row> +<row> +<entry> +package +</entry> +<entry> +The target Java package for generated code. +</entry> +<entry> +generated +</entry> + +</row> +<row> +<entry> +binding +</entry> +<entry> +A JAX-WS or JAXB binding file +</entry> +<entry> +none +</entry> + +</row> +<row> +<entry> +wsdlLocation +</entry> +<entry> +Value to use for @WebService.wsdlLocation +</entry> +<entry> +generated +</entry> + +</row> +<row> +<entry> +destdir +</entry> +<entry> +The output directory for generated artifacts. +</entry> +<entry> +"output" +</entry> + +</row> +<row> +<entry> +sourcedestdir +</entry> +<entry> +The output directory for Java source. +</entry> +<entry> +value of destdir +</entry> + +</row> +<row> +<entry> +verbose +</entry> +<entry> +Enables more informational output about command progress. +</entry> +<entry> +false +</entry> + +</row> +<row> +<entry> +wsdl +</entry> +<entry> +The WSDL file or URL +</entry> +<entry> +n/a +</entry> + +</row> +</tbody></tgroup> +</table> + +</para> +<para> +Also, the following nested elements are supported:<table> +<title/><tgroup cols=3D"3"><tbody><row> +<entry> +Element +</entry> +<entry> +Description +</entry> +<entry> +Default +</entry> + +</row> +<row> +<entry> +binding +</entry> +<entry> +A JAX-WS or JAXB binding file +</entry> +<entry> +none +</entry> + +</row> +<row> +<entry> +jvmarg +</entry> +<entry> +Allows setting of custom jvm arguments +</entry> + +</row> +</tbody></tgroup> +</table> + +</para> +<section id=3D"Wsconsume_Examples_2"><title>Examples + +Generate JAX-WS source and classes in a separate JVM with separate directo= ries, a custom wsdl location attribute, and a list of binding files from fo= o.wsdl:<wsconsume = + fork=3D"true" + verbose=3D"true" + destdir=3D"output" + sourcedestdir=3D"gen-src" + keep=3D"true" + wsdllocation=3D"handEdited.wsdl" = + wsdl=3D"foo.wsdl"> + <binding dir=3D"binding-files" includes=3D"*.xml" excludes=3D"bad.xml"= /> +</wsconsume> + + + + + + + +
Ant Task + +Note + + +With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSProvideT= ask + + +The wsprovide ant task has the following attributes:
+<tgroup cols=3D"3"><tbody><row> +<entry> +Attribute +</entry> +<entry> +Description +</entry> +<entry> +Default +</entry> + +</row> +<row> +<entry> +fork +</entry> +<entry> +Whether or not to run the generation task in a separate VM. +</entry> +<entry> +true +</entry> + +</row> +<row> +<entry> +keep +</entry> +<entry> +Keep/Enable Java source code generation. +</entry> +<entry> +false +</entry> + +</row> +<row> +<entry> +destdir +</entry> +<entry> +The output directory for generated artifacts. +</entry> +<entry> +"output" +</entry> + +</row> +<row> +<entry> +resourcedestdir +</entry> +<entry> +The output directory for resource artifacts (WSDL/XSD). +</entry> +<entry> +value of destdir +</entry> + +</row> +<row> +<entry> +sourcedestdir +</entry> +<entry> +The output directory for Java source. +</entry> +<entry> +value of destdir +</entry> + +</row> +<row> +<entry> +genwsdl +</entry> +<entry> +Whether or not to generate WSDL. +</entry> +<entry> +false +</entry> + +</row> +<row> +<entry> +verbose +</entry> +<entry> +Enables more informational output about command progress. +</entry> +<entry> +false +</entry> + +</row> +<row> +<entry> +<emphasis role=3D"bold">sei</emphasis> +</entry> +<entry> +<emphasis role=3D"bold">Service Endpoint Implementation.</emphasis> +</entry> + +</row> +<row> +<entry> +classpath +</entry> +<entry> +The classpath that contains the service endpoint implementation. +</entry> +<entry> +"." +</entry> + +</row> +</tbody></tgroup> +</table> + +</para> +<section id=3D"Wsprovide_Examples_2"><title>Examples + +Executing wsprovide in verbose mode with separate output directories for s= ource, resources, and classes:<target name=3D"test-wspro= ivde" depends=3D"init"> + <taskdef name=3D"wsprovide" classname=3D"org.jboss.wsf.spi.tools.ant.W= SProvideTask"> + <classpath refid=3D"core.classpath"/> + </taskdef> + <wsprovide + fork=3D"false" + keep=3D"true" + destdir=3D"out" + resourcedestdir=3D"out-resource" + sourcedestdir=3D"out-source" + genwsdl=3D"true" = + verbose=3D"true" + sei=3D"org.jboss.test.ws.jaxws.jsr181.soapbinding.DocWrappedServiceImpl"&= gt; + <classpath> + <pathelement path=3D"${tests.output.dir}/classes"/> + </classpath> + </wsprovide> +</target> + + + +Category:Tools (Category:Tools) + + + + +
+Wsrunclient + +wsrunclient is a command line tool that invokes a JBossWS JAX-WS Web Servi= ce client.It builds the correct classpath and endorsed libs for you. Feel f= ree to usethe code for this script to make your own shell scripts. It is op= en sourceafter all. + +
Usage + + wsrunclient [-classpath <additional class path>] &l= t;java-main-class> [arguments...] + + +
+
Examples + +Invoking a standalone JAX-WS client:wsrunclient echo.EchoC= lient + + +Invoking a standalone JAX-WS client that uses external jars:wsrunclient -classpath jar1.jar:jar2.jar echo.EchoClient + + +Category:Tools (Category:Tools) + +
+
+ \ No newline at end of file Property changes on: stack/native/tags/jbossws-native-2.0.3.GA/JBossWS-2.0.= 3.GA-doc_export.xml ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF --===============1171134869176104408==--