001: package com.meterware.httpunit;
002:
003: /********************************************************************************************************************
004: * $Id: HTMLSegment.java,v 1.15 2004/09/29 17:15:24 russgold Exp $
005: *
006: * Copyright (c) 2000-2004, Russell Gold
007: *
008: * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
009: * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
010: * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
011: * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
012: *
013: * The above copyright notice and this permission notice shall be included in all copies or substantial portions
014: * of the Software.
015: *
016: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
017: * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
018: * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
019: * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
020: * DEALINGS IN THE SOFTWARE.
021: *
022: *******************************************************************************************************************/
023: import org.xml.sax.SAXException;
024:
025: /**
026: * Represents the parse tree for a segment of HTML.
027: *
028: * @author <a href="mailto:russgold@httpunit.org">Russell Gold</a>
029: **/
030: public interface HTMLSegment {
031:
032: /**
033: * Returns the HTMLElement found in this segment with the specified ID.
034: * @exception SAXException thrown if there is an error parsing the segment.
035: */
036: public HTMLElement getElementWithID(String id) throws SAXException;
037:
038: /**
039: * Returns the HTMLElements found in this segment with the specified name.
040: */
041: public HTMLElement[] getElementsWithName(String name)
042: throws SAXException;
043:
044: /**
045: * Returns the HTMLElements found with the specified attribute value.
046: *
047: * @since 1.6
048: */
049: public HTMLElement[] getElementsWithAttribute(String name,
050: String value) throws SAXException;
051:
052: /**
053: * Returns a list of HTML element names contained in this HTML section.
054: */
055: public String[] getElementNames() throws SAXException;
056:
057: /**
058: * Returns the forms found in this HTML segment in the order in which they appear.
059: * @exception SAXException thrown if there is an error parsing the segment.
060: **/
061: public WebForm[] getForms() throws SAXException;
062:
063: /**
064: * Returns the form found in this HTML segment with the specified ID.
065: * @exception SAXException thrown if there is an error parsing the segment.
066: **/
067: public WebForm getFormWithID(String ID) throws SAXException;
068:
069: /**
070: * Returns the form found in this HTML segment with the specified name.
071: * @exception SAXException thrown if there is an error parsing the segment.
072: **/
073: public WebForm getFormWithName(String name) throws SAXException;
074:
075: /**
076: * Returns the first form found in the page matching the specified criteria.
077: * @exception SAXException thrown if there is an error parsing the response.
078: **/
079: public WebForm getFirstMatchingForm(HTMLElementPredicate predicate,
080: Object value) throws SAXException;
081:
082: /**
083: * Returns all forms found in the page matching the specified criteria.
084: * @exception SAXException thrown if there is an error parsing the response.
085: **/
086: public WebForm[] getMatchingForms(HTMLElementPredicate predicate,
087: Object criteria) throws SAXException;
088:
089: /**
090: * Returns the links found in this HTML segment in the order in which they appear.
091: * @exception SAXException thrown if there is an error parsing the segment.
092: **/
093: public WebLink[] getLinks() throws SAXException;
094:
095: /**
096: * Returns the first link which contains the specified text.
097: * @exception SAXException thrown if there is an error parsing the segment.
098: **/
099: public WebLink getLinkWith(String text) throws SAXException;
100:
101: /**
102: * Returns the first link which contains an image with the specified text as its 'alt' attribute.
103: * @exception SAXException thrown if there is an error parsing the segment.
104: **/
105: public WebLink getLinkWithImageText(String text)
106: throws SAXException;
107:
108: /**
109: * Returns the first link found in the page matching the specified criteria.
110: * @exception SAXException thrown if there is an error parsing the response.
111: **/
112: public WebLink getFirstMatchingLink(HTMLElementPredicate predicate,
113: Object value) throws SAXException;
114:
115: /**
116: * Returns all links found in the page matching the specified criteria.
117: * @exception SAXException thrown if there is an error parsing the response.
118: **/
119: public WebLink[] getMatchingLinks(HTMLElementPredicate predicate,
120: Object criteria) throws SAXException;
121:
122: /**
123: * Returns the images found in the page in the order in which they appear.
124: * @exception SAXException thrown if there is an error parsing the segment.
125: **/
126: public WebImage[] getImages() throws SAXException;
127:
128: /**
129: * Returns the image found in the page with the specified name.
130: * @exception SAXException thrown if there is an error parsing the segment.
131: **/
132: public WebImage getImageWithName(String name) throws SAXException;
133:
134: /**
135: * Returns the first image found in the page with the specified src attribute.
136: * @exception SAXException thrown if there is an error parsing the segment.
137: **/
138: public WebImage getImageWithSource(String source)
139: throws SAXException;
140:
141: /**
142: * Returns the first image found in the page with the specified alt attribute.
143: * @exception SAXException thrown if there is an error parsing the segment.
144: **/
145: public WebImage getImageWithAltText(String source)
146: throws SAXException;
147:
148: /**
149: * Returns the applets found in the page in the order in which they appear.
150: * @exception SAXException thrown if there is an error parsing the segment.
151: **/
152: public WebApplet[] getApplets() throws SAXException;
153:
154: /**
155: * Returns the top-level block elements found in the page in the order in which they appear.
156: * @exception SAXException thrown if there is an error parsing the segment.
157: *
158: * @since 1.6
159: */
160: public TextBlock[] getTextBlocks() throws SAXException;
161:
162: /**
163: * Returns the top-level tables found in this HTML segment in the order in which
164: * they appear.
165: * @exception SAXException thrown if there is an error parsing the segment.
166: **/
167: public WebTable[] getTables() throws SAXException;
168:
169: /**
170: * Returns the first table in the response which matches the specified predicate and value.
171: * Will recurse into any nested tables, as needed.
172: * @return the selected table, or null if none is found
173: **/
174: public WebTable getFirstMatchingTable(
175: HTMLElementPredicate predicate, Object criteria)
176: throws SAXException;
177:
178: /**
179: * Returns all tables found in the page matching the specified criteria.
180: * @exception SAXException thrown if there is an error parsing the response.
181: **/
182: public WebTable[] getMatchingTables(HTMLElementPredicate predicate,
183: Object criteria) throws SAXException;
184:
185: /**
186: * Returns the first table in this HTML segment which has the specified text as the full text of
187: * its first non-blank row and non-blank column. Will recurse into any nested tables, as needed.
188: * @return the selected table, or null if none is found
189: * @exception SAXException thrown if there is an error parsing the segment.
190: **/
191: public WebTable getTableStartingWith(final String text)
192: throws SAXException;
193:
194: /**
195: * Returns the first table in this HTML segment which has the specified text as a prefix of the text
196: * in its first non-blank row and non-blank column. Will recurse into any nested tables, as needed.
197: * @return the selected table, or null if none is found
198: * @exception SAXException thrown if there is an error parsing the segment.
199: **/
200: public WebTable getTableStartingWithPrefix(String text)
201: throws SAXException;
202:
203: /**
204: * Returns the first table in this HTML segment which has the specified text as its summary attribute.
205: * Will recurse into any nested tables, as needed.
206: * @return the selected table, or null if none is found
207: * @exception SAXException thrown if there is an error parsing the segment.
208: **/
209: public WebTable getTableWithSummary(String summary)
210: throws SAXException;
211:
212: /**
213: * Returns the first table in this HTML segment which has the specified text as its ID attribute.
214: * Will recurse into any nested tables, as needed.
215: * @return the selected table, or null if none is found
216: * @exception SAXException thrown if there is an error parsing the segment.
217: **/
218: public WebTable getTableWithID(final String ID) throws SAXException;
219:
220: }
|