2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file xmltooling/soap/SOAPClient.h
24 * Implements SOAP 1.1 messaging over a transport.
27 #ifndef __xmltooling_soap11client_h__
28 #define __xmltooling_soap11client_h__
30 #include <xmltooling/soap/SOAPTransport.h>
34 class XMLTOOL_API Envelope;
35 class XMLTOOL_API Fault;
38 * Implements SOAP 1.1 messaging over a transport.
40 * In the abstract, this can be a one-way exchange, or use asynchronous
41 * transports, but this is mostly theoretical at this point.
43 class XMLTOOL_API SOAPClient
45 MAKE_NONCOPYABLE(SOAPClient);
50 * @param validate true iff schema validation should be used
52 SOAPClient(bool validate=false);
54 virtual ~SOAPClient();
57 * Controls schema validation of incoming XML messages.
58 * This is separate from other forms of programmatic validation of objects,
59 * but can detect a much wider range of syntax errors.
61 * @param validate true iff the client should use a validating XML parser
63 void setValidating(bool validate=true);
66 * Sends the supplied envelope to the identified recipient/endpoint.
68 * <p>The client object will instantiate a transport layer object
69 * appropriate for the endpoint URL provided and supply it to the
70 * prepareTransport() method below.
72 * <p>To authenticate the server end, the transport layer object
73 * exposes a method to load a TrustEngine and CredentialResolver
74 * in a subclass-specific version of the prepareTransport() method.
76 * @param env SOAP envelope to send
77 * @param addr addressing information
79 virtual void send(const Envelope& env, const xmltooling::SOAPTransport::Address& addr);
82 * Returns the response message, if any. As long as a response is
83 * "expected" but not available, nullptr will be returned. If no response
84 * will be forthcoming, an exception is raised.
86 * <p>The caller is responsible for freeing the returned envelope.
88 virtual Envelope* receive();
91 * Resets the object for another call.
97 * Allows client to supply transport-layer settings prior to sending message.
99 * @param transport reference to transport layer
101 virtual void prepareTransport(xmltooling::SOAPTransport& transport);
104 * Handling of SOAP faults.
106 * @param fault SOAP Fault received by client
107 * @return true iff the Fault should be treated as a fatal error
109 virtual bool handleFault(const soap11::Fault& fault);
111 /** Flag controlling schema validation. */
114 /** Holds response until retrieved by caller. */
115 xmltooling::SOAPTransport* m_transport;
120 #endif /* __xmltooling_soap11client_h__ */