View Javadoc

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 }