1 /* 2 * Copyright (c) 2005, 2012, 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.wsaddressing; 27 28 29 import org.w3c.dom.Element; 30 31 import java.util.ArrayList; 32 import java.util.List; 33 import java.util.Map; 34 import java.util.HashMap; 35 import javax.xml.namespace.QName; 36 import javax.xml.ws.WebServiceException; 37 import javax.xml.ws.spi.Provider; 38 39 40 /** 41 * This class is used to build <code>W3CEndpointReference</code> 42 * instances. The intended use of this clsss is for 43 * an application component, for example a factory component, 44 * to create an <code>W3CEndpointReference</code> for a 45 * web service endpoint published by the same 46 * Java EE application. It can also be used to create 47 * <code>W3CEndpointReferences</code> for an Java SE based 48 * endpoint by providing the <code>address</code> property. 49 * <p> 50 * When creating a <code>W3CEndpointReference</code> for an 51 * endpoint that is not published by the same Java EE application, 52 * the <code>address</code> property MUST be specified. 53 * <p> 54 * When creating a <code>W3CEndpointReference</code> for an endpoint 55 * published by the same Java EE application, the <code>address</code> 56 * property MAY be <code>null</code> but then the <code>serviceName</code> 57 * and <code>endpointName</code> MUST specify an endpoint published by 58 * the same Java EE application. 59 * <p> 60 * When the <code>wsdlDocumentLocation</code> is specified it MUST refer 61 * to a valid WSDL document and the <code>serviceName</code> and 62 * <code>endpointName</code> (if specified) MUST match a service and port 63 * in the WSDL document. 64 * 65 * @since 1.6, JAX-WS 2.1 66 */ 67 public final class W3CEndpointReferenceBuilder { 68 /** 69 * Creates a new <code>W3CEndpointReferenceBuilder</code> instance. 70 */ 71 public W3CEndpointReferenceBuilder() { 72 referenceParameters = new ArrayList<Element>(); 73 metadata = new ArrayList<Element>(); 74 attributes = new HashMap<QName, String>(); 75 elements = new ArrayList<Element>(); 76 } 77 78 /** 79 * Sets the <code>address</code> to the 80 * <code>W3CEndpointReference</code> instance's 81 * <code>wsa:Address</code>. 82 * <p> 83 * The <code>address</code> MUST be set to a non-<code>null</code> 84 * value when building a <code>W3CEndpointReference</code> for a 85 * web service endpoint that is not published by the same 86 * Java EE application or when running on Java SE. 87 * 88 * @param address The address of the endpoint to be targeted 89 * by the returned <code>W3CEndpointReference</code>. 90 * 91 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 92 * the <code>address</code> set to the <code>wsa:Address</code>. 93 */ 94 public W3CEndpointReferenceBuilder address(String address) { 95 this.address = address; 96 return this; 97 } 98 99 /** 100 * Sets the <code>interfaceName</code> as the 101 * <code>wsam:InterfaceName</code> element in the 102 * <code>wsa:Metadata</code> element. 103 * 104 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 105 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 106 * 107 * @param interfaceName The port type name of the endpoint to be targeted 108 * by the returned <code>W3CEndpointReference</code>. 109 * 110 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 111 * the <code>interfaceName</code> as <code>wsam:InterfaceName</code> 112 * element added to the <code>wsa:Metadata</code> element 113 * @since 1.7 114 */ 115 public W3CEndpointReferenceBuilder interfaceName(QName interfaceName) { 116 this.interfaceName = interfaceName; 117 return this; 118 } 119 120 /** 121 * Sets the <code>serviceName</code> as the 122 * <code>wsam:ServiceName</code> element in the 123 * <code>wsa:Metadata</code> element. 124 * 125 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 126 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 127 * 128 * @param serviceName The service name of the endpoint to be targeted 129 * by the returned <code>W3CEndpointReference</code>. This property 130 * may also be used with the <code>endpointName</code> (portName) 131 * property to lookup the <code>address</code> of a web service 132 * endpoint that is published by the same Java EE application. 133 * 134 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 135 * the <code>serviceName</code> as <code>wsam:ServiceName</code> 136 * element added to the <code>wsa:Metadata</code> element 137 * 138 */ 139 public W3CEndpointReferenceBuilder serviceName(QName serviceName) { 140 this.serviceName = serviceName; 141 return this; 142 } 143 144 /** 145 * Sets the <code>endpointName</code> as 146 * <code>wsam:ServiceName/@EndpointName</code> in the 147 * <code>wsa:Metadata</code> element. This method can only be called 148 * after the {@link #serviceName} method has been called. 149 * <p> 150 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 151 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 152 * 153 * @param endpointName The name of the endpoint to be targeted 154 * by the returned <code>W3CEndpointReference</code>. The 155 * <code>endpointName</code> (portName) property may also be 156 * used with the <code>serviceName</code> property to lookup 157 * the <code>address</code> of a web service 158 * endpoint published by the same Java EE application. 159 * 160 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 161 * the <code>endpointName</code> as 162 * <code>wsam:ServiceName/@EndpointName</code> in the 163 * <code>wsa:Metadata</code> element. 164 * 165 * @throws IllegalStateException, if the <code>serviceName</code> 166 * has not been set. 167 * @throws IllegalArgumentException, if the <code>endpointName</code>'s 168 * Namespace URI doesn't match <code>serviceName</code>'s Namespace URI 169 * 170 */ 171 public W3CEndpointReferenceBuilder endpointName(QName endpointName) { 172 if (serviceName == null) { 173 throw new IllegalStateException("The W3CEndpointReferenceBuilder's serviceName must be set before setting the endpointName: "+endpointName); 174 } 175 176 this.endpointName = endpointName; 177 return this; 178 } 179 180 /** 181 * Sets the <code>wsdlDocumentLocation</code> that will be referenced 182 * as <code>wsa:Metadata/@wsdli:wsdlLocation</code>. The namespace name 183 * for the wsdli:wsdlLocation's value can be taken from the WSDL itself. 184 * 185 * <p> 186 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 187 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 188 * 189 * @param wsdlDocumentLocation The location of the WSDL document to 190 * be referenced in the <code>wsa:Metadata</code> of the 191 * <code>W3CEndpointReference</code>. 192 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 193 * the <code>wsdlDocumentLocation</code> that is to be referenced. 194 */ 195 public W3CEndpointReferenceBuilder wsdlDocumentLocation(String wsdlDocumentLocation) { 196 this.wsdlDocumentLocation = wsdlDocumentLocation; 197 return this; 198 } 199 200 /** 201 * Adds the <code>referenceParameter</code> to the 202 * <code>W3CEndpointReference</code> instance 203 * <code>wsa:ReferenceParameters</code> element. 204 * 205 * @param referenceParameter The element to be added to the 206 * <code>wsa:ReferenceParameters</code> element. 207 * 208 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 209 * the <code>referenceParameter</code> added to the 210 * <code>wsa:ReferenceParameters</code> element. 211 * 212 * @throws java.lang.IllegalArgumentException if <code>referenceParameter</code> 213 * is <code>null</code>. 214 */ 215 public W3CEndpointReferenceBuilder referenceParameter(Element referenceParameter) { 216 if (referenceParameter == null) 217 throw new java.lang.IllegalArgumentException("The referenceParameter cannot be null."); 218 referenceParameters.add(referenceParameter); 219 return this; 220 } 221 222 /** 223 * Adds the <code>metadataElement</code> to the 224 * <code>W3CEndpointReference</code> instance's 225 * <code>wsa:Metadata</code> element. 226 * 227 * @param metadataElement The element to be added to the 228 * <code>wsa:Metadata</code> element. 229 * 230 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 231 * the <code>metadataElement</code> added to the 232 * <code>wsa:Metadata</code> element. 233 * 234 * @throws java.lang.IllegalArgumentException if <code>metadataElement</code> 235 * is <code>null</code>. 236 */ 237 public W3CEndpointReferenceBuilder metadata(Element metadataElement) { 238 if (metadataElement == null) 239 throw new java.lang.IllegalArgumentException("The metadataElement cannot be null."); 240 metadata.add(metadataElement); 241 return this; 242 } 243 244 /** 245 * Adds an extension element to the 246 * <code>W3CEndpointReference</code> instance's 247 * <code>wsa:EndpointReference</code> element. 248 * 249 * @param element The extension element to be added to the 250 * <code>W3CEndpointReference</code> 251 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 252 * the extension <code>element</code> added to the 253 * <code>W3CEndpointReference</code> instance. 254 * @throws java.lang.IllegalArgumentException if <code>element</code> 255 * is <code>null</code>. 256 * 257 * @since 1.7, JAX-WS 2.2 258 */ 259 public W3CEndpointReferenceBuilder element(Element element) { 260 if (element == null) { 261 throw new IllegalArgumentException("The extension element cannot be null."); 262 } 263 elements.add(element); 264 return this; 265 } 266 267 /** 268 * Adds an extension attribute to the 269 * <code>W3CEndpointReference</code> instance's 270 * <code>wsa:EndpointReference</code> element. 271 * 272 * @param name The name of the extension attribute to be added to the 273 * <code>W3CEndpointReference</code> 274 * @param value extension attribute value 275 * @return A <code>W3CEndpointReferenceBuilder</code> instance with 276 * the extension attribute added to the <code>W3CEndpointReference</code> 277 * instance. 278 * @throws java.lang.IllegalArgumentException if <code>name</code> 279 * or <code>value</code> is <code>null</code>. 280 * 281 * @since 1.7, JAX-WS 2.2 282 */ 283 public W3CEndpointReferenceBuilder attribute(QName name, String value) { 284 if (name == null || value == null) { 285 throw new IllegalArgumentException("The extension attribute name or value cannot be null."); 286 } 287 attributes.put(name, value); 288 return this; 289 } 290 291 /** 292 * Builds a <code>W3CEndpointReference</code> from the accumulated 293 * properties set on this <code>W3CEndpointReferenceBuilder</code> 294 * instance. 295 * <p> 296 * This method can be used to create a <code>W3CEndpointReference</code> 297 * for any endpoint by specifying the <code>address</code> property along 298 * with any other desired properties. This method 299 * can also be used to create a <code>W3CEndpointReference</code> for 300 * an endpoint that is published by the same Java EE application. 301 * This method can automatically determine the <code>address</code> of 302 * an endpoint published by the same Java EE application that is identified by the 303 * <code>serviceName</code> and 304 * <code>endpointName</code> properties. If the <code>address</code> is 305 * <code>null</code> and the <code>serviceName</code> and 306 * <code>endpointName</code> 307 * do not identify an endpoint published by the same Java EE application, a 308 * <code>java.lang.IllegalStateException</code> MUST be thrown. 309 * 310 * 311 * @return <code>W3CEndpointReference</code> from the accumulated 312 * properties set on this <code>W3CEndpointReferenceBuilder</code> 313 * instance. This method never returns <code>null</code>. 314 * 315 * @throws IllegalStateException 316 * <ul> 317 * <li>If the <code>address</code>, <code>serviceName</code> and 318 * <code>endpointName</code> are all <code>null</code>. 319 * <li>If the <code>serviceName</code> service is <code>null</code> and the 320 * <code>endpointName</code> is NOT <code>null</code>. 321 * <li>If the <code>address</code> property is <code>null</code> and 322 * the <code>serviceName</code> and <code>endpointName</code> do not 323 * specify a valid endpoint published by the same Java EE 324 * application. 325 * <li>If the <code>serviceName</code> is NOT <code>null</code> 326 * and is not present in the specified WSDL. 327 * <li>If the <code>endpointName</code> port is not <code>null</code> and it 328 * is not present in <code>serviceName</code> service in the WSDL. 329 * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code> 330 * and does not represent a valid WSDL. 331 * </ul> 332 * @throws WebServiceException If an error occurs while creating the 333 * <code>W3CEndpointReference</code>. 334 * 335 */ 336 public W3CEndpointReference build() { 337 if (elements.isEmpty() && attributes.isEmpty() && interfaceName == null) { 338 // 2.1 API 339 return Provider.provider().createW3CEndpointReference(address, 340 serviceName, endpointName, metadata, wsdlDocumentLocation, 341 referenceParameters); 342 } 343 return Provider.provider().createW3CEndpointReference(address, 344 interfaceName, serviceName, endpointName, metadata, wsdlDocumentLocation, 345 referenceParameters, elements, attributes); 346 } 347 348 private String address; 349 private List<Element> referenceParameters; 350 private List<Element> metadata; 351 private QName interfaceName; 352 private QName serviceName; 353 private QName endpointName; | 1 /* 2 * Copyright (c) 2005, 2015, 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.wsaddressing; 27 28 29 import org.w3c.dom.Element; 30 31 import java.util.ArrayList; 32 import java.util.List; 33 import java.util.Map; 34 import java.util.HashMap; 35 import javax.xml.namespace.QName; 36 import javax.xml.ws.WebServiceException; 37 import javax.xml.ws.spi.Provider; 38 39 40 /** 41 * This class is used to build {@code W3CEndpointReference} 42 * instances. The intended use of this clsss is for 43 * an application component, for example a factory component, 44 * to create an {@code W3CEndpointReference} for a 45 * web service endpoint published by the same 46 * Java EE application. It can also be used to create 47 * {@code W3CEndpointReferences} for an Java SE based 48 * endpoint by providing the {@code address} property. 49 * <p> 50 * When creating a {@code W3CEndpointReference} for an 51 * endpoint that is not published by the same Java EE application, 52 * the {@code address} property MUST be specified. 53 * <p> 54 * When creating a {@code W3CEndpointReference} for an endpoint 55 * published by the same Java EE application, the {@code address} 56 * property MAY be {@code null} but then the {@code serviceName} 57 * and {@code endpointName} MUST specify an endpoint published by 58 * the same Java EE application. 59 * <p> 60 * When the {@code wsdlDocumentLocation} is specified it MUST refer 61 * to a valid WSDL document and the {@code serviceName} and 62 * {@code endpointName} (if specified) MUST match a service and port 63 * in the WSDL document. 64 * 65 * @since 1.6, JAX-WS 2.1 66 */ 67 public final class W3CEndpointReferenceBuilder { 68 /** 69 * Creates a new {@code W3CEndpointReferenceBuilder} instance. 70 */ 71 public W3CEndpointReferenceBuilder() { 72 referenceParameters = new ArrayList<Element>(); 73 metadata = new ArrayList<Element>(); 74 attributes = new HashMap<QName, String>(); 75 elements = new ArrayList<Element>(); 76 } 77 78 /** 79 * Sets the {@code address} to the 80 * {@code W3CEndpointReference} instance's 81 * {@code wsa:Address}. 82 * <p> 83 * The {@code address} MUST be set to a non-{@code null} 84 * value when building a {@code W3CEndpointReference} for a 85 * web service endpoint that is not published by the same 86 * Java EE application or when running on Java SE. 87 * 88 * @param address The address of the endpoint to be targeted 89 * by the returned {@code W3CEndpointReference}. 90 * 91 * @return A {@code W3CEndpointReferenceBuilder} instance with 92 * the {@code address} set to the {@code wsa:Address}. 93 */ 94 public W3CEndpointReferenceBuilder address(String address) { 95 this.address = address; 96 return this; 97 } 98 99 /** 100 * Sets the {@code interfaceName} as the 101 * {@code wsam:InterfaceName} element in the 102 * {@code wsa:Metadata} element. 103 * 104 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 105 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 106 * 107 * @param interfaceName The port type name of the endpoint to be targeted 108 * by the returned {@code W3CEndpointReference}. 109 * 110 * @return A {@code W3CEndpointReferenceBuilder} instance with 111 * the {@code interfaceName} as {@code wsam:InterfaceName} 112 * element added to the {@code wsa:Metadata} element 113 * @since 1.7 114 */ 115 public W3CEndpointReferenceBuilder interfaceName(QName interfaceName) { 116 this.interfaceName = interfaceName; 117 return this; 118 } 119 120 /** 121 * Sets the {@code serviceName} as the 122 * {@code wsam:ServiceName} element in the 123 * {@code wsa:Metadata} element. 124 * 125 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 126 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 127 * 128 * @param serviceName The service name of the endpoint to be targeted 129 * by the returned {@code W3CEndpointReference}. This property 130 * may also be used with the {@code endpointName} (portName) 131 * property to lookup the {@code address} of a web service 132 * endpoint that is published by the same Java EE application. 133 * 134 * @return A {@code W3CEndpointReferenceBuilder} instance with 135 * the {@code serviceName} as {@code wsam:ServiceName} 136 * element added to the {@code wsa:Metadata} element 137 * 138 */ 139 public W3CEndpointReferenceBuilder serviceName(QName serviceName) { 140 this.serviceName = serviceName; 141 return this; 142 } 143 144 /** 145 * Sets the {@code endpointName} as 146 * {@code wsam:ServiceName/@EndpointName} in the 147 * {@code wsa:Metadata} element. This method can only be called 148 * after the {@link #serviceName} method has been called. 149 * <p> 150 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 151 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 152 * 153 * @param endpointName The name of the endpoint to be targeted 154 * by the returned {@code W3CEndpointReference}. The 155 * {@code endpointName} (portName) property may also be 156 * used with the {@code serviceName} property to lookup 157 * the {@code address} of a web service 158 * endpoint published by the same Java EE application. 159 * 160 * @return A {@code W3CEndpointReferenceBuilder} instance with 161 * the {@code endpointName} as 162 * {@code wsam:ServiceName/@EndpointName} in the 163 * {@code wsa:Metadata} element. 164 * 165 * @throws java.lang.IllegalStateException if the {@code serviceName} 166 * has not been set 167 * 168 * @throws java.lang.IllegalArgumentException if the {@code endpointName}'s 169 * Namespace URI doesn't match {@code serviceName}'s Namespace URI 170 * 171 */ 172 public W3CEndpointReferenceBuilder endpointName(QName endpointName) { 173 if (serviceName == null) { 174 throw new IllegalStateException("The W3CEndpointReferenceBuilder's serviceName must be set before setting the endpointName: "+endpointName); 175 } 176 177 this.endpointName = endpointName; 178 return this; 179 } 180 181 /** 182 * Sets the {@code wsdlDocumentLocation} that will be referenced 183 * as {@code wsa:Metadata/@wsdli:wsdlLocation}. The namespace name 184 * for the wsdli:wsdlLocation's value can be taken from the WSDL itself. 185 * 186 * <p> 187 * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr"> 188 * 2.1 Referencing WSDL Metadata from an EPR</a> for more details. 189 * 190 * @param wsdlDocumentLocation The location of the WSDL document to 191 * be referenced in the {@code wsa:Metadata} of the 192 * {@code W3CEndpointReference}. 193 * @return A {@code W3CEndpointReferenceBuilder} instance with 194 * the {@code wsdlDocumentLocation} that is to be referenced. 195 */ 196 public W3CEndpointReferenceBuilder wsdlDocumentLocation(String wsdlDocumentLocation) { 197 this.wsdlDocumentLocation = wsdlDocumentLocation; 198 return this; 199 } 200 201 /** 202 * Adds the {@code referenceParameter} to the 203 * {@code W3CEndpointReference} instance 204 * {@code wsa:ReferenceParameters} element. 205 * 206 * @param referenceParameter The element to be added to the 207 * {@code wsa:ReferenceParameters} element. 208 * 209 * @return A {@code W3CEndpointReferenceBuilder} instance with 210 * the {@code referenceParameter} added to the 211 * {@code wsa:ReferenceParameters} element. 212 * 213 * @throws java.lang.IllegalArgumentException if {@code referenceParameter} 214 * is {@code null}. 215 */ 216 public W3CEndpointReferenceBuilder referenceParameter(Element referenceParameter) { 217 if (referenceParameter == null) 218 throw new java.lang.IllegalArgumentException("The referenceParameter cannot be null."); 219 referenceParameters.add(referenceParameter); 220 return this; 221 } 222 223 /** 224 * Adds the {@code metadataElement} to the 225 * {@code W3CEndpointReference} instance's 226 * {@code wsa:Metadata} element. 227 * 228 * @param metadataElement The element to be added to the 229 * {@code wsa:Metadata} element. 230 * 231 * @return A {@code W3CEndpointReferenceBuilder} instance with 232 * the {@code metadataElement} added to the 233 * {@code wsa:Metadata} element. 234 * 235 * @throws java.lang.IllegalArgumentException if {@code metadataElement} 236 * is {@code null}. 237 */ 238 public W3CEndpointReferenceBuilder metadata(Element metadataElement) { 239 if (metadataElement == null) 240 throw new java.lang.IllegalArgumentException("The metadataElement cannot be null."); 241 metadata.add(metadataElement); 242 return this; 243 } 244 245 /** 246 * Adds an extension element to the 247 * {@code W3CEndpointReference} instance's 248 * {@code wsa:EndpointReference} element. 249 * 250 * @param element The extension element to be added to the 251 * {@code W3CEndpointReference} 252 * @return A {@code W3CEndpointReferenceBuilder} instance with 253 * the extension {@code element} added to the 254 * {@code W3CEndpointReference} instance. 255 * @throws java.lang.IllegalArgumentException if {@code element} 256 * is {@code null}. 257 * 258 * @since 1.7, JAX-WS 2.2 259 */ 260 public W3CEndpointReferenceBuilder element(Element element) { 261 if (element == null) { 262 throw new IllegalArgumentException("The extension element cannot be null."); 263 } 264 elements.add(element); 265 return this; 266 } 267 268 /** 269 * Adds an extension attribute to the 270 * {@code W3CEndpointReference} instance's 271 * {@code wsa:EndpointReference} element. 272 * 273 * @param name The name of the extension attribute to be added to the 274 * {@code W3CEndpointReference} 275 * @param value extension attribute value 276 * @return A {@code W3CEndpointReferenceBuilder} instance with 277 * the extension attribute added to the {@code W3CEndpointReference} 278 * instance. 279 * @throws java.lang.IllegalArgumentException if {@code name} 280 * or {@code value} is {@code null}. 281 * 282 * @since 1.7, JAX-WS 2.2 283 */ 284 public W3CEndpointReferenceBuilder attribute(QName name, String value) { 285 if (name == null || value == null) { 286 throw new IllegalArgumentException("The extension attribute name or value cannot be null."); 287 } 288 attributes.put(name, value); 289 return this; 290 } 291 292 /** 293 * Builds a {@code W3CEndpointReference} from the accumulated 294 * properties set on this {@code W3CEndpointReferenceBuilder} 295 * instance. 296 * <p> 297 * This method can be used to create a {@code W3CEndpointReference} 298 * for any endpoint by specifying the {@code address} property along 299 * with any other desired properties. This method 300 * can also be used to create a {@code W3CEndpointReference} for 301 * an endpoint that is published by the same Java EE application. 302 * This method can automatically determine the {@code address} of 303 * an endpoint published by the same Java EE application that is identified by the 304 * {@code serviceName} and 305 * {@code endpointName} properties. If the {@code address} is 306 * {@code null} and the {@code serviceName} and 307 * {@code endpointName} 308 * do not identify an endpoint published by the same Java EE application, a 309 * {@code java.lang.IllegalStateException} MUST be thrown. 310 * 311 * 312 * @return {@code W3CEndpointReference} from the accumulated 313 * properties set on this {@code W3CEndpointReferenceBuilder} 314 * instance. This method never returns {@code null}. 315 * 316 * @throws IllegalStateException 317 * <ul> 318 * <li>If the {@code address}, {@code serviceName} and 319 * {@code endpointName} are all {@code null}. 320 * <li>If the {@code serviceName} service is {@code null} and the 321 * {@code endpointName} is NOT {@code null}. 322 * <li>If the {@code address} property is {@code null} and 323 * the {@code serviceName} and {@code endpointName} do not 324 * specify a valid endpoint published by the same Java EE 325 * application. 326 * <li>If the {@code serviceName} is NOT {@code null} 327 * and is not present in the specified WSDL. 328 * <li>If the {@code endpointName} port is not {@code null} and it 329 * is not present in {@code serviceName} service in the WSDL. 330 * <li>If the {@code wsdlDocumentLocation} is NOT {@code null} 331 * and does not represent a valid WSDL. 332 * </ul> 333 * @throws WebServiceException If an error occurs while creating the 334 * {@code W3CEndpointReference}. 335 * 336 */ 337 public W3CEndpointReference build() { 338 if (elements.isEmpty() && attributes.isEmpty() && interfaceName == null) { 339 // 2.1 API 340 return Provider.provider().createW3CEndpointReference(address, 341 serviceName, endpointName, metadata, wsdlDocumentLocation, 342 referenceParameters); 343 } 344 return Provider.provider().createW3CEndpointReference(address, 345 interfaceName, serviceName, endpointName, metadata, wsdlDocumentLocation, 346 referenceParameters, elements, attributes); 347 } 348 349 private String address; 350 private List<Element> referenceParameters; 351 private List<Element> metadata; 352 private QName interfaceName; 353 private QName serviceName; 354 private QName endpointName; |