2 * Copyright 2001-2007 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file xmltooling/soap/SOAPClient.h
20 * Implements SOAP 1.1 messaging over a transport.
23 #ifndef __xmltooling_soap11client_h__
24 #define __xmltooling_soap11client_h__
26 #include <xmltooling/security/CredentialResolver.h>
27 #include <xmltooling/soap/SOAPTransport.h>
31 class XMLTOOL_API Envelope;
32 class XMLTOOL_API Fault;
35 * Implements SOAP 1.1 messaging over a transport.
37 * In the abstract, this can be a one-way exchange, or use asynchronous
38 * transports, but this is mostly theoretical at this point.
40 class XMLTOOL_API SOAPClient
42 MAKE_NONCOPYABLE(SOAPClient);
47 * @param validate true iff schema validation should be used
49 SOAPClient(bool validate=false) : m_validate(validate), m_transport(NULL) {}
51 virtual ~SOAPClient();
54 * Controls schema validation of incoming XML messages.
55 * This is separate from other forms of programmatic validation of objects,
56 * but can detect a much wider range of syntax errors.
58 * @param validate true iff the client should use a validating XML parser
60 void setValidating(bool validate=true) {
61 m_validate = validate;
65 * Sends the supplied envelope to the identified recipient/endpoint.
67 * <p>The client object will instantiate a transport layer object
68 * appropriate for the endpoint URL provided and supply it to the
69 * prepareTransport() method below.
71 * <p>To authenticate the server end, the transport layer object
72 * exposes a method to load a TrustEngine and CredentialResolver
73 * in a subclass-specific version of the prepareTransport() method.
75 * @param env SOAP envelope to send
76 * @param addr addressing information
78 virtual void send(const Envelope& env, const xmltooling::SOAPTransport::Address& addr);
81 * Returns the response message, if any. As long as a response is
82 * "expected" but not available, NULL will be returned. If no response
83 * will be forthcoming, an exception is raised.
85 * <p>The caller is responsible for freeing the returned envelope.
87 virtual Envelope* receive();
90 * Resets the object for another call.
96 * Allows client to supply transport-layer settings prior to sending message.
98 * @param transport reference to transport layer
100 virtual void prepareTransport(xmltooling::SOAPTransport& transport) {}
103 * Handling of SOAP faults.
105 * @param fault SOAP Fault received by client
106 * @return true iff the Fault should be treated as a fatal error
108 virtual bool handleFault(const soap11::Fault& fault);
110 /** Flag controlling schema validation. */
113 /** Holds response until retrieved by caller. */
114 xmltooling::SOAPTransport* m_transport;
119 #endif /* __xmltooling_soap11client_h__ */