memory_datasrc.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343
  1. // Copyright (C) 2010 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. #ifndef __MEMORY_DATA_SOURCE_H
  15. #define __MEMORY_DATA_SOURCE_H 1
  16. #include <string>
  17. #include <boost/noncopyable.hpp>
  18. #include <datasrc/zonetable.h>
  19. #include <datasrc/client.h>
  20. #include <cc/data.h>
  21. namespace isc {
  22. namespace dns {
  23. class Name;
  24. class RRsetList;
  25. };
  26. namespace datasrc {
  27. /// A derived zone finder class intended to be used with the memory data source.
  28. ///
  29. /// Conceptually this "finder" maintains a local in-memory copy of all RRs
  30. /// of a single zone from some kind of source (right now it's a textual
  31. /// master file, but it could also be another data source with a database
  32. /// backend). This is why the class has methods like \c load() or \c add().
  33. ///
  34. /// This class is non copyable.
  35. class InMemoryZoneFinder : boost::noncopyable, public ZoneFinder {
  36. ///
  37. /// \name Constructors and Destructor.
  38. public:
  39. /// \brief Constructor from zone parameters.
  40. ///
  41. /// This constructor internally involves resource allocation, and if
  42. /// it fails, a corresponding standard exception will be thrown.
  43. /// It never throws an exception otherwise.
  44. ///
  45. /// \param rrclass The RR class of the zone.
  46. /// \param origin The origin name of the zone.
  47. InMemoryZoneFinder(const isc::dns::RRClass& rrclass,
  48. const isc::dns::Name& origin);
  49. /// The destructor.
  50. virtual ~InMemoryZoneFinder();
  51. //@}
  52. /// \brief Returns the origin of the zone.
  53. virtual isc::dns::Name getOrigin() const;
  54. /// \brief Returns the class of the zone.
  55. virtual isc::dns::RRClass getClass() const;
  56. /// \brief Looks up an RRset in the zone.
  57. ///
  58. /// See documentation in \c Zone.
  59. ///
  60. /// It returns NULL pointer in case of NXDOMAIN and NXRRSET.
  61. virtual FindResult find(const isc::dns::Name& name,
  62. const isc::dns::RRType& type,
  63. const FindOptions options = FIND_DEFAULT);
  64. /// \brief Version of find that returns all types at once
  65. ///
  66. /// It acts the same as find, just that when the correct node is found,
  67. /// all the RRsets are filled into the target parameter instead of being
  68. /// returned by the result.
  69. virtual FindResult findAll(const isc::dns::Name& name,
  70. std::vector<isc::dns::ConstRRsetPtr>& target,
  71. const FindOptions options = FIND_DEFAULT);
  72. /// \brief Imelementation of the ZoneFinder::findPreviousName method
  73. ///
  74. /// This one throws NotImplemented exception, as InMemory doesn't
  75. /// support DNSSEC currently.
  76. virtual isc::dns::Name findPreviousName(const isc::dns::Name& query) const;
  77. /// \brief Inserts an rrset into the zone.
  78. ///
  79. /// It puts another RRset into the zone.
  80. ///
  81. /// Except for NullRRset and OutOfZone, this method does not guarantee
  82. /// strong exception safety (it is currently not needed, if it is needed
  83. /// in future, it should be implemented).
  84. ///
  85. /// \throw NullRRset \c rrset is a NULL pointer.
  86. /// \throw OutOfZone The owner name of \c rrset is outside of the
  87. /// origin of the zone.
  88. /// \throw AddError Other general errors.
  89. /// \throw Others This method might throw standard allocation exceptions.
  90. ///
  91. /// \param rrset The set to add.
  92. /// \return SUCCESS or EXIST (if an rrset for given name and type already
  93. /// exists).
  94. result::Result add(const isc::dns::ConstRRsetPtr& rrset);
  95. /// \brief RRSet out of zone exception.
  96. ///
  97. /// This is thrown if addition of an RRset that doesn't belong under the
  98. /// zone's origin is requested.
  99. struct OutOfZone : public InvalidParameter {
  100. OutOfZone(const char* file, size_t line, const char* what) :
  101. InvalidParameter(file, line, what)
  102. { }
  103. };
  104. /// \brief RRset is NULL exception.
  105. ///
  106. /// This is thrown if the provided RRset parameter is NULL.
  107. struct NullRRset : public InvalidParameter {
  108. NullRRset(const char* file, size_t line, const char* what) :
  109. InvalidParameter(file, line, what)
  110. { }
  111. };
  112. /// \brief General failure exception for \c add().
  113. ///
  114. /// This is thrown against general error cases in adding an RRset
  115. /// to the zone.
  116. ///
  117. /// Note: this exception would cover cases for \c OutOfZone or
  118. /// \c NullRRset. We'll need to clarify and unify the granularity
  119. /// of exceptions eventually. For now, exceptions are added as
  120. /// developers see the need for it.
  121. struct AddError : public InvalidParameter {
  122. AddError(const char* file, size_t line, const char* what) :
  123. InvalidParameter(file, line, what)
  124. { }
  125. };
  126. /// Return the master file name of the zone
  127. ///
  128. /// This method returns the name of the zone's master file to be loaded.
  129. /// The returned string will be an empty unless the zone finder has
  130. /// successfully loaded a zone.
  131. ///
  132. /// This method should normally not throw an exception. But the creation
  133. /// of the return string may involve a resource allocation, and if it
  134. /// fails, the corresponding standard exception will be thrown.
  135. ///
  136. /// \return The name of the zone file loaded in the zone finder, or an empty
  137. /// string if the zone hasn't loaded any file.
  138. const std::string getFileName() const;
  139. /// \brief Load zone from masterfile.
  140. ///
  141. /// This loads data from masterfile specified by filename. It replaces
  142. /// current content. The masterfile parsing ability is kind of limited,
  143. /// see isc::dns::masterLoad.
  144. ///
  145. /// This throws isc::dns::MasterLoadError if there is problem with loading
  146. /// (missing file, malformed, it contains different zone, etc - see
  147. /// isc::dns::masterLoad for details).
  148. ///
  149. /// In case of internal problems, OutOfZone, NullRRset or AssertError could
  150. /// be thrown, but they should not be expected. Exceptions caused by
  151. /// allocation may be thrown as well.
  152. ///
  153. /// If anything is thrown, the previous content is preserved (so it can
  154. /// be used to update the data, but if user makes a typo, the old one
  155. /// is kept).
  156. ///
  157. /// \param filename The master file to load.
  158. ///
  159. /// \todo We may need to split it to some kind of build and commit/abort.
  160. /// This will probably be needed when a better implementation of
  161. /// configuration reloading is written.
  162. void load(const std::string& filename);
  163. /// Exchanges the content of \c this zone finder with that of the given
  164. /// \c zone_finder.
  165. ///
  166. /// This method never throws an exception.
  167. ///
  168. /// \param zone_finder Another \c InMemoryZone object which is to
  169. /// be swapped with \c this zone finder.
  170. void swap(InMemoryZoneFinder& zone_finder);
  171. private:
  172. /// \name Hidden private data
  173. //@{
  174. struct InMemoryZoneFinderImpl;
  175. InMemoryZoneFinderImpl* impl_;
  176. //@}
  177. // The friend here is for InMemoryClient::getIterator. The iterator
  178. // needs to access the data inside the zone, so the InMemoryClient
  179. // extracts the pointer to data and puts it into the iterator.
  180. // The access is read only.
  181. friend class InMemoryClient;
  182. };
  183. /// \brief A data source client that holds all necessary data in memory.
  184. ///
  185. /// The \c InMemoryClient class provides an access to a conceptual data
  186. /// source that maintains all necessary data in a memory image, thereby
  187. /// allowing much faster lookups. The in memory data is a copy of some
  188. /// real physical source - in the current implementation a list of zones
  189. /// are populated as a result of \c addZone() calls; zone data is given
  190. /// in a standard master file (but there's a plan to use database backends
  191. /// as a source of the in memory data).
  192. ///
  193. /// Although every data source client is assumed to be of the same RR class,
  194. /// the \c InMemoryClient class does not enforce the assumption through
  195. /// its interface.
  196. /// For example, the \c addZone() method does not check if the new zone is of
  197. /// the same RR class as that of the others already in memory.
  198. /// It is caller's responsibility to ensure this assumption.
  199. ///
  200. /// <b>Notes to developer:</b>
  201. ///
  202. /// The addZone() method takes a (Boost) shared pointer because it would be
  203. /// inconvenient to require the caller to maintain the ownership of zones,
  204. /// while it wouldn't be safe to delete unnecessary zones inside the dedicated
  205. /// backend.
  206. ///
  207. /// The findZone() method takes a domain name and returns the best matching
  208. /// \c InMemoryZoneFinder in the form of (Boost) shared pointer, so that it can
  209. /// provide the general interface for all data sources.
  210. class InMemoryClient : public DataSourceClient {
  211. public:
  212. ///
  213. /// \name Constructors and Destructor.
  214. ///
  215. //@{
  216. /// Default constructor.
  217. ///
  218. /// This constructor internally involves resource allocation, and if
  219. /// it fails, a corresponding standard exception will be thrown.
  220. /// It never throws an exception otherwise.
  221. InMemoryClient();
  222. /// The destructor.
  223. ~InMemoryClient();
  224. //@}
  225. /// Return the number of zones stored in the client.
  226. ///
  227. /// This method never throws an exception.
  228. ///
  229. /// \return The number of zones stored in the client.
  230. unsigned int getZoneCount() const;
  231. /// Add a zone (in the form of \c ZoneFinder) to the \c InMemoryClient.
  232. ///
  233. /// \c zone_finder must not be associated with a NULL pointer; otherwise
  234. /// an exception of class \c InvalidParameter will be thrown.
  235. /// If internal resource allocation fails, a corresponding standard
  236. /// exception will be thrown.
  237. /// This method never throws an exception otherwise.
  238. ///
  239. /// \param zone_finder A \c ZoneFinder object to be added.
  240. /// \return \c result::SUCCESS If the zone_finder is successfully
  241. /// added to the client.
  242. /// \return \c result::EXIST The memory data source already
  243. /// stores a zone that has the same origin.
  244. result::Result addZone(ZoneFinderPtr zone_finder);
  245. /// Returns a \c ZoneFinder for a zone_finder that best matches the given
  246. /// name.
  247. ///
  248. /// This derived version of the method never throws an exception.
  249. /// For other details see \c DataSourceClient::findZone().
  250. virtual FindResult findZone(const isc::dns::Name& name) const;
  251. /// \brief Implementation of the getIterator method
  252. virtual ZoneIteratorPtr getIterator(const isc::dns::Name& name,
  253. bool separate_rrs = false) const;
  254. /// In-memory data source is read-only, so this derived method will
  255. /// result in a NotImplemented exception.
  256. ///
  257. /// \note We plan to use a database-based data source as a backend
  258. /// persistent storage for an in-memory data source. When it's
  259. /// implemented we may also want to allow the user of the in-memory client
  260. /// to update via its updater (this may or may not be a good idea and
  261. /// is subject to further discussions).
  262. virtual ZoneUpdaterPtr getUpdater(const isc::dns::Name& name,
  263. bool replace, bool journaling = false)
  264. const;
  265. virtual std::pair<ZoneJournalReader::Result, ZoneJournalReaderPtr>
  266. getJournalReader(const isc::dns::Name& zone, uint32_t begin_serial,
  267. uint32_t end_serial) const;
  268. private:
  269. // TODO: Do we still need the PImpl if nobody should manipulate this class
  270. // directly any more (it should be handled through DataSourceClient)?
  271. class InMemoryClientImpl;
  272. InMemoryClientImpl* impl_;
  273. };
  274. /// \brief Creates an instance of the Memory datasource client
  275. ///
  276. /// Currently the configuration passed here must be a MapElement, formed as
  277. /// follows:
  278. /// \code
  279. /// { "type": string ("memory"),
  280. /// "class": string ("IN"/"CH"/etc),
  281. /// "zones": list
  282. /// }
  283. /// Zones list is a list of maps:
  284. /// { "origin": string,
  285. /// "file": string
  286. /// }
  287. /// \endcode
  288. /// (i.e. the configuration that was used prior to the datasource refactor)
  289. ///
  290. /// This configuration setup is currently under discussion and will change in
  291. /// the near future.
  292. ///
  293. /// \param config The configuration for the datasource instance
  294. /// \param error This string will be set to an error message if an error occurs
  295. /// during initialization
  296. /// \return An instance of the memory datasource client, or NULL if there was
  297. /// an error
  298. extern "C" DataSourceClient* createInstance(isc::data::ConstElementPtr config,
  299. std::string& error);
  300. /// \brief Destroy the instance created by createInstance()
  301. extern "C" void destroyInstance(DataSourceClient* instance);
  302. }
  303. }
  304. #endif // __DATA_SOURCE_MEMORY_H
  305. // Local Variables:
  306. // mode: c++
  307. // End: