shibsp/handler/AbstractHandler.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file shibsp/handler/AbstractHandler.h
  19  *
  20  * Base class for handlers based on a DOMPropertySet.
  21  */
  22
  23 #ifndef __shibsp_abshandler_h__
  24 #define __shibsp_abshandler_h__
  25
  26 #include <shibsp/handler/Handler.h>
  27 #include <shibsp/util/DOMPropertySet.h>
  28
  29 #include <log4cpp/Category.hh>
  30 #include <saml/binding/HTTPRequest.h>
  31 #include <saml/binding/HTTPResponse.h>
  32 #include <xmltooling/XMLObject.h>
  33
  34 namespace shibsp {
  35
  36     class SHIBSP_API Application;
  37     class SHIBSP_API SPRequest;
  38
  39 #if defined (_MSC_VER)
  40     #pragma warning( push )
  41     #pragma warning( disable : 4250 )
  42 #endif
  43
  44     /**
  45      * Base class for handlers based on a DOMPropertySet.
  46      */
  47     class SHIBSP_API AbstractHandler : public virtual Handler, public DOMPropertySet
  48     {
  49     protected:
  50         /**
  51          * Constructor
  52          *
  53          * @param e         DOM element to load as property set.
  54          * @param filter    optional filter controls what child elements to include as nested PropertySets
  55          * @param remapper  optional map of property rename rules for legacy property support
  56          */
  57         AbstractHandler(
  58             const xercesc::DOMElement* e,
  59             log4cpp::Category& log,
  60             xercesc::DOMNodeFilter* filter=NULL,
  61             const std::map<std::string,std::string>* remapper=NULL
  62             );
  63
  64         /**
  65          * Examines a protocol response message for errors and raises an annotated exception
  66          * if an error is found.
  67          *
  68          * <p>The base class version understands SAML 1.x and SAML 2.0 responses.
  69          *
  70          * @param response      a response message of some known protocol
  71          */
  72         virtual void checkError(const xmltooling::XMLObject* response) const;
  73
  74         /**
  75          * Implements various mechanisms to preserve RelayState,
  76          * such as cookies or StorageService-backed keys.
  77          *
  78          * <p>If a supported mechanism can be identified, the input parameter will be
  79          * replaced with a suitable state key.
  80          *
  81          * @param application   the associated Application
  82          * @param response      outgoing HTTP response
  83          * @param relayState    RelayState token to supply with message
  84          */
  85         virtual void preserveRelayState(const Application& application, opensaml::HTTPResponse& response, std::string& relayState) const;
  86
  87         /**
  88          * Implements various mechanisms to recover RelayState,
  89          * such as cookies or StorageService-backed keys.
  90          *
  91          * <p>If a supported mechanism can be identified, the input parameter will be
  92          * replaced with the recovered state information.
  93          *
  94          * @param application   the associated Application
  95          * @param request       incoming HTTP request
  96          * @param relayState    RelayState token supplied with message
  97          * @param clear         true iff the token state should be cleared
  98          */
  99         virtual void recoverRelayState(
 100             const Application& application, opensaml::HTTPRequest& request, std::string& relayState, bool clear=true
 101             ) const;
 102
 103         /** Logging object. */
 104         log4cpp::Category& m_log;
 105
 106     public:
 107         virtual ~AbstractHandler() {}
 108     };
 109
 110 #if defined (_MSC_VER)
 111     #pragma warning( pop )
 112 #endif
 113
 114 };
 115
 116 #endif /* __shibsp_abshandler_h__ */