The page you’re looking for does not exist. It may have been moved. You can return to the start page, or follow one of the links in the navigation to the left.
+If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken. +If you typed the URL of this page manually, please double check that you entered the address correctly.
+The page you requested has been relocated to https://playframework.github.io/play-soap/2.x/index.html.
diff --git a/play-soap/1.x/handlers.html b/play-soap/1.x/handlers.html new file mode 100644 index 0000000..f6056f1 --- /dev/null +++ b/play-soap/1.x/handlers.html @@ -0,0 +1,388 @@ + + + + + +JAX WS provides an abstraction called handlers to allow cross cutting concerns to be implemented across all calls. Handlers are able to inspect and modify the incoming and outgoing messages, including SOAP data objects and request/response headers. They’re also able to block requests from being made entirely.
+Use cases for handlers include logging, security, monitoring, and many other application specific concerns. For examples of how to implement security using handlers, see Security.
+A handler can be implemented by extending a sub type of javax.xml.ws.handler.Handler. Which subtype you implement depends on your use case, for more details about the types of handlers, see here. We’ll implement a simple logging handler, to do this we extend javax.xml.ws.handler.soap.SOAPHandler.
import javax.xml.namespace.QName;
+import javax.xml.soap.SOAPMessage;
+import javax.xml.ws.handler.MessageContext;
+import javax.xml.ws.handler.soap.SOAPHandler;
+import javax.xml.ws.handler.soap.SOAPMessageContext;
+import java.util.Set;
+
+public class LoggingHandler implements SOAPHandler<SOAPMessageContext> {
+ public Set<QName> getHeaders() {
+ return null;
+ }
+
+ public boolean handleMessage(SOAPMessageContext context) {
+ Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
+ SOAPMessage message = context.getMessage();
+
+ try {
+ if (outbound) {
+ System.out.println("Sending message:");
+ message.writeTo(System.out);
+ } else {
+ Integer responseCode = (Integer) context.get(MessageContext.HTTP_RESPONSE_CODE);
+ System.out.println("Received " + responseCode + "response:");
+ message.writeTo(System.out);
+ }
+ System.out.println();
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ return true;
+ }
+
+ public boolean handleFault(SOAPMessageContext context) {
+ return true;
+ }
+
+ public void close(MessageContext context) {
+ }
+}The main method to implement here is the handleMessage method. It takes in the message context, and returns a boolean to say whether message processing should continue down the handler chain. By returning false, you can block the request.
The same method is invoked for outgoing messages (that is, the request sent to the server) and incoming messages (that is, the response coming from the server). To know whether a message is incoming or outgoing, the outbound property needs to be checked. This is done using the following code:
+Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);You can see that the SOAP message is also being loaded so that it can be logged, this is the XML representation of the method invocation or response. You can also see that the HTTP response code is being read from incoming messages, and being logged.
+To use the logging handler that we implemented, we can supply it to get method for our port from the service. For example, to use it with the HelloWorldService that we saw earlier in the documentation, simply pass the list of handlers to the getHelloWorld method, like so:
HelloWorld client = helloWorldService.getHelloWorld(new LoggingHandler());A handler can be implemented by extending a sub type of javax.xml.ws.handler.Handler. Which subtype you implement depends on your use case, for more details about the types of handlers, see here. We’ll implement a simple logging handler, to do this we extend javax.xml.ws.handler.soap.SOAPHandler.
import javax.xml.ws.handler.MessageContext
+import javax.xml.ws.handler.soap.{SOAPMessageContext, SOAPHandler}
+
+class LoggingHandler extends SOAPHandler[SOAPMessageContext] {
+ def getHeaders = null
+
+ def handleMessage(context: SOAPMessageContext) = {
+ val outbound = context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]
+ val message = context.getMessage
+
+ if (outbound) {
+ println(s"Sending message:")
+ message.writeTo(System.out)
+ } else {
+ val responseCode = context.get(MessageContext.HTTP_RESPONSE_CODE)
+ println(s"Received $responseCode response:")
+ message.writeTo(System.out)
+ }
+ println()
+ true
+ }
+
+ def close(context: MessageContext) = ()
+
+ def handleFault(context: SOAPMessageContext) = {
+ println(s"Received fault:")
+ context.getMessage.writeTo(System.out)
+ println()
+ true
+ }
+}The main method to implement here is the handleMessage method. It takes in the message context, and returns a boolean to say whether message processing should continue down the handler chain. By returning false, you can block the request.
The same method is invoked for outgoing messages (that is, the request sent to the server) and incoming messages (that is, the response coming from the server). To know whether a message is incoming or outgoing, the outbound property needs to be checked. This is done using the following code:
+val outbound = context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]You can see that the SOAP message is also being loaded so that it can be logged, this is the XML representation of the method invocation or response. You can also see that the HTTP response code is being read from incoming messages, and being logged.
+To use the logging handler that we implemented, we can supply it to get method for our port from the service. For example, to use it with the HelloWorldService that we saw earlier in the documentation, simply pass the list of handlers to the helloWorld method, like so:
val client: HelloWorld = helloWorldService.helloWorld(new LoggingHandler)Play SOAP allows a Play application to make calls on a remote web service using SOAP. It provides a reactive interface to doing so, making HTTP requests asynchronously and returning promises/futures of the result.
+Play SOAP builds on the JAX WS spec, but doesn’t implement it exactly. JAX WS, while it does have support for making asynchronous calls, this support is somewhat clumsy, requiring all asynchronous methods to have an Async suffix, and requiring the passing of an AsyncHandler argument to handle the response, which makes it awkward to integrate into an asynchronous framework since `AsyncHandler’s do not compose well with other asynchronous constructs. This support could be described as a second class citizen, bolted on to the spec as an after thought.
In contrast, Play SOAP provides asynchronous invocation of SOAP services as a first class citizen. Play SOAP methods all return promises, making them easy to compose with promises from other libraries, and allowing application code to be focussed on business logic, not on wiring asynchronous callbacks together.
+Play SOAP is an sbt plugin that transforms WSDLs into SOAP client interfaces, and provides a client library that takes Play SOAP generated interfaces and dynamically implements them to make calls on remote services. The sbt plugin is called SbtWsdl, and this is the starting point to installing and using Play SOAP.
Once you have sbt WSDL generating a soap client for you, it is quite straightforward to use. How you access it depends on the service and port names in the WSDL. Consider the following service section from a WSDL:
+<wsdl:service name="HelloWorldService">
+ <wsdl:port binding="tns:HelloWorldSoapBinding" name="HelloWorld">
+ <soap:address location="http://example.com/helloWorld"/>
+ </wsdl:port>
+</wsdl:service>Assuming that the package name that the client was generated into is com.example, Play will generate a service class called com.example.HelloWorldService. This class is actually a Play plugin that allows you to configure the client, including configuring the address for each port to use.
Note that there are some situations where sbt WSDL won’t use the service name from the WSDL, these are when the name of the service conflicts with another class that it generated, such as the name of the service endpoint interface. In that case, sbt WSDL will append _Service to the end of the service name, for example com.example.HelloWorldService_Service.
Having located the service class, you can now get a port. In the above WSDL there is one port named HelloWorld, and, according to the HelloWorldSoapBinding (not shown above), this returns a service endpoint interface called HelloWorld. To access the endpoint, simply have it injected into your components or controllers, like so in Scala:
class MyComponent @Inject() (helloWorldService: HelloWorldService) {
+ val client: HelloWorld = helloWorldService.helloWorld
+}Or in Java:
+public class MyComponent {
+
+ private final HelloWorldService helloWorldService;
+
+ @Inject
+ public MyComponent(HelloWorldService helloWorldService) {
+ this.helloWorldService - helloWorldService;
+ }
+
+ public void someMethod() {
+ HelloWorld client = helloWorldService.getHelloWorld();
+ // use the client somehow
+ }
+}Once you’ve got a reference to the client, you can invoke methods on it. For example, let’s assume our client has operation called sayHello that takes a String parameter and returns a String parameter. To invoke this from a Play Scala action, you would do this:
import play.api.libs.concurrent.Execution.Implicits._
+
+def hello(name: String) = Action.async {
+ val client: HelloWorld = helloWorldService.helloWorld
+ client.sayHello(name).map { answer =>
+ Ok(answer)
+ }
+}To invoke it from a Play Java action you would do this:
+import java.util.concurrent.CompletionStage;
+
+public CompletionStage<Result> hello(String name) {
+ HelloWorld client = helloWorldService.getHelloWorld();
+ return client.sayHello(name).map(answer -> {
+ return ok(answer);
+ });
+}The generated data objects will all be Java beans, with getter/setter style properties, and using Java collections. For convenience when working with the Java collections, you may import the Scala implicit conversions for Scala collections, like so:
+import scala.collection.JavaConverters._Using this you can work with Java collections as if they were Scala collections, and pass Scala collections to setters and methods that accept Java collections.
+It’s also important to remember that many properties could be null.
A pure Scala client that uses case classes, Scala collections and Option is a possible future enhancement for the Play SOAP library.
Configuration for the client works hierarchically, each configuration item is first checked to see if it’s defined for the port, if not then for the service, and finally globally. The format for global configuration is play.soap.*. The format for configuration applying to a particular service is play.soap.services.<fqsn>, where <fqsn> is the fully qualified service name, for example, com.example.HelloWorldService. The format for configuration applying to a particular port is play.soap.services.<fqsn>.ports.<portName>, where <portName> is the name of the port, for example HelloWorld.
So for the client above, to set the debug log just for the port, you would set:
+play.soap.services.com.example.HelloWorldService.ports.HelloWorld.debugLog = trueTo set it for the whole service, you would set:
+play.soap.services.com.example.HelloWorldService.debugLog = trueAnd to set it globally, you would set:
+play.soap.debugLog = trueThe address of a port can be set using the address property. For example, to set the address of every port for the HelloWorldService:
play.soap.services.com.example.HelloWorldService.address = "http://example.com/helloWorld"The debug log will log the outbound and inbound messages, including HTTP headers, made by the client. An example of this is as follows:
+16:52:17.953 [pool-1-thread-1] INFO o.a.c.s.H.HelloWorldPort.HelloWorld - Outbound Message
+---------------------------
+ID: 1
+Address: http://example.com/helloWorld
+Encoding: UTF-8
+Http-Method: POST
+Content-Type: text/xml
+Headers: {Accept=[*/*], SOAPAction=[""]}
+Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:sayHello xmlns:ns2="http://example.com/"><name>world</name></ns2:sayHello></soap:Body></soap:Envelope>
+--------------------------------------
+16:52:18.180 [default-workqueue-1] INFO o.a.c.s.H.HelloWorldPort.HelloWorld - Inbound Message
+----------------------------
+ID: 1
+Response-Code: 200
+Encoding: UTF-8
+Content-Type: text/xml;charset=UTF-8
+Headers: {Content-Length=[204], content-type=[text/xml;charset=UTF-8], Server=[Jetty(8.1.15.v20140411)]}
+Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:sayHelloResponse xmlns:ns2="http://example.com/"><return>Hello world</return></ns2:sayHelloResponse></soap:Body></soap:Envelope>
+--------------------------------------The debug log can be turned on using the debugLog property, for example, to turn it on globally:
play.soap.debugLog = trueIn combination with the debugLog property, you may need to adjust the logging levels in your Play application. To see the debug log, you need to ensure that org.apache.cxf.services is configured to log at least INFO messages. This can be further refined by supplying the service name, port and service endpoint interface name, for example, org.apache.cxf.services.HelloWorldService.
To install sbt WSDL into your Play project, add the following lines to your project/plugins.sbt:
addSbtPlugin("com.typesafe.sbt" % "sbt-play-soap" % "1.2.0") // requires sbt 1.x, the last version with support for sbt 0.13.18 is 1.1.3The plugin is automatically activated on install, and this will also cause the necessary Play SOAP client libraries to be added to your project.
+There are two ways to supply WSDLs to the plugin. One is to configure a URL or set of URLs to point the compiler at. This can be done by using the wsdlUrls setting:
WsdlKeys.wsdlUrls in Compile += url("http://someservice.com/path?wsdl")Notice that the setting must be in the compile scope - WSDL’s can also be compiled just for the Test scope too.
The other is to place WSDLs in the conf/wsdls directory for a Play project, or in src/main/wsdl for an ordinary SBT project. You can also use both local files and urls.
sbt WSDL can generate clients to either return scala.concurrent.Future for Scala projects, or java.util.concurrent.CompletionStage for Java projects. If your project is a Play project, the future API will automatically be selected based on whether you enabled the PlayJava or PlayScala plugin. If it’s an ordinary sbt project, it will default to scala.concurrent.Future. This can be configured to use the Java promise using the futureApi setting:
WsdlKeys.futureApi := WsdlKeys.PlayJavaFutureApiBy default, all WSDLs will be generated into a package structure that matches the namespace in the WSDL. For example, if you have a WSDL that defines a targetNamespace="http://example.com/", the package that the client will be generated into will be com.example.
The package can be configured in many ways. One way is to override it globally, that is, for all WSDLs and namespaces, this can be done using the packageName setting:
WsdlKeys.packageName := Some("com.mycompany.example")Additionally, individual namespaces can be configured using the packageMappings setting:
WsdlKeys.packageMappings += ("http://example.com/" -> "com.mycompany.example")Both packageName and packageMappings can be used together, packageMappings will take precedence over packageName.
sbt WSDL is built on top of the Apache CXF wsdl2java tool. Many of the options that it supports can also be used when you’re using sbt WSDL. To see a full list of options supported by Apache CXF, run sbt wsdlHelp. These options can then be configured in your build by adding them to the wsdlArgs setting.
For example, if you the WSDL contains an operation called sayHello, and you want this to be generated using wrapper style (that is, all the arguments to the method are passed using a single object that wraps them), you could add the following configuration:
WsdlKeys.wsdlToCodeArgs += "-bareMethods=sayHello"In some cases you may want to have completely different configurations for different WSDL files - or you may want to use the same WSDL file to generate two different clients. This can be done using the wsdlTasks task. By default, this task is built by combining all the settings used above, but if you override it, then the settings above will be ignored.
Each wsdl generation task that is executed is defined by the following case class:
+case class WsdlTask(
+ url: URL,
+ futureApi: FutureApi = ScalaFutureApi,
+ packageName: Option[String] = None,
+ packageMappings: Map[String, String] = Map.empty,
+ serviceName: Option[String] = None,
+ args: Seq[String] = Nil
+)Let’s say you have one WSDL on the filesystem in src/main/wsdl/foo.wsdl, and you want it generated into the com.example.foo package using the Scala future API, and another WSDL at http://example.com/bar?wsdl that you want generated into the com.example.bar package using the Java future API, then you could configure that like this:
WsdlKeys.wsdlTasks in Compile := Seq(
+ WsdlKeys.WsdlTask((sourceDirectory.value / "wsdl" / "foo.wsdl").toURI.toURL),
+ packageName = Some("com.example.foo")
+ ),
+ WsdlKeys.WsdlTask(url("http://example.com/bar?wsdl"),
+ futureApi = WsdlKeys.PlayJavaFutureApi,
+ packageName = Some("com.example.bar")
+ )
+)Most security protocols can be implemented in Play SOAP using handlers. For general documentation on handlers, see here.
+Let’s say you wanted to make authenticated requests on a web service that expected an authentication token in the request header. To implement this, you can get the request headers from the message context, and add the authentication token there. The HTTP request headers can be loaded by reading the javax.xml.ws.handler.MessageContext.HTTP_REQUEST_HEADERS property. Of course, this should only be done when the message is an outbound message, so the implementation needs to check that as well.
import javax.xml.namespace.QName;
+import javax.xml.ws.handler.MessageContext;
+import javax.xml.ws.handler.soap.SOAPHandler;
+import javax.xml.ws.handler.soap.SOAPMessageContext;
+import java.util.*;
+
+public class AuthenticationHandler implements SOAPHandler<SOAPMessageContext> {
+
+ public Set<QName> getHeaders() {
+ return null;
+ }
+
+ public boolean handleMessage(SOAPMessageContext context) {
+ Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
+
+ if (outbound) {
+ // Get headers, create if null
+ Map<String, List<String>> headers = (Map) context.get(MessageContext.HTTP_REQUEST_HEADERS);
+ if (headers == null) {
+ headers = new HashMap<>();
+ }
+
+ // Add authentication header
+ headers.put("Authentication-Token", Arrays.asList("somesecret"));
+ context.put(MessageContext.HTTP_REQUEST_HEADERS, headers);
+ }
+ return true;
+ }
+
+ public boolean handleFault(SOAPMessageContext context) {
+ return true;
+ }
+
+ public void close(MessageContext context) {
+ }
+}Note that in the collection types used by the JAX WS API are Java collection types, so care needs to be taken to ensure that these types are used in the Scala code, rather than the Scala collection types. A common way to address this in Scala is to use aliased imports, prepending the letter J to each type, for example, import java.util.{Map ⇒ JMap}.
import javax.xml.ws.handler.MessageContext
+import javax.xml.ws.handler.soap.{SOAPMessageContext, SOAPHandler}
+
+import java.util.{Map => JMap, List => JList, HashMap => JHashMap}
+import scala.collection.JavaConverters._
+
+class AuthenticationHandler extends SOAPHandler[SOAPMessageContext] {
+ def getHeaders = null
+
+ def handleMessage(context: SOAPMessageContext) = {
+ // If this is an outbound message
+ if (context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]) {
+
+ // Get the request headers, which may be null, in which case create them
+ val headers = Option(context.get(MessageContext.HTTP_REQUEST_HEADERS)
+ .asInstanceOf[JMap[String, JList[String]]]
+ ).getOrElse(new JHashMap[String, JList[String]])
+
+ // Add the authentication token to the headers
+ headers += ("Authentication-Token" -> List("somesecret"))
+
+ // Attach the headers to the context
+ context += (MessageContext.HTTP_REQUEST_HEADERS -> headers)
+
+ }
+ true
+ }
+
+ def close(context: MessageContext) = ()
+
+ def handleFault(context: SOAPMessageContext) = true
+}JAX WS provides an abstraction called handlers to allow cross cutting concerns to be implemented across all calls. Handlers are able to inspect and modify the incoming and outgoing messages, including SOAP data objects and request/response headers. They’re also able to block requests from being made entirely.
+Use cases for handlers include logging, security, monitoring, and many other application specific concerns. For examples of how to implement security using handlers, see Security.
+A handler can be implemented by extending a sub type of javax.xml.ws.handler.Handler. Which subtype you implement depends on your use case, for more details about the types of handlers, see here. We’ll implement a simple logging handler, to do this we extend javax.xml.ws.handler.soap.SOAPHandler.
import javax.xml.namespace.QName;
+import javax.xml.soap.SOAPMessage;
+import javax.xml.ws.handler.MessageContext;
+import javax.xml.ws.handler.soap.SOAPHandler;
+import javax.xml.ws.handler.soap.SOAPMessageContext;
+import java.util.Set;
+
+public class LoggingHandler implements SOAPHandler<SOAPMessageContext> {
+ public Set<QName> getHeaders() {
+ return null;
+ }
+
+ public boolean handleMessage(SOAPMessageContext context) {
+ Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
+ SOAPMessage message = context.getMessage();
+
+ try {
+ if (outbound) {
+ System.out.println("Sending message:");
+ message.writeTo(System.out);
+ } else {
+ Integer responseCode = (Integer) context.get(MessageContext.HTTP_RESPONSE_CODE);
+ System.out.println("Received " + responseCode + "response:");
+ message.writeTo(System.out);
+ }
+ System.out.println();
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ return true;
+ }
+
+ public boolean handleFault(SOAPMessageContext context) {
+ return true;
+ }
+
+ public void close(MessageContext context) {
+ }
+}The main method to implement here is the handleMessage method. It takes in the message context, and returns a boolean to say whether message processing should continue down the handler chain. By returning false, you can block the request.
The same method is invoked for outgoing messages (that is, the request sent to the server) and incoming messages (that is, the response coming from the server). To know whether a message is incoming or outgoing, the outbound property needs to be checked. This is done using the following code:
+Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);You can see that the SOAP message is also being loaded so that it can be logged, this is the XML representation of the method invocation or response. You can also see that the HTTP response code is being read from incoming messages, and being logged.
+To use the logging handler that we implemented, we can supply it to get method for our port from the service. For example, to use it with the HelloWorldService that we saw earlier in the documentation, simply pass the list of handlers to the getHelloWorld method, like so:
HelloWorld client = helloWorldService.getHelloWorld(new LoggingHandler());A handler can be implemented by extending a sub type of javax.xml.ws.handler.Handler. Which subtype you implement depends on your use case, for more details about the types of handlers, see here. We’ll implement a simple logging handler, to do this we extend javax.xml.ws.handler.soap.SOAPHandler.
import javax.xml.ws.handler.MessageContext
+import javax.xml.ws.handler.soap.{SOAPMessageContext, SOAPHandler}
+
+class LoggingHandler extends SOAPHandler[SOAPMessageContext] {
+ def getHeaders = null
+
+ def handleMessage(context: SOAPMessageContext) = {
+ val outbound = context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]
+ val message = context.getMessage
+
+ if (outbound) {
+ println(s"Sending message:")
+ message.writeTo(System.out)
+ } else {
+ val responseCode = context.get(MessageContext.HTTP_RESPONSE_CODE)
+ println(s"Received $responseCode response:")
+ message.writeTo(System.out)
+ }
+ println()
+ true
+ }
+
+ def close(context: MessageContext) = ()
+
+ def handleFault(context: SOAPMessageContext) = {
+ println(s"Received fault:")
+ context.getMessage.writeTo(System.out)
+ println()
+ true
+ }
+}The main method to implement here is the handleMessage method. It takes in the message context, and returns a boolean to say whether message processing should continue down the handler chain. By returning false, you can block the request.
The same method is invoked for outgoing messages (that is, the request sent to the server) and incoming messages (that is, the response coming from the server). To know whether a message is incoming or outgoing, the outbound property needs to be checked. This is done using the following code:
+val outbound = context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]You can see that the SOAP message is also being loaded so that it can be logged, this is the XML representation of the method invocation or response. You can also see that the HTTP response code is being read from incoming messages, and being logged.
+To use the logging handler that we implemented, we can supply it to get method for our port from the service. For example, to use it with the HelloWorldService that we saw earlier in the documentation, simply pass the list of handlers to the helloWorld method, like so:
val client: HelloWorld = helloWorldService.helloWorld(new LoggingHandler)Once you have sbt WSDL generating a soap client for you, it is quite straightforward to use. How you access it depends on the service and port names in the WSDL. Consider the following service section from a WSDL:
+<wsdl:service name="HelloWorldService">
+ <wsdl:port binding="tns:HelloWorldSoapBinding" name="HelloWorld">
+ <soap:address location="http://example.com/helloWorld"/>
+ </wsdl:port>
+</wsdl:service>Assuming that the package name that the client was generated into is com.example, Play will generate a service class called com.example.HelloWorldService. This class is actually a Play plugin that allows you to configure the client, including configuring the address for each port to use.
Note that there are some situations where sbt WSDL won’t use the service name from the WSDL, these are when the name of the service conflicts with another class that it generated, such as the name of the service endpoint interface. In that case, sbt WSDL will append _Service to the end of the service name, for example com.example.HelloWorldService_Service.
Having located the service class, you can now get a port. In the above WSDL there is one port named HelloWorld, and, according to the HelloWorldSoapBinding (not shown above), this returns a service endpoint interface called HelloWorld. To access the endpoint, simply have it injected into your components or controllers, like so in Scala:
class MyComponent @Inject() (helloWorldService: HelloWorldService) {
+ val client: HelloWorld = helloWorldService.helloWorld
+}Or in Java:
+public class MyComponent {
+
+ private final HelloWorldService helloWorldService;
+
+ @Inject
+ public MyComponent(HelloWorldService helloWorldService) {
+ this.helloWorldService - helloWorldService;
+ }
+
+ public void someMethod() {
+ HelloWorld client = helloWorldService.getHelloWorld();
+ // use the client somehow
+ }
+}Once you’ve got a reference to the client, you can invoke methods on it. For example, let’s assume our client has operation called sayHello that takes a String parameter and returns a String parameter. To invoke this from a Play Scala action, you would do this:
import play.api.libs.concurrent.Execution.Implicits._
+
+def hello(name: String) = Action.async {
+ val client: HelloWorld = helloWorldService.helloWorld
+ client.sayHello(name).map { answer =>
+ Ok(answer)
+ }
+}To invoke it from a Play Java action you would do this:
+import java.util.concurrent.CompletionStage;
+
+public CompletionStage<Result> hello(String name) {
+ HelloWorld client = helloWorldService.getHelloWorld();
+ return client.sayHello(name).map(answer -> {
+ return ok(answer);
+ });
+}The generated data objects will all be Java beans, with getter/setter style properties, and using Java collections. For convenience when working with the Java collections, you may import the Scala implicit conversions for Scala collections, like so:
+import scala.collection.JavaConverters._Using this you can work with Java collections as if they were Scala collections, and pass Scala collections to setters and methods that accept Java collections.
+It’s also important to remember that many properties could be null.
A pure Scala client that uses case classes, Scala collections and Option is a possible future enhancement for the Play SOAP library.
Configuration for the client works hierarchically, each configuration item is first checked to see if it’s defined for the port, if not then for the service, and finally globally. The format for global configuration is play.soap.*. The format for configuration applying to a particular service is play.soap.services.<fqsn>, where <fqsn> is the fully qualified service name, for example, com.example.HelloWorldService. The format for configuration applying to a particular port is play.soap.services.<fqsn>.ports.<portName>, where <portName> is the name of the port, for example HelloWorld.
So for the client above, to set the debug log just for the port, you would set:
+play.soap.services.com.example.HelloWorldService.ports.HelloWorld.debugLog = trueTo set it for the whole service, you would set:
+play.soap.services.com.example.HelloWorldService.debugLog = trueAnd to set it globally, you would set:
+play.soap.debugLog = trueThe address of a port can be set using the address property. For example, to set the address of every port for the HelloWorldService:
play.soap.services.com.example.HelloWorldService.address = "http://example.com/helloWorld"The debug log will log the outbound and inbound messages, including HTTP headers, made by the client. An example of this is as follows:
+16:52:17.953 [pool-1-thread-1] INFO o.a.c.s.H.HelloWorldPort.HelloWorld - Outbound Message
+---------------------------
+ID: 1
+Address: http://example.com/helloWorld
+Encoding: UTF-8
+Http-Method: POST
+Content-Type: text/xml
+Headers: {Accept=[*/*], SOAPAction=[""]}
+Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:sayHello xmlns:ns2="http://example.com/"><name>world</name></ns2:sayHello></soap:Body></soap:Envelope>
+--------------------------------------
+16:52:18.180 [default-workqueue-1] INFO o.a.c.s.H.HelloWorldPort.HelloWorld - Inbound Message
+----------------------------
+ID: 1
+Response-Code: 200
+Encoding: UTF-8
+Content-Type: text/xml;charset=UTF-8
+Headers: {Content-Length=[204], content-type=[text/xml;charset=UTF-8], Server=[Jetty(8.1.15.v20140411)]}
+Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:sayHelloResponse xmlns:ns2="http://example.com/"><return>Hello world</return></ns2:sayHelloResponse></soap:Body></soap:Envelope>
+--------------------------------------The debug log can be turned on using the debugLog property, for example, to turn it on globally:
play.soap.debugLog = trueIn combination with the debugLog property, you may need to adjust the logging levels in your Play application. To see the debug log, you need to ensure that org.apache.cxf.services is configured to log at least INFO messages. This can be further refined by supplying the service name, port and service endpoint interface name, for example, org.apache.cxf.services.HelloWorldService.
Most security protocols can be implemented in Play SOAP using handlers. For general documentation on handlers, see here.
+Let’s say you wanted to make authenticated requests on a web service that expected an authentication token in the request header. To implement this, you can get the request headers from the message context, and add the authentication token there. The HTTP request headers can be loaded by reading the javax.xml.ws.handler.MessageContext.HTTP_REQUEST_HEADERS property. Of course, this should only be done when the message is an outbound message, so the implementation needs to check that as well.
import javax.xml.namespace.QName;
+import javax.xml.ws.handler.MessageContext;
+import javax.xml.ws.handler.soap.SOAPHandler;
+import javax.xml.ws.handler.soap.SOAPMessageContext;
+import java.util.*;
+
+public class AuthenticationHandler implements SOAPHandler<SOAPMessageContext> {
+
+ public Set<QName> getHeaders() {
+ return null;
+ }
+
+ public boolean handleMessage(SOAPMessageContext context) {
+ Boolean outbound = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
+
+ if (outbound) {
+ // Get headers, create if null
+ Map<String, List<String>> headers = (Map) context.get(MessageContext.HTTP_REQUEST_HEADERS);
+ if (headers == null) {
+ headers = new HashMap<>();
+ }
+
+ // Add authentication header
+ headers.put("Authentication-Token", Arrays.asList("somesecret"));
+ context.put(MessageContext.HTTP_REQUEST_HEADERS, headers);
+ }
+ return true;
+ }
+
+ public boolean handleFault(SOAPMessageContext context) {
+ return true;
+ }
+
+ public void close(MessageContext context) {
+ }
+}Note that in the collection types used by the JAX WS API are Java collection types, so care needs to be taken to ensure that these types are used in the Scala code, rather than the Scala collection types. A common way to address this in Scala is to use aliased imports, prepending the letter J to each type, for example, import java.util.{Map ⇒ JMap}.
import javax.xml.ws.handler.MessageContext
+import javax.xml.ws.handler.soap.{SOAPMessageContext, SOAPHandler}
+
+import java.util.{Map => JMap, List => JList, HashMap => JHashMap}
+import scala.collection.JavaConverters._
+
+class AuthenticationHandler extends SOAPHandler[SOAPMessageContext] {
+ def getHeaders = null
+
+ def handleMessage(context: SOAPMessageContext) = {
+ // If this is an outbound message
+ if (context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY)
+ .asInstanceOf[java.lang.Boolean]) {
+
+ // Get the request headers, which may be null, in which case create them
+ val headers = Option(context.get(MessageContext.HTTP_REQUEST_HEADERS)
+ .asInstanceOf[JMap[String, JList[String]]]
+ ).getOrElse(new JHashMap[String, JList[String]])
+
+ // Add the authentication token to the headers
+ headers += ("Authentication-Token" -> List("somesecret"))
+
+ // Attach the headers to the context
+ context += (MessageContext.HTTP_REQUEST_HEADERS -> headers)
+
+ }
+ true
+ }
+
+ def close(context: MessageContext) = ()
+
+ def handleFault(context: SOAPMessageContext) = true
+}We have upgraded CXF to the next major version, 4.0. Because CXF 4.0 is based on JakartaEE 9.1, all references to the javax.* classpath needed to be migrated to jakarta.*. For more details, see the CXF 4.0 release notes
In order to support CXF 4.0, Play SOAP 2.x now requires Java 11. CXF 3.5 is the last major release of CXF that supported Java 8.
Play SOAP allows an application to make calls on a remote web service using SOAP. It provides a reactive interface to doing so, making HTTP requests asynchronously and returning promises/futures of the result.
+Play SOAP builds on the JAX WS spec, but doesn’t implement it exactly. JAX WS does have support for making asynchronous calls, but this support is somewhat clumsy. It requires all asynchronous methods to have an Async suffix, and requires the passing of an AsyncHandler argument to handle the response. This makes it awkward to integrate into an asynchronous framework, since AsyncHandler s do not compose well with other asynchronous constructs. This support could be described as a second class citizen, bolted on to the spec as an afterthought.
In contrast, Play SOAP provides asynchronous invocation of SOAP services as a first class citizen. Play SOAP methods all return promises, making them easy to compose with promises from other libraries, and allowing application code to be focussed on business logic, not on wiring asynchronous callbacks together.
+To implement the proxy, we have to implement our own version of JaxWsClientProxy. This is the CXF JDK proxy interceptor that implements JAX WS interfaces. It’s here that asynchronous requests are handled, and the logic here is hard coded - it implements the JAX WS requirements, if a method ends in Async and returns something that implements Future then dispatch an asynchronous call. Hence why we have to implement our own to make every method asynchronous regardless of name, and to allow scala Future and Java CompletionStage return types.
+This class has a lot of logic copied from JaxWsClientProxy, the actual part that has been customised is quite simple, it just creates a promise, and sends an asynchronous callback that redeems the promise.
+When the SOAP bindings are generated, JAXB bindings are generated from the return type. Since this type is a future, we need to tell CXF to use the type it contains.
+JAX WS provides a Holder type, this is used to allow methods return multiple values, something that is not possible otherwise in Java. It does this by having the first value returned as the return value of the method, and passing additional Holder objects as arguments to the method, whose values are set when the method returns. Although this wasn’t designed with returning futures in mind, the implementation of it in Apache CXF makes it quite simple to reuse this mechanism to extract the return type, hence this is what we’re doing. This allows us to completely reuse all the reflection code from Apache CXF that generates the bindings from the interface.
+In future, we may decide to implement our own reflection code for generating bindings, but for now using the Holder mechanism is good enough. A small amount of hacking is necessary to use it, due to some odd behaviour by the CXF JAX WS support - when the bindings are created, the JAX WS support automatically inserts its own configuration, and implements it in such a way that any configuration that we’ve added for holders gets overridden. We work around this by overriding a method that eventually injects this configuration but is invoked before the binding is actually done, and after invoking the super for the method, we inject our own configuration to override the default behaviour.
+Use wsdl2java with options:
+export CLASSPATH=../../play-soap-plugin.jar
+wsdl2java -fe play '-xjc-Xplay:lang java' '-xjc-Xplay:target play' helloWorld.wsdlExample using play-soap-plugin with wsdl2java gradle plugin:
Add the following dependencies and plugin configuration to your build.gradle file. Additional arguments needed to generate java classes for our web-service WSDLs should be added to the wsdl2java block.
plugins {
+ id "no.nils.wsdl2java" version "0.12"
+}
+
+dependencies {
+ wsdl2java(
+ [group: 'com.typesafe.play', name: 'play-soap-plugin', version: '2.0.0']
+ )
+}
+
+wsdl2java {
+ wsdlsToGenerate = [
+ ['-fe', 'play', '-xjc-Xplay:lang java', '-xjc-Xplay:target play', "${projectDir}/src/main/resources/helloWorld.wsdl"]
+ ]
+}Play SOAP Plugin is a plugin module to JAXB that converts WSDLs into SOAP client interfaces for work with asynchronous requests.
+Start by adding the dependency play-soap-plugin to the project and set required WSDL options:
| Option | +Accepted values | +Required | +Interpretation | +
|---|---|---|---|
-fe |
+play |
+true |
+Specifies the frontend to enable |
+
-xjc-Xplay:lang |
+scala, java |
+true |
+Generate the future type to wrap an original type. +
|
+
-xjc-Xplay:target |
+play |
+false |
+Generates SOAP client classes for the specified framework. +
|
+
Additional documentation on WSDL2JAVA options can be found +here.
+Example using play-soap-plugin with cxf-codegen-plugin maven plugin:
Add the following dependencies and plugin configuration to your pom.xml file. Additional arguments needed to generate java classes for our web-service WSDLs should be added to the <wsdlOptions> block.
<dependencies>
+ <dependency>
+ <groupId>com.typesafe.play</groupId>
+ <artifactId>play-soap-plugin</artifactId>
+ <version>${play.soap.plugin.version}</version>
+ </dependency>
+</dependencies>
+
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-codegen-plugin</artifactId>
+ <version>${cxf.version}</version>
+ <executions>
+ <execution>
+ <id>generate-sources</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <defaultOptions>
+ <frontEnd>play</frontEnd>
+ </defaultOptions>
+ <wsdlOptions>
+ <wsdlOption>
+ <wsdl>${basedir}/src/main/resources/helloWorld.wsdl</wsdl>
+ <extraargs>
+ <extraarg>-xjc-Xplay:lang java</extraarg>
+ <extraarg>-xjc-Xplay:target play</extraarg>
+ </extraargs>
+ </wsdlOption>
+ </wsdlOptions>
+ </configuration>
+ <goals>
+ <goal>wsdl2java</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>Example using play-soap-plugin with sbt-cxf plugin
Add dependency and plugin into your project in project/plugins.sbt:
libraryDependencies ++= Seq("com.typesafe.play" % "play-soap-plugin" % "2.0.0")
+
+addSbtPlugin("io.paymenthighway.sbt" % "sbt-cxf" % "1.6")Add the plugin configuration to the build.sbt file. Additional arguments needed to generate java classes for our web-service WSDLs should be added as parameters to the cxfWSDLs setting:
enablePlugins(CxfPlugin)
+
+val CxfVersion = "3.3.3"
+
+version in CXF := CxfVersion
+
+cxfWSDLs := Seq(
+ Wsdl("HelloWorld",(Compile / resourceDirectory).value / "helloWorld.wsdl",
+ Seq("-fe", "play", "-xjc-Xplay:lang scala", "-xjc-Xplay:target play"))
+)