xmltooling/soap/SOAPClient.h

   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__ */