Module java.xml.ws
Package javax.xml.ws.wsaddressing

## Class W3CEndpointReferenceBuilder

- java.lang.Object
- - javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilder

-     public final class W3CEndpointReferenceBuilder
      extends Object

  This class is used to build `W3CEndpointReference` instances. The intended use of this clsss is for an application component, for example a factory component, to create an `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.

  When creating a `W3CEndpointReference` for an endpoint that is not published by the same Java EE application, the `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 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 in the WSDL document.

  Since:
    1.6, JAX-WS 2.1

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `W3CEndpointReferenceBuilder​()` | Creates a new `W3CEndpointReferenceBuilder` instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `W3CEndpointReferenceBuilder` | `address​(String address)` | Sets the `address` to the `W3CEndpointReference` instance's `wsa:Address`.
    `W3CEndpointReferenceBuilder` | `attribute​(QName name, String value)` | Adds an extension attribute to the `W3CEndpointReference` instance's `wsa:EndpointReference` element.
    `W3CEndpointReference` | `build​()` | Builds a `W3CEndpointReference` from the accumulated properties set on this `W3CEndpointReferenceBuilder` instance.
    `W3CEndpointReferenceBuilder` | `element​(Element element)` | Adds an extension element to the `W3CEndpointReference` instance's `wsa:EndpointReference` element.
    `W3CEndpointReferenceBuilder` | `endpointName​(QName endpointName)` | Sets the `endpointName` as `wsam:ServiceName/@EndpointName` in the `wsa:Metadata` element.
    `W3CEndpointReferenceBuilder` | `interfaceName​(QName interfaceName)` | Sets the `interfaceName` as the `wsam:InterfaceName` element in the `wsa:Metadata` element.
    `W3CEndpointReferenceBuilder` | `metadata​(Element metadataElement)` | Adds the `metadataElement` to the `W3CEndpointReference` instance's `wsa:Metadata` element.
    `W3CEndpointReferenceBuilder` | `referenceParameter​(Element referenceParameter)` | Adds the `referenceParameter` to the `W3CEndpointReference` instance `wsa:ReferenceParameters` element.
    `W3CEndpointReferenceBuilder` | `serviceName​(QName serviceName)` | Sets the `serviceName` as the `wsam:ServiceName` element in the `wsa:Metadata` element.
    `W3CEndpointReferenceBuilder` | `wsdlDocumentLocation​(String wsdlDocumentLocation)` | Sets the `wsdlDocumentLocation` that will be referenced as `wsa:Metadata/@wsdli:wsdlLocation`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### W3CEndpointReferenceBuilder

          public W3CEndpointReferenceBuilder​()

      Creates a new `W3CEndpointReferenceBuilder` instance.

  - ### Method Detail

    - #### address

          public W3CEndpointReferenceBuilder address​(String address)

      Sets the `address` to the `W3CEndpointReference` instance's `wsa:Address`.

      The `address` MUST be set to a non-`null` value when building a `W3CEndpointReference` for a web service endpoint that is not published by the same Java EE application or when running on Java SE.

      Parameters:
        `address` - The address of the endpoint to be targeted by the returned `W3CEndpointReference`.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `address` set to the `wsa:Address`.

    - #### interfaceName

          public W3CEndpointReferenceBuilder interfaceName​(QName interfaceName)

      Sets the `interfaceName` as the `wsam:InterfaceName` element in the `wsa:Metadata` element. See 2.1 Referencing WSDL Metadata from an EPR for more details.
      Parameters:
        `interfaceName` - The port type name of the endpoint to be targeted by the returned `W3CEndpointReference`.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `interfaceName` as `wsam:InterfaceName` element added to the `wsa:Metadata` element
      Since:
        1.7

    - #### serviceName

          public W3CEndpointReferenceBuilder serviceName​(QName serviceName)

      Sets the `serviceName` as the `wsam:ServiceName` element in the `wsa:Metadata` element. See 2.1 Referencing WSDL Metadata from an EPR for more details.
      Parameters:
        `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 endpoint that is published by the same Java EE application.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `serviceName` as `wsam:ServiceName` element added to the `wsa:Metadata` element

    - #### endpointName

          public W3CEndpointReferenceBuilder endpointName​(QName endpointName)

      Sets the `endpointName` as `wsam:ServiceName/@EndpointName` in the `wsa:Metadata` element. This method can only be called after the `serviceName` method has been called.

      See 2.1 Referencing WSDL Metadata from an EPR for more details.

      Parameters:
        `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 endpoint published by the same Java EE application.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `endpointName` as `wsam:ServiceName/@EndpointName` in the `wsa:Metadata` element.
      Throws:
        `IllegalStateException` - if the `serviceName` has not been set
        `IllegalArgumentException` - if the `endpointName`'s Namespace URI doesn't match `serviceName`'s Namespace URI

    - #### wsdlDocumentLocation

          public W3CEndpointReferenceBuilder wsdlDocumentLocation​(String wsdlDocumentLocation)

      Sets the `wsdlDocumentLocation` that will be referenced as `wsa:Metadata/@wsdli:wsdlLocation`. The namespace name for the wsdli:wsdlLocation's value can be taken from the WSDL itself.

      See 2.1 Referencing WSDL Metadata from an EPR for more details.

      Parameters:
        `wsdlDocumentLocation` - The location of the WSDL document to be referenced in the `wsa:Metadata` of the `W3CEndpointReference`.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `wsdlDocumentLocation` that is to be referenced.

    - #### referenceParameter

          public W3CEndpointReferenceBuilder referenceParameter​(Element referenceParameter)

      Adds the `referenceParameter` to the `W3CEndpointReference` instance `wsa:ReferenceParameters` element.
      Parameters:
        `referenceParameter` - The element to be added to the `wsa:ReferenceParameters` element.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `referenceParameter` added to the `wsa:ReferenceParameters` element.
      Throws:
        `IllegalArgumentException` - if `referenceParameter` is `null`.

    - #### metadata

          public W3CEndpointReferenceBuilder metadata​(Element metadataElement)

      Adds the `metadataElement` to the `W3CEndpointReference` instance's `wsa:Metadata` element.
      Parameters:
        `metadataElement` - The element to be added to the `wsa:Metadata` element.
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the `metadataElement` added to the `wsa:Metadata` element.
      Throws:
        `IllegalArgumentException` - if `metadataElement` is `null`.

    - #### element

          public W3CEndpointReferenceBuilder element​(Element element)

      Adds an extension element to the `W3CEndpointReference` instance's `wsa:EndpointReference` element.
      Parameters:
        `element` - The extension element to be added to the `W3CEndpointReference`
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the extension `element` added to the `W3CEndpointReference` instance.
      Throws:
        `IllegalArgumentException` - if `element` is `null`.
      Since:
        1.7, JAX-WS 2.2

    - #### attribute

          public W3CEndpointReferenceBuilder attribute​(QName name,
                                                       String value)

      Adds an extension attribute to the `W3CEndpointReference` instance's `wsa:EndpointReference` element.
      Parameters:
        `name` - The name of the extension attribute to be added to the `W3CEndpointReference`
        `value` - extension attribute value
      Returns:
        A `W3CEndpointReferenceBuilder` instance with the extension attribute added to the `W3CEndpointReference` instance.
      Throws:
        `IllegalArgumentException` - if `name` or `value` is `null`.
      Since:
        1.7, JAX-WS 2.2

    - #### build

          public W3CEndpointReference build​()

      Builds a `W3CEndpointReference` from the accumulated properties set on this `W3CEndpointReferenceBuilder` instance.

      This method can be used to create a `W3CEndpointReference` for any endpoint by specifying the `address` property along with any other desired properties. This method can also be used to create a `W3CEndpointReference` for an endpoint that is published by the same Java EE application. This method can automatically determine the `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` do not identify an endpoint published by the same Java EE application, a `java.lang.IllegalStateException` MUST be thrown.

      Returns:
        `W3CEndpointReference` from the accumulated properties set on this `W3CEndpointReferenceBuilder` instance. This method never returns `null`.
      Throws:
        `IllegalStateException` -
        - If the `address`, `serviceName` and `endpointName` are all `null`.
        - If the `serviceName` service is `null` and the `endpointName` is NOT `null`.
        - If the `address` property is `null` and the `serviceName` and `endpointName` do not specify a valid endpoint published by the same Java EE application.
        - If the `serviceName` is NOT `null` and is not present in the specified WSDL.
        - If the `endpointName` port is not `null` and it is not present in `serviceName` service in the WSDL.
        - If the `wsdlDocumentLocation` is NOT `null` and does not represent a valid WSDL.
        `WebServiceException` - If an error occurs while creating the `W3CEndpointReference`.