--- old/src/java.xml.ws/share/classes/javax/xml/ws/Service.java 2015-07-08 13:25:25.000000000 +0200 +++ new/src/java.xml.ws/share/classes/javax/xml/ws/Service.java 2015-07-08 13:25:25.000000000 +0200 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -33,8 +33,8 @@ import javax.xml.ws.spi.Provider; /** - * Service objects provide the client view of a Web service. - *

Service acts as a factory of the following: + * {@code Service} objects provide the client view of a Web service. + *

{@code Service} acts as a factory of the following: *

* *

The ports available on a service can be enumerated using the - * getPorts method. Alternatively, you can pass a - * service endpoint interface to the unary getPort method + * {@code getPorts} method. Alternatively, you can pass a + * service endpoint interface to the unary {@code getPort} method * and let the runtime select a compatible port. * - *

Handler chains for all the objects created by a Service - * can be set by means of a HandlerResolver. + *

Handler chains for all the objects created by a {@code Service} + * can be set by means of a {@code HandlerResolver}. * - *

An Executor may be set on the service in order + *

An {@code Executor} may be set on the service in order * to gain better control over the threads used to dispatch asynchronous * callbacks. For instance, thread pooling with certain parameters - * can be enabled by creating a ThreadPoolExecutor and + * can be enabled by creating a {@code ThreadPoolExecutor} and * registering it with the service. * * @since 1.6, JAX-WS 2.0 @@ -67,8 +67,8 @@ private ServiceDelegate delegate; /** - * The orientation of a dynamic client or service. MESSAGE provides - * access to entire protocol message, PAYLOAD to protocol message + * The orientation of a dynamic client or service. {@code MESSAGE} provides + * access to entire protocol message, {@code PAYLOAD} to protocol message * payload only. **/ public enum Mode { MESSAGE, PAYLOAD } @@ -87,9 +87,9 @@ /** - * The getPort method returns a proxy. A service client + * The {@code getPort} method returns a proxy. A service client * uses this proxy to invoke operations on the target - * service endpoint. The serviceEndpointInterface + * service endpoint. The {@code serviceEndpointInterface} * specifies the service endpoint interface that is supported by * the created dynamic proxy instance. * @@ -108,8 +108,8 @@ *

  • If there is any missing WSDL metadata * as required by this method. *
  • If an illegal - * serviceEndpointInterface - * or portName is specified. + * {@code serviceEndpointInterface} + * or {@code portName} is specified. * * @see java.lang.reflect.Proxy * @see java.lang.reflect.InvocationHandler @@ -120,9 +120,9 @@ } /** - * The getPort method returns a proxy. A service client + * The {@code getPort} method returns a proxy. A service client * uses this proxy to invoke operations on the target - * service endpoint. The serviceEndpointInterface + * service endpoint. The {@code serviceEndpointInterface} * specifies the service endpoint interface that is supported by * the created dynamic proxy instance. * @@ -131,8 +131,8 @@ * @param serviceEndpointInterface Service endpoint interface * supported by the dynamic proxy instance. * @param features A list of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * @return Object Proxy instance that * supports the specified service endpoint * interface. @@ -144,8 +144,8 @@ *
  • If there is any missing WSDL metadata * as required by this method. *
  • If an illegal - * serviceEndpointInterface - * or portName is specified. + * {@code serviceEndpointInterface} + * or {@code portName} is specified. *
  • If a feature is enabled that is not compatible * with this port or is unsupported. * @@ -162,8 +162,8 @@ /** - * The getPort method returns a proxy. The parameter - * serviceEndpointInterface specifies the service + * The {@code getPort} method returns a proxy. The parameter + * {@code serviceEndpointInterface} specifies the service * endpoint interface that is supported by the returned proxy. * In the implementation of this method, the JAX-WS * runtime system takes the responsibility of selecting a protocol @@ -180,7 +180,7 @@ *
  • If there is any missing WSDL metadata * as required by this method. *
  • If an illegal - * serviceEndpointInterface + * {@code serviceEndpointInterface} * is specified. * **/ @@ -190,8 +190,8 @@ /** - * The getPort method returns a proxy. The parameter - * serviceEndpointInterface specifies the service + * The {@code getPort} method returns a proxy. The parameter + * {@code serviceEndpointInterface} specifies the service * endpoint interface that is supported by the returned proxy. * In the implementation of this method, the JAX-WS * runtime system takes the responsibility of selecting a protocol @@ -200,8 +200,8 @@ * * @param serviceEndpointInterface Service endpoint interface. * @param features A list of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * @return Object instance that supports the * specified service endpoint interface. * @throws WebServiceException @@ -211,7 +211,7 @@ *
  • If there is any missing WSDL metadata * as required by this method. *
  • If an illegal - * serviceEndpointInterface + * {@code serviceEndpointInterface} * is specified. *
  • If a feature is enabled that is not compatible * with this port or is unsupported. @@ -228,31 +228,31 @@ /** - * The getPort method returns a proxy. - * The parameter endpointReference specifies the + * The {@code getPort} method returns a proxy. + * The parameter {@code endpointReference} specifies the * endpoint that will be invoked by the returned proxy. If there * are any reference parameters in the - * endpointReference, then those reference + * {@code endpointReference}, then those reference * parameters MUST appear as SOAP headers, indicating them to be * reference parameters, on all messages sent to the endpoint. - * The endpointReference's address MUST be used + * The {@code endpointReference's} address MUST be used * for invocations on the endpoint. - * The parameter serviceEndpointInterface specifies + * The parameter {@code serviceEndpointInterface} specifies * the service endpoint interface that is supported by the * returned proxy. * In the implementation of this method, the JAX-WS * runtime system takes the responsibility of selecting a protocol * binding (and a port) and configuring the proxy accordingly from - * the WSDL associated with this Service instance or - * from the metadata from the endpointReference. - * If this Service instance has a WSDL and - * the endpointReference metadata + * the WSDL associated with this {@code Service} instance or + * from the metadata from the {@code endpointReference}. + * If this {@code Service} instance has a WSDL and + * the {@code endpointReference} metadata * also has a WSDL, then the WSDL from this instance MUST be used. - * If this Service instance does not have a WSDL and - * the endpointReference does have a WSDL, then the - * WSDL from the endpointReference MAY be used. + * If this {@code Service} instance does not have a WSDL and + * the {@code endpointReference} does have a WSDL, then the + * WSDL from the {@code endpointReference} MAY be used. * The returned proxy should not be reconfigured by the client. - * If this Service instance has a known proxy + * If this {@code Service} instance has a known proxy * port that matches the information contained in * the WSDL, * then that proxy is returned, otherwise a WebServiceException @@ -260,20 +260,20 @@ *

    * Calling this method has the same behavior as the following * 

    -     * port = service.getPort(portName, serviceEndpointInterface);
+     * {@code port = service.getPort(portName, serviceEndpointInterface);}
      *
    - * where the portName is retrieved from the - * metadata of the endpointReference or from the - * serviceEndpointInterface and the WSDL - * associated with this Service instance. + * where the {@code portName} is retrieved from the + * metadata of the {@code endpointReference} or from the + * {@code serviceEndpointInterface} and the WSDL + * associated with this {@code Service} instance. * - * @param endpointReference The EndpointReference + * @param endpointReference The {@code EndpointReference} * for the target service endpoint that will be invoked by the * returned proxy. * @param serviceEndpointInterface Service endpoint interface. - * @param features A list of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * @param features A list of {@code WebServiceFeatures} to configure on the + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * @return Object Proxy instance that supports the * specified service endpoint interface. * @throws WebServiceException @@ -282,16 +282,16 @@ * of the proxy. *
  • If there is any missing WSDL metadata * as required by this method. - *
  • If the endpointReference metadata does - * not match the serviceName of this - * Service instance. - *
  • If a portName cannot be extracted - * from the WSDL or endpointReference metadata. + *
  • If the {@code endpointReference} metadata does + * not match the {@code serviceName} of this + * {@code Service} instance. + *
  • If a {@code portName} cannot be extracted + * from the WSDL or {@code endpointReference} metadata. *
  • If an invalid - * endpointReference + * {@code endpointReference} * is specified. *
  • If an invalid - * serviceEndpointInterface + * {@code serviceEndpointInterface} * is specified. *
  • If a feature is enabled that is not compatible * with this port or is unsupported. @@ -307,7 +307,7 @@ /** * Creates a new port for the service. Ports created in this way contain * no WSDL port type information and can only be used for creating - * Dispatchinstances. + * {@code Dispatch}instances. * * @param portName Qualified name for the target service endpoint. * @param bindingId A String identifier of a binding. @@ -325,14 +325,14 @@ /** - * Creates a Dispatch instance for use with objects of + * Creates a {@code Dispatch} instance for use with objects of * the client's choosing. * * @param portName Qualified name for the target service endpoint * @param type The class of object used for messages or message * payloads. Implementations are required to support - * javax.xml.transform.Source, javax.xml.soap.SOAPMessage - * and javax.activation.DataSource, depending on + * {@code javax.xml.transform.Source}, {@code javax.xml.soap.SOAPMessage} + * and {@code javax.activation.DataSource}, depending on * the binding in use. * @param mode Controls whether the created dispatch instance is message * or payload oriented, i.e. whether the client will work with complete @@ -343,7 +343,7 @@ * * @return Dispatch instance. * @throws WebServiceException If any error in the creation of - * the Dispatch object. + * the {@code Dispatch} object. * * @see javax.xml.transform.Source * @see javax.xml.soap.SOAPMessage @@ -354,26 +354,26 @@ /** - * Creates a Dispatch instance for use with objects of + * Creates a {@code Dispatch} instance for use with objects of * the client's choosing. * * @param portName Qualified name for the target service endpoint * @param type The class of object used for messages or message * payloads. Implementations are required to support - * javax.xml.transform.Source and javax.xml.soap.SOAPMessage. + * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}. * @param mode Controls whether the created dispatch instance is message * or payload oriented, i.e. whether the client will work with complete * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the client will work with - * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE - * when type is SOAPMessage. - * @param features A list of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE} + * when type is {@code SOAPMessage}. + * @param features A list of {@code WebServiceFeatures} to configure on the + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * * @return Dispatch instance. * @throws WebServiceException If any error in the creation of - * the Dispatch object or if a + * the {@code Dispatch} object or if a * feature is enabled that is not compatible with * this port or is unsupported. * @@ -390,64 +390,64 @@ /** - * Creates a Dispatch instance for use with objects of + * Creates a {@code Dispatch} instance for use with objects of * the client's choosing. If there * are any reference parameters in the - * endpointReference, then those reference + * {@code endpointReference}, then those reference * parameters MUST appear as SOAP headers, indicating them to be * reference parameters, on all messages sent to the endpoint. - * The endpointReference's address MUST be used + * The {@code endpointReference's} address MUST be used * for invocations on the endpoint. * In the implementation of this method, the JAX-WS * runtime system takes the responsibility of selecting a protocol * binding (and a port) and configuring the dispatch accordingly from - * the WSDL associated with this Service instance or - * from the metadata from the endpointReference. - * If this Service instance has a WSDL and - * the endpointReference + * the WSDL associated with this {@code Service} instance or + * from the metadata from the {@code endpointReference}. + * If this {@code Service} instance has a WSDL and + * the {@code endpointReference} * also has a WSDL in its metadata, then the WSDL from this instance MUST be used. - * If this Service instance does not have a WSDL and - * the endpointReference does have a WSDL, then the - * WSDL from the endpointReference MAY be used. - * An implementation MUST be able to retrieve the portName from the - * endpointReference metadata. + * If this {@code Service} instance does not have a WSDL and + * the {@code endpointReference} does have a WSDL, then the + * WSDL from the {@code endpointReference} MAY be used. + * An implementation MUST be able to retrieve the {@code portName} from the + * {@code endpointReference} metadata. *

    * This method behaves the same as calling * 

    -     * dispatch = service.createDispatch(portName, type, mode, features);
+     * {@code dispatch = service.createDispatch(portName, type, mode, features);}
      *
    - * where the portName is retrieved from the - * WSDL or EndpointReference metadata. + * where the {@code portName} is retrieved from the + * WSDL or {@code EndpointReference} metadata. * - * @param endpointReference The EndpointReference + * @param endpointReference The {@code EndpointReference} * for the target service endpoint that will be invoked by the - * returned Dispatch object. + * returned {@code Dispatch} object. * @param type The class of object used to messages or message * payloads. Implementations are required to support - * javax.xml.transform.Source and javax.xml.soap.SOAPMessage. + * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}. * @param mode Controls whether the created dispatch instance is message * or payload oriented, i.e. whether the client will work with complete * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the client will work with - * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE - * when type is SOAPMessage. - * @param features An array of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE} + * when type is {@code SOAPMessage}. + * @param features An array of {@code WebServiceFeatures} to configure on the + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * * @return Dispatch instance * @throws WebServiceException * @@ -465,7 +465,7 @@ } /** - * Creates a Dispatch instance for use with JAXB + * Creates a {@code Dispatch} instance for use with JAXB * generated objects. * * @param portName Qualified name for the target service endpoint @@ -479,7 +479,7 @@ * * @return Dispatch instance. * @throws WebServiceException If any error in the creation of - * the Dispatch object. + * the {@code Dispatch} object. * * @see javax.xml.bind.JAXBContext **/ @@ -490,7 +490,7 @@ /** - * Creates a Dispatch instance for use with JAXB + * Creates a {@code Dispatch} instance for use with JAXB * generated objects. * * @param portName Qualified name for the target service endpoint @@ -501,13 +501,13 @@ * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the client will work with * SOAP messages or the contents of a SOAP body. - * @param features A list of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * @param features A list of {@code WebServiceFeatures} to configure on the + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * * @return Dispatch instance. * @throws WebServiceException If any error in the creation of - * the Dispatch object or if a + * the {@code Dispatch} object or if a * feature is enabled that is not compatible with * this port or is unsupported. * @@ -523,39 +523,39 @@ /** - * Creates a Dispatch instance for use with JAXB + * Creates a {@code Dispatch} instance for use with JAXB * generated objects. If there * are any reference parameters in the - * endpointReference, then those reference + * {@code endpointReference}, then those reference * parameters MUST appear as SOAP headers, indicating them to be * reference parameters, on all messages sent to the endpoint. - * The endpointReference's address MUST be used + * The {@code endpointReference's} address MUST be used * for invocations on the endpoint. * In the implementation of this method, the JAX-WS * runtime system takes the responsibility of selecting a protocol * binding (and a port) and configuring the dispatch accordingly from - * the WSDL associated with this Service instance or - * from the metadata from the endpointReference. - * If this Service instance has a WSDL and - * the endpointReference + * the WSDL associated with this {@code Service} instance or + * from the metadata from the {@code endpointReference}. + * If this {@code Service} instance has a WSDL and + * the {@code endpointReference} * also has a WSDL in its metadata, then the WSDL from this instance * MUST be used. - * If this Service instance does not have a WSDL and - * the endpointReference does have a WSDL, then the - * WSDL from the endpointReference MAY be used. - * An implementation MUST be able to retrieve the portName from the - * endpointReference metadata. + * If this {@code Service} instance does not have a WSDL and + * the {@code endpointReference} does have a WSDL, then the + * WSDL from the {@code endpointReference} MAY be used. + * An implementation MUST be able to retrieve the {@code portName} from the + * {@code endpointReference} metadata. *

    * This method behavies the same as calling * 

    -     * dispatch = service.createDispatch(portName, context, mode, features);
+     * {@code dispatch = service.createDispatch(portName, context, mode, features);}
      *
    - * where the portName is retrieved from the - * WSDL or endpointReference metadata. + * where the {@code portName} is retrieved from the + * WSDL or {@code endpointReference} metadata. * - * @param endpointReference The EndpointReference + * @param endpointReference The {@code EndpointReference} * for the target service endpoint that will be invoked by the - * returned Dispatch object. + * returned {@code Dispatch} object. * @param context The JAXB context used to marshall and unmarshall * messages or message payloads. * @param mode Controls whether the created dispatch instance is message @@ -563,23 +563,23 @@ * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the client will work with * SOAP messages or the contents of a SOAP body. - * @param features An array of WebServiceFeatures to configure on the - * proxy. Supported features not in the features - * parameter will have their default values. + * @param features An array of {@code WebServiceFeatures} to configure on the + * proxy. Supported features not in the {@code features + * } parameter will have their default values. * * @return Dispatch instance * @throws WebServiceException * @@ -604,12 +604,12 @@ } /** - * Returns an Iterator for the list of - * QNames of service endpoints grouped by this + * Returns an {@code Iterator} for the list of + * {@code QName}s of service endpoints grouped by this * service * - * @return Returns java.util.Iterator with elements - * of type javax.xml.namespace.QName. + * @return Returns {@code java.util.Iterator} with elements + * of type {@code javax.xml.namespace.QName}. * @throws WebServiceException If this Service class does not * have access to the required WSDL metadata. **/ @@ -630,8 +630,8 @@ /** * Returns the configured handler resolver. * - * @return HandlerResolver The HandlerResolver being - * used by this Service instance, or null + * @return HandlerResolver The {@code HandlerResolver} being + * used by this {@code Service} instance, or {@code null} * if there isn't one. **/ public HandlerResolver getHandlerResolver() { @@ -639,14 +639,14 @@ } /** - * Sets the HandlerResolver for this Service + * Sets the {@code HandlerResolver} for this {@code Service} * instance. *

    * The handler resolver, if present, will be called once for each * proxy or dispatch instance that is created, and the handler chain * returned by the resolver will be set on the instance. * - * @param handlerResolver The HandlerResolver to use + * @param handlerResolver The {@code HandlerResolver} to use * for all subsequently created proxy/dispatch objects. * * @see javax.xml.ws.handler.HandlerResolver @@ -656,12 +656,12 @@ } /** - * Returns the executor for this Serviceinstance. + * Returns the executor for this {@code Service}instance. * * The executor is used for all asynchronous invocations that * require callbacks. * - * @return The java.util.concurrent.Executor to be + * @return The {@code java.util.concurrent.Executor} to be * used to invoke a callback. * * @see java.util.concurrent.Executor @@ -671,12 +671,12 @@ } /** - * Sets the executor for this Service instance. + * Sets the executor for this {@code Service} instance. * * The executor is used for all asynchronous invocations that * require callbacks. * - * @param executor The java.util.concurrent.Executor + * @param executor The {@code java.util.concurrent.Executor} * to be used to invoke a callback. * * @throws SecurityException If the instance does not support @@ -690,14 +690,14 @@ } /** - * Creates a Service instance. + * Creates a {@code Service} instance. * * The specified WSDL document location and service qualified name MUST - * uniquely identify a wsdl:service element. + * uniquely identify a {@code wsdl:service} element. * - * @param wsdlDocumentLocation URL for the WSDL document location + * @param wsdlDocumentLocation {@code URL} for the WSDL document location * for the service - * @param serviceName QName for the service + * @param serviceName {@code QName} for the service * @throws WebServiceException If any error in creation of the * specified service. **/ @@ -708,15 +708,15 @@ } /** - * Creates a Service instance. The created instance is + * Creates a {@code Service} instance. The created instance is * configured with the web service features. * * The specified WSDL document location and service qualified name MUST - * uniquely identify a wsdl:service element. + * uniquely identify a {@code wsdl:service} element. * - * @param wsdlDocumentLocation URL for the WSDL document location + * @param wsdlDocumentLocation {@code URL} for the WSDL document location * for the service - * @param serviceName QName for the service + * @param serviceName {@code QName} for the service * @param features Web Service features that must be configured on * the service. If the provider doesn't understand a feature, * it must throw a WebServiceException. @@ -731,9 +731,9 @@ } /** - * Creates a Service instance. + * Creates a {@code Service} instance. * - * @param serviceName QName for the service + * @param serviceName {@code QName} for the service * @throws WebServiceException If any error in creation of the * specified service */ @@ -742,10 +742,10 @@ } /** - * Creates a Service instance. The created instance is + * Creates a {@code Service} instance. The created instance is * configured with the web service features. * - * @param serviceName QName for the service + * @param serviceName {@code QName} for the service * @param features Web Service features that must be configured on * the service. If the provider doesn't understand a feature, * it must throw a WebServiceException.