shibsp/attribute/Attribute.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 shibsp/attribute/Attribute.h
  23  *
  24  * A resolved attribute.
  25  */
  26
  27 #ifndef __shibsp_attribute_h__
  28 #define __shibsp_attribute_h__
  29
  30 #include <shibsp/remoting/ddf.h>
  31
  32 #include <map>
  33 #include <string>
  34 #include <vector>
  35
  36 namespace shibsp {
  37
  38 #if defined (_MSC_VER)
  39     #pragma warning( push )
  40     #pragma warning( disable : 4251 )
  41 #endif
  42
  43     /**
  44      * A resolved attribute.
  45      *
  46      * <p>Resolved attributes are a neutral construct that represent both simple and
  47      * complex attribute data structures that might be found in SAML assertions
  48      * or obtained from other sources.
  49      *
  50      * <p>Attributes consist of an id/name that is locally unique (that is, unique to a
  51      * configuration at any given point in time) and zero or more values. Values can
  52      * be of any type or structure, but will generally be made available to applications
  53      * only if a serialized string form exists. More complex values can be used with
  54      * access control plugins and other components that understand them, however.
  55      */
  56     class SHIBSP_API Attribute
  57     {
  58         MAKE_NONCOPYABLE(Attribute);
  59     protected:
  60         /**
  61          * Constructor
  62          *
  63          * @param ids   array with primary identifier in first position, followed by any aliases
  64          */
  65         Attribute(const std::vector<std::string>& ids);
  66
  67         /**
  68          * Constructs based on a remoted Attribute.
  69          *
  70          * <p>This allows Attribute objects to be recreated after marshalling.
  71          * The DDF supplied must be a struct containing a single list member named
  72          * with the Attribute's "id" and containing the values.
  73          *
  74          * @param in    input object containing marshalled Attribute
  75          */
  76         Attribute(DDF& in);
  77
  78         /**
  79          * Maintains a copy of serialized attribute values, when possible.
  80          *
  81          * <p>Implementations should maintain the array when values are added or removed.
  82          */
  83         mutable std::vector<std::string> m_serialized;
  84
  85     public:
  86         virtual ~Attribute();
  87
  88         /**
  89          * Returns the Attribute identifier.
  90          *
  91          * @return the Attribute identifier
  92          */
  93         const char* getId() const;
  94
  95         /**
  96          * Returns all of the effective names for the Attribute.
  97          *
  98          * @return immutable array of identifiers, with the primary ID in the first position
  99          */
 100         const std::vector<std::string>& getAliases() const;
 101
 102         /**
 103          * Returns all of the effective names for the Attribute.
 104          *
 105          * @return mutable array of identifiers, with the primary ID in the first position
 106          */
 107         std::vector<std::string>& getAliases();
 108
 109         /**
 110          * Sets whether case sensitivity should apply to basic value comparisons.
 111          *
 112          * @param caseSensitive  true iff value comparisons should be case sensitive
 113          */
 114         void setCaseSensitive(bool caseSensitive);
 115
 116         /**
 117          * Sets whether the attribute should be exported for CGI use.
 118          *
 119          * @param internal  true iff the attribute should <strong>NOT</strong> be exported
 120          */
 121         void setInternal(bool internal);
 122
 123         /**
 124          * Indicates whether case sensitivity should apply to basic value comparisons.
 125          *
 126          * @return  true iff value comparisons should be case sensitive
 127          */
 128         bool isCaseSensitive() const;
 129
 130         /**
 131          * Indicates whether the attribute should be exported for CGI use.
 132          *
 133          * @return  true iff the attribute should <strong>NOT</strong> be exported
 134          */
 135         bool isInternal() const;
 136
 137         /**
 138          * Returns the number of values.
 139          *
 140          * @return  number of values
 141          */
 142         virtual size_t valueCount() const;
 143
 144         /**
 145          * Returns serialized Attribute values encoded as UTF-8 strings.
 146          *
 147          * @return  an immutable vector of values
 148          */
 149         virtual const std::vector<std::string>& getSerializedValues() const;
 150
 151         /**
 152          * Informs the Attribute that values have changed and any serializations
 153          * must be cleared.
 154          */
 155         virtual void clearSerializedValues()=0;
 156
 157         /**
 158          * Gets the string equivalent of the value at the specified position (starting from zero).
 159          *
 160          * @param index position of value
 161          * @return the specified value in its "string" form, or nullptr if undefined
 162          */
 163         virtual const char* getString(size_t index) const;
 164
 165         /**
 166          * Gets the "scope" of the value at the specified position (starting from zero).
 167          *
 168          * @param index position of value
 169          * @return the specified value's "scope", or nullptr if attribute is unscoped
 170          */
 171         virtual const char* getScope(size_t index) const;
 172
 173         /**
 174          * Removes the value at the specified position (starting from zero).
 175          *
 176          * @param index position of value to remove
 177          */
 178         virtual void removeValue(size_t index);
 179
 180         /**
 181          * Marshalls an Attribute for remoting.
 182          *
 183          * <p>This allows Attribute objects to be communicated across process boundaries
 184          * without excess XML parsing. The DDF returned must be a struct containing
 185          * a single list member named with the Attribute's "id". The name of the struct
 186          * should contain the registered name of the Attribute implementation.
 187          */
 188         virtual DDF marshall() const;
 189
 190         /**
 191          * Unmarshalls a remoted Attribute.
 192          *
 193          * @param in    remoted Attribute data
 194          * @return  a resolved Attribute of the proper subclass
 195          */
 196         static Attribute* unmarshall(DDF& in);
 197
 198         /** A function that unmarshalls remoted data into the proper Attribute subclass. */
 199         typedef Attribute* AttributeFactory(DDF& in);
 200
 201         /**
 202          * Registers an AttributeFactory function for a given attribute "type".
 203          *
 204          * @param type      string used at the root of remoted Attribute structures
 205          * @param factory   factory function
 206          */
 207         static void registerFactory(const char* type, AttributeFactory* factory);
 208
 209         /**
 210          * Deregisters an AttributeFactory function for a given attribute "type".
 211          *
 212          * @param type      string used at the root of remoted Attribute structures
 213          */
 214         static void deregisterFactory(const char* type);
 215
 216         /**
 217          * Clears the map of factories.
 218          */
 219         static void deregisterFactories();
 220
 221     private:
 222         static std::map<std::string,AttributeFactory*> m_factoryMap;
 223         std::vector<std::string> m_id;
 224         bool m_caseSensitive,m_internal;
 225     };
 226
 227 #if defined (_MSC_VER)
 228     #pragma warning( pop )
 229 #endif
 230
 231     /** Registers built-in Attribute types into the runtime. */
 232     void registerAttributeFactories();
 233
 234 };
 235
 236 #endif /* __shibsp_attribute_h__ */