0
# Message Processing
1

2
Central message processing APIs providing SOAP message abstraction, pipeline processing, attachment handling, and header management. These APIs form the foundation for all web service communication in JAX-WS.
3

4
## Capabilities
5

6
### Message Abstraction
7

8
Core SOAP message representation supporting various formats and providing unified access to message content.
9

10
```java { .api }
11
/**
12
 * Abstract representation of a SOAP message with support for various formats and operations
13
 */
14
package com.sun.xml.ws.api.message;
15
public abstract class Message {
16
    /** Check if message has a payload body */
17
    public abstract boolean hasPayload();
18
    
19
    /** Get payload local name */
20
    public abstract String getPayloadLocalPart();
21
    
22
    /** Get payload namespace URI */
23
    public abstract String getPayloadNamespaceURI();
24
    
25
    /** Check if message is a SOAP fault */
26
    public abstract boolean isFault();
27
    
28
    /** Get first detail entry name for faults */
29
    public abstract QName getFirstDetailEntryName();
30
    
31
    /** Read payload as XML Source for processing */
32
    public abstract Source readPayloadAsSource();
33
    
34
    /** Read entire envelope as XML Source */
35
    public abstract Source readEnvelopeAsSource();
36
    
37
    /** Read payload as XMLStreamReader */
38
    public abstract XMLStreamReader readPayload() throws XMLStreamException;
39
    
40
    /** Read payload as JAXB object */
41
    public abstract <T> T readPayloadAsJAXB(Unmarshaller unmarshaller) throws JAXBException;
42
    
43
    /** Read payload as JAXB object using Bridge */
44
    public abstract <T> T readPayloadAsJAXB(Bridge<T> bridge) throws JAXBException;
45
    
46
    /** Read payload as JAXB object using XMLBridge */
47
    public abstract <T> T readPayloadAsJAXB(XMLBridge<T> bridge) throws JAXBException;
48
    
49
    /** Convert to SAAJ SOAPMessage for compatibility */
50
    public abstract SOAPMessage readAsSOAPMessage() throws SOAPException;
51
    
52
    /** Write message content to SAX ContentHandler */
53
    public abstract void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) throws SAXException;
54
    
55
    /** Write message to XMLStreamWriter */
56
    public abstract void writeTo(XMLStreamWriter writer) throws XMLStreamException;
57
    
58
    /** Write payload to XMLStreamWriter */
59
    public abstract void writePayloadTo(XMLStreamWriter writer) throws XMLStreamException;
60
    
61
    /** Get SOAP version */
62
    public final SOAPVersion getSOAPVersion();
63
    
64
    /** Get message headers */
65
    public abstract MessageHeaders getHeaders();
66
    
67
    /** Get collection of MIME attachments */
68
    public abstract AttachmentSet getAttachments();
69
    
70
    /** Check if message has attachments */
71
    protected boolean hasAttachments();
72
    
73
    /** Consume message (makes it no longer readable) */
74
    public abstract void consume();
75
    
76
    /** Create copy of message */
77
    public abstract Message copy();
78
    
79
    /** Get unique message ID */
80
    public String getID(SOAPVersion soapVersion, AddressingVersion addressingVersion);
81
}
82
```
83

84
### Message Factory
85

86
Factory methods for creating various types of messages.
87

88
```java { .api }
89
/**
90
 * Factory class for creating Message instances from various sources
91
 */
92
public final class Messages {
93
    /** Create message from JAXB object */
94
    public static Message create(JAXBContext jaxbContext, Object jaxbObject, SOAPVersion soapVersion);
95
    
96
    /** Create message from XML Source */
97
    public static Message create(Source source, SOAPVersion soapVersion);
98
    
99
    /** Create message from SOAPMessage */
100
    public static Message create(SOAPMessage soapMessage);
101
    
102
    /** Create empty message */
103
    public static Message createEmpty(SOAPVersion soapVersion);
104
    
105
    /** Create fault message */
106
    public static Message create(SOAPFault fault);
107
}
108
```
109

110
### Packet Container
111

112
Container for messages with associated metadata and processing context.
113

114
```java { .api }
115
/**
116
 * Container for SOAP message with associated metadata, properties, and processing context.
117
 * Extends BaseDistributedPropertySet and implements MessageContext and MessageMetadata.
118
 */
119
public final class Packet extends BaseDistributedPropertySet 
120
    implements MessageContext, MessageMetadata {
121
    
122
    /** Get the SOAP message */
123
    public Message getMessage();
124
    
125
    /** Set the SOAP message */
126
    public void setMessage(Message msg);
127
    
128
    /** Get properties as Map including invocation properties */
129
    public Map<String, Object> asMapIncludingInvocationProperties();
130
    
131
    /** Get strongly-typed satellite object (inherited) */
132
    public <T> T getSatellite(Class<T> satelliteClass);
133
    
134
    /** Set satellite object (inherited) */
135
    public <T> void setSatellite(Class<T> satelliteClass, T satellite);
136
    
137
    /** Create client response packet */
138
    public Packet createClientResponse(Message responseMessage);
139
    
140
    /** Create server response packet */
141
    public Packet createServerResponse(@Nullable Message responseMessage, 
142
                                      @NotNull QName wsdlOperationName, 
143
                                      @NotNull WSDLPort wsdlPort, 
144
                                      @NotNull SEIModel seiModel, 
145
                                      @NotNull WSBinding binding);
146
    
147
    /** Copy packet with optional message copying */
148
    public Packet copy(boolean copyMessage);
149
    
150
    /** Get endpoint address */
151
    public @NotNull EndpointAddress getEndpointAddress();
152
    
153
    /** Set endpoint address */
154
    public void setEndpointAddress(@NotNull EndpointAddress address);
155
    
156
    /** Get WSDL operation name */
157
    public @Nullable QName getWSDLOperation();
158
    
159
    /** Set WSDL operation name */
160
    public void setWSDLOperation(@Nullable QName wsdlOp);
161
    
162
    /** Check if packet represents a request */
163
    public boolean isRequestMessage;
164
    
165
    /** Check if transport is synchronous */
166
    public Boolean transportBackChannel;
167
    
168
    /** Get content negotiation property map */
169
    public ContentNegotiation contentNegotiation;
170
}
171
```
172

173
### SOAP Headers
174

175
Header management for SOAP messages with support for various header formats.
176

177
```java { .api }
178
/**
179
 * Individual SOAP header representation
180
 */
181
public abstract class Header {
182
    /** Get header element name */
183
    public abstract QName getName();
184
    
185
    /** Get namespace URI */
186
    public String getNamespaceURI();
187
    
188
    /** Get local name */
189
    public String getLocalPart();
190
    
191
    /** Check if header is targeted to role */
192
    public abstract boolean isTargetedToRole(Set<String> roles, SOAPVersion soapVersion);
193
    
194
    /** Read header as XML Source */
195
    public abstract Source readAsSource();
196
    
197
    /** Read header as JAXB object */
198
    public abstract <T> T readAsJAXB(JAXBContext jaxbContext) throws JAXBException;
199
    
200
    /** Write header to XMLStreamWriter */
201
    public abstract void writeTo(XMLStreamWriter writer) throws XMLStreamException;
202
}
203

204
/**
205
 * Collection of SOAP headers with management operations.
206
 * Extends ArrayList and implements MessageHeaders interface.
207
 */
208
public final class HeaderList extends ArrayList<Header> implements MessageHeaders {
209
    /** Add header to collection */
210
    public void add(Header header);
211
    
212
    /** Get header by name */
213
    public Header get(QName name, boolean markAsUnderstood);
214
    
215
    /** Get header by namespace and local name */
216
    public Header get(String nsUri, String localName, boolean markAsUnderstood);
217
    
218
    /** Get all headers for namespace */
219
    public List<Header> getHeaders(String nsUri);
220
    
221
    /** Get all headers for namespace and local name */
222
    public List<Header> getHeaders(String nsUri, String localName);
223
    
224
    /** Remove header by QName */
225
    public boolean remove(QName name);
226
    
227
    /** Remove header by namespace and local name */
228
    public boolean remove(String nsUri, String localName);
229
    
230
    /** Check if headers exist */
231
    public boolean hasHeaders();
232
    
233
    /** Get iterator over headers */
234
    public Iterator<Header> iterator();
235
    
236
    /** Mark header as understood */
237
    public void understood(QName name);
238
    
239
    /** Mark header as understood by namespace and local name */
240
    public void understood(String nsUri, String localName);
241
    
242
    /** Get headers not understood */
243
    public Set<QName> getNotUnderstoodHeaders(Set<String> roles, Set<QName> knownHeaders, WSBinding binding);
244
}
245
```
246

247
### Header Factory
248

249
Factory methods for creating various types of headers.
250

251
```java { .api }
252
/**
253
 * Factory methods for creating SOAP headers
254
 */
255
public final class Headers {
256
    /** Create header from JAXB object */
257
    public static Header create(JAXBContext jaxbContext, Object jaxbObject) throws JAXBException;
258
    
259
    /** Create header from XML Source */
260
    public static Header create(QName name, Source source);
261
    
262
    /** Create string-based header */
263
    public static Header create(QName name, String value);
264
    
265
    /** Create header from DOM Element */
266
    public static Header create(Element element);
267
}
268
```
269

270
### Pipeline Processing
271

272
Asynchronous processing pipeline with tube-based architecture.
273

274
```java { .api }
275
/**
276
 * Asynchronous processing unit in message pipeline
277
 */
278
package com.sun.xml.ws.api.pipe;
279
public interface Tube {
280
    /** Process request packet and return next action */
281
    NextAction processRequest(Packet request);
282
    
283
    /** Process response packet and return next action */
284
    NextAction processResponse(Packet response);
285
    
286
    /** Pre-destroy cleanup */
287
    void preDestroy();
288
    
289
    /** Create copy of tube */
290
    Tube copy(TubeCloner cloner);
291
}
292

293
/**
294
 * Next action in pipeline processing - final class with instance methods
295
 */
296
public final class NextAction {
297
    /** Continue processing with next tube */
298
    public NextAction invoke(Tube next, Packet packet);
299
    
300
    /** Suspend processing and resume later */
301
    public NextAction suspend(Packet packet, Runnable onResume);
302
    
303
    /** Suspend with fiber and runnable */
304
    public NextAction suspend(Packet packet, Fiber.CompletionCallback onResume);
305
    
306
    /** Return response immediately */
307
    public NextAction returnWith(Packet response);
308
    
309
    /** Throw exception */
310
    public NextAction throwException(Throwable throwable);
311
    
312
    /** Get the packet associated with this action */
313
    public Packet getPacket();
314
    
315
    /** Get the next tube to invoke */
316
    public Tube getNext();
317
    
318
    /** Get throwable if action is to throw exception */
319
    public Throwable getThrowable();
320
    
321
    /** Check if this action suspends processing */
322
    public boolean isSuspend();
323
    
324
    /** Check if this action returns a response */
325
    public boolean isReturn();
326
    
327
    /** Check if this action throws an exception */
328
    public boolean isThrow();
329
    
330
    /** Check if this action invokes next tube */
331
    public boolean isInvoke();
332
}
333
```
334

335
### Codec System
336

337
Message encoding and decoding between different formats.
338

339
```java { .api }
340
/**
341
 * Encodes/decodes SOAP messages to/from transport format
342
 */
343
public interface Codec {
344
    /** Get MIME content type for encoding */
345
    String getMimeType();
346
    
347
    /** Get supported content types for decoding */
348
    ContentType getStaticContentType(Packet packet);
349
    
350
    /** Encode packet to output stream */
351
    ContentType encode(Packet packet, OutputStream out) throws IOException;
352
    
353
    /** Decode input stream to packet */
354
    void decode(InputStream in, String contentType, Packet packet) throws IOException;
355
    
356
    /** Create copy of codec */
357
    Codec copy();
358
}
359
```
360

361
### Attachment Handling
362

363
MIME attachment support for SOAP messages.
364

365
```java { .api }
366
/**
367
 * MIME attachment representation
368
 */
369
package com.sun.xml.ws.api.message;
370
public interface Attachment {
371
    /** Get Content-ID header value */
372
    String getContentId();
373
    
374
    /** Get Content-Type header value */
375
    String getContentType();
376
    
377
    /** Get attachment content as byte array */
378
    byte[] asByteArray();
379
    
380
    /** Get attachment as DataHandler */
381
    DataHandler asDataHandler();
382
    
383
    /** Get attachment as XML Source */
384
    Source asSource();
385
    
386
    /** Get attachment as InputStream */
387
    InputStream asInputStream();
388
    
389
    /** Write attachment to OutputStream */
390
    void writeTo(OutputStream os) throws IOException;
391
}
392

393
/**
394
 * Collection of attachments with management operations
395
 */
396
public interface AttachmentSet extends Iterable<Attachment> {
397
    /** Get attachment by Content-ID */
398
    Attachment get(String contentId);
399
    
400
    /** Check if attachments exist */
401
    boolean isEmpty();
402
    
403
    /** Add attachment */
404
    void add(Attachment attachment);
405
    
406
    /** Get iterator over attachments */
407
    Iterator<Attachment> iterator();
408
}
409
```
410

411
**Usage Examples:**
412

413
```java
414
import com.sun.xml.ws.api.message.*;
415
import com.sun.xml.ws.api.pipe.*;
416

417
// Create message from JAXB object
418
JAXBContext jaxbContext = JAXBContext.newInstance(MyRequestType.class);
419
MyRequestType request = new MyRequestType();
420
Message message = Messages.create(jaxbContext, request, SOAPVersion.SOAP_11);
421

422
// Add custom header
423
HeaderList headers = message.getHeaders();
424
Header customHeader = Headers.create(new QName("http://example.com", "CustomHeader"), "value");
425
headers.add(customHeader);
426

427
// Create packet with message
428
Packet packet = new Packet(message);
429
packet.put("custom.property", "value");
430

431
// Process through tube pipeline
432
public class MyTube implements Tube {
433
    private Tube next;
434
    
435
    public NextAction processRequest(Packet request) {
436
        // Process request
437
        Message msg = request.getMessage();
438
        if (msg.hasPayload()) {
439
            // Handle request logic
440
        }
441
        
442
        // Continue to next tube
443
        return NextAction.invoke(next, request);
444
    }
445
    
446
    public NextAction processResponse(Packet response) {
447
        // Process response
448
        return NextAction.returnWith(response);
449
    }
450
}
451
```