0
# Server Endpoints
1

2
Server-side web service endpoint creation, lifecycle management, request processing, and deployment integration with support for various hosting scenarios including standalone, servlet containers, and application servers.
3

4
## Capabilities
5

6
### Endpoint Creation and Management
7

8
Core server-side processing object providing complete web service endpoint functionality.
9

10
```java { .api }
11
/**
12
 * Root server-side processing object that represents a web service endpoint.
13
 * Implements ComponentRegistry and ComponentEx interfaces.
14
 */
15
package com.sun.xml.ws.api.server;
16
public abstract class WSEndpoint<T> implements ComponentRegistry, ComponentEx {
17
    /** Create endpoint from implementation class with full configuration */
18
    public static <T> WSEndpoint<T> create(
19
        Class<T> implType,                                    // Implementation class
20
        boolean processHandlerAnnotation,                     // Process @HandlerChain annotations
21
        Invoker invoker,                                      // Service instance invoker
22
        QName serviceName,                                    // WSDL service name  
23
        QName portName,                                       // WSDL port name
24
        Container container,                                  // Runtime container
25
        WSBinding binding,                                    // Protocol binding
26
        SDDocumentSource primaryWsdl,                        // Primary WSDL document
27
        Collection<? extends SDDocumentSource> metadata,     // Additional metadata
28
        EntityResolver resolver,                             // XML entity resolver
29
        boolean isTransportSynchronous                       // Transport synchronization
30
    );
31
    
32
    /** Create endpoint from existing endpoint with new binding */
33
    public static <T> WSEndpoint<T> create(WSEndpoint<T> endpoint, WSBinding binding);
34
    
35
    /** Get implementation class */
36
    public abstract @NotNull Class<T> getImplementationClass();
37
    
38
    /** Get codec for message encoding/decoding */
39
    public abstract @NotNull Codec createCodec();
40
    
41
    /** Get complete service definition including WSDL */
42
    public abstract @Nullable ServiceDefinition getServiceDefinition();
43
    
44
    /** Get service endpoint interface model */
45
    public abstract @Nullable SEIModel getSEIModel();
46
    
47
    /** Get protocol binding */
48
    public abstract @NotNull WSBinding getBinding();
49
    
50
    /** Get runtime container */
51
    public abstract @NotNull Container getContainer();
52
    
53
    /** Get port name */
54
    public abstract @NotNull QName getPortName();
55
    
56
    /** Get service name */
57
    public abstract @NotNull QName getServiceName();
58
    
59
    /** Get WSDL port information */
60
    public abstract @Nullable WSDLPort getPort();
61
    
62
    /** Set executor for async processing */
63
    public abstract void setExecutor(@NotNull Executor exec);
64
    
65
    /** Schedule packet for async processing */
66
    public abstract void schedule(@NotNull Packet request, @NotNull CompletionCallback callback);
67
    
68
    /** Create processing pipeline head */
69
    public abstract @NotNull PipeHead createPipeHead();
70
    
71
    /** Get engine (may throw UnsupportedOperationException) */
72
    public Engine getEngine();
73
    
74
    /** Get bound endpoints */
75
    public List<BoundEndpoint> getBoundEndpoints();
76
    
77
    /** Get all registered components */
78
    public abstract @NotNull Set<Component> getComponents();
79
    
80
    /** Get service provider interface implementation */
81
    public abstract @Nullable <S> S getSPI(@NotNull Class<S> spiType);
82
    
83
    /** Get managed object manager */
84
    public abstract @NotNull ManagedObjectManager getManagedObjectManager();
85
    
86
    /** Close managed object manager */
87
    public abstract void closeManagedObjectManager();
88
    
89
    /** Get tube assembler context */
90
    public abstract @NotNull ServerTubeAssemblerContext getAssemblerContext();
91
    
92
    /** Get operation dispatcher */
93
    public @Nullable OperationDispatcher getOperationDispatcher();
94
    
95
    /** Dispose endpoint and clean up resources */
96
    public abstract void dispose();
97
    
98
    /** Get endpoint reference */
99
    public abstract WSEndpointReference getEndpointReference(Class<? extends EndpointReference> clazz, 
100
                                                           String address, String wsdlAddress, 
101
                                                           Element... referenceParameters);
102
                                                           
103
    /** Create service response for exception */
104
    public Packet createServiceResponseForException(ThrowableContainerPropertySet tc,
105
                                                   Packet responsePacket,
106
                                                   SOAPVersion soapVersion,
107
                                                   WSDLPort wsdlPort,
108
                                                   SEIModel seiModel,
109
                                                   WSBinding binding);
110
}
111
```
112

113
### Transport Adapters
114

115
Transport-specific adapters that bridge between endpoints and various transport protocols.
116

117
```java { .api }
118
/**
119
 * Transport-specific adapter for handling protocol-specific requests
120
 */
121
public abstract class Adapter<TK> {
122
    /** Get toolkit-specific adapter implementation */
123
    public abstract ToolkitAdapter<TK> getToolkit();
124
    
125
    /** Handle incoming request using transport toolkit */
126
    public abstract void handle(TK connection) throws IOException;
127
    
128
    /** Get associated endpoint */
129
    public WSEndpoint<?> getEndpoint();
130
    
131
    /** Get URL pattern for adapter */
132
    public String getUrlPattern();
133
}
134

135
/**
136
 * HTTP-specific adapter implementation
137
 */
138
package com.sun.xml.ws.transport.http;
139
public final class HttpAdapter extends Adapter<WSHTTPConnection> {
140
    /** Create standalone HTTP adapter */
141
    public static HttpAdapter createAlone(WSEndpoint<?> endpoint, Map<String, String> urlPattern);
142
    
143
    /** Handle HTTP connection */
144
    public void handle(WSHTTPConnection connection) throws IOException;
145
    
146
    /** Get HTTP metadata document */
147
    public void publishWSDL(WSHTTPConnection connection) throws IOException;
148
}
149
```
150

151
### Container Integration
152

153
Container abstraction for integration with various runtime environments.
154

155
```java { .api }
156
/**
157
 * Runtime container abstraction providing services and lifecycle management
158
 */
159
public abstract class Container {
160
    /** Get container-specific service implementation */
161
    public abstract <T> T getSPI(Class<T> spiType);
162
    
163
    /** Get components of specified type */
164
    public <T> Iterable<Component<T>> getComponents(Class<T> componentType);
165
    
166
    /** Default container implementation */
167
    public static final Container NONE = new Container() {
168
        public <T> T getSPI(Class<T> spiType) { return null; }
169
    };
170
}
171

172
/**
173
 * Container resolver for discovering container implementations
174
 */
175
public abstract class ContainerResolver {
176
    /** Get container for current thread */
177
    public static Container getContainer();
178
    
179
    /** Set container for current thread */
180
    public static void setContainer(Container container);
181
    
182
    /** Get default container implementation */
183
    public abstract Container getContainer(Class<?> endpointClass) throws WebServiceException;
184
}
185
```
186

187
### Service Instance Management
188

189
Lifecycle management for web service implementation instances.
190

191
```java { .api }
192
/**
193
 * Manages lifecycle of service implementation instances
194
 */
195
public abstract class InstanceResolver<T> {
196
    /** Resolve service instance for request */
197
    public abstract T resolve(Packet request);
198
    
199
    /** Dispose service instance after request */
200
    public abstract void dispose(T instance);
201
    
202
    /** Create singleton instance resolver */
203
    public static <T> InstanceResolver<T> createSingleton(T singleton);
204
    
205
    /** Create resolver that creates new instance per request */
206
    public static <T> InstanceResolver<T> createFromInstanceResolverAnnotation(Class<T> clazz);
207
    
208
    /** Create resolver using specific factory */
209
    public static <T> InstanceResolver<T> createDefault(Class<T> clazz, boolean hasDefaultConstructor);
210
}
211

212
/**
213
 * Service method invocation abstraction
214
 */
215
public interface Invoker {
216
    /** Invoke service method with packet context */
217
    Object invoke(Packet request, Method method, Object... args) throws 
218
        IllegalAccessException, IllegalArgumentException, InvocationTargetException;
219
    
220
    /** Invoke method on specific instance */
221
    <T> T invoke(Packet request, Object instance, Method method, Object... args) throws
222
        IllegalAccessException, IllegalArgumentException, InvocationTargetException;
223
}
224
```
225

226
### Service Definition and Metadata
227

228
Service description including WSDL and schema documents.
229

230
```java { .api }
231
/**
232
 * Service description document (WSDL, schema, etc.)
233
 */
234
public abstract class SDDocument {
235
    /** Get document URL */
236
    public abstract URL getURL();
237
    
238
    /** Get document as Source */
239
    public abstract Source read() throws IOException, SAXException;
240
    
241
    /** Get document as InputStream */
242
    public abstract InputStream read() throws IOException;
243
    
244
    /** Check if document is WSDL */
245
    public abstract boolean isWSDL();
246
    
247
    /** Check if document is schema */  
248
    public abstract boolean isSchema();
249
    
250
    /** Get target namespace */
251
    public abstract QName getRootName();
252
}
253

254
/**
255
 * Complete service definition including all metadata documents
256
 */
257
public interface ServiceDefinition extends Iterable<SDDocument> {
258
    /** Get primary WSDL document */
259
    SDDocument getPrimary();
260
    
261
    /** Filter documents by criteria */
262
    Iterable<SDDocument> filter(SDDocumentFilter filter);
263
    
264
    /** Add schema resolver */
265
    void addFilter(SDDocumentFilter filter);
266
}
267

268
/**
269
 * Source for service description documents
270
 */
271
public abstract class SDDocumentSource {
272
    /** Get document URL */  
273
    public abstract URL getSystemId();
274
    
275
    /** Read document as Source */
276
    public abstract Source read() throws IOException, SAXException;
277
    
278
    /** Create from URL */
279
    public static SDDocumentSource create(URL url);
280
    
281
    /** Create from Source */
282
    public static SDDocumentSource create(URL systemId, Source source);
283
}
284
```
285

286
### Endpoint Publishing
287

288
Simplified endpoint publishing for standalone deployments.
289

290
```java { .api }
291
/**
292
 * HTTP endpoint publishing utilities
293
 */
294
package com.sun.xml.ws.transport.http;
295
public final class HttpEndpoint {
296
    /** Publish endpoint at HTTP address */
297
    public static HttpEndpoint publish(String address, Object implementor);
298
    
299
    /** Publish with executor service */
300
    public static HttpEndpoint publish(String address, Object implementor, Executor executor);
301
    
302
    /** Stop endpoint */
303
    public void stop();
304
    
305
    /** Check if endpoint is stopped */
306
    public boolean isStopped();
307
}
308
```
309

310
**Usage Examples:**
311

312
```java
313
import com.sun.xml.ws.api.server.*;
314
import com.sun.xml.ws.transport.http.*;
315

316
// Create endpoint programmatically
317
@WebService
318
public class CalculatorImpl {
319
    @WebMethod
320
    public int add(int a, int b) {
321
        return a + b;
322
    }
323
}
324

325
// Create endpoint with full configuration
326
Class<CalculatorImpl> implClass = CalculatorImpl.class;
327
Invoker invoker = InstanceResolver.createDefault(implClass, true).createInvoker();
328
QName serviceName = new QName("http://example.com/", "CalculatorService");  
329
QName portName = new QName("http://example.com/", "CalculatorPort");
330
WSBinding binding = BindingImpl.create(BindingID.SOAP11_HTTP);
331

332
WSEndpoint<CalculatorImpl> endpoint = WSEndpoint.create(
333
    implClass,
334
    true,                    // Process handler annotations
335
    invoker,
336
    serviceName,
337
    portName,
338
    Container.NONE,         // No container
339
    binding,
340
    null,                   // No primary WSDL
341
    Collections.emptyList(), // No metadata
342
    null,                   // No entity resolver
343
    true                    // Synchronous transport
344
);
345

346
// Create HTTP adapter
347
HttpAdapter adapter = HttpAdapter.createAlone(endpoint, Collections.emptyMap());
348

349
// Publish endpoint
350
HttpEndpoint httpEndpoint = HttpEndpoint.publish("http://localhost:8080/calculator", adapter);
351

352
// Custom container with services
353
Container customContainer = new Container() {
354
    @SuppressWarnings("unchecked")
355
    public <T> T getSPI(Class<T> spiType) {
356
        if (spiType == MyCustomService.class) {
357
            return (T) new MyCustomServiceImpl();
358
        }
359
        return null;
360
    }
361
};
362

363
// Use custom instance resolver
364
InstanceResolver<CalculatorImpl> resolver = new InstanceResolver<CalculatorImpl>() {
365
    public CalculatorImpl resolve(Packet request) {
366
        // Custom instance creation logic
367
        return new CalculatorImpl();
368
    }
369
    
370
    public void dispose(CalculatorImpl instance) {
371
        // Custom cleanup logic
372
    }
373
};
374
```