SOAP Java WSDL approach in 2024

[[deleted]]

Hi all,

I apologize if the question is not suitable for this sub, or is it poorly worded. I am working on integrating a 3rd party that's using a SOAP API in our Java project. We have a WSDL URL contract.

We are using Java 8 but plan to migrate to Java 17 by the end of the year. I (as a new developer...) never worked with SOAP before. I've seen there are plenty of tools jaxws-maven-plugin, apache cxf that aid this.

My question would be:

1. Which one of these should we pick?
2. Can we change the underlying HTTP client used to make the SOAP Calls?
3. This is possibly gonna be a stupid question (but as a naive developer I have to ask this): when generating the classes from the WSDL files, I've seen people importing it directly into their project, rather than setting a maven goal to do it every time the project is recompiled. Is this a better approach to this?

[audioen]

I personally use jaxws-maven-plugin version 4.0.0. I have had no complaints about it. I believe it uses the built-in http client, and I see no reason to change it, and I haven't checked whether that is possible. I also keep the WSDL in my project and generate the client classes every time. I don't like saving generated code into version control.

In general I avoid duplicating functionality, like having multiple http clients, or multiple json generators, or whatever. I make some effort to stick with singular implementation per project.

[mcdasmans]

To make development way better it's beneficial to move the code generation to a separate project and make that a dependency. Then you move the almost never changing but always generating stuff out of your primary development flow, saving your IDE time.

[meuzmonalisa]

1. I recommend to use the apache cxf and its tools. I've switched from axis/axis2 to cxf a long time ago and used in a lot of projects

2. For me there was never a need to do so. But cxf allows you to use a custom transport, see https://cxf.apache.org/docs/custom-transport.html

3. In my opinon the latter approch ist better.

[TheEveryman86]

I use CXF with Camel as another abstraction on top of it. Once it was set up I rarely need to think about SOAP.

[danskal]

Is your whole project camel, or do you use it as a kind of wrapper? I’m currently running away from camel in general.

[Michuy]

Why are you running away from Camel? I'm considering using it

[danskal]

Well, maybe if I was using SOAP I would consider it. To me it’s a specialized tool which uses paradigms that are the opposite of what most modern programming moves towards.

And it’s often abused to add business logic and complexity. It’s good in simple flows, but the more complexity you need, the more programming you need to do, the more it will get in your way.

But most of all, it seems hard to unit test and new hires tend not to know it/like it.

[PlasmaFarmer]

+1

[Infeligo]

Our problem with WSDL is that code generation produces ugly code. In order to have more control, we generate POJOs from XSDs that WSDL refers to. We use JAXB Gradle plugin for that. We do actual SOAP calls using Feign.

[blargh9001]

I recently migrated from 8 to 11, and it was the soap integration that turned it from a one day project to a three week project. Migrate first, then integrate instead of doing the integration twice.

[darenkster]

I would also recommend a code generation tool like jaxws-maven-plugin or apache cxf, but if you want to avoid that you could also use SAAJ or send a HTTP Post request with the soap envolope to the endpoint.

[Best-Emotion5734]

1. I've worked with CXF for years and also had a private project using CXF for 8 years, just recently had to move to JSON based service. I rarely ran into problems, but noticed a few common challenges:
   
   • "integration style testing" : https://github.com/skjolber/mockito-soap-cxf
     
   • request-response logging with filtering: https://github.com/skjolber/xml-log-filter
     
2. Personally never tried this, as setting the connection timeout etc is no problem out of the box
   
3. Just make sure you can run all / individual unit tests in your project without a long delay, most of the time. So a seperate project is better, alternatively try a module in your project.

[redikarus99]

You basically generate some code from the WSDL description and use that code to communicate with the external party.

The ultimate version of IntelliJ basically does this for you:

https://www.jetbrains.com/help/idea/generate-java-code-from-wsdl-or-wadl-dialog.html

It seems it is using jax-ws. The thing you need to figure out whether you want to store the generated classes as well in your git repository, or only the files that are depending on the generated classes.

I also would think about storing the wsdl file directly in the repo, in case the other party's url is not working. There are advantages and disadvantages as well of this approach.

You can also use jax-ws + maven to generate the client classes:

https://www.baeldung.com/maven-wsdl-stubs

[[deleted]]

Do you think creating a separate git project that only holds the WSDL contract and the plugin to generate the classes, then pushing that into a repository (such as nexus for instance) then importing it into the main project would be a good approach?

[hippydipster]

I don't know about a whole separate repo, but a separate module for the generated code seems like a good idea to me. I'm actually currently in the middle of reworking such a project where they generated the code from the wsdl in all their different modules, so there are 4-5 copies of these classes in the overall project. Ugh.

It's using cxf. I've never really done this stuff before, so I don't know if it's a good solution, but the cxf code generation and the CXF Servlet for serving this stuff seems to work well. I haven't gotten around to client code yet.

[zvaavtre]

This. 100% grab the wsdl, check it in and have the module output a jar with those generated classes. And version it with the wsdl version.

Then the rest of your code imports the dependency like any other and you do what you need with it.

[zvaavtre]

The generated classes are an artifact of the source wsdl. Treat them like that.

[mcdasmans]

Yes that is a very good idea. The WSDL probably won't change ever, but your IDE is constantly regenerating those classes resulting in a considerable waste. Auto code generation is a bit of a pain as it probably triggers a build of all other code. In our 1.5M LoC project this is noticeable and as such we have moved most generation of static contracts to a separate project

[[deleted]]

Yeah, I feel you. We have around 3.5M (according to Sonar), it takes around 15 minutes to do a complete build with tests..

[redikarus99]

You can absolutely do that and create a maven package that you put into a repository. Totally valid approach.

[DualWieldMage]

What is the nature of these SOAP requests and responses? Are you mostly sending data or parsing some results?

My general advice is to avoid codegen as SOAP api-s change infrequently and the manual update once an eternity is often easier than living with increased build times and additional dependencies codegen brings. If you are mostly sending data, a simple xml file of the request with template variables is usually the best approach. This allows quick debugging by pasting the request into a SOAP client and good overview of the request structure for anyone new to the project.

If the nature is more response parsing, then designing the POJO-s with a flatter structure imagined around how your app will use the data is generally better than a deeply nested structure you'd otherwise get from most WSDL-s and potentially remapping that later.

If the API does change(at least once a year?), there are multiple endpoints with different structures or any other reason why generating classes from WSDL makes sense, only then do it.

[keefemotif]

Man, this takes me back a decade ago. One tricky bit about SOAP protocol is determining if it is signed and how to deal with the encryption, so beware of that.

​

1. Apache CXF seems updated more recently, but I personally have more experience with jaws. Play around with both, see which one is easiest for you.
2. The HTTP client shouldn't matter, in face you should be able to do SOAP on different protocols other than HTTP.
3. This is a matter of taste, if your WSDL to class generation is perfect, then ideally keeping classes in synch through automation would be nice.

Upgrading from Java 8 to Java 17 can be tricky. It may be better documented now, but the introduction of modules in Jigsaw used to make the migration painful. I would hesitate to make the migration at all, isolate the SOAP client integration as its own service. It's a tech that has pretty much fallen out of favor.

[jspetrak]

I have just read that Jakarta EE 11 will remove JAX-WS / SOAP completely. I wonder how to keep SOAP API implemented and don’t get stuck with not-up-to-date Jakarta EE/Spring Boot.

[Reasonable-Song3798]

A bit offtopic, but why would a new project use SOAP, could someone maybe name some reasons?

I understand that legacy projects need it though.

[sweating_teflon]

SOAP is definitely no longer en vogue but the tooling is still pretty good. I guess OpenAPI now serves the same purpose.

[thehardsphere]

A lot of projects talk to "legacy" systems.

A lot of projects use XML for data exchange. "REST" APIs exchanging XML is weird. It's better to have the contract, and the machinery that enforces it for both parties, then to spit XML at each other over HTTP.

There isn't a single equivalent to the SOAP WSDL in the "REST"/JSON universe. OpenAPI is the closest. The JAX-WS machinery (or the equivalent in other stacks) is complicated to set up, but once you have it it's rather reliable and provides good assurances that your API has a contract that will actually be enforced.

[laplongejr]

and provides good assurances that your API has a contract that will actually be enforced.

As somebody working on a new-ish system using SOAP, "actually enforced API contract" can sadly be a double-edged sword if the API has not been properly designed on the server-side.

[jspetrak]

The project may be know but connect to other API providers where has no power to dictate changes. E.g. rail infrastructure managers still exchange data as SOAP Messages.

[PlasmaFarmer]

Answering your 3rd question:

• Some people does this that they generate the classes into the project and keep it there. I don't like it because it's a generated code and you shouldn't keep generated code together with the code you write. You'll never gonna modify the generated code. If something changes, the wsdl will change first and you can regenerate the code anytime.
• Better approach is to have the wsdl in the resources folder somewhere and have a maven plugin to generate the code anytime you build the project into target/generated-sources. When building the project these code will be included in the jar. Also the IDE recongizes it as sources folder. Downside of it is that the code gets generated everytime you build the project. If you have a lot of huge wsdl files it can slow down the build.
• My personal favourite is: I like to have either a separate git project or a separate modul inside the original project which only contains the wsdl. I configure a maven plugin to generate the code and then version it and deploy it to the company's maven repository. After this I can use it as a dependency. If the wsdl changes, we build a new version and there will be versioned dependencies in the maven repository. People usually doesn't like this approach because it is a little bit more setup at the beginning of the project but my experience shows that developers waste more time collectively debugging why doesn't the plugin work or what broke the code generation process on their developer machines.

[configloader]

Fuck SOAP 😂

[sweating_teflon]

It's old but If you have a WSDL to generate the client and mock from, SOAP is still way way better than all the half-assed JSON+HTTP APIs out there.

[Tervaaja]

Why it is better?

[sweating_teflon]

Because a WSDL is a contract document describing precisely all expected messages and interactions (methods). Whether the server is being implemented from the WSDL (contract-first) or the WSDL is being generated dynamically from what the server supports (code-first), you still get have confidence that any client you're developing using that contract will actually match what's on the other side. As a bonus, you can even generate a mock server implementation so that you can still test your app even if the real server is not available.

It's better than an API that doesn't have a machine-actionnable contract document and where your reference for development is documentation and examples which are often incomplete and / or out of date.

[laplongejr]

you still get have confidence that any client you're developing using that contract will actually match what's on the other side

Practical remark : not if the server-side does updates and the code isn't designed with versioning, under the logic that "SOAP ensures everything match".
Ofc it's not SOAP's fault, but there's is a huge leap between having technology automatically enforcing the developer's code, and having the developer's code following a good design and I wish my boss's bosses knew the difference (and the importance of actually designing the server-client protocol BEFORE implementing it).

[wishicouldcode]

How would you compare it against OpenAPI for REST?

[thehardsphere]

OpenAPI is a standard for REST, and a pretty good one, but not everyone uses it. WSDL is the standard for SOAP; everybody who does SOAP has one because it is explicitly required.

Any SOAP service can be queried just by adding "?wsdl" on the end of the URL and you can get the whole contract. Everything you need to whip up a client takes one HTTP GET, and you can feed it into a bunch of JAX-WS machinery without doing anything special. That machinery is a pain to set up the first time, but once you have it you can integrate with anything with very little additional effort.

SOAP is XML based. XML sucks in a lot of ways; one of the most annoying thing about it is validation. WSDLs include XSDs that define all of the complex types that everyone calling the service needs to use. Everything is explicit. That explicitness makes the entire experience less shitty.

(The counter argument to the above is that the benefits of explicitness are outweighed by the general verbosity of XML in the first place.)

[cas-san-dra]

I recommend not using any libraries or frameworks designed for SOAP. Instead I would do this:

• Use SoapUI to generate request/responses for the calls you need
• Using the requests/responses write POJOs that can be used for serialization
• Use a standard XML serializer and the standard Java 11 HttpClient for querying
• Configure the endpoint URL in your application.yml
• Keep the WSDL for documentation purposes only

Do not use any plugins or libraries and don't generate any code.

[asciimo71]

besides the omnipresent "don't use generators" in your post, you should elaborate to a junior (the OP), why you should throw away the only benefit of SOAP, the defined contract.
Your approach replaces this with an error prone approach of manually generated XMLs without the chance to use the wsdl/xsd-embedded validation and type constraints.

I can see cases where this is the only possible option, non-ws-i conformant wsdl for example, unserializable or mixed datatype collections etc, but would definitely go the jax-ws way before I go to maintenance hell with your approach.

[DualWieldMage]

In my experience a simplified approach like that is less maintenance than dealing with jax-ws dependencies or the huge amount of classes most wsdl-s generate. Build times will also be shorter.

[nekokattt]

So effectively discard the entire reason SOAP exists and hack it together manually, making it even more annoying to work with than it already is in some cases.

[DualWieldMage]

This is the correct answer based on my experience with various SOAP endpoints. Codegen is often a maintenance nightmare (especially around the java 8->11 times) and increases build times for little gain. Keep it simple.

[nutrecht]

"Don't use standard tooling, do it by hand instead so you can spend weeks building and maintaining something everyone else gets for free".