1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.directory.server.core.entry;
20
21
22 import java.util.List;
23 import java.util.Set;
24
25 import javax.naming.NamingException;
26
27 import org.apache.directory.shared.ldap.entry.Entry;
28 import org.apache.directory.shared.ldap.entry.EntryAttribute;
29 import org.apache.directory.shared.ldap.entry.Value;
30 import org.apache.directory.shared.ldap.schema.AttributeType;
31
32
33 /**
34 * A server side entry which is schema aware.
35 *
36 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
37 * @version $Rev$, $Date$
38 */
39 public interface ServerEntry extends Entry, Cloneable
40 {
41 /**
42 * <p>
43 * Add an attribute (represented by its AttributeType and some binary values) into an
44 * entry.
45 * </p>
46 * <p>
47 * If we already have an attribute with the same values, the duplicated values
48 * are not added (duplicated values are not allowed)
49 * </p>
50 * <p>
51 * If the value cannot be added, or if the AttributeType is null or invalid,
52 * a NamingException is thrown.
53 * </p>
54 *
55 * @param attributeType The attribute Type.
56 * @param values The list of binary values to inject. It can be empty.
57 * @throws NamingException If the attribute does not exist
58 */
59 void add( AttributeType attributeType, byte[]... values ) throws NamingException;
60
61
62 /**
63 * <p>
64 * Add an attribute (represented by its AttributeType and some String values) into an
65 * entry.
66 * </p>
67 * <p>
68 * If we already have an attribute with the same values, the duplicated values
69 * are not added (duplicated values are not allowed)
70 * </p>
71 * <p>
72 * If the value cannot be added, or if the AttributeType is null or invalid,
73 * a NamingException is thrown.
74 * </p>
75 *
76 * @param attributeType The attribute Type
77 * @param values The list of binary values to inject. It can be empty
78 * @throws NamingException If the attribute does not exist
79 */
80 void add( AttributeType attributeType, String... values ) throws NamingException;
81
82
83 /**
84 * <p>
85 * Add an attribute (represented by its AttributeType and some values) into an
86 * entry.
87 * </p>
88 * <p>
89 * If we already have an attribute with the same values, the duplicated values
90 * are not added (duplicated values are not allowed)
91 * </p>
92 * <p>
93 * If the value cannot be added, or if the AttributeType is null or invalid,
94 * a NamingException is thrown.
95 * </p>
96 *
97 * @param attributeType The attribute Type
98 * @param values The list of binary values to inject. It can be empty
99 * @throws NamingException If the attribute does not exist
100 */
101 void add( AttributeType attributeType, Value<?>... values ) throws NamingException;
102
103
104 /**
105 * <p>
106 * Add an attribute (represented by its AttributeType and some binary values) into an
107 * entry. Set the User Provider ID at the same time
108 * </p>
109 * <p>
110 * If we already have an attribute with the same values, the duplicated values
111 * are not added (duplicated values are not allowed)
112 * </p>
113 * <p>
114 * If the value cannot be added, or if the AttributeType is null or invalid,
115 * a NamingException is thrown.
116 * </p>
117 *
118 * @param upId The user provided ID for the added AttributeType
119 * @param attributeType The attribute Type.
120 * @param values The list of binary values to add. It can be empty.
121 * @throws NamingException If the attribute does not exist
122 */
123 void add( String upId, AttributeType attributeType, byte[]... values ) throws NamingException;
124
125
126 /**
127 * <p>
128 * Add an attribute (represented by its AttributeType and some String values) into an
129 * entry. Set the User Provider ID at the same time
130 * </p>
131 * <p>
132 * If we already have an attribute with the same values, the duplicated values
133 * are not added (duplicated values are not allowed)
134 * </p>
135 * <p>
136 * If the value cannot be added, or if the AttributeType is null or invalid,
137 * a NamingException is thrown.
138 * </p>
139 *
140 * @param upId The user provided ID for the added AttributeType
141 * @param attributeType The attribute Type.
142 * @param values The list of binary values to add. It can be empty.
143 * @throws NamingException If the attribute does not exist
144 */
145 void add( String upId, AttributeType attributeType, String... values ) throws NamingException;
146
147
148 /**
149 * <p>
150 * Add an attribute (represented by its AttributeType and some values) into an
151 * entry. Set the User Provider ID at the same time
152 * </p>
153 * <p>
154 * If we already have an attribute with the same values, nothing is done
155 * (duplicated values are not allowed)
156 * </p>
157 * <p>
158 * If the value cannot be added, or if the AttributeType is null or invalid,
159 * a NamingException is thrown.
160 * </p>
161 *
162 * @param upId The user provided ID for the added AttributeType
163 * @param attributeType The attribute Type.
164 * @param values The list of values to add. It can be empty.
165 * @throws NamingException If the attribute does not exist
166 */
167 void add( String upId, AttributeType attributeType, Value<?>... values ) throws NamingException;
168
169
170 // -----------------------------------------------------------------------
171 // Container (get/put/remove) Methods
172 // -----------------------------------------------------------------------
173 /**
174 * Checks if an entry contains an attribute with some given binary values.
175 *
176 * @param attributeType The Attribute we are looking for.
177 * @param values The searched values.
178 * @return <code>true</code> if all the values are found within the attribute,
179 * <code>false</code> otherwise, or if the attributes does not exist.
180 * @throws NamingException If the attribute does not exists
181 */
182 boolean contains( AttributeType attributeType, byte[]... values );
183
184
185 /**
186 * Checks if an entry contains an attribute with some given String values.
187 *
188 * @param attributeType The Attribute we are looking for.
189 * @param values The searched values.
190 * @return <code>true</code> if all the values are found within the attribute,
191 * <code>false</code> otherwise, or if the attributes does not exist.
192 * @throws NamingException If the attribute does not exists
193 */
194 boolean contains( AttributeType attributeType, String... values );
195
196
197 /**
198 * Checks if an entry contains an attribute with some given binary values.
199 *
200 * @param attributeType The Attribute we are looking for.
201 * @param values The searched values.
202 * @return <code>true</code> if all the values are found within the attribute,
203 * <code>false</code> otherwise, or if the attributes does not exist.
204 * @throws NamingException If the attribute does not exists
205 */
206 boolean contains( AttributeType attributeType, Value<?>... values );
207
208
209 /**
210 * Checks if an entry contains a specific AttributeType.
211 *
212 * @param attributeType The AttributeType to look for.
213 * @return <code>true</code> if the attribute is found within the entry.
214 */
215 boolean containsAttribute( AttributeType attributeType );
216
217
218 /**
219 * <p>
220 * Returns the attribute with the specified AttributeType. The return value
221 * is <code>null</code> if no match is found.
222 * </p>
223 *
224 * @param attributeType The attributeType we are looking for.
225 * @return the attribute associated with the AttributeType.
226 */
227 /**
228 * Returns the attribute associated with an AttributeType
229 *
230 * @param the AttributeType we are looking for
231 * @return the associated attribute
232 */
233 EntryAttribute get( AttributeType attributeType );
234
235
236 /**
237 * Gets all the attributes type
238 *
239 * @return The combined set of all the attributes.
240 */
241 Set<AttributeType> getAttributeTypes();
242
243
244 /**
245 * Tells if an entry has a specific ObjectClass Attribute
246 *
247 * @param objectClass The ObjectClass we want to check
248 * @return <code>true</code> if the ObjectClass value is present
249 * in the ObjectClass attribute
250 */
251 boolean hasObjectClass( EntryAttribute objectClass );
252
253
254 /**
255 * Fail fast check performed to determine entry consistency according to schema
256 * characteristics.
257 *
258 * @return true if the entry, it's attributes and their values are consistent
259 * with the schema
260 */
261 boolean isValid();
262
263
264 /**
265 * Check performed to determine entry consistency according to the schema
266 * requirements of a particular objectClass. The entry must be of that objectClass
267 * to return true: meaning if the entry's objectClass attribute does not contain
268 * the objectClass argument, then false should be returned.
269 *
270 * @param objectClass the objectClass to use while checking for validity
271 * @return true if the entry, it's attributes and their values are consistent
272 * with the objectClass
273 */
274 boolean isValid( String objectClass );
275
276
277 /**
278 * Check performed to determine entry consistency according to the schema
279 * requirements of a particular objectClass. The entry must be of that objectClass
280 * to return true: meaning if the entry's objectClass attribute does not contain
281 * the objectClass argument, then false should be returned.
282 *
283 * @param objectClass the objectClass to use while checking for validity
284 * @return true if the entry, it's attributes and their values are consistent
285 * with the objectClass
286 */
287 boolean isValid( EntryAttribute objectClass );
288
289
290 /**
291 * <p>
292 * Places a new attribute with the supplied AttributeType and binary values
293 * into the attribute collection.
294 * </p>
295 * <p>
296 * If there is already an attribute with the same AttributeType, the old
297 * one is removed from the collection and is returned by this method.
298 * </p>
299 * <p>
300 * This method provides a mechanism to put an attribute with a
301 * <code>null</code> value: the value may be <code>null</code>.
302 *
303 * @param attributeType the type of the new attribute to be put
304 * @param values the binary values of the new attribute to be put
305 * @return the old attribute with the same identifier, if exists; otherwise
306 * <code>null</code>
307 * @throws NamingException if there are failures
308 */
309 EntryAttribute put( AttributeType attributeType, byte[]... values ) throws NamingException;
310
311
312 /**
313 * <p>
314 * Places a new attribute with the supplied AttributeType and String values
315 * into the attribute collection.
316 * </p>
317 * <p>
318 * If there is already an attribute with the same AttributeType, the old
319 * one is removed from the collection and is returned by this method.
320 * </p>
321 * <p>
322 * This method provides a mechanism to put an attribute with a
323 * <code>null</code> value: the value may be <code>null</code>.
324 *
325 * @param attributeType the type of the new attribute to be put
326 * @param values the String values of the new attribute to be put
327 * @return the old attribute with the same identifier, if exists; otherwise
328 * <code>null</code>
329 * @throws NamingException if there are failures
330 */
331 EntryAttribute put( AttributeType attributeType, String... values ) throws NamingException;
332
333
334 /**
335 * <p>
336 * Places a new attribute with the supplied AttributeType and some values
337 * into the attribute collection.
338 * </p>
339 * <p>
340 * If there is already an attribute with the same AttributeType, the old
341 * one is removed from the collection and is returned by this method.
342 * </p>
343 * <p>
344 * This method provides a mechanism to put an attribute with a
345 * <code>null</code> value: the value may be <code>null</code>.
346 *
347 * @param attributeType the type of the new attribute to be put
348 * @param values the values of the new attribute to be put
349 * @return the old attribute with the same identifier, if exists; otherwise
350 * <code>null</code>
351 * @throws NamingException if there are failures
352 */
353 EntryAttribute put( AttributeType attributeType, Value<?>... values ) throws NamingException;
354
355
356 /**
357 * <p>
358 * Places a new attribute with the supplied AttributeType and some binary values
359 * into the attribute collection.
360 * </p>
361 * <p>
362 * The given User provided ID will be used for this new AttributeEntry.
363 * </p>
364 * <p>
365 * If there is already an attribute with the same AttributeType, the old
366 * one is removed from the collection and is returned by this method.
367 * </p>
368 * <p>
369 * This method provides a mechanism to put an attribute with a
370 * <code>null</code> value: the value may be <code>null</code>.
371 *
372 * @param upId The User Provided ID to be stored into the AttributeEntry
373 * @param values the binary values of the new attribute to be put
374 * @return the old attribute with the same identifier, if exists; otherwise
375 * <code>null</code>
376 * @throws NamingException if there are failures.
377 */
378 EntryAttribute put( String upId, AttributeType attributeType, byte[]... values ) throws NamingException;
379
380
381 /**
382 * <p>
383 * Places a new attribute with the supplied AttributeType and some String values
384 * into the attribute collection.
385 * </p>
386 * <p>
387 * The given User provided ID will be used for this new AttributeEntry.
388 * </p>
389 * <p>
390 * If there is already an attribute with the same AttributeType, the old
391 * one is removed from the collection and is returned by this method.
392 * </p>
393 * <p>
394 * This method provides a mechanism to put an attribute with a
395 * <code>null</code> value: the value may be <code>null</code>.
396 *
397 * @param upId The User Provided ID to be stored into the AttributeEntry
398 * @param attributeType the type of the new attribute to be put
399 * @param values the String values of the new attribute to be put
400 * @return the old attribute with the same identifier, if exists; otherwise
401 * <code>null</code>
402 * @throws NamingException if there are failures.
403 */
404 EntryAttribute put( String upId, AttributeType attributeType, String... values ) throws NamingException;
405
406
407 /**
408 * <p>
409 * Places a new attribute with the supplied AttributeType and some values
410 * into the attribute collection.
411 * </p>
412 * <p>
413 * The given User provided ID will be used for this new AttributeEntry.
414 * </p>
415 * <p>
416 * If there is already an attribute with the same AttributeType, the old
417 * one is removed from the collection and is returned by this method.
418 * </p>
419 * <p>
420 * This method provides a mechanism to put an attribute with a
421 * <code>null</code> value: the value may be <code>null</code>.
422 *
423 * @param upId The User Provided ID to be stored into the AttributeEntry
424 * @param attributeType the type of the new attribute to be put
425 * @param values the values of the new attribute to be put
426 * @return the old attribute with the same identifier, if exists; otherwise
427 * <code>null</code>
428 * @throws NamingException if there are failures.
429 */
430 EntryAttribute put( String upId, AttributeType attributeType, Value<?>... values ) throws NamingException;
431
432
433 /**
434 * <p>
435 * Removes the specified binary values from an attribute.
436 * </p>
437 * <p>
438 * If at least one value is removed, this method returns <code>true</code>.
439 * </p>
440 * <p>
441 * If there is no more value after having removed the values, the attribute
442 * will be removed too.
443 * </p>
444 * <p>
445 * If the attribute does not exist, nothing is done and the method returns
446 * <code>false</code>
447 * </p>
448 *
449 * @param attributeType The attribute type
450 * @param values the values to be removed
451 * @return <code>true</code> if at least a value is removed, <code>false</code>
452 * if not all the values have been removed or if the attribute does not exist.
453 */
454 boolean remove( AttributeType attributeType, byte[]... values ) throws NamingException;
455
456
457 /**
458 * <p>
459 * Removes the specified String values from an attribute.
460 * </p>
461 * <p>
462 * If at least one value is removed, this method returns <code>true</code>.
463 * </p>
464 * <p>
465 * If there is no more value after having removed the values, the attribute
466 * will be removed too.
467 * </p>
468 * <p>
469 * If the attribute does not exist, nothing is done and the method returns
470 * <code>false</code>
471 * </p>
472 *
473 * @param attributeType The attribute type
474 * @param values the values to be removed
475 * @return <code>true</code> if at least a value is removed, <code>false</code>
476 * if not all the values have been removed or if the attribute does not exist.
477 */
478 boolean remove( AttributeType attributeType, String... values ) throws NamingException;
479
480
481 /**
482 * <p>
483 * Removes the specified values from an attribute.
484 * </p>
485 * <p>
486 * If at least one value is removed, this method returns <code>true</code>.
487 * </p>
488 * <p>
489 * If there is no more value after having removed the values, the attribute
490 * will be removed too.
491 * </p>
492 * <p>
493 * If the attribute does not exist, nothing is done and the method returns
494 * <code>false</code>
495 * </p>
496 *
497 * @param attributeType The attribute type
498 * @param values the values to be removed
499 * @return <code>true</code> if at least a value is removed, <code>false</code>
500 * if not all the values have been removed or if the attribute does not exist.
501 */
502 boolean remove( AttributeType attributeType, Value<?>... values ) throws NamingException;
503
504
505 /**
506 * Removes the specified attributes. The removed attributes are
507 * returned by this method. If there were no attribute the return value
508 * is <code>null</code>.
509 *
510 * @param attributes the attributes to be removed
511 * @return the removed attribute, if exists; otherwise <code>null</code>
512 */
513 List<EntryAttribute> remove( EntryAttribute... attributes ) throws NamingException;
514
515
516 /**
517 * <p>
518 * Removes the attribute with the specified AttributeTypes.
519 * </p>
520 * <p>
521 * The removed attribute are returned by this method.
522 * </p>
523 * <p>
524 * If there is no attribute with the specified AttributeTypes,
525 * the return value is <code>null</code>.
526 * </p>
527 *
528 * @param attributes the AttributeTypes to be removed
529 * @return the removed attributes, if any, as a list; otherwise <code>null</code>
530 */
531 List<EntryAttribute> removeAttributes( AttributeType... attributes );
532
533
534 /**
535 * <p>
536 * Put some new attributes using the attributeTypes.
537 * No value is inserted.
538 * </p>
539 * <p>
540 * If an existing Attribute is found, it will be replaced by an
541 * empty attribute, and returned to the caller.
542 * </p>
543 *
544 * @param attributeTypes The AttributeTypes to add.
545 * @return A list of replaced Attributes, of <code>null</code> if no attribute are removed.
546 */
547 List<EntryAttribute> set( AttributeType... attributeTypes );
548
549
550 /**
551 * A clone method to produce a clone of the current object
552 */
553 Entry clone();
554
555
556 /**
557 * Convert the ServerEntry to a ClientEntry
558 *
559 * @return An instance of ClientEntry
560 */
561 Entry toClientEntry() throws NamingException;
562 }