View Javadoc

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 }