KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > htmlparser > Tag


1 // HTMLParser Library $Name: v1_5_20050313 $ - A java-based parser for HTML
2 // http://sourceforge.org/projects/htmlparser
3 // Copyright (C) 2004 Derrick Oswald
4 //
5 // Revision Control Information
6 //
7 // $Source: /cvsroot/htmlparser/htmlparser/src/org/htmlparser/Tag.java,v $
8 // $Author: derrickoswald $
9 // $Date: 2004/07/02 00:49:26 $
10 // $Revision: 1.4 $
11 //
12 // This library is free software; you can redistribute it and/or
13 // modify it under the terms of the GNU Lesser General Public
14 // License as published by the Free Software Foundation; either
15 // version 2.1 of the License, or (at your option) any later version.
16 //
17 // This library is distributed in the hope that it will be useful,
18 // but WITHOUT ANY WARRANTY; without even the implied warranty of
19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 // Lesser General Public License for more details.
21 //
22 // You should have received a copy of the GNU Lesser General Public
23 // License along with this library; if not, write to the Free Software
24 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25 //
26
27 package org.htmlparser;
28
29 import java.util.Hashtable JavaDoc;
30 import java.util.Vector JavaDoc;
31
32 import org.htmlparser.scanners.Scanner;
33
34 /**
35  * Identifies what a Tag such as <XXX xxx yyy="zzz"> can do.
36  * Adds features to a Node that are specific to a tag.
37  */
38 public interface Tag extends Node
39 {
40     /**
41      * Returns the value of an attribute.
42      * @param name Name of attribute, case insensitive.
43      * @return The value associated with the attribute or null if it does
44      * not exist, or is a stand-alone or
45      */
46     public String JavaDoc getAttribute (String JavaDoc name);
47
48     /**
49      * Set attribute with given key, value pair.
50      * Figures out a quote character to use if necessary.
51      * @param key The name of the attribute.
52      * @param value The value of the attribute.
53      */
54     public void setAttribute (String JavaDoc key, String JavaDoc value);
55
56     /**
57      * Set attribute with given key, value pair where the value is quoted by quote.
58      * @param key The name of the attribute.
59      * @param value The value of the attribute.
60      * @param quote The quote character to be used around value.
61      * If zero, it is an unquoted value.
62      */
63     public void setAttribute (String JavaDoc key, String JavaDoc value, char quote);
64
65     /**
66      * Remove the attribute with the given key, if it exists.
67      * @param key The name of the attribute.
68      */
69     public void removeAttribute (String JavaDoc key);
70
71     /**
72      * Returns the attribute with the given name.
73      * @param name Name of attribute, case insensitive.
74      * @return The attribute or null if it does
75      * not exist.
76      */
77     public Attribute getAttributeEx (String JavaDoc name);
78
79     /**
80      * Set an attribute.
81      * This replaces an attribute of the same name.
82      * To set the zeroth attribute (the tag name), use setTagName().
83      * @param attribute The attribute to set.
84      */
85     public void setAttributeEx (Attribute attribute);
86
87     /**
88      * Gets the attributes in the tag.
89      * @return Returns the list of {@link Attribute Attributes} in the tag.
90      */
91     public Vector JavaDoc getAttributesEx ();
92
93     /**
94      * Sets the attributes.
95      * NOTE: Values of the extended hashtable are two element arrays of String,
96      * with the first element being the original name (not uppercased),
97      * and the second element being the value.
98      * @param attribs The attribute collection to set.
99      */
100     public void setAttributesEx (Vector JavaDoc attribs);
101     
102     /**
103      * Gets the attributes in the tag.
104      * This is not the preferred method to get attributes, see {@link
105      * #getAttributesEx getAttributesEx} which returns a list of {@link
106      * Attribute} objects, which offer more information than the simple
107      * <code>String</code> objects available from this <code>Hashtable</code>.
108      * @return Returns a list of name/value pairs representing the attributes.
109      * These are not in order, the keys (names) are converted to uppercase and the values
110      * are not quoted, even if they need to be. The table <em>will</em> return
111      * <code>null</code> if there was no value for an attribute (no equals
112      * sign or nothing to the right of the equals sign). A special entry with
113      * a key of SpecialHashtable.TAGNAME ("$<TAGNAME>$") holds the tag name.
114      * The conversion to uppercase is performed with an ENGLISH locale.
115      * @deprecated Use getAttributesEx() instead.
116      */
117     public Hashtable JavaDoc getAttributes ();
118
119     /**
120      * Sets the attributes.
121      * A special entry with a key of SpecialHashtable.TAGNAME ("$<TAGNAME>$")
122      * sets the tag name.
123      * @param attributes The attribute collection to set.
124      * @deprecated Use setAttributesEx() instead.
125      */
126     public void setAttributes (Hashtable JavaDoc attributes);
127
128     /**
129      * Return the name of this tag.
130      * <p>
131      * <em>
132      * Note: This value is converted to uppercase and does not
133      * begin with "/" if it is an end tag. Nor does it end with
134      * a slash in the case of an XML type tag.
135      * The conversion to uppercase is performed with an ENGLISH locale.
136      * </em>
137      * @return The tag name.
138      */
139     public String JavaDoc getTagName ();
140
141     /**
142      * Set the name of this tag.
143      * This creates or replaces the first attribute of the tag (the
144      * zeroth element of the attribute vector).
145      * @param name The tag name.
146      */
147     public void setTagName (String JavaDoc name);
148
149     /**
150      * Return the name of this tag.
151      * @return The tag name or null if this tag contains nothing or only
152      * whitespace.
153      */
154     public String JavaDoc getRawTagName ();
155
156     /**
157      * Determines if the given tag breaks the flow of text.
158      * @return <code>true</code> if following text would start on a new line,
159      * <code>false</code> otherwise.
160      */
161     public boolean breaksFlow ();
162
163     /**
164      * Predicate to determine if this tag is an end tag (i.e. &lt;/HTML&gt;).
165      * @return <code>true</code> if this tag is an end tag.
166      */
167     public boolean isEndTag ();
168
169     /**
170      * Set this tag to be an end tag, or not.
171      * Adds or removes the leading slash on the tag name.
172      * @param endTag If true, this tag is made into an end tag.
173      * Any attributes it may have had are dropped.
174      */
175 // public void setEndTag (boolean endTag);
176
177     /**
178      * Is this an empty xml tag of the form &lt;tag/&gt;.
179      * @return true if the last character of the last attribute is a '/'.
180      */
181     public boolean isEmptyXmlTag ();
182
183     /**
184      * Set this tag to be an empty xml node, or not.
185      * Adds or removes an ending slash on the tag.
186      * @param emptyXmlTag If true, ensures there is an ending slash in the node,
187      * i.e. &lt;tag/&gt;, otherwise removes it.
188      */
189     public void setEmptyXmlTag (boolean emptyXmlTag);
190
191     /**
192      * Return the set of names handled by this tag.
193      * Since this a a generic tag, it has no ids.
194      * @return The names to be matched that create tags of this type.
195      */
196     public String JavaDoc[] getIds ();
197
198     /**
199      * Return the set of tag names that cause this tag to finish.
200      * These are the normal (non end tags) that if encountered while
201      * scanning (a composite tag) will cause the generation of a virtual
202      * tag.
203      * Since this a a non-composite tag, the default is no enders.
204      * @return The names of following tags that stop further scanning.
205      */
206     public String JavaDoc[] getEnders ();
207
208     /**
209      * Return the set of end tag names that cause this tag to finish.
210      * These are the end tags that if encountered while
211      * scanning (a composite tag) will cause the generation of a virtual
212      * tag.
213      * Since this a a non-composite tag, it has no end tag enders.
214      * @return The names of following end tags that stop further scanning.
215      */
216     public String JavaDoc[] getEndTagEnders ();
217
218     /**
219      * Get the end tag for this (composite) tag.
220      * For a non-composite tag this always returns <code>null</code>.
221      * @return The tag that terminates this composite tag, i.e. &lt;/HTML&gt;.
222      */
223     public Tag getEndTag ();
224
225     /**
226      * Set the end tag for this (composite) tag.
227      * For a non-composite tag this is a no-op.
228      * @param end The tag that terminates this composite tag, i.e. &lt;/HTML&gt;.
229      */
230     public void setEndTag (Tag end);
231
232     /**
233      * Return the scanner associated with this tag.
234      * @return The scanner associated with this tag.
235      */
236     public Scanner getThisScanner ();
237
238     /**
239      * Set the scanner associated with this tag.
240      * @param scanner The scanner for this tag.
241      */
242     public void setThisScanner (Scanner scanner);
243     
244     /**
245      * Get the line number where this tag starts.
246      * @return The (zero based) line number in the page where this tag starts.
247      */
248     public int getStartingLineNumber ();
249     /**
250      * Get the line number where this tag ends.
251      * @return The (zero based) line number in the page where this tag ends.
252      */
253     public int getEndingLineNumber ();
254 }
255
Popular Tags