org.clapper.curn
Class MetaPlugIn

java.lang.Object
  org.clapper.curn.MetaPlugIn

All Implemented Interfaces:

CacheLoadedPlugIn, FeedConfigItemPlugIn, MainConfigItemPlugIn, OutputHandlerConfigItemPlugIn, PlugIn, PostConfigPlugIn, PostFeedDownloadPlugIn, PostFeedOutputPlugIn, PostFeedParsePlugIn, PostOutputHandlerFlushPlugIn, PostOutputPlugIn, PreCacheSavePlugIn, PreFeedDownloadPlugIn, PreFeedOutputPlugIn, ShutdownPlugIn, StartupPlugIn, UnknownSectionConfigItemPlugIn

public class MetaPlugIn
extends java.lang.Object
implements CacheLoadedPlugIn, FeedConfigItemPlugIn, MainConfigItemPlugIn, OutputHandlerConfigItemPlugIn, PostConfigPlugIn, PostFeedDownloadPlugIn, PostFeedOutputPlugIn, PostFeedParsePlugIn, PostOutputHandlerFlushPlugIn, PreCacheSavePlugIn, PreFeedDownloadPlugIn, PreFeedOutputPlugIn, PostOutputPlugIn, ShutdownPlugIn, StartupPlugIn, UnknownSectionConfigItemPlugIn

A MetaPlugIn object is basically a plug-in that contains all the loaded plug-ins. It's a singleton that makes it easier for curn to invoke the various loaded plugins. It is not used outside of curn. The MetaPlugIn singleton object is loaded by an instance of the PlugInManager class.

Version:

$Revision: 6491 $

See Also:

PlugIn, PlugInManager, CacheLoadedPlugIn, FeedConfigItemPlugIn, MainConfigItemPlugIn, OutputHandlerConfigItemPlugIn, PostConfigPlugIn, PostFeedDownloadPlugIn, PostFeedOutputPlugIn, PostFeedParsePlugIn, PostOutputHandlerFlushPlugIn, PreCacheSavePlugIn, PreFeedDownloadPlugIn, PreFeedOutputPlugIn, ShutdownPlugIn, StartupPlugIn, UnknownSectionConfigItemPlugIn, Curn

Method Summary

void	addPlugIn(PlugIn plugIn) Add a plug-in to the list of plug-ins wrapped in this object.
static MetaPlugIn	getMetaPlugIn() Get the MetaPlugIn singleton.
java.lang.String	getPlugInName() Get a displayable name for the plug-in.
java.lang.String	getPlugInSortKey() Get the sort key for this plug-in.
void	initPlugIn() Initialize the plug-in.
void	registerPersistentDataClientPlugIns(DataPersister dataPersister) Find all plug-ins that implement the PersistentDataClient interface and register them with the specified DataPersister.
void	runCacheLoadedPlugIn(FeedCache cache) Called after the curn cache has been read (and after any expired entries have been purged), but before any feeds are processed.
boolean	runFeedConfigItemPlugIn(java.lang.String sectionName, java.lang.String paramName, CurnConfig config, FeedInfo feedInfo) Called immediately after curn has read and processed a configuration item in a "feed" configuration section.
void	runMainConfigItemPlugIn(java.lang.String sectionName, java.lang.String paramName, CurnConfig config) Called immediately after curn has read and processed a configuration item in the main [curn] configuration section.
boolean	runOutputHandlerConfigItemPlugIn(java.lang.String sectionName, java.lang.String paramName, CurnConfig config, ConfiguredOutputHandler handler) Called immediately after curn has read and processed a configuration item in an output handler configuration section.
void	runPostConfigPlugIn(CurnConfig config) Called after the entire configuration has been read and parsed, but before any feeds are processed.
boolean	runPostFeedDownloadPlugIn(FeedInfo feedInfo, java.io.File feedDataFile, java.lang.String encoding) Called immediately after a feed is downloaded.
void	runPostFeedOutputPlugIn(FeedInfo feedInfo, OutputHandler outputHandler) Called immediately after a parsed feed is passed to an output handler.
boolean	runPostFeedParsePlugIn(FeedInfo feedInfo, RSSChannel channel) Called immediately after a feed is parsed, but before it is otherwise processed.
boolean	runPostOutputHandlerFlushPlugIn(OutputHandler outputHandler) Called immediately after an output handler is flushed (i.e., after it has been called to process all feeds and its output has been written to a temporary file), but before that output is displayed, emailed, etc.
void	runPostOutputPlugIn(java.util.Collection<OutputHandler> outputHandlers) Called after curn has flushed all output handlers.
void	runPreCacheSavePlugIn(FeedCache cache) Called right before the curn cache is to be saved.
boolean	runPreFeedDownloadPlugIn(FeedInfo feedInfo, java.net.URLConnection urlConn) Called just before a feed is downloaded.
void	runPreFeedOutputPlugIn(FeedInfo feedInfo, RSSChannel channel, OutputHandler outputHandler) Called immediately before a parsed feed is passed to an output handler.
void	runShutdownPlugIn() Called just before curn gets ready to exit.
void	runStartupPlugIn() Called immediately after curn has started, but before it has loaded its configuration file or its cache.
void	runUnknownSectionConfigItemPlugIn(java.lang.String sectionName, java.lang.String paramName, CurnConfig config) Called immediately after curn has read and processed a configuration item in an unknown configuration section.

Methods inherited from class java.lang.Object

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

Method Detail

getMetaPlugIn

public static MetaPlugIn getMetaPlugIn()

Get the MetaPlugIn singleton.

Returns:

the MetaPlugIn singleton

Throws:

CurnException - on error

addPlugIn

public void addPlugIn(PlugIn plugIn)

Add a plug-in to the list of plug-ins wrapped in this object. This method is only intended for use by the PlugInManager.

Parameters:

plugIn - the PlugIn to add

registerPersistentDataClientPlugIns

public void registerPersistentDataClientPlugIns(DataPersister dataPersister)

Find all plug-ins that implement the PersistentDataClient interface and register them with the specified DataPersister.

Parameters:

dataPersister - the DataPersister

getPlugInName

public java.lang.String getPlugInName()

Description copied from interface: PlugIn

Get a displayable name for the plug-in.

Specified by:

getPlugInName in interface PlugIn

Returns:

the name

getPlugInSortKey

public java.lang.String getPlugInSortKey()

Description copied from interface: PlugIn

Get the sort key for this plug-in.

Specified by:

getPlugInSortKey in interface PlugIn

Returns:

the sort key string.

initPlugIn

public void initPlugIn()
                throws CurnException

Description copied from interface: PlugIn

Initialize the plug-in. This method is called before any of the plug-in methods are called.

Specified by:

initPlugIn in interface PlugIn

Throws:

CurnException - on error

runStartupPlugIn

public void runStartupPlugIn()
                      throws CurnException

Description copied from interface: StartupPlugIn

Called immediately after curn has started, but before it has loaded its configuration file or its cache. This method can be used for plug-in initialization.

Specified by:

runStartupPlugIn in interface StartupPlugIn

Throws:

CurnException - on error

runMainConfigItemPlugIn

public void runMainConfigItemPlugIn(java.lang.String sectionName,
                                    java.lang.String paramName,
                                    CurnConfig config)
                             throws CurnException

Description copied from interface: MainConfigItemPlugIn

Called immediately after curn has read and processed a configuration item in the main [curn] configuration section. All configuration items are passed, one by one, to each loaded plug-in. If a plug-in class is not interested in a particular configuration item, this method should simply return without doing anything. Note that some configuration items may simply be variable assignment; there's no real way to distinguish a variable assignment from a blessed configuration item.

Specified by:

runMainConfigItemPlugIn in interface MainConfigItemPlugIn

Parameters:

sectionName - the name of the configuration section where the item was found

paramName - the name of the parameter

config - the CurnConfig object

Throws:

CurnException - on error

See Also:

CurnConfig

runFeedConfigItemPlugIn

public boolean runFeedConfigItemPlugIn(java.lang.String sectionName,
                                       java.lang.String paramName,
                                       CurnConfig config,
                                       FeedInfo feedInfo)
                                throws CurnException

Description copied from interface: FeedConfigItemPlugIn

Called immediately after curn has read and processed a configuration item in a "feed" configuration section. All configuration items are passed, one by one, to each loaded plug-in. If a plug-in class is not interested in a particular configuration item, this method should simply return without doing anything. Note that some configuration items may simply be variable assignment; there's no real way to distinguish a variable assignment from a blessed configuration item.

Specified by:

runFeedConfigItemPlugIn in interface FeedConfigItemPlugIn

Parameters:

sectionName - the name of the configuration section where the item was found

paramName - the name of the parameter

config - the CurnConfig object

feedInfo - partially complete FeedInfo object for the feed. The URL is guaranteed to be present, but no other fields are.

Returns:

true to continue processing the feed, false to skip it

Throws:

CurnException - on error

See Also:

CurnConfig, FeedInfo, FeedInfo.getURL()

runOutputHandlerConfigItemPlugIn

public boolean runOutputHandlerConfigItemPlugIn(java.lang.String sectionName,
                                                java.lang.String paramName,
                                                CurnConfig config,
                                                ConfiguredOutputHandler handler)
                                         throws CurnException

Description copied from interface: OutputHandlerConfigItemPlugIn

Called immediately after curn has read and processed a configuration item in an output handler configuration section. All configuration items are passed, one by one, to each loaded plug-in. If a plug-in class is not interested in a particular configuration item, this method should simply return without doing anything. Note that some configuration items may simply be variable assignment; there's no real way to distinguish a variable assignment from a blessed configuration item.

Specified by:

runOutputHandlerConfigItemPlugIn in interface OutputHandlerConfigItemPlugIn

Parameters:

sectionName - the name of the configuration section where the item was found

paramName - the name of the parameter

config - the CurnConfig object

handler - partially complete ConfiguredOutputHandler object. The class name is guaranteed to be set, but the other fields may not be.

Returns:

true to continue processing the handler, false to skip it

Throws:

CurnException - on error

See Also:

CurnConfig, ConfiguredOutputHandler

runUnknownSectionConfigItemPlugIn

public void runUnknownSectionConfigItemPlugIn(java.lang.String sectionName,
                                              java.lang.String paramName,
                                              CurnConfig config)
                                       throws CurnException

Description copied from interface: UnknownSectionConfigItemPlugIn

Called immediately after curn has read and processed a configuration item in an unknown configuration section. All configuration items are passed, one by one, to each loaded plug-in. If a plug-in class is not interested in a particular configuration item, this method should simply return without doing anything. Note that some configuration items may simply be variable assignment; there's no real way to distinguish a variable assignment from a blessed configuration item.

Specified by:

runUnknownSectionConfigItemPlugIn in interface UnknownSectionConfigItemPlugIn

Parameters:

sectionName - the name of the configuration section where the item was found

paramName - the name of the parameter

config - the CurnConfig object

Throws:

CurnException - on error

See Also:

CurnConfig, FeedInfo, FeedInfo.getURL()

runPostConfigPlugIn

public void runPostConfigPlugIn(CurnConfig config)
                         throws CurnException

Description copied from interface: PostConfigPlugIn

Called after the entire configuration has been read and parsed, but before any feeds are processed. Intercepting this event is useful for plug-ins that want to adjust the configuration. For instance, the curn command-line wrapper intercepts this plug-in event so it can adjust the configuration to account for command line options.

Specified by:

runPostConfigPlugIn in interface PostConfigPlugIn

Parameters:

config - the parsed CurnConfig object

Throws:

CurnException - on error

See Also:

CurnConfig

runCacheLoadedPlugIn

public void runCacheLoadedPlugIn(FeedCache cache)
                          throws CurnException

Description copied from interface: CacheLoadedPlugIn

Called after the curn cache has been read (and after any expired entries have been purged), but before any feeds are processed.

Specified by:

runCacheLoadedPlugIn in interface CacheLoadedPlugIn

Parameters:

cache - the loaded FeedCache object

Throws:

CurnException - on error

runPreFeedDownloadPlugIn

public boolean runPreFeedDownloadPlugIn(FeedInfo feedInfo,
                                        java.net.URLConnection urlConn)
                                 throws CurnException

Description copied from interface: PreFeedDownloadPlugIn

Called just before a feed is downloaded. This method can return false to signal curn that the feed should be skipped. The plug-in method can also set values on the URLConnection used to download the plug-in, via URL.setRequestProperty(). (Note that all URLs, even file: URLs, are passed into this method. Setting a request property on the URLConnection object for a file: URL will have no effect--though it isn't specifically harmful.)

Possible uses for a pre-feed download plug-in include:

• filtering on feed URL to prevent downloading non-matching feeds
• changing the default User-Agent value
• setting a non-standard HTTP header field

Specified by:

runPreFeedDownloadPlugIn in interface PreFeedDownloadPlugIn

Parameters:

feedInfo - the FeedInfo object for the feed to be downloaded

urlConn - the java.net.URLConnection object that will be used to download the feed's XML.

Returns:

true if curn should continue to process the feed, false to skip the feed

Throws:

CurnException - on error

See Also:

FeedInfo

runPostFeedDownloadPlugIn

public boolean runPostFeedDownloadPlugIn(FeedInfo feedInfo,
                                         java.io.File feedDataFile,
                                         java.lang.String encoding)
                                  throws CurnException

Description copied from interface: PostFeedDownloadPlugIn

Called immediately after a feed is downloaded. This method can return false to signal curn that the feed should be skipped. For instance, a plug-in that filters on the unparsed XML feed content could use this method to weed out non-matching feeds before they are downloaded.

Specified by:

runPostFeedDownloadPlugIn in interface PostFeedDownloadPlugIn

Parameters:

feedInfo - the FeedInfo object for the feed that has been downloaded

feedDataFile - the file containing the downloaded, unparsed feed XML. curn may delete this file after all plug-ins are notified!

encoding - the encoding used to store the data in the file, or null for the default

Returns:

true if curn should continue to process the feed, false to skip the feed. A return value of false aborts all further processing on the feed. In particular, curn will not pass the feed along to other plug-ins that have yet to be notified of this event.

Throws:

CurnException - on error

See Also:

FeedInfo

runPostFeedParsePlugIn

public boolean runPostFeedParsePlugIn(FeedInfo feedInfo,
                                      RSSChannel channel)
                               throws CurnException

Description copied from interface: PostFeedParsePlugIn

Called immediately after a feed is parsed, but before it is otherwise processed. A post-feed parse plug-in has access to the parsed RSS feed data, via an RSSChannel object. This method can return false to signal curn that the feed should be skipped. For instance, a plug-in that filters on the parsed feed data could use this method to weed out non-matching feeds before they are downloaded. Similarly, a plug-in that edits the parsed data (removing or editing individual items, for instance) could use method to do so.

Specified by:

runPostFeedParsePlugIn in interface PostFeedParsePlugIn

Parameters:

feedInfo - the FeedInfo object for the feed that has been downloaded and parsed.

channel - the parsed channel data

Returns:

true if curn should continue to process the feed, false to skip the feed. A return value of false aborts all further processing on the feed. In particular, curn will not pass the feed along to other plug-ins that have yet to be notified of this event.

Throws:

CurnException - on error

See Also:

RSSChannel, FeedInfo

runPreFeedOutputPlugIn

public void runPreFeedOutputPlugIn(FeedInfo feedInfo,
                                   RSSChannel channel,
                                   OutputHandler outputHandler)
                            throws CurnException

Description copied from interface: PreFeedOutputPlugIn

Called immediately before a parsed feed is passed to an output handler. This method cannot affect the feed's processing. (The time to stop the processing of a feed is in one of the other, preceding phases.) This method will be called multiple times for each feed if there are multiple output handlers.

Specified by:

runPreFeedOutputPlugIn in interface PreFeedOutputPlugIn

Parameters:

feedInfo - the FeedInfo object for the feed that has been downloaded and parsed.

channel - the parsed channel data. The plug-in is free to edit this data; it's receiving a copy that's specific to the output handler.

outputHandler - the OutputHandler that is about to be called. This object is read-only.

Throws:

CurnException - on error

See Also:

RSSChannel, FeedInfo

runPostFeedOutputPlugIn

public void runPostFeedOutputPlugIn(FeedInfo feedInfo,
                                    OutputHandler outputHandler)
                             throws CurnException

Description copied from interface: PostFeedOutputPlugIn

Called immediately after a parsed feed is passed to an output handler. This method cannot affect the feed's processing. (The time to stop the processing of a feed is in one of the other, preceding phases.) This method will be called multiple times for each feed if there are multiple output handlers.

Specified by:

runPostFeedOutputPlugIn in interface PostFeedOutputPlugIn

Parameters:

feedInfo - the FeedInfo object for the feed that has been downloaded and parsed.

outputHandler - the OutputHandler that is about to be called. This object is read-only.

Throws:

CurnException - on error

See Also:

FeedInfo, OutputHandler

runPostOutputHandlerFlushPlugIn

public boolean runPostOutputHandlerFlushPlugIn(OutputHandler outputHandler)
                                        throws CurnException

Description copied from interface: PostOutputHandlerFlushPlugIn

Called immediately after an output handler is flushed (i.e., after it has been called to process all feeds and its output has been written to a temporary file), but before that output is displayed, emailed, etc.

Specified by:

runPostOutputHandlerFlushPlugIn in interface PostOutputHandlerFlushPlugIn

Parameters:

outputHandler - the OutputHandler that is about to be called. This object is read-only.

Returns:

true if curn should process the output, false to skip the output from the handler.

Throws:

CurnException - on error

See Also:

OutputHandler

runPostOutputPlugIn

public void runPostOutputPlugIn(java.util.Collection<OutputHandler> outputHandlers)
                         throws CurnException

Description copied from interface: PostOutputPlugIn

Called after curn has flushed all output handlers. A post-output plug-in is a useful place to consolidate the output from all output handlers. For instance, such a plug-in might pack all the output into a zip file, or email it.

Specified by:

runPostOutputPlugIn in interface PostOutputPlugIn

Parameters:

outputHandlers - a Collection of the OutputHandler objects (useful for obtaining the output files, for instance).

Throws:

CurnException - on error

See Also:

OutputHandler

runPreCacheSavePlugIn

public void runPreCacheSavePlugIn(FeedCache cache)
                           throws CurnException

Description copied from interface: PreCacheSavePlugIn

Called right before the curn cache is to be saved. A plug-in might choose to edit the cache at this point.

Specified by:

runPreCacheSavePlugIn in interface PreCacheSavePlugIn

Parameters:

cache - the FeedCache object

Throws:

CurnException - on error

runShutdownPlugIn

public void runShutdownPlugIn()
                       throws CurnException

Description copied from interface: ShutdownPlugIn

Called just before curn gets ready to exit. This method allows plug-ins to perform any clean-up they require.

Specified by:

runShutdownPlugIn in interface ShutdownPlugIn

Throws:

CurnException - on error