javax.xml.ws.EndpointReference Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2005-2017 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://oss.oracle.com/licenses/CDDL+GPL-1.1
* or 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 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;
import javax.xml.bind.annotation.XmlTransient;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamResult;
import javax.xml.ws.spi.Provider;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import java.io.StringWriter;
/**
* This class represents an WS-Addressing EndpointReference
* which is a remote reference to a web service endpoint.
* See
* Web Services Addressing 1.0 - Core
* for more information on WS-Addressing EndpointReferences.
*
* This class is immutable as the typical web service developer
* need not be concerned with its contents. The web service
* developer should use this class strictly as a mechanism to
* reference a remote web service endpoint. See the {@link Service} APIs
* that clients can use to that utilize an {@code EndpointReference}.
* See the {@link javax.xml.ws.Endpoint}, and
* {@link javax.xml.ws.BindingProvider} APIs on how
* {@code EndpointReferences} can be created for published
* endpoints.
*
* Concrete implementations of this class will represent
* an {@code EndpointReference} for a particular version of Addressing.
* For example the {@link W3CEndpointReference} is for use
* with W3C Web Services Addressing 1.0 - Core Recommendation.
* If JAX-WS implementors need to support different versions
* of addressing, they should write their own
* {@code EndpointReference} subclass for that version.
* This will allow a JAX-WS implementation to create
* a vendor specific {@code EndpointReferences} that the
* vendor can use to flag a different version of
* addressing.
*
* Web service developers that wish to pass or return
* {@code EndpointReference} in Java methods in an
* SEI should use
* concrete instances of an {@code EndpointReference} such
* as the {@code W3CEndpointReference}. This way the
* schema mapped from the SEI will be more descriptive of the
* type of endpoint reference being passed.
*
* JAX-WS implementors are expected to extract the XML infoset
* from an {@code EndpointReferece} using the
* {@link EndpointReference#writeTo}
* method.
*
* JAXB will bind this class to xs:anyType. If a better binding
* is desired, web services developers should use a concrete
* subclass such as {@link W3CEndpointReference}.
*
* @see W3CEndpointReference
* @see Service
* @since 1.6, JAX-WS 2.1
*/
@XmlTransient // to treat this class like Object as far as databinding is concerned (proposed JAXB 2.1 feature)
public abstract class EndpointReference {
//
//Default constructor to be only called by derived types.
//
/**
* Default constructor.
*/
protected EndpointReference(){}
/**
* Factory method to read an EndpointReference from the infoset contained in
* {@code eprInfoset}. This method delegates to the vendor specific
* implementation of the {@link javax.xml.ws.spi.Provider#readEndpointReference} method.
*
* @param eprInfoset The {@code EndpointReference} infoset to be unmarshalled
*
* @return the EndpointReference unmarshalled from {@code eprInfoset}
* never {@code null}
* @throws WebServiceException
* if an error occurs while creating the
* {@code EndpointReference} from the {@code eprInfoset}
* @throws java.lang.IllegalArgumentException
* if the {@code null} {@code eprInfoset} value is given.
*/
public static EndpointReference readFrom(Source eprInfoset) {
return Provider.provider().readEndpointReference(eprInfoset);
}
/**
* write this {@code EndpointReference} to the specified infoset format
*
* @param result for writing infoset
* @throws WebServiceException
* if there is an error writing the
* {@code EndpointReference} to the specified {@code result}.
*
* @throws java.lang.IllegalArgumentException
* If the {@code null} {@code result} value is given.
*/
public abstract void writeTo(Result result);
/**
* The {@code getPort} method returns a proxy. If there
* are any reference parameters in the
* {@code EndpointReference} instance, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The parameter {@code serviceEndpointInterface} specifies
* the service endpoint interface that is supported by the
* returned proxy.
* The {@code EndpointReference} instance specifies the
* endpoint that will be invoked by the returned proxy.
* In the implementation of this method, the JAX-WS
* runtime system takes the responsibility of selecting a protocol
* binding (and a port) and configuring the proxy accordingly from
* the WSDL Metadata from this {@code EndpointReference} or from
* annotations on the {@code serviceEndpointInterface}. For this method
* to successfully return a proxy, WSDL metadata MUST be available and the
* {@code EndpointReference} instance MUST contain an implementation understood
* {@code serviceName} metadata.
*
* Because this port is not created from a {@code Service} object, handlers
* will not automatically be configured, and the {@code HandlerResolver}
* and {@code Executor} cannot be get or set for this port. The
* {@code BindingProvider().getBinding().setHandlerChain()}
* method can be used to manually configure handlers for this port.
*
*
* @param Service endpoint interface
* @param serviceEndpointInterface Service endpoint interface
* @param features An array of {@code WebServiceFeatures} to configure on the
* proxy. Supported features not in the {@code features
* } parameter will have their default values.
* @return Object Proxy instance that supports the
* specified service endpoint interface
* @throws WebServiceException
*
* - If there is an error during creation
* of the proxy
*
- If there is any missing WSDL metadata
* as required by this method
*
- If this
* {@code endpointReference}
* is invalid
*
- If an illegal
* {@code serviceEndpointInterface}
* is specified
*
- If a feature is enabled that is not compatible with
* this port or is unsupported.
*
*
* @see java.lang.reflect.Proxy
* @see WebServiceFeature
**/
public T getPort(Class serviceEndpointInterface,
WebServiceFeature... features) {
return Provider.provider().getPort(this, serviceEndpointInterface,
features);
}
/**
* Displays EPR infoset for debugging convenience.
*
* @return a string representation of the object
*/
@Override
public String toString() {
StringWriter w = new StringWriter();
writeTo(new StreamResult(w));
return w.toString();
}
}