View Javadoc
1   /*
2    * Copyright (c) 2005, 2011, 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 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 }