You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by km...@apache.org on 2014/02/11 18:26:52 UTC
svn commit: r1567225 [3/15] - in /spamassassin/site/full/3.4.x: ./ doc/
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,116 @@
+NAME
+ Mail::SpamAssassin::BayesStore::MySQL - MySQL Specific Bayesian Storage
+ Module Implementation
+
+SYNOPSIS
+DESCRIPTION
+ This module implements a MySQL specific based bayesian storage module.
+ It requires that you are running at least version 4.1 of MySQL, if you
+ are running a version of MySQL < 4.1 then several aspects of this module
+ will fail and possibly corrupt your bayes database data.
+
+ In addition, this module will support rollback on error, if you are
+ using the InnoDB database table type in MySQL. For more information
+ please review the instructions in sql/README.bayes.
+
+METHODS
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer) token_expiration(\%
+ $opts, Integer $newdelta, @ @vars)
+
+ Description: This method performs the database specific expiration of
+ tokens based on the passed in $newdelta and @vars.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ set_last_expire
+ public instance (Boolean) set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ The assumption is that the tokens already exist in the database.
+
+ We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
+ make some assumptions about how to handle the data (ie no need to batch
+ like we do in tok_get_all)
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method perfoms any cleanup necessary before moving
+ onto the next operation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+Private Methods
+ _connect_db
+ private instance (Boolean) _connect_db ()
+
+ Description: This method connects to the SQL database.
+
+ _initialize_db
+ private instance (Boolean) _initialize_db ()
+
+ Description: This method will check to see if a user has had their bayes
+ variables initialized. If not then it will perform this initialization.
+
+ _put_token
+ private instance (Boolean) _put_token (string $token, integer
+ $spam_count, integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating a token in the database.
+
+ _put_tokens
+ private instance (Boolean) _put_tokens (\% $tokens, integer $spam_count,
+ integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating tokens in the database.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,208 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::PgSQL - PostgreSQL Specific Bayesian Storage Module Implementation</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ </ul>
+
+ <li><a href="#private_methods">Private Methods</a></li>
+ <ul>
+
+ <li><a href="#_connect_db">_connect_db</a></li>
+ <li><a href="#_put_token">_put_token</a></li>
+ <li><a href="#_put_tokens">_put_tokens</a></li>
+ <li><a href="#_token_select_string">_token_select_string</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore::PgSQL - PostgreSQL Specific Bayesian Storage Module Implementation</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This module implements a PostgreSQL specific bayesian storage module.</p>
+<p>It subclasses Mail::SpamAssassin::BayesStore::SQL and overrides any methods
+which makes SQL calls involving the token column. Since PostgreSQL uses BYTEA
+for the token column type you must make sure that the DBD driver does the proper
+quoting. You can accomplish this by binding the token column to a specific type.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="token_expiration">token_expiration</a></h2>
+<p>public instance (Integer, Integer,
+ Integer, Integer) token_expiration(\% $opts,
+ Integer $newdelta,
+ @ @vars)</p>
+<p>Description:
+This method performs the database specific expiration of tokens based on
+the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+<p>
+</p>
+<h2><a name="seen_put">seen_put</a></h2>
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+<p>Description:
+This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of
+two values 's' for spam and 'h' for ham.</p>
+<p>
+</p>
+<h2><a name="seen_delete">seen_delete</a></h2>
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+<p>Description:
+This method removes <code>$msgid</code> from the database.</p>
+<p>
+</p>
+<h2><a name="set_last_expire">set_last_expire</a></h2>
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+<p>Description:
+This method sets the last expire time.</p>
+<p>
+</p>
+<h2><a name="set_running_expire_tok">set_running_expire_tok</a></h2>
+<p>public instance (String $time) set_running_expire_tok ()</p>
+<p>Description:
+This method sets the time that an expire starts running.</p>
+<p>
+</p>
+<h2><a name="remove_running_expire_tok">remove_running_expire_tok</a></h2>
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+<p>Description:
+This method removes the row in the database that indicates that
+and expire is currently running.</p>
+<p>
+</p>
+<h2><a name="tok_get">tok_get</a></h2>
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+<p>Description:
+This method retrieves a specificed token (<code>$token</code>) from the database
+and returns it's spam_count, ham_count and last access time.</p>
+<p>
+</p>
+<h2><a name="tok_get_all">tok_get_all</a></h2>
+<p>public instance (\@) tok_get (@ $tokens)</p>
+<p>Description:
+This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns
+an array ref of arrays spam count, ham acount and last access time.</p>
+<p>
+</p>
+<h2><a name="nspam_nham_change">nspam_nham_change</a></h2>
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)</p>
+<p>Description:
+This method updates the number of spam and the number of ham in the database.</p>
+<p>
+</p>
+<h2><a name="tok_touch">tok_touch</a></h2>
+<p>public instance (Boolean) tok_touch (String $token,
+ String $atime)</p>
+<p>Description:
+This method updates the given tokens (<code>$token</code>) atime.</p>
+<p>The assumption is that the token already exists in the database.</p>
+<p>
+</p>
+<h2><a name="tok_touch_all">tok_touch_all</a></h2>
+<p>public instance (Boolean) tok_touch (\@ $tokens
+ String $atime)</p>
+<p>Description:
+This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token
+atime is < <code>$atime</code>.</p>
+<p>The assumption is that the tokens already exist in the database.</p>
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make
+some assumptions about how to handle the data (ie no need to batch like we
+do in tok_get_all)</p>
+<p>
+</p>
+<h2><a name="cleanup">cleanup</a></h2>
+<p>public instance (Boolean) cleanup ()</p>
+<p>Description:
+This method perfoms any cleanup necessary before moving onto the next
+operation.</p>
+<p>
+</p>
+<h2><a name="clear_database">clear_database</a></h2>
+<p>public instance (Boolean) clear_database ()</p>
+<p>Description:
+This method deletes all records for a particular user.</p>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+<p>
+</p>
+<hr />
+<h1><a name="private_methods">Private Methods</a></h1>
+<p>
+</p>
+<h2><a name="_connect_db">_connect_db</a></h2>
+<p>private instance (Boolean) _connect_db ()</p>
+<p>Description:
+This method connects to the SQL database.</p>
+<p>
+</p>
+<h2><a name="_put_token">_put_token</a></h2>
+<p>private instance (Boolean) _put_token (string $token,
+ integer $spam_count,
+ integer $ham_count,
+ string $atime)</p>
+<p>Description:
+This method performs the work of either inserting or updating a token in
+the database.</p>
+<p>
+</p>
+<h2><a name="_put_tokens">_put_tokens</a></h2>
+<p>private instance (Boolean) _put_tokens (\% $token,
+ integer $spam_count,
+ integer $ham_count,
+ string $atime)</p>
+<p>Description:
+This method performs the work of either inserting or updating tokens in
+the database.</p>
+<p>
+</p>
+<h2><a name="_token_select_string">_token_select_string</a></h2>
+<p>private instance (String) _token_select_string</p>
+<p>Description:
+This method returns the string to be used in SELECT statements to represent
+the token column.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,128 @@
+NAME
+ Mail::SpamAssassin::BayesStore::PgSQL - PostgreSQL Specific Bayesian
+ Storage Module Implementation
+
+SYNOPSIS
+DESCRIPTION
+ This module implements a PostgreSQL specific bayesian storage module.
+
+ It subclasses Mail::SpamAssassin::BayesStore::SQL and overrides any
+ methods which makes SQL calls involving the token column. Since
+ PostgreSQL uses BYTEA for the token column type you must make sure that
+ the DBD driver does the proper quoting. You can accomplish this by
+ binding the token column to a specific type.
+
+METHODS
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer) token_expiration(\%
+ $opts, Integer $newdelta, @ @vars)
+
+ Description: This method performs the database specific expiration of
+ tokens based on the passed in $newdelta and @vars.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ set_last_expire
+ public instance (Boolean) set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ tok_get
+ public instance (Integer, Integer, Integer) tok_get (String $token)
+
+ Description: This method retrieves a specificed token ($token) from the
+ database and returns it's spam_count, ham_count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get (@ $tokens)
+
+ Description: This method retrieves the specified tokens ($tokens) from
+ storage and returns an array ref of arrays spam count, ham acount and
+ last access time.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ The assumption is that the tokens already exist in the database.
+
+ We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
+ make some assumptions about how to handle the data (ie no need to batch
+ like we do in tok_get_all)
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method perfoms any cleanup necessary before moving
+ onto the next operation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+Private Methods
+ _connect_db
+ private instance (Boolean) _connect_db ()
+
+ Description: This method connects to the SQL database.
+
+ _put_token
+ private instance (Boolean) _put_token (string $token, integer
+ $spam_count, integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating a token in the database.
+
+ _put_tokens
+ private instance (Boolean) _put_tokens (\% $token, integer $spam_count,
+ integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating tokens in the database.
+
+ _token_select_string
+ private instance (String) _token_select_string
+
+ Description: This method returns the string to be used in SELECT
+ statements to represent the token column.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,414 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module Implementation</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new">new</a></li>
+ <li><a href="#prefork_init">prefork_init</a></li>
+ <li><a href="#spamd_child_init">spamd_child_init</a></li>
+ <li><a href="#tie_db_readonly">tie_db_readonly</a></li>
+ <li><a href="#tie_db_writable">tie_db_writable</a></li>
+ <li><a href="#_open_db">_open_db</a></li>
+ <li><a href="#untie_db">untie_db</a></li>
+ <li><a href="#sync_due">sync_due</a></li>
+ <li><a href="#expiry_due">expiry_due</a></li>
+ <li><a href="#seen_get">seen_get</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#get_storage_variables">get_storage_variables</a></li>
+ <li><a href="#get_running_expire_tok">get_running_expire_tok</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#tok_count_change">tok_count_change</a></li>
+ <li><a href="#multi_tok_count_change">multi_tok_count_change</a></li>
+ <li><a href="#nspam_nham_get">nspam_nham_get</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#get_magic_re">get_magic_re</a></li>
+ <li><a href="#sync">sync</a></li>
+ <li><a href="#perform_upgrade">perform_upgrade</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ <li><a href="#dump_db_toks">dump_db_toks</a></li>
+ <li><a href="#backup_database">backup_database</a></li>
+ <li><a href="#restore_database">restore_database</a></li>
+ <li><a href="#db_readable">db_readable</a></li>
+ <li><a href="#db_writable">db_writable</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module Implementation</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This module implementes a Redis based bayesian storage module.</p>
+<p>Apache SpamAssassin v3.4.0 introduces support for keeping
+a Bayes database on a Redis server, either running locally, or accessed
+over network. Similar to SQL backends, the database may be concurrently
+used by several hosts running SpamAssassin.</p>
+<p>The current implementation only supports a global Bayes database, i.e.
+per-recipient sub-databases are not supported. The Redis 2.6.* server
+supports access over IPv4 or over a Unix socket, starting with Redis
+version 2.8.0 also IPv6 is supported. Bear in mind that Redis server only
+offers limited access controls, so it is advisable to let the Redis server
+bind to a loopback interface only, or to use other mechanisms to limit
+access, such as local firewall rules.</p>
+<p>The Redis backend for Bayes can put a Lua scripting support in a Redis
+server to good use, improving performance. The Lua support is available
+in Redis server since version 2.6. In absence of a Lua support, the Redis
+backend uses batched (pipelined) traditional Redis commands, so it should
+work with a Redis server version 2.4 (untested), although this is not
+recommended for busy sites.</p>
+<p>Expiration of token and 'seen' message id entries is left to the Redis
+server. There is no provision for manually expiring a database, so it is
+highly recommended to leave the setting bayes_auto_expire to its default
+value 1 (i.e. enabled).</p>
+<p>Example configuration:</p>
+<pre>
+ bayes_store_module Mail::SpamAssassin::BayesStore::Redis
+ bayes_sql_dsn server=127.0.0.1:6379;password=foo;database=2
+ bayes_token_ttl 21d
+ bayes_seen_ttl 8d
+ bayes_auto_expire 1</pre>
+<p>A redis server with a Lua support (2.6 or higher) is recommended
+for performance reasons.</p>
+<p>The bayes_sql_dsn config variable has been hijacked for our purposes:</p>
+<pre>
+ bayes_sql_dsn</pre>
+<pre>
+ Optional config parameters affecting a connection to a redis server.</pre>
+<pre>
+ This is a semicolon-separated list of option=value pairs, where an option
+ can be: server, password, database. Unrecognized options are silently
+ ignored.</pre>
+<pre>
+ The 'server' option specifies a socket on which a redis server is
+ listening. It can be an absolute path of a Unix socket, or a host:port
+ pair, where a host can be an IPv4 or IPv6 address or a host name.
+ An IPv6 address must be enclosed in brackets, e.g. [::1]:6379
+ (IPv6 support in a redis server is available since version 2.8.0).
+ A default is to connect to an INET socket at 127.0.0.1, port 6379.</pre>
+<pre>
+ The value of a 'password' option is sent in an AUTH command to a redis
+ server on connecting if a server requests authentication. A password is
+ sent in plain text and a redis server only offers an optional rudimentary
+ authentication. To limit access to a redis server use its 'bind' option
+ to bind to a specific interface (typically to a loopback interface),
+ or use a host-based firewall.</pre>
+<pre>
+ The value of a 'database' option can be an non-negative (small) integer,
+ which is passed to a redis server with a SELECT command on connecting,
+ and chooses a sub-database index. A default database index is 0.</pre>
+<pre>
+ Example: server=localhost:6379;password=foo;database=2</pre>
+<pre>
+ bayes_token_ttl</pre>
+<pre>
+ Controls token expiry (ttl value in SECONDS, sent as-is to Redis)
+ when bayes_auto_expire is true. Default value is 3 weeks (but check
+ Mail::SpamAssassin::Conf.pm to make sure).</pre>
+<pre>
+ bayes_seen_ttl</pre>
+<pre>
+ Controls 'seen' expiry (ttl value in SECONDS, sent as-is to Redis)
+ when bayes_auto_expire is true. Default value is 8 days (but check
+ Mail::SpamAssassin::Conf.pm to make sure).</pre>
+<p>Expiry is done internally in Redis using *_ttl settings mentioned above,
+but only if bayes_auto_expire is true (which is a default). This is
+why --force-expire etc does nothing, and token counts and atime values
+are shown as zero in statistics.</p>
+<p>LIMITATIONS: Only global bayes storage is implemented, per-user bayes is
+not currently available. Dumping (sa-learn --backup, or --dump) of a huge
+database may not be possible if all keys do not fit into process memory.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new">new</a></h2>
+<p>public class (Mail::SpamAssassin::BayesStore::Redis) new (Mail::Spamassassin::Plugin::Bayes $bayes)</p>
+<p>Description:
+This methods creates a new instance of the Mail::SpamAssassin::BayesStore::Redis
+object. It expects to be passed an instance of the Mail::SpamAssassin:Bayes
+object which is passed into the Mail::SpamAssassin::BayesStore parent object.</p>
+<p>
+</p>
+<h2><a name="prefork_init">prefork_init</a></h2>
+<p>public instance (Boolean) prefork_init ();</p>
+<p>Description:
+This optional method is called in the parent process shortly before
+forking off child processes.</p>
+<p>
+</p>
+<h2><a name="spamd_child_init">spamd_child_init</a></h2>
+<p>public instance (Boolean) spamd_child_init ();</p>
+<p>Description:
+This optional method is called in a child process shortly after being spawned.</p>
+<p>
+</p>
+<h2><a name="tie_db_readonly">tie_db_readonly</a></h2>
+<p>public instance (Boolean) tie_db_readonly ();</p>
+<p>Description:
+This method ensures that the database connection is properly setup and working.</p>
+<p>
+</p>
+<h2><a name="tie_db_writable">tie_db_writable</a></h2>
+<p>public instance (Boolean) tie_db_writable ()</p>
+<p>Description:
+This method ensures that the database connection is properly setup and
+working. If necessary it will initialize the database so that they can
+begin using the database immediately.</p>
+<p>
+</p>
+<h2><a name="_open_db">_open_db</a></h2>
+<p>private instance (Boolean) _open_db (Boolean $writable)</p>
+<p>Description:
+This method ensures that the database connection is properly setup and
+working. It will initialize bayes variables so that they can begin using
+the database immediately.</p>
+<p>
+</p>
+<h2><a name="untie_db">untie_db</a></h2>
+<p>public instance () untie_db ()</p>
+<p>Description:
+Closes any open db handles. You can safely call this at any time.</p>
+<p>
+</p>
+<h2><a name="sync_due">sync_due</a></h2>
+<p>public instance (Boolean) sync_due ()</p>
+<p>Description:
+This method determines if a database sync is currently required.</p>
+<p>Unused for Redis implementation.</p>
+<p>
+</p>
+<h2><a name="expiry_due">expiry_due</a></h2>
+<p>public instance (Boolean) expiry_due ()</p>
+<p>Description:
+This methods determines if an expire is due.</p>
+<p>Unused for Redis implementation.</p>
+<p>
+</p>
+<h2><a name="seen_get">seen_get</a></h2>
+<p>public instance (String) seen_get (string $msgid)</p>
+<p>Description:
+This method retrieves the stored value, if any, for <code>$msgid</code>. The return
+value is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code>
+is not found.</p>
+<p>
+</p>
+<h2><a name="seen_put">seen_put</a></h2>
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+<p>Description:
+This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one
+of two values 's' for spam and 'h' for ham.</p>
+<p>
+</p>
+<h2><a name="seen_delete">seen_delete</a></h2>
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+<p>Description:
+This method removes <code>$msgid</code> from the database.</p>
+<p>
+</p>
+<h2><a name="get_storage_variables">get_storage_variables</a></h2>
+<p>public instance (@) get_storage_variables ()</p>
+<p>Description:
+This method retrieves the various administrative variables used by
+the Bayes process and database.</p>
+<p>The values returned in the array are in the following order:</p>
+<p>0: scan count base
+1: number of spam
+2: number of ham
+3: number of tokens in db
+4: last expire atime
+5: oldest token in db atime
+6: db version value
+7: last journal sync
+8: last atime delta
+9: last expire reduction count
+10: newest token in db atime</p>
+<p>Only 1,2,6 are used with Redis, others return zero always.</p>
+<p>
+</p>
+<h2><a name="get_running_expire_tok">get_running_expire_tok</a></h2>
+<p>public instance (String $time) get_running_expire_tok ()</p>
+<p>Description:
+This method determines if an expire is currently running and returns
+the last time set.</p>
+<p>
+</p>
+<h2><a name="set_running_expire_tok">set_running_expire_tok</a></h2>
+<p>public instance (String $time) set_running_expire_tok ()</p>
+<p>Description:
+This method sets the time that an expire starts running.</p>
+<p>
+</p>
+<h2><a name="remove_running_expire_tok">remove_running_expire_tok</a></h2>
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+<p>Description:
+This method removes the row in the database that indicates that
+and expire is currently running.</p>
+<p>
+</p>
+<h2><a name="tok_get">tok_get</a></h2>
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+<p>Description:
+This method retrieves a specificed token (<code>$token</code>) from the database
+and returns its spam_count, ham_count and last access time.</p>
+<p>
+</p>
+<h2><a name="tok_get_all">tok_get_all</a></h2>
+<p>public instance (\@) tok_get (@ $tokens)</p>
+<p>Description:
+This method retrieves the specified tokens (<code>$tokens</code>) from storage and
+returns a ref to arrays spam count, ham count and last access time.</p>
+<p>
+</p>
+<h2><a name="tok_count_change">tok_count_change</a></h2>
+<p>public instance (Boolean) tok_count_change (
+ Integer $dspam, Integer $dham, String $token, String $newatime)</p>
+<p>Description:
+This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to
+<code>$tok</code> along with updating <code>$tok</code>s atime with <code>$atime</code>.</p>
+<p>
+</p>
+<h2><a name="multi_tok_count_change">multi_tok_count_change</a></h2>
+<p>public instance (Boolean) multi_tok_count_change (
+ Integer $dspam, Integer $dham, \% $tokens, String $newatime)</p>
+<p>Description:
+This method takes a <code>$dspam</code> and <code>$dham</code> and adds it to all of the
+tokens in the <code>$tokens</code> hash ref along with updating each token's
+atime with <code>$atime</code>.</p>
+<p>
+</p>
+<h2><a name="nspam_nham_get">nspam_nham_get</a></h2>
+<p>public instance ($spam_count, $ham_count) nspam_nham_get ()</p>
+<p>Description:
+This method retrieves the total number of spam and the total number of
+ham learned.</p>
+<p>
+</p>
+<h2><a name="nspam_nham_change">nspam_nham_change</a></h2>
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)</p>
+<p>Description:
+This method updates the number of spam and the number of ham in the database.</p>
+<p>
+</p>
+<h2><a name="tok_touch">tok_touch</a></h2>
+<p>public instance (Boolean) tok_touch (String $token,
+ String $atime)</p>
+<p>Description:
+This method updates the given tokens (<code>$token</code>) atime.</p>
+<p>The assumption is that the token already exists in the database.</p>
+<p>We will never update to an older atime</p>
+<p>
+</p>
+<h2><a name="tok_touch_all">tok_touch_all</a></h2>
+<p>public instance (Boolean) tok_touch (\@ $tokens
+ String $atime)</p>
+<p>Description:
+This method does a mass update of the given list of tokens <code>$tokens</code>,
+if the existing token atime is < <code>$atime</code>.</p>
+<p>
+</p>
+<h2><a name="cleanup">cleanup</a></h2>
+<p>public instance (Boolean) cleanup ()</p>
+<p>Description:
+This method perfoms any cleanup necessary before moving onto the next
+operation.</p>
+<p>
+</p>
+<h2><a name="get_magic_re">get_magic_re</a></h2>
+<p>public instance (String) get_magic_re ()</p>
+<p>Description:
+This method returns a regexp which indicates a magic token.</p>
+<p>
+</p>
+<h2><a name="sync">sync</a></h2>
+<p>public instance (Boolean) sync (\% $opts)</p>
+<p>Description:
+This method performs a sync of the database</p>
+<p>
+</p>
+<h2><a name="perform_upgrade">perform_upgrade</a></h2>
+<p>public instance (Boolean) perform_upgrade (\% $opts);</p>
+<p>Description:
+Performs an upgrade of the database from one version to another, not
+currently used in this implementation.</p>
+<p>
+</p>
+<h2><a name="clear_database">clear_database</a></h2>
+<p>public instance (Boolean) clear_database ()</p>
+<p>Description:
+This method deletes all records for a particular user.</p>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+<p>
+</p>
+<h2><a name="dump_db_toks">dump_db_toks</a></h2>
+<p>public instance () dump_db_toks (String $template, String $regex, Array @vars)</p>
+<p>Description:
+This method loops over all tokens, computing the probability for the token
+and then printing it out according to the passed in token.</p>
+<p>
+</p>
+<h2><a name="backup_database">backup_database</a></h2>
+<p>public instance (Boolean) backup_database ()</p>
+<p>Description:
+This method will dump the users database in a machine readable format.</p>
+<p>
+</p>
+<h2><a name="restore_database">restore_database</a></h2>
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+<p>Description:
+This method restores a database from the given filename, <code>$filename</code>.</p>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+<p>
+</p>
+<h2><a name="db_readable">db_readable</a></h2>
+<p>public instance (Boolean) <code>db_readable()</code></p>
+<p>Description:
+This method returns a boolean value indicating if the database is in a
+readable state.</p>
+<p>
+</p>
+<h2><a name="db_writable">db_writable</a></h2>
+<p>public instance (Boolean) <code>db_writable()</code></p>
+<p>Description:
+This method returns a boolean value indicating if the database is in a
+writable state.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,331 @@
+NAME
+ Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module
+ Implementation
+
+SYNOPSIS
+DESCRIPTION
+ This module implementes a Redis based bayesian storage module.
+
+ Apache SpamAssassin v3.4.0 introduces support for keeping a Bayes
+ database on a Redis server, either running locally, or accessed over
+ network. Similar to SQL backends, the database may be concurrently used
+ by several hosts running SpamAssassin.
+
+ The current implementation only supports a global Bayes database, i.e.
+ per-recipient sub-databases are not supported. The Redis 2.6.* server
+ supports access over IPv4 or over a Unix socket, starting with Redis
+ version 2.8.0 also IPv6 is supported. Bear in mind that Redis server
+ only offers limited access controls, so it is advisable to let the Redis
+ server bind to a loopback interface only, or to use other mechanisms to
+ limit access, such as local firewall rules.
+
+ The Redis backend for Bayes can put a Lua scripting support in a Redis
+ server to good use, improving performance. The Lua support is available
+ in Redis server since version 2.6. In absence of a Lua support, the
+ Redis backend uses batched (pipelined) traditional Redis commands, so it
+ should work with a Redis server version 2.4 (untested), although this is
+ not recommended for busy sites.
+
+ Expiration of token and 'seen' message id entries is left to the Redis
+ server. There is no provision for manually expiring a database, so it is
+ highly recommended to leave the setting bayes_auto_expire to its default
+ value 1 (i.e. enabled).
+
+ Example configuration:
+
+ bayes_store_module Mail::SpamAssassin::BayesStore::Redis
+ bayes_sql_dsn server=127.0.0.1:6379;password=foo;database=2
+ bayes_token_ttl 21d
+ bayes_seen_ttl 8d
+ bayes_auto_expire 1
+
+ A redis server with a Lua support (2.6 or higher) is recommended for
+ performance reasons.
+
+ The bayes_sql_dsn config variable has been hijacked for our purposes:
+
+ bayes_sql_dsn
+
+ Optional config parameters affecting a connection to a redis server.
+
+ This is a semicolon-separated list of option=value pairs, where an option
+ can be: server, password, database. Unrecognized options are silently
+ ignored.
+
+ The 'server' option specifies a socket on which a redis server is
+ listening. It can be an absolute path of a Unix socket, or a host:port
+ pair, where a host can be an IPv4 or IPv6 address or a host name.
+ An IPv6 address must be enclosed in brackets, e.g. [::1]:6379
+ (IPv6 support in a redis server is available since version 2.8.0).
+ A default is to connect to an INET socket at 127.0.0.1, port 6379.
+
+ The value of a 'password' option is sent in an AUTH command to a redis
+ server on connecting if a server requests authentication. A password is
+ sent in plain text and a redis server only offers an optional rudimentary
+ authentication. To limit access to a redis server use its 'bind' option
+ to bind to a specific interface (typically to a loopback interface),
+ or use a host-based firewall.
+
+ The value of a 'database' option can be an non-negative (small) integer,
+ which is passed to a redis server with a SELECT command on connecting,
+ and chooses a sub-database index. A default database index is 0.
+
+ Example: server=localhost:6379;password=foo;database=2
+
+ bayes_token_ttl
+
+ Controls token expiry (ttl value in SECONDS, sent as-is to Redis)
+ when bayes_auto_expire is true. Default value is 3 weeks (but check
+ Mail::SpamAssassin::Conf.pm to make sure).
+
+ bayes_seen_ttl
+
+ Controls 'seen' expiry (ttl value in SECONDS, sent as-is to Redis)
+ when bayes_auto_expire is true. Default value is 8 days (but check
+ Mail::SpamAssassin::Conf.pm to make sure).
+
+ Expiry is done internally in Redis using *_ttl settings mentioned above,
+ but only if bayes_auto_expire is true (which is a default). This is why
+ --force-expire etc does nothing, and token counts and atime values are
+ shown as zero in statistics.
+
+ LIMITATIONS: Only global bayes storage is implemented, per-user bayes is
+ not currently available. Dumping (sa-learn --backup, or --dump) of a
+ huge database may not be possible if all keys do not fit into process
+ memory.
+
+METHODS
+ new
+ public class (Mail::SpamAssassin::BayesStore::Redis) new
+ (Mail::Spamassassin::Plugin::Bayes $bayes)
+
+ Description: This methods creates a new instance of the
+ Mail::SpamAssassin::BayesStore::Redis object. It expects to be passed an
+ instance of the Mail::SpamAssassin:Bayes object which is passed into the
+ Mail::SpamAssassin::BayesStore parent object.
+
+ prefork_init
+ public instance (Boolean) prefork_init ();
+
+ Description: This optional method is called in the parent process
+ shortly before forking off child processes.
+
+ spamd_child_init
+ public instance (Boolean) spamd_child_init ();
+
+ Description: This optional method is called in a child process shortly
+ after being spawned.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ();
+
+ Description: This method ensures that the database connection is
+ properly setup and working.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If necessary it will initialize the database
+ so that they can begin using the database immediately.
+
+ _open_db
+ private instance (Boolean) _open_db (Boolean $writable)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. It will initialize bayes variables so that
+ they can begin using the database immediately.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: Closes any open db handles. You can safely call this at any
+ time.
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This method determines if a database sync is currently
+ required.
+
+ Unused for Redis implementation.
+
+ expiry_due
+ public instance (Boolean) expiry_due ()
+
+ Description: This methods determines if an expire is due.
+
+ Unused for Redis implementation.
+
+ seen_get
+ public instance (String) seen_get (string $msgid)
+
+ Description: This method retrieves the stored value, if any, for $msgid.
+ The return value is the stored string ('s' for spam and 'h' for ham) or
+ undef if $msgid is not found.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative variables
+ used by the Bayes process and database.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base 1: number of spam 2: number of ham 3: number of
+ tokens in db 4: last expire atime 5: oldest token in db atime 6: db
+ version value 7: last journal sync 8: last atime delta 9: last expire
+ reduction count 10: newest token in db atime
+
+ Only 1,2,6 are used with Redis, others return zero always.
+
+ get_running_expire_tok
+ public instance (String $time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently running
+ and returns the last time set.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ tok_get
+ public instance (Integer, Integer, Integer) tok_get (String $token)
+
+ Description: This method retrieves a specificed token ($token) from the
+ database and returns its spam_count, ham_count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get (@ $tokens)
+
+ Description: This method retrieves the specified tokens ($tokens) from
+ storage and returns a ref to arrays spam count, ham count and last
+ access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change ( Integer $dspam, Integer
+ $dham, String $token, String $newatime)
+
+ Description: This method takes a $spam_count and $ham_count and adds it
+ to $tok along with updating $toks atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change ( Integer $dspam,
+ Integer $dham, \% $tokens, String $newatime)
+
+ Description: This method takes a $dspam and $dham and adds it to all of
+ the tokens in the $tokens hash ref along with updating each token's
+ atime with $atime.
+
+ nspam_nham_get
+ public instance ($spam_count, $ham_count) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham learned.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ We will never update to an older atime
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method perfoms any cleanup necessary before moving
+ onto the next operation.
+
+ get_magic_re
+ public instance (String) get_magic_re ()
+
+ Description: This method returns a regexp which indicates a magic token.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts);
+
+ Description: Performs an upgrade of the database from one version to
+ another, not currently used in this implementation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ dump_db_toks
+ public instance () dump_db_toks (String $template, String $regex, Array
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in token.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename, Boolean
+ $showdots)
+
+ Description: This method restores a database from the given filename,
+ $filename.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a writable state.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,434 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::SQL - SQL Bayesian Storage Module Implementation</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new">new</a></li>
+ <li><a href="#tie_db_readonly">tie_db_readonly</a></li>
+ <li><a href="#tie_db_writable">tie_db_writable</a></li>
+ <li><a href="#untie_db">untie_db</a></li>
+ <li><a href="#calculate_expire_delta">calculate_expire_delta</a></li>
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#sync_due">sync_due</a></li>
+ <li><a href="#seen_get">seen_get</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#get_storage_variables">get_storage_variables</a></li>
+ <li><a href="#dump_db_toks">dump_db_toks</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#get_running_expire_tok">get_running_expire_tok</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#tok_count_change">tok_count_change</a></li>
+ <li><a href="#multi_tok_count_change">multi_tok_count_change</a></li>
+ <li><a href="#nspam_nham_get">nspam_nham_get</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#get_magic_re">get_magic_re</a></li>
+ <li><a href="#sync">sync</a></li>
+ <li><a href="#perform_upgrade">perform_upgrade</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ <li><a href="#backup_database">backup_database</a></li>
+ <li><a href="#restore_database">restore_database</a></li>
+ <li><a href="#db_readable">db_readable</a></li>
+ <li><a href="#db_writable">db_writable</a></li>
+ </ul>
+
+ <li><a href="#private_methods">Private Methods</a></li>
+ <ul>
+
+ <li><a href="#_connect_db">_connect_db</a></li>
+ <li><a href="#_get_db_version">_get_db_version</a></li>
+ <li><a href="#_initialize_db">_initialize_db</a></li>
+ <li><a href="#_put_token">_put_token</a></li>
+ <li><a href="#_put_tokens">_put_tokens</a></li>
+ <li><a href="#_get_oldest_token_age">_get_oldest_token_age</a></li>
+ <li><a href="#_get_num_hapaxes">_get_num_hapaxes</a></li>
+ <li><a href="#_get_num_lowfreq">_get_num_lowfreq</a></li>
+ <li><a href="#_token_select_string">_token_select_string</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore::SQL - SQL Bayesian Storage Module Implementation</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This module implementes a SQL based bayesian storage module.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new">new</a></h2>
+<p>public class (Mail::SpamAssassin::BayesStore::SQL) new (Mail::Spamassassin::Plugin::Bayes $bayes)</p>
+<p>Description:
+This methods creates a new instance of the Mail::SpamAssassin::BayesStore::SQL
+object. It expects to be passed an instance of the Mail::SpamAssassin:Bayes
+object which is passed into the Mail::SpamAssassin::BayesStore parent object.</p>
+<p>This method sets up the database connection and determines the username to
+use in queries.</p>
+<p>
+</p>
+<h2><a name="tie_db_readonly">tie_db_readonly</a></h2>
+<p>public instance (Boolean) tie_db_readonly ();</p>
+<p>Description:
+This method ensures that the database connection is properly setup
+and working. If necessary it will initialize a user's bayes variables
+so that they can begin using the database immediately.</p>
+<p>
+</p>
+<h2><a name="tie_db_writable">tie_db_writable</a></h2>
+<p>public instance (Boolean) tie_db_writable ()</p>
+<p>Description:
+This method ensures that the database connection is properly setup
+and working. If necessary it will initialize a users bayes variables
+so that they can begin using the database immediately.</p>
+<p>
+</p>
+<h2><a name="untie_db">untie_db</a></h2>
+<p>public instance () untie_db ()</p>
+<p>Description:
+Disconnects from an SQL server.</p>
+<p>
+</p>
+<h2><a name="calculate_expire_delta">calculate_expire_delta</a></h2>
+<p>public instance (%) calculate_expire_delta (Integer $newest_atime,
+ Integer $start,
+ Integer $max_expire_mult)</p>
+<p>Description:
+This method performs a calculation on the data to determine the optimum
+atime for token expiration.</p>
+<p>
+</p>
+<h2><a name="token_expiration">token_expiration</a></h2>
+<p>public instance (Integer, Integer,
+ Integer, Integer) token_expiration(\% $opts,
+ Integer $newdelta,
+ @ @vars)</p>
+<p>Description:
+This method performs the database specific expiration of tokens based on
+the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+<p>
+</p>
+<h2><a name="sync_due">sync_due</a></h2>
+<p>public instance (Boolean) sync_due ()</p>
+<p>Description:
+This method determines if a database sync is currently required.</p>
+<p>Unused for SQL based implementation.</p>
+<p>
+</p>
+<h2><a name="seen_get">seen_get</a></h2>
+<p>public instance (String) seen_get (string $msgid)</p>
+<p>Description:
+This method retrieves the stored value, if any, for <code>$msgid</code>. The return value
+is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code> is not
+found.</p>
+<p>
+</p>
+<h2><a name="seen_put">seen_put</a></h2>
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+<p>Description:
+This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of
+two values 's' for spam and 'h' for ham.</p>
+<p>
+</p>
+<h2><a name="seen_delete">seen_delete</a></h2>
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+<p>Description:
+This method removes <code>$msgid</code> from the database.</p>
+<p>
+</p>
+<h2><a name="get_storage_variables">get_storage_variables</a></h2>
+<p>public instance (@) get_storage_variables ()</p>
+<p>Description:
+This method retrieves the various administrative variables used by
+the Bayes process and database.</p>
+<p>The values returned in the array are in the following order:</p>
+<p>0: scan count base</p>
+<p>1: number of spam</p>
+<p>2: number of ham</p>
+<p>3: number of tokens in db</p>
+<p>4: last expire atime</p>
+<p>5: oldest token in db atime</p>
+<p>6: db version value</p>
+<p>7: last journal sync</p>
+<p>8: last atime delta</p>
+<p>9: last expire reduction count</p>
+<p>10: newest token in db atime</p>
+<p>
+</p>
+<h2><a name="dump_db_toks">dump_db_toks</a></h2>
+<p>public instance () dump_db_toks (String $template, String $regex, Array @vars)</p>
+<p>Description:
+This method loops over all tokens, computing the probability for the token and then
+printing it out according to the passed in token.</p>
+<p>
+</p>
+<h2><a name="set_last_expire">set_last_expire</a></h2>
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+<p>Description:
+This method sets the last expire time.</p>
+<p>
+</p>
+<h2><a name="get_running_expire_tok">get_running_expire_tok</a></h2>
+<p>public instance (String $time) get_running_expire_tok ()</p>
+<p>Description:
+This method determines if an expire is currently running and returns
+the last time set.</p>
+<p>There can be multiple times, so we just pull the greatest (most recent)
+value.</p>
+<p>
+</p>
+<h2><a name="set_running_expire_tok">set_running_expire_tok</a></h2>
+<p>public instance (String $time) set_running_expire_tok ()</p>
+<p>Description:
+This method sets the time that an expire starts running.</p>
+<p>
+</p>
+<h2><a name="remove_running_expire_tok">remove_running_expire_tok</a></h2>
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+<p>Description:
+This method removes the row in the database that indicates that
+and expire is currently running.</p>
+<p>
+</p>
+<h2><a name="tok_get">tok_get</a></h2>
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+<p>Description:
+This method retrieves a specificed token (<code>$token</code>) from the database
+and returns it's spam_count, ham_count and last access time.</p>
+<p>
+</p>
+<h2><a name="tok_get_all">tok_get_all</a></h2>
+<p>public instance (\@) tok_get (@ $tokens)</p>
+<p>Description:
+This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns
+an array ref of arrays spam count, ham acount and last access time.</p>
+<p>
+</p>
+<h2><a name="tok_count_change">tok_count_change</a></h2>
+<p><table cellspacing="0" cellpadding="0"><tr><td>public instance (Boolean) tok_count_change (Integer $spam_count,
+<tr><td><td> Integer $ham_count,
+<tr><td><td> String $token,
+<tr><td><td> String $atime)</table></p>
+<p>Description:
+This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to
+<code>$tok</code> along with updating <code>$tok</code>s atime with <code>$atime</code>.</p>
+<p>
+</p>
+<h2><a name="multi_tok_count_change">multi_tok_count_change</a></h2>
+<p><table cellspacing="0" cellpadding="0"><tr><td>public instance (Boolean) multi_tok_count_change (Integer $spam_count,
+<tr><td> <td> Integer $ham_count,
+<tr><td><td> <td> \% $tokens,
+<tr><td><td> String $atime)</table></p>
+<p>Description:
+This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to all
+of the tokens in the <code>$tokens</code> hash ref along with updating each token's
+atime with <code>$atime</code>.</p>
+<p>
+</p>
+<h2><a name="nspam_nham_get">nspam_nham_get</a></h2>
+<p>public instance ($spam_count, $ham_count) nspam_nham_get ()</p>
+<p>Description:
+This method retrieves the total number of spam and the total number of
+ham learned.</p>
+<p>
+</p>
+<h2><a name="nspam_nham_change">nspam_nham_change</a></h2>
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)</p>
+<p>Description:
+This method updates the number of spam and the number of ham in the database.</p>
+<p>
+</p>
+<h2><a name="tok_touch">tok_touch</a></h2>
+<p>public instance (Boolean) tok_touch (String $token,
+ String $atime)</p>
+<p>Description:
+This method updates the given tokens (<code>$token</code>) atime.</p>
+<p>The assumption is that the token already exists in the database.</p>
+<p>
+</p>
+<h2><a name="tok_touch_all">tok_touch_all</a></h2>
+<p>public instance (Boolean) tok_touch (\@ $tokens
+ String $atime)</p>
+<p>Description:
+This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token
+atime is < <code>$atime</code>.</p>
+<p>The assumption is that the tokens already exist in the database.</p>
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make
+some assumptions about how to handle the data (ie no need to batch like we
+do in tok_get_all)</p>
+<p>
+</p>
+<h2><a name="cleanup">cleanup</a></h2>
+<p>public instance (Boolean) cleanup ()</p>
+<p>Description:
+This method perfoms any cleanup necessary before moving onto the next
+operation.</p>
+<p>
+</p>
+<h2><a name="get_magic_re">get_magic_re</a></h2>
+<p>public instance get_magic_re (String)</p>
+<p>Description:
+This method returns a regexp which indicates a magic token.</p>
+<p>Unused in SQL implementation.</p>
+<p>
+</p>
+<h2><a name="sync">sync</a></h2>
+<p>public instance (Boolean) sync (\% $opts)</p>
+<p>Description:
+This method performs a sync of the database</p>
+<p>
+</p>
+<h2><a name="perform_upgrade">perform_upgrade</a></h2>
+<p>public instance (Boolean) perform_upgrade (\% $opts);</p>
+<p>Description:
+Performs an upgrade of the database from one version to another, not
+currently used in this implementation.</p>
+<p>
+</p>
+<h2><a name="clear_database">clear_database</a></h2>
+<p>public instance (Boolean) clear_database ()</p>
+<p>Description:
+This method deletes all records for a particular user.</p>
+<p>Callers should be aware that any errors returned by this method
+could cause the database to be inconsistent for the given user.</p>
+<p>
+</p>
+<h2><a name="backup_database">backup_database</a></h2>
+<p>public instance (Boolean) backup_database ()</p>
+<p>Description:
+This method will dump the users database in a machine readable format.</p>
+<p>
+</p>
+<h2><a name="restore_database">restore_database</a></h2>
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+<p>Description:
+This method restores a database from the given filename, <code>$filename</code>.</p>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+<p>
+</p>
+<h2><a name="db_readable">db_readable</a></h2>
+<p>public instance (Boolean) <code>db_readable()</code></p>
+<p>Description:
+This method returns a boolean value indicating if the database is in a
+readable state.</p>
+<p>
+</p>
+<h2><a name="db_writable">db_writable</a></h2>
+<p>public instance (Boolean) <code>db_writeable()</code></p>
+<p>Description:
+This method returns a boolean value indicating if the database is in a
+writable state.</p>
+<p>
+</p>
+<hr />
+<h1><a name="private_methods">Private Methods</a></h1>
+<p>
+</p>
+<h2><a name="_connect_db">_connect_db</a></h2>
+<p>private instance (Boolean) _connect_db ()</p>
+<p>Description:
+This method connects to the SQL database.</p>
+<p>
+</p>
+<h2><a name="_get_db_version">_get_db_version</a></h2>
+<p>private instance (Integer) _get_db_version ()</p>
+<p>Description:
+Gets the current version of the database from the special global vars
+tables.</p>
+<p>
+</p>
+<h2><a name="_initialize_db">_initialize_db</a></h2>
+<p>private instance (Boolean) _initialize_db ()</p>
+<p>Description:
+This method will check to see if a user has had their bayes variables
+initialized. If not then it will perform this initialization.</p>
+<p>
+</p>
+<h2><a name="_put_token">_put_token</a></h2>
+<p>private instance (Boolean) _put_token (string $token,
+ integer $spam_count,
+ integer $ham_count,
+ string $atime)</p>
+<p>Description:
+This method performs the work of either inserting or updating a token in
+the database.</p>
+<p>
+</p>
+<h2><a name="_put_tokens">_put_tokens</a></h2>
+<p>private instance (Boolean) _put_tokens (\% $tokens,
+ integer $spam_count,
+ integer $ham_count,
+ string $atime)</p>
+<p>Description:
+This method performs the work of either inserting or updating tokens in
+the database.</p>
+<p>
+</p>
+<h2><a name="_get_oldest_token_age">_get_oldest_token_age</a></h2>
+<p>private instance (Integer) _get_oldest_token_age ()</p>
+<p>Description:
+This method finds the atime of the oldest token in the database.</p>
+<p>The use of <code>min(atime)</code> in the SQL is ugly and but really the most efficient
+way of getting the oldest_token_age after we've done a mass expire. It should
+only be called at expire time.</p>
+<p>
+</p>
+<h2><a name="_get_num_hapaxes">_get_num_hapaxes</a></h2>
+<p>private instance (Integer) _get_num_hapaxes ()</p>
+<p>Description:
+This method gets the total number of hapaxes (spam_count + ham_count == 1) in
+the token database for a user.</p>
+<p>
+</p>
+<h2><a name="_get_num_lowfreq">_get_num_lowfreq</a></h2>
+<p>private instance (Integer) _get_num_lowfreq ()</p>
+<p>Description:
+This method gets the total number of lowfreq tokens (spam_count < 8 and
+ham_count < 8) in the token database for a user</p>
+<p>
+</p>
+<h2><a name="_token_select_string">_token_select_string</a></h2>
+<p>private instance (String) _token_select_string</p>
+<p>Description:
+This method returns the string to be used in SELECT statements to represent
+the token column.</p>
+<p>The default is to use the RPAD function to pad the token out to 5 characters.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,326 @@
+NAME
+ Mail::SpamAssassin::BayesStore::SQL - SQL Bayesian Storage Module
+ Implementation
+
+SYNOPSIS
+DESCRIPTION
+ This module implementes a SQL based bayesian storage module.
+
+METHODS
+ new
+ public class (Mail::SpamAssassin::BayesStore::SQL) new
+ (Mail::Spamassassin::Plugin::Bayes $bayes)
+
+ Description: This methods creates a new instance of the
+ Mail::SpamAssassin::BayesStore::SQL object. It expects to be passed an
+ instance of the Mail::SpamAssassin:Bayes object which is passed into the
+ Mail::SpamAssassin::BayesStore parent object.
+
+ This method sets up the database connection and determines the username
+ to use in queries.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ();
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If necessary it will initialize a user's
+ bayes variables so that they can begin using the database immediately.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If necessary it will initialize a users
+ bayes variables so that they can begin using the database immediately.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: Disconnects from an SQL server.
+
+ calculate_expire_delta
+ public instance (%) calculate_expire_delta (Integer $newest_atime,
+ Integer $start, Integer $max_expire_mult)
+
+ Description: This method performs a calculation on the data to determine
+ the optimum atime for token expiration.
+
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer) token_expiration(\%
+ $opts, Integer $newdelta, @ @vars)
+
+ Description: This method performs the database specific expiration of
+ tokens based on the passed in $newdelta and @vars.
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This method determines if a database sync is currently
+ required.
+
+ Unused for SQL based implementation.
+
+ seen_get
+ public instance (String) seen_get (string $msgid)
+
+ Description: This method retrieves the stored value, if any, for $msgid.
+ The return value is the stored string ('s' for spam and 'h' for ham) or
+ undef if $msgid is not found.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative variables
+ used by the Bayes process and database.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base
+
+ 1: number of spam
+
+ 2: number of ham
+
+ 3: number of tokens in db
+
+ 4: last expire atime
+
+ 5: oldest token in db atime
+
+ 6: db version value
+
+ 7: last journal sync
+
+ 8: last atime delta
+
+ 9: last expire reduction count
+
+ 10: newest token in db atime
+
+ dump_db_toks
+ public instance () dump_db_toks (String $template, String $regex, Array
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in token.
+
+ set_last_expire
+ public instance (Boolean) set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ get_running_expire_tok
+ public instance (String $time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently running
+ and returns the last time set.
+
+ There can be multiple times, so we just pull the greatest (most recent)
+ value.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ tok_get
+ public instance (Integer, Integer, Integer) tok_get (String $token)
+
+ Description: This method retrieves a specificed token ($token) from the
+ database and returns it's spam_count, ham_count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get (@ $tokens)
+
+ Description: This method retrieves the specified tokens ($tokens) from
+ storage and returns an array ref of arrays spam count, ham acount and
+ last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change (Integer $spam_count, Integer
+ $ham_count, String $token, String $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds it
+ to $tok along with updating $toks atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change (Integer $spam_count,
+ Integer $ham_count, \% $tokens, String $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds it
+ to all of the tokens in the $tokens hash ref along with updating each
+ token's atime with $atime.
+
+ nspam_nham_get
+ public instance ($spam_count, $ham_count) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham learned.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ The assumption is that the tokens already exist in the database.
+
+ We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
+ make some assumptions about how to handle the data (ie no need to batch
+ like we do in tok_get_all)
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method perfoms any cleanup necessary before moving
+ onto the next operation.
+
+ get_magic_re
+ public instance get_magic_re (String)
+
+ Description: This method returns a regexp which indicates a magic token.
+
+ Unused in SQL implementation.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts);
+
+ Description: Performs an upgrade of the database from one version to
+ another, not currently used in this implementation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ cause the database to be inconsistent for the given user.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename, Boolean
+ $showdots)
+
+ Description: This method restores a database from the given filename,
+ $filename.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writeable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a writable state.
+
+Private Methods
+ _connect_db
+ private instance (Boolean) _connect_db ()
+
+ Description: This method connects to the SQL database.
+
+ _get_db_version
+ private instance (Integer) _get_db_version ()
+
+ Description: Gets the current version of the database from the special
+ global vars tables.
+
+ _initialize_db
+ private instance (Boolean) _initialize_db ()
+
+ Description: This method will check to see if a user has had their bayes
+ variables initialized. If not then it will perform this initialization.
+
+ _put_token
+ private instance (Boolean) _put_token (string $token, integer
+ $spam_count, integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating a token in the database.
+
+ _put_tokens
+ private instance (Boolean) _put_tokens (\% $tokens, integer $spam_count,
+ integer $ham_count, string $atime)
+
+ Description: This method performs the work of either inserting or
+ updating tokens in the database.
+
+ _get_oldest_token_age
+ private instance (Integer) _get_oldest_token_age ()
+
+ Description: This method finds the atime of the oldest token in the
+ database.
+
+ The use of min(atime) in the SQL is ugly and but really the most
+ efficient way of getting the oldest_token_age after we've done a mass
+ expire. It should only be called at expire time.
+
+ _get_num_hapaxes
+ private instance (Integer) _get_num_hapaxes ()
+
+ Description: This method gets the total number of hapaxes (spam_count +
+ ham_count == 1) in the token database for a user.
+
+ _get_num_lowfreq
+ private instance (Integer) _get_num_lowfreq ()
+
+ Description: This method gets the total number of lowfreq tokens
+ (spam_count < 8 and ham_count < 8) in the token database for a user
+
+ _token_select_string
+ private instance (String) _token_select_string
+
+ Description: This method returns the string to be used in SELECT
+ statements to represent the token column.
+
+ The default is to use the RPAD function to pad the token out to 5
+ characters.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,193 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Client - Client for spamd Protocol</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#public_methods">PUBLIC METHODS</a></li>
+ <ul>
+
+ <li><a href="#new">new</a></li>
+ <li><a href="#process">process</a></li>
+ <li><a href="#check">check</a></li>
+ <li><a href="#headers">headers</a></li>
+ <li><a href="#learn">learn</a></li>
+ <li><a href="#report">report</a></li>
+ <li><a href="#revoke">revoke</a></li>
+ <li><a href="#ping">ping</a></li>
+ </ul>
+
+ <li><a href="#private_methods">PRIVATE METHODS</a></li>
+ <ul>
+
+ <li><a href="#_create_connection">_create_connection</a></li>
+ <li><a href="#_parse_response_line">_parse_response_line</a></li>
+ <li><a href="#_clear_errors">_clear_errors</a></li>
+ <li><a href="#_filter">_filter</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Client - Client for spamd Protocol</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $client = Mail::SpamAssassin::Client->new({
+ port => 783,
+ host => 'localhost',
+ username => 'someuser'});
+ or</pre>
+<pre>
+ my $client = Mail::SpamAssassin::Client->new({
+ socketpath => '/path/to/socket',
+ username => 'someuser'});</pre>
+<pre>
+ Optionally takes timeout, which is applied to IO::Socket for the
+ initial connection. If not supplied, it defaults to 30 seconds.</pre>
+<pre>
+ if ($client->ping()) {
+ print "Ping is ok\n";
+ }</pre>
+<pre>
+ my $result = $client->process($testmsg);</pre>
+<pre>
+ if ($result->{isspam} eq 'True') {
+ do something with spam message here
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>Mail::SpamAssassin::Client is a module which provides a perl implementation of
+the spamd protocol.</p>
+<p>
+</p>
+<hr />
+<h1><a name="public_methods">PUBLIC METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new">new</a></h2>
+<p>public class (Mail::SpamAssassin::Client) new (\% $args)</p>
+<p>Description:
+This method creates a new Mail::SpamAssassin::Client object.</p>
+<p>
+</p>
+<h2><a name="process">process</a></h2>
+<p>public instance (\%) process (String $msg)</p>
+<p>Description:
+This method calls the spamd server with the PROCESS command.</p>
+<p>The return value is a hash reference containing several pieces of information,
+if available:</p>
+<p>content_length</p>
+<p>isspam</p>
+<p>score</p>
+<p>threshold</p>
+<p>message</p>
+<p>
+</p>
+<h2><a name="check">check</a></h2>
+<p>public instance (\%) check (String $msg)</p>
+<p>Description:
+The method implements the check call.</p>
+<p>See the process method for the return value.</p>
+<p>
+</p>
+<h2><a name="headers">headers</a></h2>
+<p>public instance (\%) headers (String $msg)</p>
+<p>Description:
+This method implements the headers call.</p>
+<p>See the process method for the return value.</p>
+<p>
+</p>
+<h2><a name="learn">learn</a></h2>
+<p>public instance (Boolean) learn (String $msg, Integer $learntype)</p>
+<p>Description:
+This method implements the learn call. <code>$learntype</code> should be
+an integer, 0 for spam, 1 for ham and 2 for forget. The return
+value is a boolean indicating if the message was learned or not.</p>
+<p>An undef return value indicates that there was an error and you
+should check the resp_code/resp_msg values to determine what
+the error was.</p>
+<p>
+</p>
+<h2><a name="report">report</a></h2>
+<p>public instance (Boolean) report (String $msg)</p>
+<p>Description:
+This method provides the report interface to spamd.</p>
+<p>
+</p>
+<h2><a name="revoke">revoke</a></h2>
+<p>public instance (Boolean) revoke (String $msg)</p>
+<p>Description:
+This method provides the revoke interface to spamd.</p>
+<p>
+</p>
+<h2><a name="ping">ping</a></h2>
+<p>public instance (Boolean) ping ()</p>
+<p>Description:
+This method performs a server ping and returns 0 or 1 depending on
+if the server responded correctly.</p>
+<p>
+</p>
+<hr />
+<h1><a name="private_methods">PRIVATE METHODS</a></h1>
+<p>
+</p>
+<h2><a name="_create_connection">_create_connection</a></h2>
+<p>private instance (IO::Socket) _create_connection ()</p>
+<p>Description:
+This method sets up a proper IO::Socket connection based on the arguments
+used when creating the client object.</p>
+<p>On failure, it sets an internal error code and returns undef.</p>
+<p>
+</p>
+<h2><a name="_parse_response_line">_parse_response_line</a></h2>
+<p>private instance (@) _parse_response_line (String $line)</p>
+<p>Description:
+This method parses the initial response line/header from the server
+and returns its parts.</p>
+<p>We have this as a separate method in case we ever decide to get fancy
+with the response line.</p>
+<p>
+</p>
+<h2><a name="_clear_errors">_clear_errors</a></h2>
+<p>private instance () _clear_errors ()</p>
+<p>Description:
+This method clears out any current errors.</p>
+<p>
+</p>
+<h2><a name="_filter">_filter</a></h2>
+<p>private instance (\%) _filter (String $msg, String $command)</p>
+<p>Description:
+Makes the actual call to the spamd server for the various filter method
+(ie PROCESS, CHECK, HEADERS, etc). The command that is passed in is
+sent to the spamd server.</p>
+<p>The return value is a hash reference containing several pieces of information,
+if available:</p>
+<p>content_length</p>
+<p>isspam</p>
+<p>score</p>
+<p>threshold</p>
+<p>message (if available)</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,140 @@
+NAME
+ Mail::SpamAssassin::Client - Client for spamd Protocol
+
+SYNOPSIS
+ my $client = Mail::SpamAssassin::Client->new({
+ port => 783,
+ host => 'localhost',
+ username => 'someuser'});
+ or
+
+ my $client = Mail::SpamAssassin::Client->new({
+ socketpath => '/path/to/socket',
+ username => 'someuser'});
+
+ Optionally takes timeout, which is applied to IO::Socket for the
+ initial connection. If not supplied, it defaults to 30 seconds.
+
+ if ($client->ping()) {
+ print "Ping is ok\n";
+ }
+
+ my $result = $client->process($testmsg);
+
+ if ($result->{isspam} eq 'True') {
+ do something with spam message here
+ }
+
+DESCRIPTION
+ Mail::SpamAssassin::Client is a module which provides a perl
+ implementation of the spamd protocol.
+
+PUBLIC METHODS
+ new
+ public class (Mail::SpamAssassin::Client) new (\% $args)
+
+ Description: This method creates a new Mail::SpamAssassin::Client
+ object.
+
+ process
+ public instance (\%) process (String $msg)
+
+ Description: This method calls the spamd server with the PROCESS
+ command.
+
+ The return value is a hash reference containing several pieces of
+ information, if available:
+
+ content_length
+
+ isspam
+
+ score
+
+ threshold
+
+ message
+
+ check
+ public instance (\%) check (String $msg)
+
+ Description: The method implements the check call.
+
+ See the process method for the return value.
+
+ headers
+ public instance (\%) headers (String $msg)
+
+ Description: This method implements the headers call.
+
+ See the process method for the return value.
+
+ learn
+ public instance (Boolean) learn (String $msg, Integer $learntype)
+
+ Description: This method implements the learn call. $learntype should be
+ an integer, 0 for spam, 1 for ham and 2 for forget. The return value is
+ a boolean indicating if the message was learned or not.
+
+ An undef return value indicates that there was an error and you should
+ check the resp_code/resp_msg values to determine what the error was.
+
+ report
+ public instance (Boolean) report (String $msg)
+
+ Description: This method provides the report interface to spamd.
+
+ revoke
+ public instance (Boolean) revoke (String $msg)
+
+ Description: This method provides the revoke interface to spamd.
+
+ ping
+ public instance (Boolean) ping ()
+
+ Description: This method performs a server ping and returns 0 or 1
+ depending on if the server responded correctly.
+
+PRIVATE METHODS
+ _create_connection
+ private instance (IO::Socket) _create_connection ()
+
+ Description: This method sets up a proper IO::Socket connection based on
+ the arguments used when creating the client object.
+
+ On failure, it sets an internal error code and returns undef.
+
+ _parse_response_line
+ private instance (@) _parse_response_line (String $line)
+
+ Description: This method parses the initial response line/header from
+ the server and returns its parts.
+
+ We have this as a separate method in case we ever decide to get fancy
+ with the response line.
+
+ _clear_errors
+ private instance () _clear_errors ()
+
+ Description: This method clears out any current errors.
+
+ _filter
+ private instance (\%) _filter (String $msg, String $command)
+
+ Description: Makes the actual call to the spamd server for the various
+ filter method (ie PROCESS, CHECK, HEADERS, etc). The command that is
+ passed in is sent to the spamd server.
+
+ The return value is a hash reference containing several pieces of
+ information, if available:
+
+ content_length
+
+ isspam
+
+ score
+
+ threshold
+
+ message (if available)
+