Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Building and Consuming Services

SOAP with Java (JAX-WS) and .NET (WCF)

Learn how the two big SOAP ecosystems work - code-first and contract-first in Java (Jakarta XML Web Services, CXF) and .NET (WCF, CoreWCF) - with read-only real code and runnable Node.js stand-ins.

SOAP's home ground is the enterprise, and enterprises mostly run Java and .NET. Both platforms have mature toolkits that make SOAP feel like calling a local method: you write a class, add a few attributes, and the framework publishes a WSDL, validates incoming XML and converts it to your objects. This lesson explains how that works so you can read and write such services with confidence, whichever language your project uses.

Our editor cannot run the real Java or .NET SOAP stacks: they need Maven or NuGet packages, a web server and network access. The framework code below is read-only. The runnable examples are labelled stand-ins written in Node.js that reproduce the idea (code-first publishing and contract-first generation) without any framework.

Two ways to start: code-first and contract-first

  • Code-first: you write the service class and the toolkit generates the WSDL. Quick to start, but the contract is a by-product of your code, so renaming a method silently changes the public interface.
  • Contract-first: you write (or receive) the WSDL and XSD, then generate code from them. Slower to start, but the contract is the source of truth and survives refactoring. This is the usual choice when a partner dictates the interface.
flowchart LR
  subgraph Code-first
    A["Java/C# class + annotations"] --> B["WSDL generated"]
  end
  subgraph Contract-first
    C["WSDL + XSD"] --> D["Stubs generated"]
    D --> E["You implement the interface"]
  end

Both approaches meet in the middle: a class that implements the contract, and a WSDL that describes it.

Java: Jakarta XML Web Services (JAX-WS)

JAX-WS was part of the JDK until Java 8 and was removed in Java 11. It lives on as Jakarta XML Web Services with the reference implementation Metro, and as part of Apache CXF, which is also what Spring Boot projects typically use. The package names changed from javax.jws to jakarta.jws.

A code-first service (read-only):

Java
import jakarta.jws.WebMethod;
import jakarta.jws.WebParam;
import jakarta.jws.WebService;

@WebService(serviceName = "CalcService", targetNamespace = "urn:calc")
public class Calc {

    @WebMethod
    public int add(@WebParam(name = "a") int a, @WebParam(name = "b") int b) {
        return a + b;
    }

    @WebMethod
    public double divide(@WebParam(name = "a") int a, @WebParam(name = "b") int b)
            throws DivisionException {
        if (b == 0) throw new DivisionException("Division by zero");
        return (double) a / b;
    }
}

The annotations drive everything: @WebService marks the class as an endpoint, @WebMethod exposes a method, @WebParam names XML elements. A checked exception such as DivisionException annotated with @WebFault becomes a declared fault in the WSDL. In a plain Java SE program you would publish it with Endpoint.publish("http://localhost:8080/calc", new Calc()); in Spring Boot with CXF you register it as a bean.

Contract-first uses a tool: wsimport (Metro) or wsdl2java (CXF) reads the WSDL and writes a service interface, data classes from the XSD, and a client factory class. You then implement the generated interface.

.NET: WCF and CoreWCF

Windows Communication Foundation (WCF) is the classic .NET SOAP stack, built on [ServiceContract] interfaces:

C#
[ServiceContract(Namespace = "urn:calc")]
public interface ICalc
{
    [OperationContract]
    int Add(int a, int b);

    [OperationContract]
    [FaultContract(typeof(DivisionFault))]
    double Divide(int a, int b);
}

public class Calc : ICalc
{
    public int Add(int a, int b) => a + b;
    public double Divide(int a, int b) =>
        b == 0 ? throw new FaultException<DivisionFault>(new DivisionFault("Division by zero"))
               : (double)a / b;
}

WCF server hosting exists only on .NET Framework. For modern .NET, the server side is the community project CoreWCF, and the client side uses the System.ServiceModel packages. To consume a WSDL, run dotnet-svcutil (or add a "Connected Service" in Visual Studio) and it generates a client proxy class:

C#
var client = new CalcClient(CalcClient.EndpointConfiguration.BasicHttpBinding_ICalc);
int sum = await client.AddAsync(2, 40);

WCF separates contract (the interface), binding (protocol, encoding, security, such as BasicHttpBinding for SOAP 1.1 or WSHttpBinding for WS-* features) and address, which mirrors the WSDL's portType, binding and port.

For other languages, Python has zeep (client) and spyne (server), PHP has the built-in SoapClient and SoapServer, and Node.js has the soap package.

Stand-in 1: what wsdl2java does

A code generator is a program that reads operation metadata and prints source code. This stand-in prints a Java interface for the same operations as our WSDL lesson. It is not the real tool, but it shows the transformation at work.

Node.js Stand-in: generating a service interface

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in 2: code-first publishing

In code-first mode the framework inspects your class and derives the contract. Here JavaScript reflection plays that role: we list a service's methods and build a WSDL-like summary from a table of declared parameter names, which JavaScript cannot read at run time the way Java annotations allow.

Node.js Stand-in: deriving a contract from a class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that only methods in the exposed table become operations. In Java and C# the same safety comes from the explicit opt-in annotation (@WebMethod, [OperationContract]): nothing is exposed unless you say so.

Practical advice

  • Pin the namespace explicitly (targetNamespace, Namespace). Defaults are derived from package names, which makes the contract change when you move a class.
  • Prefer document/literal wrapped style, the default in modern toolkits and the one the WS-I Basic Profile endorses; avoid rpc/encoded.
  • Keep service interfaces coarse-grained. One call that returns an order with its lines beats ten calls that fetch pieces.
  • Declare faults in the contract instead of throwing generic exceptions.
  • Do not use your database entities as message types: map to dedicated data transfer objects so schema changes stay deliberate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main risk of code-first SOAP development?

    When the WSDL is generated from code, renaming a method or moving a class can change what partners see unless namespaces and names are pinned.
  2. 2. What replaced the javax.jws package after JAX-WS left the JDK?

    JAX-WS moved to Jakarta EE and its packages are now under jakarta.*; Metro and Apache CXF implement it.
  3. 3. Which .NET concept corresponds to a WSDL portType?

    The service contract lists the operations, just as portType does in WSDL.
  4. 4. Which tool generates a .NET client proxy from a WSDL?

    dotnet-svcutil (or Visual Studio's Connected Services) reads the WSDL and emits a typed client.

Summary

  • Java uses Jakarta XML Web Services (Metro, Apache CXF); .NET uses WCF (clients) and CoreWCF (servers on modern .NET).
  • Code-first generates the WSDL from annotated classes; contract-first generates code from the WSDL.
  • Annotations or attributes opt operations in; pin namespaces and declare faults.
  • Prefer document/literal wrapped style and coarse-grained operations with dedicated message types.

Next: Testing SOAP Services with node:test