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 and Description
`W3CEndpointReferenceBuilder()` Creates a new `W3CEndpointReferenceBuilder` instance.

### Method Summary

All Methods Instance Methods Concrete Methods
`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`.