Copyright (c) 2000-2002 ChurchillObjects.com

churchillobjects.rss4j.generator
Class RssGenerator

java.lang.Object
  |
  +--churchillobjects.rss4j.generator.RssGenerator
Direct Known Subclasses:
RssGeneratorImpl090

public abstract class RssGenerator
extends java.lang.Object

A base and factory class for RSS generator objects. From a version number, will construct an appropriate implementation and generate the RSS document.


Field Summary
protected  int channelBuildDate
           
protected  int channelCopyrightMax
           
protected  int channelDescriptionMax
           
protected  int channelDocsMax
           
protected  int channelLinkMax
           
protected  int channelManagingEditorMax
           
protected  int channelPubDate
           
protected  int channelTitleMax
           
protected  int channelWebmasterMax
           
protected  org.w3c.dom.Document doc
          The XML document, used as it is being built.
protected  org.w3c.dom.DOMImplementation domImpl
          The DOM implementation used by the XML toolkit (user-supplied, but best to use Apache's Xerces).
protected  org.apache.xml.serialize.OutputFormat format
          An XML formatter object for the document when it is serialized.
protected  int imageDescriptionMax
           
protected  int imageLinkMax
           
protected  int imageTitleMax
           
protected  int imageUrlMax
           
protected  int itemDescriptionMax
           
protected  int itemLinkMax
           
protected  int itemTitleMax
           
protected  java.io.OutputStream outputStream
           
protected  java.io.Writer outputWriter
           
protected  org.w3c.dom.Element rootElement
           
protected  int textInputDescriptionMax
           
protected  int textInputLinkMax
           
protected  int textInputNameMax
           
protected  int textInputTitleMax
           
private  boolean truncateText
           
 
Constructor Summary
(package private) RssGenerator()
          Constructor.
 
Method Summary
protected  org.w3c.dom.Element add(org.w3c.dom.Element baseElement, java.lang.String nodeName, java.lang.String textValue)
          Convenience method that adds a new node to an existing XML element with the specified value.
protected abstract  void createRssDocument(churchillobjects.rss4j.RssDocument data)
          Subclass implementation for creating the DOM from the specified RSS document object model.
protected  java.lang.String embedHtml(java.lang.String s)
          For fields that may have HTML embedded in the code, adds a CDATA wrapper for the text value so that XML validators will not blow up.
protected abstract  void finishDocument()
           
static java.lang.String generateRss(churchillobjects.rss4j.RssDocument document)
          Creates an appropriate instance of RssGenerator with a StringWriter and generates the RSS into the writer, then returns the XML as a string.
static void generateRss(churchillobjects.rss4j.RssDocument document, java.io.File file)
          Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified file object.
static void generateRss(churchillobjects.rss4j.RssDocument document, java.io.OutputStream output)
          Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified output stream.
static void generateRss(churchillobjects.rss4j.RssDocument document, java.io.Writer output)
          Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified output writer.
private static churchillobjects.rss4j.generator.RssGenerator getGenerator(churchillobjects.rss4j.RssDocument document)
          Returns the appropriate generator for the specified RSS document object.
protected abstract  void handleChannel(churchillobjects.rss4j.RssChannel channel)
           
 boolean isTruncateText()
          Inidcates that truncation is on or off, whereby certain text (titles, descriptions, etc.
protected abstract  void setMaxLengths()
          Implemented by subclasses.
 void setTruncateText(boolean b)
          Set this accessor to TRUE if truncation of text is desired.
protected  java.lang.String truncate(java.lang.String s, int length)
           
protected  void validateUri(java.lang.String s)
          For fields that must have valid URIs, checks to see that the field contains one of the four valid URI prefixes (http, https, ftp or mailto).
protected  void validateValueOptional(java.lang.String value, java.lang.String name, int maxLength)
          Overloaded version of validateValueOptional, for when there is no minimum length for the field (1 will be used for minimum length).
protected  void validateValueOptional(java.lang.String value, java.lang.String name, int minLength, int maxLength)
          Validates a value for a field that is not required, checking its minimum and maximum lengths.
protected  void validateValueRequired(java.lang.String value, java.lang.String name, int maxLength)
          Overloaded version of validateValueRequired, for when there is no minimum length for the field (1 will be used for minimum length).
protected  void validateValueRequired(java.lang.String value, java.lang.String name, int minLength, int maxLength)
          Validates a value for a field that is required, checking its minimum and maximum lengths.
private  void writeRssDocument(churchillobjects.rss4j.RssDocument data)
          Serializes the completed DOM structure to the source given by the client code.
private  void writeRssDocument(churchillobjects.rss4j.RssDocument data, java.io.File file)
          Overloaded write method for a Java File object.
private  void writeRssDocument(churchillobjects.rss4j.RssDocument data, java.io.OutputStream output)
          Overloaded write method fo a Java IO output stream.
private  void writeRssDocument(churchillobjects.rss4j.RssDocument data, java.io.Writer output)
          Overloaded write method for a Java IO writer object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

domImpl

protected org.w3c.dom.DOMImplementation domImpl
The DOM implementation used by the XML toolkit (user-supplied, but best to use Apache's Xerces).


format

protected org.apache.xml.serialize.OutputFormat format
An XML formatter object for the document when it is serialized.


doc

protected org.w3c.dom.Document doc
The XML document, used as it is being built.


outputWriter

protected java.io.Writer outputWriter

outputStream

protected java.io.OutputStream outputStream

rootElement

protected org.w3c.dom.Element rootElement

truncateText

private boolean truncateText

channelTitleMax

protected int channelTitleMax

channelDescriptionMax

protected int channelDescriptionMax

channelLinkMax

protected int channelLinkMax

channelPubDate

protected int channelPubDate

channelBuildDate

protected int channelBuildDate

channelManagingEditorMax

protected int channelManagingEditorMax

channelWebmasterMax

protected int channelWebmasterMax

channelCopyrightMax

protected int channelCopyrightMax

channelDocsMax

protected int channelDocsMax

imageTitleMax

protected int imageTitleMax

imageUrlMax

protected int imageUrlMax

imageLinkMax

protected int imageLinkMax

imageDescriptionMax

protected int imageDescriptionMax

itemTitleMax

protected int itemTitleMax

itemLinkMax

protected int itemLinkMax

itemDescriptionMax

protected int itemDescriptionMax

textInputTitleMax

protected int textInputTitleMax

textInputDescriptionMax

protected int textInputDescriptionMax

textInputNameMax

protected int textInputNameMax

textInputLinkMax

protected int textInputLinkMax
Constructor Detail

RssGenerator

RssGenerator()
       throws RssGenerationException
Constructor. Sets up the XML document and formatter, then invokes setMaxLengths.

Method Detail

generateRss

public static java.lang.String generateRss(churchillobjects.rss4j.RssDocument document)
                                    throws RssGenerationException
Creates an appropriate instance of RssGenerator with a StringWriter and generates the RSS into the writer, then returns the XML as a string.

Parameters:
document -
Returns:
RssGenerationException

generateRss

public static void generateRss(churchillobjects.rss4j.RssDocument document,
                               java.io.OutputStream output)
                        throws RssGenerationException
Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified output stream.

Parameters:
document -
output -
Throws:
RssGenerationException

generateRss

public static void generateRss(churchillobjects.rss4j.RssDocument document,
                               java.io.File file)
                        throws RssGenerationException
Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified file object.

Parameters:
document -
file -
Throws:
RssGenerationException

generateRss

public static void generateRss(churchillobjects.rss4j.RssDocument document,
                               java.io.Writer output)
                        throws RssGenerationException
Creates an appropriate instance of RssGenerator and has it write the RSS code to the specified output writer.

Parameters:
document -
output -
Throws:
RssGenerationException

getGenerator

private static churchillobjects.rss4j.generator.RssGenerator getGenerator(churchillobjects.rss4j.RssDocument document)
                                                                   throws RssGenerationException
Returns the appropriate generator for the specified RSS document object. If none, then a RSSGenerationException is thrown.

Parameters:
document -
Returns:
RssGenerationException

setMaxLengths

protected abstract void setMaxLengths()
Implemented by subclasses. If there are field length limitations that need to be adhered to, then the version implementation would set them here and it will be invoked at initialization time.


handleChannel

protected abstract void handleChannel(churchillobjects.rss4j.RssChannel channel)
                               throws RssGenerationException
RssGenerationException

finishDocument

protected abstract void finishDocument()
                                throws RssGenerationException
RssGenerationException

writeRssDocument

private void writeRssDocument(churchillobjects.rss4j.RssDocument data)
                       throws RssGenerationException
Serializes the completed DOM structure to the source given by the client code. Any problems here are wrapped in an RssGenerationException and thrown up the stack.

Parameters:
data -
Throws:
RssGenerationException

createRssDocument

protected abstract void createRssDocument(churchillobjects.rss4j.RssDocument data)
                                   throws RssGenerationException
Subclass implementation for creating the DOM from the specified RSS document object model.

Parameters:
data -
Throws:
RssGenerationException

writeRssDocument

private void writeRssDocument(churchillobjects.rss4j.RssDocument data,
                              java.io.OutputStream output)
                       throws RssGenerationException
Overloaded write method fo a Java IO output stream. The resulting RSS code will be written to the specified output stream.

Parameters:
data -
output -
Throws:
RssGenerationException

writeRssDocument

private void writeRssDocument(churchillobjects.rss4j.RssDocument data,
                              java.io.File file)
                       throws RssGenerationException
Overloaded write method for a Java File object. The resulting RSS code will be written to the specified file.

Parameters:
data -
file -
Throws:
RssGenerationException

writeRssDocument

private void writeRssDocument(churchillobjects.rss4j.RssDocument data,
                              java.io.Writer output)
                       throws RssGenerationException
Overloaded write method for a Java IO writer object. The resulting RSS code will be written to the specified writer.

Parameters:
data -
output -
Throws:
RssGenerationException

add

protected org.w3c.dom.Element add(org.w3c.dom.Element baseElement,
                                  java.lang.String nodeName,
                                  java.lang.String textValue)
Convenience method that adds a new node to an existing XML element with the specified value. The method will not create and add the new node if the value is null.

Parameters:
baseElement -
nodeName -
textValue -
Returns:

setTruncateText

public void setTruncateText(boolean b)
Set this accessor to TRUE if truncation of text is desired. This will truncate any text that is truncatable (titles, descriptions, etc) and append an ellipsis (three dots) at the end of the text to show that there is more. This only applies if the text would otherwise exceed the limit of the field during generation (and thus will not change the object that contains the too-long text). Applies to RSS 0.90 and 0.91 specifications.

Parameters:
b - Truncate too-long text during RSS generation, if the standard warrants it.

isTruncateText

public boolean isTruncateText()
Inidcates that truncation is on or off, whereby certain text (titles, descriptions, etc. will be truncated if they exceed the RSS standard being used.

Returns:
If text will be truncated if it happens to be too long for the standard.

truncate

protected java.lang.String truncate(java.lang.String s,
                                    int length)
                             throws RssGenerationException
Parameters:
s - The string value to truncate. If null, then nothing is done.
length - The number of characters to truncate to. If zero, then there is no limit on the length of the element.
Returns:
The truncated (if necessary) string, or null if s is null.
Throws:
RssGenerationException

validateValueRequired

protected void validateValueRequired(java.lang.String value,
                                     java.lang.String name,
                                     int minLength,
                                     int maxLength)
                              throws RssGenerationException
Validates a value for a field that is required, checking its minimum and maximum lengths. If the value is null, has no length or exceeds the required length (if any), then an RssGenerationException is thrown up the stack. the test passes.

Parameters:
value -
name -
minLength -
maxLength -
Throws:
RssGenerationException

validateValueRequired

protected void validateValueRequired(java.lang.String value,
                                     java.lang.String name,
                                     int maxLength)
                              throws RssGenerationException
Overloaded version of validateValueRequired, for when there is no minimum length for the field (1 will be used for minimum length).

Parameters:
value -
name -
maxLength -
Throws:
RssGenerationException

validateValueOptional

protected void validateValueOptional(java.lang.String value,
                                     java.lang.String name,
                                     int minLength,
                                     int maxLength)
                              throws RssGenerationException
Validates a value for a field that is not required, checking its minimum and maximum lengths. If the value is null or there is no maximum (not > 0), then the test passes.

Parameters:
value -
name -
minLength -
maxLength -
Throws:
RssGenerationException

validateValueOptional

protected void validateValueOptional(java.lang.String value,
                                     java.lang.String name,
                                     int maxLength)
                              throws RssGenerationException
Overloaded version of validateValueOptional, for when there is no minimum length for the field (1 will be used for minimum length).

Parameters:
value -
name -
maxLength -
Throws:
RssGenerationException

embedHtml

protected java.lang.String embedHtml(java.lang.String s)
For fields that may have HTML embedded in the code, adds a CDATA wrapper for the text value so that XML validators will not blow up.

Parameters:
s - The text to be evaluated
Returns:
The modified text, or original if not modified

validateUri

protected void validateUri(java.lang.String s)
                    throws RssGenerationException
For fields that must have valid URIs, checks to see that the field contains one of the four valid URI prefixes (http, https, ftp or mailto).

Parameters:
s - The URI value to evaluate
Throws:
RssGenerationException - When the validation fails

Copyright (c) 2000-2002 ChurchillObjects.com