KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > au > id > jericho > lib > html > AttributesOutputSegment


1 // Jericho HTML Parser - Java based library for analysing and manipulating HTML
2 // Version 2.2
3 // Copyright (C) 2006 Martin Jericho
4 // http://sourceforge.net/projects/jerichohtml/
5 //
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
10 // http://www.gnu.org/copyleft/lesser.html
11 //
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 // Lesser General Public License for more details.
16 //
17 // You should have received a copy of the GNU Lesser General Public
18 // License along with this library; if not, write to the Free Software
19 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
21 package au.id.jericho.lib.html;
22
23 import java.util.*;
24 import java.io.*;
25
26 /**
27  * Implements an {@link OutputSegment} whose content is a list of attribute name/value pairs.
28  * <p>
29  * This output segment is designed to replace the original {@link Attributes} segment in the source,
30  * providing a simple means of adding, modifying and removing attributes.
31  * <p>
32  * Each instance of this class contains a <code>java.util.Map</code> of name/value pairs which can either be
33  * specified directly in the constructor or initialised to the same entries as the source {@link Attributes}
34  * specified in the constructor.
35  * This map can be accessed via the {@link #getMap()} method, and its entries modified as required before output.
36  * <p>
37  * Keys in the map must be <code>String</code> objects, and values must implement the <code>CharSequence</code> interface.
38  * <p>
39  * An attribute with no value is represented by a map entry with a <code>null</code> value.
40  * <p>
41  * Attribute values are stored unencoded in the map, and are automatically
42  * {@linkplain CharacterReference#encode(CharSequence) encoded} if necessary during output.
43  * <p>
44  * The use of invalid characters in attribute names results in unspecified behaviour.
45  * <p>
46  * Note that methods in the <code>Attributes</code> class treat attribute names as case insensitive,
47  * whereas the <code>Map</code> treats them as case sensitive.
48  * <h4>Example of Usage:</h4>
49  * <pre>
50  * Source source=new Source(htmlDocument);
51  * Attributes bodyAttributes
52  * =source.findNextStartTag(0,Tag.BODY).getAttributes();
53  * AttributesOutputSegment bodyAttributesOutputSegment
54  * =new AttributesOutputSegment(bodyAttributes,true);
55  * bodyAttributesOutputSegment.getMap().put("bgcolor","green");
56  * OutputDocument outputDocument=new OutputDocument(source);
57  * outputDocument.register(bodyAttributesOutputSegment);
58  * String htmlDocumentWithGreenBackground=outputDocument.toString();
59  * </pre>
60  * <p>
61  * This class has been deprecated as of version 2.2 and the functionality replaced with the
62  * {@link OutputDocument#replace(Attributes, Map)} and {@link OutputDocument#replace(Attributes, boolean convertNamesToLowerCase)} methods.
63  *
64  * @see OutputDocument
65  * @see Attributes
66  * @deprecated Use the {@link OutputDocument#replace(Attributes, Map)} and {@link OutputDocument#replace(Attributes, boolean convertNamesToLowerCase)} methods instead.
67  */
68 public class AttributesOutputSegment implements OutputSegment {
69     private int begin;
70     private int end;
71     private Map map;
72
73     /**
74      * Constructs a new <code>AttributesOutputSegment</code> with the same span and initial name/value entries as the specified source {@link Attributes}.
75      * <p>
76      * Specifying a value of <code>true</code> as an argument to the <code>convertNamesToLowerCase</code> parameter
77      * causes all attribute names to be converted to lower case in the map.
78      * This simplifies the process of finding/updating specific attributes since map keys are case sensitive.
79      * <p>
80      * Attribute values are automatically {@linkplain CharacterReference#decode(CharSequence) decoded} before
81      * being loaded into the map.
82      * <p>
83      * Calling this constructor with the following code:
84      * <div style="margin-left: 2em"><code>new AttributesOutputSegment(attributes, convertNamesToLowerCase)</code></div>
85      * is logically equivalent to calling:
86      * <div style="margin-left: 2em"><code>new AttributesOutputSegment(attributes, attributes.populateMap(new LinkedHashMap(), convertNamesToLowerCase))</code></div>
87      * <p>
88      * The use of <code>LinkedHashMap</code> to implement the map ensures (probably unnecessarily) that
89      * existing attributes are output in the same order as they appear in the source document, and new
90      * attributes are output in the same order as they are added.
91      *
92      * @param attributes the <code>Attributes</code> defining the span and initial name/value entries of the new <code>AttributesOutputSegment</code>.
93      * @param convertNamesToLowerCase specifies whether all attribute names are converted to lower case in the map.
94      * @see #AttributesOutputSegment(Attributes,Map)
95      */
96     public AttributesOutputSegment(final Attributes attributes, final boolean convertNamesToLowerCase) {
97         this(attributes,attributes.getMap(convertNamesToLowerCase));
98     }
99
100     /**
101      * Constructs a new <code>AttributesOutputSegment</code> with the same span
102      * as the specified source {@link Attributes}, using the specified <code>Map</code> to
103      * store the entries.
104      * <p>
105      * This constructor might be used if the <code>Map</code> containing the new attribute values
106      * should not be preloaded with the same entries as the source attributes, or a map implementation
107      * other than <code>LinkedHashMap</code> is required.
108      *
109      * @param attributes the <code>Attributes</code> defining the span of the new <code>AttributesOutputSegment</code>.
110      * @param map the <code>Map</code> containing the name/value entries.
111      * @see #AttributesOutputSegment(Attributes, boolean convertNamesToLowerCase)
112      */
113     public AttributesOutputSegment(final Attributes attributes, final Map map) {
114         if (map==null || attributes==null) throw new IllegalArgumentException JavaDoc("both arguments must be non-null");
115         begin=attributes.getBegin();
116         end=attributes.getEnd();
117         this.map=map;
118     }
119
120     public int getBegin() {
121         return begin;
122     }
123
124     public int getEnd() {
125         return end;
126     }
127
128     /**
129      * Returns the <code>Map</code> containing the name/value entries to be output.
130      * @return the <code>Map</code> containing the name/value entries to be output.
131      */
132     public Map getMap() {
133         return map;
134     }
135
136     /**
137      * Writes the contents of the {@linkplain #getMap() map} as HTML attribute name/value pairs to the specified <code>Writer</code>.
138      * <p>
139      * Each attribute is preceded by a single space, and all values are
140      * {@linkplain CharacterReference#encode(CharSequence) encoded} and enclosed in double quotes.
141      *
142      * @param writer the destination <code>java.io.Writer</code> for the output.
143      * @throws IOException if an I/O exception occurs.
144      * @see Attributes#generateHTML(Map attributesMap)
145      */
146     public void writeTo(final Writer writer) throws IOException {
147         Attributes.appendHTML(writer,map);
148     }
149
150     public long getEstimatedMaximumOutputLength() {
151         return (end-begin)*2;
152     }
153
154     public String JavaDoc toString() {
155         return Attributes.generateHTML(map);
156     }
157
158     public String JavaDoc getDebugInfo() {
159         StringWriter stringWriter=new StringWriter();
160         stringWriter.getBuffer().append('(').append(begin).append(',').append(end).append("):");
161         try {output(stringWriter);} catch (IOException ex) {} // IOException never occurs in StringWriter
162 return stringWriter.toString();
163     }
164
165     /**
166      * Outputs the contents of the {@linkplain #getMap() map} as HTML attribute name/value pairs to the specified <code>Writer</code>.
167      *
168      * @param writer the destination <code>java.io.Writer</code> for the output.
169      * @throws IOException if an I/O exception occurs.
170      * @deprecated Use {@link #writeTo(Writer)} instead.
171      */
172     public void output(final Writer writer) throws IOException {
173         writeTo(writer);
174     }
175 }
176
Popular Tags