Attribute


1   /*
2    * @(#)Attribute.java   1.12 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.naming.directory;
9   
10  import java.util.Vector  ;
11  import java.util.Enumeration  ;
12  import java.util.NoSuchElementException  ;
13  
14  import javax.naming.NamingException  ;
15  import javax.naming.NamingEnumeration  ;
16  import javax.naming.OperationNotSupportedException  ;
17  
18  /**
19    * This interface represents an attribute associated with a named object.
20    *<p>
21    * In a directory, named objects can have associated with them
22    * attributes.  The <tt>Attribute</tt> interface represents an attribute associated
23    * with a named object.  An attribute contains 0 or more, possibly null, values.
24    * The attribute values can be ordered or unordered (see <tt>isOrdered()</tt>).
25    * If the values are unordered, no duplicates are allowed.
26    * If the values are ordered, duplicates are allowed.
27    *<p>
28    * The content and representation of an attribute and its values is defined by
29    * the attribute's <em>schema</em>. The schema contains information
30    * about the attribute's syntax and other properties about the attribute.
31    * See <tt>getAttributeDefinition()</tt> and
32    * <tt>getAttributeSyntaxDefinition()</tt>
33    * for details regarding how to get schema information about an attribute
34    * if the underlying directory service supports schemas.
35    *<p>
36    * Equality of two attributes is determined by the implementation class.
37    * A simple implementation can use <tt>Object.equals()</tt> to determine equality 
38    * of attribute values, while a more sophisticated implementation might
39    * make use of schema information to determine equality.
40    * Similarly, one implementation might provide a static storage
41    * structure which simply returns the values passed to its
42    * constructor, while another implementation might define <tt>get()</tt> and 
43    * <tt>getAll()</tt>.
44    * to get the values dynamically from the directory.
45    *<p>
46    * Note that updates to <tt>Attribute</tt> (such as adding or removing a
47    * value) do not affect the corresponding representation of the attribute
48    * in the directory.  Updates to the directory can only be effected
49    * using operations in the <tt>DirContext</tt> interface.
50    *
51    * @author Rosanna Lee
52    * @author Scott Seligman
53    * @version 1.12 04/05/05
54    *
55    * @see BasicAttribute
56    * @since 1.3
57    */
58  public interface Attribute extends Cloneable  , java.io.Serializable   {
59      /**
60        * Retrieves an enumeration of the attribute's values.
61        * The behaviour of this enumeration is unspecified
62        * if the attribute's values are added, changed,
63        * or removed while the enumeration is in progress.
64        * If the attribute values are ordered, the enumeration's items
65        * will be ordered.
66        *
67        * @return A non-null enumeration of the attribute's values.
68        * Each element of the enumeration is a possibly null Object. The object's
69        * class is the class of the attribute value. The element is null
70        * if the attribute's value is null.
71        * If the attribute has zero values, an empty enumeration 
72        * is returned.
73        * @exception NamingException
74        *     If a naming exception was encountered while retrieving
75        *     the values.
76        * @see #isOrdered
77        */
78      NamingEnumeration  <?> getAll() throws NamingException  ;
79  
80      /**
81        * Retrieves one of this attribute's values.
82        * If the attribute has more than one value and is unordered, any one of
83        * the values is returned.
84        * If the attribute has more than one value and is ordered, the
85        * first value is returned.
86        *
87        * @return A possibly null object representing one of 
88        *        the attribute's value. It is null if the attribute's value
89        *        is null.
90        * @exception NamingException
91        *     If a naming exception was encountered while retrieving
92        *     the value.
93        * @exception java.util.NoSuchElementException
94        *     If this attribute has no values.
95        */
96      Object   get() throws NamingException  ;
97  
98      /** 
99        * Retrieves the number of values in this attribute.
100       *
101       * @return The nonnegative number of values in this attribute.
102       */
103     int size();
104 
105     /**
106       * Retrieves the id of this attribute.
107       *
108       * @return The id of this attribute. It cannot be null.
109       */
110     String   getID();
111 
112     /**
113       * Determines whether a value is in the attribute.
114       * Equality is determined by the implementation, which may use
115       * <tt>Object.equals()</tt> or schema information to determine equality.
116       *
117       * @param attrVal The possibly null value to check. If null, check
118       *  whether the attribute has an attribute value whose value is null.
119       * @return true if attrVal is one of this attribute's values; false otherwise.
120       * @see java.lang.Object#equals
121       * @see BasicAttribute#equals
122       */
123     boolean contains(Object   attrVal);
124     /**
125       * Adds a new value to the attribute. 
126       * If the attribute values are unordered and
127       * <tt>attrVal</tt> is already in the attribute, this method does nothing.
128       * If the attribute values are ordered, <tt>attrVal</tt> is added to the end of
129       * the list of attribute values.
130       *<p>
131       * Equality is determined by the implementation, which may use
132       * <tt>Object.equals()</tt> or schema information to determine equality.
133       *
134       * @param attrVal The new possibly null value to add. If null, null
135       *  is added as an attribute value.
136       * @return true if a value was added; false otherwise.
137       */
138     boolean add(Object   attrVal);
139 
140     /**
141       * Removes a specified value from the attribute.
142       * If <tt>attrval</tt> is not in the attribute, this method does nothing.
143       * If the attribute values are ordered, the first occurrence of 
144       * <tt>attrVal</tt> is removed and attribute values at indices greater 
145       * than the removed
146       * value are shifted up towards the head of the list (and their indices
147       * decremented by one).
148       *<p>
149       * Equality is determined by the implementation, which may use
150       * <tt>Object.equals()</tt> or schema information to determine equality.
151       *
152       * @param attrval The possibly null value to remove from this attribute.
153       * If null, remove the attribute value that is null.
154       * @return true if the value was removed; false otherwise.
155       */
156     boolean remove(Object   attrval);
157 
158     /**
159       * Removes all values from this attribute.
160       */
161     void clear();
162 
163     /**
164       * Retrieves the syntax definition associated with the attribute.
165       * An attribute's syntax definition specifies the format
166       * of the attribute's value(s). Note that this is different from 
167       * the attribute value's representation as a Java object. Syntax 
168       * definition refers to the directory's notion of <em>syntax</em>.
169       *<p>
170       * For example, even though a value might be
171       * a Java String object, its directory syntax might be "Printable String"
172       * or "Telephone Number". Or a value might be a byte array, and its
173       * directory syntax is "JPEG" or "Certificate".
174       * For example, if this attribute's syntax is "JPEG",
175       * this method would return the syntax definition for "JPEG".
176       * <p>
177       * The information that you can retrieve from a syntax definition
178       * is directory-dependent.
179       *<p>
180       * If an implementation does not support schemas, it should throw
181       * OperationNotSupportedException. If an implementation does support
182       * schemas, it should define this method to return the appropriate
183       * information.
184       * @return The attribute's syntax definition. Null if the implementation
185       *    supports schemas but this particular attribute does not have
186       *    any schema information.
187       * @exception OperationNotSupportedException If getting the schema
188       *     is not supported.
189       * @exception NamingException If a naming exception occurs while getting
190       *     the schema.
191       */
192 
193     DirContext   getAttributeSyntaxDefinition() throws NamingException  ;
194 
195     /**
196       * Retrieves the attribute's schema definition.
197       * An attribute's schema definition contains information
198       * such as whether the attribute is multivalued or single-valued,
199       * the matching rules to use when comparing the attribute's values.
200       *
201       * The information that you can retrieve from an attribute definition
202       * is directory-dependent.
203       *
204       *<p>
205       * If an implementation does not support schemas, it should throw
206       * OperationNotSupportedException. If an implementation does support
207       * schemas, it should define this method to return the appropriate
208       * information.
209       * @return This attribute's schema definition. Null if the implementation
210       *     supports schemas but this particular attribute does not have
211       *     any schema information.
212       * @exception OperationNotSupportedException If getting the schema
213       *     is not supported.
214       * @exception NamingException If a naming exception occurs while getting
215       *     the schema.
216       */ 
217     DirContext   getAttributeDefinition() throws NamingException  ;
218 
219     /**
220       * Makes a copy of the attribute. 
221       * The copy contains the same attribute values as the original attribute:
222       * the attribute values are not themselves cloned.
223       * Changes to the copy will not affect the original and vice versa.
224       *
225       * @return A non-null copy of the attribute.
226       */
227     Object   clone();
228 
229     //----------- Methods to support ordered multivalued attributes
230 
231     /**
232       * Determines whether this attribute's values are ordered.
233       * If an attribute's values are ordered, duplicate values are allowed.
234       * If an attribute's values are unordered, they are presented
235       * in any order and there are no duplicate values.
236       * @return true if this attribute's values are ordered; false otherwise.
237       * @see #get(int)
238       * @see #remove(int)
239       * @see #add(int, java.lang.Object)
240       * @see #set(int, java.lang.Object)
241       */
242     boolean isOrdered();
243 
244     /**
245      * Retrieves the attribute value from the ordered list of attribute values.
246      * This method returns the value at the <tt>ix</tt> index of the list of
247      * attribute values.
248      * If the attribute values are unordered,
249      * this method returns the value that happens to be at that index.
250      * @param ix The index of the value in the ordered list of attribute values.
251      * 0 <= <tt>ix</tt> < <tt>size()</tt>.
252      * @return The possibly null attribute value at index <tt>ix</tt>; 
253      *   null if the attribute value is null.
254      * @exception NamingException If a naming exception was encountered while
255      * retrieving the value.
256      * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
257      */
258     Object   get(int ix) throws NamingException  ;
259 
260     /**
261      * Removes an attribute value from the ordered list of attribute values.
262      * This method removes the value at the <tt>ix</tt> index of the list of
263      * attribute values. 
264      * If the attribute values are unordered,
265      * this method removes the value that happens to be at that index.
266      * Values located at indices greater than <tt>ix</tt> are shifted up towards
267      * the front of the list (and their indices decremented by one).
268      *
269      * @param ix The index of the value to remove.
270      * 0 <= <tt>ix</tt> < <tt>size()</tt>.
271      * @return The possibly null attribute value at index <tt>ix</tt> that was removed; 
272      *   null if the attribute value is null.
273      * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
274      */
275     Object   remove(int ix);
276 
277     /**
278      * Adds an attribute value to the ordered list of attribute values.
279      * This method adds <tt>attrVal</tt> to the list of attribute values at
280      * index <tt>ix</tt>.
281      * Values located at indices at or greater than <tt>ix</tt> are 
282      * shifted down towards the end of the list (and their indices incremented 
283      * by one).
284      * If the attribute values are unordered and already have <tt>attrVal</tt>,
285      * <tt>IllegalStateException</tt> is thrown.
286      *
287      * @param ix The index in the ordered list of attribute values to add the new value.
288      * 0 <= <tt>ix</tt> <= <tt>size()</tt>.
289      * @param attrVal The possibly null attribute value to add; if null, null is
290      * the value added.
291      * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
292      * @exception IllegalStateException If the attribute values are unordered and
293      * <tt>attrVal</tt> is one of those values.
294      */
295     void add(int ix, Object   attrVal);
296 
297 
298     /**
299      * Sets an attribute value in the ordered list of attribute values.
300      * This method sets the value at the <tt>ix</tt> index of the list of
301      * attribute values to be <tt>attrVal</tt>. The old value is removed.
302      * If the attribute values are unordered,
303      * this method sets the value that happens to be at that index
304      * to <tt>attrVal</tt>, unless <tt>attrVal</tt> is already one of the values.
305      * In that case, <tt>IllegalStateException</tt> is thrown.
306      *
307      * @param ix The index of the value in the ordered list of attribute values.
308      * 0 <= <tt>ix</tt> < <tt>size()</tt>.
309      * @param attrVal The possibly null attribute value to use. 
310      * If null, 'null' replaces the old value.
311      * @return The possibly null attribute value at index ix that was replaced. 
312      *   Null if the attribute value was null.
313      * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
314      * @exception IllegalStateException If <tt>attrVal</tt> already exists and the
315      *    attribute values are unordered.
316      */
317     Object   set(int ix, Object   attrVal);
318 
319     /**
320      * Use serialVersionUID from JNDI 1.1.1 for interoperability.
321      */
322     static final long serialVersionUID = 8707690322213556804L;
323 }
324
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags