From 2e9c28f376325341ad1005564626e0c0e5bb6960 Mon Sep 17 00:00:00 2001
From: Thibault Charbonnier <thibaultcha@me.com>
Date: Sun, 19 Apr 2015 18:50:46 +0200
Subject: [PATCH] refactor: :prepare notice in kong.lua

:prepare might disappear in the future.
---
 kong/dao/cassandra/factory.lua | 55 ++++++++++++++++++----------------
 kong/kong.lua                  |  3 +-
 2 files changed, 31 insertions(+), 27 deletions(-)

diff --git a/kong/dao/cassandra/factory.lua b/kong/dao/cassandra/factory.lua
index 56828623283..0ece6350310 100644
--- a/kong/dao/cassandra/factory.lua
+++ b/kong/dao/cassandra/factory.lua
@@ -61,36 +61,39 @@ function CassandraFactory:drop()
   ]]
 end
 
--- Prepare all statements in collection._queries and put them in statements cache
--- Should be called with only a collection and will recursively call itself for nested statements.
--- @param collection A collection with a ._queries property
-local function prepare_collection(collection, collection_queries)
-  if not collection_queries then collection_queries = collection._queries end
-
-  for stmt_name, collection_query in pairs(collection_queries) do
-    if type(collection_query) == "table" and collection_query.query == nil then
-      -- Nested queries, let's recurse to prepare them too
-      prepare_collection(collection, collection_query)
-    else
-      -- _queries can contain strings or tables with string + keys of parameters to bind
-      local query_to_prepare
-      if type(collection_query) == "string" then
-        query_to_prepare = collection_query
-      elseif collection_query.query then
-        query_to_prepare = collection_query.query
-      end
-
-      local _, err = collection:prepare_kong_statement(query_to_prepare, collection_query.params)
-      if err then
-        error(err)
+-- Prepare all statements of collections `._queries` property and put them
+-- in a statements cache
+--
+-- Note:
+-- Even if the BaseDAO's :_execute() method support preparation of statements on-the-go,
+-- this method should be called when Kong starts in order to detect any failure in advance
+-- as well as test the connection to Cassandra.
+--
+-- @return error if any
+function CassandraFactory:prepare()
+  local function prepare_collection(collection, collection_queries)
+    if not collection_queries then collection_queries = collection._queries end
+    for stmt_name, collection_query in pairs(collection_queries) do
+      if type(collection_query) == "table" and collection_query.query == nil then
+        -- Nested queries, let's recurse to prepare them too
+        prepare_collection(collection, collection_query)
+      else
+        -- _queries can contain strings or tables with string + keys of parameters to bind
+        local query_to_prepare
+        if type(collection_query) == "string" then
+          query_to_prepare = collection_query
+        elseif collection_query.query then
+          query_to_prepare = collection_query.query
+        end
+
+        local _, err = collection:prepare_kong_statement(query_to_prepare, collection_query.params)
+        if err then
+          error(err)
+        end
       end
     end
   end
-end
 
--- Prepare all statements of collections
--- @return error if any
-function CassandraFactory:prepare()
   for _, collection in ipairs({ self.apis,
                                 self.consumers,
                                 self.plugins_configurations,
diff --git a/kong/kong.lua b/kong/kong.lua
index 00ae8ba6512..f3fba42ce38 100644
--- a/kong/kong.lua
+++ b/kong/kong.lua
@@ -139,7 +139,8 @@ function _M.init()
   -- Loading configuration
   configuration, dao = IO.load_configuration_and_dao(os.getenv("KONG_CONF"))
 
-  -- Initializing DAO
+  -- Prepare all collections' statements. Even if optional, this call is useful to check
+  -- all statements are valid in advance.
   local err = dao:prepare()
   if err then
     error(err)