saml/saml2/metadata/MetadataProvider.h

   1 /*
   2  *  Copyright 2001-2006 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 saml/saml2/metadata/MetadataProvider.h
  19  *
  20  * Supplies an individual source of metadata.
  21  */
  22
  23 #ifndef __saml2_metadataprov_h__
  24 #define __saml2_metadataprov_h__
  25
  26 #include <xmltooling/Lockable.h>
  27 #include <saml/saml2/metadata/MetadataFilter.h>
  28
  29 namespace opensaml {
  30
  31     namespace saml2md {
  32
  33         /**
  34          * Supplies an individual source of metadata.
  35          *
  36          * The source can be a local file, remote service, or the result of a
  37          * dynamic lookup, can include local caching, etc.
  38          */
  39         class SAML_API MetadataProvider : public virtual xmltooling::Lockable
  40         {
  41             MAKE_NONCOPYABLE(MetadataProvider);
  42
  43         protected:
  44             /**
  45              * Constructor. If a DOM is supplied, a set of default logic will be
  46              * used to identify and build MetadataFilter plugins and install them
  47              * into the provider. The following XML content is supported:
  48              *
  49              * <ul>
  50              *  <li>&lt;MetadataFilter&gt; elements with a type attribute
  51              *  <li>&lt;Exclude&gt; elements representing a BlacklistMetadataFilter
  52              *  <li>&lt;BlacklistMetadataFilter&gt; element containing &lt;Exclude&gt; elements
  53              *  <li>&lt;Include&gt; elements representing a WhitelistMetadataFilter
  54              *  <li>&lt;WhitelistMetadataFilter&gt; element containing &lt;Include&gt; elements
  55              * </ul>
  56              *
  57              * XML namespaces are ignored in the processing of these elements.
  58              *
  59              * @param e DOM to supply configuration for provider
  60              */
  61             MetadataProvider(const DOMElement* e=NULL);
  62
  63         public:
  64             /**
  65              * Destructor will delete any installed filters.
  66              */
  67             virtual ~MetadataProvider();
  68
  69             /**
  70              * Adds a metadata filter to apply to any resolved metadata. Will not be applied
  71              * to metadata that is already loaded.
  72              *
  73              * @param newFilter metadata filter to add
  74              */
  75             virtual void addMetadataFilter(MetadataFilter* newFilter) {
  76                 m_filters.push_back(newFilter);
  77             }
  78
  79             /**
  80              * Removes a metadata filter. The caller must delete the filter if necessary.
  81              *
  82              * @param oldFilter metadata filter to remove
  83              * @return  the old filter
  84              */
  85             virtual MetadataFilter* removeMetadataFilter(MetadataFilter* oldFilter) {
  86                 for (std::vector<MetadataFilter*>::iterator i=m_filters.begin(); i!=m_filters.end(); i++) {
  87                     if (oldFilter==(*i)) {
  88                         m_filters.erase(i);
  89                         return oldFilter;
  90                     }
  91                 }
  92                 return NULL;
  93             }
  94
  95             /**
  96              * Should be called after instantiating provider and adding filters, but before
  97              * performing any lookup operations. Allows the provider to defer initialization
  98              * processes that are likely to result in exceptions until after the provider is
  99              * safely created. Providers SHOULD perform as much processing as possible in
 100              * this method so as to report/log any errors that would affect later processing.
 101              */
 102             virtual void init()=0;
 103
 104             /**
 105              * Gets the entire metadata tree, after the registered filter has been applied.
 106              * The caller MUST unlock the provider when finished with the data.
 107              *
 108              * @return the entire metadata tree
 109              */
 110             virtual const xmltooling::XMLObject* getMetadata() const=0;
 111
 112             /**
 113              * Gets the metadata for a given entity. If a valid entity is returned,
 114              * the provider will be left in a locked state. The caller MUST unlock the
 115              * provider when finished with the entity.
 116              *
 117              * @param id                    the ID of the entity
 118              * @param requireValidMetadata  indicates whether the metadata for the entity must be valid/current
 119              *
 120              * @return the entity's metadata or NULL if there is no metadata or no valid metadata
 121              */
 122             virtual const EntityDescriptor* getEntityDescriptor(const XMLCh* id, bool requireValidMetadata=true) const=0;
 123
 124             /**
 125              * Gets the metadata for a given entity. If a valid entity is returned,
 126              * the provider will be left in a locked state. The caller MUST unlock the
 127              * provider when finished with the entity.
 128              *
 129              * @param id                    the ID of the entity
 130              * @param requireValidMetadata  indicates whether the metadata for the entity must be valid/current
 131              *
 132              * @return the entity's metadata or NULL if there is no metadata or no valid metadata
 133              */
 134             virtual const EntityDescriptor* getEntityDescriptor(const char* id, bool requireValidMetadata=true) const=0;
 135
 136             /**
 137              * Gets the metadata for a given group of entities. If a valid group is returned,
 138              * the resolver will be left in a locked state. The caller MUST unlock the
 139              * resolver when finished with the group.
 140              *
 141              * @param name                  the name of the group
 142              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 143              *
 144              * @return the group's metadata or NULL if there is no metadata or no valid metadata
 145              */
 146             virtual const EntitiesDescriptor* getEntitiesDescriptor(const XMLCh* name, bool requireValidMetadata=true) const=0;
 147
 148             /**
 149              * Gets the metadata for a given group of entities. If a valid group is returned,
 150              * the resolver will be left in a locked state. The caller MUST unlock the
 151              * resolver when finished with the group.
 152              *
 153              * @param name                  the name of the group
 154              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 155              *
 156              * @return the group's metadata or NULL if there is no metadata or no valid metadata
 157              */
 158             virtual const EntitiesDescriptor* getEntitiesDescriptor(const char* name, bool requireValidMetadata=true) const=0;
 159
 160         protected:
 161             /**
 162              * Applies any installed filters to a metadata instance.
 163              *
 164              * @param xmlObject the metadata to be filtered
 165              */
 166             void doFilters(xmltooling::XMLObject& xmlObject) const;
 167
 168         private:
 169             std::vector<MetadataFilter*> m_filters;
 170         };
 171
 172         /**
 173          * Registers MetadataProvider classes into the runtime.
 174          */
 175         void SAML_API registerMetadataProviders();
 176
 177         /** MetadataProvider based on local XML files */
 178         #define FILESYSTEM_METADATA_PROVIDER  "org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider"
 179     };
 180 };
 181
 182 #endif /* __saml2_metadataprov_h__ */