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 javax.naming.NamingException;
027
028 import org.apache.directory.shared.ldap.name.LdapDN;
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 LdapDN 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( LdapDN 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 NamingException If we can't add any of the attributes
133 */
134 void add( EntryAttribute... attributes ) throws NamingException;
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 NamingException If we can't add any of the values
144 */
145 void add( String upId, String... values ) throws NamingException;
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 NamingException If we can't add any of the values
155 */
156 void add( String upId, byte[]... values ) throws NamingException;
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 NamingException If we can't add any of the values
166 */
167 void add( String upId, Value<?>... values ) throws NamingException;
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 NamingException if the operation fails
184 */
185 List<EntryAttribute> put( EntryAttribute... attributes ) throws NamingException;
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 NamingException;
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 NamingException;
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 NamingException;
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 NamingException;
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 NamingException If the attribute does not exist
350 */
351 boolean contains( EntryAttribute... attributes ) throws NamingException;
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 }