/*
 * 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
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.xml.ws.wsaddressing;


import org.w3c.dom.Element;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.HashMap;
import javax.xml.namespace.QName;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.spi.Provider;


This class is used to build W3CEndpointReference instances. The intended use of this clsss is for an application component, for example a factory component, to create an W3CEndpointReference for a web service endpoint published by the same Java EE application. It can also be used to create W3CEndpointReferences for an Java SE based endpoint by providing the address property. 
 When creating a W3CEndpointReference for an endpoint that is not published by the same Java EE application, the address property MUST be specified. 
 When creating a W3CEndpointReference for an endpoint published by the same Java EE application, the address property MAY be null but then the serviceName and endpointName MUST specify an endpoint published by the same Java EE application. 
 When the wsdlDocumentLocation is specified it MUST refer to a valid WSDL document and the serviceName and endpointName (if specified) MUST match a service and port in the WSDL document. 
Since:
1.6, JAX-WS 2.1/**
 * 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} for a
 * web service endpoint published by the same
 * Java EE application. It can also be used to create
 * {@code W3CEndpointReferences} for an Java SE based
 * endpoint by providing the {@code address} property.
 * <p>
 * When creating a {@code W3CEndpointReference} for an
 * endpoint that is not published by the same Java EE application,
 * the {@code address} property MUST be specified.
 * <p>
 * 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} 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 W3CEndpointReferenceBuilder 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 address to the W3CEndpointReference instance's wsa:Address. 
 The address MUST be set to a non-null value when building a W3CEndpointReference for a web service endpoint that is not published by the same Java EE application or when running on Java SE. 
Params:
address – The address of the endpoint to be targeted by the returned W3CEndpointReference.
Returns:
A W3CEndpointReferenceBuilder instance with the address set to the wsa:Address./**
     * Sets the {@code address} to the
     * {@code W3CEndpointReference} instance's
     * {@code wsa:Address}.
     * <p>
     * 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}.
     *
     * @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 interfaceName as the wsam:InterfaceName element in the wsa:Metadata element. See 
2.1 Referencing WSDL Metadata from an EPR for more details.
Params:
interfaceName – The port type name of the endpoint to be targeted by the returned W3CEndpointReference.
Returns:
A W3CEndpointReferenceBuilder instance with the interfaceName as wsam:InterfaceName element added to the wsa:Metadata element
Since:
1.7/**
     * 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}.
     *
     * @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 serviceName as the wsam:ServiceName element in the wsa:Metadata element. See 
2.1 Referencing WSDL Metadata from an EPR for more details.
Params:
serviceName – The service name of the endpoint to be targeted by the returned W3CEndpointReference. This property may also be used with the endpointName (portName) property to lookup the address of a web service endpoint that is published by the same Java EE application.
Returns:
A W3CEndpointReferenceBuilder instance with the serviceName as wsam:ServiceName element added to the wsa:Metadata 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}.  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} 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 endpointName as wsam:ServiceName/@EndpointName in the wsa:Metadata element. This method can only be called after the serviceName method has been called. 

See 
2.1 Referencing WSDL Metadata from an EPR for more details.
Params:
endpointName – The name of the endpoint to be targeted by the returned W3CEndpointReference. The endpointName (portName) property may also be used with the serviceName property to lookup the address of a web service endpoint published by the same Java EE application.
Throws:
IllegalStateException – if the serviceName has not been set
IllegalArgumentException – if the endpointName's Namespace URI doesn't match serviceName's Namespace URI
Returns:
A W3CEndpointReferenceBuilder instance with the endpointName as wsam:ServiceName/@EndpointName in the wsa:Metadata element./**
     * 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}. 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} 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);
        }

        this.endpointName = endpointName;
        return this;
    }

    
Sets the wsdlDocumentLocation that will be referenced as wsa:Metadata/@wsdli:wsdlLocation. The namespace name for the wsdli:wsdlLocation's value can be taken from the WSDL itself. 

See 
2.1 Referencing WSDL Metadata from an EPR for more details.
Params:
wsdlDocumentLocation – The location of the WSDL document to be referenced in the wsa:Metadata of the W3CEndpointReference.
Returns:
A W3CEndpointReferenceBuilder instance with the wsdlDocumentLocation that is to be referenced./**
     * 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} 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 referenceParameter to the W3CEndpointReference instance wsa:ReferenceParameters element. 
Params:
referenceParameter – The element to be added to the wsa:ReferenceParameters element.
Throws:
IllegalArgumentException – if referenceParameter is null.
Returns:
A W3CEndpointReferenceBuilder instance with the referenceParameter added to the wsa:ReferenceParameters 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} element.
     *
     * @return A {@code W3CEndpointReferenceBuilder} instance with
     *   the {@code referenceParameter} added to the
     *   {@code wsa:ReferenceParameters} element.
     *
     * @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 metadataElement to the W3CEndpointReference instance's wsa:Metadata element. 
Params:
metadataElement – The element to be added to the wsa:Metadata element.
Throws:
IllegalArgumentException – if metadataElement is null.
Returns:
A W3CEndpointReferenceBuilder instance with the metadataElement added to the wsa:Metadata 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} element.
     *
     * @return A {@code W3CEndpointReferenceBuilder} instance with
     *   the {@code metadataElement} added to the
     *    {@code wsa:Metadata} element.
     *
     * @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 W3CEndpointReference instance's wsa:EndpointReference element. 
Params:
element – The extension element to be added to the W3CEndpointReference
Throws:
IllegalArgumentException – if element is null.
Returns:
A W3CEndpointReferenceBuilder instance with the extension element added to the W3CEndpointReference instance.
Since:
1.7, JAX-WS 2.2/**
     * Adds an extension element to the
     * {@code W3CEndpointReference} instance's
     * {@code wsa:EndpointReference} element.
     *
     * @param element The extension element to be added to the
     *   {@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) {
            throw new IllegalArgumentException("The extension element cannot be null.");
        }
        elements.add(element);
        return this;
    }

    
Adds an extension attribute to the W3CEndpointReference instance's wsa:EndpointReference element. 
Params:
name – The name of the extension attribute to be added to the W3CEndpointReference
value – extension attribute value
Throws:
IllegalArgumentException – if name or value is null.
Returns:
A W3CEndpointReferenceBuilder instance with the extension attribute added to the W3CEndpointReference instance.
Since:
1.7, JAX-WS 2.2/**
     * Adds an extension attribute to the
     * {@code W3CEndpointReference} instance's
     * {@code wsa:EndpointReference} element.
     *
     * @param name The name of the extension attribute to be added to the
     *   {@code W3CEndpointReference}
     * @param value extension attribute value
     * @return A {@code W3CEndpointReferenceBuilder} instance with
     *   the extension attribute added to the {@code W3CEndpointReference}
     *   instance.
     * @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) {
            throw new IllegalArgumentException("The extension attribute name or value cannot be null.");
        }
        attributes.put(name, value);
        return this;
    }

    
Builds a W3CEndpointReference from the accumulated properties set on this W3CEndpointReferenceBuilder instance. 
 This method can be used to create a W3CEndpointReference for any endpoint by specifying the address property along with any other desired properties. This method can also be used to create a W3CEndpointReference for an endpoint that is published by the same Java EE application. This method can automatically determine the address of an endpoint published by the same Java EE application that is identified by the serviceName and endpointName properties. If the address is null and the serviceName and endpointName do not identify an endpoint published by the same Java EE application, a java.lang.IllegalStateException MUST be thrown. 
Throws:
IllegalStateException – 
    

       
If the address, serviceName and endpointName are all null. 
If the serviceName service is null and the endpointName is NOT null. 
If the address property is null and the serviceName and endpointName do not specify a valid endpoint published by the same Java EE application. 
If the serviceName is NOT null and is not present in the specified WSDL. 
If the endpointName port is not null and it is not present in serviceName service in the WSDL. 
If the wsdlDocumentLocation is NOT null and does not represent a valid WSDL. 
WebServiceException – If an error occurs while creating the W3CEndpointReference.
Returns:
W3CEndpointReference from the accumulated properties set on this W3CEndpointReferenceBuilder instance. This method never returns null./**
     * 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}
     * 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} for
     * an endpoint that is published by the same Java EE application.
     * 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} 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} MUST be thrown.
     *
     *
     * @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 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} is NOT {@code null}
     *             and is not present in the specified WSDL.
     *        <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}.
     *
     */
    public W3CEndpointReference build() {
        if (elements.isEmpty() && attributes.isEmpty() && interfaceName == null) {
            // 2.1 API
            return Provider.provider().createW3CEndpointReference(address,
                serviceName, endpointName, metadata, wsdlDocumentLocation,
                referenceParameters);
        }
        return Provider.provider().createW3CEndpointReference(address,
                interfaceName, serviceName, endpointName, metadata, wsdlDocumentLocation,
                referenceParameters, elements, attributes);
    }

    private String address;
    private List<Element> referenceParameters;
    private List<Element> metadata;
    private QName interfaceName;
    private QName serviceName;
    private QName endpointName;
    private String wsdlDocumentLocation;
    private Map<QName,String> attributes;
    private List<Element> elements;
}