001: /* Attributable.java
002:
003: {{IS_NOTE
004:
005: Purpose:
006: Description:
007: History:
008: C2001/10/23 12:38:28, reate, Tom M. Yeh
009: }}IS_NOTE
010:
011: Copyright (C) 2001 Potix Corporation. All Rights Reserved.
012:
013: {{IS_RIGHT
014: This program is distributed under GPL Version 2.0 in the hope that
015: it will be useful, but WITHOUT ANY WARRANTY.
016: }}IS_RIGHT
017: */
018: package org.zkoss.idom;
019:
020: import java.util.List;
021:
022: /**
023: * Represents a class that has attributes.
024: * It is usually implemented by a class that also implements Item or Group.
025: * Currently, only Element implements it.
026: *
027: * <p>Design consideration: Be as similar to Group as possible.
028: *
029: * @author tomyeh
030: * @see Item
031: * @see Attribute
032: */
033: public interface Attributable {
034: /**
035: * Returns all attributes of this object.
036: *
037: * <p>The returned list is "live". Any modification to it affects
038: * the object that owns the attributes.
039: *
040: * <p>If the new added attribute has the same tag name as
041: * that of any existent attribute, DOMException is thrown.
042: * Thus, it is, sometimes, more convenient to ue setAttribute.
043: *
044: * <p>Naming reason: we don't call it getAttributes() to avoid
045: * the name conflict with Node.getAttributes().
046: *
047: * @return an empty list if no attribute at all
048: */
049: public List getAttributeItems();
050:
051: /**
052: * Gets the index of the first attribute that matches
053: * the specified criteria.
054: *
055: * @param indexFrom the index to start searching from; 0 for beginning
056: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
057: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
058: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
059: * the tag name if FIND_BY_TAGNAME specified; null to ignore
060: * @param mode the serach mode; zero or any combination of Item.FIND_xxx
061: * @return the index if found; -1 if not found
062: */
063: public int getAttributeIndex(int indexFrom, String namespace,
064: String name, int mode);
065:
066: /**
067: * Gets the index of the attribute with the giving local name.
068: *
069: * @param indexFrom the index to start searching from; 0 for beginning
070: * @param tname the tag name (i.e., {@link Attribute#getName}) --
071: * consists of the prefix and the local name
072: * @return the index if found; -1 if not found
073: */
074: public int getAttributeIndex(int indexFrom, String tname);
075:
076: /**
077: * Gets the value of the first attribute that matches
078: * the giving criteria, or null if not found.
079: *
080: * <p>According to Section 3.3.3 of XML 1.0 spec, the value is normalized,
081: * including trimmed.
082: *
083: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
084: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
085: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
086: * the tag name if FIND_BY_TAGNAME specified; null to ignore
087: * @return the value of the attribute; null if not found
088: */
089: public String getAttributeValue(String namespace, String name,
090: int mode);
091:
092: /** Returns the value of the attribute of the specified tag name,
093: * or null if not specified.
094: *
095: * <p>Note: unlike W3C's getAttribute, which returns empty if not specified,
096: * this method returns null if not specified.
097: */
098: public String getAttributeValue(String tname);
099:
100: /**
101: * Gets the first attribute that matches the specified criteria.
102: *
103: * <p>The name is a bit strange because we have to avoid name conflicts
104: * with org.w3c.dom.Node.
105: *
106: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
107: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
108: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
109: * the tag name if FIND_BY_TAGNAME specified; null to ignore
110: * @param mode the serach mode; zero or any combination of Item.FIND_xxx
111: * @return the index if found; -1 if not found
112: */
113: public Attribute getAttributeItem(String namespace, String name,
114: int mode);
115:
116: /**
117: * Gets the attribute with the tag name.
118: *
119: * <p>The name is a bit strange because we have to avoid name conflicts
120: * with org.w3c.dom.Node.
121: *
122: * @param tname the tag name (i.e., {@link Attribute#getName}) --
123: * consists of the prefix and the local name
124: * @return null if not found
125: */
126: public Attribute getAttributeItem(String tname);
127:
128: /**
129: * Gets a list of attributes of the specified criteria.
130: *
131: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
132: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
133: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
134: * the tag name if FIND_BY_TAGNAME specified; null to ignore
135: * @param mode the serach mode; zero or any combination of Item.FIND_xxx
136: * @return null if not found
137: */
138: public List getAttributes(String namespace, String name, int mode);
139:
140: /**
141: * Adds the giving attribute.
142: * If there is any existent one with the same tag name,
143: * it will be replaced. If not, the new attribute will be appended.
144: *
145: * @param attr the new attribute to add
146: * @return the attribute being replaced; null if no one is replaced
147: */
148: public Attribute setAttribute(Attribute attr);
149:
150: /**
151: * Sets the value of the attribute with the giving tag name.
152: * If the attribute doesn't exist, a new attribute will be created
153: * and added.
154: *
155: * <p>Note: it looks similar to Attribute(String, String), <i>but</i>
156: * this method requires the <i>tag</i> name.
157: *
158: * @param tname the tag name (i.e., Attribute.getName)
159: * @param value the new value.
160: * @return the attribute being replaced; null if no one is replaced
161: */
162: public Attribute setAttributeValue(String tname, String value);
163:
164: /** Returns whether it is aware of the modificatioin of attributes.
165: * If true, the modified flag is set if any of its attribute is modified.
166: * <p>Default: false.
167: */
168: public boolean isAttributeModificationAware();
169:
170: /** Sets whether it is aware of the modificatioin of attributes.
171: */
172: public void setAttributeModificationAware(boolean aware);
173: }
|