001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws.soap;
007:
008: import javax.xml.ws.Action;
009: import javax.xml.ws.BindingProvider;
010: import javax.xml.ws.FaultAction;
011: import javax.xml.ws.WebServiceFeature;
012: import javax.xml.ws.WebServiceException;
013: import javax.xml.ws.spi.Provider;
014:
015: /**
016: * This feature represents the use of WS-Addressing with either
017: * the SOAP 1.1/HTTP or SOAP 1.2/HTTP binding. Using this feature
018: * with any other binding is NOT required.
019: * <p>
020: * Enabling this feature on the client will cause the JAX-WS runtime
021: * to include WS-Addressing headers in SOAP messages.
022: * <p>
023: * If the web service developer has not explicitly enabled this feature,
024: * it MAY be automatically enabled if the associated WSDL enables
025: * WS-Addressing with an implementation recognized WSDL extension element.
026: * However, in this version of JAX-WS, there is no standard WSDL
027: * extension that a client can rely on to automatically enable WS-Addressing,
028: * nor is there a standard default value specified for WS-Addressing
029: * <code>Action</code> headers.
030: * <p>
031: * To write a portable endpoint and its corresponding client with this
032: * version of JAX-WS, an endpoint MUST explicitly specify what WS-Addressing
033: * <code>Actions</code> are to be used via the {@link Action} and
034: * {@link FaultAction} annotations. The client MUST explicitly enable
035: * addresssing via this <code>AddressingFeature</code>, and for each invocation,
036: * the client MUST explicitly set the {@link BindingProvider#SOAPACTION_URI_PROPERTY}.
037: * After the W3C WG on WS-Addressing has specified how the use of WS-Addressing
038: * is specified in the WSDL, and what the default value must be for Action headers,
039: * a future version of JAX-WS will remove these requirements.
040: * <p>
041: * See {@link javax.xml.ws.RespectBindingFeature} for more information
042: * on required WSDL extensions.
043: * <p>
044: * The following describes the effects of this feature with respect
045: * to be enabled or disabled:
046: * <ul>
047: * <li> ENABLED: In this Mode, WS-Addressing will be enabled.
048: * At runtime, WS-Addressing headers
049: * MUST be consumed by the receiver and produced by the
050: * sender even if the WSDL declares otherwise. The
051: * mustUnderstand="0" attribute MUST be used on the WS-Addressing
052: * headers.
053: * <li> DISABLED: In this Mode, WS-Addressing will be disabled
054: * even if an associated WSDL specifies otherwise. At runtime,
055: * WS-Addressing headers MUST NOT be used. WS-Addressing may be explicitly
056: * disabled to prevent a JAX-WS implementation from consuming and producing
057: * WS-Addressing headers. If an application
058: * has implemented WS-Addressing itself, it MUST explicitly disable this feature.
059: * Not doing so may break compatibility with future versions of JAX-WS.
060: * </ul>
061: * <p>
062: * The {@link #required} property can be used to
063: * specify if WS-Addressing headers MUST be present
064: * on incoming messages. This property only has meaning when used on the
065: * endpoint and has no affect when used on the client.
066: * By default the
067: * <code>required</code> property is <code>false</code>.
068: <p>
069:
070: * See <a href="http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/">Web Services Addressing - Core</a>
071: * and <a href="http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/">Web Services Addressing 1.0 - SOAP Binding</a>
072: * for more information on WS-Addressing.
073: *
074: * @since JAX-WS 2.1
075: */
076: public final class AddressingFeature extends WebServiceFeature {
077: /**
078: * Constant value identifying the AddressingFeature
079: */
080: public static final String ID = "http://www.w3.org/2005/08/addressing/module";
081:
082: /**
083: * Property for the <code>required</code> feature parameter. When WS-Addressing
084: * is enabled, the value of this property will be used
085: * to specify if WS-Addressing headers MUST be present on incoming messages. This
086: * property only has meaning on the endpoint and has no
087: * affect when used on the client.
088: */
089: protected boolean required = false;
090:
091: /**
092: * Create an <code>AddressingFeature</code>.
093: * The instance created will be enabled.
094: */
095: public AddressingFeature() {
096: this .enabled = true;
097: }
098:
099: /**
100: * Create an <code>AddressingFeature</code>
101: *
102: * @param enabled specifies whether this feature should
103: * be enabled or not.
104: */
105: public AddressingFeature(boolean enabled) {
106: this .enabled = enabled;
107: }
108:
109: /**
110: * Create an <code>AddressingFeature</code>
111: *
112: * @param enabled specifies whether this feature should
113: * be enabled or not.
114: * @param required specifies whether
115: * WS-Addressing headers MUST be present on incoming messages. This property
116: * only has meaning on the endpoint and has no affect when
117: * used on the client.
118: */
119: public AddressingFeature(boolean enabled, boolean required) {
120: this .enabled = enabled;
121: this .required = required;
122: }
123:
124: /**
125: * {@inheritDoc}
126: */
127: public String getID() {
128: return ID;
129: }
130:
131: /**
132: * Gets the boolean value used to determine if WS-Addressing
133: * headers MUST be present on incoming messages. This property
134: * only has meaning on the endpoint, and has no affect
135: * when used on the client.
136: *
137: * @return the current required value
138: */
139: public boolean isRequired() {
140: return required;
141: }
142: }
|