Branch data Line data Source code
1 : : // Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
2 : : //
3 : : // Permission to use, copy, modify, and/or distribute this software for any
4 : : // purpose with or without fee is hereby granted, provided that the above
5 : : // copyright notice and this permission notice appear in all copies.
6 : : //
7 : : // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8 : : // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 : : // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
10 : : // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 : : // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 : : // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 : : // PERFORMANCE OF THIS SOFTWARE.
14 : :
15 : : #ifndef __DATASRC_ZONE_ITERATOR_H
16 : : #define __DATASRC_ZONE_ITERATOR_H 1
17 : :
18 : : #include <dns/rrset.h>
19 : :
20 : : #include <boost/noncopyable.hpp>
21 : :
22 : : #include <datasrc/zone.h>
23 : :
24 : : namespace isc {
25 : : namespace datasrc {
26 : :
27 : : /**
28 : : * \brief Read-only iterator to a zone.
29 : : *
30 : : * You can get an instance of (descendand of) ZoneIterator from
31 : : * DataSourceClient::getIterator() method. The actual concrete implementation
32 : : * will be different depending on the actual data source used. This is the
33 : : * abstract interface.
34 : : *
35 : : * There's no way to start iterating from the beginning again or return.
36 : : */
37 : 43 : class ZoneIterator : public boost::noncopyable {
38 : : public:
39 : : /**
40 : : * \brief Destructor
41 : : *
42 : : * Virtual destructor. It is empty, but ensures the right destructor from
43 : : * descendant is called.
44 : : */
45 : 43 : virtual ~ ZoneIterator() { }
46 : :
47 : : /**
48 : : * \brief Get next RRset from the zone.
49 : : *
50 : : * This returns the next RRset in the zone as a shared pointer. The
51 : : * shared pointer is used to allow both accessing in-memory data and
52 : : * automatic memory management.
53 : : *
54 : : * Any special order is not guaranteed.
55 : : *
56 : : * While this can potentially throw anything (including standard allocation
57 : : * errors), it should be rare.
58 : : *
59 : : * \return Pointer to the next RRset or NULL pointer when the iteration
60 : : * gets to the end of the zone.
61 : : */
62 : : virtual isc::dns::ConstRRsetPtr getNextRRset() = 0;
63 : :
64 : : /**
65 : : * \brief Return the SOA record of the zone in the iterator context.
66 : : *
67 : : * This method returns the zone's SOA record (if any, and a valid zone
68 : : * should have it) in the form of an RRset object. This SOA is identical
69 : : * to that (again, if any) contained in the sequence of RRsets returned
70 : : * by the iterator. In that sense this method is redundant, but is
71 : : * provided as a convenient utility for the application of the
72 : : * iterator; the application may need to know the SOA serial or the
73 : : * SOA RR itself for the purpose of protocol handling or skipping the
74 : : * expensive iteration processing.
75 : : *
76 : : * If the zone doesn't have an SOA (which is broken, but some data source
77 : : * may allow that situation), this method returns NULL. Also, in the
78 : : * normal and valid case, the SOA should have exactly one RDATA, but
79 : : * this API does not guarantee it as some data source may accept such an
80 : : * abnormal condition. It's up to the caller whether to check the number
81 : : * of RDATA and how to react to the unexpected case.
82 : : *
83 : : * Each concrete derived method must ensure that the SOA returned by this
84 : : * method is identical to the zone's SOA returned via the iteration.
85 : : * For example, even if another thread or process updates the SOA while
86 : : * the iterator is working, the result of this method must not be
87 : : * affected by the update. For database based data sources, this can
88 : : * be done by making the entire iterator operation as a single database
89 : : * transaction, but the actual implementation can differ.
90 : : *
91 : : * \exception None
92 : : *
93 : : * \return A shared pointer to an SOA RRset that would be returned
94 : : * from the iteration. It will be NULL if the zone doesn't have an SOA.
95 : : */
96 : : virtual isc::dns::ConstRRsetPtr getSOA() const = 0;
97 : : };
98 : :
99 : : }
100 : : }
101 : : #endif // __DATASRC_ZONE_ITERATOR_H
102 : :
103 : : // Local Variables:
104 : : // mode: c++
105 : : // End:
|
