0
# Policy Framework
1

2
WS-Policy implementation providing declarative configuration of web service capabilities, policy attachment, assertion processing, and policy-driven feature configuration. The framework enables standards-based policy negotiation and enforcement.
3

4
## Capabilities
5

6
### Core Policy Representation
7

8
Central policy abstractions providing normalized policy representation and assertion management.
9

10
```java { .api }
11
/**
12
 * Normalized policy representation containing assertion alternatives
13
 */
14
package com.sun.xml.ws.policy;
15
public final class Policy implements Iterable<AssertionSet> {
16
    /** Create policy from source model */
17
    public static Policy createPolicy(PolicySourceModel model) throws PolicyException;
18
    
19
    /** Create empty policy */
20
    public static Policy createEmptyPolicy();
21
    
22
    /** Create policy from existing policy */
23
    public static Policy createPolicy(Policy... policies) throws PolicyException;
24
    
25
    /** Check if policy is empty */
26
    public boolean isEmpty();
27
    
28
    /** Check if policy contains assertions */
29
    public boolean contains(String assertionNamespace);
30
    
31
    /** Get iterator over assertion sets (alternatives) */
32
    public Iterator<AssertionSet> iterator();
33
    
34
    /** Normalize policy for client or server side */
35
    public Policy normalize(boolean isClient) throws PolicyException;
36
    
37
    /** Merge with another policy */
38
    public Policy merge(Policy policy) throws PolicyException;
39
    
40
    /** Intersect with another policy */
41
    public Policy intersect(Policy policy) throws PolicyException;
42
    
43
    /** Get policy ID */
44
    public String getId();
45
    
46
    /** Get policy name */
47
    public String getName();
48
}
49

50
/**
51
 * Collection of policy assertions representing one policy alternative
52
 */
53
public final class AssertionSet implements Iterable<PolicyAssertion> {
54
    /** Create assertion set from assertions */
55
    public static AssertionSet createAssertionSet(Collection<PolicyAssertion> assertions);
56
    
57
    /** Check if assertion set is empty */
58
    public boolean isEmpty();
59
    
60
    /** Get iterator over assertions */
61
    public Iterator<PolicyAssertion> iterator();
62
    
63
    /** Get assertions by type */
64
    public Collection<PolicyAssertion> get(QName assertionType);
65
    
66
    /** Check if contains assertion type */
67
    public boolean contains(QName assertionType);
68
}
69
```
70

71
### Policy Assertions
72

73
Base classes and implementations for policy assertions with support for simple and complex assertions.
74

75
```java { .api }
76
/**
77
 * Base class for all policy assertions
78
 */
79
public abstract class PolicyAssertion {
80
    /** Get assertion name (QName) */
81
    public abstract QName getName();
82
    
83
    /** Get assertion data including attributes */
84
    public final AssertionData getData();
85
    
86
    /** Check if assertion is optional */
87
    public final boolean isOptional();
88
    
89
    /** Check if assertion is private (ignorable) */
90
    public final boolean isPrivate();
91
    
92
    /** Get nested policy (for complex assertions) */
93
    public final Policy getNestedPolicy();
94
    
95
    /** Get nested assertions */
96
    public final Iterator<PolicyAssertion> getNestedAssertionsIterator();
97
    
98
    /** Check if assertion has nested policy */
99
    public final boolean hasNestedPolicy();
100
    
101
    /** Check if assertion has nested assertions */
102
    public final boolean hasNestedAssertions();
103
}
104

105
/**
106
 * Simple policy assertion with no nested content
107
 */
108
public abstract class SimpleAssertion extends PolicyAssertion {
109
    /** Constructor with assertion data */
110
    protected SimpleAssertion(AssertionData data, Collection<PolicyAssertion> assertionParameters);
111
    
112
    /** Get assertion value */
113
    public final String getValue();
114
    
115
    /** Check if assertion has value */
116
    public final boolean hasValue();
117
}
118

119
/**
120
 * Complex policy assertion with nested policy content
121
 */
122
public abstract class ComplexAssertion extends PolicyAssertion {
123
    /** Constructor with assertion data and nested policy */
124
    protected ComplexAssertion(AssertionData data, Collection<PolicyAssertion> assertionParameters, 
125
                             Policy nestedPolicy);
126
    
127
    /** Get nested policy */
128
    public final Policy getNestedPolicy();
129
}
130
```
131

132
### Policy Storage and Retrieval
133

134
Policy map providing organized storage and retrieval of policies by scope and subject.
135

136
```java { .api }
137
/**
138
 * Storage and retrieval system for policies organized by scope
139
 */
140
public final class PolicyMap {
141
    /** Get effective policy for service endpoint */
142
    public Policy getServiceEffectivePolicy(PolicyMapKey key) throws PolicyException;
143
    
144
    /** Get effective policy for endpoint */
145
    public Policy getEndpointEffectivePolicy(PolicyMapKey key) throws PolicyException;
146
    
147
    /** Get effective policy for operation */
148
    public Policy getOperationEffectivePolicy(PolicyMapKey key) throws PolicyException;
149
    
150
    /** Get effective policy for input message */
151
    public Policy getInputMessageEffectivePolicy(PolicyMapKey key) throws PolicyException;
152
    
153
    /** Get effective policy for output message */
154
    public Policy getOutputMessageEffectivePolicy(PolicyMapKey key) throws PolicyException;
155
    
156
    /** Get effective policy for fault message */
157
    public Policy getFaultMessageEffectivePolicy(PolicyMapKey key) throws PolicyException;
158
    
159
    /** Check if policy map is empty */
160
    public boolean isEmpty();
161
    
162
    /** Get all service subjects */
163
    public Collection<PolicyMapKey> getAllServiceScopeKeys();
164
    
165
    /** Get all endpoint subjects */
166
    public Collection<PolicyMapKey> getAllEndpointScopeKeys();
167
    
168
    /** Get all operation subjects */
169
    public Collection<PolicyMapKey> getAllOperationScopeKeys();
170
}
171

172
/**
173
 * Key for accessing policies in policy map
174
 */
175
public final class PolicyMapKey {
176
    /** Create service scope key */
177
    public static PolicyMapKey createServiceScopeKey(QName service);
178
    
179
    /** Create endpoint scope key */
180
    public static PolicyMapKey createEndpointScopeKey(QName service, QName port);
181
    
182
    /** Create operation scope key */
183
    public static PolicyMapKey createOperationScopeKey(QName service, QName port, QName operation);
184
    
185
    /** Create input message scope key */
186
    public static PolicyMapKey createInputMessageScopeKey(QName service, QName port, QName operation);
187
    
188
    /** Create output message scope key */
189
    public static PolicyMapKey createOutputMessageScopeKey(QName service, QName port, QName operation);
190
    
191
    /** Create fault message scope key */
192
    public static PolicyMapKey createFaultMessageScopeKey(QName service, QName port, QName operation, QName fault);
193
    
194
    /** Get service name */
195
    public QName getServiceName();
196
    
197
    /** Get port name */
198
    public QName getPortName();
199
    
200
    /** Get operation name */
201
    public QName getOperationName();
202
}
203
```
204

205
### Policy Source Model
206

207
Source model representation for policy documents before normalization.
208

209
```java { .api }
210
/**
211
 * Source representation of policy document
212
 */
213
package com.sun.xml.ws.policy.sourcemodel;
214
public final class PolicySourceModel {
215
    /** Create policy source model */
216
    public static PolicySourceModel createPolicySourceModel(QName policyName, String policyId);
217
    
218
    /** Get root model node */
219
    public ModelNode getRootNode();
220
    
221
    /** Get namespace to prefix mappings */
222
    public Map<String, String> getNamespaceToPrefixMapping();
223
    
224
    /** Expand policy model */
225
    public PolicySourceModel expand() throws PolicyException;
226
    
227
    /** Check if model contains assertion */
228
    public boolean containsAssertion(QName assertionName);
229
}
230

231
/**
232
 * Model node in policy source tree
233
 */
234
public final class ModelNode implements Iterable<ModelNode> {
235
    /** Get node type */
236
    public NodeType getType();
237
    
238
    /** Get node data */
239
    public AssertionData getNodeData();
240
    
241
    /** Get parent node */
242
    public ModelNode getParentNode();
243
    
244
    /** Get child nodes */
245
    public Iterator<ModelNode> getChildNodesIterator();
246
    
247
    /** Add child node */
248
    public ModelNode addChild(NodeType nodeType, AssertionData nodeData);
249
    
250
    /** Check if node has children */
251
    public boolean hasChildren();
252
}
253

254
/**
255
 * Policy model generator for creating source models
256
 */
257
public final class PolicyModelGenerator {
258
    /** Generate policy model from policy */
259
    public PolicySourceModel translate(Policy policy) throws PolicyException;
260
    
261
    /** Generate policy model with custom translator */
262
    public PolicySourceModel translate(Policy policy, PolicyModelTranslator translator) throws PolicyException;
263
}
264
```
265

266
### Policy Subject and Attachment
267

268
Policy subject identification and attachment mechanisms.
269

270
```java { .api }
271
/**
272
 * Policy attachment subject
273
 */
274
package com.sun.xml.ws.policy.subject;
275
public final class PolicySubject {
276
    /** Create policy subject */
277
    public static PolicySubject createPolicySubject(Object subject, Policy policy);
278
    
279
    /** Get subject object */
280
    public Object getSubject();
281
    
282
    /** Get attached policy */
283
    public Policy getPolicy();
284
    
285
    /** Attach policy to subject */
286
    public void attach(Policy policy);
287
}
288

289
/**
290
 * WSDL binding subject for policy attachment
291
 */
292
public final class WsdlBindingSubject {
293
    /** Create binding subject */
294
    public static WsdlBindingSubject createBindingSubject(QName bindingName);
295
    
296
    /** Create binding operation subject */
297
    public static WsdlBindingSubject createBindingOperationSubject(QName bindingName, QName operationName);
298
    
299
    /** Create binding message subject */
300
    public static WsdlBindingSubject createBindingMessageSubject(QName bindingName, QName operationName, 
301
                                                               QName messageName, WsdlMessageType messageType);
302
    
303
    /** Get binding name */
304
    public QName getName();
305
    
306
    /** Get message type */
307
    public WsdlMessageType getMessageType();
308
    
309
    /** Check if subject is binding level */
310
    public boolean isBindingSubject();
311
    
312
    /** Check if subject is operation level */
313
    public boolean isBindingOperationSubject();
314
    
315
    /** Check if subject is message level */
316
    public boolean isBindingMessageSubject();
317
}
318
```
319

320
### Service Provider Interfaces
321

322
Extension points for custom policy assertion creators and validators.
323

324
```java { .api }
325
/**
326
 * SPI for creating custom policy assertions
327
 */
328
package com.sun.xml.ws.policy.spi;
329
public interface PolicyAssertionCreator {
330
    /** Get supported domain namespace URIs */
331
    String[] getSupportedDomainNamespaceURIs();
332
    
333
    /** Create assertion from assertion data */
334
    PolicyAssertion createAssertion(AssertionData data, Collection<PolicyAssertion> assertionParameters, 
335
                                  Policy nestedPolicy) throws AssertionCreationException;
336
}
337

338
/**
339
 * SPI for validating policy assertions
340
 */
341
public interface PolicyAssertionValidator {
342
    /** Validate assertion */
343
    Fitness validateClientSide(PolicyAssertion assertion);
344
    
345
    /** Validate server side */
346
    Fitness validateServerSide(PolicyAssertion assertion);
347
    
348
    /** Get supported domain namespaces */
349
    String[] declareSupportedDomains();
350
}
351

352
/**
353
 * SPI for mapping namespace prefixes in policy documents
354
 */
355
public interface PrefixMapper {
356
    /** Get preferred prefix for namespace */
357
    String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix);
358
}
359

360
/**
361
 * SPI for policy logging integration
362
 */
363
public interface LoggingProvider {
364
    /** Get logger for policy subsystem */
365
    PolicyLogger getLogger(Class<?> componentClass);
366
}
367
```
368

369
### JAX-WS Policy Integration
370

371
Integration between policy framework and JAX-WS runtime for feature configuration.
372

373
```java { .api }
374
/**
375
 * SPI for configuring WebServiceFeatures from policy
376
 */
377
package com.sun.xml.ws.policy.jaxws.spi;
378
public interface PolicyFeatureConfigurator {
379
    /** Get supported assertion namespaces */
380
    Collection<QName> getSupportedAssertions();
381
    
382
    /** Configure features from policy map */
383
    Collection<WebServiceFeature> getFeatures(PolicyMapKey key, PolicyMap policyMap) throws PolicyException;
384
}
385

386
/**
387
 * SPI for configuring policy map from external sources
388
 */
389
public interface PolicyMapConfigurator {
390
    /** Update policy map with external policies */
391
    Collection<PolicySubject> update(PolicyMap policyMap, SEIModel model, WSBinding wsBinding) throws PolicyException;
392
}
393
```
394

395
**Usage Examples:**
396

397
```java
398
import com.sun.xml.ws.policy.*;
399
import com.sun.xml.ws.policy.sourcemodel.*;
400
import com.sun.xml.ws.policy.spi.*;
401

402
// Create simple policy assertion
403
public class MyCustomAssertion extends SimpleAssertion {
404
    public static final QName ASSERTION_NAME = new QName("http://example.com/policy", "MyAssertion");
405
    
406
    public MyCustomAssertion(AssertionData data, Collection<PolicyAssertion> parameters) {
407
        super(data, parameters);
408
    }
409
    
410
    public QName getName() {
411
        return ASSERTION_NAME;
412
    }
413
}
414

415
// Custom assertion creator
416
public class MyAssertionCreator implements PolicyAssertionCreator {
417
    public String[] getSupportedDomainNamespaceURIs() {
418
        return new String[] { "http://example.com/policy" };
419
    }
420
    
421
    public PolicyAssertion createAssertion(AssertionData data, 
422
                                         Collection<PolicyAssertion> assertionParameters, 
423
                                         Policy nestedPolicy) throws AssertionCreationException {
424
        if (MyCustomAssertion.ASSERTION_NAME.equals(data.getName())) {
425
            return new MyCustomAssertion(data, assertionParameters);
426
        }
427
        return null;
428
    }
429
}
430

431
// Policy creation and processing
432
PolicySourceModel sourceModel = PolicySourceModel.createPolicySourceModel(
433
    new QName("http://example.com", "MyPolicy"), "policy1");
434

435
ModelNode rootNode = sourceModel.getRootNode();
436
ModelNode assertionNode = rootNode.addChild(NodeType.ASSERTION, 
437
    AssertionData.createAssertionData(MyCustomAssertion.ASSERTION_NAME));
438

439
// Create policy from source model
440
Policy policy = Policy.createPolicy(sourceModel);
441

442
// Policy map usage
443
PolicyMap policyMap = new PolicyMap();
444
PolicyMapKey endpointKey = PolicyMapKey.createEndpointScopeKey(
445
    new QName("http://example.com", "MyService"),
446
    new QName("http://example.com", "MyPort"));
447

448
Policy effectivePolicy = policyMap.getEndpointEffectivePolicy(endpointKey);
449

450
// Policy merging
451
Policy policy1 = Policy.createPolicy(sourceModel1);
452
Policy policy2 = Policy.createPolicy(sourceModel2);
453
Policy mergedPolicy = policy1.merge(policy2);
454

455
// Feature configuration from policy
456
public class MyFeatureConfigurator implements PolicyFeatureConfigurator {
457
    public Collection<QName> getSupportedAssertions() {
458
        return Arrays.asList(MyCustomAssertion.ASSERTION_NAME);
459
    }
460
    
461
    public Collection<WebServiceFeature> getFeatures(PolicyMapKey key, PolicyMap policyMap) 
462
            throws PolicyException {
463
        Policy policy = policyMap.getEndpointEffectivePolicy(key);
464
        
465
        List<WebServiceFeature> features = new ArrayList<>();
466
        for (AssertionSet alternative : policy) {
467
            for (PolicyAssertion assertion : alternative) {
468
                if (MyCustomAssertion.ASSERTION_NAME.equals(assertion.getName())) {
469
                    features.add(new MyCustomFeature());
470
                }
471
            }
472
        }
473
        return features;
474
    }
475
}
476
```