This specification defines the following entities:

Figure 160.1 Jakarta™ XML Web Services Overview Diagram

The Jakarta™ XML Web Services specification defines the programming model and APIs for web service endpoints and handlers, but does not prescribe how these components should be discovered and managed in a dynamic environment. In a traditional Jakarta EE application server, endpoints are typically deployed as part of a WAR file with static configuration. This static deployment model conflicts with OSGi's dynamic nature where bundles can be installed, started, stopped, and uninstalled at any time.

While in a traditional web application the configuration is rather static and known in advance, in OSGi items can come and go anytime and code should be aware of this dynamism. Also, registration of listeners must happen before an endpoint is published, and only weak typing makes it hard to handle this correctly manually. As a result, the publishing of Web Services in the current state of the specification goes against the loose coupling concept usually provided by OSGi as it requires knowledge about the stakeholders involved.

It is therefore the responsibility of the Web Services Whiteboard to handle these cases in a transparent manner so the user can focus on the actual work and use common dependency injection techniques like Declarative Services to inject dependencies. The whiteboard pattern allows endpoint implementors and handlers to be registered as OSGi services, and the whiteboard implementation automatically manages their lifecycle, publishing and unpublishing endpoints as services come and go.

Endpoint Implementors can be registered with the Jakarta™ XML Web Services Whiteboard by registering them as Whiteboard services. This means that the endpoint POJO implementations are registered in the Service Registry. As Web Service Endpoints are POJOs, they may be registered using any valid service interface, including Object, and use any Jakarta™ XML Web Services annotations on the endpoint object, just as they would outside of OSGi. The Jakarta™ XML Web Services specification defines annotations such as @WebService, @WebMethod, and @WebParam to declare web service endpoints and their operations (see [1] Jakarta™ XML Web Services Specification for details on these annotations).

To be picked up as endpoints, the POJO must be registered with the osgi.jakarta.xml.ws.endpoint.implementor service property with a value of "true". This property serves as a marker to the Jakarta™ XML Web Services Whiteboard runtime, indicating that this OSGi service should be further processed as an endpoint.

Besides that, the property osgi.jakarta.xml.ws.endpoint.address can be specified as a way to indicate at what address an Endpoint should be published. If given, this must be passed to the Endpoint.publish(String) method as defined in the [6] Jakarta™ XML Web Services Endpoint Publishing. If it is not specified or is empty, it is assumed that there is some other property available to allow the Whiteboard runtime to derive the publishing address or context. In the scope of this specification, there is the osgi.jakarta.xml.ws.endpoint.http.contextpath property that defines that the endpoint should be published to the HTTP transport where / represents the root. What host or port is chosen is defined by the configuration of the implementation.

The code below shows a simple echo web service Endpoint Implementor. The @WebService and @WebMethod annotations are Jakarta™ XML Web Services annotations that define the service interface and operations; these annotations are processed by the Jakarta™ XML Web Services runtime, not by the Whiteboard runtime. The Whiteboard runtime is only responsible for managing the lifecycle and registration of the endpoint:

@WebService
@WhiteboardEndpoint(address = "http://localhost/echo")
@Component(immediate = true, service = WSEcho.class, property = "wstype=echo")
public class WSEcho {

    @WebMethod(operationName = "echo", action = "echo")
    public String echo(@WebParam(name = "textIn") String text) {
        return text;
    }

}

There is no particular order in which Endpoint Implementors are published. They could be registered as soon as the service is visible in the OSGi service registry or even delayed in the background. If any particular ordering of publishing is desired, this must be synchronized externally, e.g., by observing the Runtime Service and waiting for a prerequisite endpoint to show up. Due to the dynamic nature of OSGi, most systems should be designed in a way that the exact point in time of publishing the endpoint is not required for the system to function correctly.

Web Service Handlers can be registered with the Jakarta™ XML Web Services Whiteboard in one of two ways:

At runtime the Handler Chain is determined based on the total set of handlers, regardless of how they were registered.

To be identified as a Handler Service by the Jakarta™ XML Web Services Whiteboard the service must be registered in the following way.

A Correctly registered handler will be included in the Handler Chain used when publishing the endpoint. It will also result in a HandlerDTO being added to the RuntimeDTO of the Whiteboard Runtime Service.

Failing to register the service appropriately will result in it being ignored by the whiteboard runtime. Correctly registering a handler which turns out to be invalid, for example if it is incorrectly annotated and rejected by the Web Services runtime, will result in a FailedHandlerDTO being added to the RuntimeDTO as described in Whiteboard Error Handling.

The code below shows an example of a logging handler that wants to intercept incoming and outgoing messages, this handler is targeted to any registered Endpoint Implementor:

@Component(service = Handler.class)
@XmlWsHandler()
public class SOAPLoggingHandler implements SOAPHandler<SOAPMessageContext> {

     public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleMessage(SOAPMessageContext smc) {
         smc.getMessage().writeTo(System.out);
        return true;
    }

    public boolean handleFault(SOAPMessageContext smc) {
        smc.getMessage().writeTo(System.err);
        return true;
    }

    public void close(MessageContext messageContext) {
    }
    
}

The combination of static and dynamic handlers are assembled into a handler chain according to the natural order of their service references, usually referred to as service ranking order. This means that Handlers with a higher service ranking will be positioned before those with a lower service ranking in the chain. If two handlers have the same ranking they are sorted according to their service id, with handlers registered later being positioned later in the handler chain.

If a static handler chain is provided then this is maintained in the configured order and must be placed immediately after all services with a ranking of 1 or higher and before any services with a ranking of 0 or lower.

This handler chain is then passed to the Jakarta™ XML Web Services implementation where it is used to process requests.

160.1.4.1 Understanding Handler Execution Order

This specification follows the Jakarta™ XML Web Services execution model as defined in [4] Jakarta™ XML Web Services Handler Execution. When working across multiple Jakarta specifications, developers should understand these execution model differences to avoid incorrect assumptions about handler or filter ordering.

The Jakarta™ XML Web Services specification defines a specific handler execution model that may initially seem counterintuitive. Understanding the rationale behind this design is important for correctly implementing handler chains, especially when working with different Jakarta specifications that have different execution models.

160.1.4.1.1 Jakarta™ XML Web Services Handler Execution Model

As specified in [4] Jakarta™ XML Web Services Handler Execution, the Jakarta™ XML Web Services handler execution follows these rules:

• Outbound messages: Handler processing starts with the first handler in the chain and proceeds in the same order as the handler chain.

• Inbound messages: The order of processing is reversed - processing starts with the last handler in the chain and proceeds backwards.

As a result, while handlers are assembled in order of service ranking (highest first), the actual processing order depends on the message direction. Users should be aware of this distinction to avoid confusion about handler execution order.

This bidirectional processing model is designed to support the layered nature of SOAP message processing. The key insight is that handlers often work in complementary pairs during request and response processing. Consider these common use cases:

1. Security Processing: A security handler might encrypt or sign parts of an outbound SOAP message. On the inbound response, the same handler needs to decrypt or verify signatures. The reversed execution order ensures that the security handler that processed the outbound request is also the one that processes the corresponding inbound response, maintaining proper context and state.

2. Logging and Monitoring: A logging handler positioned early in the chain for outbound messages can log the original message before any transformations. For inbound messages, by being processed last (reversed order), it logs the final processed response. This creates a symmetrical logging pattern around the entire message flow.

3. Message Transformation: Protocol handlers (SOAPHandler) work at the SOAP message level and need to process messages before logical handlers (LogicalHandler) on outbound messages. On inbound messages, the reverse is needed - logical handlers should see the message after protocol-level processing is complete. The reversed execution naturally provides this layering.

This model creates a "tunnel" or "onion layer" pattern where each handler wraps the message processing, processing it on the way out and unwrapping it on the way back in. This is particularly important for SOAP-based web services where message integrity, security, and proper protocol layering are critical.

To illustrate this execution flow, consider a complete request-response cycle between a client and server, where both use a handler chain consisting of handlers A, B, and C (ordered by service ranking with A having the highest rank):

Figure 160.2 Handler Execution Flow: Complete Request-Response Cycle

As shown in Figure 160.2, the handler chain is traversed in different directions depending on whether the message is inbound or outbound, and whether it is being processed on the client or server side. This symmetric execution model ensures that complementary operations (such as encryption/decryption or signing/verification) are performed by the same handler in the appropriate order.

It is also important to note that when different handler types are used (such as LogicalHandler and SOAPHandler), each type executes as a group in different phases of message processing. This means that ordering cannot be controlled between handlers of different types, as they run in separate processing phases. The detailed rules for handler ordering across different handler types are described in the Jakarta™ XML Web Services specification (see [5] Jakarta™ XML Web Services Handler Ordering).

160.1.4.1.2 Comparison with Other Jakarta Specifications

Understanding how Jakarta™ XML Web Services differs from other Jakarta specifications helps clarify the design rationale. The key difference is that Jakarta XML Web Services uses a single handler type that processes both outbound and inbound messages, requiring reversed execution for inbound processing. Other specifications use distinct components for request and response processing.

160.1.4.1.2.1 Jakarta™ RESTful Web Services

Jakarta™ RESTful Web Services (Jakarta REST) uses distinct filter types for requests and responses: ContainerRequestFilter and ContainerResponseFilter (see [16] Jakarta™ RESTful Web Services Filters). Each filter type has its own priority ordering as defined in Section 6.5.1 "Priorities" (see [15] Jakarta™ RESTful Web Services Priorities). Since request and response are handled by separate filter types, there is no need for reversed execution - each can be ordered independently.

Similar to how Jakarta XML Web Services separates handlers into logical and SOAP handler types for different processing phases, Jakarta REST uses @PreMatching annotations to divide filters into groups that execute at different stages of the processing pipeline (see [17] Jakarta™ RESTful Web Services Processing Pipeline). However, the fundamental difference remains: Jakarta REST filters can directly wrap the request/response objects, while Jakarta XML Web Services handlers work on a message-based approach where the response message does not yet exist during outbound processing.

160.1.4.1.2.2 Jakarta™ Servlet

Jakarta™ Servlet filters (see [18] Jakarta™ Servlet Specification) provide another comparison point. A servlet filter is called once and processes both request and response in a single invocation by wrapping them. The filter chain executes in declaration order for request processing, and automatically reverses for response processing because each filter wraps the next filter in the chain (see [19] Jakarta™ Servlet Filter Chain). This is conceptually similar to Jakarta XML Web Services' reversed execution, but achieved through the wrapping pattern rather than explicit handler chain reversal. The difference is that servlet filters can wrap request and response objects directly, whereas Jakarta XML Web Services handlers must work with messages where the response is not yet available during outbound processing.

If a handler wants to target a specific Endpoint Implementor it can specify the osgi.jakarta.xml.ws.handler.filter service properties and will only be installed for such Endpoint Implementor that match the provided filter.

The previous example targeting an Endpoint Implementor registered with a wstype property of echo looks like this:

@Component(service = Handler.class)
@XmlWsHandler(filter="(wstype=echo)")
public class SOAPLoggingHandler implements SOAPHandler<SOAPMessageContext> {

       ... like before ...
}

The WebserviceServiceRuntime service represents the runtime state information of a Jakarta XML Web Services Whiteboard instance. This information is provided through Data Transfer Objects (DTOs). The architecture of OSGi DTOs is described in OSGi Core Release 8.

The WebserviceServiceRuntime provides service registration properties to describe its underlying Jakarta XML Web Services Whiteboard. These service properties can include implementation-specific key-value pairs. They also include the following:

The getRuntimeDTO() method allows access to the RuntimeDTO that provides a snapshot of the current state of the runtime to gather information about

The EndpointDTO provides the following information:

The FailedDTO is the base class for the FailedEndpointDTO and FailedEndpointDTO and provides basic information about a failure:

The FailedEndpointDTO extends the FailedDTO with additional information specific to endpoints:

The FailedHandlerDTO extends the FailedDTO with additional information specific to handlers:

There are a number of error cases where the Jakarta Web Service whiteboard may be unable to correctly register an endpoint or use a given handler. All of these cases must result in a failure DTO being created with the appropriate error code.