Netrequire Server

Catalogue > store.lua

Provides a simple interface to store key/value pairs in a persistent storage mechanism.

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
29:
30:
31:
32:
33:
34:
35:
36:
37:
38:
39:
40:
41:
42:
43:
44:
45:
46:
47:
48:
49:
50:
51:
52:
53:
54:
55:
56:
57:
58:
59:
60:
61:
62:
63:
64:
65:
66:
67:
68:
69:
70:
71:
72:
73:
74:
75:
76:
77:
78:
79:
80:
81:
82:
83:
84:
85:
86:
87:
88:
89:
90:
91:
92:
93:
94:
95:
96:
97:
98:
99:
100:
101:
102:
103:
104:
105:
106:
107:
108:
109:
110:
111:
112:
113:
114:
115:
116:
117:
118:
119:
120:
121:
122:
123:
124:
125:
126:
127:
128:
129:
130:
131:
132:
133:
134:
135:
136:
137:
138:
139:
140:
141:
142:
143:
144:
145:
146:
147:
148:
149:
150:
151:
152:
153:
154:
155:
156:
157:
158:
159:
160:
161:
162:
163:
164:
165:
166:
167:
168:
169:
170:
171:
172:
173:
174:
175:
176:
-- $Revision: 1.6 $
-- $Date: 2013-05-07 21:56:08 $

--
-- The store module
-- Copyright (c) 2011-2012 iNTERFACEWARE Inc. ALL RIGHTS RESERVED
-- iNTERFACEWARE permits you to use, modify, and distribute this file in accordance
-- with the terms of the iNTERFACEWARE license agreement accompanying the software
-- in which it is used.
--

local store = {}

-- Constants.
local STORE_NAME = "store.db"
local DROP_TABLE_COMMAND = "DROP TABLE IF EXISTS store"
local CREATE_TABLE_COMMAND = [[
CREATE TABLE store
(
CKey Text(255) NOT NULL PRIMARY KEY,
CValue Text(255) 
)
]]

-- Functions.
local function trace(a,b,c,d) return end

-- use to create connection object when needed
local function connCreate()
   return db.connect{api=db.SQLITE, name=STORE_NAME}
end

-- This function returns the state of the store table by performing a general select
-- query on it.
function store.getTableState()
   local conn = connCreate()
   local R = conn:query ("SELECT * FROM store")
   conn:close()
   return R
end

-- This function resets the state of the store table by first deleting it and then
-- recreating it.
function store.resetTableState()
   -- This operation is performed as a database transaction to prevent another
   -- Translator script from accidentally attempting to access the store table
   -- while it has been temporarily deleted.
   local conn = connCreate()
   conn:begin()
   conn:execute{sql=DROP_TABLE_COMMAND, live=true}
   conn:execute{sql=CREATE_TABLE_COMMAND, live=true}
   conn:commit()
   conn:close()
end
   
function store.put(Key, Value)
   local conn = connCreate()
   local R = conn:query('REPLACE INTO store(CKey, CValue) VALUES(' .. conn:quote(tostring(Key)) .. ',' .. conn:quote(tostring(Value)) .. ')')
   conn:close()
end

function store.get(Key)
   local conn = connCreate()
   local R = conn:query('SELECT CValue from store WHERE CKey = ' .. conn:quote(tostring(Key)))
   conn:close()
   
   if #R == 0 then
      return nil
   end
   
   return R[1].CValue:nodeValue()
end

-- Local Functions

-- INITITALIZE DB: This automatically ensures the SQLlite database exists and has the store table present at script compile time.   
local function init()
   local conn = connCreate()
   local R = conn:query('SELECT * from sqlite_master WHERE type="table" and tbl_name="store"')
   conn:close()
   
   trace(#R)
   if #R == 0 then
      store.resetTableState()
   end
end
init() -- DO NOT REMOVE: Calls init() (once only) at script compile time to perform the initialization

-- help for the functions

if help then
   ------------------------
   -- store.getTableState()
   ------------------------
   local h = help.example()
   h.Title = 'store.getTableState'
   h.Desc = 'Return the state of the store table, by selecting all the rows.'
   h.Usage = 'store.getTableState()'
   h.Parameters = ''
   h.Returns = {[1]={['Desc']='All the rows from the store table <u>result set node tree</u>'}}
   h.ParameterTable = false
   h.Examples = {[1]=[[<pre>
      -- check the state of the store table, if more than 1 row then empty the store
      if  #store.getTableState() > 1 then
         store.resetTableState()
      end
      </pre>]]}
   h.SeeAlso = ''
   help.set{input_function=store.getTableState, help_data=h}

   --------------------------
   -- store.resetTableState()
   --------------------------
   local h = help.example()
   h.Title = 'store.resetTableState'
   h.Desc = 'Reset the state of the store table, by deleting and recreating the table.'
   h.Usage = 'store.resetTableState()'
   h.Parameters = ''
   h.Returns = 'none.'
   h.ParameterTable = false
   h.Examples = {[1]=[[<pre>
      -- reset the store table if more than 1 row exists
      if  #store.getTableState() > 1 then
         store.resetTableState()
      end
      </pre>]]}
   h.SeeAlso = ''
   help.set{input_function=store.resetTableState, help_data=h}

   ------------------------
   -- store.put()
   ------------------------
   local h = help.example()
   h.Title = 'store.put'
   h.Desc = [[Insert a Value for the Key. If the Key exists then replace the value. 
              If the Key does not exist insert a new Key and Value.]]
   h.Usage = 'store.put(Key, Value)'
   h.Parameters = {
      [1]={['Key']={['Desc']='Unique Identifier <u>string</u>'}},
      [2]={['Value']={['Desc']='Value to store <u>string</u>'}}
   }
   h.Returns = 'none.'
   h.ParameterTable = false
   h.Examples = {[1]=[[<pre>store.put('I am the Key', 'I am the Value')</pre>]]}
   h.SeeAlso = ''
   help.set{input_function=store.put, help_data=h}

   ------------------------
   -- store.get()
   ------------------------
   local h = help.example()
   h.Title = 'store.get'
   h.Desc = 'Retrieve the Value for the specified Key.'
   h.Usage = 'store.get(Key)'
   h.Parameters = {
      [1]={['Key']={['Desc']='Unique Identifier <u>string</u>'}}
   }
   h.Returns = {[1]={['Desc']='The Value of the row specified by the Key <u>string</u>'}}
   h.ParameterTable = false
   h.Examples = {[1]=[[<pre>store.get('I am the Key')</pre>]]}
   h.SeeAlso = ''
   help.set{input_function=store.get, help_data=h}
end

return store