org.jasen
Class JasenScanner

java.lang.Object
  org.jasen.JasenScanner

public final class JasenScanner

extends Object

JasenScanner is a singleton scanner class for safe scanning of email messages using the jASEN engine.

All message scanning should be done through this class to guarantee thread safety and in particular to allow for correct behaviour during auto updates.

It is not, however, mandatory that this class be used exclusively for scanning, merely recommended.
For direct (non-singleton) access to the engine, use the org.jasen.core.engine.Jasen class

Author:

Jason Polites

See Also:

Jasen

Method Summary

void	destroy() Destroys the engine and all registered plugins
boolean	forceUpdate() Forces the engine to run an update check
JasenAutoUpdateListener	getAutoUpdateListener() Gets the listener registered for auto update events if one has been set.
Jasen	getEngine() Gets the reference to the internal scan engine
static JasenScanner	getInstance() Gets the current instance of the JasenScanner
List	getPlugins() Returns a read-only list of the plugins registered in the engine.
JasenScanListener	getScanListener() Gets the listener registered for scan events if one has been set.
void	init() Initialises the engine with the default configuration
void	init(InputStream in) Deprecated.
void	init(JasenConfigurationLoader loader) Initialises the engine using the configuration loader provided
void	init(String config) Deprecated.
boolean	isAlive() Returns true IFF the engine is initialised and ready for scans.
boolean	notifyPendingUpdate(JasenAutoUpdateParcel parcel) Called by the AutoUpdateManager if there is an update pending to signal a pause in scanning
void	notifyScan() Records the occurrance of a scan
void	notifyScanComplete() Records the completion of a scan
void	notifyUpdateComplete(JasenAutoUpdateReport report) Called by the AutoUpdateManager when the update has completed
void	notifyUpdateDownload(long bytes)
JasenScanResult	scan(javax.mail.internet.MimeMessage mm) Scans the given message.
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, float threshold) Scans the given message.
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, float threshold, String[] ignored) Scans the given message.
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, JasenMessage message) Scans the message without a threshold specified
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, JasenMessage message, float threshold) Scans the given mime message using the already mime-parsed JasenMessage.
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, JasenMessage message, float threshold, String[] ignored) Scans the given mime message using the already mime-parsed JasenMessage.
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, JasenMessage message, String[] ignored) Scans the message without a threshold specified
JasenScanResult	scan(javax.mail.internet.MimeMessage mm, String[] ignored) Scans the given message.
void	setAutoUpdateListener(JasenAutoUpdateListener autoUpdateListener) Sets the listener which will record update completion events.
void	setScanListener(JasenScanListener scanListener) Sets the listener which will record scan events.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static final JasenScanner getInstance()

Gets the current instance of the JasenScanner

Returns:

The current (and only) JasenScanner instance

getEngine

public Jasen getEngine()

Gets the reference to the internal scan engine

Returns:

The single Jasen instance

init

public void init()
          throws JasenException

Initialises the engine with the default configuration

Throws:

JasenException

See Also:

Jasen.init()

init

public void init(JasenConfigurationLoader loader)
          throws JasenException

Initialises the engine using the configuration loader provided

Parameters:

loader -

Throws:

JasenException

See Also:

Jasen.init(JasenConfigurationLoader)

init

public void init(String config)
          throws JasenException

Deprecated.

Initialises the engine with the configuration file specified

Parameters:

config - The absolute path to the configuration file

Throws:

JasenException

See Also:

Jasen.init(String)

init

public void init(InputStream in)
          throws JasenException

Deprecated.

Initialises the engine with the configuration document passed as a stream

Parameters:

in -

Throws:

JasenException

See Also:

Jasen.init(InputStream)

destroy

public void destroy()

Destroys the engine and all registered plugins

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm)
                     throws JasenException

Scans the given message.

All plugins will execute regardless of the probability (or computed total probability) discovered from any single plugin or combination thereof

Parameters:

mm - The MimeMessage to be scanned

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            float threshold)
                     throws JasenException

Scans the given message.

The threshold value indicates the value at which we know the message is spam without continuing

If the engine computes this threshold prior to all plugins executing, tests are stopped and the result is returned immediately

Parameters:

mm - The MimeMessage to be scanned

threshold - The marker above which scanning ceases

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, JasenMessage, float)

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            JasenMessage message)
                     throws JasenException

Scans the message without a threshold specified

Parameters:

mm - The MimeMessage to be scanned

message - A pre-parsed JasenMessage

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, JasenMessage, float)

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            JasenMessage message,
                            float threshold)
                     throws JasenException

Scans the given mime message using the already mime-parsed JasenMessage.

This implementation allows calling applications to implement their own JasenMessage by passing it to the scan engine.

Parameters:

mm - The MimeMessage to be scanned

message - A pre-parsed JasenMessage

threshold - The thresholds. If any one plugin yields a result >= threshold, scanning is ceased and the result returned immediately

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, float)

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            String[] ignored)
                     throws JasenException

Scans the given message.

All plugins will execute regardless of the probability (or computed total probability) discovered from any single plugin or combination thereof

Parameters:

mm - The MimeMessage to be scanned

ignored - A list of plugin names which will be ignored during the scan. May be null

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            float threshold,
                            String[] ignored)
                     throws JasenException

Scans the given message.

The threshold value indicates the value at which we know the message is spam without continuing

If the engine computes this threshold prior to all plugins executing, tests are stopped and the result is returned immediately

Parameters:

mm - The MimeMessage to be scanned

threshold - The marker above which scanning ceases

ignored - A list of plugin names which will be ignored during the scan. May be null

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, JasenMessage, float)

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            JasenMessage message,
                            String[] ignored)
                     throws JasenException

Scans the message without a threshold specified

Parameters:

mm - The MimeMessage to be scanned

message - A pre-parsed JasenMessage

ignored - A list of plugin names which will be ignored during the scan. May be null

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, JasenMessage, float)

scan

public JasenScanResult scan(javax.mail.internet.MimeMessage mm,
                            JasenMessage message,
                            float threshold,
                            String[] ignored)
                     throws JasenException

Scans the given mime message using the already mime-parsed JasenMessage.

This implementation allows calling applications to implement their own JasenMessage by passing it to the scan engine.

Parameters:

mm - The MimeMessage to be scanned

message - A pre-parsed JasenMessage

threshold - The thresholds. If any one plugin yields a result >= threshold, scanning is ceased and the result returned immediately

ignored - A list of plugin names which will be ignored during the scan. May be null

Returns:

The results of the scan as a JasenScanResult

Throws:

JasenException

See Also:

scan(MimeMessage, JasenMessage, float)

notifyScan

public void notifyScan()
                throws JasenException

Records the occurrance of a scan

Throws:

JasenException

notifyScanComplete

public void notifyScanComplete()
                        throws JasenException

Records the completion of a scan

Throws:

JasenException

notifyPendingUpdate

public boolean notifyPendingUpdate(JasenAutoUpdateParcel parcel)

Called by the AutoUpdateManager if there is an update pending to signal a pause in scanning

notifyUpdateComplete

public void notifyUpdateComplete(JasenAutoUpdateReport report)
                          throws JasenException

Called by the AutoUpdateManager when the update has completed

Parameters:

report - A report of the results of an update

Throws:

JasenException

notifyUpdateDownload

public void notifyUpdateDownload(long bytes)

isAlive

public boolean isAlive()

Returns true IFF the engine is initialised and ready for scans.

Returns:

True if the engine is alive, false otherwise.

getScanListener

public JasenScanListener getScanListener()

Gets the listener registered for scan events if one has been set.

Returns:

The current listener, or null if no listener has been set

setScanListener

public void setScanListener(JasenScanListener scanListener)

Sets the listener which will record scan events.

Parameters:

scanListener -

getAutoUpdateListener

public JasenAutoUpdateListener getAutoUpdateListener()

Gets the listener registered for auto update events if one has been set.

Returns:

The registered listener, or null if no listener has been set

setAutoUpdateListener

public void setAutoUpdateListener(JasenAutoUpdateListener autoUpdateListener)

Sets the listener which will record update completion events.

Parameters:

autoUpdateListener -

forceUpdate

public boolean forceUpdate()
                    throws JasenException

Forces the engine to run an update check

Returns:

If true, the force request was received and the engine is checking for updates. If false, the engine is either not running, or is already in the process of checking

Throws:

JasenException

getPlugins

public List getPlugins()

Returns a read-only list of the plugins registered in the engine.
The list does not allow modification. Any attempt to modify the list will result in an UnsupportedOperationException

Returns:

A list of PluginContainer objects containing the registered plugins

See Also:

PluginContainer