001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws.wsaddressing;
007:
008: import org.w3c.dom.Element;
009:
010: import java.util.ArrayList;
011: import java.util.List;
012: import javax.xml.namespace.QName;
013: import javax.xml.ws.WebServiceException;
014: import javax.xml.ws.spi.Provider;
015:
016: /**
017: * This class is used to build <code>W3CEndpointReference</code>
018: * instances. The intended use of this clsss is for
019: * an application component, for example a factory component,
020: * to create an <code>W3CEndpointReference</code> for a
021: * web service endpoint published by the same
022: * Java EE application. It can also be used to create
023: * <code>W3CEndpointReferences</code> for an Java SE based
024: * endpoint by providing the <code>address</code> property.
025: * <p>
026: * When creating a <code>W3CEndpointReference</code> for an
027: * endpoint that is not published by the same Java EE application,
028: * the <code>address</code> property MUST be specified.
029: * <p>
030: * When creating a <code>W3CEndpointReference</code> for an endpoint
031: * published by the same Java EE application, the <code>address</code>
032: * property MAY be <code>null</code> but then the <code>serviceName</code>
033: * and <code>endpointName</code> MUST specify an endpoint published by
034: * the same Java EE application.
035: * <p>
036: * When the <code>wsdlDocumentLocation</code> is specified it MUST refer
037: * to a valid WSDL document and the <code>serviceName</code> and
038: * <code>endpointName</code> (if specified) MUST match a service and port
039: * in the WSDL document.
040: *
041: * @since JAX-WS 2.1
042: */
043: public final class W3CEndpointReferenceBuilder {
044: /**
045: * Creates a new <code>W3CEndpointReferenceBuilder</code> instance.
046: */
047: public W3CEndpointReferenceBuilder() {
048: referenceParameters = new ArrayList<Element>();
049: metadata = new ArrayList<Element>();
050: }
051:
052: /**
053: * Sets the <code>address</code> to the
054: * <code>W3CEndpointReference</code> instance's
055: * <code>wsa:Address</code>.
056: * <p>
057: * The <code>address</code> MUST be set to a non-<code>null</code>
058: * value when building a <code>W3CEndpointReference</code> for a
059: * web service endpoint that is not published by the same
060: * Java EE application or when running on Java SE.
061: *
062: * @param address The address of the endpoint to be targeted
063: * by the returned <code>W3CEndpointReference<code>.
064: *
065: * @return A <code>W3CEndpointReferenceBuilder</code> instance with
066: * the <code>address</code> set to the <code>wsa:Address</code>.
067: */
068: public W3CEndpointReferenceBuilder address(String address) {
069: this .address = address;
070: return this ;
071: }
072:
073: /**
074: * Sets the <code>serviceName</code> of the endpoint to be targeted
075: * by the returned <code>W3CEndpointReference</code>.
076: *
077: * @param serviceName The service name of the endpoint to be targeted
078: * by the returned <code>W3CEndpointReference<code>. This property
079: * may also be used with the <code>endpointName</code> (portName)
080: * property to lookup the <code>address</code> of a web service
081: * endpoint that is published by the same Java EE application.
082: *
083: * @return A <code>W3CEndpointReferenceBuilder</code> instance with
084: * the <code>serviceName</code> property set.
085: *
086: */
087: public W3CEndpointReferenceBuilder serviceName(QName serviceName) {
088: this .serviceName = serviceName;
089: return this ;
090: }
091:
092: /**
093: * Sets the <code>endpointName</code> of the endpoint to
094: * be targeted by the returned <code>W3CEndpointRefernce</code>.
095: * This method can only
096: * be called after the {@link #serviceName} method has been called.
097: *
098: * @param endpointName The name of the endpoint to be targeted
099: * by the returned <code>W3CEndpointReference<code>. The
100: * <code>endpointName</code> (portName) property may also be
101: * used with the <code>serviceName</code> property to lookup
102: * the <code>address</code> of a web service
103: * endpoint published by the same Java EE application.
104: *
105: * @return A <code>W3CEndpointReferenceBuilder</code> instance with
106: * the <code>endpointName</code> property set.
107: *
108: * @throws java.lang.IllegalStateException If the <code>serviceName</code> has not
109: * been set.
110: */
111: public W3CEndpointReferenceBuilder endpointName(QName endpointName) {
112: if (serviceName == null) {
113: throw new IllegalStateException(
114: "The W3CEndpointReferenceBuilder's serviceName must be set before setting the endpointName: "
115: + 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(
134: String wsdlDocumentLocation) {
135: this .wsdlDocumentLocation = wsdlDocumentLocation;
136: return this ;
137: }
138:
139: /**
140: * Adds the <code>referenceParameter</code> to the
141: * <code>W3CEndpointReference</code> instance
142: * <code>wsa:ReferenceParameters</code> element.
143: *
144: * @param referenceParameter The element to be added to the
145: * <code>wsa:ReferenceParameters</code> element.
146: *
147: * @return A <code>W3CEndpointReferenceBuilder</code> instance with
148: * the <code>referenceParameter</code> added to the
149: * <code>wsa:ReferenceParameters</code> element.
150: *
151: * @throws java.lang.IllegalArgumentException if <code>referenceParameter</code>
152: * is <code>null</code>.
153: */
154: public W3CEndpointReferenceBuilder referenceParameter(
155: Element referenceParameter) {
156: if (referenceParameter == null)
157: throw new java.lang.IllegalArgumentException(
158: "The referenceParameter cannot be null.");
159: referenceParameters.add(referenceParameter);
160: return this ;
161: }
162:
163: /**
164: * Adds the <code>metadataElement</code> to the
165: * <code>W3CEndpointReference</code> instance's
166: * <code>wsa:Metadata</code> element.
167: *
168: * @param metadataElement The element to be added to the
169: * <code>wsa:Metadata</code> element.
170: *
171: * @return A <code>W3CEndpointReferenceBuilder</code> instance with
172: * the <code>metadataElement</code> added to the
173: * <code>wsa:Metadata</code> element.
174: *
175: * @throws java.lang.IllegalArgumentException if <code>metadataElement</code>
176: * is <code>null</code>.
177: */
178: public W3CEndpointReferenceBuilder metadata(Element metadataElement) {
179: if (metadataElement == null)
180: throw new java.lang.IllegalArgumentException(
181: "The metadataElement cannot be null.");
182: metadata.add(metadataElement);
183: return this ;
184: }
185:
186: /**
187: * Builds a <code>W3CEndpointReference</code> from the accumulated
188: * properties set on this <code>W3CEndpointReferenceBuilder</code>
189: * instance.
190: * <p>
191: * This method can be used to create a <code>W3CEndpointReference</code>
192: * for any endpoint by specifying the <code>address</code> property along
193: * with any other desired properties. This method
194: * can also be used to create a <code>W3CEndpointReference</code> for
195: * an endpoint that is published by the same Java EE application.
196: * This method can automatically determine the <code>address</code> of
197: * an endpoint published by the same Java EE application that is identified by the
198: * <code>serviceName</code> and
199: * <code>endpointName</code> properties. If the <code>address</code> is
200: * <code>null</code> and the <code>serviceName</code> and
201: * <code>endpointName</code>
202: * do not identify an endpoint published by the same Java EE application, a
203: * <code>java.lang.IllegalStateException</code> MUST be thrown.
204: *
205: *
206: * @return <code>W3CEndpointReference</code> from the accumulated
207: * properties set on this <code>W3CEndpointReferenceBuilder</code>
208: * instance. This method never returns <code>null</code>.
209: *
210: * @throws java.lang.IllegalStateException
211: * <ul>
212: * <li>If the <code>address</code>, <code>serviceName</code> and
213: * <code>endpointName</code> are all <code>null</code>.
214: * <li>If the <code>serviceName</code> service is <code>null</code> and the
215: * <code>endpointName</code> is NOT <code>null</code>.
216: * <li>If the <code>address</code> property is <code>null</code> and
217: * the <code>serviceName</code> and <code>endpointName</code> do not
218: * specify a valid endpoint published by the same Java EE
219: * application.
220: * <li>If the <code>serviceName</code> is NOT <code>null</code>
221: * and is not present in the specified WSDL.
222: * <li>If the <code>endpointName</code> port is not <code>null<code> and it
223: * is not present in <code>serviceName</code> service in the WSDL.
224: * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
225: * and does not represent a valid WSDL.
226: * </ul>
227: * @throws WebServiceException If an error occurs while creating the
228: * <code>W3CEndpointReference</code>.
229: *
230: */
231: public W3CEndpointReference build() {
232: return Provider.provider().createW3CEndpointReference(address,
233: serviceName, endpointName, metadata,
234: wsdlDocumentLocation, referenceParameters);
235: }
236:
237: private String address;
238: private List<Element> referenceParameters;
239: private List<Element> metadata;
240: private QName serviceName;
241: private QName endpointName;
242: private String wsdlDocumentLocation;
243: }
|