KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > ws > EndpointReference


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