001/*
002 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
003 * 
004 * This software is open source. 
005 * See the bottom of this file for the licence.
006 * 
007 * $Id: ElementPath.java,v 1.1 2001/05/18 18:32:56 drwhite Exp $
008 */
009
010package org.dom4j;
011
012/** This interface is used by {@link ElementHandler} instances to
013  * retrieve information about the current path hierarchy they
014  * are to process.  It's primary use is to retrieve the current
015  * {@link Element} being processed.
016  *
017  * @author <a href="mailto:dwhite@equipecom.com">Dave White</a>
018  * @version $Revision: 1.1 $
019  */
020public interface ElementPath
021{
022    /** @return the number of elements in the path */
023    public int size();
024    
025    /** @return the element at the specified depth index, 0 = root element*/
026    public Element getElement(int depth);
027    
028    /** @return the path as a string */
029    public String getPath();
030    
031    /** @return the current element */
032    public Element getCurrent();
033    
034    /** Adds the <code>ElementHandler</code> to be called when the 
035      * specified path is encounted.  The path can be either an absolute
036      * path (i.e. prefixed with "/") or a relative path (i.e. assummed
037      * to be a child of the current path as retrieved by <b>getPath</b>.
038      *
039      * @param path is the path to be handled
040      * @param handler is the <code>ElementHandler</code> to be called
041      * by the event based processor.
042      */
043    public void addHandler(String path, ElementHandler handler);
044    
045    /** Removes the <code>ElementHandler</code> from the event based
046      * processor, for the specified path.  The path can be either an 
047      * absolute path (i.e. prefixed with "/") or a relative path 
048      * (i.e. assummed to be a child of the current path as retrieved 
049      * by <b>getPath</b>.
050      *
051      * @param path is the path to remove the <code>ElementHandler</code> for.
052      */
053    public void removeHandler(String path);
054}
055
056
057
058
059/*
060 * Redistribution and use of this software and associated documentation
061 * ("Software"), with or without modification, are permitted provided
062 * that the following conditions are met:
063 *
064 * 1. Redistributions of source code must retain copyright
065 *    statements and notices.  Redistributions must also contain a
066 *    copy of this document.
067 *
068 * 2. Redistributions in binary form must reproduce the
069 *    above copyright notice, this list of conditions and the
070 *    following disclaimer in the documentation and/or other
071 *    materials provided with the distribution.
072 *
073 * 3. The name "DOM4J" must not be used to endorse or promote
074 *    products derived from this Software without prior written
075 *    permission of MetaStuff, Ltd.  For written permission,
076 *    please contact dom4j-info@metastuff.com.
077 *
078 * 4. Products derived from this Software may not be called "DOM4J"
079 *    nor may "DOM4J" appear in their names without prior written
080 *    permission of MetaStuff, Ltd. DOM4J is a registered
081 *    trademark of MetaStuff, Ltd.
082 *
083 * 5. Due credit should be given to the DOM4J Project
084 *    (http://dom4j.org/).
085 *
086 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS
087 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
088 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
089 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
090 * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
091 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
092 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
093 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
094 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
095 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
096 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
097 * OF THE POSSIBILITY OF SUCH DAMAGE.
098 *
099 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
100 *
101 * $Id: ElementPath.java,v 1.1 2001/05/18 18:32:56 drwhite Exp $
102 */