001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws;
007:
008: import javax.xml.bind.annotation.XmlTransient;
009: import javax.xml.transform.Result;
010: import javax.xml.transform.Source;
011: import javax.xml.transform.stream.StreamResult;
012: import javax.xml.ws.spi.Provider;
013: import javax.xml.ws.wsaddressing.W3CEndpointReference;
014: import java.io.StringWriter;
015:
016: /**
017: * This class represents an WS-Addressing EndpointReference
018: * which is a remote reference to a web service endpoint.
019: * See <a href="http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/">
020: * Web Services Addressing 1.0 - Core</a>
021: * for more information on WS-Addressing EndpointReferences.
022: * <p>
023: * This class is immutable as the typical web service developer
024: * need not be concerned with its contents. The web service
025: * developer should use this class strictly as a mechanism to
026: * reference a remote web service endpoint. See the {@link Service} APIs
027: * that clients can use to that utilize an <code>EndpointReference</code>.
028: * See the {@link javax.xml.ws.Endpoint}, and
029: * {@link javax.xml.ws.BindingProvider} APIs on how
030: * <code>EndpointReferences</code> can be created for published
031: * endpoints.
032: * <p>
033: * Concrete implementations of this class will represent
034: * an <code>EndpointReference</code> for a particular version of Addressing.
035: * For example the {@link W3CEndpointReference} is for use
036: * with W3C Web Services Addressing 1.0 - Core Recommendation.
037: * If JAX-WS implementors need to support different versions
038: * of addressing, they should write their own
039: * <code>EndpointReference</code> subclass for that version.
040: * This will allow a JAX-WS implementation to create
041: * vendor specific <code>EndpointReferences</code> that that
042: * vendor can use to flag a different version of
043: * addressing.
044: * <p>
045: * Web service developers that wish to pass or return
046: * <code>EndpointReferences</code> in Java methods in an
047: * SEI should use
048: * concrete instances of an <code>EndpointReference</code> such
049: * as the <code>W3CEndpointReference</code>. This way the
050: * schema mapped from the SEI will be more descriptive of the
051: * type of endpoint reference being passed.
052: * <p>
053: * JAX-WS implementors are expected to extract the XML infoset
054: * from an <CODE>EndpointReferece</CODE> using the
055: * <code>{@link EndpointReference#writeTo}</code>
056: * method.
057: * <p>
058: * JAXB will bind this class to xs:anyType. If a better binding
059: * is desired, web services developers should use a concrete
060: * subclass such as {@link W3CEndpointReference}.
061: *
062: * @see W3CEndpointReference
063: * @see Service
064: * @since JAX-WS 2.1
065: */
066: @XmlTransient
067: // to treat this class like Object as far as databinding is concerned (proposed JAXB 2.1 feature)
068: public abstract class EndpointReference {
069: //
070: //Default constructor to be only called by derived types.
071: //
072: protected EndpointReference() {
073: };
074:
075: /**
076: * Factory method to read an EndpointReference from the infoset contained in
077: * <code>eprInfoset</code>. This method delegates to the vendor specific
078: * implementation of the {@link javax.xml.ws.spi.Provider#readEndpointReference} method.
079: *
080: * @param eprInfoset The <code>EndpointReference<code> infoset to be unmarshalled
081: *
082: * @return the EndpointReference unmarshalled from <code>eprInfoset</code>
083: * never <code>null</code>
084: * @throws WebServiceException
085: * if an error occurs while creating the
086: * <code>EndpointReference</code> from the <CODE>eprInfoset</CODE>
087: * @throws java.lang.IllegalArgumentException
088: * if the <code>null</code> <code>eprInfoset</tt> value is given.
089: */
090: public static EndpointReference readFrom(Source eprInfoset) {
091: return Provider.provider().readEndpointReference(eprInfoset);
092: }
093:
094: /**
095: * write this <code>EndpointReference</code> to the specified infoset format
096: * @throws WebServiceException
097: * if there is an error writing the
098: * <code>EndpointReference</code> to the specified <code>result</code>.
099: *
100: * @throws java.lang.IllegalArgumentException
101: * If the <code>null</code> <code>result</tt> value is given.
102: */
103: public abstract void writeTo(Result result);
104:
105: /**
106: * The <code>getPort</code> method returns a proxy. If there
107: * are any reference parameters in the
108: * <code>EndpointReference</code> instance, then those reference
109: * parameters MUST appear as SOAP headers, indicating them to be
110: * reference parameters, on all messages sent to the endpoint.
111: * The parameter <code>serviceEndpointInterface</code> specifies
112: * the service endpoint interface that is supported by the
113: * returned proxy.
114: * The <code>EndpointReference</code> instance specifies the
115: * endpoint that will be invoked by the returned proxy.
116: * In the implementation of this method, the JAX-WS
117: * runtime system takes the responsibility of selecting a protocol
118: * binding (and a port) and configuring the proxy accordingly from
119: * the WSDL Metadata from this <code>EndpointReference</code> or from
120: * annotations on the <code>serviceEndpointInterface</code>. For this method
121: * to successfully return a proxy, WSDL metadata MUST be available and the
122: * <code>EndpointReference</code> instance MUST contain an implementation understood
123: * <code>serviceName</code> metadata.
124: * <p>
125: * Because this port is not created from a <code>Service</code> object, handlers
126: * will not automatically be configured, and the <code>HandlerResolver</code>
127: * and <code>Executor</code> cannot be get or set for this port. The
128: * <code>BindingProvider().getBinding().setHandlerChain()</code>
129: * method can be used to manually configure handlers for this port.
130: *
131: *
132: * @param serviceEndpointInterface Service endpoint interface
133: * @param features An array of <code>WebServiceFeatures</code> to configure on the
134: * proxy. Supported features not in the <code>features
135: * </code> parameter will have their default values.
136: * @return Object Proxy instance that supports the
137: * specified service endpoint interface
138: * @throws WebServiceException
139: * <UL>
140: * <LI>If there is an error during creation
141: * of the proxy
142: * <LI>If there is any missing WSDL metadata
143: * as required by this method
144: * <LI>If this
145: * <code>endpointReference</code>
146: * is invalid
147: * <LI>If an illegal
148: * <code>serviceEndpointInterface</code>
149: * is specified
150: * <LI>If a feature is enabled that is not compatible with
151: * this port or is unsupported.
152: * </UL>
153: *
154: * @see java.lang.reflect.Proxy
155: * @see WebServiceFeature
156: **/
157: public <T> T getPort(Class<T> serviceEndpointInterface,
158: WebServiceFeature... features) {
159: return Provider.provider().getPort(this ,
160: serviceEndpointInterface, features);
161: }
162:
163: /**
164: * Displays EPR infoset for debugging convenience.
165: */
166: public String toString() {
167: StringWriter w = new StringWriter();
168: writeTo(new StreamResult(w));
169: return w.toString();
170: }
171: }
|