All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.ws.EndpointReference Maven / Gradle / Ivy

There is a newer version: 2.3.1
Show newest version
/*
 * 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;

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 EndpointReference. * See the {@link javax.xml.ws.Endpoint}, and * {@link javax.xml.ws.BindingProvider} APIs on how * EndpointReferences can be created for published * endpoints. *

* Concrete implementations of this class will represent * an 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 * EndpointReference subclass for that version. * This will allow a JAX-WS implementation to create * a vendor specific EndpointReferences that the * vendor can use to flag a different version of * addressing. *

* Web service developers that wish to pass or return * EndpointReference in Java methods in an * SEI should use * concrete instances of an EndpointReference such * as the 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 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 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. // protected EndpointReference(){} /** * Factory method to read an EndpointReference from the infoset contained in * eprInfoset. This method delegates to the vendor specific * implementation of the {@link javax.xml.ws.spi.Provider#readEndpointReference} method. * * @param eprInfoset The EndpointReference infoset to be unmarshalled * * @return the EndpointReference unmarshalled from eprInfoset * never null * @throws WebServiceException * if an error occurs while creating the * EndpointReference from the eprInfoset * @throws java.lang.IllegalArgumentException * if the null eprInfoset value is given. */ public static EndpointReference readFrom(Source eprInfoset) { return Provider.provider().readEndpointReference(eprInfoset); } /** * write this EndpointReference to the specified infoset format * * @param result for writing infoset * @throws WebServiceException * if there is an error writing the * EndpointReference to the specified result. * * @throws java.lang.IllegalArgumentException * If the null result value is given. */ public abstract void writeTo(Result result); /** * The getPort method returns a proxy. If there * are any reference parameters in the * 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 serviceEndpointInterface specifies * the service endpoint interface that is supported by the * returned proxy. * The 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 EndpointReference or from * annotations on the serviceEndpointInterface. For this method * to successfully return a proxy, WSDL metadata MUST be available and the * EndpointReference instance MUST contain an implementation understood * serviceName metadata. *

* Because this port is not created from a Service object, handlers * will not automatically be configured, and the HandlerResolver * and Executor cannot be get or set for this port. The * BindingProvider().getBinding().setHandlerChain() * method can be used to manually configure handlers for this port. * * * @param serviceEndpointInterface Service endpoint interface * @param features An array of WebServiceFeatures to configure on the * proxy. Supported features not in the 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 * endpointReference * is invalid *
  • If an illegal * 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. */ public String toString() { StringWriter w = new StringWriter(); writeTo(new StreamResult(w)); return w.toString(); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy