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    }