Dynamic metadata provider implementation.
[shibboleth/opensaml2.git] / saml / saml2 / metadata / MetadataProvider.h
index 3f5f814..2e9b4b9 100644 (file)
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2006 Internet2
+ *  Copyright 2001-2007 Internet2
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
  */
 
 /**
- * @file MetadataProvider.h
+ * @file saml/saml2/metadata/MetadataProvider.h
  * 
  * Supplies an individual source of metadata.
  */
 #ifndef __saml2_metadataprov_h__
 #define __saml2_metadataprov_h__
 
-#include <xmltooling/Lockable.h>
-#include <saml/saml2/metadata/MetadataFilter.h>
+#include <saml/base.h>
+#include <xmltooling/exceptions.h>
+#include <xmltooling/XMLObject.h>
+#include <xmltooling/security/CredentialResolver.h>
 
 namespace opensaml {
+    
+    class SAML_API SAMLArtifact;
 
     namespace saml2md {
-        
+
+        class SAML_API EntityDescriptor;
+        class SAML_API EntitiesDescriptor;
+        class SAML_API RoleDescriptor;
+        class SAML_API MetadataCredentialResolver;
+        class SAML_API MetadataFilter;
+
+#if defined (_MSC_VER)
+        #pragma warning( push )
+        #pragma warning( disable : 4251 )
+#endif
+
         /**
          * Supplies an individual source of metadata.
          * 
          * The source can be a local file, remote service, or the result of a
-         * dynamic lookup, can include local caching, etc.
+         * dynamic lookup, can include local caching, etc. Providers
+         * <strong>MUST</strong> be locked before any lookup operations.
          */
-        class SAML_API MetadataProvider : public virtual xmltooling::Lockable
+        class SAML_API MetadataProvider : public virtual xmltooling::CredentialResolver
         {
             MAKE_NONCOPYABLE(MetadataProvider);
         protected:
-            MetadataProvider() : m_filter(NULL) {}
+            /**
+             * Constructor.
+             * 
+             * If a DOM is supplied, a set of default logic will be used to identify
+             * and build MetadataFilter plugins and install them into the provider.
+             * 
+             * The following XML content is supported:
+             * 
+             * <ul>
+             *  <li>&lt;MetadataFilter&gt; elements with a type attribute and type-specific content
+             *  <li>&lt;Exclude&gt; elements representing a BlacklistMetadataFilter
+             *  <li>&lt;BlacklistMetadataFilter&gt; element containing &lt;Exclude&gt; elements 
+             *  <li>&lt;Include&gt; elements representing a WhitelistMetadataFilter
+             *  <li>&lt;SignatureMetadataFilter&gt; element containing a &lt;KeyResolver&gt; element 
+             *  <li>&lt;WhitelistMetadataFilter&gt; element containing &lt;Include&gt; elements 
+             * </ul>
+             * 
+             * XML namespaces are ignored in the processing of these elements.
+             * 
+             * @param e DOM to supply configuration for provider
+             */
+            MetadataProvider(const xercesc::DOMElement* e=NULL);
             
         public:
-            virtual ~MetadataProvider() {
-                delete m_filter;
-            }
+            /**
+             * Destructor will delete any installed filters.
+             */
+            virtual ~MetadataProvider();
             
             /**
-             * Gets the metadata filter applied to the resolved metadata.
+             * Adds a metadata filter to apply to any resolved metadata. Will not be applied
+             * to metadata that is already loaded.
              * 
-             * @return the metadata filter applied to the resolved metadata
+             * @param newFilter metadata filter to add
              */
-            const MetadataFilter* getMetadataFilter() const {
-                return m_filter;
+            virtual void addMetadataFilter(MetadataFilter* newFilter) {
+                m_filters.push_back(newFilter);
             }
-        
+
             /**
-             * Sets the metadata filter applied to the resolved metadata.
+             * Removes a metadata filter. The caller must delete the filter if necessary.
              * 
-             * @param newFilter the metadata filter applied to the resolved metadata
+             * @param oldFilter metadata filter to remove
+             * @return  the old filter
              */
-            void setMetadataFilter(MetadataFilter* newFilter) {
-                delete m_filter;
-                m_filter=newFilter;
+            virtual MetadataFilter* removeMetadataFilter(MetadataFilter* oldFilter) {
+                for (std::vector<MetadataFilter*>::iterator i=m_filters.begin(); i!=m_filters.end(); i++) {
+                    if (oldFilter==(*i)) {
+                        m_filters.erase(i);
+                        return oldFilter;
+                    }
+                }
+                return NULL;
             }
             
             /**
-             * Should be called after instantiating provider and setting filter, but before
+             * Should be called after instantiating provider and adding filters, but before
              * performing any lookup operations. Allows the provider to defer initialization
              * processes that are likely to result in exceptions until after the provider is
              * safely created. Providers SHOULD perform as much processing as possible in
              * this method so as to report/log any errors that would affect later processing.
-             * Also, any inputs supplied to the factory MUST persist until the completion of
-             * this method, but the caller is then free to modify or delete them.
              */
             virtual void init()=0;
             
@@ -95,7 +138,7 @@ namespace opensaml {
              * 
              * @return the entity's metadata or NULL if there is no metadata or no valid metadata
              */
-            virtual const EntityDescriptor* getEntityDescriptor(const XMLCh* id, bool requireValidMetadata=true) const=0;
+            virtual const EntityDescriptor* getEntityDescriptor(const XMLCh* id, bool requireValidMetadata=true) const;
 
             /**
              * Gets the metadata for a given entity. If a valid entity is returned,
@@ -110,6 +153,17 @@ namespace opensaml {
             virtual const EntityDescriptor* getEntityDescriptor(const char* id, bool requireValidMetadata=true) const=0;
 
             /**
+             * Gets the metadata for an entity that issued a SAML artifact. If a valid entity is returned,
+             * the provider will be left in a locked state. The caller MUST unlock the
+             * provider when finished with the entity.
+             *  
+             * @param artifact              a SAML artifact to find the issuer of
+             * 
+             * @return the entity's metadata or NULL if there is no valid metadata
+             */
+            virtual const EntityDescriptor* getEntityDescriptor(const SAMLArtifact* artifact) const=0;
+
+            /**
              * Gets the metadata for a given group of entities. If a valid group is returned,
              * the resolver will be left in a locked state. The caller MUST unlock the
              * resolver when finished with the group.
@@ -119,7 +173,7 @@ namespace opensaml {
              * 
              * @return the group's metadata or NULL if there is no metadata or no valid metadata
              */
-            virtual const EntitiesDescriptor* getEntitiesDescriptor(const XMLCh* name, bool requireValidMetadata=true) const=0;
+            virtual const EntitiesDescriptor* getEntitiesDescriptor(const XMLCh* name, bool requireValidMetadata=true) const;
 
             /**
              * Gets the metadata for a given group of entities. If a valid group is returned,
@@ -134,16 +188,36 @@ namespace opensaml {
             virtual const EntitiesDescriptor* getEntitiesDescriptor(const char* name, bool requireValidMetadata=true) const=0;
 
         protected:
-            MetadataFilter* m_filter;
+            /**
+             * Applies any installed filters to a metadata instance.
+             * 
+             * @param xmlObject the metadata to be filtered
+             */
+            void doFilters(xmltooling::XMLObject& xmlObject) const;
+
+        private:
+            std::vector<MetadataFilter*> m_filters;
         };
-        
+
+#if defined (_MSC_VER)
+        #pragma warning( pop )
+#endif
+
         /**
          * Registers MetadataProvider classes into the runtime.
          */
         void SAML_API registerMetadataProviders();
         
-        /** MetadataProvider based on local XML files */
-        #define FILESYSTEM_METADATA_PROVIDER  "org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider"
+        /** MetadataProvider based on local or remote XML file */
+        #define XML_METADATA_PROVIDER  "XML"
+
+        /** MetadataProvider based on dynamic resolution */
+        #define DYNAMIC_METADATA_PROVIDER  "Dynamic"
+
+        /** MetadataProvider that wraps a sequence of metadata providers. */
+        #define CHAINING_METADATA_PROVIDER  "Chaining"
+
+        DECL_XMLTOOLING_EXCEPTION(MetadataException,SAML_EXCEPTIONAPI(SAML_API),opensaml::saml2md,xmltooling::XMLToolingException,Exceptions related to metadata use);
     };
 };