1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32 package com.unitesk.atp.dynattrs;
33
34 import java.util.Set;
35
36 /***
37 * <P>Attributed object is a Java object decorated by attributes.
38 * Each attribute has a name and value.
39 * A name of an attribute is a string.
40 *
41 * <P>There are two kinds of attributes: simple and indexed attributes.
42 * Simple attribute has a single value that may be retrieved or modified.
43 * Indexed attribute is a list of values that can be accessed by integer index.
44 * Indexed attribute can be considered as simple.
45 * In this case a value of an attribute is an entire list.
46 *
47 * <P>For example, this interface can be implemented:
48 * <UL>
49 * <LI>Using JavaBeans naming convention to retrieve and modify attributes
50 * through <I>getter</I> and <I>setter</I> methods using reflection.
51 * </LI>
52 * <LI>Using map to store attribute's names and values to provide
53 * dynamic creation and removing of attributes.
54 * </LI>
55 * </UL>
56 *
57 * <P>TODO: add mapped attributes as in org.apache.commons.beanutils
58 *
59 * @author <A href="mailto:demakov@ispras.ru">Alexey Demakov</A>
60 * @version $Id: Attributed.java,v 1.1 2004/10/09 06:19:04 all-x Exp $
61 */
62 public interface Attributed
63 {
64 /***
65 * Checks existence of an attribute with the specified name.
66 *
67 * @param name The name of an attribute.
68 * @return <CODE>true</CODE> if there exists an attribute with
69 * the specified name, <CODE>false</CODE> otherwise.
70 * @throws NullPointerException
71 * If <CODE>name</CODE> is <CODE>null</CODE>.
72 */
73 boolean hasAttribute( String name );
74
75 /***
76 * Checks whether attributes may be created dynamically.
77 * The value of this property doesn't change during object life.
78 *
79 * @return <CODE>true</CODE> if attributes may be created
80 * dynamically, <CODE>false</CODE> otherwise.
81 */
82 boolean isAttrCreatable();
83
84 /***
85 * Checks whether an attribute with the specified name
86 * may be removed dynamically.
87 *
88 * @param name The name of an attribute.
89 * @return <CODE>true</CODE> if an attribute with
90 * the specified name may be removed dynamically,
91 * <CODE>false</CODE> otherwise.
92 * @throws AttributeException
93 * Some possible reasons:
94 * <UL>
95 * <LI><CODE>name == null</CODE></LI>
96 * <LI>there is no attribute with the specified name</LI>
97 * <LI>there was an underlying exception</LI>
98 * </UL>
99 * (analyze exception parameters).
100 * @see #hasAttribute(String)
101 */
102 boolean isRemovable( String name );
103
104 /***
105 * Checks whether a value of an attribute with the specified name
106 * may be changed.
107 *
108 * @param name The name of an attribute.
109 * @return <CODE>true</CODE> if a value of an attribute with
110 * the specified name may be changed,
111 * <CODE>false</CODE> otherwise.
112 * @throws AttributeException
113 * Some possible reasons:
114 * <UL>
115 * <LI><CODE>name == null</CODE></LI>
116 * <LI>there is no attribute with the specified name</LI>
117 * <LI>there was an underlying exception</LI>
118 * </UL>
119 * (analyze exception parameters).
120 * @see #hasAttribute(String)
121 */
122 boolean isWritable( String name );
123
124 /***
125 * Checks whether an attribute with the specified name may be indexed.
126 *
127 * @param name The name of an attribute
128 * @return <CODE>true</CODE> if a value of an attribute with
129 * the specified name may be indexed,
130 * <CODE>false</CODE> otherwise.
131 * @throws AttributeException
132 * Some possible reasons:
133 * <UL>
134 * <LI><CODE>name == null</CODE></LI>
135 * <LI>there is no attribute with the specified name</LI>
136 * <LI>there was an underlying exception</LI>
137 * </UL>
138 * (analyze exception parameters).
139 * @see #hasAttribute(String)
140 */
141 boolean isIndexed( String name );
142
143
144
145 /***
146 * Adds an attribute with the specified name and value.
147 *
148 * @param name The name of new attribute.
149 * @param value The value of new attribute.
150 * @throws UnsupportedOperationException
151 * if {link #isAttrCreatable()} returns <CODE>false</CODE>
152 * @throws AttributeException
153 * Some possible reasons:
154 * <UL>
155 * <LI><CODE>name == null</CODE></LI>
156 * <LI>there is attribute with the specified name already</LI>
157 * <LI>there was an underlying exception</LI>
158 * </UL>
159 * (analyze exception parameters).
160 * @see #hasAttribute(String)
161 */
162 void addAttribute( String name, Object value );
163
164 /***
165 * Removes an attribute with the specified name.
166 * If there is no attribute with the specified name nothing happens.
167 *
168 * @param name The name of an attribute.
169 * @throws UnsupportedOperationException
170 * if operation is not supported
171 * @throws AttributeException
172 * Some possible reasons:
173 * <UL>
174 * <LI><CODE>name == null</CODE></LI>
175 * <LI>the specified attribute is not removable</LI>
176 * <LI>there was an underlying exception</LI>
177 * </UL>
178 * (analyze exception parameters).
179 * @see #hasAttribute(String)
180 * @see #isRemovable(String)
181 */
182 void removeAttribute( String name );
183
184
185
186 /***
187 * Retrieves the value of a simple attribute with the specified name.
188 *
189 * @param name The name of an attribute.
190 * @return The value of an attribute.
191 * @throws AttributeException
192 * Some possible reasons:
193 * <UL>
194 * <LI><CODE>name == null</CODE></LI>
195 * <LI>there is no attribute with the specified name</LI>
196 * <LI>there was an underlying exception</LI>
197 * </UL>
198 * (analyze exception parameters).
199 * @see #hasAttribute(String)
200 */
201 Object getAttribute( String name );
202
203 /***
204 * Changes the value of a simple attribute with the specified name.
205 *
206 * @param name The name of an attribute.
207 * @param value The new value of an attribute.
208 * @throws AttributeException
209 * Some possible reasons:
210 * <UL>
211 * <LI><CODE>name == null</CODE></LI>
212 * <LI>there is no attribute with the specified name</LI>
213 * <LI>attribute type is not compatible with <CODE>value</CODE>
214 * <LI>there was an underlying exception</LI>
215 * </UL>
216 * (analyze exception parameters).
217 * @see #hasAttribute(String)
218 * @see #isWritable(String)
219 */
220 void setAttribute( String name, Object value );
221
222
223
224 /***
225 * Returns the size of an indexed attribute with the specified name.
226 *
227 * @param name The name of an indexed attribute.
228 * @return The size of an indexed attribute.
229 * @throws AttributeException
230 * Some possible reasons:
231 * <UL>
232 * <LI><CODE>name == null</CODE></LI>
233 * <LI>there is no attribute with the specified name</LI>
234 * <LI>attribute value is not indexed</LI>
235 * <LI>there was an underlying exception</LI>
236 * </UL>
237 * (analyze exception parameters).
238 * @see #hasAttribute(String)
239 * @see #isIndexed(String)
240 */
241 int sizeAttribute( String name );
242
243 /***
244 * Retrieves the value of the specified element of an indexed attribute
245 * with the specified name.
246 *
247 * @param name The name of an indexed attribute.
248 * @param index The index of an indexed attribute.
249 * @return The value of an attribute.
250 * @throws AttributeException
251 * Some possible reasons:
252 * <UL>
253 * <LI><CODE>name == null</CODE></LI>
254 * <LI>there is no attribute with the specified name</LI>
255 * <LI>attribute value is not indexed</LI>
256 * <LI>attribute index is out of bounds</LI>
257 * <LI>there was an underlying exception</LI>
258 * </UL>
259 * (analyze exception parameters).
260 * @see #hasAttribute(String)
261 * @see #isIndexed(String)
262 * @see #sizeAttribute(String)
263 */
264 Object getAttribute( String name, int index );
265
266 /***
267 * Changes the value of the specified element of an indexed attribute
268 * with the specified name.
269 *
270 * @param name The name of an indexed attribute.
271 * @param index The index of an indexed attribute.
272 * @param elem The new value of an element with the specified index.
273 * @throws AttributeException
274 * Some possible reasons:
275 * <UL>
276 * <LI><CODE>name == null</CODE></LI>
277 * <LI>there is no attribute with the specified name</LI>
278 * <LI>attribute is not writable</LI>
279 * <LI>attribute is not indexed</LI>
280 * <LI>attribute index is out of bounds</LI>
281 * <LI>attribute element type is not compatible with <CODE>elem</CODE></LI>
282 * <LI>there was an underlying exception</LI>
283 * </UL>
284 * (analyze exception parameters).
285 * @see #hasAttribute(String)
286 * @see #isWritable(String)
287 * @see #isIndexed(String)
288 * @see #sizeAttribute(String)
289 */
290 void setAttribute( String name, int index, Object elem );
291
292
293
294 /***
295 * Returns the names of all attributes.
296 *
297 * @return The set containing the names of all attributes.
298 * @see java.util.Map#keySet()
299 */
300 Set
301 }