001: /*---------------------------------------------------------------------------*\
002: $Id: OutputHandler.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 java.io.File;
049:
050: import org.clapper.curn.parser.RSSChannel;
051:
052: import org.clapper.util.config.ConfigurationException;
053:
054: /**
055: * This interface defines the methods that must be supported by a class
056: * that is to be plugged into <i>curn</i> as an output handler. It is
057: * responsible for writing any channel headers, item headers, and item
058: * information. It will only be called with items that should be displayed;
059: * any channel items that are cached and should be skipped are not handed
060: * to the output handler. <i>curn</i> models output in this manner to make
061: * it simpler to substitute different kinds of output handlers.
062: *
063: * @see Curn
064: * @see OutputHandlerFactory
065: * @see org.clapper.curn.parser.RSSChannel
066: * @see org.clapper.curn.parser.RSSItem
067: *
068: * @version <tt>$Revision: 7041 $</tt>
069: */
070: public interface OutputHandler {
071: /*----------------------------------------------------------------------*\
072: Constants
073: \*----------------------------------------------------------------------*/
074:
075: /*----------------------------------------------------------------------*\
076: Public Methods
077: \*----------------------------------------------------------------------*/
078:
079: /**
080: * Get the name of this output handler. The name must be unique.
081: *
082: * @return the name
083: */
084: public String getName();
085:
086: /**
087: * Set the name of this output handler. Called by <i>curn</i>.
088: *
089: * @param name the name
090: *
091: * @throws CurnException on error
092: */
093: public void setName(String name) throws CurnException;
094:
095: /**
096: * Initializes the output handler for another set of RSS channels.
097: *
098: * @param config the parsed <i>curn</i> configuration data. The
099: * output handler is responsible for retrieving its
100: * own parameters from the configuration, by calling
101: * <tt>config.getOutputHandlerSpecificVariables()</tt>
102: * @param cfgHandler the <tt>ConfiguredOutputHandler</tt> wrapper
103: * containing this object; the wrapper has some useful
104: * metadata, such as the object's configuration section
105: * name and extra variables.
106: *
107: * @throws ConfigurationException configuration error
108: * @throws CurnException some other initialization error
109: *
110: * @see CurnConfig
111: * @see ConfiguredOutputHandler
112: */
113: public void init(CurnConfig config,
114: ConfiguredOutputHandler cfgHandler)
115: throws ConfigurationException, CurnException;
116:
117: /**
118: * Make a copy of the output handler.
119: *
120: * @return a clean, initialized copy of the output handler
121: *
122: * @throws CurnException on error
123: */
124: public OutputHandler makeCopy() throws CurnException;
125:
126: /**
127: * Display the list of <tt>RSSItem</tt> news items to whatever output
128: * is defined for the underlying class. Output should be written to the
129: * <tt>PrintWriter</tt> that was passed to the {@link #init init()} method.
130: *
131: * @param channel The parsed channel data. <i>curn</i> will pass a
132: * copy of the actual {@link RSSChannel} object, so the
133: * output handler can edit its contents, if necessary,
134: * without affecting other output handlers.
135: * @param feedInfo The feed.
136: *
137: * @throws CurnException unable to write output
138: */
139: public void displayChannel(RSSChannel channel, FeedInfo feedInfo)
140: throws CurnException;
141:
142: /**
143: * Flush any buffered-up output and close the underlying output
144: * stream(s), if any. <i>curn</i> calls this method once, after calling
145: * <tt>displayChannelItems()</tt> for all channels. If the output
146: * handler doesn't need to flush any output, it can simply return
147: * without doing anything.
148: *
149: * @throws CurnException unable to write output
150: */
151: public void flush() throws CurnException;
152:
153: /**
154: * Get the content (i.e., MIME) type for output produced by this output
155: * handler.
156: *
157: * @return the content type
158: *
159: * @see #hasGeneratedOutput
160: * @see #getGeneratedOutput
161: */
162: public String getContentType();
163:
164: /**
165: * Get the <tt>File</tt> that represents the output produced by the
166: * handler, if applicable. (Use of a <tt>File</tt>, rather than an
167: * <tt>InputStream</tt>, is more efficient when mailing the output,
168: * since the email API ultimately wants files and will create
169: * temporary files for <tt>InputStream</tt>s.)
170: *
171: * @return the output file, or null if no suitable output was produced
172: *
173: * @throws CurnException an error occurred
174: */
175: public File getGeneratedOutput() throws CurnException;
176:
177: /**
178: * Get the output encoding.
179: *
180: * @return the encoding
181: */
182: public String getOutputEncoding();
183:
184: /**
185: * Determine whether this handler has produced any actual output (i.e.,
186: * whether {@link #getGeneratedOutput()} will return a non-null
187: * <tt>InputStream</tt> if called).
188: *
189: * @return <tt>true</tt> if the handler has produced output,
190: * <tt>false</tt> if not
191: *
192: * @see #getGeneratedOutput
193: * @see #getContentType
194: */
195: public boolean hasGeneratedOutput();
196: }
|