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