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 #ifndef SHIBSP_LITE
  31 # include <saml/saml2/core/Protocols.h>
  32 #endif
  33 #include <xmltooling/XMLObject.h>
  34 #include <xmltooling/io/HTTPRequest.h>
  35 #include <xmltooling/io/HTTPResponse.h>
  36
  37 namespace shibsp {
  38
  39     class SHIBSP_API Application;
  40     class SHIBSP_API SPRequest;
  41
  42 #if defined (_MSC_VER)
  43     #pragma warning( push )
  44     #pragma warning( disable : 4250 )
  45 #endif
  46
  47     /**
  48      * Base class for handlers based on a DOMPropertySet.
  49      */
  50     class SHIBSP_API AbstractHandler : public virtual Handler, public DOMPropertySet
  51     {
  52     protected:
  53         /**
  54          * Constructor
  55          *
  56          * @param e         DOM element to load as property set.
  57          * @param filter    optional filter controls what child elements to include as nested PropertySets
  58          * @param remapper  optional map of property rename rules for legacy property support
  59          */
  60         AbstractHandler(
  61             const xercesc::DOMElement* e,
  62             log4cpp::Category& log,
  63             xercesc::DOMNodeFilter* filter=NULL,
  64             const std::map<std::string,std::string>* remapper=NULL
  65             );
  66
  67 #ifndef SHIBSP_LITE
  68         /**
  69          * Examines a protocol response message for errors and raises an annotated exception
  70          * if an error is found.
  71          *
  72          * <p>The base class version understands SAML 1.x and SAML 2.0 responses.
  73          *
  74          * @param response      a response message of some known protocol
  75          */
  76         virtual void checkError(const xmltooling::XMLObject* response) const;
  77
  78         /**
  79          * Prepares Status information in a SAML 2.0 response.
  80          *
  81          * @param response  a SAML 2.0 response message
  82          * @param code      SAML status code
  83          * @param ex        optional message to pass back
  84          */
  85         void prepareResponse(
  86             opensaml::saml2p::StatusResponseType& response, const XMLCh* code, const XMLCh* subcode=NULL, const char* msg=NULL
  87             ) const;
  88 #endif
  89
  90         /**
  91          * Implements various mechanisms to preserve RelayState,
  92          * such as cookies or StorageService-backed keys.
  93          *
  94          * <p>If a supported mechanism can be identified, the input parameter will be
  95          * replaced with a suitable state key.
  96          *
  97          * @param application   the associated Application
  98          * @param response      outgoing HTTP response
  99          * @param relayState    RelayState token to supply with message
 100          */
 101         virtual void preserveRelayState(const Application& application, xmltooling::HTTPResponse& response, std::string& relayState) const;
 102
 103         /**
 104          * Implements various mechanisms to recover RelayState,
 105          * such as cookies or StorageService-backed keys.
 106          *
 107          * <p>If a supported mechanism can be identified, the input parameter will be
 108          * replaced with the recovered state information.
 109          *
 110          * @param application   the associated Application
 111          * @param request       incoming HTTP request
 112          * @param relayState    RelayState token supplied with message
 113          * @param clear         true iff the token state should be cleared
 114          */
 115         virtual void recoverRelayState(
 116             const Application& application, xmltooling::HTTPRequest& request, std::string& relayState, bool clear=true
 117             ) const;
 118
 119         /** Logging object. */
 120         log4cpp::Category& m_log;
 121
 122         /** Configuration namespace for custom properties. */
 123         xmltooling::auto_ptr_char m_configNS;
 124
 125     public:
 126         virtual ~AbstractHandler() {}
 127     };
 128
 129 #if defined (_MSC_VER)
 130     #pragma warning( pop )
 131 #endif
 132
 133 };
 134
 135 #endif /* __shibsp_abshandler_h__ */