View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.soap;
17  
18  /**
19   * A point-to-point connection that a client can use for sending messages
20   * directly to a remote party (represented by a URL, for instance).
21   * <p>
22   * A client can obtain a <code>SOAPConnection</code> object simply by
23   * calling the following static method.
24   * <pre>
25   *
26   *      SOAPConnection con = SOAPConnection.newInstance();
27   * </pre>
28   * A <code>SOAPConnection</code> object can be used to send messages
29   * directly to a URL following the request/response paradigm.  That is,
30   * messages are sent using the method <code>call</code>, which sends the
31   * message and then waits until it gets a reply.
32   */
33  public abstract class SOAPConnection {
34  
35      public SOAPConnection() {}
36  
37      /**
38       * Sends the given message to the specified endpoint and
39       * blocks until it has returned the response.
40       * @param request the <CODE>SOAPMessage</CODE>
41       *     object to be sent
42       * @param endpoint an <code>Object</code> that identifies
43       *            where the message should be sent. It is required to
44       *            support Objects of type
45       *            <code>java.lang.String</code>,
46       *            <code>java.net.URL</code>, and when JAXM is present
47       *            <code>javax.xml.messaging.URLEndpoint</code>
48       * @return the <CODE>SOAPMessage</CODE> object that is the
49       *     response to the message that was sent
50       * @throws  SOAPException if there is a SOAP error
51       */
52      public abstract SOAPMessage call(SOAPMessage request, Object endpoint)
53          throws SOAPException;
54  
55      /**
56       * Closes this <CODE>SOAPConnection</CODE> object.
57       * @throws  SOAPException if there is a SOAP error
58       */
59      public abstract void close() throws SOAPException;
60  }