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.io.Externalizable;
023    import java.util.Iterator;
024    import java.util.List;
025    
026    import org.apache.directory.shared.ldap.exception.LdapException;
027    
028    import org.apache.directory.shared.ldap.name.DN;
029    
030    
031    /**
032     * <p>
033     * This interface represent a LDAP entry. An LDAP entry contains :
034     * <li> A distinguished name (DN)</li>
035     * <li> A list of attributes</li>
036     * </p>
037     * <p>
038     * The available methods on this object are described in this interface.
039     * </p>
040     * <p>
041     * This interface is used by the serverEntry and clientEntry interfaces.
042     *</p>
043     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
044     * @version $Rev$, $Date$
045     */
046    public interface Entry extends Cloneable, Iterable<EntryAttribute>, Externalizable
047    {
048        /**
049         * Remove all the attributes for this entry. The DN is not reset
050         */
051        void clear();
052    
053    
054        /**
055         * Clone the current entry
056         */
057        Entry clone();
058    
059    
060        /**
061         * Get this entry's DN.
062         *
063         * @return The entry's DN
064         */
065        DN getDn();
066    
067    
068        /**
069         * Tells if an entry as a specific ObjectClass value
070         * 
071         * @param objectClass The ObjectClassw we want to check
072         * @return <code>true</code> if the ObjectClass value is present 
073         * in the ObjectClass attribute
074         */
075        boolean hasObjectClass( String objectClass );
076    
077    
078        /**
079         * <p>
080         * Returns the attribute with the specified alias. The return value
081         * is <code>null</code> if no match is found.  
082         * </p>
083         * <p>An Attribute with an id different from the supplied alias may 
084         * be returned: for example a call with 'cn' may in some implementations 
085         * return an Attribute whose getId() field returns 'commonName'.
086         * </p>
087         *
088         * @param alias an aliased name of the attribute identifier
089         * @return the attribute associated with the alias
090         */
091        EntryAttribute get( String alias );
092    
093    
094        /**
095         * <p>
096         * Put some new ClientAttribute using the User Provided ID. 
097         * No value is inserted. 
098         * </p>
099         * <p>
100         * If an existing Attribute is found, it will be replaced by an
101         * empty attribute, and returned to the caller.
102         * </p>
103         * 
104         * @param upIds The user provided IDs of the AttributeTypes to add.
105         * @return A list of replaced Attributes.
106         */
107        List<EntryAttribute> set( String... upIds );
108    
109    
110        /**
111         * Set this entry's DN.
112         *
113         * @param dn The DN associated with this entry
114         */
115        void setDn( DN dn );
116    
117    
118        /**
119         * Returns an enumeration containing the zero or more attributes in the
120         * collection. The behavior of the enumeration is not specified if the
121         * attribute collection is changed.
122         *
123         * @return an enumeration of all contained attributes
124         */
125        Iterator<EntryAttribute> iterator();
126    
127    
128        /**
129         * Add some Attributes to the current Entry.
130         *
131         * @param attributes The attributes to add
132         * @throws LdapException If we can't add any of the attributes
133         */
134        void add( EntryAttribute... attributes ) throws LdapException;
135    
136    
137        /**
138         * Add some String values to the current Entry.
139         *
140         * @param upId The user provided ID of the attribute we want to add 
141         * some values to
142         * @param values The list of String values to add
143         * @throws LdapException If we can't add any of the values
144         */
145        void add( String upId, String... values ) throws LdapException;
146    
147    
148        /**
149         * Add some binary values to the current Entry.
150         *
151         * @param upId The user provided ID of the attribute we want to add 
152         * some values to
153         * @param values The list of binary values to add
154         * @throws LdapException If we can't add any of the values
155         */
156        void add( String upId, byte[]... values ) throws LdapException;
157    
158    
159        /**
160         * Add some Values to the current Entry.
161         *
162         * @param upId The user provided ID of the attribute we want to add 
163         * some values to
164         * @param values The list of Values to add
165         * @throws LdapException If we can't add any of the values
166         */
167        void add( String upId, Value<?>... values ) throws LdapException;
168    
169    
170        /**
171         * <p>
172         * Places attributes in the attribute collection. 
173         * </p>
174         * <p>If there is already an attribute with the same ID as any of the 
175         * new attributes, the old ones are removed from the collection and 
176         * are returned by this method. If there was no attribute with the 
177         * same ID the return value is <code>null</code>.
178         *</p>
179         *
180         * @param attributes the attributes to be put
181         * @return the old attributes with the same OID, if exist; otherwise
182         *         <code>null</code>
183         * @exception LdapException if the operation fails
184         */
185        List<EntryAttribute> put( EntryAttribute... attributes ) throws LdapException;
186    
187    
188        /**
189         * <p>
190         * Put an attribute (represented by its ID and some binary values) into an entry. 
191         * </p>
192         * <p> 
193         * If the attribute already exists, the previous attribute will be 
194         * replaced and returned.
195         * </p>
196         *
197         * @param upId The attribute ID
198         * @param values The list of binary values to put. It can be empty.
199         * @return The replaced attribute
200         */
201        EntryAttribute put( String upId, byte[]... values );
202    
203    
204        /**
205         * <p>
206         * Put an attribute (represented by its ID and some String values) into an entry. 
207         * </p>
208         * <p> 
209         * If the attribute already exists, the previous attribute will be 
210         * replaced and returned.
211         * </p>
212         *
213         * @param upId The attribute ID
214         * @param values The list of String values to put. It can be empty.
215         * @return The replaced attribute
216         */
217        EntryAttribute put( String upId, String... values );
218    
219    
220        /**
221         * <p>
222         * Put an attribute (represented by its ID and some values) into an entry. 
223         * </p>
224         * <p> 
225         * If the attribute already exists, the previous attribute will be 
226         * replaced and returned.
227         * </p>
228         *
229         * @param upId The attribute ID
230         * @param values The list of values to put. It can be empty.
231         * @return The replaced attribute
232         */
233        EntryAttribute put( String upId, Value<?>... values );
234    
235    
236        /**
237          * Removes the specified attributes. The removed attributes are
238          * returned by this method. If there were no attribute the return value
239          * is <code>null</code>.
240          *
241          * @param attributes the attributes to be removed
242          * @return the removed attribute, if exists; otherwise <code>null</code>
243          */
244        List<EntryAttribute> remove( EntryAttribute... attributes ) throws LdapException;
245    
246    
247        /**
248         * <p>
249         * Removes the specified binary values from an attribute.
250         * </p>
251         * <p>
252         * If at least one value is removed, this method returns <code>true</code>.
253         * </p>
254         * <p>
255         * If there is no more value after having removed the values, the attribute
256         * will be removed too.
257         * </p>
258         * <p>
259         * If the attribute does not exist, nothing is done and the method returns 
260         * <code>false</code>
261         * </p> 
262         *
263         * @param upId The attribute ID  
264         * @param attributes the attributes to be removed
265         * @return <code>true</code> if at least a value is removed, <code>false</code>
266         * if not all the values have been removed or if the attribute does not exist. 
267         */
268        boolean remove( String upId, byte[]... values ) throws LdapException;
269    
270    
271        /**
272         * <p>
273         * Removes the specified String values from an attribute.
274         * </p>
275         * <p>
276         * If at least one value is removed, this method returns <code>true</code>.
277         * </p>
278         * <p>
279         * If there is no more value after havong removed the values, the attribute
280         * will be removed too.
281         * </p>
282         * <p>
283         * If the attribute does not exist, nothing is done and the method returns 
284         * <code>false</code>
285         * </p> 
286         *
287         * @param upId The attribute ID  
288         * @param attributes the attributes to be removed
289         * @return <code>true</code> if at least a value is removed, <code>false</code>
290         * if no values have been removed or if the attribute does not exist. 
291         */
292        boolean remove( String upId, String... values ) throws LdapException;
293    
294    
295        /**
296         * <p>
297         * Removes the specified values from an attribute.
298         * </p>
299         * <p>
300         * If at least one value is removed, this method returns <code>true</code>.
301         * </p>
302         * <p>
303         * If there is no more value after having removed the values, the attribute
304         * will be removed too.
305         * </p>
306         * <p>
307         * If the attribute does not exist, nothing is done and the method returns 
308         * <code>false</code>
309         * </p> 
310         *
311         * @param upId The attribute ID  
312         * @param attributes the attributes to be removed
313         * @return <code>true</code> if at least a value is removed, <code>false</code>
314         * if not all the values have been removed or if the attribute does not exist. 
315         */
316        boolean remove( String upId, Value<?>... values ) throws LdapException;
317    
318    
319        /**
320          * <p>
321          * Removes the attribute with the specified alias. 
322          * </p>
323          * <p>
324          * The removed attribute are returned by this method. 
325          * </p>
326          * <p>
327          * If there is no attribute with the specified alias,
328          * the return value is <code>null</code>.
329          * </p>
330          *
331          * @param attributes an aliased name of the attribute to be removed
332          * @return the removed attributes, if any, as a list; otherwise <code>null</code>
333          */
334        List<EntryAttribute> removeAttributes( String... attributes );
335    
336    
337        /**
338         * <p>
339         * Checks if an entry contains a list of attributes.
340         * </p>
341         * <p>
342         * If the list is null or empty, this method will return <code>true</code>
343         * if the entry has no attribute, <code>false</code> otherwise.
344         * </p>
345         *
346         * @param attributes The Attributes to look for
347         * @return <code>true</code> if all the attributes are found within 
348         * the entry, <code>false</code> if at least one of them is not present.
349         * @throws LdapException If the attribute does not exist
350         */
351        boolean contains( EntryAttribute... attributes ) throws LdapException;
352    
353    
354        /**
355         * Checks if an entry contains an attribute with some binary values.
356         *
357         * @param id The Attribute we are looking for.
358         * @param values The searched values.
359         * @return <code>true</code> if all the values are found within the attribute,
360         * false if at least one value is not present or if the ID is not valid. 
361         */
362        boolean contains( String upId, byte[]... values );
363    
364    
365        /**
366         * Checks if an entry contains an attribute with some String values.
367         *
368         * @param id The Attribute we are looking for.
369         * @param values The searched values.
370         * @return <code>true</code> if all the values are found within the attribute,
371         * false if at least one value is not present or if the ID is not valid. 
372         */
373        boolean contains( String upId, String... values );
374    
375    
376        /**
377         * Checks if an entry contains an attribute with some values.
378         *
379         * @param id The Attribute we are looking for.
380         * @param values The searched values.
381         * @return <code>true</code> if all the values are found within the attribute,
382         * false if at least one value is not present or if the ID is not valid. 
383         */
384        boolean contains( String upId, Value<?>... values );
385    
386    
387        /**
388         * Checks if an entry contains some specific attributes.
389         *
390         * @param attributes The Attributes to look for.
391         * @return <code>true</code> if the attributes are all found within the entry.
392         */
393        boolean containsAttribute( String... attributes );
394    
395        
396        /**
397         * Returns the number of attributes.
398         *
399         * @return the number of attributes
400         */
401        int size();
402    }