au.id.jericho.lib.html

Class OutputDocument

Implemented Interfaces:
CharStreamSource

public final class OutputDocument
extends java.lang.Object
implements CharStreamSource

Represents a modified version of an original Source document.

An OutputDocument represents an original source document that has been modified by substituting segments of it with other text. Each of these substitutions must be registered in the output document, which is most commonly done using the various replace, remove or insert methods in this class. These methods internally register one or more OutputSegment objects to define each substitution. After all of the substitutions have been registered, the modified text can be retrieved using the writeTo(Writer) or toString() methods.

The registered output segments may be adjacent, and as of version 2.5 may also overlap. In most cases only output segments that have been removed or replaced with spaces legitimately overlap each other. Registering overlapping output segments that generate output will generally yield unexpected results.

If unexpected results are being generated from an OutputDocument, the getDebugInfo() method provides information on each registered output segment, which should provide enough information to determine the cause of the problem. In most cases the problem will be caused by overlapping output segments.

The following example converts all externally referenced style sheets to internal style sheets:

  URL sourceUrl=new URL(sourceUrlString);
  String htmlText=Util.getString(new InputStreamReader(sourceUrl.openStream()));
  Source source=new Source(htmlText);
  OutputDocument outputDocument=new OutputDocument(source);
  StringBuffer sb=new StringBuffer();
  List linkStartTags=source.findAllStartTags(Tag.LINK);
  for (Iterator i=linkStartTags.iterator(); i.hasNext();) {
    StartTag startTag=(StartTag)i.next();
    Attributes attributes=startTag.getAttributes();
    String rel=attributes.getValue("rel");
    if (!"stylesheet".equalsIgnoreCase(rel)) continue;
    String href=attributes.getValue("href");
    if (href==null) continue;
    String styleSheetContent;
    try {
      styleSheetContent=Util.getString(new InputStreamReader(new URL(sourceUrl,href).openStream()));
    } catch (Exception ex) {
      continue; // don't convert if URL is invalid
    }
    sb.setLength(0);
    sb.append("<style");
    Attribute typeAttribute=attributes.get("type");
    if (typeAttribute!=null) sb.append(' ').append(typeAttribute);
    sb.append(">\n").append(styleSheetContent).append("\n</style>");
    outputDocument.replace(startTag,sb);
  }
  String convertedHtmlText=outputDocument.toString();
 
See Also:
OutputSegment

Constructor Summary

OutputDocument(Source source)
Constructs a new output document based on the specified source document.

Method Summary

String
getDebugInfo()
Returns a string representation of this object useful for debugging purposes.
long
getEstimatedMaximumOutputLength()
List
getRegisteredOutputSegments()
Returns a list all of the registered OutputSegment objects in this output document.
CharSequence
getSourceText()
Returns the original source text upon which this output document is based.
void
insert(int pos, CharSequence text)
Inserts the specified text at the specified character position in this output document.
void
register(OutputSegment outputSegment)
Registers the specified output segment in this output document.
void
remove(Collection segments)
Removes all the segments from this output document represented by the specified source Segment objects.
void
remove(Segment segment)
Removes the specified segment from this output document.
void
replace(Attributes attributes, Map map)
Replaces the specified attributes segment in this source document with the name/value entries in the specified Map.
Map
replace(Attributes attributes, boolean convertNamesToLowerCase)
Replaces the specified Attributes segment in this output document with the name/value entries in the returned Map.
void
replace(FormControl formControl)
Replaces the specified FormControl in this output document.
void
replace(FormFields formFields)
Replaces all the constituent form controls from the specified FormFields in this output document.
void
replace(Segment segment, CharSequence text)
Replaces the specified segment in this output document with the specified text.
void
replace(int begin, int end, CharSequence text)
Replaces the specified segment of this output document with the specified text.
void
replace(int begin, int end, char ch)
Replaces the specified segment of this output document with the specified character.
void
replaceWithSpaces(int begin, int end)
Replaces the specified segment of this output document with a string of spaces of the same length.
String
toString()
Returns the final content of this output document as a String.
void
writeTo(Writer writer)
Writes the final content of this output document to the specified Writer.

Constructor Details

OutputDocument

public OutputDocument(Source source)
Constructs a new output document based on the specified source document.
Parameters:
source - the source document.

Method Details

getDebugInfo

public String getDebugInfo()
Returns:
a string representation of this object useful for debugging purposes.

getEstimatedMaximumOutputLength

public long getEstimatedMaximumOutputLength()
Specified by:
getEstimatedMaximumOutputLength in interface CharStreamSource

getRegisteredOutputSegments

public List getRegisteredOutputSegments()
Returns a list all of the registered OutputSegment objects in this output document.

The output segments are sorted in order of their starting position in the document.

The returned list is modifiable and any changes will affect the output generated by this OutputDocument.

Returns:
a list all of the registered OutputSegment objects in this output document.

getSourceText

public CharSequence getSourceText()
Returns the original source text upon which this output document is based.
Returns:
the original source text upon which this output document is based.

insert

public void insert(int pos,
                   CharSequence text)
Inserts the specified text at the specified character position in this output document.
Parameters:
pos - the character position at which to insert the text.
text - the replacement text.

register

public void register(OutputSegment outputSegment)
Registers the specified output segment in this output document.

Use this method if you want to use a customised OutputSegment class.

Parameters:
outputSegment - the output segment to register.

remove

public void remove(Collection segments)
Removes all the segments from this output document represented by the specified source Segment objects.

This is equivalent to the following code:

  for (Iterator i=segments.iterator(); i.hasNext();)
remove((Segment)i.next());
Parameters:
segments - a collection of segments to remove, represented by source Segment objects.

remove

public void remove(Segment segment)
Removes the specified segment from this output document.

This is equivalent to replace(segment,null).

Parameters:
segment - the segment to remove.

replace

public void replace(Attributes attributes,
                    Map map)
Replaces the specified attributes segment in this source document with the name/value entries in the specified Map.

This method might be used if the Map containing the new attribute values should not be preloaded with the same entries as the source attributes, or a map implementation other than LinkedHashMap is required. Otherwise, the replace(Attributes, boolean convertNamesToLowerCase) method is generally more useful.

Keys in the map must be String objects, and values must implement the CharSequence interface.

An attribute with no value is represented by a map entry with a null value.

Attribute values are stored unencoded in the map, and are automatically encoded if necessary during output.

The use of invalid characters in attribute names results in unspecified behaviour.

Note that methods in the Attributes class treat attribute names as case insensitive, whereas the Map treats them as case sensitive.

Parameters:
attributes - the Attributes object defining the span of the segment to replace.
map - the Map containing the name/value entries.
See Also:
replace(Attributes, boolean convertNamesToLowerCase)

replace

public Map replace(Attributes attributes,
                   boolean convertNamesToLowerCase)
Replaces the specified Attributes segment in this output document with the name/value entries in the returned Map. The returned map initially contains entries representing the attributes from the source document, which can be modified before output.

The documentation of the replace(Attributes,Map) method contains more information about the requirements of the map entries.

Specifying a value of true as an argument to the convertNamesToLowerCase parameter causes all original attribute names to be converted to lower case in the map. This simplifies the process of finding/updating specific attributes since map keys are case sensitive.

Attribute values are automatically decoded before being loaded into the map.

This method is logically equivalent to:
replace(attributes, attributes.populateMap(new LinkedHashMap(),convertNamesToLowerCase))

The use of LinkedHashMap to implement the map ensures (probably unnecessarily) that existing attributes are output in the same order as they appear in the source document, and new attributes are output in the same order as they are added.

  Source source=new Source(htmlDocument);
  Attributes bodyAttributes
    =source.findNextStartTag(0,Tag.BODY).getAttributes();
  OutputDocument outputDocument=new OutputDocument(source);
  Map attributesMap=outputDocument.replace(bodyAttributes,true);
  attributesMap.put("bgcolor","green");
  String htmlDocumentWithGreenBackground=outputDocument.toString();
Parameters:
attributes - the Attributes segment defining the span of the segment and initial name/value entries of the returned map.
convertNamesToLowerCase - specifies whether all attribute names are converted to lower case in the map.
Returns:
a Map containing the name/value entries to be output.

replace

public void replace(FormControl formControl)
Replaces the specified FormControl in this output document.

The effect of this method is to register zero or more output segments in the output document as required to reflect previous modifications to the control's state. The state of a control includes its submission value, output style, and whether it has been disabled.

The state of the form control should not be modified after this method is called, as there is no guarantee that subsequent changes either will or will not be reflected in the final output. A second call to this method with the same parameter is not allowed. It is therefore recommended to call this method as the last action before the output is generated.

Although the specifics of the number and nature of the output segments added in any particular circumstance is not defined in the specification, it can generally be assumed that only the minimum changes necessary are made to the original document. If the state of the control has not been modified, calling this method has no effect at all.

Parameters:
formControl - the form control to replace.

replace

public void replace(FormFields formFields)
Replaces all the constituent form controls from the specified FormFields in this output document.

This is equivalent to the following code:

for (Iterator i=formFields.getFormControls().iterator(); i.hasNext();)
replace((FormControl)i.next());

The state of any of the form controls in the specified form fields should not be modified after this method is called, as there is no guarantee that subsequent changes either will or will not be reflected in the final output. A second call to this method with the same parameter is not allowed. It is therefore recommended to call this method as the last action before the output is generated.

Parameters:
formFields - the form fields to replace.

replace

public void replace(Segment segment,
                    CharSequence text)
Replaces the specified segment in this output document with the specified text.

Specifying a null argument to the text parameter is exactly equivalent to specifying an empty string, and results in the segment being completely removed from the output document.

Parameters:
segment - the segment to replace.
text - the replacement text, or null to remove the segment.

replace

public void replace(int begin,
                    int end,
                    CharSequence text)
Replaces the specified segment of this output document with the specified text.

Specifying a null argument to the text parameter is exactly equivalent to specifying an empty string, and results in the segment being completely removed from the output document.

Parameters:
begin - the character position at which to begin the replacement.
end - the character position at which to end the replacement.
text - the replacement text, or null to remove the segment.

replace

public void replace(int begin,
                    int end,
                    char ch)
Replaces the specified segment of this output document with the specified character.
Parameters:
begin - the character position at which to begin the replacement.
end - the character position at which to end the replacement.
ch - the replacement character.

replaceWithSpaces

public void replaceWithSpaces(int begin,
                              int end)
Parameters:
begin - the character position at which to begin the replacement.
end - the character position at which to end the replacement.

toString

public String toString()
Returns the final content of this output document as a String.
Specified by:
toString in interface CharStreamSource
Returns:
the final content of this output document as a String.

writeTo

public void writeTo(Writer writer)
            throws IOException
Specified by:
writeTo in interface CharStreamSource
Parameters:
writer - the destination java.io.Writer for the output.
See Also:
toString()