data.h 21.3 KB
Newer Older
Jelte Jansen's avatar
Jelte Jansen committed
1
// Copyright (C) 2010  Internet Systems Consortium, Inc. ("ISC")
2 3 4 5 6 7 8 9 10 11 12 13 14
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

15 16 17 18 19 20 21
#ifndef _ISC_DATA_H
#define _ISC_DATA_H 1

#include <string>
#include <vector>
#include <map>
#include <boost/shared_ptr.hpp>
22
#include <stdexcept>
23
#include <exceptions/exceptions.h>
24

Jelte Jansen's avatar
Jelte Jansen committed
25
namespace isc { namespace data {
26

27 28 29
class Element;
// todo: describe the rationale behind ElementPtr?
typedef boost::shared_ptr<Element> ElementPtr;
30
typedef boost::shared_ptr<const Element> ConstElementPtr;
31 32 33 34 35 36

///
/// \brief A standard Data module exception that is thrown if a function
/// is called for an Element that has a wrong type (e.g. int_value on a
/// ListElement)
///
37
class TypeError : public isc::Exception {
38
public:
Jelte Jansen's avatar
Jelte Jansen committed
39
    TypeError(const char* file, size_t line, const char* what) :
40
        isc::Exception(file, line, what) {}
41 42 43 44 45 46
};

///
/// \brief A standard Data module exception that is thrown if a parse
/// error is encountered when constructing an Element from a string
///
Jelte Jansen's avatar
Jelte Jansen committed
47 48 49
// i'd like to use Exception here but we need one that is derived from
// runtime_error (as this one is directly based on external data, and
// i want to add some values to any static data string that is provided)
50
class JSONError : public isc::Exception {
51
public:
52 53
    JSONError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
54 55 56 57 58 59 60 61 62 63 64
};

///
/// \brief The \c Element class represents a piece of data, used by
/// the command channel and configuration parts.
///
/// An \c Element can contain simple types (int, real, string, bool and
/// None), and composite types (list and string->element maps)
///
/// Elements should in calling functions usually be referenced through
/// an \c ElementPtr, which can be created using the factory functions
65
/// \c Element::create() and \c Element::fromJSON()
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
///
/// Notes to developers: Element is a base class, implemented by a
/// specific subclass for each type (IntElement, BoolElement, etc).
/// Element does define all functions for all types, and defaults to
/// raising a \c TypeError for functions that are not supported for
/// the type in question.
///
class Element {
    
private:
    // technically the type could be omitted; is it useful?
    // should we remove it or replace it with a pure virtual
    // function getType?
    int type;

protected:
    Element(int t) { type = t; }

public:
85 86
    // any is a special type used in list specifications, specifying
    // that the elements can be of any type
87
    enum types { integer, real, boolean, null, string, list, map, any };
88 89 90 91
    // base class; make dtor virtual
    virtual ~Element() {};

    /// \return the type of this element
92
    int getType() const { return (type); }
93

94 95 96
    /// Returns a string representing the Element and all its
    /// child elements; note that this is different from stringValue(),
    /// which only returns the single value of a StringElement
Jelte Jansen's avatar
Jelte Jansen committed
97 98
    ///
    /// The resulting string will contain the Element in JSON format.
99 100
    ///
    /// \return std::string containing the string representation
101
    std::string str() const;
102 103 104 105 106

    /// Returns the wireformat for the Element and all its child
    /// elements.
    ///
    /// \return std::string containing the element in wire format
107 108
    std::string toWire() const;
    void toWire(std::ostream& out) const;
109

110
    /// \name pure virtuals, every derived class must implement these
Jelte Jansen's avatar
Jelte Jansen committed
111

112 113
    /// \returns true if the other ElementPtr has the same type and
    ///          value
114
    virtual bool equals(const Element& other) const = 0;
115
    
Jelte Jansen's avatar
Jelte Jansen committed
116 117
    /// Converts the Element to JSON format and appends it to
    /// the given stringstream.
118
    virtual void toJSON(std::ostream& ss) const = 0;
Jelte Jansen's avatar
Jelte Jansen committed
119

120 121 122 123 124 125 126 127
    /// \name Type-specific getters
    ///
    /// \brief These functions only
    /// work on their corresponding Element type. For all other
    /// types, a TypeError is thrown.
    /// If you want an exception-safe getter method, use
    /// getValue() below
    //@{
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
    virtual long int intValue() const
    { isc_throw(TypeError, "intValue() called on non-integer Element"); };
    virtual double doubleValue() const
    { isc_throw(TypeError, "doubleValue() called on non-double Element"); };
    virtual bool boolValue() const
    { isc_throw(TypeError, "boolValue() called on non-Bool Element"); };
    virtual std::string stringValue() const
    { isc_throw(TypeError, "stringValue() called on non-string Element"); };
    virtual const std::vector<ConstElementPtr>& listValue() const {
        // replace with real exception or empty vector?
        isc_throw(TypeError, "listValue() called on non-list Element");
    };
    virtual const std::map<std::string, ConstElementPtr>& mapValue() const {
        // replace with real exception or empty map?
        isc_throw(TypeError, "mapValue() called on non-map Element");
    };
144 145 146 147 148 149 150 151 152 153 154
    //@}

    /// \name Exception-safe getters
    ///
    /// \brief The getValue() functions return false if the given reference
    /// is of another type than the element contains
    /// By default it always returns false; the derived classes
    /// override the function for their type, copying their
    /// data to the given reference and returning true
    ///
    //@{
Jelte Jansen's avatar
Jelte Jansen committed
155
    virtual bool getValue(long int& t);
156 157 158
    virtual bool getValue(double& t);
    virtual bool getValue(bool& t);
    virtual bool getValue(std::string& t);
159 160
    virtual bool getValue(std::vector<ConstElementPtr>& t);
    virtual bool getValue(std::map<std::string, ConstElementPtr>& t);
161
    //@}
162

163 164 165 166 167 168 169 170
    ///
    /// \name Exception-safe setters.
    ///
    /// \brief Return false if the Element is not
    /// the right type. Set the value and return true if the Elements
    /// is of the correct type
    ///
    //@{
Jelte Jansen's avatar
Jelte Jansen committed
171
    virtual bool setValue(const long int v);
172 173 174
    virtual bool setValue(const double v);
    virtual bool setValue(const bool t);
    virtual bool setValue(const std::string& v);
175 176
    virtual bool setValue(const std::vector<ConstElementPtr>& v);
    virtual bool setValue(const std::map<std::string, ConstElementPtr>& v);
177 178 179 180 181 182 183 184 185 186 187 188 189 190
    //@}



    // Other functions for specific subtypes

    /// \name ListElement functions
    ///
    /// \brief If the Element on which these functions are called are not
    /// an instance of ListElement, a TypeError exception is thrown.
    //@{
    /// Returns the ElementPtr at the given index. If the index is out
    /// of bounds, this function throws an std::out_of_range exception.
    /// \param i The position of the ElementPtr to return
191
    virtual ConstElementPtr get(const int i) const;
192

193 194 195 196
    /// Sets the ElementPtr at the given index. If the index is out
    /// of bounds, this function throws an std::out_of_range exception.
    /// \param i The position of the ElementPtr to set
    /// \param element The ElementPtr to set at the position
197
    virtual void set(const size_t i, ConstElementPtr element);
198

199 200
    /// Adds an ElementPtr to the list
    /// \param element The ElementPtr to add
201
    virtual void add(ConstElementPtr element);
202

203 204 205
    /// Removes the element at the given position. If the index is out
    /// of nothing happens.
    /// \param i The index of the element to remove.
206
    virtual void remove(const int i);
207

208
    /// Returns the number of elements in the list.
209
    virtual size_t size() const;
210
    //@}
211

212 213 214 215 216 217 218 219 220
    
    /// \name MapElement functions
    ///
    /// \brief If the Element on which these functions are called are not
    /// an instance of MapElement, a TypeError exception is thrown.
    //@{
    /// Returns the ElementPtr at the given key
    /// \param name The key of the Element to return
    /// \return The ElementPtr at the given key
221
    virtual ConstElementPtr get(const std::string& name) const;
222

223 224
    /// Sets the ElementPtr at the given key
    /// \param name The key of the Element to set
225
    /// \param element The ElementPtr to set at the given key.
226
    virtual void set(const std::string& name, ConstElementPtr element);
227

228 229
    /// Remove the ElementPtr at the given key
    /// \param name The key of the Element to remove
230
    virtual void remove(const std::string& name);
231

232 233 234
    /// Checks if there is data at the given key
    /// \param name The key of the Element to remove
    /// \return true if there is data at the key, false if not.
235
    virtual bool contains(const std::string& name) const;
236

237 238 239 240 241 242 243 244 245 246 247 248 249
    /// Recursively finds any data at the given identifier. The
    /// identifier is a /-separated list of names of nested maps, with
    /// the last name being the leaf that is returned.
    ///
    /// For instance, if you have a MapElement that contains another
    /// MapElement at the key "foo", and that second MapElement contains
    /// Another Element at key "bar", the identifier for that last
    /// element from the first is "foo/bar".
    ///
    /// \param identifier The identifier of the element to find
    /// \return The ElementPtr at the given identifier. Returns a
    /// null ElementPtr if it is not found, which can be checked with
    /// Element::is_null(ElementPtr e).
250
    virtual ConstElementPtr find(const std::string& identifier) const;
251

252 253 254 255
    /// See \c Element::find()
    /// \param identifier The identifier of the element to find
    /// \param t Reference to store the resulting ElementPtr, if found.
    /// \return true if the element was found, false if not.
256
    virtual bool find(const std::string& identifier, ConstElementPtr t) const;
257 258
    //@}

259

260
    /// \name Factory functions
261
    
262 263 264 265 266 267 268 269
    // TODO: should we move all factory functions to a different class
    // so as not to burden the Element base with too many functions?
    // and/or perhaps even to a separate header?

    /// \name Direct factory functions
    /// \brief These functions simply wrap the given data directly
    /// in an Element object, and return a reference to it, in the form
    /// of an \c ElementPtr.
270 271 272
    /// These factory functions are exception-free (unless there is
    /// no memory available, in which case bad_alloc is raised by the
    /// underlying system).
273 274
    /// (Note that that is different from an NullElement, which
    /// represents an empty value, and is created with Element::create())
275
    //@{
276
    static ElementPtr create();
Jelte Jansen's avatar
Jelte Jansen committed
277
    static ElementPtr create(const long int i);
JINMEI Tatuya's avatar
JINMEI Tatuya committed
278
    static ElementPtr create(const int i) { return (create(static_cast<long int>(i))); };
279 280 281 282 283
    static ElementPtr create(const double d);
    static ElementPtr create(const bool b);
    static ElementPtr create(const std::string& s);
    // need both std:string and char *, since c++ will match
    // bool before std::string when you pass it a char *
JINMEI Tatuya's avatar
JINMEI Tatuya committed
284
    static ElementPtr create(const char *s) { return (create(std::string(s))); }
285 286 287

    /// \brief Creates an empty ListElement type ElementPtr.
    static ElementPtr createList();
288

289 290
    /// \brief Creates an empty MapElement type ElementPtr.
    static ElementPtr createMap();
291 292
    //@}

293

294 295
    /// \name Compound factory functions

Jelte Jansen's avatar
Jelte Jansen committed
296 297
    /// \brief These functions will parse the given string (JSON)
    /// representation  of a compound element. If there is a parse
Jelte Jansen's avatar
Jelte Jansen committed
298
    /// error, an exception of the type isc::data::JSONError is thrown.
299 300

    //@{
301
    /// Creates an Element from the given JSON string
302 303 304
    /// \param in The string to parse the element from
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given string.
305
    static ElementPtr fromJSON(const std::string& in);
Jelte Jansen's avatar
Jelte Jansen committed
306

307 308 309
    /// Creates an Element from the given input stream containing JSON
    /// formatted data.
    ///
310 311 312
    /// \param in The string to parse the element from
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given input stream.
Jelte Jansen's avatar
Jelte Jansen committed
313 314
    static ElementPtr fromJSON(std::istream& in) throw(JSONError);
    static ElementPtr fromJSON(std::istream& in, const std::string& file_name) throw(JSONError);
315

316 317 318
    /// Creates an Element from the given input stream, where we keep
    /// track of the location in the stream for error reporting.
    ///
319 320
    /// \param in The string to parse the element from.
    /// \param file The input file name.
321 322
    /// \param line A reference to the int where the function keeps
    /// track of the current line.
323
    /// \param pos A reference to the int where the function keeps
324 325 326 327
    /// track of the current position within the current line.
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given input stream.
    // make this one private?
Jelte Jansen's avatar
Jelte Jansen committed
328
    static ElementPtr fromJSON(std::istream& in, const std::string& file, int& line, int &pos) throw(JSONError);
329 330
    //@}

331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346
    /// \name Type name conversion functions

    /// Returns the name of the given type as a string
    ///
    /// \param type The type to return the name of
    /// \return The name of the type, or "unknown" if the type
    ///         is not known.
    static std::string typeToName(Element::types type);

    /// Converts the string to the corresponding type
    /// Throws a TypeError if the name is unknown.
    ///
    /// \param type_name The name to get the type of
    /// \return the corresponding type value
    static Element::types nameToType(const std::string& type_name);

347 348 349 350 351
    /// \name Wire format factory functions

    /// These function pparse the wireformat at the given stringstream
    /// (of the given length). If there is a parse error an exception
    /// of the type isc::cc::DecodeError is raised.
352
    
353 354 355
    //@{
    /// Creates an Element from the wire format in the given
    /// stringstream of the given length.
Jelte Jansen's avatar
Jelte Jansen committed
356
    /// Since the wire format is JSON, thise is the same as
357
    /// fromJSON, and could be removed.
Jelte Jansen's avatar
Jelte Jansen committed
358
    ///
359 360 361 362
    /// \param in The input stringstream.
    /// \param length The length of the wireformat data in the stream
    /// \return ElementPtr with the data that is parsed.
    static ElementPtr fromWire(std::stringstream& in, int length);
Jelte Jansen's avatar
Jelte Jansen committed
363

364
    /// Creates an Element from the wire format in the given string
Jelte Jansen's avatar
Jelte Jansen committed
365
    /// Since the wire format is JSON, thise is the same as
366
    /// fromJSON, and could be removed.
Jelte Jansen's avatar
Jelte Jansen committed
367
    ///
368 369 370 371 372 373 374
    /// \param s The input string
    /// \return ElementPtr with the data that is parsed.
    static ElementPtr fromWire(const std::string& s);
    //@}
};

class IntElement : public Element {
Jelte Jansen's avatar
Jelte Jansen committed
375
    long int i;
376 377

public:
JINMEI Tatuya's avatar
JINMEI Tatuya committed
378
    IntElement(long int v) : Element(integer), i(v) { }
379
    long int intValue() const { return (i); }
380
    using Element::getValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
381
    bool getValue(long int& t) { t = i; return (true); }
382
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
383
    bool setValue(const long int v) { i = v; return (true); }
384 385
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
386 387 388 389 390 391 392
};

class DoubleElement : public Element {
    double d;

public:
    DoubleElement(double v) : Element(real), d(v) {};
393
    double doubleValue() const { return (d); }
394
    using Element::getValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
395
    bool getValue(double& t) { t = d; return (true); }
396
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
397
    bool setValue(const double v) { d = v; return (true); }
398 399
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
400 401 402 403 404 405 406
};

class BoolElement : public Element {
    bool b;

public:
    BoolElement(const bool v) : Element(boolean), b(v) {};
407
    bool boolValue() const { return (b); }
408
    using Element::getValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
409
    bool getValue(bool& t) { t = b; return (true); }
410
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
411
    bool setValue(const bool v) { b = v; return (true); }
412 413
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
414 415 416 417 418
};

class NullElement : public Element {
public:
    NullElement() : Element(null) {};
419 420
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
421 422 423 424 425 426 427
};

class StringElement : public Element {
    std::string s;

public:
    StringElement(std::string v) : Element(string), s(v) {};
428
    std::string stringValue() const { return (s); }
429
    using Element::getValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
430
    bool getValue(std::string& t) { t = s; return (true); }
431
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
432
    bool setValue(const std::string& v) { s = v; return (true); }
433 434
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
435 436 437
};

class ListElement : public Element {
438
    std::vector<ConstElementPtr> l;
439 440

public:
441 442
    ListElement() : Element(list) {}
    const std::vector<ConstElementPtr>& listValue() const { return (l); }
443
    using Element::getValue;
444 445 446 447
    bool getValue(std::vector<ConstElementPtr>& t) {
        t = l;
        return (true);
    }
448
    using Element::setValue;
449 450 451 452
    bool setValue(const std::vector<ConstElementPtr>& v) {
        l = v;
        return (true);
    }
453
    using Element::get;
454
    ConstElementPtr get(int i) const { return (l.at(i)); }
455
    using Element::set;
456 457 458 459
    void set(size_t i, ConstElementPtr e) {
        l.at(i) = e;
    }
    void add(ConstElementPtr e) { l.push_back(e); };
460
    using Element::remove;
461
    void remove(int i) { l.erase(l.begin() + i); };
462 463 464
    void toJSON(std::ostream& ss) const;
    size_t size() const { return (l.size()); }
    bool equals(const Element& other) const;
465 466 467
};

class MapElement : public Element {
468
    std::map<std::string, ConstElementPtr> m;
469 470

public:
471
    MapElement() : Element(map) {}
472
    // TODO: should we have direct iterators instead of exposing the std::map here?
473 474 475
    const std::map<std::string, ConstElementPtr>& mapValue() const {
        return (m);
    }
476
    using Element::getValue;
477 478 479 480
    bool getValue(std::map<std::string, ConstElementPtr>& t) {
        t = m;
        return (true);
    }
481
    using Element::setValue;
482 483 484 485
    bool setValue(std::map<std::string, ConstElementPtr>& v) {
        m = v;
        return (true);
    }
486
    using Element::get;
487
    ConstElementPtr get(const std::string& s) const {
488 489
        return (contains(s) ? m.find(s)->second : ConstElementPtr());
    }
490
    using Element::set;
491
    void set(const std::string& key, ConstElementPtr value);
492
    using Element::remove;
493
    void remove(const std::string& s) { m.erase(s); }
494 495 496 497
    bool contains(const std::string& s) const {
        return (m.find(s) != m.end());
    }
    void toJSON(std::ostream& ss) const;
498 499 500 501 502 503
    
    // we should name the two finds better...
    // find the element at id; raises TypeError if one of the
    // elements at path except the one we're looking for is not a
    // mapelement.
    // returns an empty element if the item could not be found
504
    ConstElementPtr find(const std::string& id) const;
505 506 507 508 509

    // find the Element at 'id', and store the element pointer in t
    // returns true if found, or false if not found (either because
    // it doesnt exist or one of the elements in the path is not
    // a MapElement)
510
    bool find(const std::string& id, ConstElementPtr t) const;
511

512
    bool equals(const Element& other) const;
513 514 515 516 517
};

/// Checks whether the given ElementPtr is a NULL pointer
/// \param p The ElementPtr to check
/// \return true if it is NULL, false if not.
518
bool isNull(ConstElementPtr p);
519

520 521
///
/// \brief Remove all values from the first ElementPtr that are
522
/// equal in the second. Both ElementPtrs MUST be MapElements
523 524 525 526
/// The use for this function is to end up with a MapElement that
/// only contains new and changed values (for ModuleCCSession and
/// configuration update handlers)
/// Raises a TypeError if a or b are not MapElements
527 528 529 530 531 532 533 534
void removeIdentical(ElementPtr a, ConstElementPtr b);

/// \brief Create a new ElementPtr from the first ElementPtr, removing all
/// values that are equal in the second. Both ElementPtrs MUST be MapElements.
/// The returned ElementPtr will be a MapElement that only contains new and
/// changed values (for ModuleCCSession and configuration update handlers).
/// Raises a TypeError if a or b are not MapElements
ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
535

536 537 538 539 540
/// \brief Merges the data from other into element.
/// (on the first level). Both elements must be
/// MapElements.
/// Every string,value pair in other is copied into element
/// (the ElementPtr of value is copied, this is not a new object)
Jelte Jansen's avatar
Jelte Jansen committed
541 542 543 544 545 546
/// Unless the value is a NullElement, in which case the
/// key is removed from element, rather than setting the value to
/// the given NullElement.
/// This way, we can remove values from for instance maps with
/// configuration data (which would then result in reverting back
/// to the default).
547
/// Raises a TypeError if either ElementPtr is not a MapElement
548
void merge(ElementPtr element, ConstElementPtr other);
549

550 551 552
///
/// \brief Insert the Element as a string into stream.
///
553
/// This method converts the \c ElementPtr into a string with
554 555 556 557 558 559
/// \c Element::str() and inserts it into the
/// output stream \c out.
///
/// This function overloads the global operator<< to behave as described in
/// ostream::operator<< but applied to \c ElementPtr objects.
///
560
/// \param out A \c std::ostream object on which the insertion operation is
561 562 563
/// performed.
/// \param e The \c ElementPtr object to insert.
/// \return A reference to the same \c std::ostream object referenced by
564
/// parameter \c out after the insertion operation.
565
std::ostream& operator<<(std::ostream& out, const Element& e);
566

567 568
bool operator==(const Element& a, const Element& b);
bool operator!=(const Element& a, const Element& b);
JINMEI Tatuya's avatar
JINMEI Tatuya committed
569
} }
570
#endif // _ISC_DATA_H
571 572 573 574

// Local Variables: 
// mode: c++
// End: