shibsp/attribute/Attribute.h

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