001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019 package org.apache.directory.shared.ldap.entry;
020
021 import java.io.Externalizable;
022 import java.util.Iterator;
023 import java.util.List;
024
025 import org.apache.directory.shared.ldap.exception.LdapException;
026 import org.apache.directory.shared.ldap.exception.LdapInvalidAttributeValueException;
027 import org.apache.directory.shared.ldap.schema.AttributeType;
028 import org.apache.directory.shared.ldap.schema.SyntaxChecker;
029
030 /**
031 * A generic interface mocking the Attribute JNDI interface. This interface
032 * will be the base interface for the ServerAttribute and ClientAttribute.
033 *
034 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
035 * @version $Rev$, $Date$
036 */
037 public interface EntryAttribute extends Iterable<Value<?>>, Cloneable, Externalizable
038 {
039 /**
040 * Adds some values to this attribute. If the new values are already present in
041 * the attribute values, the method has no effect.
042 * <p>
043 * The new values are added at the end of list of values.
044 * </p>
045 * <p>
046 * This method returns the number of values that were added.
047 * </p>
048 * <p>
049 * If the value's type is different from the attribute's type,
050 * a conversion is done. For instance, if we try to set some String
051 * into a Binary attribute, we just store the UTF-8 byte array
052 * encoding for this String.
053 * </p>
054 * <p>
055 * If we try to store some byte[] in a HR attribute, we try to
056 * convert those byte[] assuming they represent an UTF-8 encoded
057 * String. Of course, if it's not the case, the stored value will
058 * be incorrect.
059 * </p>
060 * <p>
061 * It's the responsibility of the caller to check if the stored
062 * values are consistent with the attribute's type.
063 * </p>
064 * <p>
065 * The caller can set the HR flag in order to enforce a type for
066 * the current attribute, otherwise this type will be set while
067 * adding the first value, using the value's type to set the flag.
068 * </p>
069 *
070 * @param vals some new values to be added which may be null
071 * @return the number of added values, or 0 if none has been added
072 */
073 int add( String... vals );
074
075
076 /**
077 * Adds some values to this attribute. If the new values are already present in
078 * the attribute values, the method has no effect.
079 * <p>
080 * The new values are added at the end of list of values.
081 * </p>
082 * <p>
083 * This method returns the number of values that were added.
084 * </p>
085 * If the value's type is different from the attribute's type,
086 * a conversion is done. For instance, if we try to set some String
087 * into a Binary attribute, we just store the UTF-8 byte array
088 * encoding for this String.
089 * If we try to store some byte[] in a HR attribute, we try to
090 * convert those byte[] assuming they represent an UTF-8 encoded
091 * String. Of course, if it's not the case, the stored value will
092 * be incorrect.
093 * <br>
094 * It's the responsibility of the caller to check if the stored
095 * values are consistent with the attribute's type.
096 * <br>
097 * The caller can set the HR flag in order to enforce a type for
098 * the current attribute, otherwise this type will be set while
099 * adding the first value, using the value's type to set the flag.
100 *
101 * @param vals some new values to be added which may be null
102 * @return the number of added values, or 0 if none has been added
103 */
104 int add( byte[]... vals );
105
106
107 /**
108 * Adds some values to this attribute. If the new values are already present in
109 * the attribute values, the method has no effect.
110 * <p>
111 * The new values are added at the end of list of values.
112 * </p>
113 * <p>
114 * This method returns the number of values that were added.
115 * </p>
116 * <p>
117 * If the value's type is different from the attribute's type,
118 * a conversion is done. For instance, if we try to set some
119 * StringValue into a Binary attribute, we just store the UTF-8
120 * byte array encoding for this StringValue.
121 * </p>
122 * <p>
123 * If we try to store some BinaryValue in a HR attribute, we try to
124 * convert those BinaryValue assuming they represent an UTF-8 encoded
125 * String. Of course, if it's not the case, the stored value will
126 * be incorrect.
127 * </p>
128 * <p>
129 * It's the responsibility of the caller to check if the stored
130 * values are consistent with the attribute's type.
131 * </p>
132 * <p>
133 * The caller can set the HR flag in order to enforce a type for
134 * the current attribute, otherwise this type will be set while
135 * adding the first value, using the value's type to set the flag.
136 * </p>
137 * <p>
138 * <b>Note : </b>If the entry contains no value, and the unique added value
139 * is a null length value, then this value will be considered as
140 * a binary value.
141 * </p>
142 * @param vals some new values to be added which may be null
143 * @return the number of added values, or 0 if none has been added
144 */
145 int add( Value<?>... val );
146
147
148 /**
149 * Remove all the values from this attribute.
150 */
151 void clear();
152
153
154 /**
155 * @return A clone of the current object
156 */
157 EntryAttribute clone();
158
159
160 /**
161 * <p>
162 * Indicates whether the specified values are some of the attribute's values.
163 * </p>
164 * <p>
165 * If the Attribute is not HR, the values will be converted to byte[]
166 * </p>
167 *
168 * @param vals the values
169 * @return true if this attribute contains all the values, otherwise false
170 */
171 boolean contains( String... vals );
172
173
174 /**
175 * <p>
176 * Indicates whether the specified values are some of the attribute's values.
177 * </p>
178 * <p>
179 * If the Attribute is HR, the values will be converted to String
180 * </p>
181 *
182 * @param vals the values
183 * @return true if this attribute contains all the values, otherwise false
184 */
185 boolean contains( byte[]... vals );
186
187
188 /**
189 * <p>
190 * Indicates whether the specified values are some of the attribute's values.
191 * </p>
192 * <p>
193 * If the Attribute is HR, the binary values will be converted to String before
194 * being checked.
195 * </p>
196 *
197 * @param vals the values
198 * @return true if this attribute contains all the values, otherwise false
199 */
200 boolean contains( Value<?>... vals );
201
202
203 /**
204 * Get the attribute type associated with this ServerAttribute.
205 *
206 * @return the attributeType associated with this entry attribute
207 */
208 AttributeType getAttributeType();
209
210
211 /**
212 * <p>
213 * Set the attribute type associated with this ServerAttribute.
214 * </p>
215 * <p>
216 * The current attributeType will be replaced. It is the responsibility of
217 * the caller to insure that the existing values are compatible with the new
218 * AttributeType
219 * </p>
220 *
221 * @param attributeType the attributeType associated with this entry attribute
222 */
223 void setAttributeType( AttributeType attributeType );
224
225
226 /**
227 * <p>
228 * Check if the current attribute type is of the expected attributeType
229 * </p>
230 * <p>
231 * This method won't tell if the current attribute is a descendant of
232 * the attributeType. For instance, the "CN" serverAttribute will return
233 * false if we ask if it's an instance of "Name".
234 * </p>
235 *
236 * @param attributeId The AttributeType ID to check
237 * @return True if the current attribute is of the expected attributeType
238 * @throws LdapInvalidAttributeValueException If there is no AttributeType
239 */
240 boolean instanceOf( String attributeId ) throws LdapInvalidAttributeValueException;
241
242
243 /**
244 * <p>
245 * Get the first value of this attribute. If there is none,
246 * null is returned.
247 * </p>
248 * <p>
249 * Note : even if we are storing values into a Set, one can assume
250 * the values are ordered following the insertion order.
251 * </p>
252 * <p>
253 * This method is meant to be used if the attribute hold only one value.
254 * </p>
255 *
256 * @return The first value for this attribute.
257 */
258 Value<?> get();
259
260
261 /**
262 * Returns an iterator over all the attribute's values.
263 * <p>
264 * The effect on the returned enumeration of adding or removing values of
265 * the attribute is not specified.
266 * </p>
267 * <p>
268 * This method will throw any <code>NamingException</code> that occurs.
269 * </p>
270 *
271 * @return an enumeration of all values of the attribute
272 */
273 Iterator<Value<?>> getAll();
274
275
276 /**
277 * <p>
278 * Get the nth value of this attribute. If there is none,
279 * null is returned.
280 * </p>
281 * <p>
282 * Note : even if we are storing values into a Set, one can assume
283 * the values are ordered following the insertion order.
284 * </p>
285 * <p>
286 *
287 * @param i the index of the value to get
288 * @return The nth value for this attribute.
289 */
290 Value<?> get( int i );
291
292
293 /**
294 * <p>
295 * Get the byte[] value, if and only if the value is known to be Binary,
296 * otherwise a InvalidAttributeValueException will be thrown
297 * </p>
298 * <p>
299 * Note that this method returns the first value only.
300 * </p>
301 *
302 * @return The value as a byte[]
303 * @throws LdapInvalidAttributeValueException If the value is a String
304 */
305 byte[] getBytes() throws LdapInvalidAttributeValueException;
306
307
308 /**
309 * Get's the attribute identifier for this entry. This is the value
310 * that will be used as the identifier for the attribute within the
311 * entry.
312 *
313 * @return the identifier for this attribute
314 */
315 String getId();
316
317
318 /**
319 * Get's the user provided identifier for this entry. This is the value
320 * that will be used as the identifier for the attribute within the
321 * entry. If this is a commonName attribute for example and the user
322 * provides "COMMONname" instead when adding the entry then this is
323 * the format the user will have that entry returned by the directory
324 * server. To do so we store this value as it was given and track it
325 * in the attribute using this property.
326 *
327 * @return the user provided identifier for this attribute
328 */
329 String getUpId();
330
331
332 /**
333 * <p>
334 * Tells if the attribute is Human Readable.
335 * </p>
336 * <p>This flag is set by the caller, or implicitly when adding String
337 * values into an attribute which is not yet declared as Binary.
338 * </p>
339 * @return
340 */
341 boolean isHR();
342
343
344 /**
345 * <p>
346 * Get the String value, if and only if the value is known to be a String,
347 * otherwise a InvalidAttributeValueException will be thrown
348 * </p>
349 * <p>
350 * Note that this method returns the first value only.
351 * </p>
352 *
353 * @return The value as a String
354 * @throws LdapInvalidAttributeValueException If the value is a byte[]
355 */
356 String getString() throws LdapInvalidAttributeValueException;
357
358
359 /**
360 * Puts some values to this attribute.
361 * <p>
362 * The new values will replace the previous values.
363 * </p>
364 * <p>
365 * This method returns the number of values that were put.
366 * </p>
367 *
368 * @param val some values to be put which may be null
369 * @return the number of added values, or 0 if none has been added
370 */
371 int put( String... vals );
372
373
374 /**
375 * Puts some values to this attribute.
376 * <p>
377 * The new values will replace the previous values.
378 * </p>
379 * <p>
380 * This method returns the number of values that were put.
381 * </p>
382 *
383 * @param val some values to be put which may be null
384 * @return the number of added values, or 0 if none has been added
385 */
386 int put( byte[]... vals );
387
388
389 /**
390 * Puts some values to this attribute.
391 * <p>
392 * The new values are replace the previous values.
393 * </p>
394 * <p>
395 * This method returns the number of values that were put.
396 * </p>
397 *
398 * @param val some values to be put which may be null
399 * @return the number of added values, or 0 if none has been added
400 */
401 int put( Value<?>... vals );
402
403
404 /**
405 * <p>
406 * Puts a list of values into this attribute.
407 * </p>
408 * <p>
409 * The new values will replace the previous values.
410 * </p>
411 * <p>
412 * This method returns the number of values that were put.
413 * </p>
414 *
415 * @param vals the values to be put
416 * @return the number of added values, or 0 if none has been added
417 */
418 int put( List<Value<?>> vals );
419
420
421 /**
422 * <p>
423 * Removes all the values that are equal to the given values.
424 * </p>
425 * <p>
426 * Returns true if all the values are removed.
427 * </p>
428 * <p>
429 * If the attribute type is not HR, then the values will be first converted
430 * to byte[]
431 * </p>
432 *
433 * @param vals the values to be removed
434 * @return true if all the values are removed, otherwise false
435 */
436 boolean remove( String... vals );
437
438
439 /**
440 * <p>
441 * Removes all the values that are equal to the given values.
442 * </p>
443 * <p>
444 * Returns true if all the values are removed.
445 * </p>
446 * <p>
447 * If the attribute type is HR, then the values will be first converted
448 * to String
449 * </p>
450 *
451 * @param vals the values to be removed
452 * @return true if all the values are removed, otherwise false
453 */
454 boolean remove( byte[]... val );
455
456
457 /**
458 * <p>
459 * Removes all the values that are equal to the given values.
460 * </p>
461 * <p>
462 * Returns true if all the values are removed.
463 * </p>
464 * <p>
465 * If the attribute type is HR and some value which are not String, we
466 * will convert the values first (same thing for a non-HR attribute).
467 * </p>
468 *
469 * @param vals the values to be removed
470 * @return true if all the values are removed, otherwise false
471 */
472 boolean remove( Value<?>... vals );
473
474
475 /**
476 * <p>
477 * Set the attribute to Human Readable or to Binary.
478 * </p>
479 * @param isHR <code>true</code> for a Human Readable attribute,
480 * <code>false</code> for a Binary attribute.
481 */
482 void setHR( boolean isHR );
483
484
485 /**
486 * Set the normalized ID. The ID will be lowercased, and spaces
487 * will be trimmed.
488 *
489 * @param id The attribute ID
490 * @throws IllegalArgumentException If the ID is empty or null or
491 * resolve to an empty value after being trimmed
492 */
493 public void setId( String id );
494
495
496 /**
497 * Set the user provided ID. It will also set the ID, normalizing
498 * the upId (removing spaces before and after, and lowercasing it)
499 *
500 * @param upId The attribute ID
501 * @throws IllegalArgumentException If the ID is empty or null or
502 * resolve to an empty value after being trimmed
503 */
504 public void setUpId( String upId );
505
506
507 /**
508 * <p>
509 * Set the user provided ID. If we have none, the upId is assigned
510 * the attributetype's name. If it does not have any name, we will
511 * use the OID.
512 * </p>
513 * <p>
514 * If we have an upId and an AttributeType, they must be compatible. :
515 * - if the upId is an OID, it must be the AttributeType's OID
516 * - otherwise, its normalized form must be equals to ones of
517 * the attributeType's names.
518 * </p>
519 * <p>
520 * In any case, the ATtributeType will be changed. The caller is responsible for
521 * the present values to be compatoble with the new AttributeType.
522 * </p>
523 *
524 * @param upId The attribute ID
525 * @param attributeType The associated attributeType
526 */
527 void setUpId( String upId, AttributeType attributeType );
528
529
530 /**
531 * Retrieves the number of values in this attribute.
532 *
533 * @return the number of values in this attribute, including any values
534 * wrapping a null value if there is one
535 */
536 int size();
537
538
539 /**
540 * <p>
541 * Checks to see if this attribute is valid along with the values it contains.
542 * </p>
543 * <p>
544 * An attribute is valid if :
545 * <li>All of its values are valid with respect to the attributeType's syntax checker</li>
546 * <li>If the attributeType is SINGLE-VALUE, then no more than a value should be present</li>
547 *</p>
548 * @return true if the attribute and it's values are valid, false otherwise
549 * @throws LdapException if there is a failure to check syntaxes of values
550 */
551 boolean isValid() throws LdapException;
552
553
554 /**
555 * Checks to see if this attribute is valid along with the values it contains.
556 *
557 * @param checker The syntax checker
558 * @return true if the attribute and it's values are valid, false otherwise
559 * @throws LdapException if there is a failure to check syntaxes of values
560 */
561 boolean isValid( SyntaxChecker checker) throws LdapException;
562
563
564 /**
565 * Convert the ServerAttribute to a ClientAttribute
566 *
567 * @return An instance of ClientAttribute
568 */
569 EntryAttribute toClientAttribute();
570 }