database.h 7.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// Copyright (C) 2011  Internet Systems Consortium, Inc. ("ISC")
//
// 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.

#ifndef __DATABASE_DATASRC_H
#define __DATABASE_DATASRC_H

#include <datasrc/client.h>

namespace isc {
namespace datasrc {

23
/**
24
 * \brief Abstraction of lowlevel database with DNS data
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
 *
 * This class is defines interface to databases. Each supported database
 * will provide methods for accessing the data stored there in a generic
 * manner. The methods are meant to be low-level, without much or any knowledge
 * about DNS and should be possible to translate directly to queries.
 *
 * On the other hand, how the communication with database is done and in what
 * schema (in case of relational/SQL database) is up to the concrete classes.
 *
 * This class is non-copyable, as copying connections to database makes little
 * sense and will not be needed.
 *
 * \todo Is it true this does not need to be copied? For example the zone
 *     iterator might need it's own copy. But a virtual clone() method might
 *     be better for that than copy constructor.
 *
 * \note The same application may create multiple connections to the same
42 43 44
 *     database, having multiple instances of this class. If the database
 *     allows having multiple open queries at one connection, the connection
 *     class may share it.
45
 */
46
class DatabaseAbstraction : boost::noncopyable {
47
public:
48 49 50 51 52 53
    /**
     * \brief Destructor
     *
     * It is empty, but needs a virtual one, since we will use the derived
     * classes in polymorphic way.
     */
54
    virtual ~DatabaseAbstraction() { }
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
    /**
     * \brief Retrieve a zone identifier
     *
     * This method looks up a zone for the given name in the database. It
     * should match only exact zone name (eg. name is equal to the zone's
     * apex), as the DatabaseClient will loop trough the labels itself and
     * find the most suitable zone.
     *
     * It is not specified if and what implementation of this method may throw,
     * so code should expect anything.
     *
     * \param name The name of the zone's apex to be looked up.
     * \return The first part of the result indicates if a matching zone
     *     was found. In case it was, the second part is internal zone ID.
     *     This one will be passed to methods finding data in the zone.
     *     It is not required to keep them, in which case whatever might
71
     *     be returned - the ID is only passed back to the database as
72 73
     *     an opaque handle.
     */
74
    virtual std::pair<bool, int> getZone(const isc::dns::Name& name) const = 0;
75 76
};

77 78 79 80 81
/**
 * \brief Concrete data source client oriented at database backends.
 *
 * This class (together with corresponding versions of ZoneFinder,
 * ZoneIterator, etc.) translates high-level data source queries to
82
 * low-level calls on DatabaseAbstraction. It calls multiple queries
83
 * if necessary and validates data from the database, allowing the
84
 * DatabaseAbstraction to be just simple translation to SQL/other
85 86 87 88
 * queries to database.
 *
 * While it is possible to subclass it for specific database in case
 * of special needs, it is not expected to be needed. This should just
89
 * work as it is with whatever DatabaseAbstraction.
90
 */
91 92
class DatabaseClient : public DataSourceClient {
public:
93 94 95
    /**
     * \brief Constructor
     *
96
     * It initializes the client with a database.
97
     *
98
     * \exception isc::InvalidParameter if database is NULL. It might throw
99 100
     * standard allocation exception as well, but doesn't throw anything else.
     *
101 102
     * \param database The database to use to get data. As the parameter
     *     suggests, the client takes ownership of the database and will
103 104
     *     delete it when itself deleted.
     */
105
    DatabaseClient(boost::shared_ptr<DatabaseAbstraction> database);
106 107 108 109 110
    /**
     * \brief Corresponding ZoneFinder implementation
     *
     * The zone finder implementation for database data sources. Similarly
     * to the DatabaseClient, it translates the queries to methods of the
111
     * database.
112 113 114 115 116 117 118 119 120 121 122 123 124 125
     *
     * Application should not come directly in contact with this class
     * (it should handle it trough generic ZoneFinder pointer), therefore
     * it could be completely hidden in the .cc file. But it is provided
     * to allow testing and for rare cases when a database needs slightly
     * different handling, so it can be subclassed.
     *
     * Methods directly corresponds to the ones in ZoneFinder.
     */
    class Finder : public ZoneFinder {
    public:
        /**
         * \brief Constructor
         *
126
         * \param database The database (shared with DatabaseClient) to
127 128
         *     be used for queries (the one asked for ID before).
         * \param zone_id The zone ID which was returned from
129 130
         *     DatabaseAbstraction::getZone and which will be passed to further
         *     calls to the database.
131
         */
132
        Finder(boost::shared_ptr<DatabaseAbstraction> database, int zone_id);
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
133 134
        // The following three methods are just implementations of inherited
        // ZoneFinder's pure virtual methods.
135 136
        virtual isc::dns::Name getOrigin() const;
        virtual isc::dns::RRClass getClass() const;
137 138 139 140
        virtual FindResult find(const isc::dns::Name& name,
                                const isc::dns::RRType& type,
                                isc::dns::RRsetList* target = NULL,
                                const FindOptions options = FIND_DEFAULT)
141
            const;
142 143 144 145 146 147 148 149 150
        /**
         * \brief The zone ID
         *
         * This function provides the stored zone ID as passed to the
         * constructor. This is meant for testing purposes and normal
         * applications shouldn't need it.
         */
        int zone_id() const { return (zone_id_); }
        /**
151
         * \brief The database.
152
         *
153
         * This function provides the database stored inside as
154 155 156
         * passed to the constructor. This is meant for testing purposes and
         * normal applications shouldn't need it.
         */
157 158
        const DatabaseAbstraction& database() const {
            return (*database_);
159
        }
160
    private:
161
        boost::shared_ptr<DatabaseAbstraction> database_;
162 163 164 165 166
        const int zone_id_;
    };
    /**
     * \brief Find a zone in the database
     *
167
     * This queries database's getZone to find the best matching zone.
168 169 170 171
     * It will propagate whatever exceptions are thrown from that method
     * (which is not restricted in any way).
     *
     * \param name Name of the zone or data contained there.
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
172 173 174 175 176
     * \return FindResult containing the code and an instance of Finder, if
     *     anything is found. However, application should not rely on the
     *     ZoneFinder being instance of Finder (possible subclass of this class
     *     may return something else and it may change in future versions), it
     *     should use it as a ZoneFinder only.
177
     */
178 179
    virtual FindResult findZone(const isc::dns::Name& name) const;
private:
180 181
    /// \brief Our database.
    const boost::shared_ptr<DatabaseAbstraction> database_;
182 183 184 185 186 187
};

}
}

#endif