javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilder Maven / Gradle / Ivy
Show all versions of webservices-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2005-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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 JAX-WS 2.1
*/
public final class W3CEndpointReferenceBuilder {
/**
* Creates a new W3CEndpointReferenceBuilder instance.
*/
public W3CEndpointReferenceBuilder() {
referenceParameters = new ArrayList();
metadata = new ArrayList();
attributes = new HashMap();
elements = new ArrayList();
}
/**
* 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.
*
* @param address The address of the endpoint to be targeted
* by the returned W3CEndpointReference.
*
* @return A W3CEndpointReferenceBuilder instance with
* the address set to the 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.
*
* @param interfaceName The port type name of the endpoint to be targeted
* by the returned W3CEndpointReference.
*
* @return A W3CEndpointReferenceBuilder instance with
* the interfaceName as wsam:InterfaceName
* element added to the wsa:Metadata element
*/
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.
*
* @param 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.
*
* @return A W3CEndpointReferenceBuilder instance with
* the serviceName as wsam:ServiceName
* element added to the 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 {@link #serviceName} method has been called.
*
* See
* 2.1 Referencing WSDL Metadata from an EPR for more details.
*
* @param 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.
*
* @return A W3CEndpointReferenceBuilder instance with
* the endpointName as
* wsam:ServiceName/@EndpointName in the
* wsa:Metadata element.
*
* @throws IllegalStateException, if the serviceName
* has not been set.
* @throws IllegalArgumentException, if the endpointName's
* Namespace URI doesn't match 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.
*
* @param wsdlDocumentLocation The location of the WSDL document to
* be referenced in the wsa:Metadata of the
* W3CEndpointReference.
* @return A W3CEndpointReferenceBuilder instance with
* the 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.
*
* @param referenceParameter The element to be added to the
* wsa:ReferenceParameters element.
*
* @return A W3CEndpointReferenceBuilder instance with
* the referenceParameter added to the
* wsa:ReferenceParameters element.
*
* @throws java.lang.IllegalArgumentException if referenceParameter
* is 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.
*
* @param metadataElement The element to be added to the
* wsa:Metadata element.
*
* @return A W3CEndpointReferenceBuilder instance with
* the metadataElement added to the
* wsa:Metadata element.
*
* @throws java.lang.IllegalArgumentException if metadataElement
* is 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.
*
* @param element The extension element to be added to the
* W3CEndpointReference
* @return A W3CEndpointReferenceBuilder instance with
* the extension element added to the
* W3CEndpointReference instance.
* @throws java.lang.IllegalArgumentException if element
* is null.
*
* @since 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.
*
* @param name The name of the extension attribute to be added to the
* W3CEndpointReference
* @param value extension attribute value
* @return A W3CEndpointReferenceBuilder instance with
* the extension attribute added to the W3CEndpointReference
* instance.
* @throws java.lang.IllegalArgumentException if name
* or value is null.
*
* @since 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.
*
*
* @return W3CEndpointReference from the accumulated
* properties set on this W3CEndpointReferenceBuilder
* instance. This method never returns null.
*
* @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.
*
* @throws WebServiceException If an error occurs while creating the
* 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 referenceParameters;
private List metadata;
private QName interfaceName;
private QName serviceName;
private QName endpointName;
private String wsdlDocumentLocation;
private Map attributes;
private List elements;
}