Java > Open Source Codes > javax > xml > ws > wsaddressing > W3CEndpointReferenceBuilder


1 /*
2  * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
3  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4  */
5
6 package javax.xml.ws.wsaddressing;
7
8
9 import org.w3c.dom.Element ;
10
11 import java.util.ArrayList ;
12 import java.util.List ;
13 import javax.xml.namespace.QName ;
14 import javax.xml.ws.WebServiceException;
15 import javax.xml.ws.spi.Provider;
16
17
18 /**
19  * This class is used to build <code>W3CEndpointReference</code>
20  * instances. The intended use of this clsss is for
21  * an application component, for example a factory component,
22  * to create an <code>W3CEndpointReference</code> for a
23  * web service endpoint published by the same
24  * Java EE application. It can also be used to create
25  * <code>W3CEndpointReferences</code> for an Java SE based
26  * endpoint by providing the <code>address</code> property.
27  * <p>
28  * When creating a <code>W3CEndpointReference</code> for an
29  * endpoint that is not published by the same Java EE application,
30  * the <code>address</code> property MUST be specified.
31  * <p>
32  * When creating a <code>W3CEndpointReference</code> for an endpoint
33  * published by the same Java EE application, the <code>address</code>
34  * property MAY be <code>null</code> but then the <code>serviceName</code>
35  * and <code>endpointName</code> MUST specify an endpoint published by
36  * the same Java EE application.
37  * <p>
38  * When the <code>wsdlDocumentLocation</code> is specified it MUST refer
39  * to a valid WSDL document and the <code>serviceName</code> and
40  * <code>endpointName</code> (if specified) MUST match a service and port
41  * in the WSDL document.
42  *
43  * @since JAX-WS 2.1
44  */
45 public final class W3CEndpointReferenceBuilder {
46     /**
47      * Creates a new <code>W3CEndpointReferenceBuilder</code> instance.
48      */
49     public W3CEndpointReferenceBuilder() {
50         referenceParameters = new ArrayList <Element >();
51         metadata = new ArrayList <Element >();
52     }
53     
54     /**
55      * Sets the <code>address</code> to the
56      * <code>W3CEndpointReference</code> instance's
57      * <code>wsa:Address</code>.
58      * <p>
59      * The <code>address</code> MUST be set to a non-<code>null</code>
60      * value when building a <code>W3CEndpointReference</code> for a
61      * web service endpoint that is not published by the same
62      * Java EE application or when running on Java SE.
63      *
64      * @param address The address of the endpoint to be targeted
65      * by the returned <code>W3CEndpointReference<code>.
66      *
67      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
68      * the <code>address</code> set to the <code>wsa:Address</code>.
69      */
70     public W3CEndpointReferenceBuilder address(String address) {
71         this.address = address;
72         return this;
73     }
74     
75     /**
76      * Sets the <code>serviceName</code> of the endpoint to be targeted
77      * by the returned <code>W3CEndpointReference</code>.
78      *
79      * @param serviceName The service name of the endpoint to be targeted
80      * by the returned <code>W3CEndpointReference<code>. This property
81      * may also be used with the <code>endpointName</code> (portName)
82      * property to lookup the <code>address</code> of a web service
83      * endpoint that is published by the same Java EE application.
84      *
85      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
86      * the <code>serviceName</code> property set.
87      *
88      */
89     public W3CEndpointReferenceBuilder serviceName(QName serviceName) {
90         this.serviceName = serviceName;
91         return this;
92     }
93     
94     /**
95      * Sets the <code>endpointName</code> of the endpoint to
96      * be targeted by the returned <code>W3CEndpointRefernce</code>.
97      * This method can only
98      * be called after the {@link #serviceName} method has been called.
99      *
100      * @param endpointName The name of the endpoint to be targeted
101      * by the returned <code>W3CEndpointReference<code>. The
102      * <code>endpointName</code> (portName) property may also be
103      * used with the <code>serviceName</code> property to lookup
104      * the <code>address</code> of a web service
105      * endpoint published by the same Java EE application.
106      *
107      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
108      * the <code>endpointName</code> property set.
109      *
110      * @throws java.lang.IllegalStateException If the <code>serviceName</code> has not
111      * been set.
112      */
113     public W3CEndpointReferenceBuilder endpointName(QName endpointName) {
114         if (serviceName == null) {
115             throw new IllegalStateException ("The W3CEndpointReferenceBuilder's serviceName must be set before setting the endpointName: "+endpointName);
116         }
117         
118         this.endpointName = endpointName;
119         return this;
120     }
121     
122     /**
123      * Sets the <code>wsdlDocumentLocation</code> associated with the targeted
124      * <code>W3CEndpointReference</code>.
125      *
126      * @param wsdlDocumentLocation The location of the WSDL document associated
127      * with the targeted <code>W3CEndpointReference</code>.
128      *
129      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
130      * the <code>wsdlDocumentLocation</code> property set.
131      *
132      */
133     public W3CEndpointReferenceBuilder wsdlDocumentLocation(String wsdlDocumentLocation) {
134         this.wsdlDocumentLocation = wsdlDocumentLocation;
135         return this;
136     }
137     
138     /**
139      * Adds the <code>referenceParameter</code> to the
140      * <code>W3CEndpointReference</code> instance
141      * <code>wsa:ReferenceParameters</code> element.
142      *
143      * @param referenceParameter The element to be added to the
144      * <code>wsa:ReferenceParameters</code> element.
145      *
146      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
147      * the <code>referenceParameter</code> added to the
148      * <code>wsa:ReferenceParameters</code> element.
149      *
150      * @throws java.lang.IllegalArgumentException if <code>referenceParameter</code>
151      * is <code>null</code>.
152      */
153     public W3CEndpointReferenceBuilder referenceParameter(Element referenceParameter) {
154         if (referenceParameter == null)
155             throw new java.lang.IllegalArgumentException ("The referenceParameter cannot be null.");
156         referenceParameters.add(referenceParameter);
157         return this;
158     }
159     
160     /**
161      * Adds the <code>metadataElement</code> to the
162      * <code>W3CEndpointReference</code> instance's
163      * <code>wsa:Metadata</code> element.
164      *
165      * @param metadataElement The element to be added to the
166      * <code>wsa:Metadata</code> element.
167      *
168      * @return A <code>W3CEndpointReferenceBuilder</code> instance with
169      * the <code>metadataElement</code> added to the
170      * <code>wsa:Metadata</code> element.
171      *
172      * @throws java.lang.IllegalArgumentException if <code>metadataElement</code>
173      * is <code>null</code>.
174      */
175     public W3CEndpointReferenceBuilder metadata(Element metadataElement) {
176         if (metadataElement == null)
177             throw new java.lang.IllegalArgumentException ("The metadataElement cannot be null.");
178         metadata.add(metadataElement);
179         return this;
180     }
181     
182     /**
183      * Builds a <code>W3CEndpointReference</code> from the accumulated
184      * properties set on this <code>W3CEndpointReferenceBuilder</code>
185      * instance.
186      * <p>
187      * This method can be used to create a <code>W3CEndpointReference</code>
188      * for any endpoint by specifying the <code>address</code> property along
189      * with any other desired properties. This method
190      * can also be used to create a <code>W3CEndpointReference</code> for
191      * an endpoint that is published by the same Java EE application.
192      * This method can automatically determine the <code>address</code> of
193      * an endpoint published by the same Java EE application that is identified by the
194      * <code>serviceName</code> and
195      * <code>endpointName</code> properties. If the <code>address</code> is
196      * <code>null</code> and the <code>serviceName</code> and
197      * <code>endpointName</code>
198      * do not identify an endpoint published by the same Java EE application, a
199      * <code>java.lang.IllegalStateException</code> MUST be thrown.
200      *
201      *
202      * @return <code>W3CEndpointReference</code> from the accumulated
203      * properties set on this <code>W3CEndpointReferenceBuilder</code>
204      * instance. This method never returns <code>null</code>.
205      *
206      * @throws java.lang.IllegalStateException
207      * <ul>
208      * <li>If the <code>address</code>, <code>serviceName</code> and
209      * <code>endpointName</code> are all <code>null</code>.
210      * <li>If the <code>serviceName</code> service is <code>null</code> and the
211      * <code>endpointName</code> is NOT <code>null</code>.
212      * <li>If the <code>address</code> property is <code>null</code> and
213      * the <code>serviceName</code> and <code>endpointName</code> do not
214      * specify a valid endpoint published by the same Java EE
215      * application.
216      * <li>If the <code>serviceName</code> is NOT <code>null</code>
217      * and is not present in the specified WSDL.
218      * <li>If the <code>endpointName</code> port is not <code>null<code> and it
219      * is not present in <code>serviceName</code> service in the WSDL.
220      * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
221      * and does not represent a valid WSDL.
222      * </ul>
223      * @throws WebServiceException If an error occurs while creating the
224      * <code>W3CEndpointReference</code>.
225      *
226      */
227     public W3CEndpointReference build() {
228         return Provider.provider().createW3CEndpointReference(address,
229                 serviceName, endpointName, metadata, wsdlDocumentLocation,
230                 referenceParameters);
231     }
232     
233     private String address;
234     private List <Element > referenceParameters;
235     private List <Element > metadata;
236     private QName serviceName;
237     private QName endpointName;
238     private String wsdlDocumentLocation;
239 }
240

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags