KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jdom > contrib > ids > IdDocument


1 /*--
2
3  $Id: IdDocument.java,v 1.2 2004/02/06 09:57:48 jhunter Exp $
4
5  Copyright (C) 2001-2004 Jason Hunter & Brett McLaughlin.
6  All rights reserved.
7
8  Redistribution and use in source and binary forms, with or without
9  modification, are permitted provided that the following conditions
10  are met:
11
12  1. Redistributions of source code must retain the above copyright
13     notice, this list of conditions, and the following disclaimer.
14
15  2. Redistributions in binary form must reproduce the above copyright
16     notice, this list of conditions, and the disclaimer that follows
17     these conditions in the documentation and/or other materials
18     provided with the distribution.
19
20  3. The name "JDOM" must not be used to endorse or promote products
21     derived from this software without prior written permission. For
22     written permission, please contact <request_AT_jdom_DOT_org>.
23
24  4. Products derived from this software may not be called "JDOM", nor
25     may "JDOM" appear in their name, without prior written permission
26     from the JDOM Project Management <request_AT_jdom_DOT_org>.
27
28  In addition, we request (but do not require) that you include in the
29  end-user documentation provided with the redistribution and/or in the
30  software itself an acknowledgement equivalent to the following:
31      "This product includes software developed by the
32       JDOM Project (http://www.jdom.org/)."
33  Alternatively, the acknowledgment may be graphical using the logos
34  available at http://www.jdom.org/images/logos.
35
36  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
40  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  SUCH DAMAGE.
48
49  This software consists of voluntary contributions made by many
50  individuals on behalf of the JDOM Project and was originally
51  created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
52  Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
53  on the JDOM Project, please see <http://www.jdom.org/>.
54
55  */
56
57 package org.jdom.contrib.ids;
58
59 import java.util.*;
60
61 import org.jdom.Document;
62 import org.jdom.DocType;
63 import org.jdom.Element;
64
65
66 /**
67  * IdDocument extends the default JDOM document to support looking
68  * up elements using their ID attribute.
69  * <p>
70  * Instances of this class should not be created directly but through
71  * the {@link IdFactory}. Using this factory ensures that the
72  * document is made of {@link IdElement} instances which update the
73  * look-up table when the element attribute list is updated.</p>
74  * <p>
75  * The method {@link #getElementById} allows looking up an element
76  * in the document given the value of its ID attribute. Instead of
77  * scanning the whole document when searching for an element,
78  * <code>IdDocument</code> uses a lookup table for fast direct
79  * access to the elements. Hence, applications using this method
80  * should see their performances improved compared to walking the
81  * document tree.</p>
82  *
83  * @author Laurent Bihanic
84  */
85 public class IdDocument extends Document {
86
87    /**
88     * <p>The ID lookup table for the document.</p>
89     */
90    private Map ids = new HashMap();
91
92    /**
93     * <p>
94     * Creates a new <code>IdDocument</code>, with the supplied
95     * <code>{@link Element}</code> as the root element and the
96     * supplied <code>{@link DocType}</code> declaration.</p>
97     *
98     * @param rootElement <code>Element</code> for document root.
99     * @param docType <code>DocType</code> declaration.
100     */
101    public IdDocument(Element root, DocType docType) {
102       super(root, docType);
103    }
104
105    /**
106     * <p>
107     * Creates a new <code>Document</code>, with the supplied
108     * <code>{@link Element}</code> as the root element, and no
109     * <code>{@link DocType document type}</code> declaration.
110     * </p>
111     *
112     * @param rootElement <code>Element</code> for document root.
113     */
114    public IdDocument(Element root) {
115       super(root);
116    }
117
118    /**
119     * <p>
120     * Retrieves an element using the value of its ID attribute as
121     * key.</p>
122     *
123     * @param id the value of the ID attribute of the element to
124     * retrieve.
125     * @return the <code>Element</code> associated to <code>id</code>
126     * or <code>null</code> if none was found.
127     */
128    public Element getElementById(String JavaDoc id) {
129       return ((Element)(ids.get(id)));
130    }
131
132    /**
133     * <p>
134     * Adds the specified ID to the ID lookup table of this document
135     * and make it point to the associated element.</p>
136     *
137     * @param id the ID to add.
138     * @param elt the <code>Element</code> associated to the ID.
139     */
140    protected void addId(String JavaDoc id, Element elt) {
141       ids.put(id, elt);
142       return;
143    }
144
145    /**
146     * <p>
147     * Removes the specified ID from the ID lookup table of this
148     * document.</p>
149     *
150     * @param id the ID to remove.
151     * @return <code>true</code> if the ID was found and removed;
152     * <code>false</code> otherwise.
153     */
154    protected boolean removeId(String JavaDoc id) {
155       return (ids.remove(id) != null);
156    }
157 }
158
159
Popular Tags