1Mail::SpamAssassin::BayUesseSrtoCroen:t:rSiQbLu(t3e)d PeMralilD:o:cSupmaemnAtsastaisosnin::BayesStore::SQL(3)
2
3
4

NAME

6       Mail::SpamAssassin::BayesStore::SQL - SQL Bayesian Storage Module
7       Implementation
8

SYNOPSIS

DESCRIPTION

11       This module implementes a SQL based bayesian storage module.
12

METHODS

14       new
15
16       public class (Mail::SpamAssassin::BayesStore::SQL) new (Mail::Spamas‐
17       sassin::Bayes $bayes)
18
19       Description: This methods creates a new instance of the Mail::SpamAs‐
20       sassin::BayesStore::SQL object.  It expects to be passed an instance of
21       the Mail::SpamAssassin:Bayes object which is passed into the Mail::Spa‐
22       mAssassin::BayesStore parent object.
23
24       This method sets up the database connection and determines the username
25       to use in queries.
26
27       tie_db_readonly
28
29       public instance (Boolean) tie_db_readonly ();
30
31       Description: This method ensures that the database connection is prop‐
32       erly setup and working.  If necessary it will initialize a user's bayes
33       variables so that they can begin using the database immediately.
34
35       tie_db_writable
36
37       public instance (Boolean) tie_db_writable ()
38
39       Description: This method ensures that the database connetion is prop‐
40       erly setup and working. If necessary it will initialize a users bayes
41       variables so that they can begin using the database immediately.
42
43       untie_db
44
45       public instance () untie_db ()
46
47       Description: This method is unused for the SQL based implementation.
48
49       calculate_expire_delta
50
51       public instance (%) calculate_expire_delta (Integer $newest_atime,
52                                                    Integer $start,
53                                                    Integer $max_expire_mult)
54
55       Description: This method performs a calculation on the data to deter‐
56       mine the optimum atime for token expiration.
57
58       token_expiration
59
60       public instance (Integer, Integer,
61                        Integer, Integer) token_expiration(\% $opts,
62                                                           Integer $newdelta,
63                                                           @ @vars)
64
65       Description: This method performs the database specific expiration of
66       tokens based on the passed in $newdelta and @vars.
67
68       sync_due
69
70       public instance (Boolean) sync_due ()
71
72       Description: This method determines if a database sync is currently
73       required.
74
75       Unused for SQL based implementation.
76
77       seen_get
78
79       public instance (String) seen_get (string $msgid)
80
81       Description: This method retrieves the stored value, if any, for
82       $msgid.  The return value is the stored string ('s' for spam and 'h'
83       for ham) or undef if $msgid is not found.
84
85       seen_put
86
87       public (Boolean) seen_put (string $msgid, char $flag)
88
89       Description: This method records $msgid as the type given by $flag.
90       $flag is one of two values 's' for spam and 'h' for ham.
91
92       seen_delete
93
94       public instance (Boolean) seen_delete (string $msgid)
95
96       Description: This method removes $msgid from the database.
97
98       get_storage_variables
99
100       public instance (@) get_storage_variables ()
101
102       Description: This method retrieves the various administrative variables
103       used by the Bayes process and database.
104
105       The values returned in the array are in the following order:
106
107       0: scan count base
108
109       1: number of spam
110
111       2: number of ham
112
113       3: number of tokens in db
114
115       4: last expire atime
116
117       5: oldest token in db atime
118
119       6: db version value
120
121       7: last journal sync
122
123       8: last atime delta
124
125       9: last expire reduction count
126
127       10: newest token in db atime
128
129       dump_db_toks
130
131       public instance () dump_db_toks (String $template, String $regex, Array
132       @vars)
133
134       Description: This method loops over all tokens, computing the probabil‐
135       ity for the token and then printing it out according to the passed in
136       token.
137
138       set_last_expire
139
140       public instance (Boolean) set_last_expire (Integer $time)
141
142       Description: This method sets the last expire time.
143
144       get_running_expire_tok
145
146       public instance (String $time) get_running_expire_tok ()
147
148       Description: This method determines if an expire is currently running
149       and returns the last time set.
150
151       There can be multiple times, so we just pull the greatest (most recent)
152       value.
153
154       set_running_expire_tok
155
156       public instance (String $time) set_running_expire_tok ()
157
158       Description: This method sets the time that an expire starts running.
159
160       remove_running_expire_tok
161
162       public instance (Boolean) remove_running_expire_tok ()
163
164       Description: This method removes the row in the database that indicates
165       that and expire is currently running.
166
167       tok_get
168
169       public instance (Integer, Integer, Integer) tok_get (String $token)
170
171       Description: This method retrieves a specificed token ($token) from the
172       database and returns it's spam_count, ham_count and last access time.
173
174       tok_get_all
175
176       public instance (\@) tok_get (@ $tokens)
177
178       Description: This method retrieves the specified tokens ($tokens) from
179       storage and returns an array ref of arrays spam count, ham acount and
180       last access time.
181
182       tok_count_change
183
184       public instance (Boolean) tok_count_change (Integer $spam_count,
185                                    Integer $ham_count,
186                                    String $token,
187       String $atime)
188
189       Description: This method takes a $spam_count and $ham_count and adds it
190       to $tok along with updating $toks atime with $atime.
191
192       multi_tok_count_change
193
194       public instance (Boolean) multi_tok_count_change (Integer $spam_count,
195                                          Integer $ham_count,
196                                           \% $tokens,
197                                          String $atime)
198
199       Description: This method takes a $spam_count and $ham_count and adds it
200       to all of the tokens in the $tokens hash ref along with updating each
201       tokens atime with $atime.
202
203       nspam_nham_get
204
205       public instance ($spam_count, $ham_count) nspam_nham_get ()
206
207       Description: This method retrieves the total number of spam and the
208       total number of ham learned.
209
210       nspam_nham_change
211
212       public instance (Boolean) nspam_nham_change (Integer $num_spam,
213                                                    Integer $num_ham)
214
215       Description: This method updates the number of spam and the number of
216       ham in the database.
217
218       tok_touch
219
220       public instance (Boolean) tok_touch (String $token,
221                                            String $atime)
222
223       Description: This method updates the given tokens ($token) atime.
224
225       The assumption is that the token already exists in the database.
226
227       tok_touch_all
228
229       public instance (Boolean) tok_touch (\@ $tokens
230                                            String $atime)
231
232       Description: This method does a mass update of the given list of tokens
233       $tokens, if the existing token atime is < $atime.
234
235       The assumption is that the tokens already exist in the database.
236
237       We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
238       make some assumptions about how to handle the data (ie no need to batch
239       like we do in tok_get_all)
240
241       cleanup
242
243       public instance (Boolean) cleanup ()
244
245       Description: This method peroms any cleanup necessary before moving
246       onto the next operation.
247
248       get_magic_re
249
250       public instance get_magic_re (String)
251
252       Description: This method returns a regexp which indicates a magic
253       token.
254
255       Unused in SQL implementation.
256
257       sync
258
259       public instance (Boolean) sync (\% $opts)
260
261       Description: This method performs a sync of the database
262
263       perform_upgrade
264
265       public instance (Boolean) perform_upgrade (\% $opts);
266
267       Description: Performs an upgrade of the database from one version to
268       another, not currently used in this implementation.
269
270       clear_database
271
272       public instance (Boolean) clear_database ()
273
274       Description: This method deletes all records for a particular user.
275
276       Callers should be aware that any errors returned by this method could
277       causes the database to be inconsistent for the given user.
278
279       backup_database
280
281       public instance (Boolean) backup_database ()
282
283       Description: This method will dump the users database in a marchine
284       readable format.
285
286       restore_database
287
288       public instance (Boolean) restore_database (String $filename, Boolean
289       $showdots)
290
291       Description: This method restores a database from the given filename,
292       $filename.
293
294       Callers should be aware that any errors returned by this method could
295       causes the database to be inconsistent for the given user.
296
297       db_readable
298
299       public instance (Boolean) db_readable()
300
301       Description: This method returns a boolean value indicating if the
302       database is in a readable state.
303
304       db_writable
305
306       public instance (Boolean) db_writeable()
307
308       Description: This method returns a boolean value indicating if the
309       database is in a writable state.
310

Private Methods

312       _connect_db
313
314       private instance (Boolean) _connect_db ()
315
316       Description: This method connects to the SQL database.
317
318       _get_db_version
319
320       private instance (Integer) _get_db_version ()
321
322       Description: Gets the current version of the database from the special
323       global vars tables.
324
325       _initialize_db
326
327       private instance (Boolean) _initialize_db ()
328
329       Description: This method will check to see if a user has had their
330       bayes variables initialized. If not then it will perform this initial‐
331       ization.
332
333       _put_token
334
335       private instance (Boolean) _put_token (string $token,
336                                              integer $spam_count,
337                                              integer $ham_count,
338                                  string $atime)
339
340       Description: This method performs the work of either inserting or
341       updating a token in the database.
342
343       _put_tokens
344
345       private instance (Boolean) _put_tokens (\% $tokens,
346                                               integer $spam_count,
347                                               integer $ham_count,
348                             string $atime)
349
350       Description: This method performs the work of either inserting or
351       updating tokens in the database.
352
353       _get_oldest_token_age
354
355       private instance (Integer) _get_oldest_token_age ()
356
357       Description: This method finds the atime of the oldest token in the
358       database.
359
360       The use of min(atime) in the SQL is ugly and but really the most effi‐
361       cient way of getting the oldest_token_age after we've done a mass
362       expire.  It should only be called at expire time.
363
364       _get_num_hapaxes
365
366       private instance (Integer) _get_num_hapaxes ()
367
368       Description: This method gets the total number of hapaxes (spam_count +
369       ham_count == 1) in the token database for a user.
370
371       _get_num_lowfreq
372
373       private instance (Integer) _get_num_lowfreq ()
374
375       Description: This method gets the total number of lowfreq tokens
376       (spam_count < 8 and ham_count < 8) in the token database for a user
377
378       _token_select_string
379
380       private instance (String) _token_select_string
381
382       Description: This method returns the string to be used in SELECT state‐
383       ments to represent the token column.
384
385       The default is to use the RPAD function to pad the token out to 5 char‐
386       acters.
387
388
389
390perl v5.8.8                       2008-01M-a0i5l::SpamAssassin::BayesStore::SQL(3)