1 /** 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. 6 * 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 10 * License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 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. 19 */ 20 21 /** 22 * @file xmltooling/soap/SOAPClient.h 23 * 24 * Implements SOAP 1.1 messaging over a transport. 25 */ 26 27 #ifndef __xmltooling_soap11client_h__ 28 #define __xmltooling_soap11client_h__ 29 30 #include <xmltooling/soap/SOAPTransport.h> 31 32 namespace soap11 { 33 34 class XMLTOOL_API Envelope; 35 class XMLTOOL_API Fault; 36 37 /** 38 * Implements SOAP 1.1 messaging over a transport. 39 * 40 * In the abstract, this can be a one-way exchange, or use asynchronous 41 * transports, but this is mostly theoretical at this point. 42 */ 43 class XMLTOOL_API SOAPClient 44 { 45 MAKE_NONCOPYABLE(SOAPClient); 46 public: 47 /** 48 * Constructor 49 * 50 * @param validate true iff schema validation should be used 51 */ 52 SOAPClient(bool validate=false); 53 54 virtual ~SOAPClient(); 55 56 /** 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. 60 * 61 * @param validate true iff the client should use a validating XML parser 62 */ 63 void setValidating(bool validate=true); 64 65 /** 66 * Sends the supplied envelope to the identified recipient/endpoint. 67 * 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. 71 * 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. 75 * 76 * @param env SOAP envelope to send 77 * @param addr addressing information 78 */ 79 virtual void send(const Envelope& env, const xmltooling::SOAPTransport::Address& addr); 80 81 /** 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. 85 * 86 * <p>The caller is responsible for freeing the returned envelope. 87 */ 88 virtual Envelope* receive(); 89 90 /** 91 * Resets the object for another call. 92 */ 93 virtual void reset(); 94 95 protected: 96 /** 97 * Allows client to supply transport-layer settings prior to sending message. 98 * 99 * @param transport reference to transport layer 100 */ 101 virtual void prepareTransport(xmltooling::SOAPTransport& transport); 102 103 /** 104 * Handling of SOAP faults. 105 * 106 * @param fault SOAP Fault received by client 107 * @return true iff the Fault should be treated as a fatal error 108 */ 109 virtual bool handleFault(const soap11::Fault& fault); 110 111 /** Flag controlling schema validation. */ 112 bool m_validate; 113 114 /** Holds response until retrieved by caller. */ 115 xmltooling::SOAPTransport* m_transport; 116 }; 117 118 }; 119 120 #endif /* __xmltooling_soap11client_h__ */ 121