BIND 10 trac978, updated. 70af8c7c72300e1afe1974de22c117ff5566487d [trac978] Cleanup of comments and exceptions
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Jun 17 20:58:28 UTC 2011
The branch, trac978 has been updated
via 70af8c7c72300e1afe1974de22c117ff5566487d (commit)
via 03e690228b6f5184d67a4ff3de56a861fcac9a23 (commit)
from d749aee2ec681e0304dd53c63f276af98edeaf31 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 70af8c7c72300e1afe1974de22c117ff5566487d
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Fri Jun 17 22:54:28 2011 +0200
[trac978] Cleanup of comments and exceptions
commit 03e690228b6f5184d67a4ff3de56a861fcac9a23
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Fri Jun 17 22:40:29 2011 +0200
[trac978] Some documentation of the syntax
-----------------------------------------------------------------------
Summary of changes:
src/lib/acl/loader.h | 106 +++++++++++++++++++++++++++-----------
src/lib/exceptions/exceptions.h | 11 ++++
2 files changed, 86 insertions(+), 31 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/acl/loader.h b/src/lib/acl/loader.h
index b4266f4..95de9e5 100644
--- a/src/lib/acl/loader.h
+++ b/src/lib/acl/loader.h
@@ -91,6 +91,50 @@ BasicAction defaultActionLoader(data::ConstElementPtr action);
*
* To allow any kind of checks to exist in the application, creators are
* registered for the names of the checks.
+ *
+ * An ACL definition looks like this:
+ * \verbatim
+ * [
+ * {
+ * "action": "ACCEPT",
+ * "match-type": <parameter>
+ * },
+ * {
+ * "action": "REJECT",
+ * "match-type": <parameter>
+ * "another-match-type": [<parameter1>, <parameter2>]
+* },
+* {
+* "action": "DROP"
+* }
+ * ]
+ * \endverbatim
+ *
+ * This is a list of elements. Each element must have an "action"
+ * entry/keyword. That one specifies which action is returned if this
+ * element matches (the value of the key is passed to the action loader
+ * (see the constructor). It may be any piece of JSON which the action
+ * loader expects.
+ *
+ * The rest of the element are matches. The left side is the name of the
+ * match type (for example match for source IP address or match for message
+ * size). The <parameter> is whatever is needed to describe the match and
+ * depends on the match type, the loader passes it verbatim to creator
+ * of that match type.
+ *
+ * There may be multiple match types in single element. In such case, all
+ * of the matches must match for the element to take action (so, in the second
+ * element, both "match-type" and "another-match-type" must be satisfied).
+ * If there's no match in the element, the action is taken/returned without
+ * conditions, every time (makes sense as the last entry, as the ACL will
+ * never get past it).
+ *
+ * The second entry shows another thing - if there's a list as the value
+ * for some match and the match itself is not expecting a list, it is taken
+ * as an "or" - a match for at last one of the choices in the list must match.
+ * So, for the second entry, both "match-type" and "another-match-type" must
+ * be satisfied, but the another one is satisfied by either parameter1 or
+ * parameter2.
*/
template<typename Context, typename Action = BasicAction> class Loader {
public:
@@ -113,7 +157,10 @@ public:
* \brief Creator of the checks.
*
* This can be registered within the Loader and will be used to create the
- * checks.
+ * checks. It is expected multiple creators (for multiple types, one can
+ * handle even multiple names) will be created and registered to support
+ * range of things we could check. This allows for customizing/extending
+ * the loader.
*/
class CheckCreator {
public:
@@ -149,10 +196,14 @@ public:
/**
* \brief Is list or-abbreviation allowed?
*
- * If this returns true and the parameter is list, the loader will
- * call the create method with each element of the list and aggregate
- * all the results in OR compound check. If it is false, the parameter
- * is passed verbatim no matter if it is or isn't a list.
+ * If this returns true and the parameter (eg. the value we check
+ * against, the one that is passed as the second parameter of create)
+ * is list, the loader will call the create method with each element of
+ * the list and aggregate all the results in OR compound check. If it
+ * is false, the parameter is passed verbatim no matter if it is or
+ * isn't a list. For example, IP check will have this as true (so
+ * multiple IP addresses can be passed as options), but AND operator
+ * will return false and handle the list of subexpressions itself.
*
* The rationale behind this is that it is common to specify list of
* something that matches (eg. list of IP addresses).
@@ -197,10 +248,10 @@ public:
/**
* \brief Load a check.
*
- * This parses a check dict (block) and calls a creator (or creators, if
- * more than one check is found inside) for it. It ignores the "action"
- * key, as it is a reserved keyword used to specify actions inside the
- * ACL.
+ * This parses a check dict (block, the one element of ACL) and calls a
+ * creator (or creators, if more than one check is found inside) for it. It
+ * ignores the "action" key, as it is a reserved keyword used to specify
+ * actions inside the ACL.
*
* This may throw LoaderError if it is not a dict or if some of the type
* names is not known (there's no creator registered for it). The
@@ -218,9 +269,8 @@ public:
map = description->mapValue();
}
catch (const data::TypeError&) {
- throw LoaderError(__FILE__, __LINE__,
- "Check description is not a map",
- description);
+ isc_throw_1(LoaderError, "Check description is not a map",
+ description);
}
// Call the internal part with extracted map
return (loadCheck(description, map));
@@ -242,8 +292,7 @@ public:
// We first check it's a list, so we can use the list reference
// (the list may be huge)
if (description->getType() != data::Element::list) {
- throw LoaderError(__FILE__, __LINE__, "ACL not a list",
- description);
+ isc_throw_1(LoaderError, "ACL not a list", description);
}
// First create an empty ACL
const List &list(description->listValue());
@@ -256,14 +305,12 @@ public:
map = (*i)->mapValue();
}
catch (const data::TypeError&) {
- throw LoaderError(__FILE__, __LINE__, "ACL element not a map",
- *i);
+ isc_throw_1(LoaderError, "ACL element not a map", *i);
}
// Create an action for the element
const Map::const_iterator action(map.find("action"));
if (action == map.end()) {
- throw LoaderError(__FILE__, __LINE__,
- "No action in ACL element", *i);
+ isc_throw_1(LoaderError, "No action in ACL element", *i);
}
const Action acValue(action_loader_(action->second));
// Now create the check if there's one
@@ -303,9 +350,8 @@ private:
// Now, do we have any definition? Or is it and abbreviation?
switch (map.size()) {
case 0:
- throw LoaderError(__FILE__, __LINE__,
- "Check description is empty",
- description);
+ isc_throw_1(LoaderError, "Check description is empty",
+ description);
case 1: {
// Get the first and only item
const Map::const_iterator checkDesc(map.begin());
@@ -313,24 +359,22 @@ private:
const typename Creators::const_iterator
creatorIt(creators_.find(name));
if (creatorIt == creators_.end()) {
- throw LoaderError(__FILE__, __LINE__,
- ("No creator for ACL check " +
- name).c_str(),
- description);
+ isc_throw_1(LoaderError, "No creator for ACL check " <<
+ name, description);
}
if (creatorIt->second->allowListAbbreviation() &&
checkDesc->second->getType() == data::Element::list) {
- throw LoaderError(__FILE__, __LINE__,
- "Not implemented (OR-abbreviated form)",
- checkDesc->second);
+ isc_throw_1(LoaderError,
+ "Not implemented (OR-abbreviated form)",
+ checkDesc->second);
}
// Create the check and return it
return (creatorIt->second->create(name, checkDesc->second));
}
default:
- throw LoaderError(__FILE__, __LINE__,
- "Not implemented (AND-abbreviated form)",
- description);
+ isc_throw_1(LoaderError,
+ "Not implemented (AND-abbreviated form)",
+ description);
}
}
/**
diff --git a/src/lib/exceptions/exceptions.h b/src/lib/exceptions/exceptions.h
index a42037b..d0f1d74 100644
--- a/src/lib/exceptions/exceptions.h
+++ b/src/lib/exceptions/exceptions.h
@@ -163,6 +163,17 @@ public:
oss__ << stream; \
throw type(__FILE__, __LINE__, oss__.str().c_str()); \
} while (1)
+
+///
+/// Similar as isc_throw, but allows the exception to have one additional
+/// parameter (the stream/text goes first)
+#define isc_throw_1(type, stream, param1) \
+ do { \
+ std::ostringstream oss__; \
+ oss__ << stream; \
+ throw type(__FILE__, __LINE__, oss__.str().c_str(), param1); \
+ } while (1)
+
}
#endif // __EXCEPTIONS_H
More information about the bind10-changes
mailing list