1 /*
2 * Copyright 2005-2008 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.ldap.core;
18
19 import java.util.SortedSet;
20
21 import javax.naming.Name;
22 import javax.naming.directory.Attributes;
23 import javax.naming.directory.DirContext;
24
25 /**
26 * Interface for DirContextAdapter.
27 *
28 * @author Mattias Hellborg Arthursson
29 * @see DirContextAdapter
30 */
31 public interface DirContextOperations extends DirContext,
32 AttributeModificationsAware {
33
34 /**
35 * Gets the update mode. An entry in update mode will keep track of its
36 * modifications so that they can be retrieved using
37 * {@link AttributeModificationsAware#getModificationItems()}. The update
38 * mode should be <code>true</code> for a new entry and <code>true</code>
39 * for an existing entry that is being updated.
40 *
41 * @return update mode.
42 */
43 boolean isUpdateMode();
44
45 /**
46 * Creates a String array of the names of the attributes which have been
47 * changed.
48 *
49 * If this is a new entry, all set entries will be in the list. If this is
50 * an updated entry, only changed and removed entries will be in the array.
51 *
52 * @return Array of String
53 */
54 String[] getNamesOfModifiedAttributes();
55
56 /**
57 * Get the value of a String attribute. If more than one attribute value
58 * exists for the specified attribute, only the first one will be returned.
59 *
60 * @param name name of the attribute.
61 * @return the value of the attribute.
62 * @throws ClassCastException if the value of the entry is not a String.
63 */
64 String getStringAttribute(String name);
65
66 /**
67 * Get the value of an Object attribute. If more than one attribute value
68 * exists for the specified attribute, only the first one will be returned.
69 *
70 * @param name name of the attribute.
71 * @return the attribute value as an object if it exists, or
72 * <code>null</code> otherwise.
73 */
74 Object getObjectAttribute(String name);
75
76 /**
77 * Set the with the name <code>name</code> to the <code>value</code>.
78 *
79 * @param name name of the attribute.
80 * @param value value to set the attribute to.
81 */
82 public void setAttributeValue(String name, Object value);
83
84 /**
85 * Sets a multivalue attribute, disregarding the order of the values.
86 *
87 * If value is null or value.length == 0 then the attribute will be removed.
88 *
89 * If update mode, changes will be made only if the array has more or less
90 * objects or if one or more object has changed. Reordering the objects will
91 * not cause an update.
92 *
93 * @param name The id of the attribute.
94 * @param values Attribute values.
95 */
96 void setAttributeValues(String name, Object[] values);
97
98 /**
99 * Sets a multivalue attribute.
100 *
101 * If value is null or value.length == 0 then the attribute will be removed.
102 *
103 * If update mode, changes will be made if the array has more or less
104 * objects or if one or more string has changed.
105 *
106 * Reordering the objects will only cause an update if orderMatters is set
107 * to true.
108 *
109 * @param name The id of the attribute.
110 * @param values Attribute values.
111 * @param orderMatters If <code>true</code>, it will be changed even if data
112 * was just reordered.
113 */
114 void setAttributeValues(String name, Object[] values, boolean orderMatters);
115
116 /**
117 * Add a value to the Attribute with the specified name. If the Attribute
118 * doesn't exist it will be created. This method makes sure that the there
119 * will be no duplicates of an added value - it the value exists it will not
120 * be added again.
121 *
122 * @param name the name of the Attribute to which the specified value should
123 * be added.
124 * @param value the Attribute value to add.
125 */
126 void addAttributeValue(String name, Object value);
127
128 /**
129 * Add a value to the Attribute with the specified name. If the Attribute
130 * doesn't exist it will be created. The <code>addIfDuplicateExists</code>
131 * parameter controls the handling of duplicates. It <code>false</code>,
132 * this method makes sure that the there will be no duplicates of an added
133 * value - it the value exists it will not be added again.
134 *
135 * @param name the name of the Attribute to which the specified value should
136 * be added.
137 * @param value the Attribute value to add.
138 * @param addIfDuplicateExists <code>true</code> will add the value
139 * regardless of whether there is an identical value already, allowing for
140 * duplicate attribute values; <code>false</code> will not add the value if
141 * it already exists.
142 */
143 void addAttributeValue(String name, Object value,
144 boolean addIfDuplicateExists);
145
146 /**
147 * Remove a value from the Attribute with the specified name. If the
148 * Attribute doesn't exist, do nothing.
149 *
150 * @param name the name of the Attribute from which the specified value
151 * should be removed.
152 * @param value the value to remove.
153 */
154 void removeAttributeValue(String name, Object value);
155
156 /**
157 * Update the attributes.This will mean that the getters (
158 * <code>getStringAttribute</code> methods) will return the updated values,
159 * and the modifications will be forgotten (i.e.
160 * {@link AttributeModificationsAware#getModificationItems()} will return an
161 * empty array.
162 */
163 void update();
164
165 /**
166 * Get all values of a String attribute.
167 *
168 * @param name name of the attribute.
169 * @return a (possibly empty) array containing all registered values of the
170 * attribute as Strings if the attribute is defined or <code>null</code>
171 * otherwise.
172 * @throws ArrayStoreException if any of the attribute values is not a
173 * String.
174 */
175 String[] getStringAttributes(String name);
176
177 /**
178 * Get all values of an Object attribute.
179 *
180 * @param name name of the attribute.
181 * @return a (possibly empty) array containing all registered values of the
182 * attribute if the attribute is defined or <code>null</code> otherwise.
183 * @since 1.3
184 */
185 Object[] getObjectAttributes(String name);
186
187 /**
188 * Get all String values of the attribute as a <code>SortedSet</code>.
189 *
190 * @param name name of the attribute.
191 * @return a <code>SortedSet</code> containing all values of the attribute,
192 * or <code>null</code> if the attribute does not exist.
193 */
194 SortedSet getAttributeSortedStringSet(String name);
195
196 /**
197 * Returns the DN relative to the base path.
198 *
199 * @return The distinguished name of the current context.
200 *
201 * @see DirContextAdapter#getNameInNamespace()
202 */
203 Name getDn();
204
205 /**
206 * Set the dn of this entry.
207 *
208 * @param dn the dn.
209 */
210 void setDn(Name dn);
211
212 /*
213 * (non-Javadoc)
214 *
215 * @see javax.naming.Context#getNameInNamespace()
216 */
217 String getNameInNamespace();
218
219 /**
220 * If this instance results from a referral, this method returns the url of
221 * the referred server.
222 *
223 * @return The url of the referred server, e.g.
224 * <code>ldap://localhost:389</code>, or the empty string if this is not a
225 * referral.
226 * @since 1.3
227 */
228 String getReferralUrl();
229
230 /**
231 * Checks whether this instance results from a referral.
232 *
233 * @return <code>true</code> if this instance results from a referral,
234 * <code>false</code> otherwise.
235 * @since 1.3
236 */
237 boolean isReferral();
238
239 /**
240 * Get all the Attributes.
241 *
242 * @return all the Attributes.
243 * @since 1.3
244 */
245 Attributes getAttributes();
246 }