--- old/src/java.xml.ws/share/classes/javax/xml/ws/wsaddressing/W3CEndpointReferenceBuilder.java 2015-07-09 12:14:20.000000000 +0200 +++ new/src/java.xml.ws/share/classes/javax/xml/ws/wsaddressing/W3CEndpointReferenceBuilder.java 2015-07-09 12:14:20.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 @@ -38,35 +38,35 @@ /** - * This class is used to build W3CEndpointReference + * This class is used to build {@code W3CEndpointReference} * instances. The intended use of this clsss is for * an application component, for example a factory component, - * to create an W3CEndpointReference for a + * to create an {@code W3CEndpointReference} for a * web service endpoint published by the same * Java EE application. It can also be used to create - * W3CEndpointReferences for an Java SE based - * endpoint by providing the address property. + * {@code W3CEndpointReferences} for an Java SE based + * endpoint by providing the {@code address} property. *

- * When creating a W3CEndpointReference for an + * When creating a {@code W3CEndpointReference} for an * endpoint that is not published by the same Java EE application, - * the address property MUST be specified. + * the {@code address} property MUST be specified. *

- * When creating a W3CEndpointReference for an endpoint - * published by the same Java EE application, the address - * property MAY be null but then the serviceName - * and endpointName MUST specify an endpoint published by + * When creating a {@code W3CEndpointReference} for an endpoint + * published by the same Java EE application, the {@code address} + * property MAY be {@code null} but then the {@code serviceName} + * and {@code endpointName} MUST specify an endpoint published by * the same Java EE application. *

- * When the wsdlDocumentLocation is specified it MUST refer - * to a valid WSDL document and the serviceName and - * endpointName (if specified) MUST match a service and port + * When the {@code wsdlDocumentLocation} is specified it MUST refer + * to a valid WSDL document and the {@code serviceName} and + * {@code endpointName} (if specified) MUST match a service and port * in the WSDL document. * * @since 1.6, JAX-WS 2.1 */ public final class W3CEndpointReferenceBuilder { /** - * Creates a new W3CEndpointReferenceBuilder instance. + * Creates a new {@code W3CEndpointReferenceBuilder} instance. */ public W3CEndpointReferenceBuilder() { referenceParameters = new ArrayList(); @@ -76,20 +76,20 @@ } /** - * Sets the address to the - * W3CEndpointReference instance's - * wsa:Address. + * Sets the {@code address} to the + * {@code W3CEndpointReference} instance's + * {@code wsa:Address}. *

- * The address MUST be set to a non-null - * value when building a W3CEndpointReference for a + * The {@code address} MUST be set to a non-{@code null} + * value when building a {@code W3CEndpointReference} for a * web service endpoint that is not published by the same * Java EE application or when running on Java SE. * * @param address The address of the endpoint to be targeted - * by the returned W3CEndpointReference. + * by the returned {@code W3CEndpointReference}. * - * @return A W3CEndpointReferenceBuilder instance with - * the address set to the wsa:Address. + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code address} set to the {@code wsa:Address}. */ public W3CEndpointReferenceBuilder address(String address) { this.address = address; @@ -97,19 +97,19 @@ } /** - * Sets the interfaceName as the - * wsam:InterfaceName element in the - * wsa:Metadata element. + * Sets the {@code interfaceName} as the + * {@code wsam:InterfaceName} element in the + * {@code wsa:Metadata} element. * * See * 2.1 Referencing WSDL Metadata from an EPR for more details. * * @param interfaceName The port type name of the endpoint to be targeted - * by the returned W3CEndpointReference. + * by the returned {@code W3CEndpointReference}. * - * @return A W3CEndpointReferenceBuilder instance with - * the interfaceName as wsam:InterfaceName - * element added to the wsa:Metadata element + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code interfaceName} as {@code wsam:InterfaceName} + * element added to the {@code wsa:Metadata} element * @since 1.7 */ public W3CEndpointReferenceBuilder interfaceName(QName interfaceName) { @@ -118,22 +118,22 @@ } /** - * Sets the serviceName as the - * wsam:ServiceName element in the - * wsa:Metadata element. + * Sets the {@code serviceName} as the + * {@code wsam:ServiceName} element in the + * {@code wsa:Metadata} element. * * See * 2.1 Referencing WSDL Metadata from an EPR for more details. * * @param serviceName The service name of the endpoint to be targeted - * by the returned W3CEndpointReference. This property - * may also be used with the endpointName (portName) - * property to lookup the address of a web service + * by the returned {@code W3CEndpointReference}. This property + * may also be used with the {@code endpointName} (portName) + * property to lookup the {@code address} of a web service * endpoint that is published by the same Java EE application. * - * @return A W3CEndpointReferenceBuilder instance with - * the serviceName as wsam:ServiceName - * element added to the wsa:Metadata element + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code serviceName} as {@code wsam:ServiceName} + * element added to the {@code wsa:Metadata} element * */ public W3CEndpointReferenceBuilder serviceName(QName serviceName) { @@ -142,30 +142,31 @@ } /** - * Sets the endpointName as - * wsam:ServiceName/@EndpointName in the - * wsa:Metadata element. This method can only be called + * Sets the {@code endpointName} as + * {@code wsam:ServiceName/@EndpointName} in the + * {@code wsa:Metadata} element. This method can only be called * after the {@link #serviceName} method has been called. *

* See * 2.1 Referencing WSDL Metadata from an EPR for more details. * * @param endpointName The name of the endpoint to be targeted - * by the returned W3CEndpointReference. The - * endpointName (portName) property may also be - * used with the serviceName property to lookup - * the address of a web service + * by the returned {@code W3CEndpointReference}. The + * {@code endpointName} (portName) property may also be + * used with the {@code serviceName} property to lookup + * the {@code address} of a web service * endpoint published by the same Java EE application. * - * @return A W3CEndpointReferenceBuilder instance with - * the endpointName as - * wsam:ServiceName/@EndpointName in the - * wsa:Metadata element. - * - * @throws IllegalStateException, if the serviceName - * has not been set. - * @throws IllegalArgumentException, if the endpointName's - * Namespace URI doesn't match serviceName's Namespace URI + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code endpointName} as + * {@code wsam:ServiceName/@EndpointName} in the + * {@code wsa:Metadata} element. + * + * @throws java.lang.IllegalStateException if the {@code serviceName} + * has not been set + * + * @throws java.lang.IllegalArgumentException if the {@code endpointName}'s + * Namespace URI doesn't match {@code serviceName}'s Namespace URI * */ public W3CEndpointReferenceBuilder endpointName(QName endpointName) { @@ -178,8 +179,8 @@ } /** - * Sets the wsdlDocumentLocation that will be referenced - * as wsa:Metadata/@wsdli:wsdlLocation. The namespace name + * Sets the {@code wsdlDocumentLocation} that will be referenced + * as {@code wsa:Metadata/@wsdli:wsdlLocation}. The namespace name * for the wsdli:wsdlLocation's value can be taken from the WSDL itself. * *

@@ -187,10 +188,10 @@ * 2.1 Referencing WSDL Metadata from an EPR for more details. * * @param wsdlDocumentLocation The location of the WSDL document to - * be referenced in the wsa:Metadata of the - * W3CEndpointReference. - * @return A W3CEndpointReferenceBuilder instance with - * the wsdlDocumentLocation that is to be referenced. + * be referenced in the {@code wsa:Metadata} of the + * {@code W3CEndpointReference}. + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code wsdlDocumentLocation} that is to be referenced. */ public W3CEndpointReferenceBuilder wsdlDocumentLocation(String wsdlDocumentLocation) { this.wsdlDocumentLocation = wsdlDocumentLocation; @@ -198,19 +199,19 @@ } /** - * Adds the referenceParameter to the - * W3CEndpointReference instance - * wsa:ReferenceParameters element. + * Adds the {@code referenceParameter} to the + * {@code W3CEndpointReference} instance + * {@code wsa:ReferenceParameters} element. * * @param referenceParameter The element to be added to the - * wsa:ReferenceParameters element. + * {@code wsa:ReferenceParameters} element. * - * @return A W3CEndpointReferenceBuilder instance with - * the referenceParameter added to the - * wsa:ReferenceParameters element. + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code referenceParameter} added to the + * {@code wsa:ReferenceParameters} element. * - * @throws java.lang.IllegalArgumentException if referenceParameter - * is null. + * @throws java.lang.IllegalArgumentException if {@code referenceParameter} + * is {@code null}. */ public W3CEndpointReferenceBuilder referenceParameter(Element referenceParameter) { if (referenceParameter == null) @@ -220,19 +221,19 @@ } /** - * Adds the metadataElement to the - * W3CEndpointReference instance's - * wsa:Metadata element. + * Adds the {@code metadataElement} to the + * {@code W3CEndpointReference} instance's + * {@code wsa:Metadata} element. * * @param metadataElement The element to be added to the - * wsa:Metadata element. + * {@code wsa:Metadata} element. * - * @return A W3CEndpointReferenceBuilder instance with - * the metadataElement added to the - * wsa:Metadata element. + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the {@code metadataElement} added to the + * {@code wsa:Metadata} element. * - * @throws java.lang.IllegalArgumentException if metadataElement - * is null. + * @throws java.lang.IllegalArgumentException if {@code metadataElement} + * is {@code null}. */ public W3CEndpointReferenceBuilder metadata(Element metadataElement) { if (metadataElement == null) @@ -243,16 +244,16 @@ /** * Adds an extension element to the - * W3CEndpointReference instance's - * wsa:EndpointReference element. + * {@code W3CEndpointReference} instance's + * {@code wsa:EndpointReference} element. * * @param element The extension element to be added to the - * W3CEndpointReference - * @return A W3CEndpointReferenceBuilder instance with - * the extension element added to the - * W3CEndpointReference instance. - * @throws java.lang.IllegalArgumentException if element - * is null. + * {@code W3CEndpointReference} + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the extension {@code element} added to the + * {@code W3CEndpointReference} instance. + * @throws java.lang.IllegalArgumentException if {@code element} + * is {@code null}. * * @since 1.7, JAX-WS 2.2 */ @@ -266,17 +267,17 @@ /** * Adds an extension attribute to the - * W3CEndpointReference instance's - * wsa:EndpointReference element. + * {@code W3CEndpointReference} instance's + * {@code wsa:EndpointReference} element. * * @param name The name of the extension attribute to be added to the - * W3CEndpointReference + * {@code W3CEndpointReference} * @param value extension attribute value - * @return A W3CEndpointReferenceBuilder instance with - * the extension attribute added to the W3CEndpointReference + * @return A {@code W3CEndpointReferenceBuilder} instance with + * the extension attribute added to the {@code W3CEndpointReference} * instance. - * @throws java.lang.IllegalArgumentException if name - * or value is null. + * @throws java.lang.IllegalArgumentException if {@code name} + * or {@code value} is {@code null}. * * @since 1.7, JAX-WS 2.2 */ @@ -289,48 +290,48 @@ } /** - * Builds a W3CEndpointReference from the accumulated - * properties set on this W3CEndpointReferenceBuilder + * Builds a {@code W3CEndpointReference} from the accumulated + * properties set on this {@code W3CEndpointReferenceBuilder} * instance. *

- * This method can be used to create a W3CEndpointReference - * for any endpoint by specifying the address property along + * This method can be used to create a {@code W3CEndpointReference} + * for any endpoint by specifying the {@code address} property along * with any other desired properties. This method - * can also be used to create a W3CEndpointReference for + * can also be used to create a {@code W3CEndpointReference} for * an endpoint that is published by the same Java EE application. - * This method can automatically determine the address of + * This method can automatically determine the {@code address} of * an endpoint published by the same Java EE application that is identified by the - * serviceName and - * endpointName properties. If the address is - * null and the serviceName and - * endpointName + * {@code serviceName} and + * {@code endpointName} properties. If the {@code address} is + * {@code null} and the {@code serviceName} and + * {@code endpointName} * do not identify an endpoint published by the same Java EE application, a - * java.lang.IllegalStateException MUST be thrown. + * {@code java.lang.IllegalStateException} MUST be thrown. * * - * @return W3CEndpointReference from the accumulated - * properties set on this W3CEndpointReferenceBuilder - * instance. This method never returns null. + * @return {@code W3CEndpointReference} from the accumulated + * properties set on this {@code W3CEndpointReferenceBuilder} + * instance. This method never returns {@code null}. * * @throws IllegalStateException *

* @throws WebServiceException If an error occurs while creating the - * W3CEndpointReference. + * {@code W3CEndpointReference}. * */ public W3CEndpointReference build() {