01: /*
02: * $Id: SOAPConnection.java,v 1.13 2006/03/30 00:59:40 ofung Exp $
03: * $Revision: 1.13 $
04: * $Date: 2006/03/30 00:59:40 $
05: */
06:
07: /*
08: * The contents of this file are subject to the terms
09: * of the Common Development and Distribution License
10: * (the License). You may not use this file except in
11: * compliance with the License.
12: *
13: * You can obtain a copy of the license at
14: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15: * See the License for the specific language governing
16: * permissions and limitations under the License.
17: *
18: * When distributing Covered Code, include this CDDL
19: * Header Notice in each file and include the License file
20: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21: * If applicable, add the following below the CDDL Header,
22: * with the fields enclosed by brackets [] replaced by
23: * you own identifying information:
24: * "Portions Copyrighted [year] [name of copyright owner]"
25: *
26: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27: */
28: package javax.xml.soap;
29:
30: /**
31: * A point-to-point connection that a client can use for sending messages
32: * directly to a remote party (represented by a URL, for instance).
33: * <p>
34: * The SOAPConnection class is optional. Some implementations may
35: * not implement this interface in which case the call to
36: * <code>SOAPConnectionFactory.newInstance()</code> (see below) will
37: * throw an <code>UnsupportedOperationException</code>.
38: * <p>
39: * A client can obtain a <code>SOAPConnection</code> object using a
40: * {@link SOAPConnectionFactory} object as in the following example:
41: * <PRE>
42: * SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
43: * SOAPConnection con = factory.createConnection();
44: * </PRE>
45: * A <code>SOAPConnection</code> object can be used to send messages
46: * directly to a URL following the request/response paradigm. That is,
47: * messages are sent using the method <code>call</code>, which sends the
48: * message and then waits until it gets a reply.
49: */
50: public abstract class SOAPConnection {
51:
52: /**
53: * Sends the given message to the specified endpoint and blocks until
54: * it has returned the response.
55: *
56: * @param request the <code>SOAPMessage</code> object to be sent
57: * @param to an <code>Object</code> that identifies
58: * where the message should be sent. It is required to
59: * support Objects of type
60: * <code>java.lang.String</code>,
61: * <code>java.net.URL</code>, and when JAXM is present
62: * <code>javax.xml.messaging.URLEndpoint</code>
63: *
64: * @return the <code>SOAPMessage</code> object that is the response to the
65: * message that was sent
66: * @throws SOAPException if there is a SOAP error
67: */
68: public abstract SOAPMessage call(SOAPMessage request, Object to)
69: throws SOAPException;
70:
71: /**
72: * Gets a message from a specific endpoint and blocks until it receives,
73: *
74: * @param to an <code>Object</code> that identifies where
75: * the request should be sent. Objects of type
76: * <code>java.lang.String</code> and
77: * <code>java.net.URL</code> must be supported.
78: *
79: * @return the <code>SOAPMessage</code> object that is the response to the
80: * get message request
81: * @throws SOAPException if there is a SOAP error
82: * @since SAAJ 1.3
83: */
84: public SOAPMessage get(Object to) throws SOAPException {
85: throw new UnsupportedOperationException(
86: "All subclasses of SOAPConnection must override get()");
87: }
88:
89: /**
90: * Closes this <code>SOAPConnection</code> object.
91: *
92: * @throws SOAPException if there is a SOAP error
93: */
94: public abstract void close() throws SOAPException;
95: }
|