--- a/jaxws/src/share/classes/javax/xml/ws/Endpoint.java Wed Jul 05 16:49:07 2017 +0200
+++ b/jaxws/src/share/classes/javax/xml/ws/Endpoint.java Mon Apr 20 15:14:39 2009 -0700
@@ -28,6 +28,9 @@
import java.util.List;
import java.util.Map;
import javax.xml.ws.spi.Provider;
+import javax.xml.ws.wsaddressing.W3CEndpointReference;
+import org.w3c.dom.Element;
+
/**
* A Web service endpoint.
@@ -54,7 +57,7 @@
* <p>An endpoint may have a list of metadata documents, such as WSDL
* and XMLSchema documents, bound to it. At publishing time, the
* JAX-WS implementation will try to reuse as much of that metadata
- * as possible instead of generating new one based on the annotations
+ * as possible instead of generating new ones based on the annotations
* present on the implementor.
*
* @since JAX-WS 2.0
@@ -64,209 +67,225 @@
* @see javax.xml.ws.soap.SOAPBinding
* @see java.util.concurrent.Executor
*
-**/
+ **/
public abstract class Endpoint {
- /** Standard property: name of WSDL service.
- * <p>Type: javax.xml.namespace.QName
- **/
- public static final String WSDL_SERVICE = "javax.xml.ws.wsdl.service";
+ /** Standard property: name of WSDL service.
+ * <p>Type: javax.xml.namespace.QName
+ **/
+ public static final String WSDL_SERVICE = "javax.xml.ws.wsdl.service";
+
+ /** Standard property: name of WSDL port.
+ * <p>Type: javax.xml.namespace.QName
+ **/
+ public static final String WSDL_PORT = "javax.xml.ws.wsdl.port";
+
- /** Standard property: name of WSDL port.
- * <p>Type: javax.xml.namespace.QName
- **/
- public static final String WSDL_PORT = "javax.xml.ws.wsdl.port";
+ /**
+ * Creates an endpoint with the specified implementor object. If there is
+ * a binding specified via a BindingType annotation then it MUST be used else
+ * a default of SOAP 1.1 / HTTP binding MUST be used.
+ * <p>
+ * The newly created endpoint may be published by calling
+ * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
+ * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
+ *
+ *
+ * @param implementor The endpoint implementor.
+ *
+ * @return The newly created endpoint.
+ *
+ **/
+ public static Endpoint create(Object implementor) {
+ return create(null, implementor);
+ }
+
+ /**
+ * Creates an endpoint with the specified binding type and
+ * implementor object.
+ * <p>
+ * The newly created endpoint may be published by calling
+ * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
+ * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
+ *
+ * @param bindingId A URI specifying the binding to use. If the bindingID is
+ * <code>null</code> and no binding is specified via a BindingType
+ * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
+ *
+ * @param implementor The endpoint implementor.
+ *
+ * @return The newly created endpoint.
+ *
+ **/
+ public static Endpoint create(String bindingId, Object implementor) {
+ return Provider.provider().createEndpoint(bindingId, implementor);
+ }
- /**
- * Creates an endpoint with the specified implementor object. If there is
- * a binding specified via a BindingType annotation then it MUST be used else
- * a default of SOAP 1.1 / HTTP binding MUST be used.
- * <p>
- * The newly created endpoint may be published by calling
- * one of the javax.xml.ws.Endpoint#publish(String) and
- * javax.xml.ws.Endpoint#publish(Object) methods.
- *
- *
- * @param implementor The endpoint implementor.
- *
- * @return The newly created endpoint.
- *
- **/
- public static Endpoint create(Object implementor) {
- return create(null, implementor);
- }
+ /**
+ * Returns the binding for this endpoint.
+ *
+ * @return The binding for this endpoint
+ **/
+ public abstract Binding getBinding();
+
+ /**
+ * Returns the implementation object for this endpoint.
+ *
+ * @return The implementor for this endpoint
+ **/
+ public abstract Object getImplementor();
- /**
- * Creates an endpoint with the specified binding type and
- * implementor object.
- * <p>
- * The newly created endpoint may be published by calling
- * one of the javax.xml.ws.Endpoint#publish(String) and
- * javax.xml.ws.Endpoint#publish(Object) methods.
- *
- * @param bindingId A URI specifying the binding to use. If the bindingID is
- * <code>null</code> and no binding is specified via a BindingType
- * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
- *
- * @param implementor The endpoint implementor.
- *
- * @return The newly created endpoint.
- *
- **/
- public static Endpoint create(String bindingId, Object implementor) {
- return Provider.provider().createEndpoint(bindingId, implementor);
- }
+ /**
+ * Publishes this endpoint at the given address.
+ * The necessary server infrastructure will be created and
+ * configured by the JAX-WS implementation using some default configuration.
+ * In order to get more control over the server configuration, please
+ * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead.
+ *
+ * @param address A URI specifying the address to use. The address
+ * MUST be compatible with the binding specified at the
+ * time the endpoint was created.
+ *
+ * @throws java.lang.IllegalArgumentException
+ * If the provided address URI is not usable
+ * in conjunction with the endpoint's binding.
+ *
+ * @throws java.lang.IllegalStateException
+ * If the endpoint has been published already or it has been stopped.
+ *
+ * @throws java.lang.SecurityException
+ * If a <code>java.lang.SecurityManger</code>
+ * is being used and the application doesn't have the
+ * <code>WebServicePermission("publishEndpoint")</code> permission.
+ **/
+ public abstract void publish(String address);
- /**
- * Returns the binding for this endpoint.
- *
- * @return The binding for this endpoint
- **/
- public abstract Binding getBinding();
-
- /**
- * Returns the implementation object for this endpoint.
- *
- * @return The implementor for this endpoint
- **/
- public abstract Object getImplementor();
-
- /**
- * Publishes this endpoint at the given address.
- * The necessary server infrastructure will be created and
- * configured by the JAX-WS implementation using some default configuration.
- * In order to get more control over the server configuration, please
- * use the javax.xml.ws.Endpoint#publish(Object) method instead.
- *
- * @param address A URI specifying the address to use. The address
- * must be compatible with the binding specified at the
- * time the endpoint was created.
- *
- * @throws java.lang.IllegalArgumentException
- * If the provided address URI is not usable
- * in conjunction with the endpoint's binding.
- *
- * @throws java.lang.IllegalStateException
- * If the endpoint has been published already or it has been stopped.
- **/
- public abstract void publish(String address);
+ /**
+ * Creates and publishes an endpoint for the specified implementor
+ * object at the given address.
+ * <p>
+ * The necessary server infrastructure will be created and
+ * configured by the JAX-WS implementation using some default configuration.
+ *
+ * In order to get more control over the server configuration, please
+ * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
+ * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
+ *
+ * @param address A URI specifying the address and transport/protocol
+ * to use. A http: URI MUST result in the SOAP 1.1/HTTP
+ * binding being used. Implementations may support other
+ * URI schemes.
+ * @param implementor The endpoint implementor.
+ *
+ * @return The newly created endpoint.
+ *
+ * @throws java.lang.SecurityException
+ * If a <code>java.lang.SecurityManger</code>
+ * is being used and the application doesn't have the
+ * <code>WebServicePermission("publishEndpoint")</code> permission.
+ *
+ **/
+ public static Endpoint publish(String address, Object implementor) {
+ return Provider.provider().createAndPublishEndpoint(address, implementor);
+ }
- /**
- * Creates and publishes an endpoint for the specified implementor
- * object at the given address.
- * <p>
- * The necessary server infrastructure will be created and
- * configured by the JAX-WS implementation using some default configuration.
- *
- * In order to get more control over the server configuration, please
- * use the javax.xml.ws.Endpoint#create(String,Object) and
- * javax.xml.ws.Endpoint#publish(Object) method instead.
- *
- * @param address A URI specifying the address and transport/protocol
- * to use. A http: URI must result in the SOAP 1.1/HTTP
- * binding being used. Implementations may support other
- * URI schemes.
- * @param implementor The endpoint implementor.
- *
- * @return The newly created endpoint.
- *
- **/
- public static Endpoint publish (String address, Object implementor) {
- return Provider.provider().createAndPublishEndpoint(address, implementor);
- }
+ /**
+ * Publishes this endpoint at the provided server context.
+ * A server context encapsulates the server infrastructure
+ * and addressing information for a particular transport.
+ * For a call to this method to succeed, the server context
+ * passed as an argument to it MUST be compatible with the
+ * endpoint's binding.
+ *
+ * @param serverContext An object representing a server
+ * context to be used for publishing the endpoint.
+ *
+ * @throws java.lang.IllegalArgumentException
+ * If the provided server context is not
+ * supported by the implementation or turns
+ * out to be unusable in conjunction with the
+ * endpoint's binding.
+ *
+ * @throws java.lang.IllegalStateException
+ * If the endpoint has been published already or it has been stopped.
+ *
+ * @throws java.lang.SecurityException
+ * If a <code>java.lang.SecurityManger</code>
+ * is being used and the application doesn't have the
+ * <code>WebServicePermission("publishEndpoint")</code> permission.
+ **/
+ public abstract void publish(Object serverContext);
- /**
- * Publishes this endpoint at the provided server context.
- * A server context encapsulates the server infrastructure
- * and addressing information for a particular transport.
- * For a call to this method to succeed, the server context
- * passed as an argument to it must be compatible with the
- * endpoint's binding.
- *
- * @param serverContext An object representing a server
- * context to be used for publishing the endpoint.
- *
- * @throws java.lang.IllegalArgumentException
- * If the provided server context is not
- * supported by the implementation or turns
- * out to be unusable in conjunction with the
- * endpoint's binding.
- *
- * @throws java.lang.IllegalStateException
- * If the endpoint has been published already or it has been stopped.
- **/
- public abstract void publish(Object serverContext);
+ /**
+ * Stops publishing this endpoint.
+ *
+ * If the endpoint is not in a published state, this method
+ * has no effect.
+ *
+ **/
+ public abstract void stop();
- /**
- * Stops publishing this endpoint.
- *
- * If the endpoint is not in a published state, this method
- * has not effect.
- *
- **/
- public abstract void stop();
+ /**
+ * Returns true if the endpoint is in the published state.
+ *
+ * @return <code>true</code> if the endpoint is in the published state.
+ **/
+ public abstract boolean isPublished();
- /**
- * Returns true if the endpoint is in the published state.
- *
- * @return <code>true</code> if the endpoint is in the published state.
- **/
- public abstract boolean isPublished();
+ /**
+ * Returns a list of metadata documents for the service.
+ *
+ * @return <code>List<javax.xml.transform.Source></code> A list of metadata documents for the service
+ **/
+ public abstract List<javax.xml.transform.Source> getMetadata();
- /**
- * Returns a list of metadata documents for the service.
- *
- * @return <code>List<javax.xml.transform.Source></code> A list of metadata documents for the service
- **/
- public abstract List<javax.xml.transform.Source> getMetadata();
-
- /**
- * Sets the metadata for this endpoint.
- *
- * @param metadata A list of XML document sources containing
- * metadata information for the endpoint (e.g.
- * WSDL or XML Schema documents)
- *
- * @throws java.lang.IllegalStateException If the endpoint
- * has already been published.
- **/
- public abstract void setMetadata(List<javax.xml.transform.Source> metadata);
+ /**
+ * Sets the metadata for this endpoint.
+ *
+ * @param metadata A list of XML document sources containing
+ * metadata information for the endpoint (e.g.
+ * WSDL or XML Schema documents)
+ *
+ * @throws java.lang.IllegalStateException If the endpoint
+ * has already been published.
+ **/
+ public abstract void setMetadata(List<javax.xml.transform.Source> metadata);
- /**
- * Returns the executor for this <code>Endpoint</code>instance.
- *
- * The executor is used to dispatch an incoming request to
- * the implementor object.
- *
- * @return The <code>java.util.concurrent.Executor</code> to be
- * used to dispatch a request.
- *
- * @see java.util.concurrent.Executor
- **/
- public abstract java.util.concurrent.Executor getExecutor();
+ /**
+ * Returns the executor for this <code>Endpoint</code>instance.
+ *
+ * The executor is used to dispatch an incoming request to
+ * the implementor object.
+ *
+ * @return The <code>java.util.concurrent.Executor</code> to be
+ * used to dispatch a request.
+ *
+ * @see java.util.concurrent.Executor
+ **/
+ public abstract java.util.concurrent.Executor getExecutor();
- /**
- * Sets the executor for this <code>Endpoint</code> instance.
- *
- * The executor is used to dispatch an incoming request to
- * the implementor object.
- *
- * If this <code>Endpoint</code> is published using the
- * <code>publish(Object)</code> method and the specified server
- * context defines its own threading behavior, the executor
- * may be ignored.
- *
- * @param executor The <code>java.util.concurrent.Executor</code>
- * to be used to dispatch a request.
- *
- * @throws SecurityException If the instance does not support
- * setting an executor for security reasons (e.g. the
- * necessary permissions are missing).
- *
- * @see java.util.concurrent.Executor
- **/
- public abstract void setExecutor(java.util.concurrent.Executor executor);
+ /**
+ * Sets the executor for this <code>Endpoint</code> instance.
+ *
+ * The executor is used to dispatch an incoming request to
+ * the implementor object.
+ *
+ * If this <code>Endpoint</code> is published using the
+ * <code>publish(Object)</code> method and the specified server
+ * context defines its own threading behavior, the executor
+ * may be ignored.
+ *
+ * @param executor The <code>java.util.concurrent.Executor</code>
+ * to be used to dispatch a request.
+ *
+ * @throws SecurityException If the instance does not support
+ * setting an executor for security reasons (e.g. the
+ * necessary permissions are missing).
+ *
+ * @see java.util.concurrent.Executor
+ **/
+ public abstract void setExecutor(java.util.concurrent.Executor executor);
/**
@@ -275,7 +294,7 @@
* @return Map<String,Object> The property bag
* associated with this instance.
**/
- public abstract Map<String,Object> getProperties();
+ public abstract Map<String,Object> getProperties();
/**
* Sets the property bag for this <code>Endpoint</code> instance.
@@ -283,5 +302,59 @@
* @param properties The property bag associated with
* this instance.
**/
- public abstract void setProperties(Map<String,Object> properties);
+ public abstract void setProperties(Map<String,Object> properties);
+
+ /**
+ * Returns the <code>EndpointReference</code> associated with
+ * this <code>Endpoint</code> instance.
+ * <p>
+ * If the Binding for this <code>bindingProvider</code> is
+ * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
+ * <code>W3CEndpointReference</code> MUST be returned.
+ *
+ * @param referenceParameters Reference parameters to be associated with the
+ * returned <code>EndpointReference</code> instance.
+ * @return EndpointReference of this <code>Endpoint</code> instance.
+ * If the returned <code>EndpointReference</code> is of type
+ * <code>W3CEndpointReference</code> then it MUST contain the
+ * the specified <code>referenceParameters</code>.
+
+ * @throws WebServiceException If any error in the creation of
+ * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
+ * not in the published state.
+ * @throws UnsupportedOperationException If this <code>BindingProvider</code>
+ * uses the XML/HTTP binding.
+ *
+ * @see W3CEndpointReference
+ *
+ * @since JAX-WS 2.1
+ **/
+ public abstract EndpointReference getEndpointReference(Element... referenceParameters);
+
+
+ /**
+ * Returns the <code>EndpointReference</code> associated with
+ * this <code>Endpoint</code> instance.
+ *
+ * @param clazz Specifies the type of EndpointReference that MUST be returned.
+ * @param referenceParameters Reference parameters to be associated with the
+ * returned <code>EndpointReference</code> instance.
+ * @return EndpointReference of type <code>clazz</code> of this
+ * <code>Endpoint<code> instance.
+ * If the returned <code>EndpointReference</code> is of type
+ * <code>W3CEndpointReference</code> then it MUST contain the
+ * the specified <code>referenceParameters</code>.
+
+ * @throws WebServiceException If any error in the creation of
+ * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
+ * not in the published state or if the <code>clazz</code> is not a supported
+ * <code>EndpointReference</code> type.
+ * @throws UnsupportedOperationException If this <code>BindingProvider</code>
+ * uses the XML/HTTP binding.
+ *
+ *
+ * @since JAX-WS 2.1
+ **/
+ public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
+ Element... referenceParameters);
}