zkoss/zk

/* Attributable.java


Purpose: 
Description: 
History:
C2001/10/23 12:38:28, reate, Tom M. Yeh

Copyright (C) 2001 Potix Corporation. All Rights Reserved.

{{IS_RIGHT
    This program is distributed under LGPL Version 2.1 in the hope that
    it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/
package org.zkoss.idom;

import java.util.List;

/**
 * Represents a class that has attributes.
 * It is usually implemented by a class that also implements Item or Group.
 * Currently, only Element implements it.
 *
 * <p>Design consideration: Be as similar to Group as possible.
 *
 * @author tomyeh
 * @see Item
 * @see Attribute
 */
public interface Attributable {
    /**
     * Returns all attributes of this object.
     *
     * <p>The returned list is "live". Any modification to it affects
     * the object that owns the attributes.
     *
     * <p>If the new added attribute has the same tag name as
     * that of any existent attribute, DOMException is thrown.
     * Thus, it is, sometimes, more convenient to ue setAttribute.
     *
     * <p>Naming reason: we don't call it getAttributes() to avoid
     * the name conflict with Node.getAttributes().
     *
     * @return an empty list if no attribute at all
     */
    public List<Attribute> getAttributeItems();

    /**
     * Gets the index of the first attribute that matches
     * the specified criteria.
     *
     * @param indexFrom the index to start searching from; 0 for beginning
     * @param namespace the namespace URI if FIND_BY_PREFIX is not specified;
     * the namespace prefix if FIND_BY_PREFIX specified; null to ignore
     * @param name the local name if FIND_BY_TAGNAME is not specified;
     * the tag name if FIND_BY_TAGNAME specified; null to ignore
     * @param mode the search mode; zero or any combination of Item.FIND_xxx
     * @return the index if found; -1 if not found
     */
    public int
    getAttributeIndex(int indexFrom, String namespace, String name, int mode);
    /**
     * Gets the index of the attribute with the giving local name.
     *
     * @param indexFrom the index to start searching from; 0 for beginning
     * @param tname the tag name (i.e., {@link Attribute#getName}) --
     * consists of the prefix and the local name
     * @return the index if found; -1 if not found
     */
    public int getAttributeIndex(int indexFrom, String tname);

    /**
     * Gets the value of the first attribute that matches
     * the giving criteria, or null if not found.
     *
     * <p>According to Section 3.3.3 of XML 1.0 spec, the value is normalized,
     * including trimmed.
     *
     * @param namespace the namespace URI if FIND_BY_PREFIX is not specified;
     * the namespace prefix if FIND_BY_PREFIX specified; null to ignore
     * @param name the local name if FIND_BY_TAGNAME is not specified;
     * the tag name if FIND_BY_TAGNAME specified; null to ignore
     * @return the value of the attribute; null if not found
     */
    public String getAttributeValue(String namespace, String name, int mode);
    /** Returns the value of the attribute of the specified tag name,
     * or null if not specified.
     *
     * <p>Note: unlike W3C's getAttribute, which returns empty if not specified,
     * this method returns null if not specified.
     */
    public String getAttributeValue(String tname);

    /**
     * Gets the first attribute that matches the specified criteria.
     *
     * <p>The name is a bit strange because we have to avoid name conflicts
     * with org.w3c.dom.Node.
     *
     * @param namespace the namespace URI if FIND_BY_PREFIX is not specified;
     * the namespace prefix if FIND_BY_PREFIX specified; null to ignore
     * @param name the local name if FIND_BY_TAGNAME is not specified;
     * the tag name if FIND_BY_TAGNAME specified; null to ignore
     * @param mode the search mode; zero or any combination of Item.FIND_xxx
     * @return the index if found; -1 if not found
     */
    public Attribute getAttributeItem(String namespace, String name, int mode);
    /**
     * Gets the attribute with the tag name.
     *
     * <p>The name is a bit strange because we have to avoid name conflicts
     * with org.w3c.dom.Node.
     *
     * @param tname the tag name (i.e., {@link Attribute#getName}) --
     * consists of the prefix and the local name
     * @return null if not found
     */    
    public Attribute getAttributeItem(String tname);

    /**
     * Gets a list of attributes of the specified criteria.
     *
     * @param namespace the namespace URI if FIND_BY_PREFIX is not specified;
     * the namespace prefix if FIND_BY_PREFIX specified; null to ignore
     * @param name the local name if FIND_BY_TAGNAME is not specified;
     * the tag name if FIND_BY_TAGNAME specified; null to ignore
     * @param mode the search mode; zero or any combination of Item.FIND_xxx
     * @return null if not found
     */
    public List<Attribute> getAttributes(String namespace, String name, int mode);

    /**
     * Adds the giving attribute.
     * If there is any existent one with the same tag name,
     * it will be replaced. If not, the new attribute will be appended.
     *
     * @param attr the new attribute to add
     * @return the attribute being replaced; null if no one is replaced
     */
    public Attribute setAttribute(Attribute attr);
    /**
     * Sets the value of the attribute with the giving tag name.
     * If the attribute doesn't exist, a new attribute will be created
     * and added.
     *
     * <p>Note: it looks similar to Attribute(String, String), <i>but</i>
     * this method requires the <i>tag</i> name.
     *
     * @param tname the tag name (i.e., Attribute.getName)
     * @param value the new value.
     * @return the attribute being replaced; null if no one is replaced
     */
    public Attribute setAttributeValue(String tname, String value);
}