This demo shows using mapping files when complex types are (de)serialized between the server side and the client side.

The server side contains the demo.advanced.fpml.server.ServiceImpl class. This is a simple Web service implementation with three account operations. One for putting money into an account (deposit), second one for withdrawing the money (withdraw) and last one for asking the amount being currently stored on the account (info).

The exact interface of all these operations and used structures is written in the provided WSDL file along with the exact protocol specification. The structures being exchanged between server and client sides are described by Financial products Markup Language (FpML).

The server is started with the demo.advanced.fpml.server.Server class on an URL such as "http://jumbo:6060". The class demo.advanced.fpml.server.ServiceImpl is published there on the "/demo/advanced/AccountOperations" path. SESJ executes the Web service directly from the demo.advanced.fpml.server.ServiceImpl class and uses presented WSDL file to map client calls onto implemented services.

The client side is implemented in the demo.advanced.fpml.client.Client class. Again, it uses classes and structures previously generated from the WSDL file, same as the one used on the server side. When run, it looks up the published Web service on the "[server URL] + /demo/advanced/AccountOperations" URL and asks for the WSDL file (therefore, no WSDL file is needed to be provided to the client).

This demo provides an example of the use of mapping files when exchanging complex types. It also shows that SESJ is currently able to successfully handle FpML schemas.

Users familiar with the Web Services Description Language (WSDL) can write a description of their own service. This example uses the FpML schemas for types definition; however, users may use any other publicly available schema or even the one written on their own. The only restriction they have to obey is to thoroughly follow the WSDL and XML Schema specifications.

Provided that the interface description written into a WSDL file is completed, users may generate the server side as well as the client side classes and structures. For both sides the same WSDL2Java tool is used; however, the --output-language parameter indicates the side which the files are just being generated for. Along with this generation, the mapping files are also generated.

Based on the generated files, users can implement both sides of the communication. Since for any type specified in the WSDL file is the appropriate java source file generated, they may easily implement the Web service and use just standard java interfaces and classes.

Obviously, users are allowed to change the interface description in the WSDL file provided that they re-generate the classes as well. However, any change in the interface leads very likely to an inherent change in the service and client implementations as well.

Note 1: Please, pay attention to the fact that class instances being exchanged between the server side and the client side are serialized (e.g. on the server side) from a completely different class type than are deserialized to (e.g. on the client side) later on. For example, when a server sends an exception to a client, SESJ serializes the exception of type demo.advanced.fpml.server.generated.AnyFault and later deserializes it into an instance of type demo.advanced.fpml.client.generated.AnyFault. From the strict java namespace point of view is the fact that both class types contain same fields, rather a coincidence.

Note 2: Please, make always sure that the server mapping file is stored under the same directory and under the same name (but with the extension - .xmap) as the service class it maps; similarly, the client mapping file must be stored under the same directory and under the same name (with the extension - .xmap) as the service proxy it maps.

In this example, the mapping file for the class demo.advanced.fpml.server.ServiceImpl (demo.advanced.fpml.client.generated.AccountOperationsPortType, in case of the client side) is stored under the same directory as the class but into a file of the name demo/advanced/fpml/server/SeviceImpl.xmap (demo/advanced/fpml/client/generated/AccountOperationsPortType.xmap, respectively).

Question: Why have been chosen such a name for the server mapping file?

Answer: Since the class implementing the service is called so.

Question: Why have been chosen such a name for the client mapping file?

Answer: If you had a look to the client source file, you would find these two lines there:

...
AccountOperationsPortType service = null;
...
service = (AccountOperationsPortType) 
                serviceClient.createProxy(AccountOperationsPortType.class);
...

Client uses the demo.advanced.fpml.client.generated.AccountOperationsPortType proxy to call all services. The mapping file helps SESJ to correctly (de)serialize all data being exchanged. That's why the mapping file must have the name above.

In addition to the files described in Files and Directories, this demo contains:

You can run the demo using "run.sh" or "run.bat" scripts. The script on invocation without arguments prints out a help message.

Demo can be run in two different ways: