Our service defines exactly one operation, namely the findPrice operation. This is an operation which expects some WKNs or ISINs as input and responds with the appropriate market prices or with a fault message if an error occurres. The operation follows therefore the request/response pattern. Interface definitions are denoted with the wsdl:portType tag in WSDL 1.1:

The wsdl:input, wsdl:output and wsdl:fault elements from line 28, 29 and 30 are in turn referencing the relevant messages which are describing the data being exchanged between the Web service and its clients during such a operation. For now we are following the input message:

For every expected input parameter the wsdl:message tag contains a wsdl:part element. In this case we are expecting only one parameter and this is the request itself, mainly consisting of a list of IDs identifying the securities. The element attribut refers already to an xml element with the (qualified) name tns:SecurityPriceServiceRequest. How this element actually looks like is defined within the (external) XML schema:

The wsdl:output and wsdl:fault elements are connected in the exact same manner with elements whose types are defined within the external schema. Before I discuss the types within the schema another important section of the WSDL document remains to be shown, namely the binding:

The binding refers to the above presented interface definition, that is the wsdl:portType and describes how the findPrice operation will be actually transmitted over the wire. Of course we are using SOAP messages on top of the HTTP protocol here. Furthermore we are specifying the document/literal style which means that the payload contains only the actual data to be passed to the service. Today the document/literal style is the recommended practise because the data going over the wire can be validated against the employed XML schema without much ado. This is convenient when the client and the service are managed by different platforms, e.g. by Java and .NET.

You may review the complete SecurityPriceService.wsdl.

[Top]

The namespace of all XML elements and attributs in connection with the SecurityPriceService has been specified with http://de.christofreichardt/SecurityPriceService. Our schema document targets this namespace in line 4. Additionally, we declare a prefix for this namespace in line 5 to distinguish our to be defined elements from other elements (e.g. elements out of the XML schema namespace). Now we can continue with our exploration of the message connected with the wsdl:input of the findPrice operation:

We see the declaration of a root element named SecurityPriceServiceRequest of type tns:SecurityPriceServiceRequest in line 8. Sometimes (complex) types are denoted with the postfix 'Type' (that would be SecurityPriceServiceRequestType) to differentiate between types and elements, but in our case this would lead to Java classes with the same postfix and this would be rather unusual. Our SecurityPriceServiceRequest element consists of an UserId element, a TransactionId element, a sequence of maximal 25 WKN or ISIN elements and an provider attribut with the default value OnVista. The decision to use an attribute to store the provider value results from the XML Schema specification concerning the occurence constraints, see 2.2.1 Occurrence Constraints within the XML schema recommendation of the W3C. It is specified that if an attribut (with a default value) that does not appear at all within an instance document the schema processor must provide the attribut together with its default value, whereas the handling of (missing) elements with default values is slightly different. We will look how wsconsume deals with this requirement later on.

How could such a SecurityPriceServiceRequest actually look like? See the subsequent example:

The above XML fragment will be embedded within a SOAP envelope (and body) at runtime. Next we look at how the SecurityPriceServiceResponse is defined. This will be a bit more complicated, since there is more than one type of security to consider. This demo takes shares, index certificates and options into account. Therefore we define a AbstractSecurityPrice type as starting point. This type consists of the actual security, that is its name, WKN and ISIN as well as its current rate (bid and ask). The OptionPrice type for example extends this AbstractSecurityPrice by adding the strike price, an expiration date and the way of the exercise (american or european).

The definition of the SecurityPriceServiceResponse type starts at line 24. Such a response consists of a timestamp and the list of the requested market prices. Then comes the definition of the Security type. This is simply a sequence of the security's name, its WKN and ISIN. Any security price consists of the Security itself and its market rate (bid and ask). We take the OptionPrice as an example for a specialised security price. Such an OptionPrice simply adds the strike price, an expiration date and the way of the exercise of the option.

See below how an actual SecurityPriceServiceResponse might look like:

You may review the complete SecurityPriceServiceSchema.xsd.

[Top]

The wsdl:portType definition translates directly into a Java (endpoint) interface. Apache CXF does that for us during the generate-sources phase of the build lifecycle:

This boils down to the interface signature as shown below:

Both SecurityPriceServiceRequest and SecurityPriceServiceResponse are JAXB value classes which have been generated for us too. To get an idea I present the SecurityPriceServiceRequest value class below:

The JAX-WS runtime uses these value classes to generate the appropriate XML at execution time. See e.g. the definition of the provider property in the lines 19,20 and 45-50. Thus the code generation has taken the default value for the provider into account.

Of course the web service must provide an implementation of the SecurityPriceServicePortType (endpoint) interface:

Since I didn't have a direct connection to the stock exchange, I'm checking the relevant online resources (like OnVista) to get the market rates. When evaluating these resources I'm using the Jsoup html parser to retrieve the desired pieces of information. This presupposes a particular and well known page layout. If OnVista changes this layout the price extraction must be reworked. The implementation should not be tight to a particular provider or to any certain price determination. Thus the Strategy pattern is applied to abstract from the actual price extraction. An offline provider for testing purposes has been made available too.

[Top]

It has to be mentioned that the provided service uses a web descriptor. The descriptor mainly maps endpoint implementations on url patterns. The application server then turns it into an address at which the endpoint can be accessed. That is this overrides the wsdl:port section of the WSDL file (the server would do this anyway).

[Top]