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) : m_id(ids), m_caseSensitive(true), m_internal(false) {
  62         }
  63
  64         /**
  65          * Constructs based on a remoted Attribute.
  66          *
  67          * <p>This allows Attribute objects to be recreated after marshalling.
  68          * The DDF supplied must be a struct containing a single list member named
  69          * with the Attribute's "id" and containing the values.
  70          *
  71          * @param in    input object containing marshalled Attribute
  72          */
  73         Attribute(DDF& in);
  74
  75         /**
  76          * Maintains a copy of serialized attribute values, when possible.
  77          *
  78          * <p>Implementations should maintain the array when values are added or removed.
  79          */
  80         mutable std::vector<std::string> m_serialized;
  81
  82     public:
  83         virtual ~Attribute();
  84
  85         /**
  86          * Returns the Attribute identifier.
  87          *
  88          * @return the Attribute identifier
  89          */
  90         const char* getId() const;
  91
  92         /**
  93          * Returns all of the effective names for the Attribute.
  94          *
  95          * @return immutable array of identifiers, with the primary ID in the first position
  96          */
  97         const std::vector<std::string>& getAliases() const;
  98
  99         /**
 100          * Returns all of the effective names for the Attribute.
 101          *
 102          * @return mutable array of identifiers, with the primary ID in the first position
 103          */
 104         std::vector<std::string>& getAliases();
 105
 106         /**
 107          * Sets whether case sensitivity should apply to basic value comparisons.
 108          *
 109          * @param caseSensitive  true iff value comparisons should be case sensitive
 110          */
 111         void setCaseSensitive(bool caseSensitive);
 112
 113         /**
 114          * Sets whether the attribute should be exported for CGI use.
 115          *
 116          * @param export  true iff the attribute should <strong>NOT</strong> be exported
 117          */
 118         void setInternal(bool internal);
 119
 120         /**
 121          * Indicates whether case sensitivity should apply to basic value comparisons.
 122          *
 123          * @return  true iff value comparisons should be case sensitive
 124          */
 125         bool isCaseSensitive() const;
 126
 127         /**
 128          * Indicates whether the attribute should be exported for CGI use.
 129          *
 130          * @return  true iff the attribute should <strong>NOT</strong> be exported
 131          */
 132         bool isInternal() const;
 133
 134         /**
 135          * Returns the number of values.
 136          *
 137          * @return  number of values
 138          */
 139         virtual size_t valueCount() const;
 140
 141         /**
 142          * Returns serialized Attribute values encoded as UTF-8 strings.
 143          *
 144          * @return  an immutable vector of values
 145          */
 146         virtual const std::vector<std::string>& getSerializedValues() const;
 147
 148         /**
 149          * Informs the Attribute that values have changed and any serializations
 150          * must be cleared.
 151          */
 152         virtual void clearSerializedValues()=0;
 153
 154         /**
 155          * Gets the string equivalent of the value at the specified position (starting from zero).
 156          *
 157          * @param index position of value
 158          * @return the specified value in its "string" form, or NULL if undefined
 159          */
 160         virtual const char* getString(size_t index) const;
 161
 162         /**
 163          * Gets the "scope" of the value at the specified position (starting from zero).
 164          *
 165          * @param index position of value
 166          * @return the specified value's "scope", or NULL if attribute is unscoped
 167          */
 168         virtual const char* getScope(size_t index) const;
 169
 170         /**
 171          * Removes the value at the specified position (starting from zero).
 172          *
 173          * @param index position of value to remove
 174          */
 175         virtual void removeValue(size_t index);
 176
 177         /**
 178          * Marshalls an Attribute for remoting.
 179          *
 180          * <p>This allows Attribute objects to be communicated across process boundaries
 181          * without excess XML parsing. The DDF returned must be a struct containing
 182          * a single list member named with the Attribute's "id". The name of the struct
 183          * should contain the registered name of the Attribute implementation.
 184          */
 185         virtual DDF marshall() const;
 186
 187         /**
 188          * Unmarshalls a remoted Attribute.
 189          *
 190          * @param in    remoted Attribute data
 191          * @return  a resolved Attribute of the proper subclass
 192          */
 193         static Attribute* unmarshall(DDF& in);
 194
 195         /** A function that unmarshalls remoted data into the proper Attribute subclass. */
 196         typedef Attribute* AttributeFactory(DDF& in);
 197
 198         /**
 199          * Registers an AttributeFactory function for a given attribute "type".
 200          *
 201          * @param type      string used at the root of remoted Attribute structures
 202          * @param factory   factory function
 203          */
 204         static void registerFactory(const char* type, AttributeFactory* factory);
 205
 206         /**
 207          * Deregisters an AttributeFactory function for a given attribute "type".
 208          *
 209          * @param type      string used at the root of remoted Attribute structures
 210          */
 211         static void deregisterFactory(const char* type);
 212
 213         /**
 214          * Clears the map of factories.
 215          */
 216         static void deregisterFactories();
 217
 218     private:
 219         static std::map<std::string,AttributeFactory*> m_factoryMap;
 220         std::vector<std::string> m_id;
 221         bool m_caseSensitive,m_internal;
 222     };
 223
 224 #if defined (_MSC_VER)
 225     #pragma warning( pop )
 226 #endif
 227
 228     /** Registers built-in Attribute types into the runtime. */
 229     void registerAttributeFactories();
 230
 231 };
 232
 233 #endif /* __shibsp_attribute_h__ */