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     */
020    package org.apache.directory.server.core;
021    
022    
023    import java.io.File;
024    import java.util.List;
025    import java.util.Set;
026    
027    import org.apache.directory.server.core.changelog.ChangeLog;
028    import org.apache.directory.server.core.entry.ServerEntryFactory;
029    import org.apache.directory.server.core.event.EventService;
030    import org.apache.directory.server.core.interceptor.Interceptor;
031    import org.apache.directory.server.core.interceptor.InterceptorChain;
032    import org.apache.directory.server.core.journal.Journal;
033    import org.apache.directory.server.core.partition.Partition;
034    import org.apache.directory.server.core.partition.PartitionNexus;
035    import org.apache.directory.server.core.replication.ReplicationConfiguration;
036    import org.apache.directory.server.core.schema.SchemaService;
037    import org.apache.directory.shared.ldap.csn.Csn;
038    import org.apache.directory.shared.ldap.entry.ServerEntry;
039    import org.apache.directory.shared.ldap.ldif.LdifEntry;
040    import org.apache.directory.shared.ldap.name.DN;
041    import org.apache.directory.shared.ldap.schema.SchemaManager;
042    
043    
044    /**
045     * Provides JNDI service to {@link AbstractContextFactory}.
046     *
047     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
048     * @version $Rev: 927146 $, $Date: 2010-03-24 19:39:54 +0100 (Wed, 24 Mar 2010) $
049     */
050    public interface DirectoryService extends ServerEntryFactory
051    {
052        String JNDI_KEY = DirectoryService.class.getName();
053    
054        /**
055         * Reverts the server's state to an earlier revision.  Note that the revsion number
056         * still increases to revert back even though the state reverted to is the same.
057         * Note that implementations may lock the server from making changes or searching
058         * the directory until this operation has completed.
059         *
060         * @param revision the revision number to revert to
061         * @return the new revision reached by applying all changes needed to revert to the
062         * original state
063         * @throws Exception if there are problems reverting back to the earlier state
064         * @throws IllegalArgumentException if the revision provided is greater than the current
065         * revision or less than 0
066         * @throws UnsupportedOperationException if this feature is not supported by the
067         * change log
068         */
069        long revert( long revision ) throws Exception;
070    
071    
072        /**
073         * Reverts the server's state to the latest tagged snapshot if one was taken.  If
074         * there is no tag a illegal state exception will result.  If the latest revision
075         * is not earlier than the current revision (both are same), then no changes were
076         * made to the directory to be reverted.  In this case we return the current
077         * revision and do nothiig loggin the fact that we ignored the request to revert.
078         *
079         * @return the new revision reached by applying all changes needed to revert
080         * to the new state or the same version before this call if no revert actually
081         * took place
082         * @throws Exception if there are problems reverting back to the earlier state
083         * @throws UnsupportedOperationException if this feature is not supported by the
084         * change log
085         */
086        long revert() throws Exception;
087    
088    
089        PartitionNexus getPartitionNexus();
090    
091    
092        InterceptorChain getInterceptorChain();
093    
094    
095        void addPartition( Partition partition ) throws Exception;
096        
097    
098        void removePartition( Partition partition ) throws Exception;
099    
100        /**
101         * @return The Directory Service SchemaManager
102         */
103        SchemaManager getSchemaManager();
104    
105    
106        /**
107         * @return The referral manager
108         */
109        ReferralManager getReferralManager();
110    
111        
112        /**
113         * Set the referralManager
114         * 
115         * @org.apache.xbean.Property hidden="true"
116         * @param referralManager The initialized referralManager
117         */
118        void setReferralManager( ReferralManager referralManager );
119    
120        
121        SchemaService getSchemaService();
122    
123    
124        /**
125         * @org.apache.xbean.Property hidden="true"
126         */
127        void setSchemaService( SchemaService schemaService );
128        
129        
130        EventService getEventService();
131        
132        /**
133         * @org.apache.xbean.Property hidden="true"
134         */
135        void setEventService( EventService eventService );
136    
137    
138        /**
139         * Starts up this service.
140         * 
141         * @throws Exception if failed to start up
142         */
143        void startup() throws Exception;
144    
145    
146        /**
147         * Shuts down this service.
148         * 
149         * @throws Exception if failed to shut down
150         */
151        void shutdown() throws Exception;
152    
153    
154        /**
155         * Calls {@link Partition#sync()} for all registered {@link Partition}s.
156         * @throws Exception if synchronization failed
157         */
158        void sync() throws Exception;
159    
160    
161        /**
162         * Returns <tt>true</tt> if this service is started.
163         * @return true if the service has started, false otherwise
164         */
165        boolean isStarted();
166    
167        
168        CoreSession getAdminSession() throws Exception;
169        
170        
171        /**
172         * Gets a logical session to perform operations on this DirectoryService
173         * as the anonymous user.  This bypasses authentication without 
174         * propagating a bind operation into the core.
175         *
176         * @return a logical session as the anonymous user
177         */
178        CoreSession getSession() throws Exception;
179    
180        
181        /**
182         * Gets a logical session to perform operations on this DirectoryService
183         * as a specific user.  This bypasses authentication without propagating 
184         * a bind operation into the core.
185         *
186         * @return a logical session as a specific user
187         */
188        CoreSession getSession( LdapPrincipal principal ) throws Exception;
189    
190        
191        /**
192         * Gets a logical session to perform operations on this DirectoryService
193         * as a specific user with a separate authorization principal.  This 
194         * bypasses authentication without propagating a bind operation into the 
195         * core.
196         *
197         * @return a logical session as a specific user
198         */
199        CoreSession getSession( DN principalDn, byte[] credentials ) throws Exception;
200    
201        
202        /**
203         * Gets a logical session to perform operations on this DirectoryService
204         * as a specific user with a separate authorization principal.  This 
205         * bypasses authentication without propagating a bind operation into the 
206         * core.
207         *
208         * @return a logical session as a specific user
209         */
210        CoreSession getSession( DN principalDn, byte[] credentials, String saslMechanism, String saslAuthId ) 
211            throws Exception;
212    
213        
214        /**
215         * @org.apache.xbean.Property hidden="true"
216         */
217        void setInstanceId( String instanceId );
218    
219    
220        String getInstanceId();
221    
222    
223        /**
224         * Gets the {@link Partition}s used by this DirectoryService.
225         *
226         * @return the set of partitions used
227         */
228        Set<? extends Partition> getPartitions();
229    
230    
231        /**
232         * Sets {@link Partition}s used by this DirectoryService.
233         *
234         * @org.apache.xbean.Property nestedType="org.apache.directory.server.core.partition.Partition"
235         * @param partitions the partitions to used
236         */
237        void setPartitions( Set<? extends Partition> partitions );
238    
239    
240        /**
241         * Returns <tt>true</tt> if access control checks are enabled.
242         *
243         * @return true if access control checks are enabled, false otherwise
244         */
245        boolean isAccessControlEnabled();
246    
247    
248        /**
249         * Sets whether to enable basic access control checks or not.
250         *
251         * @param accessControlEnabled true to enable access control checks, false otherwise
252         */
253        void setAccessControlEnabled( boolean accessControlEnabled );
254    
255    
256        /**
257         * Returns <tt>true</tt> if anonymous access is allowed on entries besides the RootDSE.
258         * If the access control subsystem is enabled then access to some entries may not be
259         * allowed even when full anonymous access is enabled.
260         *
261         * @return true if anonymous access is allowed on entries besides the RootDSE, false
262         * if anonymous access is allowed to all entries.
263         */
264        boolean isAllowAnonymousAccess();
265    
266    
267        /**
268         * Returns <tt>true</tt> if the service requires the userPassword attribute
269         * to be masked. It's an option in the server.xml file.
270         *
271         * @return true if the service requires that the userPassword is to be hidden
272         */
273        boolean isPasswordHidden();
274    
275        
276        /**
277         * Sets whether to allow anonymous access to entries other than the RootDSE.  If the
278         * access control subsystem is enabled then access to some entries may not be allowed
279         * even when full anonymous access is enabled.
280         *
281         * @param enableAnonymousAccess true to enable anonymous access, false to disable it
282         */
283        void setAllowAnonymousAccess( boolean enableAnonymousAccess );
284    
285    
286        /**
287         * Sets whether the userPassword attribute is readable, or hidden.
288         *
289         * @param passwordHidden true to enable hide the userPassword attribute, false otherwise
290         */
291        void setPasswordHidden( boolean passwordHidden );
292    
293    
294        /**
295         * Returns interceptors in the server.
296         *
297         * @return the interceptors in the server.
298         */
299        List<Interceptor> getInterceptors();
300    
301    
302        /**
303         * Sets the interceptors in the server.
304         *
305         * @org.apache.xbean.Property nestedType="org.apache.directory.server.core.interceptor.Interceptor"
306         * @param interceptors the interceptors to be used in the server.
307         */
308        void setInterceptors( List<Interceptor> interceptors );
309    
310    
311        /**
312         * {@inheritDoc}
313         */
314        void setJournal( Journal journal );
315    
316        
317        /**
318         * Returns test directory entries({@link LdifEntry}) to be loaded while
319         * bootstrapping.
320         *
321         * @return test entries to load during bootstrapping
322         */
323        List<LdifEntry> getTestEntries();
324    
325    
326        /**
327         * Sets test directory entries({@link Attributes}) to be loaded while
328         * bootstrapping.
329         *
330         * @org.apache.xbean.Property nestedType="org.apache.directory.shared.ldap.ldif.Entry"
331         * @param testEntries the test entries to load while bootstrapping
332         */
333        void setTestEntries( List<? extends LdifEntry> testEntries );
334    
335    
336        /**
337         * Returns working directory (counterpart of <tt>var/lib</tt>) where partitions are
338         * stored by default.
339         *
340         * @return the directory where partition's are stored.
341         */
342        File getWorkingDirectory();
343    
344    
345        /**
346         * Sets working directory (counterpart of <tt>var/lib</tt>) where partitions are stored
347         * by default.
348         *
349         * @param workingDirectory the directory where the server's partitions are stored by default.
350         */
351        void setWorkingDirectory( File workingDirectory );
352    
353    
354        /**
355         * Sets the shutdown hook flag which controls whether or not this DirectoryService
356         * registers a JVM shutdown hook to flush caches and synchronize to disk safely.  This is
357         * enabled by default.
358         *
359         * @org.apache.xbean.Property hidden="true"
360         * @param shutdownHookEnabled true to enable the shutdown hook, false to disable
361         */
362        void setShutdownHookEnabled( boolean shutdownHookEnabled );
363    
364    
365        /**
366         * Checks to see if this DirectoryService has registered a JVM shutdown hook
367         * to flush caches and synchronize to disk safely.  This is enabled by default.
368         *
369         * @return true if a shutdown hook is registered, false if it is not
370         */
371        boolean isShutdownHookEnabled();
372    
373    
374        void setExitVmOnShutdown( boolean exitVmOnShutdown );
375    
376    
377        boolean isExitVmOnShutdown();
378    
379    
380        void setSystemPartition( Partition systemPartition );
381    
382    
383        Partition getSystemPartition();
384    
385    
386        boolean isDenormalizeOpAttrsEnabled();
387    
388    
389        void setDenormalizeOpAttrsEnabled( boolean denormalizeOpAttrsEnabled );
390    
391    
392        /**
393         * Gets the ChangeLog service for this DirectoryService used for tracking
394         * changes (revisions) to the server and using them to revert the server
395         * to earlier revisions.
396         *
397         * @return the change log service
398         */
399        ChangeLog getChangeLog();
400    
401    
402        /**
403         * Gets the Journal service for this DirectoryService used for tracking
404         * changes to the server.
405         *
406         * @return the journal service
407         */
408        Journal getJournal();
409    
410    
411        /**
412         * Sets the ChangeLog service for this DirectoryService used for tracking
413         * changes (revisions) to the server and using them to revert the server
414         * to earlier revisions.
415         *
416         * @param changeLog the change log service to set
417         */
418        void setChangeLog( ChangeLog changeLog );
419        
420    
421        /**
422         * Create a new ServerEntry.
423         * 
424         * @param ldif the String representing the attributes, in LDIF format
425         * @param dn the DN for this new entry
426         */
427        ServerEntry newEntry( String ldif, String dn );
428        
429        
430        /**
431         * Gets the operation manager.
432         */
433        OperationManager getOperationManager();
434    
435    
436        /**
437         * @return The maximum allowed size for an incoming PDU
438         */
439        int getMaxPDUSize();
440    
441    
442        /**
443         * Set the maximum allowed size for an incoming PDU 
444         * @param maxPDUSize A positive number of bytes for the PDU. A negative or
445         * null value will be transformed to {@link Integer#MAX_VALUE}
446         */
447        void setMaxPDUSize( int maxPDUSize );
448        
449        
450        /**
451         * Get an Interceptor instance from its name
452         * @param interceptorName The interceptor's name for which we want the instance 
453         * @return
454         */
455        Interceptor getInterceptor( String interceptorName );
456        
457        
458        /**
459         * Get a new CSN
460         * @return The CSN generated for this directory service
461         */
462        Csn getCSN();
463    
464    
465        /**
466         * @return the replicaId
467         */
468        int getReplicaId();
469    
470    
471        /**
472         * @param replicaId the replicaId to set
473         */
474        void setReplicaId( int replicaId );
475    
476    
477        /**
478         * Sets the replication configuration in the server.
479         *
480         * @param replicationConfiguration the replication configuration to be used in the server.
481         */
482        void setReplicationConfiguration( ReplicationConfiguration replicationConfig );
483        
484        
485        /**
486         * @return the replication configuration for this DirectoryService
487         */
488        ReplicationConfiguration getReplicationConfiguration();
489        
490        
491        /**
492         * Associates a SchemaManager to the service
493         * 
494         * @param schemaManager The SchemaManager to associate
495         */
496        void setSchemaManager( SchemaManager schemaManager );
497    }