How to change a top down web service without overwriting existing code

Question

I am fairly new to eclipse and Java development. Please bear with me if this sounds like a trivial question.

I am trying to modify an existing web service. This was originally developed using top down approach (i.e. WSDL first and then generate Java bean skeleton).

I have made changes to the WSDL and now need to incorporate these in the web service. When I right click on the WSDL to generate Java bean skeleton, existing code is getting overwritten. When I set the preference to not overwrite existing code, it prompts me to overlay each file and I am not sure which ones I should overlay and which ones I should not.

Is there a way I can make changes to the existing code with out overwriting it?

Is this how we should modify existing web services?

Answer 1

Please bear with me if this sounds like a trivial question.

This is not a trivial question. What's trivial are all the "Hello World" web service examples and tutorials you'll find on the web, which never offer any kind of advice on how to manage the "Real World" web services later on.

Is this how we should modify existing web services?

Well... not really. I'll try to provide a general explanation and maybe a possible solution for your particular case, so you please bear with me (:D) as this will be a long post.

Contract first vs. contract last

There are two approaches when building web services: contract first and contract last.

Contract first means creating a WSDL and then generating the Java code that implements the contract stipulated by the WSDL. Contract last means creating your Java code and later generate the WSDL based on the code.

Both have advantages and disadvantages but what is important in both is the contract.

The contract

Your WSDL describes the contract. Once you deploy your web service, the contract must remain frozen. The contract is the basis for the communication between the web service and its clients (don't even get me started on web services interoperability).

The web service and all the clients implement this contract in their code.

I have made changes to the WSDL...

That's not always a good idea.

When a web service contract changes, users of the contract may get broken. When you change the WSDL you regenerate the web service code to support the new contract. But what about the clients?

If the new modifications break the contract, you will have to instruct all clients to obtain the new contract and change their code to accommodate for the changes. How many clients do you have for this web service of yours? What changes did you make to the WSDL?

Contract breaking changes vs non breaking changes

You can have some changes done to the contract without breaking the clients. For example, you can have a new operation added. The clients don't know about it in their code and what they don't know can't hurt them. You can also add some optional parameters to existing messages; since they are optional it means they can be omitted when communicating and the clients code don't know about it and what they don't know can't hurt them. These are the non-breaking changes.

Breaking changes... well... break the contract. These include for example changing operation names, changing message parameter types or names, adding mandatory parameters etc. The client code is now broken. Clients just found out about it (existing code no longer works) and they get hurt. Your web service is no longer usable at this point.

What type of changes did you perform on your WSDL?

The code

In contract-last approach, the WSDL is generated based on the web service code. This has the disadvantage that it ties the code implementation to the WSDL. If you make changes to the code you might trigger changes in the WSDL, thus in the contract you agreed with your clients.

But if in the contract-first approach you make changes to the WSDL and then regenerate the web service skeleton code, you again changed the contract. You didn't do any better... and now you have yet another problem. What happens to the web service existing skeleton code you now generate once again?

Generating code from the WSDL

When you generate code from the WSDL you get your web service skeleton. This is boilerplate code that just gets your web service messages on the wire in the SOAP format specified by the contract.

You normally generate this code and include it in your project to be used by "the important" web service code, the code that actually provides "the service". How you use this code is important. You have to take into account the case of generating the code again at a later time without overwriting your existing code.

Normally, a code generation tool can split your skeleton code into an interface and an implementation of that interface. You must discard the generated implementation and provide your own implementation of the interface. You provide your implementation in a different place so that it does not get overwritten when generating the skeleton code. If the interface changes of course you will have compilation problems in your implementation because it won't match the new contract, but at least you still have the code to modify it :D.

Unfortunately this is not what happens in most projects. People modify the generated implementation directly and when they generate the skeleton again, they loose all their added code. Most generation tools insert a warning in the code "This is computer generated code. All changes will be lost if this code is again generated..." or something similar, but do people listen?

Possible solution in your case

OK, enough rambling...

Is there a way I can make changes to the existing code without overwriting it?

Do it manually (assuming it is a non breaking change)!

It takes some time but it's not hard to do. You take the original WSDL and generate the code for it in a separate folder: Folder1. Take the new WSDL and generate the code for it in a yet again separate folder: Folder2. Make a diff of the two directories to see what files changed. Look inside the files.

You now know how your code will have to be changed in the existing project code. Now you must find out if the originally generated code was modified in some way after it was generated. Compare project folder to Folder1.

Then do the modifications by hand.

If instead this is a breakable change, you might want to see if it's possible to migrate the clients. If not, you might have to expose your web service on two endpoints, each with its own WSDL contract to the same web service and migrate the clients with time, if that's even possible.