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 [2/15] - in /spamassassin/site/full/3.4.x: ./ doc/
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,180 @@
+NAME
+ Mail::SpamAssassin::ArchiveIterator - find and process messages one at a
+ time
+
+SYNOPSIS
+ my $iter = new Mail::SpamAssassin::ArchiveIterator(
+ {
+ 'opt_max_size' => 256 * 1024, # 0 implies no limit
+ 'opt_cache' => 1,
+ }
+ );
+
+ $iter->set_functions( \&wanted, sub { } );
+
+ eval { $iter->run(@ARGV); };
+
+ sub wanted {
+ my($class, $filename, $recv_date, $msg_array) = @_;
+
+ ...
+ }
+
+DESCRIPTION
+ The Mail::SpamAssassin::ArchiveIterator module will go through a set of
+ mbox files, mbx files, and directories (with a single message per file)
+ and generate a list of messages. It will then call the "wanted_sub" and
+ "result_sub" functions appropriately per message.
+
+METHODS
+ $item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ]
+ )
+ Constructs a new "Mail::SpamAssassin::ArchiveIterator" object. You
+ may pass the following attribute-value pairs to the constructor. The
+ pairs are optional unless otherwise noted.
+
+ opt_max_size
+ A value of option *opt_max_size* determines a limit (number of
+ bytes) beyond which a message is considered large and is skipped
+ by ArchiveIterator.
+
+ A value 0 implies no size limit, all messages are examined. An
+ undefined value implies a default limit of 256 KiB.
+
+ opt_all
+ Setting this option to true implicitly sets *opt_max_size* to 0,
+ i.e. no limit of a message size, all messages are processes by
+ ArchiveIterator. For compatibility with SpamAssassin versions
+ older than 3.4.0 which lacked option *opt_max_size*.
+
+ opt_scanprob
+ Randomly select messages to scan, with a probability of N, where
+ N ranges from 0.0 (no messages scanned) to 1.0 (all messages
+ scanned). Default is 1.0.
+
+ This setting can be specified separately for each target.
+
+ opt_before
+ Only use messages which are received after the given time_t
+ value. Negative values are an offset from the current time, e.g.
+ -86400 = last 24 hours; or as parsed by Time::ParseDate (e.g.
+ '-6 months')
+
+ This setting can be specified separately for each target.
+
+ opt_after
+ Same as opt_before, except the messages are only used if after
+ the given time_t value.
+
+ This setting can be specified separately for each target.
+
+ opt_want_date
+ Set to 1 (default) if you want the received date to be filled in
+ in the "wanted_sub" callback below. Set this to 0 to avoid this;
+ it's a good idea to set this to 0 if you can, as it imposes a
+ performance hit.
+
+ opt_skip_empty_messages
+ Set to 1 if you want to skip corrupt, 0-byte messages. The
+ default is 0.
+
+ opt_cache
+ Set to 0 (default) if you don't want to use cached information
+ to help speed up ArchiveIterator. Set to 1 to enable. This
+ setting requires "opt_cachedir" also be set.
+
+ opt_cachedir
+ Set to the path of a directory where you wish to store cached
+ information for "opt_cache", if you don't want to mix them with
+ the input files (as is the default). The directory must be both
+ readable and writable.
+
+ wanted_sub
+ Reference to a subroutine which will process message data.
+ Usually set via set_functions(). The routine will be passed 5
+ values: class (scalar), filename (scalar), received date
+ (scalar), message content (array reference, one message line per
+ element), and the message format key ('f' for file, 'm' for
+ mbox, 'b' for mbx).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ result_sub
+ Reference to a subroutine which will process the results of the
+ wanted_sub for each message processed. Usually set via
+ set_functions(). The routine will be passed 3 values: class
+ (scalar), result (scalar, returned from wanted_sub), and
+ received date (scalar).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ scan_progress_sub
+ Reference to a subroutine which will be called intermittently
+ during the 'scan' phase of the mass-check. No guarantees are
+ made as to how frequently this may happen, mind you.
+
+ opt_from_regex
+ This setting allows for flexibility in specifying the mbox
+ format From seperator.
+
+ It defaults to the regular expression:
+
+ /^From \S+ ?(\S\S\S \S\S\S .\d .\d:\d\d:\d\d
+ \d{4}|.\d-\d\d-\d{4}_\d\d:\d\d:\d\d_)/
+
+ Some SpamAssassin programs such as sa-learn will use the
+ configuration option 'mbox_format_from_regex' to override the
+ default regular expression.
+
+ set_functions( \&wanted_sub, \&result_sub )
+ Sets the subroutines used for message processing (wanted_sub), and
+ result reporting. For more information, see *new()* above.
+
+ run ( @target_paths )
+ Generates the list of messages to process, then runs each message
+ through the configured wanted subroutine. Files which have a name
+ ending in ".gz" or ".bz2" will be properly uncompressed via call to
+ "gzip -dc" and "bzip2 -dc" respectively.
+
+ The target_paths array is expected to be either one element per path
+ in the following format: "class:format:raw_location", or a hash
+ reference containing key-value option pairs and a 'target' key with
+ a value in that format.
+
+ The key-value option pairs that can be used are: opt_scanprob,
+ opt_after, opt_before. See the constructor method's documentation
+ for more information on their effects.
+
+ run() returns 0 if there was an error (can't open a file, etc,) and
+ 1 if there were no errors.
+
+ class
+ Either 'h' for ham or 's' for spam. If the class is longer than
+ 1 character, it will be truncated. If blank, 'h' is default.
+
+ format
+ Specifies the format of the raw_location. "dir" is a directory
+ whose files are individual messages, "file" a file with a single
+ message, "mbox" an mbox formatted file, or "mbx" for an mbx
+ formatted directory.
+
+ "detect" can also be used. This assumes "mbox" for any file
+ whose path contains the pattern "/\.mbox/i", "file" anything
+ that is not a directory, or "directory" otherwise.
+
+ raw_location
+ Path to file or directory. File globbing is allowed using the
+ standard csh-style globbing (see "perldoc -f glob"). "~" at the
+ front of the value will be replaced by the "HOME" environment
+ variable. Escaped whitespace is protected as well.
+
+ NOTE: "~user" is not allowed.
+
+ NOTE 2: "-" is not allowed as a raw location. To have
+ ArchiveIterator deal with STDIN, generate a temp file.
+
+SEE ALSO
+ "Mail::SpamAssassin" "spamassassin" "mass-check"
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,195 @@
+<!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::AsyncLoop - scanner asynchronous event loop</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="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>An asynchronous event loop used for long-running operations, performed ``in the
+background'' during the Mail::SpamAssassin::check() scan operation, such as DNS
+blocklist lookups.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_start_lookup">$ent = $async->start_lookup($ent, $master_deadline)</a></strong><br />
+</dt>
+<dd>
+Register the start of a long-running asynchronous lookup operation.
+<code>$ent</code> is a hash reference containing the following items:
+</dd>
+<dl>
+<dt><strong><a name="item_key">key (required)</a></strong><br />
+</dt>
+<dd>
+A key string, unique to this lookup. This is what is reported in
+debug messages, used as the key for <a href="#item_get_lookup"><code>get_lookup()</code></a>, etc.
+</dd>
+<p></p>
+<dt><strong><a name="item_id">id (required)</a></strong><br />
+</dt>
+<dd>
+An ID string, also unique to this lookup. Typically, this is the DNS packet ID
+as returned by DnsResolver's <code>bgsend</code> method. Sadly, the Net::DNS
+architecture forces us to keep a separate ID string for this task instead of
+reusing <a href="#item_key"><code>key</code></a> -- if you are not using DNS lookups through DnsResolver, it
+should be OK to just reuse <a href="#item_key"><code>key</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_type">type (required)</a></strong><br />
+</dt>
+<dd>
+A string, typically one word, used to describe the type of lookup in log
+messages, such as <code>DNSBL</code>, <code>MX</code>, <code>TXT</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_zone">zone (optional)</a></strong><br />
+</dt>
+<dd>
+A zone specification (typically a DNS zone name - e.g. host, domain, or RBL)
+which may be used as a key to look up per-zone settings. No semantics on this
+parameter is imposed by this module. Currently used to fetch by-zone timeouts.
+</dd>
+<p></p>
+<dt><strong><a name="item_timeout_initial">timeout_initial (optional)</a></strong><br />
+</dt>
+<dd>
+An initial value of elapsed time for which we are willing to wait for a
+response (time in seconds, floating point value is allowed). When elapsed
+time since a query started exceeds the timeout value and there are no other
+queries to wait for, the query is aborted. The actual timeout value ranges
+from timeout_initial and gradually approaches timeout_min (see next parameter)
+as the number of already completed queries approaches the number of all
+queries started.
+</dd>
+<dd>
+<p>If a caller does not explicitly provide this parameter or its value is
+undefined, a default initial timeout value is settable by a configuration
+variable rbl_timeout.</p>
+</dd>
+<dd>
+<p>If a value of the timeout_initial parameter is below timeout_min, the initial
+timeout is set to timeout_min.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_timeout_min">timeout_min (optional)</a></strong><br />
+</dt>
+<dd>
+A lower bound (in seconds) to which the actual timeout approaches as the
+number of queries completed approaches the number of all queries started.
+Defaults to 0.2 * timeout_initial.
+</dd>
+<p></p></dl>
+<p><code>$ent</code> is returned by this method, with its contents augmented by additional
+information.</p>
+<dt><strong><a name="item_bgsend_and_start_lookup">$ent = $async->bgsend_and_start_lookup($domain, $type, $class, $ent, $cb, %options)</a></strong><br />
+</dt>
+<dd>
+A common idiom: calls <code>bgsend</code>, followed by a call to <a href="#item_start_lookup"><code>start_lookup</code></a>,
+returning the argument $ent object as modified by <a href="#item_start_lookup"><code>start_lookup</code></a> and
+filled-in with a query ID.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_lookup">$ent = $async-><code>get_lookup($key)</code></a></strong><br />
+</dt>
+<dd>
+Retrieve the pending-lookup object for the given key <code>$key</code>.
+</dd>
+<dd>
+<p>If the lookup is complete, this will return <code>undef</code>.</p>
+</dd>
+<dd>
+<p>Note that a lookup is still considered ``pending'' until <a href="#item_complete_lookups"><code>complete_lookups()</code></a> is
+called, even if it has been reported as complete via <a href="#item_set_response_packet"><code>set_response_packet()</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_log_lookups_timing">$async-><code>log_lookups_timing()</code></a></strong><br />
+</dt>
+<dd>
+Log sorted timing for all completed lookups.
+</dd>
+<p></p>
+<dt><strong><a name="item_complete_lookups">$alldone = $async-><code>complete_lookups()</code></a></strong><br />
+</dt>
+<dd>
+Perform a poll of the pending lookups, to see if any are completed.
+Callbacks on completed queries will be called from poll_responses().
+</dd>
+<dd>
+<p>If there are no lookups remaining, or if too much time has elapsed since
+any results were returned, <code>1</code> is returned, otherwise <code>0</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_abort_remaining_lookups">$async-><code>abort_remaining_lookups()</code></a></strong><br />
+</dt>
+<dd>
+Abort any remaining lookups.
+</dd>
+<p></p>
+<dt><strong><a name="item_set_response_packet">$async->set_response_packet($id, $pkt, $key, $timestamp)</a></strong><br />
+</dt>
+<dd>
+Register a ``response packet'' for a given query. <code>$id</code> is the ID for the
+query, and must match the <a href="#item_id"><code>id</code></a> supplied in <a href="#item_start_lookup"><code>start_lookup()</code></a>. <code>$pkt</code> is the
+packet object for the response. A parameter <code>$key</code> identifies an entry in a
+hash %{$self->{pending_lookups}} where the object which spawned this query can
+be found, and through which futher information about the query is accessible.
+</dd>
+<dd>
+<p><code>$pkt</code> may be undef, indicating that no response packet is available, but a
+query has completed (e.g. was aborted or dismissed) and is no longer ``pending''.</p>
+</dd>
+<dd>
+<p>The DNS resolver's response packet <code>$pkt</code> will be made available to a callback
+subroutine through its argument as well as in <code>$ent-<gt</code>{response_packet}>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_report_id_complete">$async-><code>report_id_complete($id,$key,$key,$timestamp)</code></a></strong><br />
+</dt>
+<dd>
+Legacy. Equivalent to $self->set_response_packet($id,undef,$key,$timestamp),
+i.e. providing undef as a response packet. Register that a query has
+completed and is no longer ``pending''. <code>$id</code> is the ID for the query,
+and must match the <a href="#item_id"><code>id</code></a> supplied in <a href="#item_start_lookup"><code>start_lookup()</code></a>.
+</dd>
+<dd>
+<p>One or the other of <a href="#item_set_response_packet"><code>set_response_packet()</code></a> or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>
+should be called, but not both.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_last_poll_responses_time">$time = $async-><code>last_poll_responses_time()</code></a></strong><br />
+</dt>
+<dd>
+Get the time of the last call to <code>poll_responses()</code> (which is called
+from <a href="#item_complete_lookups"><code>complete_lookups()</code></a>. If <code>poll_responses()</code> was never called or
+<a href="#item_abort_remaining_lookups"><code>abort_remaining_lookups()</code></a> has been called <a href="#item_last_poll_responses_time"><code>last_poll_responses_time()</code></a>
+will return undef.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,121 @@
+NAME
+ Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
+
+DESCRIPTION
+ An asynchronous event loop used for long-running operations, performed
+ "in the background" during the Mail::SpamAssassin::check() scan
+ operation, such as DNS blocklist lookups.
+
+METHODS
+ $ent = $async->start_lookup($ent, $master_deadline)
+ Register the start of a long-running asynchronous lookup operation.
+ $ent is a hash reference containing the following items:
+
+ key (required)
+ A key string, unique to this lookup. This is what is reported in
+ debug messages, used as the key for "get_lookup()", etc.
+
+ id (required)
+ An ID string, also unique to this lookup. Typically, this is the
+ DNS packet ID as returned by DnsResolver's "bgsend" method.
+ Sadly, the Net::DNS architecture forces us to keep a separate ID
+ string for this task instead of reusing "key" -- if you are not
+ using DNS lookups through DnsResolver, it should be OK to just
+ reuse "key".
+
+ type (required)
+ A string, typically one word, used to describe the type of
+ lookup in log messages, such as "DNSBL", "MX", "TXT".
+
+ zone (optional)
+ A zone specification (typically a DNS zone name - e.g. host,
+ domain, or RBL) which may be used as a key to look up per-zone
+ settings. No semantics on this parameter is imposed by this
+ module. Currently used to fetch by-zone timeouts.
+
+ timeout_initial (optional)
+ An initial value of elapsed time for which we are willing to
+ wait for a response (time in seconds, floating point value is
+ allowed). When elapsed time since a query started exceeds the
+ timeout value and there are no other queries to wait for, the
+ query is aborted. The actual timeout value ranges from
+ timeout_initial and gradually approaches timeout_min (see next
+ parameter) as the number of already completed queries approaches
+ the number of all queries started.
+
+ If a caller does not explicitly provide this parameter or its
+ value is undefined, a default initial timeout value is settable
+ by a configuration variable rbl_timeout.
+
+ If a value of the timeout_initial parameter is below
+ timeout_min, the initial timeout is set to timeout_min.
+
+ timeout_min (optional)
+ A lower bound (in seconds) to which the actual timeout
+ approaches as the number of queries completed approaches the
+ number of all queries started. Defaults to 0.2 *
+ timeout_initial.
+
+ $ent is returned by this method, with its contents augmented by
+ additional information.
+
+ $ent = $async->bgsend_and_start_lookup($domain, $type, $class, $ent,
+ $cb, %options)
+ A common idiom: calls "bgsend", followed by a call to
+ "start_lookup", returning the argument $ent object as modified by
+ "start_lookup" and filled-in with a query ID.
+
+ $ent = $async->get_lookup($key)
+ Retrieve the pending-lookup object for the given key $key.
+
+ If the lookup is complete, this will return "undef".
+
+ Note that a lookup is still considered "pending" until
+ "complete_lookups()" is called, even if it has been reported as
+ complete via "set_response_packet()".
+
+ $async->log_lookups_timing()
+ Log sorted timing for all completed lookups.
+
+ $alldone = $async->complete_lookups()
+ Perform a poll of the pending lookups, to see if any are completed.
+ Callbacks on completed queries will be called from poll_responses().
+
+ If there are no lookups remaining, or if too much time has elapsed
+ since any results were returned, 1 is returned, otherwise 0.
+
+ $async->abort_remaining_lookups()
+ Abort any remaining lookups.
+
+ $async->set_response_packet($id, $pkt, $key, $timestamp)
+ Register a "response packet" for a given query. $id is the ID for
+ the query, and must match the "id" supplied in "start_lookup()".
+ $pkt is the packet object for the response. A parameter $key
+ identifies an entry in a hash %{$self->{pending_lookups}} where the
+ object which spawned this query can be found, and through which
+ futher information about the query is accessible.
+
+ $pkt may be undef, indicating that no response packet is available,
+ but a query has completed (e.g. was aborted or dismissed) and is no
+ longer "pending".
+
+ The DNS resolver's response packet $pkt will be made available to a
+ callback subroutine through its argument as well as in
+ "$ent-<gt"{response_packet}>.
+
+ $async->report_id_complete($id,$key,$key,$timestamp)
+ Legacy. Equivalent to
+ $self->set_response_packet($id,undef,$key,$timestamp), i.e.
+ providing undef as a response packet. Register that a query has
+ completed and is no longer "pending". $id is the ID for the query,
+ and must match the "id" supplied in "start_lookup()".
+
+ One or the other of "set_response_packet()" or
+ "report_id_complete()" should be called, but not both.
+
+ $time = $async->last_poll_responses_time()
+ Get the time of the last call to "poll_responses()" (which is called
+ from "complete_lookups()". If "poll_responses()" was never called or
+ "abort_remaining_lookups()" has been called
+ "last_poll_responses_time()" will return undef.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,89 @@
+<!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::AutoWhitelist - auto-whitelist handler for SpamAssassin</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>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::AutoWhitelist - auto-whitelist handler for SpamAssassin</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ (see Mail::SpamAssassin)</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>Mail::SpamAssassin is a module to identify spam using text analysis and
+several internet-based realtime blacklists.</p>
+<p>This class is used internally by SpamAssassin to manage the automatic
+whitelisting functionality. Please refer to the <code>Mail::SpamAssassin</code>
+documentation for public interfaces.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_check_address">$meanscore = awl->check_address($addr, $originating_ip, $signedby);</a></strong><br />
+</dt>
+<dd>
+This method will return the mean score of all messages associated with the
+given address, or undef if the address hasn't been seen before.
+</dd>
+<dd>
+<p>If <strong>$originating_ip</strong> is supplied, it will be used in the lookup.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_count">awl->count();</a></strong><br />
+</dt>
+<dd>
+This method will return the count of messages used in determining the
+whitelist correction.
+</dd>
+<p></p>
+<dt><strong><a name="item_add_score">awl->add_score($score);</a></strong><br />
+</dt>
+<dd>
+This method will add half the score to the current entry. Half the
+score is used, so that repeated use of the same From and IP address
+combination will gradually reduce the score.
+</dd>
+<p></p>
+<dt><strong><a name="item_add_known_good_address">awl->add_known_good_address($addr);</a></strong><br />
+</dt>
+<dd>
+This method will add a score of -100 to the given address -- effectively
+``bootstrapping'' the address as being one that should be whitelisted.
+</dd>
+<p></p>
+<dt><strong><a name="item_add_known_bad_address">awl->add_known_bad_address($addr);</a></strong><br />
+</dt>
+<dd>
+This method will add a score of 100 to the given address -- effectively
+``bootstrapping'' the address as being one that should be blacklisted.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,42 @@
+NAME
+ Mail::SpamAssassin::AutoWhitelist - auto-whitelist handler for
+ SpamAssassin
+
+SYNOPSIS
+ (see Mail::SpamAssassin)
+
+DESCRIPTION
+ Mail::SpamAssassin is a module to identify spam using text analysis and
+ several internet-based realtime blacklists.
+
+ This class is used internally by SpamAssassin to manage the automatic
+ whitelisting functionality. Please refer to the "Mail::SpamAssassin"
+ documentation for public interfaces.
+
+METHODS
+ $meanscore = awl->check_address($addr, $originating_ip, $signedby);
+ This method will return the mean score of all messages associated
+ with the given address, or undef if the address hasn't been seen
+ before.
+
+ If $originating_ip is supplied, it will be used in the lookup.
+
+ awl->count();
+ This method will return the count of messages used in determining
+ the whitelist correction.
+
+ awl->add_score($score);
+ This method will add half the score to the current entry. Half the
+ score is used, so that repeated use of the same From and IP address
+ combination will gradually reduce the score.
+
+ awl->add_known_good_address($addr);
+ This method will add a score of -100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ whitelisted.
+
+ awl->add_known_bad_address($addr);
+ This method will add a score of 100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ blacklisted.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,37 @@
+<!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::Bayes - support for learning classifiers</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="#description">DESCRIPTION</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Bayes - support for learning classifiers</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This is the general class used to train a learning classifier with new samples
+of spam and ham mail, and classify based on prior training.</p>
+<p>Prior to version 3.3.0, the default Bayes implementation was here; if you're
+looking for information on that, it has moved to
+<code>Mail::SpamAssassin::Plugin::Bayes</code>.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,11 @@
+NAME
+ Mail::SpamAssassin::Bayes - support for learning classifiers
+
+DESCRIPTION
+ This is the general class used to train a learning classifier with new
+ samples of spam and ham mail, and classify based on prior training.
+
+ Prior to version 3.3.0, the default Bayes implementation was here; if
+ you're looking for information on that, it has moved to
+ "Mail::SpamAssassin::Plugin::Bayes".
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,533 @@
+<!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 - Storage Module for default Bayes classifier</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="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore - Storage Module for default Bayes classifier</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This is the public API for the Bayesian store methods. Any implementation of
+the storage module for the default Bayes classifier must implement these methods.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_new">new</a></strong><br />
+</dt>
+<dd>
+public class (Mail::SpamAssassin::BayesStore) new (Mail::SpamAssassin::Plugin::Bayes $bayes)
+</dd>
+<dd>
+<p>Description:
+This method creates a new instance of the Mail::SpamAssassin::BayesStore
+object. You must pass in an instance of the Mail::SpamAssassin::Plugin::Bayes
+object, which is stashed for use throughout the module.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_db_version">DB_VERSION</a></strong><br />
+</dt>
+<dd>
+public instance (Integer) DB_VERSION ()
+</dd>
+<dd>
+<p>Description:
+This method returns the currently supported database version for the
+implementation.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_read_db_configs">read_db_configs</a></strong><br />
+</dt>
+<dd>
+public instance () read_db_configs ()
+</dd>
+<dd>
+<p>Description:
+This method reads any needed config variables from the configuration object
+and then calls the Mail::SpamAssassin::Plugin::Bayes read_db_configs method.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_prefork_init">prefork_init</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) prefork_init ()
+</dd>
+<dd>
+<p>Description:
+This optional method is called in the parent process shortly before
+forking off child processes.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_spamd_child_init">spamd_child_init</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) spamd_child_init ()
+</dd>
+<dd>
+<p>Description:
+This optional method is called in a child process shortly after being spawned.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tie_db_readonly">tie_db_readonly</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) tie_db_readonly ()
+</dd>
+<dd>
+<p>Description:
+This method opens up the database in readonly mode.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tie_db_writable">tie_db_writable</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) tie_db_writable ()
+</dd>
+<dd>
+<p>Description:
+This method opens up the database in writable mode.</p>
+</dd>
+<dd>
+<p>Any callers of this methods should ensure that they call <a href="#item_untie_db"><code>untie_db()</code></a>
+afterwards.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_untie_db">untie_db</a></strong><br />
+</dt>
+<dd>
+public instance () untie_db ()
+</dd>
+<dd>
+<p>Description:
+This method unties the database.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_calculate_expire_delta">calculate_expire_delta</a></strong><br />
+</dt>
+<dd>
+public instance (%) calculate_expire_delta (Integer $newest_atime,
+ Integer $start,
+ Integer $max_expire_mult)
+</dd>
+<dd>
+<p>Description:
+This method performs a calculation on the data to determine the optimum
+atime for token expiration.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_token_expiration">token_expiration</a></strong><br />
+</dt>
+<dd>
+public instance (Integer, Integer,
+ Integer, Integer) token_expiration(\% $opts,
+ Integer $newest_atime,
+ Integer $newdelta)
+</dd>
+<dd>
+<p>Description:
+This method performs the database specific expiration of tokens based on
+the passed in <code>$newest_atime</code> and <code>$newdelta</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_expire_old_tokens">expire_old_tokens</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) expire_old_tokens (\% hashref)
+</dd>
+<dd>
+<p>Description:
+This method expires old tokens from the database.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_expire_old_tokens_trapped">expire_old_tokens_trapped</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) expire_old_tokens_trapped (\% $opts)
+</dd>
+<dd>
+<p>Description:
+This methods does the actual token expiration.</p>
+</dd>
+<dd>
+<p>XXX More docs here about the methodology and what not</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_sync_due">sync_due</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) sync_due ()
+</dd>
+<dd>
+<p>Description:
+This methods determines if a sync is due.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_expiry_due">expiry_due</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) expiry_due ()
+</dd>
+<dd>
+<p>Description:
+This methods determines if an expire is due.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_seen_get">seen_get</a></strong><br />
+</dt>
+<dd>
+public instance (Char) seen_get (String $msgid)
+</dd>
+<dd>
+<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>
+</dd>
+<p></p>
+<dt><strong><a name="item_seen_put">seen_put</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) seen_put (String $msgid, Char $flag)
+</dd>
+<dd>
+<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>
+</dd>
+<p></p>
+<dt><strong><a name="item_seen_delete">seen_delete</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) seen_delete (String $msgid)
+</dd>
+<dd>
+<p>Description:
+This method removes <code>$msgid</code> from storage.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_storage_variables">get_storage_variables</a></strong><br />
+</dt>
+<dd>
+public instance (@) get_storage_variables ()
+</dd>
+<dd>
+<p>Description:
+This method retrieves the various administrative variables used by
+the Bayes storage implementation.</p>
+</dd>
+<dd>
+<p>The values returned in the array are in the following order:</p>
+</dd>
+<dd>
+<p>0: scan count base</p>
+</dd>
+<dd>
+<p>1: number of spam</p>
+</dd>
+<dd>
+<p>2: number of ham</p>
+</dd>
+<dd>
+<p>3: number of tokens in db</p>
+</dd>
+<dd>
+<p>4: last expire atime</p>
+</dd>
+<dd>
+<p>5: oldest token in db atime</p>
+</dd>
+<dd>
+<p>6: db version value</p>
+</dd>
+<dd>
+<p>7: last journal sync</p>
+</dd>
+<dd>
+<p>8: last atime delta</p>
+</dd>
+<dd>
+<p>9: last expire reduction count</p>
+</dd>
+<dd>
+<p>10: newest token in db atime</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dump_db_toks">dump_db_toks</a></strong><br />
+</dt>
+<dd>
+public instance () dump_db_toks (String $template, String $regex, @ @vars)
+</dd>
+<dd>
+<p>Description:
+This method loops over all tokens, computing the probability for the token
+and then printing it out according to the passed in template.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_set_last_expire">set_last_expire</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) _set_last_expire (Integer $time)
+</dd>
+<dd>
+<p>Description:
+This method sets the last expire time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_running_expire_tok">get_running_expire_tok</a></strong><br />
+</dt>
+<dd>
+public instance (Time) get_running_expire_tok ()
+</dd>
+<dd>
+<p>Description:
+This method determines if an expire is currently running and returns the time
+the expire started.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_set_running_expire_tok">set_running_expire_tok</a></strong><br />
+</dt>
+<dd>
+public instance (Time) set_running_expire_tok ()
+</dd>
+<dd>
+<p>Description:
+This method sets the running expire time to the current time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_running_expire_tok">remove_running_expire_tok</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) remove_running_expire_tok ()
+</dd>
+<dd>
+<p>Description:
+This method removes a currently set running expire time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tok_get">tok_get</a></strong><br />
+</dt>
+<dd>
+public instance (Integer, Integer, Time) tok_get (String $token)
+</dd>
+<dd>
+<p>Description:
+This method retrieves the specified token (<code>$token</code>) from storage and returns
+it's spam count, ham acount and last access time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tok_get_all">tok_get_all</a></strong><br />
+</dt>
+<dd>
+public instance (\@) tok_get_all (@ @tokens)
+</dd>
+<dd>
+<p>Description:
+This method retrieves the specified tokens (<code>@tokens</code>) from storage and
+returns an array ref of arrays spam count, ham count and last access time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tok_count_change">tok_count_change</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) tok_count_change (Integer $spam_count,
+ Integer $ham_count,
+ String $token,
+ Time $atime)
+</dd>
+<dd>
+<p>Description:
+This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to
+<code>$token</code> along with updating <code>$token</code>s atime with <code>$atime</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_multi_tok_count_change">multi_tok_count_change</a></strong><br />
+</dt>
+<dd>
+<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>
+</dd>
+<dd>
+<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 tokens
+atime with <code>$atime</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_nspam_nham_get">nspam_nham_get</a></strong><br />
+</dt>
+<dd>
+public instance (Integer, Integer) nspam_nham_get ()
+</dd>
+<dd>
+<p>Description:
+This method retrieves the total number of spam and the total number of ham
+currently under storage.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_nspam_nham_change">nspam_nham_change</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)
+</dd>
+<dd>
+<p>Description:
+This method updates the number of spam and the number of ham in the database.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tok_touch">tok_touch</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) tok_touch (String $token,
+ Time $atime)
+</dd>
+<dd>
+<p>Description:
+This method updates the given tokens (<code>$token</code>) access time.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_tok_touch_all">tok_touch_all</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) tok_touch_all (\@ $tokens,
+ Time $atime)
+</dd>
+<dd>
+<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>
+</dd>
+<p></p>
+<dt><strong><a name="item_cleanup">cleanup</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) cleanup ()
+</dd>
+<dd>
+<p>Description:
+This method performs any cleanup necessary before moving onto the next
+operation.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_magic_re">get_magic_re</a></strong><br />
+</dt>
+<dd>
+public instance get_magic_re (String)
+</dd>
+<dd>
+<p>Description:
+This method returns a regexp which indicates a magic token.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_sync">sync</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) sync (\% $opts)
+</dd>
+<dd>
+<p>Description:
+This method performs a sync of the database.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_perform_upgrade">perform_upgrade</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) perform_upgrade (\% $opts)
+</dd>
+<dd>
+<p>Description:
+This method is a utility method that performs any necessary upgrades
+between versions. It should know how to handle previous versions and
+what needs to happen to upgrade them.</p>
+</dd>
+<dd>
+<p>A true return value indicates success.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_database">clear_database</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) clear_database ()
+</dd>
+<dd>
+<p>Description:
+This method deletes all records for a particular user.</p>
+</dd>
+<dd>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_backup_database">backup_database</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) backup_database ()
+</dd>
+<dd>
+<p>Description:
+This method will dump the users database in a machine readable format.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_restore_database">restore_database</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) restore_database (String $filename, Boolean $showdots)
+</dd>
+<dd>
+<p>Description:
+This method restores a database from the given filename, <code>$filename</code>.</p>
+</dd>
+<dd>
+<p>Callers should be aware that any errors returned by this method
+could causes the database to be inconsistent for the given user.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_db_readable">db_readable</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) db_readable ()
+</dd>
+<dd>
+<p>Description:
+This method returns whether or not the Bayes DB is available in a
+readable state.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_db_writable">db_writable</a></strong><br />
+</dt>
+<dd>
+public instance (Boolean) db_writable ()
+</dd>
+<dd>
+<p>Description:
+This method returns whether or not the Bayes DB is available in a
+writable state.</p>
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,292 @@
+NAME
+ Mail::SpamAssassin::BayesStore - Storage Module for default Bayes
+ classifier
+
+DESCRIPTION
+ This is the public API for the Bayesian store methods. Any
+ implementation of the storage module for the default Bayes classifier
+ must implement these methods.
+
+METHODS
+ new public class (Mail::SpamAssassin::BayesStore) new
+ (Mail::SpamAssassin::Plugin::Bayes $bayes)
+
+ Description: This method creates a new instance of the
+ Mail::SpamAssassin::BayesStore object. You must pass in an instance
+ of the Mail::SpamAssassin::Plugin::Bayes object, which is stashed
+ for use throughout the module.
+
+ DB_VERSION
+ public instance (Integer) DB_VERSION ()
+
+ Description: This method returns the currently supported database
+ version for the implementation.
+
+ read_db_configs
+ public instance () read_db_configs ()
+
+ Description: This method reads any needed config variables from the
+ configuration object and then calls the
+ Mail::SpamAssassin::Plugin::Bayes read_db_configs method.
+
+ 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 opens up the database in readonly mode.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method opens up the database in writable mode.
+
+ Any callers of this methods should ensure that they call untie_db()
+ afterwards.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: This method unties the database.
+
+ 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 $newest_atime, Integer $newdelta)
+
+ Description: This method performs the database specific expiration
+ of tokens based on the passed in $newest_atime and $newdelta.
+
+ expire_old_tokens
+ public instance (Boolean) expire_old_tokens (\% hashref)
+
+ Description: This method expires old tokens from the database.
+
+ expire_old_tokens_trapped
+ public instance (Boolean) expire_old_tokens_trapped (\% $opts)
+
+ Description: This methods does the actual token expiration.
+
+ XXX More docs here about the methodology and what not
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This methods determines if a sync is due.
+
+ expiry_due
+ public instance (Boolean) expiry_due ()
+
+ Description: This methods determines if an expire is due.
+
+ seen_get
+ public instance (Char) 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 instance (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 storage.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative
+ variables used by the Bayes storage implementation.
+
+ 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, @
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in template.
+
+ 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 (Time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently
+ running and returns the time the expire started.
+
+ set_running_expire_tok
+ public instance (Time) set_running_expire_tok ()
+
+ Description: This method sets the running expire time to the current
+ time.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes a currently set running expire
+ time.
+
+ tok_get
+ public instance (Integer, Integer, Time) tok_get (String $token)
+
+ Description: This method retrieves the specified token ($token) from
+ storage and returns it's spam count, ham acount and last access
+ time.
+
+ tok_get_all
+ public instance (\@) tok_get_all (@ @tokens)
+
+ Description: This method retrieves the specified tokens (@tokens)
+ from storage and returns an array ref of arrays spam count, ham
+ count and last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change (Integer $spam_count,
+ Integer $ham_count, String $token, Time $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds
+ it to $token along with updating $tokens 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 tokens atime with $atime.
+
+ nspam_nham_get
+ public instance (Integer, Integer) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham currently under storage.
+
+ 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, Time $atime)
+
+ Description: This method updates the given tokens ($token) access
+ time.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch_all (\@ $tokens, Time $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 performs 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.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database.
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts)
+
+ Description: This method is a utility method that performs any
+ necessary upgrades between versions. It should know how to handle
+ previous versions and what needs to happen to upgrade them.
+
+ A true return value indicates success.
+
+ 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.
+
+ 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 whether or not the Bayes DB is
+ available in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable ()
+
+ Description: This method returns whether or not the Bayes DB is
+ available in a writable state.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,365 @@
+<!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::BDB - BerkeleyDB 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="#_open_db">_open_db</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_tokens">dump_tokens</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>
+ <li><a href="#_extract_atime">_extract_atime</a></li>
+ <li><a href="#_put_token">_put_token</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB 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 BDB 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::BDB
+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="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 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:
+Closes any open db handles. You can safely call this at any time.</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 BDB 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_tokens">dump_tokens</a></h2>
+<p>public instance () dump_tokens (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 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 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>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 tokens
+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>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 (String) get_magic_re ()</p>
+<p>Description:
+This method returns a regexp which indicates a magic token.</p>
+<p>Unused in BDB 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 causes 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_writable()</code></p>
+<p>Description:
+This method returns a boolean value indicating if the database is in a
+writable state.</p>
+<p>
+</p>
+<h2><a name="_extract_atime">_extract_atime</a></h2>
+<p>private instance () _extract_atime (String $token,
+ String $value,
+ String $index)</p>
+<p>Description:
+This method ensures that the database connection is properly setup and
+working. If appropriate it will initialize a users bayes variables so
+that they can begin using the database immediately.</p>
+<p>
+</p>
+<h2><a name="_put_token">_put_token</a></h2>
+<p>FIXME: This is rarely a good interface, because of the churn that will
+often happen in the ``magic'' tokens. Open-code this stuff in the
+presence of loops.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,282 @@
+NAME
+ Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module
+ Implementation
+
+SYNOPSIS
+DESCRIPTION
+ This module implementes a BDB 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::BDB object. It expects to be passed an
+ instance of the Mail::SpamAssassin:Bayes object which is passed into the
+ Mail::SpamAssassin::BayesStore parent object.
+
+ 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 a users 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.
+
+ 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 BDB 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_tokens
+ public instance () dump_tokens (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 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 an array ref of arrays spam count, ham acount 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 tokens 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.
+
+ 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 (String) get_magic_re ()
+
+ Description: This method returns a regexp which indicates a magic token.
+
+ Unused in BDB 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
+ causes 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_writable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a writable state.
+
+ _extract_atime
+ private instance () _extract_atime (String $token, String $value, String
+ $index)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If appropriate it will initialize a users
+ bayes variables so that they can begin using the database immediately.
+
+ _put_token
+ FIXME: This is rarely a good interface, because of the churn that will
+ often happen in the "magic" tokens. Open-code this stuff in the presence
+ of loops.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,194 @@
+<!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::MySQL - MySQL 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="#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="#_initialize_db">_initialize_db</a></li>
+ <li><a href="#_put_token">_put_token</a></li>
+ <li><a href="#_put_tokens">_put_tokens</a></li>
+ </ul>
+
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::BayesStore::MySQL - MySQL 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 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.</p>
+<p>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.</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="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="_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>
+
+</body>
+
+</html>