1 /* 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.ws.soap; 27 28 import javax.xml.ws.WebServiceFeature; 29 import javax.xml.ws.Endpoint; 30 import javax.xml.ws.Service; 31 32 /** 33 * AddressingFeature represents the use of WS-Addressing with either 34 * the SOAP 1.1/HTTP or SOAP 1.2/HTTP binding. Using this feature 35 * with any other binding is undefined. 36 * <p> 37 * This feature can be used during the creation of SEI proxy, and 38 * {@link javax.xml.ws.Dispatch} instances on the client side and {@link Endpoint} 39 * instances on the server side. This feature cannot be used for {@link Service} 40 * instance creation on the client side. 41 * <p> 42 * The following describes the effects of this feature with respect 43 * to be enabled or disabled: 44 * <ul> 45 * <li> ENABLED: In this Mode, WS-Addressing will be enabled. It means 46 * the endpoint supports WS-Addressing but does not require its use. 47 * A sender could send messages with WS-Addressing headers or without 48 * WS-Addressing headers. But a receiver MUST consume both types of 49 * messages. 50 * <li> DISABLED: In this Mode, WS-Addressing will be disabled. 51 * At runtime, WS-Addressing headers MUST NOT be used by a sender or 52 * receiver. 53 * </ul> 54 * <p> 55 * If the feature is enabled, the {@code required} property determines 56 * whether the endpoint requires WS-Addressing. If it is set true, 57 * WS-Addressing headers MUST be present on incoming and outgoing messages. 58 * By default the {@code required} property is {@code false}. 59 * 60 * <p> 61 * If the web service developer has not explicitly enabled this feature, 62 * WSDL's wsam:Addressing policy assertion is used to find 63 * the use of WS-Addressing. By using the feature explicitly, an application 64 * overrides WSDL's indication of the use of WS-Addressing. In some cases, 65 * this is really required. For example, if an application has implemented 66 * WS-Addressing itself, it can use this feature to disable addressing. That 67 * means a JAX-WS implementation doesn't consume or produce WS-Addressing 68 * headers. 69 * 70 * <p> 71 * If addressing is enabled, a corresponding wsam:Addressing policy assertion 72 * must be generated in the WSDL as per 73 * <a href="http://www.w3.org/TR/ws-addr-metadata/#wspolicyassertions"> 74 * 3.1 WS-Policy Assertions</a> 75 * 76 * <p> 77 * <b>Example 1: </b>Possible Policy Assertion in the generated WSDL for 78 * {@code @Addressing} 79 * <pre> {@code 80 * <wsam:Addressing wsp:Optional="true"> 81 * <wsp:Policy/> 82 * </wsam:Addressing> } 83 * </pre> 84 * 85 * <p> 86 * <b>Example 2: </b>Possible Policy Assertion in the generated WSDL for 87 * {@code @Addressing(required=true)} 88 * <pre> {@code 89 * <wsam:Addressing> 90 * <wsp:Policy/> 91 * </wsam:Addressing> } 92 * </pre> 93 * 94 * <p> 95 * <b>Example 3: </b>Possible Policy Assertion in the generated WSDL for 96 * {@code @Addressing(required=true, responses=Responses.ANONYMOUS)} 97 * <pre> {@code 98 * <wsam:Addressing> 99 * <wsp:Policy> 100 * <wsam:AnonymousResponses/> 101 * </wsp:Policy> 102 * </wsam:Addressing> } 103 * </pre> 104 * 105 * <p> 106 * See <a href="http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/"> 107 * Web Services Addressing - Core</a>, 108 * <a href="http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/"> 109 * Web Services Addressing 1.0 - SOAP Binding</a>, 110 * and <a href="http://www.w3.org/TR/ws-addr-metadata/"> 111 * Web Services Addressing 1.0 - Metadata</a> 112 * for more information on WS-Addressing. 113 * 114 * @see Addressing 115 * @since 1.6, JAX-WS 2.1 116 */ 117 118 public final class AddressingFeature extends WebServiceFeature { 119 /** 120 * Constant value identifying the AddressingFeature 121 */ 122 public static final String ID = "http://www.w3.org/2005/08/addressing/module"; 123 124 /** 125 * If addressing is enabled, this property determines whether the endpoint 126 * requires WS-Addressing. If required is true, WS-Addressing headers MUST 127 * be present on incoming and outgoing messages. 128 */ 129 // should be private final, keeping original modifier due to backwards compatibility 130 protected boolean required; 131 132 /** 133 * If addressing is enabled, this property determines if endpoint requires 134 * the use of only anonymous responses, or only non-anonymous responses, or all. 135 * 136 * <p> 137 * {@link Responses#ALL} supports all response types and this is the default 138 * value. 139 * 140 * <p> 141 * {@link Responses#ANONYMOUS} requires the use of only anonymous 142 * responses. It will result into wsam:AnonymousResponses nested assertion 143 * as specified in 144 * <a href="http://www.w3.org/TR/ws-addr-metadata/#wspolicyanonresponses"> 145 * 3.1.2 AnonymousResponses Assertion</a> in the generated WSDL. 146 * 147 * <p> 148 * {@link Responses#NON_ANONYMOUS} requires the use of only non-anonymous 149 * responses. It will result into 150 * wsam:NonAnonymousResponses nested assertion as specified in 151 * <a href="http://www.w3.org/TR/ws-addr-metadata/#wspolicynonanonresponses"> 152 * 3.1.3 NonAnonymousResponses Assertion</a> in the generated WSDL. 153 * 154 * @since 1.7, JAX-WS 2.2 155 */ 156 public enum Responses { 157 /** 158 * Specifies the use of only anonymous 159 * responses. It will result into wsam:AnonymousResponses nested assertion 160 * as specified in 161 * <a href="http://www.w3.org/TR/ws-addr-metadata/#wspolicyanonresponses"> 162 * 3.1.2 AnonymousResponses Assertion</a> in the generated WSDL. 163 */ 164 ANONYMOUS, 165 166 /** 167 * Specifies the use of only non-anonymous 168 * responses. It will result into 169 * wsam:NonAnonymousResponses nested assertion as specified in 170 * <a href="http://www.w3.org/TR/ws-addr-metadata/#wspolicynonanonresponses"> 171 * 3.1.3 NonAnonymousResponses Assertion</a> in the generated WSDL. 172 */ 173 NON_ANONYMOUS, 174 175 /** 176 * Supports all response types and this is the default 177 */ 178 ALL 179 } 180 181 private final Responses responses; 182 183 /** 184 * Creates and configures an {@code AddressingFeature} with the 185 * use of addressing requirements. The created feature enables 186 * ws-addressing i.e. supports ws-addressing but doesn't require 187 * its use. It is also configured to accept all the response types. 188 */ 189 public AddressingFeature() { 190 this(true, false, Responses.ALL); 191 } 192 193 /** 194 * Creates and configures an {@code AddressingFeature} with the 195 * use of addressing requirements. If {@code enabled} is true, 196 * it enables ws-addressing i.e. supports ws-addressing but doesn't 197 * require its use. It also configures to accept all the response types. 198 * 199 * @param enabled true enables ws-addressing i.e.ws-addressing 200 * is supported but doesn't require its use 201 */ 202 public AddressingFeature(boolean enabled) { 203 this(enabled, false, Responses.ALL); 204 } 205 206 /** 207 * Creates and configures an {@code AddressingFeature} with the 208 * use of addressing requirements. If {@code enabled} and 209 * {@code required} are true, it enables ws-addressing and 210 * requires its use. It also configures to accept all the response types. 211 * 212 * @param enabled true enables ws-addressing i.e.ws-addressing 213 * is supported but doesn't require its use 214 * @param required true means requires the use of ws-addressing . 215 */ 216 public AddressingFeature(boolean enabled, boolean required) { 217 this(enabled, required, Responses.ALL); 218 } 219 220 /** 221 * Creates and configures an {@code AddressingFeature} with the 222 * use of addressing requirements. If {@code enabled} and 223 * {@code required} are true, it enables ws-addressing and 224 * requires its use. Also, the response types can be configured using 225 * {@code responses} parameter. 226 * 227 * @param enabled true enables ws-addressing i.e.ws-addressing 228 * is supported but doesn't require its use 229 * @param required true means requires the use of ws-addressing . 230 * @param responses specifies what type of responses are required 231 * 232 * @since 1.7, JAX-WS 2.2 233 */ 234 public AddressingFeature(boolean enabled, boolean required, Responses responses) { 235 this.enabled = enabled; 236 this.required = required; 237 this.responses = responses; 238 } 239 240 /** 241 * {@inheritDoc} 242 */ 243 public String getID() { 244 return ID; 245 } 246 247 /** 248 * If addressing is enabled, this property determines whether the endpoint 249 * requires WS-Addressing. If required is true, WS-Addressing headers MUST 250 * be present on incoming and outgoing messages. 251 * 252 * @return the current required value 253 */ 254 public boolean isRequired() { 255 return required; 256 } 257 258 /** 259 * If addressing is enabled, this property determines whether endpoint 260 * requires the use of anonymous responses, or non-anonymous responses, 261 * or all responses. 262 * 263 * @return {@link Responses#ALL} when endpoint supports all types of 264 * responses, 265 * {@link Responses#ANONYMOUS} when endpoint requires the use of 266 * only anonymous responses, 267 * {@link Responses#NON_ANONYMOUS} when endpoint requires the use 268 * of only non-anonymous responses 269 * 270 * @since 1.7, JAX-WS 2.2 271 */ 272 public Responses getResponses() { 273 return responses; 274 } 275 276 }