XOM API for Processing XML with Java

[Mik Lernout <mik AT futurestreet.org>]

Hmm, allow me to disagree :-)

I like the type safety of the Nodes and Elements (really enjoyed your 
interview on Artima describing that by the way) but why could they not 
be implemented at the same time, for example by adding an iterator() on 
the Elements and the Nodes-classes, like in the attachment I send with 
this mail. It would not alter the type safetyness and, at the same time, 
allow access to the list in a Collections - standard way.

As for the Attributes argument: why is there getAttributeCount() and a 
getAttribute(int index) if you would only get them by name? I don't see 
the difference between Elements and Attributes: probably most people 
will use the getChildElements(name) and getAttribute(name), but we still 
need to provide access to the list of these items, in a clean way. If 
you would expose the Attributes you would bring down the number of 
methods on Element, standardize to calling a 'count' a 'size' everywhere 
and allow for another type safe "value-ish" object to interface with.

Mik

PS: While reviewing my mail I thought I'd add that referring to child 
elements without using their name is probably a bit more common than 
doing the same with attributes but what the heck: the arguments remain 
valid.

Elliotte Rusty Harold wrote:

> > Dear all,
> >
> > I just encountered two rather noizy thingies in the XOM API:
> >
> >    * Why doesn't Elements and Nodes implement List? It would make it a
> >      lot easier to introduce XOM in current scripting languages (think
> >      JSTL / velocity / FreeMarker / .. ) and would give an
> >      instantanious familiar interface to novice programmers. I can
> >      understand the 'no two ways to do the same thing '-principle, but
> >      that does not really count here, does it... just a thought...
>
>
> List is insufficiently type-safe. The while collections API is. I 
> don't consider List to be appropriate for cases where you know the 
> types of the nodes. That is, the Object type should not be used when 
> you know the result is an Element.
>
> >    * Why is there no Attributes? The |*getAttributeCount
> >
> > <http://www.cafeconleche.org/XOM/apidocs/nu/xom/Element.html#getAttributeCount%28%29>*()| 
> >
> >      and |*getAttribute
> >
> > <http://www.cafeconleche.org/XOM/apidocs/nu/xom/Element.html#getAttribute%28int%29>*(int 
> > index)|
> >      feel awkward and unnatural compared to Elements and Nodes.
> >
> > I don't know what you guys think of this, but for me the first item 
> > is already a critical factor in using/not-usingXOM for my currenct 
> > project...
>
>
>
> There is an Attributes class but it's not public. I don't think 
> iterating through all the attributes of an element is very common. 
> It's more common to ask for a specific attribute by name.


// Copyright 2002, 2003 Elliotte Rusty Harold
// 
// This library is free software; you can redistribute 
// it and/or modify it under the terms of version 2.1 of 
// the GNU Lesser General Public License as published by  
// the Free Software Foundation.
// 
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
// GNU Lesser General Public License for more details.
// 
// You should have received a copy of the GNU Lesser General 
// Public License along with this library; if not, write to the 
// Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
// Boston, MA  02111-1307  USA
// 
// You can contact Elliotte Rusty Harold by sending e-mail to
// elharo AT metalab.unc.edu. Please include the word "XOM" in the
// subject line. The XOM home page is temporarily located at
// http://www.cafeconleche.org/XOM/  but will eventually move
// to http://www.xom.nu/

package nu.xom;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.ListIterator;

/**
 * 
 * <p>
 * Implements a read-only list of elements for traversal purposes.
 * Changes to the document from which this list was generated
 * are not reflected in this list. Changes to the individual 
 * <code>Element</code> objects in the list are reflected.
 * </p>
 * 
 * @author Elliotte Rusty Harold
 * @version 1.0d13
 * 
 *
 */
public final class Elements {

    
    private List elements = new ArrayList(1);
    
    // non-public constructor to prevent instantiation
    Elements() {}
    
    /**
     * <p>
     * Returns the number of elements in the list.
     * This is guaranteed non-negative. 
     * </p>
     * 
     * @return the number of elements in the list
     */
    public int size() {
        return elements.size(); 
    }
    
    /**
     * <p>
     * Returns the index<sup>th</sup> element in the list.
     * The first element has index 0. The last element
     * has index <code>size()-1</code>.
     * </p>
     * 
     * @param index the element to return
     * 
     * @return the element at the specified position
     * 
     * @throws IndexOutOfBoundsException if index is negative 
     *     or greater than or equal to the size of the list
     */
    public Element get(int index) {
        return (Element) elements.get(index);   
    }
    
    
    // Add the specified Element object to the list
    void add(Element element) {
        elements.add(element);
    }
    
    public Iterator getIterator(){
        return new ElementsIterator(this);
    }    
    
    private class ElementsIterator implements Iterator{
        
        private Iterator innerIterator;
        
        private ElementsIterator(Elements innerElements){
                innerIterator = innerElements.elements.listIterator();
        }


                /* 
                 * @see java.util.Iterator#hasNext()
                 */
                public boolean hasNext() {
                        return innerIterator.hasNext();
                }

                /* 
                 * @see java.util.Iterator#next()
                 */
                public Object next() {
                        return innerIterator.next();
                }

                /* 
                 * @see java.util.Iterator#remove()
                 */
                public void remove() {
                        innerIterator.remove();
                }

    }

}