001: /*---------------------------------------------------------------------------*\
002: $Id: PlugIn.java 7041 2007-09-09 01:04:47Z bmc $
003: ---------------------------------------------------------------------------
004: This software is released under a BSD-style license:
005:
006: Copyright (c) 2004-2007 Brian M. Clapper. All rights reserved.
007:
008: Redistribution and use in source and binary forms, with or without
009: modification, are permitted provided that the following conditions are
010: met:
011:
012: 1. Redistributions of source code must retain the above copyright notice,
013: this list of conditions and the following disclaimer.
014:
015: 2. The end-user documentation included with the redistribution, if any,
016: must include the following acknowlegement:
017:
018: "This product includes software developed by Brian M. Clapper
019: (bmc@clapper.org, http://www.clapper.org/bmc/). That software is
020: copyright (c) 2004-2007 Brian M. Clapper."
021:
022: Alternately, this acknowlegement may appear in the software itself,
023: if wherever such third-party acknowlegements normally appear.
024:
025: 3. Neither the names "clapper.org", "curn", nor any of the names of the
026: project contributors may be used to endorse or promote products
027: derived from this software without prior written permission. For
028: written permission, please contact bmc@clapper.org.
029:
030: 4. Products derived from this software may not be called "curn", nor may
031: "clapper.org" appear in their names without prior written permission
032: of Brian M. Clapper.
033:
034: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
035: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
036: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
037: NO EVENT SHALL BRIAN M. CLAPPER BE LIABLE FOR ANY DIRECT, INDIRECT,
038: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
039: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
040: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
041: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
042: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
043: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
044: \*---------------------------------------------------------------------------*/
045:
046: package org.clapper.curn;
047:
048: import org.clapper.curn.parser.RSSChannel;
049:
050: /**
051: * <p>This interface defines the methods that must be supported by a class
052: * that is to be plugged into <i>curn</i> as a generalized plug-in.
053: * <i>curn</i> plug-ins are invoked at various phases of <i>curn</i>
054: * execution.</p>
055: *
056: * <p>Each plug-in phase is represented by its own Java interface, and
057: * each interface has exactly one method. A plug-in that intercepts
058: * multiple <i>curn</i> processing phases must implement the interfaces for
059: * each of the phases. Here are the plug-in phases, in execution order.</p>
060: *
061: * <table border="1" align="center">
062: * <tr valign="top">
063: * <th align="left">Plug-in interface</th>
064: * <th align="left">Plug-in method</th>
065: * <th align="left">Description</th>
066: * </tr>
067: *
068: * <tr valign="top">
069: * <td align="left">{@link StartupPlugIn}</td>
070: * <td align="left">{@link StartupPlugIn#runStartupPlugIn runStartupPlugIn()}</td>
071: * <td>Called immediately after <i>curn</i> has started, but before it has
072: * loaded its configuration file or its cache. Intercepting this phase
073: * is useful if a plug-in needs to perform initialization.</td>
074: * </tr>
075: *
076: * <tr valign="top">
077: * <td align="left">{@link MainConfigItemPlugIn}</td>
078: * <td align="left">{@link MainConfigItemPlugIn#runMainConfigItemPlugIn runMainConfigItemPlugIn()}</td>
079: * <td>Called immediately after <i>curn</i> has read and processed a
080: * configuration item in the main <tt>[curn]</tt> configuration
081: * section. All configuration items are passed, one by one, to each
082: * loaded plug-in. If a plug-in class is not interested in a
083: * particular configuration item, its
084: * <tt>runMainConfigItemPlugIn()</tt> method should simply return
085: * without doing anything. Note that some configuration items may
086: * simply be variable assignment; there's no real way to distinguish a
087: * variable assignment from a blessed configuration item.</td>
088: *
089: * </tr>
090: *
091: * <tr valign="top">
092: * <td align="left">{@link FeedConfigItemPlugIn}</td>
093: * <td align="left">{@link FeedConfigItemPlugIn#runFeedConfigItemPlugIn runFeedConfigItemPlugIn()}</td>
094: * <td>Called immediately after <i>curn</i> has read and processed a
095: * configuration item in a "Feed" configuration section. All
096: * configuration items are passed, one by one, to each loaded plug-in.
097: * If a plug-in class is not interested in a particular configuration
098: * item, its <tt>runFeedConfigItemPlugIn()</tt> method should simply
099: * return without doing anything. Note that some configuration items
100: * may simply be variable assignment; there's no real way to
101: * distinguish a variable assignment from a blessed configuration
102: * item.</td>
103: * </tr>
104: *
105: * <tr valign="top">
106: * <td align="left">{@link OutputHandlerConfigItemPlugIn}</td>
107: * <td align="left">{@link OutputHandlerConfigItemPlugIn#runOutputHandlerConfigItemPlugIn runOutputHandlerConfigItemPlugIn()}</td>
108: * <td>Called immediately after <i>curn</i> has read and processed a
109: * configuration item in an "OutputHandler" configuration section. All
110: * configuration items are passed, one by one, to each loaded plug-in.
111: * If a plug-in class is not interested in a particular configuration
112: * item, its <tt>runOutputHandlerConfigItemPlugIn()</tt> method should
113: * simply return without doing anything. Note that some configuration
114: * items may simply be variable assignment; there's no real way to
115: * distinguish a variable assignment from a blessed configuration
116: * item.</td>
117: * </tr>
118: *
119: * <tr valign="top">
120: * <td align="left">{@link UnknownSectionConfigItemPlugIn}</td>
121: * <td align="left">{@link UnknownSectionConfigItemPlugIn#runUnknownSectionConfigItemPlugIn runUnknownSectionConfigItemPlugIn()}</td>
122: * <td>Called immediately after <i>curn</i> has read and processed a
123: * configuration item in an unknown configuration section. All
124: * configuration items are passed, one by one, to each loaded plug-in.
125: * If a plug-in class is not interested in a particular configuration
126: * item, its <tt>runUnknownSectionConfigItemPlugIn()</tt> method should
127: * simply return without doing anything. Note that some configuration
128: * items may simply be variable assignment; there's no real way to
129: * distinguish a variable assignment from a blessed configuration
130: * item.</td>
131: * </tr>
132: *
133: * <tr valign="top">
134: * <td align="left">{@link PostConfigPlugIn}</td>
135: * <td align="left">{@link PostConfigPlugIn#runPostConfigPlugIn runPostConfigPlugIn()}</td>
136: * <td>Called after the entire configuration has been read and parsed, but
137: * before any feeds are processed. Intercepting this event is useful
138: * for plug-ins that want to adjust the configuration. For instance,
139: * the <i>curn</i> command-line wrapper intercepts this plug-in event
140: * so it can adjust the configuration to account for command line
141: * options.</td>
142: * </tr>
143: *
144: * <tr valign="top">
145: * <td align="left">{@link CacheLoadedPlugIn}</td>
146: * <td align="left">{@link CacheLoadedPlugIn#runCacheLoadedPlugIn runCacheLoadedPlugIn()}</td>
147: * <td>Called after the <i>curn</i> cache has been read (and after any
148: * expired entries have been purged), but before any feeds are processed.
149: * </td>
150: * </tr>
151: *
152: * <tr valign="top">
153: * <td align="left">{@link PreFeedDownloadPlugIn}</td>
154: * <td align="left">{@link PreFeedDownloadPlugIn#runPreFeedDownloadPlugIn runPreFeedDownloadPlugIn()}</td>
155: * <td>Called just before a feed is downloaded. This method can return
156: * <tt>false</tt> to signal <i>curn</i> that the feed should be
157: * skipped. The plug-in method can also set values on the
158: * <tt>URLConnection</tt> used to download the plug-in, via
159: * <tt>URL.setRequestProperty()</tt>. (Note that <i>all</i> URLs, even
160: * <tt>file:</tt> URLs, are passed into this method. Setting a request
161: * property on the <tt>URLConnection</tt> object for a <tt>file:</tt>
162: * URL will have no effect--though it isn't specifically harmful.)</p>
163: *
164: * <p>Possible uses for a pre-feed download plug-in include:</p>
165: *
166: * <ul>
167: * <li>filtering on feed URL to prevent downloading non-matching feeds
168: * <li>changing the default User-Agent value
169: * <li>setting a non-standard HTTP header field
170: * </ul>
171: * </td>
172: * </tr>
173: *
174: * <tr valign="top">
175: * <td align="left">{@link PostFeedDownloadPlugIn}</td>
176: * <td align="left">{@link PostFeedDownloadPlugIn#runPostFeedDownloadPlugIn runPostFeedDownloadPlugIn()}</td>
177: * <td> Called immediately after a feed is downloaded. This method can
178: * return <tt>false</tt> to signal <i>curn</i> that the feed should be
179: * skipped. For instance, a plug-in that filters on the unparsed XML
180: * feed content could use this method to weed out non-matching feeds
181: * before they are downloaded.
182: * </td>
183: * </tr>
184: *
185: * <tr valign="top">
186: * <td align="left">{@link PostFeedParsePlugIn}</td>
187: * <td align="left">{@link PostFeedParsePlugIn#runPostFeedParsePlugIn runPostFeedParsePlugIn()}</td>
188: * <td>Called immediately after a feed is parsed, but before it is
189: * otherwise processed. A post-feed parse plug-in has access to the
190: * <i>parsed</i> RSS feed data, via an {@link RSSChannel} object. This
191: * method can return <tt>false</tt> to signal <i>curn</i> that the
192: * feed should be skipped. For instance, a plug-in that filters on the
193: * parsed feed data could use this method to weed out non-matching
194: * feeds before they are downloaded. Similarly, a plug-in that edits
195: * the parsed data (removing or editing individual items, for
196: * instance) could use method to do so.</td>
197: * </tr>
198: *
199: * <tr valign="top">
200: * <td align="left">{@link PreFeedOutputPlugIn}</td>
201: * <td align="left">{@link PreFeedOutputPlugIn#runPreFeedOutputPlugIn runPreFeedOutputPlugIn()}</td>
202: * <td>Called immediately before a parsed feed is passed to an output
203: * handler. A pre-feed output plug-in cannot affect the feed's
204: * processing. (The time to stop the processing of a feed is in one of
205: * the other, preceding phases.) This method will be called multiple
206: * times for each feed if there are multiple output handlers.</td>
207: * </tr>
208: *
209: * <tr valign="top">
210: * <td align="left">{@link PostFeedOutputPlugIn}</td>
211: * <td align="left">{@link PostFeedOutputPlugIn#runPostFeedOutputPlugIn runPostFeedOutputPlugIn()}</td>
212: * <td>Called immediately after a parsed feed is passed to an output
213: * handler. A post-feed output plug-in cannot affect the feed's
214: * processing. (The time to stop the processing of a feed is in one of
215: * the other, preceding phases.) This method will be called multiple
216: * times for each feed if there are multiple output handlers.</td>
217: * </tr>
218: *
219: * <tr valign="top">
220: * <td align="left">{@link PostOutputHandlerFlushPlugIn}</td>
221: * <td align="left">{@link PostOutputHandlerFlushPlugIn#runPostOutputHandlerFlushPlugIn runPostOutputHandlerFlushPlugIn()}</td>
222: * <td>Called immediately after an output handler is flushed (i.e., after
223: * it has been called to process all feeds and its output has been
224: * written to a temporary file), but before that output is
225: * displayed, emailed, etc.
226: * </td>
227: * </tr>
228: *
229: * <tr valign="top">
230: * <td align="left">{@link PostOutputPlugIn}</td>
231: * <td align="left">{@link PostOutputPlugIn#runPostOutputPlugIn runPostOutputPlugIn()}</td>
232: * <td>Called after <i>curn</i> has flush <i>all</i> output handlers. A
233: * post-output plug-in is a useful place to consolidate the output from
234: * all output handlers. For instance, such a plug-in might pack all the
235: * output into a zip file, or email it.</td>
236: * </td>
237: * </tr>
238: *
239: * <tr valign="top">
240: * <td align="left">{@link PreCacheSavePlugIn}</td>
241: * <td align="left">{@link PreCacheSavePlugIn#runPreCacheSavePlugIn runPreCacheSavePlugIn()}</td>
242: * <td>Called right before the <i>curn</i> cache is to be saved. A plug-in
243: * might choose to edit the cache at this point.</td>
244: * </tr>
245: *
246: * <tr valign="top">
247: * <td align="left">{@link ShutdownPlugIn}</td>
248: * <td align="left">{@link ShutdownPlugIn#runShutdownPlugIn runShutdownPlugIn()}</td>
249: * <td> Called just before <i>curn</i> gets ready to exit. This method
250: * allows plug-ins to perform any clean-up they require.</td>
251: * </tr>
252: * </table>
253: *
254: * @version <tt>$Revision: 7041 $</tt>
255: */
256: public interface PlugIn {
257: /*----------------------------------------------------------------------*\
258: Public Methods
259: \*----------------------------------------------------------------------*/
260:
261: /**
262: * Get a displayable name for the plug-in.
263: *
264: * @return the name
265: */
266: public String getPlugInName();
267:
268: /**
269: * Get the sort key for this plug-in.
270: *
271: * @return the sort key string.
272: */
273: public String getPlugInSortKey();
274:
275: /**
276: * Initialize the plug-in. This method is called before any of the
277: * plug-in methods are called.
278: *
279: * @throws CurnException on error
280: */
281: public void initPlugIn() throws CurnException;
282: }
|