001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.directory;
019:
020: import java.io.Serializable;
021: import javax.naming.NamingEnumeration;
022: import javax.naming.NamingException;
023: import javax.naming.directory.DirContext;
024:
025: /**
026: * This interface defines the valid operations on a particular attribute of a
027: * directory entry.
028: * <p>
029: * An attribute can have zero or more values. The value may be null.
030: * </p>
031: * <p>
032: * When there are multiple values for a particular attribute, the collection of
033: * values may be specifically ordered or unordered. This interface provides a
034: * method for determining whether the order is maintained.
035: * </p>
036: * <p>
037: * If the values of an attribute are ordered, then duplicates are allowed. If
038: * the values are unordered then duplicates are not allowed.
039: * </p>
040: * <p>
041: * If the values are unordered then the indexed operations work as if the values
042: * added previously to the attribute had been done using ordered semantics. For
043: * example, if the values "a", "b" and "c" were previously added to an unordered
044: * attribute using "<code>add("a"); add("b"); add("c");</code>", it is
045: * equivalent to adding the same objects to an ordered attribute using "<code>add(0,"a"); add(1,"b"); add(2,"c");</code>".
046: * In this case, if we do "<code>remove(1)</code>" on the unordered list,
047: * the value "b" is removed, changing the index of "c" to 1.
048: * </p>
049: * <p>
050: * Multiple null values can be added to an attribute. It is not the same as
051: * having no values on an attribute. If a null value is added to an unordered
052: * attribute which already has a null value, the <code>add</code> method has
053: * no effect.
054: * </p>
055: * <p>
056: * A directory may optionally provide information about the syntax of an
057: * attribute's value via a schema. The methods
058: * <code>getAttributeDefinition</code> and
059: * <code>getAttributeSyntaxDefinition</code> return the schema definitions if
060: * they exist.
061: * </p>
062: * <p>
063: * Note that updates to the attribute via this interface do not affect the
064: * directory directly. The only mechanism for modifying the directory is through
065: * the {@link DirContext}.
066: * </p>
067: * <p>
068: * Concrete implementations of this <code>Attribute</code> interface may be
069: * either static or dynamic, and this interface does not make any distinction
070: * between the two types. A static attribute implementation retrieves its value
071: * from the directory once and stores it locally, a dynamic attribute
072: * implementation will go back to the directory for each request.
073: * </p>
074: */
075: public interface Attribute extends Cloneable, Serializable {
076:
077: /*
078: * This constant is used during deserialization to check the version which
079: * created the serialized object.
080: */
081: static final long serialVersionUID = 0x78d7ee3675a55244L;
082:
083: /**
084: * Adds a value at the specified index. The index is only meaningful if the
085: * values are ordered. If there are already values at this index and above,
086: * they are moved up one position.
087: * <p>
088: * It is permissible to use this method when the values are not ordered but
089: * in this case, if a value equals to <code>val</code> already exists then
090: * this method throws an <code>IllegalStateException</code> because
091: * duplicates are not allowed.
092: * </p>
093: * <p>
094: * The permitted range for index is 0 <= index <= <code>size()</code>.
095: * The range allows the list to grow by one. If the index is outside this
096: * range this method throws an <code>IndexOutOfBoundsException</code>.
097: * </p>
098: *
099: * @param index
100: * the position index
101: * @param val
102: * a new value to be added which may be null
103: * @throws IllegalStateException
104: * If the new value equals to an existing value in an unordered
105: * <code>Attribute</code>.
106: * @throws IndexOutOfBoundsException
107: * If the index is invalid.
108: */
109: void add(int index, Object val);
110:
111: /**
112: * Adds a value to this attribute. For unordered attribute values this
113: * method adds the new value unless the value is already present. If the new
114: * value is already present in unordered attribute values, the method has no
115: * effect.
116: * <p>
117: * For ordered attribute values, the new value is added at the end of list
118: * of values.
119: * </p>
120: * <p>
121: * This method returns true or false to indicate whether a value was added.
122: * </p>
123: *
124: * @param val
125: * a new value to be added which may be null
126: * @return true if a value was added, otherwise false
127: */
128: boolean add(Object val);
129:
130: /**
131: * Clears all values of this attribute.
132: */
133: void clear();
134:
135: /**
136: * Returns a deep copy of the attribute containing all the same values. The
137: * values are not cloned.
138: *
139: * @return a deep clone of this attribute
140: */
141: Object clone();
142:
143: /**
144: * Indicates whether the specified value is one of the attribute's values.
145: *
146: * @param val
147: * the value which may be null
148: * @return true if this attribute contains the value, otherwise false
149: */
150: boolean contains(Object val);
151:
152: /**
153: * Gets a value of this attribute. For unordered values, returns any of the
154: * values. For ordered values, returns the first. <code>null</code> is a
155: * valid value.
156: * <p>
157: * If the attribute has no values this method throws
158: * <code>NoSuchElementException</code>.
159: * </p>
160: *
161: * @return a value of this attribute
162: * @throws NamingException
163: * If the attribute has no value.
164: */
165: Object get() throws NamingException;
166:
167: /**
168: * Returns the value at the specified index, even for unordered values. This
169: * method throws <code>IndexOutOfBoundsException</code> if the index is
170: * outside the valid range 0 <= index < <code>size()</code>.
171: *
172: * <p>
173: * If the attribute has no values this method throws
174: * <code>NoSuchElementException</code>.
175: * </p>
176: *
177: * @param index
178: * the position index
179: * @return the value at the specified index
180: * @throws IndexOutOfBoundsException
181: * If the index is invalid.
182: * @throws NamingException
183: * If the attribute has no value.
184: */
185: Object get(int index) throws NamingException;
186:
187: /**
188: * Returns an enumeration of all the attribute's values. The enumeration is
189: * ordered if the values are.
190: * <p>
191: * The effect on the returned enumeration of adding or removing values of
192: * the attribute is not specified.
193: * </p>
194: * <p>
195: * This method will throw any <code>NamingException</code> that occurs.
196: * </p>
197: *
198: * @return an enumeration of all values of the attribute
199: * @throws NamingException
200: * If any <code>NamingException</code> occurs.
201: */
202: NamingEnumeration<?> getAll() throws NamingException;
203:
204: /**
205: * Returns the attribute's schema definition. If this operation is not
206: * supported, an <code>
207: * OperationNotSupportedException</code> is thrown. If
208: * the implementation supports schemas but no schema is set, it is valid to
209: * return null.
210: * <p>
211: * This method will throw any <code>NamingException</code> that occurs.
212: * </p>
213: *
214: * @return the schema definitions if they exist
215: * @throws NamingException
216: * If any <code>NamingException</code> occurs.
217: */
218: DirContext getAttributeDefinition() throws NamingException;
219:
220: /**
221: * Returns the attribute's syntax definition. If this operation is not
222: * supported, an <code>
223: * OperationNotSupportedException</code> is thrown. If
224: * the implementation supports syntax definitions but no syntax definition
225: * is set, it is valid to return null.
226: * <p>
227: * This method will throw any <code>NamingException</code> that occurs.
228: * </p>
229: *
230: * @return the syntax definitions if they exist
231: * @throws NamingException
232: * If any <code>NamingException</code> occurs.
233: */
234: DirContext getAttributeSyntaxDefinition() throws NamingException;
235:
236: /**
237: * Returns the identity of this attribute. This method is not expected to
238: * return null.
239: *
240: * @return the ID of this attribute
241: */
242: String getID();
243:
244: /**
245: * Indicates whether the values of this attribute are ordered or not.
246: *
247: * @return true if the values of this attribute are ordered, otherwise false
248: */
249: boolean isOrdered();
250:
251: /**
252: * Removes the values at the specified index, even for unordered values.
253: * Values at higher indexes move one position lower.
254: * <p>
255: * If the index is outside the valid range 0 <= index <
256: * <code>size()</code> this method throws an
257: * <code>IndexOutOfBoundsException</code>.
258: * </p>
259: *
260: * @param index
261: * the position index
262: * @return the removed value
263: * @throws IndexOutOfBoundsException
264: * If the index is invalid.
265: */
266: Object remove(int index);
267:
268: /**
269: * Removes a value that is equal to the given value. There may be more than
270: * one match in ordered value, in which case the equal value with the lowest
271: * index is removed. After an ordered value is removed, values at higher
272: * indexes move one position lower.
273: * <p>
274: * Returns true if a value is removed. If there is no value equal to <code>
275: * val</code>
276: * this method simply returns false.
277: * </p>
278: *
279: * @param val
280: * the value to be removed
281: * @return true if the value is removed, otherwise false
282: */
283: boolean remove(Object val);
284:
285: /**
286: * Replaces the value at the specified index with the given value. The old
287: * value (which may be null) is returned.
288: * <p>
289: * If the values are unordered and the given value is already present this
290: * method throws an <code>IllegalStateException</code>.
291: * </p>
292: * <p>
293: * The valid range for the index is 0 <= index < <code>size()</code>.
294: * This method throws an <code>IndexOutOfBoundsException</code> if the
295: * index is outside this range.
296: * </p>
297: *
298: * @param index
299: * the position index
300: * @param val
301: * the new value
302: * @return the original value at the specified index
303: * @throws IndexOutOfBoundsException
304: * If the index is invalid.
305: */
306: Object set(int index, Object val);
307:
308: /**
309: * Gets the count of the values in this attribute.
310: *
311: * @return the count of the values in this attribute
312: */
313: int size();
314:
315: }
|