mysql_lease_mgr.h 28.8 KB
Newer Older
1
// Copyright (C) 2012-2014 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
#ifndef MYSQL_LEASE_MGR_H
#define MYSQL_LEASE_MGR_H
17

18
#include <dhcp/hwaddr.h>
19
20
#include <dhcpsrv/lease_mgr.h>

21
#include <boost/scoped_ptr.hpp>
22
#include <boost/utility.hpp>
23
#include <mysql.h>
24
25

#include <time.h>
26
27
28
29

namespace isc {
namespace dhcp {

30
31
/// @brief MySQL Handle Holder
///
32
/// Small RAII object for safer initialization, will close the database
33
34
35
36
37
38
39
40
41
/// connection upon destruction.  This means that if an exception is thrown
/// during database initialization, resources allocated to the database are
/// guaranteed to be freed.
///
/// It makes no sense to copy an object of this class.  After the copy, both
/// objects would contain pointers to the same MySql context object.  The
/// destruction of one would invalid the context in the remaining object.
/// For this reason, the class is declared noncopyable.
class MySqlHolder : public boost::noncopyable {
42
public:
43
44
45
46
47
48

    /// @brief Constructor
    ///
    /// Initialize MySql and store the associated context object.
    ///
    /// @throw DbOpenError Unable to initialize MySql handle.
49
50
51
52
53
54
    MySqlHolder() : mysql_(mysql_init(NULL)) {
        if (mysql_ == NULL) {
            isc_throw(DbOpenError, "unable to initialize MySQL");
        }
    }

55
56
57
    /// @brief Destructor
    ///
    /// Frees up resources allocated by the initialization of MySql.
58
    ~MySqlHolder() {
59
        if (mysql_ != NULL) {
60
61
            mysql_close(mysql_);
        }
62
63
        // The library itself shouldn't be needed anymore
        mysql_library_end();
64
65
    }

66
67
68
69
    /// @brief Conversion Operator
    ///
    /// Allows the MySqlHolder object to be passed as the context argument to
    /// mysql_xxx functions.
70
71
72
73
74
    operator MYSQL*() const {
        return (mysql_);
    }

private:
75
    MYSQL* mysql_;      ///< Initialization context
76
77
};

78
79
// Define the current database schema values

80
const uint32_t CURRENT_VERSION_VERSION = 2;
81
const uint32_t CURRENT_VERSION_MINOR = 0;
82

83

84
// Forward declaration of the Lease exchange objects.  These classes are defined
85
// in the .cc file.
86
class MySqlLease4Exchange;
87
88
89
class MySqlLease6Exchange;


90
/// @brief MySQL Lease Manager
91
///
92
93
94
95
/// This class provides the \ref isc::dhcp::LeaseMgr interface to the MySQL
/// database.  Use of this backend presupposes that a MySQL database is
/// available and that the Kea schema has been created within it.

96
97
98
99
100
101
class MySqlLeaseMgr : public LeaseMgr {
public:
    /// @brief Constructor
    ///
    /// Uses the following keywords in the parameters passed to it to
    /// connect to the database:
102
103
104
105
    /// - name - Name of the database to which to connect (mandatory)
    /// - host - Host to which to connect (optional, defaults to "localhost")
    /// - user - Username under which to connect (optional)
    /// - password - Password for "user" on the database (optional)
106
107
108
109
110
111
112
113
114
    ///
    /// If the database is successfully opened, the version number in the
    /// schema_version table will be checked against hard-coded value in
    /// the implementation file.
    ///
    /// Finally, all the SQL commands are pre-compiled.
    ///
    /// @param parameters A data structure relating keywords and values
    ///        concerned with the database.
115
    ///
116
117
118
119
    /// @throw isc::dhcp::NoDatabaseName Mandatory database name not given
    /// @throw isc::dhcp::DbOpenError Error opening the database
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
120
121
122
123
124
    MySqlLeaseMgr(const ParameterMap& parameters);

    /// @brief Destructor (closes database)
    virtual ~MySqlLeaseMgr();

125
    /// @brief Adds an IPv4 lease
126
127
    ///
    /// @param lease lease to be added
128
129
130
131
    ///
    /// @result true if the lease was added, false if not (because a lease
    ///         with the same address was already there).
    ///
132
133
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
134
    virtual bool addLease(const Lease4Ptr& lease);
135

136
    /// @brief Adds an IPv6 lease
137
138
    ///
    /// @param lease lease to be added
139
140
141
142
    ///
    /// @result true if the lease was added, false if not (because a lease
    ///         with the same address was already there).
    ///
143
144
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
145
    virtual bool addLease(const Lease6Ptr& lease);
146
147
148
149

    /// @brief Returns an IPv4 lease for specified IPv4 address
    ///
    /// This method return a lease that is associated with a given address.
150
    /// For other query types (by hardware addr, by Client ID) there can be
151
152
153
154
155
156
157
158
    /// several leases in different subnets (e.g. for mobile clients that
    /// got address in different subnets). However, for a single address
    /// there can be only one lease, so this method returns a pointer to
    /// a single lease, not a container of leases.
    ///
    /// @param addr address of the searched lease
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
159
160
161
162
163
164
    ///
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
165
    virtual Lease4Ptr getLease4(const isc::asiolink::IOAddress& addr) const;
166

167

168
169
170
171
172
173
174
175
176
177
    /// @brief Returns existing IPv4 leases for specified hardware address.
    ///
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
    ///
    /// @param hwaddr hardware address of the client
    ///
    /// @return lease collection
178
179
180
181
182
183
    ///
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
184
    virtual Lease4Collection getLease4(const isc::dhcp::HWAddr& hwaddr) const;
185
186
187
188
189
190
191
192
193
194
195

    /// @brief Returns existing IPv4 leases for specified hardware address
    ///        and a subnet
    ///
    /// There can be at most one lease for a given HW address in a single
    /// pool, so this method with either return a single lease or NULL.
    ///
    /// @param hwaddr hardware address of the client
    /// @param subnet_id identifier of the subnet that lease must belong to
    ///
    /// @return a pointer to the lease (or NULL if a lease is not found)
196
197
198
199
200
201
    ///
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
202
    virtual Lease4Ptr getLease4(const isc::dhcp::HWAddr& hwaddr,
203
                                SubnetID subnet_id) const;
204
205
206
207
208
209
210
211
212
213
214

    /// @brief Returns existing IPv4 lease for specified client-id
    ///
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
    ///
    /// @param clientid client identifier
    ///
    /// @return lease collection
215
216
217
218
219
220
    ///
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
221
    virtual Lease4Collection getLease4(const ClientId& clientid) const;
222

223
224
225
226
227
228
229
230
231
232
233
234
235
    /// @brief Returns IPv4 lease for the specified client identifier, HW
    /// address and subnet identifier.
    ///
    /// @param client_id A client identifier.
    /// @param hwaddr Hardware address.
    /// @param subnet_id A subnet identifier.
    ///
    /// @return A pointer to the lease or NULL if the lease is not found.
    /// @throw isc::NotImplemented On every call as this function is currently
    /// not implemented for the MySQL backend.
    virtual Lease4Ptr getLease4(const ClientId& client_id, const HWAddr& hwaddr,
                                SubnetID subnet_id) const;

236
237
238
239
240
241
242
243
244
    /// @brief Returns existing IPv4 lease for specified client-id
    ///
    /// There can be at most one lease for a given HW address in a single
    /// pool, so this method with either return a single lease or NULL.
    ///
    /// @param clientid client identifier
    /// @param subnet_id identifier of the subnet that lease must belong to
    ///
    /// @return a pointer to the lease (or NULL if a lease is not found)
245
246
247
248
249
250
    ///
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
251
    virtual Lease4Ptr getLease4(const ClientId& clientid,
252
                                SubnetID subnet_id) const;
253
254
255
256

    /// @brief Returns existing IPv6 lease for a given IPv6 address.
    ///
    /// For a given address, we assume that there will be only one lease.
257
    /// The assumption here is that there will not be site or link-local
258
259
    /// addresses used, so there is no way of having address duplication.
    ///
260
    /// @param type specifies lease type: (NA, TA or PD)
261
262
263
    /// @param addr address of the searched lease
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
264
    ///
265
266
    /// @throw isc::BadValue record retrieved from database had an invalid
    ///        lease type field.
267
268
269
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
270
271
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
272
    virtual Lease6Ptr getLease6(Lease::Type type,
273
                                const isc::asiolink::IOAddress& addr) const;
274
275
276
277
278
279
280
281

    /// @brief Returns existing IPv6 leases for a given DUID+IA combination
    ///
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
    ///
282
    /// @param type specifies lease type: (NA, TA or PD)
283
284
285
286
    /// @param duid client DUID
    /// @param iaid IA identifier
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
287
288
289
290
291
292
293
294
    ///
    /// @throw isc::BadValue record retrieved from database had an invalid
    ///        lease type field.
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
295
    virtual Lease6Collection getLeases6(Lease::Type type, const DUID& duid,
296
                                        uint32_t iaid) const;
297
298
299

    /// @brief Returns existing IPv6 lease for a given DUID+IA combination
    ///
300
    /// @param type specifies lease type: (NA, TA or PD)
301
302
303
304
    /// @param duid client DUID
    /// @param iaid IA identifier
    /// @param subnet_id subnet id of the subnet the lease belongs to
    ///
305
    /// @return lease collection (may be empty if no lease is found)
306
307
308
309
310
311
312
313
    ///
    /// @throw isc::BadValue record retrieved from database had an invalid
    ///        lease type field.
    /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to
    ///        fit into the space allocated for the result.  This indicates a
    ///        programming error.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
314
    virtual Lease6Collection getLeases6(Lease::Type type, const DUID& duid,
315
                                        uint32_t iaid, SubnetID subnet_id) const;
316
317
318

    /// @brief Updates IPv4 lease.
    ///
319
320
321
    /// Updates the record of the lease in the database (as identified by the
    /// address) with the data in the passed lease object.
    ///
322
323
    /// @param lease4 The lease to be updated.
    ///
324
325
326
327
    /// @throw isc::dhcp::NoSuchLease Attempt to update a lease that did not
    ///        exist.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
328
    virtual void updateLease4(const Lease4Ptr& lease4);
329

330
    /// @brief Updates IPv6 lease.
331
    ///
332
333
334
    /// Updates the record of the lease in the database (as identified by the
    /// address) with the data in the passed lease object.
    ///
335
    /// @param lease6 The lease to be updated.
336
    ///
337
338
339
340
    /// @throw isc::dhcp::NoSuchLease Attempt to update a lease that did not
    ///        exist.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
341
    virtual void updateLease6(const Lease6Ptr& lease6);
342

343
    /// @brief Deletes a lease.
344
    ///
345
346
    /// @param addr Address of the lease to be deleted.  This can be an IPv4
    ///             address or an IPv6 address.
347
348
    ///
    /// @return true if deletion was successful, false if no such lease exists
349
    ///
350
351
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
352
    virtual bool deleteLease(const isc::asiolink::IOAddress& addr);
353

354
355
356
357
358
359
360
361
362
    /// @brief Return backend type
    ///
    /// Returns the type of the backend (e.g. "mysql", "memfile" etc.)
    ///
    /// @return Type of the backend.
    virtual std::string getType() const {
        return (std::string("mysql"));
    }

363
364
365
    /// @brief Returns backend name.
    ///
    /// Each backend have specific name, e.g. "mysql" or "sqlite".
366
367
    ///
    /// @return Name of the backend.
368
    virtual std::string getName() const;
369
370
371
372

    /// @brief Returns description of the backend.
    ///
    /// This description may be multiline text that describes the backend.
373
374
    ///
    /// @return Description of the backend.
375
    virtual std::string getDescription() const;
376
377
378
379
380
381

    /// @brief Returns backend version.
    ///
    /// @return Version number as a pair of unsigned integers.  "first" is the
    ///         major version number, "second" the minor number.
    ///
382
383
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
384
385
    virtual std::pair<uint32_t, uint32_t> getVersion() const;

386
387
388
389
390
    /// @brief Commit Transactions
    ///
    /// Commits all pending database operations.  On databases that don't
    /// support transactions, this is a no-op.
    ///
391
    /// @throw DbOperationError Iif the commit failed.
392
393
394
395
396
397
398
    virtual void commit();

    /// @brief Rollback Transactions
    ///
    /// Rolls back all pending database operations.  On databases that don't
    /// support transactions, this is a no-op.
    ///
399
    /// @throw DbOperationError If the rollback failed.
400
401
402
403
    virtual void rollback();

    ///@{
    /// The following methods are used to convert between times and time
404
405
406
407
408
    /// intervals stored in the Lease object, and the times stored in the
    /// database.  The reason for the difference is because in the DHCP server,
    /// the cltt (Client Time Since Last Transmission) is the natural data; in
    /// the lease file - which may be read by the user - it is the expiry time
    /// of the lease.
409
410
411

    /// @brief Convert Lease Time to Database Times
    ///
412
413
414
415
    /// Within the DHCP servers, times are stored as client last transmit time
    /// and valid lifetime.  In the database, the information is stored as
    /// valid lifetime and "expire" (time of expiry of the lease).  They are
    /// related by the equation:
416
    ///
417
    /// - expire = client last transmit time + valid lifetime
418
419
420
421
422
    ///
    /// This method converts from the times in the lease object into times
    /// able to be added to the database.
    ///
    /// @param cltt Client last transmit time
423
    /// @param valid_lifetime Valid lifetime
424
425
426
    /// @param expire Reference to MYSQL_TIME object where the expiry time of
    ///        the lease will be put.
    static
427
428
    void convertToDatabaseTime(time_t cltt, uint32_t valid_lifetime,
                               MYSQL_TIME& expire);
429
430
431

    /// @brief Convert Database Time to Lease Times
    ///
432
433
434
435
    /// Within the database, time is stored as "expire" (time of expiry of the
    /// lease) and valid lifetime.  In the DHCP server, the information is
    /// stored client last transmit time and valid lifetime.  These are related
    /// by the equation:
436
    ///
437
    /// - client last transmit time = expire - valid_lifetime
438
439
440
441
442
443
    ///
    /// This method converts from the times in the database into times
    /// able to be inserted into the lease object.
    ///
    /// @param expire Reference to MYSQL_TIME object from where the expiry
    ///        time of the lease is taken.
444
    /// @param valid_lifetime lifetime of the lease.
445
446
447
    /// @param cltt Reference to location where client last transmit time
    ///        is put.
    static
448
    void convertFromDatabaseTime(const MYSQL_TIME& expire,
449
                                 uint32_t valid_lifetime, time_t& cltt);
450
451
    ///@}

452
    /// @brief Statement Tags
453
    ///
454
    /// The contents of the enum are indexes into the list of SQL statements
455
    enum StatementIndex {
456
        DELETE_LEASE4,              // Delete from lease4 by address
457
        DELETE_LEASE6,              // Delete from lease6 by address
458
        GET_LEASE4_ADDR,            // Get lease4 by address
459
460
        GET_LEASE4_CLIENTID,        // Get lease4 by client ID
        GET_LEASE4_CLIENTID_SUBID,  // Get lease4 by client ID & subnet ID
461
462
        GET_LEASE4_HWADDR,          // Get lease4 by HW address
        GET_LEASE4_HWADDR_SUBID,    // Get lease4 by HW address & subnet ID
463
464
        GET_LEASE6_ADDR,            // Get lease6 by address
        GET_LEASE6_DUID_IAID,       // Get lease6 by DUID and IAID
465
        GET_LEASE6_DUID_IAID_SUBID, // Get lease6 by DUID, IAID and subnet ID
466
        GET_VERSION,                // Obtain version number
467
        INSERT_LEASE4,              // Add entry to lease4 table
468
        INSERT_LEASE6,              // Add entry to lease6 table
469
        UPDATE_LEASE4,              // Update a Lease4 entry
470
471
        UPDATE_LEASE6,              // Update a Lease6 entry
        NUM_STATEMENTS              // Number of statements
472
473
    };

474
private:
475
476
477
478
479
480
481
482
483
484
    /// @brief Prepare Single Statement
    ///
    /// Creates a prepared statement from the text given and adds it to the
    /// statements_ vector at the given index.
    ///
    /// @param index Index into the statements_ vector into which the text
    ///        should be placed.  The vector must be big enough for the index
    ///        to be valid, else an exception will be thrown.
    /// @param text Text of the SQL statement to be prepared.
    ///
485
486
487
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
    /// @throw isc::InvalidParameter 'index' is not valid for the vector.
488
489
490
491
492
493
    void prepareStatement(StatementIndex index, const char* text);

    /// @brief Prepare statements
    ///
    /// Creates the prepared statements for all of the SQL statements used
    /// by the MySQL backend.
494
    ///
495
496
497
498
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
    /// @throw isc::InvalidParameter 'index' is not valid for the vector.  This
    ///        represents an internal error within the code.
499
500
    void prepareStatements();

501
502
503
504
505
    /// @brief Open Database
    ///
    /// Opens the database using the information supplied in the parameters
    /// passed to the constructor.
    ///
506
507
    /// @throw NoDatabaseName Mandatory database name not given
    /// @throw DbOpenError Error opening the database
508
509
    void openDatabase();

510
511
    /// @brief Add Lease Common Code
    ///
512
513
514
    /// This method performs the common actions for both flavours (V4 and V6)
    /// of the addLease method.  It binds the contents of the lease object to
    /// the prepared statement and adds it to the database.
515
516
517
518
519
520
521
522
523
524
    ///
    /// @param stindex Index of statemnent being executed
    /// @param bind MYSQL_BIND array that has been created for the type
    ///        of lease in question.
    ///
    /// @return true if the lease was added, false if it was not added because
    ///         a lease with that address already exists in the database.
    ///
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
525
    bool addLeaseCommon(StatementIndex stindex, std::vector<MYSQL_BIND>& bind);
526

527
528
529
530
531
532
    /// @brief Get Lease Collection Common Code
    ///
    /// This method performs the common actions for obtaining multiple leases
    /// from the database.
    ///
    /// @param stindex Index of statement being executed
533
    /// @param bind MYSQL_BIND array for input parameters
534
    /// @param exchange Exchange object to use
535
536
537
    /// @param lease LeaseCollection object returned.  Note that any leases in
    ///        the collection when this method is called are not erased: the
    ///        new data is appended to the end.
538
539
540
541
542
543
544
545
546
    /// @param single If true, only a single data item is to be retrieved.
    ///        If more than one is present, a MultipleRecords exception will
    ///        be thrown.
    ///
    /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
    /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved
    ///        from the database where only one was expected.
547
    template <typename Exchange, typename LeaseCollection>
548
    void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,
549
550
                            Exchange& exchange, LeaseCollection& result,
                            bool single = false) const;
551

552
    /// @brief Get Lease Collection
553
    ///
554
555
    /// Gets a collection of Lease4 objects.  This is just an interface to
    /// the get lease collection common code.
556
    ///
557
    /// @param stindex Index of statement being executed
558
    /// @param bind MYSQL_BIND array for input parameters
559
560
561
    /// @param lease LeaseCollection object returned.  Note that any leases in
    ///        the collection when this method is called are not erased: the
    ///        new data is appended to the end.
562
563
564
565
566
567
    ///
    /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
    /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved
    ///        from the database where only one was expected.
568
    void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,
569
                            Lease4Collection& result) const {
570
        getLeaseCollection(stindex, bind, exchange4_, result);
571
572
573
574
575
576
577
578
    }

    /// @brief Get Lease Collection
    ///
    /// Gets a collection of Lease6 objects.  This is just an interface to
    /// the get lease collection common code.
    ///
    /// @param stindex Index of statement being executed
579
    /// @param bind MYSQL_BIND array for input parameters
580
581
    /// @param lease LeaseCollection object returned.  Note that any existing
    ///        data in the collection is erased first.
582
583
584
585
586
587
    ///
    /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid.
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
    /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved
    ///        from the database where only one was expected.
588
    void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,
589
                            Lease6Collection& result) const {
590
        getLeaseCollection(stindex, bind, exchange6_, result);
591
592
    }

593
    /// @brief Get Lease4 Common Code
594
595
596
597
598
599
    ///
    /// This method performs the common actions for the various getLease4()
    /// methods.  It acts as an interface to the getLeaseCollection() method,
    /// but retrieveing only a single lease.
    ///
    /// @param stindex Index of statement being executed
600
    /// @param bind MYSQL_BIND array for input parameters
601
    /// @param lease Lease4 object returned
602
    void getLease(StatementIndex stindex, MYSQL_BIND* bind,
603
604
                  Lease4Ptr& result) const;

605
    /// @brief Get Lease6 Common Code
606
    ///
607
    /// This method performs the common actions for the various getLease46)
608
609
610
611
    /// methods.  It acts as an interface to the getLeaseCollection() method,
    /// but retrieveing only a single lease.
    ///
    /// @param stindex Index of statement being executed
612
    /// @param bind MYSQL_BIND array for input parameters
613
    /// @param lease Lease6 object returned
614
    void getLease(StatementIndex stindex, MYSQL_BIND* bind,
615
616
617
618
619
620
621
                   Lease6Ptr& result) const;

    /// @brief Update lease common code
    ///
    /// Holds the common code for updating a lease.  It binds the parameters
    /// to the prepared statement, executes it, then checks how many rows
    /// were affected.
622
623
    ///
    /// @param stindex Index of prepared statement to be executed
624
    /// @param bind Array of MYSQL_BIND objects representing the parameters.
625
626
    ///        (Note that the number is determined by the number of parameters
    ///        in the statement.)
627
    /// @param lease Pointer to the lease object whose record is being updated.
628
    ///
629
630
    /// @throw NoSuchLease Could not update a lease because no lease matches
    ///        the address given.
631
632
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
633
    template <typename LeasePtr>
634
635
    void updateLeaseCommon(StatementIndex stindex, MYSQL_BIND* bind,
                           const LeasePtr& lease);
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652

    /// @brief Delete lease common code
    ///
    /// Holds the common code for deleting a lease.  It binds the parameters
    /// to the prepared statement, executes the statement and checks to
    /// see how many rows were deleted.
    ///
    /// @param stindex Index of prepared statement to be executed
    /// @param bind Array of MYSQL_BIND objects representing the parameters.
    ///        (Note that the number is determined by the number of parameters
    ///        in the statement.)
    ///
    /// @return true if one or more rows were deleted, false if none were
    ///         deleted.
    ///
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
653
    bool deleteLeaseCommon(StatementIndex stindex, MYSQL_BIND* bind);
654

655
656
657
658
659
660
661
662
663
664
    /// @brief Check Error and Throw Exception
    ///
    /// Virtually all MySQL functions return a status which, if non-zero,
    /// indicates an error.  This inline function conceals a lot of error
    /// checking/exception-throwing code.
    ///
    /// @param status Status code: non-zero implies an error
    /// @param index Index of statement that caused the error
    /// @param what High-level description of the error
    ///
665
666
    /// @throw isc::dhcp::DbOperationError An operation on the open database has
    ///        failed.
667
    inline void checkError(int status, StatementIndex index,
668
669
670
                           const char* what) const {
        if (status != 0) {
            isc_throw(DbOperationError, what << " for <" <<
671
                      text_statements_[index] << ">, reason: " <<
672
673
                      mysql_error(mysql_) << " (error code " <<
                      mysql_errno(mysql_) << ")");
674
675
676
        }
    }

677
    // Members
678

679
680
681
682
    /// The exchange objects are used for transfer of data to/from the database.
    /// They are pointed-to objects as the contents may change in "const" calls,
    /// while the rest of this object does not.  (At alternative would be to
    /// declare them as "mutable".)
683
684
    boost::scoped_ptr<MySqlLease4Exchange> exchange4_; ///< Exchange object
    boost::scoped_ptr<MySqlLease6Exchange> exchange6_; ///< Exchange object
685
    MySqlHolder mysql_;
686
687
    std::vector<MYSQL_STMT*> statements_;       ///< Prepared statements
    std::vector<std::string> text_statements_;  ///< Raw text of statements
688
689
690
691
692
};

}; // end of isc::dhcp namespace
}; // end of isc namespace

693
#endif // MYSQL_LEASE_MGR_H