< prev index next >

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

Print this page

        

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -36,138 +36,139 @@
 import javax.xml.ws.WebServiceException;
 import javax.xml.ws.spi.Provider;
 
 
 /**
- * This class is used to build <code>W3CEndpointReference</code>
+ * This class is used to build {@code W3CEndpointReference}
  * instances. The intended use of this clsss is for
  * an application component, for example a factory component,
- * to create an <code>W3CEndpointReference</code> for a
+ * to create an {@code W3CEndpointReference} for a
  * web service endpoint published by the same
  * Java EE application. It can also be used to create
- * <code>W3CEndpointReferences</code> for an Java SE based
- * endpoint by providing the <code>address</code> property.
+ * {@code W3CEndpointReferences} for an Java SE based
+ * endpoint by providing the {@code address} property.
  * <p>
- * When creating a <code>W3CEndpointReference</code> for an
+ * When creating a {@code W3CEndpointReference} for an
  * endpoint that is not published by the same Java EE application,
- * the <code>address</code> property MUST be specified.
+ * the {@code address} property MUST be specified.
  * <p>
- * When creating a <code>W3CEndpointReference</code> for an endpoint
- * published by the same Java EE application, the <code>address</code>
- * property MAY be <code>null</code> but then the <code>serviceName</code>
- * and <code>endpointName</code> MUST specify an endpoint published by
+ * When creating a {@code W3CEndpointReference} for an endpoint
+ * published by the same Java EE application, the {@code address}
+ * property MAY be {@code null} but then the {@code serviceName}
+ * and {@code endpointName} MUST specify an endpoint published by
  * the same Java EE application.
  * <p>
- * When the <code>wsdlDocumentLocation</code> is specified it MUST refer
- * to a valid WSDL document and the <code>serviceName</code> and
- * <code>endpointName</code> (if specified) MUST match a service and port
+ * When the {@code wsdlDocumentLocation} is specified it MUST refer
+ * to a valid WSDL document and the {@code serviceName} and
+ * {@code endpointName} (if specified) MUST match a service and port
  * in the WSDL document.
  *
  * @since 1.6, JAX-WS 2.1
  */
 public final class W3CEndpointReferenceBuilder {
     /**
-     * Creates a new <code>W3CEndpointReferenceBuilder</code> instance.
+     * Creates a new {@code W3CEndpointReferenceBuilder} instance.
      */
     public W3CEndpointReferenceBuilder() {
         referenceParameters = new ArrayList<Element>();
         metadata = new ArrayList<Element>();
         attributes = new HashMap<QName, String>();
         elements = new ArrayList<Element>();
     }
 
     /**
-     * Sets the <code>address</code> to the
-     * <code>W3CEndpointReference</code> instance's
-     * <code>wsa:Address</code>.
+     * Sets the {@code address} to the
+     * {@code W3CEndpointReference} instance's
+     * {@code wsa:Address}.
      * <p>
-     * The <code>address</code> MUST be set to a non-<code>null</code>
-     * value when building a <code>W3CEndpointReference</code> for a
+     * The {@code address} MUST be set to a non-{@code null}
+     * value when building a {@code W3CEndpointReference} for a
      * web service endpoint that is not published by the same
      * Java EE application or when running on Java SE.
      *
      * @param address The address of the endpoint to be targeted
-     *      by the returned <code>W3CEndpointReference</code>.
+     *      by the returned {@code W3CEndpointReference}.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>address</code> set to the <code>wsa:Address</code>.
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code address} set to the {@code wsa:Address}.
      */
     public W3CEndpointReferenceBuilder address(String address) {
         this.address = address;
         return this;
     }
 
     /**
-     * Sets the <code>interfaceName</code> as the
-     * <code>wsam:InterfaceName</code> element in the
-     * <code>wsa:Metadata</code> element.
+     * Sets the {@code interfaceName} as the
+     * {@code wsam:InterfaceName} element in the
+     * {@code wsa:Metadata} element.
      *
      * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr">
      * 2.1 Referencing WSDL Metadata from an EPR</a> for more details.
      *
      * @param interfaceName The port type name of the endpoint to be targeted
-     *      by the returned <code>W3CEndpointReference</code>.
+     *      by the returned {@code W3CEndpointReference}.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>interfaceName</code> as <code>wsam:InterfaceName</code>
-     *   element added to the <code>wsa:Metadata</code> element
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code interfaceName} as {@code wsam:InterfaceName}
+     *   element added to the {@code wsa:Metadata} element
      * @since 1.7
      */
     public W3CEndpointReferenceBuilder interfaceName(QName interfaceName) {
         this.interfaceName = interfaceName;
         return this;
     }
 
     /**
-     * Sets the <code>serviceName</code> as the
-     * <code>wsam:ServiceName</code> element in the
-     * <code>wsa:Metadata</code> element.
+     * Sets the {@code serviceName} as the
+     * {@code wsam:ServiceName} element in the
+     * {@code wsa:Metadata} element.
      *
      * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr">
      * 2.1 Referencing WSDL Metadata from an EPR</a> for more details.
      *
      * @param serviceName The service name of the endpoint to be targeted
-     *      by the returned <code>W3CEndpointReference</code>.  This property
-     *      may also be used with the <code>endpointName</code> (portName)
-     *      property to lookup the <code>address</code> of a web service
+     *      by the returned {@code W3CEndpointReference}.  This property
+     *      may also be used with the {@code endpointName} (portName)
+     *      property to lookup the {@code address} of a web service
      *      endpoint that is published by the same Java EE application.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>serviceName</code> as <code>wsam:ServiceName</code>
-     *   element added to the <code>wsa:Metadata</code> element
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code serviceName} as {@code wsam:ServiceName}
+     *   element added to the {@code wsa:Metadata} element
      *
      */
     public W3CEndpointReferenceBuilder serviceName(QName serviceName) {
         this.serviceName = serviceName;
         return this;
     }
 
     /**
-     * Sets the <code>endpointName</code> as
-     * <code>wsam:ServiceName/@EndpointName</code> in the
-     * <code>wsa:Metadata</code> element. This method can only be called
+     * Sets the {@code endpointName} as
+     * {@code wsam:ServiceName/@EndpointName} in the
+     * {@code wsa:Metadata} element. This method can only be called
      * after the {@link #serviceName} method has been called.
      * <p>
      * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr">
      * 2.1 Referencing WSDL Metadata from an EPR</a> for more details.
      *
      * @param endpointName The name of the endpoint to be targeted
-     *      by the returned <code>W3CEndpointReference</code>. The
-     *      <code>endpointName</code> (portName) property may also be
-     *      used with the <code>serviceName</code> property to lookup
-     *      the <code>address</code> of a web service
+     *      by the returned {@code W3CEndpointReference}. The
+     *      {@code endpointName} (portName) property may also be
+     *      used with the {@code serviceName} property to lookup
+     *      the {@code address} of a web service
      *      endpoint published by the same Java EE application.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>endpointName</code> as
-     * <code>wsam:ServiceName/@EndpointName</code> in the
-     * <code>wsa:Metadata</code> element.
-     *
-     * @throws IllegalStateException, if the <code>serviceName</code>
-     * has not been set.
-     * @throws IllegalArgumentException, if the <code>endpointName</code>'s
-     * Namespace URI doesn't match <code>serviceName</code>'s Namespace URI
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code endpointName} as
+     *   {@code wsam:ServiceName/@EndpointName} in the
+     *   {@code wsa:Metadata} element.
+     *
+     * @throws java.lang.IllegalStateException if the {@code serviceName}
+     *   has not been set
+     *
+     * @throws java.lang.IllegalArgumentException if the {@code endpointName}'s
+     *   Namespace URI doesn't match {@code serviceName}'s Namespace URI
      *
      */
     public W3CEndpointReferenceBuilder endpointName(QName endpointName) {
         if (serviceName == null) {
             throw new IllegalStateException("The W3CEndpointReferenceBuilder's serviceName must be set before setting the endpointName: "+endpointName);

@@ -176,85 +177,85 @@
         this.endpointName = endpointName;
         return this;
     }
 
     /**
-     * Sets the <code>wsdlDocumentLocation</code> that will be referenced
-     * as <code>wsa:Metadata/@wsdli:wsdlLocation</code>. The namespace name
+     * Sets the {@code wsdlDocumentLocation} that will be referenced
+     * as {@code wsa:Metadata/@wsdli:wsdlLocation}. The namespace name
      * for the wsdli:wsdlLocation's value can be taken from the WSDL itself.
      *
      * <p>
      * See <a href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#refmetadatfromepr">
      * 2.1 Referencing WSDL Metadata from an EPR</a> for more details.
      *
      * @param wsdlDocumentLocation The location of the WSDL document to
-     *      be referenced in the <code>wsa:Metadata</code> of the
-     *     <code>W3CEndpointReference</code>.
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>wsdlDocumentLocation</code> that is to be referenced.
+     *      be referenced in the {@code wsa:Metadata} of the
+     *     {@code W3CEndpointReference}.
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code wsdlDocumentLocation} that is to be referenced.
      */
     public W3CEndpointReferenceBuilder wsdlDocumentLocation(String wsdlDocumentLocation) {
         this.wsdlDocumentLocation = wsdlDocumentLocation;
         return this;
     }
 
     /**
-     * Adds the <code>referenceParameter</code> to the
-     * <code>W3CEndpointReference</code> instance
-     * <code>wsa:ReferenceParameters</code> element.
+     * Adds the {@code referenceParameter} to the
+     * {@code W3CEndpointReference} instance
+     * {@code wsa:ReferenceParameters} element.
      *
      * @param referenceParameter The element to be added to the
-     *      <code>wsa:ReferenceParameters</code> element.
+     *      {@code wsa:ReferenceParameters} element.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>referenceParameter</code> added to the
-     *   <code>wsa:ReferenceParameters</code> element.
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code referenceParameter} added to the
+     *   {@code wsa:ReferenceParameters} element.
      *
-     * @throws java.lang.IllegalArgumentException if <code>referenceParameter</code>
-     * is <code>null</code>.
+     * @throws java.lang.IllegalArgumentException if {@code referenceParameter}
+     * is {@code null}.
      */
     public W3CEndpointReferenceBuilder referenceParameter(Element referenceParameter) {
         if (referenceParameter == null)
             throw new java.lang.IllegalArgumentException("The referenceParameter cannot be null.");
         referenceParameters.add(referenceParameter);
         return this;
     }
 
     /**
-     * Adds the <code>metadataElement</code> to the
-     * <code>W3CEndpointReference</code> instance's
-     * <code>wsa:Metadata</code> element.
+     * Adds the {@code metadataElement} to the
+     * {@code W3CEndpointReference} instance's
+     * {@code wsa:Metadata} element.
      *
      * @param metadataElement The element to be added to the
-     *      <code>wsa:Metadata</code> element.
+     *      {@code wsa:Metadata} element.
      *
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the <code>metadataElement</code> added to the
-     *    <code>wsa:Metadata</code> element.
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the {@code metadataElement} added to the
+     *    {@code wsa:Metadata} element.
      *
-     * @throws java.lang.IllegalArgumentException if <code>metadataElement</code>
-     * is <code>null</code>.
+     * @throws java.lang.IllegalArgumentException if {@code metadataElement}
+     * is {@code null}.
      */
     public W3CEndpointReferenceBuilder metadata(Element metadataElement) {
         if (metadataElement == null)
             throw new java.lang.IllegalArgumentException("The metadataElement cannot be null.");
         metadata.add(metadataElement);
         return this;
     }
 
     /**
      * Adds an extension element to the
-     * <code>W3CEndpointReference</code> instance's
-     * <code>wsa:EndpointReference</code> element.
+     * {@code W3CEndpointReference} instance's
+     * {@code wsa:EndpointReference} element.
      *
      * @param element The extension element to be added to the
-     *   <code>W3CEndpointReference</code>
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the extension <code>element</code> added to the
-     *    <code>W3CEndpointReference</code> instance.
-     * @throws java.lang.IllegalArgumentException if <code>element</code>
-     * is <code>null</code>.
+     *   {@code W3CEndpointReference}
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the extension {@code element} added to the
+     *    {@code W3CEndpointReference} instance.
+     * @throws java.lang.IllegalArgumentException if {@code element}
+     * is {@code null}.
      *
      * @since 1.7, JAX-WS 2.2
      */
     public W3CEndpointReferenceBuilder element(Element element) {
         if (element == null) {

@@ -264,21 +265,21 @@
         return this;
     }
 
     /**
      * Adds an extension attribute to the
-     * <code>W3CEndpointReference</code> instance's
-     * <code>wsa:EndpointReference</code> element.
+     * {@code W3CEndpointReference} instance's
+     * {@code wsa:EndpointReference} element.
      *
      * @param name The name of the extension attribute to be added to the
-     *   <code>W3CEndpointReference</code>
+     *   {@code W3CEndpointReference}
      * @param value extension attribute value
-     * @return A <code>W3CEndpointReferenceBuilder</code> instance with
-     *   the extension attribute added to the <code>W3CEndpointReference</code>
+     * @return A {@code W3CEndpointReferenceBuilder} instance with
+     *   the extension attribute added to the {@code W3CEndpointReference}
      *   instance.
-     * @throws java.lang.IllegalArgumentException if <code>name</code>
-     *   or <code>value</code> is <code>null</code>.
+     * @throws java.lang.IllegalArgumentException if {@code name}
+     *   or {@code value} is {@code null}.
      *
      * @since 1.7, JAX-WS 2.2
      */
     public W3CEndpointReferenceBuilder attribute(QName name, String value) {
         if (name == null || value == null) {

@@ -287,52 +288,52 @@
         attributes.put(name, value);
         return this;
     }
 
     /**
-     * Builds a <code>W3CEndpointReference</code> from the accumulated
-     * properties set on this <code>W3CEndpointReferenceBuilder</code>
+     * Builds a {@code W3CEndpointReference} from the accumulated
+     * properties set on this {@code W3CEndpointReferenceBuilder}
      * instance.
      * <p>
-     * This method can be used to create a <code>W3CEndpointReference</code>
-     * for any endpoint by specifying the <code>address</code> property along
+     * This method can be used to create a {@code W3CEndpointReference}
+     * for any endpoint by specifying the {@code address} property along
      * with any other desired properties.  This method
-     * can also be used to create a <code>W3CEndpointReference</code> for
+     * can also be used to create a {@code W3CEndpointReference} for
      * an endpoint that is published by the same Java EE application.
-     * This method can automatically determine the <code>address</code> of
+     * This method can automatically determine the {@code address} of
      * an endpoint published by the same Java EE application that is identified by the
-     * <code>serviceName</code> and
-     * <code>endpointName</code> properties.  If the <code>address</code> is
-     * <code>null</code> and the <code>serviceName</code> and
-     * <code>endpointName</code>
+     * {@code serviceName} and
+     * {@code endpointName} properties.  If the {@code address} is
+     * {@code null} and the {@code serviceName} and
+     * {@code endpointName}
      * do not identify an endpoint published by the same Java EE application, a
-     * <code>java.lang.IllegalStateException</code> MUST be thrown.
+     * {@code java.lang.IllegalStateException} MUST be thrown.
      *
      *
-     * @return <code>W3CEndpointReference</code> from the accumulated
-     * properties set on this <code>W3CEndpointReferenceBuilder</code>
-     * instance. This method never returns <code>null</code>.
+     * @return {@code W3CEndpointReference} from the accumulated
+     * properties set on this {@code W3CEndpointReferenceBuilder}
+     * instance. This method never returns {@code null}.
      *
      * @throws IllegalStateException
      *     <ul>
-     *        <li>If the <code>address</code>, <code>serviceName</code> and
-     *            <code>endpointName</code> are all <code>null</code>.
-     *        <li>If the <code>serviceName</code> service is <code>null</code> and the
-     *            <code>endpointName</code> is NOT <code>null</code>.
-     *        <li>If the <code>address</code> property is <code>null</code> and
-     *            the <code>serviceName</code> and <code>endpointName</code> do not
+     *        <li>If the {@code address}, {@code serviceName} and
+     *            {@code endpointName} are all {@code null}.
+     *        <li>If the {@code serviceName} service is {@code null} and the
+     *            {@code endpointName} is NOT {@code null}.
+     *        <li>If the {@code address} property is {@code null} and
+     *            the {@code serviceName} and {@code endpointName} do not
      *            specify a valid endpoint published by the same Java EE
      *            application.
-     *        <li>If the <code>serviceName</code> is NOT <code>null</code>
+     *        <li>If the {@code serviceName} is NOT {@code null}
      *             and is not present in the specified WSDL.
-     *        <li>If the <code>endpointName</code> port is not <code>null</code> and it
-     *             is not present in <code>serviceName</code> service in the WSDL.
-     *        <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
+     *        <li>If the {@code endpointName} port is not {@code null} and it
+     *             is not present in {@code serviceName} service in the WSDL.
+     *        <li>If the {@code wsdlDocumentLocation} is NOT {@code null}
      *            and does not represent a valid WSDL.
      *     </ul>
      * @throws WebServiceException If an error occurs while creating the
-     *                             <code>W3CEndpointReference</code>.
+     *                             {@code W3CEndpointReference}.
      *
      */
     public W3CEndpointReference build() {
         if (elements.isEmpty() && attributes.isEmpty() && interfaceName == null) {
             // 2.1 API
< prev index next >