org.jasen
Class JasenScanner

java.lang.Object
  extended byorg.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