All Downloads are FREE. Search and download functionalities are using the official Maven repository.

js.dom.Document Maven / Gradle / Ivy

The newest version!
package js.dom;

import java.io.IOException;
import java.io.Writer;

/**
 * Document interface is a simplified morph of W3C DOM Document. Basically a document is a tree of elements with a unique root.
 * It supplies getter for root element and methods for element creation, import and searching.
 * 

* All search operations are performed using depth-first algorithm, i.e starts from root and explores as far as possible along * each branch before backtracking. There are basically two kinds of search: getBy and findBy. First * always returns an {@link Element} or null while the second returns {@link EList}, possible empty. One can use * {@link EList#isEmpty} to check if findBy actually found something. *

* Where reasonable, search methods has variant for name space. As stated not all search methods have support for name space; * for example searching by CSS class has not name space since class attribute name is only in global scope. All * methods handling name spaces follows W3C DOM convention, i.e. has the name suffixed with NS. First parameter is * always name space. If name space parameter is null, name space aware methods degenerate to their not name space counterpart, * e.g. getByTagNS(null, "p") delegates getByTag("p"). *

* If document is parsed without name space support, element 'NS' getters always returns null and 'NS' finders always return * empty list. Also, on document without name space support, element and attribute names include prefix. For example, * ns:name element has null name space and local name 'ns:name'. When searching for element use 'ns:name' for name * and search method without NS suffix. * * @author Iulian Rotaru * @version final */ public interface Document { /** * Test if this document is a XML instance. * * @return true if this document is XML. */ boolean isXML(); /** * Create element and set attributes. Create an element of requested tag owned by this document. Also set attributes values * if optional attribute name/value pairs are present; throws illegal argument if a name/value is incomplete, i.e. odd * number of arguments. It is user code responsibility to supply attribute name and value in proper order. Note that newly * created element is not part of document tree until explicitly add or insert it as a child to a parent. So, elements * creation follows the same W3C DOM pattern: create the element then add it as a child. * *

	 * Element p = doc.createElement("p", "id", "paragraph-id", "title", "tooltip description");
	 * body.addChild(p);
	 * 
* * @param tagName tag name for element to be created, * @param attrNameValues optional pairs of attribute name followed by value. * @return newly created element. * @throws IllegalArgumentException if tagName parameter is null or empty or attrNameValues * parameter is not complete. * @see Element#setAttr(String, String) */ Element createElement(String tagName, String... attrNameValues); /** * Create element in requested name space. Create an element of requested tag, owned by this document, within the name * space. Note that newly created element is not part of document tree until explicitly add or insert it as a child to a * parent. So, elements creation follows the same W3C DOM pattern: create the element then add it as a child. * *
	 * Element p = doc.createElementNS(namespaceURI, "p");
	 * body.addChild(p);
	 * 
*

* Null namespaceURI is considered global scope and this method delegates * {@link #createElement(String, String...)}, without attributes. *

* This method has no attributes parameters as {@link #createElement(String, String...)} because is user code decision if * attribute name has name space or not. * * @param namespaceURI name space URI, * @param tagName tag name for element to be created. * @return newly created element. * @throws IllegalArgumentException if tagName parameter is null or empty. */ Element createElementNS(String namespaceURI, String tagName); /** * Import element. Import an element that belongs to another document and return it. Note that newly imported element is not * part of this document tree until explicitly appended or inserted to a parent element. Also import is always deep, that * is, element children are imported too. * *

	 * Element el = doc.importElement(foreignDoc.getByTag("Luke Skywalker"));
	 * doc.getByTag("Dark Vader").addChild(el);
	 * 
* * @param el foreign element. * @return newly imported element. * @throws IllegalArgumentException if element parameter is null or if element already belongs to this document. */ Element importElement(Element el); /** * Retrieve the root of this document tree. * * @return this document root. */ Element getRoot(); /** * Get the element with specified ID. This method looks for an attribute with type ID, usually named id. * Attribute type is set at document validation using DTD or schema information. Trying to use this method on a document * without schema always returns null. * * @param id element ID to look for. * @return element with specified ID or null. * @throws IllegalArgumentException if id parameter is null or empty. */ Element getById(String id); /** * Search entire document for elements with given tag name and return the first element found. Returns null if there is no * element with requested tag name. Note that wild card asterisk (*) matches all tags in which case first child is returned. *

* On XML documents tag name is case sensitive whereas in HTML is not. For consistency sake is recommended to always * consider tags name as case sensitive. Also, if document contains name spaces but is parsed without name space support, * tag name for name space elements should use name space prefix. * * @param tagName case sensitive tag name to search for. * @return first element with specified tag or null. * @throws IllegalArgumentException if tag name parameter is null or empty. */ Element getByTag(String tagName); /** * Get the element with tag name in the requested name space. Tag name is a local name, that is, has no name space prefix; * name space if identified by separated namespaceURI parameter. *

* Search entire document for elements with given tag name, within name space, and return the first found. Returns null if * there is no element with requested tag name. Note that wild card asterisk (*) for tag name matches all tags in which case * first child is returned. Always returns null if this document is not parsed with name space support. *

* If name space parameter is wild card ('*') all name spaces are considered, that is, entire document. Null name space is * considered default scope, that is, elements without any prefix in which case this method degenerates to * {@link #getByTag(String)} counterpart. *

* On XML documents tag name is case sensitive whereas in HTML is not. For consistency sake is recommended to always * consider tag names as case sensitive. * * @param namespaceURI name space URI, * @param tagName local tag name to search for, case sensitive. * @return first element with specified tag or null. * @throws IllegalArgumentException if tag name parameter is null or empty. */ Element getByTagNS(String namespaceURI, String tagName); /** * Find elements by tag. Return all elements from this document having specified tag name. Returns empty list if there is * not element with requested tag name. Note that wild card asterisk (*) for tag name matches all tags in which case all * elements are returned. *

* On XML documents tag name is case sensitive whereas in HTML is not. For consistency sake is recommended to always * consider tags name as case sensitive. If document contains name spaces but is parsed without name space support, tag name * for name space elements should use name space prefix. * * @param tagName tag name to search for, case sensitive. * @return list of found elements, possible empty. * @throws IllegalArgumentException if tagName parameter is null or empty. */ EList findByTag(String tagName); /** * Find elements having requested tag name into the given name space. Returns empty list if there is not element with * requested tag name. Note that wild card asterisk (*) for tag name matches all tags in which case all elements are * returned. *

* If name space parameter is wild card ('*') all name spaces are considered, that is, entire document. Null name space is * considered default scope, that is, elements without any prefix. *

* On XML documents tag name is case sensitive whereas in HTML is not. For consistency sake is recommended to always * consider tag names as case sensitive. * * @param namespaceURI name space URI, possible wild card or null, * @param tagName local tag name, case sensitive. * @return list of found elements, possible empty. * @throws IllegalArgumentException if tagName parameter is null or empty. */ EList findByTagNS(String namespaceURI, String tagName); /** * Get element by XPath. Evaluate XPath expression and return first element found. Returns null if XPath evaluation has no * results. Note that XPath expression is case sensitive; this is especially relevant for HTML documents, that uses upper * case for tag names. *

* XPath expression xpath can be formatted as supported by {@link String#format} in which case * args arguments should be supplied. * * @param xpath XPath expression to evaluate, * @param args optional arguments if xpath is formatted. * @return first element found or null. * @throws IllegalArgumentException if xpath parameter is null or empty. */ Element getByXPath(String xpath, Object... args); /** * Evaluate XPath expression with name space prefixes and return first element found. Returns null if XPath evaluation has * no results. Note that XPath expression is case sensitive; this is especially relevant for HTML documents that uses upper * case for tag names. *

* Name space context maps prefixes to name space URI. See {@link NamespaceContext} for a discussion about expressions with * name space. *

* XPath expression xpath can be formatted as supported by {@link String#format} in which case * args arguments should be supplied. * * @param namespaceContext name space context maps prefixes to name space URI, * @param xpath XPath expression to evaluate, * @param args optional arguments if xpath is formatted. * @return first element found or null. * @throws IllegalArgumentException if namespaceContext parameter is null or xpath parameter is * null or empty. */ Element getByXPathNS(NamespaceContext namespaceContext, String xpath, Object... args); /** * Evaluate XPath expression and return the list of found elements. Returns empty list if XPath evaluation has no results. * Note that XPath expression is case sensitive; this is especially relevant for HTML documents that uses upper case for tag * names. *

* XPath expression xpath can be formatted as supported by {@link String#format} in which case * args arguments should be supplied. * * @param xpath XPath expression to evaluate, * @param args optional arguments if xpath is formatted. * @return list of found elements, possible empty. * @throws IllegalArgumentException if xpath parameter is null or empty. */ EList findByXPath(String xpath, Object... args); /** * Evaluate XPath expression with name space prefixes and return the list of found elements. Returns empty list if XPath * evaluation has no results. Note that XPath expression is case sensitive; this is especially relevant for HTML documents * that uses upper case for tag names. *

* Name space context maps prefixes to name space URI. See {@link NamespaceContext} for a discussion about expressions with * name space. *

* XPath expression xpath can be formatted as supported by {@link String#format} in which case * args arguments should be supplied. * * @param namespaceContext name space context, * @param xpath XPath expression to evaluate, * @param args optional arguments if xpath is formatted. * @return list of found elements, possible empty. * @throws IllegalArgumentException if namespaceContext parameter is null or xpath parameter is * null or empty. */ EList findByXPathNS(NamespaceContext namespaceContext, String xpath, Object... args); /** * Evaluate CSS selectors and return first element found. Returns null if CSS evaluation has no results. CSS * selector can be formatted as supported by {@link String#format} in which case args parameter * should be supplied. *

* Implementation note: this method is not yet implemented and always throws unsupported operation. * * @param selector CSS selector to evaluate, * @param args optional arguments if selectors is formatted. * @return first found element or null. * @throws IllegalArgumentException if selector parameter is null or empty. */ Element getByCss(String selector, Object... args); /** * Find elements by CSS selectors. Evaluate CSS selectors and return found elements. Returns empty list if CSS evaluation * has no results. CSS selector can be formatted as supported by {@link String#format} in which case * args parameter should be supplied. *

* Implementation note: this method is not yet implemented and always throws unsupported operation. * * @param selector CSS selector to evaluate, * @param args optional arguments if selector is formatted. * @return list of found elements, possible empty. * @throws IllegalArgumentException if selector parameter is null or empty. */ EList findByCss(String selector, Object... args); /** * Get element by CSS class. Retrieve first element possessing requested CSS class. Returns null if there is no element with * such CSS class. * * @param cssClass CSS class to search for. * @return found element or null. * @throws IllegalArgumentException if CSS class parameter is null or empty. */ Element getByCssClass(String cssClass); /** * Find elements by CSS class. Retrieve elements possessing given CSS class. Returns empty list if given CSS class is null * or empty or there is no element with such CSS class. * * @param cssClass CSS class to search for. * @return list of found elements, possible empty. * @throws IllegalArgumentException if CSS class parameter is null or empty. */ EList findByCssClass(String cssClass); /** * Get element by attribute name and optional value. Retrieve first element possessing requested attribute. Returns null if * there is no element with requested attribute name and value, if present. * * @param name attribute name, * @param value optional attribute value. * @return found element or null. * @throws IllegalArgumentException if attribute name parameter is null or empty. */ Element getByAttr(String name, String... value); /** * Get the list of document elements having requested attribute. Requested attribute is identified by its name and optional * by its value. Returns empty list if there is no element with requested attribute. * * @param name attribute name, * @param value optional attribute value. * @return found element or null. * @throws IllegalArgumentException if attribute name parameter is null or empty. */ EList findByAttr(String name, String... value); /** * Serialize this document to standard output. */ void dump(); /** * Serialize this document and optionally close destination writer. Serialize this document to given writer. If optional * closeWriter flag is present and is true closes destination writer after serialization completes. * * @param writer destination writer, * @param closeWriter optional flag, if true close destination writer. * @throws IOException if writing operation fails. */ void serialize(Writer writer, boolean... closeWriter) throws IOException; }





© 2015 - 2025 Weber Informatics LLC | Privacy Policy