1 /* 2 * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.ws; 27 28 import javax.xml.bind.annotation.XmlTransient; 29 import javax.xml.transform.Result; 30 import javax.xml.transform.Source; 31 import javax.xml.transform.stream.StreamResult; 32 import javax.xml.ws.spi.Provider; 33 import javax.xml.ws.wsaddressing.W3CEndpointReference; 34 import java.io.StringWriter; 35 36 /** 37 * This class represents an WS-Addressing EndpointReference 38 * which is a remote reference to a web service endpoint. 39 * See <a href="http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/"> 40 * Web Services Addressing 1.0 - Core</a> 41 * for more information on WS-Addressing EndpointReferences. 42 * <p> 43 * This class is immutable as the typical web service developer 44 * need not be concerned with its contents. The web service 45 * developer should use this class strictly as a mechanism to 46 * reference a remote web service endpoint. See the {@link Service} APIs 47 * that clients can use to that utilize an <code>EndpointReference</code>. 48 * See the {@link javax.xml.ws.Endpoint}, and 49 * {@link javax.xml.ws.BindingProvider} APIs on how 50 * <code>EndpointReferences</code> can be created for published 51 * endpoints. 52 * <p> 53 * Concrete implementations of this class will represent 54 * an <code>EndpointReference</code> for a particular version of Addressing. 55 * For example the {@link W3CEndpointReference} is for use 56 * with W3C Web Services Addressing 1.0 - Core Recommendation. 57 * If JAX-WS implementors need to support different versions 58 * of addressing, they should write their own 59 * <code>EndpointReference</code> subclass for that version. 60 * This will allow a JAX-WS implementation to create 61 * a vendor specific <code>EndpointReferences</code> that the 62 * vendor can use to flag a different version of 63 * addressing. 64 * <p> 65 * Web service developers that wish to pass or return 66 * <code>EndpointReference</code> in Java methods in an 67 * SEI should use 68 * concrete instances of an <code>EndpointReference</code> such 69 * as the <code>W3CEndpointReference</code>. This way the 70 * schema mapped from the SEI will be more descriptive of the 71 * type of endpoint reference being passed. 72 * <p> 73 * JAX-WS implementors are expected to extract the XML infoset 74 * from an <CODE>EndpointReferece</CODE> using the 75 * <code>{@link EndpointReference#writeTo}</code> 76 * method. 77 * <p> 78 * JAXB will bind this class to xs:anyType. If a better binding 79 * is desired, web services developers should use a concrete 80 * subclass such as {@link W3CEndpointReference}. 81 * 82 * @see W3CEndpointReference 83 * @see Service 84 * @since 1.6, JAX-WS 2.1 85 */ 86 @XmlTransient // to treat this class like Object as far as databinding is concerned (proposed JAXB 2.1 feature) 87 public abstract class EndpointReference { 88 // 89 //Default constructor to be only called by derived types. 90 // 91 protected EndpointReference(){} 92 93 /** 94 * Factory method to read an EndpointReference from the infoset contained in 95 * <code>eprInfoset</code>. This method delegates to the vendor specific 96 * implementation of the {@link javax.xml.ws.spi.Provider#readEndpointReference} method. 97 * 98 * @param eprInfoset The <code>EndpointReference</code> infoset to be unmarshalled 99 * 100 * @return the EndpointReference unmarshalled from <code>eprInfoset</code> 101 * never <code>null</code> 102 * @throws WebServiceException 103 * if an error occurs while creating the 104 * <code>EndpointReference</code> from the <CODE>eprInfoset</CODE> 105 * @throws java.lang.IllegalArgumentException 106 * if the <code>null</code> <code>eprInfoset</code> value is given. 107 */ 108 public static EndpointReference readFrom(Source eprInfoset) { 109 return Provider.provider().readEndpointReference(eprInfoset); 110 } 111 112 /** 113 * write this <code>EndpointReference</code> to the specified infoset format 114 * 115 * @param result for writing infoset 116 * @throws WebServiceException 117 * if there is an error writing the 118 * <code>EndpointReference</code> to the specified <code>result</code>. 119 * 120 * @throws java.lang.IllegalArgumentException 121 * If the <code>null</code> <code>result</code> value is given. 122 */ 123 public abstract void writeTo(Result result); 124 125 126 /** 127 * The <code>getPort</code> method returns a proxy. If there 128 * are any reference parameters in the 129 * <code>EndpointReference</code> instance, then those reference 130 * parameters MUST appear as SOAP headers, indicating them to be 131 * reference parameters, on all messages sent to the endpoint. 132 * The parameter <code>serviceEndpointInterface</code> specifies 133 * the service endpoint interface that is supported by the 134 * returned proxy. 135 * The <code>EndpointReference</code> instance specifies the 136 * endpoint that will be invoked by the returned proxy. 137 * In the implementation of this method, the JAX-WS 138 * runtime system takes the responsibility of selecting a protocol 139 * binding (and a port) and configuring the proxy accordingly from 140 * the WSDL Metadata from this <code>EndpointReference</code> or from 141 * annotations on the <code>serviceEndpointInterface</code>. For this method 142 * to successfully return a proxy, WSDL metadata MUST be available and the 143 * <code>EndpointReference</code> instance MUST contain an implementation understood 144 * <code>serviceName</code> metadata. 145 * <p> 146 * Because this port is not created from a <code>Service</code> object, handlers 147 * will not automatically be configured, and the <code>HandlerResolver</code> 148 * and <code>Executor</code> cannot be get or set for this port. The 149 * <code>BindingProvider().getBinding().setHandlerChain()</code> 150 * method can be used to manually configure handlers for this port. 151 * 152 * 153 * @param serviceEndpointInterface Service endpoint interface 154 * @param features An array of <code>WebServiceFeatures</code> to configure on the 155 * proxy. Supported features not in the <code>features 156 * </code> parameter will have their default values. 157 * @return Object Proxy instance that supports the 158 * specified service endpoint interface 159 * @throws WebServiceException 160 * <UL> 161 * <LI>If there is an error during creation 162 * of the proxy 163 * <LI>If there is any missing WSDL metadata 164 * as required by this method 165 * <LI>If this 166 * <code>endpointReference</code> 167 * is invalid 168 * <LI>If an illegal 169 * <code>serviceEndpointInterface</code> 170 * is specified 171 * <LI>If a feature is enabled that is not compatible with 172 * this port or is unsupported. 173 * </UL> 174 * 175 * @see java.lang.reflect.Proxy 176 * @see WebServiceFeature 177 **/ 178 public <T> T getPort(Class<T> serviceEndpointInterface, 179 WebServiceFeature... features) { 180 return Provider.provider().getPort(this, serviceEndpointInterface, 181 features); 182 } 183 184 /** 185 * Displays EPR infoset for debugging convenience. 186 */ 187 public String toString() { 188 StringWriter w = new StringWriter(); 189 writeTo(new StreamResult(w)); 190 return w.toString(); 191 } 192 }