Unravel โบ Java concepts โบ APIs and web
SOAP and JAX-WS web services
SOAP is an older, XML-based way for systems to call each other, still common in banking, insurance and government.
Learn these first
At a glance
Formal business letters with a strict template and an envelope format.
- 1A WSDL defines operations, messages (XML Schema types) and the endpointwsimport or a Maven plugin generates a client proxy and Java classes for the types.
- 2JAX-WS server: annotate a class with @WebService and methods with @WebMethod; the runtime publishes the WSDLSpring Web Services is contract-first: @Endpoint classes with @PayloadRoot map XML elements to methods.
- 3Clients use the generated service class (new OrderService().getOrderPort()) or WebServiceTemplate.marshalSendAndReceive
- 4Errors come back as SOAP faults, which the client sees as exceptions (SOAPFaultException)
- Set connect and read timeouts on the binding provider (BindingProvider.REQUEST_CONTEXT)
- WS-Security (signatures, username tokens) adds heavy configuration
- A call serializes the request object to XML with JAXB, wraps it in a SOAP Envelope with Header and Body, posts it over HTTP with a SOAPAction header, and unmarshals the response body the same way
@Endpointpublic class CountryEndpoint { private static final String NAMESPACE = "http://acme.com/countries"; @PayloadRoot(namespace = NAMESPACE, localPart = "getCountryRequest") @ResponsePayload public GetCountryResponse getCountry(@RequestPayload GetCountryRequest request) { GetCountryResponse response = new GetCountryResponse(); response.setCountry(repository.find(request.getName())); return response; }}- line 5 uses PayloadRoot, the core of SOAP and JAX-WS web services
- line 6 uses ResponsePayload, the core of SOAP and JAX-WS web services
- line 7 uses RequestPayload, the core of SOAP and JAX-WS web services
Read the full explanation (about 1 min)
SOAP is an older, XML-based way for systems to call each other, still common in banking, insurance and government. A WSDL file describes the operations, and tools generate Java classes to call or implement them.
A mental model
Formal business letters with a strict template and an envelope format. Slow and verbose, but both parties know exactly what each field means and the contract is written down.
How it works
A WSDL defines operations, messages (XML Schema types) and the endpoint. wsimport or a Maven plugin generates a client proxy and Java classes for the types.
JAX-WS server: annotate a class with @WebService and methods with @WebMethod; the runtime publishes the WSDL. Spring Web Services is contract-first: @Endpoint classes with @PayloadRoot map XML elements to methods.
Clients use the generated service class (new OrderService().getOrderPort()) or WebServiceTemplate.marshalSendAndReceive.
Errors come back as SOAP faults, which the client sees as exceptions (SOAPFaultException).
Going deeper
Set connect and read timeouts on the binding provider (BindingProvider.REQUEST_CONTEXT). SOAP calls to slow partner systems are a common cause of hung threads.
WS-Security (signatures, username tokens) adds heavy configuration. Prefer mutual TLS at the transport layer where the partner allows.
Use contract-first: keep the WSDL and schemas as the source of truth and generate code, so changes are explicit and versioned.
Under the hood
A call serializes the request object to XML with JAXB, wraps it in a SOAP Envelope with Header and Body, posts it over HTTP with a SOAPAction header, and unmarshals the response body the same way. Handlers form a chain around that for logging and security headers.
Common mistakes
- No timeouts on SOAP clients.
- Generating code from a WSDL fetched at runtime.
- Hand-editing generated classes.
- XXE-vulnerable XML parsing.
How Unravel recognises it
When you paste code, Unravel looks for these signs of soap and jax-ws web services. Spotting them yourself is a good habit when you read unfamiliar code:
- Annotations:
@WebService@WebMethod@SOAPBinding@WebParam@WebResult@WebServiceClient@WebServiceRef@PayloadRoot@EnableWs@RequestPayload@ResponsePayload - Types:
WebServiceTemplateSOAPMessageSOAPFaultSoapFaultExceptionWsdl11DefinitionDefaultWsdl11DefinitionJaxb2MarshallerSOAPFaultExceptionBindingProviderSOAPHandler
Part of a learning path
Related concepts
Frequently asked questions
What is SOAP and JAX-WS web services?
SOAP is an older, XML-based way for systems to call each other, still common in banking, insurance and government. A WSDL file describes the operations, and tools generate Java classes to call or implement them.
What are the most common mistakes with SOAP and JAX-WS web services?
No timeouts on SOAP clients. Generating code from a WSDL fetched at runtime. Hand-editing generated classes. XXE-vulnerable XML parsing.
How can I see SOAP and JAX-WS web services in real code?
Paste your own Java into Unravel and it will point out where soap and jax-ws web services appears, explain how it works at the detail level you choose, and draw the flow of the code around it.