1/*
2 * Copyright (c) 2005, 2017, 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
26package javax.xml.ws;
27
28import javax.xml.bind.annotation.XmlTransient;
29import javax.xml.transform.Result;
30import javax.xml.transform.Source;
31import javax.xml.transform.stream.StreamResult;
32import javax.xml.ws.spi.Provider;
33import javax.xml.ws.wsaddressing.W3CEndpointReference;
34import 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}.
48 * See the {@link javax.xml.ws.Endpoint}, and
49 * {@link javax.xml.ws.BindingProvider} APIs on how
50 * {@code EndpointReferences} can be created for published
51 * endpoints.
52 * <p>
53 * Concrete implementations of this class will represent
54 * an {@code EndpointReference} 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} subclass for that version.
60 * This will allow a JAX-WS implementation to create
61 * a vendor specific {@code EndpointReferences} 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} in Java methods in an
67 * SEI should use
68 * concrete instances of an {@code EndpointReference} such
69 * as the {@code W3CEndpointReference}.  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} using the
75 * {@link EndpointReference#writeTo}
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)
87public abstract class EndpointReference {
88    //
89    //Default constructor to be only called by derived types.
90    //
91
92    /**
93     * Default constructor.
94     */
95    protected EndpointReference(){}
96
97    /**
98     * Factory method to read an EndpointReference from the infoset contained in
99     * {@code eprInfoset}. This method delegates to the vendor specific
100     * implementation of the {@link javax.xml.ws.spi.Provider#readEndpointReference} method.
101     *
102     * @param eprInfoset The {@code EndpointReference} infoset to be unmarshalled
103     *
104     * @return the EndpointReference unmarshalled from {@code eprInfoset}
105     *    never {@code null}
106     * @throws WebServiceException
107     *    if an error occurs while creating the
108     *    {@code EndpointReference} from the {@code eprInfoset}
109     * @throws java.lang.IllegalArgumentException
110     *     if the {@code null} {@code eprInfoset} value is given.
111     */
112    public static EndpointReference readFrom(Source eprInfoset) {
113        return Provider.provider().readEndpointReference(eprInfoset);
114    }
115
116    /**
117     * write this {@code EndpointReference} to the specified infoset format
118     *
119     * @param result for writing infoset
120     * @throws WebServiceException
121     *   if there is an error writing the
122     *   {@code EndpointReference} to the specified {@code result}.
123     *
124     * @throws java.lang.IllegalArgumentException
125     *      If the {@code null} {@code result} value is given.
126     */
127    public abstract void writeTo(Result result);
128
129
130    /**
131     * The {@code getPort} method returns a proxy. If there
132     * are any reference parameters in the
133     * {@code EndpointReference} instance, then those reference
134     * parameters MUST appear as SOAP headers, indicating them to be
135     * reference parameters, on all messages sent to the endpoint.
136     * The parameter  {@code serviceEndpointInterface} specifies
137     * the service endpoint interface that is supported by the
138     * returned proxy.
139     * The {@code EndpointReference} instance specifies the
140     * endpoint that will be invoked by the returned proxy.
141     * In the implementation of this method, the JAX-WS
142     * runtime system takes the responsibility of selecting a protocol
143     * binding (and a port) and configuring the proxy accordingly from
144     * the WSDL Metadata from this {@code EndpointReference} or from
145     * annotations on the {@code serviceEndpointInterface}.  For this method
146     * to successfully return a proxy, WSDL metadata MUST be available and the
147     * {@code EndpointReference} instance MUST contain an implementation understood
148     * {@code serviceName} metadata.
149     * <p>
150     * Because this port is not created from a {@code Service} object, handlers
151     * will not automatically be configured, and the {@code HandlerResolver}
152     * and {@code Executor} cannot be get or set for this port. The
153     * {@code BindingProvider().getBinding().setHandlerChain()}
154     * method can be used to manually configure handlers for this port.
155     *
156     *
157     * @param <T> Service endpoint interface
158     * @param serviceEndpointInterface Service endpoint interface
159     * @param features  An array of {@code WebServiceFeatures} to configure on the
160     *                proxy.  Supported features not in the {@code features
161     *                } parameter will have their default values.
162     * @return Object Proxy instance that supports the
163     *                  specified service endpoint interface
164     * @throws WebServiceException
165     *                  <UL>
166     *                  <LI>If there is an error during creation
167     *                      of the proxy
168     *                  <LI>If there is any missing WSDL metadata
169     *                      as required by this method
170     *                  <LI>If this
171     *                      {@code endpointReference}
172     *                      is invalid
173     *                  <LI>If an illegal
174     *                      {@code serviceEndpointInterface}
175     *                      is specified
176     *                  <LI>If a feature is enabled that is not compatible with
177     *                      this port or is unsupported.
178     *                   </UL>
179     *
180     * @see java.lang.reflect.Proxy
181     * @see WebServiceFeature
182     **/
183    public <T> T getPort(Class<T> serviceEndpointInterface,
184                         WebServiceFeature... features) {
185        return Provider.provider().getPort(this, serviceEndpointInterface,
186                                           features);
187    }
188
189    /**
190     * Displays EPR infoset for debugging convenience.
191     *
192     * @return a string representation of the object
193     */
194    @Override
195    public String toString() {
196        StringWriter w = new StringWriter();
197        writeTo(new StreamResult(w));
198        return w.toString();
199    }
200}
201