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

Private Methods

279   _connect_db
280       private instance (Boolean) _connect_db ()
281
282       Description: This method connects to the SQL database.
283
284   _get_db_version
285       private instance (Integer) _get_db_version ()
286
287       Description: Gets the current version of the database from the special
288       global vars tables.
289
290   _initialize_db
291       private instance (Boolean) _initialize_db ()
292
293       Description: This method will check to see if a user has had their
294       bayes variables initialized. If not then it will perform this
295       initialization.
296
297   _put_token
298       private instance (Boolean) _put_token (string $token,
299                                              integer $spam_count,
300                                              integer $ham_count,
301                                  string $atime)
302
303       Description: This method performs the work of either inserting or
304       updating a token in the database.
305
306   _put_tokens
307       private instance (Boolean) _put_tokens (\% $tokens,
308                                               integer $spam_count,
309                                               integer $ham_count,
310                             string $atime)
311
312       Description: This method performs the work of either inserting or
313       updating tokens in the database.
314
315   _get_oldest_token_age
316       private instance (Integer) _get_oldest_token_age ()
317
318       Description: This method finds the atime of the oldest token in the
319       database.
320
321       The use of min(atime) in the SQL is ugly and but really the most
322       efficient way of getting the oldest_token_age after we've done a mass
323       expire.  It should only be called at expire time.
324
325   _get_num_hapaxes
326       private instance (Integer) _get_num_hapaxes ()
327
328       Description: This method gets the total number of hapaxes (spam_count +
329       ham_count == 1) in the token database for a user.
330
331   _get_num_lowfreq
332       private instance (Integer) _get_num_lowfreq ()
333
334       Description: This method gets the total number of lowfreq tokens
335       (spam_count < 8 and ham_count < 8) in the token database for a user
336
337   _token_select_string
338       private instance (String) _token_select_string
339
340       Description: This method returns the string to be used in SELECT
341       statements to represent the token column.
342
343       The default is to use the RPAD function to pad the token out to 5
344       characters.
345
346
347
348perl v5.10.1                      2010-03M-a1i6l::SpamAssassin::BayesStore::SQL(3)