< prev index next >

src/java.xml.ws/share/classes/javax/xml/ws/wsaddressing/W3CEndpointReferenceBuilder.java

Print this page


   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;
< prev index next >