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
022 import java.util.List;
023 import java.util.Set;
024
025 import org.apache.directory.shared.ldap.exception.LdapException;
026 import org.apache.directory.shared.ldap.schema.AttributeType;
027
028
029 /**
030 * A server side entry which is schema aware.
031 *
032 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
033 * @version $Rev$, $Date$
034 */
035 public interface ServerEntry extends Entry, Cloneable
036 {
037 /**
038 * <p>
039 * Add an attribute (represented by its AttributeType and some binary values) into an
040 * entry.
041 * </p>
042 * <p>
043 * If we already have an attribute with the same values, the duplicated values
044 * are not added (duplicated values are not allowed)
045 * </p>
046 * <p>
047 * If the value cannot be added, or if the AttributeType is null or invalid,
048 * a LdapException is thrown.
049 * </p>
050 *
051 * @param attributeType The attribute Type.
052 * @param values The list of binary values to inject. It can be empty.
053 * @throws LdapException If the attribute does not exist
054 */
055 void add( AttributeType attributeType, byte[]... values ) throws LdapException;
056
057
058 /**
059 * <p>
060 * Add an attribute (represented by its AttributeType and some String values) into an
061 * entry.
062 * </p>
063 * <p>
064 * If we already have an attribute with the same values, the duplicated values
065 * are not added (duplicated values are not allowed)
066 * </p>
067 * <p>
068 * If the value cannot be added, or if the AttributeType is null or invalid,
069 * a LdapException is thrown.
070 * </p>
071 *
072 * @param attributeType The attribute Type
073 * @param values The list of binary values to inject. It can be empty
074 * @throws LdapException If the attribute does not exist
075 */
076 void add( AttributeType attributeType, String... values ) throws LdapException;
077
078
079 /**
080 * <p>
081 * Add an attribute (represented by its AttributeType and some values) into an
082 * entry.
083 * </p>
084 * <p>
085 * If we already have an attribute with the same values, the duplicated values
086 * are not added (duplicated values are not allowed)
087 * </p>
088 * <p>
089 * If the value cannot be added, or if the AttributeType is null or invalid,
090 * a LdapException is thrown.
091 * </p>
092 *
093 * @param attributeType The attribute Type
094 * @param values The list of binary values to inject. It can be empty
095 * @throws LdapException If the attribute does not exist
096 */
097 void add( AttributeType attributeType, Value<?>... values ) throws LdapException;
098
099
100 /**
101 * <p>
102 * Add an attribute (represented by its AttributeType and some binary values) into an
103 * entry. Set the User Provider ID at the same time
104 * </p>
105 * <p>
106 * If we already have an attribute with the same values, the duplicated values
107 * are not added (duplicated values are not allowed)
108 * </p>
109 * <p>
110 * If the value cannot be added, or if the AttributeType is null or invalid,
111 * a LdapException is thrown.
112 * </p>
113 *
114 * @param upId The user provided ID for the added AttributeType
115 * @param attributeType The attribute Type.
116 * @param values The list of binary values to add. It can be empty.
117 * @throws LdapException If the attribute does not exist
118 */
119 void add( String upId, AttributeType attributeType, byte[]... values ) throws LdapException;
120
121
122 /**
123 * <p>
124 * Add an attribute (represented by its AttributeType and some String values) into an
125 * entry. Set the User Provider ID at the same time
126 * </p>
127 * <p>
128 * If we already have an attribute with the same values, the duplicated values
129 * are not added (duplicated values are not allowed)
130 * </p>
131 * <p>
132 * If the value cannot be added, or if the AttributeType is null or invalid,
133 * a LdapException is thrown.
134 * </p>
135 *
136 * @param upId The user provided ID for the added AttributeType
137 * @param attributeType The attribute Type.
138 * @param values The list of binary values to add. It can be empty.
139 * @throws LdapException If the attribute does not exist
140 */
141 void add( String upId, AttributeType attributeType, String... values ) throws LdapException;
142
143
144 /**
145 * <p>
146 * Add an attribute (represented by its AttributeType and some values) into an
147 * entry. Set the User Provider ID at the same time
148 * </p>
149 * <p>
150 * If we already have an attribute with the same values, nothing is done
151 * (duplicated values are not allowed)
152 * </p>
153 * <p>
154 * If the value cannot be added, or if the AttributeType is null or invalid,
155 * a LdapException is thrown.
156 * </p>
157 *
158 * @param upId The user provided ID for the added AttributeType
159 * @param attributeType The attribute Type.
160 * @param values The list of values to add. It can be empty.
161 * @throws LdapException If the attribute does not exist
162 */
163 void add( String upId, AttributeType attributeType, Value<?>... values ) throws LdapException;
164
165
166 // -----------------------------------------------------------------------
167 // Container (get/put/remove) Methods
168 // -----------------------------------------------------------------------
169 /**
170 * Checks if an entry contains an attribute with some given binary values.
171 *
172 * @param attributeType The Attribute we are looking for.
173 * @param values The searched values.
174 * @return <code>true</code> if all the values are found within the attribute,
175 * <code>false</code> otherwise, or if the attributes does not exist.
176 * @throws LdapException If the attribute does not exists
177 */
178 boolean contains( AttributeType attributeType, byte[]... values );
179
180
181 /**
182 * Checks if an entry contains an attribute with some given String values.
183 *
184 * @param attributeType The Attribute we are looking for.
185 * @param values The searched values.
186 * @return <code>true</code> if all the values are found within the attribute,
187 * <code>false</code> otherwise, or if the attributes does not exist.
188 * @throws LdapException If the attribute does not exists
189 */
190 boolean contains( AttributeType attributeType, String... values );
191
192
193 /**
194 * Checks if an entry contains an attribute with some given binary values.
195 *
196 * @param attributeType The Attribute we are looking for.
197 * @param values The searched values.
198 * @return <code>true</code> if all the values are found within the attribute,
199 * <code>false</code> otherwise, or if the attributes does not exist.
200 * @throws LdapException If the attribute does not exists
201 */
202 boolean contains( AttributeType attributeType, Value<?>... values );
203
204
205 /**
206 * Checks if an entry contains a specific AttributeType.
207 *
208 * @param attributeType The AttributeType to look for.
209 * @return <code>true</code> if the attribute is found within the entry.
210 */
211 boolean containsAttribute( AttributeType attributeType );
212
213
214 /**
215 * <p>
216 * Returns the attribute with the specified AttributeType. The return value
217 * is <code>null</code> if no match is found.
218 * </p>
219 *
220 * @param attributeType The attributeType we are looking for.
221 * @return the attribute associated with the AttributeType.
222 */
223 /**
224 * Returns the attribute associated with an AttributeType
225 *
226 * @param the AttributeType we are looking for
227 * @return the associated attribute
228 */
229 EntryAttribute get( AttributeType attributeType );
230
231
232 /**
233 * Gets all the attributes type
234 *
235 * @return The combined set of all the attributes.
236 */
237 Set<AttributeType> getAttributeTypes();
238
239
240 /**
241 * Tells if an entry has a specific ObjectClass Attribute
242 *
243 * @param objectClass The ObjectClass we want to check
244 * @return <code>true</code> if the ObjectClass value is present
245 * in the ObjectClass attribute
246 */
247 boolean hasObjectClass( EntryAttribute objectClass );
248
249
250 /**
251 * Fail fast check performed to determine entry consistency according to schema
252 * characteristics.
253 *
254 * @return true if the entry, it's attributes and their values are consistent
255 * with the schema
256 */
257 boolean isValid();
258
259
260 /**
261 * Check performed to determine entry consistency according to the schema
262 * requirements of a particular objectClass. The entry must be of that objectClass
263 * to return true: meaning if the entry's objectClass attribute does not contain
264 * the objectClass argument, then false should be returned.
265 *
266 * @param objectClass the objectClass to use while checking for validity
267 * @return true if the entry, it's attributes and their values are consistent
268 * with the objectClass
269 */
270 boolean isValid( String objectClass );
271
272
273 /**
274 * Check performed to determine entry consistency according to the schema
275 * requirements of a particular objectClass. The entry must be of that objectClass
276 * to return true: meaning if the entry's objectClass attribute does not contain
277 * the objectClass argument, then false should be returned.
278 *
279 * @param objectClass the objectClass to use while checking for validity
280 * @return true if the entry, it's attributes and their values are consistent
281 * with the objectClass
282 */
283 boolean isValid( EntryAttribute objectClass );
284
285
286 /**
287 * <p>
288 * Places a new attribute with the supplied AttributeType and binary values
289 * into the attribute collection.
290 * </p>
291 * <p>
292 * If there is already an attribute with the same AttributeType, the old
293 * one is removed from the collection and is returned by this method.
294 * </p>
295 * <p>
296 * This method provides a mechanism to put an attribute with a
297 * <code>null</code> value: the value may be <code>null</code>.
298 *
299 * @param attributeType the type of the new attribute to be put
300 * @param values the binary values of the new attribute to be put
301 * @return the old attribute with the same identifier, if exists; otherwise
302 * <code>null</code>
303 * @throws LdapException if there are failures
304 */
305 EntryAttribute put( AttributeType attributeType, byte[]... values ) throws LdapException;
306
307
308 /**
309 * <p>
310 * Places a new attribute with the supplied AttributeType and String values
311 * into the attribute collection.
312 * </p>
313 * <p>
314 * If there is already an attribute with the same AttributeType, the old
315 * one is removed from the collection and is returned by this method.
316 * </p>
317 * <p>
318 * This method provides a mechanism to put an attribute with a
319 * <code>null</code> value: the value may be <code>null</code>.
320 *
321 * @param attributeType the type of the new attribute to be put
322 * @param values the String values of the new attribute to be put
323 * @return the old attribute with the same identifier, if exists; otherwise
324 * <code>null</code>
325 * @throws LdapException if there are failures
326 */
327 EntryAttribute put( AttributeType attributeType, String... values ) throws LdapException;
328
329
330 /**
331 * <p>
332 * Places a new attribute with the supplied AttributeType and some values
333 * into the attribute collection.
334 * </p>
335 * <p>
336 * If there is already an attribute with the same AttributeType, the old
337 * one is removed from the collection and is returned by this method.
338 * </p>
339 * <p>
340 * This method provides a mechanism to put an attribute with a
341 * <code>null</code> value: the value may be <code>null</code>.
342 *
343 * @param attributeType the type of the new attribute to be put
344 * @param values the values of the new attribute to be put
345 * @return the old attribute with the same identifier, if exists; otherwise
346 * <code>null</code>
347 * @throws LdapException if there are failures
348 */
349 EntryAttribute put( AttributeType attributeType, Value<?>... values ) throws LdapException;
350
351
352 /**
353 * <p>
354 * Places a new attribute with the supplied AttributeType and some binary values
355 * into the attribute collection.
356 * </p>
357 * <p>
358 * The given User provided ID will be used for this new AttributeEntry.
359 * </p>
360 * <p>
361 * If there is already an attribute with the same AttributeType, the old
362 * one is removed from the collection and is returned by this method.
363 * </p>
364 * <p>
365 * This method provides a mechanism to put an attribute with a
366 * <code>null</code> value: the value may be <code>null</code>.
367 *
368 * @param upId The User Provided ID to be stored into the AttributeEntry
369 * @param values the binary values of the new attribute to be put
370 * @return the old attribute with the same identifier, if exists; otherwise
371 * <code>null</code>
372 * @throws LdapException if there are failures.
373 */
374 EntryAttribute put( String upId, AttributeType attributeType, byte[]... values ) throws LdapException;
375
376
377 /**
378 * <p>
379 * Places a new attribute with the supplied AttributeType and some String values
380 * into the attribute collection.
381 * </p>
382 * <p>
383 * The given User provided ID will be used for this new AttributeEntry.
384 * </p>
385 * <p>
386 * If there is already an attribute with the same AttributeType, the old
387 * one is removed from the collection and is returned by this method.
388 * </p>
389 * <p>
390 * This method provides a mechanism to put an attribute with a
391 * <code>null</code> value: the value may be <code>null</code>.
392 *
393 * @param upId The User Provided ID to be stored into the AttributeEntry
394 * @param attributeType the type of the new attribute to be put
395 * @param values the String values of the new attribute to be put
396 * @return the old attribute with the same identifier, if exists; otherwise
397 * <code>null</code>
398 * @throws LdapException if there are failures.
399 */
400 EntryAttribute put( String upId, AttributeType attributeType, String... values ) throws LdapException;
401
402
403 /**
404 * <p>
405 * Places a new attribute with the supplied AttributeType and some values
406 * into the attribute collection.
407 * </p>
408 * <p>
409 * The given User provided ID will be used for this new AttributeEntry.
410 * </p>
411 * <p>
412 * If there is already an attribute with the same AttributeType, the old
413 * one is removed from the collection and is returned by this method.
414 * </p>
415 * <p>
416 * This method provides a mechanism to put an attribute with a
417 * <code>null</code> value: the value may be <code>null</code>.
418 *
419 * @param upId The User Provided ID to be stored into the AttributeEntry
420 * @param attributeType the type of the new attribute to be put
421 * @param values the values of the new attribute to be put
422 * @return the old attribute with the same identifier, if exists; otherwise
423 * <code>null</code>
424 * @throws LdapException if there are failures.
425 */
426 EntryAttribute put( String upId, AttributeType attributeType, Value<?>... values ) throws LdapException;
427
428
429 /**
430 * <p>
431 * Removes the specified binary values from an attribute.
432 * </p>
433 * <p>
434 * If at least one value is removed, this method returns <code>true</code>.
435 * </p>
436 * <p>
437 * If there is no more value after having removed the values, the attribute
438 * will be removed too.
439 * </p>
440 * <p>
441 * If the attribute does not exist, nothing is done and the method returns
442 * <code>false</code>
443 * </p>
444 *
445 * @param attributeType The attribute type
446 * @param values the values to be removed
447 * @return <code>true</code> if at least a value is removed, <code>false</code>
448 * if not all the values have been removed or if the attribute does not exist.
449 */
450 boolean remove( AttributeType attributeType, byte[]... values ) throws LdapException;
451
452
453 /**
454 * <p>
455 * Removes the specified String values from an attribute.
456 * </p>
457 * <p>
458 * If at least one value is removed, this method returns <code>true</code>.
459 * </p>
460 * <p>
461 * If there is no more value after having removed the values, the attribute
462 * will be removed too.
463 * </p>
464 * <p>
465 * If the attribute does not exist, nothing is done and the method returns
466 * <code>false</code>
467 * </p>
468 *
469 * @param attributeType The attribute type
470 * @param values the values to be removed
471 * @return <code>true</code> if at least a value is removed, <code>false</code>
472 * if not all the values have been removed or if the attribute does not exist.
473 */
474 boolean remove( AttributeType attributeType, String... values ) throws LdapException;
475
476
477 /**
478 * <p>
479 * Removes the specified values from an attribute.
480 * </p>
481 * <p>
482 * If at least one value is removed, this method returns <code>true</code>.
483 * </p>
484 * <p>
485 * If there is no more value after having removed the values, the attribute
486 * will be removed too.
487 * </p>
488 * <p>
489 * If the attribute does not exist, nothing is done and the method returns
490 * <code>false</code>
491 * </p>
492 *
493 * @param attributeType The attribute type
494 * @param values the values to be removed
495 * @return <code>true</code> if at least a value is removed, <code>false</code>
496 * if not all the values have been removed or if the attribute does not exist.
497 */
498 boolean remove( AttributeType attributeType, Value<?>... values ) throws LdapException;
499
500
501 /**
502 * Removes the specified attributes. The removed attributes are
503 * returned by this method. If there were no attribute the return value
504 * is <code>null</code>.
505 *
506 * @param attributes the attributes to be removed
507 * @return the removed attribute, if exists; otherwise <code>null</code>
508 */
509 List<EntryAttribute> remove( EntryAttribute... attributes ) throws LdapException;
510
511
512 /**
513 * <p>
514 * Removes the attribute with the specified AttributeTypes.
515 * </p>
516 * <p>
517 * The removed attribute are returned by this method.
518 * </p>
519 * <p>
520 * If there is no attribute with the specified AttributeTypes,
521 * the return value is <code>null</code>.
522 * </p>
523 *
524 * @param attributes the AttributeTypes to be removed
525 * @return the removed attributes, if any, as a list; otherwise <code>null</code>
526 */
527 List<EntryAttribute> removeAttributes( AttributeType... attributes );
528
529
530 /**
531 * <p>
532 * Put some new attributes using the attributeTypes.
533 * No value is inserted.
534 * </p>
535 * <p>
536 * If an existing Attribute is found, it will be replaced by an
537 * empty attribute, and returned to the caller.
538 * </p>
539 *
540 * @param attributeTypes The AttributeTypes to add.
541 * @return A list of replaced Attributes, of <code>null</code> if no attribute are removed.
542 */
543 List<EntryAttribute> set( AttributeType... attributeTypes );
544
545
546 /**
547 * A clone method to produce a clone of the current object
548 */
549 Entry clone();
550
551
552 /**
553 * Convert the ServerEntry to a ClientEntry
554 *
555 * @return An instance of ClientEntry
556 */
557 Entry toClientEntry() throws LdapException;
558 }