1. /*

  2.  * $Id: DocumentEx.java,v 1.1.1.1 2000/11/23 01:53:35 edwingo Exp $

  3.  *

  4.  * The Apache Software License, Version 1.1

  5.  *

  6.  *

  7.  * Copyright (c) 2000 The Apache Software Foundation.  All rights 

  8.  * reserved.

  9.  *

  10.  * Redistribution and use in source and binary forms, with or without

  11.  * modification, are permitted provided that the following conditions

  12.  * are met:

  13.  *

  14.  * 1. Redistributions of source code must retain the above copyright

  15.  *    notice, this list of conditions and the following disclaimer. 

  16.  *

  17.  * 2. Redistributions in binary form must reproduce the above copyright

  18.  *    notice, this list of conditions and the following disclaimer in

  19.  *    the documentation and/or other materials provided with the

  20.  *    distribution.

  21.  *

  22.  * 3. The end-user documentation included with the redistribution,

  23.  *    if any, must include the following acknowledgment:  

  24.  *       "This product includes software developed by the

  25.  *        Apache Software Foundation (http://www.apache.org/)."

  26.  *    Alternately, this acknowledgment may appear in the software itself,

  27.  *    if and wherever such third-party acknowledgments normally appear.

  28.  *

  29.  * 4. The names "Crimson" and "Apache Software Foundation" must

  30.  *    not be used to endorse or promote products derived from this

  31.  *    software without prior written permission. For written 

  32.  *    permission, please contact apache@apache.org.

  33.  *

  34.  * 5. Products derived from this software may not be called "Apache",

  35.  *    nor may "Apache" appear in their name, without prior written

  36.  *    permission of the Apache Software Foundation.

  37.  *

  38.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

  39.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

  40.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

  41.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR

  42.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  43.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  44.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

  45.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

  46.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

  47.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

  48.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  49.  * SUCH DAMAGE.

  50.  * ====================================================================

  51.  *

  52.  * This software consists of voluntary contributions made by many

  53.  * individuals on behalf of the Apache Software Foundation and was

  54.  * originally based on software copyright (c) 1999, Sun Microsystems, Inc., 

  55.  * http://www.sun.com.  For more information on the Apache Software 

  56.  * Foundation, please see <http://www.apache.org/>.

  57.  */

  58. 

  59. package org.apache.crimson.tree;

  60. 

  61. import java.util.Locale;

  62. 

  63. import org.w3c.dom.Document;

  64. import org.w3c.dom.Node;

  65. 

  66. 

  67. /**

  68.  * This interface extends the DOM Document model in several useful ways.

  69.  * It supports:  <UL>

  70.  *

  71.  * <LI> Application-specialized element creation and document customization

  72.  *	at parse time;

  73.  * <LI> Document printing;

  74.  * <LI> The URI with which the document is associated;

  75.  * <LI> Access to elements by their XML "ID" attributes (when the

  76.  *	document was constructed with an appropriate XML parser);

  77.  * <LI> Application-level control over the language in which

  78.  *      diagnostics are provided (useful for multi-language applications

  79.  *	such as servers);

  80.  * <LI> Moving nodes between DOM Documents.  (DOM Level 1 only talks

  81.  *	about nodes that are coupled to a single DOM document.)

  82.  *

  83.  * </UL>

  84.  *

  85.  *

  86.  * @author David Brownell

  87.  * @version $Revision: 1.1.1.1 $

  88.  */

  89. public interface DocumentEx extends Document, XmlWritable, ElementFactory

  90. {

  91.     /**

  92.      * Returns the system ID (a URI) associated with the document,

  93.      * or null if this is unknown.

  94.      */

  95.     public String getSystemId ();

  96. 

  97. 

  98.     /**

  99.      * Assigns the element factory to be used by this document.

  100.      */

  101.     public void setElementFactory (ElementFactory factory);

  102. 

  103. 

  104.     /**

  105.      * Returns the element factory to be used by this document.

  106.      */

  107.     public ElementFactory getElementFactory ();

  108. 

  109. 

  110.     /**

  111.      * Returns the element whose ID is given by the parameter; or null

  112.      * if no such element is known.  Element IDs are declared by

  113.      * attributes of type "ID", and are commonly used for internal

  114.      * linking by using attributes of type IDREF or IDREFS to turn

  115.      * XML's hierarchical data structure into a directed graph.

  116.      *

  117.      * <P> Note that DOM itself provides no way to identify which element

  118.      * attributes are declared with the "ID" attribute type.  This feature

  119.      * relies on interfaces which may not be publicly exposed, such as

  120.      * XML processors telling a DOM builder about those attributes.

  121.      *

  122.      * @param id The value of the ID attribute which will be matched

  123.      *	by any element which is returned. 

  124.      * @deprecated  As of DOM level 2, replaced by the method

  125.      *              Document.getElementById

  126.      */

  127.     // Note:  HTML DOM has getElementById() with "Element" return type

  128.     public ElementEx getElementExById (String id);

  129. 

  130. 

  131.     /**

  132.      * Returns the locale to be used for diagnostic messages.

  133.      */

  134.     public Locale	getLocale ();

  135. 

  136. 

  137.     /**

  138.      * Assigns the locale to be used for diagnostic messages.

  139.      * Multi-language applications, such as web servers dealing with

  140.      * clients from different locales, need the ability to interact

  141.      * with clients in languages other than the server's default.

  142.      * When a Document is created, its locale is the default

  143.      * locale for the virtual machine.

  144.      *

  145.      * @see #chooseLocale

  146.      */

  147.     public void	setLocale (Locale locale);

  148. 

  149. 

  150.     /**

  151.      * Chooses a client locale to use for diagnostics, using the first

  152.      * language specified in the list that is supported by this DOM

  153.      * implementation. That locale is then automatically assigned using <a

  154.      * href="#setLocale(java.util.Locale)">setLocale()</a>.  Such a list

  155.      * could be provided by a variety of user preference mechanisms,

  156.      * including the HTTP <em>Accept-Language</em> header field.

  157.      *

  158.      * @see org.apache.crimson.util.MessageCatalog

  159.      *

  160.      * @param languages Array of language specifiers, ordered with the most

  161.      *	preferable one at the front.  For example, "en-ca" then "fr-ca",

  162.      *  followed by "zh_CN".  Both RFC 1766 and Java styles are supported.

  163.      * @return The chosen locale, or null.

  164.      */

  165.     public Locale chooseLocale (String languages []);

  166. 

  167. 

  168.     /**

  169.      * Changes the "owner document" of the given node, and all child

  170.      * and associated attribute nodes, to be this document.  If the

  171.      * node has a parent, it is first removed from that parent.

  172.      * 

  173.      * @param node the node whose "owner" will be changed.

  174.      * @exception DOMException WRONG_DOCUMENT_ERROR when attempting

  175.      *	to change the owner for some other DOM implementation<P>

  176.      *	HIERARCHY_REQUEST_ERROR when the node is a document, document

  177.      *	type, entity, or notation; or when it is an attribute associated

  178.      *  with an element whose owner is not being (recursively) changed.

  179.      */

  180.     public void changeNodeOwner (Node node);

  181. }