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 */
20 package org.apache.directory.server.xdbm;
21
22
23 import org.apache.directory.server.schema.registries.Registries;
24 import org.apache.directory.server.core.entry.ServerEntry;
25 import org.apache.directory.shared.ldap.name.LdapDN;
26 import org.apache.directory.shared.ldap.name.Rdn;
27 import org.apache.directory.shared.ldap.entry.ModificationOperation;
28 import org.apache.directory.shared.ldap.entry.Modification;
29
30 import java.io.File;
31 import java.util.Set;
32 import java.util.Iterator;
33 import java.util.List;
34
35
36 /**
37 * Represents an entry store based on the Table, Index, and MasterTable
38 * database structure.
39 *
40 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
41 * @version $$Rev$$
42 */
43 public interface Store<E>
44 {
45 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.1) for apacheNdn op attrib */
46 String NDN = "1.3.6.1.4.1.18060.0.4.1.2.1";
47 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.2) for apacheUpdn op attrib */
48 String UPDN = "1.3.6.1.4.1.18060.0.4.1.2.2";
49 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.5) for apacheOneAlias index */
50 String ONEALIAS = "1.3.6.1.4.1.18060.0.4.1.2.5";
51 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.6) for apacheSubAlias index */
52 String SUBALIAS = "1.3.6.1.4.1.18060.0.4.1.2.6";
53 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.7) for apacheAlias index */
54 String ALIAS = "1.3.6.1.4.1.18060.0.4.1.2.7";
55 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.43) for apacheSubLevel index*/
56 String SUBLEVEL = "1.3.6.1.4.1.18060.0.4.1.2.43";
57 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.3) for apachePresence op attrib */
58 String PRESENCE = "1.3.6.1.4.1.18060.0.4.1.2.3";
59 /** Private OID (1.3.6.1.4.1.18060.0.4.1.2.4) for apacheOneLevel op attrib */
60 String ONELEVEL = "1.3.6.1.4.1.18060.0.4.1.2.4";
61
62 /*
63 * W H Y H A V E A S T O R E I N T E R F A C E ?
64 * ------------------------------------------------------
65 *
66 * Some may question why we have this Store interface when the Partition
67 * interface abstracts away partition implementation details in the server
68 * core. This is due to a complicated chicken and egg problem with the
69 * additional need to abstract stores for the SearchEngine. This way the
70 * SearchEngine and it's default implementation can be independent of the
71 * Partition interface. Once this is achieved the default SearchEngine
72 * implementation can be removed from the core. This will allow for
73 * better modularization, with the ability to easily substitute new
74 * SearchEngine implementations into ApacheDS.
75 *
76 *
77 * H I S T O R Y
78 * -------------
79 *
80 * Originally the JdbmStore class came about due to a cyclic dependency.
81 * The bootstrap-partition module is created by the bootstrap-plugin
82 * module. The core depends on the bootstrap-partition module to
83 * bootstrap the server. The bootstrap-partition module depends on the
84 * bootstrap-plugin which builds a JdbmStore stuffing it with all the
85 * information needed for the server to bootstrap. The bootstrap-plugin
86 * hence must be built before it can generate the bootstrap-partition and
87 * it cannot have a dependency on the core. We could not use the
88 * JdbmPartition because it depends on the Partition interface and this
89 * is an integral part of the core. If we did then there would be a
90 * cyclic dependency between modules in the apacheds pom. To avoid this
91 * the JdbmStore class was created and the guts of the JDBM partition were
92 * put into the jdbm-store module. This jdbm-store module does not depend
93 * on core and can be used by the bootstrap-plugin to build the
94 * bootstrap-partition.
95 *
96 * Hence it's project dependencies that drove the creation of the
97 * JdbmStore class. Later we realized, the default SeachEngine used by
98 * all Table, Index, MasterTable scheme based partitions depends on
99 * BTreePartition which depends on Partition. We would like to remove
100 * this search engine out of the core so it can easily be swapped out,
101 * but most importantly so we can have the search depend on any kind of
102 * store. There's no reason why the SearchEngine should depend on a
103 * Partition (store with search capabilities) when it just needs a simple
104 * store and it's indices to conduct search operations.
105 */
106
107
108 void setWorkingDirectory( File workingDirectory );
109
110
111 File getWorkingDirectory();
112
113
114 void setUserIndices( Set<Index<?,E>> userIndices );
115
116
117 Set<Index<?,E>> getUserIndices();
118
119
120 void setSuffixDn( String suffixDn );
121
122
123 String getSuffixDn();
124
125
126 void setSyncOnWrite( boolean isSyncOnWrite );
127
128
129 boolean isSyncOnWrite();
130
131
132 void setCacheSize( int cacheSize );
133
134
135 int getCacheSize();
136
137
138 void setName( String name );
139
140
141 String getName();
142
143
144 /**
145 * Initialize the JDBM storage system.
146 *
147 * @param registries the schema registries
148 * @throws Exception on failure to lookup elements in registries
149 * @throws Exception on failure to create database files
150 */
151 void init( Registries registries ) throws Exception;
152
153
154 /**
155 * Close the parttion : we have to close all the userIndices and the master table.
156 *
157 * @throws Exception lazily thrown on any closer failures to avoid leaving
158 * open files
159 */
160 void destroy() throws Exception;
161
162
163 /**
164 * Gets whether the store is initialized.
165 *
166 * @return true if the partition store is initialized
167 */
168 boolean isInitialized();
169
170
171 /**
172 * This method is called when the synch thread is waking up, to write
173 * the modified data.
174 *
175 * @throws Exception on failures to sync database files to disk
176 */
177 void sync() throws Exception;
178
179
180 void addIndex( Index<?,E> index ) throws Exception;
181
182
183 Index<String,E> getPresenceIndex();
184
185
186 void setPresenceIndex( Index<String,E> index ) throws Exception;
187
188
189 Index<Long,E> getOneLevelIndex();
190
191
192 void setOneLevelIndex( Index<Long,E> index ) throws Exception;
193
194
195 Index<Long,E> getSubLevelIndex();
196
197
198 void setSubLevelIndex( Index<Long,E> index ) throws Exception;
199
200
201 Index<String,E> getAliasIndex();
202
203
204 void setAliasIndex( Index<String,E> index ) throws Exception;
205
206
207 Index<Long,E> getOneAliasIndex();
208
209
210 void setOneAliasIndex( Index<Long,E> index ) throws Exception;
211
212
213 Index<Long,E> getSubAliasIndex();
214
215
216 void setSubAliasIndex( Index<Long,E> index ) throws Exception;
217
218
219 Index<String,E> getUpdnIndex();
220
221
222 void setUpdnIndex( Index<String,E> index ) throws Exception;
223
224
225 Index<String,E> getNdnIndex();
226
227
228 void setNdnIndex( Index<String,E> index ) throws Exception;
229
230
231 Iterator<String> userIndices();
232
233
234 Iterator<String> systemIndices();
235
236
237 boolean hasUserIndexOn( String id ) throws Exception;
238
239
240 boolean hasSystemIndexOn( String id ) throws Exception;
241
242
243 Index<?,E> getUserIndex( String id ) throws IndexNotFoundException;
244
245
246 Index<?,E> getSystemIndex( String id ) throws IndexNotFoundException;
247
248
249 Long getEntryId( String dn ) throws Exception;
250
251
252 String getEntryDn( Long id ) throws Exception;
253
254
255 /**
256 * Gets the Long id of an entry's parent using the child entry's
257 * normalized dn. Note that the suffix entry returns 0, which does not
258 * map to any entry.
259 *
260 * @param dn the normalized distinguished name of the child
261 * @return the id of the parent entry or zero if the suffix entry the
262 * normalized suffix dn string is used
263 * @throws Exception on failures to access the underlying store
264 */
265 Long getParentId( String dn ) throws Exception;
266
267
268 Long getParentId( Long childId ) throws Exception;
269
270
271 String getEntryUpdn( Long id ) throws Exception;
272
273
274 String getEntryUpdn( String dn ) throws Exception;
275
276
277 int count() throws Exception;
278
279
280 void add( LdapDN normName, ServerEntry entry ) throws Exception;
281
282
283 ServerEntry lookup( Long id ) throws Exception;
284
285
286 void delete( Long id ) throws Exception;
287
288
289 /**
290 * Gets an IndexEntry Cursor over the child nodes of an entry.
291 *
292 * @param id the id of the parent entry
293 * @return an IndexEntry Cursor over the child entries
294 * @throws Exception on failures to access the underlying store
295 */
296 IndexCursor<Long,E> list( Long id ) throws Exception;
297
298
299 int getChildCount( Long id ) throws Exception;
300
301
302 LdapDN getSuffix();
303
304
305 LdapDN getUpSuffix();
306
307
308 void setProperty( String propertyName, String propertyValue ) throws Exception;
309
310
311 String getProperty( String propertyName ) throws Exception;
312
313
314 void modify( LdapDN dn, ModificationOperation modOp, ServerEntry mods ) throws Exception;
315
316
317 void modify( LdapDN dn, List<Modification> mods ) throws Exception;
318
319
320 /**
321 * Changes the relative distinguished name of an entry specified by a
322 * distinguished name with the optional removal of the old Rdn attribute
323 * value from the entry. Name changes propagate down as dn changes to the
324 * descendants of the entry where the Rdn changed.
325 *
326 * An Rdn change operation does not change parent child relationships. It
327 * merely propagates a name change at a point in the DIT where the Rdn is
328 * changed. The change propagates down the subtree rooted at the
329 * distinguished name specified.
330 *
331 * @param dn the normalized distinguished name of the entry to alter
332 * @param newRdn the new Rdn to set
333 * @param deleteOldRdn whether or not to remove the old Rdn attr/val
334 * @throws Exception if there are any errors propagating the name changes
335 */
336 void rename( LdapDN dn, Rdn newRdn, boolean deleteOldRdn ) throws Exception;
337
338
339 void move( LdapDN oldChildDn, LdapDN newParentDn, Rdn newRdn, boolean deleteOldRdn ) throws Exception;
340
341
342 void move( LdapDN oldChildDn, LdapDN newParentDn ) throws Exception;
343
344
345 void initRegistries( Registries registries );
346 }