01: /*---------------------------------------------------------------------------*\
02: $Id: PreFeedDownloadPlugIn.java 7041 2007-09-09 01:04:47Z bmc $
03: ---------------------------------------------------------------------------
04: This software is released under a BSD-style license:
05:
06: Copyright (c) 2004-2007 Brian M. Clapper. All rights reserved.
07:
08: Redistribution and use in source and binary forms, with or without
09: modification, are permitted provided that the following conditions are
10: met:
11:
12: 1. Redistributions of source code must retain the above copyright notice,
13: this list of conditions and the following disclaimer.
14:
15: 2. The end-user documentation included with the redistribution, if any,
16: must include the following acknowlegement:
17:
18: "This product includes software developed by Brian M. Clapper
19: (bmc@clapper.org, http://www.clapper.org/bmc/). That software is
20: copyright (c) 2004-2007 Brian M. Clapper."
21:
22: Alternately, this acknowlegement may appear in the software itself,
23: if wherever such third-party acknowlegements normally appear.
24:
25: 3. Neither the names "clapper.org", "curn", nor any of the names of the
26: project contributors may be used to endorse or promote products
27: derived from this software without prior written permission. For
28: written permission, please contact bmc@clapper.org.
29:
30: 4. Products derived from this software may not be called "curn", nor may
31: "clapper.org" appear in their names without prior written permission
32: of Brian M. Clapper.
33:
34: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
35: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
36: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
37: NO EVENT SHALL BRIAN M. CLAPPER BE LIABLE FOR ANY DIRECT, INDIRECT,
38: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
39: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
40: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
41: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
42: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
43: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44: \*---------------------------------------------------------------------------*/
45:
46: package org.clapper.curn;
47:
48: import java.net.URLConnection;
49:
50: /**
51: * This interface defines the methods that must be supported by plug-ins
52: * that wish to be notified just before <i>curn</i> downloads a feed.
53: *
54: * @see PlugIn
55: * @see MetaPlugIn
56: * @see PostFeedDownloadPlugIn
57: * @see PostFeedParsePlugIn
58: * @see Curn
59: *
60: * @version <tt>$Revision: 7041 $</tt>
61: */
62: public interface PreFeedDownloadPlugIn extends PlugIn {
63: /*----------------------------------------------------------------------*\
64: Public Methods
65: \*----------------------------------------------------------------------*/
66:
67: /**
68: * <p>Called just before a feed is downloaded. This method can return
69: * <tt>false</tt> to signal <i>curn</i> that the feed should be
70: * skipped. The plug-in method can also set values on the
71: * <tt>URLConnection</tt> used to download the plug-in, via
72: * <tt>URL.setRequestProperty()</tt>. (Note that <i>all</i> URLs, even
73: * <tt>file:</tt> URLs, are passed into this method. Setting a request
74: * property on the <tt>URLConnection</tt> object for a <tt>file:</tt>
75: * URL will have no effect--though it isn't specifically harmful.)</p>
76: *
77: * <p>Possible uses for a pre-feed download plug-in include:</p>
78: *
79: * <ul>
80: * <li>filtering on feed URL to prevent downloading non-matching feeds
81: * <li>changing the default User-Agent value
82: * <li>setting a non-standard HTTP header field
83: * </ul>
84: *
85: * @param feedInfo the {@link FeedInfo} object for the feed to be
86: * downloaded
87: * @param urlConn the <tt>java.net.URLConnection</tt> object that will
88: * be used to download the feed's XML.
89: *
90: * @return <tt>true</tt> if <i>curn</i> should continue to process the
91: * feed, <tt>false</tt> to skip the feed
92: *
93: * @throws CurnException on error
94: *
95: * @see FeedInfo
96: */
97: public boolean runPreFeedDownloadPlugIn(FeedInfo feedInfo,
98: URLConnection urlConn) throws CurnException;
99: }
|